@commercelayer/agent-cli 0.8.1 → 1.0.0-dev.1

package/dist/api/stub/shopping.js

@@ -1,673 +0,0 @@
-// 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';
-import { baseLanguage, marketLocale, texts } from './locale.js';
-import { queryWords, rank } from './search.js';
-const lang = (ctx) => ctx.language ?? baseLanguage(ctx.record);
-/** 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
-/** A path in the storefront (img/eth.jpg) is served from the store host: shopping agents always get a full URL,
- * and for a product without an image, its tile. */
-const imageUrl = (ctx, p) => new URL(p.image_url ?? `tiles/${encodeURIComponent(p.sku)}.svg${lang(ctx) === baseLanguage(ctx.record) ? '' : `?lang=${lang(ctx)}`}`, `${ctx.origin}/`).href;
-/** A product page: under the locale of the buyer's country when it is in the market, else the market's first. */
-function productUrl(ctx, p, market) {
-    if (ctx.record.storefront_mode === 'agent-only')
-        return undefined;
-    const l = marketLocale(ctx.record, market.code, ctx.country);
-    return `${ctx.origin}${l ? `/${l.path}` : ''}/products/${encodeURIComponent(p.sku)}`;
-}
-/** asked: the country the buyer asked about (filters.fulfills_to, else context), whose shipping the variant answers for. */
-function variant(ctx, p, market, asked) {
-    const price = { amount: toMinor(p.prices[market.currency], market.currency), currency: market.currency };
-    const v = {
-        id: p.sku,
-        sku: p.sku,
-        title: texts(p, lang(ctx)).name,
-        description: { plain: texts(p, lang(ctx)).description ?? texts(p, lang(ctx)).name },
-        // Agent-only stores have no product pages to link to.
-        url: productUrl(ctx, p, market),
-        price,
-        // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
-        availability: { available: true, status: 'in_stock' },
-        // Like the store: which market the price is for. tax_included comes from a Commerce Layer price list: none here.
-        metadata: { prices: { market: market.code, market_name: market.name, currency: market.currency, countries: market.countries } },
-    };
-    v.media = [{ type: 'image', url: imageUrl(ctx, p) }];
-    if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
-        const o = shippingOption(market);
-        // days is "3" or "3-5": the earliest and latest arrival, at noon UTC.
-        const [first, last = first] = String(market.shipping?.days ?? '0').split('-').map((d) => Number(d.trim()) || 0);
-        const day = (n) => {
-            const at = new Date(Date.now() + n * 86_400_000);
-            at.setUTCHours(12, 0, 0, 0);
-            return at.toISOString().replace('.000', '');
-        };
-        const ships = !asked || market.countries.includes(asked.toUpperCase());
-        const availability = ships ? v.availability : { available: false, status: 'out_of_stock' };
-        const method = {
-            type: 'shipping',
-            description: { plain: `Ships to ${market.countries.join(', ')}` },
-            ships_to: market.countries,
-            availability,
-            options: ships ? [{ id: o.id, title: o.title, description: o.description, totals: [{ type: 'fulfillment', display_text: 'Shipping', amount: o.totals[0].amount }], earliest_fulfillment_time: day(first), latest_fulfillment_time: day(last) }] : [],
-        };
-        if (asked)
-            method.destination = { address_country: asked.toUpperCase(), ships };
-        // Like the store: the variant stays available; the method says it does not ship there.
-        v.fulfillment = { methods: [method] };
-    }
-    return v;
-}
-function product(ctx, p, market, asked, match) {
-    const v = variant(ctx, p, market, asked);
-    const out = {
-        id: `prod_${p.sku}`,
-        handle: p.sku.toLowerCase(),
-        title: v.title,
-        description: v.description,
-        url: v.url,
-        price_range: { min: v.price, max: v.price },
-        variants: [v],
-    };
-    if (v.media)
-        out.media = v.media;
-    // Like the store: the base language's path, which filters.categories matches.
-    if (p.category)
-        out.categories = [{ value: p.category, taxonomy: 'merchant' }];
-    if (match && match.words.length)
-        out.metadata = { search: { score: match.score, all_words: match.all, words: match.words, matched_on: match.matched } };
-    return out;
-}
-/** A category path folded as the store folds it: case and spacing, not accents. */
-const categoryKey = (c) => c.split('>').map((l) => l.trim().toLowerCase().replace(/\s+/g, ' ')).join(' > ');
-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 ?? '').trim();
-    const max = body.filters?.price?.max;
-    const min = body.filters?.price?.min;
-    const asked = body.filters?.fulfills_to?.address_country ?? body.context?.address_country;
-    // Like the store: filters.fulfills_to restricts the results to what ships there (context alone only seeds availability).
-    const shipsTo = body.filters?.fulfills_to?.address_country?.toUpperCase();
-    if (shipsTo && !market.countries.includes(shipsTo)) {
-        const other = markets(ctx).find((m) => m.countries.includes(shipsTo));
-        const content = other
-            ? `The ${market.name} market ships to ${market.countries.join(', ')}, not to ${shipsTo}. The ${other.name} market (${other.currency}) does: send context.address_country ${shipsTo} for its prices.`
-            : `The store does not ship to ${shipsTo}.`;
-        return { ucp: envelope(ctx, 'catalog.search'), products: [], pagination: { has_next_page: false, total_count: 0 }, messages: [{ type: 'info', code: 'no_results', path: '$.filters.fulfills_to.address_country', content }] };
-    }
-    let all = Object.values(applied(ctx).products).filter((p) => p.prices[market.currency] !== undefined);
-    // Like the store: a category matches itself and the paths below it, by whole levels.
-    const wanted = (body.filters?.categories ?? []).map((c) => categoryKey(String(c)));
-    if (wanted.length)
-        all = all.filter((p) => p.category && wanted.some((w) => categoryKey(p.category) === w || categoryKey(p.category).startsWith(`${w} > `)));
-    all = all.filter((p) => (min === undefined || toMinor(p.prices[market.currency], market.currency) >= min) && (max === undefined || toMinor(p.prices[market.currency], market.currency) <= max));
-    // Like the store: words in any order, ranked; every word before some of them.
-    const ranked = rank(all, q);
-    const limit = Math.max(1, Number(body.pagination?.limit ?? 10));
-    const offset = Number(body.pagination?.cursor ?? 0) || 0;
-    const page = ranked.slice(offset, offset + limit);
-    const hasNext = offset + limit < ranked.length;
-    const out = {
-        ucp: envelope(ctx, 'catalog.search'),
-        products: page.map(({ product: p, match }) => product(ctx, p, market, asked, match)),
-        pagination: { has_next_page: hasNext, total_count: ranked.length, ...(hasNext ? { cursor: String(offset + limit) } : {}) },
-    };
-    const categories = [...new Set(Object.values(applied(ctx).products).map((p) => p.category).filter(Boolean))].sort().join('; ');
-    const messages = [];
-    const words = queryWords(q);
-    if (!ranked.length)
-        messages.push({ type: 'info', code: 'no_results', content: `No products match${words.length ? `: searched the words "${words.join(' ')}" in titles, categories and descriptions, in any order` : ''}.${categories ? ` The store's categories: ${categories}.` : ''} Retry with fewer or other words, or with one of them in filters.categories.` });
-    else if (words.length > 1 && !ranked[0].match.all)
-        messages.push({ type: 'info', code: 'partial_match', content: `No product has every word of "${q}"; these have some of them (${words.join(', ')}), best first.${categories ? ` The store's categories: ${categories}.` : ''}` });
-    if (!body.context?.address_country && !body.context?.currency)
-        messages.push({ type: 'info', code: 'prices', content: `Prices are in ${market.currency} for the ${market.name} market (${market.countries.join(', ')}). Send context.address_country for another country's prices and shipping.` });
-    if (messages.length)
-        out.messages = messages;
-    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: texts(p, lang(ctx)).name, price };
-        item.image_url = imageUrl(ctx, p);
-        lines.push({ id: prev?.id ?? `li_${++n}`, item, quantity: qty, totals: [{ type: 'subtotal', amount: price * qty }, { type: 'total', amount: price * qty }] });
-    });
-    return { lines, messages };
-}
-/** The promotions that match these lines and codes, as Commerce Layer applies them: by priority, an exclusive one alone. */
-function promotionDiscounts(ctx, market, lines, codes, shipping) {
-    const now = Date.now();
-    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
-    const upper = codes.map((c) => c.toUpperCase());
-    const used = new Set();
-    const matching = [];
-    for (const p of Object.values(ctx.record.promotions ?? {})) {
-        if (!p.enabled || p.flex || !p.actions || Date.parse(p.starts) > now || Date.parse(p.ends) <= now)
-            continue;
-        if (p.market && p.market !== market.code)
-            continue;
-        const r = p.rules ?? {};
-        const code = r.coupons?.find((c) => upper.includes(c.toUpperCase()));
-        if (r.coupons && !code)
-            continue;
-        if (code)
-            used.add(code.toUpperCase());
-        if (r.order_amount && subtotal < toMinor(r.order_amount.min, market.currency))
-            continue;
-        if (r.skus && !lines.some((l) => r.skus.includes(l.item.id)))
-            continue;
-        matching.push({ p, code });
-    }
-    matching.sort((a, b) => (a.p.priority ?? Infinity) - (b.p.priority ?? Infinity));
-    const exclusive = matching.find((m) => m.p.exclusive);
-    const applied = [];
-    for (const { p, code } of exclusive ? [exclusive] : matching) {
-        let amount = 0;
-        for (const a of p.actions) {
-            const on = (skus) => lines.filter((l) => !skus || skus.includes(l.item.id));
-            const units = (skus) => on(skus).flatMap((l) => Array(l.quantity).fill(l.item.price)).sort((x, y) => x - y);
-            if (a.type === 'percentage')
-                amount += Math.floor((on(a.skus).reduce((s, l) => s + l.totals[0].amount, 0) * a.value) / 100);
-            else if (a.type === 'fixed_amount')
-                amount += Math.min(toMinor(a.value, market.currency), subtotal);
-            else if (a.type === 'free_shipping')
-                amount += shipping ?? 0;
-            else if (a.type === 'fixed_price')
-                amount += on(a.skus).reduce((s, l) => s + Math.max(0, l.item.price - toMinor(a.price, market.currency)) * l.quantity, 0);
-            else if (a.type === 'free_gift')
-                amount += units(a.skus).slice(0, a.quantity).reduce((s, x) => s + x, 0);
-            else if (a.cheapest_free) {
-                const all = units(a.skus);
-                amount += all.slice(0, Math.floor(all.length / a.x) * (a.x - a.y)).reduce((s, x) => s + x, 0);
-            }
-            else
-                amount += on(a.skus).reduce((s, l) => s + Math.floor(l.quantity / a.x) * (a.x - a.y) * l.item.price, 0);
-        }
-        if (amount > 0)
-            applied.push({ ...(code ? { code } : {}), title: p.name, amount, ...(code ? {} : { automatic: true }), method: 'across' });
-    }
-    return { applied, used };
-}
-/**
- * Discounts: the store's promotions (automatic ones, and those whose code was entered) plus the
- * sandbox code, 10% off the items. A code that applies nothing is reported with a warning.
- */
-function discounts(ctx, body, lines, messages, market, shipping) {
-    if (!ctx.shared.has('dev.ucp.shopping.discount'))
-        return undefined;
-    const codes = (body.discounts?.codes ?? []).map((c) => String(c));
-    const subtotal = lines.reduce((s, l) => s + l.totals[0].amount, 0);
-    const { applied: appliedList, used } = promotionDiscounts(ctx, market, lines, codes, shipping);
-    const seen = new Set();
-    codes.forEach((code, i) => {
-        const key = code.toUpperCase();
-        if (seen.has(key))
-            messages.push(warn('discount_code_already_applied', `${code} is already applied.`, `$.discounts.codes[${i}]`));
-        else if (key === SANDBOX_CODE)
-            appliedList.push({ code: SANDBOX_CODE, title: '10% off', amount: Math.floor(subtotal / 10), method: 'across' });
-        else if (!used.has(key))
-            messages.push(warn('discount_code_invalid', `${code} is not a valid code.`, `$.discounts.codes[${i}]`));
-        else if (!appliedList.some((d) => d.code?.toUpperCase() === key))
-            messages.push(warn('discount_code_invalid', `${code} does not apply to this order.`, `$.discounts.codes[${i}]`));
-        seen.add(key);
-    });
-    if (body.discounts === undefined && !appliedList.length)
-        return undefined;
-    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, market);
-    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'));
-    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;
-    const discount = discounts(ctx, requested, lines, messages, market, shipping);
-    if (discount)
-        ck.discounts = discount;
-    else
-        delete ck.discounts;
-    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;
-    // What the merchant view of the order reads (stub/orders.ts): it lands placed, payment authorized.
-    Object.assign(order, { _placed_at: new Date().toISOString(), _market: ck._market, _cart_id: ck._cart_id, _codes: ck.discounts?.codes ?? [], _language: lang(ctx) });
-    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;
-}