@commercelayer/agent-cli 1.0.0-dev.12 → 1.0.0-dev.13

package/README.md

@@ -15,7 +15,7 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
 - A ref flag, or one the schema marks `nullable`, given `null` or an empty value sends `null` and takes it off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`, `c11r orders update 1001 --coupon-code null` sends `coupon_code: null`. A ref the schema marks `nullable: false`, and any other field, sends the text.
-- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
+- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (`--payment-settings "Invoice, 60 days"`); an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
 - A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
 - A field with documented values the API does not enforce (`known`: webhook topics) takes any value. One outside them is sent anyway, with the warning `unknown_value` and `did_you_mean`. Help lists up to 20 of them, and past that says how many and that `c11r schema <noun>` has them all.
@@ -35,6 +35,8 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `c11r report sales [--from] [--to] [--by] [--interval] [--market] [--top]` | Sales in a window, from the Metrics API. A plain noun: its flags come from the API's schema. |
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
+| `c11r shop profile\|search\|get\|ask <store>` | Reading a store that speaks UCP, as a shopping agent: what it offers, its catalog, a variant, a question. No organization. See below. |
+| `c11r shop checkout <store> [<checkout>]`, `shop order <store> <checkout>` | Buying there for the human: their details after their yes on what is shared, then the payment after their yes on the total, with the sandbox test handler only. |
 
 A loop runs a skill a Manage or Report noun's schema names in `loop.skill`, or in `loop.skills` for a noun with several (`manage-orders`, `manage-stock`, `report-sales`, `report-pending`, ...); a report loop allows no verb and only reports. create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
 
@@ -83,7 +85,7 @@ Records that share a key (two shipping methods with the same name in one market,
 
 After a Configure write that went through (create, update, delete or a domain verb), in a folder whose `store.yml` names the same organization, the answer warns `config_drift` and `.c11r/drift` notes the write; `config plan` repeats the warning, and `config export` clears it.
 
-`c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
+`c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. The file must be inside the project folder: a path that leads out of it, by `..`, an absolute path or a symlink, is refused with `invalid_value` on `out` before anything is sent. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
 
 `c11r exports get <id> --out <file>` downloads a completed export while its link lasts (5 minutes), unzipped unless the name ends in `.gz`; `--wait` reads the job again until it completes.
 
@@ -128,6 +130,17 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 
 `rate_limited` is retried twice with a short backoff, for reads and writes: nothing was processed. `commercelayer_busy` and `commercelayer_unavailable` are retried for reads only; a write that may have reached Commerce Layer fails with its next step. The one exception is `sandbox create`: it sends a fresh `Idempotency-Key`, and after a 5xx or a lost connection it repeats the create with the same key, so the API answers the sandbox it made and its token is stored. Each retry waits as long as the API says (`retry_after` seconds in the error, or the `Retry-After` header), at most 30 seconds; without it, 1 then 3 seconds. When the API asks for longer than 30 seconds, the CLI does not wait: the error goes to the agent, with `retry_after`, to plan around. Each retry writes a line to stderr.
 
+## Shop
+
+`c11r shop` buys for the human from any store that speaks UCP. The CLI talks to the store directly, with no organization and no call to the API. `<store>` is the store's host (`shop.example.com`) or an https URL on it.
+
+- Every call carries `UCP-Agent: profile="https://commercelayer.ai/ucp/agent-cli/profile.json"`, a `Request-Id`, a `Content-Digest` with a body, and an `Idempotency-Key` on a write. The CLI holds no keys and signs no request. The store's answers are checked against the keys its `/.well-known/ucp` publishes: a digest that does not match, or a signature that does not verify, is `invalid_response` and the answer is not used. An unsigned answer warns `answer_unsigned`. A store that wants signed requests is `not_supported`.
+- `profile`, `search`, `get` and `ask` only read. `get` and `ask` take the variant or the question as the bare value after the store.
+- `checkout` opens a checkout with `--item ID=QTY` (repeated) and the buyer's `--email`, `--first-name`, `--last-name`, `--phone` and `--address.street`, `--address.line-2`, `--address.locality`, `--address.postal-code`, `--address.region`, `--address.country`, all but the line 2 and the region required. Each is the human's, never invented: a missing one is `missing_value` with a human step. Before any of them is sent, `confirmation_required` shows every value and the host (`Sharing with shop.example.com: Ada Lovelace, ada@example.com, ...`); the agent asks the human and, on their yes, runs it again with `--yes`. `checkout <store> <checkout>` changes one (items, the buyer, the address, `--shipping <option>`), or with nothing to change reads it again. The answer has the totals with shipping and, when it is ready, `next` is the order.
+- `order <store> <checkout>` shows the total and asks the same way, then pays with the sandbox test handler (`ai.commercelayer.sandbox`), where no money moves, and answers the order. On a checkout already paid it answers the order and pays nothing. A checkout that is not ready is `invalid_transition`: when the store's messages name the fields it still needs, `next_step` is the command with their flags (`--phone PHONE`), and when they do not, it is a human step at the store's checkout page; a declined payment is `store_refused` with the store's words.
+- The CLI has no flag for card data. A store without the sandbox handler is `payment_handler_unsupported` before anything of the human's is sent, with the store's URL for the human to buy there in person.
+- With `--dry-run`, checkout answers what it would send and order the total it would pay: nothing is sent.
+
 ## Environment
 
 | Variable | What it does |

package/dist/argv.js

@@ -181,9 +181,10 @@ export function coerce(key, spec, raw) {
             // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
             if (item === 'object')
                 return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
-            // An in filter on names or text takes the value whole: a name may have a comma ("UK VAT, manual").
-            // Several are the flag repeated, or a JSON array. Enums, numbers and dates still split on commas.
-            if (spec.filter?.op === 'in' && (item === 'string' || item === 'ref'))
+            // A name or text is one value per flag, in a filter or not: a name may have a comma
+            // ("Invoice, 60 days"). Several are the flag repeated, or a JSON array. Enums, numbers and
+            // dates still split on commas.
+            if (item === 'string' || item === 'ref')
                 return [raw];
             return raw
                 .split(',')

package/dist/builtins/extensions.js

@@ -11,7 +11,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import zlib from 'node:zlib';
-import { credentialsFile, hintOf, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
+import { credentialsFile, hintOf, projectDir, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
@@ -272,19 +272,49 @@ export const exports = {
         return { ...r, data: { ...rest, file, bytes: bytes.length, unzipped: zipped && !file.endsWith('.gz') } };
     },
 };
+/** Where a path really lands: symlinks followed, dangling ones too, and the missing rest as written. */
+function realPath(p, hops = 0) {
+    let st = null;
+    try {
+        st = fs.lstatSync(p);
+    }
+    catch {
+        st = null;
+    }
+    if (st?.isSymbolicLink() && hops < 40)
+        return realPath(path.resolve(realPath(path.dirname(p), hops + 1), fs.readlinkSync(p)), hops + 1);
+    if (st)
+        return fs.realpathSync(p);
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(realPath(parent, hops), path.basename(p));
+}
+/**
+ * --out resolved from here, refused (invalid_value on out) when it lands outside the project folder:
+ * by .., by an absolute path, or by a symlink on the way (the file itself or a folder above it).
+ */
+function insideProject(out) {
+    const file = path.resolve(out);
+    const root = fs.realpathSync(projectDir());
+    const target = realPath(file);
+    const rel = path.relative(root, target);
+    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        fail('invalid_value', `--out ${out} is outside the project folder ${root}: c11r writes only inside it.`, { path: 'out', details: { project: root, resolved: target } });
+    }
+    return file;
+}
 // scaffold (46): drop-in --out writes the snippet as one HTML file, its head part and its body part
 // each under a comment saying where it goes. It never replaces a different file without --yes.
 export const scaffold = {
     flags: {
         'drop-in': {
-            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. A different file there is replaced only with --yes.' },
+            out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. It must be inside the project folder. A different file there is replaced only with --yes.' },
         },
     },
     async run(run) {
         const out = run.parsed.values.out;
         if (run.verb.name !== 'drop-in' || !out)
             return undefined;
-        const file = path.resolve(out);
+        const file = insideProject(out);
         // Before anything is sent: a different file there stays without --yes.
         const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
         const r = await run.send(resourceRequest('scaffold', run.verb, undefined, run.parsed.values));

package/dist/builtins/index.js

@@ -4,5 +4,6 @@
 import { auth } from './auth.js';
 import { loops } from './loops.js';
 import { sandbox, status } from './sandbox.js';
-export const builtins = { sandbox, status, loops, auth };
+import { shop } from './shop.js';
+export const builtins = { sandbox, status, loops, auth, shop };
 export { extensions } from './extensions.js';

package/dist/builtins/loops.js

@@ -21,7 +21,7 @@ const policyFlags = (required) => [
     { name: 'skill', type: 'string', required, description: 'The skill the loop runs, as in manage-orders or report-sales: one a noun\'s schema names in loop.skill or loop.skills.' },
     { name: 'every', type: 'string', required, description: 'How often a pass should run, as in 15m, 2h or 1d. The scheduler reads it; the CLI does not wait.' },
     { name: 'allow', type: 'array', description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs. Without it the loop only reports what is waiting.' },
-    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500, repeated per currency. Above it, the item waits for the human.' },
+    { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500 per currency, the flag repeated or separated by commas. Above it, the item waits for the human.' },
     { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.' },
 ];
 export const loops = {
@@ -147,7 +147,9 @@ async function write(run, name, file) {
     });
 }
 /** 500, or EUR=500 per currency. */
-function maxTotal(items) {
+function maxTotal(given) {
+    // Amounts and currency codes hold no comma: EUR=500,USD=550 is two, as is the flag repeated.
+    const items = given.flatMap((i) => i.split(',')).map((i) => i.trim()).filter(Boolean);
     const plain = items.filter((i) => !i.includes('='));
     if (plain.length && plain.length !== items.length)
         fail('invalid_value', '--max-total takes one amount, or one CURRENCY=amount per currency, not both.', { path: 'max_total' });

package/dist/builtins/shop.js

@@ -0,0 +1,504 @@
+// c11r shop (shop-agent-stores): the agent buys for its human from any store that speaks UCP.
+// Built in: the CLI talks to the store directly, needs no organization (state none), and holds no
+// keys (see ucp.ts). Each step is one command, so the agent talks to the human in between:
+//
+//   profile, search, get, ask   read the store; nothing of the human's is sent.
+//   checkout                    sends the buyer's details, the human's own words, after their yes
+//                               on exactly what goes to which host. No money moves.
+//   order                       pays with the sandbox handler, after their yes on the total. On a
+//                               checkout already paid, it answers the order and pays nothing.
+//
+// Only the sandbox handler: a store without it is refused before anything of the human's is sent.
+import { confirm } from '../confirm.js';
+import { fail } from '../errors.js';
+import { envelope } from '../http.js';
+import { parseSchema } from '../schema.js';
+import { call, discover, handlersOf, minorOf, money, mustPay, originOf, sandboxPayment } from '../ucp.js';
+const ADDRESS = [
+    { name: 'street', type: 'string', description: 'Street and number: Via Roma 1.' },
+    { name: 'line_2', type: 'string', description: 'Apartment, floor, care of.' },
+    { name: 'locality', type: 'string', description: 'The city or town.' },
+    { name: 'postal_code', type: 'string', description: 'The postal code.' },
+    { name: 'region', type: 'string', description: 'The state or province, where the country has them: CA, TO.' },
+    { name: 'country', type: 'string', description: 'The country, as a two-letter code: IT.' },
+];
+const BUYER = [
+    { name: 'email', type: 'string', description: 'The buyer\'s email, as the human gave it.' },
+    { name: 'first_name', type: 'string', description: 'The buyer\'s first name, as the human gave it.' },
+    { name: 'last_name', type: 'string', description: 'The buyer\'s last name, as the human gave it.' },
+    { name: 'phone', type: 'string', description: 'The buyer\'s phone number, as the human gave it.' },
+    { name: 'address', type: 'object', properties: ADDRESS, description: 'Where to ship, as the human gave it: --address.street, --address.locality, --address.postal-code, --address.region, --address.country.' },
+];
+const STORE_ID = { accepts: ['host', 'url'], example: 'shop.example.com' };
+export const shop = {
+    schema: parseSchema({
+        noun: 'shop',
+        group: 'shop',
+        skill: 'shop-agent-stores',
+        kind: 'task',
+        description: 'Buying for the human from any store that speaks UCP, as a shopping agent: the CLI talks to the store directly, with no organization. It pays only with the sandbox test handler, where no money moves. The buyer\'s details are the human\'s, never invented, and nothing of theirs is sent or paid without their yes.',
+        id: STORE_ID,
+        verbs: [
+            { verb: 'profile', method: 'GET', path: '/shop/{id}/profile', state: 'none', live: false, effect: 'Reads the store\'s UCP profile: what it offers this CLI, its payment handlers, and can_pay, whether this CLI can pay there.' },
+            {
+                verb: 'search',
+                method: 'GET',
+                path: '/shop/{id}/search',
+                state: 'none',
+                live: false,
+                query: [
+                    { name: 'query', type: 'string', description: 'What the human looks for, in their words.' },
+                    { name: 'country', type: 'string', description: 'The country to ship to, as a two-letter code: prices and shipping for it.' },
+                    { name: 'category', type: 'array', items: 'string', description: 'A category or a parent of one (Coffee for Coffee > Single origin), repeated: any of them matches.' },
+                    { name: 'min_price', type: 'number', description: 'The lowest price, in major units of the store\'s currency.' },
+                    { name: 'max_price', type: 'number', description: 'The highest price, in major units of the store\'s currency.' },
+                    { name: 'in_stock', type: 'boolean', description: 'Only what is in stock.' },
+                    { name: 'sort', type: 'enum', values: ['relevance', 'price_asc', 'price_desc'], description: 'The order of the results.' },
+                    { name: 'limit', type: 'integer', description: 'How many products, 50 at most. Default 20.' },
+                ],
+                effect: 'Searches the store\'s catalog: products with their variants, prices, availability and images. A variant id is what checkout --item takes.',
+            },
+            {
+                verb: 'get',
+                method: 'GET',
+                path: '/shop/{id}/get',
+                state: 'none',
+                live: false,
+                query: [
+                    { name: 'variant', type: 'array', items: 'string', required: true, description: 'A variant id from search, repeated for several. The first bare value after the store is one.' },
+                    { name: 'country', type: 'string', description: 'The country to ship to, as a two-letter code.' },
+                ],
+                effect: 'Looks variants up by id: the full product, its price, availability and how it ships.',
+            },
+            {
+                verb: 'ask',
+                method: 'GET',
+                path: '/shop/{id}/ask',
+                state: 'none',
+                live: false,
+                query: [{ name: 'question', type: 'string', required: true, description: 'The human\'s question, in their words. The first bare value after the store.' }],
+                effect: 'Asks the store a question in plain words, when it answers them over UCP (dev.ucp.common.ask).',
+            },
+            {
+                verb: 'checkout',
+                method: 'POST',
+                path: '/shop/{id}/checkout',
+                state: 'none',
+                live: false,
+                body: [
+                    { name: 'checkout', type: 'string', description: 'A checkout to change or read again, by the id checkout answered. The first bare value after the store. Without it, a new checkout.' },
+                    { name: 'item', type: 'array', items: 'string', description: 'A variant id and its quantity, ID=QTY (ID alone is 1), repeated. On a checkout given, QTY 0 takes it out.' },
+                    ...BUYER,
+                    { name: 'shipping', type: 'string', description: 'A shipping option id from shipping_options. Without it, the store\'s first.' },
+                ],
+                effect: 'Opens a checkout, or changes one: items, the buyer and where to ship. No money moves. The buyer\'s details go to the store only after the human\'s yes on exactly what is shared and with which host; ask the human for each, never invent one. Answers the totals with shipping, and what the store still needs.',
+            },
+            {
+                verb: 'order',
+                method: 'POST',
+                path: '/shop/{id}/order',
+                state: 'none',
+                live: false,
+                body: [{ name: 'checkout', type: 'string', required: true, description: 'The checkout to pay, by the id checkout answered. The first bare value after the store.' }],
+                effect: 'Pays a checkout that is ready with the sandbox test handler (no money moves), after the human\'s yes on the total, and answers the order. On a checkout already paid, answers its order and pays nothing.',
+            },
+        ],
+    }),
+    positional: { get: 'variant', ask: 'question', checkout: 'checkout', order: 'checkout' },
+    async run(run) {
+        const origin = originOf(run.parsed.id);
+        const store = await discover(origin);
+        switch (run.verb.name) {
+            case 'profile':
+                return profile(store);
+            case 'search':
+                return search(run, store);
+            case 'get':
+                return get(run, store);
+            case 'ask':
+                return ask(run, store);
+            case 'checkout':
+                return checkout(run, store);
+            case 'order':
+                return order(run, store);
+        }
+        return undefined;
+    },
+};
+const cmd = (store, ...rest) => ['c11r shop', ...rest.slice(0, 1), store.host, ...rest.slice(1)].join(' ');
+const plain = (d) => (typeof d === 'string' ? d : (d?.plain ?? d?.markdown ?? d?.html));
+const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && !v.length)));
+const upper = (v) => (typeof v === 'string' && v ? v.toUpperCase() : undefined);
+/** An answer, with signed: false and a warning when the store did not sign it. */
+function answer(data, c, extra = {}) {
+    const unsigned = c?.signature === 'unsigned';
+    return envelope(data, {
+        ...extra,
+        warnings: [...(extra.warnings ?? []), ...(unsigned ? [{ code: 'answer_unsigned', message: 'The store did not sign this answer, so it cannot be checked as the store\'s own.' }] : [])],
+    });
+}
+// ---------- profile
+function profile(store) {
+    const { handlers, can_pay } = handlersOf(store);
+    return envelope({
+        store: store.host,
+        name: store.profile.name ?? undefined,
+        ucp_version: store.profile.ucp?.version,
+        endpoint: store.endpoint,
+        capabilities: [...store.capabilities].sort(),
+        payment_handlers: handlers,
+        can_pay,
+        signed: store.keys.length > 0,
+    }, {
+        next: [{ command: cmd(store, 'search', '--query WORDS'), why: 'what the store sells' }],
+        warnings: can_pay ? [] : [{ code: 'cannot_pay_here', message: `This CLI pays only with the sandbox test handler; ${store.host} ${handlers.length ? `takes ${handlers.join(', ')}` : 'takes no payment over UCP'}. The human buys there in person.` }],
+    });
+}
+// ---------- reading
+function variantView(v) {
+    const m = v.fulfillment?.methods?.[0];
+    return drop({
+        id: v.id,
+        sku: v.sku,
+        title: v.title,
+        price: v.price ? money(v.price.amount, v.price.currency) : undefined,
+        list_price: v.list_price && v.list_price.amount !== v.price?.amount ? money(v.list_price.amount, v.list_price.currency) : undefined,
+        available: v.availability?.available,
+        availability: v.availability?.status,
+        image_url: v.media?.find((x) => x.type === 'image')?.url,
+        ships_to: m?.ships_to,
+        ships_to_country: m?.destination ? m.destination.ships !== false : undefined,
+    });
+}
+function productView(p, full) {
+    const description = plain(p.description);
+    return drop({
+        id: p.id,
+        title: p.title,
+        description: full || !description || description.length <= 200 ? description : `${description.slice(0, 197)}...`,
+        url: p.url,
+        image_url: p.media?.find((x) => x.type === 'image')?.url,
+        categories: Array.isArray(p.categories) ? p.categories.map((c) => c.value ?? c) : undefined,
+        variants: (p.variants ?? []).map(variantView),
+    });
+}
+const context = (country) => (upper(country) ? { context: { address_country: upper(country) } } : {});
+async function search(run, store) {
+    if (!store.capabilities.has('dev.ucp.shopping.catalog.search'))
+        fail('not_supported', `${store.host} offers no catalog search over UCP.`, { next_step: { action: 'human_step', url: store.origin } });
+    const v = run.parsed.values;
+    const limit = Math.min(Math.max(Number(v.limit ?? 20), 1), 50);
+    const body = { pagination: { limit }, ...context(v.country) };
+    if (typeof v.query === 'string' && v.query)
+        body.query = v.query;
+    const filters = {};
+    if (Array.isArray(v.category) && v.category.length)
+        filters.categories = v.category;
+    if (v.in_stock)
+        filters.availability = 'in_stock';
+    const sort = v.sort && v.sort !== 'relevance' ? v.sort : undefined;
+    if (sort)
+        body.sort = sort;
+    if (v.min_price !== undefined || v.max_price !== undefined) {
+        // filters.price is in minor units of the currency the store prices in here: ask it which.
+        const probe = await call(store, 'POST', `${store.endpoint}/catalog/search`, { ...body, ...(Object.keys(filters).length ? { filters } : {}), pagination: { limit: 1 } }, 'a catalog search');
+        const currency = probe.body?.products?.[0]?.variants?.[0]?.price?.currency;
+        if (currency) {
+            body.context = { ...(body.context ?? {}), currency };
+            filters.price = drop({ min: v.min_price === undefined ? undefined : minorOf(Number(v.min_price), currency), max: v.max_price === undefined ? undefined : minorOf(Number(v.max_price), currency) });
+        }
+    }
+    if (Object.keys(filters).length)
+        body.filters = filters;
+    const c = await call(store, 'POST', `${store.endpoint}/catalog/search`, body, 'a catalog search');
+    const products = c.body?.products ?? [];
+    const first = products[0]?.variants?.[0]?.id;
+    return answer(drop({
+        store: store.host,
+        query: body.query,
+        count: products.length,
+        total_count: c.body?.pagination?.total_count,
+        has_more: c.body?.pagination?.has_next_page || undefined,
+        products: products.map((p) => productView(p, false)),
+        messages: c.body?.messages,
+    }), c, { next: first ? [{ command: cmd(store, 'get', first), why: 'the whole product, and how it ships' }] : [] });
+}
+async function get(run, store) {
+    if (!store.capabilities.has('dev.ucp.shopping.catalog.lookup'))
+        fail('not_supported', `${store.host} offers no catalog lookup over UCP: search finds products there.`, { next_step: { action: 'fix_request', command: cmd(store, 'search', '--query WORDS') } });
+    const ids = run.parsed.values.variant;
+    const c = await call(store, 'POST', `${store.endpoint}/catalog/lookup`, { ids, ...context(run.parsed.values.country) }, ids.length > 1 ? `variants ${ids.join(', ')}` : `variant ${ids[0]}`);
+    const products = c.body?.products ?? [];
+    const found = new Set(products.flatMap((p) => (p.variants ?? []).map((x) => x.id)));
+    const missing = ids.filter((id) => !found.has(id));
+    if (!products.length)
+        fail('not_found', `${store.host} sells no variant ${ids.join(', ')}.`, { path: 'variant', next_step: { action: 'fix_request', command: cmd(store, 'search', '--query WORDS') } });
+    return answer(drop({ store: store.host, products: products.map((p) => productView(p, true)), missing }), c, {
+        next: [{ command: cmd(store, 'checkout', `--item ${ids[0]}=QTY ${HUMAN_FLAGS}`), why: 'buy it: every detail from the human, never invented' }],
+        warnings: missing.length ? [{ code: 'not_found', message: `${store.host} did not answer ${missing.join(', ')}.`, path: 'variant' }] : [],
+    });
+}
+async function ask(run, store) {
+    if (!store.capabilities.has('dev.ucp.common.ask'))
+        fail('not_supported', `${store.host} does not answer questions over UCP: its catalog search may.`, { next_step: { action: 'fix_request', command: cmd(store, 'search', '--query WORDS') } });
+    const question = run.parsed.values.question;
+    const c = await call(store, 'POST', `${store.commonEndpoint ?? store.endpoint}/ask`, { query: question }, 'a question');
+    return answer(drop({ store: store.host, question, answer: plain(c.body?.answer), links: c.body?.links, messages: c.body?.messages }), c);
+}
+function items(raw) {
+    return (raw ?? []).map((s) => {
+        const m = s.match(/^(.+?)(?:=(\d+))?$/);
+        if (!m || !m[1].trim())
+            fail('invalid_value', `--item ${s} is not ID or ID=QTY: a variant id from search, as in ETH-250=2.`, { path: 'item' });
+        return { id: m[1].trim(), quantity: m[2] === undefined ? 1 : Number(m[2]) };
+    });
+}
+/** The buyer and the address as the flags give them, in UCP's names. Only what was given. */
+function given(v) {
+    const a = (v.address ?? {});
+    const buyer = drop({ email: v.email, first_name: v.first_name, last_name: v.last_name, phone_number: v.phone });
+    const address = drop({ street_address: a.street, extended_address: a.line_2, address_locality: a.locality, postal_code: a.postal_code, address_region: upper(a.region), address_country: upper(a.country) });
+    return { buyer, address };
+}
+const NEEDED = [
+    ['--email', (b) => b.email],
+    ['--first-name', (b) => b.first_name],
+    ['--last-name', (b) => b.last_name],
+    ['--phone', (b) => b.phone_number],
+    ['--address.street', (_, a) => a.street_address],
+    ['--address.locality', (_, a) => a.address_locality],
+    ['--address.postal-code', (_, a) => a.postal_code],
+    ['--address.country', (_, a) => a.address_country],
+];
+/** Every detail a new checkout needs, each a CAPS word the human's value replaces. */
+const HUMAN_FLAGS = '--email EMAIL --first-name FIRST_NAME --last-name LAST_NAME --phone PHONE --address.street STREET --address.locality CITY --address.postal-code POSTAL_CODE --address.country COUNTRY';
+/** The flags that give what a store's messages say is missing, by the UCP field they name. */
+const FIELD_FLAGS = [
+    [/\bemail\b/, '--email EMAIL'],
+    [/\bfirst_name\b/, '--first-name FIRST_NAME'],
+    [/\blast_name\b/, '--last-name LAST_NAME'],
+    [/\bphone(_number)?\b/, '--phone PHONE'],
+    [/\bstreet_address\b/, '--address.street STREET'],
+    [/\bextended_address\b/, '--address.line-2 LINE_2'],
+    [/\baddress_locality\b/, '--address.locality CITY'],
+    [/\bpostal_code\b/, '--address.postal-code POSTAL_CODE'],
+    [/\baddress_region\b/, '--address.region REGION'],
+    [/\baddress_country\b/, '--address.country COUNTRY'],
+    [/\bselected_option_id\b/, '--shipping OPTION_ID'],
+    [/\bline_items\b/, '--item VARIANT=QTY'],
+];
+/** A runnable command for what the store still needs, or null when its messages name no field. */
+function stillNeeds(ck, store) {
+    const said = (ck.messages ?? []).map((m) => [m.path, m.code].filter(Boolean).join(' ')).join(' ');
+    const flags = FIELD_FLAGS.filter(([re]) => re.test(said)).map(([, f]) => f);
+    return flags.length ? cmd(store, 'checkout', ck.id, ...flags) : null;
+}
+/** What the human sees before their details go: every value, in one line. */
+function sharing(buyer, address) {
+    const name = [buyer.first_name, buyer.last_name].filter(Boolean).join(' ');
+    const place = [[address.postal_code, address.address_locality].filter(Boolean).join(' '), address.address_region, address.address_country].filter(Boolean).join(' ');
+    return [name, buyer.email, buyer.phone_number, address.street_address, address.extended_address, place].filter(Boolean).join(', ');
+}
+/** The update payload for a checkout: everything the platform may write, sent whole again. */
+function replay(ck) {
+    const out = { line_items: (ck.line_items ?? []).map((l) => ({ id: l.id, item: { id: l.item?.id }, quantity: l.quantity })) };
+    for (const k of ['buyer', 'context'])
+        if (ck[k] !== undefined)
+            out[k] = ck[k];
+    if (ck.discounts?.codes?.length)
+        out.discounts = { codes: ck.discounts.codes };
+    if (ck.fulfillment?.methods) {
+        out.fulfillment = {
+            methods: ck.fulfillment.methods.map((m) => ({
+                id: m.id,
+                type: m.type,
+                line_item_ids: m.line_item_ids,
+                destinations: m.destinations,
+                selected_destination_id: m.selected_destination_id ?? null,
+                groups: (m.groups ?? []).map((g) => ({ id: g.id, selected_option_id: g.selected_option_id ?? null })),
+            })),
+        };
+    }
+    return out;
+}
+const destinationOf = (ck) => {
+    const m = ck.fulfillment?.methods?.[0];
+    return m?.destinations?.find((d) => d.id === m.selected_destination_id);
+};
+function checkoutView(ck, store) {
+    const cur = ck.currency;
+    const group = ck.fulfillment?.methods?.[0]?.groups?.[0];
+    const options = group?.options ?? [];
+    const option = options.find((o) => o.id === group?.selected_option_id);
+    const totalOf = (t) => t?.find((x) => x.type === 'total')?.amount;
+    const optionView = (o) => drop({ id: o.id, title: o.title, description: plain(o.description), price: totalOf(o.totals) === undefined ? undefined : money(totalOf(o.totals), cur) });
+    const { id: _id, type: _type, ...ship_to } = destinationOf(ck) ?? {};
+    const total = totalOf(ck.totals);
+    return drop({
+        id: ck.id,
+        status: ck.status,
+        store: store.host,
+        currency: cur,
+        line_items: (ck.line_items ?? []).map((l) => drop({ item_id: l.item?.id, title: l.item?.title, quantity: l.quantity, unit_price: l.item?.price === undefined ? undefined : money(l.item.price, cur), total: totalOf(l.totals) === undefined ? undefined : money(totalOf(l.totals), cur) })),
+        buyer: ck.buyer ? drop(Object.fromEntries(Object.entries(ck.buyer).filter(([k]) => k !== 'consent'))) : undefined,
+        ship_to: Object.keys(ship_to).length ? ship_to : undefined,
+        shipping: option ? optionView(option) : undefined,
+        shipping_options: options.length > 1 ? options.map(optionView) : undefined,
+        totals: (ck.totals ?? []).map((t) => drop({ type: t.type, label: t.display_text, ...money(t.amount, cur) })),
+        total: total === undefined ? undefined : money(total, cur),
+        messages: ck.messages,
+        order: ck.order,
+        continue_url: ck.continue_url,
+        expires_at: ck.expires_at,
+    });
+}
+function nextOf(ck, store) {
+    if (ck.status === 'ready_for_complete')
+        return [{ command: cmd(store, 'order', ck.id), why: `pay ${ck.totals ? money(ck.totals.find((t) => t.type === 'total')?.amount ?? 0, ck.currency).display : 'the total'} with the sandbox test handler, after the human's yes on it` }];
+    if (ck.status === 'completed' && ck.order?.id)
+        return [{ command: cmd(store, 'order', ck.id), why: 'the order' }];
+    const needs = stillNeeds(ck, store);
+    return needs ? [{ command: needs, why: 'what the store says in messages is missing, from the human' }] : [];
+}
+async function checkout(run, store) {
+    const v = run.parsed.values;
+    const id = v.checkout;
+    // Nothing of the human's goes to a store this CLI cannot pay at.
+    mustPay(store);
+    const lines = items(v.item);
+    const { buyer, address } = given(v);
+    const current = id ? (await call(store, 'GET', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}`, undefined, `checkout ${id}`)).body : null;
+    if (current && (current.status === 'completed' || current.status === 'canceled')) {
+        if (lines.length || Object.keys(buyer).length || Object.keys(address).length || v.shipping) {
+            fail('invalid_transition', `Checkout ${id} is ${current.status}: it takes no changes.`, { details: { status: current.status }, next_step: current.status === 'completed' ? { action: 'fix_request', command: cmd(store, 'order', id) } : { action: 'fix_request', command: cmd(store, 'checkout', `--item VARIANT=QTY ${HUMAN_FLAGS}`) } }, 'rejected');
+        }
+    }
+    if (!current) {
+        if (!lines.length)
+            fail('missing_value', 'A new checkout needs at least one --item: a variant id from search, as in --item ETH-250=1.', { path: 'item', next_step: { action: 'fix_request', command: cmd(store, 'search', '--query WORDS') } });
+        const missing = NEEDED.filter(([, pick]) => !pick(buyer, address)).map(([f]) => f);
+        if (missing.length) {
+            fail('missing_value', `A checkout needs the buyer's ${missing.join(', ')}. Ask the human for each: they are the human's, never invented.`, { path: missing[0].replace(/^--/, '').replace(/-/g, '_'), details: { missing }, next_step: { action: 'human_step' } });
+        }
+    }
+    // A read: a checkout given with nothing to change.
+    if (current && !lines.length && !Object.keys(buyer).length && !Object.keys(address).length && !v.shipping) {
+        return envelope(checkoutView(current, store), { next: nextOf(current, store) });
+    }
+    // What goes to the store of the human's: every value, shown back to them first.
+    const shared = Object.keys(buyer).length || Object.keys(address).length ? sharing(buyer, address) : null;
+    if (shared && !run.globals.dryRun) {
+        await confirm(`Share the buyer's details with ${store.host}`, run.line, { yes: run.globals.yes, prompter: run.prompter, sentence: `Sharing with ${store.host}: ${shared}`, details: { store: store.host, buyer, ship_to: address } });
+    }
+    const body = current ? replay(current) : { line_items: lines.map((l) => ({ item: { id: l.id }, quantity: l.quantity })), ...context(address.address_country) };
+    if (current) {
+        for (const l of lines) {
+            const i = body.line_items.findIndex((x) => x.item.id === l.id);
+            if (l.quantity === 0) {
+                if (i >= 0)
+                    body.line_items.splice(i, 1);
+            }
+            else if (i >= 0)
+                body.line_items[i].quantity = l.quantity;
+            else
+                body.line_items.push({ item: { id: l.id }, quantity: l.quantity });
+        }
+        if (!body.line_items.length)
+            fail('invalid_value', `That leaves checkout ${id} with no items: keep one, or let it expire.`, { path: 'item' });
+    }
+    if (Object.keys(buyer).length)
+        body.buyer = drop({ ...(body.buyer ?? {}), ...buyer });
+    if (Object.keys(address).length || v.shipping) {
+        const method = body.fulfillment?.methods?.[0] ?? { type: 'shipping' };
+        if (Object.keys(address).length) {
+            const prev = (current && destinationOf(current)) ?? {};
+            const b = (body.buyer ?? {});
+            const dest = drop({ ...prev, first_name: b.first_name, last_name: b.last_name, phone_number: b.phone_number, ...address, id: prev.id ?? 'dest_1' });
+            delete dest.type;
+            method.destinations = [dest];
+            method.selected_destination_id = dest.id;
+            if (address.address_country)
+                body.context = { ...(body.context ?? {}), address_country: address.address_country };
+        }
+        if (v.shipping)
+            method.groups = (method.groups?.length ? method.groups : [{ id: 'grp_1' }]).map((g) => ({ ...g, selected_option_id: v.shipping }));
+        body.fulfillment = { methods: [method, ...(body.fulfillment?.methods?.slice(1) ?? [])] };
+    }
+    if (run.globals.dryRun)
+        return envelope({ dry_run: true, store: store.host, checkout: id ?? null, would_send: body, sharing: shared });
+    let c;
+    if (current)
+        c = await call(store, 'PUT', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}`, body, `checkout ${id}`);
+    else {
+        // A new checkout: the items first, then the buyer and the address on it, as the store takes them.
+        const { buyer: b, fulfillment: f, ...open } = body;
+        c = await call(store, 'POST', `${store.endpoint}/checkout-sessions`, open, 'a new checkout');
+        const again = replay(c.body);
+        if (b)
+            again.buyer = b;
+        if (f) {
+            const m = f.methods[0];
+            again.fulfillment = { methods: [{ ...m, line_item_ids: (c.body.line_items ?? []).map((l) => l.id) }] };
+        }
+        c = await call(store, 'PUT', `${store.endpoint}/checkout-sessions/${encodeURIComponent(c.body.id)}`, again, `checkout ${c.body.id}`);
+    }
+    // A store that offers shipping options without picking one: its first, said in the answer.
+    const group = c.body.fulfillment?.methods?.[0]?.groups?.[0];
+    if (group && !group.selected_option_id && group.options?.length) {
+        const again = replay(c.body);
+        again.fulfillment.methods[0].groups[0].selected_option_id = group.options[0].id;
+        c = await call(store, 'PUT', `${store.endpoint}/checkout-sessions/${encodeURIComponent(c.body.id)}`, again, `checkout ${c.body.id}`);
+    }
+    const ck = c.body;
+    return answer(checkoutView(ck, store), c, { next: nextOf(ck, store) });
+}
+// ---------- order
+function orderView(o, store, checkoutId) {
+    const cur = o.currency;
+    const totalOf = (t) => t?.find((x) => x.type === 'total')?.amount;
+    return drop({
+        id: o.id,
+        label: o.label,
+        permalink_url: o.permalink_url,
+        store: store.host,
+        checkout: checkoutId,
+        currency: cur,
+        line_items: (o.line_items ?? []).map((l) => drop({ item_id: l.item?.id, title: l.item?.title, quantity: l.quantity?.total ?? l.quantity, status: l.status, total: totalOf(l.totals) === undefined || !cur ? undefined : money(totalOf(l.totals), cur) })),
+        fulfillment: (o.fulfillment?.expectations ?? []).map((e) => drop({ method: e.method_type, destination: e.destination, description: plain(e.description) })),
+        totals: cur ? (o.totals ?? []).map((t) => drop({ type: t.type, label: t.display_text, ...money(t.amount, cur) })) : undefined,
+        total: cur && totalOf(o.totals) !== undefined ? money(totalOf(o.totals), cur) : undefined,
+    });
+}
+async function placed(store, ck, paid) {
+    const ref = ck.order;
+    const c = await call(store, 'GET', `${store.endpoint}/orders/${encodeURIComponent(ref.id)}`, undefined, `order ${ref.id}`);
+    return answer({ ...orderView({ label: ref.label, permalink_url: ref.permalink_url, ...c.body }, store, ck.id), paid_now: paid }, c);
+}
+async function order(run, store) {
+    const id = run.parsed.values.checkout;
+    const ck = (await call(store, 'GET', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}`, undefined, `checkout ${id}`)).body;
+    // Paid already: the order, and nothing paid again.
+    if (ck.status === 'completed' && ck.order?.id)
+        return placed(store, ck, false);
+    if (ck.status === 'canceled')
+        fail('invalid_transition', `Checkout ${id} was canceled: it cannot be paid.`, { details: { status: ck.status }, next_step: { action: 'fix_request', command: cmd(store, 'checkout', `--item VARIANT=QTY ${HUMAN_FLAGS}`) } }, 'rejected');
+    mustPay(store, { continue_url: ck.continue_url ?? null });
+    if (ck.status !== 'ready_for_complete') {
+        const said = (ck.messages ?? []).map((m) => m.content).filter(Boolean).join(' ');
+        fail('invalid_transition', `Checkout ${id} is ${ck.status}, not ready to pay${said ? `: ${said}` : '.'}`, { details: { status: ck.status, messages: ck.messages ?? [] }, next_step: stillNeeds(ck, store) ? { action: 'fix_request', command: stillNeeds(ck, store) } : { action: 'human_step', url: ck.continue_url ?? null } }, 'rejected');
+    }
+    const totalAmount = (ck.totals ?? []).find((t) => t.type === 'total')?.amount;
+    const total = totalAmount === undefined ? null : money(totalAmount, ck.currency);
+    const sentence = `Paying ${total?.display ?? 'the total'} to ${store.host} for checkout ${id}, with the sandbox test handler (no money moves)`;
+    if (run.globals.dryRun)
+        return envelope({ dry_run: true, store: store.host, checkout: id, total, would_pay: true });
+    await confirm(`Pay checkout ${id}`, run.line, { yes: run.globals.yes, prompter: run.prompter, sentence, details: { store: store.host, checkout: id, total } });
+    const c = await call(store, 'POST', `${store.endpoint}/checkout-sessions/${encodeURIComponent(id)}/complete`, sandboxBody(), `checkout ${id}`);
+    const done = c.body;
+    if (done.status !== 'completed' || !done.order?.id) {
+        const said = (done.messages ?? []).map((m) => m.content).filter(Boolean).join(' ');
+        fail('store_refused', `${store.host} did not take the payment for checkout ${id}${said ? `: ${said}` : '.'}`, { details: { status: done.status, messages: done.messages ?? [] }, next_step: { action: 'human_step', url: done.continue_url ?? null } }, 'rejected');
+    }
+    return placed(store, done, true);
+}
+const sandboxBody = () => ({ ...sandboxPayment(), signals: { 'dev.ucp.user_agent': 'c11r' } });

package/dist/confirm.js

@@ -40,18 +40,25 @@ export const terminal = {
         });
     },
 };
+/**
+ * action names what needs a yes ("Destroy sandbox"). sentence, when given, is what the human is
+ * shown instead, whole ("Sharing with shop.example.com: Ada Lovelace, ..."), and details go with
+ * the error, so the agent can show the human the same.
+ */
 export async function confirm(action, command, opts) {
     if (opts.yes)
         return;
     const p = opts.prompter ?? terminal;
+    const said = opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} This` : action;
     if (!p.interactive) {
         // The agent asks the human; on a yes it repeats the command with --yes. next never carries the
         // --yes itself: only the human's answer adds it.
-        fail('confirmation_required', `${action} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
+        fail('confirmation_required', `${said} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
             next_step: { action: 'fix_request', command },
+            ...(opts.details ? { details: opts.details } : {}),
         });
     }
-    const answer = (await p.ask(`${action}. Go ahead? [y/N] `)).trim().toLowerCase();
+    const answer = (await p.ask(opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} Go ahead? [y/N] ` : `${action}. Go ahead? [y/N] `)).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes')
-        fail('confirmation_declined', `${action}: not confirmed, nothing was changed.`);
+        fail('confirmation_declined', opts.sentence ? `${opts.sentence.replace(/\.?$/, '')}: not confirmed, nothing was sent.` : `${action}: not confirmed, nothing was changed.`);
 }

package/dist/engine.js

@@ -65,8 +65,11 @@ async function executeOnce(argv, opts) {
         const by = verb.refused.by === 'commercelayer' ? 'Commerce Layer' : verb.refused.by;
         fail('not_supported', `c11r ${schema.noun} ${verb.name} is refused by ${by}: ${verb.description || 'it cannot be done through the API.'}`, { details: { refused_by: verb.refused.by }, next_step: { action: 'none' } });
     }
-    const positional = ext?.positional?.[verb.name];
-    const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : cmd.rest;
+    // A bare value that is a flag's: the first for a verb with no id (sales-calls book <slot>), the
+    // second, after the id, for one with (shop order <store> <checkout>).
+    const positional = (builtins[schema.noun]?.positional ?? ext?.positional)?.[verb.name];
+    const bare = (i) => cmd.rest[i] !== undefined && !cmd.rest[i].startsWith('-');
+    const rest = !positional ? cmd.rest : !verb.id && bare(0) ? [`--${positional}`, ...cmd.rest] : verb.id && bare(0) && bare(1) ? [cmd.rest[0], `--${positional}`, ...cmd.rest.slice(1)] : cmd.rest;
     const parsed = parseFields(schema.noun, verb, rest);
     ext?.prepare?.(verb, parsed);
     // Files first, so a required document given with --file counts; a secret is typed only once

package/dist/errors.js

@@ -62,6 +62,10 @@ const KIND = {
     no_credentials: 'auth',
     forbidden: 'rejected',
     claim_not_found: 'not_found',
+    // A store spoken to over UCP (c11r shop).
+    store_unavailable: 'unavailable',
+    store_refused: 'rejected',
+    payment_handler_unsupported: 'rejected',
 };
 /** For an API error whose code the CLI does not know: from the HTTP status. */
 export function kindOfStatus(status) {

package/dist/help.js

@@ -30,7 +30,7 @@ export function indexHelp(builtins, api) {
         description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
         nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
         standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
-        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes the flag repeated or a JSON array, and the same rule holds: enums, numbers and dates also separated by commas, a name or text one value per flag (--payment-settings "Invoice, 60 days"); an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
         global_flags: GLOBAL_FLAG_HELP,
         exit_codes: EXIT_CODE_HELP,
         more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',

package/dist/ucp.js

@@ -0,0 +1,207 @@
+// A UCP platform client: what any shopping agent does to buy from a store that speaks UCP.
+// The CLI talks to the store directly, as the agent CLI platform: its profile is the static
+// https://commercelayer.ai/ucp/agent-cli/profile.json, it holds no keys, and stores verify no
+// request signature. Every call carries UCP-Agent and Request-Id, a Content-Digest with a body,
+// and an Idempotency-Key on writes. The store signs its answers (RFC 9421, ES256 over @status,
+// content-digest and content-type): the CLI checks them against keys[] of its /.well-known/ucp.
+import crypto from 'node:crypto';
+import { CliError, fail } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const UCP_VERSION = '2026-08-25';
+export const AGENT_PROFILE_URL = 'https://commercelayer.ai/ucp/agent-cli/profile.json';
+/** The sandbox payment handler: no money moves. The only one this CLI pays with. */
+export const SANDBOX_HANDLER = 'ai.commercelayer.sandbox';
+const SANDBOX_HANDLER_ID = 'cl_sandbox';
+const SANDBOX_CREDENTIAL_TYPE = 'sandbox_token';
+const SANDBOX_TOKEN_SUCCESS = 'sbx_tok_success';
+const TIMEOUT_MS = 30_000;
+/** A store from a host or a URL on it: https only (http for localhost, in tests). */
+export function originOf(given) {
+    let url = null;
+    try {
+        url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(given) ? given : `https://${given}`);
+    }
+    catch {
+        url = null;
+    }
+    if (!url || !url.hostname)
+        fail('invalid_value', `${given} is not a store: give its host, as in shop.example.com, or an https URL on it.`, { path: 'id' });
+    const local = ['localhost', '127.0.0.1'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+        fail('invalid_value', `${given} is not https: UCP stores are served over https.`, { path: 'id' });
+    return url.origin;
+}
+/** GET /.well-known/ucp: what the store offers this CLI. */
+export async function discover(origin) {
+    const res = await http('GET', `${origin}/.well-known/ucp`, { accept: 'application/json' });
+    const host = new URL(origin).host;
+    if (res.status === 404)
+        fail('not_found', `${host} serves no UCP profile (/.well-known/ucp answered 404): it does not sell to agents.`, { path: 'id', next_step: { action: 'human_step', url: origin } });
+    if (res.status !== 200)
+        fail('store_unavailable', `${host}/.well-known/ucp answered ${res.status}.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    const profile = parse(res.body);
+    if (!profile || typeof profile.ucp !== 'object')
+        fail('invalid_response', `${host}/.well-known/ucp is not a UCP profile.`, { next_step: { action: 'none' } });
+    const ucp = profile.ucp;
+    if (ucp.version !== UCP_VERSION)
+        fail('not_supported', `${host} speaks UCP ${ucp.version ?? '(no version)'}; this CLI speaks ${UCP_VERSION}.`, { details: { store_version: ucp.version ?? null, cli_version: UCP_VERSION }, next_step: { action: 'none' } });
+    const rest = (name) => (ucp.services?.[name] ?? []).find((s) => s.transport === 'rest')?.endpoint ?? null;
+    const endpoint = rest('dev.ucp.shopping');
+    if (!endpoint)
+        fail('not_supported', `${host}'s profile has no REST dev.ucp.shopping service.`, { next_step: { action: 'none' } });
+    const capabilities = new Set();
+    for (const [name, entries] of Object.entries((ucp.capabilities ?? {})))
+        if (Array.isArray(entries) && entries.some((e) => e.version === UCP_VERSION))
+            capabilities.add(name);
+    return { origin, host, profile, endpoint, commonEndpoint: rest('dev.ucp.common'), capabilities, keys: Array.isArray(profile.keys) ? profile.keys : [] };
+}
+/** The payment handlers the store offers, by name, and whether this CLI can pay there. */
+export function handlersOf(store) {
+    const handlers = Object.keys(store.profile.ucp?.payment_handlers ?? {});
+    return { handlers, can_pay: handlers.includes(SANDBOX_HANDLER) && store.capabilities.has('dev.ucp.shopping.checkout') };
+}
+/** Before anything of the human's is sent: a store this CLI cannot pay at is refused. */
+export function mustPay(store, extra = {}) {
+    if (!store.capabilities.has('dev.ucp.shopping.checkout')) {
+        fail('not_supported', `${store.host} offers no UCP checkout: an agent can browse it, not buy there.`, { next_step: { action: 'human_step', url: store.origin } });
+    }
+    const { handlers } = handlersOf(store);
+    if (!handlers.includes(SANDBOX_HANDLER)) {
+        fail('payment_handler_unsupported', `${store.host} takes ${handlers.length ? handlers.join(', ') : 'no payment handler'}; this CLI pays only with the ${SANDBOX_HANDLER} test handler, where no money moves. The human buys there in person.`, { details: { handlers }, next_step: { action: 'human_step', url: extra.continue_url ?? store.origin } }, 'rejected');
+    }
+}
+export const sandboxPayment = () => ({ payment: { instruments: [{ id: 'pi_1', handler_id: SANDBOX_HANDLER_ID, type: 'card', selected: true, credential: { type: SANDBOX_CREDENTIAL_TYPE, token: SANDBOX_TOKEN_SUCCESS } }] } });
+/** A UCP call. The answer's digest and signature are checked; an error is a CliError. */
+export async function call(store, method, url, body, what = 'the store') {
+    const raw = body === undefined ? undefined : JSON.stringify(body);
+    const headers = { accept: 'application/json', 'ucp-agent': `profile="${AGENT_PROFILE_URL}"`, 'request-id': crypto.randomUUID() };
+    if (raw !== undefined) {
+        headers['content-type'] = 'application/json';
+        headers['content-digest'] = contentDigest(raw);
+    }
+    if (method !== 'GET' && !/\/catalog\/|\/ask$/.test(url))
+        headers['idempotency-key'] = crypto.randomUUID();
+    const res = await http(method, url, headers, raw);
+    const signature = checkAnswer(store, res);
+    const parsed = parse(res.body);
+    if (res.status >= 400 || parsed?.ucp?.status === 'error')
+        refused(store, res.status, parsed, what);
+    if (!parsed || typeof parsed !== 'object')
+        fail('invalid_response', `${store.host} answered ${what} with no JSON.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    return { status: res.status, body: parsed, signature };
+}
+/** The store's own words, as an error the agent can show the human. */
+function refused(store, status, body, what) {
+    const messages = Array.isArray(body?.messages) ? body.messages : [];
+    const first = messages.find((m) => m.type === 'error') ?? messages[0];
+    const code = body?.code ?? first?.code;
+    const said = body?.content ?? first?.content ?? `it answered ${status}`;
+    const details = { status, store_code: code ?? null, messages: messages.length ? messages : undefined };
+    if (status === 404 || code === 'not_found')
+        fail('not_found', `${store.host} does not know ${what}: ${said}`, { details, next_step: { action: 'none' } });
+    if (status === 401 && /signature/i.test(`${code} ${said}`)) {
+        fail('not_supported', `${store.host} wants a signed request, and this CLI signs none: ${said}`, { details, next_step: { action: 'human_step', url: store.origin } });
+    }
+    if (status === 401 || code === 'identity_required')
+        fail('forbidden', `${store.host} refused ${what}: ${said} This CLI reads only orders it placed.`, { details, next_step: { action: 'none' } });
+    if (status === 429 || status >= 500)
+        fail('store_unavailable', `${store.host} could not answer ${what}: ${said}`, { details, next_step: { action: 'retry_later' } });
+    fail('store_refused', `${store.host} refused ${what}: ${said}`, { details, next_step: { action: 'human_step' } }, 'rejected');
+}
+async function http(method, url, headers, body) {
+    let res;
+    try {
+        res = await fetch(url, { method, headers: { 'user-agent': USER_AGENT, ...headers }, body, redirect: 'follow', signal: AbortSignal.timeout(TIMEOUT_MS) });
+    }
+    catch (e) {
+        const host = (() => {
+            try {
+                return new URL(url).host;
+            }
+            catch {
+                return url;
+            }
+        })();
+        throw new CliError({ code: 'store_unavailable', message: `${host} could not be reached: ${e.message}.`, required_state: null, required_plan: null, missing: null, path: null, next_step: { action: 'retry_later', command: null, url: null } }, 'unavailable');
+    }
+    const out = {};
+    res.headers.forEach((v, k) => (out[k.toLowerCase()] = v));
+    return { status: res.status, headers: out, body: await res.text() };
+}
+function parse(text) {
+    if (!text)
+        return null;
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- digests and signatures (RFC 9530, RFC 9421)
+export function contentDigest(body) {
+    return `sha-256=:${crypto.createHash('sha256').update(body).digest('base64')}:`;
+}
+function serializeParams(p) {
+    let s = `(${p.components.map((c) => `"${c}"`).join(' ')})`;
+    if (p.created !== undefined)
+        s += `;created=${p.created}`;
+    return `${s};keyid="${p.keyid}"`;
+}
+export function signatureBase(values, p) {
+    return [...p.components.map((c) => `"${c}": ${values[c] ?? ''}`), `"@signature-params": ${serializeParams(p)}`].join('\n');
+}
+function parseSignature(input, signature) {
+    if (!input || !signature)
+        return null;
+    const m = input.match(/^\s*([a-z0-9_-]+)=\(([^)]*)\)((?:;[a-z]+=[^;]*)*)\s*$/i);
+    if (!m)
+        return null;
+    const [, label, list, rest] = m;
+    const params = { components: [...list.matchAll(/"([^"]+)"/g)].map((x) => x[1]), keyid: '' };
+    for (const [, k, v] of rest.matchAll(/;([a-z]+)=("[^"]*"|[^;]*)/g)) {
+        if (k === 'keyid')
+            params.keyid = v.replace(/^"|"$/g, '');
+        if (k === 'created')
+            params.created = Number(v);
+    }
+    const sig = signature.match(new RegExp(`${label}=:([A-Za-z0-9+/=]+):`));
+    return sig ? { params, signature: sig[1] } : null;
+}
+function verify(base, signature, jwk) {
+    try {
+        const { kid: _k, use: _u, alg: _a, key_ops: _o, ...key } = jwk;
+        return crypto.verify('sha256', Buffer.from(base), { key: crypto.createPublicKey({ key: key, format: 'jwk' }), dsaEncoding: 'ieee-p1363' }, Buffer.from(signature, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+/** A digest that does not match, or a signature that does not verify: the answer is not trusted. */
+function checkAnswer(store, res) {
+    const digest = res.headers['content-digest'];
+    if (digest && digest !== contentDigest(res.body))
+        fail('invalid_response', `${store.host}'s answer does not match its Content-Digest: it was changed on the way, and is not used.`, { next_step: { action: 'retry_later' } });
+    const sig = parseSignature(res.headers['signature-input'], res.headers.signature);
+    if (!sig)
+        return 'unsigned';
+    const key = store.keys.find((k) => k.kid === sig.params.keyid);
+    const values = { '@status': String(res.status), 'content-digest': digest ?? '', 'content-type': res.headers['content-type'] ?? '' };
+    if (!key || !verify(signatureBase(values, sig.params), sig.signature, key)) {
+        fail('invalid_response', `${store.host}'s answer is signed with ${key ? 'a signature that does not verify' : `a key its profile does not publish (${sig.params.keyid})`}: it is not used.`, { next_step: { action: 'none' } });
+    }
+    return 'verified';
+}
+export function money(amount, currency) {
+    let digits = 2;
+    try {
+        digits = new Intl.NumberFormat('en', { style: 'currency', currency }).resolvedOptions().maximumFractionDigits ?? 2;
+    }
+    catch {
+        digits = 2;
+    }
+    const major = amount / 10 ** digits;
+    return { amount, currency, display: `${amount < 0 ? '-' : ''}${currency} ${Math.abs(major).toFixed(digits)}` };
+}
+export const minorOf = (major, currency) => Math.round(major * 10 ** (money(0, currency).display.split('.')[1]?.length ?? 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.12",
+  "version": "1.0.0-dev.13",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [