@commercelayer/agent-cli 0.3.1 → 0.5.1

package/dist/api/stub/orders.js

@@ -0,0 +1,359 @@
+// Orders and shipments as the merchant manages them, the API's view=merchant and
+// /shipments routes: the stub keeps the Commerce Layer state machine on each UCP
+// order, in _merchant, so the tests cover the same transitions as the platform.
+//
+// An order lands placed with its payment authorized. approve (optionally with
+// capture), capture, cancel, refund, archive and unarchive move it; its one shipment
+// goes upcoming → on_hold | picking | packing | ready_to_ship → shipped → delivered.
+import { money } from '../../ucp/shop.js';
+import { minorUnits } from '../../ucp/platform.js';
+import { baseLanguage } from './locale.js';
+export const ORDER_STATUSES = ['placed', 'approved', 'cancelled', 'editing'];
+export const PAYMENT_STATUSES = ['unpaid', 'authorized', 'partially_authorized', 'paid', 'partially_paid', 'voided', 'partially_voided', 'refunded', 'partially_refunded', 'free'];
+export const FULFILLMENT_STATUSES = ['unfulfilled', 'in_progress', 'fulfilled', 'not_required'];
+export const SHIPMENT_STATUSES = ['upcoming', 'on_hold', 'picking', 'packing', 'ready_to_ship', 'shipped', 'delivered', 'cancelled'];
+const OPEN_SHIPMENTS = ['upcoming', 'on_hold', 'picking', 'packing', 'ready_to_ship'];
+const WORKING = ['on_hold', 'picking', 'packing', 'ready_to_ship'];
+export class OrderError extends Error {
+    status;
+    code;
+    hint;
+    constructor(status, code, message, hint) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+const now = () => new Date().toISOString();
+const number = (o) => o.label.replace(/^#/, '');
+const total = (o) => o.totals.find((t) => t.type === 'total')?.amount ?? 0;
+const sum = (o, type) => merchant(o).transactions.filter((t) => t.type === type && t.succeeded).reduce((s, t) => s + t.amount, 0);
+/** The merchant state of an order, created on first use as Commerce Layer has it after placement. */
+function merchant(o) {
+    if (!o._merchant) {
+        const at = o._placed_at ?? now();
+        o._merchant = {
+            status: 'placed',
+            placed_at: at,
+            archived_at: null,
+            transactions: [{ type: 'authorization', amount: total(o), succeeded: true, at }],
+            shipment: { id: `shp_${o.id.replace(/^ord_/, '')}`, number: `${number(o)}/S/001`, status: 'upcoming', tracking: null, dates: { created_at: at, on_hold_at: null, picking_at: null, packing_at: null, ready_to_ship_at: null, shipped_at: null, delivered_at: null } },
+        };
+    }
+    return o._merchant;
+}
+function paymentStatus(o) {
+    if (total(o) === 0)
+        return 'free';
+    const captured = sum(o, 'capture');
+    const refunded = sum(o, 'refund');
+    if (sum(o, 'void') > 0)
+        return 'voided';
+    if (refunded > 0)
+        return refunded >= captured ? 'refunded' : 'partially_refunded';
+    if (captured > 0)
+        return captured >= total(o) ? 'paid' : 'partially_paid';
+    return 'authorized';
+}
+function fulfillmentStatus(o) {
+    const s = merchant(o).shipment.status;
+    if (s === 'shipped' || s === 'delivered')
+        return 'fulfilled';
+    if (WORKING.includes(s))
+        return 'in_progress';
+    return 'unfulfilled';
+}
+const destination = (o) => o.fulfillment?.expectations?.[0]?.destination ?? {};
+const units = (o) => o.line_items.reduce((s, l) => s + (l.quantity?.total ?? l.quantity ?? 0), 0);
+function shipmentRef(o) {
+    const s = merchant(o).shipment;
+    return { id: s.id, number: s.number, status: s.status, tracking: s.tracking };
+}
+function row(o) {
+    const m = merchant(o);
+    return {
+        id: o.id,
+        number: number(o),
+        status: m.status,
+        payment_status: paymentStatus(o),
+        fulfillment_status: fulfillmentStatus(o),
+        placed_at: m.placed_at,
+        market: o._market ?? null,
+        country: destination(o).address_country ?? null,
+        currency: o.currency,
+        total: money(total(o), o.currency),
+        email: o._buyer?.email ?? null,
+        items: units(o),
+        shipments: [shipmentRef(o)],
+        archived: m.archived_at !== null,
+    };
+}
+function address(o) {
+    const d = destination(o);
+    if (!Object.keys(d).length)
+        return null;
+    return {
+        name: [d.first_name, d.last_name].filter(Boolean).join(' ') || null,
+        company: null,
+        line_1: d.street_address ?? null,
+        line_2: d.extended_address ?? null,
+        city: d.address_locality ?? null,
+        zip_code: d.postal_code ?? null,
+        state_code: d.address_region ?? null,
+        country_code: d.address_country ?? null,
+        phone: o._buyer?.phone_number ?? null,
+    };
+}
+function detail(o, r) {
+    const m = merchant(o);
+    const cur = o.currency;
+    const amount = (type) => o.totals.filter((t) => t.type === type).reduce((s, t) => s + t.amount, 0);
+    const captured = sum(o, 'capture') - sum(o, 'refund');
+    return {
+        ...row(o),
+        line_items: o.line_items.map((l) => ({
+            item_id: l.item?.id,
+            sku: l.item?.id,
+            name: l.item?.title,
+            quantity: l.quantity?.total ?? l.quantity,
+            unit_price: money(l.item?.price ?? 0, cur),
+            total: money(l.totals?.find((t) => t.type === 'total')?.amount ?? 0, cur),
+        })),
+        totals: { subtotal: money(amount('subtotal'), cur), discount: money(amount('discount'), cur), shipping: money(amount('fulfillment'), cur), taxes: money(amount('tax'), cur), total: money(total(o), cur), codes: o._codes ?? [] },
+        shipping_address: address(o),
+        billing_address: address(o),
+        shipping_method: o.fulfillment?.expectations?.[0]?.description ?? null,
+        payment: { method: 'Sandbox', source: 'sandbox wire transfer', status: paymentStatus(o), captured: money(Math.max(0, sum(o, 'capture')), cur), refundable: money(Math.max(0, captured), cur) },
+        transactions: m.transactions.map((t) => ({ ...t, amount: money(t.amount, cur) })),
+        language: o._language ?? baseLanguage(r),
+        archived_at: m.archived_at,
+        ucp: { id: o.id, permalink_url: o.permalink_url },
+    };
+}
+const orders = (r) => Object.values(r.ucp.orders).slice().reverse();
+/** An order by id, number, #number, or the checkout or cart it came from. */
+function findOrder(r, wanted) {
+    const o = orders(r).find((x) => x.id === wanted || x.label === wanted || x.label === `#${wanted}` || x.checkout_id === wanted || x._cart_id === wanted);
+    if (!o)
+        throw new OrderError(404, 'not_found', `There is no order ${wanted}.`, 'Run `c11r orders list` to see the orders.');
+    return o;
+}
+/** The commands an order allows now, as the API names them in its hints. */
+function orderCommands(o) {
+    const m = merchant(o);
+    const n = number(o);
+    const pay = paymentStatus(o);
+    const out = [];
+    if (m.status === 'placed')
+        out.push(`c11r orders approve ${n} [--capture]`);
+    if (m.status === 'approved' && pay === 'authorized')
+        out.push(`c11r orders capture ${n}`);
+    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status) && ['authorized', 'free'].includes(pay))
+        out.push(`c11r orders cancel ${n}`);
+    if (['paid', 'partially_refunded'].includes(pay))
+        out.push(`c11r orders refund ${n} [--amount <major>]`);
+    out.push(m.archived_at ? `c11r orders unarchive ${n}` : `c11r orders archive ${n}`);
+    return out;
+}
+const refuse = (what, allowed) => {
+    throw new OrderError(422, 'invalid_transition', what, `Allowed now: ${allowed.join('; ')}.`);
+};
+export function listOrders(r, q) {
+    const list = (name, allowed, fallback) => {
+        const raw = q.get(name);
+        if (!raw)
+            return fallback;
+        const vs = raw.split(',').map((v) => v.trim());
+        if (vs.includes('all'))
+            return allowed;
+        for (const v of vs)
+            if (!allowed.includes(v))
+                throw new OrderError(422, 'invalid_argument', `${name}=${v} is not one of ${allowed.join(', ')}, all.`, `Use --${name} with one of ${allowed.join(', ')}, or all.`);
+        return vs;
+    };
+    const statuses = list('status', ORDER_STATUSES, ['placed', 'approved']);
+    const payments = list('payment', PAYMENT_STATUSES, PAYMENT_STATUSES);
+    const fulfillments = list('fulfillment', FULFILLMENT_STATUSES, FULFILLMENT_STATUSES);
+    const archived = q.get('archived') ?? 'false';
+    if (!['true', 'false', 'all'].includes(archived))
+        throw new OrderError(422, 'invalid_argument', `archived=${archived} is not true, false or all.`, 'Use --archived for only archived orders, --archived all for every order.');
+    const limit = q.get('limit') === null ? 25 : Number(q.get('limit'));
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new OrderError(422, 'invalid_argument', `limit=${q.get('limit')} is not between 1 and 100.`, 'Use --limit with a number from 1 to 100.');
+    const rows = orders(r)
+        .map(row)
+        // Archived orders are listed only when asked for, whatever their status.
+        .filter((x) => (archived === 'all' ? true : archived === 'true' ? x.archived : !x.archived))
+        .filter((x) => (archived === 'true' && !q.get('status') ? true : statuses.includes(x.status)))
+        .filter((x) => payments.includes(x.payment_status) && fulfillments.includes(x.fulfillment_status));
+    return { orders: rows.slice(0, limit) };
+}
+export const showOrder = (r, id) => detail(findOrder(r, id), r);
+export function orderAction(r, id, action, body) {
+    const o = findOrder(r, id);
+    const m = merchant(o);
+    const at = now();
+    const capture = () => {
+        m.transactions.push({ type: 'capture', amount: total(o) - sum(o, 'capture'), succeeded: true, at });
+    };
+    switch (action) {
+        case 'approve':
+            if (m.status !== 'placed')
+                refuse(`Order ${number(o)} is ${m.status}: only a placed order can be approved.`, orderCommands(o));
+            m.status = 'approved';
+            if (body?.capture === true && paymentStatus(o) === 'authorized')
+                capture();
+            break;
+        case 'capture':
+            if (m.status !== 'approved' || paymentStatus(o) !== 'authorized')
+                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an approved order with an authorized payment can be captured.`, orderCommands(o));
+            capture();
+            break;
+        case 'cancel':
+            if (m.status === 'cancelled')
+                refuse(`Order ${number(o)} is already cancelled.`, orderCommands(o));
+            if (['shipped', 'delivered'].includes(m.shipment.status))
+                refuse(`Order ${number(o)} has shipped: it cannot be cancelled.`, orderCommands(o));
+            if (!['authorized', 'free'].includes(paymentStatus(o)))
+                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: refund it to cancel it.`, orderCommands(o));
+            if (paymentStatus(o) === 'authorized')
+                m.transactions.push({ type: 'void', amount: total(o), succeeded: true, at });
+            m.status = 'cancelled';
+            m.shipment.status = 'cancelled';
+            break;
+        case 'refund': {
+            if (!['paid', 'partially_refunded'].includes(paymentStatus(o)))
+                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: only a captured payment can be refunded.`, orderCommands(o));
+            const refundable = sum(o, 'capture') - sum(o, 'refund');
+            let amount = refundable;
+            if (body?.amount !== undefined) {
+                if (typeof body.amount !== 'number' || !Number.isFinite(body.amount) || body.amount <= 0)
+                    throw new OrderError(422, 'invalid_argument', `amount ${body.amount} is not a positive number.`, 'Give --amount in major units, for example --amount 4.50, or leave it out to refund everything still refundable.');
+                amount = Math.round(body.amount * minorUnits(o.currency));
+                if (amount > refundable)
+                    throw new OrderError(422, 'refund_exceeds', `${money(amount, o.currency).display} is more than the ${money(refundable, o.currency).display} still refundable on order ${number(o)}.`, `Refund at most ${money(refundable, o.currency).major}, or leave --amount out to refund all of it.`);
+            }
+            m.transactions.push({ type: 'refund', amount, succeeded: true, at });
+            // As in Commerce Layer: refunding the last of the payment cancels the order.
+            if (sum(o, 'refund') >= sum(o, 'capture')) {
+                m.status = 'cancelled';
+                if (OPEN_SHIPMENTS.includes(m.shipment.status))
+                    m.shipment.status = 'cancelled';
+            }
+            break;
+        }
+        case 'archive':
+            m.archived_at ??= at;
+            break;
+        case 'unarchive':
+            m.archived_at = null;
+            break;
+        default:
+            throw new OrderError(404, 'not_found', `No order action ${action}.`, 'Use approve, capture, cancel, refund, archive or unarchive.');
+    }
+    return detail(o, r);
+}
+// ---------- shipments
+function shipmentRow(o) {
+    const s = merchant(o).shipment;
+    return {
+        id: s.id,
+        number: s.number,
+        status: s.status,
+        order: { id: o.id, number: number(o), status: merchant(o).status },
+        country: destination(o).address_country ?? null,
+        shipping_method: o.fulfillment?.expectations?.[0]?.description ?? null,
+        items: units(o),
+        tracking: s.tracking,
+        dates: { ...s.dates },
+    };
+}
+/** A shipment by id or number, or the one shipment of an order by its id or number. */
+function findShipment(r, wanted) {
+    const o = orders(r).find((x) => merchant(x).shipment.id === wanted || merchant(x).shipment.number === wanted) ?? orders(r).find((x) => x.id === wanted || x.label === wanted || x.label === `#${wanted}`);
+    if (!o)
+        throw new OrderError(404, 'not_found', `There is no shipment ${wanted}.`, 'Run `c11r fulfillment list` to see the shipments.');
+    return o;
+}
+function shipmentCommands(o) {
+    const s = merchant(o).shipment;
+    const approved = merchant(o).status === 'approved';
+    const n = s.number;
+    const out = [];
+    const can = (cmd, ok) => ok && out.push(`c11r fulfillment ${cmd} ${n}`);
+    can('hold', ['upcoming', 'picking', 'packing', 'ready_to_ship'].includes(s.status) && merchant(o).status !== 'cancelled');
+    can('pick', approved && ['upcoming', 'on_hold', 'packing', 'ready_to_ship'].includes(s.status));
+    can('pack', approved && ['on_hold', 'picking', 'ready_to_ship'].includes(s.status));
+    can('ready', approved && ['on_hold', 'picking', 'packing'].includes(s.status));
+    can('ship', approved && OPEN_SHIPMENTS.includes(s.status));
+    can('deliver', s.status === 'shipped');
+    if (!out.length && merchant(o).status === 'placed')
+        out.push(`c11r orders approve ${number(o)} [--capture]`);
+    return out;
+}
+export function listShipments(r, q) {
+    const raw = q.get('status');
+    let statuses = [...OPEN_SHIPMENTS];
+    if (raw) {
+        const vs = raw.split(',').map((v) => v.trim());
+        if (vs.includes('all'))
+            statuses = SHIPMENT_STATUSES;
+        else {
+            for (const v of vs)
+                if (!SHIPMENT_STATUSES.includes(v))
+                    throw new OrderError(422, 'invalid_argument', `status=${v} is not one of ${SHIPMENT_STATUSES.join(', ')}, all.`, `Use --status with one of ${SHIPMENT_STATUSES.join(', ')}, or all.`);
+            statuses = vs;
+        }
+    }
+    const limit = q.get('limit') === null ? 25 : Number(q.get('limit'));
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new OrderError(422, 'invalid_argument', `limit=${q.get('limit')} is not between 1 and 100.`, 'Use --limit with a number from 1 to 100.');
+    return { shipments: orders(r).filter((o) => statuses.includes(merchant(o).shipment.status)).map(shipmentRow).slice(0, limit) };
+}
+export function showShipment(r, id) {
+    const o = findShipment(r, id);
+    return { ...shipmentRow(o), line_items: o.line_items.map((l) => ({ sku: l.item?.id, name: l.item?.title, quantity: l.quantity?.total ?? l.quantity })), address: address(o), parcels: [] };
+}
+const URL_RE = /^https:\/\/\S+$/;
+export function shipmentAction(r, id, action, body) {
+    const o = findShipment(r, id);
+    const m = merchant(o);
+    const s = m.shipment;
+    const at = now();
+    const move = (to, from, needsApproved) => {
+        if (!from.includes(s.status) || (needsApproved && m.status !== 'approved') || m.status === 'cancelled') {
+            const why = needsApproved && m.status !== 'approved' ? `its order ${number(o)} is ${m.status}` : `it is ${s.status}`;
+            refuse(`Shipment ${s.number} cannot go ${to.replace(/_/g, ' ')}: ${why}.`, shipmentCommands(o));
+        }
+        s.status = to;
+        s.dates[`${to}_at`] = at;
+    };
+    switch (action) {
+        case 'hold':
+            return move('on_hold', ['upcoming', 'picking', 'packing', 'ready_to_ship'], false), showShipment(r, s.id);
+        case 'pick':
+            return move('picking', ['upcoming', 'on_hold', 'packing', 'ready_to_ship'], true), showShipment(r, s.id);
+        case 'pack':
+            return move('packing', ['on_hold', 'picking', 'ready_to_ship'], true), showShipment(r, s.id);
+        case 'ready':
+            return move('ready_to_ship', ['on_hold', 'picking', 'packing'], true), showShipment(r, s.id);
+        case 'ship': {
+            for (const k of ['carrier', 'tracking', 'tracking_url']) {
+                const v = body?.[k];
+                if (v !== undefined && (typeof v !== 'string' || !v.trim() || v.length > 255))
+                    throw new OrderError(422, 'invalid_argument', `${k} must be text of 1 to 255 characters.`, `Give --${k.replace('_', '-')} a value, or leave it out.`);
+            }
+            if (body?.tracking_url !== undefined && !URL_RE.test(body.tracking_url))
+                throw new OrderError(422, 'invalid_argument', `tracking_url ${body.tracking_url} is not an https URL.`, 'Give --tracking-url the carrier\'s tracking page, starting with https://.');
+            move('shipped', OPEN_SHIPMENTS, true);
+            if (body?.carrier || body?.tracking || body?.tracking_url)
+                s.tracking = { carrier: body.carrier, number: body.tracking, url: body.tracking_url };
+            return showShipment(r, s.id);
+        }
+        case 'deliver':
+            return move('delivered', ['shipped'], false), showShipment(r, s.id);
+        default:
+            throw new OrderError(404, 'not_found', `No shipment action ${action}.`, 'Use hold, pick, pack, ready, ship or deliver.');
+    }
+}

package/dist/api/stub/search.js

@@ -0,0 +1,78 @@
+// A copy of the store Worker's search (commercelayer-ai-store src/store/search.ts), so the
+// stub ranks as the store does. Keep it in step with the store's; only the import differs.
+//
+// Catalog search over what apply sent: words in any order, ranked. A query is folded
+// (case and accents aside), split into words, stripped of the stop words of the theme's
+// languages and of plurals; each product scores by where its words appear (title over
+// category over description, in its base text or any translation) and by how many of
+// the query's words it has. Products with every word come first, then those with some;
+// ties go by sku. No embeddings: what a word means is not known here, only that it is there.
+const WEIGHT = { sku: 8, title: 4, category: 2, description: 1 };
+/** Lower case, without accents: "Caffè" and "caffe" compare equal. */
+export const fold = (t) => t.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+// The theme's languages: en, it, fr, de, es. Words that say nothing about a product.
+const STOP = new Set(`a an and any are as at be best but by can do does for from get good have i in into is it its looking me my need of on or our please some something show that the their them these this those to want with without you your
+il lo la i gli le un uno una di da del della dei delle per con su e o che qualcosa cerco vorrei voglio mi un po
+le la les un une des de du d et ou pour avec sur dans au aux en quelque chose je veux cherche
+der die das ein eine einen einem und oder fur mit auf im in zu etwas ich suche mochte
+el la los las un una unos unas de del y o para con en algo busco quiero`.split(/\s+/));
+/** A word in one spelling: folded, and singular for the common plurals (beans, berries, boxes). */
+function stem(word) {
+    if (word.length > 4 && word.endsWith('ies'))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 4 && /(ches|shes|sses|xes)$/.test(word))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith('s') && !/(ss|us|is)$/.test(word))
+        return word.slice(0, -1);
+    return word;
+}
+const wordsIn = (text) => (text ? fold(text).split(/[^\p{L}\p{N}]+/u).filter(Boolean).map(stem) : []);
+/** The words a query searches for: no stop words, no repeats, in the order given. */
+export function queryWords(text) {
+    return [...new Set(wordsIn(text).filter((w) => !STOP.has(w)))];
+}
+/** A product's words by field, its base text and every translation together. */
+function fieldsOf(p) {
+    const texts = [p, ...Object.values(p.translations ?? {})];
+    return {
+        sku: new Set([fold(p.sku), ...wordsIn(p.sku)]),
+        title: new Set(texts.flatMap((t) => wordsIn(t.name))),
+        category: new Set(texts.flatMap((t) => wordsIn(t.category))),
+        description: new Set(texts.flatMap((t) => wordsIn(t.description))),
+    };
+}
+/** A word is in a field when the field has it, or (for words of four letters or more) a word that starts with it: "filt" finds "filter". */
+const has = (field, word) => field.has(word) || (word.length >= 4 && [...field].some((w) => w.startsWith(word)));
+/** How well a product matches the query's words, or null when none of them is in it. */
+export function scoreOf(p, words) {
+    if (!words.length)
+        return { score: 0, words: [], matched: [], all: true };
+    const fields = fieldsOf(p);
+    const found = [];
+    const matched = new Set();
+    let score = 0;
+    for (const w of words) {
+        const where = Object.keys(WEIGHT).filter((f) => has(fields[f], w));
+        if (!where.length)
+            continue;
+        found.push(w);
+        where.forEach((f) => matched.add(f));
+        score += WEIGHT[where[0]];
+    }
+    if (!found.length)
+        return null;
+    const all = found.length === words.length;
+    // Every word beats some words; more words beat better places.
+    score += found.length * 10 + (all ? 100 : 0);
+    return { score, words: found, matched: Object.keys(WEIGHT).filter((f) => matched.has(f)), all };
+}
+/** The products matching a query, best first; ties by sku. An empty query (or only stop words) matches everything, by sku. */
+export function rank(products, text) {
+    const words = queryWords(text);
+    return products
+        .flatMap((product) => {
+        const match = scoreOf(product, words);
+        return match ? [{ product, match }] : [];
+    })
+        .sort((a, b) => b.match.score - a.match.score || (a.product.sku < b.product.sku ? -1 : a.product.sku > b.product.sku ? 1 : 0));
+}

package/dist/api/stub/shopping.js

@@ -3,6 +3,9 @@
 // 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 = {
@@ -88,62 +91,123 @@ function returnPolicy(ctx) {
 // ---------- 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`, `${ctx.origin}/`).href;
-function variant(ctx, p, market) {
+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: p.name,
-        description: { plain: p.description ?? p.name },
+        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: ctx.record.storefront_mode === 'agent-only' ? undefined : `${ctx.origin}/products/${encodeURIComponent(p.sku)}`,
+        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);
-        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 }] }] };
+        // 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) {
-    const v = variant(ctx, p, market);
+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: p.name,
-        description: { plain: p.description ?? p.name },
+        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 ?? '').toLowerCase().trim();
+    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);
-    if (q)
-        all = all.filter((p) => `${p.name} ${p.description ?? ''} ${p.sku}`.toLowerCase().includes(q));
+    // 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 = all.slice(offset, offset + limit);
-    const hasNext = offset + limit < all.length;
+    const page = ranked.slice(offset, offset + limit);
+    const hasNext = offset + limit < ranked.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) } : {}) },
+        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;
@@ -202,7 +266,7 @@ function buildLines(ctx, market, requested, existing = []) {
         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 };
+        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 }] });
     });
@@ -570,6 +634,8 @@ function placeOrder(ctx, ck) {
         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)