@commercelayer/agent-cli 0.2.3 → 0.3.0

package/README.md

@@ -18,16 +18,24 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, images, and the store's name, policies and theme. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
 | `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused. While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
 | `catalog pull` | Read the products from the catalog source in `store.yml` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
-| `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image get a neutral tile. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
+| `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image show the tile the store host draws for them, at `/tiles/<sku>.svg`. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
 | `storefront publish` | Custom storefronts only. Upload the folder at `storefront.path` (default `storefront`) to the store host, where it replaces the hosted theme, leaving out dotfiles. `/img/` on the store host is always the store's images, so files under the folder's `img/` are not served: publish lists them as `not_served`. |
 | `storefront check` | Custom storefronts only. Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
 | `promotions list` · `show <id>` | The store's promotions, live in Commerce Layer: id, name, status, rules, actions, uses, dates; `managed: false` for ones made in the dashboard. |
 | `promotions create` · `update <id>` | Create a promotion, or replace one, from a spec in YAML or JSON on stdin or `-f <file>` (see [Promotions](#promotions)). Prints the promotion and the `orders test` call that checks it. |
 | `promotions enable <id>` · `disable <id>` · `delete <id>` | Turn a promotion on or off, or delete it (ask the human first). |
+| `links list` · `show <id>` | The store's links, live in Commerce Layer: url, id, name, status, what it sells, markets, dates; `managed: false` for ones made in the dashboard. |
+| `links create` | Create a shareable link to a microstore (sku, skus or category) or an order's checkout, from a spec in YAML or JSON on stdin or `-f <file>` (see [Links](#links)). Prints the link, `url` first. |
+| `links enable <id>` · `disable <id>` · `delete <id>` | Turn a link on or off, or delete it (ask the human first). |
 | `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order, the `discounts` applied (promotions and codes, in minor units like the totals) and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
 | `orders show <id or number>` | One order. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
+| `ucp search [<query>] [--country <CC>]` · `ucp product <id>` | Buy for the human, step by step (see [Buying for the human](#buying-for-the-human)): the store's products, prices in major units in `price.display`. |
+| `ucp checkout create --item <sku>[:<qty>] … [--code <discount>] [--country <CC>]` | Open a checkout; `messages` say what is still missing (email, shipping address). |
+| `ucp checkout update <id> [--email …] [--street …] [--item <sku>:<qty>] [--code …] [--shipping <option>]` | Give the buyer's details (flags, or YAML or JSON on stdin or `-f`), change items or codes; `ready_for_complete` once nothing is missing, with shipping in the total. |
+| `ucp checkout show <id>` · `cancel <id>` · `complete <id> [--decline]` | Read, cancel, or pay a checkout with the sandbox handler (after the human said yes): `order` has `label` and `permalink_url`. |
+| `ucp order <id>` · `ucp ask "<question>"` | Read an order the CLI placed; ask the store a question. Every `ucp` buying command takes `--store <host>` to buy from any UCP store. |
 | `ucp check` | Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way (the output says which). Exits 1 on a failed check. |
 | `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the UCP profile URL. |
 | `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
@@ -86,6 +94,17 @@ Optional: `market` (a market code; without it, every market), `starts` and `ends
 
 `list` and `show` print each promotion in the normalized form plus `status` (`active`, `scheduled`, `expired`, `disabled`, `used_up`) and `uses`; that output can be edited and sent back to `update`. Promotions made outside c11r (the dashboard, the sandbox's `SANDBOX10`) are listed with `managed: false` and Commerce Layer's id: `enable`, `disable` and `delete` work on them, `update` answers `promotion_not_managed`. `percentage` is a whole number from 1 to 100; a promotion takes at most 20 codes, a free gift at most 25 SKUs. More than 10 active promotion actions without a coupon gives a `warnings` entry (Commerce Layer applies 10). `orders test --code <CODE>` proves one: its `discounts` lists what was taken off, automatic promotions with `automatic: true`, and a code that applied nothing is a `discount_code_invalid` warning in `messages`.
 
+### Links
+Links are live settings in Commerce Layer too, never store files: shareable URLs that open a hosted microstore for one sku, a set of skus or a category, or the hosted checkout for an order. A spec, in YAML or JSON on stdin or with `-f <file>`:
+
+```yaml
+id: single-origins       # the handle: lowercase letters, digits, dashes; unique
+name: Single origins
+for: { category: Coffee > Single origin }   # or { sku: ETH }, { skus: [ETH, COL] }, { order: 1001 | cart_... }
+```
+
+Optional: `market` (a code or a list; without it, every market; an order link takes the order's market and none), `starts` (default now) and `ends` (default a month after `starts`; a day, or a UTC time; a bare `ends` day runs to 23:59:59Z), `params` (names to plain values, added to the URL). A category becomes the skus of its products in store.yml when the command runs; a link sells at most 100 skus. An order link opens the checkout of a draft or pending order: its number, or the id of a UCP cart or checkout (`cart_...`, `chk_...`), read back as the order's number. A placed order opens its thank-you page, so `create` refuses it. Commerce Layer opens a link in one market, so a link has a URL per market: `urls`, by market code, and `url`, the first market's. `create`, `list` and `show` print `url` and `urls` first, then the spec, `status` (`pending`, `active`, `expired`, `disabled`: the first market's; enable and disable act on every market) and `created_at`. A disabled or pending link opens Commerce Layer's not-found page; checkout takes the sandbox's manual payment (wire transfer) unless a gateway is added. A link cannot change: delete it and create it again (what `show` prints can be sent back to `create`). Links made outside c11r are listed with `managed: false` and Commerce Layer's id, and may sell `for: { sku_list: <name> }`; `enable`, `disable` and `delete` work on them.
+
 ### The products folder
 Beyond a handful of products, put the catalog in `.commercelayer/products/` and leave `products` out of `store.yml`. Every file in the folder is merged into the catalog by sku, in file-name order:
 - `<name>.yml`: a list of products in the shape above (one file per collection, or one per product, as you like).
@@ -117,7 +136,7 @@ One rule for images: `img/<file>` anywhere in `store.yml` (product `image_url`,
 
 A custom storefront replaces the theme: `storefront.path` in `store.yml` names its folder, `storefront init` writes a drop-in.js scaffold, `storefront publish` uploads it, `storefront check` checks it. Its pages link product images at `/img/`; its own files (fonts, icons, styles) go in `assets/`, not `img/`.
 
-Error codes: `invalid_theme`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
+Error codes: `invalid_theme`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `invalid_link`, `link_exists`, `link_not_managed` (reserved), `links_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
 | What | Where |
@@ -132,6 +151,10 @@ Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (liv
 | Pages | `/policies/{privacy,terms,returns}` (defaults when `store.yml` has no `policies`), `/carts/{id}`, `/checkout-sessions/{id}` (`continue_url`), `/orders/{id}` (`permalink_url`), and the published storefront at `/`. |
 Transport rules the store enforces: `UCP-Agent` (an HTTPS platform profile URL) and `Request-Id` on every request; `Idempotency-Key` on every state change, replayed when the body matches and `409` when it does not; `Content-Digest` verified when present. Every service response carries `Content-Digest`, `Signature-Input` and `Signature` (ES256 over `@status`, `content-digest`, `content-type`, key `kid` from the profile). Orders are private: readable by the platform that placed them or with a buyer token carrying an order scope; anything else gets `401` with `WWW-Authenticate: Bearer`. Catalog ids are the skus (`product.id` is `prod_<sku>`, `variant.id` is the sku); amounts are integers in minor units.
 The CLI is a UCP **platform**: its profile is served at `https://commercelayer.ai/ucp/agent-cli/profile.json` (`ucp profile --agent` prints it) and goes in `UCP-Agent` on every call. The store negotiates the capability intersection with it. `orders test` is the buyer; `ucp check` runs 30-odd checks across profile, transport rules, catalog, cart, discount, checkout, fulfillment, consent, payment, signatures, idempotency, order, identity linking, ask and permalink.
+### Buying for the human
+
+An agent can buy from any UCP store on behalf of its human, one step per command, talking to the human in between: `ucp search` to show the products, `ucp checkout create --item <sku>:<qty>` for what they picked, `ucp checkout update <id>` with the email and shipping address they give (never invented), then, once they said yes to the total, `ucp checkout complete <id>`, and the order's `label` and `permalink_url` back to them. Money comes as `{ amount, currency, major, display }`: `amount` in minor units as UCP has it, `display` for the human. The store is `--store <hostname or origin>`, or this folder's store when there is one; checkout and order ids are remembered with their store (in `~/.local/state/c11r/ucp.json`), so later steps need no `--store`. Paying needs the store's sandbox handler (`ai.commercelayer.sandbox`, test payments only): a store with a real gateway answers `payment_handler_unsupported`, and the human pays at the checkout's `continue_url`. Responses are signature-checked like `orders test`: `signature` is `verified`, `invalid`, `unknown_key` or `unsigned`.
+
 ## Requirements
 
 Node 20 or later. One runtime dependency (`yaml`).

package/dist/api/client.js

@@ -27,39 +27,47 @@ export function createApi(auth) {
             fail(err.code, err.message, err.hint);
         fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
     };
-    // Promotions: on an API older than them, the collection route is an unknown route (404 not_found).
-    const promotions = () => `${org()}/promotions`;
-    const one = (id) => `${promotions()}/${encodeURIComponent(id)}`;
-    const unsupported = async (call) => {
+    // Promotions and links: on an API older than them, the collection route is an unknown route (404 not_found).
+    const collection = (kind) => `${org()}/${kind}`;
+    const one = (kind, id) => `${collection(kind)}/${encodeURIComponent(id)}`;
+    const unsupported = async (kind, call) => {
         try {
             return await call;
         }
         catch (e) {
             if (e instanceof CliError && (e.code === 'not_found' || (e.code === 'api_error' && /\b404\b/.test(e.message))))
-                fail('promotions_unsupported', 'This API does not manage promotions yet.', 'Try again later; tell the human if it persists.');
+                fail(`${kind}_unsupported`, `This API does not manage ${kind} yet.`, 'Try again later; tell the human if it persists.');
             throw e;
         }
     };
-    const found = async (id, call) => {
+    const found = async (kind, id, call) => {
         try {
             return await call;
         }
         catch (e) {
             if (e instanceof CliError && e.code === 'not_found')
-                fail('not_found', `There is no promotion ${id}.`, 'Run `c11r promotions list` for the ids, or `c11r promotions create` to make it.');
+                fail('not_found', `There is no ${kind.slice(0, -1)} ${id}.`, `Run \`c11r ${kind} list\` for the ids, or \`c11r ${kind} create\` to make it.`);
             throw e;
         }
     };
     return {
-        listPromotions: () => unsupported(request('GET', promotions())),
-        createPromotion: (spec) => unsupported(request('POST', promotions(), spec)),
-        getPromotion: (id) => found(id, request('GET', one(id))),
-        updatePromotion: (id, spec) => found(id, request('PUT', one(id), spec)),
-        setPromotionEnabled: (id, enabled) => found(id, request('POST', `${one(id)}/${enabled ? 'enable' : 'disable'}`)),
+        listPromotions: () => unsupported('promotions', request('GET', collection('promotions'))),
+        createPromotion: (spec) => unsupported('promotions', request('POST', collection('promotions'), spec)),
+        getPromotion: (id) => found('promotions', id, request('GET', one('promotions', id))),
+        updatePromotion: (id, spec) => found('promotions', id, request('PUT', one('promotions', id), spec)),
+        setPromotionEnabled: (id, enabled) => found('promotions', id, request('POST', `${one('promotions', id)}/${enabled ? 'enable' : 'disable'}`)),
         deletePromotion: async (id) => {
-            await found(id, request('DELETE', one(id)));
+            await found('promotions', id, request('DELETE', one('promotions', id)));
         },
-        createSandbox: (name) => request('POST', '/sandboxes', { name }),
+        listLinks: () => unsupported('links', request('GET', collection('links'))),
+        createLink: (spec) => unsupported('links', request('POST', collection('links'), spec)),
+        getLink: (id) => found('links', id, request('GET', one('links', id))),
+        setLinkEnabled: (id, enabled) => found('links', id, request('POST', `${one('links', id)}/${enabled ? 'enable' : 'disable'}`)),
+        deleteLink: async (id) => {
+            await found('links', id, request('DELETE', one('links', id)));
+        },
+        // C11R_TEST=1 (our own test runs) asks the API to tag the organization as a test.
+        createSandbox: (name) => request('POST', '/sandboxes', process.env.C11R_TEST === '1' ? { name, test: true } : { name }),
         getStore: () => request('GET', org()),
         applyStore: (body) => request('PUT', `${org()}/resources`, body),
         uploadAssets: (files) => request('PUT', `${org()}/assets`, { files }),

package/dist/api/stub/management.js

@@ -59,13 +59,60 @@ function unknownSkus(r, spec) {
     }
     return undefined;
 }
+/** As the API lists it: the spec plus the first market's url, every url, and status. */
+function listedLink(l) {
+    const { enabled, urls, ...link } = l;
+    const now = Date.now();
+    const status = !enabled ? 'disabled' : Date.parse(l.ends) <= now ? 'expired' : Date.parse(l.starts) > now ? 'pending' : 'active';
+    return { ...link, url: Object.values(urls)[0], urls, status, managed: true };
+}
+/** The API checks a link against the store: applied skus and markets, draft orders. Answers the markets it gets a link in. */
+function linkMarkets(r, spec) {
+    const known = r.applied?.products ?? {};
+    const f = spec.for;
+    const list = 'sku' in f ? [['for.sku', f.sku]] : 'skus' in f ? f.skus.map((s, i) => [`for.skus[${i}]`, s]) : [];
+    for (const [path, sku] of list)
+        if (!(sku in known))
+            return error(422, 'invalid_link', `${path}: unknown sku ${sku}.`, 'Use skus of applied products: run `c11r apply` first if you just added them.');
+    if ('order' in f) {
+        if (spec.markets)
+            return error(422, 'invalid_link', "markets: an order link uses the order's market.", 'Leave markets out.');
+        // A UCP cart or checkout id names the draft order behind it, read back as its number (the stub's: the id's suffix).
+        const cart = /^cart_/.test(f.order) ? r.ucp.carts[f.order] : undefined;
+        // A cart is the same order as the checkout made from it.
+        const ucp = cart ? (Object.values(r.ucp.checkouts).find((c) => c._cart_id === f.order && c.status === 'completed') ?? cart) : /^chk_/.test(f.order) ? r.ucp.checkouts[f.order] : undefined;
+        if (ucp) {
+            const placed = ucp.order?.label;
+            if (ucp.status === 'completed' && placed)
+                return error(422, 'invalid_link', `for.order: order ${placed.replace(/^#/, '')} is placed: a link opens the checkout of a draft or pending order.`, 'Link a cart or checkout that is not completed.');
+            if (ucp.status === 'canceled')
+                return error(422, 'invalid_link', `for.order: no order ${f.order}.`, 'The checkout is canceled: link another cart or checkout.');
+            const market = Object.values(r.applied?.markets ?? {}).find((m) => m.currency === ucp.currency)?.code ?? Object.keys(r.applied?.markets ?? {})[0];
+            spec.for = { order: f.order.replace(/^(cart|chk)_/, '') };
+            return [market];
+        }
+        const draft = r.draft_orders?.[f.order];
+        if (draft)
+            return [draft.market];
+        if (publicOrders(r).some((o) => o.label.replace(/^#/, '') === f.order))
+            return error(422, 'invalid_link', `for.order: order ${f.order} is placed: a link opens the checkout of a draft or pending order.`, 'A placed order opens its thank-you page, not a checkout: link a draft or pending order.');
+        return error(422, 'invalid_link', `for.order: no order ${f.order}.`, 'Use the number of a draft or pending order in the store.');
+    }
+    const applied = Object.keys(r.applied?.markets ?? {});
+    const markets = spec.markets ?? applied;
+    const i = markets.findIndex((m) => !applied.includes(m));
+    if (i >= 0)
+        return error(422, 'invalid_link', `markets[${i}]: unknown market ${markets[i]}.`, 'Use markets that are applied: run `c11r apply` first if you just added it.');
+    return markets;
+}
 export function handleManagement(req) {
     const db = readDb();
     const path = req.url.pathname;
     if (req.method === 'POST' && path === '/sandboxes') {
         // Like Commerce Layer: the organization is named `name`, and its slug is derived
         // from it, suffixed -2, -3, ... when taken. The slug is the org and the store host.
-        const name = String(readJson(req)?.name ?? 'store');
+        const body = readJson(req);
+        const name = String(body?.name ?? 'store');
         const base = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'store';
         let slug = base;
         for (let n = 2; db[slug]; n++)
@@ -78,6 +125,7 @@ export function handleManagement(req) {
             org: slug,
             token: `sbx_${crypto.randomBytes(16).toString('hex')}`,
             sandbox: true,
+            ...(body?.test === true ? { test: true } : {}),
             claimed: false,
             claim_url: `https://commercelayer.ai/claim/${crypto.randomBytes(6).toString('hex')}`,
             expires_at: expires.toISOString(),
@@ -211,6 +259,48 @@ export function handleManagement(req) {
             }
         }
     }
+    // Links: live, synchronous, keyed by id; one Commerce Layer link per market.
+    if (rest === '/links' || rest.startsWith('/links/')) {
+        const store = (record.links ??= {});
+        const [, , rawId, verb] = rest.split('/');
+        const id = rawId === undefined ? undefined : decodeURIComponent(rawId);
+        const save = () => writeDb(db);
+        if (id === undefined) {
+            if (req.method === 'GET')
+                return json(200, { links: Object.keys(store).sort().map((k) => listedLink(store[k])) });
+            if (req.method === 'POST') {
+                const spec = readJson(req);
+                if (store[spec.id])
+                    return error(409, 'link_exists', `There is already a link ${spec.id}.`, 'Pick another id, or delete the link and create it again.');
+                const markets = linkMarkets(record, spec);
+                if (!Array.isArray(markets))
+                    return markets;
+                // One Commerce Layer link per market: a scope with several markets does not open.
+                const urls = Object.fromEntries(markets.map((m) => [m, `https://c11.page/${crypto.randomBytes(6).toString('base64url')}`]));
+                // An order link reads back with the order's market.
+                store[spec.id] = { ...spec, markets, urls, enabled: true, created_at: new Date().toISOString() };
+                save();
+                return json(201, listedLink(store[spec.id]));
+            }
+        }
+        else {
+            const l = store[id];
+            if (!l)
+                return error(404, 'not_found', `There is no link ${id}.`, 'Run `c11r links list`.');
+            if (verb === undefined && req.method === 'GET')
+                return json(200, listedLink(l));
+            if (verb === undefined && req.method === 'DELETE') {
+                delete store[id];
+                save();
+                return { status: 204, headers: {}, body: '' };
+            }
+            if ((verb === 'enable' || verb === 'disable') && req.method === 'POST') {
+                l.enabled = verb === 'enable';
+                save();
+                return json(200, listedLink(l));
+            }
+        }
+    }
     if (req.method === 'PUT' && rest === '/assets') {
         const { files } = readJson(req);
         let total = 0;

package/dist/api/stub/shopping.js

@@ -86,8 +86,9 @@ 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. */
-const imageUrl = (ctx, url) => new URL(url, `${ctx.origin}/`).href;
+/** 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 price = { amount: toMinor(p.prices[market.currency], market.currency), currency: market.currency };
     const v = {
@@ -100,8 +101,7 @@ function variant(ctx, p, market) {
         // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
         availability: { available: true, status: 'in_stock' },
     };
-    if (p.image_url)
-        v.media = [{ type: 'image', url: imageUrl(ctx, p.image_url) }];
+    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 }] }] };
@@ -202,8 +202,7 @@ function buildLines(ctx, market, requested, existing = []) {
         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 };
-        if (p.image_url)
-            item.image_url = imageUrl(ctx, p.image_url);
+        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 }] });
     });
     return { lines, messages };

package/dist/api/stub/theme.js

@@ -2,6 +2,8 @@
 // custom storefront: the same settings in the same places (accent, logo or wordmark,
 // hero image or band, tagline), the products by top-level category, a page per product
 // 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.
 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) {
@@ -21,7 +23,8 @@ export function renderTheme(r, path, search) {
     const tagline = theme.tagline ?? `Ships to ${markets.flatMap((m) => m.countries).join(', ')}`;
     const logo = theme.logo ? `<img class="logo" src="/${esc(theme.logo.replace(/^\//, ''))}" alt="${esc(name)}">` : `<span class="wordmark">${esc(name)}</span>`;
     const img = (url) => (/^https?:/.test(url) ? url : `/${url}`);
-    const card = (p) => `<article class="product"><a href="/products/${encodeURIComponent(p.sku)}${keep}">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<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 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>`;
     let title = name;
     let body;
     const m = path.match(/^\/products\/([^/]+)$/);
@@ -31,7 +34,7 @@ export function renderTheme(r, path, search) {
             const top = p.category?.split(' > ')[0] ?? 'Other';
             groups.set(top, [...(groups.get(top) ?? []), p]);
         }
-        const hero = theme.hero ? `<section class="hero" style="background-image:url('${esc(img(theme.hero))}')">` : '<section class="hero band">';
+        const hero = `<section class="hero" style="background-image:url('${esc(theme.hero ? img(theme.hero) : '/tiles/hero.svg')}')">`;
         body = `${hero}<h1>${esc(name)}</h1><p class="tagline">${esc(tagline)}</p></section><main>${[...groups].map(([k, ps]) => `<section><h2>${esc(k)}</h2><div class="grid">${ps.map(card).join('')}</div></section>`).join('')}</main>`;
     }
     else if (m) {
@@ -39,7 +42,7 @@ export function renderTheme(r, path, search) {
         if (!p)
             return null;
         title = `${p.name} · ${name}`;
-        body = `<main class="product-page">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<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>`;
+        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>`;
     }
     else
         return null;
@@ -61,3 +64,29 @@ ${body}
 `;
     return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: html };
 }
+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) {
+    const m = path.match(/^\/tiles\/([^/]+)\.svg$/);
+    if (!m)
+        return null;
+    const color = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(r.theme?.color ?? '') ? r.theme.color : '#2f5d50';
+    const headers = { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=300', 'x-content-type-options': 'nosniff' };
+    let svg;
+    if (m[1] === 'hero')
+        svg = `<svg xmlns="http://www.w3.org/2000/svg" width="2400" height="900" viewBox="0 0 2400 900"><rect width="2400" height="900" fill="${color}"/><circle cx="1900" cy="450" r="360" fill="#ffffff" fill-opacity="0.12"/></svg>`;
+    else {
+        let sku;
+        try {
+            sku = decodeURIComponent(m[1]);
+        }
+        catch {
+            return null;
+        }
+        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>`;
+    }
+    return { status: 200, headers, body: svg };
+}

package/dist/api/stub/ucp.js

@@ -8,7 +8,7 @@ import { contentDigest, signHeaders } from '../../ucp/signing.js';
 import { strip } from './db.js';
 import { json } from './http.js';
 import * as shop from './shopping.js';
-import { renderTheme } from './theme.js';
+import { renderTheme, renderTile } from './theme.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
@@ -305,6 +305,9 @@ function handlePermalink(req, r, origin, path) {
 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) {
     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>`);
     // A custom storefront (an uploaded index.html) serves every path; otherwise the theme renders its routes.
     if (files['index.html'] === undefined) {
         const page = renderTheme(r, path, search);

package/dist/bin.js

@@ -4,10 +4,16 @@
 // 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']);
+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 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. */
+const lists = {};
+const set = (k, v) => {
+    values[k] = v;
+    (lists[k] ??= []).push(v);
+};
 const args = [];
 for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -21,9 +27,9 @@ for (let i = 0; i < argv.length; i++) {
     }
     const eq = a.indexOf('=');
     if (eq > 0)
-        values[a.slice(2, eq)] = a.slice(eq + 1);
+        set(a.slice(2, eq), a.slice(eq + 1));
     else if (VALUE_OPTIONS.has(a) && i + 1 < argv.length && !argv[i + 1].startsWith('--'))
-        values[a.slice(2)] = argv[++i];
+        set(a.slice(2), argv[++i]);
     else
         flags.add(a);
 }
@@ -71,6 +77,18 @@ async function run() {
             if (sub === 'delete')
                 return cmd.promotionsDelete(args[2]);
             throw new CliError('unknown_command', `There is no command "promotions ${sub ?? ''}".`, 'Use `c11r promotions list`, `show <id>`, `create`, `update <id>`, `enable <id>`, `disable <id>` or `delete <id>`.');
+        case 'links':
+            if (sub === 'list')
+                return cmd.linksList();
+            if (sub === 'show')
+                return cmd.linksShow(args[2]);
+            if (sub === 'create')
+                return cmd.linksCreate(values);
+            if (sub === 'enable' || sub === 'disable')
+                return cmd.linksEnable(args[2], sub === 'enable');
+            if (sub === 'delete')
+                return cmd.linksDelete(args[2]);
+            throw new CliError('unknown_command', `There is no command "links ${sub ?? ''}".`, 'Use `c11r links list`, `show <id>`, `create`, `enable <id>`, `disable <id>` or `delete <id>`.');
         case 'orders':
             if (sub === 'test')
                 return cmd.ordersTest(flags, values);
@@ -84,7 +102,29 @@ async function run() {
                 return cmd.ucpProfile(flags);
             if (sub === 'check')
                 return cmd.ucpCheck();
-            throw new CliError('unknown_command', `There is no command "ucp ${sub ?? ''}".`, 'Use `c11r ucp profile` or `c11r ucp check`.');
+            if (sub === 'search')
+                return cmd.ucpSearch(args.slice(2).join(' '), values);
+            if (sub === 'product')
+                return cmd.ucpProduct(args[2], values);
+            if (sub === 'order')
+                return cmd.ucpOrder(args[2], values);
+            if (sub === 'ask')
+                return cmd.ucpAsk(args.slice(2).join(' '), values);
+            if (sub === 'checkout') {
+                const [, , action, id] = args;
+                if (action === 'create')
+                    return cmd.ucpCheckoutCreate(values, lists);
+                if (action === 'update')
+                    return cmd.ucpCheckoutUpdate(id, values, lists);
+                if (action === 'show')
+                    return cmd.ucpCheckoutShow(id, values);
+                if (action === 'cancel')
+                    return cmd.ucpCheckoutCancel(id, values);
+                if (action === 'complete')
+                    return cmd.ucpCheckoutComplete(id, values, flags);
+                throw new CliError('unknown_command', `There is no command "ucp checkout ${action ?? ''}".`, 'Use `c11r ucp checkout create`, `update <id>`, `show <id>`, `cancel <id>` or `complete <id>`.');
+            }
+            throw new CliError('unknown_command', `There is no command "ucp ${sub ?? ''}".`, 'Use `c11r ucp search`, `product`, `checkout`, `order`, `ask`, `profile` or `check`.');
         default:
             throw new CliError('unknown_command', `There is no command "${name}".`, `Run \`c11r help\`. Commands: ${Object.keys(cmd.HELP).join(', ')}.`);
     }

package/dist/commands.js

@@ -10,12 +10,14 @@ import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from
 import { storefrontFiles } from './storefront.js';
 import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
+import { checkLink } from './links.js';
 import { ACTIVE_LIMIT, activeWithoutCoupon, checkPromotion } from './promotions.js';
 import YAML from 'yaml';
 import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
+import * as shop from './ucp/shop.js';
 import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 /** The package version, read from package.json so a release bumps it in one place. */
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
@@ -34,11 +36,26 @@ export const HELP = {
     'promotions enable': 'Turn a promotion on: c11r promotions enable <id>.',
     'promotions disable': 'Turn a promotion off without deleting it: c11r promotions disable <id>.',
     'promotions delete': 'Delete a promotion from Commerce Layer: c11r promotions delete <id>. Ask the human first; to pause one, disable it.',
+    'links list': 'The store\'s links, live in Commerce Layer (not in store files): shareable URLs that open a hosted microstore for one sku, a set of skus or a category, or the hosted checkout for an order. For each: id, name, url, status (pending, active, expired, disabled), for (sku | skus | category with its skus | order), markets, starts, ends, params; managed: false marks one made in the dashboard (its id is Commerce Layer\'s).',
+    'links show': 'One link by id, as list shows it: c11r links show <id>.',
+    'links create': "Create a link from a spec in YAML or JSON, on stdin (c11r links create <<'EOF' ... EOF) or with -f <file>: { id, name, for: { sku } | { skus: [...] } | { category: \"A > B\" } | { order: <number> | cart_<id> | chk_<id> }, market (a code or a list; default every market; none for an order), starts (default now), ends (default a month after starts), params }. id is the handle, unique. A category becomes the skus of its products in store.yml now (at most 100 skus). An order link opens the checkout of a draft or pending order: its number, or the id of a UCP cart or checkout. One Commerce Layer link per market: urls has each, url the first market's. A link cannot be changed: delete it and create it again. Errors: invalid_link (the message starts with the path in the spec), link_exists.",
+    'links enable': 'Turn a link on: c11r links enable <id>.',
+    'links disable': 'Turn a link off without deleting it: its url stops opening. c11r links disable <id>.',
+    'links delete': 'Delete a link from Commerce Layer: c11r links delete <id>. Ask the human first; to pause one, disable it.',
     'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline. discounts lists what promotions and codes took off; a code that applied nothing is a discount_code_invalid warning in messages.',
     'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
     'orders show': 'Show one order: c11r orders show <id or number>.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
     'ucp check': 'Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way. Exits 1 when a check fails.',
+    'ucp search': "Buy for the human, step 1: search a store's catalog over UCP. c11r ucp search [<query>] [--country CC] [--store <host>]; no query lists the whole catalog (up to 50). Returns { store, query, count, total_count, has_more, products: [{ id, title, description, url, image_url, variants: [{ id, sku, title, price: { amount, currency, major, display }, available, availability, ships }] }], signature }. Show the human the titles and price.display (amount is in minor units: never show it), let them pick, then c11r ucp checkout create --item <sku>. --store is any UCP store (hostname or https origin); the default is this folder's store.",
+    'ucp product': 'Look at one product over UCP, with every variant and the full description: c11r ucp product <product id or sku> [--country CC] [--store <host>]. Returns { store, product: { id, title, description, url, image_url, variants: [...] }, signature }, variants as in ucp search.',
+    'ucp checkout create': "Buy for the human, step 2: open a checkout with the items the human picked. c11r ucp checkout create --item <sku>[:<qty>] [--item ...] [--code <discount>] [--country CC] [--store <host>]. Returns the checkout: { id, status, store, currency, line_items: [{ id, sku, title, quantity, unit_price, total }], buyer, ship_to, shipping, discounts, codes, totals: [{ type, label, amount, major, display }], total, messages, continue_url, expires_at, links, signature }. status is incomplete until the buyer's email and shipping address are given: messages say what is missing. Ask the human for them, never invent them, then c11r ucp checkout update <id>. The id is remembered with its store: later steps need no --store.",
+    'ucp checkout update': "Buy for the human, step 3: give the buyer's details, change items or codes. c11r ucp checkout update <id> [--email --first-name --last-name --phone] [--street --city --postal-code --region --country] [--item <sku>:<qty> (0 removes)] [--code <discount> (adds)] [--shipping <option id>]; or the same as YAML or JSON on stdin or -f <file>: { buyer: { email, first_name, last_name, phone_number }, address: { street_address, address_locality, postal_code, address_region, address_country }, items: [\"SKU:2\"], codes: [...] (replaces), shipping }. Only what is given changes. Returns the checkout as in create: status ready_for_complete once nothing is missing, with shipping and the total including it; or incomplete with messages (address_undeliverable says where the store ships). Show the human the line items, shipping and total.display, ask for an explicit yes, then c11r ucp checkout complete <id>.",
+    'ucp checkout show': 'Show a checkout as the store has it now: c11r ucp checkout show <id> [--store <host>]. Returns the checkout as in ucp checkout create.',
+    'ucp checkout cancel': 'Cancel a checkout the human no longer wants: c11r ucp checkout cancel <id> [--store <host>]. Returns the checkout, status canceled.',
+    'ucp checkout complete': "Buy for the human, step 4, only after the human said yes to the total: pay the checkout. c11r ucp checkout complete <id> [--decline] [--store <host>]. Pays with the sandbox handler (ai.commercelayer.sandbox: test payments, no money moves); --decline uses the declined test card. Returns the checkout with status completed and order: { id, label, permalink_url }, plus payment_handler. Tell the human the order label and give them permalink_url. A store with no sandbox handler (a live store with a real payment gateway) answers payment_handler_unsupported: give the human continue_url to pay there. A declined payment leaves status ready_for_complete with a payment_failed message.",
+    'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ sku, title, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
+    'ucp ask': 'Ask a store a question in plain language over UCP (shipping, returns, what it sells): c11r ucp ask "<question>" [--store <host>]. Returns { store, question, answer, links, messages, signature }. The answer is the store\'s: quote it, do not embellish it. Ask only answers; buy with ucp checkout.',
     status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists).',
     claim: 'Start keeping this sandbox store: returns a URL and a code for the human to approve in the browser.',
     help: 'Describe the commands. `c11r help <command>` for one command, `c11r help <group>` (catalog, orders, storefront, ucp) for a group.',
@@ -347,15 +364,153 @@ export async function claim() {
         next: 'Ask the human to open verification_url and enter user_code, then run `c11r status`.',
     };
 }
+// ---------- ucp: buying for the human, step by step, from this store or any UCP store
+/** The store to buy from: --store, else the one an id was made at, else this folder's. */
+async function shopOrigin(values, id) {
+    if (values.store)
+        return shop.originOf(values.store);
+    const known = id ? shop.remembered(id) : undefined;
+    if (known)
+        return known;
+    if (!readCredentials())
+        fail('no_store', 'There is no store in this folder, and no --store was given.', 'Pass the store to buy from: --store <hostname or https origin>.');
+    return storeOrigin();
+}
+const needId = (id, command) => {
+    if (!id)
+        fail('missing_argument', `${command} needs a checkout id.`, 'Use the id that c11r ucp checkout create printed (chk_...).');
+    return id;
+};
+const checkoutNext = (ck) => {
+    if (ck.status === 'completed')
+        return `Paid. Tell the human: order ${ck.order?.label ?? ck.order?.id}, and give them ${ck.order?.permalink_url}.`;
+    if (ck.status === 'canceled')
+        return 'Canceled. Open a new one with c11r ucp checkout create --item <sku> if the human wants to buy.';
+    if (ck.status === 'ready_for_complete') {
+        const declined = (ck.messages ?? []).some((m) => m.code === 'payment_failed');
+        if (declined)
+            return `The payment failed: tell the human. Try again only if they ask: c11r ucp checkout complete ${ck.id}.`;
+        return `Show the human the items, shipping and total (${ck.total?.display}), ask for an explicit yes, then run c11r ucp checkout complete ${ck.id}.`;
+    }
+    const errors = (ck.messages ?? []).filter((m) => m.type === 'error').map((m) => m.content);
+    return `Still needed: ${errors.join(' ') || 'see messages'} Ask the human (never invent buyer details), then run c11r ucp checkout update ${ck.id} with what they said.`;
+};
+export async function ucpSearch(query, values) {
+    const r = await shop.search(await shopOrigin(values), query, values.country);
+    return { ...r, next: r.count ? 'Show the human the products (title, price.display), let them pick, then c11r ucp checkout create --item <sku>[:<qty>].' : 'Nothing matched: try another query, or none for the whole catalog.' };
+}
+export async function ucpProduct(id, values) {
+    if (!id)
+        fail('missing_argument', 'ucp product needs a product id or sku.', 'Use an id or sku from c11r ucp search.');
+    return shop.product(await shopOrigin(values), id, values.country);
+}
+export async function ucpCheckoutCreate(values, lists) {
+    const items = (lists.item ?? []).map(shop.parseItem);
+    if (!items.length)
+        fail('missing_argument', 'ucp checkout create needs at least one --item.', 'Example: c11r ucp checkout create --item ETH-250:2. The skus are in c11r ucp search.');
+    if (items.some((l) => l.quantity < 1))
+        fail('invalid_argument', 'An --item quantity must be 1 or more.', 'Example: --item ETH-250:2.');
+    const ck = await shop.createCheckout(await shopOrigin(values), items, lists.code ?? [], values.country);
+    return { ...ck, next: checkoutNext(ck) };
+}
+const BUYER_FLAGS = { email: 'email', 'first-name': 'first_name', 'last-name': 'last_name', phone: 'phone_number' };
+const ADDRESS_FLAGS = { street: 'street_address', city: 'address_locality', 'postal-code': 'postal_code', region: 'address_region', country: 'address_country' };
+export async function ucpCheckoutUpdate(id, values, lists) {
+    needId(id, 'ucp checkout update');
+    const pick = (map) => {
+        const out = {};
+        for (const [flag, key] of Object.entries(map))
+            if (values[flag] !== undefined)
+                out[key] = values[flag];
+        return Object.keys(out).length ? out : undefined;
+    };
+    const changes = { buyer: pick(BUYER_FLAGS), address: pick(ADDRESS_FLAGS), items: lists.item?.map(shop.parseItem), add_codes: lists.code, shipping: values.shipping };
+    const flagged = Object.values(changes).some((v) => v !== undefined);
+    if (!flagged || values.file) {
+        // No flags: the changes as YAML or JSON on stdin or -f.
+        const raw = await readText(values, 'checkout update', `Give the changes as flags (--email ..., --street ...) or as YAML or JSON on stdin or -f <file>: { buyer: {...}, address: {...}, items, codes, shipping }.`);
+        const bad = (msg) => fail('invalid_argument', `checkout update: ${msg}`, 'The input is { buyer: { email, first_name, last_name, phone_number }, address: { street_address, address_locality, postal_code, address_region, address_country }, items: ["SKU:2"], codes: [...], shipping }.');
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            bad('the input is not a map.');
+        const r = raw;
+        for (const k of Object.keys(r))
+            if (!['buyer', 'address', 'items', 'codes', 'shipping'].includes(k))
+                bad(`unknown key ${k}.`);
+        const map = (o, keys, what) => {
+            if (o === undefined)
+                return undefined;
+            if (!o || typeof o !== 'object' || Array.isArray(o))
+                bad(`${what} is not a map.`);
+            for (const [k, v] of Object.entries(o))
+                if (!keys.includes(k) || typeof v !== 'string')
+                    bad(`${what}.${k} is not one of ${keys.join(', ')} with a text value.`);
+            return o;
+        };
+        if (r.buyer !== undefined)
+            changes.buyer = { ...map(r.buyer, Object.values(BUYER_FLAGS), 'buyer'), ...changes.buyer };
+        if (r.address !== undefined)
+            changes.address = { ...map(r.address, ['first_name', 'last_name', 'extended_address', ...Object.values(ADDRESS_FLAGS)], 'address'), ...changes.address };
+        if (r.items !== undefined) {
+            if (!Array.isArray(r.items))
+                bad('items is not a list.');
+            changes.items = [...r.items.map((x) => (typeof x === 'string' ? shop.parseItem(x) : x && typeof x === 'object' && typeof x.sku === 'string' && Number.isInteger(x.quantity) ? { sku: x.sku, quantity: x.quantity } : bad('items holds "SKU:QTY" or { sku, quantity }.'))), ...(changes.items ?? [])];
+        }
+        if (r.codes !== undefined) {
+            if (!Array.isArray(r.codes) || r.codes.some((c) => typeof c !== 'string'))
+                bad('codes is not a list of codes.');
+            changes.codes = [...r.codes, ...(changes.add_codes ?? [])];
+        }
+        if (r.shipping !== undefined)
+            changes.shipping = changes.shipping ?? String(r.shipping);
+    }
+    if (changes.items?.some((l) => !Number.isInteger(l.quantity) || l.quantity < 0))
+        fail('invalid_argument', 'An item quantity must be 0 (remove it) or more.', 'Example: --item ETH-250:2.');
+    const ck = await shop.updateCheckout(await shopOrigin(values, id), id, changes);
+    return { ...ck, next: checkoutNext(ck) };
+}
+export async function ucpCheckoutShow(id, values) {
+    const ck = await shop.getCheckout(await shopOrigin(values, needId(id, 'ucp checkout show')), id);
+    return { ...ck, next: checkoutNext(ck) };
+}
+export async function ucpCheckoutCancel(id, values) {
+    const ck = await shop.cancelCheckout(await shopOrigin(values, needId(id, 'ucp checkout cancel')), id);
+    return { ...ck, next: checkoutNext(ck) };
+}
+export async function ucpCheckoutComplete(id, values, flags) {
+    const ck = await shop.completeCheckout(await shopOrigin(values, needId(id, 'ucp checkout complete')), id, flags.has('--decline'));
+    return { ...ck, payment_handler: 'ai.commercelayer.sandbox (test payments only)', next: checkoutNext(ck) };
+}
+export async function ucpOrder(id, values) {
+    if (!id)
+        fail('missing_argument', 'ucp order needs an order id.', 'Use order.id from c11r ucp checkout complete.');
+    const o = await shop.getOrder(await shopOrigin(values, id), id);
+    return { ...o, next: `Tell the human: order ${o.label}, details at ${o.permalink_url}.` };
+}
+export async function ucpAsk(question, values) {
+    if (!question.trim())
+        fail('missing_argument', 'ucp ask needs a question.', 'Example: c11r ucp ask "Do you ship to Canada?".');
+    return shop.ask(await shopOrigin(values), question);
+}
 // ---------- promotions: live settings in Commerce Layer, not store files
-/** The fields list, show and the writes print, in a stable order. */
-const READ_ONLY = ['status', 'uses', 'managed'];
-/** The spec from -f <file> or stdin, YAML or JSON, validated against store.yml's markets and products. */
-async function readSpec(values) {
-    let text = "";
+/** What list and show print beyond the spec: dropped when it is sent back. */
+const READ_ONLY = ['status', 'uses', 'managed', 'url', 'urls', 'created_at'];
+/**
+ * A spec from -f <file> or stdin, YAML or JSON, for promotions and links. What show prints
+ * can be edited and sent back: the read-only fields are dropped.
+ */
+async function readInput(values, what) {
+    const raw = await readText(values, what, `Give the ${what} as YAML or JSON on stdin (c11r ${what}s create <<'EOF' ... EOF) or with -f <file>.`, `invalid_${what}`);
+    if (raw && typeof raw === 'object' && !Array.isArray(raw))
+        for (const k of READ_ONLY)
+            delete raw[k];
+    return raw;
+}
+/** YAML or JSON from -f <file> or stdin, parsed. */
+async function readText(values, what, usage, invalid = 'invalid_argument') {
+    let text = '';
     if (values.file) {
         if (!fs.existsSync(values.file))
-            fail('missing_argument', `There is no file ${values.file}.`, 'Give the promotion as YAML or JSON with -f <file>, or on stdin.');
+            fail('missing_argument', `There is no file ${values.file}.`, `Give the ${what} as YAML or JSON with -f <file>, or on stdin.`);
         text = fs.readFileSync(values.file, 'utf8');
     }
     else if (!process.stdin.isTTY) {
@@ -366,20 +521,21 @@ async function readSpec(values) {
         text = Buffer.concat(chunks).toString('utf8');
     }
     else
-        fail('missing_argument', 'No promotion given.', "Give the promotion as YAML or JSON on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>.");
+        fail('missing_argument', `No ${what} given.`, usage);
     if (!text.trim())
-        fail('missing_argument', 'No promotion given: the input is empty.', "Give the promotion as YAML or JSON on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>.");
+        fail('missing_argument', `No ${what} given: the input is empty.`, usage);
     let raw;
     try {
         raw = YAML.parse(text);
     }
     catch (e) {
-        fail('invalid_promotion', `promotion: not valid YAML or JSON: ${e.message.split('\n')[0]}`, 'Fix the syntax and run the command again.');
+        fail(invalid, `${what}: not valid YAML or JSON: ${e.message.split('\n')[0]}`, 'Fix the syntax and run the command again.');
     }
-    // What show prints can be edited and sent back: the read-only fields are dropped.
-    if (raw && typeof raw === 'object' && !Array.isArray(raw))
-        for (const k of READ_ONLY)
-            delete raw[k];
+    return raw;
+}
+/** A promotion spec, validated against store.yml's markets and products. */
+async function readSpec(values) {
+    const raw = await readInput(values, 'promotion');
     const store = loadStore();
     return checkPromotion(raw, store.markets, store.products);
 }
@@ -433,3 +589,43 @@ export async function promotionsDelete(id) {
     await createApi(requireCredentials()).deletePromotion(id);
     return { status: 'deleted', id };
 }
+// ---------- links: live settings in Commerce Layer, not store files
+/** A link as list, show and the writes print it: url and urls first. */
+const urlFirst = ({ url, urls, ...l }) => ({ url, urls, ...l });
+const linkNext = (l) => {
+    const what = 'order' in l.for ? 'the hosted checkout for the order' : 'a microstore for what it sells';
+    const which = Object.keys(l.urls ?? {}).length > 1 ? `the url of each market in urls (url is ${Object.keys(l.urls)[0]}'s)` : 'the url';
+    if (l.status === 'pending')
+        return `Give the human ${which}: it opens ${what} from ${l.starts}; until then it shows a not-found page.`;
+    if (l.status === 'active')
+        return `Give the human ${which}: it opens ${what} until ${l.ends}. Payment is manual (wire transfer) unless a gateway is added.`;
+    return undefined;
+};
+export async function linksList() {
+    const { links } = await createApi(requireCredentials()).listLinks();
+    return { count: links.length, links: links.map(urlFirst) };
+}
+export async function linksShow(id) {
+    if (!id)
+        fail('missing_argument', 'Which link?', 'Use `c11r links show <id>`; `c11r links list` has the ids.');
+    return urlFirst(await createApi(requireCredentials()).getLink(id));
+}
+export async function linksCreate(values) {
+    const api = createApi(requireCredentials());
+    const raw = await readInput(values, 'link');
+    const store = loadStore();
+    const created = await api.createLink(checkLink(raw, store.markets, store.products));
+    return { status: 'created', link: urlFirst(created), next: linkNext(created) };
+}
+export async function linksEnable(id, enabled) {
+    if (!id)
+        fail('missing_argument', 'Which link?', `Use \`c11r links ${enabled ? 'enable' : 'disable'} <id>\`.`);
+    const link = await createApi(requireCredentials()).setLinkEnabled(id, enabled);
+    return { status: enabled ? 'enabled' : 'disabled', link: urlFirst(link), next: enabled ? linkNext(link) : undefined };
+}
+export async function linksDelete(id) {
+    if (!id)
+        fail('missing_argument', 'Which link?', 'Use `c11r links delete <id>`, after asking the human.');
+    await createApi(requireCredentials()).deleteLink(id);
+    return { status: 'deleted', id };
+}

package/dist/links.js

@@ -0,0 +1,118 @@
+// Links: shareable URLs that open a hosted microstore for one SKU, a set of SKUs or a
+// category, or the hosted checkout for an order. Live configuration in Commerce Layer, made
+// with c11r links create; never in store.yml. The CLI validates the spec against store.yml
+// (skus, categories, markets) and sends one normalized link; the API makes the CL link.
+import { isoDate } from './promotions.js';
+import { fail } from './output.js';
+const KEYS = ['id', 'name', 'for', 'market', 'markets', 'starts', 'ends', 'params'];
+const FOR = ['sku', 'skus', 'category', 'order'];
+/** The SKUs one link can sell: the API's limit. */
+const MAX_SKUS = 100;
+const SHAPE_HINT = 'See the links skill for the shape: https://commercelayer.ai/skills/links.md';
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const seconds = (d) => d.toISOString().replace(/\.\d{3}Z$/, 'Z');
+/** One calendar month after a date-time, in UTC. */
+function monthAfter(iso) {
+    const d = new Date(iso);
+    d.setUTCMonth(d.getUTCMonth() + 1);
+    return seconds(d);
+}
+/**
+ * Validate one link spec (YAML or JSON, as given to links create) and normalize it to the
+ * wire shape, or fail invalid_link naming the path inside the spec. A category becomes its
+ * products' skus as they are now, from store.yml.
+ */
+export function checkLink(raw, markets, products, now = new Date()) {
+    const skus = new Set(products.map((p) => p.sku));
+    const bad = (msg, hint, path = 'link') => fail('invalid_link', `${path}: ${msg}`, hint);
+    if (!isObj(raw))
+        bad('is not a map.', `A link is a map with id, name and for. ${SHAPE_HINT}`);
+    const l = raw;
+    if (typeof l.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(l.id))
+        bad(`id is ${l.id === undefined ? 'missing' : `"${String(l.id)}"`}.`, 'Give the link an id of lowercase letters, digits and dashes, such as summer-bundle: the handle for show, enable, disable and delete.');
+    const id = l.id;
+    for (const k of Object.keys(l))
+        if (!KEYS.includes(k))
+            bad(`unknown key ${k}.`, `A link's keys are ${KEYS.join(', ')}.`);
+    const link = { id, name: l.name === undefined ? id : String(l.name), for: { sku: '' }, starts: '', ends: '' };
+    if (!link.name.trim() || link.name.length > 255)
+        bad('name is empty or longer than 255 characters.', 'Write a short name the human will recognize in the dashboard.');
+    // for: exactly one of sku, skus, category, order. show prints a category with its skus: those are read again.
+    const f = l.for;
+    if (!isObj(f))
+        bad(f === undefined ? 'has no for.' : 'for is not a map.', `Say what the link sells: for: { sku: <sku> }, { skus: [...] }, { category: "A > B" } or { order: <number> }. ${SHAPE_HINT}`);
+    const given = Object.keys(f).filter((k) => !('category' in f && k === 'skus'));
+    if (given.includes('sku_list'))
+        bad('sku_list is a list made in the dashboard.', 'Name the skus (for: { skus: [...] }) or a category instead.', 'for');
+    for (const k of given)
+        if (!FOR.includes(k))
+            bad(`unknown key ${k}.`, `for takes one of ${FOR.join(', ')}.`, 'for');
+    if (given.length !== 1)
+        bad(`has ${given.length ? given.join(' and ') : 'nothing'}.`, 'Give exactly one of sku, skus, category or order: a link sells one thing.', 'for');
+    const kind = given[0];
+    const v = f[kind];
+    if (kind === 'sku') {
+        if (typeof v !== 'string' || !skus.has(v))
+            bad(`${String(v)} is not a product.`, "Use the SKU of one of the store's products.", 'for.sku');
+        link.for = { sku: v };
+    }
+    else if (kind === 'skus') {
+        if (!Array.isArray(v) || !v.length)
+            bad('is not a list of SKUs.', 'List one or more SKUs: skus: [ETH, COL].', 'for.skus');
+        if (v.length > MAX_SKUS)
+            bad(`has ${v.length} SKUs.`, `A link sells at most ${MAX_SKUS} SKUs: make several links.`, 'for.skus');
+        v.forEach((s, i) => {
+            if (typeof s !== 'string' || !skus.has(s))
+                bad(`${String(s)} is not a product.`, "Use SKUs of the store's products.", `for.skus[${i}]`);
+        });
+        link.for = { skus: [...new Set(v)] };
+    }
+    else if (kind === 'category') {
+        const name = String(v).split('>').map((s) => s.trim()).filter(Boolean).join(' > ');
+        const found = products.filter((x) => x.category === name || x.category?.startsWith(`${name} > `)).map((x) => x.sku);
+        if (!name || !found.length)
+            bad(`no product is in category "${String(v)}".`, `Use a category of the store's products, written as in the products: ${[...new Set(products.map((x) => x.category).filter(Boolean))].join(', ') || 'none has a category yet'}.`, 'for.category');
+        if (found.length > MAX_SKUS)
+            bad(`"${name}" has ${found.length} products.`, `A link sells at most ${MAX_SKUS} SKUs: use a narrower category, or several links.`, 'for.category');
+        link.for = { category: name, skus: found.sort() };
+    }
+    else {
+        if (!(typeof v === 'string' && v.trim()) && !(Number.isInteger(v) && v > 0))
+            bad(`${String(v)} is not an order number.`, 'Use the number of a draft or pending order, or the id of a UCP cart or checkout (cart_..., chk_...): the order behind it.', 'for.order');
+        link.for = { order: String(v).trim().replace(/^#/, '') };
+    }
+    // Markets: a code or a list, under market or markets; none means every market. An order has its own.
+    if (l.market !== undefined && l.markets !== undefined)
+        bad('has market and markets.', 'Use one of them.');
+    const m = l.market ?? l.markets;
+    const path = l.market !== undefined ? 'market' : 'markets';
+    if (kind === 'order') {
+        if (m !== undefined)
+            bad(`${path}: an order link has the order's market.`, 'Remove market: the checkout opens in the market the order was placed in.');
+    }
+    else if (m === undefined)
+        link.markets = markets.map((x) => x.code);
+    else {
+        const codes = Array.isArray(m) ? m : [m];
+        if (!codes.length)
+            bad('is empty.', 'List one or more market codes, or leave it out for every market.', path);
+        codes.forEach((c, i) => {
+            if (!markets.some((x) => x.code === c))
+                bad(`${String(c)} is not in markets.`, `Use the code of one of the store's markets: ${markets.map((x) => x.code).join(', ')}.`, Array.isArray(m) ? `${path}[${i}]` : path);
+        });
+        link.markets = [...new Set(codes)];
+    }
+    link.starts = l.starts === undefined ? seconds(now) : isoDate(l.starts, false, (msg, h) => bad(`starts ${msg}`, h));
+    link.ends = l.ends === undefined ? monthAfter(link.starts) : isoDate(l.ends, true, (msg, h) => bad(`ends ${msg}`, h));
+    if (Date.parse(link.ends) <= Date.parse(link.starts))
+        bad('ends is not after starts.', 'Make the end date later than the start date.');
+    if (l.params !== undefined) {
+        if (!isObj(l.params))
+            bad('params is not a map.', 'params is a map of names to text, numbers or true/false, added to the link URL.');
+        for (const [k, p] of Object.entries(l.params))
+            if (!['string', 'number', 'boolean'].includes(typeof p))
+                bad(`${k} is not text, a number or true/false.`, 'params values are plain values, added to the link URL.', `params.${k}`);
+        link.params = l.params;
+    }
+    return link;
+}

package/dist/promotions.js

@@ -17,7 +17,7 @@ const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
 const isInt = (v, min) => Number.isInteger(v) && v >= min;
 const list = (v) => (Array.isArray(v) ? v : [v]);
 /** A date or a date-time, as ISO UTC. A bare day starts at 00:00:00Z and ends at 23:59:59Z. */
-function isoDate(v, end, bad) {
+export function isoDate(v, end, bad) {
     const s = v instanceof Date ? v.toISOString().replace(/\.000Z$/, 'Z') : String(v);
     const hint = 'Write a day, 2026-12-01, or a time in UTC, 2026-12-01T09:00:00Z.';
     if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {

package/dist/storefront.js

@@ -3,10 +3,13 @@
 // top-level category), styles.css (theme tokens first, then the drop-in.css
 // overrides, then the page) and app.js (market switch, category links, and a
 // product page at #/p/<sku>). Product images are the store's, at /img/<file> (from
-// .commercelayer/img/, uploaded by apply). The agent then makes it the human's.
+// .commercelayer/img/, uploaded by apply); a product without one shows the tile the
+// store host draws at /tiles/<sku>.svg. The agent then makes it the human's.
 import { isLocalImage } from './store.js';
 /** img/<file> is the store's image at /img/<file> on the store host, whatever page links it. */
 const imageSrc = (url) => (isLocalImage(url) ? `/${url}` : url);
+/** A product without an image gets the tile the store host draws for it, at /tiles/<sku>.svg. */
+const productImage = (p) => (p.image_url ? imageSrc(p.image_url) : `/tiles/${encodeURIComponent(p.sku)}.svg`);
 const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 /** The scaffold's files, by path relative to the storefront folder. */
 export function storefrontFiles(store, clientId) {
@@ -17,7 +20,7 @@ function indexHtml(store, clientId) {
     const card = (p, h) => {
         const href = `#/p/${encodeURIComponent(p.sku)}`;
         return `      <article class="product" id="p-${esc(p.sku)}">
-        <a class="media" href="${esc(href)}" tabindex="-1">${p.image_url ? `<img src="${esc(imageSrc(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder" aria-hidden="true"></div>'}</a>
+        <a class="media" href="${esc(href)}" tabindex="-1"><img src="${esc(productImage(p))}" alt="${esc(p.name)}"${p.image_url ? '' : ' loading="lazy"'}></a>
         <${h}><a href="${esc(href)}">${esc(p.name)}</a></${h}>
 ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-price code="${esc(p.sku)}"><cl-price-amount type="compare-at"></cl-price-amount> <cl-price-amount type="price"></cl-price-amount></cl-price>
         <cl-availability code="${esc(p.sku)}"><cl-availability-status type="available">In stock</cl-availability-status><cl-availability-status type="unavailable">Sold out</cl-availability-status></cl-availability>
@@ -53,7 +56,7 @@ ${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-pric
     }
     const options = store.markets.map((m) => `          <option value="${esc(m.code)}">${esc(m.name)} (${esc(m.currency)})</option>`).join('\n');
     // What the product page shows, by sku. Prices and availability come live from drop-in.js.
-    const data = Object.fromEntries(store.products.map((p) => [p.sku, { name: p.name, description: p.description, image_url: p.image_url && imageSrc(p.image_url), category: p.category }]));
+    const data = Object.fromEntries(store.products.map((p) => [p.sku, { name: p.name, description: p.description, image_url: productImage(p), category: p.category }]));
     const json = JSON.stringify(data, null, 2).replace(/</g, '\\u003c');
     return `<!doctype html>
 <html lang="en">

package/dist/ucp/platform.js

@@ -74,7 +74,7 @@ export function agentProfile() {
             },
         },
         name: 'Commerce Layer agent CLI',
-        description: 'c11r, the Commerce Layer CLI for coding agents, acting as a shopping platform: it places test orders and checks a store speaks UCP.',
+        description: 'The Commerce Layer agent CLI: a shopping agent that buys from UCP stores on behalf of a human, places test orders in its own store and checks that a store speaks UCP.',
     };
 }
 /** Minor units per currency unit (ISO 4217 exponent). */

package/dist/ucp/shop.js

@@ -0,0 +1,308 @@
+// Buying from a store step by step, for an agent shopping on behalf of its human: search,
+// look at a product, open a checkout, give the buyer's details, pay, read the order. Each
+// step is one command, so the agent talks to the human in between. The results are trimmed
+// for a conversation: prices in major units as well as minor, what is still missing.
+// buy.ts is the one-shot test buyer; this is the real one, with the human's details.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fail } from '../output.js';
+import { discover, replay, shopping, UcpError } from './client.js';
+import { sandboxInstrument } from './buy.js';
+import { minorUnits, SANDBOX_HANDLER } from './platform.js';
+// ---------- which store an id belongs to
+/** Checkout and order ids, by the store origin they were made at: later steps need no --store. */
+const stateFile = () => process.env.C11R_UCP_STATE ?? path.join(process.env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state'), 'c11r', 'ucp.json');
+const MAX_REMEMBERED = 200;
+function readState() {
+    try {
+        return JSON.parse(fs.readFileSync(stateFile(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function remember(id, origin) {
+    const s = readState();
+    delete s[id];
+    s[id] = origin;
+    const keys = Object.keys(s);
+    for (const k of keys.slice(0, Math.max(0, keys.length - MAX_REMEMBERED)))
+        delete s[k];
+    fs.mkdirSync(path.dirname(stateFile()), { recursive: true });
+    fs.writeFileSync(stateFile(), JSON.stringify(s, null, 2) + '\n', { mode: 0o600 });
+}
+export const remembered = (id) => readState()[id];
+/** A store origin from --store: an origin, a URL on the store, or a bare hostname. */
+export function originOf(given) {
+    let url;
+    try {
+        url = new URL(/^[a-z]+:\/\//i.test(given) ? given : `https://${given}`);
+    }
+    catch {
+        fail('invalid_argument', `--store ${given} is not a URL or hostname.`, 'Give the store as a hostname (shop.example.com) or an origin (https://shop.example.com).');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname)))
+        fail('invalid_argument', `--store ${given} is not https.`, 'UCP stores are served over https: give https://<host>.');
+    return url.origin;
+}
+export function money(amount, currency) {
+    const minor = minorUnits(currency);
+    const decimals = Math.round(Math.log10(minor));
+    const major = amount / minor;
+    return { amount, currency, major, display: `${amount < 0 ? '-' : ''}${currency} ${Math.abs(major).toFixed(decimals)}` };
+}
+const plain = (d) => d?.plain ?? d?.markdown ?? d?.html;
+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,
+        title: v.title,
+        price: v.price ? money(v.price.amount, v.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,
+    };
+}
+export function productView(p, full = false) {
+    const variants = (p.variants ?? []).map(variantView);
+    const description = plain(p.description);
+    const image = p.media?.find((m) => m.type === 'image')?.url ?? variants[0]?.image_url;
+    return {
+        id: p.id,
+        title: p.title,
+        description: full || !description || description.length <= 200 ? description : `${description.slice(0, 197)}...`,
+        url: p.url,
+        image_url: image,
+        // 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 })),
+    };
+}
+const sign = (c) => c.signature ?? 'unsigned';
+function selectedDestination(ck) {
+    const m = ck.fulfillment?.methods?.[0];
+    return m?.destinations?.find((d) => d.id === m.selected_destination_id);
+}
+/** A checkout for the conversation: what is in it, what it costs, what is still missing. */
+export function checkoutView(ck, origin, call) {
+    const cur = ck.currency;
+    const method = ck.fulfillment?.methods?.[0];
+    const group = method?.groups?.[0];
+    const options = group?.options ?? [];
+    const option = options.find((o) => o.id === group?.selected_option_id);
+    const optionView = (o) => ({ id: o.id, title: o.title, description: plain(o.description), price: o.totals?.find((t) => t.type === 'total') ? money(o.totals.find((t) => t.type === 'total').amount, cur) : undefined });
+    const { id: _id, type: _type, ...address } = selectedDestination(ck) ?? {};
+    const total = (ck.totals ?? []).find((t) => t.type === 'total');
+    return {
+        id: ck.id,
+        status: ck.status,
+        store: origin,
+        currency: cur,
+        line_items: (ck.line_items ?? []).map((l) => ({
+            id: l.id,
+            sku: l.item?.id,
+            title: l.item?.title,
+            quantity: l.quantity,
+            unit_price: l.item?.price === undefined ? undefined : money(l.item.price, cur),
+            total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),
+        })),
+        buyer: ck.buyer ? Object.fromEntries(Object.entries(ck.buyer).filter(([k]) => k !== 'consent')) : undefined,
+        ship_to: Object.keys(address).length ? address : undefined,
+        shipping: option ? optionView(option) : undefined,
+        shipping_options: options.length > 1 ? options.map(optionView) : undefined,
+        discounts: ck.discounts?.applied?.length ? ck.discounts.applied.map((d) => ({ code: d.code, title: d.title, automatic: d.automatic, amount: money(d.amount, cur) })) : undefined,
+        codes: ck.discounts?.codes?.length ? ck.discounts.codes : undefined,
+        totals: (ck.totals ?? []).map((t) => ({ type: t.type, label: t.display_text, ...money(t.amount, cur) })),
+        total: total ? money(total.amount, cur) : undefined,
+        messages: ck.messages,
+        order: ck.order,
+        continue_url: ck.continue_url,
+        expires_at: ck.expires_at,
+        links: ck.links,
+        signature: sign(call),
+    };
+}
+export function orderView(o, origin, call) {
+    const cur = o.currency;
+    return {
+        id: o.id,
+        label: o.label,
+        permalink_url: o.permalink_url,
+        store: origin,
+        checkout_id: o.checkout_id,
+        currency: cur,
+        line_items: (o.line_items ?? []).map((l) => ({
+            sku: l.item?.id,
+            title: l.item?.title,
+            quantity: l.quantity?.total ?? l.quantity,
+            status: l.status,
+            total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),
+        })),
+        fulfillment: (o.fulfillment?.expectations ?? []).map((e) => ({ method: e.method_type, destination: e.destination, description: e.description })),
+        events: o.fulfillment?.events?.length ? o.fulfillment.events : undefined,
+        totals: (o.totals ?? []).map((t) => ({ type: t.type, label: t.display_text, ...money(t.amount, cur) })),
+        signature: sign(call),
+    };
+}
+// ---------- the steps
+/** Turn a store's refusal into a CLI error; a missing checkout or order is not_found. */
+async function step(origin, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        if (!(e instanceof UcpError))
+            throw e;
+        const code = e.call.body?.messages?.[0]?.code;
+        if (code === 'not_found' || e.call.status === 404)
+            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.`);
+    }
+}
+/** --item SKU or SKU:QTY. */
+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]) };
+}
+export async function open(origin) {
+    const store = await discover(origin);
+    if (!store.capabilities.has('dev.ucp.shopping.checkout'))
+        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) {
+    const store = await discover(origin);
+    const body = { query, pagination: { limit: 50 } };
+    if (country)
+        body.context = { address_country: country.toUpperCase() };
+    const call = await step(origin, () => shopping.search(store, body));
+    const r = call.body;
+    const products = r.products ?? [];
+    return {
+        store: origin,
+        query,
+        count: products.length,
+        total_count: r.pagination?.total_count,
+        has_more: r.pagination?.has_next_page || undefined,
+        products: products.map((p) => productView(p)),
+        messages: r.messages,
+        signature: sign(call),
+    };
+}
+export async function product(origin, id, country) {
+    const store = await discover(origin);
+    const body = { id };
+    if (country)
+        body.context = { address_country: country.toUpperCase() };
+    const call = await step(origin, () => shopping.product(store, body));
+    return { store: origin, product: productView(call.body.product, true), signature: sign(call) };
+}
+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 })) };
+    if (country)
+        body.context = { address_country: country.toUpperCase() };
+    if (codes.length)
+        body.discounts = { codes };
+    const call = await step(origin, () => shopping.createCheckout(store, body));
+    remember(call.body.id, origin);
+    return checkoutView(call.body, origin, call);
+}
+export async function getCheckout(origin, id) {
+    const store = await open(origin);
+    const call = await step(origin, () => shopping.getCheckout(store, id));
+    return checkoutView(call.body, origin, call);
+}
+const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== ''));
+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>.');
+    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);
+        if (l.quantity === 0) {
+            if (i >= 0)
+                body.line_items.splice(i, 1);
+        }
+        else if (i >= 0)
+            body.line_items[i].quantity = l.quantity;
+        else
+            body.line_items.push({ item: { id: l.sku }, 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}.`);
+    const codes = ch.codes ?? [...(current.discounts?.codes ?? []), ...(ch.add_codes ?? [])];
+    if (ch.codes || ch.add_codes?.length)
+        body.discounts = { codes: [...new Set(codes)] };
+    if (ch.address || ch.shipping) {
+        const method = body.fulfillment?.methods?.[0] ?? { type: 'shipping', line_item_ids: (current.line_items ?? []).map((l) => l.id) };
+        if (ch.address) {
+            const prev = selectedDestination(current) ?? {};
+            const buyer = (body.buyer ?? {});
+            const dest = clean({ ...prev, first_name: buyer.first_name, last_name: buyer.last_name, ...ch.address, id: prev.id ?? 'dest_1' });
+            if (dest.address_country)
+                dest.address_country = String(dest.address_country).toUpperCase();
+            delete dest.type;
+            method.destinations = [dest];
+            method.selected_destination_id = dest.id;
+        }
+        if (ch.shipping)
+            method.groups = (method.groups?.length ? method.groups : [{ id: 'grp_1' }]).map((g) => ({ ...g, selected_option_id: ch.shipping }));
+        body.fulfillment = { methods: [method, ...(body.fulfillment?.methods?.slice(1) ?? [])] };
+    }
+    let call = await step(origin, () => shopping.updateCheckout(store, id, body));
+    // A store that offers shipping options without picking one: take its first, and say which in the result.
+    const group = call.body.fulfillment?.methods?.[0]?.groups?.[0];
+    if (group && !group.selected_option_id && group.options?.length) {
+        const again = replay(call.body);
+        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.
+    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));
+    }
+    return checkoutView(call.body, origin, call);
+}
+export async function cancelCheckout(origin, id) {
+    const store = await open(origin);
+    const call = await step(origin, () => shopping.cancelCheckout(store, id));
+    return checkoutView(call.body, origin, call);
+}
+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}.`);
+    }
+    const call = await step(origin, () => shopping.completeCheckout(store, id, { payment: { instruments: [sandboxInstrument(decline)] }, signals: { 'dev.ucp.user_agent': 'c11r' } }));
+    const ck = call.body;
+    if (ck.order?.id)
+        remember(ck.order.id, origin);
+    return checkoutView(ck, origin, call);
+}
+export async function getOrder(origin, id) {
+    const store = await discover(origin);
+    const call = await step(origin, () => shopping.getOrder(store, id));
+    return orderView(call.body, origin, call);
+}
+export async function ask(origin, question) {
+    const store = await discover(origin);
+    if (!store.capabilities.has('dev.ucp.common.ask'))
+        fail('ask_unsupported', `The store at ${origin} does not answer questions over UCP.`, 'Search its catalog instead: c11r ucp search <query>.');
+    const call = await step(origin, () => shopping.ask(store, { query: question }));
+    const r = call.body;
+    return { store: origin, question, answer: plain(r.answer), links: r.links, messages: r.messages, signature: sign(call) };
+}

package/package.json

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