@commercelayer/agent-cli 0.5.2 → 0.8.0

package/dist/ops.js

@@ -0,0 +1,190 @@
+// The merchant agent running the store on a schedule: what is new since the last run, what the
+// policy approves and captures, what it holds for the human, what is stuck. The policy is the
+// human's, read here and never sent to the API; the cursor (.commercelayer/ops.json) keeps a
+// run from reporting the same order twice. Shipping and cancelling stay with the human.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { jsonCursor, MAX_SEEN, strings } from './cursor.js';
+import { paths } from './files.js';
+import { fail } from './output.js';
+import { minorUnits } from './ucp/platform.js';
+// ---------- the policy
+/**
+ * Where the policy is read from: .commercelayer/ops.yml, the whole file (key null). Committed
+ * with the store and agreed with the human; never sent to the API.
+ */
+export const POLICY_SOURCE = { file: 'ops.yml', key: null };
+export const DEFAULT_POLICY = { auto_approve: false, auto_capture: false, review_above: null, hold_countries: [], stuck_days: 2, transit_days: 7, mail_orders: { auto_place: false, labels: { pending: 'pending', ordered: 'ordered', declined: 'declined' } } };
+const POLICY_KEYS = Object.keys(DEFAULT_POLICY);
+export const policyPath = () => path.join(paths.dir, POLICY_SOURCE.file);
+/** The policy, the defaults where it says nothing; invalid_policy with the fix when it is wrong. */
+export function loadPolicy() {
+    const file = policyPath();
+    if (!fs.existsSync(file))
+        return { ...DEFAULT_POLICY, source: null };
+    let doc;
+    try {
+        doc = YAML.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail('invalid_policy', `${file} is not valid YAML: ${e.message.split('\n')[0]}`, 'Fix the YAML, then run the command again.');
+    }
+    const raw = POLICY_SOURCE.key ? doc?.[POLICY_SOURCE.key] : doc;
+    const where = POLICY_SOURCE.key ? `${POLICY_SOURCE.key} in ${file}` : file;
+    return { ...checkPolicy(raw, where), source: file };
+}
+export function checkPolicy(raw, where) {
+    if (raw === undefined || raw === null)
+        return { ...DEFAULT_POLICY };
+    const bad = (what, hint) => fail('invalid_policy', `${where}: ${what}`, hint);
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        bad('the policy is not a set of settings.', `Write it as settings, one per line: auto_approve: true, review_above: 500, … (${POLICY_KEYS.join(', ')}).`);
+    const p = raw;
+    const unknown = Object.keys(p).filter((k) => !POLICY_KEYS.includes(k));
+    if (unknown.length)
+        bad(`${unknown.join(', ')} ${unknown.length === 1 ? 'is not a setting' : 'are not settings'} of the policy.`, `The settings are ${POLICY_KEYS.join(', ')}.`);
+    const out = { ...DEFAULT_POLICY, mail_orders: { auto_place: false, labels: { ...DEFAULT_POLICY.mail_orders.labels } } };
+    for (const k of ['auto_approve', 'auto_capture']) {
+        if (p[k] === undefined)
+            continue;
+        if (typeof p[k] !== 'boolean')
+            bad(`${k} is ${JSON.stringify(p[k])}, not true or false.`, `Write ${k}: true or ${k}: false.`);
+        out[k] = p[k];
+    }
+    if (p.review_above !== undefined && p.review_above !== null) {
+        if (typeof p.review_above !== 'number' || !Number.isFinite(p.review_above) || p.review_above < 0)
+            bad(`review_above is ${JSON.stringify(p.review_above)}, not an amount.`, 'Give it in major units of the order\'s currency, for example review_above: 500, or leave it out to hold none for their total.');
+        out.review_above = p.review_above;
+    }
+    if (p.hold_countries !== undefined) {
+        const list = p.hold_countries;
+        if (!Array.isArray(list) || list.some((c) => typeof c !== 'string' || !/^[A-Za-z]{2}$/.test(c)))
+            bad(`hold_countries is ${JSON.stringify(list)}, not a list of country codes.`, 'Write ISO 3166 codes: hold_countries: [US, CA].');
+        out.hold_countries = list.map((c) => c.toUpperCase());
+    }
+    for (const k of ['stuck_days', 'transit_days']) {
+        if (p[k] === undefined)
+            continue;
+        const n = p[k];
+        if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0)
+            bad(`${k} is ${JSON.stringify(n)}, not a number of days.`, `Write a number of days above 0, for example ${k}: ${DEFAULT_POLICY[k]}.`);
+        out[k] = n;
+    }
+    if (p.mail_orders !== undefined && p.mail_orders !== null) {
+        const m = p.mail_orders;
+        const fix = 'Write it as mail_orders: { auto_place: false, labels: { pending: pending, ordered: ordered, declined: declined } }; every setting is optional.';
+        if (typeof m !== 'object' || Array.isArray(m))
+            bad(`mail_orders is ${JSON.stringify(m)}, not a set of settings.`, fix);
+        const extra = Object.keys(m).filter((k) => k !== 'auto_place' && k !== 'labels');
+        if (extra.length)
+            bad(`mail_orders.${extra[0]} is not a setting: mail_orders has auto_place and labels.`, fix);
+        if (m.auto_place !== undefined && typeof m.auto_place !== 'boolean')
+            bad(`mail_orders.auto_place is ${JSON.stringify(m.auto_place)}, not true or false.`, fix);
+        out.mail_orders.auto_place = m.auto_place === true;
+        if (m.labels !== undefined && m.labels !== null) {
+            const l = m.labels;
+            if (typeof l !== 'object' || Array.isArray(l))
+                bad(`mail_orders.labels is ${JSON.stringify(l)}, not a set of names.`, fix);
+            const names = Object.keys(DEFAULT_POLICY.mail_orders.labels);
+            const other = Object.keys(l).filter((k) => !names.includes(k));
+            if (other.length)
+                bad(`mail_orders.labels.${other[0]} is not a label: the labels are ${names.join(', ')}.`, fix);
+            for (const k of names) {
+                const v = l[k];
+                if (v === undefined)
+                    continue;
+                if (typeof v !== 'string' || !v.trim() || v.length > 50 || v.startsWith('\\'))
+                    bad(`mail_orders.labels.${k} is ${JSON.stringify(v)}, not a label name.`, 'A label is a name of 1 to 50 characters, not starting with a backslash (\\Seen and the like are IMAP flags).');
+                out.mail_orders.labels[k] = v;
+            }
+        }
+    }
+    return out;
+}
+export const cursorPath = () => path.join(paths.dir, 'ops.json');
+// Machine state, rewritten on every run: kept out of git like the credentials.
+const cursor = () => jsonCursor(cursorPath(), (c) => ({ last_run: typeof c?.last_run === 'string' ? c.last_run : null, seen: strings(c?.seen) }));
+export const readCursor = () => cursor().read();
+export const writeCursor = (c) => cursor().write({ last_run: c.last_run, seen: c.seen.slice(0, MAX_SEEN) });
+// ---------- time
+const UNITS = { h: 3600_000, d: 86_400_000, w: 7 * 86_400_000 };
+/** "24h", "7d", "2w" or an ISO date or time: the instant it means, relative to now. */
+export function parseSince(raw, flag, now = Date.now()) {
+    const rel = raw.trim().match(/^(\d+(?:\.\d+)?)\s*([hdw])$/i);
+    if (rel)
+        return new Date(now - Number(rel[1]) * UNITS[rel[2].toLowerCase()]);
+    const t = Date.parse(raw);
+    if (!/^\d{4}-\d{2}-\d{2}/.test(raw.trim()) || Number.isNaN(t))
+        fail('invalid_argument', `--${flag} ${raw} is not a time.`, `Use a span back from now (24h, 7d, 30d) or an ISO date (2026-11-01, 2026-11-01T09:00:00Z).`);
+    return new Date(t);
+}
+const DAY = 86_400_000;
+const days = (ms) => Math.round((ms / DAY) * 10) / 10;
+const brief = (o) => ({ id: o.id, number: o.number, placed_at: o.placed_at, country: o.country, channel: o.channel, email: o.email, items: o.items, total: o.total, payment_status: o.payment_status });
+/** Why the policy holds an order for the human, if it does. */
+export function holdReason(o, p) {
+    const reasons = [];
+    if (p.review_above !== null && o.total.major > p.review_above)
+        reasons.push(`its total ${o.total.display} is above ${o.currency} ${p.review_above.toFixed(2)} (review_above)`);
+    if (o.country && p.hold_countries.includes(o.country.toUpperCase()))
+        reasons.push(`it ships to ${o.country.toUpperCase()} (hold_countries)`);
+    return reasons.length ? reasons.join(' and ') : undefined;
+}
+/** What the policy does with a placed order. */
+export function decidePlaced(o, p) {
+    const held = holdReason(o, p);
+    if (held)
+        return { order: brief(o), action: 'hold', reason: held };
+    if (!p.auto_approve)
+        return { order: brief(o), action: 'wait', reason: 'auto_approve is off: the human approves orders' };
+    if (p.auto_capture && o.payment_status === 'authorized')
+        return { order: brief(o), action: 'approve_capture' };
+    return { order: brief(o), action: 'approve' };
+}
+/** What the policy does with an approved order whose payment is only authorized. */
+export function decideApproved(o, p) {
+    if (!p.auto_capture)
+        return { order: brief(o), action: 'wait', reason: 'auto_capture is off: the human says when to take the payment' };
+    return { order: brief(o), action: 'capture' };
+}
+/** Picking, packing or ready to ship for too long is stuck; on hold is the merchant's choice, never stuck. */
+const WORKING = ['picking', 'packing', 'ready_to_ship'];
+/** A stuck shipment as ops prints it, from its row and its age in days. */
+export function stuckView(s, age, p) {
+    const since = s.status_changed_at ?? s.dates?.[`${s.status}_at`] ?? '';
+    const reason = s.status === 'shipped' ? `shipped ${age} days ago and not delivered (transit_days ${p.transit_days})` : `${s.status.replace(/_/g, ' ')} for ${age} days (stuck_days ${p.stuck_days})`;
+    return { shipment: { id: s.id, number: s.number, status: s.status, order: s.order, country: s.country, tracking: s.tracking }, days: age, since, reason };
+}
+/**
+ * The same as the API's snapshot, for an API without it: shipments picking, packing or ready to
+ * ship longer than stuck_days, or shipped longer than transit_days, from when they entered it.
+ */
+export function stuckShipments(list, p, now = Date.now()) {
+    const out = [];
+    for (const s of list) {
+        const d = (s.dates ?? {});
+        const entered = Date.parse(s.status_changed_at ?? d[`${s.status}_at`] ?? '');
+        if (Number.isNaN(entered))
+            continue;
+        const age = days(now - entered);
+        if ((WORKING.includes(s.status) && now - entered > p.stuck_days * DAY) || (s.status === 'shipped' && now - entered > p.transit_days * DAY))
+            out.push(stuckView(s, age, p));
+    }
+    return out.sort((a, b) => b.days - a.days);
+}
+// ---------- words
+/** "EUR 20.00 + USD 12.00": money in several currencies, summed per currency. */
+export function totalsByCurrency(list) {
+    const by = new Map();
+    for (const m of list)
+        by.set(m.currency, (by.get(m.currency) ?? 0) + m.amount);
+    return [...by].map(([currency, amount]) => {
+        const unit = minorUnits(currency);
+        const major = amount / unit;
+        return { amount, currency, major, display: `${currency} ${major.toFixed(Math.round(Math.log10(unit)))}` };
+    });
+}
+export const moneyText = (list) => (list.length ? list.map((m) => m.display).join(' + ') : '0');
+export const numbers = (list) => list.map((d) => `#${d.order.number}`).join(', ');
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;

package/dist/orderRequest.js

@@ -0,0 +1,141 @@
+// An order request from an email or a message (orders create), checked before it is sent: the
+// same rules the API applies, so a request missing what only the human knows fails here, naming
+// the path. Nothing is ever made up: no placeholder names, phones or addresses.
+import { fail } from './output.js';
+export const MAX_ITEMS = 25;
+const KEYS = ['source', 'customer', 'ship_to', 'bill_to', 'items', 'notes', 'reference', 'language', 'place', 'force'];
+const ASK = 'Ask the human for it; never invent it.';
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const bad = (path, what, hint = ASK) => fail('invalid_argument', `${path}: ${what}`, hint, path);
+/** A text field: absent is undefined; present, it is a non-empty string of at most max characters. */
+function text(o, key, path, opts = {}) {
+    const v = o[key];
+    if (v === undefined || v === null || (typeof v === 'string' && !v.trim())) {
+        if (opts.required)
+            bad(`${path}.${key}`, 'is missing.');
+        return undefined;
+    }
+    if (typeof v !== 'string' && typeof v !== 'number')
+        bad(`${path}.${key}`, `is ${JSON.stringify(v)}, not text.`, 'Give it as text.');
+    const s = String(v).trim();
+    // A dash or a question mark stands for "unknown": the human has to say it.
+    if (/^[-?.]+$/.test(s))
+        bad(`${path}.${key}`, `is "${s}", a placeholder.`);
+    if (s.length > (opts.max ?? 255))
+        bad(`${path}.${key}`, `is longer than ${opts.max ?? 255} characters.`, 'Shorten it.');
+    return s;
+}
+function unknownKeys(o, allowed, path) {
+    const extra = Object.keys(o).filter((k) => !allowed.includes(k));
+    if (extra.length)
+        bad(`${path ? `${path}.` : ''}${extra[0]}`, `is not a field${path ? ` of ${path}` : ''}.`, `The fields are ${allowed.join(', ')}.`);
+}
+function address(o, path, withNames) {
+    if (!isObj(o))
+        return bad(path, 'is missing: the address the order ships to.');
+    const fields = ['line_1', 'line_2', 'city', 'postal_code', 'region', 'country', 'phone', ...(withNames ? ['first_name', 'last_name', 'company'] : [])];
+    unknownKeys(o, fields, path);
+    const country = text(o, 'country', path, { required: true }).toUpperCase();
+    if (!/^[A-Z]{2}$/.test(country))
+        bad(`${path}.country`, `is "${country}", not an ISO 3166 country code.`, 'Give the two-letter code: IT, FR, US.');
+    const out = {
+        line_1: text(o, 'line_1', path, { required: true }),
+        line_2: text(o, 'line_2', path),
+        city: text(o, 'city', path, { required: true }),
+        postal_code: text(o, 'postal_code', path, { required: true, max: 20 }),
+        region: text(o, 'region', path, { max: 50 }),
+        country,
+        phone: text(o, 'phone', path, { max: 40 }),
+        ...(withNames ? { first_name: text(o, 'first_name', path), last_name: text(o, 'last_name', path), company: text(o, 'company', path) } : {}),
+    };
+    return Object.fromEntries(Object.entries(out).filter(([, v]) => v !== undefined));
+}
+/** The request, checked and trimmed; invalid_argument naming the path, or too_many_items. */
+export function checkOrderRequest(raw) {
+    if (!isObj(raw))
+        return bad('request', 'is not a set of fields.', `Give it as YAML or JSON with ${KEYS.join(', ')}.`);
+    unknownKeys(raw, KEYS, '');
+    if (!isObj(raw.customer))
+        bad('customer', 'is missing: who the order is for (email, first_name, last_name or company, phone).');
+    const c = raw.customer;
+    unknownKeys(c, ['email', 'first_name', 'last_name', 'company', 'phone'], 'customer');
+    const email = text(c, 'email', 'customer', { required: true });
+    if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email))
+        bad('customer.email', `is "${email}", not an email address.`);
+    const customer = { email, first_name: text(c, 'first_name', 'customer'), last_name: text(c, 'last_name', 'customer'), company: text(c, 'company', 'customer'), phone: text(c, 'phone', 'customer', { max: 40 }) };
+    if (!customer.company && !(customer.first_name && customer.last_name))
+        bad(customer.first_name ? 'customer.last_name' : 'customer.first_name', 'is missing: an order needs the first and last name, or a company.');
+    const ship_to = address(raw.ship_to, 'ship_to', false);
+    if (!customer.phone && !ship_to.phone)
+        bad('customer.phone', 'is missing: Commerce Layer needs a phone number for the shipping address.');
+    const bill_to = raw.bill_to === undefined || raw.bill_to === null ? undefined : address(raw.bill_to, 'bill_to', true);
+    if (!Array.isArray(raw.items) || raw.items.length === 0)
+        bad('items', 'is missing: at least one line, { sku, quantity } or { query, quantity }.', 'Give each line a sku, or the words that name the product as query.');
+    const list = raw.items;
+    if (list.length > MAX_ITEMS)
+        fail('too_many_items', `items: ${list.length} lines, more than the ${MAX_ITEMS} one order takes.`, `Split it into orders of at most ${MAX_ITEMS} lines, with the human.`, 'items');
+    const items = list.map((it, i) => {
+        const path = `items[${i}]`;
+        if (!isObj(it))
+            return bad(path, `is ${JSON.stringify(it)}, not { sku, quantity } or { query, quantity }.`, 'Give each line a sku or a query, and a quantity.');
+        unknownKeys(it, ['sku', 'query', 'quantity'], path);
+        const sku = text(it, 'sku', path, { max: 100 });
+        const query = text(it, 'query', path, { max: 200 });
+        if (!sku && !query)
+            bad(path, 'has neither sku nor query.', 'Give the sku, or the words that name the product as query.');
+        const q = it.quantity ?? 1;
+        if (typeof q !== 'number' || !Number.isInteger(q) || q < 1 || q > 10_000)
+            bad(`${path}.quantity`, `is ${JSON.stringify(q)}, not a whole number from 1 to 10,000.`, 'Give how many, as the message says; ask the human if it looks wrong.');
+        return { ...(sku ? { sku } : {}), ...(query ? { query } : {}), quantity: q };
+    });
+    // Required: it makes the request idempotent, so a message never makes two orders.
+    let source;
+    {
+        const how = 'Give where the order came from: --source email:<Message-ID> for an email, --source message:<id> for anything else (the chat message or form id), or source: { kind, id } in the request.';
+        if (raw.source === undefined || raw.source === null)
+            bad('source', 'is missing: where the order came from.', how);
+        if (!isObj(raw.source))
+            return bad('source', 'is not { kind, id }.', how);
+        const s = raw.source;
+        unknownKeys(s, ['kind', 'id', 'from', 'subject', 'received_at'], 'source');
+        const kind = text(s, 'kind', 'source', { required: true });
+        if (kind !== 'email' && kind !== 'message')
+            bad('source.kind', `is "${kind}", not email or message.`, 'Use email for an email, message for anything else (a chat, a form, a call).');
+        source = { kind: kind, id: text(s, 'id', 'source', { required: true }), from: text(s, 'from', 'source'), subject: text(s, 'subject', 'source', { max: 500 }), received_at: text(s, 'received_at', 'source', { max: 40 }) };
+        source = Object.fromEntries(Object.entries(source).filter(([, v]) => v !== undefined));
+    }
+    const language = text(raw, 'language', 'request', { max: 5 })?.toLowerCase();
+    if (language && !/^[a-z]{2}$/.test(language))
+        bad('language', `is "${language}", not an ISO 639-1 code.`, 'Give the two-letter code: en, it, fr.');
+    for (const k of ['place', 'force'])
+        if (raw[k] !== undefined && typeof raw[k] !== 'boolean')
+            bad(k, `is ${JSON.stringify(raw[k])}, not true or false.`, `Write ${k}: true or leave it out.`);
+    const out = {
+        source,
+        customer: Object.fromEntries(Object.entries(customer).filter(([, v]) => v !== undefined)),
+        ship_to,
+        ...(bill_to ? { bill_to } : {}),
+        items,
+        ...(text(raw, 'notes', 'request', { max: 1000 }) ? { notes: text(raw, 'notes', 'request', { max: 1000 }) } : {}),
+        ...(text(raw, 'reference', 'request') ? { reference: text(raw, 'reference', 'request') } : {}),
+        ...(language ? { language } : {}),
+        ...(raw.place === true ? { place: true } : {}),
+        ...(raw.force === true ? { force: true } : {}),
+    };
+    return out;
+}
+/** "SKU:3" → { sku, quantity }, "dark roast:2" → { query, quantity }; no ":<n>" is 1. */
+export function lineFlag(raw, kind) {
+    const m = raw.match(/^(.*?)(?::\s*(\d+))?$/s);
+    const value = m[1].trim();
+    if (!value)
+        fail('invalid_argument', `--${kind === 'sku' ? 'item' : 'query'} ${raw} names nothing.`, kind === 'sku' ? 'Use --item <sku>:<quantity>, for example --item ETH:3.' : 'Use --query "<words>:<quantity>", for example --query "dark roast:2".');
+    return { [kind]: value, quantity: m[2] === undefined ? 1 : Number(m[2]) };
+}
+/** "email:<id>" or "message:<id>": the kind is everything before the first colon. */
+export function sourceFlag(raw) {
+    const i = raw.indexOf(':');
+    if (i < 1 || !raw.slice(i + 1).trim())
+        fail('invalid_argument', `--source ${raw} is not kind:id.`, 'Use --source email:<Message-ID> for an email, --source message:<id> for anything else.');
+    return { kind: raw.slice(0, i), id: raw.slice(i + 1).trim() };
+}

package/dist/output.js

@@ -6,14 +6,18 @@
 export class CliError extends Error {
     code;
     hint;
-    constructor(code, message, hint) {
+    path;
+    constructor(code, message, hint, 
+    /** The field of a request the error is about: customer.phone, items[0].quantity. */
+    path) {
         super(message);
         this.code = code;
         this.hint = hint;
+        this.path = path;
     }
 }
-export function fail(code, message, hint) {
-    throw new CliError(code, message, hint);
+export function fail(code, message, hint, path) {
+    throw new CliError(code, message, hint, path);
 }
 export function progress(data) {
     process.stderr.write(JSON.stringify(data) + '\n');

package/dist/store.js

@@ -59,6 +59,8 @@ catalog:
   #                    # C11R_SUPABASE_URL and C11R_SUPABASE_KEY in .commercelayer/credentials
   # source: merchant   # a Google Merchant Center feed, RSS (XML) or TSV: url is the feed;
   #                    # translations: { it: <the it feed url> } adds other languages, by id
+  # source: website    # a brand's website, for a demo store: url is the site; limit is how
+  #                    # many products (default 100, at most 500). Images stay on the site.
   # url: https://...
   # table: products