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

package/dist/http.js

@@ -0,0 +1,117 @@
+// Requests to the c11r API (contract sections 1, 2, 3 and 8). C11R_API_URL points the CLI at
+// another API, such as wrangler dev on http://localhost:8787/v1 (a URL without /v1 gets it).
+// Every answer is the envelope { data, state, warnings, next }; every error { error, state }.
+//
+// Query flags: --live sends mode=live on every request, --dry-run sends dry_run=true on writes,
+// and a confirmed destructive verb sends confirm=true (the form that works on every verb).
+//
+// Retries, as the PM ruled: rate_limited means nothing was processed, so reads and writes are
+// retried twice with a short backoff. commercelayer_busy and commercelayer_unavailable are
+// retried for reads only: a write that may have reached Commerce Layer fails with its next step.
+// The exception is a write with an Idempotency-Key (sandbox create): the API answers the same key
+// with the same result, so it is repeated with that key after any 5xx or a lost connection too.
+import { CliError, errorBody, fail, kindOfStatus } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const DEFAULT_API_URL = 'https://api.commercelayer.ai/v1';
+export function apiUrl() {
+    const raw = (process.env.C11R_API_URL || DEFAULT_API_URL).replace(/\/+$/, '');
+    return /\/v\d+$/.test(raw) ? raw : `${raw}/v1`;
+}
+/** An answer of the CLI's own, in the API's shape. state null: the CLI cannot tell it. */
+export const envelope = (data, extra = {}) => ({ data, state: null, warnings: [], next: [], ...extra });
+const RETRY_ALWAYS = new Set(['rate_limited']);
+const RETRY_READS = new Set(['commercelayer_busy', 'commercelayer_unavailable']);
+const TRIES = 3;
+export function urlOf(req, ctx) {
+    const q = new URLSearchParams(req.query ?? {});
+    if (ctx.live)
+        q.set('mode', 'live');
+    if (req.dryRun && req.method !== 'GET')
+        q.set('dry_run', 'true');
+    if (req.confirm)
+        q.set('confirm', 'true');
+    const qs = q.toString();
+    return `${apiUrl()}${req.path}${qs ? `?${qs}` : ''}`;
+}
+/** Sends the request: the envelope, or the API's error as a CliError. */
+export async function request(req, ctx) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await once(req, ctx);
+        }
+        catch (e) {
+            const safe = req.method === 'GET' || req.idempotencyKey !== undefined;
+            const retryable = e instanceof CliError && (RETRY_ALWAYS.has(e.code) || (safe && (RETRY_READS.has(e.code) || (req.idempotencyKey !== undefined && (e.code === 'api_unreachable' || e.kind === 'unavailable')))));
+            if (!retryable || attempt >= TRIES)
+                throw e;
+            // The API's retry_after (seconds, in the error or the Retry-After header) is waited for, up
+            // to the cap. Longer than the cap: no wait here, the error goes to the agent to plan around.
+            const after = retryAfterMs(e);
+            if (after !== null && after > retryCapMs())
+                throw e;
+            const wait = after ?? backoffMs() * 3 ** (attempt - 1);
+            process.stderr.write(JSON.stringify({ retrying: { code: e.code, attempt, of: TRIES - 1, in_ms: wait } }) + '\n');
+            await new Promise((r) => setTimeout(r, wait));
+        }
+    }
+}
+async function once(req, ctx) {
+    const headers = { 'user-agent': USER_AGENT, accept: 'application/json' };
+    if (req.body !== undefined)
+        headers['content-type'] = 'application/json';
+    if (ctx.token)
+        headers.authorization = `Bearer ${ctx.token}`;
+    if (req.idempotencyKey)
+        headers['idempotency-key'] = req.idempotencyKey;
+    const url = urlOf(req, ctx);
+    const timeout = req.timeoutMs ?? timeoutMs();
+    let res;
+    try {
+        res = await fetch(url, { method: req.method, headers, body: req.body === undefined ? undefined : JSON.stringify(req.body), redirect: 'manual', signal: AbortSignal.timeout(timeout) });
+    }
+    catch (e) {
+        const why = e.name === 'TimeoutError' ? `no answer in ${timeout / 1000} s` : e.message;
+        fail('api_unreachable', `The c11r API at ${new URL(url).origin} did not answer: ${why}.${process.env.C11R_API_URL ? ` C11R_API_URL is set to ${process.env.C11R_API_URL}.` : ''}`, {
+            // A write may have arrived before the answer was lost: never "retry" it blindly.
+            next_step: req.method === 'GET' ? { action: 'retry_later' } : { action: 'none' },
+        });
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : null;
+    }
+    catch {
+        fail('invalid_response', `The API answered ${res.status} with something that is not JSON.`, { details: { status: res.status } }, res.ok ? 'unavailable' : kindOfStatus(res.status));
+    }
+    if (!res.ok)
+        throw apiError(res.status, data, res.headers.get('retry-after'));
+    if (!data || typeof data !== 'object' || Array.isArray(data) || !('data' in data)) {
+        fail('invalid_response', `The API answered ${res.status} without the envelope (data, state).`, { details: { status: res.status } });
+    }
+    return { data: data.data, state: data.state ?? null, warnings: data.warnings ?? [], next: data.next ?? [] };
+}
+/** The API's error, kept as the API wrote it, with the HTTP status in details. */
+function apiError(status, data, retryAfterHeader = null) {
+    const e = data?.error;
+    if (!e || typeof e !== 'object' || typeof e.code !== 'string') {
+        return new CliError(errorBody(status >= 500 ? 'api_error' : 'invalid_response', `The API answered ${status} without an error object.`, { details: { status } }), kindOfStatus(status), data?.state ?? null);
+    }
+    const body = {
+        ...errorBody(e.code, String(e.message ?? `The API answered ${status} (${e.code}).`)),
+        ...e,
+        details: { ...(e.details ?? {}), status, ...(retryAfterHeader !== null && e.retry_after === undefined && /^\d+(\.\d+)?$/.test(retryAfterHeader) ? { retry_after: Number(retryAfterHeader) } : {}) },
+    };
+    const known = new CliError(body, undefined, data.state ?? null);
+    return known.kind === 'unexpected' ? new CliError(body, kindOfStatus(status), data.state ?? null) : known;
+}
+/** retry_after in seconds, from the error or the Retry-After header, in ms; null when absent. */
+function retryAfterMs(e) {
+    const raw = e.body.retry_after ?? e.body.details?.retry_after;
+    const n = Number(raw);
+    return raw === undefined || raw === null || !Number.isFinite(n) || n < 0 ? null : n * 1000;
+}
+/** The longest wait for one retry: 30 s, C11R_RETRY_CAP_S to change it. */
+export const retryCapMs = () => (process.env.C11R_RETRY_CAP_S === undefined ? 30 : Number(process.env.C11R_RETRY_CAP_S)) * 1000;
+const timeoutMs = () => Number(process.env.C11R_TIMEOUT_MS) || 30_000;
+const backoffMs = () => (process.env.C11R_RETRY_MS === undefined ? 1000 : Number(process.env.C11R_RETRY_MS));

package/dist/login.js

@@ -0,0 +1,133 @@
+// The human's login: their own Provisioning API application, client id and secret (contract
+// section 18). The secret never leaves this machine: the CLI exchanges it for a Provisioning
+// access token at Commerce Layer's auth endpoint and sends only that token to the c11r API. Both
+// stay in credentials.json, mode 600, and are printed never.
+//
+// The token lasts two hours. A command that needs the login takes the stored token while it has
+// more than a minute left, else mints a new one. C11R_PROVISIONING_TOKEN, for CI, is a ready token
+// used as is.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { storedLogin, storeLogin } from './config.js';
+import { CliError, errorBody, fail } from './errors.js';
+import { USER_AGENT } from './version.js';
+export const PROVISIONING_URL = 'https://dashboard.commercelayer.io/user/provisioning_api';
+const AUTH_URL = 'https://auth.commercelayer.io/oauth/token';
+const MARGIN_MS = 60_000;
+export const authUrl = () => process.env.C11R_AUTH_URL || AUTH_URL;
+/** Where the human saves the client id and secret when there is no terminal to type them in. */
+export function secretFileDefault() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(base, 'c11r', 'provisioning.secret');
+}
+/** client_credentials at Commerce Layer. A refusal is the human's to fix: new values in the dashboard. */
+export async function mint(clientId, clientSecret) {
+    let res;
+    try {
+        res = await fetch(authUrl(), {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json', 'user-agent': USER_AGENT },
+            body: JSON.stringify({ grant_type: 'client_credentials', client_id: clientId, client_secret: clientSecret }),
+            signal: AbortSignal.timeout(Number(process.env.C11R_TIMEOUT_MS) || 30_000),
+        });
+    }
+    catch (e) {
+        fail('api_unreachable', `Commerce Layer's auth endpoint (${new URL(authUrl()).origin}) did not answer: ${e.message}.`, { next_step: { action: 'retry_later' } });
+    }
+    const body = (await res.json().catch(() => null));
+    if (res.status === 400 || res.status === 401) {
+        fail('unauthorized', 'Commerce Layer refused this client id and secret. They have to be the ones of the human\'s own Provisioning API application, from the dashboard.', {
+            path: 'client_secret',
+            next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL },
+        });
+    }
+    if (!res.ok || typeof body?.access_token !== 'string') {
+        fail('commercelayer_unavailable', `Commerce Layer's auth endpoint answered ${res.status} without a token.`, { details: { status: res.status }, next_step: { action: 'retry_later' } });
+    }
+    const seconds = Number(body.expires_in) || 7200;
+    return { token: body.access_token, expires_at: new Date(Date.now() + seconds * 1000).toISOString() };
+}
+export function loginRequired(message) {
+    return new CliError(errorBody('login_required', message, {
+        next_step: { action: 'human_step', command: 'c11r auth login', url: PROVISIONING_URL },
+        details: { secret_file: secretFileDefault() },
+    }));
+}
+/** The token a login command sends; minted again when it is about to end. */
+export async function loginToken(opts = {}) {
+    if (process.env.C11R_PROVISIONING_TOKEN)
+        return process.env.C11R_PROVISIONING_TOKEN;
+    const login = storedLogin();
+    if (!login) {
+        throw loginRequired('This needs the human\'s Commerce Layer login, and this machine has none. Ask the human for the client id and secret of their Provisioning API application, from the dashboard, saved in the file named in details.secret_file; then c11r auth login reads it.');
+    }
+    if (!opts.fresh && login.token && login.expires_at && Date.parse(login.expires_at) - Date.now() > MARGIN_MS)
+        return login.token;
+    let minted;
+    try {
+        minted = await mint(login.client_id, login.client_secret);
+    }
+    catch (e) {
+        if (e instanceof CliError && e.code === 'unauthorized') {
+            throw loginRequired('The stored login no longer works: Commerce Layer refused its client id and secret, as when the Provisioning API application was deleted or changed. The human saves the new ones; then c11r auth login reads them.');
+        }
+        throw e;
+    }
+    storeLogin({ ...login, token: minted.token, expires_at: minted.expires_at });
+    return minted.token;
+}
+export const hasLogin = () => Boolean(process.env.C11R_PROVISIONING_TOKEN) || storedLogin() !== null;
+/** The client id and secret, from a file the human saved: key=value lines, JSON, or the secret alone. */
+export function readSecretFile(file) {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch {
+        fail('invalid_value', `${file} does not exist.`, { path: 'secret_file' });
+    }
+    if (st.isSymbolicLink() || !st.isFile())
+        fail('insecure_file', `${file} is not a plain file. c11r reads a secret only from a plain file.`, { path: 'secret_file' });
+    if (st.mode & 0o077) {
+        fail('insecure_file', `${file} can be read by other users (mode ${(st.mode & 0o777).toString(8)}). c11r reads a secret only from a file that only its owner can read, mode 600.`, {
+            path: 'secret_file',
+            next_step: { action: 'human_step', command: null, url: null },
+            details: { file, mode: (st.mode & 0o777).toString(8) },
+        });
+    }
+    const text = fs.readFileSync(file, 'utf8');
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    try {
+        const json = JSON.parse(text);
+        if (json && typeof json === 'object')
+            return { client_id: str(json.client_id), client_secret: str(json.client_secret) };
+    }
+    catch {
+        // Not JSON.
+    }
+    if (lines.length === 1 && !lines[0].includes('='))
+        return { client_secret: lines[0] };
+    const out = {};
+    for (const l of lines) {
+        const eq = l.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = l.slice(0, eq).trim().toLowerCase().replace(/^(cl_|commercelayer_)/, '');
+        const value = l.slice(eq + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+        if (key === 'client_id' && value)
+            out.client_id = value;
+        if (key === 'client_secret' && value)
+            out.client_secret = value;
+    }
+    return out;
+}
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+/** The two-line template for the human to complete, mode 600 from the start; an existing file is left as is. */
+export function writeSecretTemplate(file) {
+    if (fs.existsSync(file))
+        return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, 'client_id=\nclient_secret=\n', { mode: 0o600, flag: 'wx' });
+    return true;
+}

package/dist/resources.js

@@ -0,0 +1,41 @@
+// One URL grammar for every noun (contract section 1), so no noun has its own path code:
+//   list    GET    /<noun>                 filters as ?filter[<field>][<op>]=<value>
+//   get     GET    /<noun>/<id>
+//   create  POST   /<noun>
+//   update  PATCH  /<noun>/<id>
+//   delete  DELETE /<noun>/<id>
+//   <verb>  POST   /<noun>/<id>/<verb>, or /<noun>/<verb> for a verb on the collection
+// The schema's path wins when it has one. Each value goes where its flag says: the body, the
+// query, or a filter; a local flag (--out) is the CLI's and is never sent.
+export function resourceRequest(noun, verb, id, values) {
+    const base = `/${noun}`;
+    const one = id === undefined ? base : `${base}/${encodeURIComponent(id)}`;
+    const query = {};
+    const body = {};
+    for (const [key, value] of Object.entries(values)) {
+        const flag = verb.flags[key];
+        if (value === undefined)
+            continue;
+        if (!flag || flag.to === 'body')
+            body[key] = value;
+        else if (flag.to === 'local')
+            continue;
+        else if (flag.to === 'filter')
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+        else
+            query[key] = text(value);
+    }
+    // The schema's own route when it gives one (/plans/current, /members/invite), else the grammar.
+    const path = verb.path
+        ? verb.path.replace(/\{[^}]+\}/, id === undefined ? '' : encodeURIComponent(id))
+        : ['list', 'get', 'create', 'update', 'delete'].includes(verb.name)
+            ? verb.name === 'list' || verb.name === 'create'
+                ? base
+                : one
+            : `${one}/${verb.name}`;
+    const req = { method: verb.method, path, query };
+    if (verb.method !== 'GET' && verb.method !== 'DELETE')
+        req.body = body;
+    return req;
+}
+const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));

package/dist/schema.js

@@ -0,0 +1,152 @@
+// The schema of a noun, as the contract's schema document has it (section 5.1), and what the
+// engine makes of it: for every verb, the flags it takes and where each one goes (body, query or
+// filter). A plain noun (markets, orders, carts, about 60 of them) has no code in the CLI: its
+// schema is read from GET /v1/schema/<noun>. Built-in nouns (sandbox, loops, report) write theirs
+// in the same document format, so one reader serves both.
+import { closest, fail, fixWith } from './errors.js';
+const FIELD_TYPES = ['string', 'integer', 'number', 'money', 'boolean', 'date', 'datetime', 'enum', 'object', 'array', 'ref'];
+export const FILTER_OPS = ['eq', 'in', 'gt', 'gte', 'lt', 'lte', 'start', 'cont', 'null'];
+/** The contract's names; sandbox, the first proposal's name for an organization token, still reads. */
+const CREDENTIALS = { none: 'none', organization: 'organization', login: 'login', 'organization|login': 'organization|login', sandbox: 'organization', 'sandbox|login': 'organization|login' };
+const STANDARD = ['list', 'get', 'create', 'update', 'delete'];
+const METHOD = { list: 'GET', get: 'GET', create: 'POST', update: 'PATCH', delete: 'DELETE' };
+export function parseSchema(raw, expected) {
+    const doc = raw;
+    if (!doc || typeof doc !== 'object' || typeof doc.noun !== 'string' || !Array.isArray(doc.verbs))
+        bad(expected, 'it has no noun or no verbs');
+    const fields = (doc.fields ?? []).map((f) => field(f, doc.noun));
+    const verbs = {};
+    for (const v of doc.verbs) {
+        if (!v || typeof v.verb !== 'string')
+            bad(doc.noun, 'a verb has no name');
+        const name = v.verb;
+        const flags = {};
+        if (name === 'list')
+            listFlags(flags, fields, doc);
+        if (name === 'create')
+            for (const f of fields)
+                if (f.create === 'required' || f.create === 'optional')
+                    flags[f.name] = flag(f, 'body', f.create === 'required');
+        if (name === 'update')
+            for (const f of fields)
+                if (f.update)
+                    flags[f.name] = flag(f, 'body', false);
+        const method = v.method?.toUpperCase() ?? METHOD[name] ?? 'POST';
+        // A name in body refers to a field of the document. On a GET it is a query parameter.
+        const own = (list) => (list ?? []).filter((x) => x !== '...' && !(name === 'list' && x === 'waiting')).map((x) => (typeof x === 'string' ? byName(fields, x) : field(x, doc.noun)));
+        for (const f of own(v.body))
+            if (!flags[f.name] || f.create === 'required')
+                flags[f.name] = flag(f, method === 'GET' ? 'query' : 'body', Boolean(f.required || (name === 'create' && f.create === 'required')));
+        for (const f of own(v.query))
+            flags[f.name] = flag(f, 'query', Boolean(f.required));
+        if (v.secret) {
+            flags.out = { type: 'string', to: 'local', description: 'The file the secret is written to, mode 600. By default one under ~/.config/c11r/secrets/<org>/.' };
+            flags.format = { type: 'enum', to: 'local', values: ['env', 'json'], description: 'env: KEY=value lines, for a .env file; json: one JSON object. By default as the API answers it.' };
+        }
+        const destructive = Boolean(v.destructive);
+        const state = v.state ?? 'sandbox';
+        if (v.credential !== undefined && !CREDENTIALS[v.credential])
+            bad(doc.noun, `verb ${name} has credential ${String(v.credential)}`);
+        verbs[name] = {
+            name,
+            description: v.effect ?? (STANDARD.includes(name) ? standardDescription(name, doc.noun) : ''),
+            method,
+            id: v.path ? /\{[^}]+\}/.test(v.path) : !['list', 'create'].includes(name),
+            destructive,
+            // A policy never deletes nor returns money, whatever else the document says.
+            loopable: Boolean(v.loopable) && !v.deletes && !v.returns_money && name !== 'delete',
+            live: v.live !== false,
+            state,
+            plan: v.plan ?? null,
+            credential: v.credential ? CREDENTIALS[v.credential] : state === 'none' ? 'none' : 'organization',
+            secret: Boolean(v.secret),
+            confirmIf: Array.isArray(v.confirm_if) ? v.confirm_if.filter((x) => typeof x === 'string') : [],
+            refused: v.served === false ? { by: v.refused_by ?? 'the API' } : null,
+            path: v.path ? v.path.replace(/^\/v\d+(?=\/)/, '') : null,
+            flags,
+        };
+    }
+    return {
+        noun: doc.noun,
+        description: doc.description ?? '',
+        skill: doc.skill ?? null,
+        verbs,
+        id: doc.id ? { accepts: doc.id.accepts ?? [], example: doc.id.example ?? null } : null,
+        waiting: doc.waiting ?? null,
+        loop: doc.loop ?? null,
+        doc,
+    };
+}
+function listFlags(flags, fields, doc) {
+    for (const f of fields) {
+        for (const op of f.filter ?? []) {
+            const key = op === 'eq' ? f.name : `${f.name}.${op}`;
+            const base = flag(f, 'filter', false);
+            if (op === 'in')
+                flags[key] = { ...base, type: 'array', items: f.type === 'array' ? f.items : f.type, filter: { field: f.name, op } };
+            else if (op === 'null')
+                flags[key] = { ...base, type: 'boolean', values: undefined, filter: { field: f.name, op } };
+            else
+                flags[key] = { ...base, filter: { field: f.name, op } };
+        }
+    }
+    if (doc.waiting)
+        flags.waiting = { type: 'boolean', to: 'query', description: doc.waiting.meaning ?? 'Only what needs a decision now.' };
+    flags.page = { type: 'integer', to: 'query', description: 'The page to return, from 1.' };
+    flags.limit = { type: 'integer', to: 'query', description: 'How many to return on a page.' };
+    const sortable = fields.filter((f) => f.sort).map((f) => f.name);
+    if (sortable.length)
+        flags.sort = { type: 'string', to: 'query', description: `A field to sort by (${sortable.join(', ')}); a leading minus sorts descending.` };
+}
+/** A field named in a verb's body. One the document does not define is taken as a string. */
+function byName(fields, name) {
+    return fields.find((x) => x.name === name) ?? { name, type: 'string' };
+}
+function field(f, noun) {
+    if (!f || typeof f.name !== 'string')
+        bad(noun, 'a field has no name');
+    if (!FIELD_TYPES.includes(f.type))
+        bad(noun, `field ${f.name} has type ${String(f.type)}`);
+    return f;
+}
+function flag(f, to, required) {
+    return {
+        type: f.type,
+        to,
+        ...(f.values ? { values: f.values } : {}),
+        ...(f.items ? { items: f.items } : {}),
+        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, p.type])) } : {}),
+        ...(f.noun ? { noun: f.noun } : {}),
+        ...(required ? { required: true } : {}),
+        ...(f.description ? { description: f.description } : {}),
+    };
+}
+function bad(noun, why) {
+    fail('invalid_response', `The API's schema${noun ? ` for ${noun}` : ''} is not one c11r reads: ${why}.`, { next_step: { action: 'none' } });
+}
+function standardDescription(verb, noun) {
+    return ({
+        list: `Lists the ${noun}, filtered by any of the flags.`,
+        get: `Returns one of the ${noun} by id.`,
+        create: `Creates one of the ${noun} from the flags.`,
+        update: `Changes the given fields of one of the ${noun}; the others stay as they are.`,
+        delete: `Deletes one of the ${noun}. It cannot be undone.`,
+    }[verb] ?? '');
+}
+/** The verb, or unknown_verb naming the ones there are. */
+export function verbOf(schema, verb) {
+    const names = Object.keys(schema.verbs);
+    if (!verb)
+        fail('missing_argument', `c11r ${schema.noun} needs a verb: ${names.join(', ')}.`, { details: { verbs: names }, next_step: fixWith(`c11r ${schema.noun} --help`) });
+    const v = schema.verbs[verb];
+    if (!v) {
+        const standard = STANDARD.includes(verb);
+        // Whether Commerce Layer has it or this API does not serve it yet, the CLI cannot tell.
+        fail('unknown_verb', `${schema.noun} has no verb ${verb}${standard ? ' in this API' : ''}. Its verbs are ${names.join(', ')}.`, {
+            did_you_mean: closest(verb, names),
+            details: { verbs: names },
+            next_step: fixWith(`c11r ${schema.noun} --help`),
+        });
+    }
+    return v;
+}

package/dist/schemas.js

@@ -0,0 +1,72 @@
+// Where plain nouns' schemas come from: GET /v1/schema for the list, GET /v1/schema/<noun> for
+// one (contract section 5), cached on disk for a few minutes so a command costs one request, not
+// two. Schemas are the same at every state, so no token is sent. C11R_SCHEMA_CACHE=0 turns the
+// cache off.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CliError, closest, fail, fixWith } from './errors.js';
+import { apiUrl, request } from './http.js';
+import { parseSchema } from './schema.js';
+import { VERSION } from './version.js';
+const TTL_MS = 10 * 60_000;
+function cacheFile(key) {
+    if (process.env.C11R_SCHEMA_CACHE === '0')
+        return null;
+    const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    const host = crypto.createHash('sha256').update(apiUrl()).digest('hex').slice(0, 12);
+    return path.join(base, 'c11r', `schema-${VERSION}-${host}`, `${key}.json`);
+}
+async function cached(key, load) {
+    const file = cacheFile(key);
+    if (file) {
+        try {
+            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS)
+                return JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            // Not cached, or unreadable: load it.
+        }
+    }
+    const value = await load();
+    if (file) {
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, JSON.stringify(value));
+        }
+        catch {
+            // A read-only home is fine: no cache.
+        }
+    }
+    return value;
+}
+const anonymous = { live: false, token: null };
+/** Every noun of the spec the API knows, served or not yet. */
+export async function apiNouns() {
+    const data = await cached('_index', async () => (await request({ method: 'GET', path: '/schema' }, anonymous)).data);
+    return Array.isArray(data?.nouns) ? data.nouns : [];
+}
+/** One plain noun's schema, or unknown_noun with close matches. */
+export async function apiSchema(noun, builtins) {
+    if (!/^[a-z][a-z0-9-]*$/.test(noun))
+        unknownNoun(noun, builtins);
+    let doc;
+    try {
+        doc = await cached(noun, async () => (await request({ method: 'GET', path: `/schema/${noun}` }, anonymous)).data);
+    }
+    catch (e) {
+        if (e instanceof CliError && e.kind === 'not_found') {
+            const known = await apiNouns().catch(() => []);
+            unknownNoun(noun, [...builtins, ...known.map((n) => n.noun)]);
+        }
+        if (e instanceof CliError && e.kind === 'unavailable') {
+            fail('schema_unavailable', `c11r reads the fields and verbs of ${noun} from the API, and could not: ${e.body.message}`, { next_step: e.body.next_step ?? { action: 'retry_later' }, details: { cause: e.code } });
+        }
+        throw e;
+    }
+    return parseSchema(doc, noun);
+}
+function unknownNoun(noun, known) {
+    fail('unknown_noun', `c11r has no noun ${noun}.`, { did_you_mean: closest(noun, known), next_step: fixWith('c11r help') });
+}