@commercelayer/agent-cli 0.2.2 → 0.2.5

package/dist/commands.js

@@ -4,13 +4,15 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createApi } from './api/client.js';
-import { ignoreCredentials, paths, readCredentials, requireCredentials, writeCredentials } from './files.js';
+import { ignoreCredentials, paths, readCredentials, requireCredentials, writeAgentNotes, writeCredentials } from './files.js';
 import { CliError, fail, progress } from './output.js';
 import { diff, hashStore, loadStore, storefrontPath, template, toApplied } from './store.js';
 import { storefrontFiles } from './storefront.js';
 import { imageNotes, planAssets, uploadAssets } from './assets.js';
 import { pull } from './catalog.js';
-import { ACTIVE_LIMIT, activeWithoutCoupon } from './promotions.js';
+import { checkLink } from './links.js';
+import { ACTIVE_LIMIT, activeWithoutCoupon, checkPromotion } from './promotions.js';
+import YAML from 'yaml';
 import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
@@ -19,13 +21,26 @@ import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
 /** The package version, read from package.json so a release bumps it in one place. */
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
 export const HELP = {
-    init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials. Reuses the store if store.yml already exists.',
-    plan: 'Show 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 (Commerce Layer applies 10); missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
-    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, promotions, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes (products, promotions) unless --allow-delete is given. Flex promotions need the Rules Engine: on an organization without it apply stops with flex_unavailable and applies nothing. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
+    init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials, and a section in AGENTS.md and CLAUDE.md (created, or appended once) that points later agents in this repo to the skills: commit them. Reuses the store if store.yml already exists.',
+    plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku).',
+    apply: 'Make the store match .commercelayer/store.yml and .commercelayer/products/: markets, products, the theme (its settings, and the images in .commercelayer/img/ that the theme and products reference, uploaded when new or changed), name and policies. The store\'s website is live at preview_url after apply. Refuses deletes unless --allow-delete is given. Product changes go through a Commerce Layer import: apply waits for it (progress as JSON lines on stderr) and prints one result; if it stops with apply_pending the import keeps going, so run `c11r status` to follow it. While Commerce Layer is busy or unavailable it keeps reading, with a retrying line. An apply still running is finished first. --full re-imports every product and price, after edits in the Commerce Layer dashboard.',
     'catalog pull': 'Read the products from the catalog source in store.yml (catalog: { source: supabase | sheets | merchant, url, table }) and write them to .commercelayer/products/catalog.csv; then plan and apply as usual. Columns: sku, name, description, image_url, category and one price column per market currency, in lowercase (eur, usd). Supabase reads C11R_SUPABASE_URL and C11R_SUPABASE_KEY (the anon key) from .commercelayer/credentials or the environment; a Google Sheet needs its CSV link or a link anyone can open; a Merchant Center feed is RSS/XML or TSV.',
     'storefront init': 'Custom storefronts only: the hosted theme needs none of this (set theme: in store.yml and apply). Write a static storefront on drop-in.js, no build step: storefront/index.html (the products by category, a minicart that opens on add to cart, the hosted cart and checkout, and a product page at #/p/<sku>), styles.css (theme tokens first) and app.js. Product images are the store\'s, at /img/ (.commercelayer/img/, uploaded by apply); the site\'s own files go in storefront/assets/. Refuses to overwrite unless --force is given.',
     'storefront check': 'Custom storefronts only. Check the published storefront at the preview URL: drop-in.js and its config block wired to this store, the drop-in elements, an add to cart for every product, every image loading, alt text, stylesheets after drop-in.css, the theme tokens and drop-in overrides, title, lang, viewport, description, and whether the folder changed since publish. Prints { status, summary, checks: [{ id, kind, status: pass|warn|fail, message, fix, items }] }; exits 1 when a check fails.',
     'storefront publish': 'Custom storefronts only: upload the storefront folder (store.yml storefront.path, default storefront) to the preview URL, where it replaces the hosted theme.',
+    'promotions list': 'The store\'s promotions, live in Commerce Layer (not in store files): id, name, status (active, scheduled, expired, disabled, used_up), rules, actions, uses, starts, ends; managed: false marks one made in the dashboard (its id is Commerce Layer\'s), which can be enabled, disabled or deleted but not updated. warnings flags more than 10 active promotion actions without a coupon (Commerce Layer applies 10).',
+    'promotions show': 'One promotion by id, as list shows it: c11r promotions show <id>.',
+    'promotions create': "Create a promotion from a spec in YAML or JSON, on stdin (c11r promotions create <<'EOF' ... EOF) or with -f <file>: { id, name, market, starts, ends, limit, priority, exclusive, enabled, rules: [{ coupon | order_amount: { min } | skus | category }], actions: [{ percentage | fixed_amount | free_shipping | fixed_price | free_gift | buy_x_pay_y }] } or flex: { rules } in place of rules and actions. id is the handle, unique. Amounts are in the market currency, in major units. A category becomes the skus of its products in store.yml now: after adding products to it, run update again. Errors: invalid_promotion (the message starts with the path in the spec), promotion_exists, flex_unavailable (no Rules Engine: nothing is created). Check it with orders test --code.",
+    'promotions update': 'Replace a promotion with a whole spec, same as create, on stdin or -f <file>: c11r promotions update <id>. The id stays the same. What show prints can be edited and sent back. A promotion made in the dashboard (managed: false) cannot be updated: promotion_not_managed; enable, disable and delete work on it.',
+    'promotions enable': 'Turn a promotion on: c11r promotions enable <id>.',
+    'promotions disable': 'Turn a promotion off without deleting it: c11r promotions disable <id>.',
+    'promotions delete': 'Delete a promotion from Commerce Layer: c11r promotions delete <id>. Ask the human first; to pause one, disable it.',
+    'links list': 'The store\'s links, live in Commerce Layer (not in store files): shareable URLs that open a hosted microstore for one sku, a set of skus or a category, or the hosted checkout for an order. For each: id, name, url, status (pending, active, expired, disabled), for (sku | skus | category with its skus | order), markets, starts, ends, params; managed: false marks one made in the dashboard (its id is Commerce Layer\'s).',
+    'links show': 'One link by id, as list shows it: c11r links show <id>.',
+    'links create': "Create a link from a spec in YAML or JSON, on stdin (c11r links create <<'EOF' ... EOF) or with -f <file>: { id, name, for: { sku } | { skus: [...] } | { category: \"A > B\" } | { order: <number> | cart_<id> | chk_<id> }, market (a code or a list; default every market; none for an order), starts (default now), ends (default a month after starts), params }. id is the handle, unique. A category becomes the skus of its products in store.yml now (at most 100 skus). An order link opens the checkout of a draft or pending order: its number, or the id of a UCP cart or checkout. One Commerce Layer link per market: urls has each, url the first market's. A link cannot be changed: delete it and create it again. Errors: invalid_link (the message starts with the path in the spec), link_exists.",
+    'links enable': 'Turn a link on: c11r links enable <id>.',
+    'links disable': 'Turn a link off without deleting it: its url stops opening. c11r links disable <id>.',
+    'links delete': 'Delete a link from Commerce Layer: c11r links delete <id>. Ask the human first; to pause one, disable it.',
     'orders test': 'Buy from the store over UCP as a shopping agent would, paying with the sandbox handler: discover, search, checkout, address, pay, read the order. Options: --sku <id> --quantity <n> --country <CC> --code <discount> --via-cart --decline. discounts lists what promotions and codes took off; a code that applied nothing is a discount_code_invalid warning in messages.',
     '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>.',
@@ -54,7 +69,8 @@ export async function init(values) {
     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 notes = writeAgentNotes();
+        return { status: 'reused', org: s.org, claim_url: s.claim_url, expires_at: s.expires_at, preview_url: s.preview_url, files: notes.length ? notes : undefined };
     }
     // The business name becomes the organization's name; the platform derives the
     // org slug (and so the store hostname) from it. The folder name is the fallback.
@@ -69,6 +85,7 @@ export async function init(values) {
     const files = [paths.store, paths.credentials];
     if (ignoreCredentials())
         files.push('.gitignore');
+    files.push(...writeAgentNotes());
     return {
         status: 'created',
         org: sandbox.org,
@@ -80,16 +97,6 @@ export async function init(values) {
         next: 'Describe the store in .commercelayer/store.yml (products there or in .commercelayer/products/*.yml|csv, the theme under theme:, images in .commercelayer/img/), then run c11r plan and c11r apply: the website is live at preview_url.',
     };
 }
-/** Warnings plan and apply give about promotions: the active limit, and an API without them. */
-function promotionWarnings(state, desired) {
-    const out = [];
-    if (desired.promotions.length && state.promotions === undefined)
-        out.push('This API does not apply promotions yet: apply will refuse while store.yml has any.');
-    const active = activeWithoutCoupon(desired.promotions);
-    if (active.count > ACTIVE_LIMIT)
-        out.push(`${active.count} promotions without a coupon are active (one per action, in ${active.ids.join(', ')}): Commerce Layer applies at most ${ACTIVE_LIMIT}, the ones with the lowest priority number. Give the rest a coupon, end dates, or enabled: false.`);
-    return out.length ? out : undefined;
-}
 export async function plan() {
     const api = createApi(requireCredentials());
     const desired = loadStore();
@@ -101,7 +108,6 @@ export async function plan() {
         changes,
         deletes: changes.filter((c) => c.action === 'delete' && c.type !== 'asset').length,
         ...imageNotes(assets),
-        warnings: promotionWarnings(state, desired),
         next: assets.missing.length ? 'Put the missing images in .commercelayer/img/ (img/<file> in store.yml is .commercelayer/img/<file>), or fix the references: apply refuses until they are there.' : undefined,
     };
 }
@@ -160,9 +166,6 @@ export async function apply(flags) {
     if (assets.missing.length) {
         fail('missing_images', `The store references images that are not in .commercelayer/img/: ${assets.missing.join('; ')}.`, 'Put the files there (img/<file> in store.yml is .commercelayer/img/<file>), or fix or remove the references, then apply again.');
     }
-    if (desired.promotions.length && state.promotions === undefined) {
-        fail('promotions_unsupported', 'This API does not apply promotions yet.', 'Remove promotions: from store.yml to apply the rest, or update c11r (npx @commercelayer/agent-cli@latest) and try again.');
-    }
     // Images first, so the theme and products never point at a file the store host does not have yet.
     const uploaded = assets.supported ? await uploadAssets(api, assets) : 0;
     const body = {
@@ -171,7 +174,6 @@ export async function apply(flags) {
         name: desired.name,
         policies: desired.policies,
         theme: desired.theme ?? {},
-        promotions: desired.promotions,
         ...(assets.supported && { assets: assets.keep }),
         ...(flags.has('--allow-delete') && { allow_delete: true }),
         ...(flags.has('--full') && { full: true }),
@@ -181,10 +183,9 @@ export async function apply(flags) {
     const done = job ? await follow(api, started) : started;
     if (job && done.apply?.id === job.id && done.apply.status === 'failed') {
         const errors = done.apply.errors;
-        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.promotion && !e.message.startsWith(`promotion ${e.promotion}:`) ? `promotion ${e.promotion}: ${e.message}` : e.message)).join('; ');
-        const promos = errors.filter((e) => e.promotion && !e.sku).length;
-        const what = errors.length === 1 ? (promos ? '1 promotion was refused' : '1 product was refused') : promos === errors.length ? `${errors.length} promotions were refused` : promos ? `${errors.length} items were refused` : `${errors.length} products were refused`;
-        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', `Fix ${promos ? 'them' : 'those products'} in store.yml${promos ? '' : ' or the catalog source'} and run \`c11r apply\` again; the rest of the store is unchanged.`);
+        const list = errors.map((e) => (e.sku ? `${e.sku}: ${e.message}` : e.message)).join('; ');
+        const what = errors.length === 1 ? '1 product was refused' : `${errors.length} products were refused`;
+        fail('apply_failed', errors.length ? `${what}: ${list}` : 'The apply failed in Commerce Layer.', 'Fix those products in store.yml or the catalog source and run `c11r apply` again; the rest of the store is unchanged.');
     }
     return {
         status: 'applied',
@@ -192,8 +193,6 @@ export async function apply(flags) {
         preview_url: done.preview_url,
         markets: desired.markets.length,
         products: desired.products.length,
-        promotions: desired.promotions.length || undefined,
-        warnings: promotionWarnings(state, desired),
         payment_gateway: 'sandbox (test payments only)',
         images_uploaded: uploaded || undefined,
         unused_images: assets.unused.length ? assets.unused : undefined,
@@ -355,3 +354,137 @@ export async function claim() {
         next: 'Ask the human to open verification_url and enter user_code, then run `c11r status`.',
     };
 }
+// ---------- promotions: live settings in Commerce Layer, not store files
+/** What list and show print beyond the spec: dropped when it is sent back. */
+const READ_ONLY = ['status', 'uses', 'managed', 'url', 'urls', 'created_at'];
+/**
+ * A spec from -f <file> or stdin, YAML or JSON, for promotions and links. What show prints
+ * can be edited and sent back: the read-only fields are dropped.
+ */
+async function readInput(values, what) {
+    const usage = `Give the ${what} as YAML or JSON on stdin (c11r ${what}s create <<'EOF' ... EOF) or with -f <file>.`;
+    let text = '';
+    if (values.file) {
+        if (!fs.existsSync(values.file))
+            fail('missing_argument', `There is no file ${values.file}.`, `Give the ${what} as YAML or JSON with -f <file>, or on stdin.`);
+        text = fs.readFileSync(values.file, 'utf8');
+    }
+    else if (!process.stdin.isTTY) {
+        // A stream read: readFileSync(0) fails with EAGAIN on a pipe whose writer is still running.
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        text = Buffer.concat(chunks).toString('utf8');
+    }
+    else
+        fail('missing_argument', `No ${what} given.`, usage);
+    if (!text.trim())
+        fail('missing_argument', `No ${what} given: the input is empty.`, usage);
+    let raw;
+    try {
+        raw = YAML.parse(text);
+    }
+    catch (e) {
+        fail(`invalid_${what}`, `${what}: not valid YAML or JSON: ${e.message.split('\n')[0]}`, 'Fix the syntax and run the command again.');
+    }
+    if (raw && typeof raw === 'object' && !Array.isArray(raw))
+        for (const k of READ_ONLY)
+            delete raw[k];
+    return raw;
+}
+/** A promotion spec, validated against store.yml's markets and products. */
+async function readSpec(values) {
+    const raw = await readInput(values, 'promotion');
+    const store = loadStore();
+    return checkPromotion(raw, store.markets, store.products);
+}
+/** Warn when more promotion actions without a coupon are live than Commerce Layer applies. */
+async function activeWarning(api) {
+    const { promotions } = await api.listPromotions();
+    const live = promotions.filter((p) => p.status === 'active' || p.status === 'scheduled');
+    const active = activeWithoutCoupon(live);
+    return active.count > ACTIVE_LIMIT ? [`${active.count} promotions without a coupon are active or scheduled (one per action, in ${active.ids.join(', ')}): Commerce Layer applies at most ${ACTIVE_LIMIT}, the ones with the lowest priority number. Give the rest a coupon, an end date, or disable them.`] : undefined;
+}
+const checkNext = (p) => p.rules?.coupons?.length ? `Check it: c11r orders test --code ${p.rules.coupons[0]}, and read discounts.` : p.flex ? undefined : 'Check it: c11r orders test with an order that matches the rules (--sku, --quantity), and read discounts.';
+export async function promotionsList() {
+    const api = createApi(requireCredentials());
+    const { promotions } = await api.listPromotions();
+    return { count: promotions.length, promotions, warnings: await activeWarning(api) };
+}
+export async function promotionsShow(id) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions show <id>`; `c11r promotions list` has the ids.');
+    return createApi(requireCredentials()).getPromotion(id);
+}
+export async function promotionsCreate(values) {
+    const api = createApi(requireCredentials());
+    const spec = await readSpec(values);
+    const created = await api.createPromotion(spec);
+    return { status: 'created', promotion: created, warnings: await activeWarning(api), next: checkNext(created) };
+}
+export async function promotionsUpdate(id, values) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions update <id>` with the whole promotion on stdin or -f <file>.');
+    const api = createApi(requireCredentials());
+    // A promotion made outside c11r has Commerce Layer's id, which is no spec id: say what it is first.
+    if ((await api.getPromotion(id)).managed === false)
+        fail('promotion_not_managed', `Promotion ${id} was made outside c11r, in the dashboard.`, 'Create a c11r promotion with `c11r promotions create` and delete this one with `c11r promotions delete`, or edit it in the dashboard.');
+    const spec = await readSpec(values);
+    if (spec.id !== id)
+        fail('invalid_promotion', `id: the spec has id ${spec.id}, the command ${id}.`, 'An id never changes: use the same id, or create a new promotion and delete the old one.');
+    const updated = await api.updatePromotion(id, spec);
+    return { status: 'updated', promotion: updated, warnings: await activeWarning(api), next: checkNext(updated) };
+}
+export async function promotionsEnable(id, enabled) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', `Use \`c11r promotions ${enabled ? 'enable' : 'disable'} <id>\`.`);
+    const api = createApi(requireCredentials());
+    const p = await api.setPromotionEnabled(id, enabled);
+    return { status: enabled ? 'enabled' : 'disabled', promotion: p, warnings: enabled ? await activeWarning(api) : undefined };
+}
+export async function promotionsDelete(id) {
+    if (!id)
+        fail('missing_argument', 'Which promotion?', 'Use `c11r promotions delete <id>`, after asking the human.');
+    await createApi(requireCredentials()).deletePromotion(id);
+    return { status: 'deleted', id };
+}
+// ---------- links: live settings in Commerce Layer, not store files
+/** A link as list, show and the writes print it: url and urls first. */
+const urlFirst = ({ url, urls, ...l }) => ({ url, urls, ...l });
+const linkNext = (l) => {
+    const what = 'order' in l.for ? 'the hosted checkout for the order' : 'a microstore for what it sells';
+    const which = Object.keys(l.urls ?? {}).length > 1 ? `the url of each market in urls (url is ${Object.keys(l.urls)[0]}'s)` : 'the url';
+    if (l.status === 'pending')
+        return `Give the human ${which}: it opens ${what} from ${l.starts}; until then it shows a not-found page.`;
+    if (l.status === 'active')
+        return `Give the human ${which}: it opens ${what} until ${l.ends}. Payment is manual (wire transfer) unless a gateway is added.`;
+    return undefined;
+};
+export async function linksList() {
+    const { links } = await createApi(requireCredentials()).listLinks();
+    return { count: links.length, links: links.map(urlFirst) };
+}
+export async function linksShow(id) {
+    if (!id)
+        fail('missing_argument', 'Which link?', 'Use `c11r links show <id>`; `c11r links list` has the ids.');
+    return urlFirst(await createApi(requireCredentials()).getLink(id));
+}
+export async function linksCreate(values) {
+    const api = createApi(requireCredentials());
+    const raw = await readInput(values, 'link');
+    const store = loadStore();
+    const created = await api.createLink(checkLink(raw, store.markets, store.products));
+    return { status: 'created', link: urlFirst(created), next: linkNext(created) };
+}
+export async function linksEnable(id, enabled) {
+    if (!id)
+        fail('missing_argument', 'Which link?', `Use \`c11r links ${enabled ? 'enable' : 'disable'} <id>\`.`);
+    const link = await createApi(requireCredentials()).setLinkEnabled(id, enabled);
+    return { status: enabled ? 'enabled' : 'disabled', link: urlFirst(link), next: enabled ? linkNext(link) : undefined };
+}
+export async function linksDelete(id) {
+    if (!id)
+        fail('missing_argument', 'Which link?', 'Use `c11r links delete <id>`, after asking the human.');
+    await createApi(requireCredentials()).deleteLink(id);
+    return { status: 'deleted', id };
+}

package/dist/files.js

@@ -61,3 +61,24 @@ export function ignoreCredentials() {
     fs.appendFileSync('.gitignore', `${sep}${paths.credentials}\n`);
     return true;
 }
+/** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */
+const AGENT_NOTE_HEADING = '# Store on Commerce Layer';
+export const AGENT_NOTE = `${AGENT_NOTE_HEADING}
+This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch \`https://commercelayer.ai/skills.md\` with \`curl -fsSL\` and load the skill for the task from \`skills/<name>.md\`; follow it rather than calling the Commerce Layer API directly. If \`.commercelayer/store.yml\` is missing, start from \`https://commercelayer.ai/start.md\`.
+`;
+/**
+ * Write the note to AGENTS.md and CLAUDE.md (Claude Code reads that name) in the repo root:
+ * created when absent, appended as a section when the file has other content, left alone
+ * when the section is already there. Returns the files written.
+ */
+export function writeAgentNotes() {
+    const written = [];
+    for (const file of ['AGENTS.md', 'CLAUDE.md']) {
+        const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        if (before.split('\n').some((line) => line.trim() === AGENT_NOTE_HEADING))
+            continue;
+        fs.writeFileSync(file, before.trim() ? `${before.replace(/\s*$/, '')}\n\n${AGENT_NOTE}` : AGENT_NOTE);
+        written.push(file);
+    }
+    return written;
+}

package/dist/links.js

@@ -0,0 +1,118 @@
+// Links: shareable URLs that open a hosted microstore for one SKU, a set of SKUs or a
+// category, or the hosted checkout for an order. Live configuration in Commerce Layer, made
+// with c11r links create; never in store.yml. The CLI validates the spec against store.yml
+// (skus, categories, markets) and sends one normalized link; the API makes the CL link.
+import { isoDate } from './promotions.js';
+import { fail } from './output.js';
+const KEYS = ['id', 'name', 'for', 'market', 'markets', 'starts', 'ends', 'params'];
+const FOR = ['sku', 'skus', 'category', 'order'];
+/** The SKUs one link can sell: the API's limit. */
+const MAX_SKUS = 100;
+const SHAPE_HINT = 'See the links skill for the shape: https://commercelayer.ai/skills/links.md';
+const isObj = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+const seconds = (d) => d.toISOString().replace(/\.\d{3}Z$/, 'Z');
+/** One calendar month after a date-time, in UTC. */
+function monthAfter(iso) {
+    const d = new Date(iso);
+    d.setUTCMonth(d.getUTCMonth() + 1);
+    return seconds(d);
+}
+/**
+ * Validate one link spec (YAML or JSON, as given to links create) and normalize it to the
+ * wire shape, or fail invalid_link naming the path inside the spec. A category becomes its
+ * products' skus as they are now, from store.yml.
+ */
+export function checkLink(raw, markets, products, now = new Date()) {
+    const skus = new Set(products.map((p) => p.sku));
+    const bad = (msg, hint, path = 'link') => fail('invalid_link', `${path}: ${msg}`, hint);
+    if (!isObj(raw))
+        bad('is not a map.', `A link is a map with id, name and for. ${SHAPE_HINT}`);
+    const l = raw;
+    if (typeof l.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(l.id))
+        bad(`id is ${l.id === undefined ? 'missing' : `"${String(l.id)}"`}.`, 'Give the link an id of lowercase letters, digits and dashes, such as summer-bundle: the handle for show, enable, disable and delete.');
+    const id = l.id;
+    for (const k of Object.keys(l))
+        if (!KEYS.includes(k))
+            bad(`unknown key ${k}.`, `A link's keys are ${KEYS.join(', ')}.`);
+    const link = { id, name: l.name === undefined ? id : String(l.name), for: { sku: '' }, starts: '', ends: '' };
+    if (!link.name.trim() || link.name.length > 255)
+        bad('name is empty or longer than 255 characters.', 'Write a short name the human will recognize in the dashboard.');
+    // for: exactly one of sku, skus, category, order. show prints a category with its skus: those are read again.
+    const f = l.for;
+    if (!isObj(f))
+        bad(f === undefined ? 'has no for.' : 'for is not a map.', `Say what the link sells: for: { sku: <sku> }, { skus: [...] }, { category: "A > B" } or { order: <number> }. ${SHAPE_HINT}`);
+    const given = Object.keys(f).filter((k) => !('category' in f && k === 'skus'));
+    if (given.includes('sku_list'))
+        bad('sku_list is a list made in the dashboard.', 'Name the skus (for: { skus: [...] }) or a category instead.', 'for');
+    for (const k of given)
+        if (!FOR.includes(k))
+            bad(`unknown key ${k}.`, `for takes one of ${FOR.join(', ')}.`, 'for');
+    if (given.length !== 1)
+        bad(`has ${given.length ? given.join(' and ') : 'nothing'}.`, 'Give exactly one of sku, skus, category or order: a link sells one thing.', 'for');
+    const kind = given[0];
+    const v = f[kind];
+    if (kind === 'sku') {
+        if (typeof v !== 'string' || !skus.has(v))
+            bad(`${String(v)} is not a product.`, "Use the SKU of one of the store's products.", 'for.sku');
+        link.for = { sku: v };
+    }
+    else if (kind === 'skus') {
+        if (!Array.isArray(v) || !v.length)
+            bad('is not a list of SKUs.', 'List one or more SKUs: skus: [ETH, COL].', 'for.skus');
+        if (v.length > MAX_SKUS)
+            bad(`has ${v.length} SKUs.`, `A link sells at most ${MAX_SKUS} SKUs: make several links.`, 'for.skus');
+        v.forEach((s, i) => {
+            if (typeof s !== 'string' || !skus.has(s))
+                bad(`${String(s)} is not a product.`, "Use SKUs of the store's products.", `for.skus[${i}]`);
+        });
+        link.for = { skus: [...new Set(v)] };
+    }
+    else if (kind === 'category') {
+        const name = String(v).split('>').map((s) => s.trim()).filter(Boolean).join(' > ');
+        const found = products.filter((x) => x.category === name || x.category?.startsWith(`${name} > `)).map((x) => x.sku);
+        if (!name || !found.length)
+            bad(`no product is in category "${String(v)}".`, `Use a category of the store's products, written as in the products: ${[...new Set(products.map((x) => x.category).filter(Boolean))].join(', ') || 'none has a category yet'}.`, 'for.category');
+        if (found.length > MAX_SKUS)
+            bad(`"${name}" has ${found.length} products.`, `A link sells at most ${MAX_SKUS} SKUs: use a narrower category, or several links.`, 'for.category');
+        link.for = { category: name, skus: found.sort() };
+    }
+    else {
+        if (!(typeof v === 'string' && v.trim()) && !(Number.isInteger(v) && v > 0))
+            bad(`${String(v)} is not an order number.`, 'Use the number of a draft or pending order, or the id of a UCP cart or checkout (cart_..., chk_...): the order behind it.', 'for.order');
+        link.for = { order: String(v).trim().replace(/^#/, '') };
+    }
+    // Markets: a code or a list, under market or markets; none means every market. An order has its own.
+    if (l.market !== undefined && l.markets !== undefined)
+        bad('has market and markets.', 'Use one of them.');
+    const m = l.market ?? l.markets;
+    const path = l.market !== undefined ? 'market' : 'markets';
+    if (kind === 'order') {
+        if (m !== undefined)
+            bad(`${path}: an order link has the order's market.`, 'Remove market: the checkout opens in the market the order was placed in.');
+    }
+    else if (m === undefined)
+        link.markets = markets.map((x) => x.code);
+    else {
+        const codes = Array.isArray(m) ? m : [m];
+        if (!codes.length)
+            bad('is empty.', 'List one or more market codes, or leave it out for every market.', path);
+        codes.forEach((c, i) => {
+            if (!markets.some((x) => x.code === c))
+                bad(`${String(c)} is not in markets.`, `Use the code of one of the store's markets: ${markets.map((x) => x.code).join(', ')}.`, Array.isArray(m) ? `${path}[${i}]` : path);
+        });
+        link.markets = [...new Set(codes)];
+    }
+    link.starts = l.starts === undefined ? seconds(now) : isoDate(l.starts, false, (msg, h) => bad(`starts ${msg}`, h));
+    link.ends = l.ends === undefined ? monthAfter(link.starts) : isoDate(l.ends, true, (msg, h) => bad(`ends ${msg}`, h));
+    if (Date.parse(link.ends) <= Date.parse(link.starts))
+        bad('ends is not after starts.', 'Make the end date later than the start date.');
+    if (l.params !== undefined) {
+        if (!isObj(l.params))
+            bad('params is not a map.', 'params is a map of names to text, numbers or true/false, added to the link URL.');
+        for (const [k, p] of Object.entries(l.params))
+            if (!['string', 'number', 'boolean'].includes(typeof p))
+                bad(`${k} is not text, a number or true/false.`, 'params values are plain values, added to the link URL.', `params.${k}`);
+        link.params = l.params;
+    }
+    return link;
+}

package/dist/promotions.js

@@ -17,7 +17,7 @@ const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
 const isInt = (v, min) => Number.isInteger(v) && v >= min;
 const list = (v) => (Array.isArray(v) ? v : [v]);
 /** A date or a date-time, as ISO UTC. A bare day starts at 00:00:00Z and ends at 23:59:59Z. */
-function isoDate(v, end, bad) {
+export function isoDate(v, end, bad) {
     const s = v instanceof Date ? v.toISOString().replace(/\.000Z$/, 'Z') : String(v);
     const hint = 'Write a day, 2026-12-01, or a time in UTC, 2026-12-01T09:00:00Z.';
     if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
@@ -29,29 +29,55 @@ function isoDate(v, end, bad) {
         bad(`"${s}" is not a date.`, hint);
     return new Date(s).toISOString().replace(/\.000Z$/, 'Z');
 }
-/** Validate promotions: and normalize them to the wire shape, or fail invalid_promotion with the path. */
-export function checkPromotions(raw, markets, products) {
-    if (raw === undefined || raw === null)
-        return [];
-    if (!Array.isArray(raw))
-        fail('invalid_promotion', 'promotions in store.yml is not a list.', `Write promotions as a YAML list under \`promotions:\`, one entry per promotion. ${SHAPE_HINT}`);
+/**
+ * The normalized shape (what list and show print) back to the YAML shorthand, so a promotion
+ * read with show can be edited and sent to update: rules as an object, actions with a type.
+ */
+function fromListed(p) {
+    const out = { ...p };
+    if (isObj(p.rules)) {
+        const r = p.rules;
+        out.rules = [
+            ...(r.coupons !== undefined ? [{ coupon: r.coupons }] : []),
+            ...(r.order_amount !== undefined ? [{ order_amount: r.order_amount }] : []),
+            ...(r.skus !== undefined ? [{ skus: r.skus }] : []),
+            ...Object.keys(r).filter((k) => !['coupons', 'order_amount', 'skus'].includes(k)).map((k) => ({ [k]: r[k] })),
+        ];
+    }
+    if (Array.isArray(p.actions)) {
+        out.actions = p.actions.map((a) => {
+            if (!isObj(a) || typeof a.type !== 'string')
+                return a;
+            const { type, ...rest } = a;
+            if (type === 'free_shipping')
+                return 'free_shipping';
+            if (type === 'percentage' || type === 'fixed_amount') {
+                const { value, ...targets } = rest;
+                return { [type]: value, ...targets };
+            }
+            return { [type]: rest };
+        });
+    }
+    return out;
+}
+/**
+ * Validate one promotion spec (YAML or JSON, as given to promotions create or update) and
+ * normalize it to the wire shape, or fail invalid_promotion naming the path inside the spec.
+ * Categories become their products' skus as they are now, from store.yml.
+ */
+export function checkPromotion(raw, markets, products) {
     const skus = new Set(products.map((p) => p.sku));
     const currencies = new Set(markets.map((m) => m.currency));
-    const ids = new Set();
-    const out = [];
-    raw.forEach((p, i) => {
-        let at = `promotions[${i}]`;
-        const bad = (msg, hint, path = at) => fail('invalid_promotion', `${path}: ${msg}`, hint);
+    const at = 'promotion';
+    const bad = (msg, hint, path = at) => fail('invalid_promotion', `${path}: ${msg}`, hint);
+    {
+        const p = raw;
         if (!isObj(p))
-            bad('is not a map.', `Each promotion is a map with id, rules and actions. ${SHAPE_HINT}`);
-        const pr = p;
+            bad('is not a map.', `A promotion is a map with id, rules and actions. ${SHAPE_HINT}`);
+        const pr = fromListed(p);
         if (typeof pr.id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(pr.id))
-            bad(`id is ${pr.id === undefined ? 'missing' : `"${String(pr.id)}"`}.`, 'Give every promotion an id of lowercase letters, digits and dashes, such as welcome10. The store identifies the promotion by it: keep it stable.');
+            bad(`id is ${pr.id === undefined ? 'missing' : `"${String(pr.id)}"`}.`, 'Give the promotion an id of lowercase letters, digits and dashes, such as welcome10: the handle for show, update, enable, disable and delete.');
         const id = pr.id;
-        if (ids.has(id))
-            bad(`two promotions have id ${id}.`, 'Give every promotion a unique id.');
-        ids.add(id);
-        at = `promotions[${i}] (${id})`;
         for (const k of Object.keys(pr))
             if (!KEYS.includes(k))
                 bad(`unknown key ${k}.`, `A promotion's keys are ${KEYS.join(', ')}.`);
@@ -95,13 +121,12 @@ export function checkPromotions(raw, markets, products) {
             if (!isObj(f) || !Array.isArray(f.rules) || f.rules.length === 0)
                 bad('flex has no rules.', 'Write flex: { rules: [...] }, each rule with conditions and actions. See docs.commercelayer.io/rules-engine.');
             f.rules.forEach((r, j) => {
-                const path = `${at}.flex.rules[${j}]`;
+                const path = `flex.rules[${j}]`;
                 if (!isObj(r) || !Array.isArray(r.conditions) || !r.conditions.length || !Array.isArray(r.actions) || !r.actions.length)
                     bad('needs a list of conditions and a list of actions.', 'Each flex rule has conditions (field, matcher, value) and actions (type, selector, value).', path);
             });
             promo.flex = f;
-            out.push(promo);
-            return;
+            return promo;
         }
         // Rules: a list of single-key maps; none means every order.
         const rules = {};
@@ -127,7 +152,7 @@ export function checkPromotions(raw, markets, products) {
         if (!Array.isArray(rawRules))
             bad('rules is not a list.', `Write rules as a list: rules: [{ coupon: CODE }]. ${SHAPE_HINT}`);
         rawRules.forEach((r, j) => {
-            const path = `${at}.rules[${j}]`;
+            const path = `rules[${j}]`;
             if (!isObj(r) || Object.keys(r).length !== 1)
                 bad('is not a single rule.', `Each rule is one of ${RULES.join(', ')}, written as a one-key map: { coupon: CODE }.`, path);
             const [k, v] = Object.entries(r)[0];
@@ -145,6 +170,8 @@ export function checkPromotions(raw, markets, products) {
                 }
                 if (!l.length)
                     bad('coupon has no code.', 'Write coupon: CODE, or a list of codes.', path);
+                if (new Set(l).size > 20)
+                    bad(`coupon has ${new Set(l).size} codes.`, 'A promotion takes at most 20 codes: split them across promotions.', path);
                 rules.coupons = [...new Set(l)];
             }
             else if (k === 'order_amount') {
@@ -166,7 +193,7 @@ export function checkPromotions(raw, markets, products) {
         const types = new Set();
         let needsCurrency = Boolean(rules.order_amount);
         pr.actions.forEach((a, j) => {
-            const path = `${at}.actions[${j}]`;
+            const path = `actions[${j}]`;
             const entry = a === 'free_shipping' ? { free_shipping: true } : a;
             if (!isObj(entry))
                 bad('is not an action.', `Each action is one of ${ACTIONS.join(', ')}: { percentage: 10 }, or free_shipping.`, path);
@@ -196,8 +223,8 @@ export function checkPromotions(raw, markets, products) {
             };
             if (k === 'percentage') {
                 only(entry, ['percentage', 'skus', 'category']);
-                if (!isNum(v) || v <= 0 || v > 100)
-                    bad(`percentage is ${String(v)}.`, 'percentage is a number above 0 and up to 100: 10 is 10% off. To make shipping free, use free_shipping.', path);
+                if (!isInt(v, 1) || v > 100)
+                    bad(`percentage is ${String(v)}.`, 'percentage is a whole number from 1 to 100: 10 is 10% off. To make shipping free, use free_shipping.', path);
                 const t = target(entry, false);
                 actions.push({ type: 'percentage', value: v, ...(t ? { skus: t } : {}) });
             }
@@ -232,7 +259,10 @@ export function checkPromotions(raw, markets, products) {
                         bad('free_gift needs the SKUs given away.', 'Write free_gift: { skus: [GIFT-SKU], quantity: 1 }.', path);
                     if (o.quantity !== undefined && !isInt(o.quantity, 1))
                         bad(`free_gift.quantity is ${String(o.quantity)}.`, 'quantity is a whole number of 1 or more.', path);
-                    actions.push({ type: 'free_gift', skus: target(o, true), quantity: o.quantity ?? 1 });
+                    const gifts = target(o, true);
+                    if (gifts.length > 25)
+                        bad(`free_gift has ${gifts.length} skus.`, 'A free gift takes at most 25 SKUs: narrow the list or the category.', path);
+                    actions.push({ type: 'free_gift', skus: gifts, quantity: o.quantity ?? 1 });
                 }
                 else {
                     only(o, ['x', 'y', 'cheapest_free', 'skus', 'category']);
@@ -248,9 +278,8 @@ export function checkPromotions(raw, markets, products) {
             bad('has an amount but no market, in a store with several currencies.', 'Set market: so the amount has a currency, or use a percentage.');
         promo.rules = rules;
         promo.actions = actions;
-        out.push(promo);
-    });
-    return out;
+        return promo;
+    }
 }
 /**
  * Commerce Layer promotions active without a coupon: each action of an enabled promotion that