@commercelayer/agent-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# @commercelayer/agent-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`c11r`, the Commerce Layer CLI for coding agents. An agent reads [commercelayer.ai/start.md](https://commercelayer.ai/start.md), runs this CLI, and the human ends up with a working store in a sandbox: products, prices, a market, a storefront at `<org>.sandbox.commercelayer.store`, and a paid test order. No account needed until they decide to keep it.
+
+Every store speaks the [Universal Commerce Protocol](https://ucp.dev) on its own hostname, so shopping agents can discover it, browse it and buy from it. The CLI itself buys through UCP (`orders test`) and checks the store against the spec (`ucp check`), so what it verifies is what any agent would get.
+
+It is a separate tool from [`@commercelayer/cli`](https://www.npmjs.com/package/@commercelayer/cli), the CLI for humans. The package is `@commercelayer/agent-cli`; the command is `c11r` (c, eleven letters, r), short and unmistakable in an agent's transcript.
+
+```
+npx -y @commercelayer/agent-cli@latest init   # runs c11r init
+```
+
+## The four repos of commercelayer.ai
+
+commercelayer.ai lets a coding agent build and run a store on Commerce Layer. A human pastes one prompt, the agent reads `start.md`, runs the CLI, and the human ends up with a store in a sandbox that both people and shopping agents can buy from. It is four repos, siblings in the same workspace:
+
+| Repo | What it is | Where it runs |
+| --- | --- | --- |
+| `commercelayer-ai-site` | the website and the agent-facing docs: `start.md`, `skills.md`, `skills/*.md`, plus the CLI's UCP platform profile and the sandbox payment-handler schema | commercelayer.ai, Cloudflare Pages |
+| `commercelayer-ai-cli` | `@commercelayer/agent-cli`, the CLI the agent runs as `c11r`: `init`, `plan`, `apply`, `storefront`, `orders test`, `ucp check`, `claim`. Prints JSON only. | npm, in the agent's repo |
+| `commercelayer-ai-api` | the management API the CLI talks to: sandboxes and their life cycle, `apply`, storefront uploads, orders, claims | api.commercelayer.ai, Cloudflare Worker |
+| `commercelayer-ai-store` | the store host: every store's website and its [UCP](https://ucp.dev) merchant endpoints (release 2026-08-25) | `<org>.sandbox.commercelayer.store` and, once live, `<org>.commercelayer.store`, Cloudflare Worker |
+
+**This repo is the CLI.** It owns everything the agent runs: the commands and their JSON, the store files in the agent's repo (`.commercelayer/store.yml` and `.commercelayer/products/`), the drop-in.js storefront scaffold, the UCP buyer and conformance check, and the stub of the whole platform in `src/api/stub/`, which is the reference the API and the store host are ported from. It depends on the API for the management contract in `src/api/types.ts`, on the store host for the UCP surface, and on the site for the platform profile and handler schema it names in `src/ucp/platform.ts`; a change to the stub is mirrored in the API and the store host, and a change to the management contract is mirrored in the API. The site depends on it: every command, flag, file and JSON field the skills describe must exist here, so a change to the commands or the store files is mirrored on the site.
+
+## How it works
+
+- **The repo is the store.** `.commercelayer/store.yml` holds the desired state (name, markets, storefront, policies, and the products of a small store) and is committed; a large catalog goes in `.commercelayer/products/` as `.yml` or `.csv` files. `plan` shows what `apply` would change; `apply` makes the store match the files.
+- **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
+- **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
+- **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `init` | Create a sandbox store, with no login. 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. |
+| `apply [--allow-delete]` | Make the store match the files. Refuses deletes without the flag. |
+| `storefront init [--force]` | Write `storefront/index.html`: a static page on [drop-in.js](https://commercelayer.github.io/drop-in.js/) listing the products in `store.yml`, with the hosted cart and checkout, wired to the sandbox's sales channel. Refuses to overwrite without the flag. |
+| `storefront publish` | Upload the folder at `storefront.path` (default `storefront`) to the store host. |
+| `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 and every step. |
+| `orders list` | The orders placed in the store, newest first, as UCP order entities. |
+| `orders show <id or number>` | One order. |
+| `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
+| `ucp check` | Walk every UCP capability the store advertises and report what passes. Exits 1 on a failed check. |
+| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, pending changes, orders, the UCP profile URL. |
+| `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
+| `help [<command>]` | Describe the commands. `--version` prints the version. |
+
+## store.yml
+
+`init` writes a commented template. A filled-in store looks like this:
+
+```yaml
+name: Beans
+
+markets:
+  # One market per region you sell in. countries are ISO 3166 codes.
+  # shipping is optional: without it orders ship free as "Standard".
+  - code: eu
+    name: Europe
+    countries: [IT, FR, DE, ES]
+    currency: EUR
+    shipping: { method: Standard, price: 4.90, days: 3-5 }
+  - code: us
+    name: United States
+    countries: [US]
+    currency: USD
+
+products:
+  # sku is unique and stays the same when you rename a product.
+  - sku: COFFEE-ETH-250
+    name: Ethiopia Yirgacheffe, 250 g
+    description: Washed, floral, bright.
+    image_url: https://example.com/eth.jpg
+    prices: { EUR: 14.50, USD: 16.00 }
+
+storefront:
+  # The web app in this repo that sells the products, relative to the repo root.
+  path: storefront
+
+policies:
+  # Pages shopping agents show buyers before they pay. Without them the store
+  # serves default sandbox pages at <preview_url>/policies/<name>.
+  privacy_policy: https://example.com/privacy
+  terms_of_service: https://example.com/terms
+  returns: https://example.com/returns
+```
+
+### 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:
+
+- `<name>.yml`: a list of products in the shape above (one file per collection, or one per product, as you like).
+- `<name>.csv`: one product per row. The first line names the columns: `sku`, `name`, `description`, `image_url`, and one column per currency, named by its ISO 4217 code, holding the price. Quoted cells and CRLF are fine; empty cells are left out.
+
+```csv
+sku,name,description,EUR,USD
+COFFEE-ETH-250,"Ethiopia Yirgacheffe, 250 g","Washed, floral, bright.",14.50,16.00
+COFFEE-COL-250,"Colombia Huila, 250 g",,12.00,13.50
+```
+
+Errors name the file (and line, for CSV) and the sku, so one product file can be fixed without reading the rest. Moving a product between `store.yml` and a file is not a change to the store: `plan` keys everything by sku. The catalog has no stock: inventory is tracked live in Commerce Layer, and the sandbox treats every product as in stock. Prices in these files are what the store charges; a published storefront reads prices and availability live from Commerce Layer.
+
+Rules `plan` and `apply` enforce: a name, at least one market and one product; every market has `code`, `name`, `countries` and an ISO 4217 `currency`; codes and skus are unique across all files; a product has only `sku`, `name`, `description`, `image_url` and `prices`; every product has a price in the currency of every market; `shipping`, if present, has `method` and a non-negative `price`; policy entries are URLs. Currency, languages and tax follow from the countries.
+
+Error codes: `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `storefront_exists`, `no_storefront`, `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 |
+| --- | --- |
+| Business profile | `GET /.well-known/ucp` (`Cache-Control: public, max-age=300`, ES256 public key in `keys[]`) |
+| Shopping service `dev.ucp.shopping` | `/ucp/v1`: `POST /catalog/search`, `POST /catalog/lookup`, `POST /catalog/product`, `POST /carts`, `GET/PUT /carts/{id}`, `POST /carts/{id}/cancel`, `POST /checkout-sessions`, `GET/PUT /checkout-sessions/{id}`, `POST /checkout-sessions/{id}/complete`, `POST /checkout-sessions/{id}/cancel`, `GET /orders/{id}` |
+| Common service `dev.ucp.common` | `/ucp/v1`: `POST /ask` |
+| Extensions | `dev.ucp.shopping.fulfillment` (one shipping method per market, from `shipping` in `store.yml`), `dev.ucp.shopping.discount` (the sandbox accepts code `SANDBOX10`, 10% off the items), `dev.ucp.shopping.buyer_consent`, `dev.ucp.shopping.policy.return` (30-day returns) |
+| Identity linking `dev.ucp.common.identity_linking` | `GET /.well-known/oauth-authorization-server`, `GET /oauth/authorize` (PKCE S256; the sandbox approves at once), `POST /oauth/token` (`authorization_code`, `client_credentials`), `POST /oauth/revoke`, `GET /oauth/jwks`. Scopes `dev.ucp.shopping.order:read`, `dev.ucp.shopping.order:manage`. |
+| Permalink `dev.ucp.shopping.permalink` | `GET /buy/{sku}:{qty}[,...]?context/postal_code=…&discounts/codes/0=…` → `303` to the cart |
+| Payment handler `ai.commercelayer.sandbox` | id `cl_sandbox`, `card` instruments, credential `{ "type": "sandbox_token", "token": "sbx_tok_success" \| "sbx_tok_declined", "expiry": … }`. No money moves. |
+| Pages | `/policies/{privacy,terms,returns}` (defaults when `store.yml` has no `policies`), `/carts/{id}`, `/checkout-sessions/{id}` (`continue_url`), `/orders/{id}` (`permalink_url`), and the published storefront at `/`. |
+
+Transport rules the store enforces: `UCP-Agent` (an HTTPS platform profile URL) and `Request-Id` on every request; `Idempotency-Key` on every state change, replayed when the body matches and `409` when it does not; `Content-Digest` verified when present. Every service response carries `Content-Digest`, `Signature-Input` and `Signature` (ES256 over `@status`, `content-digest`, `content-type`, key `kid` from the profile). Orders are private: readable by the platform that placed them or with a buyer token carrying an order scope; anything else gets `401` with `WWW-Authenticate: Bearer`. Catalog ids are the skus (`product.id` is `prod_<sku>`, `variant.id` is the sku); amounts are integers in minor units.
+
+The CLI is a UCP **platform**: its profile is served at `https://commercelayer.ai/ucp/agent-cli/profile.json` (`ucp profile --agent` prints it) and goes in `UCP-Agent` on every call. The store negotiates the capability intersection with it. `orders test` is the buyer; `ucp check` runs 30-odd checks across profile, transport rules, catalog, cart, discount, checkout, fulfillment, consent, payment, signatures, idempotency, order, identity linking, ask and permalink.
+
+## The management API
+
+The CLI keeps no state of its own: the store lives behind `api.commercelayer.ai` (the `commercelayer-ai-api` Worker) and the store hosts (the `commercelayer-ai-store` Worker). This repo ships a stub of the whole platform with the same routes, which both Workers are ported from and tested against. `src/api/types.ts` is the management contract; `src/api/stub/management.ts` is the reference for the API, and `src/api/stub/ucp.ts` and `shopping.ts` are the reference for the store host. A change to the stub is mirrored in the Worker it belongs to.
+
+| Route | Auth | Does |
+| --- | --- | --- |
+| `POST /sandboxes` `{ name }` | none | Create a sandbox with one sales channel and one signing key. Returns `org`, `token`, `claim_url`, `expires_at`, `preview_url`, `sales_channel_client_id`. |
+| `GET /stores/:org` | bearer | The store: `applied`, `applied_hash`, `orders` (UCP entities, newest first), `storefront`, `sales_channel_client_id`, `claimed`, `expires_at`, `preview_url`, `claim_url`. |
+| `PUT /stores/:org/resources` `{ applied, hash, name, policies }` | bearer | Make the store match the resources (markets by code, products by sku). `hash` digests every store file on disk; `status` compares it to report pending changes. Market scopes are `market:code:<code>`. |
+| `PUT /stores/:org/storefront` `{ path, files: [{ path, content_base64 }] }` | bearer | Replace the static files served at the store host. `422 no_storefront` without an `index.html`. Returns `{ path, files, published_at }`. (The real API should take a `tar.gz` body with a size cap; base64 JSON is fine for the sandbox.) |
+| `GET /stores/:org/orders` | bearer | The orders, newest first. |
+| `GET /stores/:org/orders/:id` | bearer | One order, by id or label number, or `404 not_found`. |
+| `POST /stores/:org/claim` | bearer | Start the device flow: `verification_url`, `user_code`. |
+
+Errors come back as `{ "error": { "code", "message", "hint" } }` with 4xx/5xx and are printed as they are.
+
+`C11R_API_URL` picks the platform:
+
+- unset: `https://api.commercelayer.ai` and the real store hosts
+- `stub`: the stub in-process, state in `~/.local/state/c11r/stub-api.json` (or `$C11R_STUB_DB`). No server to run; what agent tests use.
+- `http://localhost:4747`: the stub over HTTP (`npm run stub-api`), to exercise the real client. Store hosts are reached as `http://localhost:4747/-/<org>.sandbox.commercelayer.store/...` or with a `Host` header.
+
+## Development
+
+```
+npm install
+npm run dev -- help              # run from source
+npm test                         # build, then end-to-end tests against the in-process stub
+npm run stub-api                 # serve the stub platform on :4747
+```
+
+Node 20 or later, one runtime dependency (`yaml`). Source in `src/`: `bin.ts` parses arguments, `commands.ts` has one function per command, `store.ts` validates and diffs the store, `products.ts` reads the product files (YAML and CSV), `files.ts` handles the files in the repo, `storefront.ts` is the drop-in.js scaffold; `api/` is the management client, its contract, the transport and the stub (`stub/management.ts`, `stub/ucp.ts`, `stub/shopping.ts`); `ucp/` is the UCP side: `platform.ts` (this CLI's profile and shared constants), `client.ts` (discovery and the REST calls), `signing.ts` (RFC 9421/9530), `buy.ts` (the buyer flow), `check.ts` (the conformance walk).

package/dist/api/client.js

@@ -0,0 +1,39 @@
+// The client for the management API at api.commercelayer.ai.
+import { 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(/\/$/, '');
+    const org = () => {
+        if (!auth)
+            fail('no_store', 'There is no store in this repo.', 'Run `c11r init` in the repo root first.');
+        return `/stores/${auth.org}`;
+    };
+    const request = async (method, path, body) => {
+        const headers = { accept: 'application/json' };
+        if (auth)
+            headers.authorization = `Bearer ${auth.token}`;
+        const res = await send(method, base + path, headers, body === undefined ? undefined : JSON.stringify(body));
+        let data;
+        try {
+            data = res.body ? JSON.parse(res.body) : null;
+        }
+        catch {
+            fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, report it at https://commercelayer.ai/support with the output of `c11r status`.');
+        }
+        if (res.status < 400)
+            return data;
+        const err = data?.error;
+        if (err)
+            fail(err.code, err.message, err.hint);
+        fail('api_error', `The API answered ${res.status}.`, 'Try again. If it keeps happening, report it at https://commercelayer.ai/support with the output of `c11r status`.');
+    };
+    return {
+        createSandbox: (name) => request('POST', '/sandboxes', { name }),
+        getStore: () => request('GET', org()),
+        applyStore: (body) => request('PUT', `${org()}/resources`, body),
+        publishStorefront: (path, files) => request('PUT', `${org()}/storefront`, { path, files }),
+        listOrders: () => request('GET', `${org()}/orders`),
+        getOrder: (id) => request('GET', `${org()}/orders/${encodeURIComponent(id)}`),
+        startClaim: () => request('POST', `${org()}/claim`),
+    };
+}

package/dist/api/server.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Serve the stub platform over HTTP, so the CLI's real HTTP client can be exercised:
+//   npm run stub-api                       (port 4747)
+//   C11R_API_URL=http://localhost:4747 c11r init
+// Store hosts are reached as http://localhost:4747/-/<org>.sandbox.commercelayer.store/...
+// or with a real Host header.
+import http from 'node:http';
+import { handle } from './stub/index.js';
+const port = Number(process.env.PORT ?? 4747);
+http
+    .createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => (raw += chunk));
+    req.on('end', () => {
+        const headers = {};
+        for (const [k, v] of Object.entries(req.headers))
+            if (typeof v === 'string')
+                headers[k.toLowerCase()] = v;
+        const host = headers.host ?? `localhost:${port}`;
+        const url = new URL(req.url ?? '/', `http://${host}`);
+        const { status, headers: resHeaders, body } = handle({ method: req.method ?? 'GET', url, headers, body: raw || undefined });
+        res.writeHead(status, resHeaders);
+        res.end(body);
+    });
+})
+    .listen(port, () => console.log(`stub platform on http://localhost:${port}`));

package/dist/api/stub/db.js

@@ -0,0 +1,37 @@
+// The stub's state: one JSON file, one record per sandbox. The real platform keeps
+// the same data behind api.commercelayer.ai and the store hosts.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const dbFile = process.env.C11R_STUB_DB
+    ?? path.join(process.env.XDG_STATE_HOME ?? path.join(os.homedir(), '.local', 'state'), 'c11r', 'stub-api.json');
+export function readDb() {
+    return fs.existsSync(dbFile) ? JSON.parse(fs.readFileSync(dbFile, 'utf8')) : {};
+}
+export function writeDb(db) {
+    fs.mkdirSync(path.dirname(dbFile), { recursive: true });
+    fs.writeFileSync(dbFile, JSON.stringify(db, null, 2) + '\n');
+}
+export const SANDBOX_DOMAIN = 'sandbox.commercelayer.store';
+/** The org a store hostname belongs to, or null if it is not a store host. */
+export function orgOfHost(hostname) {
+    const m = hostname.match(/^([a-z0-9-]+)\.sandbox\.commercelayer\.store$/);
+    return m ? m[1] : null;
+}
+/** Orders of a store, newest first, without private members. */
+export function publicOrders(r) {
+    return Object.values(r.ucp.orders).map((o) => strip(o)).reverse();
+}
+/** A deep copy without the members whose name starts with _. */
+export function strip(value) {
+    if (Array.isArray(value))
+        return value.map(strip);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            if (!k.startsWith('_'))
+                out[k] = strip(v);
+        return out;
+    }
+    return value;
+}

package/dist/api/stub/http.js

@@ -0,0 +1,18 @@
+// The HTTP shapes the stub works with: what a Cloudflare Worker would see. Keeping
+// the stub HTTP-shaped lets UCP headers (UCP-Agent, Idempotency-Key, signatures)
+// be modelled the way the real API will have to handle them.
+export function json(status, body, headers = {}) {
+    return { status, headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body) };
+}
+/** The management API's error shape, the same the CLI prints. */
+export function error(status, code, message, hint) {
+    return json(status, { error: { code, message, hint } });
+}
+export function readJson(req) {
+    if (!req.body)
+        return undefined;
+    return JSON.parse(req.body);
+}
+export function bearer(req) {
+    return req.headers.authorization?.replace(/^Bearer /i, '');
+}

package/dist/api/stub/index.js

@@ -0,0 +1,27 @@
+// A stand-in for the whole platform: api.commercelayer.ai (management) and
+// <org>.sandbox.commercelayer.store (the store: UCP, OAuth, the storefront).
+// server.ts serves it over HTTP; transport.ts calls handle() in-process when
+// C11R_API_URL=stub, so agent tests need no server running.
+//
+// Routing is by hostname. Over local HTTP, where subdomains do not resolve, the
+// path prefix /-/<host>/... stands in for the hostname.
+import { orgOfHost, readDb, writeDb } from './db.js';
+import { json } from './http.js';
+import { handleManagement } from './management.js';
+import { handleUcp } from './ucp.js';
+export function handle(req) {
+    let url = req.url;
+    const prefixed = url.pathname.match(/^\/-\/([^/]+)(\/.*)?$/);
+    if (prefixed)
+        url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
+    const org = orgOfHost(url.hostname);
+    if (org === null)
+        return handleManagement({ ...req, url });
+    const db = readDb();
+    const store = db[org];
+    if (!store)
+        return json(404, { error: { code: 'not_found', message: `There is no store at ${url.hostname}.`, hint: 'The sandbox may have expired.' } });
+    const res = handleUcp({ ...req, url }, store);
+    writeDb(db);
+    return res;
+}

package/dist/api/stub/management.js

@@ -0,0 +1,86 @@
+// The management API at api.commercelayer.ai: sandboxes, resources, storefront
+// uploads, orders, claims. The CLI's only private API; the store hosts speak UCP.
+import crypto from 'node:crypto';
+import { generateKey } from '../../ucp/signing.js';
+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, name: _name, policies: _policies, ...state } = r;
+    return { ...state, orders: publicOrders(r) };
+}
+export function handleManagement(req) {
+    const db = readDb();
+    const path = req.url.pathname;
+    if (req.method === 'POST' && path === '/sandboxes') {
+        const name = String(readJson(req)?.name ?? 'store');
+        const slug = `${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'store'}-${crypto.randomBytes(2).toString('hex')}`;
+        const expires = new Date(Date.now() + 7 * 24 * 3600 * 1000);
+        expires.setUTCHours(0, 0, 0, 0);
+        const kid = `${slug}-${new Date().toISOString().slice(0, 7)}`;
+        const { privateJwk, publicJwk } = generateKey(kid);
+        const record = {
+            org: slug,
+            token: `sbx_${crypto.randomBytes(16).toString('hex')}`,
+            sandbox: true,
+            claimed: false,
+            claim_url: `https://commercelayer.ai/claim/${crypto.randomBytes(6).toString('hex')}`,
+            expires_at: expires.toISOString(),
+            preview_url: `https://${slug}.${SANDBOX_DOMAIN}`,
+            sales_channel_client_id: `sc_${crypto.randomBytes(12).toString('hex')}`,
+            storefront: null,
+            applied: null,
+            applied_hash: null,
+            ucp: { kid, private_jwk: privateJwk, public_jwk: publicJwk, carts: {}, checkouts: {}, orders: {}, idempotency: {}, webhooks: [], tokens: {}, codes: {}, files: {} },
+        };
+        db[slug] = record;
+        writeDb(db);
+        const { org, token, claim_url, expires_at, preview_url, sales_channel_client_id } = record;
+        return json(201, { org, token, claim_url, expires_at, preview_url, sales_channel_client_id });
+    }
+    const m = path.match(/^\/stores\/([^/]+)(\/.*)?$/);
+    if (!m)
+        return error(404, 'not_found', `No route ${req.method} ${path}.`, 'Check the command; run `c11r help`.');
+    const [, org, rest = ''] = m;
+    const record = db[org];
+    if (!record || record.token !== bearer(req)) {
+        return error(401, 'unauthorized', `No sandbox ${org} for this token.`, 'The sandbox may have expired or the credentials file may be stale. Remove .commercelayer/credentials and run `c11r init` again.');
+    }
+    if (new Date(record.expires_at) < new Date() && !record.claimed) {
+        return error(410, 'expired', `Sandbox ${org} expired on ${record.expires_at}.`, 'Remove .commercelayer/credentials and run `c11r init` to create a new sandbox; store.yml is kept.');
+    }
+    if (req.method === 'GET' && rest === '')
+        return json(200, publicState(record));
+    if (req.method === 'PUT' && rest === '/resources') {
+        const { applied, hash, name, policies } = readJson(req);
+        record.applied = applied;
+        record.applied_hash = hash;
+        record.name = name;
+        record.policies = policies ?? {};
+        writeDb(db);
+        return json(200, publicState(record));
+    }
+    if (req.method === 'PUT' && rest === '/storefront') {
+        const { path: dir, files } = readJson(req);
+        if (!files?.some((f) => f.path === 'index.html')) {
+            return error(422, 'no_storefront', 'The upload has no index.html.', 'Run `c11r storefront init` to create one, or set storefront.path in store.yml to the folder that has index.html.');
+        }
+        record.ucp.files = Object.fromEntries(files.map((f) => [f.path, f.content_base64]));
+        record.storefront = { path: dir, files: files.length, published_at: new Date().toISOString() };
+        writeDb(db);
+        return json(200, record.storefront);
+    }
+    if (req.method === 'GET' && rest === '/orders')
+        return json(200, publicOrders(record));
+    const one = rest.match(/^\/orders\/([^/]+)$/);
+    if (req.method === 'GET' && one) {
+        const wanted = decodeURIComponent(one[1]);
+        const found = publicOrders(record).find((o) => o.id === wanted || o.label === wanted || o.label === `#${wanted}`);
+        if (!found)
+            return error(404, 'not_found', `There is no order ${wanted}.`, 'Run `c11r orders list` to see the orders.');
+        return json(200, found);
+    }
+    if (req.method === 'POST' && rest === '/claim') {
+        return json(200, { verification_url: 'https://commercelayer.ai/device', user_code: 'BXQT-4KMF' });
+    }
+    return error(404, 'not_found', `No route ${req.method} ${path}.`, 'Check the command; run `c11r help`.');
+}