@commercelayer/agent-cli 0.3.1 → 0.5.0

package/dist/store.js

@@ -5,6 +5,8 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import YAML from 'yaml';
+import { DEFAULT_LANGUAGE, ISO_639_1, PLAIN, TRANSLATED } from './languages.js';
+import { localesOf } from './locales.js';
 import { fail } from './output.js';
 import { paths } from './files.js';
 import { productFiles, readProductFile } from './products.js';
@@ -19,6 +21,10 @@ export const template = (name) => `# Commerce Layer store. This file is the stor
 # Every product needs a price in the currency of every market.
 
 name: ${name}
+# language: en       # the products' language, ISO 639-1 (default en). Other languages
+#                    # go in the products: name: { en: Ethiopia, it: Etiopia }, and the same
+#                    # for description and category; in CSV, name_it, description_it, category_it.
+#                    # The website has a page per country, in that country's language.
 
 markets:
   # One market per region you sell in. countries are ISO 3166 codes.
@@ -51,7 +57,8 @@ catalog:
   # source: sheets     # a Google Sheet published as CSV: url is its CSV link
   # source: supabase   # a Supabase table: table is its name (default products);
   #                    # C11R_SUPABASE_URL and C11R_SUPABASE_KEY in .commercelayer/credentials
-  # source: merchant   # a Google Merchant Center feed, RSS (XML) or TSV: url is the feed
+  # source: merchant   # a Google Merchant Center feed, RSS (XML) or TSV: url is the feed;
+  #                    # translations: { it: <the it feed url> } adds other languages, by id
   # url: https://...
   # table: products
 
@@ -151,12 +158,16 @@ export function loadStore() {
     }
     const theme = checkTheme(doc.theme);
     checkStorefront(doc.storefront);
+    const language = storeLanguage(doc.language);
     const currencies = [...new Set(markets.map((m) => m.currency))];
-    const products = checkProducts(sourced, currencies);
-    return { name: doc.name, markets, products, storefront: doc.storefront, policies, theme };
+    const products = checkProducts(sourced, currencies, language);
+    const languages = storeLanguages({ language, products });
+    if (languages.length > MAX_LANGUAGES)
+        fail('invalid_store', `The store has ${languages.length} languages: ${languages.join(', ')}.`, `A store has at most ${MAX_LANGUAGES} languages, the base one (${language}) included. Drop the translations of the others.`);
+    return { name: doc.name, language, markets, products, storefront: doc.storefront, policies, theme };
 }
 /** The product rules, shared by loadStore and catalog pull: errors name each product's source. */
-export function checkProducts(sourced, currencies) {
+export function checkProducts(sourced, currencies, language = DEFAULT_LANGUAGE) {
     const skus = new Map();
     const products = [];
     for (const { product: p, source } of sourced) {
@@ -177,11 +188,16 @@ export function checkProducts(sourced, currencies) {
         if (p.image_url !== undefined && !isImageRef(String(p.image_url))) {
             fail('invalid_product', `Product ${p.sku} in ${source} has image_url "${p.image_url}".`, IMAGE_HINT);
         }
-        if (p.category !== undefined) {
-            const parts = typeof p.category === 'string' ? p.category.split('>').map((c) => c.trim()) : [''];
-            if (parts.some((c) => !c))
-                fail('invalid_product', `Product ${p.sku} in ${source} has category "${p.category}".`, 'A category is a path of names from the top level, separated by " > ", such as "Coffee > Single origin". Leave it out for no category.');
-            p.category = parts.join(' > ');
+        translate(p, source, language);
+        if (p.category !== undefined)
+            p.category = categoryPath(p.category, `Product ${p.sku} in ${source} has category "${p.category}".`);
+        for (const [ll, t] of Object.entries(p.translations ?? {})) {
+            if (t.category === undefined)
+                continue;
+            t.category = categoryPath(t.category, `Product ${p.sku} in ${source} has category.${ll} "${t.category}".`);
+            const levels = (c) => c.split(' > ').length;
+            if (levels(t.category) !== levels(p.category))
+                fail('invalid_product', `Product ${p.sku} in ${source} has category.${ll} "${t.category}", with ${levels(t.category)} levels; "${p.category}" has ${levels(p.category)}.`, 'A translated category names the same levels as the base one, each translated: "Coffee > Single origin" is "Caffè > Monorigine" in it.');
         }
         for (const c of currencies) {
             const price = p.prices?.[c];
@@ -193,6 +209,60 @@ export function checkProducts(sourced, currencies) {
     }
     return products;
 }
+/** store.yml `language:`, validated: the base language, default en. */
+export function storeLanguage(raw) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_LANGUAGE;
+    const ll = String(raw);
+    if (!ISO_639_1.has(ll))
+        fail('invalid_store', `language in store.yml is "${ll}".`, 'Use the ISO 639-1 code of the language the products are written in, in lower case: en, it, fr, de, es, ... Leave it out for en.');
+    return ll;
+}
+const categoryPath = (value, message) => {
+    const parts = typeof value === 'string' ? value.split('>').map((c) => c.trim()) : [''];
+    if (parts.some((c) => !c))
+        fail('invalid_product', message, 'A category is a path of names from the top level, separated by " > ", such as "Coffee > Single origin". Leave it out for no category.');
+    return parts.join(' > ');
+};
+/**
+ * name, description and category as a string (the base language) or a { <ll>: text } map, from
+ * YAML or from name_<ll> columns: the base language's text stays on the product, the others move
+ * to translations, sorted by language.
+ */
+function translate(p, source, language) {
+    const raw = p;
+    if (raw.translations !== undefined)
+        fail('invalid_product', `Product ${p.sku} in ${source} has translations.`, 'Write the other languages in the fields themselves: name: { en: Ethiopia, it: Etiopia }, or name_it columns in CSV.');
+    const out = {};
+    for (const field of TRANSLATED) {
+        const v = raw[field];
+        if (v === undefined || v === null || typeof v !== 'object')
+            continue;
+        if (Array.isArray(v))
+            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} as a list.`, `Write ${field} as text, or as a map of language codes to text: ${field}: { ${language}: ..., it: ... }.`);
+        const map = v;
+        for (const [ll, text] of Object.entries(map)) {
+            if (ll !== PLAIN && !ISO_639_1.has(ll))
+                fail('invalid_product', `Product ${p.sku} in ${source}: ${field}.${ll} is not a language.`, 'Use ISO 639-1 codes in lower case for the languages: en, it, fr, de, es, ...');
+            if (typeof text !== 'string' && typeof text !== 'number')
+                fail('invalid_product', `Product ${p.sku} in ${source}: ${field}.${ll} is not text.`, `Write each language's ${field} as plain text.`);
+        }
+        const plain = map[PLAIN];
+        const base = map[language];
+        if (plain !== undefined && base !== undefined && String(plain) !== String(base))
+            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} and ${field}_${language} with different texts.`, `${language} is the store's base language: the plain ${field} column is its text. Keep one of the two.`);
+        const text = base ?? plain;
+        if (text === undefined || String(text).trim() === '')
+            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} in ${Object.keys(map).filter((k) => k !== PLAIN).join(', ')} but not in ${language}, the store's base language.`, `Add the ${language} text (${field}: { ${language}: ... }), or set language: in store.yml to the products' base language.`);
+        raw[field] = String(text);
+        for (const [ll, t] of Object.entries(map))
+            if (ll !== PLAIN && ll !== language && String(t).trim() !== '')
+                (out[ll] ??= {})[field] = String(t).trim();
+    }
+    const languages = Object.keys(out).sort();
+    if (languages.length)
+        p.translations = Object.fromEntries(languages.map((ll) => [ll, out[ll]]));
+}
 /** An image reference that is a file in .commercelayer/img/ (img/eth.jpg), not a URL. */
 export const isLocalImage = (url) => !/^[a-z][a-z0-9+.-]*:/i.test(url) && !url.startsWith('//');
 /** The paths the store host serves images at, as the API accepts them. */
@@ -245,8 +315,21 @@ export function toApplied(store) {
     return {
         markets: Object.fromEntries(store.markets.map((m) => [m.code, m])),
         products: Object.fromEntries(store.products.map((p) => [p.sku, p])),
+        ...(store.language !== DEFAULT_LANGUAGE && { language: store.language }),
     };
 }
+/** The store's languages: the base one first, then every language a product is translated into. */
+export const storeLanguages = (store) => [store.language, ...[...new Set(store.products.flatMap((p) => Object.keys(p.translations ?? {})))].sort()];
+/** Translations in a language no country of the store speaks: kept, but no page shows them. */
+export function languageWarnings(store) {
+    const spoken = new Set(localesOf(toApplied(store)).map((l) => l.language));
+    return storeLanguages(store)
+        .slice(1)
+        .filter((ll) => !spoken.has(ll))
+        .map((ll) => `Products are translated into ${ll}, which no country of the store speaks (${[...spoken].join(', ') || 'none'}): no page shows it, but shopping agents can ask for it over UCP.`);
+}
+/** At most this many languages, base included: the API's limit. */
+export const MAX_LANGUAGES = 6;
 /** JSON with sorted keys and no undefined values, so key order never reads as a change. */
 export const canonical = (v) => JSON.stringify(v ?? {}, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x));
 /** The one definition of "pending changes": what apply would do. plan and status both use it. */
@@ -273,6 +356,9 @@ export function diff(state, desired) {
     if (!applied ? storefrontMode(desired) !== 'hosted' : state.storefront_mode !== undefined && (state.storefront_mode ?? 'hosted') !== storefrontMode(desired)) {
         changes.push({ action: 'update', type: 'store', id: 'storefront_mode' });
     }
+    // The base language: a change from what is applied (en before the first apply, and when absent).
+    if ((applied?.language ?? DEFAULT_LANGUAGE) !== desired.language)
+        changes.push({ action: 'update', type: 'store', id: 'language' });
     const after = toApplied(desired);
     for (const kind of ['markets', 'products']) {
         const type = kind.slice(0, -1);

package/dist/ucp/shop.js

@@ -53,6 +53,23 @@ export function money(amount, currency) {
     return { amount, currency, major, display: `${amount < 0 ? '-' : ''}${currency} ${Math.abs(major).toFixed(decimals)}` };
 }
 const plain = (d) => d?.plain ?? d?.markdown ?? d?.html;
+/** How a variant ships, from fulfillment.methods[0]: where to, the first option's price and arrival, and whether it ships to the country asked. */
+function shippingView(m, currency) {
+    if (!m)
+        return undefined;
+    const o = m.options?.[0];
+    const amount = o?.totals?.find((t) => t.type === 'fulfillment' || t.type === 'total')?.amount;
+    const view = {
+        to: m.ships_to,
+        option: o?.title,
+        price: amount !== undefined && currency ? money(amount, currency) : undefined,
+        earliest: o?.earliest_fulfillment_time,
+        latest: o?.latest_fulfillment_time,
+        // Only when a country was asked (--country): false when the store does not ship there.
+        ships_to_country: m.destination ? m.destination.ships !== false : undefined,
+    };
+    return Object.values(view).some((x) => x !== undefined) ? Object.fromEntries(Object.entries(view).filter(([, x]) => x !== undefined)) : undefined;
+}
 function variantView(v) {
     const shipping = v.fulfillment?.methods?.map((m) => plain(m.description)).filter(Boolean).join('; ');
     return {
@@ -60,10 +77,13 @@ function variantView(v) {
         sku: v.sku,
         title: v.title,
         price: v.price ? money(v.price.amount, v.price.currency) : undefined,
+        // The price before a sale, when the store shows one.
+        list_price: v.list_price && v.list_price.amount !== v.price?.amount ? money(v.list_price.amount, v.list_price.currency) : undefined,
         available: v.availability?.available ?? undefined,
         availability: v.availability?.status ?? undefined,
         image_url: v.media?.find((m) => m.type === 'image')?.url,
         ships: shipping || undefined,
+        shipping: shippingView(v.fulfillment?.methods?.[0], v.price?.currency),
     };
 }
 export function productView(p, full = false) {
@@ -76,6 +96,10 @@ export function productView(p, full = false) {
         description: full || !description || description.length <= 200 ? description : `${description.slice(0, 197)}...`,
         url: p.url,
         image_url: image,
+        categories: p.categories?.length ? p.categories.map((c) => c.value) : undefined,
+        // A text search ranks products with every word first; partial marks one with only some of them.
+        partial: p.metadata?.search?.all_words === false || undefined,
+        matched_on: p.metadata?.search?.matched_on,
         // A search lists a variant's image only when it is not the product's.
         variants: full ? variants : variants.map((v) => ({ ...v, image_url: v.image_url === image ? undefined : v.image_url })),
     };
@@ -176,17 +200,40 @@ export async function open(origin) {
         fail('checkout_unsupported', `The store at ${origin} does not offer UCP checkout to this CLI.`, 'It can only be browsed: give the human the store URL to buy there.');
     return store;
 }
-export async function search(origin, query, country) {
+export async function search(origin, query, f = {}) {
     const store = await discover(origin);
-    const body = { query, pagination: { limit: 50 } };
-    if (country)
-        body.context = { address_country: country.toUpperCase() };
+    const body = { pagination: { limit: 50 } };
+    if (query)
+        body.query = query;
+    if (f.country)
+        body.context = { address_country: f.country.toUpperCase() };
+    const filters = {};
+    if (f.categories?.length)
+        filters.categories = f.categories;
+    if (f.min !== undefined || f.max !== undefined) {
+        // filters.price is in minor units of context.currency: ask the store which currency it prices in here.
+        const probe = await step(origin, () => shopping.search(store, { ...body, ...(f.categories?.length ? { filters } : {}), pagination: { limit: 1 } }));
+        const currency = probe.body.products?.[0]?.variants?.[0]?.price?.currency;
+        if (currency) {
+            body.context = { ...body.context, currency };
+            filters.price = { ...(f.min !== undefined ? { min: Math.round(f.min * minorUnits(currency)) } : {}), ...(f.max !== undefined ? { max: Math.round(f.max * minorUnits(currency)) } : {}) };
+        }
+    }
+    if (Object.keys(filters).length)
+        body.filters = filters;
     const call = await step(origin, () => shopping.search(store, body));
     const r = call.body;
-    const products = r.products ?? [];
+    let products = r.products ?? [];
+    // A store that ignores filters.price still gets the bounds applied here.
+    if (filters.price)
+        products = products.filter((p) => (p.variants ?? []).some((v) => v.price && (filters.price.min === undefined || v.price.amount >= filters.price.min) && (filters.price.max === undefined || v.price.amount <= filters.price.max)));
+    // Which market, currency and countries the prices are for: the store says it per variant, the same for all.
+    const prices = products.flatMap((p) => p.variants ?? []).find((v) => v.metadata?.prices)?.metadata.prices;
     return {
         store: origin,
         query,
+        prices: prices ? { market: prices.market, market_name: prices.market_name, currency: prices.currency, countries: prices.countries, tax_included: prices.tax_included } : undefined,
+        filters: Object.keys(filters).length ? { categories: filters.categories, min_price: f.min, max_price: f.max, currency: body.context?.currency } : undefined,
         count: products.length,
         total_count: r.pagination?.total_count,
         has_more: r.pagination?.has_next_page || undefined,
@@ -224,7 +271,7 @@ export async function updateCheckout(origin, id, ch) {
     const store = await open(origin);
     const current = (await step(origin, () => shopping.getCheckout(store, id))).body;
     if (current.status === 'completed' || current.status === 'canceled')
-        fail('checkout_closed', `The checkout ${id} is ${current.status}.`, current.status === 'completed' ? `It is paid: c11r ucp order ${current.order?.id ?? '<id>'}.` : 'Open a new one: c11r ucp checkout create --item <sku>.');
+        fail('checkout_closed', `The checkout ${id} is ${current.status}.`, current.status === 'completed' ? `It is an order now: c11r ucp order ${current.order?.id ?? '<id>'}.` : 'Open a new one: c11r ucp checkout create --item <sku>.');
     const body = replay(current);
     if (ch.buyer)
         body.buyer = clean({ ...(current.buyer ?? {}), ...ch.buyer });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [