@commercelayer/agent-cli 0.3.1 → 0.5.0

package/README.md

@@ -1,5 +1,5 @@
 # @commercelayer/agent-cli
-`c11r`, the Commerce Layer CLI for coding agents. An agent reads [commercelayer.ai/start.md](https://commercelayer.ai/start.md), runs this CLI, and the human ends up with a working store in a sandbox: products, prices, a market, a storefront at `<org>.sandbox.commercelayer.store`, and a paid test order. No account needed until they decide to keep it.
+`c11r`, the Commerce Layer CLI for coding agents. An agent reads [commercelayer.ai/start.md](https://commercelayer.ai/start.md), runs this CLI, and the human ends up with a working store in a sandbox: products, prices, a market, a storefront at `<org>.sandbox.commercelayer.store`, and a test order to approve, capture and ship. No account needed until they decide to keep it.
 Every store speaks the [Universal Commerce Protocol](https://ucp.dev) on its own hostname, so shopping agents can discover it, browse it and buy from it. The CLI itself buys through UCP (`orders test`) and checks the store against the spec (`ucp check`), so what it verifies is what any agent would get.
 It is a separate tool from [`@commercelayer/cli`](https://www.npmjs.com/package/@commercelayer/cli), the CLI for humans. The package is `@commercelayer/agent-cli`; the command is `c11r` (c, eleven letters, r), short and unmistakable in an agent's transcript.
 ```
@@ -28,10 +28,13 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `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. |
+| `orders list [--status placed\|approved\|cancelled\|editing\|all] [--payment <status>] [--fulfillment <status>] [--archived [all]] [--limit <n>]` | The store's orders, live in Commerce Layer, newest first; by default placed and approved, not archived, 25 at most (see [Orders and fulfillment](#orders-and-fulfillment)). |
+| `orders show <number or id>` | One order as the merchant sees it: line items, totals, addresses, payment and transactions, shipments, and `next`, what it waits for. |
+| `orders approve <n> [--capture]` · `capture` · `cancel` · `refund <n> [--amount <major>]` · `archive` · `unarchive` | Move an order; each prints the order after it. |
+| `fulfillment list [--status <status>\|all] [--limit <n>]` · `show <shipment>` | The shipments, by default the ones not shipped yet. A shipment is its number (`1001/S/001`), its id, or its order's number. |
+| `fulfillment hold` · `pick` · `pack` · `ready` · `ship <shipment> [--carrier] [--tracking] [--tracking-url]` · `deliver` | Move a shipment; each prints the shipment after it. |
 | `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 search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--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 with their categories, prices in major units in `price.display`, sale prices, shipping and the market the prices are for. |
 | `ucp checkout create --item <variant id>[:<qty>] … [--code <discount>] [--country <CC>]` | Open a checkout; `messages` say what is still missing (email, shipping address). |
 | `ucp checkout update <id> [--email …] [--street …] [--item <variant id>:<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`. |
@@ -119,6 +122,18 @@ COFFEE-COL-250,"Colombia Huila, 250 g",,Coffee > Single origin,12.00,13.50
 ```
 Errors name the file (and line, for CSV) and the sku, so one product file can be fixed without reading the rest. Moving a product between `store.yml` and a file is not a change to the store: `plan` keys everything by sku. The catalog has no stock: inventory is tracked live in Commerce Layer, and the sandbox treats every product as in stock. Prices in these files are what the store charges; a published storefront reads prices and availability live from Commerce Layer.
 Rules `plan` and `apply` enforce: a name, at least one market and one product; every market has `code`, `name`, `countries` and an ISO 4217 `currency`; codes and skus are unique across all files; a product has only `sku`, `name`, `description`, `image_url`, `category` and `prices`; a `category` is a path of names from the top level, separated by ` > `; an `image_url` is an `https://` URL or a path in the storefront folder such as `img/eth.jpg` (served from the store host, given to shopping agents as a full URL); every product has a price in the currency of every market; `shipping`, if present, has `method` and a non-negative `price`; policy entries are URLs. Currency, languages and tax follow from the countries.
+### Languages
+`language:` at the top of `store.yml` is the language the products are written in (ISO 639-1, default `en`). A product's `name`, `description` and `category` can also be a map with the base language and others, and a CSV takes `name_<ll>`, `description_<ll>` and `category_<ll>` columns next to the plain ones:
+```yaml
+language: en
+products:
+  - sku: ETH
+    name: { en: Ethiopia, it: Etiopia }
+    category: { en: Coffee > Single origin, it: Caffè > Monorigine }   # the same levels, each translated
+    prices: { EUR: 14.50 }
+```
+A store has at most 6 languages, the base one included. Every country gets its own pages, `/<cc>-<ll>/` (`/it-it/`), in that country's language: the product texts in it when the product has them, the base language otherwise; `/` lets the buyer choose the country when there are several. Shopping agents get the same texts over UCP, in the language they ask for. `plan` warns about a language no country of the store speaks. A store without translations plans and applies as before.
+
 ### A catalog the human edits
 When the products live in a tool the human edits too, `store.yml` names it and `c11r catalog pull` copies it into `.commercelayer/products/catalog.csv`, sorted by sku: same source, same file. Pull applies the product rules above before it writes, with errors naming the row in the source, and reports the skus added, changed and removed. Removed products leave the store only through `apply --allow-delete`. Every source has the same columns: `sku`, `name`, `description`, `image_url`, `category`, and one price column per market currency, named by its ISO 4217 code in lowercase (`eur`, `usd`).
 ```yaml
@@ -127,9 +142,9 @@ catalog:
   url: https://docs.google.com/spreadsheets/d/e/2PACX-.../pub?output=csv
   # table: products  # supabase only
 ```
-- `sheets`: a Google Sheet, by its CSV link (File > Share > Publish to web > Comma-separated values) or by its own link when anyone with the link can view it. No key.
+- `sheets`: a Google Sheet, by its CSV link (File > Share > Publish to web > Comma-separated values) or by its own link when anyone with the link can view it. No key. Translations are `name_<ll>`, `description_<ll>` and `category_<ll>` columns, in sheets and Supabase tables alike.
 - `supabase`: a table (default `products`), read over the REST API with the project's anon key: `C11R_SUPABASE_URL=https://<project>.supabase.co` and `C11R_SUPABASE_KEY=<anon key>` in `.commercelayer/credentials`, or the environment. The key needs a row level security policy that allows select. Never use the `service_role` key. Columns `id`, `created_at` and `updated_at` are skipped.
-- `merchant`: a Google Merchant Center product feed URL, RSS 2.0 (XML, `g:` namespace) or TSV. `id` is the sku, `title` the name, `description`, `image_link` the image, `price` (`14.50 EUR`) the price in its currency, `product_type` the category. An id listed once per currency is one product with several prices. Other attributes, `sale_price` included, are ignored.
+- `merchant`: a Google Merchant Center product feed URL, RSS 2.0 (XML, `g:` namespace) or TSV. `id` is the sku, `title` the name, `description`, `image_link` the image, `price` (`14.50 EUR`) the price in its currency, `product_type` the category. An id listed once per currency is one product with several prices. Other attributes, `sale_price` included, are ignored. Other languages: `catalog.translations: { it: <the Italian feed URL> }`, one feed per language, merged by `id` (`title`, `description`, `product_type`).
 Error codes: `no_catalog_source`, `invalid_catalog`, `missing_credentials`, `catalog_unreachable`, `catalog_unauthorized`, `catalog_not_found`, `catalog_not_csv`, `catalog_error`, `empty_catalog`, plus `invalid_product` and `missing_price`.
 
 ### The website
@@ -142,6 +157,12 @@ 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_storefront`, `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`.
+## Orders and fulfillment
+
+Orders land **placed** with the payment **authorized**, not taken: the store no longer approves or captures them. The merchant, through the agent, accepts an order with `orders approve <n> --capture` (or approves now and runs `orders capture <n>` later), cancels one it doesn't want (`orders cancel`, which voids the authorization; a shipped order can't be cancelled, a captured one is refunded instead), and gives money back with `orders refund <n> [--amount <major units>]` (the last of it cancels the order). `orders archive` hides an order from the list, whatever its status; `orders list --archived` shows them. Every command prints the order after it and a `next` that says what it waits for; a move the order doesn't allow answers `invalid_transition`, with the commands it allows now in the hint.
+
+Each order has one shipment, `upcoming` when placed. `fulfillment hold` works on a placed order; `pick`, `pack`, `ready` and `ship` need the order approved, and `on_hold`, `picking`, `packing` and `ready_to_ship` move freely between each other. `ship` takes the carrier's `--carrier`, `--tracking` and `--tracking-url` (https); `deliver` follows `ship`. An API older than these routes answers `orders_unsupported` or `fulfillment_unsupported`.
+
 ## 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 |
@@ -158,7 +179,7 @@ Transport rules the store enforces: `UCP-Agent` (an HTTPS platform profile URL)
 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 <variant id>:<qty>` for what they picked (the `variants[].id` search lists; the sku on Commerce Layer stores), `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): any store without it (every store taking real payments) 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`.
+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 (words in any order; `--category`, which includes the subcategories, and `--min-price`/`--max-price` in major units narrow it; the `messages` the store sends, such as its categories when nothing matched, are passed on), `ucp checkout create --item <variant id>:<qty>` for what they picked (the `variants[].id` search lists; the sku on Commerce Layer stores), `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): any store without it (every store taking real payments) 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
 

package/dist/api/client.js

@@ -50,7 +50,66 @@ export function createApi(auth) {
             throw e;
         }
     };
+    // Orders and shipments for the merchant: an API older than them answers the UCP array on GET
+    // /orders?view=merchant and not_found on the routes it lacks. A not_found on one order or
+    // shipment is checked against the list, so a missing order is still not_found.
+    const qs = (query) => {
+        const p = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== ''));
+        return p.toString() ? `&${p}` : '';
+    };
+    const ordersUnsupported = () => fail('orders_unsupported', 'This API does not manage orders for the merchant yet.', 'Try again later; tell the human if it persists. c11r orders test still places test orders.');
+    const shipmentsUnsupported = () => fail('fulfillment_unsupported', 'This API does not manage shipments yet.', 'Try again later; tell the human if it persists.');
+    const listMerchantOrders = async (query) => {
+        const r = (await request('GET', `${org()}/orders?view=merchant${qs(query)}`));
+        if (Array.isArray(r) || !Array.isArray(r.orders))
+            ordersUnsupported();
+        return r;
+    };
+    const listShipments = async (query) => {
+        try {
+            const p = new URLSearchParams(Object.entries(query).filter(([, v]) => v !== undefined && v !== ''));
+            return (await request('GET', `${org()}/shipments${p.toString() ? `?${p}` : ''}`));
+        }
+        catch (e) {
+            if (e instanceof CliError && e.code === 'not_found')
+                shipmentsUnsupported();
+            throw e;
+        }
+    };
+    const orderCall = async (call) => {
+        try {
+            return await call();
+        }
+        catch (e) {
+            if (e instanceof CliError && e.code === 'not_found')
+                await listMerchantOrders({ limit: '1' });
+            throw e;
+        }
+    };
+    const shipmentCall = async (call) => {
+        try {
+            return await call();
+        }
+        catch (e) {
+            if (e instanceof CliError && e.code === 'not_found')
+                await listShipments({ limit: '1' });
+            throw e;
+        }
+    };
+    const orderPath = (id) => `${org()}/orders/${encodeURIComponent(id)}`;
+    const shipmentPath = (id) => `${org()}/shipments/${encodeURIComponent(id)}`;
     return {
+        listMerchantOrders,
+        getMerchantOrder: (id) => orderCall(async () => {
+            const o = (await request('GET', `${orderPath(id)}?view=merchant`));
+            if (o && o.payment_status === undefined)
+                ordersUnsupported();
+            return o;
+        }),
+        orderAction: (id, action, body) => orderCall(() => request('POST', `${orderPath(id)}/${action}`, body ?? {})),
+        listShipments,
+        getShipment: (id) => shipmentCall(() => request('GET', shipmentPath(id))),
+        shipmentAction: (id, action, body) => shipmentCall(() => request('POST', `${shipmentPath(id)}/${action}`, body ?? {})),
         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))),

package/dist/api/stub/locale.js

@@ -0,0 +1,52 @@
+// Locales on the store host, as the store Worker does them: one per country, from the
+// `locales` the API derives on apply (the stub keeps them on the record). The texts come
+// from applied.products[sku].translations[ll], falling back to the base language.
+export const COOKIE = 'c11r_locale';
+export const baseLanguage = (r) => r.applied?.language ?? 'en';
+/** The languages the store has: the base one, then every language a product is translated into. */
+export function languagesOf(r) {
+    const out = new Set([baseLanguage(r)]);
+    for (const p of Object.values(r.applied?.products ?? {}))
+        for (const ll of Object.keys(p.translations ?? {}))
+            out.add(ll);
+    return out;
+}
+/** A product's name, description and category in a language, falling back to the base one. */
+export function texts(p, ll) {
+    const t = p.translations?.[ll] ?? {};
+    return { name: t.name ?? p.name, description: t.description ?? p.description, category: t.category ?? p.category };
+}
+/** The store's locales; none before an apply that derived them (the site stays as it was). */
+export const localesOf = (r) => r.locales ?? [];
+/** The locale at /<path>/, by its country: a known country with the wrong language still matches. */
+export const localeOfCountry = (r, country) => localesOf(r).find((l) => l.country === country.toUpperCase());
+/** The locale a cookie names, if it is one of the store's. */
+export function cookieLocale(r, cookie) {
+    const m = cookie?.match(new RegExp(`(?:^|;\\s*)${COOKIE}=([a-z]{2}-[a-z]{2})`));
+    return m ? localesOf(r).find((l) => l.path === m[1]) : undefined;
+}
+/** The locale of a product URL for a market: the buyer's country when it is in the market, else the market's first. */
+export function marketLocale(r, market, country) {
+    const ls = localesOf(r).filter((l) => l.market === market);
+    return ls.find((l) => country && l.country === country.toUpperCase()) ?? ls[0];
+}
+/**
+ * The language of a UCP catalog answer: context.language (primary subtag), else the first
+ * Accept-Language the store has, else the language of the buyer's country's locale, else the base.
+ */
+export function ucpLanguage(r, context, acceptLanguage) {
+    const has = languagesOf(r);
+    const primary = (tag) => tag.trim().split(/[-_;]/)[0].toLowerCase();
+    const asked = typeof context?.language === 'string' ? primary(context.language) : '';
+    if (has.has(asked))
+        return asked;
+    for (const part of (acceptLanguage ?? '').split(',')) {
+        const ll = primary(part);
+        if (ll && has.has(ll))
+            return ll;
+    }
+    const country = typeof context?.address_country === 'string' ? localeOfCountry(r, context.address_country) : undefined;
+    if (country && has.has(country.language))
+        return country.language;
+    return baseLanguage(r);
+}

package/dist/api/stub/management.js

@@ -3,11 +3,13 @@
 import crypto from 'node:crypto';
 import { canonical, IMAGE_PATH } from '../../store.js';
 import { generateKey } from '../../ucp/signing.js';
+import { localesOf } from '../../locales.js';
 import { publicOrders, readDb, SANDBOX_DOMAIN, writeDb } from './db.js';
 import { bearer, error, json, readJson } from './http.js';
+import { listOrders, listShipments, OrderError, orderAction, shipmentAction, showOrder, showShipment } from './orders.js';
 function publicState(r) {
     const { token: _token, ucp: _ucp, pending: _pending, asset_files: _files, ...state } = r;
-    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, storefront_mode: r.storefront_mode ?? 'hosted', assets: r.assets ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, storefront_mode: r.storefront_mode ?? 'hosted', locales: r.locales ?? [], assets: r.assets ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
 }
 /** Like Commerce Layer refusing a sku in an import. Only the stub does this, so tests can exercise apply_failed. */
 const REFUSED = /^REFUSED-/;
@@ -175,6 +177,8 @@ export function handleManagement(req) {
             return error(409, 'deletes_need_approval', `Apply would delete product ${removed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
         // The name, policies and markets apply in the request; products go through an
         // import job (SKUs, prices, then cleanups for removals) when any changed.
+        // Locales come from the markets, which apply in the request, as the API derives them.
+        record.locales = localesOf(applied);
         record.name = name;
         record.policies = policies ?? {};
         if (theme !== undefined)
@@ -190,7 +194,9 @@ export function handleManagement(req) {
                 }
             }
         }
-        const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || canonical(before[sku]) !== canonical(applied.products[sku]));
+        // Translations live in applied only: changing them makes no Commerce Layer call, like the API.
+        const commerce = (p) => canonical(p && { ...p, translations: undefined });
+        const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || commerce(before[sku]) !== commerce(applied.products[sku]));
         if (changed.length === 0 && removed.length === 0) {
             record.applied = applied;
             record.applied_hash = hash;
@@ -339,9 +345,39 @@ export function handleManagement(req) {
         writeDb(db);
         return json(200, record.storefront);
     }
+    // The merchant's orders and shipments (view=merchant); a bare GET /orders stays the UCP list older CLIs read.
+    const merchant = (run, save = false) => {
+        try {
+            const out = run();
+            if (save)
+                writeDb(db);
+            return json(200, out);
+        }
+        catch (e) {
+            if (e instanceof OrderError)
+                return error(e.status, e.code, e.message, e.hint);
+            throw e;
+        }
+    };
+    const q = req.url.searchParams;
+    const merchantView = q.get('view') === 'merchant';
+    if (req.method === 'GET' && rest === '/orders' && merchantView)
+        return merchant(() => listOrders(record, q));
+    const act = rest.match(/^\/orders\/([^/]+)\/(approve|capture|cancel|refund|archive|unarchive)$/);
+    if (req.method === 'POST' && act)
+        return merchant(() => orderAction(record, decodeURIComponent(act[1]), act[2], readJson(req) ?? {}), true);
+    if (req.method === 'GET' && rest === '/shipments')
+        return merchant(() => listShipments(record, q));
+    const ship = rest.match(/^\/shipments\/(.+?)(?:\/(hold|pick|pack|ready|ship|deliver))?$/);
+    if (ship && req.method === 'POST' && ship[2])
+        return merchant(() => shipmentAction(record, decodeURIComponent(ship[1]), ship[2], readJson(req) ?? {}), true);
+    if (ship && req.method === 'GET' && !ship[2])
+        return merchant(() => showShipment(record, decodeURIComponent(ship[1])));
     if (req.method === 'GET' && rest === '/orders')
         return json(200, publicOrders(record));
     const one = rest.match(/^\/orders\/([^/]+)$/);
+    if (req.method === 'GET' && one && merchantView)
+        return merchant(() => showOrder(record, decodeURIComponent(one[1])));
     if (req.method === 'GET' && one) {
         const wanted = decodeURIComponent(one[1]);
         const found = publicOrders(record).find((o) => o.id === wanted || o.label === wanted || o.label === `#${wanted}`);

package/dist/api/stub/orders.js

@@ -0,0 +1,359 @@
+// Orders and shipments as the merchant manages them, the API's view=merchant and
+// /shipments routes: the stub keeps the Commerce Layer state machine on each UCP
+// order, in _merchant, so the tests cover the same transitions as the platform.
+//
+// An order lands placed with its payment authorized. approve (optionally with
+// capture), capture, cancel, refund, archive and unarchive move it; its one shipment
+// goes upcoming → on_hold | picking | packing | ready_to_ship → shipped → delivered.
+import { money } from '../../ucp/shop.js';
+import { minorUnits } from '../../ucp/platform.js';
+import { baseLanguage } from './locale.js';
+export const ORDER_STATUSES = ['placed', 'approved', 'cancelled', 'editing'];
+export const PAYMENT_STATUSES = ['unpaid', 'authorized', 'partially_authorized', 'paid', 'partially_paid', 'voided', 'partially_voided', 'refunded', 'partially_refunded', 'free'];
+export const FULFILLMENT_STATUSES = ['unfulfilled', 'in_progress', 'fulfilled', 'not_required'];
+export const SHIPMENT_STATUSES = ['upcoming', 'on_hold', 'picking', 'packing', 'ready_to_ship', 'shipped', 'delivered', 'cancelled'];
+const OPEN_SHIPMENTS = ['upcoming', 'on_hold', 'picking', 'packing', 'ready_to_ship'];
+const WORKING = ['on_hold', 'picking', 'packing', 'ready_to_ship'];
+export class OrderError extends Error {
+    status;
+    code;
+    hint;
+    constructor(status, code, message, hint) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+const now = () => new Date().toISOString();
+const number = (o) => o.label.replace(/^#/, '');
+const total = (o) => o.totals.find((t) => t.type === 'total')?.amount ?? 0;
+const sum = (o, type) => merchant(o).transactions.filter((t) => t.type === type && t.succeeded).reduce((s, t) => s + t.amount, 0);
+/** The merchant state of an order, created on first use as Commerce Layer has it after placement. */
+function merchant(o) {
+    if (!o._merchant) {
+        const at = o._placed_at ?? now();
+        o._merchant = {
+            status: 'placed',
+            placed_at: at,
+            archived_at: null,
+            transactions: [{ type: 'authorization', amount: total(o), succeeded: true, at }],
+            shipment: { id: `shp_${o.id.replace(/^ord_/, '')}`, number: `${number(o)}/S/001`, status: 'upcoming', tracking: null, dates: { created_at: at, on_hold_at: null, picking_at: null, packing_at: null, ready_to_ship_at: null, shipped_at: null, delivered_at: null } },
+        };
+    }
+    return o._merchant;
+}
+function paymentStatus(o) {
+    if (total(o) === 0)
+        return 'free';
+    const captured = sum(o, 'capture');
+    const refunded = sum(o, 'refund');
+    if (sum(o, 'void') > 0)
+        return 'voided';
+    if (refunded > 0)
+        return refunded >= captured ? 'refunded' : 'partially_refunded';
+    if (captured > 0)
+        return captured >= total(o) ? 'paid' : 'partially_paid';
+    return 'authorized';
+}
+function fulfillmentStatus(o) {
+    const s = merchant(o).shipment.status;
+    if (s === 'shipped' || s === 'delivered')
+        return 'fulfilled';
+    if (WORKING.includes(s))
+        return 'in_progress';
+    return 'unfulfilled';
+}
+const destination = (o) => o.fulfillment?.expectations?.[0]?.destination ?? {};
+const units = (o) => o.line_items.reduce((s, l) => s + (l.quantity?.total ?? l.quantity ?? 0), 0);
+function shipmentRef(o) {
+    const s = merchant(o).shipment;
+    return { id: s.id, number: s.number, status: s.status, tracking: s.tracking };
+}
+function row(o) {
+    const m = merchant(o);
+    return {
+        id: o.id,
+        number: number(o),
+        status: m.status,
+        payment_status: paymentStatus(o),
+        fulfillment_status: fulfillmentStatus(o),
+        placed_at: m.placed_at,
+        market: o._market ?? null,
+        country: destination(o).address_country ?? null,
+        currency: o.currency,
+        total: money(total(o), o.currency),
+        email: o._buyer?.email ?? null,
+        items: units(o),
+        shipments: [shipmentRef(o)],
+        archived: m.archived_at !== null,
+    };
+}
+function address(o) {
+    const d = destination(o);
+    if (!Object.keys(d).length)
+        return null;
+    return {
+        name: [d.first_name, d.last_name].filter(Boolean).join(' ') || null,
+        company: null,
+        line_1: d.street_address ?? null,
+        line_2: d.extended_address ?? null,
+        city: d.address_locality ?? null,
+        zip_code: d.postal_code ?? null,
+        state_code: d.address_region ?? null,
+        country_code: d.address_country ?? null,
+        phone: o._buyer?.phone_number ?? null,
+    };
+}
+function detail(o, r) {
+    const m = merchant(o);
+    const cur = o.currency;
+    const amount = (type) => o.totals.filter((t) => t.type === type).reduce((s, t) => s + t.amount, 0);
+    const captured = sum(o, 'capture') - sum(o, 'refund');
+    return {
+        ...row(o),
+        line_items: o.line_items.map((l) => ({
+            item_id: l.item?.id,
+            sku: l.item?.id,
+            name: l.item?.title,
+            quantity: l.quantity?.total ?? l.quantity,
+            unit_price: money(l.item?.price ?? 0, cur),
+            total: money(l.totals?.find((t) => t.type === 'total')?.amount ?? 0, cur),
+        })),
+        totals: { subtotal: money(amount('subtotal'), cur), discount: money(amount('discount'), cur), shipping: money(amount('fulfillment'), cur), taxes: money(amount('tax'), cur), total: money(total(o), cur), codes: o._codes ?? [] },
+        shipping_address: address(o),
+        billing_address: address(o),
+        shipping_method: o.fulfillment?.expectations?.[0]?.description ?? null,
+        payment: { method: 'Sandbox', source: 'sandbox wire transfer', status: paymentStatus(o), captured: money(Math.max(0, sum(o, 'capture')), cur), refundable: money(Math.max(0, captured), cur) },
+        transactions: m.transactions.map((t) => ({ ...t, amount: money(t.amount, cur) })),
+        language: o._language ?? baseLanguage(r),
+        archived_at: m.archived_at,
+        ucp: { id: o.id, permalink_url: o.permalink_url },
+    };
+}
+const orders = (r) => Object.values(r.ucp.orders).slice().reverse();
+/** An order by id, number, #number, or the checkout or cart it came from. */
+function findOrder(r, wanted) {
+    const o = orders(r).find((x) => x.id === wanted || x.label === wanted || x.label === `#${wanted}` || x.checkout_id === wanted || x._cart_id === wanted);
+    if (!o)
+        throw new OrderError(404, 'not_found', `There is no order ${wanted}.`, 'Run `c11r orders list` to see the orders.');
+    return o;
+}
+/** The commands an order allows now, as the API names them in its hints. */
+function orderCommands(o) {
+    const m = merchant(o);
+    const n = number(o);
+    const pay = paymentStatus(o);
+    const out = [];
+    if (m.status === 'placed')
+        out.push(`c11r orders approve ${n} [--capture]`);
+    if (m.status === 'approved' && pay === 'authorized')
+        out.push(`c11r orders capture ${n}`);
+    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status) && ['authorized', 'free'].includes(pay))
+        out.push(`c11r orders cancel ${n}`);
+    if (['paid', 'partially_refunded'].includes(pay))
+        out.push(`c11r orders refund ${n} [--amount <major>]`);
+    out.push(m.archived_at ? `c11r orders unarchive ${n}` : `c11r orders archive ${n}`);
+    return out;
+}
+const refuse = (what, allowed) => {
+    throw new OrderError(422, 'invalid_transition', what, `Allowed now: ${allowed.join('; ')}.`);
+};
+export function listOrders(r, q) {
+    const list = (name, allowed, fallback) => {
+        const raw = q.get(name);
+        if (!raw)
+            return fallback;
+        const vs = raw.split(',').map((v) => v.trim());
+        if (vs.includes('all'))
+            return allowed;
+        for (const v of vs)
+            if (!allowed.includes(v))
+                throw new OrderError(422, 'invalid_argument', `${name}=${v} is not one of ${allowed.join(', ')}, all.`, `Use --${name} with one of ${allowed.join(', ')}, or all.`);
+        return vs;
+    };
+    const statuses = list('status', ORDER_STATUSES, ['placed', 'approved']);
+    const payments = list('payment', PAYMENT_STATUSES, PAYMENT_STATUSES);
+    const fulfillments = list('fulfillment', FULFILLMENT_STATUSES, FULFILLMENT_STATUSES);
+    const archived = q.get('archived') ?? 'false';
+    if (!['true', 'false', 'all'].includes(archived))
+        throw new OrderError(422, 'invalid_argument', `archived=${archived} is not true, false or all.`, 'Use --archived for only archived orders, --archived all for every order.');
+    const limit = q.get('limit') === null ? 25 : Number(q.get('limit'));
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new OrderError(422, 'invalid_argument', `limit=${q.get('limit')} is not between 1 and 100.`, 'Use --limit with a number from 1 to 100.');
+    const rows = orders(r)
+        .map(row)
+        // Archived orders are listed only when asked for, whatever their status.
+        .filter((x) => (archived === 'all' ? true : archived === 'true' ? x.archived : !x.archived))
+        .filter((x) => (archived === 'true' && !q.get('status') ? true : statuses.includes(x.status)))
+        .filter((x) => payments.includes(x.payment_status) && fulfillments.includes(x.fulfillment_status));
+    return { orders: rows.slice(0, limit) };
+}
+export const showOrder = (r, id) => detail(findOrder(r, id), r);
+export function orderAction(r, id, action, body) {
+    const o = findOrder(r, id);
+    const m = merchant(o);
+    const at = now();
+    const capture = () => {
+        m.transactions.push({ type: 'capture', amount: total(o) - sum(o, 'capture'), succeeded: true, at });
+    };
+    switch (action) {
+        case 'approve':
+            if (m.status !== 'placed')
+                refuse(`Order ${number(o)} is ${m.status}: only a placed order can be approved.`, orderCommands(o));
+            m.status = 'approved';
+            if (body?.capture === true && paymentStatus(o) === 'authorized')
+                capture();
+            break;
+        case 'capture':
+            if (m.status !== 'approved' || paymentStatus(o) !== 'authorized')
+                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an approved order with an authorized payment can be captured.`, orderCommands(o));
+            capture();
+            break;
+        case 'cancel':
+            if (m.status === 'cancelled')
+                refuse(`Order ${number(o)} is already cancelled.`, orderCommands(o));
+            if (['shipped', 'delivered'].includes(m.shipment.status))
+                refuse(`Order ${number(o)} has shipped: it cannot be cancelled.`, orderCommands(o));
+            if (!['authorized', 'free'].includes(paymentStatus(o)))
+                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: refund it to cancel it.`, orderCommands(o));
+            if (paymentStatus(o) === 'authorized')
+                m.transactions.push({ type: 'void', amount: total(o), succeeded: true, at });
+            m.status = 'cancelled';
+            m.shipment.status = 'cancelled';
+            break;
+        case 'refund': {
+            if (!['paid', 'partially_refunded'].includes(paymentStatus(o)))
+                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: only a captured payment can be refunded.`, orderCommands(o));
+            const refundable = sum(o, 'capture') - sum(o, 'refund');
+            let amount = refundable;
+            if (body?.amount !== undefined) {
+                if (typeof body.amount !== 'number' || !Number.isFinite(body.amount) || body.amount <= 0)
+                    throw new OrderError(422, 'invalid_argument', `amount ${body.amount} is not a positive number.`, 'Give --amount in major units, for example --amount 4.50, or leave it out to refund everything still refundable.');
+                amount = Math.round(body.amount * minorUnits(o.currency));
+                if (amount > refundable)
+                    throw new OrderError(422, 'refund_exceeds', `${money(amount, o.currency).display} is more than the ${money(refundable, o.currency).display} still refundable on order ${number(o)}.`, `Refund at most ${money(refundable, o.currency).major}, or leave --amount out to refund all of it.`);
+            }
+            m.transactions.push({ type: 'refund', amount, succeeded: true, at });
+            // As in Commerce Layer: refunding the last of the payment cancels the order.
+            if (sum(o, 'refund') >= sum(o, 'capture')) {
+                m.status = 'cancelled';
+                if (OPEN_SHIPMENTS.includes(m.shipment.status))
+                    m.shipment.status = 'cancelled';
+            }
+            break;
+        }
+        case 'archive':
+            m.archived_at ??= at;
+            break;
+        case 'unarchive':
+            m.archived_at = null;
+            break;
+        default:
+            throw new OrderError(404, 'not_found', `No order action ${action}.`, 'Use approve, capture, cancel, refund, archive or unarchive.');
+    }
+    return detail(o, r);
+}
+// ---------- shipments
+function shipmentRow(o) {
+    const s = merchant(o).shipment;
+    return {
+        id: s.id,
+        number: s.number,
+        status: s.status,
+        order: { id: o.id, number: number(o), status: merchant(o).status },
+        country: destination(o).address_country ?? null,
+        shipping_method: o.fulfillment?.expectations?.[0]?.description ?? null,
+        items: units(o),
+        tracking: s.tracking,
+        dates: { ...s.dates },
+    };
+}
+/** A shipment by id or number, or the one shipment of an order by its id or number. */
+function findShipment(r, wanted) {
+    const o = orders(r).find((x) => merchant(x).shipment.id === wanted || merchant(x).shipment.number === wanted) ?? orders(r).find((x) => x.id === wanted || x.label === wanted || x.label === `#${wanted}`);
+    if (!o)
+        throw new OrderError(404, 'not_found', `There is no shipment ${wanted}.`, 'Run `c11r fulfillment list` to see the shipments.');
+    return o;
+}
+function shipmentCommands(o) {
+    const s = merchant(o).shipment;
+    const approved = merchant(o).status === 'approved';
+    const n = s.number;
+    const out = [];
+    const can = (cmd, ok) => ok && out.push(`c11r fulfillment ${cmd} ${n}`);
+    can('hold', ['upcoming', 'picking', 'packing', 'ready_to_ship'].includes(s.status) && merchant(o).status !== 'cancelled');
+    can('pick', approved && ['upcoming', 'on_hold', 'packing', 'ready_to_ship'].includes(s.status));
+    can('pack', approved && ['on_hold', 'picking', 'ready_to_ship'].includes(s.status));
+    can('ready', approved && ['on_hold', 'picking', 'packing'].includes(s.status));
+    can('ship', approved && OPEN_SHIPMENTS.includes(s.status));
+    can('deliver', s.status === 'shipped');
+    if (!out.length && merchant(o).status === 'placed')
+        out.push(`c11r orders approve ${number(o)} [--capture]`);
+    return out;
+}
+export function listShipments(r, q) {
+    const raw = q.get('status');
+    let statuses = [...OPEN_SHIPMENTS];
+    if (raw) {
+        const vs = raw.split(',').map((v) => v.trim());
+        if (vs.includes('all'))
+            statuses = SHIPMENT_STATUSES;
+        else {
+            for (const v of vs)
+                if (!SHIPMENT_STATUSES.includes(v))
+                    throw new OrderError(422, 'invalid_argument', `status=${v} is not one of ${SHIPMENT_STATUSES.join(', ')}, all.`, `Use --status with one of ${SHIPMENT_STATUSES.join(', ')}, or all.`);
+            statuses = vs;
+        }
+    }
+    const limit = q.get('limit') === null ? 25 : Number(q.get('limit'));
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new OrderError(422, 'invalid_argument', `limit=${q.get('limit')} is not between 1 and 100.`, 'Use --limit with a number from 1 to 100.');
+    return { shipments: orders(r).filter((o) => statuses.includes(merchant(o).shipment.status)).map(shipmentRow).slice(0, limit) };
+}
+export function showShipment(r, id) {
+    const o = findShipment(r, id);
+    return { ...shipmentRow(o), line_items: o.line_items.map((l) => ({ sku: l.item?.id, name: l.item?.title, quantity: l.quantity?.total ?? l.quantity })), address: address(o), parcels: [] };
+}
+const URL_RE = /^https:\/\/\S+$/;
+export function shipmentAction(r, id, action, body) {
+    const o = findShipment(r, id);
+    const m = merchant(o);
+    const s = m.shipment;
+    const at = now();
+    const move = (to, from, needsApproved) => {
+        if (!from.includes(s.status) || (needsApproved && m.status !== 'approved') || m.status === 'cancelled') {
+            const why = needsApproved && m.status !== 'approved' ? `its order ${number(o)} is ${m.status}` : `it is ${s.status}`;
+            refuse(`Shipment ${s.number} cannot go ${to.replace(/_/g, ' ')}: ${why}.`, shipmentCommands(o));
+        }
+        s.status = to;
+        s.dates[`${to}_at`] = at;
+    };
+    switch (action) {
+        case 'hold':
+            return move('on_hold', ['upcoming', 'picking', 'packing', 'ready_to_ship'], false), showShipment(r, s.id);
+        case 'pick':
+            return move('picking', ['upcoming', 'on_hold', 'packing', 'ready_to_ship'], true), showShipment(r, s.id);
+        case 'pack':
+            return move('packing', ['on_hold', 'picking', 'ready_to_ship'], true), showShipment(r, s.id);
+        case 'ready':
+            return move('ready_to_ship', ['on_hold', 'picking', 'packing'], true), showShipment(r, s.id);
+        case 'ship': {
+            for (const k of ['carrier', 'tracking', 'tracking_url']) {
+                const v = body?.[k];
+                if (v !== undefined && (typeof v !== 'string' || !v.trim() || v.length > 255))
+                    throw new OrderError(422, 'invalid_argument', `${k} must be text of 1 to 255 characters.`, `Give --${k.replace('_', '-')} a value, or leave it out.`);
+            }
+            if (body?.tracking_url !== undefined && !URL_RE.test(body.tracking_url))
+                throw new OrderError(422, 'invalid_argument', `tracking_url ${body.tracking_url} is not an https URL.`, 'Give --tracking-url the carrier\'s tracking page, starting with https://.');
+            move('shipped', OPEN_SHIPMENTS, true);
+            if (body?.carrier || body?.tracking || body?.tracking_url)
+                s.tracking = { carrier: body.carrier, number: body.tracking, url: body.tracking_url };
+            return showShipment(r, s.id);
+        }
+        case 'deliver':
+            return move('delivered', ['shipped'], false), showShipment(r, s.id);
+        default:
+            throw new OrderError(404, 'not_found', `No shipment action ${action}.`, 'Use hold, pick, pack, ready, ship or deliver.');
+    }
+}