@chatlychat/cli 0.1.4 → 0.1.6

package/dist/commands/config.js

@@ -0,0 +1,336 @@
+/**
+ * Config-as-code: the surface an integrator keeps in a repository.
+ *
+ * Bots, routing rules, triggers, brands, transactional email copy and macros
+ * are all workspace CONFIGURATION — the things a team wants reviewed in a
+ * pull request and applied from CI, not clicked through a settings screen.
+ * That is the reason the SDK manifest grew from 55 routes to 142, and it is
+ * the reason these are commands rather than `chatly api` calls.
+ *
+ * ── One idiom for every write ─────────────────────────────────────────────
+ *
+ * Writes take a JSON document (`--file`, `--file -`, or `--body`), not a flag
+ * per field. These bodies are nested — a bot carries guardrails, a KB scope
+ * and an escalation-rule array — and `bodyFrom` explains why a flag per field
+ * would be both a worse CLI and a second place for a key name to be wrong.
+ *
+ * ── Transport ─────────────────────────────────────────────────────────────
+ *
+ * Through `ChatlyClient.request`, the escape hatch the SDK contract defines
+ * for key-accessible routes with no typed method. It is the same auth, the
+ * same `Idempotency-Key` per write, the same retry policy and the same typed
+ * errors a named method would get — `apps/cli` adds no HTTP of its own.
+ */
+import { bool, str } from '../args.js';
+import { bodyFrom, need, pagedVia, queryFrom, renderList, showObject, showRows } from './common.js';
+export async function bots(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list': {
+            // A real cursor page, and the only one on this file's surface.
+            const pages = pagedVia(chatly, '/v1/bots');
+            return renderList(args, ['id', 'name', 'slug', 'status', 'model'], pages.onePage, pages.everyPage);
+        }
+        case 'get':
+            return showObject(await chatly.request('GET', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}`));
+        case 'create':
+            /*
+             * `type: "external"` creates a customer's own push-delivered agent and
+             * answers with a signing secret and a `cb_` token, EACH SHOWN ONCE.
+             * There is no route that reads them back, so this prints the whole
+             * response rather than a summary line.
+             */
+            return showObject(await chatly.request('POST', '/v1/bots', { body: bodyFrom(args, 'the bot') }));
+        case 'update':
+            return showObject(await chatly.request('PATCH', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}`, {
+                body: bodyFrom(args, 'the fields to change'),
+            }));
+        case 'update-external':
+            return showObject(await chatly.request('PATCH', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}/external`, { body: bodyFrom(args, "the external agent's webhook, timeout or fallback copy") }));
+        case 'rotate-secret':
+            // Shown once, and the old secret stops working the moment this returns.
+            return showObject(await chatly.request('POST', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}/external/rotate-secret`));
+        /* ── An external agent's delivery ledger ──────────────────────────── */
+        case 'deliveries': {
+            /*
+             * The columns an integrator reading this is actually looking for.
+             *
+             * `status` first because it answers the question — `failed` will be
+             * retried, `dead` will not — and `httpStatus` beside it because the
+             * pair is the diagnosis: `dead` with a 401 is their signature check,
+             * `dead` with a null is a timeout or DNS, `failed` with a 503 is their
+             * load balancer and will fix itself.
+             *
+             * The signed `payload` is deliberately not a column and is not on a
+             * list row at all: `bots delivery <bot> <delivery>` serves it.
+             */
+            const botId = need(args, 2, 'a bot id');
+            const status = str(args.flags, 'status');
+            const pages = pagedVia(chatly, `/v1/bots/${encodeURIComponent(botId)}/deliveries`, status === undefined ? {} : { status });
+            return renderList(args, ['id', 'status', 'attempt', 'httpStatus', 'durationMs', 'createdAt', 'error'], pages.onePage, pages.everyPage);
+        }
+        case 'delivery':
+            // With `payload` — the exact object that was serialised and signed.
+            return showObject(await chatly.request('GET', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}/deliveries/` +
+                encodeURIComponent(need(args, 3, 'a delivery id'))));
+        case 'redeliver':
+            /*
+             * The RECORDED payload, same `eventId`, from attempt 0.
+             *
+             * Which means a receiver's own dedupe will discard it if they already
+             * processed that id — correct behaviour on their side, and the reason
+             * this is for deliveries that never got through rather than for
+             * re-running one.
+             */
+            return showObject(await chatly.request('POST', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}/deliveries/` +
+                `${encodeURIComponent(need(args, 3, 'a delivery id'))}/redeliver`));
+        case 'test-delivery':
+            /*
+             * Signs a rehearsal payload with the real secret, POSTs it to the real
+             * URL, and prints the response — so a 401 from your own verifier
+             * arrives here rather than in a log twenty minutes later.
+             *
+             * Printed WHOLE: `signature` and `payload` are the two fields worth
+             * having, because they are the exact header value and the exact object
+             * whose serialisation was signed, which is what you need to debug a
+             * verifier offline.
+             *
+             * Writes nothing, so it does not appear under `bots deliveries`.
+             */
+            return showObject(await chatly.request('POST', `/v1/bots/${encodeURIComponent(need(args, 2, 'a bot id'))}/test-delivery`));
+        default:
+            throw new Error(`Unknown: bots ${sub}`);
+    }
+}
+export async function botRoutes(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list':
+            // A bare array in evaluation order — not a cursor page, so no `--all`.
+            return showRows(args, await chatly.request('GET', '/v1/bot-routes'), [
+                'id',
+                'name',
+                'botId',
+                'priority',
+                'enabled',
+                'evaluate',
+            ]);
+        case 'resolve':
+            /*
+             * The dry-run. `--body` carries the hypothetical visitor:
+             *
+             *   chatly bot-routes resolve --body '{"page":{"path":"/shop/checkout"},
+             *     "context":{"verified":{"audience":"buyer"}}}'
+             *
+             * Printed WHOLE rather than as a table. The answer is three things —
+             * which route won, why each other route lost, and the event object the
+             * conditions were evaluated against — and the third is where you find
+             * out that a field path resolves to nothing, which is half of every
+             * routing bug.
+             */
+            return showObject(await chatly.request('POST', '/v1/bot-routes/resolve', {
+                body: args.flags['body'] === undefined ? {} : bodyFrom(args, 'the hypothetical visitor'),
+            }));
+        case 'fields':
+            // The condition vocabulary. Read this before authoring a rule: a
+            // condition naming a field that is not here is rejected on the write.
+            return showObject(await chatly.request('GET', '/v1/bot-routes/fields'));
+        case 'create':
+            return showObject(await chatly.request('POST', '/v1/bot-routes', {
+                body: bodyFrom(args, 'the routing rule'),
+            }));
+        case 'update':
+            return showObject(await chatly.request('PATCH', `/v1/bot-routes/${encodeURIComponent(need(args, 2, 'a route id'))}`, { body: bodyFrom(args, 'the fields to change') }));
+        case 'delete':
+            return showObject(await chatly.request('DELETE', `/v1/bot-routes/${encodeURIComponent(need(args, 2, 'a route id'))}`));
+        default:
+            throw new Error(`Unknown: bot-routes ${sub}`);
+    }
+}
+export async function triggers(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list': {
+            const pages = pagedVia(chatly, '/v1/triggers');
+            return renderList(args, ['id', 'name', 'eventType', 'enabled', 'priority'], pages.onePage, pages.everyPage);
+        }
+        /*
+         * `upsert`, not `create`.
+         *
+         * The manifest calls this route `triggers.create`, but `POST /v1/triggers`
+         * is an UPSERT: the handler is named `upsert`, it answers 201 on both
+         * arms, and a body carrying an existing trigger's identity replaces it.
+         * `create` is kept as an alias so the manifest's name works, but the
+         * documented verb is the one the route performs — a CLI that calls this
+         * "create" invites someone to run it twice expecting a second trigger.
+         */
+        case 'upsert':
+        case 'create':
+            return showObject(await chatly.request('POST', '/v1/triggers', { body: bodyFrom(args, 'the trigger') }));
+        case 'delete':
+            // 200 with `{ ok: true }`, not a 204.
+            return showObject(await chatly.request('DELETE', `/v1/triggers/${encodeURIComponent(need(args, 2, 'a trigger id'))}`));
+        default:
+            throw new Error(`Unknown: triggers ${sub}`);
+    }
+}
+export async function brands(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list':
+            return showRows(args, await chatly.request('GET', '/v1/brands'), [
+                'id',
+                'name',
+                'slug',
+                'domain',
+                'isDefault',
+            ]);
+        case 'create':
+            return showObject(await chatly.request('POST', '/v1/brands', { body: bodyFrom(args, 'the brand') }));
+        case 'update':
+            return showObject(await chatly.request('PATCH', `/v1/brands/${encodeURIComponent(need(args, 2, 'a brand id'))}`, { body: bodyFrom(args, 'the fields to change') }));
+        case 'delete':
+            // A soft delete that answers 200 with `{ id }` — that id is the only
+            // confirmation, so print it rather than saying "deleted".
+            return showObject(await chatly.request('DELETE', `/v1/brands/${encodeURIComponent(need(args, 2, 'a brand id'))}`));
+        default:
+            throw new Error(`Unknown: brands ${sub}`);
+    }
+}
+export async function emailTemplates(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list':
+            /*
+             * All five kinds, always — this is the CATALOGUE, not the rows. A kind
+             * the workspace has not customised comes back with `override: null`,
+             * which is the field to read to tell a customised kind from a built-in
+             * one.
+             */
+            return showRows(args, await chatly.request('GET', '/v1/email-templates'), [
+                'kind',
+                'label',
+                'audience',
+                'whenSent',
+                'override',
+            ]);
+        case 'set':
+            // A PUT: it REPLACES this workspace's copy, it does not merge into it.
+            return showObject(await chatly.request('PUT', `/v1/email-templates/${encodeURIComponent(need(args, 2, 'a template kind'))}`, { body: bodyFrom(args, 'the subject, html and text') }));
+        /*
+         * `reset`, with `delete` as an alias.
+         *
+         * `DELETE /v1/email-templates/{kind}` does not delete a template — it
+         * drops the workspace's OVERRIDE and puts the built-in copy back, and it
+         * answers 200 with `{ restored: false }` when there was nothing to drop.
+         * Printing that flag is the only way to tell "I just reverted your copy"
+         * from "there was nothing to revert".
+         */
+        case 'reset':
+        case 'delete':
+            return showObject(await chatly.request('DELETE', `/v1/email-templates/${encodeURIComponent(need(args, 2, 'a template kind'))}`));
+        default:
+            throw new Error(`Unknown: email-templates ${sub}`);
+    }
+}
+export async function macros(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list': {
+            /*
+             * NOT cursor-paginated: `@PaginationExempt`, a bare array capped at 200
+             * and ordered by usage rank. The shared manifest flagged this `paged`
+             * for a day and two SDKs built a paginator over it.
+             *
+             * `--query`, not `--q`. The handler's schema names it `query`, and zod
+             * would strip `q` without a word — the search would run unnarrowed and
+             * answer 200.
+             */
+            if (bool(args.flags, 'all')) {
+                process.stderr.write('--all is not available for macros (the route is not cursor-paginated; it ' +
+                    'answers a bare array capped at 200 rows).\n');
+                return 1;
+            }
+            const rows = await chatly.request('GET', '/v1/macros', {
+                query: queryFrom(args, [
+                    ['scope', 'scope'],
+                    ['team', 'team'],
+                    ['query', 'query'],
+                    ['language', 'language'],
+                ]),
+            });
+            return showRows(args, rows, ['id', 'name', 'shortCode', 'scope', 'language', 'usageCount']);
+        }
+        case 'get':
+            return showObject(await chatly.request('GET', `/v1/macros/${encodeURIComponent(need(args, 2, 'a macro id'))}`));
+        case 'actions':
+            // The action registry a macro's `actions` array may reference. A macro
+            // naming an action that is not here is a 422 at RUN time, not at save
+            // time, so this is the list to check before writing one.
+            return showObject(await chatly.request('GET', '/v1/macros/actions'));
+        case 'templates':
+            return showObject(await chatly.request('GET', '/v1/macros/templates'));
+        case 'template':
+            return showObject(await chatly.request('GET', `/v1/macros/templates/${encodeURIComponent(need(args, 2, 'a template slug'))}`));
+        case 'create':
+            return showObject(await chatly.request('POST', '/v1/macros', { body: bodyFrom(args, 'the macro') }));
+        case 'update':
+            return showObject(await chatly.request('PATCH', `/v1/macros/${encodeURIComponent(need(args, 2, 'a macro id'))}`, { body: bodyFrom(args, 'the fields to change') }));
+        case 'delete': {
+            // The only real 204 on the whole SDK surface: no body comes back, so
+            // there is nothing to print but a confirmation.
+            const id = need(args, 2, 'a macro id');
+            await chatly.request('DELETE', `/v1/macros/${encodeURIComponent(id)}`);
+            if (bool(args.flags, 'json')) {
+                return showObject({ deleted: id });
+            }
+            process.stdout.write(`deleted ${id}\n`);
+            return 0;
+        }
+        default:
+            throw new Error(`Unknown: macros ${sub}`);
+    }
+}
+/**
+ * Knowledge gaps: the questions the KB could not answer, and the loop that
+ * closes them.
+ *
+ * `list` → pick the most-asked → `draft` → the article exists → `triage` it
+ * resolved. That whole loop is a terminal job, which is why it is a command.
+ */
+export async function knowledgeGaps(chatly, args) {
+    const sub = args.path[1] ?? 'list';
+    switch (sub) {
+        case 'list':
+            /*
+             * `--limit` here is a plain row cap, NOT a page size: the route is
+             * `@PaginationExempt` and the recorder caps a workspace at 200 open
+             * gaps, so there is no cursor to follow and `--all` is not offered.
+             */
+            return showRows(args, await chatly.request('GET', '/v1/knowledge-gaps', {
+                query: queryFrom(args, [
+                    ['status', 'status'],
+                    ['limit', 'limit', true],
+                ]),
+            }), ['id', 'question', 'occurrences', 'status', 'lastSeenAt', 'articleId']);
+        case 'triage':
+        case 'update': {
+            const id = need(args, 2, 'a gap id');
+            // `{ status }`, strict — one of open / drafted / resolved / dismissed.
+            const status = args.path[3] ?? str(args.flags, 'status');
+            if (status === undefined) {
+                throw new Error('Give a status: `chatly knowledge-gaps triage <id> <status>`.\n' +
+                    'One of: open, drafted, resolved, dismissed.');
+            }
+            return showObject(await chatly.request('PATCH', `/v1/knowledge-gaps/${encodeURIComponent(id)}`, {
+                body: { status },
+            }));
+        }
+        case 'draft':
+            // Creates a DRAFT article from the gap — 201, and nothing is published.
+            return showObject(await chatly.request('POST', `/v1/knowledge-gaps/${encodeURIComponent(need(args, 2, 'a gap id'))}/draft`));
+        default:
+            throw new Error(`Unknown: knowledge-gaps ${sub}`);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

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

package/dist/commands/insights.d.ts

@@ -0,0 +1,5 @@
+import { type ParsedArgs } from '../args.js';
+import type { ChatlyClient } from '@chatlychat/sdk-node';
+export declare function reports(chatly: ChatlyClient, args: ParsedArgs): Promise<number>;
+export declare function billing(chatly: ChatlyClient, args: ParsedArgs): Promise<number>;
+//# sourceMappingURL=insights.d.ts.map

package/dist/commands/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["../../src/commands/insights.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7D,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,sBAAsB,CAAC;AAyBzE,wBAAsB,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAyIrF;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmIrF"}

package/dist/commands/insights.js

@@ -0,0 +1,277 @@
+/**
+ * Numbers without opening the dashboard: reports, billing and usage.
+ *
+ * ── The window is NOT the same on every report, and that was a live bug ──
+ *
+ * These commands used to pass `--from`/`--to` to every report. Three of the
+ * four they covered do not read them: `reports/overview`, `reports/agents`
+ * and `reports/conversations-by-day` take `@Query('days')` and nothing else,
+ * so `chatly reports overview --from 2026-01-01 --to 2026-02-01` answered for
+ * the last SEVEN days and said nothing about it. That is the zod-strips-an-
+ * unknown-key failure in its query form: a confident report of the wrong
+ * window.
+ *
+ * So the window flags differ per report, deliberately, and each group below
+ * says which it accepts:
+ *
+ *   --days                       overview, agents, conversations-by-day,
+ *                                sources, response-times, voice, attribution
+ *   --weeks                      cohorts, and ONLY cohorts
+ *   --date                       themes
+ *   --from --to --days --group-by  teams, labels, sla   (`reports-extended`)
+ *
+ * The last group is the only one that resolves a real range, and its two
+ * snake_case names (`group_by`, `business_hours`) are the only snake_case
+ * query parameters on the whole SDK surface.
+ */
+import { ATTRIBUTION_DIMENSIONS } from '@chatlychat/sdk-node';
+import { bool, num, str } from '../args.js';
+import { printJson } from '../output.js';
+import { DAYS, RANGE, need, queryFrom, showObject, showRows } from './common.js';
+/**
+ * The ten dimensions `reports/attribution` accepts.
+ *
+ * Listed here because the route REFUSES an unknown value rather than
+ * defaulting to `utm_source` — a typo quietly answered as something else
+ * would be a confident report of the wrong thing, and the caller would have
+ * no way to notice. Printing the list on a refusal saves a round trip.
+ */
+/*
+ * Imported from the SDK, not re-listed. This file kept its own copy of the
+ * ten so it could print them on a refusal; the SDK now exports the array as
+ * a value for exactly that, so there is one list in this dependency chain
+ * instead of two.
+ */
+/** The four meters `billing/usage` and `billing/usage/daily` accept. */
+const USAGE_EVENT_TYPES = [
+    'conversation.opened',
+    'message.sent.agent',
+    'message.sent.bot',
+    'ai.tokens',
+];
+export async function reports(chatly, args) {
+    const sub = args.path[1] ?? 'overview';
+    const days = () => queryFrom(args, DAYS);
+    switch (sub) {
+        // ── `?days` only ──────────────────────────────────────────────────────
+        case 'overview':
+            return showObject(await chatly.reports.overview(days()));
+        case 'agents':
+            // A BARE ARRAY, and the latency figures here are MEANS. The
+            // percentiles are on `reports response-times`.
+            return showRows(args, await chatly.reports.agents(days()), [
+                'userId',
+                'name',
+                'conversations',
+                'messages',
+                'csatAverage',
+            ]);
+        case 'conversations-by-day':
+            // A bare array, and days with no conversations are ABSENT rather than
+            // zero — a caller plotting a series has to fill the gaps itself.
+            return showRows(args, await chatly.reports.conversationsByDay(days()), ['day', 'count']);
+        case 'sources':
+            return showRows(args, await chatly.request('GET', '/v1/reports/sources', { query: days() }), [
+                'channelType',
+                'channelId',
+                'channelName',
+                'conversations',
+            ]);
+        case 'response-times':
+            // p50/p95 for first response and resolution. Percentiles are null when
+            // `sampleSize` is 0, which is not the same as zero seconds.
+            return showObject(await chatly.request('GET', '/v1/reports/response-times', { query: days() }));
+        case 'voice':
+            // Rates are 0-1, not percentages, and `recordingStorage.exact: false`
+            // means the byte total is part extrapolation.
+            return showObject(await chatly.request('GET', '/v1/reports/voice', { query: days() }));
+        // ── `?dimension` + `?days` ────────────────────────────────────────────
+        case 'attribution': {
+            const dimension = str(args.flags, 'dimension') ?? args.path[2];
+            if (dimension !== undefined &&
+                !ATTRIBUTION_DIMENSIONS.includes(dimension)) {
+                throw new Error(`--dimension must be one of: ${ATTRIBUTION_DIMENSIONS.join(', ')}.\n` +
+                    'The route refuses an unknown value rather than defaulting, so a typo ' +
+                    'cannot become a report of the wrong thing.');
+            }
+            // The row with `value: null` is the UNTAGGED bucket and is a real row —
+            // dropping it inflates every other percentage.
+            return showRows(args, await chatly.request('GET', '/v1/reports/attribution', {
+                query: { ...days(), ...(dimension === undefined ? {} : { dimension }) },
+            }), ['value', 'conversations', 'closed', 'percentage']);
+        }
+        // ── `?weeks`, and only `?weeks` ───────────────────────────────────────
+        case 'cohorts': {
+            /*
+             * `weeks`, NOT `days`. A `--days` here would be stripped by the
+             * handler's query read and the report would silently use its default
+             * of 8 weeks. The response echoes the CLAMPED window it actually used
+             * (2-26), which can differ from what was asked for — label axes off
+             * the echo, not off the input.
+             */
+            const weeks = num(args.flags, 'weeks');
+            return showObject(await chatly.request('GET', '/v1/reports/cohorts', {
+                query: weeks === undefined ? {} : { weeks },
+            }));
+        }
+        // ── `?date` ───────────────────────────────────────────────────────────
+        case 'themes':
+            /*
+             * A SNAPSHOT, generated by a daily worker job. There is no regenerate.
+             * `batchDate` names the batch every row was measured over and is null
+             * with an empty list when none has been generated. Rows omit
+             * `conversationIds` — `reports theme-conversations <id>` serves those.
+             */
+            return showObject(await chatly.request('GET', '/v1/reports/themes', {
+                query: queryFrom(args, [['date', 'date']]),
+            }));
+        case 'theme-conversations':
+            // An unknown or purged theme id answers 200 with an EMPTY list, not a
+            // 404 — this route cannot tell the two apart, and neither can you.
+            return showObject(await chatly.request('GET', `/v1/reports/themes/${encodeURIComponent(need(args, 2, 'a theme id'))}/conversations`));
+        // ── The full window contract ──────────────────────────────────────────
+        case 'teams':
+            /*
+             * `businessHours.applied: false` means the duration figures are
+             * CALENDAR time and `businessHours.reason` says why. The numbers are
+             * never zeroed and never relabelled, so read the flag before captioning
+             * them.
+             */
+            return showObject(await chatly.request('GET', '/v1/reports/teams', { query: queryFrom(args, RANGE) }));
+        case 'labels':
+            // Capped at the 50 busiest labels, with the remainder in
+            // `otherLabels`; `trend` covers the top 8 only. There is no cursor, so
+            // there is no way to page to the tail.
+            return showObject(await chatly.request('GET', '/v1/reports/labels', { query: queryFrom(args, RANGE) }));
+        case 'sla':
+            /*
+             * `--business-hours` is accepted by the two above and IGNORED here: the
+             * handler reads the range and passes only that to the service. It is
+             * left in `RANGE` rather than special-cased because the parameter is
+             * harmless, but do not read an SLA figure as business-hours-adjusted.
+             *
+             * `breachesTruncated` is true when the breach list hit its 200-row cap.
+             */
+            return showObject(await chatly.reports.sla(queryFrom(args, RANGE)));
+        default:
+            throw new Error(`Unknown: reports ${sub}`);
+    }
+}
+export async function billing(chatly, args) {
+    const sub = args.path[1] ?? 'summary';
+    const range = () => {
+        const out = {};
+        const from = str(args.flags, 'from');
+        if (from !== undefined) {
+            out['from'] = from;
+        }
+        const to = str(args.flags, 'to');
+        if (to !== undefined) {
+            out['to'] = to;
+        }
+        return out;
+    };
+    /**
+     * The meter, from a positional or `--event-type`.
+     *
+     * Required by `/v1/billing/usage` and `/v1/billing/usage/daily`: both
+     * validate it against a closed list and throw before doing anything else,
+     * so a call without it is a guaranteed 400 rather than a summary of
+     * everything. Four SDKs shipped it as optional.
+     */
+    const meter = (what) => {
+        const value = args.path[2] ?? str(args.flags, 'event-type');
+        if (value === undefined) {
+            throw new Error(`Give a meter: \`chatly billing ${what} <event-type>\`.\n` +
+                `One of: ${USAGE_EVENT_TYPES.join(', ')}.\n` +
+                'The route reports ONE meter over a window, not a summary of everything.');
+        }
+        /*
+         * Checked HERE rather than left to the server.
+         *
+         * The handler validates against this same closed list and 400s on an
+         * unknown value, so passing one through would turn a typo into an HTTP
+         * error a user has to decode. We already hold the list — telling them
+         * what the four are costs nothing and is the difference between a CLI
+         * and a thin curl wrapper.
+         *
+         * It also narrows the type: `billing.usage` takes `UsageEventType`, and
+         * returning a bare `string` is how this went out as `unknown` in four
+         * SDKs at once.
+         */
+        if (!USAGE_EVENT_TYPES.includes(value)) {
+            throw new Error(`\`${value}\` is not a meter.\n` + `One of: ${USAGE_EVENT_TYPES.join(', ')}.`);
+        }
+        return value;
+    };
+    switch (sub) {
+        case 'summary':
+            // `GET /v1/billing` — plan, seats, trial and cap state in one object.
+            return showObject(await chatly.request('GET', '/v1/billing'));
+        case 'plans':
+            return showRows(args, await chatly.billing.plans(), [
+                'id',
+                'name',
+                'priceCents',
+                'interval',
+                'seats',
+            ]);
+        case 'usage':
+            return showObject(await chatly.billing.usage(meter('usage'), range()));
+        case 'usage-daily':
+            /*
+             * DENSE: one entry per UTC day in `[from, to)`, zeros included — unlike
+             * `reports conversations-by-day`, which omits empty days. The two look
+             * alike and are not interchangeable.
+             */
+            return showObject(await chatly.request('GET', '/v1/billing/usage/daily', {
+                query: { eventType: meter('usage-daily'), ...range() },
+            }));
+        case 'usage-monthly':
+            // One entry per known usage event type, ALWAYS all four, plus a `total`
+            // that is already summed. `--month` is a UTC-midnight ISO date.
+            return showObject(await chatly.request('GET', '/v1/billing/usage/monthly', {
+                query: queryFrom(args, [['month', 'month']]),
+            }));
+        case 'invoices': {
+            /*
+             * Cursor-paginated on the wire — `{ data, nextCursor }` — but its
+             * envelope key is `data`, not `items`, so the shared manifest does not
+             * flag it `paged` and no SDK offers a walker over it. `--all` is
+             * therefore not offered here; follow `--cursor` by hand.
+             */
+            if (bool(args.flags, 'all')) {
+                process.stderr.write('--all is not available for invoices: the route pages under a `data` key rather ' +
+                    'than the `items` envelope every other list uses, so there is no SDK walker ' +
+                    'for it. Follow the printed cursor with --cursor.\n');
+                return 1;
+            }
+            const page = await chatly.request('GET', '/v1/billing/invoices', {
+                query: queryFrom(args, [
+                    ['cursor', 'cursor'],
+                    ['limit', 'limit', true],
+                ]),
+            });
+            if (bool(args.flags, 'json')) {
+                printJson(page);
+                return 0;
+            }
+            showRows(args, page, [
+                'id',
+                'status',
+                'amountCents',
+                'currency',
+                'periodStart',
+                'hostedInvoiceUrl',
+            ]);
+            const next = page.nextCursor;
+            if (typeof next === 'string' && next.length > 0) {
+                process.stdout.write(`next page: --cursor ${next}\n`);
+            }
+            return 0;
+        }
+        default:
+            throw new Error(`Unknown: billing ${sub}`);
+    }
+}
+//# sourceMappingURL=insights.js.map