@chatlychat/cli 0.1.3 → 0.1.5

package/dist/commands/workspace-as-code.js

@@ -0,0 +1,377 @@
+/**
+ * `chatly plan` and `chatly apply` — the workspace as a file.
+ *
+ * ═══ THE ASK ══════════════════════════════════════════════════════════════
+ *
+ * From the integrator who prompted it: "We wrote ~600 lines to idempotently
+ * upsert tools, bots, routes, cards and channel config. Offer a declarative
+ * `chatly.yaml` with `chatly plan` / `chatly apply` (diff, then apply; never
+ * deletes unless told). This is the single biggest DX win for teams that run
+ * more than one environment."
+ *
+ * A CLI rather than a Terraform provider, deliberately. A provider is a
+ * second artifact to version, publish, document and keep in step with 142
+ * routes, and this CLI is already on npm as `@chatlychat/cli` with a release
+ * pipeline. The provider is the better answer for somebody whose whole
+ * platform is Terraform; it is not the better answer for the next six months.
+ *
+ * ═══ THE CONTRACT ═════════════════════════════════════════════════════════
+ *
+ *   plan    reads the live workspace, prints a diff, WRITES NOTHING. Not one
+ *           POST, not one PATCH. `wac.spec.ts` drives the whole path through
+ *           a recording transport and fails if a single non-GET is issued —
+ *           and asserts the GETs it did make, so a plan that silently stopped
+ *           reading cannot pass the same test.
+ *   apply   makes the plan's changes. A resource on the server and absent
+ *           from the document is REPORTED AND LEFT ALONE; `--prune` is the
+ *           only thing that deletes, and there is no way to set it in the
+ *           file. Default safe, as asked.
+ *
+ * ═══ YAML ═════════════════════════════════════════════════════════════════
+ *
+ * This reads JSON. `yaml` is in the lockfile only as a transitive
+ * devDependency of `lint-staged`, which is not reachable from `apps/cli` and
+ * would not ship with the published package either way, and CLAUDE.md §2
+ * forbids adding a dependency without explicit approval. A hand-rolled YAML
+ * subset was considered and rejected: indentation, quoting, anchors and
+ * multi-line scalars are exactly the surface where a parser that is 95%
+ * right produces a document that means something other than it says, which
+ * is worse than one that will not load.
+ *
+ * So a `.yaml` path is refused with the one-line conversion rather than
+ * half-parsed, and `--file -` reads stdin, which makes any converter a pipe.
+ * The documented filename stays `chatly.yaml` in the integrator's words and
+ * `chatly.json` in this implementation; when YAML is approved, `loadDocument`
+ * is the only function that changes.
+ */
+import { readFileSync } from 'node:fs';
+import { bool, str } from '../args.js';
+import { printJson } from '../output.js';
+import { harvestSecrets, renderOutcomes, writesFor, } from '../wac/apply.js';
+import { buildPlan, tally } from '../wac/diff.js';
+import { parseDocument } from '../wac/document.js';
+import { planFooter, planForJson, renderPlan } from '../wac/render.js';
+import { resourceDef } from '../wac/resources.js';
+/** Looked for in order when `--file` is absent. */
+const DEFAULT_FILES = ['chatly.json', 'chatly.yaml', 'chatly.yml'];
+/**
+ * The row cap on `/v1/macros`, used to decide whether `--prune` is safe.
+ *
+ * `@PaginationExempt` routes answer a bare array with no cursor, so a list
+ * that comes back at exactly the cap may be truncated — and a row past the
+ * cap is INVISIBLE, not absent, which would make it an orphan and then a
+ * deletion. `diff.ts` refuses prune for a type in that state. The number is
+ * the handler's, and if it ever rises this becomes conservative rather than
+ * wrong, which is the right direction for a flag that deletes.
+ */
+const EXEMPT_LIST_CAP = 200;
+/* ── Loading ──────────────────────────────────────────────────────────── */
+function readFile(path) {
+    try {
+        // `0` is stdin, so `converter | chatly plan --file -` works.
+        return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function findDefault() {
+    for (const candidate of DEFAULT_FILES) {
+        try {
+            readFileSync(candidate, 'utf8');
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error('No document found. Looked for chatly.json, chatly.yaml and chatly.yml in this ' +
+        'directory.\nPass one with --file, or --file - to read stdin.\n' +
+        'There is a worked example at https://chatlychat.com/docs/sdk-cli#workspace-as-code');
+}
+export function loadDocument(args, env = process.env) {
+    const path = str(args.flags, 'file') ?? findDefault();
+    const raw = readFile(path);
+    if (/\.ya?ml$/i.test(path) || /^\s*(?:version|resources)\s*:/m.test(raw)) {
+        /*
+         * Refused, not half-parsed.
+         *
+         * The second half of that test catches a YAML document passed under a
+         * `.json` name or through stdin, which is the shape of the mistake
+         * somebody makes once. A YAML file handed to `JSON.parse` fails with
+         * "Unexpected token v", which sends the reader looking for a syntax error
+         * in their own file rather than at the one sentence they need.
+         */
+        throw new Error(`${path} looks like YAML, and this CLI reads JSON.\n\n` +
+            'YAML needs a parser, and adding a dependency to a published CLI is a decision this\n' +
+            'repo does not make casually (CLAUDE.md §2) — `yaml` is in the monorepo lockfile only\n' +
+            'as a transitive devDependency of lint-staged, so it is not something we already ship.\n' +
+            'A 95%-right hand-rolled YAML subset is worse than no YAML: it loads a document that\n' +
+            'means something other than what it says.\n\n' +
+            'Convert it and pipe it:\n' +
+            `  npx js-yaml ${path} | chatly plan --file -\n` +
+            '  python3 -c "import sys,yaml,json;json.dump(yaml.safe_load(sys.stdin),sys.stdout)" \\\n' +
+            `    < ${path} | chatly plan --file -`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : '?'}`);
+    }
+    return parseDocument(parsed, env);
+}
+/* ── Reading the live workspace ───────────────────────────────────────── */
+/**
+ * The live rows for every type the document mentions, and nothing else.
+ *
+ * All through `chatly.request` — the escape hatch CONTRACT.md defines — so
+ * auth, retries and the typed errors are the same ones every other command
+ * gets, and `apps/cli` still adds no HTTP of its own. Every call here is a
+ * GET; that is the property `wac.spec.ts` pins.
+ */
+export async function readLive(chatly, doc) {
+    const out = new Map();
+    for (const section of doc.sections) {
+        const { def } = section;
+        if (def.list.paged) {
+            const rows = [];
+            let cursor;
+            /*
+             * Walked by hand rather than through `autoPaginate` because the loop
+             * needs the raw envelope: `@PaginationExempt` neighbours answer a bare
+             * array and this one answers `{ items, nextCursor }`, and conflating
+             * the two is the bug that shipped in two SDKs.
+             */
+            for (let guard = 0; guard < 200; guard += 1) {
+                const page = await chatly.request('GET', def.list.path, {
+                    query: cursor === undefined ? {} : { cursor },
+                });
+                rows.push(...(page.items ?? []));
+                const next = page.nextCursor;
+                if (typeof next !== 'string' || next.length === 0 || next === cursor) {
+                    break;
+                }
+                cursor = next;
+            }
+            out.set(def.type, { rows });
+            continue;
+        }
+        const answer = await chatly.request('GET', def.list.path);
+        const rows = Array.isArray(answer) ? answer : [];
+        out.set(def.type, { rows, possiblyTruncated: rows.length >= EXEMPT_LIST_CAP });
+    }
+    return out;
+}
+/* ── plan ─────────────────────────────────────────────────────────────── */
+export async function plan(chatly, args) {
+    const doc = loadDocument(args);
+    /*
+     * The guard first, before a single read.
+     *
+     * It was second for one revision, which meant a staging document aimed at
+     * production issued nine GETs and computed a whole diff before refusing.
+     * Harmless here because they are reads — and exactly the ordering mistake
+     * that is not harmless in `apply`, where the same code shape would have
+     * written before checking.
+     */
+    const guard = await workspaceGuard(chatly, doc);
+    if (guard !== undefined) {
+        process.stderr.write(`${guard}\n`);
+        return 1;
+    }
+    const live = await readLive(chatly, doc);
+    const built = buildPlan(doc, live, { writeOnly: bool(args.flags, 'write-only') });
+    const opts = { prune: bool(args.flags, 'prune'), pruneUnsafe: built.pruneUnsafe };
+    if (bool(args.flags, 'json')) {
+        printJson(planForJson(built));
+    }
+    else {
+        process.stdout.write(renderPlan(built, opts));
+        process.stdout.write(planFooter(built, opts));
+    }
+    /*
+     * `--exit-code`, off by default.
+     *
+     * CI wants "is production still what the repo says" as an exit status, and
+     * a plan that exits 1 by default would make `chatly plan` unusable in a
+     * shell with `set -e` for the ordinary case of looking. So the behaviour is
+     * opt-in and the code is 2 — distinct from 1, which on this CLI means the
+     * request failed, and conflating "there is drift" with "the call errored"
+     * is how a drift alarm becomes a flake alarm.
+     */
+    if (bool(args.flags, 'exit-code')) {
+        const counts = tally(built);
+        return counts.create + counts.update + counts.blocked > 0 ? 2 : 0;
+    }
+    return built.items.some((i) => i.action === 'blocked') ? 1 : 0;
+}
+/**
+ * `workspace:` in the document, against the key's actual workspace.
+ *
+ * The guard that stops a staging document reaching production. It is checked
+ * on `plan` as well as `apply` — a plan is what somebody reads before they
+ * approve, so a plan computed against the wrong workspace is a worse failure
+ * than an apply that is refused.
+ *
+ * `whoami` is a GET, so this does not spend the no-writes property.
+ */
+async function workspaceGuard(chatly, doc) {
+    if (doc.workspace === undefined) {
+        return undefined;
+    }
+    const me = await chatly.whoami();
+    if (me.workspaceId === doc.workspace) {
+        return undefined;
+    }
+    return (`Refusing to run: the document says \`"workspace": "${doc.workspace}"\` and this key ` +
+        `belongs to ${me.workspaceId}.\n` +
+        'Either point --key / CHATLY_API_KEY at the right workspace, or remove the `workspace` ' +
+        'line if this document is meant to be portable.');
+}
+/* ── apply ────────────────────────────────────────────────────────────── */
+export async function apply(chatly, args) {
+    const doc = loadDocument(args);
+    const guard = await workspaceGuard(chatly, doc);
+    if (guard !== undefined) {
+        process.stderr.write(`${guard}\n`);
+        return 1;
+    }
+    const live = await readLive(chatly, doc);
+    const writeOnly = bool(args.flags, 'write-only');
+    const built = buildPlan(doc, live, { writeOnly });
+    const opts = {
+        prune: bool(args.flags, 'prune'),
+        pruneUnsafe: built.pruneUnsafe,
+        writeOnly,
+    };
+    if (!bool(args.flags, 'json')) {
+        // The plan, then the result. An apply that printed only its result would
+        // make the reader diff two commands' output to find out what it did.
+        process.stdout.write(renderPlan(built, opts));
+        process.stdout.write('\nApplying…\n\n');
+    }
+    const outcomes = await execute(chatly, built, opts);
+    if (bool(args.flags, 'json')) {
+        printJson({ outcomes, warnings: built.warnings });
+    }
+    else {
+        process.stdout.write(renderOutcomes(outcomes));
+    }
+    return outcomes.some((o) => o.state === 'failed' || o.state === 'skipped') ? 1 : 0;
+}
+/**
+ * Walk the plan and do it. Continue on failure; never cascade.
+ *
+ * Exported so `wac.spec.ts` can drive it with a scripted transport and assert
+ * on the requests that went over the wire — the shape CLAUDE.md insists on
+ * ("assert on the request, not the canned response"), since a fake transport
+ * that echoes whatever the caller sent agrees with the bug.
+ */
+export async function execute(chatly, built, opts) {
+    const outcomes = [];
+    /** `type/key` → the id a create in THIS run returned. */
+    const refIds = new Map();
+    /** `type/key` that failed, so its dependents are skipped not attempted. */
+    const failed = new Set();
+    for (const item of built.items) {
+        const def = resourceDef(item.type);
+        if (def === undefined) {
+            continue;
+        }
+        const address = `${item.type}/${item.key}`;
+        if (item.action === 'noop') {
+            continue;
+        }
+        if (item.action === 'blocked') {
+            outcomes.push({ ...base(item), state: 'skipped', detail: item.reason, secrets: [] });
+            continue;
+        }
+        const blocker = item.dependsOn.find((d) => failed.has(d));
+        if (blocker !== undefined) {
+            outcomes.push({
+                ...base(item),
+                state: 'skipped',
+                detail: `${blocker} failed above, and this names it. Attempting it anyway would produce a ` +
+                    'second error about a missing id that points at the wrong thing.',
+                secrets: [],
+            });
+            failed.add(address);
+            continue;
+        }
+        const ops = writesFor(def, item, refIds, opts);
+        if (ops.length === 0) {
+            outcomes.push({
+                ...base(item),
+                state: 'kept',
+                detail: item.action === 'orphan'
+                    ? opts.prune
+                        ? def.remove === null
+                            ? (def.removeBlocked ?? 'no DELETE route.')
+                            : 'this type cannot be pruned safely on this run (see the warnings)'
+                        : '`--prune` would delete it'
+                    : undefined,
+                secrets: [],
+            });
+            continue;
+        }
+        const secrets = [];
+        let ok = true;
+        for (const op of ops) {
+            try {
+                const response = await chatly.request(op.method, op.path, op.body === undefined ? {} : { body: op.body });
+                secrets.push(...harvestSecrets(def, item, response));
+                const id = idOf(response, def);
+                if (id !== undefined) {
+                    refIds.set(address, id);
+                }
+            }
+            catch (err) {
+                ok = false;
+                failed.add(address);
+                outcomes.push({
+                    ...base(item),
+                    state: 'failed',
+                    detail: `${op.method} ${op.path} — ${err instanceof Error ? err.message : String(err)}`,
+                    secrets,
+                });
+                break;
+            }
+        }
+        if (ok) {
+            outcomes.push({ ...base(item), state: 'applied', detail: undefined, secrets });
+        }
+    }
+    return outcomes;
+}
+function base(item) {
+    return { type: item.type, key: item.key, action: item.action };
+}
+/**
+ * The id out of a write response, for a reference a later section needs.
+ *
+ * Two levels, because `POST /v1/customer-cards` answers
+ * `{ card: { id }, secret }` rather than the card itself — the same envelope
+ * quirk that makes the secret sweep two levels deep.
+ */
+function idOf(response, def) {
+    if (typeof response !== 'object' || response === null) {
+        return undefined;
+    }
+    const top = response;
+    const direct = top[def.idField];
+    if (typeof direct === 'string' && direct.length > 0) {
+        return direct;
+    }
+    for (const value of Object.values(top)) {
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const nested = value[def.idField];
+            if (typeof nested === 'string' && nested.length > 0) {
+                return nested;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=workspace-as-code.js.map

package/dist/commands/workspace-as-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-as-code.js","sourceRoot":"","sources":["../../src/commands/workspace-as-code.ts"],"names":[],"mappings":"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"}

package/dist/help.d.ts

@@ -1,2 +1,26 @@
-export declare const HELP = "chatly \u2014 the Chatly command line\n\nUSAGE\n  chatly <command> [subcommand] [flags]\n\nAUTH\n  login                       Store an API key in ~/.config/chatly/config.json (0600)\n  logout                      Remove the stored key\n  whoami                      Which workspace this key belongs to, and its scopes\n\nCONVERSATIONS\n  conversations list          Open conversations, newest first\n  conversations get <id>      One conversation\n  conversations messages <id> The thread\n  conversations send <id> <body>\n                              Reply as the key's machine identity\n  conversations unattended    Open with no agent reply yet\n\nCONTACTS\n  contacts list               People in this workspace\n  contacts get <id>\n  contacts upsert             --email --name --external-id --phone\n  contacts tag <id> <tag>     Add a tag\n  contacts journey <id>       Timeline: conversations, events, tickets\n\nTICKETS\n  tickets list                --status --queue\n  tickets comments <id>\n  tickets queues\n\nKNOWLEDGE + SEARCH\n  search <query>              Across contacts, conversations, messages, tickets, KB\n  kb articles                 Help-centre articles\n  kb article <slug>\n\nEVENTS\n  events track <contact-id> <name>\n                              Fire a CDP event. --prop key=value, repeatable\n  events list                 --contact-id\n\nWEBHOOKS\n  webhooks deliveries         --status\n  webhooks redeliver <id>\n\nREPORTS\n  reports overview            --from --to\n  reports agents\n  reports sla\n\nWORKSPACE\n  workspace settings\n  workspace labels | inboxes | skills\n  workspace team-members <team-id>\n  channels list | channels get <id>\n  billing usage <event-type>  One meter over a window. --from --to\n  billing plans\n\nRAW\n  api <METHOD> <path>         Any route, with auth, idempotency and retries\n                              chatly api GET /v1/feature-flags\n                              chatly api POST /v1/macros --body '{\"name\":\"Refund\"}'\n\nGLOBAL FLAGS\n  --json                      Raw API response instead of a table\n  --all                       Follow pagination to the end (list commands)\n  --limit <n>                 Page size\n  --cursor <c>                Start from a cursor\n  --key <ck_\u2026>                Override the stored key for this call\n  --api-url <url>             Point at another Chatly environment\n  --help, --version\n\nDocs: https://chatlychat.com/docs/cli\n";
+/**
+ * `--help`, and the one thing it has to be: complete.
+ *
+ * ── Why this is 22 sections and not 7 ─────────────────────────────────────
+ *
+ * It was 7. `run.ts`'s own docblock said a check "makes certain that every
+ * command documented in `--help` is reachable — a command with no help entry
+ * is a command nobody finds", and no such check existed: fifteen of the
+ * twenty-two command groups had never been mentioned here, among them `ai`,
+ * `billing`, `bot-routes`, `brands`, `customer-cards`, `docs-sources`,
+ * `email-templates`, `knowledge-gaps`, `macros` and `triggers`.
+ *
+ * A CLI's help IS its documentation. An undocumented command is an unshipped
+ * command, however complete its implementation — the same defect
+ * `check-endpoint-with-no-caller` exists for one layer down.
+ *
+ * `cli.spec.ts` now checks BOTH directions on every run: every key in
+ * `COMMANDS` appears here, and every command word here resolves through
+ * `COMMANDS` or `ALIASES`. The first half is what was missing; the second is
+ * what stops this file growing a promise the CLI does not keep.
+ *
+ * The convention the spec relies on: a command line starts with exactly two
+ * spaces and its first word is the command group.
+ */
+export declare const HELP = "chatly \u2014 the Chatly command line\n\nUSAGE\n  chatly <command> [subcommand] [flags]\n\nAUTH\n  login                       Store an API key in ~/.config/chatly/config.json (0600)\n  logout                      Remove the stored key\n  whoami                      Which workspace this key belongs to, and its scopes\n\nCONVERSATIONS\n  conversations list          Open conversations, newest first\n  conversations get <id>      One conversation\n  conversations messages <id> The thread\n  conversations send <id> <body>\n                              Reply as the key's machine identity\n  conversations unattended    Open with no agent reply yet\n  conversations mood <id>     Sentiment over the thread\n  conversations return-to-bot <id> <bot-id>\n                              Give an open thread back to an assistant\n\nCONTACTS\n  contacts list               People in this workspace\n  contacts get <id>\n  contacts upsert             --email --name --external-id --phone\n  contacts tag <id> <tag>     Add a tag\n  contacts journey <id>       Timeline: conversations, events, tickets\n  contacts cards <id>         Customer-card data for this person\n\nTICKETS\n  tickets list                --status --queue\n  tickets get <id>\n  tickets comments <id>\n  tickets queues\n  tickets lineage <id>        Merge and split history\n  tickets time <id>           Time logged\n  tickets status-history <id>\n\nKNOWLEDGE + SEARCH\n  search <query>              Across contacts, conversations, messages, tickets, KB\n  kb articles                 Help-centre articles\n  kb article <slug>\n  kb collections\n\nEVENTS\n  events track <contact-id> <name>\n                              Fire a CDP event. --prop key=value, repeatable\n  events list                 --contact-id\n\nBOTS + EXTERNAL AGENTS\n  bots list | get <id>\n  bots create                 --body. type:\"external\" answers with a secret, ONCE\n  bots update <id>            --body\n  bots update-external <id>   --body. webhookUrl, timeoutSeconds, fallbackMessage\n  bots rotate-secret <id>     New signing secret, shown once. No overlap window\n  bots deliveries <id>        The push ledger. --status pending|delivered|failed|dead\n  bots delivery <id> <delivery-id>\n                              One delivery, with the exact signed payload\n  bots redeliver <id> <delivery-id>\n                              Queue the recorded payload again, from attempt 0\n  bots test-delivery <id>     Sign and POST a rehearsal payload; prints the response\n\nROUTING + AUTOMATION\n  bot-routes list | fields | create | update <id> | delete <id>\n  bot-routes resolve          Dry-run the table. --body with a hypothetical visitor\n  triggers list | get <id> | upsert | delete <id>\n  brands list | get <id> | create | update <id> | delete <id>\n  macros list | get <id> | create | update <id> | delete <id>\n  email-templates templates | get <kind> | set <kind> | reset <kind>\n  knowledge-gaps list | triage <id>\n\nINTEGRATIONS\n  webhooks deliveries         --status\n  webhooks delivery <id>\n  webhooks redeliver <id>\n  webhooks endpoints          Subscriptions, not traffic\n  webhooks events             The subscribable event catalogue\n  webhooks schema-versions\n  webhooks create             --url --event (repeatable). Answers with whsec_, once\n  webhooks pin <id> <version>\n  customer-cards list | create | update <id> | delete <id>\n  customer-cards rotate-secret <id>\n                              Update your endpoint BEFORE calling this\n  docs-sources list | providers | discover | create | update <id> | delete <id>\n  docs-sources sync <id>      --full re-reads every page\n  docs-sources subscribe <id> A refusal is a success: read the response\n  channels list | get <id> | adapters | create | update <id>\n  channels rotate-secret <id>\n\nWORKSPACE AS CODE\n  plan                        Diff chatly.json against the live workspace. Reads only\n  apply                       Make the plan's changes. Never deletes unless told\n                              --file <path>   the document (- for stdin). Default: ./chatly.json\n                              --prune         also delete what the document omits\n                              --write-only    also send fields that cannot be read back\n                              --exit-code     plan only: exit 2 when there is drift\n\nAI\n  ai providers | quota\n  ai add-provider             BYOK. --body\n  ai test-provider <key>\n  ai tools | create-tool | update-tool <id> | delete-tool <id>\n  ai tone | set-tone | generate-tone <sample>\n\nREPORTS\n  reports overview            --days\n  reports agents              Means, not percentiles\n  reports conversations-by-day\n  reports sources | response-times | voice\n  reports attribution <dim>   One of ten dimensions; an unknown one is refused\n  reports cohorts             --weeks, NOT --days\n  reports themes              --date. A daily snapshot; there is no regenerate\n  reports theme-conversations <theme-id>\n  reports teams | labels | sla\n                              --from --to --days --group-by\n\nBILLING\n  billing summary | plans | invoices\n  billing usage <event-type>  One meter over a window. --from --to\n  billing usage-daily <event-type>\n                              Dense: one row per UTC day, zeros included\n  billing usage-monthly       --month\n\nWORKSPACE\n  workspace settings\n  workspace labels | inboxes | skills\n  workspace team-members <team-id>\n  workspace key-scopes        What a key may be granted\n\nRAW\n  api <METHOD> <path>         Any route, with auth, idempotency and retries\n                              chatly api GET /v1/feature-flags\n                              chatly api POST /v1/macros --body '{\"name\":\"Refund\"}'\n\nGLOBAL FLAGS\n  --json                      Raw API response instead of a table\n  --all                       Follow pagination to the end (list commands)\n  --limit <n>                 Page size\n  --cursor <c>                Start from a cursor\n  --key <ck_\u2026>                Override the stored key for this call\n  --api-url <url>             Point at another Chatly environment\n  --help, --version\n\nDocs: https://chatlychat.com/docs/sdk-cli\n";
 //# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,k6EAwEhB,CAAC"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,8lMAgJhB,CAAC"}

package/dist/help.js

@@ -1,3 +1,27 @@
+/**
+ * `--help`, and the one thing it has to be: complete.
+ *
+ * ── Why this is 22 sections and not 7 ─────────────────────────────────────
+ *
+ * It was 7. `run.ts`'s own docblock said a check "makes certain that every
+ * command documented in `--help` is reachable — a command with no help entry
+ * is a command nobody finds", and no such check existed: fifteen of the
+ * twenty-two command groups had never been mentioned here, among them `ai`,
+ * `billing`, `bot-routes`, `brands`, `customer-cards`, `docs-sources`,
+ * `email-templates`, `knowledge-gaps`, `macros` and `triggers`.
+ *
+ * A CLI's help IS its documentation. An undocumented command is an unshipped
+ * command, however complete its implementation — the same defect
+ * `check-endpoint-with-no-caller` exists for one layer down.
+ *
+ * `cli.spec.ts` now checks BOTH directions on every run: every key in
+ * `COMMANDS` appears here, and every command word here resolves through
+ * `COMMANDS` or `ALIASES`. The first half is what was missing; the second is
+ * what stops this file growing a promise the CLI does not keep.
+ *
+ * The convention the spec relies on: a command line starts with exactly two
+ * spaces and its first word is the command group.
+ */
 export const HELP = `chatly — the Chatly command line
 
 USAGE
@@ -15,6 +39,9 @@ CONVERSATIONS
   conversations send <id> <body>
                               Reply as the key's machine identity
   conversations unattended    Open with no agent reply yet
+  conversations mood <id>     Sentiment over the thread
+  conversations return-to-bot <id> <bot-id>
+                              Give an open thread back to an assistant
 
 CONTACTS
   contacts list               People in this workspace
@@ -22,38 +49,107 @@ CONTACTS
   contacts upsert             --email --name --external-id --phone
   contacts tag <id> <tag>     Add a tag
   contacts journey <id>       Timeline: conversations, events, tickets
+  contacts cards <id>         Customer-card data for this person
 
 TICKETS
   tickets list                --status --queue
+  tickets get <id>
   tickets comments <id>
   tickets queues
+  tickets lineage <id>        Merge and split history
+  tickets time <id>           Time logged
+  tickets status-history <id>
 
 KNOWLEDGE + SEARCH
   search <query>              Across contacts, conversations, messages, tickets, KB
   kb articles                 Help-centre articles
   kb article <slug>
+  kb collections
 
 EVENTS
   events track <contact-id> <name>
                               Fire a CDP event. --prop key=value, repeatable
   events list                 --contact-id
 
-WEBHOOKS
+BOTS + EXTERNAL AGENTS
+  bots list | get <id>
+  bots create                 --body. type:"external" answers with a secret, ONCE
+  bots update <id>            --body
+  bots update-external <id>   --body. webhookUrl, timeoutSeconds, fallbackMessage
+  bots rotate-secret <id>     New signing secret, shown once. No overlap window
+  bots deliveries <id>        The push ledger. --status pending|delivered|failed|dead
+  bots delivery <id> <delivery-id>
+                              One delivery, with the exact signed payload
+  bots redeliver <id> <delivery-id>
+                              Queue the recorded payload again, from attempt 0
+  bots test-delivery <id>     Sign and POST a rehearsal payload; prints the response
+
+ROUTING + AUTOMATION
+  bot-routes list | fields | create | update <id> | delete <id>
+  bot-routes resolve          Dry-run the table. --body with a hypothetical visitor
+  triggers list | get <id> | upsert | delete <id>
+  brands list | get <id> | create | update <id> | delete <id>
+  macros list | get <id> | create | update <id> | delete <id>
+  email-templates templates | get <kind> | set <kind> | reset <kind>
+  knowledge-gaps list | triage <id>
+
+INTEGRATIONS
   webhooks deliveries         --status
+  webhooks delivery <id>
   webhooks redeliver <id>
+  webhooks endpoints          Subscriptions, not traffic
+  webhooks events             The subscribable event catalogue
+  webhooks schema-versions
+  webhooks create             --url --event (repeatable). Answers with whsec_, once
+  webhooks pin <id> <version>
+  customer-cards list | create | update <id> | delete <id>
+  customer-cards rotate-secret <id>
+                              Update your endpoint BEFORE calling this
+  docs-sources list | providers | discover | create | update <id> | delete <id>
+  docs-sources sync <id>      --full re-reads every page
+  docs-sources subscribe <id> A refusal is a success: read the response
+  channels list | get <id> | adapters | create | update <id>
+  channels rotate-secret <id>
+
+WORKSPACE AS CODE
+  plan                        Diff chatly.json against the live workspace. Reads only
+  apply                       Make the plan's changes. Never deletes unless told
+                              --file <path>   the document (- for stdin). Default: ./chatly.json
+                              --prune         also delete what the document omits
+                              --write-only    also send fields that cannot be read back
+                              --exit-code     plan only: exit 2 when there is drift
+
+AI
+  ai providers | quota
+  ai add-provider             BYOK. --body
+  ai test-provider <key>
+  ai tools | create-tool | update-tool <id> | delete-tool <id>
+  ai tone | set-tone | generate-tone <sample>
 
 REPORTS
-  reports overview            --from --to
-  reports agents
-  reports sla
+  reports overview            --days
+  reports agents              Means, not percentiles
+  reports conversations-by-day
+  reports sources | response-times | voice
+  reports attribution <dim>   One of ten dimensions; an unknown one is refused
+  reports cohorts             --weeks, NOT --days
+  reports themes              --date. A daily snapshot; there is no regenerate
+  reports theme-conversations <theme-id>
+  reports teams | labels | sla
+                              --from --to --days --group-by
+
+BILLING
+  billing summary | plans | invoices
+  billing usage <event-type>  One meter over a window. --from --to
+  billing usage-daily <event-type>
+                              Dense: one row per UTC day, zeros included
+  billing usage-monthly       --month
 
 WORKSPACE
   workspace settings
   workspace labels | inboxes | skills
   workspace team-members <team-id>
-  channels list | channels get <id>
-  billing usage <event-type>  One meter over a window. --from --to
-  billing plans
+  workspace key-scopes        What a key may be granted
 
 RAW
   api <METHOD> <path>         Any route, with auth, idempotency and retries
@@ -69,6 +165,6 @@ GLOBAL FLAGS
   --api-url <url>             Point at another Chatly environment
   --help, --version
 
-Docs: https://chatlychat.com/docs/cli
+Docs: https://chatlychat.com/docs/sdk-cli
 `;
 //# sourceMappingURL=help.js.map

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwEnB,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgJnB,CAAC"}

package/dist/run.d.ts

@@ -7,6 +7,23 @@
  * errors are unhelpful, we feel it first.
  */
 import { ChatlyClient } from '@chatlychat/sdk-node';
+import { type ParsedArgs } from './args.js';
+/**
+ * Every authenticated command, by the word a person types.
+ *
+ * A table rather than a `switch`, for one reason that is worth the churn:
+ * `cli.spec.ts` can now assert that every key here appears in `--help` and
+ * that every command documented in `--help` is reachable. A command with no
+ * help entry is a command nobody finds; a help entry with no command is a
+ * promise the CLI breaks. The `switch` this replaced could be checked for
+ * neither.
+ *
+ * Singular aliases are listed explicitly rather than derived by stripping an
+ * `s`, so `kb`, `search`, `whoami` and `ai` cannot acquire a nonsense twin.
+ */
+export declare const COMMANDS: Readonly<Record<string, (c: ChatlyClient, a: ParsedArgs) => Promise<number>>>;
+/** Singular spellings, for the groups where typing one reads naturally. */
+export declare const ALIASES: Readonly<Record<string, string>>;
 /**
  * How a client is made. Injectable for tests ONLY.
  *

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAkB,YAAY,EAAwB,MAAM,sBAAsB,CAAC;AAsB1F;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,YAAY,CAAC;AAIxF,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,UAAU,GAAE,aAA8B,GACzC,OAAO,CAAC,MAAM,CAAC,CAmFjB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAoBvE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAkB,YAAY,EAAwB,MAAM,sBAAsB,CAAC;AAE1F,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAyBlE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAC7B,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CA+CpE,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAiBpD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,YAAY,CAAC;AAIxF,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,UAAU,GAAE,aAA8B,GACzC,OAAO,CAAC,MAAM,CAAC,CAkDjB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAqBvE"}