@commercelayer/agent-cli 0.5.2 → 0.8.0

package/dist/api/stub/orders.js

@@ -9,7 +9,7 @@
 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'];
@@ -19,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();
@@ -47,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)
@@ -71,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 {
@@ -80,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,
@@ -90,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) {
@@ -123,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();
@@ -146,6 +165,8 @@ 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 !== 'cancelled' && pay === 'authorized')
@@ -160,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) {
@@ -199,10 +258,19 @@ 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;
@@ -215,6 +283,15 @@ export function orderAction(r, id, action, body) {
         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.
@@ -224,6 +301,7 @@ export function orderAction(r, id, action, body) {
             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': {
@@ -242,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';
             }
@@ -254,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 {
@@ -270,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 },
     };
 }
@@ -310,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);
@@ -332,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':
@@ -361,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/bin.js

@@ -5,7 +5,7 @@
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
 import { LATEST_HINT, NPX } from './version.js';
-const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url']);
+const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url', '--since', '--until', '--by', '--company', '--line-2', '--query', '--reference', '--notes', '--language', '--source', '--channel', '--label', '--unlabel', '--move', '--currency']);
 const argv = process.argv.slice(2);
 const flags = new Set();
 const values = {};
@@ -54,7 +54,7 @@ async function run() {
             return cmd.claim();
         case 'catalog':
             if (sub === 'pull')
-                return cmd.catalogPull();
+                return cmd.catalogPull(values);
             throw new CliError('unknown_command', `There is no command "catalog ${sub ?? ''}".`, 'Use `c11r catalog pull`.');
         case 'storefront':
             if (sub === 'init')
@@ -63,7 +63,9 @@ async function run() {
                 return cmd.storefrontPublish();
             if (sub === 'check')
                 return cmd.storefrontCheckCmd();
-            throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init`, `storefront publish` or `storefront check`.');
+            if (sub === 'inspect')
+                return cmd.storefrontInspect(args[2]);
+            throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init`, `storefront publish`, `storefront check` or `storefront inspect <url>`.');
         case 'promotions':
             if (sub === 'list')
                 return cmd.promotionsList();
@@ -93,13 +95,15 @@ async function run() {
         case 'orders':
             if (sub === 'test')
                 return cmd.ordersTest(flags, values);
+            if (sub === 'create')
+                return cmd.ordersCreate(values, lists, flags);
             if (sub === 'list')
                 return cmd.ordersList(values, flags);
             if (sub === 'show')
                 return cmd.ordersShow(args[2]);
-            if (sub === 'approve' || sub === 'capture' || sub === 'cancel' || sub === 'refund' || sub === 'archive' || sub === 'unarchive')
+            if (sub === 'place' || sub === 'approve' || sub === 'capture' || sub === 'cancel' || sub === 'refund' || sub === 'archive' || sub === 'unarchive')
                 return cmd.ordersAct(sub, args[2], values, flags);
-            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders list`, `show <number>`, `approve <number> [--capture]`, `capture`, `cancel`, `refund <number> [--amount <n>]`, `archive`, `unarchive`, or `orders test`.');
+            throw new CliError('unknown_command', `There is no command "orders ${sub ?? ''}".`, 'Use `c11r orders list`, `show <number>`, `create`, `place <number>`, `approve <number> [--capture]`, `capture`, `cancel`, `refund <number> [--amount <n>]`, `archive`, `unarchive`, or `orders test`.');
         case 'fulfillment':
             if (sub === 'list')
                 return cmd.fulfillmentList(values);
@@ -108,6 +112,26 @@ async function run() {
             if (sub === 'hold' || sub === 'pick' || sub === 'pack' || sub === 'ready' || sub === 'ship' || sub === 'deliver')
                 return cmd.fulfillmentAct(sub, args[2], values);
             throw new CliError('unknown_command', `There is no command "fulfillment ${sub ?? ''}".`, 'Use `c11r fulfillment list`, `show <shipment>`, `hold`, `pick`, `pack`, `ready`, `ship <shipment> [--carrier --tracking --tracking-url]` or `deliver`.');
+        case 'ops':
+            if (sub === 'check')
+                return cmd.opsCheck(values);
+            if (sub === 'run')
+                return cmd.opsRun(flags);
+            if (sub === 'digest')
+                return cmd.opsDigest(values);
+            throw new CliError('unknown_command', `There is no command "ops ${sub ?? ''}".`, 'Use `c11r ops check`, `ops run [--dry-run]` or `ops digest [--since 24h]`.');
+        case 'insights':
+            return cmd.insights(values);
+        case 'inbox':
+            if (sub === 'check')
+                return cmd.inboxCheck();
+            if (sub === 'list')
+                return cmd.inboxList(values, flags);
+            if (sub === 'pull')
+                return cmd.inboxPull(args[2], values, flags);
+            if (sub === 'tag')
+                return cmd.inboxTag(args[2], lists, values, flags);
+            throw new CliError('unknown_command', `There is no command "inbox ${sub ?? ''}".`, sub === 'reply' ? 'The CLI does not send email: replies stay with the human or their mail app.' : 'Use `c11r inbox check`, `list [--unseen] [--since 24h] [--limit 20]`, `pull <id> | --unseen` or `tag <id> --label <name> | --unlabel <name> | --move <folder> | --seen`.');
         case 'ucp':
             if (sub === 'profile')
                 return cmd.ucpProfile(flags);
@@ -148,7 +172,7 @@ run()
 })
     .catch((e) => {
     if (e instanceof CliError) {
-        print({ error: { code: e.code, message: e.message, hint: e.hint } });
+        print({ error: { code: e.code, message: e.message, hint: e.hint, ...(e.path ? { path: e.path } : {}) } });
     }
     else {
         const message = e instanceof Error ? e.message : String(e);