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): show each catalog category's AI shelf share, products on it, top rival and AI revenue (Product Visibility, part 5) (#1640)
Cihan50ecf93a0733
diff --git a/web/messages/en.json b/web/messages/en.jsonindex 7df416f79..3c1c55ac6 100644--- a/web/messages/en.json+++ b/web/messages/en.json@@ -7986,6 +7986,19 @@"trends": "Trends","failed": "Couldn't read the shelves right now. The other tabs still work; try again in a moment."},+ "categories": {+ "columns": {+ "category": "Category",+ "share": "Shelf share",+ "onShelf": "On shelf",+ "rival": "Top rival",+ "revenue": "AI revenue"+ },+ "prompts": "{count, plural, one {# shopping question} other {# shopping questions}}",+ "attention": "needs attention",+ "empty": "Your catalog has no categories yet. Categories come from your feed's product type or Google product category, or your store's collections.",+ "failed": "Couldn't read your catalog's categories right now. Try again in a moment."+ },"products": {"label": "Your products","viewsLabel": "Product views",@@ -8075,6 +8088,7 @@"lockedTitle": "Upgrade for full shopping analytics","lockedDescription": "Free and Starter plans see the shopping card rate. Growth unlocks the My Products tab, competitor breakdown, card-eligible prompts, and merchant analytics.","tabShelf": "Shelf",+ "tabCategories": "Categories","tabProducts": "Products","tabMyProducts": "My Products","connectCatalog": "These are your products as AI shopping cards showed them. Add your product catalog (a product feed URL or a file you upload) in <link>Settings › Integrations</link>, and the Content Editor checks your product pages' price, GTIN and stock against it.",diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.test.tsxnew file mode 100644index 000000000..4ef7b1057--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.test.tsx@@ -0,0 +1,92 @@+import { act } from 'react';+import { createRoot, type Root } from 'react-dom/client';+import { NextIntlClientProvider } from 'next-intl';+import { afterEach, beforeEach, describe, expect, it } from 'vitest';+import messages from '../../../../../../messages/en.json';+import type { CategoryRow } from '@/lib/shopping/categories';+import { CategoriesTable } from './_categories-table';++/** The Categories table (ECOM-008). */++(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =+ true;++let container: HTMLDivElement;+let root: Root;++beforeEach(() => {+ container = document.createElement('div');+ document.body.appendChild(container);+ root = createRoot(container);+});++afterEach(() => {+ act(() => root.unmount());+ container.remove();+});++function render(node: React.ReactNode) {+ act(() => {+ root.render(+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">+ {node}+ </NextIntlClientProvider>,+ );+ });+ return container.textContent ?? '';+}++const row = (over: Partial<CategoryRow>): CategoryRow => ({+ id: 'shoes',+ name: 'Shoes > Trail running shoes',+ leaf: 'Trail running shoes',+ prompts: 14,+ shelfShare: 0.31,+ productsOnShelf: 6,+ products: 24,+ topRival: { name: 'Summit Gear', domain: 'summitgear.example' },+ revenue: { value: 6100, currency: 'USD' },+ needsAttention: false,+ ...over,+});++describe('CategoriesTable', () => {+ it("lists each category's questions, share, products on shelf, top rival and AI revenue", () => {+ render(+ <CategoriesTable+ categories={[+ row({}),+ row({+ id: 'packs',+ leaf: 'Hiking backpacks',+ prompts: 11,+ shelfShare: 0.04,+ productsOnShelf: 1,+ products: 18,+ revenue: null,+ topRival: null,+ needsAttention: true,+ }),+ ]}+ loading={false}+ failed={false}+ />,+ );+ const cells = [...container.querySelectorAll('tbody tr')].map((tr) =>+ [...tr.querySelectorAll('td')].map((td) => td.textContent),+ );+ expect(cells).toEqual([+ ['Trail running shoes14 shopping questions', '31%', '6 / 24', 'Summit Gear', '$6,100'],+ ['Hiking backpacks11 shopping questions · needs attention', '4%', '1 / 18', '—', '—'],+ ]);+ });++ it('says when the catalog has no categories, or they could not be read', () => {+ expect(render(<CategoriesTable categories={null} loading={false} failed={false} />)).toContain(+ 'Your catalog has no categories yet.',+ );+ expect(render(<CategoriesTable categories={null} loading={false} failed />)).toContain(+ "Couldn't read your catalog's categories right now.",+ );+ });+});diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.tsxnew file mode 100644index 000000000..72673ba66--- /dev/null+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/_categories-table.tsx@@ -0,0 +1,128 @@+'use client';++import { useTranslations } from 'next-intl';+import { Card } from '@/components/ui/card';+import { Skeleton } from '@/components/ui/skeleton';+import {+ Table,+ TableBody,+ TableCell,+ TableHead,+ TableHeader,+ TableRow,+} from '@/components/ui/table';+import { getFaviconUrl } from '@/lib/favicon';+import { formatNumber } from '@/lib/format';+import { priceText } from '@/lib/shopping/price';+import { cn } from '@/lib/utils';+import type { CategoryRow } from '@/lib/shopping/categories';++/**+ * The Categories table (ECOM-008): one row per catalog category, with its+ * shopping questions, the brand's share of their shelves, its products on+ * them, the rival with the most slots there and its products' AI revenue.+ * A category the brand barely shows in is marked "needs attention".+ */+export function CategoriesTable({+ categories,+ loading,+ failed,+}: {+ /** Null for a catalog without categories. */+ categories: CategoryRow[] | null;+ loading: boolean;+ failed: boolean;+}) {+ const t = useTranslations('shopping.categories');+ if (loading) return <Skeleton className="h-[240px] w-full" />;+ if (failed || !categories?.length) {+ return (+ <p className="rounded-lg border border-dashed px-4 py-10 text-center text-sm text-muted-foreground">+ {failed ? t('failed') : t('empty')}+ </p>+ );+ }+ return (+ <Card className="py-0">+ <Table>+ <TableHeader>+ <TableRow>+ <TableHead className="pl-4">{t('columns.category')}</TableHead>+ <TableHead className="text-right">{t('columns.share')}</TableHead>+ <TableHead className="text-right">{t('columns.onShelf')}</TableHead>+ <TableHead>{t('columns.rival')}</TableHead>+ <TableHead className="pr-4 text-right">{t('columns.revenue')}</TableHead>+ </TableRow>+ </TableHeader>+ <TableBody>+ {categories.map((row) => (+ <TableRow+ key={row.id}+ className={cn(row.needsAttention && 'bg-amber-500/5 hover:bg-amber-500/10')}+ >+ <TableCell className="max-w-[260px] pl-4">+ <p className="truncate text-sm font-medium" title={row.name}>+ {row.leaf}+ </p>+ <p className="text-xs text-muted-foreground">+ {t('prompts', { count: row.prompts })}+ {row.needsAttention && (+ <span className="font-medium text-amber-700 dark:text-amber-400">+ {' · '}+ {t('attention')}+ </span>+ )}+ </p>+ </TableCell>+ <TableCell className="text-right">+ {row.shelfShare === null ? (+ <span className="text-muted-foreground">—</span>+ ) : (+ <span className="inline-flex items-center justify-end gap-2">+ <span+ aria-hidden+ className="hidden h-1.5 w-16 overflow-hidden rounded-full bg-muted sm:inline-block"+ >+ <span+ className={cn(+ 'block h-full rounded-full',+ row.needsAttention ? 'bg-amber-500' : 'bg-primary',+ )}+ style={{ width: `${Math.round(row.shelfShare * 100)}%` }}+ />+ </span>+ <span className="tabular-nums">{Math.round(row.shelfShare * 100)}%</span>+ </span>+ )}+ </TableCell>+ <TableCell className="text-right tabular-nums">+ {formatNumber(row.productsOnShelf)} / {formatNumber(row.products)}+ </TableCell>+ <TableCell className="max-w-[180px]">+ {row.topRival ? (+ <span className="flex min-w-0 items-center gap-1.5">+ {row.topRival.domain && (+ // eslint-disable-next-line @next/next/no-img-element -- a rival's favicon+ <img+ src={getFaviconUrl(row.topRival.domain, 32)}+ alt=""+ className="h-3.5 w-3.5 shrink-0 rounded-sm"+ loading="lazy"+ />+ )}+ <span className="truncate text-sm">{row.topRival.name}</span>+ </span>+ ) : (+ <span className="text-muted-foreground">—</span>+ )}+ </TableCell>+ <TableCell className="pr-4 text-right tabular-nums">+ {row.revenue ? priceText(Math.round(row.revenue.value), row.revenue.currency) : '—'}+ </TableCell>+ </TableRow>+ ))}+ </TableBody>+ </Table>+ </Card>+ );+}diff --git a/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsxindex 1acda7f4f..27910345a 100644--- a/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx+++ b/web/src/app/[locale]/(dashboard)/dashboard/shopping/page.tsx@@ -38,6 +38,7 @@ import {getCompetitorProducts,getCompetitorSummary,getShoppingAiOrders,+ getShoppingCategories,getShoppingProducts,getShoppingShelf,type ShoppingChartData,@@ -88,12 +89,14 @@ import { toCsv } from '@/lib/csv';import { PLATFORM_LABELS } from '@/config/platform-labels';import { formatRegionDisplay } from '@/lib/region';import type { AmazonShareDropAlert } from '@/lib/shopping-amazon-share-alert';+import type { CategoryRow } from '@/lib/shopping/categories';import { formatNumber } from '@/lib/format';import { HeaderWithAiUsage } from '@/components/ai-usage/ai-usage-meter';import { googleSourceStatus } from '@/lib/traffic-sources';import { readUrlChoice, writeUrlParams } from '@/lib/url-state';import { CatalogNote } from './_catalog-note';import { ProductDataStrip, useProductSources } from './_data-strip';+import { CategoriesTable } from './_categories-table';import { ProductsTable } from './_products-table';import { ShelfKpis, ShelfRows } from './_shelf';import { ShoppingMarketSwitch, useShoppingMarket } from './_market-switch';@@ -109,7 +112,7 @@ import { useOpenAiIndex } from './use_openai_index';const DATE_PRESETS: ShoppingDatePreset[] = ['7d', '30d', '90d', 'all'];/** The page's tabs, the one open in the URL (?tab=products). */-const SHOPPING_TABS = ['shelf', 'products', 'competitors'] as const;+const SHOPPING_TABS = ['shelf', 'categories', 'products', 'competitors'] as const;type ShoppingTab = (typeof SHOPPING_TABS)[number];// Theme tokens in globals.css ship as full oklch values; reference them@@ -147,6 +150,11 @@ export default function ShoppingPage() {const [competitorProducts, setCompetitorProducts] = useState<ShoppingProduct[]>([]);const [competitorSummary, setCompetitorSummary] = useState<CompetitorShoppingSummary[]>([]);const [orders, setOrders] = useState<ShoppingAiOrders | null>(null);+ // The catalog's categories (ECOM-008), read when their tab opens, for the filters they were read with.+ const [categories, setCategories] = useState<{+ key: string;+ rows: CategoryRow[] | null | 'failed';+ } | null>(null);const [tableLoading, setTableLoading] = useState(false);const [selectedProduct, setSelectedProduct] = useState<ShoppingProduct | null>(null);const [activeTab, setActiveTab] = useState<ShoppingTab>('shelf');@@ -279,6 +287,34 @@ export default function ShoppingPage() {// Null for a brand without a catalog, and while it reads.const catalogTable: ShoppingProducts | null | 'failed' = productsRead ?? null;+ // The Categories tab reads when it's open, once per brand and filters.+ const categoriesKey = `${activeBrandId}:${JSON.stringify(filters)}`;+ useEffect(() => {+ if (activeTab !== 'categories' || !activeBrandId || !hasFullAccess) return;+ if (!shoppingMarket.ready || categories?.key === categoriesKey) return;+ let cancelled = false;+ getShoppingCategories(activeBrandId, filters)+ .then((rows) => {+ if (!cancelled) setCategories({ key: categoriesKey, rows });+ })+ .catch((err) => {+ console.error('Failed to read the categories:', err);+ if (!cancelled) setCategories({ key: categoriesKey, rows: 'failed' });+ });+ return () => {+ cancelled = true;+ };+ }, [+ activeTab,+ activeBrandId,+ hasFullAccess,+ shoppingMarket.ready,+ categoriesKey,+ categories?.key,+ filters,+ ]);+ const categoriesRead = categories?.key === categoriesKey ? categories.rows : undefined;+// Orders from AI visits, the last 30 days whatever the filters (ECOM-006).useEffect(() => {if (!activeBrandId || !hasFullAccess) return;@@ -397,6 +433,14 @@ export default function ShoppingPage() {><TabsList><TabsTrigger value="shelf">{t('tabShelf')}</TabsTrigger>+ <TabsTrigger value="categories">+ {t('tabCategories')}+ {Array.isArray(categoriesRead) && (+ <span className="ml-1.5 text-xs tabular-nums text-muted-foreground">+ {categoriesRead.length}+ </span>+ )}+ </TabsTrigger><TabsTrigger value="products">{t('tabProducts')}</TabsTrigger><TabsTrigger value="competitors">{t('tabCompetitors')}</TabsTrigger></TabsList>@@ -457,6 +501,18 @@ export default function ShoppingPage() {)}</TabsContent>+ <TabsContent value="categories" className="space-y-6">+ {hasFullAccess ? (+ <CategoriesTable+ categories={categoriesRead === 'failed' ? null : (categoriesRead ?? null)}+ loading={categoriesRead === undefined}+ failed={categoriesRead === 'failed'}+ />+ ) : (+ <UpgradeCard t={t} requiredPlan={requiredPlanFor('shopping_analytics')} />+ )}+ </TabsContent>+<TabsContent value="products" className="space-y-6">{hasFullAccess && (productsLoading || (catalogTable && catalogTable !== 'failed')) ? (<ProductsTablediff --git a/web/src/lib/actions/shopping-categories.test.ts b/web/src/lib/actions/shopping-categories.test.tsnew file mode 100644index 000000000..61d1f3a46--- /dev/null+++ b/web/src/lib/actions/shopping-categories.test.ts@@ -0,0 +1,128 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';++/** The Categories read (ECOM-008): the catalog's categories, their live products, the cards and the rivals. */++const BRAND = '33333333-3333-3333-3333-333333333333';++let tables: Record<string, Record<string, unknown>[]>;+let stats: Record<string, unknown>[];+// The pages of catalog_product_ai_stats read.+let statsPages: [number, number][];++/** An RPC's rows, a page of at most 1000 as PostgREST gives them. */+function rpcRows() {+ let range: [number, number] = [0, 999];+ const q = {+ order: () => q,+ range: (from: number, to: number) => ((range = [from, to]), statsPages.push(range), q),+ then: (resolve: (value: unknown) => void) =>+ resolve({ data: stats.slice(range[0], Math.min(range[1], range[0] + 999) + 1), error: null }),+ };+ return q;+}++function query(table: string) {+ let range: [number, number] | undefined;+ const q = {+ select: () => q,+ eq: () => q,+ is: () => q,+ in: () => q,+ not: () => q,+ gte: () => q,+ lte: () => q,+ or: () => q,+ order: () => q,+ range: (from: number, to: number) => ((range = [from, to]), q),+ then: (resolve: (value: unknown) => void) => {+ const [from, to] = range ?? [0, 999];+ resolve({ data: (tables[table] ?? []).slice(from, to + 1), error: null });+ },+ };+ return q;+}++vi.mock('@/lib/supabase/server', () => ({+ createClient: vi.fn(async () => ({+ from: query,+ rpc: () => rpcRows(),+ })),+}));++const { getShoppingCategories } = await import('./shopping');++beforeEach(() => {+ tables = {};+ stats = [];+ statsPages = [];+});++describe('getShoppingCategories', () => {+ it('reads no categories as none', async () => {+ expect(await getShoppingCategories(BRAND, { datePreset: '30d' })).toBeNull();+ });++ it("counts a category's live products only, and names a competitor's card by the competitor", async () => {+ tables.catalog_categories = [{ id: 'packs', name: 'Hiking backpacks' }];+ tables.catalog_products = [{ id: 'ridge' }];+ tables.catalog_product_categories = [+ { product_id: 'ridge', category_id: 'packs' },+ { product_id: 'removed', category_id: 'packs' },+ ];+ tables.competitors = [{ id: 'c1', name: 'Summit Gear', domain: 'summitgear.example' }];+ tables.prompt_result_shopping_cards = [+ {+ matched_brand_role: 'competitor',+ matched_brand_id: 'c1',+ product_brand: 'Summit',+ merchant_domain: 'rei.com',+ catalog_product_id: null,+ prompt_results: { prompt: { id: 'q1', text: 'best hiking backpack' } },+ },+ {+ matched_brand_role: 'own',+ matched_brand_id: 'brand',+ product_brand: 'Northwind',+ merchant_domain: 'northwind.example',+ catalog_product_id: 'ridge',+ prompt_results: { prompt: { id: 'q1', text: 'best hiking backpack' } },+ },+ { matched_brand_role: 'other', prompt_results: null },+ ];+ stats = [{ product_id: 'ridge', ai_visits: 4, orders: 1, revenue: '119.00', currency: 'USD' }];+ expect(await getShoppingCategories(BRAND, { datePreset: '30d' })).toEqual([+ {+ id: 'packs',+ name: 'Hiking backpacks',+ leaf: 'Hiking backpacks',+ prompts: 1,+ shelfShare: 0.5,+ productsOnShelf: 1,+ products: 1,+ topRival: { name: 'Summit Gear', domain: 'summitgear.example' },+ revenue: { value: 119, currency: 'USD' },+ needsAttention: false,+ },+ ]);+ });++ it("reads every page of the products' AI revenue, past PostgREST's 1000 rows", async () => {+ tables.catalog_categories = [{ id: 'packs', name: 'Hiking backpacks' }];+ tables.catalog_products = [{ id: 'p1200' }];+ tables.catalog_product_categories = [{ product_id: 'p1200', category_id: 'packs' }];+ stats = Array.from({ length: 1201 }, (_, i) => ({+ product_id: `p${i}`,+ ai_visits: 1,+ orders: 1,+ revenue: '10.00',+ currency: 'USD',+ }));+ const [packs] = (await getShoppingCategories(BRAND, { datePreset: '30d' }))!;+ expect(statsPages).toEqual([+ [0, 999],+ [1000, 1999],+ ]);+ // The 1,201st product's revenue, past the first page.+ expect(packs.revenue).toEqual({ value: 10, currency: 'USD' });+ });+});diff --git a/web/src/lib/actions/shopping.ts b/web/src/lib/actions/shopping.tsindex 0c3df0e96..d8162426d 100644--- a/web/src/lib/actions/shopping.ts+++ b/web/src/lib/actions/shopping.ts@@ -17,6 +17,7 @@ import {type ShelfRow,type ShelfStats,} from '@/lib/shopping/shelf';+import { categoryRows, type CategoryCardRow, type CategoryRow } from '@/lib/shopping/categories';import {productRows,type CatalogProductRow,@@ -1528,3 +1529,109 @@ async function readCatalogProducts(};});}++// ── Categories (Product Visibility, ECOM-008) ─────────────────────────────────++/**+ * The Categories table: each category of the brand's catalog with its+ * shopping questions, the brand's share of their shelves, its products on+ * them, the top rival there and its products' AI revenue, over the filter+ * window. Null when the catalog has no categories.+ */+export async function getShoppingCategories(+ brandId: string,+ filters: ShoppingFilters,+): Promise<CategoryRow[] | null> {+ const supabase = await createClient();+ const categories = await readCatalogRows<{ id: string; name: string }>(+ () =>+ supabase.from('catalog_categories').select('id, name').eq('brand_id', brandId).order('id'),+ CARD_MAX_ROWS,+ );+ if (!categories.length) return null;++ const { from } = resolveDateRange(filters);+ const [live, links, cards, competitors, stats] = await Promise.all([+ readCatalogRows<{ id: string }>(+ () =>+ supabase+ .from('catalog_products')+ .select('id')+ .eq('brand_id', brandId)+ .is('removed_at', null)+ .order('id'),+ CARD_MAX_ROWS,+ ),+ readCatalogRows<{ product_id: string; category_id: string }>(+ () =>+ supabase+ .from('catalog_product_categories')+ .select('product_id, category_id')+ .eq('brand_id', brandId)+ .order('product_id')+ .order('category_id'),+ CARD_MAX_ROWS,+ ),+ fetchAllCards<{+ matched_brand_role: string;+ matched_brand_id: string | null;+ product_brand: string | null;+ merchant_domain: string | null;+ catalog_product_id: string | null;+ prompt_results: { prompt: { id: string; text: string } | null } | null;+ }>(() =>+ cardsInWindow(+ supabase,+ brandId,+ filters,+ 'matched_brand_role, matched_brand_id, product_brand, merchant_domain, catalog_product_id, prompt_results:prompt_result_id ( prompt:prompt_id ( id, text ) )',+ ),+ ),+ supabase.from('competitors').select('id, name, domain').eq('brand_id', brandId),+ readProductAiStats(supabase, brandId, from ?? daysAgoIso(90)),+ ]);+ if (competitors.error) throw new Error(competitors.error.message);++ const liveIds = new Set(live.map((row) => row.id));+ const productsOf = new Map<string, string[]>();+ for (const link of links) {+ if (!liveIds.has(link.product_id)) continue;+ if (!productsOf.has(link.category_id)) productsOf.set(link.category_id, []);+ productsOf.get(link.category_id)!.push(link.product_id);+ }+ const rows: CategoryCardRow[] = cards.flatMap((card) => {+ const prompt = card.prompt_results?.prompt;+ if (!prompt) return [];+ return [+ {+ promptId: prompt.id,+ promptText: prompt.text,+ role: card.matched_brand_role,+ competitorId: card.matched_brand_role === 'competitor' ? card.matched_brand_id : null,+ productBrand: card.product_brand,+ merchant: card.merchant_domain,+ productId: card.catalog_product_id,+ },+ ];+ });+ return categoryRows(+ categories.map((category) => ({+ id: category.id,+ name: category.name,+ productIds: productsOf.get(category.id) ?? [],+ })),+ rows,+ {+ competitors: new Map(+ (competitors.data ?? []).map((c) => [c.id, { name: c.name, domain: c.domain }]),+ ),+ revenueOf: new Map(+ stats.flatMap((row) =>+ row.orders && row.revenue !== null+ ? [[row.product_id, { value: Number(row.revenue), currency: row.currency }] as const]+ : [],+ ),+ ),+ },+ );+}diff --git a/web/src/lib/shopping/categories.test.ts b/web/src/lib/shopping/categories.test.tsnew file mode 100644index 000000000..698602002--- /dev/null+++ b/web/src/lib/shopping/categories.test.ts@@ -0,0 +1,149 @@+import { describe, expect, it } from 'vitest';+import { categoryLeaf, categoryRows, categoryWords, type CategoryCardRow } from './categories';++/** Product Visibility's Categories (ECOM-008). */++const card = (over: Partial<CategoryCardRow>): CategoryCardRow => ({+ promptId: 'q1',+ promptText: 'lightweight 30L hiking backpack for women',+ role: 'competitor',+ competitorId: 'c-summit',+ productBrand: 'Summit Gear',+ merchant: 'summitgear.example',+ productId: null,+ ...over,+});++const competitors = new Map([+ ['c-summit', { name: 'Summit Gear', domain: 'summitgear.example' }],+ ['c-trail', { name: 'TrailCo', domain: 'trailco.example' }],+]);++describe('categoryWords and categoryLeaf', () => {+ it('reads a category as its last level, its words singular', () => {+ expect(categoryLeaf('Bags > Hiking backpacks')).toBe('Hiking backpacks');+ expect(categoryLeaf('Shoes / Trail running')).toBe('Trail running');+ expect(categoryWords('Hiking backpacks & Accessories')).toEqual([+ 'hiking',+ 'backpack',+ 'accessory',+ ]);+ expect(categoryWords('Glasses')).toEqual(['glass']);+ });+});++describe('categoryRows', () => {+ const categories = [+ { id: 'packs', name: 'Bags > Hiking backpacks', productIds: ['ridge', 'trail28'] },+ { id: 'jackets', name: 'Rain jackets', productIds: ['storm'] },+ { id: 'empty', name: 'Tents', productIds: [] },+ ];+ const cards = [+ // "hiking backpack" in the question: the backpacks', the brand nowhere on it.+ card({}),+ card({ competitorId: 'c-trail', productBrand: 'TrailCo' }),+ card({}),+ card({+ promptId: 'q2',+ promptText: 'best daypack for women',+ role: 'own',+ competitorId: null,+ productId: 'ridge',+ }),+ card({+ promptId: 'q2',+ promptText: 'best daypack for women',+ role: 'other',+ competitorId: null,+ productBrand: 'Alpine Supply',+ merchant: null,+ }),+ // A jacket question, its name not in it: the brand's jacket on its shelf makes it the category's.+ card({+ promptId: 'q3',+ promptText: 'warm waterproof shell for winter',+ role: 'own',+ competitorId: null,+ productId: 'storm',+ }),+ card({ promptId: 'q3', promptText: 'warm waterproof shell for winter' }),+ ];+ const revenueOf = new Map([+ ['storm', { value: 7200, currency: 'USD' }],+ ['ridge', { value: 100, currency: 'EUR' }],+ ['trail28', { value: 300, currency: 'USD' }],+ ]);+ const rows = categoryRows(categories, cards, { competitors, revenueOf });+ const byId = Object.fromEntries(rows.map((row) => [row.id, row]));++ it("finds each category's questions by its name, or by its products on their shelves", () => {+ expect(byId.packs).toMatchObject({ leaf: 'Hiking backpacks', prompts: 2 });+ expect(byId.jackets).toMatchObject({ leaf: 'Rain jackets', prompts: 1 });+ });++ it("counts the brand's share of the shelves, its products on them, and the rival with most slots", () => {+ expect(byId.packs).toMatchObject({+ shelfShare: 1 / 5,+ productsOnShelf: 1,+ products: 2,+ topRival: { name: 'Summit Gear', domain: 'summitgear.example' },+ });+ expect(byId.jackets).toMatchObject({ shelfShare: 0.5, productsOnShelf: 1, products: 1 });+ });++ it("adds up its products' AI revenue in their main currency", () => {+ expect(byId.jackets.revenue).toEqual({ value: 7200, currency: 'USD' });+ // One sale in each currency: the first product's.+ expect(byId.packs.revenue).toEqual({ value: 100, currency: 'EUR' });+ });++ it('leaves out a category without products, and lists the most questions first', () => {+ expect(rows.map((row) => row.id)).toEqual(['packs', 'jackets']);+ });++ it('marks a category the brand barely shows in, once it has enough questions', () => {+ const many = categoryRows(+ [{ id: 'packs', name: 'Hiking backpacks', productIds: ['ridge'] }],+ [+ ...['q1', 'q2', 'q3'].flatMap((promptId) =>+ Array.from({ length: 10 }, () =>+ card({ promptId, promptText: `hiking backpacks ${promptId}` }),+ ),+ ),+ card({ role: 'own', competitorId: null, productId: 'ridge' }),+ ],+ { competitors, revenueOf: new Map() },+ );+ expect(many[0]).toMatchObject({ prompts: 3, needsAttention: true, revenue: null });+ expect(byId.packs.needsAttention).toBe(false);+ });++ it("reads a big catalog's categories without walking every card for each", () => {+ // 1,000 collections of 10 products, each named "… > Hiking backpacks", so+ // each is in all of 1,000 questions and their 50,000 cards.+ const many = Array.from({ length: 1000 }, (_, i) => ({+ id: `c${i}`,+ name: `Line ${i} > Hiking backpacks`,+ productIds: Array.from({ length: 10 }, (_, j) => `p${i * 10 + j}`),+ }));+ const shelves = Array.from({ length: 50_000 }, (_, i) =>+ card({+ promptId: `q${i % 1000}`,+ promptText: `best hiking backpack for women ${i % 1000}`,+ role: i % 5 ? 'competitor' : 'own',+ competitorId: i % 5 ? 'c-summit' : null,+ productId: i % 5 ? null : `p${i % 10_000}`,+ }),+ );+ const started = Date.now();+ const read = categoryRows(many, shelves, { competitors, revenueOf: new Map() });+ expect(Date.now() - started).toBeLessThan(1500);+ // Its products p70 and p75 were on a shelf; p71…p74 and p76…p79 weren't.+ expect(read.find((row) => row.id === 'c7')).toMatchObject({+ prompts: 1000,+ shelfShare: 0.2,+ productsOnShelf: 2,+ topRival: { name: 'Summit Gear' },+ });+ });+});diff --git a/web/src/lib/shopping/categories.ts b/web/src/lib/shopping/categories.tsnew file mode 100644index 000000000..5fdbdc2a9--- /dev/null+++ b/web/src/lib/shopping/categories.ts@@ -0,0 +1,224 @@+/**+ * Product Visibility's Categories (ECOM-008): for each category of the+ * brand's catalog, the shopping questions it answers, the brand's share of+ * the product slots on their shelves, how many of its products made a shelf,+ * the rival with the most slots there, and what its products sold from AI.+ *+ * A question is the category's when the category's own name is in it+ * ("Hiking backpacks" in "lightweight 30L hiking backpack for women", plural+ * or not), or when one of the category's products was on its shelf.+ */++export interface CategoryInput {+ id: string;+ /** As the catalog names it, maybe a path: "Bags > Hiking backpacks". */+ name: string;+ productIds: readonly string[];+}++/** A card of a shopping answer, as the categories read it. */+export interface CategoryCardRow {+ promptId: string;+ promptText: string;+ role: string;+ /** The competitor it's matched to, for a competitor's card. */+ competitorId: string | null;+ productBrand: string | null;+ merchant: string | null;+ /** The catalog product it shows, for the brand's own card (00360). */+ productId: string | null;+}++export interface CategoryRow {+ id: string;+ name: string;+ /** The category's last level, as the table names it. */+ leaf: string;+ prompts: number;+ /** The brand's share of the slots on the category's shelves; null with none. */+ shelfShare: number | null;+ productsOnShelf: number;+ products: number;+ topRival: { name: string; domain: string | null } | null;+ revenue: { value: number; currency: string | null } | null;+ needsAttention: boolean;+}++/** A category needs attention below this share of its shelves… */+export const ATTENTION_SHARE = 0.1;+/** …once it has at least this many questions. */+export const ATTENTION_PROMPTS = 3;++const FILLER = new Set(['and', 'for', 'the', 'of', 'with', 'a', 'an', '&']);++function singular(word: string): string {+ if (word.length > 4 && word.endsWith('ies')) return `${word.slice(0, -3)}y`;+ if (word.length > 4 && /(ss|x|ch|sh)es$/.test(word)) return word.slice(0, -2);+ if (word.length > 3 && word.endsWith('s') && !word.endsWith('ss')) return word.slice(0, -1);+ return word;+}++/** A text's words, lowercased, accents folded and singular. */+export function categoryWords(text: string): string[] {+ return text+ .toLowerCase()+ .normalize('NFKD')+ .replace(/\p{M}/gu, '')+ .split(/[^\p{L}\p{N}]+/u)+ .filter((word) => word && !FILLER.has(word))+ .map(singular);+}++/** A category path's last level: "Bags > Hiking backpacks" → "Hiking backpacks". */+export function categoryLeaf(name: string): string {+ return (+ name+ .split(/\s*[>/›]\s*/)+ .filter(Boolean)+ .at(-1) ?? name+ ).trim();+}++/** A rival on a question's shelves: its slots, and the card that named it first (`at`). */+interface RivalSlots {+ name: string;+ domain: string | null;+ slots: number;+ at: number;+}++/** A question's shelves, counted once for every category it's in. */+interface PromptShelves {+ words: Set<string>;+ /** The catalog products on its shelves. */+ products: Set<string>;+ slots: number;+ ownSlots: number;+ rivals: Map<string, RivalSlots>;+}++export function categoryRows(+ categories: readonly CategoryInput[],+ cards: readonly CategoryCardRow[],+ {+ competitors,+ revenueOf,+ }: {+ competitors: ReadonlyMap<string, { name: string; domain: string | null }>;+ revenueOf: ReadonlyMap<string, { value: number; currency: string | null }>;+ },+): CategoryRow[] {+ // Each question's words and shelves, and the questions each product was on:+ // a category adds up its questions' counts rather than reading every card+ // again, so a big catalog's categories don't each walk all the cards.+ const prompts = new Map<string, PromptShelves>();+ const promptsOf = new Map<string, Set<string>>();+ cards.forEach((card, at) => {+ let prompt = prompts.get(card.promptId);+ if (!prompt) {+ prompt = {+ words: new Set(categoryWords(card.promptText)),+ products: new Set(),+ slots: 0,+ ownSlots: 0,+ rivals: new Map(),+ };+ prompts.set(card.promptId, prompt);+ }+ prompt.slots += 1;+ if (card.productId) {+ prompt.products.add(card.productId);+ if (!promptsOf.has(card.productId)) promptsOf.set(card.productId, new Set());+ promptsOf.get(card.productId)!.add(card.promptId);+ }+ if (card.role === 'own') {+ prompt.ownSlots += 1;+ return;+ }+ const competitor = card.competitorId ? competitors.get(card.competitorId) : undefined;+ const name = competitor?.name ?? card.productBrand?.trim();+ if (!name) return;+ const key = name.toLowerCase();+ const rival = prompt.rivals.get(key) ?? {+ name,+ domain: competitor?.domain ?? card.merchant,+ slots: 0,+ at,+ };+ rival.slots += 1;+ prompt.rivals.set(key, rival);+ });++ return categories+ .filter((category) => category.productIds.length > 0)+ .map((category): CategoryRow => {+ const leaf = categoryLeaf(category.name);+ const words = categoryWords(leaf);+ const own = new Set(category.productIds);+ const mine = new Set<string>();+ if (words.length > 0) {+ for (const [id, prompt] of prompts) {+ if (words.every((word) => prompt.words.has(word))) mine.add(id);+ }+ }+ for (const id of own) for (const promptId of promptsOf.get(id) ?? []) mine.add(promptId);++ let slots = 0;+ let ownSlots = 0;+ // A rival's name and domain as the first card naming it gave them.+ const rivals = new Map<string, RivalSlots>();+ const shown = new Set<string>();+ for (const id of mine) {+ const prompt = prompts.get(id)!;+ slots += prompt.slots;+ ownSlots += prompt.ownSlots;+ for (const [key, rival] of prompt.rivals) {+ const kept = rivals.get(key);+ if (!kept) rivals.set(key, { ...rival });+ else {+ kept.slots += rival.slots;+ if (rival.at < kept.at) Object.assign(kept, { ...rival, slots: kept.slots });+ }+ }+ for (const productId of prompt.products) if (own.has(productId)) shown.add(productId);+ }+ const top = [...rivals.values()].sort(+ (a, b) => b.slots - a.slots || a.name.localeCompare(b.name),+ )[0];+ // Its products' AI revenue, in their main currency.+ const sales = category.productIds.flatMap((id) => {+ const sale = revenueOf.get(id);+ return sale ? [sale] : [];+ });+ const currencies = new Map<string, number>();+ for (const sale of sales) {+ currencies.set(sale.currency ?? '', (currencies.get(sale.currency ?? '') ?? 0) + 1);+ }+ const main = [...currencies].sort((a, b) => b[1] - a[1])[0]?.[0];+ const shelfShare = slots ? ownSlots / slots : null;+ return {+ id: category.id,+ name: category.name,+ leaf,+ prompts: mine.size,+ shelfShare,+ productsOnShelf: shown.size,+ products: category.productIds.length,+ topRival: top ? { name: top.name, domain: top.domain } : null,+ revenue:+ main === undefined+ ? null+ : {+ value: sales+ .filter((sale) => (sale.currency ?? '') === main)+ .reduce((sum, sale) => sum + sale.value, 0),+ currency: main || null,+ },+ needsAttention:+ mine.size >= ATTENTION_PROMPTS && shelfShare !== null && shelfShare < ATTENTION_SHARE,+ };+ })+ .sort(+ (a, b) => b.prompts - a.prompts || b.products - a.products || a.leaf.localeCompare(b.leaf),+ );+}