@commercelayer/agent-cli 0.5.1 → 0.5.2

package/README.md

@@ -35,7 +35,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `fulfillment list [--status <status>\|all] [--limit <n>]` · `show <shipment>` | The shipments, by default the ones not shipped yet. A shipment is its number (`1001/S/001`), its id, or its order's number. |
 | `fulfillment hold` · `pick` · `pack` · `ready` · `ship <shipment> [--carrier] [--tracking] [--tracking-url]` · `deliver` | Move a shipment; each prints the shipment after it. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
-| `ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country <CC>]` · `ucp product <id>` | Buy for the human, step by step (see [Buying for the human](#buying-for-the-human)): the store's products with their categories, prices in major units in `price.display`, sale prices, shipping and the market the prices are for. |
+| `ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country <CC>] [--images]` · `ucp product <id> [--images]` | Buy for the human, step by step (see [Buying for the human](#buying-for-the-human)): the store's products with their categories, prices in major units in `price.display`, sale prices, shipping and the market the prices are for. |
 | `ucp checkout create --item <variant id>[:<qty>] … [--code <discount>] [--country <CC>]` | Open a checkout; `messages` say what is still missing (email, shipping address). |
 | `ucp checkout update <id> [--email …] [--street …] [--item <variant id>:<qty>] [--code …] [--shipping <option>]` | Give the buyer's details (flags, or YAML or JSON on stdin or `-f`), change items or codes; `ready_for_complete` once nothing is missing, with shipping in the total. |
 | `ucp checkout show <id>` · `cancel <id>` · `complete <id> [--decline]` | Read, cancel, or pay a checkout with the sandbox handler (after the human said yes): `order` has `label` and `permalink_url`. |
@@ -160,9 +160,9 @@ A custom storefront replaces the theme: `storefront.path` in `store.yml` names i
 Error codes: `invalid_theme`, `invalid_storefront`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `invalid_link`, `link_exists`, `link_not_managed` (reserved), `links_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## Orders and fulfillment
 
-Orders land **placed** with the payment **authorized**, not taken: the store no longer approves or captures them. The merchant, through the agent, accepts an order with `orders approve <n> --capture` (or approves now and runs `orders capture <n>` later), cancels one it doesn't want (`orders cancel`, which voids the authorization; a shipped order can't be cancelled, a captured one is refunded instead), and gives money back with `orders refund <n> [--amount <major units>]` (the last of it cancels the order). `orders archive` hides an order from the list, whatever its status; `orders list --archived` shows them. Every command prints the order after it and a `next` that says what it waits for; a move the order doesn't allow answers `invalid_transition`, with the commands it allows now in the hint.
+Orders land **placed** with the payment **authorized**, not taken: the store no longer approves or captures them. The merchant, through the agent, accepts an order with `orders approve <n> --capture` (or approves now and runs `orders capture <n>` later; Commerce Layer also captures a placed order), cancels one it doesn't want before it ships (`orders cancel`, which voids an authorization or refunds a captured payment; a shipped order is refunded, not cancelled), and gives money back with `orders refund <n> [--amount <major units>]` (the last of it cancels the order). `orders archive` hides an order from the list, whatever its status; `orders list --archived` shows them. Every command prints the order after it and a `next` that says what it waits for; a move the order doesn't allow answers `invalid_transition`, with the commands it allows now in the hint.
 
-Each order has one shipment, `upcoming` when placed. `fulfillment hold` works on a placed order; `pick`, `pack`, `ready` and `ship` need the order approved, and `on_hold`, `picking`, `packing` and `ready_to_ship` move freely between each other. `ship` takes the carrier's `--carrier`, `--tracking` and `--tracking-url` (https); `deliver` follows `ship`. An API older than these routes answers `orders_unsupported` or `fulfillment_unsupported`.
+Each order has one shipment, `upcoming` when placed. `fulfillment hold` works on a placed order; `pick`, `pack`, `ready` and `ship` need the order approved, and `on_hold`, `picking`, `packing` and `ready_to_ship` move freely between each other and on to `shipped`. An `upcoming` shipment goes only to `hold` or `pick`, as Commerce Layer refuses to ship it straight away. `ship` takes the carrier's `--carrier`, `--tracking` and `--tracking-url` (https); `deliver` follows `ship`. An API older than these routes answers `orders_unsupported` or `fulfillment_unsupported`.
 
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
@@ -182,6 +182,8 @@ The CLI is a UCP **platform**: its profile is served at `https://commercelayer.a
 
 An agent can buy from any UCP store on behalf of its human, one step per command, talking to the human in between: `ucp search` to show the products (words in any order; `--category`, which includes the subcategories, and `--min-price`/`--max-price` in major units narrow it; the `messages` the store sends, such as its categories when nothing matched, are passed on), `ucp checkout create --item <variant id>:<qty>` for what they picked (the `variants[].id` search lists; the sku on Commerce Layer stores), `ucp checkout update <id>` with the email and shipping address they give (never invented), then, once they said yes to the total, `ucp checkout complete <id>`, and the order's `label` and `permalink_url` back to them. Money comes as `{ amount, currency, major, display }`: `amount` in minor units as UCP has it, `display` for the human. The store is `--store <hostname or origin>`, or this folder's store when there is one; checkout and order ids are remembered with their store (in `~/.local/state/c11r/ucp.json`), so later steps need no `--store`. Paying needs the store's sandbox handler (`ai.commercelayer.sandbox`, test payments only): any store without it (every store taking real payments) answers `payment_handler_unsupported`, and the human pays at the checkout's `continue_url`. Responses are signature-checked like `orders test`: `signature` is `verified`, `invalid`, `unknown_key` or `unsigned`.
 
+`--images` is for agents that can read image files and want to look at or describe a product: it saves each product's `image_url` under `<tmpdir>/c11r/images/<store host>/` (the first 24, in parallel, 5 s each, a file already there reused) and adds `image_file`, the absolute path, or `image_error`. Showing a thumbnail in a chat needs only `image_url`, which checkout and order line items carry too.
+
 ## Requirements
 
 Node 20 or later. One runtime dependency (`yaml`).

package/dist/api/stub/index.js

@@ -44,7 +44,7 @@ function outdated(req, res) {
     const current = req.headers['user-agent']?.match(/^c11r\/(\d+\.\d+\.\d+)/)?.[1];
     if (!latest || !current || !older(current, latest) || !res.body)
         return res;
-    const body = JSON.parse(res.body);
+    const body = JSON.parse(res.body.toString());
     if (!body || typeof body !== 'object' || Array.isArray(body))
         return res;
     const warning = { code: 'cli_outdated', current, latest, hint: `Run the commands with npx -y @commercelayer/agent-cli@latest. If c11r is installed globally, tell the human it is on ${current} and ${latest} exists.` };

package/dist/api/stub/orders.js

@@ -4,7 +4,8 @@
 //
 // An order lands placed with its payment authorized. approve (optionally with
 // capture), capture, cancel, refund, archive and unarchive move it; its one shipment
-// goes upcoming → on_hold | picking | packing | ready_to_ship → shipped → delivered.
+// goes upcoming → on_hold | picking → packing → ready_to_ship → shipped → delivered; as in
+// Commerce Layer, an upcoming shipment ships only once it is picking (or past it).
 import { money } from '../../ucp/shop.js';
 import { minorUnits } from '../../ucp/platform.js';
 import { baseLanguage } from './locale.js';
@@ -147,9 +148,9 @@ function orderCommands(o) {
     const out = [];
     if (m.status === 'placed')
         out.push(`c11r orders approve ${n} [--capture]`);
-    if (m.status === 'approved' && pay === 'authorized')
+    if (m.status !== 'cancelled' && pay === 'authorized')
         out.push(`c11r orders capture ${n}`);
-    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status) && ['authorized', 'free'].includes(pay))
+    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status))
         out.push(`c11r orders cancel ${n}`);
     if (['paid', 'partially_refunded'].includes(pay))
         out.push(`c11r orders refund ${n} [--amount <major>]`);
@@ -206,8 +207,9 @@ export function orderAction(r, id, action, body) {
                 capture();
             break;
         case 'capture':
-            if (m.status !== 'approved' || paymentStatus(o) !== 'authorized')
-                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an approved order with an authorized payment can be captured.`, orderCommands(o));
+            // As in Commerce Layer: a placed order can be captured before it is approved.
+            if (m.status === 'cancelled' || paymentStatus(o) !== 'authorized')
+                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an authorized payment can be captured.`, orderCommands(o));
             capture();
             break;
         case 'cancel':
@@ -215,10 +217,12 @@ export function orderAction(r, id, action, body) {
                 refuse(`Order ${number(o)} is already cancelled.`, orderCommands(o));
             if (['shipped', 'delivered'].includes(m.shipment.status))
                 refuse(`Order ${number(o)} has shipped: it cannot be cancelled.`, orderCommands(o));
-            if (!['authorized', 'free'].includes(paymentStatus(o)))
-                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: refund it to cancel it.`, orderCommands(o));
+            // Commerce Layer voids an authorized payment and refunds a captured one.
             if (paymentStatus(o) === 'authorized')
                 m.transactions.push({ type: 'void', amount: total(o), succeeded: true, at });
+            const left = sum(o, 'capture') - sum(o, 'refund');
+            if (left > 0)
+                m.transactions.push({ type: 'refund', amount: left, succeeded: true, at });
             m.status = 'cancelled';
             m.shipment.status = 'cancelled';
             break;
@@ -286,7 +290,7 @@ function shipmentCommands(o) {
     can('pick', approved && ['upcoming', 'on_hold', 'packing', 'ready_to_ship'].includes(s.status));
     can('pack', approved && ['on_hold', 'picking', 'ready_to_ship'].includes(s.status));
     can('ready', approved && ['on_hold', 'picking', 'packing'].includes(s.status));
-    can('ship', approved && OPEN_SHIPMENTS.includes(s.status));
+    can('ship', approved && WORKING.includes(s.status));
     can('deliver', s.status === 'shipped');
     if (!out.length && merchant(o).status === 'placed')
         out.push(`c11r orders approve ${number(o)} [--capture]`);
@@ -346,7 +350,7 @@ export function shipmentAction(r, id, action, body) {
             }
             if (body?.tracking_url !== undefined && !URL_RE.test(body.tracking_url))
                 throw new OrderError(422, 'invalid_argument', `tracking_url ${body.tracking_url} is not an https URL.`, 'Give --tracking-url the carrier\'s tracking page, starting with https://.');
-            move('shipped', OPEN_SHIPMENTS, true);
+            move('shipped', WORKING, true);
             if (body?.carrier || body?.tracking || body?.tracking_url)
                 s.tracking = { carrier: body.carrier, number: body.tracking, url: body.tracking_url };
             return showShipment(r, s.id);

package/dist/api/stub/theme.js

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

package/dist/api/stub/ucp.js

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

package/dist/api/transport.js

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

package/dist/bin.js

@@ -114,9 +114,9 @@ async function run() {
             if (sub === 'check')
                 return cmd.ucpCheck();
             if (sub === 'search')
-                return cmd.ucpSearch(args.slice(2).join(' '), values, lists);
+                return cmd.ucpSearch(args.slice(2).join(' '), values, lists, flags);
             if (sub === 'product')
-                return cmd.ucpProduct(args[2], values);
+                return cmd.ucpProduct(args[2], values, flags);
             if (sub === 'order')
                 return cmd.ucpOrder(args[2], values);
             if (sub === 'ask')

package/dist/commands.js

@@ -16,6 +16,7 @@ import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
+import { MAX_IMAGES, withImages } from './ucp/images.js';
 import * as shop from './ucp/shop.js';
 import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 import { LATEST_HINT, VERSION } from './version.js';
@@ -45,8 +46,8 @@ export const HELP = {
     '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 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 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 approved order, once the human said to: c11r orders capture <number>. Returns { status, order, next }; invalid_transition when it is not approved or already captured.',
-    'orders cancel': "Cancel an order the human does not want, before it ships: c11r orders cancel <number>. An authorized payment is voided. A shipped order cannot be cancelled, and a captured one is refunded instead (orders refund): both answer invalid_transition, with what is allowed in the hint. Returns { status, order, next }.",
+    '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 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.',
@@ -56,18 +57,18 @@ export const HELP = {
     'fulfillment pick': 'Mark a shipment as being picked: c11r fulfillment pick <shipment>. Needs the order approved. on_hold, picking, packing and ready_to_ship move freely between each other. Returns { status, shipment, next }; invalid_transition says what is allowed now.',
     'fulfillment pack': 'Mark a shipment as being packed: c11r fulfillment pack <shipment>. Needs the order approved. Returns { status, shipment, next }.',
     '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; works from upcoming or any step before. Ask the human for the tracking, never invent it. 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 }.',
     '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] [--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.",
-    'ucp product': 'Look at one product over UCP, with every variant and the full description: c11r ucp product <product id> [--country CC] [--store <host>]. Returns { store, product: { id, title, description, url, image_url, variants: [...] }, signature }, variants as in ucp search.',
-    'ucp checkout create': "Buy for the human, step 2: open a checkout with the items the human picked. c11r ucp checkout create --item <variant id>[:<qty>] [--item ...] [--code <discount>] [--country CC] [--store <host>]. Returns the checkout: { id, status, store, currency, line_items: [{ id, item_id, title, quantity, unit_price, total }], buyer, ship_to, shipping, discounts, codes, totals: [{ type, label, amount, major, display }], total, messages, continue_url, expires_at, links, signature }. status is incomplete until the buyer's email and shipping address are given: messages say what is missing. Ask the human for them, never invent them, then c11r ucp checkout update <id>. The id is remembered with its store: later steps need no --store.",
+    '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.",
+    'ucp product': "Look at one product over UCP, with every variant and the full description: c11r ucp product <product id> [--country CC] [--images] [--store <host>]. Returns { store, product: { id, title, description, url, image_url, variants: [...] }, signature }, variants as in ucp search. --images is for agents that can read image files and want to look at or describe a product: it saves the product's image 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.",
+    'ucp checkout create': "Buy for the human, step 2: open a checkout with the items the human picked. c11r ucp checkout create --item <variant id>[:<qty>] [--item ...] [--code <discount>] [--country CC] [--store <host>]. Returns the checkout: { id, status, store, currency, line_items: [{ id, item_id, title, image_url, quantity, unit_price, total }], buyer, ship_to, shipping, discounts, codes, totals: [{ type, label, amount, major, display }], total, messages, continue_url, expires_at, links, signature }. status is incomplete until the buyer's email and shipping address are given: messages say what is missing. Ask the human for them, never invent them, then c11r ucp checkout update <id>. The id is remembered with its store: later steps need no --store.",
     'ucp checkout update': "Buy for the human, step 3: give the buyer's details, change items or codes. c11r ucp checkout update <id> [--email --first-name --last-name --phone] [--street --city --postal-code --region --country] [--item <variant id>:<qty> (0 removes)] [--code <discount> (adds)] [--shipping <option id>]; or the same as YAML or JSON on stdin or -f <file>: { buyer: { email, first_name, last_name, phone_number }, address: { street_address, address_locality, postal_code, address_region, address_country }, items: [\"ID:2\"], codes: [...] (replaces), shipping }. Only what is given changes. Returns the checkout as in create: status ready_for_complete once nothing is missing, with shipping and the total including it; or incomplete with messages (address_undeliverable says where the store ships). Show the human the line items, shipping and total.display, ask for an explicit yes, then c11r ucp checkout complete <id>.",
     'ucp checkout show': 'Show a checkout as the store has it now: c11r ucp checkout show <id> [--store <host>]. Returns the checkout as in ucp checkout create.',
     'ucp checkout cancel': 'Cancel a checkout the human no longer wants: c11r ucp checkout cancel <id> [--store <host>]. Returns the checkout, status canceled.',
     'ucp checkout complete': "Buy for the human, step 4, only after the human said yes to the total: pay the checkout. c11r ucp checkout complete <id> [--decline] [--store <host>]. Pays with the ai.commercelayer.sandbox test handler (no money moves): only stores that advertise it can be paid; --decline uses the declined test card. Returns the checkout with status completed and order: { id, label, permalink_url }, plus payment_handler. Tell the human the order label and give them permalink_url. A store without that handler (any store taking real payments) answers payment_handler_unsupported: give the human continue_url to pay there. A declined payment leaves status ready_for_complete with a payment_failed message.",
-    'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ item_id, title, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
+    'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ item_id, title, image_url, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
     'ucp ask': 'Ask a store a question in plain language over UCP (shipping, returns, what it sells): c11r ucp ask "<question>" [--store <host>]. Returns { store, question, answer, links, messages, signature }. The answer is the store\'s: quote it, do not embellish it. Ask only answers; buy with ucp checkout.',
     status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists). search is the store\'s semantic search index: { model, status: indexing|ready|failed|too_large, vectors, embedded, updated_at, error }, or null before it first runs; until it is ready the store\'s search matches words only.',
     claim: 'Start keeping this sandbox store: returns a URL and a code for the human to approve in the browser.',
@@ -304,7 +305,7 @@ export async function ordersTest(flags, values) {
         messages: p.checkout.messages ?? p.ready.messages,
         payment_handler: 'ai.commercelayer.sandbox (test payments only)',
         steps: p.steps,
-        next: p.checkout.status === 'completed' ? `Placed, payment authorized: approve and capture it with c11r orders approve ${String(p.order?.label ?? p.order?.id).replace(/^#/, '')} --capture, then ship it with c11r fulfillment ship.` : undefined,
+        next: p.checkout.status === 'completed' ? `Placed, payment authorized: approve and capture it with c11r orders approve ${String(p.order?.label ?? p.order?.id).replace(/^#/, '')} --capture, then ship it with c11r fulfillment pick and ship.` : undefined,
     };
 }
 // Orders and shipments, live in Commerce Layer through the API. An order lands placed with its
@@ -322,13 +323,15 @@ function orderNext(o) {
     const shipment = o.shipments?.[0];
     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')
+        return `Order ${n} is placed; its payment is ${o.payment_status?.replace(/_/g, ' ')} (taken before approving). When the human accepts it, approve it: c11r orders approve ${n}. If they don't want it: c11r orders cancel ${n} (Commerce Layer refunds what was taken).`;
     if (o.status === 'placed')
         return `Order ${n} is placed and its payment is authorized, not taken. When the human accepts it, approve it and take the payment: c11r orders approve ${n} --capture (without --capture to take it later). If they don't want it: c11r orders cancel ${n}.`;
     if (o.payment_status === 'authorized')
         return `Order ${n} is approved; the payment is authorized but not taken. Take it when the human says so: c11r orders capture ${n}.`;
     if (o.fulfillment_status === 'fulfilled')
         return `Order ${n} has shipped${shipment?.tracking?.number ? ` (tracking ${shipment.tracking.number})` : ''}. Mark it delivered when it arrives: c11r fulfillment deliver ${shipment?.number ?? n}; refund all or part if the human asks: c11r orders refund ${n} [--amount <n>].`;
-    return `Order ${n} is approved and paid (${o.total?.display}). Ship it: c11r fulfillment ship ${shipment?.number ?? n} [--carrier <name> --tracking <number> --tracking-url <url>], or move it through picking and packing first (c11r fulfillment pick, pack, ready).`;
+    return `Order ${n} is approved and paid (${o.total?.display}). Pick it, then ship it: c11r fulfillment pick ${shipment?.number ?? n}, then c11r fulfillment ship ${shipment?.number ?? n} [--carrier <name> --tracking <number> --tracking-url <url>] (pack and ready in between if the human tracks them).`;
 }
 export async function ordersList(values, flags) {
     const api = createApi(requireCredentials());
@@ -377,6 +380,8 @@ function shipmentNext(s) {
         return `Shipment ${n} is on its way${s.tracking?.number ? ` (tracking ${s.tracking.number})` : ''}. Mark it delivered when it arrives: c11r fulfillment deliver ${n}.`;
     if (s.order?.status === 'placed')
         return `Shipment ${n} waits for its order ${s.order.number} to be approved: c11r orders approve ${s.order.number} --capture, once the human accepts it. It can be held meanwhile: c11r fulfillment hold ${n}.`;
+    if (s.status === 'upcoming')
+        return `Shipment ${n} is upcoming. Pick it first: c11r fulfillment pick ${n}; then ship it when it leaves: c11r fulfillment ship ${n} [--carrier <name> --tracking <number> --tracking-url <url>].`;
     return `Shipment ${n} is ${s.status.replace(/_/g, ' ')}. Ship it when it leaves: c11r fulfillment ship ${n} [--carrier <name> --tracking <number> --tracking-url <url>]; or move it on: c11r fulfillment pick, pack, ready or hold ${n}.`;
 }
 export async function fulfillmentList(values) {
@@ -510,7 +515,14 @@ const checkoutNext = (ck) => {
     const errors = (ck.messages ?? []).filter((m) => m.type === 'error').map((m) => m.content);
     return `Still needed: ${errors.join(' ') || 'see messages'} Ask the human (never invent buyer details), then run c11r ucp checkout update ${ck.id} with what they said.`;
 };
-export async function ucpSearch(query, values, lists = {}) {
+/** --images: each product's image saved to a file (image_file, or image_error), at most MAX_IMAGES. */
+async function addImages(r, list) {
+    const { products, skipped } = await withImages(r.store, list);
+    return skipped
+        ? { products, warnings: [{ code: 'images_capped', message: `Images were saved for the first ${MAX_IMAGES} products only; ${skipped} more have none.`, hint: 'Narrow the search (words, --category, prices) to get the images of the others.' }] }
+        : { products };
+}
+export async function ucpSearch(query, values, lists = {}, flags = new Set()) {
     const price = (flag) => {
         const raw = values[flag];
         if (raw === undefined)
@@ -528,12 +540,16 @@ export async function ucpSearch(query, values, lists = {}) {
     const next = r.count
         ? 'Show the human the products (title, categories, price.display, and list_price.display when it is on sale), let them pick, then c11r ucp checkout create --item <variant id>[:<qty>] (variants[].id).'
         : 'Nothing matched: read messages (the store may list its categories there), then try other words, a --category, wider prices, or no query for the whole catalog.';
-    return { ...r, next };
+    return flags.has('--images') ? { ...r, ...(await addImages(r, r.products)), next } : { ...r, next };
 }
-export async function ucpProduct(id, values) {
+export async function ucpProduct(id, values, flags = new Set()) {
     if (!id)
         fail('missing_argument', 'ucp product needs a product id.', 'Use a product id from c11r ucp search.');
-    return shop.product(await shopOrigin(values), id, values.country);
+    const r = await shop.product(await shopOrigin(values), id, values.country);
+    if (!flags.has('--images'))
+        return r;
+    const [product] = (await withImages(r.store, [r.product])).products;
+    return { ...r, product };
 }
 export async function ucpCheckoutCreate(values, lists) {
     const items = (lists.item ?? []).map(shop.parseItem);

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.5.2",
   "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": [