@commercelayer/agent-cli 0.0.0-stage → 0.1.1

package/dist/api/stub/shopping.js

@@ -0,0 +1,543 @@
+// The dev.ucp.shopping service of a store: catalog, carts, checkouts, orders and
+// ask, computed from the applied store.yml. Shapes follow the UCP 2026-08-25
+// schemas; src/ucp/platform.ts holds the constants shared with the client.
+import crypto from 'node:crypto';
+import { SANDBOX_CREDENTIAL_TYPE, SANDBOX_HANDLER, SANDBOX_HANDLER_ID, SANDBOX_TOKEN_DECLINED, SANDBOX_TOKEN_SUCCESS, toMinor, UCP_VERSION } from '../../ucp/platform.js';
+/** The discount code every sandbox accepts: 10% off the items. */
+const SANDBOX_CODE = 'SANDBOX10';
+const CONSENT_PURPOSES = {
+    'dev.ucp.consent.marketing': 'Marketing messages about new products and offers.',
+    'dev.ucp.consent.analytics': 'Analytics to improve the store.',
+    'dev.ucp.consent.preferences': 'Remembering your preferences.',
+    'dev.ucp.consent.sale_or_sharing': 'Sharing your data with partners.',
+};
+const id = (prefix) => `${prefix}_${crypto.randomBytes(6).toString('hex')}`;
+const now = () => new Date();
+const later = (hours) => new Date(Date.now() + hours * 3600 * 1000).toISOString();
+const RELEVANT = {
+    'catalog.search': ['dev.ucp.shopping.catalog.search', 'dev.ucp.shopping.fulfillment', 'dev.ucp.shopping.policy.return'],
+    'catalog.lookup': ['dev.ucp.shopping.catalog.lookup', 'dev.ucp.shopping.fulfillment', 'dev.ucp.shopping.policy.return'],
+    cart: ['dev.ucp.shopping.cart', 'dev.ucp.shopping.discount', 'dev.ucp.shopping.buyer_consent', 'dev.ucp.shopping.policy.return'],
+    checkout: ['dev.ucp.shopping.checkout', 'dev.ucp.shopping.fulfillment', 'dev.ucp.shopping.discount', 'dev.ucp.shopping.buyer_consent', 'dev.ucp.shopping.policy.return'],
+    order: ['dev.ucp.shopping.order', 'dev.ucp.shopping.policy.return'],
+    ask: ['dev.ucp.common.ask'],
+};
+export function envelope(ctx, op, status = 'success') {
+    const capabilities = {};
+    for (const name of RELEVANT[op])
+        if (ctx.shared.has(name))
+            capabilities[name] = [{ version: UCP_VERSION }];
+    const ucp = { version: UCP_VERSION, status, capabilities };
+    if (op === 'checkout')
+        ucp.payment_handlers = { [SANDBOX_HANDLER]: [{ id: SANDBOX_HANDLER_ID, version: UCP_VERSION, available_instruments: [{ type: 'card' }], config: { environment: 'sandbox' } }] };
+    return ucp;
+}
+export function errorResponse(ctx, op, code, content, extra = {}) {
+    return { ucp: envelope(ctx, op, 'error'), messages: [{ type: 'error', code, content, severity: 'unrecoverable' }], ...extra };
+}
+const err = (code, content, path, severity = 'recoverable') => ({ type: 'error', code, content, severity, ...(path ? { path } : {}) });
+const warn = (code, content, path) => ({ type: 'warning', code, content, ...(path ? { path } : {}) });
+// ---------- the store
+function applied(ctx) {
+    return ctx.record.applied ?? { markets: {}, products: {} };
+}
+function markets(ctx) {
+    return Object.values(applied(ctx).markets);
+}
+/** The market a buyer is in: by country, then by currency, else the first. */
+export function pickMarket(ctx, context) {
+    const all = markets(ctx);
+    if (all.length === 0)
+        return null;
+    const country = context?.address_country?.toUpperCase();
+    const currency = context?.currency?.toUpperCase();
+    return all.find((m) => country && m.countries.includes(country)) ?? all.find((m) => currency && m.currency === currency) ?? all[0];
+}
+function findProduct(ctx, itemId) {
+    const products = applied(ctx).products;
+    return products[itemId] ?? Object.values(products).find((p) => `prod_${p.sku}` === itemId);
+}
+function shippingOption(market) {
+    const s = market.shipping ?? { method: 'Standard', price: 0 };
+    const plain = s.price === 0 ? `Free shipping${s.days ? `, arrives in ${s.days} business days` : ''}` : s.days ? `Arrives in ${s.days} business days` : s.method;
+    return { id: `opt_${market.code}_std`, title: s.method, description: { plain }, totals: [{ type: 'total', amount: toMinor(s.price, market.currency) }] };
+}
+function policyLinks(ctx) {
+    const p = ctx.record.policies ?? {};
+    const url = (name, key) => p[key] ?? `${ctx.origin}/policies/${name}`;
+    return [
+        { type: 'terms_of_service', url: url('terms', 'terms_of_service') },
+        { type: 'privacy_policy', url: url('privacy', 'privacy_policy') },
+        { type: 'refund_policy', url: url('returns', 'returns') },
+    ];
+}
+function returnPolicy(ctx) {
+    if (!ctx.shared.has('dev.ucp.shopping.policy.return'))
+        return [];
+    return [
+        {
+            type: 'dev.ucp.shopping.policy.return',
+            description: { plain: '30-day returns from delivery, refunded to the original payment method.' },
+            eligibility: { type: 'window', duration: 'P30D', anchor: 'delivered' },
+            supported_resolutions: ['original_payment_method'],
+            methods: ['by_mail'],
+            url: policyLinks(ctx)[2].url,
+        },
+    ];
+}
+// ---------- catalog
+function variant(ctx, p, market) {
+    const price = { amount: toMinor(p.prices[market.currency], market.currency), currency: market.currency };
+    const v = {
+        id: p.sku,
+        sku: p.sku,
+        title: p.name,
+        description: { plain: p.description ?? p.name },
+        url: `${ctx.origin}/products/${encodeURIComponent(p.sku)}`,
+        price,
+        // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
+        availability: { available: true, status: 'in_stock' },
+    };
+    if (p.image_url)
+        v.media = [{ type: 'image', url: p.image_url }];
+    if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
+        const o = shippingOption(market);
+        v.fulfillment = { methods: [{ type: 'shipping', description: { plain: `Ships to ${market.countries.join(', ')}` }, availability: v.availability, options: [{ id: o.id, title: o.title, description: o.description }] }] };
+    }
+    return v;
+}
+function product(ctx, p, market) {
+    const v = variant(ctx, p, market);
+    const out = {
+        id: `prod_${p.sku}`,
+        handle: p.sku.toLowerCase(),
+        title: p.name,
+        description: { plain: p.description ?? p.name },
+        url: v.url,
+        price_range: { min: v.price, max: v.price },
+        variants: [v],
+    };
+    if (v.media)
+        out.media = v.media;
+    return out;
+}
+export function searchCatalog(ctx, body) {
+    const market = pickMarket(ctx, body.context);
+    if (!market)
+        return { ucp: envelope(ctx, 'catalog.search'), products: [], pagination: { has_next_page: false, total_count: 0 } };
+    const q = String(body.query ?? '').toLowerCase().trim();
+    const max = body.filters?.price?.max;
+    const min = body.filters?.price?.min;
+    let all = Object.values(applied(ctx).products).filter((p) => p.prices[market.currency] !== undefined);
+    if (q)
+        all = all.filter((p) => `${p.name} ${p.description ?? ''} ${p.sku}`.toLowerCase().includes(q));
+    all = all.filter((p) => (min === undefined || toMinor(p.prices[market.currency], market.currency) >= min) && (max === undefined || toMinor(p.prices[market.currency], market.currency) <= max));
+    const limit = Math.max(1, Number(body.pagination?.limit ?? 10));
+    const offset = Number(body.pagination?.cursor ?? 0) || 0;
+    const page = all.slice(offset, offset + limit);
+    const hasNext = offset + limit < all.length;
+    const out = {
+        ucp: envelope(ctx, 'catalog.search'),
+        products: page.map((p) => product(ctx, p, market)),
+        pagination: { has_next_page: hasNext, total_count: all.length, ...(hasNext ? { cursor: String(offset + limit) } : {}) },
+    };
+    const policies = returnPolicy(ctx);
+    if (policies.length)
+        out.policies = policies;
+    return out;
+}
+export function lookupCatalog(ctx, body) {
+    const market = pickMarket(ctx, body.context);
+    const ids = [...new Set((body.ids ?? []))];
+    const products = [];
+    const messages = [];
+    const seen = new Set();
+    for (const requested of ids) {
+        const p = market ? findProduct(ctx, requested) : undefined;
+        if (!p || !market) {
+            messages.push({ type: 'info', code: 'not_found', content: `No product or variant ${requested}.`, path: `$.ids[${ids.indexOf(requested)}]` });
+            continue;
+        }
+        if (seen.has(p.sku)) {
+            products.find((x) => x.id === `prod_${p.sku}`).variants[0].inputs.push({ id: requested, match: 'exact' });
+            continue;
+        }
+        seen.add(p.sku);
+        const out = product(ctx, p, market);
+        out.variants[0].inputs = [{ id: requested, match: 'exact' }];
+        products.push(out);
+    }
+    const res = { ucp: envelope(ctx, 'catalog.lookup'), products };
+    if (messages.length)
+        res.messages = messages;
+    return res;
+}
+export function getProduct(ctx, body) {
+    const market = pickMarket(ctx, body.context);
+    const p = market && body.id ? findProduct(ctx, String(body.id)) : undefined;
+    if (!p || !market)
+        return errorResponse(ctx, 'catalog.lookup', 'not_found', `No product or variant ${body.id ?? ''}.`);
+    return { ucp: envelope(ctx, 'catalog.lookup'), product: product(ctx, p, market) };
+}
+/** Line items from a request, priced in the market. Unknown or sold-out items are reported, not priced. */
+function buildLines(ctx, market, requested, existing = []) {
+    const lines = [];
+    const messages = [];
+    let n = existing.length;
+    (requested ?? []).forEach((l, i) => {
+        const itemId = String(l?.item?.id ?? '');
+        const quantity = Number(l?.quantity ?? 0);
+        const p = findProduct(ctx, itemId);
+        if (!p || p.prices[market.currency] === undefined) {
+            messages.push(err('item_unavailable', `${itemId || 'An item'} is not sold here.`, `$.line_items[${i}]`));
+            return;
+        }
+        if (!Number.isInteger(quantity) || quantity < 1) {
+            messages.push(err('invalid_quantity', `Quantity must be a positive integer.`, `$.line_items[${i}].quantity`));
+            return;
+        }
+        const price = toMinor(p.prices[market.currency], market.currency);
+        const qty = quantity;
+        const prev = existing.find((e) => e.id === l.id) ?? existing.find((e) => e.item.id === p.sku);
+        const item = { id: p.sku, title: p.name, price };
+        if (p.image_url)
+            item.image_url = p.image_url;
+        lines.push({ id: prev?.id ?? `li_${++n}`, item, quantity: qty, totals: [{ type: 'subtotal', amount: price * qty }, { type: 'total', amount: price * qty }] });
+    });
+    return { lines, messages };
+}
+/** Apply discount codes: the sandbox code is 10% off the items; anything else is rejected with a warning. */
+function discounts(ctx, body, lines, messages) {
+    if (!ctx.shared.has('dev.ucp.shopping.discount') || body.discounts === undefined)
+        return undefined;
+    const codes = (body.discounts.codes ?? []).map((c) => String(c));
+    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
+    const appliedList = [];
+    codes.forEach((code, i) => {
+        if (code.toUpperCase() === SANDBOX_CODE) {
+            if (appliedList.length)
+                messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
+            else
+                appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
+        }
+        else
+            messages.push(warn('discount_code_invalid', `${code} is not a valid code.`, `$.discounts.codes[${i}]`));
+    });
+    return { codes, applied: appliedList };
+}
+function consent(ctx, buyer) {
+    if (!ctx.shared.has('dev.ucp.shopping.buyer_consent') || !buyer?.consent)
+        return undefined;
+    const out = {};
+    for (const [purpose, given] of Object.entries(buyer.consent)) {
+        out[purpose] = { granted: Boolean(given?.granted), source: given?.source === 'business' ? 'business' : 'platform', description: CONSENT_PURPOSES[purpose] ?? purpose };
+    }
+    return out;
+}
+function totals(lines, discount, shipping) {
+    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
+    const out = [{ type: 'subtotal', display_text: 'Subtotal', amount: subtotal }];
+    const off = discount?.applied?.reduce((s, d) => s + d.amount, 0) ?? 0;
+    if (off > 0)
+        out.push({ type: 'discount', display_text: 'Discount', amount: -off });
+    if (shipping !== undefined)
+        out.push({ type: 'fulfillment', display_text: 'Shipping', amount: shipping });
+    out.push({ type: 'total', display_text: shipping === undefined ? 'Estimated total' : 'Total', amount: subtotal - off + (shipping ?? 0) });
+    return out;
+}
+// ---------- carts
+function cartFrom(ctx, body, existing) {
+    const market = pickMarket(ctx, body.context ?? existing?.context);
+    const { lines, messages } = buildLines(ctx, market, body.line_items, existing?.line_items);
+    const discount = discounts(ctx, body, lines, messages);
+    const cart = {
+        ucp: envelope(ctx, 'cart'),
+        id: existing?.id ?? id('cart'),
+        currency: market.currency,
+        line_items: lines,
+        _market: market.code,
+        _platform: ctx.platform,
+    };
+    for (const k of ['context', 'buyer', 'signals', 'attribution'])
+        if (body[k] !== undefined)
+            cart[k] = body[k];
+    const c = consent(ctx, body.buyer);
+    if (c)
+        cart.buyer = { ...(cart.buyer ?? {}), consent: c };
+    if (discount)
+        cart.discounts = discount;
+    cart.totals = totals(lines, discount, undefined);
+    if (messages.length)
+        cart.messages = messages;
+    cart.links = policyLinks(ctx);
+    const policies = returnPolicy(ctx);
+    if (policies.length)
+        cart.policies = policies;
+    cart.continue_url = `${ctx.origin}/carts/${cart.id}`;
+    cart.expires_at = existing?.expires_at ?? later(24 * 7);
+    return cart;
+}
+export function createCart(ctx, body) {
+    if (!pickMarket(ctx, body.context))
+        return { status: 200, body: errorResponse(ctx, 'cart', 'item_unavailable', 'The store has no markets yet.') };
+    const cart = cartFrom(ctx, body);
+    if (cart.line_items.length === 0 && (body.line_items ?? []).length > 0) {
+        return { status: 200, body: errorResponse(ctx, 'cart', 'item_unavailable', 'None of the items can be sold here.', { continue_url: ctx.origin }) };
+    }
+    ctx.record.ucp.carts[cart.id] = cart;
+    return { status: 201, body: cart };
+}
+export function getCart(ctx, cartId) {
+    return ctx.record.ucp.carts[cartId] ?? errorResponse(ctx, 'cart', 'not_found', `No cart ${cartId}.`);
+}
+export function updateCart(ctx, cartId, body) {
+    const existing = ctx.record.ucp.carts[cartId];
+    if (!existing)
+        return errorResponse(ctx, 'cart', 'not_found', `No cart ${cartId}.`);
+    const cart = cartFrom(ctx, body, existing);
+    ctx.record.ucp.carts[cartId] = cart;
+    return cart;
+}
+export function cancelCart(ctx, cartId) {
+    const existing = ctx.record.ucp.carts[cartId];
+    if (!existing)
+        return errorResponse(ctx, 'cart', 'not_found', `No cart ${cartId}.`);
+    delete ctx.record.ucp.carts[cartId];
+    return existing;
+}
+// ---------- checkouts
+/** Recompute everything the business decides on a checkout: lines, fulfillment, totals, status. */
+function evaluate(ctx, ck, requested) {
+    const market = markets(ctx).find((m) => m.code === ck._market);
+    const { lines, messages } = buildLines(ctx, market, requested.line_items ?? ck.line_items, ck.line_items);
+    ck.line_items = lines;
+    if (lines.length === 0)
+        messages.push(err('item_unavailable', 'The checkout has no purchasable items.', '$.line_items'));
+    const discount = discounts(ctx, requested, lines, messages);
+    if (discount)
+        ck.discounts = discount;
+    else
+        delete ck.discounts;
+    if (!ck.buyer?.email)
+        messages.push(err('missing', 'An email address is needed for the order confirmation.', '$.buyer.email'));
+    let shipping;
+    if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
+        const sent = requested.fulfillment?.methods?.[0] ?? {};
+        const method = { id: 'ful_ship', type: 'shipping', line_item_ids: lines.map((l) => l.id) };
+        const destinations = (sent.destinations ?? ck.fulfillment?.methods?.[0]?.destinations ?? []).map((d, i) => ({ type: 'shipping_address', ...d, id: d.id ?? `dest_${i + 1}`, type_: undefined }));
+        for (const d of destinations)
+            delete d.type_;
+        const selectedId = sent.selected_destination_id ?? ck.fulfillment?.methods?.[0]?.selected_destination_id ?? null;
+        method.destinations = destinations;
+        method.selected_destination_id = selectedId;
+        const selected = destinations.find((d) => d.id === selectedId);
+        if (!selected) {
+            method.groups = [];
+            messages.push(err('missing', 'A shipping address is needed.', '$.fulfillment.methods[0].selected_destination_id'));
+        }
+        else if (!market.countries.includes(String(selected.address_country ?? '').toUpperCase())) {
+            method.groups = [];
+            messages.push(err('address_undeliverable', `This store ships to ${market.countries.join(', ')} in the ${market.name} market.`, `$.fulfillment.methods[0].destinations[${destinations.indexOf(selected)}].address_country`));
+        }
+        else {
+            const option = shippingOption(market);
+            const wanted = sent.groups?.[0]?.selected_option_id;
+            if (wanted && wanted !== option.id)
+                messages.push(warn('fulfillment_changed', `Option ${wanted} is not offered; ${option.title} selected.`, '$.fulfillment.methods[0].groups[0].selected_option_id'));
+            method.groups = [{ id: 'grp_1', line_item_ids: method.line_item_ids, options: [option], selected_option_id: option.id }];
+            shipping = option.totals[0].amount;
+        }
+        ck.fulfillment = { methods: [method], available_methods: [{ type: 'shipping', line_item_ids: method.line_item_ids, fulfillable_on: 'now' }] };
+    }
+    else
+        shipping = 0;
+    ck.totals = totals(lines, discount, shipping);
+    const blocking = messages.some((m) => m.type === 'error');
+    ck.status = blocking ? 'incomplete' : 'ready_for_complete';
+    if (messages.length)
+        ck.messages = messages;
+    else
+        delete ck.messages;
+    ck.continue_url = `${ctx.origin}/checkout-sessions/${ck.id}`;
+    ck.links = policyLinks(ctx);
+    const policies = returnPolicy(ctx);
+    if (policies.length)
+        ck.policies = policies;
+    else
+        delete ck.policies;
+}
+function copyInputs(ctx, ck, body) {
+    for (const k of ['buyer', 'context', 'signals', 'attribution']) {
+        if (body[k] !== undefined)
+            ck[k] = body[k];
+    }
+    const c = consent(ctx, body.buyer);
+    if (c)
+        ck.buyer = { ...(ck.buyer ?? {}), consent: c };
+}
+export function createCheckout(ctx, body) {
+    const checkouts = ctx.record.ucp.checkouts;
+    let seed = body;
+    let cartId;
+    if (body.cart_id !== undefined) {
+        if (!ctx.shared.has('dev.ucp.shopping.cart'))
+            return { status: 200, body: errorResponse(ctx, 'checkout', 'capabilities_incompatible', 'cart_id needs the cart capability, which is not negotiated.') };
+        const cart = ctx.record.ucp.carts[body.cart_id];
+        if (!cart)
+            return { status: 200, body: errorResponse(ctx, 'checkout', 'not_found', `No cart ${body.cart_id}.`) };
+        const open = Object.values(checkouts).find((c) => c._cart_id === body.cart_id && c.status === 'incomplete');
+        if (open)
+            return { status: 200, body: open };
+        cartId = cart.id;
+        seed = { ...cart, ...body, line_items: cart.line_items.map((l) => ({ item: { id: l.item.id }, quantity: l.quantity })), discounts: cart.discounts ? { codes: cart.discounts.codes } : body.discounts, context: body.context ?? cart.context, buyer: body.buyer ?? cart.buyer };
+    }
+    else if (!Array.isArray(body.line_items)) {
+        return { status: 200, body: errorResponse(ctx, 'checkout', 'missing', 'A checkout needs line_items or a cart_id.') };
+    }
+    const market = pickMarket(ctx, seed.context);
+    if (!market)
+        return { status: 200, body: errorResponse(ctx, 'checkout', 'item_unavailable', 'The store has no markets yet.') };
+    const ck = { ucp: envelope(ctx, 'checkout'), id: id('chk'), status: 'incomplete', currency: market.currency, line_items: [], _market: market.code, _platform: ctx.platform, _created: now().toISOString() };
+    if (cartId)
+        ck._cart_id = cartId;
+    copyInputs(ctx, ck, seed);
+    evaluate(ctx, ck, seed);
+    if (ck.line_items.length === 0)
+        return { status: 200, body: errorResponse(ctx, 'checkout', 'item_unavailable', 'None of the items can be sold here.', { continue_url: ctx.origin }) };
+    ck.expires_at = later(6);
+    checkouts[ck.id] = ck;
+    return { status: 201, body: ck };
+}
+export function getCheckout(ctx, ckId) {
+    return ctx.record.ucp.checkouts[ckId] ?? errorResponse(ctx, 'checkout', 'not_found', `No checkout ${ckId}.`);
+}
+export function updateCheckout(ctx, ckId, body) {
+    const ck = ctx.record.ucp.checkouts[ckId];
+    if (!ck)
+        return errorResponse(ctx, 'checkout', 'not_found', `No checkout ${ckId}.`);
+    if (ck.status === 'completed' || ck.status === 'canceled') {
+        return { ...ck, messages: [err('not_allowed', `The checkout is ${ck.status} and cannot change.`, '$.status', 'unrecoverable')] };
+    }
+    if (ck.status === 'complete_in_progress')
+        return { ...ck, messages: [err('in_progress', 'Completion is in progress; wait for it.', '$.status')] };
+    if (!Array.isArray(body.line_items))
+        return { ...ck, messages: [err('missing', 'Update Checkout replaces the whole checkout: send line_items.', '$.line_items')] };
+    copyInputs(ctx, ck, body);
+    evaluate(ctx, ck, body);
+    return ck;
+}
+export function cancelCheckout(ctx, ckId) {
+    const ck = ctx.record.ucp.checkouts[ckId];
+    if (!ck)
+        return errorResponse(ctx, 'checkout', 'not_found', `No checkout ${ckId}.`);
+    if (ck.status === 'completed' || ck.status === 'canceled')
+        return { ...ck, messages: [err('not_allowed', `The checkout is ${ck.status}.`, '$.status', 'unrecoverable')] };
+    ck.status = 'canceled';
+    delete ck.continue_url;
+    delete ck.messages;
+    return ck;
+}
+export function completeCheckout(ctx, ckId, body) {
+    const ck = ctx.record.ucp.checkouts[ckId];
+    if (!ck)
+        return errorResponse(ctx, 'checkout', 'not_found', `No checkout ${ckId}.`);
+    if (ck.status === 'completed')
+        return ck;
+    if (ck.status !== 'ready_for_complete') {
+        return { ...ck, messages: [...(ck.messages ?? []), err('not_ready', `The checkout is ${ck.status}; resolve its messages first.`, '$.status', ck.status === 'canceled' ? 'unrecoverable' : 'recoverable')] };
+    }
+    const instruments = body.payment?.instruments ?? [];
+    const reject = (content, path = '$.payment.instruments') => ({ ...ck, messages: [err('payment_failed', content, path)] });
+    if (instruments.length !== 1)
+        return reject('Exactly one payment instrument is needed.');
+    const [pi] = instruments;
+    if (pi.handler_id !== SANDBOX_HANDLER_ID)
+        return reject(`Unknown payment handler ${pi.handler_id}; this store accepts ${SANDBOX_HANDLER_ID}.`, '$.payment.instruments[0].handler_id');
+    if (pi.type !== 'card')
+        return reject(`Instrument type ${pi.type} is not accepted; use card.`, '$.payment.instruments[0].type');
+    if (pi.credential?.type !== SANDBOX_CREDENTIAL_TYPE)
+        return reject(`Credential type must be ${SANDBOX_CREDENTIAL_TYPE}.`, '$.payment.instruments[0].credential.type');
+    if (pi.credential.token === SANDBOX_TOKEN_DECLINED)
+        return reject('The card was declined.', '$.payment.instruments[0]');
+    if (pi.credential.token !== SANDBOX_TOKEN_SUCCESS)
+        return reject(`Unknown sandbox token; use ${SANDBOX_TOKEN_SUCCESS} or ${SANDBOX_TOKEN_DECLINED}.`, '$.payment.instruments[0].credential.token');
+    if (body.signals)
+        ck.signals = body.signals;
+    if (body.attribution)
+        ck.attribution = body.attribution;
+    const { token: _t, ...credential } = pi.credential;
+    ck.payment = { instruments: [{ ...pi, selected: true, credential }] };
+    const order = placeOrder(ctx, ck);
+    ck.status = 'completed';
+    ck.order = { id: order.id, label: order.label, permalink_url: order.permalink_url };
+    delete ck.continue_url;
+    delete ck.expires_at;
+    delete ck.messages;
+    return ck;
+}
+function placeOrder(ctx, ck) {
+    const orders = ctx.record.ucp.orders;
+    const orderId = id('ord');
+    const method = ck.fulfillment?.methods?.[0];
+    const destination = method?.destinations?.find((d) => d.id === method.selected_destination_id);
+    const option = method?.groups?.[0]?.options?.find((o) => o.id === method.groups[0].selected_option_id);
+    const { type: _type, id: _id, ...address } = destination ?? {};
+    const order = {
+        ucp: envelope(ctx, 'order'),
+        id: orderId,
+        label: `#${1001 + Object.keys(orders).length}`,
+        checkout_id: ck.id,
+        permalink_url: `${ctx.origin}/orders/${orderId}`,
+        currency: ck.currency,
+        line_items: ck.line_items.map((l) => ({ id: l.id, item: l.item, quantity: { original: l.quantity, total: l.quantity, fulfilled: 0 }, totals: l.totals, status: 'processing' })),
+        fulfillment: {
+            expectations: destination
+                ? [{ id: 'exp_1', line_items: ck.line_items.map((l) => ({ id: l.id, quantity: l.quantity })), method_type: 'shipping', destination: address, description: option?.description?.plain ?? option?.title, fulfillable_on: 'now' }]
+                : [],
+            events: [],
+        },
+        adjustments: [],
+        totals: ck.totals,
+        _platform: ck._platform,
+    };
+    if (ck.policies)
+        order.policies = ck.policies;
+    if (ck.attribution)
+        order.attribution = ck.attribution;
+    if (ck.buyer)
+        order._buyer = ck.buyer;
+    orders[orderId] = order;
+    const webhook = platformWebhook(ctx);
+    if (webhook)
+        ctx.record.ucp.webhooks.push({ id: crypto.randomUUID(), timestamp: Math.floor(Date.now() / 1000), url: webhook, order_id: orderId, status: 'pending' });
+    return order;
+}
+function platformWebhook(ctx) {
+    return ctx.webhookUrl ?? null;
+}
+export function getOrder(ctx, orderId) {
+    return ctx.record.ucp.orders[orderId] ?? null;
+}
+// ---------- ask
+export function ask(ctx, body) {
+    const market = pickMarket(ctx, body.context);
+    const products = Object.values(applied(ctx).products);
+    const name = ctx.record.name ?? ctx.record.org;
+    const q = String(body.query ?? '').toLowerCase();
+    const price = (p) => (market ? `${p.prices[market.currency]} ${market.currency}` : '');
+    let plain;
+    if (products.length === 0)
+        plain = `${name} has no products yet.`;
+    else {
+        const hits = products.filter((p) => q && `${p.name} ${p.description ?? ''}`.toLowerCase().split(/\W+/).some((w) => w.length > 2 && q.includes(w)));
+        const list = (hits.length ? hits : products).map((p) => `${p.name} (${p.sku}, ${price(p)})`).join('; ');
+        plain = hits.length ? `${name} sells ${list}.` : `${name} sells ${products.length} products: ${list}. Ships to ${markets(ctx).flatMap((m) => m.countries).join(', ')}.`;
+    }
+    const out = { ucp: envelope(ctx, 'ask'), answer: { plain }, links: policyLinks(ctx).map((l) => ({ ...l, title: l.type.replace(/_/g, ' ') })) };
+    if (body.conversation?.id)
+        out.conversation = { id: body.conversation.id, expires_at: later(1) };
+    if (/\b(buy|order|cancel|refund|add to cart|checkout|pay)\b/.test(q)) {
+        out.messages = [{ type: 'info', code: 'operation_not_performed', content: 'Ask answers questions only; use the cart and checkout capabilities to buy.' }];
+    }
+    return out;
+}