Skip to content

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.

feat(catalog): match each catalog category to its page on the brand's site (shopping path, part 1) (#1587)

Cihanec1db343a55d
diff --git a/server/src/lib/catalog/__fixtures__/fake-db.js b/server/src/lib/catalog/__fixtures__/fake-db.js
index 0c9979d49..d7b658ac1 100644
--- a/server/src/lib/catalog/__fixtures__/fake-db.js
+++ b/server/src/lib/catalog/__fixtures__/fake-db.js
@@ -14,6 +14,7 @@ export function fakeDb() {
const uniqueKey = (table, row) => {
if (table === 'catalog_categories') return `${row.brand_id}|${row.name}`;
if (table === 'catalog_source_credentials') return row.source_id;
+ if (table === 'catalog_category_pages') return `${row.brand_id}|${row.category}`;
return `${row.brand_id}|${row.source}|${row.external_id}`;
};
// The unique keys' rows, by table, as the database's unique indexes find them.
diff --git a/server/src/lib/catalog/category-pages.js b/server/src/lib/catalog/category-pages.js
new file mode 100644
index 000000000..7599b0b2f
--- /dev/null
+++ b/server/src/lib/catalog/category-pages.js
@@ -0,0 +1,465 @@
+import supabaseAdmin from '../../config/supabase.js';
+import { normHost, onBrandDomain } from '../audit/host.js';
+import { foldLetters } from '../letters.js';
+
+/**
+ * Where each catalog category lives on the brand's site (shopping path, 00350):
+ * the page a buying guide or a comparison links for "hiking boots".
+ *
+ * A category with no decision is matched, on every read, to one of the
+ * brand's own pages (site_pages, 00104) whose address reads as a category
+ * page by the editor's page types for a shop (web/src/lib/content/
+ * page-types.ts, PATH_SIGNS; both sides test the cases in web/src/lib/
+ * content/__fixtures__/category-paths.json): /collections/…, /c/…,
+ * /shop/…, WooCommerce's /product-category/…, and the same words in
+ * Turkish, German, French and Spanish (/kategori/…); never a product page,
+ * a themed collection (gifts, a sale), a size guide, a comparison, a
+ * best-of list or a blog's own section (/blog/category/…). A /category/
+ * page is as often WordPress's blog archive as a shop's category, so it
+ * counts only on a host with product pages and none of WooCommerce's
+ * /product-category/ ones, and when its title isn't an archive's.
+ *
+ * The best match wins:
+ * 1. 'address': the page's last path segment is the category's name
+ * ("Shoes > Hiking Boots" → hiking-boots), its parent's words allowed
+ * beside it ("Men > Shoes" → mens-shoes);
+ * 2. 'title': the page's title or h1 holds the category's name;
+ * 3. 'words': most of the name's words are in the address or the title.
+ * A one-word name ("Shoes") matches by its address only: running-shoes
+ * isn't the shoes page. Ties go to the page naming more of the parent's
+ * words, then to the page AI cites, then visits, more. When categories
+ * find the same page, the one naming more of its parent's words there
+ * keeps it ("Women > Shoes" keeps "Women's shoes") and the others take
+ * their next page, or none. A person's decision (catalog_category_pages)
+ * replaces the match: a page, or none.
+ */
+
+/** Site pages read for a brand at most (site_pages keeps 500). */
+const MAX_PAGES = 500;
+/** Share of a category's words a page must hold for a 'words' match. */
+export const WORDS_SHARE = 0.66;
+/** Product links read for a brand with no domain stored, to know its site. */
+const MAX_PRODUCT_LINKS = 100;
+
+/** "What is …" that asks for something else (the editor's NOT_DEFINED). */
+const NOT_DEFINED =
+ 'best|differences?|costs?|prices?|benefits?|advantages?|disadvantages?|pros|cons|new|latest';
+
+/**
+ * The editor's signs a shop's page meets before its categories' (page-types.ts,
+ * PATH_SIGNS), so never a category page: a size guide, alternatives, a
+ * comparison, a definition, a policy, help, a buying guide, a best-of list,
+ * a product, a themed collection, a blog's own section.
+ */
+const NOT_CATEGORY = [
+ /(^|[/-])(size-?(guides?|charts?)|sizing-guides?|fit-guides?)([/-]|$)|\/sizing([/-]|$)/,
+ /(^|[/-])alternatives?([/-]|$)/,
+ /(^|[/-])(vs|versus)([/-]|$)|\/(compare|comparisons?)(\/|$)/,
+ new RegExp(
+ `\\/(glossary|definitions?|dictionary)([/-]|$)|\\/what-(is|are)(?!-(the-)?(${NOT_DEFINED})([/-]|$))([/-]|$)`,
+ ),
+ /\/(shipping|delivery|returns?|refunds?|exchanges?|warranty|polic(y|ies)|terms|privacy|legal)([/-]|$)/,
+ /\/(docs|documentation|help|help-center|support|faqs?|knowledge-base|kb)(\/|$)/,
+ /\/(buying-guides?|buyers?-guides?|how-to-choose)([/-]|$)/,
+ /\/(the-)?(best(?!-(practices?|time|ways?|sellers?)([/-]|$))|top-?\d+)([/-]|$)/,
+ /\/(products?|p|dp|items?)\/[^/]+/,
+ /\/collections?\/(?:[^/]*-)?(gifts?|bundles?|kits?|sets?|best-?sellers?|new-arrivals?|picks|edit|sale|clearance|outlet|deals?|offers?)(?:-|\/|$)|\/collections?\/(?:[^/]*-)?for-[a-z]/,
+ /^(\/[a-z]{2}(-[a-z]{2})?)?\/(blogs?|news|articles?|posts?|insights|stories|magazine|journal)\//,
+];
+
+/** The words WordPress names its blog's categories with too (/category/, /kategori/…). */
+const ARCHIVE_WORDS =
+ 'categor(?:y|ies)|kategori(?:ler)?|kategorie(?:n)?|categorie(?:s)?|categorias?';
+/** WooCommerce's product categories, whose site keeps its blog's at /category/. */
+const WOO_WORDS =
+ 'product-categor(?:y|ies)|urun-kategori(?:si)?|produkt-kategorie|categorie-produit|categoria-(?:producto|prodotto|produto)';
+/** The words only a shop names its categories with. */
+const SHOP_WORDS = `collections?|${WOO_WORDS}|koleksiyon(?:lar)?|kollektion(?:en)?|c|shop|catalog|departments?`;
+const CATEGORY_PATH = new RegExp(`\\/(${SHOP_WORDS}|${ARCHIVE_WORDS})\\/[^/]+`);
+const ARCHIVE_WORD = new RegExp(`^(?:${ARCHIVE_WORDS})$`);
+const WOO_PATH = new RegExp(`\\/(?:${WOO_WORDS})\\/`);
+/** A product page in the words shops use (Wix's /product-page/, IdeaSoft's /urun/…): a host that sells. */
+const PRODUCT_PAGE =
+ /\/(products?|product-page|p|dp|items?|urun(ler)?|produkte?|produits?|productos?|prodott[oi])\/[^/]+/;
+/** A WordPress archive's title: "Hiking Boots Archives", "Category: Hiking Boots". */
+const ARCHIVE_TITLE =
+ /\barchiv(e|es|os)?\b|arşiv|^\s*(category|kategori|kategorie|catégorie|categoría|categoria)\s*:/i;
+
+/** The lowercased path with no trailing slash or page extension, or null. */
+function pathOf(url) {
+ try {
+ return new URL(url).pathname
+ .toLowerCase()
+ .replace(/\.(html?|php|aspx?)$/, '')
+ .replace(/\/+$/, '');
+ } catch {
+ return null;
+ }
+}
+
+/** A path segment as it reads ("%C3%A7" → "ç"); a broken escape ("100%-cotton", Latin-1 "%E9") as it is. */
+function decoded(segment) {
+ try {
+ return decodeURIComponent(segment);
+ } catch {
+ return segment;
+ }
+}
+
+/**
+ * A category page's last path segment ("hiking-boots") and the word that
+ * makes it one ("collections"), or null when the address isn't one.
+ */
+function categoryPath(url) {
+ const path = pathOf(url);
+ if (!path || NOT_CATEGORY.some((sign) => sign.test(path))) return null;
+ const found = CATEGORY_PATH.exec(path);
+ if (!found) return null;
+ return { slug: decoded(path.slice(path.lastIndexOf('/') + 1)), word: found[1] };
+}
+
+/** A category page's last path segment ("hiking-boots"), or null when the address isn't one. */
+export function categorySlug(url) {
+ return categoryPath(url)?.slug ?? null;
+}
+
+/** A category's steps: "Shoes > Hiking Boots" → ["Shoes", "Hiking Boots"]. */
+function stepsOf(category) {
+ return String(category ?? '')
+ .split(/[>›/|]/)
+ .map((s) => s.trim())
+ .filter(Boolean);
+}
+
+/** A category's own name: the last step of "Shoes > Hiking Boots". */
+export function leafName(category) {
+ const steps = stepsOf(category);
+ return steps.length ? steps[steps.length - 1] : '';
+}
+
+/** A word's singular, roughly: boots → boot, glasses → glass, boxes → box; dress stays. */
+function singular(word) {
+ if (word.length > 4 && /(ss|x|z|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;
+}
+
+/** Lowercase words, a plural's "s" dropped: "Hiking Boots" → ["hiking", "boot"]; "Kadın" → ["kadin"]. */
+export function wordsOf(text) {
+ return foldLetters(text)
+ .split(/[^a-z0-9]+/)
+ .filter((w) => w.length > 1 && w !== 'and' && w !== 'the' && w !== 'for')
+ .map(singular);
+}
+
+const RANK = { address: 3, title: 2, words: 1 };
+/** The most of a name's or its parent's words matching reads: no category's name runs longer. */
+const MAX_NAME_WORDS = 12;
+/** The most of a page's title and h1 matching reads. */
+const MAX_HEADING_CHARS = 300;
+
+/** What matching reads of a category, once. */
+function prepareCategory(category) {
+ const steps = stepsOf(category);
+ const leaf = wordsOf(steps.length ? steps[steps.length - 1] : '').slice(0, MAX_NAME_WORDS);
+ const leafSet = new Set(leaf);
+ const parent = new Set(
+ wordsOf(steps.slice(0, -1).join(' '))
+ .filter((w) => !leafSet.has(w))
+ .slice(-MAX_NAME_WORDS),
+ );
+ return { category, leaf, leafSet, leafKey: leaf.join(' '), parent };
+}
+
+/** What matching reads of a page that reads as a category page, once; null for any other page. */
+function preparePage(page, order) {
+ const found = categoryPath(page.url);
+ if (!found) return null;
+ const heading = `${String(page.title ?? '').slice(0, MAX_HEADING_CHARS)} ${String(page.h1 ?? '').slice(0, MAX_HEADING_CHARS)}`;
+ const slugWords = wordsOf(found.slug);
+ const headingWords = wordsOf(heading);
+ return {
+ page,
+ order,
+ host: normHost(page.url),
+ archive: ARCHIVE_WORD.test(found.word),
+ heading,
+ slugWords,
+ headingText: ` ${headingWords.join(' ')} `,
+ words: new Set([...slugWords, ...headingWords]),
+ };
+}
+
+/** How well a prepared page matches a prepared category, and how many of its parent's words it names; or null. */
+function matchPrepared(c, p) {
+ if (!c.leaf.length) return null;
+ let parentHits = 0;
+ for (const w of c.parent) if (p.words.has(w)) parentHits += 1;
+ // The address: the name's words in order, with none but the parent's beside
+ // them. A slug with more words than the two can't be it.
+ if (p.slugWords.length <= c.leaf.length + c.parent.size) {
+ const rest = c.parent.size ? p.slugWords.filter((w) => !c.parent.has(w)) : p.slugWords;
+ if (rest.join(' ') === c.leafKey) return { how: 'address', parentHits };
+ }
+ // One word is too wide for a title or a share: "Shoes" isn't /collections/running-shoes.
+ if (c.leaf.length === 1) return null;
+ if (p.headingText.includes(` ${c.leafKey} `)) return { how: 'title', parentHits };
+ let common = 0;
+ for (const w of c.leafSet) if (p.words.has(w)) common += 1;
+ return common / c.leafSet.size >= WORDS_SHARE ? { how: 'words', parentHits } : null;
+}
+
+/**
+ * How well a page matches a category, or null: 'address', 'title' or
+ * 'words'. The page alone: matchCategoryPages also reads the site's other
+ * pages (a /category/ page's host) and the other categories.
+ */
+export function matchOf(category, page) {
+ const p = preparePage(page, 0);
+ return p ? (matchPrepared(prepareCategory(category), p)?.how ?? null) : null;
+}
+
+/**
+ * The site's pages that read as category pages, prepared. A /category/
+ * page counts only on a host with a product page and none of WooCommerce's
+ * product categories (whose site keeps its blog's at /category/), and when
+ * its title isn't an archive's.
+ */
+function categoryPagesOf(pages) {
+ const sells = new Set();
+ const woo = new Set();
+ for (const page of pages) {
+ const path = pathOf(page.url);
+ if (!path) continue;
+ if (PRODUCT_PAGE.test(path)) sells.add(normHost(page.url));
+ if (WOO_PATH.test(path)) woo.add(normHost(page.url));
+ }
+ const out = [];
+ pages.forEach((page, order) => {
+ const p = preparePage(page, order);
+ if (!p) return;
+ if (p.archive && (!sells.has(p.host) || woo.has(p.host) || ARCHIVE_TITLE.test(p.heading))) {
+ return;
+ }
+ out.push(p);
+ });
+ return out;
+}
+
+function compare(a, b) {
+ for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return a[i] - b[i];
+ return 0;
+}
+
+/**
+ * Categories on the same page: the ones naming most of their parent's words
+ * there keep it, the others move to their next page, until none has to.
+ * Categories naming as many share it ("Shoes" under two parents, on a page
+ * naming neither).
+ */
+function settle(choices) {
+ for (let moved = true; moved; ) {
+ moved = false;
+ const most = new Map();
+ for (const { found, at } of choices) {
+ const pick = found[at];
+ if (pick) most.set(pick.p, Math.max(most.get(pick.p) ?? 0, pick.parentHits));
+ }
+ for (const choice of choices) {
+ const pick = choice.found[choice.at];
+ if (pick && pick.parentHits < most.get(pick.p)) {
+ choice.at += 1;
+ moved = true;
+ }
+ }
+ }
+}
+
+/**
+ * Each category's best page among `pages`, or none: `{ category, page, how }`.
+ * Pure: `pages` are site_pages rows (url, title, h1, ai_citations, ga_sessions).
+ * Each page is read once, and a category only meets the pages holding one
+ * of its words.
+ */
+export function matchCategoryPages(categories, pages) {
+ const prepared = categoryPagesOf(pages);
+ const byWord = new Map();
+ for (const p of prepared) {
+ for (const w of p.words) {
+ if (!byWord.has(w)) byWord.set(w, []);
+ byWord.get(w).push(p);
+ }
+ }
+ const choices = categories.map((category) => {
+ const c = prepareCategory(category);
+ const met = new Set();
+ const found = [];
+ for (const w of c.leafSet) {
+ for (const p of byWord.get(w) ?? []) {
+ if (met.has(p)) continue;
+ met.add(p);
+ const m = matchPrepared(c, p);
+ if (!m) continue;
+ const score = [
+ RANK[m.how],
+ m.parentHits,
+ p.page.ai_citations ?? 0,
+ p.page.ga_sessions ?? 0,
+ ];
+ found.push({ p, how: m.how, parentHits: m.parentHits, score });
+ }
+ }
+ // The best first; on a tie, the page listed first.
+ found.sort((a, b) => compare(b.score, a.score) || a.p.order - b.p.order);
+ return { category, found, at: 0 };
+ });
+ settle(choices);
+ return choices.map(({ category, found, at }) => {
+ const best = found[at];
+ return {
+ category,
+ page: best
+ ? { url: best.p.page.url, title: best.p.page.title || best.p.page.h1 || null }
+ : null,
+ how: best?.how ?? null,
+ };
+ });
+}
+
+/**
+ * The brand's categories, each with its live products, how many are in
+ * stock, and its page: a person's decision first ('manual', or none), else
+ * the best match. The categories with the most products first. `how` is
+ * 'manual' for a person's decision, a page or none, and null when nothing
+ * matched. The site's pages are read only when a category is left to match.
+ *
+ * @returns {Promise<{ name: string, products: number, inStock: number,
+ * page: { url: string, title: string|null }|null,
+ * how: 'manual'|'address'|'title'|'words'|null }[]>}
+ */
+export async function categoryPages(brandId, { db = supabaseAdmin } = {}) {
+ const [counts, decisions] = await Promise.all([
+ db.rpc('catalog_category_counts', { p_brand_id: brandId }),
+ db.from('catalog_category_pages').select('category, url').eq('brand_id', brandId),
+ ]);
+ for (const [what, read] of [
+ ['category counts', counts],
+ ['category pages', decisions],
+ ]) {
+ if (read.error) throw new Error(`${what} read: ${read.error.message}`);
+ }
+ const decided = new Map((decisions.data ?? []).map((d) => [d.category, d.url]));
+ const rows = (counts.data ?? [])
+ .slice()
+ .sort((a, b) => b.products - a.products || a.category.localeCompare(b.category));
+ const open = rows.filter((r) => !decided.has(r.category)).map((r) => r.category);
+ let pages = [];
+ if (open.length) {
+ const read = await db
+ .from('site_pages')
+ .select('url, title, h1, ai_citations, ga_sessions')
+ .eq('brand_id', brandId)
+ .or('fetch_status.is.null,and(fetch_status.gte.200,fetch_status.lt.400)')
+ .limit(MAX_PAGES);
+ if (read.error) throw new Error(`site pages read: ${read.error.message}`);
+ pages = read.data ?? [];
+ }
+ const byName = new Map(matchCategoryPages(open, pages).map((m) => [m.category, m]));
+ return rows.map((r) => {
+ const base = { name: r.category, products: r.products, inStock: r.in_stock };
+ if (decided.has(r.category)) {
+ const url = decided.get(r.category);
+ // A person's decision, a page or none, is 'manual' either way.
+ return { ...base, page: url ? { url, title: null } : null, how: 'manual' };
+ }
+ const m = byName.get(r.category);
+ return { ...base, page: m?.page ?? null, how: m?.how ?? null };
+ });
+}
+
+export class CategoryPageError extends Error {
+ constructor(code, message, status = 400) {
+ super(message);
+ this.name = 'CategoryPageError';
+ this.code = code;
+ this.status = status;
+ }
+}
+
+/**
+ * Whether `url` is on the brand's site: one of its domains (brand_domains),
+ * or, for a brand with none stored, the site its catalog's products link to.
+ */
+async function onBrandSite(db, brandId, url) {
+ const { data, error } = await db.from('brand_domains').select('domain').eq('brand_id', brandId);
+ if (error) throw new Error(`brand_domains read: ${error.message}`);
+ let domains = (data ?? []).map((d) => d.domain).filter(Boolean);
+ if (!domains.length) {
+ const links = await db
+ .from('catalog_products')
+ .select('url')
+ .eq('brand_id', brandId)
+ .limit(MAX_PRODUCT_LINKS);
+ if (links.error) throw new Error(`catalog_products read: ${links.error.message}`);
+ domains = (links.data ?? []).map((p) => p.url).filter(Boolean);
+ }
+ return onBrandDomain(url, domains);
+}
+
+/**
+ * A person's decision for a category of the brand's catalog: its page
+ * (`url`, on the brand's site), none (`url` null), or back to the
+ * automatic match (`url` undefined). The caller has checked the person may.
+ */
+export async function setCategoryPage(
+ { brandId, category, url, userId },
+ { db = supabaseAdmin } = {},
+) {
+ const name = String(category ?? '').trim();
+ if (!name || name.length > 750) throw new CategoryPageError('invalid', 'Pick a category.');
+ if (url === undefined) {
+ const { error } = await db
+ .from('catalog_category_pages')
+ .delete()
+ .eq('brand_id', brandId)
+ .eq('category', name);
+ if (error) throw new Error(`catalog_category_pages delete: ${error.message}`);
+ return;
+ }
+ let address = null;
+ if (url !== null) {
+ try {
+ const parsed = new URL(String(url).trim());
+ if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password)
+ throw new Error();
+ address = parsed.href;
+ } catch {
+ throw new CategoryPageError('invalid', "That isn't a web address. Paste the page's address.");
+ }
+ if (address.length > 2048) throw new CategoryPageError('invalid', 'That address is too long.');
+ }
+ const known = await db
+ .from('catalog_categories')
+ .select('id')
+ .eq('brand_id', brandId)
+ .eq('name', name)
+ .maybeSingle();
+ if (known.error) throw new Error(`catalog_categories read: ${known.error.message}`);
+ if (!known.data) {
+ throw new CategoryPageError('not_found', "That category isn't in the brand's catalog.", 404);
+ }
+ if (address && !(await onBrandSite(db, brandId, address))) {
+ throw new CategoryPageError('off_site', "The page must be on the brand's own site.");
+ }
+ const { error } = await db.from('catalog_category_pages').upsert(
+ {
+ brand_id: brandId,
+ category: name,
+ url: address,
+ set_by: userId,
+ set_at: new Date().toISOString(),
+ },
+ { onConflict: 'brand_id,category' },
+ );
+ if (error) throw new Error(`catalog_category_pages write: ${error.message}`);
+}
diff --git a/server/src/lib/catalog/category-pages.test.js b/server/src/lib/catalog/category-pages.test.js
new file mode 100644
index 000000000..e27a4d5ce
--- /dev/null
+++ b/server/src/lib/catalog/category-pages.test.js
@@ -0,0 +1,435 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../../config/supabase.js', () => ({ default: {} }));
+
+import { fakeDb } from './__fixtures__/fake-db.js';
+import {
+ CategoryPageError,
+ categoryPages,
+ categorySlug,
+ leafName,
+ matchCategoryPages,
+ matchOf,
+ setCategoryPage,
+ wordsOf,
+} from './category-pages.js';
+
+/** Each catalog category's page on the brand's site (shopping path, 00350). */
+
+const page = (url, title = null, extra = {}) => ({ url, title, h1: null, ...extra });
+
+// The editor's page types read a shop's category pages by the same cases
+// (web/src/lib/content/page-types.test.ts, detectPageType).
+const { cases: CATEGORY_PATHS } = JSON.parse(
+ readFileSync(
+ new URL('../../../../web/src/lib/content/__fixtures__/category-paths.json', import.meta.url),
+ 'utf8',
+ ),
+);
+
+describe('categorySlug', () => {
+ it.each(CATEGORY_PATHS)("reads $url as the editor's page types do: $slug", ({ url, slug }) => {
+ expect(categorySlug(url)).toBe(slug);
+ });
+
+ it("isn't a category word alone, or what isn't an address", () => {
+ expect(categorySlug('https://shop.example/collections')).toBeNull();
+ expect(categorySlug('not a url')).toBeNull();
+ });
+
+ it("reads an address with a broken escape as it is, and doesn't fail on it", () => {
+ expect(categorySlug('https://shop.example/collections/100%-cotton')).toBe('100%-cotton');
+ expect(categorySlug('https://shop.example/collections/caf%E9')).toBe('caf%e9');
+ expect(categorySlug('https://shop.example/collections/%C3%A7anta')).toBe('çanta');
+ expect(
+ matchOf('100% Cotton', page('https://shop.example/collections/100%-cotton', '100% cotton')),
+ ).toBe('address');
+ });
+});
+
+describe('names and words', () => {
+ it("takes a category's own name and its words, plurals as one", () => {
+ expect(leafName('Shoes > Hiking Boots')).toBe('Hiking Boots');
+ expect(leafName('Apparel › Jackets / Rain Jackets')).toBe('Rain Jackets');
+ expect(wordsOf('Hiking Boots & the Socks')).toEqual(['hiking', 'boot', 'sock']);
+ expect(wordsOf('Glasses, Boxes and Dress')).toEqual(['glass', 'box', 'dress']);
+ });
+
+ it('reads Turkish and German letters as a slug spells them', () => {
+ expect(wordsOf('Kadın Ayakkabı')).toEqual(['kadin', 'ayakkabi']);
+ expect(wordsOf('İç Giyim')).toEqual(['ic', 'giyim']);
+ expect(wordsOf('Große Größen')).toEqual(['grosse', 'grossen']);
+ expect(
+ matchOf('Kadın > Kadın Ayakkabı', page('https://s.example/collections/kadin-ayakkabi')),
+ ).toBe('address');
+ expect(matchOf('Wanderschuhe', page('https://s.example/kategorie/wanderschuhe'))).toBe(
+ 'address',
+ );
+ expect(matchOf('Botas de montaña', page('https://s.example/categoria/botas-de-montana'))).toBe(
+ 'address',
+ );
+ });
+});
+
+describe('matchOf', () => {
+ it('matches by address first, then title, then most of the words', () => {
+ expect(
+ matchOf('Shoes > Hiking Boots', page('https://s.example/collections/hiking-boots')),
+ ).toBe('address');
+ expect(
+ matchOf('Hiking Boots', page('https://s.example/collections/hb-01', 'Hiking boots | Acme')),
+ ).toBe('title');
+ expect(
+ matchOf('Waterproof Hiking Boots', page('https://s.example/collections/hiking-boot-range')),
+ ).toBe('words');
+ expect(matchOf('Rain Jackets', page('https://s.example/collections/hiking-boots'))).toBeNull();
+ expect(matchOf('Hiking Boots', page('https://s.example/blog/hiking-boots'))).toBeNull();
+ });
+
+ it("matches none of a review's pages that only look like the category's", () => {
+ for (const url of [
+ 'https://s.example/collections/best-hiking-boots',
+ 'https://s.example/collections/hiking-boots-size-guide',
+ 'https://s.example/collections/hiking-boots-vs-trail-runners',
+ 'https://s.example/blog/category/hiking-boots',
+ 'https://s.example/collections/summer-sale',
+ ]) {
+ expect(matchOf('Hiking Boots', page(url, 'Summer sale: hiking boots')), url).toBeNull();
+ }
+ expect(matchOf('Hiking Boots', page('https://s.example/product-category/hiking-boots'))).toBe(
+ 'address',
+ );
+ });
+
+ it('matches a one-word name by its address only', () => {
+ expect(matchOf('Shoes', page('https://s.example/collections/shoes'))).toBe('address');
+ expect(matchOf('Shoes', page('https://s.example/collections/running-shoes'))).toBeNull();
+ expect(matchOf('Glasses', page('https://s.example/c/wine-glasses', 'Wine glasses'))).toBeNull();
+ expect(
+ matchOf('Men > Shoes', page('https://s.example/c/footwear', "Women's shoes")),
+ ).toBeNull();
+ });
+
+ it("lets the parent's words stand beside the name in the address", () => {
+ expect(matchOf('Men > Shoes', page('https://s.example/collections/mens-shoes'))).toBe(
+ 'address',
+ );
+ expect(matchOf('Men > Shoes', page('https://s.example/c/shoes-men'))).toBe('address');
+ expect(matchOf('Men > Shoes', page('https://s.example/collections/womens-shoes'))).toBeNull();
+ expect(matchOf('Shoes', page('https://s.example/collections/mens-shoes'))).toBeNull();
+ });
+});
+
+describe('matchCategoryPages', () => {
+ it('picks the best page for each category, the most cited on a tie, or none', () => {
+ const pages = [
+ page('https://s.example/collections/boots-sale', 'Hiking boots sale', { ai_citations: 1 }),
+ page('https://s.example/collections/hiking-boots', 'Boots', { ai_citations: 0 }),
+ page('https://s.example/c/socks', 'Wool socks', { ai_citations: 1 }),
+ page('https://s.example/shop/socks', 'Socks', { ai_citations: 5 }),
+ ];
+ expect(matchCategoryPages(['Hiking Boots', 'Socks', 'Tents'], pages)).toEqual([
+ {
+ category: 'Hiking Boots',
+ page: { url: 'https://s.example/collections/hiking-boots', title: 'Boots' },
+ how: 'address',
+ },
+ {
+ category: 'Socks',
+ page: { url: 'https://s.example/shop/socks', title: 'Socks' },
+ how: 'address',
+ },
+ { category: 'Tents', page: null, how: null },
+ ]);
+ });
+
+ it('breaks a tie on citations by visits, then keeps the page listed first', () => {
+ const pages = [
+ page('https://s.example/c/tents', 'Tents', { ai_citations: 2, ga_sessions: 10 }),
+ page('https://s.example/shop/tents', 'Tents', { ai_citations: 2, ga_sessions: 40 }),
+ page('https://s.example/catalog/tents', 'Tents', { ai_citations: 2, ga_sessions: 40 }),
+ ];
+ expect(matchCategoryPages(['Tents'], pages)[0].page.url).toBe('https://s.example/shop/tents');
+ });
+
+ it('gives a page to the category whose parent it names, the others take their next or none', () => {
+ const pages = [
+ page('https://s.example/collections/shoes', "Women's shoes", { ai_citations: 9 }),
+ page('https://s.example/collections/mens-shoes', 'Shoes for him'),
+ page('https://s.example/collections/hiking-boots', 'Hiking boots'),
+ ];
+ const matched = matchCategoryPages(
+ [
+ 'Men > Shoes',
+ 'Women > Shoes',
+ 'Kids > Shoes',
+ 'Men > Hiking Boots',
+ 'Women > Hiking Boots',
+ ],
+ pages,
+ );
+ expect(matched.map((m) => [m.category, m.page?.url ?? null])).toEqual([
+ ['Men > Shoes', 'https://s.example/collections/mens-shoes'],
+ ['Women > Shoes', 'https://s.example/collections/shoes'],
+ // The shoes page names another parent: Kids has none.
+ ['Kids > Shoes', null],
+ // A page naming neither parent: both keep it.
+ ['Men > Hiking Boots', 'https://s.example/collections/hiking-boots'],
+ ['Women > Hiking Boots', 'https://s.example/collections/hiking-boots'],
+ ]);
+ });
+
+ it("counts a /category/ page only on a host that sells, without WooCommerce's, untitled as an archive", () => {
+ const blog = [
+ page('https://s.example/category/hiking-boots', 'Hiking boots'),
+ page('https://shop.s.example/products/summit-boot', 'Summit boot'),
+ ];
+ expect(matchCategoryPages(['Hiking Boots'], blog)[0].page).toBeNull();
+
+ const woo = [
+ page('https://s.example/category/hiking-boots', 'Hiking boots'),
+ page('https://s.example/product/summit-boot', 'Summit boot'),
+ page('https://s.example/product-category/boots', 'Boots'),
+ ];
+ expect(matchCategoryPages(['Hiking Boots'], woo)[0].page).toBeNull();
+
+ const archive = [
+ page('https://s.example/category/hiking-boots', 'Hiking Boots Archives - Acme'),
+ page('https://s.example/p/summit-boot', 'Summit boot'),
+ ];
+ expect(matchCategoryPages(['Hiking Boots'], archive)[0].page).toBeNull();
+
+ const shop = [
+ page('https://www.s.example/kategori/kadin-ayakkabi', 'Kadın Ayakkabı'),
+ page('https://s.example/urun/yuruyus-botu', 'Yürüyüş botu'),
+ ];
+ expect(matchCategoryPages(['Kadın Ayakkabı'], shop)[0]).toMatchObject({
+ page: { url: 'https://www.s.example/kategori/kadin-ayakkabi' },
+ how: 'address',
+ });
+ });
+
+ it('matches a large catalog to a full site quickly', () => {
+ // The worst case: every name and every page hold "boots", so no page is left out unread.
+ const word = (i) => `w${i.toString(36)}x`;
+ const categories = Array.from(
+ { length: 1000 },
+ (_, i) => `Dept ${i % 12} > ${word(i)} Waterproof Boots`,
+ );
+ // Each page's address counts its reads.
+ let reads = 0;
+ const pages = Array.from({ length: 500 }, (_, i) => {
+ const url = `https://s.example/collections/${word(i * 2)}-boots`;
+ return Object.defineProperty(
+ page(null, `${word(i * 2)} boots`, { ai_citations: i % 5 }),
+ 'url',
+ {
+ get: () => {
+ reads += 1;
+ return url;
+ },
+ },
+ );
+ });
+ const started = Date.now();
+ const matched = matchCategoryPages(categories, pages);
+ // Each address is read a few times, not once for each category (500,000 reads, seconds).
+ expect(reads).toBeLessThan(10_000);
+ // Loose, for a busy machine: the read count above bounds the work.
+ expect(Date.now() - started).toBeLessThan(5000);
+ expect(matched).toHaveLength(1000);
+ expect(matched[2]).toMatchObject({
+ how: 'words',
+ page: { url: 'https://s.example/collections/w2x-boots' },
+ });
+ expect(matched[1].page).toBeNull();
+ });
+
+ it('matches long names, long addresses and long titles in time near their length', () => {
+ // 1,000 names as long as a catalog keeps (750), mostly spaces.
+ const categories = Array.from(
+ { length: 1000 },
+ (_, i) => `Boots${' '.repeat(700)}> trail boot ${i}`,
+ );
+ // 500 pages whose last segment has hundreds of words, each sharing "boot".
+ const long = Array.from({ length: 400 }, (_, i) => `boot${i % 7 ? '' : 's'}`).join('-');
+ const pages = Array.from({ length: 500 }, (_, i) =>
+ page(`https://s.example/collections/${long}-${i}`, `${'Trail boot '.repeat(2_000)}${i}`),
+ );
+ const started = Date.now();
+ const matched = matchCategoryPages(categories, pages);
+ expect(matched).toHaveLength(1000);
+ expect(Date.now() - started).toBeLessThan(5000);
+ });
+});
+
+describe('categoryPages', () => {
+ it("lists the brand's categories with their counts and pages, a person's decision first", async () => {
+ const fake = fakeDb();
+ fake.rows('site_pages').push(
+ {
+ id: '1',
+ brand_id: 'b1',
+ url: 'https://s.example/collections/hiking-boots',
+ title: 'Hiking boots',
+ },
+ {
+ id: '2',
+ brand_id: 'b1',
+ url: 'https://s.example/collections/rain-jackets',
+ title: 'Rain',
+ },
+ { id: '3', brand_id: 'b2', url: 'https://other.example/collections/tents', title: 'Tents' },
+ );
+ fake
+ .rows('catalog_category_pages')
+ .push(
+ { brand_id: 'b1', category: 'Rain Jackets', url: 'https://s.example/jackets/rain' },
+ { brand_id: 'b1', category: 'Socks', url: null },
+ );
+ const rpc = vi.fn(async () => ({
+ data: [
+ { category: 'Socks', products: 2, in_stock: 2 },
+ { category: 'Shoes > Hiking Boots', products: 24, in_stock: 18 },
+ { category: 'Rain Jackets', products: 16, in_stock: 12 },
+ { category: 'Tents', products: 16, in_stock: 3 },
+ ],
+ error: null,
+ }));
+ const categories = await categoryPages('b1', { db: { ...fake.db, rpc } });
+ expect(rpc).toHaveBeenCalledWith('catalog_category_counts', { p_brand_id: 'b1' });
+ expect(categories).toEqual([
+ {
+ name: 'Shoes > Hiking Boots',
+ products: 24,
+ inStock: 18,
+ page: { url: 'https://s.example/collections/hiking-boots', title: 'Hiking boots' },
+ how: 'address',
+ },
+ {
+ name: 'Rain Jackets',
+ products: 16,
+ inStock: 12,
+ page: { url: 'https://s.example/jackets/rain', title: null },
+ how: 'manual',
+ },
+ // Another brand's page is never matched.
+ { name: 'Tents', products: 16, inStock: 3, page: null, how: null },
+ // A person said it has none.
+ { name: 'Socks', products: 2, inStock: 2, page: null, how: 'manual' },
+ ]);
+ });
+
+ it("doesn't read the site's pages when no category is left to match", async () => {
+ const fake = fakeDb();
+ const from = vi.fn(fake.db.from);
+ fake.rows('catalog_category_pages').push({ brand_id: 'b1', category: 'Socks', url: null });
+ let data = [];
+ const rpc = vi.fn(async () => ({ data, error: null }));
+ expect(await categoryPages('b1', { db: { from, rpc } })).toEqual([]);
+ data = [{ category: 'Socks', products: 2, in_stock: 1 }];
+ expect(await categoryPages('b1', { db: { from, rpc } })).toEqual([
+ { name: 'Socks', products: 2, inStock: 1, page: null, how: 'manual' },
+ ]);
+ expect(from.mock.calls.map(([table]) => table)).not.toContain('site_pages');
+ });
+});
+
+describe('setCategoryPage', () => {
+ const setup = () => {
+ const fake = fakeDb();
+ fake.rows('brand_domains').push({ id: 'd1', brand_id: 'b1', domain: 'https://www.s.example/' });
+ fake.rows('catalog_categories').push({ id: 'c1', brand_id: 'b1', name: 'Socks' });
+ return fake;
+ };
+
+ it("keeps a page on the brand's site, none, or goes back to the match", async () => {
+ const fake = setup();
+ const set = (url) =>
+ setCategoryPage({ brandId: 'b1', category: 'Socks', url, userId: 'u1' }, { db: fake.db });
+ await set('https://shop.s.example/c/socks');
+ expect(fake.rows('catalog_category_pages')).toEqual([
+ expect.objectContaining({
+ brand_id: 'b1',
+ category: 'Socks',
+ url: 'https://shop.s.example/c/socks',
+ set_by: 'u1',
+ }),
+ ]);
+ await set(null);
+ expect(fake.rows('catalog_category_pages')).toEqual([
+ expect.objectContaining({ category: 'Socks', url: null }),
+ ]);
+ await set(undefined);
+ expect(fake.rows('catalog_category_pages')).toEqual([]);
+ });
+
+ it("refuses a page off the brand's site, or one that isn't an address", async () => {
+ const fake = setup();
+ const set = (url) =>
+ setCategoryPage({ brandId: 'b1', category: 'Socks', url, userId: 'u1' }, { db: fake.db });
+ await expect(set('https://elsewhere.example/c/socks')).rejects.toMatchObject({
+ code: 'off_site',
+ });
+ await expect(set('socks')).rejects.toBeInstanceOf(CategoryPageError);
+ await expect(set('ftp://s.example/socks')).rejects.toMatchObject({ code: 'invalid' });
+ await expect(set('https://me:[email protected]/c/socks')).rejects.toMatchObject({
+ code: 'invalid',
+ });
+ await expect(set(`https://www.s.example/c/${'a'.repeat(2048)}`)).rejects.toMatchObject({
+ code: 'invalid',
+ });
+ expect(fake.rows('catalog_category_pages')).toEqual([]);
+ });
+
+ it("refuses a category the brand's catalog doesn't have, but lets its decision go", async () => {
+ const fake = setup();
+ fake.rows('catalog_categories').push({ id: 'c2', brand_id: 'b2', name: 'Tents' });
+ fake.rows('catalog_category_pages').push({ brand_id: 'b1', category: 'Tents', url: null });
+ const set = (url) =>
+ setCategoryPage({ brandId: 'b1', category: 'Tents', url, userId: 'u1' }, { db: fake.db });
+ for (const url of ['https://www.s.example/c/tents', null]) {
+ await expect(set(url)).rejects.toMatchObject({ code: 'not_found', status: 404 });
+ }
+ // A decision left from a category gone from the catalog can still be taken back.
+ await set(undefined);
+ expect(fake.rows('catalog_category_pages')).toEqual([]);
+ });
+
+ it('takes the sites its products link to for a brand with no domain stored', async () => {
+ const fake = fakeDb();
+ fake.rows('catalog_categories').push({ id: 'c1', brand_id: 'b1', name: 'Socks' });
+ fake
+ .rows('catalog_products')
+ .push(
+ { id: 'p1', brand_id: 'b1', url: 'https://www.shop.example/products/wool-sock' },
+ { id: 'p2', brand_id: 'b1', url: null },
+ { id: 'p3', brand_id: 'b2', url: 'https://other.example/products/tent' },
+ );
+ const set = (url) =>
+ setCategoryPage({ brandId: 'b1', category: 'Socks', url, userId: 'u1' }, { db: fake.db });
+ await set('https://shop.example/collections/socks');
+ expect(fake.rows('catalog_category_pages')).toEqual([
+ expect.objectContaining({ url: 'https://shop.example/collections/socks' }),
+ ]);
+ await expect(set('https://other.example/collections/socks')).rejects.toMatchObject({
+ code: 'off_site',
+ });
+ });
+});
+
+describe('catalog_category_counts (00350)', () => {
+ it("counts a variant in stock as the editor's feed match reads it (feed-match.ts, feedStock)", () => {
+ const read = (path) => readFileSync(new URL(`../../../../${path}`, import.meta.url), 'utf8');
+ const words = (list) => [...list.matchAll(/'([a-z_]+)'/g)].map((m) => m[1]);
+ const sql = read('supabase/migrations/00350_catalog_category_pages.sql');
+ const web = read('web/src/lib/content/feed-match.ts');
+ const inStock = words(web.match(/return \[([^\]]*)\]\.includes\(a\)/)[1]);
+ expect(inStock).toContain('limited_availability');
+ expect(words(sql.match(/'_', 'g'\)\)\s+in \(([^)]*)\)/)[1])).toEqual(inStock);
+ // Read as the web reads it: lowercased, spaces and hyphens as "_".
+ expect(web).toMatch(/toLowerCase\(\)\.replace\(\/\[\\s-\]\+\/g, '_'\)/);
+ expect(sql).toMatch(/lower\(regexp_replace\(v\.availability, '\[\\s-\]\+', '_', 'g'\)\)/);
+ });
+});
diff --git a/server/src/lib/cms/webflow-items.js b/server/src/lib/cms/webflow-items.js
index 569449877..4f160e4cf 100644
--- a/server/src/lib/cms/webflow-items.js
+++ b/server/src/lib/cms/webflow-items.js
@@ -1,4 +1,5 @@
import * as cheerio from 'cheerio';
+import { foldLetters } from '../letters.js';
/**
* A page as a Webflow CMS item (Send to CMS #1331, phase 2): its rich text
@@ -185,20 +186,13 @@ export function toWebflowRichText(html) {
return { html: $.html().trim(), changed };
}
-/** Letters Unicode doesn't take apart into a base letter and its mark. */
-const LETTERS = { ı: 'i', ß: 'ss', æ: 'ae', œ: 'oe', ø: 'o', đ: 'd', ł: 'l', þ: 'th' };
-
/**
* A slug Webflow takes: lowercase letters, digits, '-' and '_', starting
* with a letter, digit or '_' (marks taken off, "ç" → "c"). Null when
* nothing of it is left (a slug in another script).
*/
export function webflowSlug(value) {
- const slug = String(value ?? '')
- .toLowerCase()
- .replace(/[ıßæœøđłþ]/g, (c) => LETTERS[c])
- .normalize('NFKD')
- .replace(/\p{M}/gu, '')
+ const slug = foldLetters(value)
.replace(/[^a-z0-9_-]+/g, '-')
.replace(/-{2,}/g, '-')
.replace(/^-+|-+$/g, '')
diff --git a/server/src/lib/letters.js b/server/src/lib/letters.js
new file mode 100644
index 000000000..5bd8c27d4
--- /dev/null
+++ b/server/src/lib/letters.js
@@ -0,0 +1,16 @@
+/** Letters Unicode doesn't take apart into a base letter and its mark. */
+export const LETTERS = { ı: 'i', ß: 'ss', æ: 'ae', œ: 'oe', ø: 'o', đ: 'd', ł: 'l', þ: 'th' };
+
+/**
+ * Text lowercased with its letters as plain Latin ones: marks taken off
+ * ("ç" → "c", "İ" → "i") and the letters Unicode keeps whole spelled out
+ * ("ı" → "i", "ß" → "ss"), so "Kadın Ayakkabı" reads as a slug's
+ * "kadin-ayakkabi" does. Other characters stay as they are.
+ */
+export function foldLetters(value) {
+ return String(value ?? '')
+ .toLowerCase()
+ .replace(/[ıßæœøđłþ]/g, (c) => LETTERS[c])
+ .normalize('NFKD')
+ .replace(/\p{M}/gu, '');
+}
diff --git a/server/src/middleware/rate-limiter.js b/server/src/middleware/rate-limiter.js
index 98e835f51..2ab69cb6a 100644
--- a/server/src/middleware/rate-limiter.js
+++ b/server/src/middleware/rate-limiter.js
@@ -131,6 +131,21 @@ export const catalogLimiter = rateLimit({
},
});
+// A catalog category's page set by hand, or put back to its match (shopping
+// path, 00350): a person goes down the table a row at a time, so a bucket
+// of its own, wider than the syncs'. Reading the table takes the API's.
+export const catalogCategoryLimiter = rateLimit({
+ windowMs: 15 * 60 * 1000,
+ max: 120,
+ keyGenerator: apiLimiterKey,
+ standardHeaders: true,
+ legacyHeaders: false,
+ message: {
+ success: false,
+ message: 'Too many requests, please try again later.',
+ },
+});
+
// A brand's CMS connection (Send to CMS, #1331): each call reaches Webflow
// through Composio, so a member's are few.
export const cmsLimiter = rateLimit({
diff --git a/server/src/middleware/rate-limiter.test.js b/server/src/middleware/rate-limiter.test.js
index 648c506a9..f1d0b93fa 100644
--- a/server/src/middleware/rate-limiter.test.js
+++ b/server/src/middleware/rate-limiter.test.js
@@ -1,7 +1,10 @@
import { describe, it, expect, beforeEach } from 'vitest';
+import express from 'express';
import {
apiLimiterKey,
botIngestKey,
+ catalogCategoryLimiter,
+ catalogLimiter,
isJourneyBeacon,
journeyEventKey,
webhookCallbackKey,
@@ -142,3 +145,28 @@ describe('rate-limiter – journey events (CE-017)', () => {
expect(isJourneyBeacon(undefined)).toBe(false);
});
});
+
+describe('rate-limiter – catalog buckets', () => {
+ it("gives category page changes a wider bucket than the syncs', apart from them", async () => {
+ const app = express();
+ app.post('/sync', catalogLimiter, (_req, res) => res.json({}));
+ app.put('/categories', catalogCategoryLimiter, (_req, res) => res.json({}));
+ const server = await new Promise((resolve) => {
+ const listening = app.listen(0, '127.0.0.1', () => resolve(listening));
+ });
+ const base = `http://127.0.0.1:${server.address().port}`;
+ const statuses = async (method, path, n) => {
+ const out = [];
+ for (let i = 0; i < n; i += 1) out.push((await fetch(base + path, { method })).status);
+ return out;
+ };
+ try {
+ // The syncs' 20 a quarter-hour run out…
+ expect((await statuses('POST', '/sync', 21)).at(-1)).toBe(429);
+ // …and a person changing the table row by row goes on past them.
+ expect(new Set(await statuses('PUT', '/categories', 40))).toEqual(new Set([200]));
+ } finally {
+ await new Promise((resolve) => server.close(resolve));
+ }
+ });
+});
diff --git a/server/src/routes/catalog.js b/server/src/routes/catalog.js
index 9c1fc0a46..f47f3b589 100644
--- a/server/src/routes/catalog.js
+++ b/server/src/routes/catalog.js
@@ -4,6 +4,11 @@ import supabaseAdmin from '../config/supabase.js';
import { connectorFor, isSignIn, signInConnectors, storeConnectors } from '../connectors/index.js';
import { assertBrandAccess } from '../lib/access.js';
import { isComposioConfigured } from '../lib/composio.js';
+import {
+ CategoryPageError,
+ categoryPages,
+ setCategoryPage,
+} from '../lib/catalog/category-pages.js';
import { credentialsConfigured } from '../lib/catalog/credentials.js';
import { syncSource } from '../lib/catalog/sources.js';
import {
@@ -14,7 +19,7 @@ import {
listSignInAccounts,
reconnectStore,
} from '../lib/catalog/stores.js';
-import { catalogLimiter } from '../middleware/rate-limiter.js';
+import { catalogCategoryLimiter, catalogLimiter } from '../middleware/rate-limiter.js';
/**
* A brand's catalog sources (#1263, 00279, 00282). Members see them through
@@ -34,6 +39,12 @@ import { catalogLimiter } from '../middleware/rate-limiter.js';
* sign-in platform's account (`input.account`), checked, then read;
* - PUT /api/catalog/sources/:id/credentials { input }: its sign-in
* replaced;
+ * - GET /api/catalog/categories?brandId=…: the brand's categories, each
+ * with its products, how many are in stock, and its page on the site
+ * (shopping path): members read it;
+ * - PUT /api/catalog/categories { brandId, category, url }: a category's
+ * page set by hand (url), or set to none (null); DELETE with
+ * ?brandId=…&category=… puts it back to the automatic match;
* - DELETE /api/catalog/sources/:id: a store removed, with its sign-in and
* its products.
*/
@@ -47,7 +58,8 @@ export const UPLOAD_MAX = '4mb';
const RESYNC_AFTER_MS = 2 * 60 * 1000;
const FORMATS = ['auto', 'google_xml', 'csv', 'meta_csv'];
-async function assertWriter(brandId, userId) {
+/** Throws a 403 unless the person is an admin or a manager of the brand's workspace; `may` says what for. */
+async function assertWriter(brandId, userId, may = 'sync the catalog') {
await assertBrandAccess(brandId, userId);
const { data: profile } = await supabaseAdmin
.from('profiles')
@@ -55,13 +67,17 @@ async function assertWriter(brandId, userId) {
.eq('id', userId)
.single();
if (!WRITE_ROLES.includes(profile?.role)) {
- const err = new Error('Only admins and managers can sync the catalog.');
+ const err = new Error(`Only admins and managers can ${may}.`);
err.status = 403;
throw err;
}
}
-function fail(req, res, err, what) {
+/** The response to a route's error; `failed` is what a 500 says. */
+function fail(req, res, err, what, failed = 'Failed to sync the catalog') {
+ if (err instanceof CategoryPageError) {
+ return res.status(err.status).json({ error: err.message, code: err.code });
+ }
if (err instanceof StoreError) {
return res.status(err.status).json({ error: err.message, code: err.code });
}
@@ -77,7 +93,7 @@ function fail(req, res, err, what) {
});
}
req.log.error({ err: { name: err?.name, message: err?.message } }, what);
- return res.status(500).json({ error: 'Failed to sync the catalog', code: 'failed' });
+ return res.status(500).json({ error: failed, code: 'failed' });
}
const outcomeBody = (outcome) => ({
@@ -208,6 +224,62 @@ router.post('/sources/:id/sync', catalogLimiter, async (req, res) => {
}
});
+const CHANGE_CATEGORY_PAGES = "change the catalog's category pages";
+const CATEGORY_PAGES_FAILED = "Failed to change the catalog's category pages";
+
+// GET /api/catalog/categories?brandId=… — the brand's categories and their pages.
+// A read like the API's others: the general limiter only.
+router.get('/categories', async (req, res) => {
+ const parsed = z.object({ brandId: z.guid() }).safeParse(req.query);
+ if (!parsed.success) return res.status(400).json({ error: 'invalid', code: 'invalid' });
+ try {
+ await assertBrandAccess(parsed.data.brandId, req.user.id);
+ return res.json({ categories: await categoryPages(parsed.data.brandId) });
+ } catch (err) {
+ return fail(
+ req,
+ res,
+ err,
+ 'catalog categories error',
+ "Failed to read the catalog's category pages",
+ );
+ }
+});
+
+const categoryBody = z.object({
+ brandId: z.guid(),
+ category: z.string().min(1).max(750),
+ url: z.string().max(2048).nullable(),
+});
+
+// PUT /api/catalog/categories — a category's page set by hand, or none (a
+// category the catalog has: 404 otherwise). Writes, here and in DELETE, take
+// a bucket of their own, apart from the syncs'.
+router.put('/categories', catalogCategoryLimiter, async (req, res) => {
+ const parsed = categoryBody.safeParse(req.body);
+ if (!parsed.success) return res.status(400).json({ error: 'invalid', code: 'invalid' });
+ try {
+ await assertWriter(parsed.data.brandId, req.user.id, CHANGE_CATEGORY_PAGES);
+ await setCategoryPage({ ...parsed.data, userId: req.user.id });
+ return res.json({ ok: true });
+ } catch (err) {
+ return fail(req, res, err, 'catalog category page error', CATEGORY_PAGES_FAILED);
+ }
+});
+
+// DELETE /api/catalog/categories?brandId=…&category=… — back to the automatic match.
+router.delete('/categories', catalogCategoryLimiter, async (req, res) => {
+ const parsed = categoryBody.omit({ url: true }).safeParse(req.query);
+ if (!parsed.success) return res.status(400).json({ error: 'invalid', code: 'invalid' });
+ try {
+ await assertWriter(parsed.data.brandId, req.user.id, CHANGE_CATEGORY_PAGES);
+ await setCategoryPage({ ...parsed.data, url: undefined, userId: req.user.id });
+ return res.json({ ok: true });
+ } catch (err) {
+ return fail(req, res, err, 'catalog category page error', CATEGORY_PAGES_FAILED);
+ }
+});
+
// POST /api/catalog/upload?brandId=…&format=… — a file's text as the body.
router.post(
'/upload',
diff --git a/server/src/routes/catalog.test.js b/server/src/routes/catalog.test.js
index c2c46fcb9..8e6190075 100644
--- a/server/src/routes/catalog.test.js
+++ b/server/src/routes/catalog.test.js
@@ -18,6 +18,8 @@ const connectStore = vi.fn();
const reconnectStore = vi.fn();
const disconnectStore = vi.fn();
const connectSignInSource = vi.fn();
+const categoryPages = vi.fn();
+const setCategoryPage = vi.fn();
const listSignInAccounts = vi.fn();
let configured;
let googleConfigured;
@@ -64,8 +66,19 @@ vi.mock('../lib/access.js', () => ({
vi.mock('../lib/catalog/sources.js', () => ({
syncSource: (...args) => syncSource(...args),
}));
-// The limiter's 20 a quarter-hour would end this file's run part way.
-vi.mock('../middleware/rate-limiter.js', () => ({ catalogLimiter: (_req, _res, next) => next() }));
+// The limiters' buckets would end this file's run part way: each request
+// notes the bucket it took instead.
+const buckets = [];
+vi.mock('../middleware/rate-limiter.js', () => ({
+ catalogLimiter: (_req, _res, next) => {
+ buckets.push('catalog');
+ next();
+ },
+ catalogCategoryLimiter: (_req, _res, next) => {
+ buckets.push('categories');
+ next();
+ },
+}));
vi.mock('../lib/catalog/credentials.js', () => ({
credentialsConfigured: () => configured,
}));
@@ -105,6 +118,20 @@ vi.mock('../connectors/index.js', () => ({
kind === 'merchant_center' ? { kind, signIn: 'google-merchant-center' } : { kind },
isSignIn: (connector) => typeof connector?.signIn === 'string',
}));
+vi.mock('../lib/catalog/category-pages.js', () => {
+ class CategoryPageError extends Error {
+ constructor(code, message, status = 400) {
+ super(message);
+ this.code = code;
+ this.status = status;
+ }
+ }
+ return {
+ CategoryPageError,
+ categoryPages: (...args) => categoryPages(...args),
+ setCategoryPage: (...args) => setCategoryPage(...args),
+ };
+});
vi.mock('../lib/composio.js', () => ({
isComposioConfigured: (provider) => provider === 'google-merchant-center' && googleConfigured,
}));
@@ -128,8 +155,19 @@ beforeEach(async () => {
},
];
assertBrandAccess.mockReset().mockResolvedValue({ orgId: 'org-1' });
+ buckets.length = 0;
syncSource.mockReset().mockResolvedValue({ status: 'ok', counts: { items: 4 } });
googleConfigured = true;
+ categoryPages.mockReset().mockResolvedValue([
+ {
+ name: 'Hiking Boots',
+ products: 24,
+ inStock: 18,
+ page: { url: 'https://shop.example/collections/hiking-boots', title: 'Hiking boots' },
+ how: 'address',
+ },
+ ]);
+ setCategoryPage.mockReset().mockResolvedValue(undefined);
connectSignInSource.mockReset().mockResolvedValue({
id: 'gmc-1',
brand_id: BRAND,
@@ -436,3 +474,129 @@ describe('DELETE /api/catalog/sources/:id', () => {
expect(disconnectStore).not.toHaveBeenCalled();
});
});
+
+describe('category pages (shopping path)', () => {
+ it("lists the brand's categories and their pages to any member", async () => {
+ role = 'analyst';
+ const res = await fetch(`${base}/categories?brandId=${BRAND}`);
+ expect(res.status).toBe(200);
+ expect((await res.json()).categories[0]).toMatchObject({
+ name: 'Hiking Boots',
+ how: 'address',
+ });
+ expect(assertBrandAccess).toHaveBeenCalledWith(BRAND, 'user-1');
+ expect(categoryPages).toHaveBeenCalledWith(BRAND);
+ expect((await fetch(`${base}/categories?brandId=nope`)).status).toBe(400);
+ });
+
+ it("sets a category's page, or none, for an admin or a manager only", async () => {
+ role = 'manager';
+ const body = { brandId: BRAND, category: 'Socks', url: 'https://shop.example/c/socks' };
+ expect((await send('PUT', '/categories', body)).status).toBe(200);
+ expect(setCategoryPage).toHaveBeenCalledWith({ ...body, userId: 'user-1' });
+ expect((await send('PUT', '/categories', { ...body, url: null })).status).toBe(200);
+ expect(setCategoryPage).toHaveBeenLastCalledWith({ ...body, url: null, userId: 'user-1' });
+
+ role = 'analyst';
+ expect((await send('PUT', '/categories', body)).status).toBe(403);
+ expect(setCategoryPage).toHaveBeenCalledTimes(2);
+ });
+
+ it("says why a page can't be set, and puts a category back to its match", async () => {
+ setCategoryPage.mockRejectedValueOnce(
+ new (await import('../lib/catalog/category-pages.js')).CategoryPageError(
+ 'off_site',
+ "The page must be on the brand's own site.",
+ ),
+ );
+ const refused = await send('PUT', '/categories', {
+ brandId: BRAND,
+ category: 'Socks',
+ url: 'https://elsewhere.example/socks',
+ });
+ expect(refused.status).toBe(400);
+ expect(await refused.json()).toEqual({
+ error: "The page must be on the brand's own site.",
+ code: 'off_site',
+ });
+
+ const back = await fetch(`${base}/categories?brandId=${BRAND}&category=Socks`, {
+ method: 'DELETE',
+ });
+ expect(back.status).toBe(200);
+ expect(setCategoryPage).toHaveBeenLastCalledWith({
+ brandId: BRAND,
+ category: 'Socks',
+ url: undefined,
+ userId: 'user-1',
+ });
+ });
+
+ it("reads under the API's limit, and writes from a bucket apart from the syncs'", async () => {
+ await fetch(`${base}/categories?brandId=${BRAND}`);
+ expect(buckets).toEqual([]);
+ await send('PUT', '/categories', { brandId: BRAND, category: 'Socks', url: null });
+ await fetch(`${base}/categories?brandId=${BRAND}&category=Socks`, { method: 'DELETE' });
+ expect(buckets).toEqual(['categories', 'categories']);
+ });
+
+ it("refuses another workspace's brand, and a body without its address", async () => {
+ assertBrandAccess.mockRejectedValueOnce(
+ Object.assign(new Error("This brand isn't in your workspace"), {
+ status: 403,
+ code: 'not_in_workspace',
+ }),
+ );
+ const other = await fetch(`${base}/categories?brandId=${BRAND}`);
+ expect(other.status).toBe(403);
+ expect((await other.json()).code).toBe('not_in_workspace');
+ expect(categoryPages).not.toHaveBeenCalled();
+
+ const missing = await send('PUT', '/categories', { brandId: BRAND, category: 'Socks' });
+ expect(missing.status).toBe(400);
+ expect(setCategoryPage).not.toHaveBeenCalled();
+ });
+
+ it('lets only an admin or a manager put a category back to its match', async () => {
+ role = 'analyst';
+ const refused = await fetch(`${base}/categories?brandId=${BRAND}&category=Socks`, {
+ method: 'DELETE',
+ });
+ expect(refused.status).toBe(403);
+ expect(await refused.json()).toEqual({
+ error: "Only admins and managers can change the catalog's category pages.",
+ code: 'forbidden',
+ });
+ expect(setCategoryPage).not.toHaveBeenCalled();
+ });
+
+ it("says a category isn't in the catalog, and what failed in these routes' words", async () => {
+ setCategoryPage.mockRejectedValueOnce(
+ new (await import('../lib/catalog/category-pages.js')).CategoryPageError(
+ 'not_found',
+ "That category isn't in the brand's catalog.",
+ 404,
+ ),
+ );
+ const gone = await send('PUT', '/categories', { brandId: BRAND, category: 'Tents', url: null });
+ expect(gone.status).toBe(404);
+ expect((await gone.json()).code).toBe('not_found');
+
+ setCategoryPage.mockRejectedValueOnce(new Error('catalog_category_pages write: down'));
+ const failed = await send('PUT', '/categories', {
+ brandId: BRAND,
+ category: 'Socks',
+ url: null,
+ });
+ expect(failed.status).toBe(500);
+ expect(await failed.json()).toEqual({
+ error: "Failed to change the catalog's category pages",
+ code: 'failed',
+ });
+
+ categoryPages.mockRejectedValueOnce(new Error('site pages read: down'));
+ const unread = await fetch(`${base}/categories?brandId=${BRAND}`);
+ expect(unread.status).toBe(500);
+ expect((await unread.json()).error).toBe("Failed to read the catalog's category pages");
+ });
+});
diff --git a/supabase/migrations/00350_catalog_category_pages.sql b/supabase/migrations/00350_catalog_category_pages.sql
new file mode 100644
index 000000000..a596f1b4f
--- /dev/null
+++ b/supabase/migrations/00350_catalog_category_pages.sql
@@ -0,0 +1,82 @@
+-- ============================================================================
+-- 00350: each catalog category's page on the brand's site (shopping path, 1)
+-- ============================================================================
+-- A brand's catalog names its categories (00278, from the products'
+-- product_type: "Shoes > Hiking Boots"), but not where each one lives on the
+-- site. The shopping path links a buying guide or a comparison to that page
+-- (/collections/hiking-boots), so the API matches each category to one of
+-- the brand's own pages that reads as a category (site_pages, 00104), every
+-- time it's asked: nothing here keeps those matches.
+--
+-- * `catalog_category_pages` keeps what a person decided instead: the
+-- page for a category (`url`), or that it has none (`url` null). A
+-- category with no row is matched automatically. Keyed by the
+-- category's name, as the catalog keeps it, so a decision outlives a
+-- sync that writes the category again.
+-- * Members read their brands' rows; the API writes them, for admins
+-- and managers, after checking the page is on the brand's domains.
+-- * `catalog_category_counts`: each category's live products and how
+-- many of them have a variant in stock, for the Settings table and the
+-- shopping path. In stock as the editor's feed match reads a variant
+-- (web/src/lib/content/feed-match.ts, feedStock): in_stock, instock,
+-- available or limited_availability, whatever its case, spaces or
+-- hyphens. The service role calls it.
+
+create table if not exists public.catalog_category_pages (
+ brand_id uuid not null references public.brands(id) on delete cascade,
+ category text not null check (char_length(category) between 1 and 750),
+ url text check (url is null or (char_length(url) <= 2048 and url ~* '^https?://')),
+ set_by uuid references public.profiles(id) on delete set null,
+ set_at timestamptz not null default now(),
+ primary key (brand_id, category)
+);
+
+alter table public.catalog_category_pages enable row level security;
+revoke all on table public.catalog_category_pages from anon, authenticated;
+grant select on table public.catalog_category_pages to authenticated;
+grant all on table public.catalog_category_pages to service_role;
+
+drop policy if exists "catalog_category_pages: member select" on public.catalog_category_pages;
+create policy "catalog_category_pages: member select"
+ on public.catalog_category_pages
+ for select
+ using (
+ brand_id in (
+ select b.id from public.brands b
+ join public.profiles p on p.organization_id = b.organization_id
+ where p.id = auth.uid()
+ )
+ );
+
+comment on table public.catalog_category_pages is
+ 'Shopping path (00350): the page a person set for a catalog category (url), or that it has none (url null). Categories with no row are matched to the brand''s site pages by the API on each read. Server writes, members read.';
+
+create or replace function public.catalog_category_counts(p_brand_id uuid)
+returns table (category text, products integer, in_stock integer)
+language sql
+stable
+set search_path = public
+as $$
+ select c.name,
+ count(distinct p.id)::integer,
+ count(distinct p.id) filter (where exists (
+ select 1 from public.catalog_variants v
+ where v.product_id = p.id
+ and v.removed_at is null
+ and lower(regexp_replace(v.availability, '[\s-]+', '_', 'g'))
+ in ('in_stock', 'instock', 'available', 'limited_availability')
+ ))::integer
+ from public.catalog_categories c
+ join public.catalog_product_categories pc on pc.category_id = c.id
+ join public.catalog_products p on p.id = pc.product_id and p.removed_at is null
+ where c.brand_id = p_brand_id
+ group by c.name
+$$;
+
+revoke all on function public.catalog_category_counts(uuid) from public, anon, authenticated;
+grant execute on function public.catalog_category_counts(uuid) to service_role;
+
+comment on function public.catalog_category_counts(uuid) is
+ 'Shopping path (00350): each catalog category of a brand with its live products and how many have a variant in stock (in_stock, instock, available or limited_availability, as feed-match.ts reads it). Service role only.';
+
+notify pgrst, 'reload schema';
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 259962a94..817bd883b 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -41669,3 +41669,89 @@ comment on table public.catalog_item_issues is
notify pgrst, 'reload schema';
+-- ─────────────────────────────────────────────────────────────────────────
+-- migrations/00350_catalog_category_pages.sql
+-- ─────────────────────────────────────────────────────────────────────────
+-- ============================================================================
+-- 00350: each catalog category's page on the brand's site (shopping path, 1)
+-- ============================================================================
+-- A brand's catalog names its categories (00278, from the products'
+-- product_type: "Shoes > Hiking Boots"), but not where each one lives on the
+-- site. The shopping path links a buying guide or a comparison to that page
+-- (/collections/hiking-boots), so the API matches each category to one of
+-- the brand's own pages that reads as a category (site_pages, 00104), every
+-- time it's asked: nothing here keeps those matches.
+--
+-- * `catalog_category_pages` keeps what a person decided instead: the
+-- page for a category (`url`), or that it has none (`url` null). A
+-- category with no row is matched automatically. Keyed by the
+-- category's name, as the catalog keeps it, so a decision outlives a
+-- sync that writes the category again.
+-- * Members read their brands' rows; the API writes them, for admins
+-- and managers, after checking the page is on the brand's domains.
+-- * `catalog_category_counts`: each category's live products and how
+-- many of them have a variant in stock, for the Settings table and the
+-- shopping path. In stock as the editor's feed match reads a variant
+-- (web/src/lib/content/feed-match.ts, feedStock): in_stock, instock,
+-- available or limited_availability, whatever its case, spaces or
+-- hyphens. The service role calls it.
+
+create table if not exists public.catalog_category_pages (
+ brand_id uuid not null references public.brands(id) on delete cascade,
+ category text not null check (char_length(category) between 1 and 750),
+ url text check (url is null or (char_length(url) <= 2048 and url ~* '^https?://')),
+ set_by uuid references public.profiles(id) on delete set null,
+ set_at timestamptz not null default now(),
+ primary key (brand_id, category)
+);
+
+alter table public.catalog_category_pages enable row level security;
+revoke all on table public.catalog_category_pages from anon, authenticated;
+grant select on table public.catalog_category_pages to authenticated;
+grant all on table public.catalog_category_pages to service_role;
+
+drop policy if exists "catalog_category_pages: member select" on public.catalog_category_pages;
+create policy "catalog_category_pages: member select"
+ on public.catalog_category_pages
+ for select
+ using (
+ brand_id in (
+ select b.id from public.brands b
+ join public.profiles p on p.organization_id = b.organization_id
+ where p.id = auth.uid()
+ )
+ );
+
+comment on table public.catalog_category_pages is
+ 'Shopping path (00350): the page a person set for a catalog category (url), or that it has none (url null). Categories with no row are matched to the brand''s site pages by the API on each read. Server writes, members read.';
+
+create or replace function public.catalog_category_counts(p_brand_id uuid)
+returns table (category text, products integer, in_stock integer)
+language sql
+stable
+set search_path = public
+as $$
+ select c.name,
+ count(distinct p.id)::integer,
+ count(distinct p.id) filter (where exists (
+ select 1 from public.catalog_variants v
+ where v.product_id = p.id
+ and v.removed_at is null
+ and lower(regexp_replace(v.availability, '[\s-]+', '_', 'g'))
+ in ('in_stock', 'instock', 'available', 'limited_availability')
+ ))::integer
+ from public.catalog_categories c
+ join public.catalog_product_categories pc on pc.category_id = c.id
+ join public.catalog_products p on p.id = pc.product_id and p.removed_at is null
+ where c.brand_id = p_brand_id
+ group by c.name
+$$;
+
+revoke all on function public.catalog_category_counts(uuid) from public, anon, authenticated;
+grant execute on function public.catalog_category_counts(uuid) to service_role;
+
+comment on function public.catalog_category_counts(uuid) is
+ 'Shopping path (00350): each catalog category of a brand with its live products and how many have a variant in stock (in_stock, instock, available or limited_availability, as feed-match.ts reads it). Service role only.';
+
+notify pgrst, 'reload schema';
+
diff --git a/web/messages/en.json b/web/messages/en.json
index c673be9fe..bb2266054 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -7948,6 +7948,43 @@
"uploadFile": "Upload a file",
"uploadHint": "CSV or XML, up to 4 MB. For a larger catalog, add its feed URL.",
"managersOnly": "Admins and managers can add and sync sources.",
+ "categories": {
+ "title": "Category pages",
+ "description": "Where each catalog category lives on your site, so buying guides and comparisons can link to it. We matched them to your site's pages that read as a category page; check them once.",
+ "unavailable": "Couldn't read the category pages right now.",
+ "category": "Category",
+ "productsHeading": "Products",
+ "pageHeading": "Page on your site",
+ "actions": "Actions",
+ "products": "{products, plural, one {# product} other {# products}} · {inStock} in stock",
+ "noPage": "No page",
+ "how": {
+ "address": "Its address names the category",
+ "title": "Its title names the category",
+ "words": "Most of the category's words",
+ "manual": "Set by hand",
+ "none": "Nothing on your site reads as it"
+ },
+ "change": "Change",
+ "changeLabel": "Change the page for {category}",
+ "urlLabel": "Page address for {category}",
+ "urlPlaceholder": "https://example.com/collections/…",
+ "save": "Save",
+ "setNone": "No page",
+ "useMatch": "Use the match",
+ "cancel": "Cancel",
+ "saved": "Saved.",
+ "errors": {
+ "invalid": "That isn't a web address. Paste the page's address.",
+ "off_site": "The page must be on the brand's own site.",
+ "not_found": "This category isn't in the catalog any more. Reload the page.",
+ "forbidden": "Only admins and managers can change this.",
+ "session": "Your session expired. Sign in again.",
+ "workspace": "This brand isn't in your workspace.",
+ "busy": "Too many requests. Wait a few minutes.",
+ "failed": "Couldn't save the page. Try again later."
+ }
+ },
"synced": "{count, plural, one {# product read} other {# products read}}",
"errors": {
"invalid": "Enter a feed address starting with http:// or https://.",
diff --git a/web/src/components/settings/catalog-category-pages.test.tsx b/web/src/components/settings/catalog-category-pages.test.tsx
new file mode 100644
index 000000000..3dd59b26a
--- /dev/null
+++ b/web/src/components/settings/catalog-category-pages.test.tsx
@@ -0,0 +1,239 @@
+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 { CategoryPage } from '@/lib/catalog-client';
+
+const listCategoryPages = vi.fn();
+const setCategoryPage = vi.fn();
+const resetCategoryPage = vi.fn();
+vi.mock('@/lib/catalog-client', () => ({
+ listCategoryPages: (...args: unknown[]) => listCategoryPages(...args),
+ setCategoryPage: (...args: unknown[]) => setCategoryPage(...args),
+ resetCategoryPage: (...args: unknown[]) => resetCategoryPage(...args),
+}));
+const role = vi.hoisted(() => ({ canManage: true }));
+vi.mock('@/hooks/use-user-role', () => ({ useUserRole: () => role }));
+const brand = vi.hoisted(() => ({ activeBrandId: 'b1' }));
+vi.mock('@/stores/use-brand-store', () => ({
+ useBrandStore: () => ({
+ activeBrandId: brand.activeBrandId,
+ brands: [
+ { id: 'b1', name: 'Acme' },
+ { id: 'b2', name: 'Northwind' },
+ ],
+ }),
+}));
+const toast = vi.hoisted(() => ({ error: vi.fn(), success: vi.fn() }));
+vi.mock('sonner', () => ({ toast }));
+
+const { CatalogCategoryPages, shortAddress } = await import('./catalog-category-pages');
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+/** Settings › Integrations › Category pages (shopping path, 00350). */
+
+let container: HTMLDivElement;
+let root: Root;
+
+const CATEGORIES: CategoryPage[] = [
+ {
+ name: 'Shoes > Hiking Boots',
+ products: 24,
+ inStock: 18,
+ page: { url: 'https://shop.example/collections/hiking-boots', title: 'Hiking boots' },
+ how: 'address',
+ },
+ {
+ name: 'Rain Jackets',
+ products: 16,
+ inStock: 12,
+ page: { url: 'https://shop.example/jackets/rain', title: null },
+ how: 'manual',
+ },
+ { name: 'Sleeping Bags', products: 9, inStock: 9, page: null, how: null },
+];
+
+async function render() {
+ await act(async () => {
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages} timeZone="UTC">
+ <CatalogCategoryPages />
+ </NextIntlClientProvider>,
+ );
+ });
+}
+const button = (label: string) =>
+ [...container.querySelectorAll('button')].find(
+ (b) => b.textContent === label || b.getAttribute('aria-label') === label,
+ );
+async function type(input: HTMLInputElement, value: string) {
+ await act(async () => {
+ const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!;
+ setter.call(input, value);
+ input.dispatchEvent(new Event('input', { bubbles: true }));
+ });
+}
+
+/** A promise resolved later, to see the table while a call is on its way. */
+function later<T>() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((r) => {
+ resolve = r;
+ });
+ return { promise, resolve };
+}
+
+beforeEach(() => {
+ role.canManage = true;
+ brand.activeBrandId = 'b1';
+ listCategoryPages.mockReset().mockResolvedValue({ ok: true, value: CATEGORIES });
+ setCategoryPage.mockReset().mockResolvedValue({ ok: true, value: true });
+ resetCategoryPage.mockReset().mockResolvedValue({ ok: true, value: true });
+ toast.error.mockReset();
+ toast.success.mockReset();
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+});
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+});
+
+describe('shortAddress', () => {
+ it("shows a page's path, or the whole address of a site's root", () => {
+ expect(shortAddress('https://shop.example/collections/boots?x=1')).toBe(
+ '/collections/boots?x=1',
+ );
+ expect(shortAddress('https://shop.example/')).toBe('https://shop.example/');
+ });
+});
+
+describe('CatalogCategoryPages', () => {
+ it("lists the brand's categories with their products, page and how it was found", async () => {
+ await render();
+ expect(listCategoryPages).toHaveBeenCalledWith('b1');
+ const text = container.textContent ?? '';
+ expect(text).toContain('Category pages');
+ expect(text).toContain('24 products · 18 in stock');
+ expect(text).toContain('/collections/hiking-boots');
+ expect(text).toContain('Its address names the category');
+ expect(text).toContain('Set by hand');
+ expect(text).toContain('No page');
+ expect(text).toContain('Nothing on your site reads as it');
+ // Four columns, with how a page was found under it, so the table fits a narrow card.
+ expect(container.querySelectorAll('thead th')).toHaveLength(4);
+ });
+
+ it("gives the form the page's cell and the button's while a category is changed", async () => {
+ await render();
+ await act(async () => button('Change the page for Sleeping Bags')!.click());
+ const input = container.querySelector('input[aria-label="Page address for Sleeping Bags"]')!;
+ expect(input.closest('td')!.colSpan).toBe(2);
+ expect(input.closest('tr')!.querySelectorAll('td')).toHaveLength(3);
+ expect(button('Change the page for Sleeping Bags')).toBeFalsy();
+ });
+
+ it("changes a category's page, and says why one can't be kept", async () => {
+ await render();
+ await act(async () => button('Change the page for Sleeping Bags')!.click());
+ const input = container.querySelector<HTMLInputElement>(
+ 'input[aria-label="Page address for Sleeping Bags"]',
+ )!;
+ await type(input, 'https://elsewhere.example/bags');
+ setCategoryPage.mockResolvedValueOnce({ ok: false, code: 'off_site' });
+ await act(async () => {
+ input.form!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+ });
+ expect(setCategoryPage).toHaveBeenCalledWith(
+ 'b1',
+ 'Sleeping Bags',
+ 'https://elsewhere.example/bags',
+ );
+ expect(toast.error).toHaveBeenCalledWith("The page must be on the brand's own site.");
+
+ await type(input, 'https://shop.example/c/sleeping-bags');
+ await act(async () => {
+ input.form!.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));
+ });
+ expect(toast.success).toHaveBeenCalledWith('Saved.');
+ // Read again after the change.
+ expect(listCategoryPages).toHaveBeenCalledTimes(2);
+ });
+
+ it('sets none, or puts a hand-set page back to the match', async () => {
+ await render();
+ await act(async () => button('Change the page for Rain Jackets')!.click());
+ await act(async () => button('Use the match')!.click());
+ expect(resetCategoryPage).toHaveBeenCalledWith('b1', 'Rain Jackets');
+
+ await act(async () => button('Change the page for Shoes > Hiking Boots')!.click());
+ // A matched page has no match to go back to.
+ expect(button('Use the match')).toBeUndefined();
+ await act(async () => button('No page')!.click());
+ expect(setCategoryPage).toHaveBeenCalledWith('b1', 'Shoes > Hiking Boots', null);
+ });
+
+ it("shows the table, not to change, to members who aren't admins or managers", async () => {
+ role.canManage = false;
+ await render();
+ expect(container.textContent).toContain('Category pages');
+ expect(button('Change the page for Rain Jackets')).toBeUndefined();
+ });
+
+ it('shows nothing while the catalog has no categories', async () => {
+ listCategoryPages.mockResolvedValue({ ok: true, value: [] });
+ await render();
+ expect(container.textContent).toBe('');
+ });
+
+ it("says so under its heading when the categories can't be read", async () => {
+ listCategoryPages.mockResolvedValue({ ok: false, code: 'failed' });
+ await render();
+ const heading = container.querySelector('#catalog-category-pages');
+ expect(heading?.textContent).toBe('Category pages');
+ expect(heading?.closest('section')?.textContent).toContain(
+ "Couldn't read the category pages right now.",
+ );
+ expect(container.querySelector('table')).toBeNull();
+ });
+
+ it("closes a row being changed when the brand changes, and never shows the last brand's rows", async () => {
+ await render();
+ await act(async () => button('Change the page for Rain Jackets')!.click());
+ expect(
+ container.querySelector('input[aria-label="Page address for Rain Jackets"]'),
+ ).not.toBeNull();
+
+ // Another brand with a category of the same name.
+ const read = later<{ ok: true; value: CategoryPage[] }>();
+ listCategoryPages.mockReturnValueOnce(read.promise);
+ brand.activeBrandId = 'b2';
+ await render();
+ expect(listCategoryPages).toHaveBeenLastCalledWith('b2');
+ expect(container.textContent).not.toContain('Rain Jackets');
+ await act(async () => read.resolve({ ok: true, value: CATEGORIES }));
+ expect(container.textContent).toContain('Rain Jackets');
+ expect(container.querySelector('input[aria-label="Page address for Rain Jackets"]')).toBeNull();
+ expect(button('Change the page for Rain Jackets')).toBeDefined();
+ });
+
+ it('holds every change while one is on its way', async () => {
+ await render();
+ await act(async () => button('Change the page for Sleeping Bags')!.click());
+ const saving = later<{ ok: true; value: true }>();
+ setCategoryPage.mockReturnValueOnce(saving.promise);
+ await act(async () => button('No page')!.click());
+ expect(button('Save')!.disabled).toBe(true);
+ expect(button('Cancel')!.disabled).toBe(true);
+ expect(button('Change the page for Rain Jackets')!.disabled).toBe(true);
+
+ await act(async () => saving.resolve({ ok: true, value: true }));
+ expect(toast.success).toHaveBeenCalledWith('Saved.');
+ expect(button('Change the page for Rain Jackets')!.disabled).toBe(false);
+ expect(button('Save')).toBeUndefined();
+ });
+});
diff --git a/web/src/components/settings/catalog-category-pages.tsx b/web/src/components/settings/catalog-category-pages.tsx
new file mode 100644
index 000000000..9214ebc8f
--- /dev/null
+++ b/web/src/components/settings/catalog-category-pages.tsx
@@ -0,0 +1,242 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useTranslations } from 'next-intl';
+import { toast } from 'sonner';
+import { Loader2, Tags } from 'lucide-react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useUserRole } from '@/hooks/use-user-role';
+import {
+ listCategoryPages,
+ resetCategoryPage,
+ setCategoryPage,
+ type CategoryPage,
+ type CategoryPageError,
+} from '@/lib/catalog-client';
+import { useBrandStore } from '@/stores/use-brand-store';
+
+/** A page's address as the table shows it: its path, or the whole address off the root. */
+export function shortAddress(url: string): string {
+ try {
+ const { pathname, search } = new URL(url);
+ return pathname === '/' && !search ? url : `${pathname}${search}`;
+ } catch {
+ return url;
+ }
+}
+
+/**
+ * Category pages (shopping path, 00350): each catalog category of the
+ * active brand and its page on the site, matched by the API or set by a
+ * person, so a buying guide or a comparison links to it. Shown once the
+ * brand's catalog has categories, and under its heading when they can't be
+ * read. Admins and managers change a page, set none, or put it back to the
+ * match; members see the table.
+ *
+ * `refreshKey`: changed by the page to read the categories again (the
+ * catalog's sources read again: a feed added or synced, a file uploaded).
+ */
+export function CatalogCategoryPages({ refreshKey = 0 }: { refreshKey?: number }) {
+ const t = useTranslations('settings.catalog.categories');
+ const { activeBrandId } = useBrandStore();
+ const { canManage } = useUserRole();
+
+ // The categories as read for a brand: another brand's never show.
+ const [loaded, setLoaded] = useState<{
+ brandId: string;
+ categories: CategoryPage[] | null;
+ } | null>(null);
+ const [reads, setReads] = useState(0);
+ // The category being changed, on the brand it was opened for, and what's typed for it.
+ const [editing, setEditing] = useState<{ brandId: string; name: string } | null>(null);
+ const [url, setUrl] = useState('');
+ const [busy, setBusy] = useState(false);
+
+ useEffect(() => {
+ if (!activeBrandId) return;
+ let cancelled = false;
+ void listCategoryPages(activeBrandId).then((result) => {
+ if (cancelled) return;
+ setLoaded({ brandId: activeBrandId, categories: result.ok ? result.value : null });
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [activeBrandId, reads, refreshKey]);
+
+ const current = loaded?.brandId === activeBrandId ? loaded : null;
+ if (!activeBrandId) return null;
+ if (current === null) return <Skeleton className="h-24 w-full" />;
+ // No catalog categories yet: nothing to match.
+ if (current.categories?.length === 0) return null;
+ // Another brand's row is never open here.
+ const open = editing?.brandId === activeBrandId ? editing.name : null;
+
+ const done = async (
+ result: { ok: true } | { ok: false; code: CategoryPageError },
+ ): Promise<void> => {
+ setBusy(false);
+ if (!result.ok) {
+ toast.error(t(`errors.${result.code}`));
+ return;
+ }
+ toast.success(t('saved'));
+ setEditing(null);
+ setReads((n) => n + 1);
+ };
+ const save = async (category: string, value: string | null) => {
+ setBusy(true);
+ await done(await setCategoryPage(activeBrandId, category, value));
+ };
+ const reset = async (category: string) => {
+ setBusy(true);
+ await done(await resetCategoryPage(activeBrandId, category));
+ };
+
+ return (
+ <section aria-labelledby="catalog-category-pages" className="space-y-3 rounded-lg border p-4">
+ <div className="flex items-start gap-3">
+ <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-md border bg-muted/50">
+ <Tags className="h-5 w-5 text-muted-foreground" />
+ </div>
+ <div className="min-w-0">
+ <p id="catalog-category-pages" className="font-medium">
+ {t('title')}
+ </p>
+ <p className="text-sm text-muted-foreground">{t('description')}</p>
+ </div>
+ </div>
+ {current.categories === null ? (
+ <p className="text-sm text-muted-foreground">{t('unavailable')}</p>
+ ) : (
+ <div className="relative overflow-x-auto rounded-md border">
+ <table className="w-full text-sm">
+ <thead>
+ <tr className="text-left text-xs text-muted-foreground">
+ <th className="px-3 py-2 font-medium">{t('category')}</th>
+ <th className="px-3 py-2 font-medium">{t('productsHeading')}</th>
+ <th className="px-3 py-2 font-medium">{t('pageHeading')}</th>
+ {canManage && (
+ <th className="px-3 py-2 font-medium">
+ <span className="sr-only">{t('actions')}</span>
+ </th>
+ )}
+ </tr>
+ </thead>
+ <tbody>
+ {current.categories.map((category) => (
+ <tr key={category.name} className="border-t align-top">
+ <td className="px-3 py-2 font-medium">{category.name}</td>
+ <td className="px-3 py-2 text-muted-foreground">
+ {t('products', { products: category.products, inStock: category.inStock })}
+ </td>
+ <td
+ className="px-3 py-2"
+ colSpan={canManage && open === category.name ? 2 : undefined}
+ >
+ {open === category.name ? (
+ <form
+ className="flex flex-col gap-2"
+ onSubmit={(e) => {
+ e.preventDefault();
+ void save(category.name, url.trim());
+ }}
+ >
+ <Input
+ type="url"
+ inputMode="url"
+ value={url}
+ maxLength={2048}
+ placeholder={t('urlPlaceholder')}
+ aria-label={t('urlLabel', { category: category.name })}
+ onChange={(e) => setUrl(e.target.value)}
+ autoFocus
+ />
+ <div className="flex flex-wrap gap-2">
+ <Button type="submit" size="sm" disabled={busy || !url.trim()}>
+ {busy && <Loader2 className="mr-2 h-3.5 w-3.5 animate-spin" />}
+ {t('save')}
+ </Button>
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ disabled={busy}
+ onClick={() => void save(category.name, null)}
+ >
+ {t('setNone')}
+ </Button>
+ {category.how === 'manual' ? (
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ disabled={busy}
+ onClick={() => void reset(category.name)}
+ >
+ {t('useMatch')}
+ </Button>
+ ) : null}
+ <Button
+ type="button"
+ size="sm"
+ variant="ghost"
+ disabled={busy}
+ onClick={() => setEditing(null)}
+ >
+ {t('cancel')}
+ </Button>
+ </div>
+ </form>
+ ) : category.page ? (
+ <a
+ href={category.page.url}
+ target="_blank"
+ rel="noreferrer"
+ className="underline underline-offset-4 [overflow-wrap:anywhere]"
+ title={category.page.title ?? undefined}
+ >
+ {shortAddress(category.page.url)}
+ </a>
+ ) : (
+ <Badge
+ variant="outline"
+ className="border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-400"
+ >
+ {t('noPage')}
+ </Badge>
+ )}
+ {open !== category.name && (
+ <p className="mt-1 text-xs text-muted-foreground">
+ {t(`how.${category.how ?? 'none'}`)}
+ </p>
+ )}
+ </td>
+ {canManage && open !== category.name && (
+ <td className="px-3 py-2 text-right">
+ <Button
+ size="sm"
+ variant="outline"
+ disabled={busy}
+ aria-label={t('changeLabel', { category: category.name })}
+ onClick={() => {
+ setEditing({ brandId: activeBrandId, name: category.name });
+ setUrl(category.page?.url ?? '');
+ }}
+ >
+ {t('change')}
+ </Button>
+ </td>
+ )}
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </section>
+ );
+}
diff --git a/web/src/components/settings/integrations-section.test.tsx b/web/src/components/settings/integrations-section.test.tsx
index e04bdb1cf..7f8a55700 100644
--- a/web/src/components/settings/integrations-section.test.tsx
+++ b/web/src/components/settings/integrations-section.test.tsx
@@ -29,11 +29,23 @@ vi.mock('@/hooks/use-integration-connect', () => ({
useIntegrationConnect: () => ({ connecting: false, connect: vi.fn() }),
}));
vi.mock('sonner', () => ({ toast: { error: vi.fn(), success: vi.fn() } }));
-// The cards read on their own (tested beside them): here they stand by their names.
+// The cards read on their own (tested beside them): here they stand by their names,
+// the catalog card keeping how it reports its reads, the category pages showing their key.
+const catalogCard = vi.hoisted(() => ({
+ onSources: null as null | ((read: { brandId: string; sources: [] | null } | null) => void),
+}));
vi.mock('./catalog-sources-card', () => ({
- CatalogSourcesCard: () => <div data-card="catalog">Product catalog</div>,
+ CatalogSourcesCard: ({ onSources }: { onSources: typeof catalogCard.onSources }) => {
+ catalogCard.onSources = onSources;
+ return <div data-card="catalog">Product catalog</div>;
+ },
}));
vi.mock('./merchant-center-accounts', () => ({ MerchantCenterAccounts: () => null }));
+vi.mock('./catalog-category-pages', () => ({
+ CatalogCategoryPages: ({ refreshKey }: { refreshKey: number }) => (
+ <div data-card="categories">{refreshKey}</div>
+ ),
+}));
vi.mock('./webflow-card', () => ({ WebflowCard: () => <div data-card="webflow">Webflow</div> }));
const { IntegrationsSection } = await import('./integrations-section');
@@ -129,4 +141,28 @@ describe('IntegrationsSection', () => {
await render();
expect(byText('Google Merchant Center')).not.toBeNull();
});
+
+ it("reads the category pages again on each read of a brand's sources after its first", async () => {
+ await render();
+ const key = () => container.querySelector('[data-card="categories"]')?.textContent;
+ const report = async (read: { brandId: string; sources: [] | null } | null) => {
+ await act(async () => catalogCard.onSources!(read));
+ };
+ // The brand's first read: the category pages read with it already.
+ await report({ brandId: 'b1', sources: [] });
+ expect(key()).toBe('0');
+ // A feed added, synced or uploaded: the sources read again.
+ const again = { brandId: 'b1', sources: [] as [] };
+ await report(again);
+ expect(key()).toBe('1');
+ // The same read heard twice counts once.
+ await report(again);
+ expect(key()).toBe('1');
+ // Another brand: its first read, while loading, then back.
+ await report(null);
+ await report({ brandId: 'b2', sources: null });
+ expect(key()).toBe('1');
+ await report({ brandId: 'b2', sources: [] });
+ expect(key()).toBe('2');
+ });
});
diff --git a/web/src/components/settings/integrations-section.tsx b/web/src/components/settings/integrations-section.tsx
index f6c425d24..8b74cd573 100644
--- a/web/src/components/settings/integrations-section.tsx
+++ b/web/src/components/settings/integrations-section.tsx
@@ -41,6 +41,7 @@ import { matchProperty } from '@/lib/property-match';
import { MERCHANT_CENTER_LABEL } from '@/lib/catalog';
import { isCloud } from '@/config/plans';
import { CatalogSourcesCard, type CatalogSourcesRead } from './catalog-sources-card';
+import { CatalogCategoryPages } from './catalog-category-pages';
import { MerchantCenterAccounts } from './merchant-center-accounts';
import { WebflowCard } from './webflow-card';
import { useIntegrationConnect } from '@/hooks/use-integration-connect';
@@ -64,6 +65,18 @@ export function IntegrationsSection() {
const [catalogReads, setCatalogReads] = useState(0);
// The catalog's sources as its card read them, for the picker to mark the accounts added.
const [catalogSources, setCatalogSources] = useState<CatalogSourcesRead | null>(null);
+ // Bumped on each read of a brand's sources after its first (a feed added or synced, a
+ // file uploaded, a store connected or removed), so the category pages count their
+ // products again. A brand's first read comes with the category pages' own.
+ const [categoryReads, setCategoryReads] = useState(0);
+ const lastSourcesRead = useRef<CatalogSourcesRead | null>(null);
+ const onCatalogSources = useCallback((read: CatalogSourcesRead | null) => {
+ setCatalogSources(read);
+ const last = lastSourcesRead.current;
+ if (!read || read === last) return;
+ if (last?.brandId === read.brandId) setCategoryReads((n) => n + 1);
+ lastSourcesRead.current = read;
+ }, []);
return (
<Card>
<CardHeader>
@@ -106,7 +119,9 @@ export function IntegrationsSection() {
/>
</IntegrationCard>
- <CatalogSourcesCard refreshKey={catalogReads} onSources={setCatalogSources} />
+ <CatalogSourcesCard refreshKey={catalogReads} onSources={onCatalogSources} />
+
+ <CatalogCategoryPages refreshKey={categoryReads} />
</IntegrationGroup>
{/* Send to CMS destinations: a new CMS's card goes in this group. */}
diff --git a/web/src/lib/catalog-client.test.ts b/web/src/lib/catalog-client.test.ts
index eb7b9d198..939d452fe 100644
--- a/web/src/lib/catalog-client.test.ts
+++ b/web/src/lib/catalog-client.test.ts
@@ -11,6 +11,9 @@ vi.mock('@/lib/supabase/client', () => ({
}));
const {
+ listCategoryPages,
+ resetCategoryPage,
+ setCategoryPage,
connectSignInAccount,
connectStore,
listSignInAccounts,
@@ -244,3 +247,58 @@ describe('StoreError', () => {
}
});
});
+
+describe('category pages (shopping path)', () => {
+ it("reads the brand's categories and their pages", async () => {
+ const categories = [{ name: 'Hiking Boots', products: 24, inStock: 18, page: null, how: null }];
+ answer(200, { categories });
+ expect(await listCategoryPages('b1')).toEqual({ ok: true, value: categories });
+ const [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe('/api/aeo/api/catalog/categories?brandId=b1');
+ expect(init).toMatchObject({ headers: { Authorization: 'Bearer tok' } });
+ });
+
+ it("sets a category's page, none, or puts it back to the match", async () => {
+ answer(200, { ok: true });
+ expect(await setCategoryPage('b1', 'Socks', 'https://s.example/c/socks')).toEqual({
+ ok: true,
+ value: true,
+ });
+ let [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe('/api/aeo/api/catalog/categories');
+ expect(init.method).toBe('PUT');
+ expect(JSON.parse(init.body)).toEqual({
+ brandId: 'b1',
+ category: 'Socks',
+ url: 'https://s.example/c/socks',
+ });
+
+ await resetCategoryPage('b1', 'Hiking Boots');
+ [url, init] = fetchMock.mock.calls[1];
+ expect(url).toBe('/api/aeo/api/catalog/categories?brandId=b1&category=Hiking+Boots');
+ expect(init.method).toBe('DELETE');
+ });
+
+ it("names the API's reasons", async () => {
+ answer(400, { code: 'off_site', error: "The page must be on the brand's own site." });
+ expect(await setCategoryPage('b1', 'Socks', 'https://x.example')).toEqual({
+ ok: false,
+ code: 'off_site',
+ });
+ answer(404, { code: 'not_found', error: "That category isn't in the brand's catalog." });
+ expect(await setCategoryPage('b1', 'Tents', null)).toEqual({ ok: false, code: 'not_found' });
+ answer(500, {});
+ expect(await listCategoryPages('b1')).toEqual({ ok: false, code: 'failed' });
+ });
+
+ it('reads an API without the route as no categories, but still fails a save there', async () => {
+ fetchMock.mockResolvedValue(
+ new Response('Cannot GET /api/catalog/categories', { status: 404 }),
+ );
+ expect(await listCategoryPages('b1')).toEqual({ ok: true, value: [] });
+ fetchMock.mockResolvedValue(
+ new Response('Cannot PUT /api/catalog/categories', { status: 404 }),
+ );
+ expect(await setCategoryPage('b1', 'Socks', null)).toEqual({ ok: false, code: 'failed' });
+ });
+});
diff --git a/web/src/lib/catalog-client.ts b/web/src/lib/catalog-client.ts
index 5661a6b5d..3e5869a50 100644
--- a/web/src/lib/catalog-client.ts
+++ b/web/src/lib/catalog-client.ts
@@ -309,3 +309,103 @@ export function connectSignInAccount(
): Promise<StoreResult> {
return connectStore(brandId, kind, { account });
}
+
+/**
+ * A catalog category and its page on the brand's site (shopping path,
+ * 00350): `how` says how it was found; 'manual' is a person's decision,
+ * a page or none (`page` null), and null is no match.
+ */
+export interface CategoryPage {
+ name: string;
+ products: number;
+ inStock: number;
+ page: { url: string; title: string | null } | null;
+ how: 'manual' | 'address' | 'title' | 'words' | null;
+}
+
+export type CategoryPageError =
+ | 'invalid'
+ | 'off_site'
+ | 'not_found'
+ | 'forbidden'
+ | 'session'
+ | 'workspace'
+ | 'busy'
+ | 'failed';
+
+const CATEGORY_KNOWN: readonly CategoryPageError[] = [
+ 'invalid',
+ 'off_site',
+ 'not_found',
+ 'forbidden',
+];
+
+/**
+ * `whenMissing`: what a 404 with no code of ours means, the route not there
+ * yet (an API older than the web).
+ */
+async function categoryCall<T>(
+ path: string,
+ init: RequestInit,
+ read: (body: Record<string, unknown>) => T,
+ whenMissing?: T,
+): Promise<{ ok: true; value: T } | { ok: false; code: CategoryPageError }> {
+ try {
+ const {
+ data: { session },
+ } = await createClient().auth.getSession();
+ if (!session) return { ok: false, code: 'session' };
+ const res = await fetch(`${BROWSER_API_BASE_URL}/api/catalog${path}`, {
+ ...init,
+ headers: {
+ ...init.headers,
+ ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+ Authorization: `Bearer ${session.access_token}`,
+ },
+ });
+ const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+ if (res.ok) return { ok: true, value: read(body) };
+ if (res.status === 404 && body.code === undefined && whenMissing !== undefined) {
+ return { ok: true, value: whenMissing };
+ }
+ const known = CATEGORY_KNOWN.find((c) => c === body.code);
+ if (known) return { ok: false, code: known };
+ const general = apiFailure(res.status, body);
+ return {
+ ok: false,
+ code:
+ general === 'session' || general === 'workspace' || general === 'busy' ? general : 'failed',
+ };
+ } catch (err) {
+ console.error('Failed to reach the catalog API:', err);
+ return { ok: false, code: 'failed' };
+ }
+}
+
+/** The brand's catalog categories and their pages on its site; none while the API has no such route. */
+export function listCategoryPages(brandId: string) {
+ return categoryCall<CategoryPage[]>(
+ `/categories?${new URLSearchParams({ brandId })}`,
+ {},
+ (body) => (body.categories as CategoryPage[] | undefined) ?? [],
+ [],
+ );
+}
+
+/** A category's page set by hand (`url`), or set to none (null). */
+export function setCategoryPage(brandId: string, category: string, url: string | null) {
+ return categoryCall(
+ '/categories',
+ { method: 'PUT', body: JSON.stringify({ brandId, category, url }) },
+ () => true,
+ );
+}
+
+/** A category back to its automatic match. */
+export function resetCategoryPage(brandId: string, category: string) {
+ return categoryCall(
+ `/categories?${new URLSearchParams({ brandId, category })}`,
+ { method: 'DELETE' },
+ () => true,
+ );
+}
diff --git a/web/src/lib/content/__fixtures__/category-paths.json b/web/src/lib/content/__fixtures__/category-paths.json
new file mode 100644
index 000000000..26682c28a
--- /dev/null
+++ b/web/src/lib/content/__fixtures__/category-paths.json
@@ -0,0 +1,41 @@
+{
+ "about": "A shop's pages that read as a category page (slug: its last path segment) or don't (slug: null). The editor's page types (page-types.test.ts, detectPageType for an e-commerce site) and the shopping path's category pages (server/src/lib/catalog/category-pages.test.js, categorySlug) test the same cases.",
+ "cases": [
+ { "url": "https://shop.example/collections/hiking-boots", "slug": "hiking-boots" },
+ { "url": "https://shop.example/Category/Rain-Jackets/", "slug": "rain-jackets" },
+ { "url": "https://shop.example/c/socks.html", "slug": "socks" },
+ { "url": "https://shop.example/product-category/boots/", "slug": "boots" },
+ { "url": "https://shop.example/shop/outdoor/tents", "slug": "tents" },
+ { "url": "https://shop.example/departments/garden", "slug": "garden" },
+ { "url": "https://shop.example/catalog/lamps", "slug": "lamps" },
+ { "url": "https://shop.example/collections/kitchen", "slug": "kitchen" },
+ { "url": "https://shop.example/collections/limited-edition", "slug": "limited-edition" },
+ { "url": "https://shop.example/collections/toothpicks", "slug": "toothpicks" },
+ { "url": "https://shop.example/collections/wholesale-boxes", "slug": "wholesale-boxes" },
+ { "url": "https://shop.example/collections/100%25-cotton", "slug": "100%-cotton" },
+ { "url": "https://shop.example/kategori/kadin-ayakkabi", "slug": "kadin-ayakkabi" },
+ { "url": "https://shop.example/urun-kategori/bot", "slug": "bot" },
+ { "url": "https://shop.example/de/kategorie/wanderschuhe", "slug": "wanderschuhe" },
+ { "url": "https://shop.example/categorie/chaussures", "slug": "chaussures" },
+ { "url": "https://shop.example/categoria-producto/botas", "slug": "botas" },
+ { "url": "https://shop.example/koleksiyon/yaz", "slug": "yaz" },
+ { "url": "https://shop.example/collections/best-hiking-boots", "slug": null },
+ { "url": "https://shop.example/collections/hiking-boots-size-guide", "slug": null },
+ { "url": "https://shop.example/collections/hiking-boots-vs-trail-runners", "slug": null },
+ { "url": "https://shop.example/collections/hiking-boot-alternatives", "slug": null },
+ { "url": "https://shop.example/c/what-is-merino", "slug": null },
+ { "url": "https://shop.example/collections/returns-policy", "slug": null },
+ { "url": "https://shop.example/shop/faq", "slug": null },
+ { "url": "https://shop.example/collections/buying-guide", "slug": null },
+ { "url": "https://shop.example/blog/category/hiking-boots", "slug": null },
+ { "url": "https://shop.example/en/blog/category/hiking-boots", "slug": null },
+ { "url": "https://shop.example/blogs/news/category/hiking-boots", "slug": null },
+ { "url": "https://shop.example/collections/summer-sale", "slug": null },
+ { "url": "https://shop.example/collections/holiday-gifts", "slug": null },
+ { "url": "https://shop.example/collections/best-sellers", "slug": null },
+ { "url": "https://shop.example/collections/for-her", "slug": null },
+ { "url": "https://shop.example/collections/boots/products/summit", "slug": null },
+ { "url": "https://shop.example/products/summit-boot", "slug": null },
+ { "url": "https://shop.example/blog/how-to-choose-boots", "slug": null }
+ ]
+}
diff --git a/web/src/lib/content/page-types.test.ts b/web/src/lib/content/page-types.test.ts
index a64f4192c..78fe59ec7 100644
--- a/web/src/lib/content/page-types.test.ts
+++ b/web/src/lib/content/page-types.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest';
+import categoryPaths from './__fixtures__/category-paths.json';
import { PAGE_TYPES } from './drafts';
import {
SITE_PAGE_TYPES,
@@ -121,6 +122,21 @@ describe('detectPageType from the URL', () => {
expect(detectPageType({ url: 'https://northwind.com/' }, 'b2b')).toBeNull();
expect(detectPageType({ url: '/about-us' }, 'b2b')).toBeNull();
});
+
+ it("keeps a blog's own pages as they were: only its /category/ archives left a shop's categories", () => {
+ expect(detectPageType({ url: '/blog/category/hiking-boots' }, 'ecommerce')).toBe('blog_post');
+ expect(detectPageType({ url: '/blog/how-to-clean-boots' }, 'ecommerce')).toBe('guide');
+ expect(detectPageType({ url: '/blog/trips/porto' }, 'b2c')).toBe('itinerary');
+ expect(detectPageType({ url: '/collections/hiking-boots-size-guide' }, 'b2b')).toBeNull();
+ });
+});
+
+// The shopping path reads a shop's category pages by the same cases
+// (server/src/lib/catalog/category-pages.test.js, categorySlug).
+describe('category pages, as the shopping path reads them (category-paths.json)', () => {
+ it.each(categoryPaths.cases)('$url: a category page when its slug is $slug', ({ url, slug }) => {
+ expect(detectPageType({ url }, 'ecommerce') === 'category_page').toBe(slug !== null);
+ });
});
describe('detectPageType from the page', () => {
diff --git a/web/src/lib/content/page-types.ts b/web/src/lib/content/page-types.ts
index a0b960b16..bddfa1438 100644
--- a/web/src/lib/content/page-types.ts
+++ b/web/src/lib/content/page-types.ts
@@ -122,14 +122,24 @@ const COLLECTION: BySite = { ecommerce: 'collection_page' };
const NOT_DEFINED =
'best|differences?|costs?|prices?|benefits?|advantages?|disadvantages?|pros|cons|new|latest';
+/** The words a shop names its category pages with: /collections/, /c/, /product-category/, /kategori/… */
+const CATEGORY_WORDS =
+ 'collections?|categor(y|ies)|product-categor(y|ies)|urun-kategori(si)?|produkt-kategorie|categorie-produit|categoria-(producto|prodotto|produto)|kategori(ler)?|kategorie(n)?|categorie(s)?|categorias?|koleksiyon(lar)?|kollektion(en)?|c|shop|catalog|departments?';
+/** A blog's own section at the start of a path: /blog/…, /en/news/…, Shopify's /blogs/…. */
+const BLOG_SECTION =
+ '(\\/[a-z]{2}(-[a-z]{2})?)?\\/(blogs?|news|articles?|posts?|insights|stories|magazine|journal)\\/';
+
/**
* URL paths, the most specific first: /blog/hubspot-vs-salesforce is a
* comparison before it is a blog post. Matched on the lowercased path with
- * no trailing slash or file extension.
+ * no trailing slash or file extension. A shop's category pages are the
+ * shopping path's too (server/src/lib/catalog/category-pages.js): both
+ * test __fixtures__/category-paths.json.
*/
const PATH_SIGNS: [RegExp, BySite][] = [
[/\/(pricing|plans|plans-and-pricing)(\/|$)/, { b2b: 'pricing' }],
- [/\/(size-?(guides?|charts?)|sizing(-guides?)?|fit-guides?)([/-]|$)/, SIZING],
+ // A size guide, also at the end of a slug: /collections/hiking-boots-size-guide.
+ [/(^|[/-])(size-?(guides?|charts?)|sizing-guides?|fit-guides?)([/-]|$)|\/sizing([/-]|$)/, SIZING],
[/(^|[/-])alternatives?([/-]|$)/, ALTERNATIVES],
[/(^|[/-])(vs|versus)([/-]|$)|\/(compare|comparisons?)(\/|$)/, COMPARISON],
[
@@ -152,15 +162,18 @@ const PATH_SIGNS: [RegExp, BySite][] = [
{ b2b: 'solution_page' },
],
[/\/(products?|p|dp|items?)\/[^/]+/, { b2b: 'feature_page', ecommerce: 'product_page' }],
- // A themed collection (gifts, bundles, "for …") before a shop's categories,
- // on whole words of the slug: /collections/kitchen and /collections/limited-edition
- // are categories.
+ // A themed collection (gifts, bundles, a sale, "for …") before a shop's
+ // categories, on whole words of the slug: /collections/kitchen,
+ // /collections/limited-edition and /collections/wholesale-boxes are categories.
[
- /\/collections?\/(?:[^/]*-)?(gifts?|bundles?|kits?|sets?|best-?sellers?|new-arrivals?|picks|edit)(?:-|\/|$)|\/collections?\/(?:[^/]*-)?for-[a-z]/,
+ /\/collections?\/(?:[^/]*-)?(gifts?|bundles?|kits?|sets?|best-?sellers?|new-arrivals?|picks|edit|sale|clearance|outlet|deals?|offers?)(?:-|\/|$)|\/collections?\/(?:[^/]*-)?for-[a-z]/,
COLLECTION,
],
+ // A shop's categories, WooCommerce's /product-category/ and the same words
+ // in Turkish, German, French and Spanish among them; never in a blog's own
+ // section (/blog/category/… is WordPress's archive of the blog's posts).
[
- /\/(collections?|categor(y|ies)|c|shop|catalog|departments?)(\/|$)/,
+ new RegExp(`^(?!${BLOG_SECTION}).*\\/(${CATEGORY_WORDS})(\\/|$)`),
{ ecommerce: 'category_page' },
],
[/\/(itinerar(y|ies)|trips?|tours?)(\/|$)|\/\d+-days?-/, { b2c: 'itinerary' }],