@commercelayer/agent-cli 0.8.0 → 1.0.0-dev.0

package/dist/api/stub/orders.js

@@ -1,625 +0,0 @@
-// 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; as in
-// Commerce Layer, an upcoming shipment ships only once it is picking (or past it).
-import { money } from '../../ucp/shop.js';
-import { minorUnits } from '../../ucp/platform.js';
-import { baseLanguage } from './locale.js';
-export const ORDER_STATUSES = ['pending', '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;
-    path;
-    constructor(status, code, message, hint, path) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.hint = hint;
-        this.path = path;
-    }
-}
-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';
-    // A pending order has no payment yet: placing it authorizes one.
-    if (!merchant(o).transactions.some((t) => t.type === 'authorization'))
-        return 'unpaid';
-    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 };
-}
-/** Who placed it: a shopping agent over UCP, a person through a checkout link, the store's own checkout, or orders create from an email or a message. */
-const channel = (o) => (o._platform === 'message' ? 'message' : !o._platform ? 'web' : /permalink|\/buy\b/.test(o._platform) ? 'link' : 'agent');
-/** The latest change to the order, its payment or its shipment. */
-function updatedAt(o) {
-    const m = merchant(o);
-    const all = [m.created_at, m.placed_at, m.updated_at, m.shipment.updated_at, ...m.transactions.map((t) => t.at), ...Object.values(m.shipment.dates)].filter((x) => !!x);
-    return all.reduce((a, b) => (Date.parse(b) > Date.parse(a) ? b : a));
-}
-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,
-        created_at: m.created_at ?? m.placed_at,
-        approved_at: m.approved_at ?? null,
-        cancelled_at: m.cancelled_at ?? null,
-        updated_at: updatedAt(o),
-        market: o._market ?? null,
-        // The shipping country, as Commerce Layer's country_code follows the shipping address.
-        country: destination(o).address_country ?? null,
-        channel: channel(o),
-        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, d = destination(o)) {
-    if (!Object.keys(d).length)
-        return null;
-    return {
-        name: [d.first_name, d.last_name].filter(Boolean).join(' ') || null,
-        company: d.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: d.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: o._bill_to ? address(o, o._bill_to) : 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 },
-        ...(o._platform === 'message' ? { source: o._source ?? null, notes: o._notes ?? null, customer_reference: o._reference ?? null } : {}),
-    };
-}
-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 === 'pending')
-        return [`c11r orders place ${n}`, `c11r orders cancel ${n}`];
-    if (m.status === 'placed')
-        out.push(`c11r orders approve ${n} [--capture]`);
-    if (m.status !== 'cancelled' && pay === 'authorized')
-        out.push(`c11r orders capture ${n}`);
-    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status))
-        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('; ')}.`);
-};
-/** since / updated_since, sort, direction, limit and page, as the API reads them: { page, limit, total, has_more }. */
-function paged(q, rows, sorts, defaultSort, kind) {
-    const time = (name) => {
-        const raw = q.get(name);
-        if (raw === null)
-            return undefined;
-        const t = Date.parse(raw);
-        if (!/^\d{4}-\d{2}-\d{2}/.test(raw) || Number.isNaN(t))
-            throw new OrderError(422, 'invalid_argument', `${name}=${raw} is not an ISO 8601 date.`, `Give ${name} as an ISO 8601 date or time.`);
-        return t;
-    };
-    // Shipments take updated_since only.
-    const since = kind === 'orders' ? time('since') : undefined;
-    const updated = time('updated_since');
-    const sort = q.get('sort') ?? defaultSort;
-    if (!sorts.includes(sort))
-        throw new OrderError(422, 'invalid_argument', `sort=${sort} is not one of ${sorts.join(', ')}.`, `Use sort with one of ${sorts.join(', ')}.`);
-    const direction = q.get('direction') ?? 'desc';
-    if (!['asc', 'desc'].includes(direction))
-        throw new OrderError(422, 'invalid_argument', `direction=${direction} is not asc or desc.`, 'Use direction=asc or desc.');
-    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 page = q.get('page') === null ? 1 : Number(q.get('page'));
-    if (!Number.isInteger(page) || page < 1)
-        throw new OrderError(422, 'invalid_argument', `page=${q.get('page')} is not a page number from 1.`, 'Use page=1, 2, …');
-    const at = (x) => Date.parse(sort === 'updated_at' ? x.updated_at : sort === 'placed_at' ? (x.placed_at ?? x.created_at) : x.dates.created_at);
-    const kept = rows
-        // A pending order has no placed_at: since is its created_at.
-        .filter((x) => since === undefined || Date.parse(x.placed_at ?? x.created_at) >= since)
-        .filter((x) => updated === undefined || Date.parse(x.updated_at) >= updated)
-        .sort((a, b) => (direction === 'asc' ? at(a) - at(b) : at(b) - at(a)) || (direction === 'asc' ? a.number.localeCompare(b.number) : b.number.localeCompare(a.number)));
-    return { [kind]: kept.slice((page - 1) * limit, page * limit), page, limit, total: kept.length, has_more: page * limit < kept.length };
-}
-export function listOrders(r, q) {
-    const list = (name, allowed, fallback, all = allowed) => {
-        const raw = q.get(name);
-        if (!raw)
-            return fallback;
-        const vs = raw.split(',').map((v) => v.trim());
-        for (const v of vs)
-            if (v !== 'all' && !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 [...new Set(vs.flatMap((v) => (v === 'all' ? all : [v])))];
-    };
-    // all is every status but pending: pending orders are listed only when asked for by name.
-    const statuses = list('status', ORDER_STATUSES, ['placed', 'approved'], ORDER_STATUSES.filter((x) => x !== 'pending'));
-    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 ch = q.get('channel');
-    if (ch)
-        for (const v of ch.split(','))
-            if (!['message', 'link'].includes(v))
-                throw new OrderError(422, 'invalid_argument', `channel=${v} is not message or link.`, 'Use --channel message or link (the markers Commerce Layer can match); for agent and web, see c11r insights --by channel.');
-    // A cancelled pending order lists with the pending ones (archived), as the API does.
-    const listed = new Map(orders(r).map((o) => [o.id, merchant(o).cancelled_pending ? 'pending' : merchant(o).status]));
-    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(listed.get(x.id))))
-        .filter((x) => payments.includes(x.payment_status) && fulfillments.includes(x.fulfillment_status))
-        .filter((x) => !ch || ch.split(',').includes(x.channel));
-    return paged(q, rows, ['placed_at', 'updated_at'], 'placed_at', 'orders');
-}
-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 'place':
-            if (m.status !== 'pending' || channel(o) !== 'message')
-                refuse(`Order ${number(o)} is ${m.status}: only a pending order can be placed.`, orderCommands(o));
-            // As the API does: a wire transfer, then _place; Commerce Layer authorizes it.
-            m.status = 'placed';
-            m.placed_at = at;
-            m.transactions.push({ type: 'authorization', amount: total(o), succeeded: true, at });
-            break;
-        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';
-            m.approved_at = at;
-            if (body?.capture === true && paymentStatus(o) === 'authorized')
-                capture();
-            break;
-        case 'capture':
-            // As in Commerce Layer: a placed order can be captured before it is approved.
-            if (m.status === 'cancelled' || paymentStatus(o) !== 'authorized')
-                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only 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 (m.status === 'pending') {
-                // Commerce Layer refuses _cancel and DELETE on a pending order: the API archives it and marks it cancelled.
-                m.status = 'cancelled';
-                m.cancelled_pending = true;
-                m.cancelled_at = at;
-                m.archived_at = at;
-                m.shipment.status = 'cancelled';
-                break;
-            }
-            if (['shipped', 'delivered'].includes(m.shipment.status))
-                refuse(`Order ${number(o)} has shipped: it cannot be cancelled.`, orderCommands(o));
-            // Commerce Layer voids an authorized payment and refunds a captured one.
-            if (paymentStatus(o) === 'authorized')
-                m.transactions.push({ type: 'void', amount: total(o), succeeded: true, at });
-            const left = sum(o, 'capture') - sum(o, 'refund');
-            if (left > 0)
-                m.transactions.push({ type: 'refund', amount: left, succeeded: true, at });
-            m.status = 'cancelled';
-            m.cancelled_at = at;
-            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';
-                m.cancelled_at = at;
-                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 place, approve, capture, cancel, refund, archive or unarchive.');
-    }
-    m.updated_at = at;
-    return detail(o, r);
-}
-// ---------- shipments
-/** When the shipment entered its status: that status's own date, created_at while upcoming, updated_at once cancelled. */
-function statusChangedAt(o) {
-    const s = merchant(o).shipment;
-    if (s.status === 'upcoming')
-        return s.dates.created_at;
-    if (s.status === 'cancelled')
-        return s.updated_at ?? s.dates.created_at;
-    return s.dates[`${s.status}_at`] ?? s.dates.created_at;
-}
-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,
-        status_changed_at: statusChangedAt(o),
-        updated_at: s.updated_at ?? s.dates.created_at,
-        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 && WORKING.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;
-        }
-    }
-    // A pending order's shipment is a draft: not something to fulfil yet.
-    return paged(q, orders(r).filter((o) => merchant(o).status !== 'pending' && statuses.includes(merchant(o).shipment.status)).map(shipmentRow), ['created_at', 'updated_at'], 'created_at', 'shipments');
-}
-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;
-        s.updated_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', WORKING, 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.');
-    }
-}
-// ---------- the ops snapshot and insights (README "Operations and insights" of the API)
-const DAY_MS = 86_400_000;
-const SNAPSHOT_CAP = 50;
-/** GET /stores/:org/ops: what the merchant agent's loop polls, oldest first, 50 a list. */
-export function opsSnapshot(r, q) {
-    const days = (name, fallback) => {
-        const raw = q.get(name);
-        if (raw === null)
-            return fallback;
-        const n = Number(raw);
-        if (!Number.isFinite(n) || n <= 0 || n > 365)
-            throw new OrderError(422, 'invalid_argument', `${name}=${raw} is not a number of days above 0 and up to 365.`, `Give ${name} in days, for example ${fallback}.`);
-        return n;
-    };
-    const thresholds = { stuck_days: days('stuck_days', 2), transit_days: days('transit_days', 7) };
-    const asOf = Date.now();
-    const rows = orders(r)
-        .filter((o) => merchant(o).archived_at === null)
-        .map(row)
-        .sort((a, b) => Date.parse(a.placed_at ?? a.created_at) - Date.parse(b.placed_at ?? b.created_at) || a.number.localeCompare(b.number));
-    const lists = {
-        placed_unapproved: rows.filter((x) => x.status === 'placed'),
-        approved_uncaptured: rows.filter((x) => x.status === 'approved' && ['authorized', 'partially_authorized'].includes(x.payment_status)),
-        awaiting_payment: rows.filter((x) => ['placed', 'approved'].includes(x.status) && x.payment_status === 'unpaid'),
-    };
-    const stuck = orders(r)
-        .map(shipmentRow)
-        .map((x) => ({ ...x, since_days: Math.round(((asOf - Date.parse(x.status_changed_at)) / DAY_MS) * 10) / 10 }))
-        .filter((x) => (['picking', 'packing', 'ready_to_ship'].includes(x.status) && x.since_days > thresholds.stuck_days) || (x.status === 'shipped' && x.since_days > thresholds.transit_days))
-        .sort((a, b) => b.since_days - a.since_days);
-    const cap = (l) => l.slice(0, SNAPSHOT_CAP);
-    return {
-        as_of: new Date(asOf).toISOString(),
-        thresholds,
-        orders: { placed_unapproved: cap(lists.placed_unapproved), approved_uncaptured: cap(lists.approved_uncaptured), awaiting_payment: cap(lists.awaiting_payment) },
-        shipments: { stuck: cap(stuck), returns: null },
-        counts: { placed_unapproved: lists.placed_unapproved.length, approved_uncaptured: lists.approved_uncaptured.length, awaiting_payment: lists.awaiting_payment.length, stuck: stuck.length },
-        has_more: { placed_unapproved: lists.placed_unapproved.length > SNAPSHOT_CAP, approved_uncaptured: lists.approved_uncaptured.length > SNAPSHOT_CAP, awaiting_payment: lists.awaiting_payment.length > SNAPSHOT_CAP, stuck: stuck.length > SNAPSHOT_CAP },
-    };
-}
-const INSIGHTS_BY = ['product', 'day', 'market', 'country', 'channel', 'promotion'];
-const CHANNEL_LABELS = { agent: 'Shopping agents (UCP)', link: 'Checkout links', web: 'Store checkout', message: 'Email and messages' };
-/** Money per currency, sorted by currency, never summed across currencies. */
-const perCurrency = (list) => {
-    const by = new Map();
-    for (const [amount, cur] of list)
-        by.set(cur, (by.get(cur) ?? 0) + amount);
-    return [...by].sort(([a], [b]) => a.localeCompare(b)).map(([cur, amount]) => money(amount, cur));
-};
-/** "24h", "7d" (any <n>h or <n>d) or an ISO date: the instant, as the API reads since. */
-function spanOrTime(raw, name, now) {
-    const rel = raw.match(/^(\d+)([hd])$/);
-    if (rel)
-        return now - Number(rel[1]) * (rel[2] === 'h' ? 3_600_000 : DAY_MS);
-    const t = Date.parse(raw);
-    if (!/^\d{4}-\d{2}-\d{2}/.test(raw) || Number.isNaN(t))
-        throw new OrderError(422, 'invalid_argument', `${name}=${raw} is not a span (24h, 7d) or an ISO 8601 date.`, `Give ${name} as 24h, 7d, 30d or an ISO date.`);
-    return t;
-}
-const regionName = (code) => {
-    try {
-        return new Intl.DisplayNames(['en'], { type: 'region' }).of(code) ?? code;
-    }
-    catch {
-        return code;
-    }
-};
-/**
- * GET /stores/:org/insights: the orders placed in the period that are placed or approved now.
- * Revenue is their totals; refunds and cancellations are reported apart.
- */
-export function insights(r, q) {
-    const now = Date.now();
-    const until = q.get('until') === null ? now : spanOrTime(q.get('until'), 'until', now);
-    const since = spanOrTime(q.get('since') ?? '30d', 'since', now);
-    if (until <= since)
-        throw new OrderError(422, 'invalid_argument', 'until is not after since.', 'Give an until later than since.');
-    if (until - since > 366 * DAY_MS)
-        throw new OrderError(422, 'invalid_argument', 'The period is longer than 366 days.', 'Ask for at most 366 days.');
-    const by = q.get('by');
-    if (by !== null && !INSIGHTS_BY.includes(by))
-        throw new OrderError(422, 'invalid_argument', `by=${by} is not one of ${INSIGHTS_BY.join(', ')}.`, `Use --by with one of ${INSIGHTS_BY.join(', ')}.`);
-    const period = orders(r).filter((o) => {
-        const t = Date.parse(merchant(o).placed_at ?? '');
-        return t >= since && t < until;
-    });
-    const counted = period.filter((o) => ['placed', 'approved'].includes(merchant(o).status));
-    const lineTotal = (l) => l.totals?.find((t) => t.type === 'total')?.amount ?? 0;
-    const rows = new Map();
-    const add = (key, label, o, u, amount) => {
-        const x = rows.get(key) ?? { key, label, orders: new Set(), units: 0, revenue: [] };
-        x.orders.add(o.id);
-        x.units += u;
-        x.revenue.push([amount, o.currency]);
-        rows.set(key, x);
-        return x;
-    };
-    const products = new Map();
-    for (const o of counted) {
-        for (const l of o.line_items) {
-            const sku = l.item?.id;
-            const x = products.get(sku) ?? { key: sku, label: l.item?.title, orders: new Set(), units: 0, revenue: [] };
-            x.orders.add(o.id);
-            x.units += l.quantity?.total ?? l.quantity ?? 0;
-            x.revenue.push([lineTotal(l), o.currency]);
-            products.set(sku, x);
-        }
-        const m = merchant(o);
-        if (by === 'day')
-            add(m.placed_at.slice(0, 10), m.placed_at.slice(0, 10), o, units(o), total(o));
-        else if (by === 'market')
-            add(o._market ?? 'none', (o._market ? r.applied?.markets?.[o._market]?.name : undefined) ?? o._market ?? 'none', o, units(o), total(o));
-        else if (by === 'country') {
-            const cc = destination(o).address_country ?? 'none';
-            add(cc, cc === 'none' ? 'none' : regionName(cc), o, units(o), total(o));
-        }
-        else if (by === 'channel')
-            add(channel(o), CHANNEL_LABELS[channel(o)], o, units(o), total(o));
-        else if (by === 'promotion') {
-            const discount = o.totals.filter((t) => t.type === 'discount').reduce((sum_, t) => sum_ + t.amount, 0);
-            for (const code of o._codes?.length ? o._codes : []) {
-                const x = add(code, code, o, units(o), total(o));
-                (x.discount ??= []).push([-Math.abs(discount), o.currency]);
-            }
-        }
-    }
-    if (by === 'product')
-        for (const [k, v] of products)
-            rows.set(k, v);
-    // Every channel, empty ones included, as the API answers.
-    if (by === 'channel')
-        for (const [key, label] of Object.entries(CHANNEL_LABELS))
-            if (!rows.has(key))
-                rows.set(key, { key, label, orders: new Set(), units: 0, revenue: [] });
-    if (by === 'day') {
-        // Every day of the period, empty ones included.
-        for (let d = Date.parse(new Date(since).toISOString().slice(0, 10)); d < until; d += DAY_MS) {
-            const key = new Date(d).toISOString().slice(0, 10);
-            if (!rows.has(key))
-                rows.set(key, { key, label: key, orders: new Set(), units: 0, revenue: [] });
-        }
-    }
-    const view = (x) => ({ key: x.key, label: x.label, orders: x.orders.size, units: x.units, revenue: perCurrency(x.revenue), ...(x.discount ? { discount: perCurrency(x.discount) } : {}) });
-    const out = [...rows.values()].map(view);
-    out.sort(by === 'day' ? (a, b) => a.key.localeCompare(b.key) : (a, b) => b.units - a.units || a.key.localeCompare(b.key));
-    const revenue = perCurrency(counted.map((o) => [total(o), o.currency]));
-    const count = new Map();
-    for (const o of counted)
-        count.set(o.currency, (count.get(o.currency) ?? 0) + 1);
-    const channels = { agent: 0, link: 0, web: 0, message: 0, partial: false };
-    for (const o of counted)
-        channels[channel(o)]++;
-    return {
-        since: new Date(since).toISOString(),
-        until: new Date(until).toISOString(),
-        by,
-        as_of: new Date(now).toISOString(),
-        source: 'stub',
-        totals: {
-            orders: counted.length,
-            units: counted.reduce((n, o) => n + units(o), 0),
-            revenue,
-            average_order: revenue.map((t) => money(Math.round(t.amount / (count.get(t.currency) || 1)), t.currency)),
-            refunds: perCurrency(period.filter((o) => sum(o, 'refund')).map((o) => [sum(o, 'refund'), o.currency])),
-            cancellations: period.filter((o) => merchant(o).status === 'cancelled').length,
-        },
-        rows: by ? out : [],
-        top_products: [...products.values()].sort((a, b) => b.units - a.units || a.key.localeCompare(b.key)).slice(0, 5).map((x) => ({ sku: x.key, name: x.label, orders: x.orders.size, units: x.units, revenue: perCurrency(x.revenue) })),
-        channel: channels,
-        partial: false,
-    };
-}