@commercelayer/agent-cli 0.0.0-stage → 0.1.1

package/dist/commands.js

@@ -0,0 +1,201 @@
+// 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, writeCredentials } from './files.js';
+import { fail } from './output.js';
+import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
+import { storefrontHtml } from './storefront.js';
+import { buy } from './ucp/buy.js';
+import { check } from './ucp/check.js';
+import { discover } from './ucp/client.js';
+import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
+export const VERSION = '0.1.0';
+export const HELP = {
+    init: 'Create a sandbox store for this repo, with no login. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
+    plan: 'Show what apply would create, update or delete, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
+    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/. Refuses deletes unless --allow-delete is given.',
+    'storefront init': 'Write storefront/index.html: a static page on drop-in.js listing the products in store.yml, with the hosted cart and checkout. Refuses to overwrite unless --force is given.',
+    'storefront publish': 'Upload the storefront folder (store.yml storefront.path, default storefront) to the sandbox preview URL.',
+    '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.',
+    'orders list': 'List the orders placed in the store, newest first, as UCP order entities.',
+    'orders show': 'Show one order: c11r orders show <id or number>.',
+    '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. Exits 1 when a check fails.',
+    status: 'Show the sandbox, what is applied, and whether store.yml has changes not yet applied.',
+    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.',
+};
+export function help(name) {
+    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, 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() {
+    const existing = readCredentials();
+    if (existing && fs.existsSync(paths.store)) {
+        const s = await createApi(existing).getStore();
+        return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url };
+    }
+    const name = 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');
+    return {
+        status: 'created',
+        org: sandbox.org,
+        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), then run c11r plan.',
+    };
+}
+export async function plan() {
+    const api = createApi(requireCredentials());
+    const desired = loadStore();
+    const state = await api.getStore();
+    const changes = diff(state.applied, desired);
+    return { status: changes.length ? 'changes' : 'up_to_date', changes, deletes: changes.filter((c) => c.action === 'delete').length };
+}
+export async function apply(flags) {
+    const api = createApi(requireCredentials());
+    const desired = loadStore();
+    const state = await api.getStore();
+    const changes = diff(state.applied, desired);
+    const deletes = changes.filter((c) => c.action === 'delete');
+    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`.');
+    }
+    const applied = await api.applyStore({ applied: toApplied(desired), hash: hashStore(), name: desired.name, policies: desired.policies });
+    return {
+        status: 'applied',
+        changes,
+        preview_url: applied.preview_url,
+        markets: desired.markets.length,
+        products: desired.products.length,
+        payment_gateway: 'sandbox (test payments only)',
+    };
+}
+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();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'index.html');
+    fs.writeFileSync(file, storefrontHtml(desired, state.sales_channel_client_id));
+    return {
+        status: 'created',
+        files: [file],
+        markets: desired.markets.map((m) => m.code),
+        products: desired.products.length,
+        next: `Set storefront.path: ${dir} in ${paths.store}, make the page the human's, then run c11r storefront publish.`,
+    };
+}
+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.');
+    }
+    const files = fs
+        .readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((e) => e.isFile())
+        .map((e) => {
+        const full = path.join(e.parentPath, e.name);
+        return { path: path.relative(dir, full).split(path.sep).join('/'), content_base64: fs.readFileSync(full).toString('base64') };
+    });
+    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 };
+}
+/** 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 {
+        status: p.checkout.status === 'completed' ? 'paid' : p.checkout.status,
+        order: p.order,
+        checkout_id: p.checkout.id,
+        messages: p.checkout.messages,
+        payment_handler: 'ai.commercelayer.sandbox (test payments only)',
+        steps: p.steps,
+    };
+}
+export async function ordersList() {
+    const api = createApi(requireCredentials());
+    return { orders: await api.listOrders() };
+}
+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 <id>`.');
+    const api = createApi(requireCredentials());
+    return { order: await api.getOrder(id) };
+}
+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, 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();
+    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),
+        pending_changes: s.applied_hash !== hashStore(),
+        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 })),
+        ucp_profile: `${s.preview_url}/.well-known/ucp`,
+    };
+}
+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`.',
+    };
+}

package/dist/files.js

@@ -0,0 +1,47 @@
+// The files the CLI keeps in the repo: .commercelayer/store.yml and the product
+// files under .commercelayer/products/ (committed), and .commercelayer/credentials
+// (gitignored: the sandbox token).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fail } from './output.js';
+const dir = '.commercelayer';
+export const paths = {
+    dir,
+    store: path.join(dir, 'store.yml'),
+    products: path.join(dir, 'products'),
+    credentials: path.join(dir, 'credentials'),
+};
+export function readCredentials() {
+    if (!fs.existsSync(paths.credentials))
+        return null;
+    const vars = {};
+    for (const line of fs.readFileSync(paths.credentials, 'utf8').split('\n')) {
+        const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        if (m)
+            vars[m[1]] = m[2];
+    }
+    if (!vars.C11R_ORG || !vars.C11R_TOKEN)
+        return null;
+    return { org: vars.C11R_ORG, token: vars.C11R_TOKEN };
+}
+export function writeCredentials(c) {
+    fs.mkdirSync(paths.dir, { recursive: true });
+    fs.writeFileSync(paths.credentials, `C11R_ORG=${c.org}\nC11R_TOKEN=${c.token}\n`, { mode: 0o600 });
+}
+/** The store and its credentials, or a failure telling the agent to run init. */
+export function requireCredentials() {
+    const c = readCredentials();
+    if (!c || !fs.existsSync(paths.store)) {
+        fail('no_store', 'There is no store in this repo.', 'Run `c11r init` in the repo root first.');
+    }
+    return c;
+}
+/** Make sure .gitignore lists the credentials file. Returns true if it changed. */
+export function ignoreCredentials() {
+    const existing = fs.existsSync('.gitignore') ? fs.readFileSync('.gitignore', 'utf8') : '';
+    if (existing.split('\n').includes(paths.credentials))
+        return false;
+    const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+    fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
+    return true;
+}

package/dist/output.js

@@ -0,0 +1,18 @@
+// Everything the CLI says is JSON on stdout: one object per run, pretty-printed.
+// A failure is { error: { code, message, hint } } with exit code 1. The hint is
+// the fix: an agent reads it and acts on it before trying anything else.
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export function fail(code, message, hint) {
+    throw new CliError(code, message, hint);
+}
+export function print(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}

package/dist/products.js

@@ -0,0 +1,128 @@
+// The catalog can be large, so it lives in files under .commercelayer/products/
+// next to (or instead of) the products list in store.yml. Every *.yml file is a
+// list of products in the store.yml shape; every *.csv file is one product per
+// row. All files are merged by sku, and errors name the file they come from.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { paths } from './files.js';
+import { fail } from './output.js';
+/** The fixed CSV columns; any other column named by an ISO 4217 code is a price. */
+export const CSV_COLUMNS = ['sku', 'name', 'description', 'image_url'];
+/** The product files, in a stable order. */
+export function productFiles() {
+    if (!fs.existsSync(paths.products))
+        return [];
+    return fs
+        .readdirSync(paths.products)
+        .filter((f) => /\.(ya?ml|csv)$/i.test(f))
+        .sort()
+        .map((f) => path.join(paths.products, f));
+}
+export function readProductFile(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    const products = /\.csv$/i.test(file) ? fromCsv(file, text) : fromYaml(file, text);
+    return products.map((product) => ({ product, source: file }));
+}
+function fromYaml(file, text) {
+    let doc;
+    try {
+        doc = YAML.parse(text);
+    }
+    catch (e) {
+        const reason = e.message.split('\n')[0];
+        fail('invalid_yaml', `${file} is not valid YAML: ${reason}`, `Fix the YAML syntax in ${file} and run the command again.`);
+    }
+    if (doc === null || doc === undefined)
+        return [];
+    if (Array.isArray(doc))
+        return doc;
+    if (typeof doc === 'object') {
+        const obj = doc;
+        if (Array.isArray(obj.products))
+            return obj.products;
+        if ('sku' in obj)
+            return [obj];
+    }
+    fail('invalid_product', `${file} is not a list of products.`, 'A product file is a YAML list of products, each with sku, name and prices, in the same shape as products in store.yml.');
+}
+/** RFC 4180: quoted cells, doubled quotes, CRLF or LF. Blank lines are skipped. */
+export function parseCsv(text) {
+    const rows = [];
+    let row = [];
+    let cell = '';
+    let quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch === '"') {
+                if (text[i + 1] === '"') {
+                    cell += '"';
+                    i++;
+                }
+                else
+                    quoted = false;
+            }
+            else
+                cell += ch;
+        }
+        else if (ch === '"')
+            quoted = true;
+        else if (ch === ',') {
+            row.push(cell);
+            cell = '';
+        }
+        else if (ch === '\n' || ch === '\r') {
+            if (ch === '\r' && text[i + 1] === '\n')
+                i++;
+            row.push(cell);
+            rows.push(row);
+            row = [];
+            cell = '';
+        }
+        else
+            cell += ch;
+    }
+    if (cell !== '' || row.length) {
+        row.push(cell);
+        rows.push(row);
+    }
+    return rows.filter((r) => !(r.length === 1 && r[0].trim() === ''));
+}
+function fromCsv(file, text) {
+    const rows = parseCsv(text.replace(/^/, ''));
+    if (rows.length === 0)
+        return [];
+    const header = rows[0].map((h) => h.trim());
+    const columns = header.map((h) => {
+        const lower = h.toLowerCase();
+        if (CSV_COLUMNS.includes(lower))
+            return { field: lower };
+        if (/^[A-Z]{3}$/.test(h))
+            return { currency: h };
+        const why = lower === 'stock' ? 'Stock is not part of the catalog: inventory is tracked live in Commerce Layer. ' : '';
+        fail('invalid_product', `${file} has a column "${h}" that is not a product field.`, `${why}CSV columns are ${CSV_COLUMNS.join(', ')} and one column per currency with the price, named by its ISO 4217 code (EUR, USD, ...). Remove or rename the column.`);
+    });
+    if (!columns.some((c) => 'field' in c && c.field === 'sku'))
+        fail('invalid_product', `${file} has no sku column.`, `The first line of a product CSV names its columns: ${CSV_COLUMNS.join(', ')} and one per currency.`);
+    const products = [];
+    rows.slice(1).forEach((cells, i) => {
+        const line = `${file}:${i + 2}`;
+        const product = { sku: '', name: '', prices: {} };
+        columns.forEach((col, j) => {
+            const value = (cells[j] ?? '').trim();
+            if (value === '')
+                return;
+            if ('currency' in col) {
+                const price = Number(value);
+                if (!Number.isFinite(price))
+                    fail('invalid_product', `${line}: ${col.currency} price "${value}" is not a number.`, 'Write prices as plain decimals, such as 14.50, with no currency sign or thousands separator.');
+                product.prices[col.currency] = price;
+            }
+            else
+                product[col.field] = value;
+        });
+        products.push(product);
+    });
+    return products;
+}

package/dist/store.js

@@ -0,0 +1,172 @@
+// .commercelayer/store.yml is the store: the desired state, committed in the repo.
+// Products can also live in files under .commercelayer/products/ (see products.ts).
+// This module reads and validates the whole thing, and diffs it against what the
+// API has applied.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import YAML from 'yaml';
+import { fail } from './output.js';
+import { paths } from './files.js';
+import { productFiles, readProductFile } from './products.js';
+/** The keys a product may have. Stock is not one: inventory lives in Commerce Layer. */
+export const PRODUCT_KEYS = ['sku', 'name', 'description', 'image_url', 'prices'];
+export const template = (name) => `# Commerce Layer store. This file is the store: edit it, then run
+#   c11r plan    to see what will change
+#   c11r apply   to make the change
+# Every product needs a price in the currency of every market.
+
+name: ${name}
+
+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: 5.00, days: 3-5 }
+
+products:
+  # Products go here, or in files under .commercelayer/products/, merged by sku:
+  #   <name>.yml   a list of products in this same shape
+  #   <name>.csv   one product per row, columns: sku, name, description, image_url,
+  #                and one column per currency (EUR, USD, ...) with the price
+  # Use the folder for anything beyond a handful of 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.
+  #   prices: { EUR: 14.50 }
+  # Stock is not part of the catalog: inventory is tracked live in Commerce Layer.
+
+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
+`;
+export function readStoreFile() {
+    return fs.readFileSync(paths.store, 'utf8');
+}
+/** storefront.path from store.yml without validating the rest, default "storefront". */
+export function storefrontPath() {
+    try {
+        const doc = YAML.parse(readStoreFile()) ?? {};
+        return doc.storefront?.path ?? 'storefront';
+    }
+    catch {
+        return 'storefront';
+    }
+}
+/** Every file the store is read from: store.yml and the product files. */
+export function storeFiles() {
+    return [paths.store, ...productFiles()];
+}
+/** A short digest of all the store's files, as they are on disk. The API keeps the one it applied. */
+export function hashStore() {
+    const h = crypto.createHash('sha256');
+    for (const file of storeFiles())
+        h.update(`${file}\n`).update(fs.readFileSync(file)).update('\n');
+    return h.digest('hex').slice(0, 12);
+}
+/** Parse and validate store.yml and the product files, or fail with the fix in the hint. */
+export function loadStore() {
+    let doc;
+    try {
+        doc = YAML.parse(readStoreFile()) ?? {};
+    }
+    catch (e) {
+        const reason = e.message.split('\n')[0];
+        fail('invalid_yaml', `store.yml is not valid YAML: ${reason}`, `Fix the YAML syntax in ${paths.store} and run the command again.`);
+    }
+    const markets = (doc.markets ?? []);
+    if (!Array.isArray(doc.products ?? []))
+        fail('invalid_store', 'products in store.yml is not a list.', 'Write products as a YAML list under `products:`, or move them to files under .commercelayer/products/.');
+    const sourced = (doc.products ?? []).map((product) => ({ product, source: paths.store }));
+    for (const file of productFiles())
+        sourced.push(...readProductFile(file));
+    if (!doc.name)
+        fail('invalid_store', 'store.yml has no name.', `Add \`name: <store name>\` at the top of ${paths.store}.`);
+    if (markets.length === 0)
+        fail('invalid_store', 'store.yml has no markets.', 'Add at least one market under `markets:`, with code, name, countries and currency. See the comments in store.yml.');
+    if (sourced.length === 0)
+        fail('invalid_store', 'The store has no products.', `Add at least one product, with sku, name and prices: under \`products:\` in ${paths.store}, or in a .yml or .csv file under ${paths.products}/. See the comments in store.yml.`);
+    const codes = new Set();
+    for (const m of markets) {
+        for (const key of ['code', 'name', 'countries', 'currency']) {
+            if (!m[key])
+                fail('invalid_market', `Market ${m.code ?? '(no code)'} has no ${key}.`, `Add \`${key}\` to the market in ${paths.store}.`);
+        }
+        if (!/^[A-Z]{3}$/.test(m.currency))
+            fail('invalid_market', `Market ${m.code} has currency "${m.currency}".`, 'Use an ISO 4217 code in capitals, such as EUR or USD.');
+        if (codes.has(m.code))
+            fail('invalid_market', `Two markets have code ${m.code}.`, 'Give every market a unique code.');
+        codes.add(m.code);
+        if (m.shipping !== undefined) {
+            if (!m.shipping.method || typeof m.shipping.price !== 'number' || m.shipping.price < 0) {
+                fail('invalid_market', `Market ${m.code} has an invalid shipping entry.`, 'Use `shipping: { method: <name>, price: <amount in the market currency>, days: <estimate> }`, or remove it for free Standard shipping.');
+            }
+        }
+    }
+    const policies = (doc.policies ?? {});
+    for (const [key, url] of Object.entries(policies)) {
+        if (url && !/^https?:\/\//.test(String(url)))
+            fail('invalid_store', `policies.${key} is not a URL.`, 'Policy entries are full URLs starting with https://, or left out to use the default sandbox pages.');
+    }
+    const currencies = [...new Set(markets.map((m) => m.currency))];
+    const skus = new Map();
+    const products = [];
+    for (const { product: p, source } of sourced) {
+        if (!p || typeof p !== 'object')
+            fail('invalid_product', `${source} has an entry that is not a product.`, 'Every product is a mapping with sku, name and prices.');
+        if (!p.sku || !p.name)
+            fail('invalid_product', `A product in ${source} has no ${p.sku ? 'name' : 'sku'}${p.sku ? ` (sku ${p.sku})` : ''}.`, 'Every product needs a sku and a name.');
+        p.sku = String(p.sku);
+        const seen = skus.get(p.sku);
+        if (seen)
+            fail('invalid_product', `Two products have sku ${p.sku}: in ${seen} and ${source}.`, 'Give every product a unique sku, or remove the duplicate.');
+        skus.set(p.sku, source);
+        const unknown = Object.keys(p).filter((k) => !PRODUCT_KEYS.includes(k));
+        if (unknown.length) {
+            const why = unknown.includes('stock') ? 'Stock is not part of the catalog: inventory is tracked live in Commerce Layer. ' : '';
+            fail('invalid_product', `Product ${p.sku} in ${source} has ${unknown.length === 1 ? 'a field' : 'fields'} not in the catalog: ${unknown.join(', ')}.`, `${why}A product has ${PRODUCT_KEYS.join(', ')}. Remove the other fields.`);
+        }
+        for (const c of currencies) {
+            const price = p.prices?.[c];
+            if (typeof price !== 'number' || price < 0) {
+                fail('missing_price', `Product ${p.sku} in ${source} has no price in ${c}.`, `Add the ${c} price to the product (\`${c}: <amount>\` under prices in YAML, a ${c} column in CSV); every product needs a price in each market's currency (${currencies.join(', ')}).`);
+            }
+        }
+        products.push(p);
+    }
+    return { name: doc.name, markets, products, storefront: doc.storefront, policies };
+}
+export function toApplied(store) {
+    return {
+        markets: Object.fromEntries(store.markets.map((m) => [m.code, m])),
+        products: Object.fromEntries(store.products.map((p) => [p.sku, p])),
+    };
+}
+export function diff(applied, desired) {
+    const changes = [];
+    const after = toApplied(desired);
+    for (const kind of ['markets', 'products']) {
+        const type = kind.slice(0, -1);
+        const before = applied?.[kind] ?? {};
+        for (const id of Object.keys(after[kind])) {
+            if (!(id in before))
+                changes.push({ action: 'create', type, id });
+            else if (JSON.stringify(before[id]) !== JSON.stringify(after[kind][id]))
+                changes.push({ action: 'update', type, id });
+        }
+        for (const id of Object.keys(before))
+            if (!(id in after[kind]))
+                changes.push({ action: 'delete', type, id });
+    }
+    return changes;
+}

package/dist/storefront.js

@@ -0,0 +1,73 @@
+// The storefront scaffold: one static page on drop-in.js listing the products in
+// store.yml, with the hosted cart and checkout. The agent then makes it the human's.
+const esc = (t) => String(t ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+export function storefrontHtml(store, clientId) {
+    const name = esc(store.name);
+    const cards = store.products
+        .map((p) => `      <article class="product">
+${p.image_url ? `        <img src="${esc(p.image_url)}" alt="">\n` : ''}        <h2>${esc(p.name)}</h2>
+${p.description ? `        <p>${esc(p.description)}</p>\n` : ''}        <cl-price code="${esc(p.sku)}"><cl-price-amount type="compare-at"></cl-price-amount> <cl-price-amount type="price"></cl-price-amount></cl-price>
+        <cl-availability code="${esc(p.sku)}"><cl-availability-status type="available">In stock</cl-availability-status><cl-availability-status type="unavailable">Sold out</cl-availability-status></cl-availability>
+        <cl-add-to-cart code="${esc(p.sku)}">Add to cart</cl-add-to-cart>
+      </article>`)
+        .join('\n');
+    const options = store.markets.map((m) => `          <option value="${esc(m.code)}">${esc(m.name)} (${esc(m.currency)})</option>`).join('\n');
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${name}</title>
+  <!-- Commerce Layer drop-in.js: prices, availability, add to cart, and links to the hosted cart and checkout. -->
+  <link href="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/drop-in.css" rel="stylesheet">
+  <script>
+    // The market comes from ?market=<code>; the first market in store.yml is the default. Keep clientId as it is.
+    var market = new URLSearchParams(location.search).get('market') || '${esc(store.markets[0].code)}';
+    window.commercelayerConfig = {
+      clientId: '${esc(clientId)}',
+      scope: 'market:code:' + market,
+      defaultAttributes: { orders: { language_code: 'en', return_url: location.origin + location.pathname } }
+    };
+  </script>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@commercelayer/drop-in.js@2/dist/drop-in/drop-in.esm.js"></script>
+  <style>
+    :root { color-scheme: light; --ink: #16181d; --muted: #5d6572; --line: #e3e6ea; --accent: #1f5eff; }
+    body { margin: 0; font-family: system-ui, sans-serif; color: var(--ink); background: #fff; }
+    header { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 20px 24px; border-bottom: 1px solid var(--line); }
+    header h1 { margin: 0; font-size: 20px; }
+    header nav { display: flex; align-items: center; gap: 16px; }
+    main { max-width: 1100px; margin: 0 auto; padding: 32px 24px; display: grid; gap: 24px; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); }
+    .product { display: flex; flex-direction: column; gap: 8px; padding: 20px; border: 1px solid var(--line); border-radius: 8px; }
+    .product img { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: 6px; }
+    .product h2 { margin: 0; font-size: 17px; }
+    .product p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.5; }
+    cl-price { font-weight: 600; }
+    cl-price-amount[type="compare-at"] { color: var(--muted); font-weight: 400; text-decoration: line-through; }
+    cl-availability { font-size: 13px; color: var(--muted); }
+    cl-add-to-cart { margin-top: auto; }
+    cl-add-to-cart::part(button), cl-checkout-link::part(a) { display: inline-block; padding: 10px 16px; border-radius: 6px; background: var(--accent); color: #fff; font: inherit; border: 0; cursor: pointer; text-decoration: none; }
+    footer { padding: 24px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>${name}</h1>
+    <nav>
+      <label>Market
+        <select onchange="location.search = '?market=' + this.value">
+${options}
+        </select>
+      </label>
+      <cl-cart-link>Cart (<cl-cart-count></cl-cart-count>)</cl-cart-link>
+      <cl-checkout-link>Checkout</cl-checkout-link>
+    </nav>
+  </header>
+  <main>
+${cards}
+  </main>
+  <footer>Sandbox store: test payments only.</footer>
+  <script>document.querySelector('header select').value = market;</script>
+</body>
+</html>
+`;
+}