@commercelayer/agent-cli 0.3.1 → 0.5.1

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.
 ```
@@ -10,6 +10,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 - **The website comes with the store.** Every store has a hosted theme at its preview URL, set by a few `theme:` settings and the product data: `apply` is all it takes. A custom storefront (your own web app) is opt-in: `storefront init`, `publish` and `check`.
 - **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
 - **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
+- **Always current.** Run it as `npx -y @commercelayer/agent-cli@latest`, even where a `c11r` binary is installed; the note `init` writes in `AGENTS.md` and `CLAUDE.md` says so. The CLI sends `User-Agent: c11r/<version> (node/<major>)`, and an outdated one gets a `cli_outdated` entry in `warnings`, with `current`, `latest` and a `hint`.
 - **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it. The keys of a catalog source go in the same file.
 ## Commands
 | Command | Does |
@@ -28,18 +29,21 @@ 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`. |
 | `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 store that speaks UCP. |
 | `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. |
+| `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 store's semantic search index (`search`: model, status, vectors, embedded, updated_at, error; null before its first run), the UCP profile URL. |
 | `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
-| `help [<command>]` | Describe the commands. `--version` prints the version. |
+| `help [<command>]` | Describe the commands. `--version` prints the version and `latest_hint`, how to always run the newest. |
 ## store.yml
 `init` writes a commented template. A filled-in store looks like this:
 ```yaml
@@ -119,6 +123,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 +143,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 +158,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 +180,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

@@ -1,5 +1,6 @@
 // The client for the management API at api.commercelayer.ai.
-import { CliError, fail } from '../output.js';
+import { CliError, fail, notice } from '../output.js';
+import { NPX } from '../version.js';
 import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
 export function createApi(auth) {
     const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
@@ -20,6 +21,19 @@ export function createApi(auth) {
         catch {
             fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
         }
+        // The API flags an outdated CLI (from the User-Agent) in warnings, on any answer, errors included.
+        const warnings = data && typeof data === 'object' && !Array.isArray(data) ? data.warnings : undefined;
+        if (Array.isArray(warnings)) {
+            const isOutdated = (w) => !!w && typeof w === 'object' && w.code === 'cli_outdated';
+            for (const n of warnings.filter(isOutdated))
+                notice({ ...n, hint: n.hint ?? `Run the commands with ${NPX}. If c11r is installed globally, tell the human it is on ${n.current} and ${n.latest} exists.` });
+            // Printed once, at the top of the output, not inside the order or store it came with.
+            const rest = warnings.filter((w) => !isOutdated(w));
+            if (rest.length)
+                data.warnings = rest;
+            else
+                delete data.warnings;
+        }
         if (res.status < 400)
             return data;
         const err = data?.error;
@@ -50,7 +64,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/index.js

@@ -16,7 +16,7 @@ export function handle(req) {
         url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
     const org = orgOfHost(url.hostname);
     if (org === null)
-        return handleManagement({ ...req, url });
+        return outdated(req, handleManagement({ ...req, url }));
     const db = readDb();
     const store = db[org];
     if (!store)
@@ -25,3 +25,28 @@ export function handle(req) {
     writeDb(db);
     return res;
 }
+/** "0.5.1" → [0, 5, 1], for comparing versions. */
+const parts = (v) => v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+const older = (a, b) => {
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) < (y[i] ?? 0);
+    return false;
+};
+/**
+ * Like the API: a CLI whose User-Agent (c11r/<version>) is older than the latest gets a
+ * cli_outdated warning on every JSON object it is answered. The stub's latest is
+ * C11R_STUB_LATEST_CLI; unset, every CLI is current.
+ */
+function outdated(req, res) {
+    const latest = process.env.C11R_STUB_LATEST_CLI;
+    const current = req.headers['user-agent']?.match(/^c11r\/(\d+\.\d+\.\d+)/)?.[1];
+    if (!latest || !current || !older(current, latest) || !res.body)
+        return res;
+    const body = JSON.parse(res.body);
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return res;
+    const warning = { code: 'cli_outdated', current, latest, hint: `Run the commands with npx -y @commercelayer/agent-cli@latest. If c11r is installed globally, tell the human it is on ${current} and ${latest} exists.` };
+    return { ...res, body: JSON.stringify({ ...body, warnings: [...(Array.isArray(body.warnings) ? body.warnings : []), warning] }) };
+}

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}`);