Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
TypeScript aeoai-agentai-searchanswer-engine-optimizationbrand-monitoringchatgptclaudecopilotdockergeminigeogoogle-ai-overviewsgrokmcpnextjsopen-sourceperplexityseosupabasetypescript
feat(shopping): score an own product's keyword match with each prompt, with the missing words (#1282, part 1) (#1487)
Gökhan Geyika31b64c3bd10
diff --git a/web/messages/en.json b/web/messages/en.jsonindex 6787e7c39..d32eb9830 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -6937,6 +6937,17 @@"drawerPlatform": "Platform","drawerRegion": "Region","drawerCardsTitle": "Cards returned",+ "matchScore": {+ "title": "Match with each prompt",+ "estimate": "Ansvisor estimate",+ "description": "How well this product's title matches each prompt it was shown for, with the searches AI ran for it: a keyword match from 0 to 100. It's our estimate, not ChatGPT's own score.",+ "yours": "This product",+ "shownFirst": "Shown first",+ "shownFirstThis": "Shown first in the latest answer",+ "missing": "Missing:",+ "empty": "No prompt to compare with in this window.",+ "unavailable": "Couldn't read the match right now."+ },"merchantSplit": {"title": "Where AI sends shoppers","description": "Where the cards for your products link, in the selected window.",diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsxindex 8a75ee972..0313a094b 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx@@ -96,6 +96,7 @@ import { HeaderWithAiUsage } from '@/components/ai-usage/ai-usage-meter';import { ShoppingMarketSwitch, useShoppingMarket } from './_market-switch';import { MerchantSplitCard } from './merchant_split_card';import { OpenAiIndexCard } from './openai_index_card';+import { ProductMatchScores } from './product_match_scores';import { ResellerPriceAlerts } from './reseller_price_alerts';import { useMerchantDestinations } from './use_merchant_destinations';import { useOpenAiIndex } from './use_openai_index';@@ -513,6 +514,8 @@ export default function ShoppingPage() {{hasFullAccess && (<ProductAppearancesDrawert={t}+ brandId={activeBrandId}+ filters={filters}product={selectedProduct}onOpenChange={(open) => {if (!open) setSelectedProduct(null);@@ -1415,9 +1418,17 @@ interface ProductAppearancesDrawerProps {t: ReturnType<typeof useTranslations<'shopping'>>;product: ShoppingProduct | null;onOpenChange: (open: boolean) => void;+ brandId: string;+ filters: ShoppingFilters;}-function ProductAppearancesDrawer({ t, product, onOpenChange }: ProductAppearancesDrawerProps) {+function ProductAppearancesDrawer({+ t,+ product,+ onOpenChange,+ brandId,+ filters,+}: ProductAppearancesDrawerProps) {const isOpen = product !== null;return (@@ -1435,6 +1446,10 @@ function ProductAppearancesDrawer({ t, product, onOpenChange }: ProductAppearanc</SheetHeader><div className="flex-1 overflow-y-auto px-5 py-4 space-y-4">+ {/* The brand's own products only: a competitor's text isn't the brand's to change. */}+ {product && !product.competitor_name && (+ <ProductMatchScores brandId={brandId} filters={filters} product={product} />+ )}{product?.appearances.map((app) => {const dateStr = new Date(app.created_at).toLocaleDateString(undefined, {month: 'short',diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.test.tsxnew file mode 100644index 000000000..589f520e1--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.test.tsx@@ -0,0 +1,111 @@+import { act } from 'react';+import { createRoot, type Root } from 'react-dom/client';+import { NextIntlClientProvider } from 'next-intl';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import messages from '../../../../../../messages/en.json';+import type { ProductPromptMatch, ShoppingProduct } from '@/lib/actions/shopping';++/** #1282, part 1: an own product's match with each prompt, in its drawer. */++const getProductMatchScores = vi.fn();+vi.mock('@/lib/actions/shopping', () => ({+ getProductMatchScores: (...args: unknown[]) => getProductMatchScores(...args),+}));++const { ProductMatchScores } = await import('./product_match_scores');++(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =+ true;++let container: HTMLDivElement;+let root: Root;++beforeEach(() => {+ getProductMatchScores.mockReset();+ container = document.createElement('div');+ document.body.appendChild(container);+ root = createRoot(container);+});++afterEach(() => {+ act(() => root.unmount());+ container.remove();+});++function product(promptIds: string[]): ShoppingProduct {+ return {+ product_title: 'Trailrunner Waterproof Hiking Boot',+ product_brand: 'Acme',+ impressions: promptIds.length,+ platforms: ['chatgpt-shopping'],+ regions: ['US'],+ last_seen: '2026-10-20T10:00:00Z',+ last_price: null,+ price_currency: null,+ top_merchant: null,+ image_url: null,+ appearances: promptIds.map((id, i) => ({+ id: `a${i}`,+ prompt_id: id,+ prompt_text: 'Best waterproof hiking boots',+ created_at: '2026-10-20T10:00:00Z',+ region: 'US',+ platform: 'chatgpt-shopping',+ raw: null,+ merchant_url: null,+ merchant_domain: null,+ })),+ };+}++async function render(p: ShoppingProduct) {+ await act(async () => {+ root.render(+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">+ <ProductMatchScores brandId="b1" filters={{ datePreset: '30d' }} product={p} />+ </NextIntlClientProvider>,+ );+ });+ return container.textContent ?? '';+}++describe('ProductMatchScores', () => {+ it("shows each prompt's score, the product shown first, and the missing words, as our estimate", async () => {+ const matches: ProductPromptMatch[] = [+ {+ promptId: 'p1',+ promptText: 'Best waterproof hiking boots',+ score: 62,+ missing: ['wet', 'rock'],+ top: { title: 'Summit Boot', score: 88, isThis: false },+ },+ {+ promptId: 'p2',+ promptText: 'Hiking boots for rain',+ score: 75,+ missing: [],+ top: { title: 'Trailrunner Waterproof Hiking Boot', score: 75, isThis: true },+ },+ ];+ getProductMatchScores.mockResolvedValue(matches);+ const text = await render(product(['p1', 'p2', 'p1']));++ expect(getProductMatchScores).toHaveBeenCalledWith(+ 'b1',+ 'Trailrunner Waterproof Hiking Boot',+ ['p1', 'p2'],+ { datePreset: '30d' },+ );+ expect(text).toContain('Ansvisor estimate');+ expect(text).toContain('This product 62');+ expect(text).toContain('Shown first 88');+ expect(text).toContain('Missing:wetrock');+ expect(text).toContain('Shown first in the latest answer');+ });++ it("says so when the read fails, and when there's no prompt to compare with", async () => {+ getProductMatchScores.mockRejectedValue(new Error('invalid'));+ expect(await render(product(['p1']))).toContain("Couldn't read the match right now.");+ expect(await render(product([]))).toContain('No prompt to compare with in this window.');+ });+});diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.tsxnew file mode 100644index 000000000..34b82c90b--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/product_match_scores.tsx@@ -0,0 +1,116 @@+'use client';++import { useEffect, useMemo, useState } from 'react';+import { useTranslations } from 'next-intl';+import { Badge } from '@/components/ui/badge';+import { Skeleton } from '@/components/ui/skeleton';+import {+ getProductMatchScores,+ type ProductPromptMatch,+ type ShoppingFilters,+ type ShoppingProduct,+} from '@/lib/actions/shopping';++/** Prompts compared at once, the most recent first (the action's own cap). */+const MAX_PROMPTS = 20;+/** Missing words shown per prompt. */+const MAX_MISSING = 8;++/**+ * Match with each prompt (#1282, part 1): in an own product's drawer, its+ * keyword match with each prompt it was shown for, the product shown first,+ * and the prompt's words its title lacks. Labelled as our estimate.+ */+export function ProductMatchScores({+ brandId,+ filters,+ product,+}: {+ brandId: string;+ filters: ShoppingFilters;+ product: ShoppingProduct;+}) {+ const t = useTranslations('shopping.matchScore');+ const promptIds = useMemo(+ () =>+ [...new Set(product.appearances.map((a) => a.prompt_id).filter(Boolean))].slice(+ 0,+ MAX_PROMPTS,+ ),+ [product],+ );+ const key = `${brandId}|${product.product_title}|${promptIds.join(',')}|${JSON.stringify(filters)}`;+ const [loaded, setLoaded] = useState<{+ key: string;+ matches: ProductPromptMatch[] | null;+ } | null>(null);++ useEffect(() => {+ if (!promptIds.length) return;+ let cancelled = false;+ getProductMatchScores(brandId, product.product_title, promptIds, filters).then(+ (matches) => !cancelled && setLoaded({ key, matches }),+ () => !cancelled && setLoaded({ key, matches: null }),+ );+ return () => {+ cancelled = true;+ };+ }, [key, brandId, product.product_title, promptIds, filters]);++ const current = loaded?.key === key ? loaded : null;++ return (+ <section className="space-y-3 rounded-lg border p-4">+ <div className="flex flex-wrap items-center justify-between gap-2">+ <h3 className="text-sm font-medium text-foreground">{t('title')}</h3>+ <Badge variant="outline" className="text-[10px]">+ {t('estimate')}+ </Badge>+ </div>+ <p className="text-xs text-muted-foreground">{t('description')}</p>+ {!promptIds.length ? (+ <p className="text-xs text-muted-foreground">{t('empty')}</p>+ ) : !current ? (+ <Skeleton className="h-24 w-full" />+ ) : !current.matches ? (+ <p className="text-xs text-muted-foreground">{t('unavailable')}</p>+ ) : !current.matches.length ? (+ <p className="text-xs text-muted-foreground">{t('empty')}</p>+ ) : (+ <ul className="divide-y">+ {current.matches.map((match) => (+ <li key={match.promptId} className="space-y-1.5 py-3 first:pt-0 last:pb-0">+ <p className="line-clamp-2 text-xs font-medium text-foreground">+ "{match.promptText}"+ </p>+ <div className="flex flex-wrap gap-x-4 gap-y-1 text-xs tabular-nums text-muted-foreground">+ <span>+ {t('yours')} <span className="font-semibold text-foreground">{match.score}</span>+ </span>+ {match.top &&+ (match.top.isThis ? (+ <span>{t('shownFirstThis')}</span>+ ) : (+ <span title={match.top.title}>+ {t('shownFirst')}{' '}+ <span className="font-semibold text-foreground">{match.top.score}</span>+ </span>+ ))}+ </div>+ {match.missing.length > 0 && (+ <div className="flex flex-wrap items-center gap-1">+ <span className="text-xs text-muted-foreground">{t('missing')}</span>+ {match.missing.slice(0, MAX_MISSING).map((word) => (+ <Badge key={word} variant="secondary" className="text-[10px]">+ {word}+ </Badge>+ ))}+ </div>+ )}+ </li>+ ))}+ </ul>+ )}+ </section>+ );+}diff --git a/web/src/lib/actions/shopping-match.test.ts b/web/src/lib/actions/shopping-match.test.tsnew file mode 100644index 000000000..da3e0d41c--- /dev/null+++ b/web/src/lib/actions/shopping-match.test.ts@@ -0,0 +1,139 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/**+ * #1282, part 1 — an own product's keyword match with each prompt it was+ * shown for, against the products shown for that prompt in the window.+ */++const BRAND = '5b0c3b8e-8a5f-4a41-9d0e-1f2a3b4c5d6e';+const P1 = '11111111-1111-4111-8111-111111111111';+const P2 = '22222222-2222-4222-8222-222222222222';++let cards: Array<Record<string, unknown>> = [];+let prompts: Array<{ id: string; text: string }> = [];+let cardFilters: Array<[string, unknown]> = [];++function fakeQueryBuilder(table: string) {+ const builder = {+ select: () => builder,+ eq: () => builder,+ gte: () => builder,+ lte: () => builder,+ or: () => builder,+ order: () => builder,+ range: () => builder,+ in: (column: string, values: unknown) => {+ if (table === 'prompt_result_shopping_cards') cardFilters.push([column, values]);+ return builder;+ },+ then: (onFulfilled: (v: unknown) => unknown) =>+ Promise.resolve({+ data: table === 'prompts' ? prompts : cards,+ error: null,+ }).then(onFulfilled),+ };+ return builder;+}++vi.mock('@/lib/supabase/server', () => ({+ createClient: async () => ({ from: (table: string) => fakeQueryBuilder(table) }),+}));++const { getProductMatchScores } = await import('./shopping');++function card(+ title: string,+ resultId: string,+ promptId: string,+ position: number,+ createdAt: string,+ searches: string[] = [],+) {+ return {+ id: `${resultId}-${position}`,+ created_at: createdAt,+ position,+ product_title: title,+ prompt_result_id: resultId,+ prompt_results: {+ prompt_id: promptId,+ search_queries: searches.map((query) => ({ query, source_platform: 'chatgpt-web' })),+ },+ };+}++beforeEach(() => {+ cardFilters = [];+ prompts = [+ { id: P1, text: 'Best waterproof hiking boots' },+ { id: P2, text: 'White sneakers for the city' },+ ];+ cards = [+ // P1, latest answer: a rival first, then the brand's boot.+ card('Summit Waterproof Hiking Boot for Wet Rock', 'r2', P1, 1, '2026-10-20T10:00:00Z', [+ 'waterproof hiking boots wet rock',+ ]),+ card('Trailrunner Waterproof Hiking Boot', 'r2', P1, 2, '2026-10-20T10:00:00Z'),+ // P1, an older answer, where the brand's boot was first.+ card('Trailrunner Waterproof Hiking Boot', 'r1', P1, 1, '2026-10-10T10:00:00Z'),+ // P2: the brand's boot alone.+ card('trailrunner waterproof hiking boot', 'r3', P2, 1, '2026-10-21T10:00:00Z'),+ ];+});++describe('getProductMatchScores', () => {+ it("scores the product for each prompt, with the latest answer's first product", async () => {+ const [p1, p2] = await getProductMatchScores(+ BRAND,+ 'Trailrunner Waterproof Hiking Boot',+ [P1, P2],+ { datePreset: '30d' },+ );+ expect(cardFilters).toEqual([['prompt_results.prompt_id', [P1, P2]]]);++ expect(p1.promptText).toBe('Best waterproof hiking boots');+ // The searches' words count: "wet" and "rock" are missing.+ expect(p1.missing).toEqual(['wet', 'rock']);+ expect(p1.top).toMatchObject({+ title: 'Summit Waterproof Hiking Boot for Wet Rock',+ isThis: false,+ });+ expect(p1.top!.score).toBeGreaterThan(p1.score);++ // Its own title shown first, case aside.+ expect(p2.top).toMatchObject({ isThis: true, score: p2.score });+ expect(p2.missing).toEqual(['white', 'sneaker', 'city']);+ expect(p2.score).toBe(0);+ });++ it('leaves out a prompt the member can no longer read, and has no top without cards', async () => {+ prompts = [{ id: P2, text: 'White sneakers for the city' }];+ cards = [];+ const matches = await getProductMatchScores(BRAND, 'White City Sneaker', [P1, P2], {+ datePreset: '7d',+ });+ expect(matches).toEqual([+ {+ promptId: P2,+ promptText: 'White sneakers for the city',+ score: 100,+ missing: [],+ top: null,+ },+ ]);+ });++ it('refuses bad input before reading anything', async () => {+ const window = { datePreset: '30d' as const };+ await expect(getProductMatchScores('b1', 'Boot', [P1], window)).rejects.toThrow('invalid');+ await expect(getProductMatchScores(BRAND, ' ', [P1], window)).rejects.toThrow('invalid');+ await expect(getProductMatchScores(BRAND, 'Boot', [], window)).rejects.toThrow('invalid');+ await expect(getProductMatchScores(BRAND, 'Boot', ['p1'], window)).rejects.toThrow('invalid');+ const many = Array.from(+ { length: 21 },+ (_, i) => `${String(i).padStart(8, '0')}-1111-4111-8111-111111111111`,+ );+ await expect(getProductMatchScores(BRAND, 'Boot', many, window)).rejects.toThrow('invalid');+ expect(cardFilters).toEqual([]);+ });+});diff --git a/web/src/lib/actions/shopping.ts b/web/src/lib/actions/shopping.tsindex 63d550c82..2a72871f6 100644--- a/web/src/lib/actions/shopping.ts+++ b/web/src/lib/actions/shopping.ts@@ -6,7 +6,9 @@ import {detectAmazonShareDrop,type AmazonShareDropAlert,} from '@/lib/shopping-amazon-share-alert';+import { z } from 'zod';import { marketRegionCodes, type ShoppingMarket } from '@/lib/shopping/markets';+import { matchScores, missingWords, queryTerms, sameProduct } from '@/lib/shopping/match-score';import {toMerchantSplit,type MerchantSplitRow,@@ -578,6 +580,149 @@ export async function getOwnProducts(return aggregateProducts(data);}+// ── Match with each prompt (#1282) ─────────────────────────────────────────────++/** Prompts read at once for one product's match. */+const MATCH_MAX_PROMPTS = 20;+/** Searches AI ran for a prompt, kept for its query. */+const MATCH_MAX_SEARCHES = 20;++export interface ProductPromptMatch {+ promptId: string;+ promptText: string;+ /** The product's keyword match with the prompt and its searches, 0–100 (Ansvisor estimate). */+ score: number;+ /** The query's words the product's title doesn't have. */+ missing: string[];+ /**+ * The product AI showed first for the prompt in its latest answer in the+ * window, with its score; `isThis` when it's this product. Null with no+ * card in the window.+ */+ top: { title: string; score: number; isThis: boolean } | null;+}++interface MatchCardRow {+ id: string;+ created_at: string;+ position: number | null;+ product_title: string | null;+ prompt_result_id: string;+ prompt_results: { prompt_id: string; search_queries: unknown } | null;+}++/** A result's searches: `search_queries` holds `{ query, source_platform }` entries. */+function searchesOf(value: unknown): string[] {+ if (!Array.isArray(value)) return [];+ return value+ .map((entry) =>+ entry && typeof entry === 'object' ? (entry as { query?: unknown }).query : null,+ )+ .filter((query): query is string => typeof query === 'string' && query.trim() !== '');+}++/**+ * How well one of the brand's own products matches each prompt it was shown+ * for (#1282, part 1: keywords): BM25 between the prompt with the searches AI+ * ran for it and the titles of every product shown for it in the window, as+ * `matchScores` computes. With it, the product AI showed first in the+ * prompt's latest answer, and its score. RLS keeps the cards, results and+ * prompts to the caller's organization.+ */+export async function getProductMatchScores(+ brandId: string,+ productTitle: string,+ promptIds: string[],+ filters: ShoppingFilters,+): Promise<ProductPromptMatch[]> {+ const ids = [...new Set(promptIds)];+ if (+ !z.guid().safeParse(brandId).success ||+ typeof productTitle !== 'string' ||+ !productTitle.trim() ||+ productTitle.length > 500 ||+ !ids.length ||+ ids.length > MATCH_MAX_PROMPTS ||+ !ids.every((id) => z.guid().safeParse(id).success)+ ) {+ throw new Error('invalid');+ }+ const supabase = await createClient();+ const [rows, prompts] = await Promise.all([+ fetchAllCards<MatchCardRow>(() =>+ cardsInWindow(+ supabase,+ brandId,+ filters,+ 'id, created_at, position, product_title, prompt_result_id, prompt_results:prompt_result_id!inner(prompt_id, search_queries)',+ ).in('prompt_results.prompt_id', ids),+ ),+ supabase.from('prompts').select('id, text').in('id', ids),+ ]);+ if (prompts.error) throw new Error(prompts.error.message);+ const textOf = new Map((prompts.data ?? []).map((p) => [p.id as string, p.text as string]));++ const byPrompt = new Map<+ string,+ { titles: string[]; searches: Set<string>; results: Map<string, MatchCardRow[]> }+ >();+ for (const row of rows) {+ const promptId = row.prompt_results?.prompt_id;+ const title = row.product_title?.trim();+ if (!promptId || !title) continue;+ let group = byPrompt.get(promptId);+ if (!group) {+ group = { titles: [], searches: new Set(), results: new Map() };+ byPrompt.set(promptId, group);+ }+ if (!group.titles.some((t) => sameProduct(t, title))) group.titles.push(title);+ for (const query of searchesOf(row.prompt_results?.search_queries)) {+ if (group.searches.size < MATCH_MAX_SEARCHES) group.searches.add(query);+ }+ const cards = group.results.get(row.prompt_result_id) ?? [];+ cards.push(row);+ group.results.set(row.prompt_result_id, cards);+ }++ return ids.flatMap((promptId) => {+ const promptText = textOf.get(promptId);+ if (!promptText) return [];+ const group = byPrompt.get(promptId);+ const terms = queryTerms(promptText, [...(group?.searches ?? [])]);+ const others = (group?.titles ?? []).filter((t) => !sameProduct(t, productTitle));+ const docs = [productTitle, ...others];+ const scores = matchScores(terms, docs);++ // The latest answer's first card: its results ordered by when, then by position.+ let top: ProductPromptMatch['top'] = null;+ const latest = [...(group?.results.values() ?? [])]+ .map((cards) => ({+ at: cards.reduce((m, c) => (c.created_at > m ? c.created_at : m), ''),+ cards,+ }))+ .sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0))[0];+ const first = latest?.cards+ .filter((c) => c.product_title?.trim())+ .sort((a, b) => (a.position ?? Infinity) - (b.position ?? Infinity))[0];+ if (first?.product_title) {+ const title = first.product_title.trim();+ const isThis = sameProduct(title, productTitle);+ const index = isThis ? 0 : docs.findIndex((d) => sameProduct(d, title));+ top = { title, score: scores[index] ?? 0, isThis };+ }++ return [+ {+ promptId,+ promptText,+ score: scores[0],+ missing: missingWords(terms, productTitle),+ top,+ },+ ];+ });+}+export async function getCompetitorProducts(brandId: string,filters: ShoppingFilters,diff --git a/web/src/lib/shopping/match-score.test.ts b/web/src/lib/shopping/match-score.test.tsnew file mode 100644index 000000000..a7c0b1dc8--- /dev/null+++ b/web/src/lib/shopping/match-score.test.ts@@ -0,0 +1,99 @@+import { describe, expect, it } from 'vitest';+import { contentWords, matchScores, missingWords, queryTerms, sameProduct } from './match-score';++/** #1282, part 1: the keyword half of a product's match with a shopping prompt. */++const COMPETING = [+ 'Trailrunner Waterproof Hiking Boot',+ 'City Sneaker Classic White',+ 'Summit Trail Shoe for Wet Rock',+ 'Everyday Running Shoe',+];++describe('contentWords', () => {+ it('keeps the words that say what the product is, as matched', () => {+ expect(contentWords('What are the best waterproof hiking boots for wet rock?')).toEqual([+ 'waterproof',+ 'hiking',+ 'boot',+ 'wet',+ 'rock',+ ]);+ });++ it('lowercases a Turkish İ without a stray dot, and drops Turkish small and intent words', () => {+ expect(contentWords('İSTANBUL için en iyi robot süpürge tavsiyesi')).toEqual([+ 'istanbul',+ 'robot',+ 'süpürge',+ ]);+ });+});++describe('queryTerms', () => {+ it("takes the prompt's words, then its searches', each once", () => {+ expect(+ queryTerms('Best waterproof hiking boots', [+ 'waterproof hiking boots wet rock',+ 'hiking boots grip',+ ]),+ ).toEqual(['waterproof', 'hiking', 'boot', 'wet', 'rock', 'grip']);+ });++ it('keeps at most 30 words', () => {+ const many = Array.from({ length: 40 }, (_, i) => `word${i}`).join(' ');+ expect(queryTerms(many)).toHaveLength(30);+ });+});++describe('matchScores', () => {+ const terms = queryTerms('waterproof hiking boots for wet rock');++ it('scores 0 to 100, the product with more of the words higher', () => {+ const [boot, sneaker, trail] = matchScores(terms, COMPETING);+ expect(boot).toBeGreaterThan(trail);+ expect(trail).toBeGreaterThan(sneaker);+ expect(sneaker).toBe(0);+ for (const score of matchScores(terms, COMPETING)) {+ expect(score).toBeGreaterThanOrEqual(0);+ expect(score).toBeLessThanOrEqual(100);+ }+ });++ it("raises a product's score when it gains a missing word", () => {+ const before = matchScores(terms, COMPETING)[0];+ const after = matchScores(terms, [+ 'Trailrunner Waterproof Hiking Boot for Wet Rock',+ ...COMPETING.slice(1),+ ])[0];+ expect(after).toBeGreaterThan(before);+ });++ it('reads 100 for a product with every word at a typical length', () => {+ expect(matchScores(['boot', 'waterproof'], ['Waterproof boot', 'Waterproof boot'])).toEqual([+ 100, 100,+ ]);+ });++ it('scores 0 with no query words, and an empty list for no products', () => {+ expect(matchScores([], COMPETING)).toEqual([0, 0, 0, 0]);+ expect(matchScores(terms, [])).toEqual([]);+ });+});++describe('missingWords', () => {+ it("lists the query's words the product lacks, never one it has", () => {+ const terms = queryTerms('waterproof hiking boots for wet rock');+ expect(missingWords(terms, 'Trailrunner Waterproof Hiking Boot')).toEqual(['wet', 'rock']);+ expect(missingWords(terms, 'Waterproof hiking boots for wet rock')).toEqual([]);+ });+});++describe('sameProduct', () => {+ it('reads two titles as one product, case, spaces and punctuation aside', () => {+ expect(+ sameProduct('Trailrunner Waterproof-Hiking Boot', 'trailrunner waterproof hiking boot'),+ ).toBe(true);+ expect(sameProduct('Trailrunner Boot', 'Trailrunner Boot 2')).toBe(false);+ });+});diff --git a/web/src/lib/shopping/match-score.ts b/web/src/lib/shopping/match-score.tsnew file mode 100644index 000000000..4b070cb7d--- /dev/null+++ b/web/src/lib/shopping/match-score.ts@@ -0,0 +1,125 @@+/**+ * How well a product matches a shopping prompt (#1282, part 1: keywords).+ *+ * In the US, ChatGPT Shopping seems to rank products by keyword match (BM25)+ * and by meaning (embeddings) between the question and the product's title+ * and opening text. This is the keyword half, our own estimate and never+ * ChatGPT's score: BM25 between the prompt's words, with the searches AI ran+ * for it, and each product competing for it. The meaning half needs an+ * embeddings model, so it comes once that is decided.+ *+ * The score runs 0–100: 100 is a product with every one of the query's words,+ * at a typical title length. Words that say what the shopper wants ("best",+ * "buy", "tavsiye") and the usual small words are left out, so they never+ * count, and never show as missing.+ */++const K1 = 1.2;+const B = 0.75;++/** Most terms a query keeps: the prompt's first, then its searches'. */+const MAX_TERMS = 30;++const STOPWORDS = new Set(+ [+ // English: small words, and the shopper's intent rather than the product.+ 'a an and are as at be but by can do does for from get has have how i if in into is it its me',+ 'my of on or our so than that the their them then there these they this those to under up us',+ 'vs versus was we were what when where which who why will with would you your',+ 'best top good great cheap cheapest buy buying review reviews recommend recommended',+ 'recommendation recommendations need want looking options option alternative alternatives',+ 'should could which worth 2024 2025 2026 2027',+ // Turkish.+ 'acaba ama bana ben bir bu da daha de en gibi hangi hangisi için ile ise kadar ki mi mı mu mü',+ 'ne nedir nasıl olan veya ve ya çok şu tavsiye tavsiyesi öneri önerisi önerir iyi uygun',+ 'alırken almak satın alınır',+ // German, French, Spanish, Italian, Dutch: the commonest small words.+ 'der die das und oder für mit ein eine einen ist sind welche welcher beste besten',+ 'le la les et ou pour avec un une des est sont quel quelle meilleur meilleurs',+ 'el la los las y o para con un una es son cuál mejor mejores',+ 'il lo gli e o per con uno una è sono quale migliore migliori',+ 'de het en of voor met een is zijn welke beste',+ ]+ .join(' ')+ .split(' '),+);++/** A text's words, in order: lowercased (Turkish İ included), letters and digits, two or more. */+function words(text: string): string[] {+ const lower = text+ .normalize('NFKC')+ .toLowerCase()+ // "İ".toLowerCase() leaves a combining dot after the i.+ .replace(/̇/g, '');+ return (lower.match(/[\p{L}\p{N}]+/gu) ?? []).filter((w) => w.length >= 2 || /^\d$/.test(w));+}++/** A word as it's matched: a plain English plural as its singular ("boots" and "boot"). */+function stem(word: string): string {+ return word.length > 3 && word.endsWith('s') && !word.endsWith('ss') ? word.slice(0, -1) : word;+}++/** A text's content words, as matched: no small or intent words. */+export function contentWords(text: string): string[] {+ return words(text)+ .filter((w) => !STOPWORDS.has(w))+ .map(stem);+}++/**+ * A prompt's query: its content words, then those of the searches AI ran+ * for it, each once, at most MAX_TERMS.+ */+export function queryTerms(prompt: string, searches: readonly string[] = []): string[] {+ const terms: string[] = [];+ const seen = new Set<string>();+ for (const text of [prompt, ...searches]) {+ for (const term of contentWords(text)) {+ if (seen.has(term)) continue;+ seen.add(term);+ terms.push(term);+ if (terms.length === MAX_TERMS) return terms;+ }+ }+ return terms;+}++/**+ * Each product's score for a query, 0–100: BM25 over the products competing+ * for it (k1 1.2, b 0.75), against a product that has each of the query's+ * words once at the average length. With no query words, every score is 0.+ */+export function matchScores(terms: readonly string[], products: readonly string[]): number[] {+ const docs = products.map(contentWords);+ const unique = [...new Set(terms)];+ if (!unique.length || !docs.length) return docs.map(() => 0);+ const avgLength = Math.max(1, docs.reduce((sum, d) => sum + d.length, 0) / docs.length);+ const idf = new Map(+ unique.map((term) => {+ const df = docs.filter((d) => d.includes(term)).length;+ return [term, Math.log(1 + (docs.length - df + 0.5) / (df + 0.5))];+ }),+ );+ // With each word once at the average length, a word's part is its idf.+ const ideal = unique.reduce((sum, term) => sum + idf.get(term)!, 0);+ return docs.map((doc) => {+ const norm = K1 * (1 - B + (B * doc.length) / avgLength);+ let score = 0;+ for (const term of unique) {+ const tf = doc.filter((w) => w === term).length;+ if (tf) score += (idf.get(term)! * tf * (K1 + 1)) / (tf + norm);+ }+ return Math.min(100, Math.round((100 * score) / ideal));+ });+}++/** The query's words a product's text doesn't have, in the query's order. */+export function missingWords(terms: readonly string[], product: string): string[] {+ const has = new Set(contentWords(product));+ return [...new Set(terms)].filter((term) => !has.has(term));+}++/** Two product titles name the same product: case, spaces and punctuation aside. */+export function sameProduct(a: string, b: string): boolean {+ return words(a).join(' ') === words(b).join(' ');+}