@commercelayer/agent-cli 0.8.1 → 1.0.0-dev.0

package/dist/commands.js

@@ -1,1241 +0,0 @@
-// One function per command. Each returns the object the CLI prints, or throws a
-// CliError. Every command is safe to re-run.
-import fs from 'node:fs';
-import path from 'node:path';
-import { createApi } from './api/client.js';
-import { ignoreCredentials, paths, readCredentials, requireCredentials, writeAgentNotes, writeCredentials } from './files.js';
-import { CliError, fail, progress } from './output.js';
-import { diff, hashStore, languageWarnings, loadStore, storefrontMode, storefrontPath, template, toApplied } from './store.js';
-import { storefrontFiles } from './storefront.js';
-import { imageNotes, planAssets, uploadAssets } from './assets.js';
-import { pull } from './catalog.js';
-import { inspect } from './inspect.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';
-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';
-export { VERSION } from './version.js';
-export const HELP = {
-    init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials, and a section in AGENTS.md and CLAUDE.md (created, or appended once) that points later agents in this repo to the skills: commit them. Reuses the store if store.yml already exists.',
-    plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, language, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku). Products may carry other languages: name, description and category as { <ll>: text } maps (the base language, store.yml language:, default en, among them), or name_<ll>, description_<ll>, category_<ll> CSV columns; at most 6 languages. warnings lists a language no country of the store speaks.',
-    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, the storefront mode (storefront.mode: hosted, the default, or agent-only: UCP and the pages it needs, no catalog pages), the theme (its settings, badge included, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
-    'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant | website, url, table, limit }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category, name_<ll>, description_<ll> and category_<ll> for other languages (name_it), and one price column per market currency, in lowercase (eur, usd). A Merchant feed adds other languages with catalog.translations: { it: <feed url> }, merged by id. Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV. source website reads a brand\'s site for a demo store (url: the site, limit: default 100, at most 500): Shopify products.json, then the WooCommerce Store API, then the sitemap\'s product pages and their JSON-LD, first that yields products wins (strategy). One row per product, first available variant (variants_skipped counts the others); prices in the site\'s currency, never converted: currency_mismatch when the markets sell in another, currency_unknown when the site does not say (ask the human, then --currency <code>). It honours robots.txt (robots_skipped), reads one request at a time, at most 2 a second, 60 s in all (budget_exhausted). Images stay on the brand\'s servers: image_url links them, nothing is copied. Prints strategy, source_site { url, title, platform, product_count_seen, currency, languages }, pulled, categories and the skipped counts: tell the human how many products the site has and how many were pulled. no_products_found: ask the human for a feed or a sheet instead.',
-    'storefront init': 'Custom storefronts only: the hosted theme needs none of this (set theme: in store.yml and apply). Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js. Product images are the store\'s, at /img/ (.commercelayer/img/, uploaded by apply); the site\'s own files go in storefront/assets/. Refuses to overwrite unless --force is given.',
-    'storefront check': 'Custom storefronts only. Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
-    'storefront inspect': "Read a brand's website for a demo store that looks like it, read-only, nothing written: c11r storefront inspect <url>. Returns { url, title, site_name, description, language, languages, theme_color, icons, og_image, og_image_width, og_image_height, og_image_is_logo (true: the og:image is the logo, not a hero photo), logo_candidates: [{ url, source: json_ld|header_img|img|header_svg, alt, width, height }], colors: [{ hex, source: theme_color|css, count, neutral }], currencies_seen, countries_seen, platform: shopify|woocommerce|unknown, robots: { products_allowed, paths } }. Pick theme.color (the first colour that is not neutral, usually) and theme.logo (a logo candidate's url: hot-linked, never downloaded; an inline SVG has url null) and show the human. robots.products_allowed false: catalog pull cannot read the products, ask for a feed or a sheet. Same polite reading as catalog pull (robots.txt, 2 requests a second). Errors: site_unreachable, site_error, robots_disallowed.",
-    'storefront publish': 'Custom storefronts only: upload the storefront folder (store.yml storefront.path, default storefront) to the preview URL, where it replaces the hosted theme.',
-    'promotions list': 'The store\'s promotions, live in Commerce Layer (not in store files): id, name, status (active, scheduled, expired, disabled, used_up), rules, actions, uses, starts, ends; managed: false marks one made in the dashboard (its id is Commerce Layer\'s), which can be enabled, disabled or deleted but not updated. warnings flags more than 10 active promotion actions without a coupon (Commerce Layer applies 10).',
-    'promotions show': 'One promotion by id, as list shows it: c11r promotions show <id>.',
-    'promotions create': "Create a promotion from a spec in YAML or JSON, on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>: { id, name, market, starts, ends, limit, priority, exclusive, enabled, rules: [{ coupon | order_amount: { min } | skus | category }], actions: [{ percentage | fixed_amount | free_shipping | fixed_price | free_gift | buy_x_pay_y }] } or flex: { rules } in place of rules and actions. id is the handle, unique. Amounts are in the market currency, in major units. A category becomes the skus of its products in store.yml now: after adding products to it, run update again. Errors: invalid_promotion (the message starts with the path in the spec), promotion_exists, flex_unavailable (no Rules Engine: nothing is created). Check it with orders test --code.",
-    'promotions update': 'Replace a promotion with a whole spec, same as create, on stdin or -f <file>: c11r promotions update <id>. The id stays the same. What show prints can be edited and sent back. A promotion made in the dashboard (managed: false) cannot be updated: promotion_not_managed; enable, disable and delete work on it.',
-    'promotions enable': 'Turn a promotion on: c11r promotions enable <id>.',
-    'promotions disable': 'Turn a promotion off without deleting it: c11r promotions disable <id>.',
-    'promotions delete': 'Delete a promotion from Commerce Layer: c11r promotions delete <id>. Ask the human first; to pause one, disable it.',
-    'links list': 'The store\'s links, live in Commerce Layer (not in store files): shareable URLs that open a hosted microstore for one sku, a set of skus or a category, or the hosted checkout for an order. For each: id, name, url, status (pending, active, expired, disabled), for (sku | skus | category with its skus | order), markets, starts, ends, params; managed: false marks one made in the dashboard (its id is Commerce Layer\'s).',
-    'links show': 'One link by id, as list shows it: c11r links show <id>.',
-    'links create': "Create a link from a spec in YAML or JSON, on stdin (c11r links create <<'EOF' ... EOF) or with -f <file>: { id, name, for: { sku } | { skus: [...] } | { category: \"A > B\" } | { order: <number> | cart_<id> | chk_<id> }, market (a code or a list; default every market; none for an order), starts (default now), ends (default a month after starts), params }. id is the handle, unique. A category becomes the skus of its products in store.yml now (at most 100 skus). An order link opens the checkout of a draft or pending order: its number, or the id of a UCP cart or checkout. One Commerce Layer link per market: urls has each, url the first market's. A link cannot be changed: delete it and create it again. Errors: invalid_link (the message starts with the path in the spec), link_exists.",
-    'links enable': 'Turn a link on: c11r links enable <id>.',
-    '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 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 }. 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.',
-    'fulfillment list': "The store's shipments, live in Commerce Layer, newest first: by default the ones not shipped yet (upcoming, on_hold, picking, packing, ready_to_ship). c11r fulfillment list [--status upcoming|on_hold|picking|packing|ready_to_ship|shipped|delivered|cancelled|all] [--limit 1-100]. Returns { count, shipments: [{ id, number (1001/S/001), status, order: { id, number, status }, country, shipping_method, items, tracking: { carrier, number, url } | null, dates }], next }.",
-    'fulfillment show': 'One shipment, with what goes in it and where: c11r fulfillment show <shipment number or id, or the order number when it has one shipment>. Returns { shipment: { ...as in fulfillment list, line_items: [{ sku, name, quantity }], address, parcels }, next }.',
-    'fulfillment hold': 'Put a shipment on hold, for an order the human wants to wait on: c11r fulfillment hold <shipment>. Works on a placed order too. Returns { status, shipment, next }.',
-    '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 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.",
-    '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, 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.',
-    help: 'Describe the commands. `c11r help <command>` for one command, `c11r help <group>` (catalog, fulfillment, links, orders, promotions, storefront, ucp) for a group.',
-};
-export function help(name) {
-    if (name && !HELP[name]) {
-        // A group (catalog, fulfillment, links, orders, promotions, storefront, ucp): its commands.
-        const group = Object.entries(HELP).filter(([k]) => k.startsWith(`${name} `));
-        if (group.length)
-            return { group: name, commands: Object.fromEntries(group) };
-    }
-    if (name) {
-        if (!HELP[name])
-            fail('unknown_command', `There is no command "${name}".`, `Commands: ${Object.keys(HELP).join(', ')}.`);
-        const showsFormat = name === 'apply' || name === 'plan';
-        return { command: name, description: HELP[name], store_format: showsFormat ? template('<name>') : undefined };
-    }
-    return { version: VERSION, latest_hint: LATEST_HINT, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
-}
-export async function init(values) {
-    const existing = readCredentials();
-    if (existing && fs.existsSync(paths.store)) {
-        const s = await createApi(existing).getStore();
-        const notes = writeAgentNotes();
-        return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url, files: notes.length ? notes : undefined };
-    }
-    // The business name becomes the organization's name; the platform derives the
-    // org slug (and so the store hostname) from it. The folder name is the fallback.
-    if (values.name !== undefined && !values.name.trim())
-        fail('invalid_argument', '--name needs the business name.', 'Example: c11r init --name "The Blue Brand". Leave it out to use the folder name.');
-    const name = values.name?.trim() || path.basename(process.cwd());
-    const sandbox = await createApi(null).createSandbox(name);
-    fs.mkdirSync(paths.dir, { recursive: true });
-    if (!fs.existsSync(paths.store))
-        fs.writeFileSync(paths.store, template(name));
-    writeCredentials({ org: sandbox.org, token: sandbox.token });
-    const files = [paths.store, paths.credentials];
-    if (ignoreCredentials())
-        files.push('.gitignore');
-    files.push(...writeAgentNotes());
-    return {
-        status: 'created',
-        org: sandbox.org,
-        name,
-        claim_url: sandbox.claim_url,
-        expires_at: sandbox.expires_at,
-        preview_url: sandbox.preview_url,
-        files,
-        next: 'Describe the store in .commercelayer/store.yml (products there or in .commercelayer/products/*.yml|csv, the theme under theme:, images in .commercelayer/img/), then run c11r plan and c11r apply: the website is live at preview_url.',
-    };
-}
-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];
-    return {
-        status: changes.length ? 'changes' : 'up_to_date',
-        changes,
-        deletes: changes.filter((c) => c.action === 'delete' && c.type !== 'asset').length,
-        ...imageNotes(assets),
-        warnings: languageWarnings(desired).length ? languageWarnings(desired) : undefined,
-        next: assets.missing.length ? 'Put the missing images in .commercelayer/img/ (img/<file> in store.yml is .commercelayer/img/<file>), or fix the references: apply refuses until they are there.' : undefined,
-    };
-}
-/** How often apply reads a running import, and when it stops waiting. Env overrides are for tests. */
-const POLL_MS = Number(process.env.C11R_APPLY_POLL_MS) || 2000;
-const WAIT_MS = Number(process.env.C11R_APPLY_WAIT_MS) || 10 * 60 * 1000;
-/** Errors that say nothing about the import itself: apply keeps polling through them. */
-const TRANSIENT = new Set(['commercelayer_busy', 'commercelayer_unavailable', 'api_error', 'api_unreachable']);
-/** The longest wait between reads while Commerce Layer answers busy (429). */
-const MAX_BACKOFF_MS = 30_000;
-const jobSummary = (j) => ({ id: j.id, status: j.status, step: j.step, processed: j.processed, total: j.total });
-/** Read the store until its apply job is no longer in progress, with a progress line per change. */
-async function follow(api, state) {
-    const until = Date.now() + WAIT_MS;
-    let s = state;
-    let last = '';
-    let wait = POLL_MS;
-    while (s.apply?.status === 'in_progress') {
-        const line = JSON.stringify(jobSummary(s.apply));
-        if (line !== last)
-            progress({ apply: jobSummary(s.apply) });
-        last = line;
-        if (Date.now() >= until) {
-            const j = s.apply;
-            fail('apply_pending', `The apply is still running: ${j.processed} of ${j.total} items done (step ${j.step}).`, 'The apply keeps going; run `c11r status` to follow it.');
-        }
-        await new Promise((r) => setTimeout(r, Math.min(wait, Math.max(0, until - Date.now()))));
-        try {
-            s = await api.getStore();
-            wait = POLL_MS;
-        }
-        catch (e) {
-            // The import runs on regardless: report the error and read again, backing off while Commerce Layer is busy.
-            if (!(e instanceof CliError) || !TRANSIENT.has(e.code))
-                throw e;
-            wait = e.code === 'commercelayer_busy' ? Math.min(MAX_BACKOFF_MS, wait * 2) : POLL_MS;
-            progress({ retrying: { code: e.code, message: e.message, next_read_ms: wait } });
-        }
-    }
-    return s;
-}
-export async function apply(flags) {
-    const api = createApi(requireCredentials());
-    const desired = loadStore();
-    // An apply still running is finished first, so the changes are counted from what it installs.
-    let state = await api.getStore();
-    if (state.apply?.status === 'in_progress')
-        state = await follow(api, state);
-    const assets = planAssets(state, desired);
-    const changes = [...diff(state, desired), ...assets.changes];
-    // Images nothing uses any more are dropped without asking: they are copies of files in the repo.
-    const deletes = changes.filter((c) => c.action === 'delete' && c.type !== 'asset');
-    if (deletes.length && !flags.has('--allow-delete')) {
-        fail('deletes_need_approval', `Apply would delete ${deletes.map((d) => `${d.type} ${d.id}`).join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
-    }
-    if (assets.missing.length) {
-        fail('missing_images', `The store references images that are not in .commercelayer/img/: ${assets.missing.join('; ')}.`, 'Put the files there (img/<file> in store.yml is .commercelayer/img/<file>), or fix or remove the references, then apply again.');
-    }
-    // Images first, so the theme and products never point at a file the store host does not have yet.
-    const uploaded = assets.supported ? await uploadAssets(api, assets) : 0;
-    const body = {
-        applied: toApplied(desired),
-        hash: hashStore(),
-        name: desired.name,
-        policies: desired.policies,
-        theme: desired.theme ?? {},
-        storefront_mode: storefrontMode(desired),
-        ...(assets.supported && { assets: assets.keep }),
-        ...(flags.has('--allow-delete') && { allow_delete: true }),
-        ...(flags.has('--full') && { full: true }),
-    };
-    const started = await api.applyStore(body);
-    const job = started.apply?.status === 'in_progress' ? started.apply : null;
-    const done = job ? await follow(api, started) : started;
-    if (job && done.apply?.id === job.id && done.apply.status === 'failed') {
-        const errors = done.apply.errors;
-        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.message)).join('; ');
-        const what = errors.length === 1 ? '1 product was refused' : `${errors.length} products were refused`;
-        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', 'Fix those products in store.yml or the catalog source and run `c11r apply` again; the rest of the store is unchanged.');
-    }
-    return {
-        status: 'applied',
-        changes,
-        preview_url: done.preview_url,
-        markets: desired.markets.length,
-        products: desired.products.length,
-        payment_gateway: 'sandbox (test payments only)',
-        images_uploaded: uploaded || undefined,
-        unused_images: assets.unused.length ? assets.unused : undefined,
-        apply: job && done.apply ? jobSummary(done.apply) : undefined,
-    };
-}
-export async function catalogPull(values) {
-    return pull(values);
-}
-export async function storefrontInspect(url) {
-    return inspect(url);
-}
-export async function storefrontInit(flags) {
-    const api = createApi(requireCredentials());
-    const desired = loadStore();
-    const dir = 'storefront';
-    if (fs.existsSync(dir) && !flags.has('--force')) {
-        fail('storefront_exists', `${dir}/ already exists.`, 'Edit the files in it, or run `c11r storefront init --force` to regenerate them from store.yml (this overwrites your changes).');
-    }
-    const state = await api.getStore();
-    const written = [];
-    for (const [name, content] of Object.entries(storefrontFiles(desired, state.sales_channel_client_id))) {
-        const file = path.join(dir, name);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, content);
-        written.push(file);
-    }
-    return {
-        status: 'created',
-        files: written,
-        markets: desired.markets.map((m) => m.code),
-        products: desired.products.length,
-        next: `Set storefront.path: ${dir} in ${paths.store}, make it the human's (restyle through the tokens at the top of styles.css; each product has a page at #/p/<sku>, built from #product-template in index.html; product images come from .commercelayer/img/ at /img/, and this site's own files go in ${dir}/assets/), then run c11r storefront publish.`,
-    };
-}
-export async function storefrontCheckCmd() {
-    return storefrontCheck(createApi(requireCredentials()));
-}
-export async function storefrontPublish() {
-    const api = createApi(requireCredentials());
-    const dir = storefrontPath();
-    if (!fs.existsSync(path.join(dir, 'index.html'))) {
-        fail('no_storefront', `There is no ${path.join(dir, 'index.html')}.`, 'Run `c11r storefront init` to create one, or set storefront.path in store.yml to the folder that has index.html.');
-    }
-    // Dotfiles (.gitkeep, .DS_Store, .env) and dot folders stay on this machine.
-    const files = fs
-        .readdirSync(dir, { recursive: true, withFileTypes: true })
-        .filter((e) => e.isFile())
-        .map((e) => path.relative(dir, path.join(e.parentPath, e.name)).split(path.sep).join('/'))
-        .filter((rel) => !rel.split('/').some((part) => part.startsWith('.')))
-        .map((rel) => ({ path: rel, content_base64: fs.readFileSync(path.join(dir, rel)).toString('base64') }));
-    // /img/ on the store host is the store's images (.commercelayer/img/, uploaded by apply): files here under img/ are never served.
-    const shadowed = files.filter((f) => f.path.startsWith('img/')).map((f) => f.path);
-    const published = await api.publishStorefront(dir, files);
-    const state = await api.getStore();
-    return {
-        status: 'published',
-        preview_url: state.preview_url,
-        path: dir,
-        files: published.files,
-        published_at: published.published_at,
-        not_served: shadowed.length ? shadowed : undefined,
-        next: shadowed.length ? `/img/ is the store's images, from .commercelayer/img/ (uploaded by apply): move product images there and this site's own files to ${dir}/assets/.` : undefined,
-    };
-}
-/** The store's origin on the web: where it speaks UCP. */
-async function storeOrigin() {
-    const api = createApi(requireCredentials());
-    const s = await api.getStore();
-    if (!s.applied)
-        fail('not_applied', 'The store has nothing applied yet.', 'Run `c11r apply` first.');
-    return s.preview_url;
-}
-export async function ordersTest(flags, values) {
-    const origin = await storeOrigin();
-    const quantity = values.quantity === undefined ? undefined : Number(values.quantity);
-    if (quantity !== undefined && (!Number.isInteger(quantity) || quantity < 1))
-        fail('invalid_argument', '--quantity must be a positive integer.', 'Example: --quantity 2.');
-    const p = await buy(origin, { sku: values.sku, quantity, country: values.country, code: values.code, viaCart: flags.has('--via-cart'), decline: flags.has('--decline') });
-    return {
-        // The store places the order with its payment authorized; the merchant approves and captures it.
-        status: p.checkout.status === 'completed' ? 'placed' : p.checkout.status,
-        order: p.order,
-        // What the promotions took off, in minor units like the totals; a code that applied nothing is in messages.
-        discounts: (p.checkout.discounts ?? p.ready.discounts)?.applied?.length ? (p.checkout.discounts ?? p.ready.discounts).applied : undefined,
-        checkout_id: p.checkout.id,
-        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 pick and ship.` : undefined,
-    };
-}
-// Orders and shipments, live in Commerce Layer through the API. An order lands placed with its
-// payment authorized; the merchant approves, captures, ships. Each answer says what comes next.
-const LIST_LIMIT = (raw) => {
-    if (raw === undefined)
-        return undefined;
-    const n = Number(raw);
-    if (!Number.isInteger(n) || n < 1 || n > 100)
-        fail('invalid_argument', `--limit ${raw} is not a number from 1 to 100.`, 'Example: --limit 50.');
-    return String(n);
-};
-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')
-        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}). 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());
-    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, 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).${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.',
-    };
-}
-export async function ordersShow(id) {
-    if (!id)
-        fail('missing_argument', 'orders show needs an order id or number.', 'Run `c11r orders list` to see the orders, then `c11r orders show <number>`.');
-    const order = await createApi(requireCredentials()).getMerchantOrder(id);
-    return { order, next: orderNext(order) };
-}
-export async function ordersAct(action, id, values, flags) {
-    if (!id)
-        fail('missing_argument', `orders ${action} needs an order id or number.`, `Run \`c11r orders list\` to see the orders, then \`c11r orders ${action} <number>\`.`);
-    const body = {};
-    if (action === 'approve' && flags.has('--capture'))
-        body.capture = true;
-    if (action === 'refund' && values.amount !== undefined) {
-        const amount = Number(values.amount);
-        if (values.amount.trim() === '' || !Number.isFinite(amount) || amount <= 0)
-            fail('invalid_argument', `--amount ${values.amount} is not an amount.`, 'Give it in major units, for example --amount 4.50; leave it out to refund everything still refundable.');
-        body.amount = amount;
-    }
-    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')
-        return `Shipment ${n} is delivered. Nothing more to do.`;
-    if (s.status === 'cancelled')
-        return `Shipment ${n} is cancelled with its order ${s.order?.number}.`;
-    if (s.status === 'shipped')
-        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) {
-    const { shipments } = await createApi(requireCredentials()).listShipments({ status: values.status, limit: LIST_LIMIT(values.limit) });
-    return {
-        count: shipments.length,
-        shipments,
-        next: shipments.length
-            ? 'Show the human the shipments (number, status, order.number, country, items). c11r fulfillment show <number> for the address and items.'
-            : 'No shipments match. Without --status the list has the ones not shipped yet: --status shipped, delivered or all for the others.',
-    };
-}
-export async function fulfillmentShow(id) {
-    if (!id)
-        fail('missing_argument', 'fulfillment show needs a shipment id or number, or an order number.', 'Run `c11r fulfillment list` to see the shipments.');
-    const shipment = await createApi(requireCredentials()).getShipment(id);
-    return { shipment, next: shipmentNext(shipment) };
-}
-export async function fulfillmentAct(action, id, values) {
-    if (!id)
-        fail('missing_argument', `fulfillment ${action} needs a shipment id or number, or an order number.`, 'Run `c11r fulfillment list` to see the shipments.');
-    const body = {};
-    if (action === 'ship') {
-        if (values.carrier !== undefined)
-            body.carrier = values.carrier;
-        if (values.tracking !== undefined)
-            body.tracking = values.tracking;
-        if (values['tracking-url'] !== undefined) {
-            if (!/^https:\/\/\S+$/.test(values['tracking-url']))
-                fail('invalid_argument', `--tracking-url ${values['tracking-url']} is not an https address.`, "Give the carrier's tracking page, starting with https://.");
-            body.tracking_url = values['tracking-url'];
-        }
-    }
-    const shipment = await createApi(requireCredentials()).shipmentAction(id, action, body);
-    return { status: shipment.status, shipment, next: shipmentNext(shipment) };
-}
-export async function ucpProfile(flags) {
-    if (flags.has('--agent'))
-        return { url: AGENT_PROFILE_URL, profile: agentProfile() };
-    const origin = await storeOrigin();
-    const store = await discover(origin);
-    return { url: `${origin}/.well-known/ucp`, profile: store.profile };
-}
-export async function ucpCheck() {
-    const origin = await storeOrigin();
-    const report = await check(origin);
-    return {
-        ...report,
-        note: report.order ? `The checkout checks placed a real test order (${report.order.label ?? report.order.id}) with the sandbox handler, payment authorized; it appears in \`c11r orders list\` like one from \`orders test\`.` : undefined,
-        next: report.status === 'pass' ? 'Any shopping agent can buy from this store.' : 'Fix the failed checks and run `c11r ucp check` again.',
-    };
-}
-export async function status() {
-    const api = createApi(requireCredentials());
-    const s = await api.getStore();
-    // Pending means exactly what plan would list, so the two never disagree. If
-    // the store files do not even load, that is pending too, with the error.
-    let pending = [];
-    let storeError;
-    try {
-        const desired = loadStore();
-        pending = [...diff(s, desired), ...planAssets(s, desired).changes];
-    }
-    catch (e) {
-        if (!(e instanceof CliError))
-            throw e;
-        storeError = { code: e.code, message: e.message, hint: e.hint };
-    }
-    return {
-        org: s.org,
-        sandbox: s.sandbox,
-        claimed: s.claimed,
-        expires_at: s.expires_at,
-        preview_url: s.preview_url,
-        sales_channel_client_id: s.sales_channel_client_id,
-        storefront: s.storefront,
-        applied: Boolean(s.applied),
-        apply: s.apply ?? undefined,
-        pending_changes: pending.length > 0 || storeError !== undefined,
-        pending: pending.length ? pending : undefined,
-        store_error: storeError,
-        markets: s.applied ? Object.keys(s.applied.markets) : [],
-        products: s.applied ? Object.keys(s.applied.products).length : 0,
-        orders: s.orders.map((o) => ({ id: o.id, label: o.label })),
-        // Semantic search: until it is ready, the store's search matches words only.
-        search: s.search ? { model: s.search.model, status: s.search.status, vectors: s.search.vectors, embedded: s.search.embedded, updated_at: s.search.updated_at, error: s.search.error } : null,
-        ucp_profile: `${s.preview_url}/.well-known/ucp`,
-        next: s.apply?.status === 'in_progress' ? 'An apply is running: run `c11r status` again to follow it, or `c11r apply` to wait for it.' : storeError ? 'Fix the store files (see store_error), then run `c11r plan`.' : pending.length ? 'Run `c11r plan` to see the changes, then `c11r apply`.' : undefined,
-    };
-}
-export async function claim() {
-    const api = createApi(requireCredentials());
-    const s = await api.getStore();
-    const started = await api.startClaim();
-    return {
-        status: 'pending',
-        verification_url: started.verification_url,
-        user_code: started.user_code,
-        claim_url: s.claim_url,
-        next: 'Ask the human to open verification_url and enter user_code, then run `c11r status`.',
-    };
-}
-// ---------- ucp: buying for the human, step by step, from this store or any UCP store
-/** The store to buy from: --store, else the one an id was made at, else this folder's. */
-async function shopOrigin(values, id) {
-    if (values.store)
-        return shop.originOf(values.store);
-    const known = id ? shop.remembered(id) : undefined;
-    if (known)
-        return known;
-    if (!readCredentials())
-        fail('no_store', 'There is no store in this folder, and no --store was given.', 'Pass the store to buy from, any store that speaks UCP: --store <hostname or https origin>.');
-    return storeOrigin();
-}
-const needId = (id, command) => {
-    if (!id)
-        fail('missing_argument', `${command} needs a checkout id.`, 'Use the id that c11r ucp checkout create printed (chk_...).');
-    return id;
-};
-const checkoutNext = (ck) => {
-    if (ck.status === 'completed')
-        return `Placed. Tell the human: order ${ck.order?.label ?? ck.order?.id}, and give them ${ck.order?.permalink_url}.`;
-    if (ck.status === 'canceled')
-        return 'Canceled. Open a new one with c11r ucp checkout create --item <variant id> if the human wants to buy.';
-    if (ck.status === 'ready_for_complete') {
-        const declined = (ck.messages ?? []).some((m) => m.code === 'payment_failed');
-        if (declined)
-            return `The payment failed: tell the human. Try again only if they ask: c11r ucp checkout complete ${ck.id}.`;
-        return `Show the human the items, shipping and total (${ck.total?.display}), ask for an explicit yes, then run c11r ucp checkout complete ${ck.id}.`;
-    }
-    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.`;
-};
-/** --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)
-            return undefined;
-        const n = Number(raw);
-        if (raw.trim() === '' || !Number.isFinite(n) || n < 0)
-            fail('invalid_argument', `--${flag} ${raw} is not a price.`, `Give it in major units, for example --${flag} 15 or --${flag} 9.90.`);
-        return n;
-    };
-    const min = price('min-price');
-    const max = price('max-price');
-    if (min !== undefined && max !== undefined && min > max)
-        fail('invalid_argument', `--min-price ${min} is above --max-price ${max}.`, 'Swap them.');
-    const r = await shop.search(await shopOrigin(values), query, { country: values.country, categories: lists.category, min, max });
-    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 flags.has('--images') ? { ...r, ...(await addImages(r, r.products)), next } : { ...r, next };
-}
-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.');
-    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);
-    if (!items.length)
-        fail('missing_argument', 'ucp checkout create needs at least one --item.', 'Example: c11r ucp checkout create --item ETH-250:2, with variant ids from c11r ucp search (variants[].id).');
-    if (items.some((l) => l.quantity < 1))
-        fail('invalid_argument', 'An --item quantity must be 1 or more.', 'Example: --item ETH-250:2.');
-    const ck = await shop.createCheckout(await shopOrigin(values), items, lists.code ?? [], values.country);
-    return { ...ck, next: checkoutNext(ck) };
-}
-const BUYER_FLAGS = { email: 'email', 'first-name': 'first_name', 'last-name': 'last_name', phone: 'phone_number' };
-const ADDRESS_FLAGS = { street: 'street_address', city: 'address_locality', 'postal-code': 'postal_code', region: 'address_region', country: 'address_country' };
-export async function ucpCheckoutUpdate(id, values, lists) {
-    needId(id, 'ucp checkout update');
-    const pick = (map) => {
-        const out = {};
-        for (const [flag, key] of Object.entries(map))
-            if (values[flag] !== undefined)
-                out[key] = values[flag];
-        return Object.keys(out).length ? out : undefined;
-    };
-    const changes = { buyer: pick(BUYER_FLAGS), address: pick(ADDRESS_FLAGS), items: lists.item?.map(shop.parseItem), add_codes: lists.code, shipping: values.shipping };
-    const flagged = Object.values(changes).some((v) => v !== undefined);
-    if (!flagged || values.file) {
-        // No flags: the changes as YAML or JSON on stdin or -f.
-        const raw = await readText(values, 'checkout update', `Give the changes as flags (--email ..., --street ...) or as YAML or JSON on stdin or -f <file>: { buyer: {...}, address: {...}, items, codes, shipping }.`);
-        const bad = (msg) => fail('invalid_argument', `checkout update: ${msg}`, 'The input is { buyer: { email, first_name, last_name, phone_number }, address: { street_address, address_locality, postal_code, address_region, address_country }, items: ["ID:2"], codes: [...], shipping }.');
-        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-            bad('the input is not a map.');
-        const r = raw;
-        for (const k of Object.keys(r))
-            if (!['buyer', 'address', 'items', 'codes', 'shipping'].includes(k))
-                bad(`unknown key ${k}.`);
-        const map = (o, keys, what) => {
-            if (o === undefined)
-                return undefined;
-            if (!o || typeof o !== 'object' || Array.isArray(o))
-                bad(`${what} is not a map.`);
-            for (const [k, v] of Object.entries(o))
-                if (!keys.includes(k) || typeof v !== 'string')
-                    bad(`${what}.${k} is not one of ${keys.join(', ')} with a text value.`);
-            return o;
-        };
-        if (r.buyer !== undefined)
-            changes.buyer = { ...map(r.buyer, Object.values(BUYER_FLAGS), 'buyer'), ...changes.buyer };
-        if (r.address !== undefined)
-            changes.address = { ...map(r.address, ['first_name', 'last_name', 'extended_address', ...Object.values(ADDRESS_FLAGS)], 'address'), ...changes.address };
-        if (r.items !== undefined) {
-            if (!Array.isArray(r.items))
-                bad('items is not a list.');
-            changes.items = [...r.items.map((x) => (typeof x === 'string' ? shop.parseItem(x) : x && typeof x === 'object' && typeof x.id === 'string' && Number.isInteger(x.quantity) ? { id: x.id, quantity: x.quantity } : bad('items holds "ID:QTY" or { id, quantity }, with variant ids.'))), ...(changes.items ?? [])];
-        }
-        if (r.codes !== undefined) {
-            if (!Array.isArray(r.codes) || r.codes.some((c) => typeof c !== 'string'))
-                bad('codes is not a list of codes.');
-            changes.codes = [...r.codes, ...(changes.add_codes ?? [])];
-        }
-        if (r.shipping !== undefined)
-            changes.shipping = changes.shipping ?? String(r.shipping);
-    }
-    if (changes.items?.some((l) => !Number.isInteger(l.quantity) || l.quantity < 0))
-        fail('invalid_argument', 'An item quantity must be 0 (remove it) or more.', 'Example: --item ETH-250:2.');
-    const ck = await shop.updateCheckout(await shopOrigin(values, id), id, changes);
-    return { ...ck, next: checkoutNext(ck) };
-}
-export async function ucpCheckoutShow(id, values) {
-    const ck = await shop.getCheckout(await shopOrigin(values, needId(id, 'ucp checkout show')), id);
-    return { ...ck, next: checkoutNext(ck) };
-}
-export async function ucpCheckoutCancel(id, values) {
-    const ck = await shop.cancelCheckout(await shopOrigin(values, needId(id, 'ucp checkout cancel')), id);
-    return { ...ck, next: checkoutNext(ck) };
-}
-export async function ucpCheckoutComplete(id, values, flags) {
-    const ck = await shop.completeCheckout(await shopOrigin(values, needId(id, 'ucp checkout complete')), id, flags.has('--decline'));
-    return { ...ck, payment_handler: 'ai.commercelayer.sandbox (test payments only)', next: checkoutNext(ck) };
-}
-export async function ucpOrder(id, values) {
-    if (!id)
-        fail('missing_argument', 'ucp order needs an order id.', 'Use order.id from c11r ucp checkout complete.');
-    const o = await shop.getOrder(await shopOrigin(values, id), id);
-    return { ...o, next: `Tell the human: order ${o.label}, details at ${o.permalink_url}.` };
-}
-export async function ucpAsk(question, values) {
-    if (!question.trim())
-        fail('missing_argument', 'ucp ask needs a question.', 'Example: c11r ucp ask "Do you ship to Canada?".');
-    return shop.ask(await shopOrigin(values), question);
-}
-// ---------- promotions: live settings in Commerce Layer, not store files
-/** What list and show print beyond the spec: dropped when it is sent back. */
-const READ_ONLY = ['status', 'uses', 'managed', 'url', 'urls', 'created_at'];
-/**
- * A spec from -f <file> or stdin, YAML or JSON, for promotions and links. What show prints
- * can be edited and sent back: the read-only fields are dropped.
- */
-async function readInput(values, what) {
-    const raw = await readText(values, what, `Give the ${what} as YAML or JSON on stdin (c11r ${what}s create <<'EOF' ... EOF) or with -f <file>.`, `invalid_${what}`);
-    if (raw && typeof raw === 'object' && !Array.isArray(raw))
-        for (const k of READ_ONLY)
-            delete raw[k];
-    return raw;
-}
-/** YAML or JSON from -f <file> or stdin, parsed. */
-async function readText(values, what, usage, invalid = 'invalid_argument') {
-    let text = '';
-    if (values.file) {
-        if (!fs.existsSync(values.file))
-            fail('missing_argument', `There is no file ${values.file}.`, `Give the ${what} as YAML or JSON with -f <file>, or on stdin.`);
-        text = fs.readFileSync(values.file, 'utf8');
-    }
-    else if (!process.stdin.isTTY) {
-        // A stream read: readFileSync(0) fails with EAGAIN on a pipe whose writer is still running.
-        const chunks = [];
-        for await (const chunk of process.stdin)
-            chunks.push(chunk);
-        text = Buffer.concat(chunks).toString('utf8');
-    }
-    else
-        fail('missing_argument', `No ${what} given.`, usage);
-    if (!text.trim())
-        fail('missing_argument', `No ${what} given: the input is empty.`, usage);
-    let raw;
-    try {
-        raw = YAML.parse(text);
-    }
-    catch (e) {
-        fail(invalid, `${what}: not valid YAML or JSON: ${e.message.split('\n')[0]}`, 'Fix the syntax and run the command again.');
-    }
-    return raw;
-}
-/** A promotion spec, validated against store.yml's markets and products. */
-async function readSpec(values) {
-    const raw = await readInput(values, 'promotion');
-    const store = loadStore();
-    return checkPromotion(raw, store.markets, store.products);
-}
-/** Warn when more promotion actions without a coupon are live than Commerce Layer applies. */
-async function activeWarning(api) {
-    const { promotions } = await api.listPromotions();
-    const live = promotions.filter((p) => p.status === 'active' || p.status === 'scheduled');
-    const active = activeWithoutCoupon(live);
-    return active.count > ACTIVE_LIMIT ? [`${active.count} promotions without a coupon are active or scheduled (one per action, in ${active.ids.join(', ')}): Commerce Layer applies at most ${ACTIVE_LIMIT}, the ones with the lowest priority number. Give the rest a coupon, an end date, or disable them.`] : undefined;
-}
-const checkNext = (p) => p.rules?.coupons?.length ? `Check it: c11r orders test --code ${p.rules.coupons[0]}, and read discounts.` : p.flex ? undefined : 'Check it: c11r orders test with an order that matches the rules (--sku, --quantity), and read discounts.';
-export async function promotionsList() {
-    const api = createApi(requireCredentials());
-    const { promotions } = await api.listPromotions();
-    return { count: promotions.length, promotions, warnings: await activeWarning(api) };
-}
-export async function promotionsShow(id) {
-    if (!id)
-        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions show <id>`; `c11r promotions list` has the ids.');
-    return createApi(requireCredentials()).getPromotion(id);
-}
-export async function promotionsCreate(values) {
-    const api = createApi(requireCredentials());
-    const spec = await readSpec(values);
-    const created = await api.createPromotion(spec);
-    return { status: 'created', promotion: created, warnings: await activeWarning(api), next: checkNext(created) };
-}
-export async function promotionsUpdate(id, values) {
-    if (!id)
-        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions update <id>` with the whole promotion on stdin or -f <file>.');
-    const api = createApi(requireCredentials());
-    // A promotion made outside c11r has Commerce Layer's id, which is no spec id: say what it is first.
-    if ((await api.getPromotion(id)).managed === false)
-        fail('promotion_not_managed', `Promotion ${id} was made outside c11r, in the dashboard.`, 'Create a c11r promotion with `c11r promotions create` and delete this one with `c11r promotions delete`, or edit it in the dashboard.');
-    const spec = await readSpec(values);
-    if (spec.id !== id)
-        fail('invalid_promotion', `id: the spec has id ${spec.id}, the command ${id}.`, 'An id never changes: use the same id, or create a new promotion and delete the old one.');
-    const updated = await api.updatePromotion(id, spec);
-    return { status: 'updated', promotion: updated, warnings: await activeWarning(api), next: checkNext(updated) };
-}
-export async function promotionsEnable(id, enabled) {
-    if (!id)
-        fail('missing_argument', 'Which promotion?', `Use \`c11r promotions ${enabled ? 'enable' : 'disable'} <id>\`.`);
-    const api = createApi(requireCredentials());
-    const p = await api.setPromotionEnabled(id, enabled);
-    return { status: enabled ? 'enabled' : 'disabled', promotion: p, warnings: enabled ? await activeWarning(api) : undefined };
-}
-export async function promotionsDelete(id) {
-    if (!id)
-        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions delete <id>`, after asking the human.');
-    await createApi(requireCredentials()).deletePromotion(id);
-    return { status: 'deleted', id };
-}
-// ---------- links: live settings in Commerce Layer, not store files
-/** A link as list, show and the writes print it: url and urls first. */
-const urlFirst = ({ url, urls, ...l }) => ({ url, urls, ...l });
-const linkNext = (l) => {
-    const what = 'order' in l.for ? 'the hosted checkout for the order' : 'a microstore for what it sells';
-    const which = Object.keys(l.urls ?? {}).length > 1 ? `the url of each market in urls (url is ${Object.keys(l.urls)[0]}'s)` : 'the url';
-    if (l.status === 'pending')
-        return `Give the human ${which}: it opens ${what} from ${l.starts}; until then it shows a not-found page.`;
-    if (l.status === 'active')
-        return `Give the human ${which}: it opens ${what} until ${l.ends}. Payment is manual (wire transfer) unless a gateway is added.`;
-    return undefined;
-};
-export async function linksList() {
-    const { links } = await createApi(requireCredentials()).listLinks();
-    return { count: links.length, links: links.map(urlFirst) };
-}
-export async function linksShow(id) {
-    if (!id)
-        fail('missing_argument', 'Which link?', 'Use `c11r links show <id>`; `c11r links list` has the ids.');
-    return urlFirst(await createApi(requireCredentials()).getLink(id));
-}
-export async function linksCreate(values) {
-    const api = createApi(requireCredentials());
-    const raw = await readInput(values, 'link');
-    const store = loadStore();
-    const created = await api.createLink(checkLink(raw, store.markets, store.products));
-    return { status: 'created', link: urlFirst(created), next: linkNext(created) };
-}
-export async function linksEnable(id, enabled) {
-    if (!id)
-        fail('missing_argument', 'Which link?', `Use \`c11r links ${enabled ? 'enable' : 'disable'} <id>\`.`);
-    const link = await createApi(requireCredentials()).setLinkEnabled(id, enabled);
-    return { status: enabled ? 'enabled' : 'disabled', link: urlFirst(link), next: enabled ? linkNext(link) : undefined };
-}
-export async function linksDelete(id) {
-    if (!id)
-        fail('missing_argument', 'Which link?', 'Use `c11r links delete <id>`, after asking the human.');
-    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 };
-    });
-}