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

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