@commercelayer/agent-cli 0.5.1 → 0.7.0

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/ucp/images.js

@@ -0,0 +1,62 @@
+// --images: each product's image_url saved as a file, for agents that can read images and
+// want to look at or describe a product. Files go under <tmpdir>/c11r/images/<store host>/,
+// named by product id and a hash of the URL, so a file already there is reused and a new
+// image gets a new file. A chat thumbnail needs only image_url, never this.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { download } from '../api/transport.js';
+export const MAX_IMAGES = 24;
+const TIMEOUT_MS = 5000;
+const MAX_BYTES = 10 * 1024 * 1024;
+const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/avif': 'avif', 'image/svg+xml': 'svg' };
+/** The folder of a store's images: C11R_IMAGES_DIR (tests) or the OS temp dir. */
+export const imagesDir = (origin) => path.join(process.env.C11R_IMAGES_DIR ?? path.join(os.tmpdir(), 'c11r', 'images'), new URL(origin).host);
+const safe = (s) => s.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 80) || 'product';
+/** One product's image: the path of its file, or why there is none. */
+async function fetchImage(dir, p) {
+    const url = p.image_url;
+    if (typeof url !== 'string' || !url)
+        return { image_error: 'The product has no image_url.' };
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { image_error: `image_url ${url} is not a URL.` };
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol))
+        return { image_error: `image_url ${url} is not an http(s) address.` };
+    const stem = `${safe(String(p.id ?? ''))}-${crypto.createHash('sha256').update(url).digest('hex').slice(0, 10)}`;
+    const kept = fs.existsSync(dir) ? fs.readdirSync(dir).find((f) => f.startsWith(`${stem}.`) && Object.values(EXT).includes(f.slice(stem.length + 1))) : undefined;
+    if (kept)
+        return { image_file: path.join(dir, kept) };
+    try {
+        const r = await download(url, TIMEOUT_MS);
+        if (r.status !== 200)
+            return { image_error: `The store answered ${r.status} for ${url}.` };
+        const ext = EXT[r.type.split(';')[0].trim().toLowerCase()];
+        if (!ext)
+            return { image_error: `${url} is not an image (content-type ${r.type || 'missing'}).` };
+        if (r.bytes.length > MAX_BYTES)
+            return { image_error: `${url} is over 10 MB.` };
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${stem}.${ext}`);
+        // Written aside then renamed, so a parallel run never reads half a file.
+        const tmp = `${file}.${process.pid}.part`;
+        fs.writeFileSync(tmp, r.bytes);
+        fs.renameSync(tmp, file);
+        return { image_file: file };
+    }
+    catch (e) {
+        const err = e;
+        return { image_error: err.name === 'TimeoutError' ? `${url} took more than ${TIMEOUT_MS / 1000} s.` : `Could not download ${url}: ${err.message}` };
+    }
+}
+/** Products with image_file or image_error, the first MAX_IMAGES in parallel; how many were left out. */
+export async function withImages(origin, products) {
+    const dir = imagesDir(origin);
+    const got = await Promise.all(products.slice(0, MAX_IMAGES).map((p) => fetchImage(dir, p)));
+    return { products: products.map((p, i) => (i < MAX_IMAGES ? { ...p, ...got[i] } : p)), skipped: Math.max(0, products.length - MAX_IMAGES) };
+}

package/dist/ucp/shop.js

@@ -128,6 +128,7 @@ export function checkoutView(ck, origin, call) {
             id: l.id,
             item_id: l.item?.id,
             title: l.item?.title,
+            image_url: l.item?.image_url,
             quantity: l.quantity,
             unit_price: l.item?.price === undefined ? undefined : money(l.item.price, cur),
             total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),
@@ -160,6 +161,7 @@ export function orderView(o, origin, call) {
         line_items: (o.line_items ?? []).map((l) => ({
             item_id: l.item?.id,
             title: l.item?.title,
+            image_url: l.item?.image_url,
             quantity: l.quantity?.total ?? l.quantity,
             status: l.status,
             total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [
@@ -31,6 +31,8 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "imapflow": "^2.10.2",
+    "postal-mime": "^4.2.0",
     "yaml": "^2.6.0"
   },
   "devDependencies": {