@commercelayer/agent-cli 0.5.1 → 0.7.0

package/dist/api/stub/orders.js

@@ -4,11 +4,12 @@
 //
 // 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.
+// 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 = ['placed', 'approved', 'cancelled', 'editing'];
+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'];
@@ -18,11 +19,13 @@ export class OrderError extends Error {
     status;
     code;
     hint;
-    constructor(status, code, message, 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();
@@ -46,6 +49,9 @@ function merchant(o) {
 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)
@@ -70,6 +76,14 @@ 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 {
@@ -79,8 +93,14 @@ function row(o) {
         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,
@@ -89,20 +109,19 @@ function row(o) {
         archived: m.archived_at !== null,
     };
 }
-function address(o) {
-    const d = destination(o);
+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: 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: o._buyer?.phone_number ?? null,
+        phone: d.phone ?? o._buyer?.phone_number ?? null,
     };
 }
 function detail(o, r) {
@@ -122,13 +141,14 @@ function detail(o, r) {
         })),
         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),
+        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();
@@ -145,11 +165,13 @@ function orderCommands(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 === 'approved' && pay === 'authorized')
+    if (m.status !== 'cancelled' && pay === 'authorized')
         out.push(`c11r orders capture ${n}`);
-    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status) && ['authorized', 'free'].includes(pay))
+    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>]`);
@@ -159,35 +181,73 @@ function orderCommands(o) {
 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) => {
+    const list = (name, allowed, fallback, all = allowed) => {
         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))
+            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 vs;
+        return [...new Set(vs.flatMap((v) => (v === 'all' ? all : [v])))];
     };
-    const statuses = list('status', ORDER_STATUSES, ['placed', 'approved']);
+    // 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 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 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(x.status)))
-        .filter((x) => payments.includes(x.payment_status) && fulfillments.includes(x.fulfillment_status));
-    return { orders: rows.slice(0, limit) };
+        .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) {
@@ -198,28 +258,50 @@ export function orderAction(r, id, action, body) {
         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':
-            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));
+            // 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));
-            if (!['authorized', 'free'].includes(paymentStatus(o)))
-                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: refund it to cancel it.`, 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': {
@@ -238,6 +320,7 @@ export function orderAction(r, id, action, body) {
             // 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';
             }
@@ -250,11 +333,21 @@ export function orderAction(r, id, action, body) {
             m.archived_at = null;
             break;
         default:
-            throw new OrderError(404, 'not_found', `No order action ${action}.`, 'Use approve, capture, cancel, refund, archive or unarchive.');
+            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 {
@@ -266,6 +359,8 @@ function shipmentRow(o) {
         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 },
     };
 }
@@ -286,7 +381,7 @@ function shipmentCommands(o) {
     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('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]`);
@@ -306,10 +401,8 @@ export function listShipments(r, q) {
             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) };
+    // 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);
@@ -328,6 +421,7 @@ export function shipmentAction(r, id, action, body) {
         }
         s.status = to;
         s.dates[`${to}_at`] = at;
+        s.updated_at = at;
     };
     switch (action) {
         case 'hold':
@@ -346,7 +440,7 @@ export function shipmentAction(r, id, action, body) {
             }
             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);
+            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);
@@ -357,3 +451,175 @@ export function shipmentAction(r, id, action, body) {
             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,
+    };
+}

package/dist/api/stub/theme.js

@@ -155,8 +155,23 @@ function renderPage(r, path, search, locale) {
     return page(r, { lang: locale ? tag(locale) : 'en', title, head: locale ? alternates(localesOf(r), path) : '', header, body, description: tagline, home: `${prefix}/${keep}` });
 }
 const xml = (t) => String(t ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
-/** /tiles/<sku>.svg and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
+/** A 1×1 PNG: the stand-in for a generated PNG tile. */
+const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkqF9fDwAEAQG/jvkFNQAAAABJRU5ErkJggg==', 'base64');
+/** /tiles/<sku>.svg, /tiles/<sku>.png and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
 export function renderTile(r, path, search) {
+    const png = path.match(/^\/tiles\/([^/]+)\.png$/);
+    if (png) {
+        let sku;
+        try {
+            sku = decodeURIComponent(png[1]);
+        }
+        catch {
+            return null;
+        }
+        if (!r.applied?.products[sku])
+            return null;
+        return { status: 200, headers: { 'content-type': 'image/png', 'cache-control': 'public, max-age=300', 'x-content-type-options': 'nosniff' }, body: PNG };
+    }
     const m = path.match(/^\/tiles\/([^/]+)\.svg$/);
     if (!m)
         return null;

package/dist/api/stub/ucp.js

@@ -68,7 +68,7 @@ function negotiate(platformUrl) {
 // ---------- the REST service
 const protocolError = (status, code, content, headers = {}) => json(status, { code, content }, headers);
 function withUcpHeaders(r, res) {
-    const digest = contentDigest(res.body);
+    const digest = contentDigest(res.body.toString());
     const values = { '@status': String(res.status), 'content-digest': digest, 'content-type': res.headers['content-type'] ?? 'application/json' };
     const sig = signHeaders('sig1', values, { components: ['@status', 'content-digest', 'content-type'], keyid: r.ucp.kid, created: Math.floor(Date.now() / 1000) }, r.ucp.private_jwk);
     return { ...res, headers: { ...res.headers, 'content-digest': digest, ...sig } };
@@ -114,7 +114,7 @@ function handleService(req, r, origin, path) {
     const res = dispatch(ctx, req.method, path, parsed);
     res.headers['content-language'] = ctx.language;
     if (mutating && key)
-        r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body };
+        r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body.toString() };
     return res;
 }
 function dispatch(ctx, method, path, body) {

package/dist/api/transport.js

@@ -8,6 +8,16 @@ import { handle } from './stub/index.js';
 import { USER_AGENT } from '../version.js';
 export const DEFAULT_API_URL = 'https://api.commercelayer.ai';
 export const apiUrl = () => process.env.C11R_API_URL ?? DEFAULT_API_URL;
+/** Where a request goes: to a local API, other hosts through its /-/<host>/ prefix. */
+function targetOf(url) {
+    const base = apiUrl();
+    const baseUrl = new URL(base);
+    const targetUrl = new URL(url);
+    if (base !== DEFAULT_API_URL && targetUrl.host !== baseUrl.host && !url.startsWith(base)) {
+        return `${base.replace(/\/$/, '')}/-/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}`;
+    }
+    return url;
+}
 export async function send(method, url, headers = {}, body) {
     const base = apiUrl();
     const lower = {};
@@ -17,14 +27,11 @@ export async function send(method, url, headers = {}, body) {
     lower['user-agent'] ??= USER_AGENT;
     if (body !== undefined && !lower['content-type'])
         lower['content-type'] = 'application/json';
-    if (base === 'stub')
-        return handle({ method, url: new URL(url), headers: lower, body });
-    let target = url;
-    const baseUrl = new URL(base);
-    const targetUrl = new URL(url);
-    if (base !== DEFAULT_API_URL && targetUrl.host !== baseUrl.host && !url.startsWith(base)) {
-        target = `${base.replace(/\/$/, '')}/-/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}`;
+    if (base === 'stub') {
+        const r = handle({ method, url: new URL(url), headers: lower, body });
+        return { ...r, body: r.body.toString() };
     }
+    const target = targetOf(url);
     let res;
     try {
         // Never follow redirects: UCP forbids it for profiles, and the 302/303 of
@@ -38,3 +45,13 @@ export async function send(method, url, headers = {}, body) {
     res.headers.forEach((v, k) => (resHeaders[k] = v));
     return { status: res.status, headers: resHeaders, body: await res.text() };
 }
+/** A file over GET, as bytes, within timeoutMs; redirects are followed (images sit behind CDNs). Throws on failure. */
+export async function download(url, timeoutMs) {
+    const headers = { 'user-agent': USER_AGENT, accept: 'image/*' };
+    if (apiUrl() === 'stub') {
+        const r = handle({ method: 'GET', url: new URL(url), headers });
+        return { status: r.status, type: r.headers['content-type'] ?? '', bytes: Buffer.from(r.body) };
+    }
+    const res = await fetch(targetOf(url), { headers, signal: AbortSignal.timeout(timeoutMs) });
+    return { status: res.status, type: res.headers.get('content-type') ?? '', bytes: Buffer.from(await res.arrayBuffer()) };
+}