@commercelayer/agent-cli 0.5.2 → 0.7.0

package/dist/commands.js

@@ -9,6 +9,11 @@ import { diff, hashStore, languageWarnings, loadStore, storefrontMode, storefron
 import { storefrontFiles } from './storefront.js';
 import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
+import * as ops from './ops.js';
+import { checkOrderRequest, lineFlag, sourceFlag } from './orderRequest.js';
+import { readInboxCursor, seenKey, writeInboxCursor } from './inbox/cursor.js';
+import { openMailbox } from './inbox/mailbox.js';
+import { parseMessage, writeMessage } from './inbox/message.js';
 import { checkLink } from './links.js';
 import { ACTIVE_LIMIT, activeWithoutCoupon, checkPromotion } from './promotions.js';
 import YAML from 'yaml';
@@ -43,11 +48,13 @@ export const HELP = {
     'links disable': 'Turn a link off without deleting it: its url stops opening. c11r links disable <id>.',
     'links delete': 'Delete a link from Commerce Layer: c11r links delete <id>. Ask the human first; to pause one, disable it.',
     'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline. The order is placed, payment authorized; approve and capture it with `c11r orders approve <id> --capture`. discounts lists what promotions and codes took off; a code that applied nothing is a discount_code_invalid warning in messages.',
-    'orders list': "The store's orders, live in Commerce Layer, newest first: by default the placed and approved ones, not archived, 25 at most. c11r orders list [--status placed|approved|cancelled|editing|all] [--payment authorized|paid|refunded|partially_refunded|voided|...] [--fulfillment unfulfilled|in_progress|fulfilled|not_required] [--archived [all]] [--limit 1-100]; a comma list takes several (--status placed,cancelled). Returns { count, orders: [{ id, number, status, payment_status, fulfillment_status, placed_at, market, country, currency, total: { amount, currency, major, display }, email, items, shipments: [{ id, number, status, tracking }], archived }], next }. Orders arrive placed with the payment authorized, not taken: they wait for the human to accept them.",
+    'orders list': "The store's orders, live in Commerce Layer, newest first: by default the placed and approved ones, not archived, 25 at most. c11r orders list [--status pending|placed|approved|cancelled|editing|all] [--channel message|link] [--payment authorized|paid|refunded|partially_refunded|voided|...] [--fulfillment unfulfilled|in_progress|fulfilled|not_required] [--archived [all]] [--limit 1-100]; a comma list takes several (--status placed,cancelled). Returns { count, orders: [{ id, number, status, payment_status, fulfillment_status, placed_at, market, country, currency, total: { amount, currency, major, display }, email, items, shipments: [{ id, number, status, tracking }], archived }], next }. Orders arrive placed with the payment authorized, not taken: they wait for the human to accept them. pending orders were made from emails or messages (orders create) and are not placed yet: placed_at is null, created_at says when; --status pending lists them (all is every status but pending: --status all,pending for both), --channel message every order from a message, --channel link those from checkout links (agent and web: insights --by channel). A pending order cancelled stays archived with them: --status pending --archived.",
     'orders show': 'One order as the merchant sees it: c11r orders show <number, #number or id>. Returns { order: { ...as in orders list, line_items: [{ sku, name, quantity, unit_price, total }], totals: { subtotal, discount, shipping, taxes, total, codes }, shipping_address, billing_address, shipping_method, payment: { method, source, status, captured, refundable }, transactions: [{ type, amount, succeeded, at }], language, archived_at, ucp: { id, permalink_url } }, next }. next says what the order is waiting for.',
+    'orders create': "Make an order from an email or a message the human received (an order by email, a chat, a PDF purchase order the agent read): c11r orders create -f <file> (or the request on stdin) --source email:<Message-ID> [--place | --hold] [--force], or with flags: --email --first-name --last-name [--company] --phone --item <sku>:<qty> (repeat it) --query \"<words>:<qty>\" (repeat it) --street [--line-2] --city --postal-code [--region] --country [--reference <PO number>] [--notes <text>] [--language <ll>] --source <kind>:<id>. source is required: email:<Message-ID> for an email, message:<id> for anything else (a chat or form message id); it keeps a message from making two orders. The request: { source: { kind: email|message, id, from, subject, received_at }, customer: { email, first_name, last_name, company, phone }, ship_to: { line_1, line_2, city, postal_code, region, country, phone }, bill_to, items: [{ sku, quantity } | { query, quantity }], notes, reference, language }. Everything comes from the message or the human, never invented: a missing phone, postal code or country is invalid_argument with path naming it (ask the human). quantity is 1 to 10,000; two lines of the same sku become one. Prices are always the catalog's: never put the email's prices in; tell the human when they differ. A query line is resolved by the store's search; a line it cannot match surely leaves status needs_review with nothing created (exit 0): resolution lists each line { requested, sku, name, confidence, candidates: [{ sku, name, price }], status: matched|ambiguous|not_found|unavailable }; ask the human which product, then run it again with --item <sku>:<qty>, or with --force to leave those lines out (line_dropped in warnings). The order is created pending (not placed) for the human's yes, then c11r orders place <number>; mail_orders: { auto_place: true } in .commercelayer/ops.yml (or --place) places it at once, --hold keeps it pending whatever the policy says. The same --source again returns the order it made (duplicate_source in warnings), never a second one. Other errors: country_not_served (with the countries the store ships to), too_many_items (25 lines at most), store_unavailable (the store's search failed: nothing created, try again). Warnings: duplicate_source, line_dropped, no_shipping_method. Returns { status: pending|placed|needs_review, order, resolution, warnings, next }.",
+    'orders place': "Place a pending order made by orders create (channel message), once the human said yes to its lines and total: c11r orders place <number>. A shopper's own checkout in progress is theirs to finish: invalid_transition. It is paid by wire transfer: placed with the payment authorized, then approved and captured like any other order. Returns { status, order, next }.",
     'orders approve': "Accept a placed order, only once the human said to: c11r orders approve <number> [--capture]. With --capture the authorized payment is taken too; without, take it later with orders capture. Returns { status, order, next } with the order after it. An order that cannot be approved answers invalid_transition: its hint lists what it allows now.",
     'orders capture': 'Take the authorized payment of an order, once the human said to: c11r orders capture <number>. Usually after approving it (or at once with orders approve --capture); a placed order can be captured too. Returns { status, order, next }; invalid_transition when nothing authorized is left to capture.',
-    'orders cancel': "Cancel an order the human does not want, before it ships: c11r orders cancel <number>. An authorized payment is voided, a captured one refunded in full. A shipped order cannot be cancelled (refund it with orders refund): invalid_transition, with what is allowed in the hint. Returns { status, order, next }.",
+    'orders cancel': "Cancel an order the human does not want, before it ships: c11r orders cancel <number>. An authorized payment is voided, a captured one refunded in full. A shipped order cannot be cancelled (refund it with orders refund): invalid_transition, with what is allowed in the hint. Returns { status, order, next }. A pending order (from orders create) is dropped: it reads cancelled and archived, and lists with --status pending --archived.",
     'orders refund': "Give money back on a captured order, only the amount the human said: c11r orders refund <number> [--amount <n>]. --amount is in major units (4.50); without it, everything still refundable. Refunding the last of the payment cancels the order. Returns { status, order, next }; refund_exceeds when the amount is more than payment.refundable.",
     'orders archive': 'Hide an order from orders list (any status), for orders that need nothing more: c11r orders archive <number>. Idempotent. orders list --archived shows them.',
     'orders unarchive': 'Bring an archived order back into orders list: c11r orders unarchive <number>. Idempotent.',
@@ -59,6 +66,14 @@ export const HELP = {
     'fulfillment ready': 'Mark a shipment ready to ship: c11r fulfillment ready <shipment>. Needs the order approved. Returns { status, shipment, next }.',
     'fulfillment ship': "Mark a shipment shipped, with the carrier's tracking when the human has it: c11r fulfillment ship <shipment> [--carrier <name>] [--tracking <number>] [--tracking-url <https url>]. Needs the order approved and the shipment picked first (c11r fulfillment pick <shipment>): an upcoming shipment cannot ship. Ask the human for the tracking, never invent it. Returns { status, shipment, next }.",
     'fulfillment deliver': 'Mark a shipped shipment delivered: c11r fulfillment deliver <shipment>. Returns { status, shipment, next }.',
+    'ops check': "Run the store on a schedule, step 1: what is new and what the policy would do, without changing anything. c11r ops check [--since 24h|7d|<ISO>]. Returns { checked_at, since, policy, new_orders, actions, held, waiting, awaiting_payment, stuck, counts, truncated, next }: new_orders are placed orders not reported before (each check remembers what it reported, so the next one does not repeat them; --since looks back from a time instead and remembers nothing); each decision is { order: { id, number, placed_at, country (the shipping country), channel, email, items, total, payment_status }, action: approve_capture | approve | capture | hold | wait, reason }; held are orders the policy keeps for the human (review_above, hold_countries), waiting are those it leaves to them (auto_approve or auto_capture off); awaiting_payment are orders with no payment yet; stuck are shipments picking, packing or ready to ship longer than stuck_days, or shipped longer than transit_days and not delivered, with { shipment, days, since, reason } (on hold is the human's choice, never stuck); counts are the real totals, and truncated says a list was cut. Ages are by the store's clock (checked_at). The policy is .commercelayer/ops.yml, agreed with the human and committed with the store, never sent to the API (c11r plan checks it): auto_approve and auto_capture (true or false, default false: set them only when the human says so), review_above (hold orders above it, in major units of the order's currency), hold_countries (hold orders shipping there, ISO codes), stuck_days (2), transit_days (7), and for orders from emails and messages mail_orders: { auto_place (false: they stay pending for the human), labels: { pending, ordered, declined } (the email labels, those names by default) }. Without the file nothing is approved: every order waits for the human. Pass next on: it says what ops run would do and what to tell the human.",
+    'ops run': "Run the store on a schedule, step 2: apply the policy in .commercelayer/ops.yml (see ops check). c11r ops run [--dry-run]. Approves, and captures when auto_capture is on, every placed order the policy does not hold; captures approved orders when auto_capture is on. It never ships, cancels or refunds: those stay with the human. Returns { ran_at, policy, new_orders, done: [{ action, order }], failed, held, waiting, awaiting_payment, stuck, next }; it acts on every order, beyond the 50 a check shows; with --dry-run, would_do instead of done, and nothing changes. failed lists orders that changed meanwhile (invalid_transition): nothing else stops. Tell the human about held and stuck, with the reasons.",
+    'ops digest': "A summary for the human of how the store is doing: c11r ops digest [--since 24h|7d|<ISO>] (default 24h). Returns { since, orders: { count, approved, cancelled }, revenue: [Money per currency], refunds, held, waiting, stuck, top_products: [{ sku, name, units, revenue }], summary, next }: count is the orders placed in the span that are placed or approved now, cancelled the ones cancelled since; refunds are apart from revenue. summary is plain text written for the human: give it to them as it is.",
+    'insights': "Sales over a time span, by one dimension: c11r insights [--since 24h|7d|30d|<ISO>] [--until <ISO>] [--by product|day|market|country|channel|promotion] (default 30d, at most 366 days). Returns { since, until, by, as_of, totals: { orders, units, revenue, average_order, refunds, cancellations }, rows: [{ key, label, orders, units, revenue, discount }], top_products: [{ sku, name, orders, units, revenue }], channel: { agent, link, web }, partial, summary, next }: orders are those placed in the span that are placed or approved now; revenue includes taxes, shipping and discounts, refunds are apart, cancellations count the orders cancelled since; rows only with --by (day has every day, country the shipping country, promotion its discount); partial: only the 1,000 newest orders are counted; money is per currency, never summed across currencies. Give the human the summary; the rows have the numbers.",
+    'inbox check': 'The inbox orders arrive in, over IMAP: c11r inbox check. Returns { host, user, folder, exists, unseen, next }. The connection is in .commercelayer/credentials (gitignored): C11R_IMAP_HOST, C11R_IMAP_USER, C11R_IMAP_PASSWORD (for Gmail an app password, never the account password), optionally C11R_IMAP_PORT (993) and C11R_IMAP_FOLDER (INBOX). Missing ones answer missing_credentials with how to set them: the human writes the password in the file, never in the chat; no output ever shows it. A mail connector the agent already has does the same job: use it first. The CLI never sends email: there is no inbox reply, replies stay with the human.',
+    'inbox list': 'The messages in the inbox, newest first: c11r inbox list [--unseen] [--since 24h|7d|<ISO>] [--limit 20]. Returns { folder, count, new, messages: [{ id, message_id, from, subject, date, seen, labels, new }], next }: new marks the messages not pulled before. Nothing is marked read.',
+    'inbox pull': 'Save messages for the agent to read: c11r inbox pull <id> | --unseen (every unseen message not pulled yet, --limit 20). Each goes to .commercelayer/inbox/<id>/ (gitignored): message.json { id, message_id, from, to, subject, date, labels, text, html, attachments: [{ file, name, content_type, size }] }, body.txt, and attachments/ with each file as it came (25 MB at most; PDFs, sheets and documents are not converted: open them yourself). Nothing is marked read. Returns { count, pulled: [{ id, dir, message, body, subject, from, message_id, attachments }], next }.',
+    'inbox tag': 'Mark what was done with an email: c11r inbox tag <id> [--label <name>]... [--unlabel <name>]... [--move <folder>] [--seen], for example --label ordered --unlabel pending --seen. On Gmail labels are labels; elsewhere keyword flags when the server keeps them, else labels_unsupported: use --move <folder>. The label names are mail_orders.labels in .commercelayer/ops.yml (pending, ordered, declined by default). Returns { status: tagged, id, labels_as: gmail_label|keyword|null, labeled, unlabeled, moved_to, seen, notes }.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
     'ucp check': 'Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way. Exits 1 when a check fails.',
     'ucp search': "Buy for the human, step 1: search a store's catalog over UCP. c11r ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country CC] [--images] [--store <host>]. Search with the words that matter, in any order (\"dark roast coffee\" or \"coffee dark\"): the store ranks products with every word first; no words lists the whole catalog (up to 50). --category narrows to a category or its subcategories (\"Coffee\" includes \"Coffee > Single origin\"), repeat it for any of several; --min-price and --max-price are in major units of the store's currency (15 means 15.00); --country is the human's country: prices, shipping and availability for it. Returns { store, query, prices: { market, market_name, currency, countries, tax_included }, filters, count, total_count, has_more, products: [{ id, title, description, url, image_url, categories: [\"Coffee > Single origin\"], partial, matched_on, variants: [{ id, sku, title, price: { amount, currency, major, display }, list_price, available, availability, shipping: { to, option, price, earliest, latest, ships_to_country } }] }], messages, signature }. list_price is the price before a sale, only when there is one; partial: true marks a product with only some of the words. Show the human the titles, categories and price.display (amount is in minor units: never show it), with shipping.price.display and the arrival dates when they ask what it costs delivered; let them pick, then c11r ucp checkout create --item <variant id>. Read messages and pass on what they say: with no results or a partial match they list the store's categories, and prices says which market the prices are for. --store is any store that speaks UCP (hostname or https origin); the default is this folder's store. --images is for agents that can read image files and want to look at or describe a product: it saves each product's image (the first 24) and adds image_file, the file's absolute path, or image_error when the download failed; showing a thumbnail in a chat needs only image_url.",
@@ -124,6 +139,8 @@ export async function init(values) {
 export async function plan() {
     const api = createApi(requireCredentials());
     const desired = loadStore();
+    // The ops policy is checked here too, so a mistake shows before a scheduled run trips on it.
+    ops.loadPolicy();
     const state = await api.getStore();
     const assets = planAssets(state, desired);
     const changes = [...diff(state, desired), ...assets.changes];
@@ -321,6 +338,10 @@ const LIST_LIMIT = (raw) => {
 function orderNext(o) {
     const n = o.number;
     const shipment = o.shipments?.[0];
+    if (o.status === 'pending')
+        return `Order ${n} is pending: made from an email or a message, not placed yet. Show the human its lines and total (c11r orders show ${n}); on their yes, place it: c11r orders place ${n}. If they don't want it: c11r orders cancel ${n}.`;
+    if (o.status === 'cancelled' && o.archived)
+        return `Order ${n} is cancelled and archived (payment ${o.payment_status}). Nothing more to do.`;
     if (o.status === 'cancelled')
         return `Order ${n} is cancelled (payment ${o.payment_status}). Nothing more to do; archive it to keep the list short: c11r orders archive ${n}.`;
     if (o.status === 'placed' && o.payment_status !== 'authorized')
@@ -338,14 +359,15 @@ export async function ordersList(values, flags) {
     const archived = values.archived ?? (flags.has('--archived') ? 'true' : undefined);
     if (archived !== undefined && !['true', 'false', 'all'].includes(archived))
         fail('invalid_argument', `--archived ${archived} is not a choice.`, 'Use --archived for only the archived orders, or --archived all for every order.');
-    const query = { status: values.status, payment: values.payment, fulfillment: values.fulfillment, archived, limit: LIST_LIMIT(values.limit) };
+    const query = { status: values.status, payment: values.payment, fulfillment: values.fulfillment, channel: values.channel, archived, limit: LIST_LIMIT(values.limit) };
     const { orders } = await api.listMerchantOrders(query);
     const waiting = orders.filter((o) => o.status === 'placed').length;
+    const pending = orders.filter((o) => o.status === 'pending').length;
     return {
         count: orders.length,
         orders,
         next: orders.length
-            ? `Show the human the orders (number, status, payment_status, total.display, email).${waiting ? ` ${waiting} placed order(s) wait for the human to approve them: c11r orders show <number> for one, then c11r orders approve <number> --capture once they say so.` : ''}`
+            ? `Show the human the orders (number, status, payment_status, total.display, email).${pending ? ` ${pending} pending order(s) from emails or messages wait for the human's yes: c11r orders show <number>, then c11r orders place <number>.` : ''}${waiting ? ` ${waiting} placed order(s) wait for the human to approve them: c11r orders show <number> for one, then c11r orders approve <number> --capture once they say so.` : ''}`
             : 'No orders match. Without --status the list has placed and approved orders only: --status all shows every one, --archived the archived ones.',
     };
 }
@@ -370,6 +392,61 @@ export async function ordersAct(action, id, values, flags) {
     const order = await createApi(requireCredentials()).orderAction(id, action, body);
     return { status: action === 'archive' ? 'archived' : action === 'unarchive' ? 'unarchived' : order.status, order, next: orderNext(order) };
 }
+// Orders from emails and messages: the agent reads the message, the API resolves the lines
+// against the catalog (catalog prices only) and creates the order pending, or placed under the
+// policy; a line it cannot resolve comes back for the human, with nothing created.
+/** The flags that write the request itself; with -f or stdin only --source may be added. */
+const REQUEST_FLAGS = ['email', 'first-name', 'last-name', 'company', 'phone', 'item', 'query', 'street', 'line-2', 'city', 'postal-code', 'region', 'country', 'reference', 'notes', 'language'];
+const CREATE_USAGE = "Give the order as YAML or JSON with -f <file> or on stdin (c11r orders create <<'EOF' ... EOF), or with flags: --email --first-name --last-name --phone --item <sku>:<qty> --street --city --postal-code --country.";
+function requestFromFlags(values, lists) {
+    const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+    return drop({
+        customer: drop({ email: values.email, first_name: values['first-name'], last_name: values['last-name'], company: values.company, phone: values.phone }),
+        ship_to: drop({ line_1: values.street, line_2: values['line-2'], city: values.city, postal_code: values['postal-code'], region: values.region, country: values.country }),
+        items: [...(lists.item ?? []).map((x) => lineFlag(x, 'sku')), ...(lists.query ?? []).map((x) => lineFlag(x, 'query'))],
+        notes: values.notes,
+        reference: values.reference,
+        language: values.language,
+    });
+}
+const RESOLUTION_WORDS = { ambiguous: 'could be several products', not_found: 'matches nothing in the catalog', unavailable: 'is not sold in that country' };
+function createdNext(r, placedBy) {
+    const order = r.order;
+    if (r.status === 'needs_review' || !order) {
+        const open = r.resolution.filter((x) => x.status !== 'matched');
+        const lines = open.map((x) => `"${x.requested}" ${RESOLUTION_WORDS[x.status] ?? x.status}${x.candidates.length ? ` (${x.candidates.map((c) => `${c.name}, ${c.sku}`).join('; ')})` : ''}`);
+        return `Nothing was created: ${ops.plural(open.length, 'line needs', 'lines need')} the human: ${lines.join('; ')}. Show them the candidates and ask which they meant; then run orders create again with --item <sku>:<quantity> for those lines (the same --source), or with --force to create the order without them.`;
+    }
+    const dup = r.warnings?.find((w) => w.code === 'duplicate_source');
+    const dropped = r.warnings?.filter((w) => w.code === 'line_dropped') ?? [];
+    const before = [
+        dup ? `This source already made order ${order.number}: nothing new was created.` : '',
+        dropped.length ? `Tell the human ${ops.plural(dropped.length, 'line was', 'lines were')} left out (warnings).` : '',
+        !dup && order.status === 'placed' && placedBy ? `Placed at once (${placedBy}).` : '',
+    ].filter(Boolean);
+    return [...before, orderNext(order)].join(' ');
+}
+export async function ordersCreate(values, lists, flags) {
+    if (flags.has('--place') && flags.has('--hold'))
+        fail('invalid_argument', '--place and --hold say opposite things.', 'Use --place to place it at once, --hold to leave it pending whatever the policy says, or neither to follow mail_orders.auto_place.');
+    const byFlags = REQUEST_FLAGS.some((k) => values[k] !== undefined);
+    if (byFlags && values.file)
+        fail('invalid_argument', 'The order is given both in a file and with flags.', 'Give it in the file (-f) or with flags, not both; --source, --place, --hold and --force go with either.');
+    const raw = byFlags ? requestFromFlags(values, lists) : await readText(values, 'order request', CREATE_USAGE);
+    if (raw && typeof raw === 'object' && !Array.isArray(raw) && values.source !== undefined)
+        raw.source = sourceFlag(values.source);
+    const request = checkOrderRequest(raw);
+    const policy = ops.loadPolicy();
+    // --hold wins; then --place or place: true in the request; then the policy.
+    const placedBy = flags.has('--hold') ? null : flags.has('--place') ? '--place' : request.place ? 'place: true in the request' : policy.mail_orders.auto_place ? 'mail_orders.auto_place in .commercelayer/ops.yml' : null;
+    delete request.place;
+    if (placedBy)
+        request.place = true;
+    if (flags.has('--force'))
+        request.force = true;
+    const r = await createApi(requireCredentials()).createOrder(request);
+    return { status: r.status, order: r.order, resolution: r.resolution, warnings: r.warnings?.length ? r.warnings : undefined, next: createdNext(r, placedBy) };
+}
 function shipmentNext(s) {
     const n = s.number;
     if (s.status === 'delivered')
@@ -776,3 +853,384 @@ export async function linksDelete(id) {
     await createApi(requireCredentials()).deleteLink(id);
     return { status: 'deleted', id };
 }
+// ---------- ops: the merchant agent on a schedule, and insights
+/** Pages read at most when a snapshot list is cut (50) and the run needs every order. */
+const MAX_PAGES = 10;
+/** Every order a list query matches, oldest first, page by page (at most MAX_PAGES of 100). */
+async function allOrders(api, query) {
+    const out = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const r = await api.listMerchantOrders({ ...query, direction: 'asc', limit: '100', page: String(page) });
+        out.push(...r.orders);
+        if (!r.has_more)
+            return { orders: out, truncated: false };
+    }
+    return { orders: out, truncated: true };
+}
+/**
+ * What the loop works on: the API's snapshot (one call, server time), each cut list read in full
+ * when the run needs it; on an API without the snapshot, one page of each list.
+ */
+async function opsSnapshot(api, policy, full) {
+    try {
+        const r = await api.getOps({ stuck_days: String(policy.stuck_days), transit_days: String(policy.transit_days) });
+        const placed = full && r.has_more.placed_unapproved ? await allOrders(api, { status: 'placed' }) : { orders: r.orders.placed_unapproved, truncated: r.has_more.placed_unapproved };
+        const uncaptured = full && r.has_more.approved_uncaptured ? await allOrders(api, { status: 'approved', payment: 'authorized,partially_authorized' }) : { orders: r.orders.approved_uncaptured, truncated: r.has_more.approved_uncaptured };
+        return {
+            as_of: r.as_of,
+            placed: placed.orders,
+            uncaptured: uncaptured.orders,
+            awaiting_payment: r.orders.awaiting_payment,
+            stuck: r.shipments.stuck.map((x) => ops.stuckView(x, x.since_days, policy)),
+            counts: { placed: r.counts.placed_unapproved, uncaptured: r.counts.approved_uncaptured, awaiting_payment: r.counts.awaiting_payment, stuck: r.counts.stuck },
+            truncated: placed.truncated || uncaptured.truncated || r.has_more.awaiting_payment || r.has_more.stuck,
+        };
+    }
+    catch (e) {
+        if (!(e instanceof CliError) || e.code !== 'ops_unsupported')
+            throw e;
+    }
+    // An API before the snapshot: one page of 25 of each list, ages by this machine's clock.
+    const [placed, uncaptured, shipments] = await Promise.all([
+        api.listMerchantOrders({ status: 'placed', limit: '25' }),
+        api.listMerchantOrders({ status: 'approved', payment: 'authorized', limit: '25' }),
+        api.listShipments({ status: 'picking,packing,ready_to_ship,shipped', limit: '25' }),
+    ]);
+    const stuck = ops.stuckShipments(shipments.shipments, policy);
+    const oldest = (l) => [...l].sort((a, b) => Date.parse(a.placed_at) - Date.parse(b.placed_at));
+    return {
+        as_of: new Date().toISOString(),
+        placed: oldest(placed.orders),
+        uncaptured: oldest(uncaptured.orders),
+        awaiting_payment: [],
+        stuck,
+        counts: { placed: placed.orders.length, uncaptured: uncaptured.orders.length, awaiting_payment: 0, stuck: stuck.length },
+        truncated: [placed.orders, uncaptured.orders, shipments.shipments].some((l) => l.length >= 25),
+    };
+}
+function opsPlan(snap, policy) {
+    const placed = snap.placed.map((o) => ops.decidePlaced(o, policy));
+    const uncaptured = snap.uncaptured.map((o) => ops.decideApproved(o, policy));
+    const all = [...placed, ...uncaptured];
+    return {
+        placed,
+        actions: all.filter((d) => d.action !== 'hold' && d.action !== 'wait'),
+        held: all.filter((d) => d.action === 'hold'),
+        waiting: all.filter((d) => d.action === 'wait'),
+        stuck: snap.stuck,
+        unpaid: snap.awaiting_payment,
+    };
+}
+const VERB = { approve_capture: ['approve and capture', 'approved and captured'], approve: ['approve', 'approved'], capture: ['capture', 'captured'] };
+const heldText = (held) => held.map((d) => `#${d.order.number} (${d.order.total.display}): ${d.reason}`).join('; ');
+const stuckText = (stuck) => stuck.map((s) => `${s.shipment.number} ${s.reason}`).join('; ');
+/** What the actions do, grouped by verb: "approve and capture 3 orders (#1, #2, #3)". */
+function actionsText(actions, past = false) {
+    return Object.entries(VERB)
+        .map(([k, [now, then]]) => {
+        const verb = past ? then : now;
+        const these = actions.filter((d) => d.action === k);
+        return these.length ? `${verb} ${ops.plural(these.length, 'order')} (${ops.numbers(these)})` : '';
+    })
+        .filter(Boolean)
+        .join(', ');
+}
+/** The rest of a next: what waits for the human, what is held, what is stuck. */
+function forTheHuman(p) {
+    const out = [];
+    if (p.held.length)
+        out.push(`Tell the human ${ops.plural(p.held.length, 'order is', 'orders are')} held for them: ${heldText(p.held)}. If they agree, c11r orders approve <number> --capture.`);
+    const approve = p.waiting.filter((d) => p.placed.includes(d));
+    const capture = p.waiting.filter((d) => !p.placed.includes(d));
+    if (approve.length)
+        out.push(`${ops.plural(approve.length, 'placed order waits', 'placed orders wait')} for the human to approve (auto_approve is off): ${ops.numbers(approve)}; c11r orders approve <number> --capture once they say so.`);
+    if (capture.length)
+        out.push(`${ops.plural(capture.length, 'approved order has', 'approved orders have')} the payment still to take (auto_capture is off): ${ops.numbers(capture)}; c11r orders capture <number> when the human says so.`);
+    if (p.unpaid.length)
+        out.push(`${ops.plural(p.unpaid.length, 'order has', 'orders have')} no payment yet: ${p.unpaid.map((o) => `#${o.number}`).join(', ')}.`);
+    if (p.stuck.length)
+        out.push(`${ops.plural(p.stuck.length, 'shipment looks', 'shipments look')} stuck: ${stuckText(p.stuck)}. Tell the human; shipping and cancelling are theirs to decide.`);
+    return out;
+}
+const policyView = (p) => ({ auto_approve: p.auto_approve, auto_capture: p.auto_capture, review_above: p.review_above, hold_countries: p.hold_countries, stuck_days: p.stuck_days, transit_days: p.transit_days });
+const brief = (o) => ({ id: o.id, number: o.number, placed_at: o.placed_at, total: o.total, payment_status: o.payment_status });
+export async function opsCheck(values) {
+    const policy = ops.loadPolicy();
+    const api = createApi(requireCredentials());
+    const cursor = ops.readCursor();
+    const snap = await opsSnapshot(api, policy, false);
+    const now = Date.parse(snap.as_of);
+    const since = values.since === undefined ? undefined : ops.parseSince(values.since, 'since', now);
+    const p = opsPlan(snap, policy);
+    const fresh = p.placed.filter((d) => (since ? Date.parse(d.order.placed_at) >= since.getTime() : !cursor.seen.includes(d.order.id)));
+    // --since looks back without moving the cursor; a plain check marks what it reported as seen.
+    if (!since)
+        ops.writeCursor({ last_run: snap.as_of, seen: [...fresh.map((d) => d.order.id), ...cursor.seen] });
+    const parts = [];
+    if (p.actions.length)
+        parts.push(`Run c11r ops run to ${actionsText(p.actions)}.`);
+    parts.push(...forTheHuman(p));
+    return {
+        checked_at: snap.as_of,
+        since: since?.toISOString() ?? cursor.last_run,
+        policy: policyView(policy),
+        new_orders: fresh,
+        actions: p.actions,
+        held: p.held,
+        waiting: p.waiting,
+        awaiting_payment: p.unpaid.length ? p.unpaid.map(brief) : undefined,
+        stuck: p.stuck,
+        counts: snap.counts,
+        truncated: snap.truncated || undefined,
+        next: parts.length ? parts.join(' ') : `Nothing to do: ${fresh.length ? ops.plural(fresh.length, 'new order') + ', all handled' : 'no new orders'}, nothing held or stuck.`,
+    };
+}
+export async function opsRun(flags) {
+    const policy = ops.loadPolicy();
+    const api = createApi(requireCredentials());
+    const dry = flags.has('--dry-run');
+    const cursor = ops.readCursor();
+    const snap = await opsSnapshot(api, policy, true);
+    const p = opsPlan(snap, policy);
+    const fresh = p.placed.filter((d) => !cursor.seen.includes(d.order.id));
+    const done = [];
+    const failed = [];
+    if (!dry) {
+        // One at a time: a refusal (the human, or another run, moved the order meanwhile) stops nothing else.
+        for (const d of p.actions) {
+            const [action, body] = d.action === 'approve_capture' ? ['approve', { capture: true }] : d.action === 'approve' ? ['approve', {}] : ['capture', {}];
+            try {
+                const o = await api.orderAction(d.order.number, action, body);
+                done.push({ action: d.action, order: { id: o.id, number: o.number, status: o.status, payment_status: o.payment_status, total: o.total } });
+            }
+            catch (e) {
+                if (!(e instanceof CliError) || !['invalid_transition', 'not_found'].includes(e.code))
+                    throw e;
+                failed.push({ action: d.action, order: d.order, error: { code: e.code, message: e.message } });
+            }
+        }
+        ops.writeCursor({ last_run: snap.as_of, seen: [...fresh.map((d) => d.order.id), ...cursor.seen] });
+    }
+    const parts = [];
+    if (dry)
+        parts.push(p.actions.length ? `Dry run: c11r ops run would ${actionsText(p.actions)}. Run it without --dry-run to do it.` : 'Dry run: nothing to approve or capture.');
+    else if (done.length)
+        parts.push(`Done: ${actionsText(p.actions.filter((d) => !failed.some((f) => f.order.id === d.order.id)), true)}. Ship them when they are ready: c11r fulfillment list.`);
+    if (failed.length)
+        parts.push(`${ops.plural(failed.length, 'order was', 'orders were')} refused (see failed): the order changed since; c11r orders show <number> for where it is now.`);
+    parts.push(...forTheHuman(p));
+    return {
+        ran_at: snap.as_of,
+        dry_run: dry || undefined,
+        policy: policyView(policy),
+        new_orders: fresh.length,
+        ...(dry ? { would_do: p.actions } : { done, failed: failed.length ? failed : undefined }),
+        held: p.held,
+        waiting: p.waiting,
+        awaiting_payment: p.unpaid.length ? p.unpaid.map(brief) : undefined,
+        stuck: p.stuck,
+        truncated: snap.truncated || undefined,
+        next: parts.length ? parts.join(' ') : 'Nothing to do: nothing to approve or capture, nothing held or stuck.',
+    };
+}
+/** "The last 24 hours", "The last 7 days", "Since 2026-11-01", "From 2026-11-01 to 2026-11-05". */
+function spanText(raw, until) {
+    if (until)
+        return `From ${raw.trim()} to ${until.trim()}`;
+    const m = raw.trim().match(/^(\d+(?:\.\d+)?)\s*([hdw])$/i);
+    if (!m)
+        return `Since ${raw.trim()}`;
+    const n = Number(m[1]);
+    const unit = { h: 'hour', d: 'day', w: 'week' }[m[2].toLowerCase()];
+    return n === 1 ? `The last ${unit}` : `The last ${n} ${unit}s`;
+}
+const INSIGHTS_BY = ['product', 'day', 'market', 'country', 'channel', 'promotion'];
+/** The period's numbers from insights (one call), or from one page of the order list on an API without it. */
+async function periodNumbers(api, since) {
+    try {
+        const r = await api.insights({ since: since.toISOString() });
+        return { orders: r.totals.orders, revenue: r.totals.revenue, refunds: r.totals.refunds, cancellations: r.totals.cancellations, top: r.top_products.map((t) => ({ sku: t.sku, name: t.name, units: t.units, revenue: t.revenue })), partial: r.partial, note: undefined };
+    }
+    catch (e) {
+        if (!(e instanceof CliError) || e.code !== 'insights_unsupported')
+            throw e;
+    }
+    const all = await api.listMerchantOrders({ status: 'all', archived: 'all', limit: '25' });
+    const inWindow = all.orders.filter((o) => Date.parse(o.placed_at) >= since.getTime());
+    const kept = inWindow.filter((o) => o.status !== 'cancelled');
+    return { orders: kept.length, revenue: ops.totalsByCurrency(kept.map((o) => o.total)), refunds: [], cancellations: inWindow.length - kept.length, top: undefined, partial: all.orders.length >= 25, note: 'Top products and refunds need insights, which this API does not report yet.' };
+}
+export async function opsDigest(values) {
+    const policy = ops.loadPolicy();
+    const api = createApi(requireCredentials());
+    const raw = values.since ?? '24h';
+    const since = ops.parseSince(raw, 'since');
+    const [n, snap, approved] = await Promise.all([periodNumbers(api, since), opsSnapshot(api, policy, false), api.listMerchantOrders({ status: 'approved', since: since.toISOString(), limit: '1' }).catch(() => null)]);
+    const p = opsPlan(snap, policy);
+    // total is every match; an API before paging gives only the page.
+    const approvedCount = approved ? (approved.total ?? approved.orders.length) : undefined;
+    const at = n.partial ? 'at least ' : '';
+    const s = [];
+    s.push(`${spanText(raw)}: ${at}${ops.plural(n.orders, 'order')}${n.orders ? `, ${ops.moneyText(n.revenue)}` : ''}${n.cancellations ? ` (${n.cancellations} more cancelled)` : ''}.`);
+    if (approvedCount)
+        s.push(`${approvedCount} approved.`);
+    if (n.refunds.length)
+        s.push(`Refunded: ${ops.moneyText(n.refunds)}.`);
+    const waitingApproval = p.waiting.filter((d) => p.placed.includes(d));
+    const toCapture = p.waiting.filter((d) => !p.placed.includes(d));
+    if (p.held.length)
+        s.push(`Held for you: ${heldText(p.held)}.`);
+    if (waitingApproval.length)
+        s.push(`Waiting for your approval: ${ops.numbers(waitingApproval)}.`);
+    if (toCapture.length)
+        s.push(`Approved, payment still to take: ${ops.numbers(toCapture)}.`);
+    if (p.stuck.length)
+        s.push(`Stuck: ${stuckText(p.stuck)}.`);
+    if (n.top?.length)
+        s.push(`Top products: ${n.top.map((t) => `${t.name} (${t.units})`).join(', ')}.`);
+    if (!p.held.length && !waitingApproval.length && !toCapture.length && !p.stuck.length)
+        s.push('Nothing waits for you.');
+    return {
+        since: since.toISOString(),
+        orders: { count: n.orders, approved: approvedCount, cancelled: n.cancellations, partial: n.partial || undefined },
+        revenue: n.revenue,
+        refunds: n.refunds,
+        held: p.held,
+        waiting: p.waiting,
+        stuck: p.stuck,
+        top_products: n.top,
+        notes: n.note ? [n.note] : undefined,
+        summary: s.join(' '),
+        next: 'Give the human the summary as it is (it is written for them); act only on what they answer.',
+    };
+}
+/** A summary of insights: totals, refunds and cancellations, channels, top products, then the rows. */
+function insightsSummary(r, raw, until) {
+    const t = r.totals;
+    const out = [];
+    out.push(`${spanText(raw, until)}: ${r.partial ? 'at least ' : ''}${ops.plural(t.orders, 'order')}, ${ops.plural(t.units, 'unit')}, ${ops.moneyText(t.revenue)}${t.orders ? ` (average ${ops.moneyText(t.average_order)})` : ''}.`);
+    const apart = [t.refunds.length ? `${ops.moneyText(t.refunds)} refunded` : '', t.cancellations ? `${ops.plural(t.cancellations, 'order')} cancelled` : ''].filter(Boolean);
+    if (apart.length)
+        out.push(`Apart from that: ${apart.join(', ')}.`);
+    const ch = r.channel;
+    if (ch && ch.agent + ch.link + ch.web + (ch.message ?? 0) && r.by !== 'channel')
+        out.push(`By channel: ${[['agent', 'by agents'], ['link', 'through links'], ['web', 'on the website'], ['message', 'from emails and messages']].filter(([k]) => ch[k]).map(([k, w]) => `${ch[k]} ${w}`).join(', ')}.`);
+    if (r.top_products?.length && r.by !== 'product')
+        out.push(`Top products: ${r.top_products.map((x) => `${x.name} (${x.units})`).join(', ')}.`);
+    const rows = r.rows.filter((x) => x.orders);
+    if (r.by && rows.length)
+        out.push(`By ${r.by}: ${rows.slice(0, 5).map((x) => `${x.label} ${ops.plural(x.orders, 'order')}, ${ops.plural(x.units, 'unit')}, ${ops.moneyText(x.revenue)}`).join('; ')}${rows.length > 5 ? `; and ${rows.length - 5} more` : ''}.`);
+    return out.join(' ');
+}
+export async function insights(values) {
+    const raw = values.since ?? '30d';
+    const since = ops.parseSince(raw, 'since');
+    const until = values.until === undefined ? undefined : ops.parseSince(values.until, 'until');
+    if (until && until <= since)
+        fail('invalid_argument', `--until ${values.until} is not after --since ${raw}.`, 'Give an --until later than --since, or leave it out for now.');
+    const by = values.by;
+    if (by !== undefined && !INSIGHTS_BY.includes(by))
+        fail('invalid_argument', `--by ${by} is not a choice.`, `Use --by with one of ${INSIGHTS_BY.join(', ')}.`);
+    const r = await createApi(requireCredentials()).insights({ since: since.toISOString(), ...(until ? { until: until.toISOString() } : {}), ...(by ? { by } : {}) });
+    return {
+        ...r,
+        summary: insightsSummary(r, raw, values.until),
+        next: `Give the human the summary.${by ? ` The rows have the numbers per ${by}.` : ' For a breakdown, --by product, day, market, country, channel or promotion.'}${r.partial ? ' partial: only the 1,000 newest orders of the period are counted; ask for a shorter period for exact numbers.' : ''}`,
+    };
+}
+// ---------- inbox: order emails over IMAP
+/** Run with the mailbox open; it is closed (logged out) whatever happens. */
+async function withMailbox(run) {
+    const mb = await openMailbox();
+    try {
+        return await run(mb);
+    }
+    finally {
+        await mb.close();
+    }
+}
+const INBOX_LIMIT = (raw) => (raw === undefined ? 20 : Number(LIST_LIMIT(raw)));
+export async function inboxCheck() {
+    return withMailbox(async (mb) => {
+        const c = await mb.check();
+        return {
+            host: mb.host,
+            user: mb.user,
+            folder: mb.folder,
+            exists: c.exists,
+            unseen: c.unseen,
+            next: c.unseen ? `${ops.plural(c.unseen, 'message is', 'messages are')} unseen: c11r inbox list --unseen.` : 'Nothing unseen in the inbox.',
+        };
+    });
+}
+export async function inboxList(values, flags) {
+    const limit = INBOX_LIMIT(values.limit);
+    const since = values.since === undefined ? undefined : ops.parseSince(values.since, 'since');
+    return withMailbox(async (mb) => {
+        const list = await mb.list({ unseen: flags.has('--unseen'), since, limit });
+        const cursor = readInboxCursor();
+        const messages = list.map((m) => ({ ...m, new: !cursor.seen.includes(seenKey(m)) }));
+        writeInboxCursor({ ...cursor, last_check: new Date().toISOString() });
+        const fresh = messages.filter((m) => m.new).length;
+        return {
+            folder: mb.folder,
+            count: messages.length,
+            new: fresh,
+            messages,
+            next: fresh
+                ? 'Read the senders and subjects. For each new message that may be an order (someone asking to buy items), c11r inbox pull <id> and read it. Leave the others alone; tell the human about questions and quote requests.'
+                : `No new messages${flags.has('--unseen') ? ' unseen' : ''}: nothing to do.`,
+        };
+    });
+}
+export async function inboxPull(id, values, flags) {
+    const all = flags.has('--unseen');
+    if (!id && !all)
+        fail('missing_argument', 'Which message?', 'Use `c11r inbox pull <id>` with an id from inbox list, or `c11r inbox pull --unseen` for every unseen message not pulled yet.');
+    const labels = ops.loadPolicy().mail_orders.labels;
+    return withMailbox(async (mb) => {
+        const cursor = readInboxCursor();
+        let ids = id ? [id] : [];
+        if (all)
+            ids = (await mb.list({ unseen: true, limit: INBOX_LIMIT(values.limit) })).filter((m) => !cursor.seen.includes(seenKey(m))).map((m) => m.id);
+        const pulled = [];
+        for (const one of ids) {
+            const got = await mb.fetch(one);
+            if (!got)
+                fail('not_found', `There is no message ${one} in ${mb.folder}.`, 'Run `c11r inbox list` for the ids.');
+            const p = writeMessage(one, await parseMessage(got.raw), got.labels);
+            pulled.push(p);
+            const key = seenKey({ id: one, message_id: p.message_id });
+            cursor.seen = [key, ...cursor.seen.filter((k) => k !== key)];
+        }
+        writeInboxCursor(cursor);
+        const first = pulled[0];
+        return {
+            count: pulled.length,
+            pulled,
+            next: !first
+                ? 'Nothing to pull: every unseen message was pulled before.'
+                : `Read ${pulled.length === 1 ? first.body : 'each body.txt'} and the files in attachments (PDFs, sheets, documents: open them yourself). If it is an order, write the request (customer, ship_to, items by sku or by the words used) to a file and run c11r orders create -f <file> --source email:<message_id>; then c11r inbox tag <id> --label ${labels.ordered} --unlabel ${labels.pending} --seen. If something is missing or unclear, ask the human; if it is not an order, leave the email for the human.`,
+        };
+    });
+}
+export async function inboxTag(id, lists, values, flags) {
+    if (!id)
+        fail('missing_argument', 'Which message?', 'Use `c11r inbox tag <id> --label <name> [--unlabel <name>] [--move <folder>] [--seen]`.');
+    const label = lists.label ?? [];
+    const unlabel = lists.unlabel ?? [];
+    for (const l of [...label, ...unlabel]) {
+        if (!l.trim() || l.length > 50)
+            fail('invalid_argument', `"${l}" is not a label name.`, 'A label is a name of 1 to 50 characters.');
+        if (l.startsWith('\\'))
+            fail('invalid_argument', `${l} is an IMAP flag, not a label.`, 'Use --seen to mark the email read; labels are plain names (ordered, pending).');
+    }
+    if (values.move !== undefined && !values.move.trim())
+        fail('invalid_argument', '--move needs a folder.', 'Use --move <folder>, an existing folder of the mailbox.');
+    if (!label.length && !unlabel.length && values.move === undefined && !flags.has('--seen'))
+        fail('missing_argument', 'Nothing to do to the email.', 'Use --label <name>, --unlabel <name>, --move <folder> or --seen (any of them together).');
+    return withMailbox(async (mb) => {
+        const r = await mb.tag(id, { label, unlabel, move: values.move, seen: flags.has('--seen') });
+        return { status: 'tagged', ...r };
+    });
+}

package/dist/cursor.js

@@ -0,0 +1,31 @@
+// A small JSON state file under .commercelayer/ that a command rewrites on every run (the ops
+// cursor, the inbox cursor): read with defaults when missing or broken, kept out of git from
+// its first write, like the credentials.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ignorePath } from './files.js';
+/** At most this many ids are remembered, newest first. */
+export const MAX_SEEN = 500;
+/** A cursor in `file`: parse turns what was read (or undefined when unreadable) into T. */
+export function jsonCursor(file, parse) {
+    return {
+        file,
+        read() {
+            try {
+                const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+                return parse(raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : undefined);
+            }
+            catch {
+                return parse(undefined);
+            }
+        },
+        write(value) {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            if (!fs.existsSync(file))
+                ignorePath(file);
+            fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+        },
+    };
+}
+/** The strings of a list read back from a cursor file, at most MAX_SEEN. */
+export const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string').slice(0, MAX_SEEN) : []);

package/dist/files.js

@@ -53,12 +53,14 @@ export function requireCredentials() {
     return c;
 }
 /** Make sure .gitignore lists the credentials file. Returns true if it changed. */
-export function ignoreCredentials() {
+export const ignoreCredentials = () => ignorePath(paths.credentials);
+/** Add a path to .gitignore unless it is there; whether it was added. */
+export function ignorePath(file) {
     const existing = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf8') : '';
-    if (existing.split('\n').includes(paths.credentials))
+    if (existing.split('\n').includes(file))
         return false;
     const sep = existing && !existing.endsWith('\n') ? '\n' : '';
-    fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
+    fs.appendFileSync('.gitignore', `${sep}${file}\n`);
     return true;
 }
 /** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */

package/dist/inbox/cursor.js

@@ -0,0 +1,11 @@
+// What the inbox commands remember between runs, in .commercelayer/inbox.json (gitignored):
+// when the inbox was last listed, and the messages already pulled, by Message-ID (or by id
+// when a message has none), so inbox list marks only the others as new.
+import path from 'node:path';
+import { jsonCursor, MAX_SEEN, strings } from '../cursor.js';
+import { paths } from '../files.js';
+const cursor = () => jsonCursor(path.join(paths.dir, 'inbox.json'), (c) => ({ last_check: typeof c?.last_check === 'string' ? c.last_check : null, seen: strings(c?.seen) }));
+export const readInboxCursor = () => cursor().read();
+export const writeInboxCursor = (c) => cursor().write({ last_check: c.last_check, seen: c.seen.slice(0, MAX_SEEN) });
+/** The key a message is remembered by. */
+export const seenKey = (m) => m.message_id ?? `id:${m.id}`;