@commercelayer/agent-cli 0.3.0 → 0.5.0

package/dist/store.js

@@ -5,18 +5,26 @@
 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';
 /** The keys a product may have. Stock is not one: inventory lives in Commerce Layer. */
 export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'category', 'prices'];
-export const THEME_KEYS = ['color', 'logo', 'hero', 'tagline'];
+export const THEME_KEYS = ['color', 'logo', 'hero', 'tagline', 'badge'];
+export const STOREFRONT_MODES = ['hosted', 'agent-only'];
+export const storefrontMode = (s) => s.storefront?.mode ?? 'hosted';
 export const template = (name) => `# Commerce Layer store. This file is the store: edit it, then run
 #   c11r plan    to see what will change
 #   c11r apply   to make the change
 # 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.
@@ -49,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
 
@@ -60,8 +69,12 @@ theme:
   # logo: img/logo.svg   # or an https:// URL; without it the name is the logo
   # hero: img/hero.jpg   # the home page's wide image; without it a band in the accent
   # tagline: Small-batch coffee, roasted in Milan   # at most 120 characters
+  # badge: Demo          # a short label next to the logo, at most 20 characters
 
 storefront:
+  # mode: hosted       # hosted (default): the website for humans, and UCP for agents.
+  #                    # agent-only: the store host serves only UCP and the pages it
+  #                    # needs (checkout, order, policy pages), no catalog pages.
   # Only for a custom storefront (your own web app in this repo, published with
   # c11r storefront publish): it replaces the theme. Its folder, from the repo root.
   # path: storefront
@@ -144,12 +157,17 @@ export function loadStore() {
             fail('invalid_store', `policies.${key} is not a URL.`, 'Policy entries are full URLs starting with https://, or left out to use the default sandbox pages.');
     }
     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) {
@@ -170,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];
@@ -186,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. */
@@ -193,12 +270,28 @@ export const IMAGE_PATH = /^img\/[A-Za-z0-9._-][A-Za-z0-9._/-]*\.(png|jpg|jpeg|w
 /** image_url, logo, hero: an https URL, or img/<file> for a file in .commercelayer/img/. */
 export const isImageRef = (url) => isLocalImage(url) ? IMAGE_PATH.test(url) && !url.includes('..') && !url.includes('//') : /^https?:\/\/\S+$/.test(url);
 const IMAGE_HINT = 'Use a full https:// URL, or img/<file> for a file in .commercelayer/img/ (letters, digits, . _ - and /; extension png, jpg, jpeg, webp, gif, avif or svg, in lowercase).';
+/** The storefront block of store.yml: path, and mode hosted or agent-only. */
+function checkStorefront(raw) {
+    if (raw === undefined || raw === null)
+        return;
+    const hint = 'Write `storefront:` with `mode: hosted` (the default) or `mode: agent-only`, and `path:` for a custom storefront. See the comments in store.yml.';
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        fail('invalid_storefront', 'storefront in store.yml is not a mapping.', hint);
+    const s = raw;
+    const unknown = Object.keys(s).filter((k) => !['mode', 'path'].includes(k));
+    if (unknown.length)
+        fail('invalid_storefront', `storefront in store.yml has ${unknown.join(', ')}, which it does not take.`, hint);
+    if (s.mode !== undefined && s.mode !== null && !STOREFRONT_MODES.includes(s.mode))
+        fail('invalid_storefront', `storefront.mode is "${String(s.mode)}".`, 'Use hosted (a website for humans, and UCP) or agent-only (UCP and the pages it needs, no catalog pages).');
+    if (s.path !== undefined && s.path !== null && typeof s.path !== 'string')
+        fail('invalid_storefront', 'storefront.path is not a folder name.', hint);
+}
 /** The theme block of store.yml, validated: the theme would ignore bad values, so say so here. */
 function checkTheme(raw) {
     if (raw === undefined || raw === null)
         return undefined;
     if (typeof raw !== 'object' || Array.isArray(raw))
-        fail('invalid_theme', 'theme in store.yml is not a mapping.', 'Write `theme:` with color, logo, hero and tagline under it, each optional. See the comments in store.yml.');
+        fail('invalid_theme', 'theme in store.yml is not a mapping.', 'Write `theme:` with color, logo, hero, tagline and badge under it, each optional. See the comments in store.yml.');
     const t = raw;
     const unknown = Object.keys(t).filter((k) => !THEME_KEYS.includes(k));
     if (unknown.length)
@@ -214,14 +307,29 @@ function checkTheme(raw) {
             fail('invalid_theme', `theme.${k} is "${theme[k]}".`, IMAGE_HINT);
     if (theme.tagline !== undefined && (theme.tagline.length > 120 || /[\r\n<>]/.test(theme.tagline)))
         fail('invalid_theme', `theme.tagline is ${theme.tagline.length > 120 ? `${theme.tagline.length} characters long` : 'not plain text on one line'}.`, 'Write the tagline as one line of plain text, at most 120 characters.');
+    if (theme.badge !== undefined && (theme.badge.length > 20 || !theme.badge.trim() || /[\r\n<>]/.test(theme.badge)))
+        fail('invalid_theme', `theme.badge is ${theme.badge.length > 20 ? `${theme.badge.length} characters long` : `"${theme.badge}"`}.`, 'Use a short plain-text label of at most 20 characters, such as Demo, with no line breaks or < >.');
     return theme;
 }
 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. */
@@ -244,6 +352,13 @@ export function diff(state, desired) {
         else if (hasTheme(before) && canonical(before) !== canonical(desired.theme))
             changes.push({ action: 'update', type: 'store', id: 'theme' });
     }
+    // The mode: a change from what the API holds (hosted before the first apply). An API that does not know it is skipped.
+    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,17 +53,37 @@ 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 {
         id: v.id,
-        sku: v.sku ?? v.id,
+        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 })),
     };
@@ -102,7 +126,7 @@ export function checkoutView(ck, origin, call) {
         currency: cur,
         line_items: (ck.line_items ?? []).map((l) => ({
             id: l.id,
-            sku: l.item?.id,
+            item_id: l.item?.id,
             title: l.item?.title,
             quantity: l.quantity,
             unit_price: l.item?.price === undefined ? undefined : money(l.item.price, cur),
@@ -134,7 +158,7 @@ export function orderView(o, origin, call) {
         checkout_id: o.checkout_id,
         currency: cur,
         line_items: (o.line_items ?? []).map((l) => ({
-            sku: l.item?.id,
+            item_id: l.item?.id,
             title: l.item?.title,
             quantity: l.quantity?.total ?? l.quantity,
             status: l.status,
@@ -160,15 +184,15 @@ async function step(origin, run) {
             fail('not_found', e.message, `The store at ${origin} does not know it. Check the id, or pass --store <the store it was made at>.`);
         if (code === 'identity_required' || e.call.status === 401)
             fail('identity_required', e.message, 'Orders are readable by the platform that placed them: this CLI can only read orders it placed.');
-        fail('ucp_error', e.message, `The store at ${origin} refused it: tell the human what it said. The skus it sells are in c11r ucp search.`);
+        fail('ucp_error', e.message, `The store at ${origin} refused it: tell the human what it said. The variant ids it sells are in c11r ucp search.`);
     }
 }
-/** --item SKU or SKU:QTY. */
+/** --item ID or ID:QTY, the variant id. */
 export function parseItem(raw) {
     const m = String(raw).match(/^(.+?)(?::(\d+))?$/);
     if (!m || !m[1].trim())
-        fail('invalid_argument', `--item ${raw} is not SKU or SKU:QUANTITY.`, 'Example: --item ETH-250:2 (quantity 1 when left out, 0 to remove it in checkout update).');
-    return { sku: m[1].trim(), quantity: m[2] === undefined ? 1 : Number(m[2]) };
+        fail('invalid_argument', `--item ${raw} is not ID or ID:QUANTITY.`, 'Use a variant id from c11r ucp search (variants[].id), for example --item ETH-250:2; quantity 1 when left out, 0 removes it in checkout update.');
+    return { id: m[1].trim(), quantity: m[2] === undefined ? 1 : Number(m[2]) };
 }
 export async function open(origin) {
     const store = await discover(origin);
@@ -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,
@@ -205,7 +252,7 @@ export async function product(origin, id, country) {
 }
 export async function createCheckout(origin, items, codes, country) {
     const store = await open(origin);
-    const body = { line_items: items.map((l) => ({ item: { id: l.sku }, quantity: l.quantity })) };
+    const body = { line_items: items.map((l) => ({ item: { id: l.id }, quantity: l.quantity })) };
     if (country)
         body.context = { address_country: country.toUpperCase() };
     if (codes.length)
@@ -224,12 +271,12 @@ 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 });
     for (const l of ch.items ?? []) {
-        const i = body.line_items.findIndex((x) => x.item.id === l.sku);
+        const i = body.line_items.findIndex((x) => x.item.id === l.id);
         if (l.quantity === 0) {
             if (i >= 0)
                 body.line_items.splice(i, 1);
@@ -237,7 +284,7 @@ export async function updateCheckout(origin, id, ch) {
         else if (i >= 0)
             body.line_items[i].quantity = l.quantity;
         else
-            body.line_items.push({ item: { id: l.sku }, quantity: l.quantity });
+            body.line_items.push({ item: { id: l.id }, quantity: l.quantity });
     }
     if (!body.line_items.length)
         fail('invalid_argument', 'The update leaves the checkout with no items.', `Keep at least one item, or cancel it: c11r ucp checkout cancel ${id}.`);
@@ -268,8 +315,8 @@ export async function updateCheckout(origin, id, ch) {
         again.fulfillment.methods[0].groups[0].selected_option_id = group.options[0].id;
         call = await step(origin, () => shopping.updateCheckout(store, id, again));
     }
-    // A store can answer ready_for_complete before the shipping is in the totals (seen once on a
-    // Commerce Layer store): read it again rather than show the human a total without shipping.
+    // A store can answer ready_for_complete before the shipping is in the totals (seen once, since
+    // fixed on the store host): read it again rather than show the human a total without shipping.
     const ck = call.body;
     if (ck.status === 'ready_for_complete' && ck.fulfillment?.methods?.[0]?.groups?.[0]?.selected_option_id && !(ck.totals ?? []).some((t) => t.type === 'fulfillment')) {
         call = await step(origin, () => shopping.getCheckout(store, id));
@@ -285,7 +332,7 @@ export async function completeCheckout(origin, id, decline) {
     const store = await open(origin);
     if (!store.profile.ucp?.payment_handlers?.[SANDBOX_HANDLER]) {
         const handlers = Object.keys(store.profile.ucp?.payment_handlers ?? {});
-        fail('payment_handler_unsupported', `The store at ${origin} takes ${handlers.length ? handlers.join(', ') : 'no payment handler this CLI knows'}; this CLI can only pay sandbox stores (${SANDBOX_HANDLER}) today.`, `Give the human the checkout's continue_url to pay there: c11r ucp checkout show ${id}.`);
+        fail('payment_handler_unsupported', `The store at ${origin} takes ${handlers.length ? handlers.join(', ') : 'no payment handler this CLI knows'}; this CLI pays only with the ${SANDBOX_HANDLER} test handler today.`, `Give the human the checkout's continue_url to pay there: c11r ucp checkout show ${id}.`);
     }
     const call = await step(origin, () => shopping.completeCheckout(store, id, { payment: { instruments: [sandboxInstrument(decline)] }, signals: { 'dev.ucp.user_agent': 'c11r' } }));
     const ck = call.body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.3.0",
+  "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": [