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

package/dist/store.js

@@ -1,379 +0,0 @@
-// .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 { DEFAULT_LANGUAGE, ISO_639_1, PLAIN, TRANSLATED } from './languages.js';
-import { localesOf } from './locales.js';
-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', 'category', 'prices'];
-export const THEME_KEYS = ['color', 'logo', 'hero', 'tagline', 'badge'];
-export const STOREFRONT_MODES = ['hosted', 'agent-only'];
-export const storefrontMode = (s) => s.storefront?.mode ?? 'hosted';
-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}
-# language: en       # the products' language, ISO 639-1 (default en). Other languages
-#                    # go in the products: name: { en: Ethiopia, it: Etiopia }, and the same
-#                    # for description and category; in CSV, name_it, description_it, category_it.
-#                    # The website has a page per country, in that country's language.
-
-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,
-  #                category, and one column per currency (EUR, USD, ...) with the price
-  # image_url is an https:// URL or a file in .commercelayer/img/, written img/<file>.
-  # category is optional, a path from the top level: Coffee > Single origin.
-  # 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.
-  #   category: Coffee > Single origin
-  #   prices: { EUR: 14.50 }
-  # Stock is not part of the catalog: inventory is tracked live in Commerce Layer.
-
-catalog:
-  # Where \`c11r catalog pull\` reads the products from, if they live in a tool the
-  # human edits. Pull writes them to .commercelayer/products/catalog.csv.
-  # source: sheets     # a Google Sheet published as CSV: url is its CSV link
-  # source: supabase   # a Supabase table: table is its name (default products);
-  #                    # C11R_SUPABASE_URL and C11R_SUPABASE_KEY in .commercelayer/credentials
-  # source: merchant   # a Google Merchant Center feed, RSS (XML) or TSV: url is the feed;
-  #                    # translations: { it: <the it feed url> } adds other languages, by id
-  # source: website    # a brand's website, for a demo store: url is the site; limit is how
-  #                    # many products (default 100, at most 500). Images stay on the site.
-  # url: https://...
-  # table: products
-
-theme:
-  # The store's website: a theme the platform renders and keeps up to date.
-  # Every setting is optional. Images live in .commercelayer/img/ and apply uploads them.
-  # color: "#2f5d50"     # the accent: buttons, links, the hero band
-  # logo: img/logo.svg   # or an https:// URL; without it the name is the logo
-  # hero: img/hero.jpg   # the home page's wide image; without it a band in the accent
-  # tagline: Small-batch coffee, roasted in Milan   # at most 120 characters
-  # badge: Demo          # a short label next to the logo, at most 20 characters
-
-storefront:
-  # mode: hosted       # hosted (default): the website for humans, and UCP for agents.
-  #                    # agent-only: the store host serves only UCP and the pages it
-  #                    # needs (checkout, order, policy pages), no catalog pages.
-  # Only for a custom storefront (your own web app in this repo, published with
-  # c11r storefront publish): it replaces the theme. Its folder, from 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.');
-            }
-        }
-    }
-    if (doc.promotions !== undefined)
-        fail('invalid_store', 'store.yml has promotions:, which is not part of the store files.', 'Promotions are live settings in Commerce Layer: create each one with `c11r promotions create -f <file>` (the same entry as YAML or JSON), then remove promotions: from store.yml.');
-    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 theme = checkTheme(doc.theme);
-    checkStorefront(doc.storefront);
-    const language = storeLanguage(doc.language);
-    const currencies = [...new Set(markets.map((m) => m.currency))];
-    const products = checkProducts(sourced, currencies, language);
-    const languages = storeLanguages({ language, products });
-    if (languages.length > MAX_LANGUAGES)
-        fail('invalid_store', `The store has ${languages.length} languages: ${languages.join(', ')}.`, `A store has at most ${MAX_LANGUAGES} languages, the base one (${language}) included. Drop the translations of the others.`);
-    return { name: doc.name, language, markets, products, storefront: doc.storefront, policies, theme };
-}
-/** The product rules, shared by loadStore and catalog pull: errors name each product's source. */
-export function checkProducts(sourced, currencies, language = DEFAULT_LANGUAGE) {
-    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.`);
-        }
-        if (p.image_url !== undefined && !isImageRef(String(p.image_url))) {
-            fail('invalid_product', `Product ${p.sku} in ${source} has image_url "${p.image_url}".`, IMAGE_HINT);
-        }
-        translate(p, source, language);
-        if (p.category !== undefined)
-            p.category = categoryPath(p.category, `Product ${p.sku} in ${source} has category "${p.category}".`);
-        for (const [ll, t] of Object.entries(p.translations ?? {})) {
-            if (t.category === undefined)
-                continue;
-            t.category = categoryPath(t.category, `Product ${p.sku} in ${source} has category.${ll} "${t.category}".`);
-            const levels = (c) => c.split(' > ').length;
-            if (levels(t.category) !== levels(p.category))
-                fail('invalid_product', `Product ${p.sku} in ${source} has category.${ll} "${t.category}", with ${levels(t.category)} levels; "${p.category}" has ${levels(p.category)}.`, 'A translated category names the same levels as the base one, each translated: "Coffee > Single origin" is "Caffè > Monorigine" in it.');
-        }
-        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 or in the catalog source); every product needs a price in each market's currency (${currencies.join(', ')}).`);
-            }
-        }
-        products.push(p);
-    }
-    return products;
-}
-/** store.yml `language:`, validated: the base language, default en. */
-export function storeLanguage(raw) {
-    if (raw === undefined || raw === null)
-        return DEFAULT_LANGUAGE;
-    const ll = String(raw);
-    if (!ISO_639_1.has(ll))
-        fail('invalid_store', `language in store.yml is "${ll}".`, 'Use the ISO 639-1 code of the language the products are written in, in lower case: en, it, fr, de, es, ... Leave it out for en.');
-    return ll;
-}
-const categoryPath = (value, message) => {
-    const parts = typeof value === 'string' ? value.split('>').map((c) => c.trim()) : [''];
-    if (parts.some((c) => !c))
-        fail('invalid_product', message, 'A category is a path of names from the top level, separated by " > ", such as "Coffee > Single origin". Leave it out for no category.');
-    return parts.join(' > ');
-};
-/**
- * name, description and category as a string (the base language) or a { <ll>: text } map, from
- * YAML or from name_<ll> columns: the base language's text stays on the product, the others move
- * to translations, sorted by language.
- */
-function translate(p, source, language) {
-    const raw = p;
-    if (raw.translations !== undefined)
-        fail('invalid_product', `Product ${p.sku} in ${source} has translations.`, 'Write the other languages in the fields themselves: name: { en: Ethiopia, it: Etiopia }, or name_it columns in CSV.');
-    const out = {};
-    for (const field of TRANSLATED) {
-        const v = raw[field];
-        if (v === undefined || v === null || typeof v !== 'object')
-            continue;
-        if (Array.isArray(v))
-            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} as a list.`, `Write ${field} as text, or as a map of language codes to text: ${field}: { ${language}: ..., it: ... }.`);
-        const map = v;
-        for (const [ll, text] of Object.entries(map)) {
-            if (ll !== PLAIN && !ISO_639_1.has(ll))
-                fail('invalid_product', `Product ${p.sku} in ${source}: ${field}.${ll} is not a language.`, 'Use ISO 639-1 codes in lower case for the languages: en, it, fr, de, es, ...');
-            if (typeof text !== 'string' && typeof text !== 'number')
-                fail('invalid_product', `Product ${p.sku} in ${source}: ${field}.${ll} is not text.`, `Write each language's ${field} as plain text.`);
-        }
-        const plain = map[PLAIN];
-        const base = map[language];
-        if (plain !== undefined && base !== undefined && String(plain) !== String(base))
-            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} and ${field}_${language} with different texts.`, `${language} is the store's base language: the plain ${field} column is its text. Keep one of the two.`);
-        const text = base ?? plain;
-        if (text === undefined || String(text).trim() === '')
-            fail('invalid_product', `Product ${p.sku} in ${source} has ${field} in ${Object.keys(map).filter((k) => k !== PLAIN).join(', ')} but not in ${language}, the store's base language.`, `Add the ${language} text (${field}: { ${language}: ... }), or set language: in store.yml to the products' base language.`);
-        raw[field] = String(text);
-        for (const [ll, t] of Object.entries(map))
-            if (ll !== PLAIN && ll !== language && String(t).trim() !== '')
-                (out[ll] ??= {})[field] = String(t).trim();
-    }
-    const languages = Object.keys(out).sort();
-    if (languages.length)
-        p.translations = Object.fromEntries(languages.map((ll) => [ll, out[ll]]));
-}
-/** An image reference that is a file in .commercelayer/img/ (img/eth.jpg), not a URL. */
-export const isLocalImage = (url) => !/^[a-z][a-z0-9+.-]*:/i.test(url) && !url.startsWith('//');
-/** The paths the store host serves images at, as the API accepts them. */
-export const IMAGE_PATH = /^img\/[A-Za-z0-9._-][A-Za-z0-9._/-]*\.(png|jpg|jpeg|webp|gif|avif|svg)$/;
-/** image_url, logo, hero: an https URL, or img/<file> for a file in .commercelayer/img/. */
-export const isImageRef = (url) => isLocalImage(url) ? IMAGE_PATH.test(url) && !url.includes('..') && !url.includes('//') : /^https?:\/\/\S+$/.test(url);
-const IMAGE_HINT = 'Use a full https:// URL, or img/<file> for a file in .commercelayer/img/ (letters, digits, . _ - and /; extension png, jpg, jpeg, webp, gif, avif or svg, in lowercase).';
-/** The storefront block of store.yml: path, and mode hosted or agent-only. */
-function checkStorefront(raw) {
-    if (raw === undefined || raw === null)
-        return;
-    const hint = 'Write `storefront:` with `mode: hosted` (the default) or `mode: agent-only`, and `path:` for a custom storefront. See the comments in store.yml.';
-    if (typeof raw !== 'object' || Array.isArray(raw))
-        fail('invalid_storefront', 'storefront in store.yml is not a mapping.', hint);
-    const s = raw;
-    const unknown = Object.keys(s).filter((k) => !['mode', 'path'].includes(k));
-    if (unknown.length)
-        fail('invalid_storefront', `storefront in store.yml has ${unknown.join(', ')}, which it does not take.`, hint);
-    if (s.mode !== undefined && s.mode !== null && !STOREFRONT_MODES.includes(s.mode))
-        fail('invalid_storefront', `storefront.mode is "${String(s.mode)}".`, 'Use hosted (a website for humans, and UCP) or agent-only (UCP and the pages it needs, no catalog pages).');
-    if (s.path !== undefined && s.path !== null && typeof s.path !== 'string')
-        fail('invalid_storefront', 'storefront.path is not a folder name.', hint);
-}
-/** The theme block of store.yml, validated: the theme would ignore bad values, so say so here. */
-function checkTheme(raw) {
-    if (raw === undefined || raw === null)
-        return undefined;
-    if (typeof raw !== 'object' || Array.isArray(raw))
-        fail('invalid_theme', 'theme in store.yml is not a mapping.', 'Write `theme:` with color, logo, hero, tagline and badge under it, each optional. See the comments in store.yml.');
-    const t = raw;
-    const unknown = Object.keys(t).filter((k) => !THEME_KEYS.includes(k));
-    if (unknown.length)
-        fail('invalid_theme', `theme in store.yml has ${unknown.length === 1 ? 'a setting' : 'settings'} the theme does not have: ${unknown.join(', ')}.`, `The theme's settings are ${THEME_KEYS.join(', ')}. A custom storefront's folder goes under storefront.path.`);
-    const theme = {};
-    for (const k of THEME_KEYS)
-        if (t[k] !== undefined && t[k] !== null)
-            theme[k] = String(t[k]);
-    if (theme.color !== undefined && !/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(theme.color))
-        fail('invalid_theme', `theme.color is "${theme.color}".`, 'Use a hex colour in quotes, #rgb or #rrggbb, such as "#2f5d50".');
-    for (const k of ['logo', 'hero'])
-        if (theme[k] !== undefined && !isImageRef(theme[k]))
-            fail('invalid_theme', `theme.${k} is "${theme[k]}".`, IMAGE_HINT);
-    if (theme.tagline !== undefined && (theme.tagline.length > 120 || /[\r\n<>]/.test(theme.tagline)))
-        fail('invalid_theme', `theme.tagline is ${theme.tagline.length > 120 ? `${theme.tagline.length} characters long` : 'not plain text on one line'}.`, 'Write the tagline as one line of plain text, at most 120 characters.');
-    if (theme.badge !== undefined && (theme.badge.length > 20 || !theme.badge.trim() || /[\r\n<>]/.test(theme.badge)))
-        fail('invalid_theme', `theme.badge is ${theme.badge.length > 20 ? `${theme.badge.length} characters long` : `"${theme.badge}"`}.`, 'Use a short plain-text label of at most 20 characters, such as Demo, with no line breaks or < >.');
-    return theme;
-}
-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])),
-        ...(store.language !== DEFAULT_LANGUAGE && { language: store.language }),
-    };
-}
-/** The store's languages: the base one first, then every language a product is translated into. */
-export const storeLanguages = (store) => [store.language, ...[...new Set(store.products.flatMap((p) => Object.keys(p.translations ?? {})))].sort()];
-/** Translations in a language no country of the store speaks: kept, but no page shows them. */
-export function languageWarnings(store) {
-    const spoken = new Set(localesOf(toApplied(store)).map((l) => l.language));
-    return storeLanguages(store)
-        .slice(1)
-        .filter((ll) => !spoken.has(ll))
-        .map((ll) => `Products are translated into ${ll}, which no country of the store speaks (${[...spoken].join(', ') || 'none'}): no page shows it, but shopping agents can ask for it over UCP.`);
-}
-/** At most this many languages, base included: the API's limit. */
-export const MAX_LANGUAGES = 6;
-/** JSON with sorted keys and no undefined values, so key order never reads as a change. */
-export const canonical = (v) => JSON.stringify(v ?? {}, (_k, x) => (x && typeof x === 'object' && !Array.isArray(x) ? Object.fromEntries(Object.entries(x).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : x));
-/** The one definition of "pending changes": what apply would do. plan and status both use it. */
-export function diff(state, desired) {
-    const changes = [];
-    const { applied } = state;
-    if (applied) {
-        if (state.name !== undefined && state.name !== null && state.name !== desired.name)
-            changes.push({ action: 'update', type: 'store', id: 'name' });
-        if (state.policies !== undefined && canonical(state.policies) !== canonical(desired.policies))
-            changes.push({ action: 'update', type: 'store', id: 'policies' });
-    }
-    // The theme is listed like a resource: a create when the store has none yet (first apply
-    // included), an update when it changes. An API that does not know themes (undefined) is skipped.
-    const hasTheme = (t) => Boolean(t && Object.keys(t).length);
-    if (!applied || state.theme !== undefined) {
-        const before = applied ? state.theme : null;
-        if (!hasTheme(before) && hasTheme(desired.theme))
-            changes.push({ action: 'create', type: 'store', id: 'theme' });
-        else if (hasTheme(before) && canonical(before) !== canonical(desired.theme))
-            changes.push({ action: 'update', type: 'store', id: 'theme' });
-    }
-    // The mode: a change from what the API holds (hosted before the first apply). An API that does not know it is skipped.
-    if (!applied ? storefrontMode(desired) !== 'hosted' : state.storefront_mode !== undefined && (state.storefront_mode ?? 'hosted') !== storefrontMode(desired)) {
-        changes.push({ action: 'update', type: 'store', id: 'storefront_mode' });
-    }
-    // The base language: a change from what is applied (en before the first apply, and when absent).
-    if ((applied?.language ?? DEFAULT_LANGUAGE) !== desired.language)
-        changes.push({ action: 'update', type: 'store', id: 'language' });
-    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 (canonical(before[id]) !== canonical(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;
-}