@commercelayer/agent-cli 1.0.0-dev.2 → 1.0.0-dev.21

package/dist/builtins/sandbox.js

@@ -1,17 +1,30 @@
-// c11r sandbox create [--name] [--seed], get, reset, claim, destroy (contract section 4), and
+// c11r sandbox create [--name] [--seed [type]] [--catalogue file], get, reset, claim, destroy (contract sections 4 and 48), and
 // c11r status (section 5). They are built in for what happens on this machine: create stores the
 // sandbox token (mode 600, ~/.config/c11r/credentials.json) and links the folder (.c11r.json);
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
 // not even by create: only its hint.
 import crypto from 'node:crypto';
-import { credentialsFile, defaultOrg, markOutWritten, outWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
+import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
 import { CliError, fail } from '../errors.js';
 import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
 import { OUT_NOT_TRACKED, removeOrgSecrets } from '../secrets.js';
 import { VERSION } from '../version.js';
+import { readCatalogue, SEED_TYPES, withShop } from '../storefront.js';
 /** The longest sandbox name the API takes (contract: 422 invalid_argument past it). */
 const NAME_MAX = 25;
+const SEED = {
+    name: 'seed',
+    type: 'enum',
+    values: [...SEED_TYPES],
+    bare: true,
+    description: 'Loads a demo shop of this type: coffee, tshirts or games, six products each, or custom, the person\'s own from --catalogue. Each has two markets, shipping, a manual payment setting (Wire transfer) and a storefront on, enough to place a test order at once. --seed alone is coffee.',
+};
+const CATALOGUE = {
+    name: 'catalogue',
+    type: 'string',
+    description: 'With --seed custom: a YAML file with the shop\'s name, its products (name, description, prices in EUR and USD, code) and optionally its look. Checked here, then sent in the same call.',
+};
 export const sandbox = {
     schema: parseSchema({
         noun: 'sandbox',
@@ -28,9 +41,10 @@ export const sandbox = {
                 live: false,
                 body: [
                     { name: 'name', type: 'string', description: 'The organization name; without it, an invented one. A name starting zztest marks a test organization.' },
-                    { name: 'seed', type: 'boolean', description: 'Loads the demo dataset: two markets, six products, shipping and a test payment method, enough to place a test order at once.' },
+                    SEED,
+                    CATALOGUE,
                 ],
-                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed is applied, in about 20 seconds.',
+                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
             },
             { verb: 'get', method: 'GET', path: '/v1/sandbox', live: false, effect: 'Returns the sandbox: organization, expiry, whether it is seeded, the token hint and the claim status.' },
             {
@@ -39,8 +53,8 @@ export const sandbox = {
                 path: '/v1/sandbox/reset',
                 live: false,
                 destructive: true,
-                body: [{ name: 'seed', type: 'boolean', description: 'Seeds the fresh organization, or not; without it, as before.' }],
-                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before, and retires the old one. The slug changes; this machine and .c11r.json follow it.',
+                body: [{ ...SEED, description: 'Seeds the fresh organization with this type, or not (--seed false); without it, as before. custom needs --catalogue again.' }, CATALOGUE],
+                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before (its storefront on again), and retires the old one. The slug changes; this machine and .c11r.json follow it.',
             },
             { verb: 'claim', method: 'POST', path: '/v1/sandbox/claim', live: false, effect: 'Returns a one-time claim URL, valid 30 minutes, for the human to open: they sign in with Commerce Layer and pick a plan. The agent never opens it for them.' },
             {
@@ -76,7 +90,7 @@ async function create(run, values) {
     if (name !== undefined && (name.trim() === '' || name.length > NAME_MAX)) {
         fail('invalid_value', `--name ${JSON.stringify(name)} is ${name.trim() === '' ? 'empty' : `${name.length} characters`}: a sandbox name has 1 to ${NAME_MAX}.`, { path: 'name', next_step: { action: 'fix_request', command: null } });
     }
-    const seed = Boolean(values.seed);
+    const { seed, catalogue } = seedBody(values);
     const test = process.env.C11R_TEST === '1' || Boolean(name?.startsWith('zztest'));
     // The token goes only when this folder, --org or C11R_ORG names a sandbox: the API then
     // finishes a failed seed there, or answers 409 conflict naming it, rather than make a second
@@ -85,7 +99,7 @@ async function create(run, values) {
     // A fresh key per create: after a 5xx or a lost connection the same create is repeated with it,
     // and the API answers the sandbox (and token) it made, rather than leave one with a lost token.
     const idempotencyKey = `c11r-${crypto.randomBytes(16).toString('base64url')}`;
-    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 120_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
+    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, ...(catalogue ? { catalogue } : {}), test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 180_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
     if (run.globals.dryRun)
         return r;
     const { token, ...data } = r.data ?? {};
@@ -98,10 +112,28 @@ async function create(run, values) {
     const warnings = r.warnings.filter((w) => w.code !== 'token_shown_once');
     if (link.previous)
         warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${data.org}. The token of ${link.previous} stays stored.` });
-    return { ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings };
+    return withShop({ ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings }, data.store);
+}
+/** --seed and --catalogue as the API takes them: custom only with a catalogue, a catalogue only with custom. */
+function seedBody(values) {
+    const seed = values.seed ?? false;
+    const file = values.catalogue;
+    if (seed === 'custom' && file === undefined) {
+        fail('missing_value', '--seed custom needs --catalogue: a YAML file with the shop\'s name and its products. Write it from what the human described, show it to them, then run the command with --catalogue <file>.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    }
+    if (file !== undefined && seed !== 'custom')
+        fail('invalid_value', '--catalogue goes only with --seed custom: the other types bring their own products.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    return { seed, catalogue: file === undefined ? undefined : readCatalogue(file) };
 }
 async function reset(run, values) {
-    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body: values.seed === undefined ? {} : { seed: values.seed } });
+    const body = {};
+    if (values.seed !== undefined || values.catalogue !== undefined) {
+        const { seed, catalogue } = seedBody(values);
+        body.seed = seed;
+        if (catalogue)
+            body.catalogue = catalogue;
+    }
+    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body });
     if (run.globals.dryRun)
         return r;
     const { org, previous_org: previous } = r.data ?? {};
@@ -112,7 +144,7 @@ async function reset(run, values) {
         if (link?.org === before)
             writeLink(org);
     }
-    return r;
+    return withShop(r, r.data?.store);
 }
 async function destroy(run) {
     let r;
@@ -124,8 +156,7 @@ async function destroy(run) {
         // here. The sandbox is gone either way, so this machine forgets it too.
         if (!(e instanceof CliError && e.code === 'unauthorized') || run.globals.dryRun || !run.org.org)
             throw e;
-        const out = outWritten(run.org.org);
-        markOutWritten(run.org.org, false);
+        const out = forgetOutWritten(run.org.org);
         forgetOrg(run.org.org);
         const link = removeLink(run.org.org);
         const secrets = removeOrgSecrets(run.org.org);
@@ -136,8 +167,7 @@ async function destroy(run) {
     const org = r.data?.org ?? run.org.org;
     if (!org)
         return r;
-    const out = outWritten(org);
-    markOutWritten(org, false);
+    const out = forgetOutWritten(org);
     forgetOrg(org);
     const link = removeLink(org);
     const secrets = removeOrgSecrets(org);

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