@commercelayer/agent-cli 0.3.1 → 0.5.0

package/dist/api/stub/search.js

@@ -0,0 +1,78 @@
+// A copy of the store Worker's search (commercelayer-ai-store src/store/search.ts), so the
+// stub ranks as the store does. Keep it in step with the store's; only the import differs.
+//
+// Catalog search over what apply sent: words in any order, ranked. A query is folded
+// (case and accents aside), split into words, stripped of the stop words of the theme's
+// languages and of plurals; each product scores by where its words appear (title over
+// category over description, in its base text or any translation) and by how many of
+// the query's words it has. Products with every word come first, then those with some;
+// ties go by sku. No embeddings: what a word means is not known here, only that it is there.
+const WEIGHT = { sku: 8, title: 4, category: 2, description: 1 };
+/** Lower case, without accents: "Caffè" and "caffe" compare equal. */
+export const fold = (t) => t.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+// The theme's languages: en, it, fr, de, es. Words that say nothing about a product.
+const STOP = new Set(`a an and any are as at be best but by can do does for from get good have i in into is it its looking me my need of on or our please some something show that the their them these this those to want with without you your
+il lo la i gli le un uno una di da del della dei delle per con su e o che qualcosa cerco vorrei voglio mi un po
+le la les un une des de du d et ou pour avec sur dans au aux en quelque chose je veux cherche
+der die das ein eine einen einem und oder fur mit auf im in zu etwas ich suche mochte
+el la los las un una unos unas de del y o para con en algo busco quiero`.split(/\s+/));
+/** A word in one spelling: folded, and singular for the common plurals (beans, berries, boxes). */
+function stem(word) {
+    if (word.length > 4 && word.endsWith('ies'))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 4 && /(ches|shes|sses|xes)$/.test(word))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith('s') && !/(ss|us|is)$/.test(word))
+        return word.slice(0, -1);
+    return word;
+}
+const wordsIn = (text) => (text ? fold(text).split(/[^\p{L}\p{N}]+/u).filter(Boolean).map(stem) : []);
+/** The words a query searches for: no stop words, no repeats, in the order given. */
+export function queryWords(text) {
+    return [...new Set(wordsIn(text).filter((w) => !STOP.has(w)))];
+}
+/** A product's words by field, its base text and every translation together. */
+function fieldsOf(p) {
+    const texts = [p, ...Object.values(p.translations ?? {})];
+    return {
+        sku: new Set([fold(p.sku), ...wordsIn(p.sku)]),
+        title: new Set(texts.flatMap((t) => wordsIn(t.name))),
+        category: new Set(texts.flatMap((t) => wordsIn(t.category))),
+        description: new Set(texts.flatMap((t) => wordsIn(t.description))),
+    };
+}
+/** A word is in a field when the field has it, or (for words of four letters or more) a word that starts with it: "filt" finds "filter". */
+const has = (field, word) => field.has(word) || (word.length >= 4 && [...field].some((w) => w.startsWith(word)));
+/** How well a product matches the query's words, or null when none of them is in it. */
+export function scoreOf(p, words) {
+    if (!words.length)
+        return { score: 0, words: [], matched: [], all: true };
+    const fields = fieldsOf(p);
+    const found = [];
+    const matched = new Set();
+    let score = 0;
+    for (const w of words) {
+        const where = Object.keys(WEIGHT).filter((f) => has(fields[f], w));
+        if (!where.length)
+            continue;
+        found.push(w);
+        where.forEach((f) => matched.add(f));
+        score += WEIGHT[where[0]];
+    }
+    if (!found.length)
+        return null;
+    const all = found.length === words.length;
+    // Every word beats some words; more words beat better places.
+    score += found.length * 10 + (all ? 100 : 0);
+    return { score, words: found, matched: Object.keys(WEIGHT).filter((f) => matched.has(f)), all };
+}
+/** The products matching a query, best first; ties by sku. An empty query (or only stop words) matches everything, by sku. */
+export function rank(products, text) {
+    const words = queryWords(text);
+    return products
+        .flatMap((product) => {
+        const match = scoreOf(product, words);
+        return match ? [{ product, match }] : [];
+    })
+        .sort((a, b) => b.match.score - a.match.score || (a.product.sku < b.product.sku ? -1 : a.product.sku > b.product.sku ? 1 : 0));
+}

package/dist/api/stub/shopping.js

@@ -3,6 +3,9 @@
 // schemas; src/ucp/platform.ts holds the constants shared with the client.
 import crypto from 'node:crypto';
 import { SANDBOX_CREDENTIAL_TYPE, SANDBOX_HANDLER, SANDBOX_HANDLER_ID, SANDBOX_TOKEN_DECLINED, SANDBOX_TOKEN_SUCCESS, toMinor, UCP_VERSION } from '../../ucp/platform.js';
+import { baseLanguage, marketLocale, texts } from './locale.js';
+import { queryWords, rank } from './search.js';
+const lang = (ctx) => ctx.language ?? baseLanguage(ctx.record);
 /** The discount code every sandbox accepts: 10% off the items. */
 const SANDBOX_CODE = 'SANDBOX10';
 const CONSENT_PURPOSES = {
@@ -88,62 +91,123 @@ function returnPolicy(ctx) {
 // ---------- catalog
 /** A path in the storefront (img/eth.jpg) is served from the store host: shopping agents always get a full URL,
  * and for a product without an image, its tile. */
-const imageUrl = (ctx, p) => new URL(p.image_url ?? `tiles/${encodeURIComponent(p.sku)}.svg`, `${ctx.origin}/`).href;
-function variant(ctx, p, market) {
+const imageUrl = (ctx, p) => new URL(p.image_url ?? `tiles/${encodeURIComponent(p.sku)}.svg${lang(ctx) === baseLanguage(ctx.record) ? '' : `?lang=${lang(ctx)}`}`, `${ctx.origin}/`).href;
+/** A product page: under the locale of the buyer's country when it is in the market, else the market's first. */
+function productUrl(ctx, p, market) {
+    if (ctx.record.storefront_mode === 'agent-only')
+        return undefined;
+    const l = marketLocale(ctx.record, market.code, ctx.country);
+    return `${ctx.origin}${l ? `/${l.path}` : ''}/products/${encodeURIComponent(p.sku)}`;
+}
+/** asked: the country the buyer asked about (filters.fulfills_to, else context), whose shipping the variant answers for. */
+function variant(ctx, p, market, asked) {
     const price = { amount: toMinor(p.prices[market.currency], market.currency), currency: market.currency };
     const v = {
         id: p.sku,
         sku: p.sku,
-        title: p.name,
-        description: { plain: p.description ?? p.name },
+        title: texts(p, lang(ctx)).name,
+        description: { plain: texts(p, lang(ctx)).description ?? texts(p, lang(ctx)).name },
         // Agent-only stores have no product pages to link to.
-        url: ctx.record.storefront_mode === 'agent-only' ? undefined : `${ctx.origin}/products/${encodeURIComponent(p.sku)}`,
+        url: productUrl(ctx, p, market),
         price,
         // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
         availability: { available: true, status: 'in_stock' },
+        // Like the store: which market the price is for. tax_included comes from a Commerce Layer price list: none here.
+        metadata: { prices: { market: market.code, market_name: market.name, currency: market.currency, countries: market.countries } },
     };
     v.media = [{ type: 'image', url: imageUrl(ctx, p) }];
     if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
         const o = shippingOption(market);
-        v.fulfillment = { methods: [{ type: 'shipping', description: { plain: `Ships to ${market.countries.join(', ')}` }, availability: v.availability, options: [{ id: o.id, title: o.title, description: o.description }] }] };
+        // days is "3" or "3-5": the earliest and latest arrival, at noon UTC.
+        const [first, last = first] = String(market.shipping?.days ?? '0').split('-').map((d) => Number(d.trim()) || 0);
+        const day = (n) => {
+            const at = new Date(Date.now() + n * 86_400_000);
+            at.setUTCHours(12, 0, 0, 0);
+            return at.toISOString().replace('.000', '');
+        };
+        const ships = !asked || market.countries.includes(asked.toUpperCase());
+        const availability = ships ? v.availability : { available: false, status: 'out_of_stock' };
+        const method = {
+            type: 'shipping',
+            description: { plain: `Ships to ${market.countries.join(', ')}` },
+            ships_to: market.countries,
+            availability,
+            options: ships ? [{ id: o.id, title: o.title, description: o.description, totals: [{ type: 'fulfillment', display_text: 'Shipping', amount: o.totals[0].amount }], earliest_fulfillment_time: day(first), latest_fulfillment_time: day(last) }] : [],
+        };
+        if (asked)
+            method.destination = { address_country: asked.toUpperCase(), ships };
+        // Like the store: the variant stays available; the method says it does not ship there.
+        v.fulfillment = { methods: [method] };
     }
     return v;
 }
-function product(ctx, p, market) {
-    const v = variant(ctx, p, market);
+function product(ctx, p, market, asked, match) {
+    const v = variant(ctx, p, market, asked);
     const out = {
         id: `prod_${p.sku}`,
         handle: p.sku.toLowerCase(),
-        title: p.name,
-        description: { plain: p.description ?? p.name },
+        title: v.title,
+        description: v.description,
         url: v.url,
         price_range: { min: v.price, max: v.price },
         variants: [v],
     };
     if (v.media)
         out.media = v.media;
+    // Like the store: the base language's path, which filters.categories matches.
+    if (p.category)
+        out.categories = [{ value: p.category, taxonomy: 'merchant' }];
+    if (match && match.words.length)
+        out.metadata = { search: { score: match.score, all_words: match.all, words: match.words, matched_on: match.matched } };
     return out;
 }
+/** A category path folded as the store folds it: case and spacing, not accents. */
+const categoryKey = (c) => c.split('>').map((l) => l.trim().toLowerCase().replace(/\s+/g, ' ')).join(' > ');
 export function searchCatalog(ctx, body) {
     const market = pickMarket(ctx, body.context);
     if (!market)
         return { ucp: envelope(ctx, 'catalog.search'), products: [], pagination: { has_next_page: false, total_count: 0 } };
-    const q = String(body.query ?? '').toLowerCase().trim();
+    const q = String(body.query ?? '').trim();
     const max = body.filters?.price?.max;
     const min = body.filters?.price?.min;
+    const asked = body.filters?.fulfills_to?.address_country ?? body.context?.address_country;
+    // Like the store: filters.fulfills_to restricts the results to what ships there (context alone only seeds availability).
+    const shipsTo = body.filters?.fulfills_to?.address_country?.toUpperCase();
+    if (shipsTo && !market.countries.includes(shipsTo)) {
+        const other = markets(ctx).find((m) => m.countries.includes(shipsTo));
+        const content = other
+            ? `The ${market.name} market ships to ${market.countries.join(', ')}, not to ${shipsTo}. The ${other.name} market (${other.currency}) does: send context.address_country ${shipsTo} for its prices.`
+            : `The store does not ship to ${shipsTo}.`;
+        return { ucp: envelope(ctx, 'catalog.search'), products: [], pagination: { has_next_page: false, total_count: 0 }, messages: [{ type: 'info', code: 'no_results', path: '$.filters.fulfills_to.address_country', content }] };
+    }
     let all = Object.values(applied(ctx).products).filter((p) => p.prices[market.currency] !== undefined);
-    if (q)
-        all = all.filter((p) => `${p.name} ${p.description ?? ''} ${p.sku}`.toLowerCase().includes(q));
+    // Like the store: a category matches itself and the paths below it, by whole levels.
+    const wanted = (body.filters?.categories ?? []).map((c) => categoryKey(String(c)));
+    if (wanted.length)
+        all = all.filter((p) => p.category && wanted.some((w) => categoryKey(p.category) === w || categoryKey(p.category).startsWith(`${w} > `)));
     all = all.filter((p) => (min === undefined || toMinor(p.prices[market.currency], market.currency) >= min) && (max === undefined || toMinor(p.prices[market.currency], market.currency) <= max));
+    // Like the store: words in any order, ranked; every word before some of them.
+    const ranked = rank(all, q);
     const limit = Math.max(1, Number(body.pagination?.limit ?? 10));
     const offset = Number(body.pagination?.cursor ?? 0) || 0;
-    const page = all.slice(offset, offset + limit);
-    const hasNext = offset + limit < all.length;
+    const page = ranked.slice(offset, offset + limit);
+    const hasNext = offset + limit < ranked.length;
     const out = {
         ucp: envelope(ctx, 'catalog.search'),
-        products: page.map((p) => product(ctx, p, market)),
-        pagination: { has_next_page: hasNext, total_count: all.length, ...(hasNext ? { cursor: String(offset + limit) } : {}) },
+        products: page.map(({ product: p, match }) => product(ctx, p, market, asked, match)),
+        pagination: { has_next_page: hasNext, total_count: ranked.length, ...(hasNext ? { cursor: String(offset + limit) } : {}) },
     };
+    const categories = [...new Set(Object.values(applied(ctx).products).map((p) => p.category).filter(Boolean))].sort().join('; ');
+    const messages = [];
+    const words = queryWords(q);
+    if (!ranked.length)
+        messages.push({ type: 'info', code: 'no_results', content: `No products match${words.length ? `: searched the words "${words.join(' ')}" in titles, categories and descriptions, in any order` : ''}.${categories ? ` The store's categories: ${categories}.` : ''} Retry with fewer or other words, or with one of them in filters.categories.` });
+    else if (words.length > 1 && !ranked[0].match.all)
+        messages.push({ type: 'info', code: 'partial_match', content: `No product has every word of "${q}"; these have some of them (${words.join(', ')}), best first.${categories ? ` The store's categories: ${categories}.` : ''}` });
+    if (!body.context?.address_country && !body.context?.currency)
+        messages.push({ type: 'info', code: 'prices', content: `Prices are in ${market.currency} for the ${market.name} market (${market.countries.join(', ')}). Send context.address_country for another country's prices and shipping.` });
+    if (messages.length)
+        out.messages = messages;
     const policies = returnPolicy(ctx);
     if (policies.length)
         out.policies = policies;
@@ -202,7 +266,7 @@ function buildLines(ctx, market, requested, existing = []) {
         const price = toMinor(p.prices[market.currency], market.currency);
         const qty = quantity;
         const prev = existing.find((e) => e.id === l.id) ?? existing.find((e) => e.item.id === p.sku);
-        const item = { id: p.sku, title: p.name, price };
+        const item = { id: p.sku, title: texts(p, lang(ctx)).name, price };
         item.image_url = imageUrl(ctx, p);
         lines.push({ id: prev?.id ?? `li_${++n}`, item, quantity: qty, totals: [{ type: 'subtotal', amount: price * qty }, { type: 'total', amount: price * qty }] });
     });
@@ -570,6 +634,8 @@ function placeOrder(ctx, ck) {
         order.attribution = ck.attribution;
     if (ck.buyer)
         order._buyer = ck.buyer;
+    // What the merchant view of the order reads (stub/orders.ts): it lands placed, payment authorized.
+    Object.assign(order, { _placed_at: new Date().toISOString(), _market: ck._market, _cart_id: ck._cart_id, _codes: ck.discounts?.codes ?? [], _language: lang(ctx) });
     orders[orderId] = order;
     const webhook = platformWebhook(ctx);
     if (webhook)

package/dist/api/stub/theme.js

@@ -4,6 +4,7 @@
 // at /products/<sku>. Prices come from what is applied; "Buy" opens the cart permalink.
 // A product without an image shows its tile, and an unset hero the generated one, both
 // drawn at /tiles/ (renderTile) as the store host does.
+import { baseLanguage, cookieLocale, COOKIE, localeOfCountry, localesOf, texts } from './locale.js';
 export const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 /** Black or white, whichever reads better on the accent. */
 function onAccent(hex) {
@@ -11,28 +12,126 @@ function onAccent(hex) {
     const [r, g, b] = [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
     return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.179 ? '#000000' : '#ffffff';
 }
-export function renderTheme(r, path, search) {
-    const products = Object.values(r.applied?.products ?? {});
+/** The selector's strings, in the store's base language; other languages fall back to en, like the store. */
+const UI = {
+    en: { choose: 'Choose your country', shipping: (c) => `Shipping to ${c}?` },
+    it: { choose: 'Scegli il tuo paese', shipping: (c) => `Spedisci in ${c}?` },
+    fr: { choose: 'Choisissez votre pays', shipping: (c) => `Livraison en ${c} ?` },
+    de: { choose: 'Wählen Sie Ihr Land', shipping: (c) => `Versand nach ${c}?` },
+    es: { choose: 'Elige tu país', shipping: (c) => `¿Envío a ${c}?` },
+};
+const countryName = (cc, ll) => {
+    try {
+        return new Intl.DisplayNames([ll], { type: 'region' }).of(cc) ?? cc;
+    }
+    catch {
+        return cc;
+    }
+};
+const tag = (l) => `${l.language}-${l.country}`;
+const alternates = (locales, rest) => [...locales.map((l) => `<link rel="alternate" hreflang="${tag(l)}" href="/${l.path}${rest === '/' ? '/' : rest}">`), '<link rel="alternate" hreflang="x-default" href="/">'].join('\n');
+/**
+ * The hosted theme's routes. With locales (two or more countries, or one): the selector at /,
+ * the pages under /<cc>-<ll>/, a cookie that remembers the choice, unprefixed product and
+ * category paths sent to the remembered or first locale. Without (not applied since locales
+ * exist): the site as it was. null when the path is not the theme's.
+ */
+export function renderTheme(r, path, search, headers = {}) {
+    const locales = localesOf(r);
+    if (!locales.length)
+        return renderPage(r, path, search, null);
+    const redirect = (to, extra = {}) => ({ status: 302, headers: { location: to, 'cache-control': 'no-store', ...extra }, body: '' });
+    if (path === '/') {
+        if (locales.length === 1)
+            return redirect(`/${locales[0].path}/`);
+        const chosen = cookieLocale(r, headers.cookie);
+        if (chosen && !search.has('change'))
+            return redirect(`/${chosen.path}/`, { vary: 'Cookie' });
+        const page = selector(r, locales, headers['cf-ipcountry']);
+        page.headers.vary = 'Cookie';
+        return page;
+    }
+    const m = path.match(/^\/([a-z]{2})-([a-z]{2})(\/.*)?$/);
+    if (m) {
+        const l = localeOfCountry(r, m[1]);
+        if (!l)
+            return null;
+        const rest = m[3] ?? '/';
+        if (l.language !== m[2])
+            return redirect(`/${l.path}${rest === '/' ? '/' : rest}`);
+        const page = renderPage(r, rest, search, l);
+        if (page)
+            page.headers['set-cookie'] = `${COOKIE}=${l.path}; Path=/; Max-Age=31536000; SameSite=Lax; Secure`;
+        return page;
+    }
+    if (/^\/(products|categories)\//.test(path))
+        return redirect(`/${(cookieLocale(r, headers.cookie) ?? locales[0]).path}${path}`, { vary: 'Cookie' });
+    return null;
+}
+function selector(r, locales, ipCountry) {
+    const base = baseLanguage(r);
+    const ui = UI[base] ?? UI.en;
     const markets = Object.values(r.applied?.markets ?? {});
+    const near = ipCountry ? localeOfCountry(r, ipCountry) : undefined;
+    const link = (l) => `<a href="/${l.path}/" hreflang="${tag(l)}" lang="${l.language}">${esc(countryName(l.country, base))}</a>`;
+    const body = `<main class="selector"><h1>${esc(ui.choose)}</h1>${near ? `<p class="suggestion"><a href="/${near.path}/">${esc(ui.shipping(countryName(near.country, base)))}</a></p>` : ''}${markets
+        .map((mk) => {
+        const ls = locales.filter((l) => l.market === mk.code);
+        return ls.length ? `<section><h2>${esc(mk.name)} (${esc(mk.currency)})</h2><ul>${ls.map((l) => `<li>${link(l)}</li>`).join('')}</ul></section>` : '';
+    })
+        .join('')}</main>`;
+    return page(r, { lang: base, title: r.name ?? r.org, head: alternates(locales, '/'), header: '', body, description: ui.choose });
+}
+function page(r, o) {
     const theme = r.theme ?? {};
     const color = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(theme.color ?? '') ? theme.color : '#2f5d50';
     const name = r.name ?? r.org;
-    const market = markets.find((m) => m.code === search.get('market')) ?? markets[0];
-    const keep = market && market !== markets[0] ? `?market=${encodeURIComponent(market.code)}` : '';
-    const price = (p) => (market && p.prices[market.currency] !== undefined ? `${market.currency} ${p.prices[market.currency].toFixed(2)}` : '');
-    const tagline = theme.tagline ?? `Ships to ${markets.flatMap((m) => m.countries).join(', ')}`;
     const badge = theme.badge ? ` <span class="badge">${esc(theme.badge)}</span>` : '';
     const logo = (theme.logo ? `<img class="logo" src="/${esc(theme.logo.replace(/^\//, ''))}" alt="${esc(name)}">` : `<span class="wordmark">${esc(name)}</span>`) + badge;
+    const html = `<!doctype html>
+<html lang="${esc(o.lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(o.title)}</title>
+<meta name="description" content="${esc(o.description)}">
+${o.head ? `${o.head}\n` : ''}<!-- c11r stub: a stand-in for the hosted theme. -->
+<style>:root{--accent:${color};--on-accent:${onAccent(color)}}body{margin:0;font-family:system-ui,sans-serif;color:#16181d}header{display:flex;justify-content:space-between;padding:16px 24px}.logo{max-height:40px}.badge{margin-left:8px;padding:2px 8px;border-radius:999px;background:var(--accent);color:var(--on-accent);font-size:12px;vertical-align:middle}.hero{padding:64px 24px;background-size:cover}.band{background:var(--accent);color:var(--on-accent)}.grid{display:grid;gap:24px;grid-template-columns:repeat(auto-fill,minmax(220px,1fr))}.buy{background:var(--accent);color:var(--on-accent);padding:8px 14px}main{padding:24px}</style>
+</head>
+<body>
+<header><a href="${o.home ?? '/'}">${logo}</a>${o.header}</header>
+${o.body}
+</body>
+</html>
+`;
+    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: html };
+}
+/** The home page and the product pages, for a locale (prefixed paths, its market, its language) or for none (the site as it was). */
+function renderPage(r, path, search, locale) {
+    const products = Object.values(r.applied?.products ?? {});
+    const markets = Object.values(r.applied?.markets ?? {});
+    const theme = r.theme ?? {};
+    const name = r.name ?? r.org;
+    const base = baseLanguage(r);
+    const ll = locale?.language ?? base;
+    const market = locale ? r.applied?.markets[locale.market] : (markets.find((m) => m.code === search.get('market')) ?? markets[0]);
+    const prefix = locale ? `/${locale.path}` : '';
+    const keep = !locale && market && market !== markets[0] ? `?market=${encodeURIComponent(market.code)}` : '';
+    // Under a locale, prices as that country writes them (14,50 € on /it-it/); the site as it was keeps EUR 14.50.
+    const money = (amount, currency) => (locale ? new Intl.NumberFormat(tag(locale), { style: 'currency', currency }).format(amount) : `${currency} ${amount.toFixed(2)}`);
+    const price = (p) => (market && p.prices[market.currency] !== undefined ? money(p.prices[market.currency], market.currency) : '');
+    const tagline = theme.tagline ?? `Ships to ${markets.flatMap((m) => m.countries).join(', ')}`;
     const img = (url) => (/^https?:/.test(url) ? url : `/${url}`);
-    const image = (p) => p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : `<span class="placeholder"><img src="/tiles/${esc(encodeURIComponent(p.sku))}.svg" alt="${esc(p.name)}" loading="lazy"></span>`;
-    const card = (p) => `<article class="product"><a href="/products/${encodeURIComponent(p.sku)}${keep}">${image(p)}<h3>${esc(p.name)}</h3></a><p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></article>`;
+    const lang = ll === base ? '' : `?lang=${ll}`;
+    const image = (p) => p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(texts(p, ll).name)}">` : `<span class="placeholder"><img src="/tiles/${esc(encodeURIComponent(p.sku))}.svg${lang}" alt="${esc(texts(p, ll).name)}" loading="lazy"></span>`;
+    const card = (p) => `<article class="product"><a href="${prefix}/products/${encodeURIComponent(p.sku)}${keep}">${image(p)}<h3>${esc(texts(p, ll).name)}</h3></a><p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></article>`;
     let title = name;
     let body;
     const m = path.match(/^\/products\/([^/]+)$/);
     if (path === '/') {
         const groups = new Map();
         for (const p of products) {
-            const top = p.category?.split(' > ')[0] ?? 'Other';
+            const top = texts(p, ll).category?.split(' > ')[0] ?? 'Other';
             groups.set(top, [...(groups.get(top) ?? []), p]);
         }
         const hero = `<section class="hero" style="background-image:url('${esc(theme.hero ? img(theme.hero) : '/tiles/hero.svg')}')">`;
@@ -42,32 +141,22 @@ export function renderTheme(r, path, search) {
         const p = r.applied?.products[decodeURIComponent(m[1])];
         if (!p)
             return null;
-        title = `${p.name} · ${name}`;
-        body = `<main class="product-page">${image(p)}<div>${p.category ? `<p class="category">${esc(p.category)}</p>` : ''}<h1>${esc(p.name)}</h1>${p.description ? `<p>${esc(p.description)}</p>` : ''}<p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></div></main>`;
+        const t = texts(p, ll);
+        title = `${t.name} · ${name}`;
+        body = `<main class="product-page">${image(p)}<div>${t.category ? `<p class="category">${esc(t.category)}</p>` : ''}<h1>${esc(t.name)}</h1>${t.description ? `<p>${esc(t.description)}</p>` : ''}<p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></div></main>`;
     }
     else
         return null;
-    const html = `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${esc(title)}</title>
-<meta name="description" content="${esc(tagline)}">
-<!-- c11r stub: a stand-in for the hosted theme. -->
-<style>:root{--accent:${color};--on-accent:${onAccent(color)}}body{margin:0;font-family:system-ui,sans-serif;color:#16181d}header{display:flex;justify-content:space-between;padding:16px 24px}.logo{max-height:40px}.badge{margin-left:8px;padding:2px 8px;border-radius:999px;background:var(--accent);color:var(--on-accent);font-size:12px;vertical-align:middle}.hero{padding:64px 24px;background-size:cover}.band{background:var(--accent);color:var(--on-accent)}.grid{display:grid;gap:24px;grid-template-columns:repeat(auto-fill,minmax(220px,1fr))}.buy{background:var(--accent);color:var(--on-accent);padding:8px 14px}main{padding:24px}</style>
-</head>
-<body>
-<header><a href="/${keep}">${logo}</a><nav>${markets.map((x) => `<a href="?market=${encodeURIComponent(x.code)}">${esc(x.name)}</a>`).join(' ')}</nav></header>
-${body}
-</body>
-</html>
-`;
-    return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: html };
+    const header = locale
+        ? localesOf(r).length > 1
+            ? `<nav><a class="country" href="/?change">${esc(countryName(locale.country, ll))} · ${esc(market?.currency ?? '')}</a></nav>`
+            : ''
+        : `<nav>${markets.map((x) => `<a href="?market=${encodeURIComponent(x.code)}">${esc(x.name)}</a>`).join(' ')}</nav>`;
+    return page(r, { lang: locale ? tag(locale) : 'en', title, head: locale ? alternates(localesOf(r), path) : '', header, body, description: tagline, home: `${prefix}/${keep}` });
 }
 const xml = (t) => String(t ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
 /** /tiles/<sku>.svg and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
-export function renderTile(r, path) {
+export function renderTile(r, path, search) {
     const m = path.match(/^\/tiles\/([^/]+)\.svg$/);
     if (!m)
         return null;
@@ -87,7 +176,7 @@ export function renderTile(r, path) {
         const p = r.applied?.products[sku];
         if (!p)
             return null;
-        svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1200" viewBox="0 0 1200 1200"><rect width="1200" height="1200" fill="${color}" fill-opacity="0.08"/><text x="600" y="600" text-anchor="middle" font-family="system-ui, sans-serif" font-size="72" fill="${color}">${xml(p.name.slice(0, 60))}</text></svg>`;
+        svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1200" viewBox="0 0 1200 1200"><rect width="1200" height="1200" fill="${color}" fill-opacity="0.08"/><text x="600" y="600" text-anchor="middle" font-family="system-ui, sans-serif" font-size="72" fill="${color}">${xml(texts(p, search?.get('lang') ?? '').name.slice(0, 60))}</text></svg>`;
     }
     return { status: 200, headers, body: svg };
 }

package/dist/api/stub/ucp.js

@@ -9,6 +9,7 @@ import { strip } from './db.js';
 import { json } from './http.js';
 import * as shop from './shopping.js';
 import { esc, renderTheme, renderTile } from './theme.js';
+import { ucpLanguage } from './locale.js';
 const SCOPES = ['dev.ucp.shopping.order:read', 'dev.ucp.shopping.order:manage'];
 const OUR_CAPABILITIES = [...SHOPPING_CAPABILITIES, 'dev.ucp.common.ask', ...Object.keys(EXTENSIONS), 'dev.ucp.common.identity_linking', 'dev.ucp.shopping.permalink'];
 // ---------- profile
@@ -107,8 +108,11 @@ function handleService(req, r, origin, path) {
             return { status: seen.status, headers: { ...seen.headers, 'idempotent-replayed': 'true' }, body: seen.body };
         }
     }
-    // 3. The operation.
+    // 3. The operation, in the language the platform asked for (or the buyer's country's, or the base).
+    ctx.language = ucpLanguage(r, parsed?.context, req.headers['accept-language']);
+    ctx.country = typeof parsed?.context?.address_country === 'string' ? parsed.context.address_country : undefined;
     const res = dispatch(ctx, req.method, path, parsed);
+    res.headers['content-language'] = ctx.language;
     if (mutating && key)
         r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body };
     return res;
@@ -303,21 +307,21 @@ function handlePermalink(req, r, origin, path) {
     return { status: 303, headers: { location: target, ...safe }, body: '' };
 }
 const MIME = { html: 'text/html; charset=utf-8', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', avif: 'image/avif', ico: 'image/x-icon', txt: 'text/plain' };
-function serveStorefront(r, path, search) {
+function serveStorefront(r, path, search, headers) {
     const files = r.ucp.files;
     // /tiles/ is the store host's own, in front of a custom storefront too: unknown tiles are a 404.
     if (path.startsWith('/tiles/'))
-        return renderTile(r, path) ?? html(404, 'Not found', `<p>No ${path} on this store.</p>`);
+        return renderTile(r, path, search) ?? html(404, 'Not found', `<p>No ${path} on this store.</p>`);
     // Agent-only: no pages for humans beyond what UCP needs; the images stay, UCP's media point at them.
     const agentOnly = r.storefront_mode === 'agent-only';
     // Links shared while the store was hosted land on the agent page.
-    if (agentOnly && /^\/(products|categories)\/./.test(path))
+    if (agentOnly && /^(\/[a-z]{2}-[a-z]{2})?\/(products|categories)\/./.test(path))
         return { status: 302, headers: { location: '/' }, body: '' };
     if (agentOnly && path === '/')
         return html(200, r.name ?? r.org, `<p>${esc(r.name ?? r.org)} sells to shopping agents over UCP: <a href="/.well-known/ucp">/.well-known/ucp</a>.</p>`);
     // A custom storefront (an uploaded index.html) serves every path; otherwise the theme renders its routes.
     if (!agentOnly && files['index.html'] === undefined) {
-        const page = renderTheme(r, path, search);
+        const page = renderTheme(r, path, search, headers);
         if (page)
             return page;
     }
@@ -365,7 +369,7 @@ export function handleUcp(req, r) {
             return html(404, 'Not found', `<p>No ${kind} ${m[2]}.</p>`);
         return html(200, `${kind === 'order' ? `Order ${found.label}` : `Your ${kind}`}`, `<p>${kind === 'order' ? 'Thank you. ' : ''}${found.line_items.length} line item(s), ${found.currency} ${(found.totals.at(-1).amount / 100).toFixed(2)}.</p>`);
     }
-    return serveStorefront(r, path, req.url.searchParams);
+    return serveStorefront(r, path, req.url.searchParams, req.headers);
 }
 /** Lets the service read the bearer token for order authorization. */
 export function bearerOf(req) {

package/dist/bin.js

@@ -4,11 +4,11 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
-const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping']);
+const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url']);
 const argv = process.argv.slice(2);
 const flags = new Set();
 const values = {};
-/** Every value of an option given more than once (--item, --code), in order; values keeps the last. */
+/** Every value of an option given more than once (--item, --code, --category), in order; values keeps the last. */
 const lists = {};
 const set = (k, v) => {
     values[k] = v;
@@ -93,17 +93,27 @@ async function run() {
             if (sub === 'test')
                 return cmd.ordersTest(flags, values);
             if (sub === 'list')
-                return cmd.ordersList();
+                return cmd.ordersList(values, flags);
             if (sub === 'show')
                 return cmd.ordersShow(args[2]);
-            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders test`, `orders list` or `orders show <id>`.');
+            if (sub === 'approve' || sub === 'capture' || sub === 'cancel' || sub === 'refund' || sub === 'archive' || sub === 'unarchive')
+                return cmd.ordersAct(sub, args[2], values, flags);
+            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders list`, `show <number>`, `approve <number> [--capture]`, `capture`, `cancel`, `refund <number> [--amount <n>]`, `archive`, `unarchive`, or `orders test`.');
+        case 'fulfillment':
+            if (sub === 'list')
+                return cmd.fulfillmentList(values);
+            if (sub === 'show')
+                return cmd.fulfillmentShow(args[2]);
+            if (sub === 'hold' || sub === 'pick' || sub === 'pack' || sub === 'ready' || sub === 'ship' || sub === 'deliver')
+                return cmd.fulfillmentAct(sub, args[2], values);
+            throw new CliError('unknown_command', `There is no command "fulfillment ${sub ?? ''}".`, 'Use `c11r fulfillment list`, `show <shipment>`, `hold`, `pick`, `pack`, `ready`, `ship <shipment> [--carrier --tracking --tracking-url]` or `deliver`.');
         case 'ucp':
             if (sub === 'profile')
                 return cmd.ucpProfile(flags);
             if (sub === 'check')
                 return cmd.ucpCheck();
             if (sub === 'search')
-                return cmd.ucpSearch(args.slice(2).join(' '), values);
+                return cmd.ucpSearch(args.slice(2).join(' '), values, lists);
             if (sub === 'product')
                 return cmd.ucpProduct(args[2], values);
             if (sub === 'order')