@commercelayer/agent-cli 0.2.2 → 0.2.5

package/README.md

@@ -14,13 +14,19 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 ## Commands
 | Command | Does |
 | --- | --- |
-| `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`. Reuses the store if they exist. |
-| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, promotions, images, and the store's name, policies and theme; `warnings` flags more than 10 active promotions without a coupon. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
-| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products and promotions Commerce Layer refused. While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--full` re-imports every product and price, after edits in the Commerce Layer dashboard. |
+| `init [--name <business name>]` | Create a sandbox store, with no login. The name (the folder name when absent) names the organization; the org slug and store hostname derive from it, numbered when taken. Writes `store.yml` (a commented template) and `credentials`, plus a short `AGENTS.md` and `CLAUDE.md` section (appended to an existing file, never twice) that sends later agents in the repo to [commercelayer.ai/skills.md](https://commercelayer.ai/skills.md). Reuses the store if they exist. |
+| `plan` | Validate `store.yml` and the product files, and list what `apply` would create, update or delete: markets, products, images, and the store's name, policies and theme. `missing_images` lists `img/<file>` references with no file in `.commercelayer/img/` (`apply` refuses them); `unused_images` lists files there that nothing references. |
+| `apply [--allow-delete] [--full]` | Make the store match the files, the website included: the theme settings, and the images in `.commercelayer/img/` that the theme and products reference, uploaded when new or changed (unused ones are dropped from the store host). Refuses deletes without `--allow-delete`. Product changes go through a Commerce Layer import: `apply` waits for it, with progress as JSON lines on stderr, and prints one result. `apply_failed` lists the products Commerce Layer refused. While Commerce Layer is busy or unavailable, `apply` keeps reading (backing off on busy) and writes a `retrying` line. `apply_pending` means the import keeps going after 10 minutes, and `c11r status` follows it. An apply still running is finished before a new one starts. `--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` (a Supabase table, a Google Sheet or a Google Merchant Center feed) into `.commercelayer/products/catalog.csv`. Then `plan` and `apply` as usual. |
-| `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image get a neutral tile. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
+| `storefront init [--force]` | Custom storefronts only. Write a static storefront on [drop-in.js](https://commercelayer.github.io/drop-in.js/), no build step, wired to the sandbox's sales channel. `index.html`: the config block, the products grouped by top-level category with a navigation, a minicart that slides in on add to cart, the hosted cart and checkout, and a product page at `#/p/<sku>` built from `<template id="product-template">` and the `#products` data. `styles.css`: theme tokens first (`--paper`, `--ink`, `--muted`, `--line`, `--accent`, `--on-accent`, `--radius`, `--font`), which also restyle drop-in.js's prices, buttons and links, so a dark theme is a token change; then the drop-in.js overrides, then the page. `app.js`: the market switch, the category links and the product page. Product images are the store's, at `/img/<file>` (from `.commercelayer/img/`, uploaded by `apply`); products with no image show the tile the store host draws for them, at `/tiles/<sku>.svg`. The site's own files go in `storefront/assets/`. Refuses to overwrite without the flag; with it, rewrites the three files. |
 | `storefront publish` | Custom storefronts only. Upload the folder at `storefront.path` (default `storefront`) to the store host, where it replaces the hosted theme, leaving out dotfiles. `/img/` on the store host is always the store's images, so files under the folder's `img/` are not served: publish lists them as `not_served`. |
 | `storefront check` | Custom storefronts only. Read the published storefront at the preview URL and check it: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product and none for unknown skus, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides (no dead `::part` rules), title, `lang`, viewport, description, and whether the folder changed since publish. Prints `{ status, summary, checks: [{ id, kind, status: pass\|warn\|fail, message, fix, items }], render }` and exits 1 when a check fails; warnings do not fail. `kind` is `static` today; a later rendering phase adds `render` checks and fills `render`. |
+| `promotions list` · `show <id>` | The store's promotions, live in Commerce Layer: id, name, status, rules, actions, uses, dates; `managed: false` for ones made in the dashboard. |
+| `promotions create` · `update <id>` | Create a promotion, or replace one, from a spec in YAML or JSON on stdin or `-f <file>` (see [Promotions](#promotions)). Prints the promotion and the `orders test` call that checks it. |
+| `promotions enable <id>` · `disable <id>` · `delete <id>` | Turn a promotion on or off, or delete it (ask the human first). |
+| `links list` · `show <id>` | The store's links, live in Commerce Layer: url, id, name, status, what it sells, markets, dates; `managed: false` for ones made in the dashboard. |
+| `links create` | Create a shareable link to a microstore (sku, skus or category) or an order's checkout, from a spec in YAML or JSON on stdin or `-f <file>` (see [Links](#links)). Prints the link, `url` first. |
+| `links enable <id>` · `disable <id>` · `delete <id>` | Turn a link on or off, or delete it (ask the human first). |
 | `orders test [--sku <id>] [--quantity <n>] [--country <CC>] [--code <discount>] [--via-cart] [--decline]` | Buy from the store over UCP as a shopping agent would: discover, search, (cart,) checkout, address, pay with the sandbox handler, read the order back. Prints the order, the `discounts` applied (promotions and codes, in minor units like the totals) and every step. |
 | `orders list` | The orders placed in the store, newest first, as UCP order entities. |
 | `orders show <id or number>` | One order. |
@@ -58,16 +64,6 @@ theme:
   logo: img/logo.svg   # or an https:// URL; default: the name as a wordmark
   hero: img/hero.jpg   # the home page's wide image; default: a band in the accent
   tagline: Small-batch coffee, roasted in Milan   # at most 120 characters; default: "Ships to <countries>"
-promotions:
-  # Discounts: rules (when, all must match) and actions (what). The id is stable.
-  - id: welcome10
-    name: Welcome, 10% off
-    rules: [{ coupon: WELCOME10 }]
-    actions: [{ percentage: 10 }]
-  - id: free-shipping-50
-    market: eu
-    rules: [{ order_amount: { min: 50 } }]
-    actions: [free_shipping]
 policies:
   # Pages shopping agents show buyers before they pay. Without them the store
   # serves default sandbox pages at <preview_url>/policies/<name>.
@@ -76,13 +72,33 @@ policies:
   returns: https://example.com/returns
 ```
 ### Promotions
-Each entry under `promotions:` has an `id` (lowercase letters, digits and dashes; the store identifies the promotion by it) and optionally `name`, `market` (a market code; without it, every market), `starts` and `ends` (a day, or a UTC time; a bare `ends` day runs to 23:59:59Z; without them the promotion is always on), `limit` (total uses), `priority` (lowest first), `exclusive` and `enabled`.
+Promotions are live settings in Commerce Layer, not store files: the `promotions` commands create and change them directly, and nothing about them is committed. A spec, in YAML or JSON on stdin or with `-f <file>`:
 
-- Rules, one of each kind at most, all matching: `coupon: CODE` or a list (8 to 40 letters, digits, `-`, `_`), `order_amount: { min }` (the items total), `skus: [...]` or `category: A > B` (resolved to its products' skus by the CLI).
+```yaml
+id: welcome10            # the handle: lowercase letters, digits, dashes; unique
+name: Welcome, 10% off
+rules: [{ coupon: WELCOME10 }]
+actions: [{ percentage: 10 }]
+```
+
+Optional: `market` (a market code; without it, every market), `starts` and `ends` (a day, or a UTC time; a bare `ends` day runs to 23:59:59Z; without them the promotion is always on), `limit` (total uses), `priority` (lowest first), `exclusive`, `enabled`.
+
+- Rules, one of each kind at most, all matching: `coupon: CODE` or a list (8 to 40 letters, digits, `-`, `_`), `order_amount: { min }` (the items total), `skus: [...]` or `category: A > B`. A category becomes the skus of its products in store.yml when the command runs: after adding products to it, run `update` again.
 - Actions: `percentage: 10` (with `skus` or `category` to limit it), `fixed_amount: 5`, `free_shipping`, `fixed_price: { price, skus|category }`, `free_gift: { skus|category, quantity }`, `buy_x_pay_y: { x, y, cheapest_free?, skus|category }`. Actions without their own skus take the rule's. Amounts are in major units, like prices; in a store with several currencies, a promotion with an amount names its `market`. Commerce Layer gets one promotion per action.
-- `flex: { rules: [...] }` holds a Commerce Layer Rules Engine promotion as written (amounts in cents), in place of `rules` and `actions`. It needs the Rules Engine: sandboxes do not have it, and `apply` stops with `flex_unavailable`, applying nothing.
+- `flex: { rules: [...] }` holds a Commerce Layer Rules Engine promotion as written (amounts in cents), in place of `rules` and `actions`. Sandboxes have no Rules Engine: `create` answers `flex_unavailable` and creates nothing.
+
+`list` and `show` print each promotion in the normalized form plus `status` (`active`, `scheduled`, `expired`, `disabled`, `used_up`) and `uses`; that output can be edited and sent back to `update`. Promotions made outside c11r (the dashboard, the sandbox's `SANDBOX10`) are listed with `managed: false` and Commerce Layer's id: `enable`, `disable` and `delete` work on them, `update` answers `promotion_not_managed`. `percentage` is a whole number from 1 to 100; a promotion takes at most 20 codes, a free gift at most 25 SKUs. More than 10 active promotion actions without a coupon gives a `warnings` entry (Commerce Layer applies 10). `orders test --code <CODE>` proves one: its `discounts` lists what was taken off, automatic promotions with `automatic: true`, and a code that applied nothing is a `discount_code_invalid` warning in `messages`.
+
+### Links
+Links are live settings in Commerce Layer too, never 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. A spec, in YAML or JSON on stdin or with `-f <file>`:
+
+```yaml
+id: single-origins       # the handle: lowercase letters, digits, dashes; unique
+name: Single origins
+for: { category: Coffee > Single origin }   # or { sku: ETH }, { skus: [ETH, COL] }, { order: 1001 | cart_... }
+```
 
-`plan` lists them as `promotion` changes, and warns when more than 10 promotion actions without a coupon are active (Commerce Layer applies 10). Removing one needs `--allow-delete`. `orders test --code <CODE>` proves one: its `discounts` lists what was taken off, and a code that applied nothing is a `discount_code_invalid` warning in `messages`.
+Optional: `market` (a code or a list; without it, every market; an order link takes the order's market and none), `starts` (default now) and `ends` (default a month after `starts`; a day, or a UTC time; a bare `ends` day runs to 23:59:59Z), `params` (names to plain values, added to the URL). A category becomes the skus of its products in store.yml when the command runs; a link sells 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 (`cart_...`, `chk_...`), read back as the order's number. A placed order opens its thank-you page, so `create` refuses it. Commerce Layer opens a link in one market, so a link has a URL per market: `urls`, by market code, and `url`, the first market's. `create`, `list` and `show` print `url` and `urls` first, then the spec, `status` (`pending`, `active`, `expired`, `disabled`: the first market's; enable and disable act on every market) and `created_at`. A disabled or pending link opens Commerce Layer's not-found page; checkout takes the sandbox's manual payment (wire transfer) unless a gateway is added. A link cannot change: delete it and create it again (what `show` prints can be sent back to `create`). Links made outside c11r are listed with `managed: false` and Commerce Layer's id, and may sell `for: { sku_list: <name> }`; `enable`, `disable` and `delete` work on them.
 
 ### The products folder
 Beyond a handful of products, put the catalog in `.commercelayer/products/` and leave `products` out of `store.yml`. Every file in the folder is merged into the catalog by sku, in file-name order:
@@ -115,7 +131,7 @@ One rule for images: `img/<file>` anywhere in `store.yml` (product `image_url`,
 
 A custom storefront replaces the theme: `storefront.path` in `store.yml` names its folder, `storefront init` writes a drop-in.js scaffold, `storefront publish` uploads it, `storefront check` checks it. Its pages link product images at `/img/`; its own files (fonts, icons, styles) go in `assets/`, not `img/`.
 
-Error codes: `invalid_theme`, `invalid_promotion`, `flex_unavailable`, `promotions_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
+Error codes: `invalid_theme`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `invalid_link`, `link_exists`, `link_not_managed` (reserved), `links_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
 | What | Where |

package/dist/api/client.js

@@ -1,5 +1,5 @@
 // The client for the management API at api.commercelayer.ai.
-import { fail } from '../output.js';
+import { CliError, fail } from '../output.js';
 import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
 export function createApi(auth) {
     const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
@@ -27,7 +27,45 @@ export function createApi(auth) {
             fail(err.code, err.message, err.hint);
         fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
     };
+    // Promotions and links: on an API older than them, the collection route is an unknown route (404 not_found).
+    const collection = (kind) => `${org()}/${kind}`;
+    const one = (kind, id) => `${collection(kind)}/${encodeURIComponent(id)}`;
+    const unsupported = async (kind, call) => {
+        try {
+            return await call;
+        }
+        catch (e) {
+            if (e instanceof CliError && (e.code === 'not_found' || (e.code === 'api_error' && /\b404\b/.test(e.message))))
+                fail(`${kind}_unsupported`, `This API does not manage ${kind} yet.`, 'Try again later; tell the human if it persists.');
+            throw e;
+        }
+    };
+    const found = async (kind, id, call) => {
+        try {
+            return await call;
+        }
+        catch (e) {
+            if (e instanceof CliError && e.code === 'not_found')
+                fail('not_found', `There is no ${kind.slice(0, -1)} ${id}.`, `Run \`c11r ${kind} list\` for the ids, or \`c11r ${kind} create\` to make it.`);
+            throw e;
+        }
+    };
     return {
+        listPromotions: () => unsupported('promotions', request('GET', collection('promotions'))),
+        createPromotion: (spec) => unsupported('promotions', request('POST', collection('promotions'), spec)),
+        getPromotion: (id) => found('promotions', id, request('GET', one('promotions', id))),
+        updatePromotion: (id, spec) => found('promotions', id, request('PUT', one('promotions', id), spec)),
+        setPromotionEnabled: (id, enabled) => found('promotions', id, request('POST', `${one('promotions', id)}/${enabled ? 'enable' : 'disable'}`)),
+        deletePromotion: async (id) => {
+            await found('promotions', id, request('DELETE', one('promotions', id)));
+        },
+        listLinks: () => unsupported('links', request('GET', collection('links'))),
+        createLink: (spec) => unsupported('links', request('POST', collection('links'), spec)),
+        getLink: (id) => found('links', id, request('GET', one('links', id))),
+        setLinkEnabled: (id, enabled) => found('links', id, request('POST', `${one('links', id)}/${enabled ? 'enable' : 'disable'}`)),
+        deleteLink: async (id) => {
+            await found('links', id, request('DELETE', one('links', id)));
+        },
         createSandbox: (name) => request('POST', '/sandboxes', { name }),
         getStore: () => request('GET', org()),
         applyStore: (body) => request('PUT', `${org()}/resources`, body),

package/dist/api/stub/management.js

@@ -7,11 +7,10 @@ import { publicOrders, readDb, SANDBOX_DOMAIN, writeDb } from './db.js';
 import { bearer, error, json, readJson } from './http.js';
 function publicState(r) {
     const { token: _token, ucp: _ucp, pending: _pending, asset_files: _files, ...state } = r;
-    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, assets: r.assets ?? {}, promotions: r.promotions ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
+    return { ...state, name: r.name ?? null, policies: r.policies ?? null, theme: r.theme ?? null, assets: r.assets ?? {}, apply: r.apply ?? null, orders: publicOrders(r) };
 }
-/** Like Commerce Layer refusing a sku or a promotion in an import. Only the stub does this, so tests can exercise apply_failed. */
+/** Like Commerce Layer refusing a sku in an import. Only the stub does this, so tests can exercise apply_failed. */
 const REFUSED = /^REFUSED-/;
-const REFUSED_PROMOTION = /^refused-/;
 /** C11R_STUB_BUSY_READS=n: the first n reads of a running import answer 503 commercelayer_busy, as when Commerce Layer rate-limits. Per process. */
 let busyReads = Number(process.env.C11R_STUB_BUSY_READS) || 0;
 /** Items an import gets through per read: small, so the CLI polls a few times. */
@@ -29,23 +28,83 @@ function advance(r) {
         return;
     job.step = 'done';
     job.finished_at = new Date().toISOString();
-    const refusedPromotions = r.pending.refused_promotions ?? [];
-    if (r.pending.refused.length || refusedPromotions.length) {
+    if (r.pending.refused.length) {
         job.status = 'failed';
-        job.errors = [
-            ...r.pending.refused.map((sku) => ({ sku, message: 'code is invalid' })),
-            ...refusedPromotions.map((id) => ({ sku: null, promotion: id, message: 'is invalid' })),
-        ].slice(0, 50);
+        job.errors = r.pending.refused.slice(0, 50).map((sku) => ({ sku, message: 'code is invalid' }));
     }
     else {
         job.status = 'completed';
         r.applied = r.pending.applied;
-        if (r.pending.promotions)
-            r.promotions = r.pending.promotions;
         r.applied_hash = job.hash;
     }
     delete r.pending;
 }
+function withDefaults(spec) {
+    return { ...spec, starts: spec.starts ?? '2000-01-01T00:00:00Z', ends: spec.ends ?? '2100-01-01T00:00:00Z', exclusive: spec.exclusive ?? false, enabled: spec.enabled ?? true };
+}
+/** As the API lists it: the spec plus status and uses. */
+function listed(p) {
+    const now = Date.now();
+    const status = !p.enabled ? 'disabled' : p.limit !== undefined && p.uses >= p.limit ? 'used_up' : Date.parse(p.ends) <= now ? 'expired' : Date.parse(p.starts) > now ? 'scheduled' : 'active';
+    return { ...p, status, managed: true };
+}
+/** The API checks skus against the last applied catalog. */
+function unknownSkus(r, spec) {
+    const known = r.applied?.products ?? {};
+    const where = [['rules.skus', spec.rules?.skus], ...(spec.actions ?? []).map((a, i) => [`actions[${i}].skus`, 'skus' in a ? a.skus : undefined])];
+    for (const [path, list] of where) {
+        const i = (list ?? []).findIndex((sku) => !(sku in known));
+        if (i >= 0)
+            return error(422, 'invalid_promotion', `${path}[${i}]: ${list[i]} is not a product of the store.`, 'Use skus of applied products: run `c11r apply` first if you just added them.');
+    }
+    return undefined;
+}
+/** As the API lists it: the spec plus the first market's url, every url, and status. */
+function listedLink(l) {
+    const { enabled, urls, ...link } = l;
+    const now = Date.now();
+    const status = !enabled ? 'disabled' : Date.parse(l.ends) <= now ? 'expired' : Date.parse(l.starts) > now ? 'pending' : 'active';
+    return { ...link, url: Object.values(urls)[0], urls, status, managed: true };
+}
+/** The API checks a link against the store: applied skus and markets, draft orders. Answers the markets it gets a link in. */
+function linkMarkets(r, spec) {
+    const known = r.applied?.products ?? {};
+    const f = spec.for;
+    const list = 'sku' in f ? [['for.sku', f.sku]] : 'skus' in f ? f.skus.map((s, i) => [`for.skus[${i}]`, s]) : [];
+    for (const [path, sku] of list)
+        if (!(sku in known))
+            return error(422, 'invalid_link', `${path}: unknown sku ${sku}.`, 'Use skus of applied products: run `c11r apply` first if you just added them.');
+    if ('order' in f) {
+        if (spec.markets)
+            return error(422, 'invalid_link', "markets: an order link uses the order's market.", 'Leave markets out.');
+        // A UCP cart or checkout id names the draft order behind it, read back as its number (the stub's: the id's suffix).
+        const cart = /^cart_/.test(f.order) ? r.ucp.carts[f.order] : undefined;
+        // A cart is the same order as the checkout made from it.
+        const ucp = cart ? (Object.values(r.ucp.checkouts).find((c) => c._cart_id === f.order && c.status === 'completed') ?? cart) : /^chk_/.test(f.order) ? r.ucp.checkouts[f.order] : undefined;
+        if (ucp) {
+            const placed = ucp.order?.label;
+            if (ucp.status === 'completed' && placed)
+                return error(422, 'invalid_link', `for.order: order ${placed.replace(/^#/, '')} is placed: a link opens the checkout of a draft or pending order.`, 'Link a cart or checkout that is not completed.');
+            if (ucp.status === 'canceled')
+                return error(422, 'invalid_link', `for.order: no order ${f.order}.`, 'The checkout is canceled: link another cart or checkout.');
+            const market = Object.values(r.applied?.markets ?? {}).find((m) => m.currency === ucp.currency)?.code ?? Object.keys(r.applied?.markets ?? {})[0];
+            spec.for = { order: f.order.replace(/^(cart|chk)_/, '') };
+            return [market];
+        }
+        const draft = r.draft_orders?.[f.order];
+        if (draft)
+            return [draft.market];
+        if (publicOrders(r).some((o) => o.label.replace(/^#/, '') === f.order))
+            return error(422, 'invalid_link', `for.order: order ${f.order} is placed: a link opens the checkout of a draft or pending order.`, 'A placed order opens its thank-you page, not a checkout: link a draft or pending order.');
+        return error(422, 'invalid_link', `for.order: no order ${f.order}.`, 'Use the number of a draft or pending order in the store.');
+    }
+    const applied = Object.keys(r.applied?.markets ?? {});
+    const markets = spec.markets ?? applied;
+    const i = markets.findIndex((m) => !applied.includes(m));
+    if (i >= 0)
+        return error(422, 'invalid_link', `markets[${i}]: unknown market ${markets[i]}.`, 'Use markets that are applied: run `c11r apply` first if you just added it.');
+    return markets;
+}
 export function handleManagement(req) {
     const db = readDb();
     const path = req.url.pathname;
@@ -105,21 +164,11 @@ export function handleManagement(req) {
         writeDb(db);
         if (record.apply?.status === 'in_progress')
             return error(409, 'apply_in_progress', 'Another apply is still running.', 'Run `c11r status` to follow it, then apply again.');
-        const { applied, hash, name, policies, theme, promotions, assets, allow_delete, full } = readJson(req);
+        const { applied, hash, name, policies, theme, assets, allow_delete, full } = readJson(req);
         const before = record.applied?.products ?? {};
         const removed = Object.keys(before).filter((sku) => !(sku in applied.products));
-        // No promotions field (older CLIs): the promotions stay as they are.
-        const promosBefore = record.promotions ?? {};
-        const promos = promotions ? Object.fromEntries(promotions.map((p) => [p.id, p])) : promosBefore;
-        const promosRemoved = Object.keys(promosBefore).filter((id) => !(id in promos));
-        const promosChanged = Object.keys(promos).filter((id) => !(id in promosBefore) || canonical(promosBefore[id]) !== canonical(promos[id]));
-        const doomed = [...removed.map((sku) => `product ${sku}`), ...promosRemoved.map((id) => `promotion ${id}`)];
-        if (doomed.length && !allow_delete)
-            return error(409, 'deletes_need_approval', `Apply would delete ${doomed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
-        // Sandboxes have no Rules Engine: a new or changed flex promotion is refused before anything applies.
-        const flexAt = (promotions ?? []).findIndex((p) => p.flex && promosChanged.includes(p.id));
-        if (flexAt >= 0)
-            return error(422, 'flex_unavailable', `promotions[${flexAt}] (${promotions[flexAt].id}): flex promotions need the Rules Engine, which this organization does not have.`, 'Tell the human flex promotions need a Commerce Layer plan with the Rules Engine; build the promotion from the standard rules and actions if you can, or remove it, then apply again.');
+        if (removed.length && !allow_delete)
+            return error(409, 'deletes_need_approval', `Apply would delete product ${removed.join(', ')}.`, 'Ask the human whether to delete these. If they agree, run `c11r apply --allow-delete`.');
         // The name, policies and markets apply in the request; products go through an
         // import job (SKUs, prices, then cleanups for removals) when any changed.
         record.name = name;
@@ -136,10 +185,8 @@ export function handleManagement(req) {
             }
         }
         const changed = Object.keys(applied.products).filter((sku) => full || !(sku in before) || canonical(before[sku]) !== canonical(applied.products[sku]));
-        const refusedPromotions = promosChanged.filter((id) => REFUSED_PROMOTION.test(id));
-        if (changed.length === 0 && removed.length === 0 && refusedPromotions.length === 0) {
+        if (changed.length === 0 && removed.length === 0) {
             record.applied = applied;
-            record.promotions = promos;
             record.applied_hash = hash;
             writeDb(db);
             return json(200, publicState(record));
@@ -150,15 +197,108 @@ export function handleManagement(req) {
             step: 'skus',
             hash,
             processed: 0,
-            total: changed.length + removed.length + promosChanged.length + promosRemoved.length,
+            total: changed.length + removed.length,
             started_at: new Date().toISOString(),
             finished_at: null,
             errors: [],
         };
-        record.pending = { applied, refused: changed.filter((sku) => REFUSED.test(sku)), promotions: promos, refused_promotions: refusedPromotions };
+        record.pending = { applied, refused: changed.filter((sku) => REFUSED.test(sku)) };
         writeDb(db);
         return json(202, publicState(record));
     }
+    // Promotions: live, synchronous, keyed by id. Sandboxes have no Rules Engine.
+    if (rest === '/promotions' || rest.startsWith('/promotions/')) {
+        const store = (record.promotions ??= {});
+        const [, , rawId, verb] = rest.split('/');
+        const id = rawId === undefined ? undefined : decodeURIComponent(rawId);
+        const save = () => writeDb(db);
+        const flexRefused = (spec) => (spec.flex ? error(422, 'flex_unavailable', 'Flex promotions need the Rules Engine, which this organization does not have.', 'Tell the human flex promotions need a Commerce Layer plan with the Rules Engine; build the promotion from the standard rules and actions if you can.') : undefined);
+        if (id === undefined) {
+            if (req.method === 'GET')
+                return json(200, { promotions: Object.keys(store).sort().map((k) => listed(store[k])) });
+            if (req.method === 'POST') {
+                const spec = readJson(req);
+                if (store[spec.id])
+                    return error(409, 'promotion_exists', `There is already a promotion ${spec.id}.`, 'Use `c11r promotions update <id>` to change it, or pick another id.');
+                const refused = flexRefused(spec) ?? unknownSkus(record, spec);
+                if (refused)
+                    return refused;
+                store[spec.id] = { ...withDefaults(spec), uses: 0 };
+                save();
+                return json(201, listed(store[spec.id]));
+            }
+        }
+        else {
+            const p = store[id];
+            if (!p)
+                return error(404, 'not_found', `There is no promotion ${id}.`, 'Run `c11r promotions list`.');
+            if (verb === undefined && req.method === 'GET')
+                return json(200, listed(p));
+            if (verb === undefined && req.method === 'PUT') {
+                const spec = readJson(req);
+                if (spec.id !== id)
+                    return error(422, 'invalid_promotion', `id: the body has ${spec.id}, the path ${id}.`, 'An id never changes.');
+                const refused = flexRefused(spec) ?? unknownSkus(record, spec);
+                if (refused)
+                    return refused;
+                store[id] = { ...withDefaults(spec), uses: p.uses };
+                save();
+                return json(200, listed(store[id]));
+            }
+            if (verb === undefined && req.method === 'DELETE') {
+                delete store[id];
+                save();
+                return { status: 204, headers: {}, body: '' };
+            }
+            if ((verb === 'enable' || verb === 'disable') && req.method === 'POST') {
+                p.enabled = verb === 'enable';
+                save();
+                return json(200, listed(p));
+            }
+        }
+    }
+    // Links: live, synchronous, keyed by id; one Commerce Layer link per market.
+    if (rest === '/links' || rest.startsWith('/links/')) {
+        const store = (record.links ??= {});
+        const [, , rawId, verb] = rest.split('/');
+        const id = rawId === undefined ? undefined : decodeURIComponent(rawId);
+        const save = () => writeDb(db);
+        if (id === undefined) {
+            if (req.method === 'GET')
+                return json(200, { links: Object.keys(store).sort().map((k) => listedLink(store[k])) });
+            if (req.method === 'POST') {
+                const spec = readJson(req);
+                if (store[spec.id])
+                    return error(409, 'link_exists', `There is already a link ${spec.id}.`, 'Pick another id, or delete the link and create it again.');
+                const markets = linkMarkets(record, spec);
+                if (!Array.isArray(markets))
+                    return markets;
+                // One Commerce Layer link per market: a scope with several markets does not open.
+                const urls = Object.fromEntries(markets.map((m) => [m, `https://c11.page/${crypto.randomBytes(6).toString('base64url')}`]));
+                // An order link reads back with the order's market.
+                store[spec.id] = { ...spec, markets, urls, enabled: true, created_at: new Date().toISOString() };
+                save();
+                return json(201, listedLink(store[spec.id]));
+            }
+        }
+        else {
+            const l = store[id];
+            if (!l)
+                return error(404, 'not_found', `There is no link ${id}.`, 'Run `c11r links list`.');
+            if (verb === undefined && req.method === 'GET')
+                return json(200, listedLink(l));
+            if (verb === undefined && req.method === 'DELETE') {
+                delete store[id];
+                save();
+                return { status: 204, headers: {}, body: '' };
+            }
+            if ((verb === 'enable' || verb === 'disable') && req.method === 'POST') {
+                l.enabled = verb === 'enable';
+                save();
+                return json(200, listedLink(l));
+            }
+        }
+    }
     if (req.method === 'PUT' && rest === '/assets') {
         const { files } = readJson(req);
         let total = 0;

package/dist/api/stub/shopping.js

@@ -86,8 +86,9 @@ function returnPolicy(ctx) {
     ];
 }
 // ---------- catalog
-/** A path in the storefront (img/eth.jpg) is served from the store host: shopping agents always get a full URL. */
-const imageUrl = (ctx, url) => new URL(url, `${ctx.origin}/`).href;
+/** A path in the storefront (img/eth.jpg) is served from the store host: shopping agents always get a full URL,
+ * and for a product without an image, its tile. */
+const imageUrl = (ctx, p) => new URL(p.image_url ?? `tiles/${encodeURIComponent(p.sku)}.svg`, `${ctx.origin}/`).href;
 function variant(ctx, p, market) {
     const price = { amount: toMinor(p.prices[market.currency], market.currency), currency: market.currency };
     const v = {
@@ -100,8 +101,7 @@ function variant(ctx, p, market) {
         // Inventory lives in Commerce Layer; the sandbox catalog has no stock, so everything is in stock.
         availability: { available: true, status: 'in_stock' },
     };
-    if (p.image_url)
-        v.media = [{ type: 'image', url: imageUrl(ctx, p.image_url) }];
+    v.media = [{ type: 'image', url: imageUrl(ctx, p) }];
     if (ctx.shared.has('dev.ucp.shopping.fulfillment')) {
         const o = shippingOption(market);
         v.fulfillment = { methods: [{ type: 'shipping', description: { plain: `Ships to ${market.countries.join(', ')}` }, availability: v.availability, options: [{ id: o.id, title: o.title, description: o.description }] }] };
@@ -202,8 +202,7 @@ function buildLines(ctx, market, requested, existing = []) {
         const qty = quantity;
         const prev = existing.find((e) => e.id === l.id) ?? existing.find((e) => e.item.id === p.sku);
         const item = { id: p.sku, title: p.name, price };
-        if (p.image_url)
-            item.image_url = imageUrl(ctx, p.image_url);
+        item.image_url = imageUrl(ctx, p);
         lines.push({ id: prev?.id ?? `li_${++n}`, item, quantity: qty, totals: [{ type: 'subtotal', amount: price * qty }, { type: 'total', amount: price * qty }] });
     });
     return { lines, messages };

package/dist/api/stub/theme.js

@@ -2,6 +2,8 @@
 // custom storefront: the same settings in the same places (accent, logo or wordmark,
 // hero image or band, tagline), the products by top-level category, a page per product
 // at /products/<sku>. Prices come from what is applied; "Buy" opens the cart permalink.
+// A product without an image shows its tile, and an unset hero the generated one, both
+// drawn at /tiles/ (renderTile) as the store host does.
 const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 /** Black or white, whichever reads better on the accent. */
 function onAccent(hex) {
@@ -21,7 +23,8 @@ export function renderTheme(r, path, search) {
     const tagline = theme.tagline ?? `Ships to ${markets.flatMap((m) => m.countries).join(', ')}`;
     const logo = theme.logo ? `<img class="logo" src="/${esc(theme.logo.replace(/^\//, ''))}" alt="${esc(name)}">` : `<span class="wordmark">${esc(name)}</span>`;
     const img = (url) => (/^https?:/.test(url) ? url : `/${url}`);
-    const card = (p) => `<article class="product"><a href="/products/${encodeURIComponent(p.sku)}${keep}">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<h3>${esc(p.name)}</h3></a><p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></article>`;
+    const image = (p) => p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : `<span class="placeholder"><img src="/tiles/${esc(encodeURIComponent(p.sku))}.svg" alt="${esc(p.name)}" loading="lazy"></span>`;
+    const card = (p) => `<article class="product"><a href="/products/${encodeURIComponent(p.sku)}${keep}">${image(p)}<h3>${esc(p.name)}</h3></a><p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></article>`;
     let title = name;
     let body;
     const m = path.match(/^\/products\/([^/]+)$/);
@@ -31,7 +34,7 @@ export function renderTheme(r, path, search) {
             const top = p.category?.split(' > ')[0] ?? 'Other';
             groups.set(top, [...(groups.get(top) ?? []), p]);
         }
-        const hero = theme.hero ? `<section class="hero" style="background-image:url('${esc(img(theme.hero))}')">` : '<section class="hero band">';
+        const hero = `<section class="hero" style="background-image:url('${esc(theme.hero ? img(theme.hero) : '/tiles/hero.svg')}')">`;
         body = `${hero}<h1>${esc(name)}</h1><p class="tagline">${esc(tagline)}</p></section><main>${[...groups].map(([k, ps]) => `<section><h2>${esc(k)}</h2><div class="grid">${ps.map(card).join('')}</div></section>`).join('')}</main>`;
     }
     else if (m) {
@@ -39,7 +42,7 @@ export function renderTheme(r, path, search) {
         if (!p)
             return null;
         title = `${p.name} · ${name}`;
-        body = `<main class="product-page">${p.image_url ? `<img src="${esc(img(p.image_url))}" alt="${esc(p.name)}">` : '<div class="placeholder"></div>'}<div>${p.category ? `<p class="category">${esc(p.category)}</p>` : ''}<h1>${esc(p.name)}</h1>${p.description ? `<p>${esc(p.description)}</p>` : ''}<p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></div></main>`;
+        body = `<main class="product-page">${image(p)}<div>${p.category ? `<p class="category">${esc(p.category)}</p>` : ''}<h1>${esc(p.name)}</h1>${p.description ? `<p>${esc(p.description)}</p>` : ''}<p class="price">${esc(price(p))}</p><a class="buy" href="/buy/${encodeURIComponent(p.sku)}:1">Buy</a></div></main>`;
     }
     else
         return null;
@@ -61,3 +64,29 @@ ${body}
 `;
     return { status: 200, headers: { 'content-type': 'text/html; charset=utf-8' }, body: html };
 }
+const xml = (t) => String(t ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
+/** /tiles/<sku>.svg and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
+export function renderTile(r, path) {
+    const m = path.match(/^\/tiles\/([^/]+)\.svg$/);
+    if (!m)
+        return null;
+    const color = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(r.theme?.color ?? '') ? r.theme.color : '#2f5d50';
+    const headers = { 'content-type': 'image/svg+xml', 'cache-control': 'public, max-age=300', 'x-content-type-options': 'nosniff' };
+    let svg;
+    if (m[1] === 'hero')
+        svg = `<svg xmlns="http://www.w3.org/2000/svg" width="2400" height="900" viewBox="0 0 2400 900"><rect width="2400" height="900" fill="${color}"/><circle cx="1900" cy="450" r="360" fill="#ffffff" fill-opacity="0.12"/></svg>`;
+    else {
+        let sku;
+        try {
+            sku = decodeURIComponent(m[1]);
+        }
+        catch {
+            return null;
+        }
+        const p = r.applied?.products[sku];
+        if (!p)
+            return null;
+        svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="1200" viewBox="0 0 1200 1200"><rect width="1200" height="1200" fill="${color}" fill-opacity="0.08"/><text x="600" y="600" text-anchor="middle" font-family="system-ui, sans-serif" font-size="72" fill="${color}">${xml(p.name.slice(0, 60))}</text></svg>`;
+    }
+    return { status: 200, headers, body: svg };
+}

package/dist/api/stub/ucp.js

@@ -8,7 +8,7 @@ import { contentDigest, signHeaders } from '../../ucp/signing.js';
 import { strip } from './db.js';
 import { json } from './http.js';
 import * as shop from './shopping.js';
-import { renderTheme } from './theme.js';
+import { renderTheme, renderTile } from './theme.js';
 const SCOPES = ['dev.ucp.shopping.order:read', 'dev.ucp.shopping.order:manage'];
 const OUR_CAPABILITIES = [...SHOPPING_CAPABILITIES, 'dev.ucp.common.ask', ...Object.keys(EXTENSIONS), 'dev.ucp.common.identity_linking', 'dev.ucp.shopping.permalink'];
 // ---------- profile
@@ -305,6 +305,9 @@ function handlePermalink(req, r, origin, path) {
 const MIME = { html: 'text/html; charset=utf-8', css: 'text/css', js: 'text/javascript', mjs: 'text/javascript', json: 'application/json', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif', avif: 'image/avif', ico: 'image/x-icon', txt: 'text/plain' };
 function serveStorefront(r, path, search) {
     const files = r.ucp.files;
+    // /tiles/ is the store host's own, in front of a custom storefront too: unknown tiles are a 404.
+    if (path.startsWith('/tiles/'))
+        return renderTile(r, path) ?? html(404, 'Not found', `<p>No ${path} on this store.</p>`);
     // A custom storefront (an uploaded index.html) serves every path; otherwise the theme renders its routes.
     if (files['index.html'] === undefined) {
         const page = renderTheme(r, path, search);

package/dist/bin.js

@@ -4,13 +4,17 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
-const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code']);
+const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file']);
 const argv = process.argv.slice(2);
 const flags = new Set();
 const values = {};
 const args = [];
 for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
+    if (a === '-f' && i + 1 < argv.length) {
+        values.file = argv[++i];
+        continue;
+    }
     if (!a.startsWith('--')) {
         args.push(a);
         continue;
@@ -53,6 +57,32 @@ async function run() {
             if (sub === 'check')
                 return cmd.storefrontCheckCmd();
             throw new CliError('unknown_command', `There is no command "storefront ${sub ?? ''}".`, 'Use `c11r storefront init`, `storefront publish` or `storefront check`.');
+        case 'promotions':
+            if (sub === 'list')
+                return cmd.promotionsList();
+            if (sub === 'show')
+                return cmd.promotionsShow(args[2]);
+            if (sub === 'create')
+                return cmd.promotionsCreate(values);
+            if (sub === 'update')
+                return cmd.promotionsUpdate(args[2], values);
+            if (sub === 'enable' || sub === 'disable')
+                return cmd.promotionsEnable(args[2], sub === 'enable');
+            if (sub === 'delete')
+                return cmd.promotionsDelete(args[2]);
+            throw new CliError('unknown_command', `There is no command "promotions ${sub ?? ''}".`, 'Use `c11r promotions list`, `show <id>`, `create`, `update <id>`, `enable <id>`, `disable <id>` or `delete <id>`.');
+        case 'links':
+            if (sub === 'list')
+                return cmd.linksList();
+            if (sub === 'show')
+                return cmd.linksShow(args[2]);
+            if (sub === 'create')
+                return cmd.linksCreate(values);
+            if (sub === 'enable' || sub === 'disable')
+                return cmd.linksEnable(args[2], sub === 'enable');
+            if (sub === 'delete')
+                return cmd.linksDelete(args[2]);
+            throw new CliError('unknown_command', `There is no command "links ${sub ?? ''}".`, 'Use `c11r links list`, `show <id>`, `create`, `enable <id>`, `disable <id>` or `delete <id>`.');
         case 'orders':
             if (sub === 'test')
                 return cmd.ordersTest(flags, values);