@commissionsight/cli 0.1.0

package/dist/commands/upload.js

@@ -0,0 +1,111 @@
+/**
+ * Upload (plan §6.3, the centerpiece): `cs upload <file>` → uploadFile, with
+ * optional job wait + scored-results dump. The bulk `cs upload batch` lives in
+ * batch.ts (Phase 5). Workspace is required when the account has multi-workspace
+ * enabled and no default is set.
+ */
+import { writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { cover } from './registry.js';
+import { loadFile, sha8 } from '../lib/file.js';
+import { resolveCarrierEntry, resolveWorkspace } from '../lib/resolve.js';
+import { periodFromOptions, formatPeriod } from '../lib/period.js';
+import { waitForJob } from '../lib/poll.js';
+import { emitCSV, RESULT_ROW_COLUMNS } from '../output/csv.js';
+import { loadConfig } from '../config/store.js';
+import { UsageError, CliError, EXIT } from '../errors.js';
+import { optStr, optBool, optNum } from '../util.js';
+export const UPLOAD_OPTIONS = {
+    carrier: { type: 'string', desc: 'Carrier id|slug|name (required)', placeholder: '<c>' },
+    period: { type: 'string', desc: 'Statement period YYYY-MM', placeholder: '<YYYY-MM>' },
+    year: { type: 'string', desc: 'Period year (with --month)', placeholder: '<n>' },
+    month: { type: 'string', desc: 'Period month (with --year)', placeholder: '<n>' },
+    workspace: { type: 'string', desc: 'Target workspace id|name', placeholder: '<w>' },
+    replace: { type: 'boolean', desc: 'Replace an existing carrier+period atomically' },
+    webhook: { type: 'string', desc: 'Webhook URL for job events', placeholder: '<url>' },
+    'idempotency-key': { type: 'string', desc: 'Override the derived idempotency key', placeholder: '<k>' },
+    wait: { type: 'boolean', desc: 'Poll the job to a terminal state' },
+    timeout: { type: 'string', desc: 'Wait timeout seconds (default 300)', placeholder: '<s>' },
+    interval: { type: 'string', desc: 'Poll interval seconds (default 2)', placeholder: '<s>' },
+    results: { type: 'boolean', desc: 'Dump scored rows on completion (implies --wait)' },
+    status: { type: 'string', desc: 'Filter results by status', choices: ['green', 'yellow', 'red'], placeholder: '<s>' },
+    'owed-only': { type: 'boolean', desc: 'Only rows with commission owed' },
+    chargeback: { type: 'boolean', desc: 'Only chargeback rows' },
+    csv: { type: 'boolean', desc: 'Emit results as CSV (with --results)' },
+    output: { type: 'string', short: 'o', desc: 'Write CSV to a file', placeholder: '<file>' },
+};
+export function uploadCommands() {
+    cover('uploadFile', 'cs upload');
+    cover('getJobResults', 'cs job results / cs upload --results');
+    return [
+        {
+            path: ['upload'],
+            summary: 'Upload a statement for a carrier + period',
+            args: [{ name: 'file', required: true }],
+            options: { ...UPLOAD_OPTIONS },
+            run: runUpload,
+        },
+    ];
+}
+async function runUpload(ctx, parsed) {
+    const filePath = parsed.args[0];
+    const o = parsed.options;
+    const carrierRef = optStr(o['carrier']);
+    if (!carrierRef)
+        throw new UsageError('--carrier <id|slug|name> is required');
+    const file = loadFile(filePath);
+    const carrier = await resolveCarrierEntry(ctx, carrierRef);
+    const period = periodFromOptions({
+        period: optStr(o['period']),
+        year: optNum(o['year']),
+        month: optNum(o['month']),
+    });
+    const workspaceId = await resolveWorkspace(ctx, optStr(o['workspace']));
+    const contextName = ctx.globals.context || loadConfig(ctx.io).current;
+    const periodStr = formatPeriod(period.periodYear, period.periodMonth);
+    const idempotencyKey = optStr(o['idempotency-key']) ??
+        `${contextName}-${carrier.slug}-${periodStr}-${sha8(filePath)}`;
+    const replace = optBool(o['replace']);
+    const webhookUrl = optStr(o['webhook']);
+    const res = await ctx.client().uploadFile({
+        file,
+        carrierId: carrier.id,
+        periodYear: period.periodYear,
+        periodMonth: period.periodMonth,
+        idempotencyKey,
+        ...(replace ? { replace: true } : {}),
+        ...(webhookUrl ? { webhookUrl } : {}),
+        ...(workspaceId ? { workspaceId } : {}),
+    });
+    ctx.log(`uploaded ${basename(filePath)} → job ${res.jobId} (${res.mode ?? res.status})`);
+    const wantResults = optBool(o['results']);
+    const wantWait = optBool(o['wait']) || wantResults;
+    let job;
+    if (wantWait) {
+        const timeoutMs = (optNum(o['timeout']) ?? 300) * 1000;
+        const intervalMs = (optNum(o['interval']) ?? 2) * 1000;
+        job = await waitForJob(ctx.client(), res.jobId, {
+            timeoutMs,
+            intervalMs,
+            onTick: (j) => ctx.log(`  job ${res.jobId}: ${j.status}`),
+        });
+        if (job.status === 'failed') {
+            const hint = job.exceptionRowCount
+                ? ` — ${job.exceptionRowCount} rejected row(s); see 'cs job exceptions ${res.jobId}'`
+                : '';
+            throw new CliError(`job failed: ${job.error ?? 'unknown error'}${hint}`, EXIT.ERROR);
+        }
+    }
+    if (wantResults) {
+        const results = await ctx.client().getJobResults(res.jobId, {
+            ...(optStr(o['status']) ? { status: optStr(o['status']) } : {}),
+            ...(optBool(o['owed-only']) ? { owedOnly: true } : {}),
+            ...(optBool(o['chargeback']) ? { chargeback: true } : {}),
+        });
+        if (optBool(o['csv']) && !ctx.globals.json) {
+            return emitCSV(ctx.io, results.data, RESULT_ROW_COLUMNS, optStr(o['output']), (p, d) => writeFileSync(p, d));
+        }
+        return { upload: res, period: results.period, count: results.data.length, results: results.data };
+    }
+    return { upload: res, ...(job ? { job } : {}) };
+}

package/dist/commands/webhook.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Webhook commands (plan §6.10). The signing secret is shown ONCE on create.
+ */
+import type { Cmd } from '../types.js';
+export declare function webhookCommands(): Cmd[];

package/dist/commands/webhook.js

@@ -0,0 +1,56 @@
+import { cover } from './registry.js';
+import { confirmDestructive } from '../lib/confirm.js';
+import { UsageError } from '../errors.js';
+import { optStr, optList } from '../util.js';
+const VALID_EVENTS = ['job.completed', 'job.failed'];
+export function webhookCommands() {
+    cover('listWebhooks', 'cs webhook list');
+    cover('createWebhook', 'cs webhook create');
+    cover('deleteWebhook', 'cs webhook delete');
+    return [
+        {
+            path: ['webhook', 'list'],
+            summary: 'List webhooks',
+            async run(ctx) {
+                return (await ctx.client().listWebhooks()).data;
+            },
+        },
+        {
+            path: ['webhook', 'create'],
+            summary: 'Create a webhook (prints the signing secret once)',
+            options: {
+                url: { type: 'string', desc: 'Delivery URL (required)', placeholder: '<url>' },
+                events: { type: 'string', desc: 'Comma list: job.completed,job.failed', placeholder: '<list>' },
+            },
+            async run(ctx, parsed) {
+                const url = optStr(parsed.options['url']);
+                if (!url)
+                    throw new UsageError('--url is required');
+                const events = optList(parsed.options['events']);
+                if (events.length === 0)
+                    throw new UsageError(`--events is required (${VALID_EVENTS.join(',')})`);
+                for (const e of events) {
+                    if (!VALID_EVENTS.includes(e)) {
+                        throw new UsageError(`invalid event: ${e} (allowed: ${VALID_EVENTS.join(', ')})`);
+                    }
+                }
+                const res = await ctx.client().createWebhook({
+                    url,
+                    events: events,
+                });
+                ctx.log('the signing secret is shown once below and will not be retrievable again');
+                return res;
+            },
+        },
+        {
+            path: ['webhook', 'delete'],
+            summary: 'Delete a webhook (destructive)',
+            args: [{ name: 'id', required: true }],
+            async run(ctx, parsed) {
+                await confirmDestructive(ctx, `delete webhook ${parsed.args[0]}`);
+                await ctx.client().deleteWebhook(parsed.args[0]);
+                return { deleted: parsed.args[0] };
+            },
+        },
+    ];
+}

package/dist/commands/workspace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Workspace commands (plan §6.1). `create` is gated behind a capability check
+ * (§0.1): SDK 2.2.0 has no createWorkspace, so it fails with the exact,
+ * actionable message until a newer SDK ships the method — at which point it
+ * lights up with no CLI change.
+ */
+import type { Cmd } from '../types.js';
+export declare function workspaceCommands(): Cmd[];

package/dist/commands/workspace.js

@@ -0,0 +1,65 @@
+import { cover } from './registry.js';
+import { getWorkspaces } from '../lib/resolve.js';
+import { upsertContext, loadConfig } from '../config/store.js';
+import { CliError, UsageError, EXIT } from '../errors.js';
+/** Exact capability-gap message from plan §0.1. */
+const CREATE_UNAVAILABLE = 'workspace create is unavailable: SDK method createWorkspace not found — upgrade @commissionsight/sdk or confirm POST /workspaces (see docs.commissionsight.com)';
+export function workspaceCommands() {
+    cover('listWorkspaces', 'cs workspace list');
+    cover('createWorkspace', 'cs workspace create');
+    return [
+        {
+            path: ['workspace', 'list'],
+            summary: 'List workspaces for the account',
+            async run(ctx) {
+                const ws = await ctx.client().listWorkspaces();
+                return { enabled: ws.enabled, workspaces: ws.workspaces };
+            },
+            render(data, ctx) {
+                const d = data;
+                ctx.io.stdout(`multi-workspace: ${d.enabled ? 'enabled' : 'disabled'}\n`);
+                for (const w of d.workspaces) {
+                    ctx.io.stdout(`  ${w.isDefault ? '*' : ' '} ${w.id}  ${w.name}\n`);
+                }
+            },
+        },
+        {
+            path: ['workspace', 'create'],
+            summary: 'Create a workspace (requires SDK createWorkspace; see §0.1)',
+            args: [{ name: 'name', required: true }],
+            async run(ctx, parsed) {
+                const name = parsed.args[0];
+                const client = ctx.client();
+                if (typeof client.createWorkspace !== 'function') {
+                    throw new CliError(CREATE_UNAVAILABLE, EXIT.ERROR);
+                }
+                return client.createWorkspace(name);
+            },
+        },
+        {
+            path: ['workspace', 'use'],
+            summary: 'Set the default workspace for the active context',
+            args: [{ name: 'nameOrId', required: true }],
+            async run(ctx, parsed) {
+                const ref = parsed.args[0];
+                const ws = await getWorkspaces(ctx);
+                const lower = ref.toLowerCase();
+                const match = ws.workspaces.find((w) => w.id === ref) ??
+                    ws.workspaces.find((w) => w.name.toLowerCase() === lower);
+                if (!match) {
+                    throw new UsageError(`unknown workspace: ${ref}`, ws.workspaces.map((w) => `${w.name} → ${w.id}`));
+                }
+                const contextName = ctx.globals.context || loadConfig(ctx.io).current;
+                upsertContext(ctx.io, contextName, {
+                    defaultWorkspaceId: match.id,
+                    defaultWorkspaceName: match.name,
+                });
+                return {
+                    context: contextName,
+                    defaultWorkspaceId: match.id,
+                    defaultWorkspaceName: match.name,
+                };
+            },
+        },
+    ];
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Config file schema (plan §4.2) + validation. One file holds many named
+ * contexts (environments); `current` selects the active one.
+ */
+export interface Context {
+    baseUrl: string;
+    /** Omitted when the user relies on env/flags for the token. */
+    token?: string;
+    defaultWorkspaceId?: string;
+    defaultWorkspaceName?: string;
+    defaultCarrierId?: string;
+}
+export interface Config {
+    version: 1;
+    current: string;
+    contexts: Record<string, Context>;
+}
+export declare const DEFAULT_CONTEXT_NAME = "default";
+export declare function emptyConfig(): Config;
+/** Coerce unknown parsed JSON into a valid Config, dropping junk. */
+export declare function validateConfig(raw: unknown): Config;

package/dist/config/schema.js

@@ -0,0 +1,33 @@
+export const DEFAULT_CONTEXT_NAME = 'default';
+export function emptyConfig() {
+    return { version: 1, current: DEFAULT_CONTEXT_NAME, contexts: {} };
+}
+/** Coerce unknown parsed JSON into a valid Config, dropping junk. */
+export function validateConfig(raw) {
+    if (!raw || typeof raw !== 'object')
+        return emptyConfig();
+    const r = raw;
+    const contexts = {};
+    if (r['contexts'] && typeof r['contexts'] === 'object') {
+        for (const [name, v] of Object.entries(r['contexts'])) {
+            if (!v || typeof v !== 'object')
+                continue;
+            const c = v;
+            contexts[name] = {
+                baseUrl: typeof c['baseUrl'] === 'string' ? c['baseUrl'] : '',
+                ...(typeof c['token'] === 'string' ? { token: c['token'] } : {}),
+                ...(typeof c['defaultWorkspaceId'] === 'string'
+                    ? { defaultWorkspaceId: c['defaultWorkspaceId'] }
+                    : {}),
+                ...(typeof c['defaultWorkspaceName'] === 'string'
+                    ? { defaultWorkspaceName: c['defaultWorkspaceName'] }
+                    : {}),
+                ...(typeof c['defaultCarrierId'] === 'string'
+                    ? { defaultCarrierId: c['defaultCarrierId'] }
+                    : {}),
+            };
+        }
+    }
+    const current = typeof r['current'] === 'string' ? r['current'] : DEFAULT_CONTEXT_NAME;
+    return { version: 1, current, contexts };
+}

package/dist/config/store.d.ts

@@ -0,0 +1,17 @@
+import type { IO } from '../io.js';
+import { type Config, type Context } from './schema.js';
+export declare function configFilePath(io: IO): string;
+export declare function loadConfig(io: IO): Config;
+export declare function saveConfig(io: IO, config: Config): void;
+/** The active context name (CLI --context flag wins, else config.current). */
+export declare function activeContextName(io: IO, config: Config, override?: string): string;
+/** Get (name, context) for the active context, or null if it doesn't exist. */
+export declare function activeContext(io: IO, override?: string): {
+    name: string;
+    context: Context | undefined;
+    config: Config;
+};
+/** Mutate + persist a context by name, creating it if absent. */
+export declare function upsertContext(io: IO, name: string, patch: Partial<Context>, opts?: {
+    setCurrent?: boolean;
+}): Config;

package/dist/config/store.js

@@ -0,0 +1,74 @@
+/**
+ * Read/write the config file (plan §4.2). Directory created 0700, file 0600.
+ * On write we re-assert perms and warn (to stderr) if they had been loosened.
+ * All paths flow through the injected IO so tests sandbox to a temp dir.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { emptyConfig, validateConfig, DEFAULT_CONTEXT_NAME } from './schema.js';
+export function configFilePath(io) {
+    if (io.configPath)
+        return io.configPath;
+    const base = io.env['XDG_CONFIG_HOME'] || join(homedir(), '.config');
+    return join(base, 'commissionsight', 'config.json');
+}
+export function loadConfig(io) {
+    const path = configFilePath(io);
+    if (!existsSync(path))
+        return emptyConfig();
+    try {
+        return validateConfig(JSON.parse(readFileSync(path, 'utf8')));
+    }
+    catch {
+        return emptyConfig();
+    }
+}
+const isPosix = platform() !== 'win32';
+export function saveConfig(io, config) {
+    const path = configFilePath(io);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Warn if an existing file had looser-than-0600 perms (POSIX only).
+    if (isPosix && existsSync(path)) {
+        try {
+            const mode = statSync(path).mode & 0o777;
+            if (mode & 0o077) {
+                io.stderr(`warning: ${path} had loose permissions (${mode.toString(8)}); tightening to 600\n`);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    writeFileSync(path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    if (isPosix) {
+        try {
+            chmodSync(dir, 0o700);
+            chmodSync(path, 0o600);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/** The active context name (CLI --context flag wins, else config.current). */
+export function activeContextName(io, config, override) {
+    return override || config.current || DEFAULT_CONTEXT_NAME;
+}
+/** Get (name, context) for the active context, or null if it doesn't exist. */
+export function activeContext(io, override) {
+    const config = loadConfig(io);
+    const name = activeContextName(io, config, override);
+    return { name, context: config.contexts[name], config };
+}
+/** Mutate + persist a context by name, creating it if absent. */
+export function upsertContext(io, name, patch, opts = {}) {
+    const config = loadConfig(io);
+    const existing = config.contexts[name] ?? { baseUrl: '' };
+    config.contexts[name] = { ...existing, ...patch };
+    if (opts.setCurrent)
+        config.current = name;
+    saveConfig(io, config);
+    return config;
+}

package/dist/context.d.ts

@@ -0,0 +1,22 @@
+import { CommissionSightClient } from '@commissionsight/sdk';
+import type { Globals, RunCtx } from './types.js';
+import type { IO } from './io.js';
+export declare const DEFAULT_BASE_URL = "https://api.commissionsight.com/v1";
+/** Resolved configuration slice the client factory needs from the config file. */
+export interface ConfigResolution {
+    baseUrl?: string;
+    token?: string;
+}
+export declare function resolveToken(globals: Globals, io: IO): string | undefined;
+/**
+ * Resolve a token from explicit sources only (flag > file > stdin > env),
+ * ignoring the config file. Used by `auth login` to capture the token being
+ * stored without re-reading stdin via the general resolver.
+ */
+export declare function resolveExplicitToken(globals: Globals, io: IO): string | undefined;
+/** Build a client for an explicit base URL + token (verification flows). */
+export declare function clientFor(baseUrl: string, token: string | undefined, io: IO): CommissionSightClient;
+export declare function resolveBaseUrl(globals: Globals, io: IO): string;
+export declare function makeClient(globals: Globals, io: IO): CommissionSightClient;
+/** Build a RunCtx with a lazily-constructed, memoized client. */
+export declare function makeRunCtx(globals: Globals, io: IO): RunCtx;

package/dist/context.js

@@ -0,0 +1,100 @@
+/**
+ * SDK client factory (plan §8). Resolves base URL + token by precedence and
+ * constructs the SDK client with an injectable fetch (mock in tests).
+ *
+ * Token precedence (highest first, plan §4.1):
+ *   1. --token            2. --token-file / --token-stdin
+ *   3. COMMISSIONSIGHT_TOKEN env   4. active context token (config file)
+ *
+ * The config-file layer is wired in Phase 2 via `resolveFromConfig`; until then
+ * it returns undefined and resolution falls through to env/flags.
+ */
+import { readFileSync } from 'node:fs';
+import { CommissionSightClient } from '@commissionsight/sdk';
+import { UsageError } from './errors.js';
+import { activeContext } from './config/store.js';
+export const DEFAULT_BASE_URL = 'https://api.commissionsight.com/v1';
+/** Read base URL + token from the active config context. */
+function configResolver(globals, io) {
+    const { context } = activeContext(io, globals.context);
+    if (!context)
+        return {};
+    return {
+        ...(context.baseUrl ? { baseUrl: context.baseUrl } : {}),
+        ...(context.token ? { token: context.token } : {}),
+    };
+}
+export function resolveToken(globals, io) {
+    // Explicit sources (flag > file > stdin > env) win; else the config context.
+    return resolveExplicitToken(globals, io) ?? configResolver(globals, io).token;
+}
+/**
+ * Resolve a token from explicit sources only (flag > file > stdin > env),
+ * ignoring the config file. Used by `auth login` to capture the token being
+ * stored without re-reading stdin via the general resolver.
+ */
+export function resolveExplicitToken(globals, io) {
+    if (globals.token)
+        return globals.token;
+    if (globals.tokenFile) {
+        try {
+            return readFileSync(globals.tokenFile, 'utf8').trim();
+        }
+        catch {
+            throw new UsageError(`could not read token file: ${globals.tokenFile}`);
+        }
+    }
+    if (globals.tokenStdin) {
+        try {
+            return readFileSync(0, 'utf8').trim();
+        }
+        catch {
+            throw new UsageError('could not read token from stdin');
+        }
+    }
+    const envTok = io.env['COMMISSIONSIGHT_TOKEN'];
+    return envTok ? envTok.trim() : undefined;
+}
+/** Build a client for an explicit base URL + token (verification flows). */
+export function clientFor(baseUrl, token, io) {
+    return new CommissionSightClient({
+        baseUrl,
+        ...(token ? { token } : {}),
+        ...(io.fetch ? { fetch: io.fetch } : {}),
+    });
+}
+export function resolveBaseUrl(globals, io) {
+    return (globals.baseUrl ??
+        io.env['COMMISSIONSIGHT_BASE_URL'] ??
+        configResolver(globals, io).baseUrl ??
+        DEFAULT_BASE_URL);
+}
+export function makeClient(globals, io) {
+    const baseUrl = resolveBaseUrl(globals, io);
+    const token = resolveToken(globals, io);
+    return new CommissionSightClient({
+        baseUrl,
+        ...(token ? { token } : {}),
+        ...(io.fetch ? { fetch: io.fetch } : {}),
+    });
+}
+/** Build a RunCtx with a lazily-constructed, memoized client. */
+export function makeRunCtx(globals, io) {
+    let client = null;
+    return {
+        globals,
+        io,
+        cache: new Map(),
+        client() {
+            if (!client)
+                client = makeClient(globals, io);
+            return client;
+        },
+        log(msg) {
+            // Logs go to stderr, suppressed by --quiet and by --json (chrome-free).
+            if (globals.quiet || globals.json)
+                return;
+            io.stderr(msg + '\n');
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error types and the ApiError.status → exit-code mapping (plan §5.2).
+ * Commands throw; the router maps to an exit code and the JSON envelope.
+ */
+import { ApiError } from '@commissionsight/sdk';
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly ERROR: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly NOTFOUND: 4;
+    readonly CONFLICT: 5;
+    readonly VALIDATION: 6;
+    readonly RATELIMIT: 7;
+    readonly TIMEOUT: 124;
+};
+/** Bad flags/args/usage — exit 2. */
+export declare class UsageError extends Error {
+    readonly exitCode: 2;
+    /** Optional candidate list (e.g. ambiguous carrier names). */
+    readonly candidates?: string[];
+    constructor(message: string, candidates?: string[]);
+}
+/** A poll/wait exceeded its timeout — exit 124. */
+export declare class TimeoutError extends Error {
+    readonly exitCode: 124;
+    constructor(message: string);
+}
+/** Generic CLI error with an explicit exit code (e.g. capability gaps). */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Map any thrown value to a process exit code. */
+export declare function exitCodeFor(err: unknown): number;
+export declare function exitCodeForStatus(status: number): number;
+export { ApiError };

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * Error types and the ApiError.status → exit-code mapping (plan §5.2).
+ * Commands throw; the router maps to an exit code and the JSON envelope.
+ */
+import { ApiError } from '@commissionsight/sdk';
+export const EXIT = {
+    OK: 0,
+    ERROR: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NOTFOUND: 4,
+    CONFLICT: 5,
+    VALIDATION: 6,
+    RATELIMIT: 7,
+    TIMEOUT: 124,
+};
+/** Bad flags/args/usage — exit 2. */
+export class UsageError extends Error {
+    exitCode = EXIT.USAGE;
+    /** Optional candidate list (e.g. ambiguous carrier names). */
+    candidates;
+    constructor(message, candidates) {
+        super(message);
+        this.name = 'UsageError';
+        this.candidates = candidates;
+    }
+}
+/** A poll/wait exceeded its timeout — exit 124. */
+export class TimeoutError extends Error {
+    exitCode = EXIT.TIMEOUT;
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+/** Generic CLI error with an explicit exit code (e.g. capability gaps). */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.ERROR) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+/** Map any thrown value to a process exit code. */
+export function exitCodeFor(err) {
+    if (err instanceof UsageError)
+        return EXIT.USAGE;
+    if (err instanceof TimeoutError)
+        return EXIT.TIMEOUT;
+    if (err instanceof CliError)
+        return err.exitCode;
+    if (err instanceof ApiError)
+        return exitCodeForStatus(err.status);
+    return EXIT.ERROR;
+}
+export function exitCodeForStatus(status) {
+    if (status === 401 || status === 403)
+        return EXIT.AUTH;
+    if (status === 404)
+        return EXIT.NOTFOUND;
+    if (status === 409)
+        return EXIT.CONFLICT;
+    if (status === 400 || status === 422)
+        return EXIT.VALIDATION;
+    if (status === 429)
+        return EXIT.RATELIMIT;
+    return EXIT.ERROR;
+}
+export { ApiError };

package/dist/globals.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Global flag specs (allowed on any command, parsed before dispatch) and the
+ * resolver that turns parsed values + env into the typed `Globals` object.
+ */
+import type { OptSpec, Globals } from './types.js';
+import type { IO } from './io.js';
+export declare const GLOBAL_OPTIONS: Record<string, OptSpec>;
+/** Keys that are global control flags, not passed down to commands as data. */
+export declare const GLOBAL_KEYS: Set<string>;
+export declare function resolveGlobals(values: Record<string, string | boolean | string[] | undefined>, io: IO): Globals;