@vorlek/cli 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# vorlek-cli
+Vorlek CLI — thin REST API wrapper
+
+## Install
+
+```sh
+npm install -g @vorlek/cli
+vorlek --version
+```
+
+This package installs the `vorlek` command. The source repository can remain
+private; first-time users should not need repository access to install or smoke
+the CLI.
+
+## Commands
+
+```sh
+vorlek auth signup
+vorlek auth use --api-key vk_live_...
+vorlek connect sendgrid --api-key SG....
+vorlek catalog
+vorlek contact upsert --provider sendgrid --email person@example.com --detail full
+vorlek contact get --provider sendgrid --email person@example.com
+vorlek operation get 01HV0000000000000000000000
+vorlek template list --provider sendgrid
+vorlek campaign list --provider mailchimp
+vorlek email send --provider sendgrid --to person@example.com --subject "Hello" --text "Hi"
+vorlek status --check
+```
+
+Tool commands accept `--detail minimal|standard|full` where the API supports
+response verbosity. Use `operation get` with the `meta.request_id` returned by
+API responses to inspect a stored operation receipt.

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { cac } from 'cac';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerCampaignCommands } from './commands/campaign.js';
+import { registerCatalogCommands } from './commands/catalog.js';
+import { registerConnectCommands } from './commands/connect.js';
+import { registerConnectionCommands } from './commands/connection.js';
+import { registerContactCommands } from './commands/contact.js';
+import { registerEmailCommands } from './commands/email.js';
+import { registerOperationCommands } from './commands/operation.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerTemplateCommands } from './commands/template.js';
+import { defaultDeps } from './deps.js';
+/**
+ * `vorlek` CLI entry. Sub-command surface per spec § 11:
+ *   vorlek auth signup | use | whoami | logout | rotate
+ *   vorlek connect <provider> | list | remove
+ *   vorlek contact upsert
+ *   vorlek status
+ *
+ * Global flags (--api-base, --json, -v/--verbose) are parsed here and
+ * threaded through `RunContext` so every command renders consistently.
+ */
+const cli = cac('vorlek');
+cli.help();
+cli.version('0.1.0');
+cli.option('--api-base <url>', 'Override API base URL (default: from config or https://api.vorlek.com)');
+cli.option('--json', 'Output raw JSON (machine-readable)');
+cli.option('-v, --verbose', 'Verbose logging (includes stack traces on errors)');
+const deps = defaultDeps();
+// Build the RunContext from cac's parsed options. cac populates these
+// in `cli.options` AFTER parse(), but our command actions run after parse
+// as well, so a closure that reads at call-time is fine.
+const ctx = {
+    json: false,
+    verbose: false,
+};
+// Patch ctx in-place once we parse — cac's flow:
+// 1. cli.command(...).action((args, opts) => {})  — action receives merged opts
+// 2. cli.parse() returns the parsed result with the SAME options
+// We mutate `ctx` from a top-level parse hook so command actions see the
+// flags before they fire.
+function bindCtxFromParsed(parsed) {
+    // biome-ignore lint/suspicious/noExplicitAny: cac's options bag is loosely typed
+    const opts = (parsed?.options ?? {});
+    ctx.json = Boolean(opts.json);
+    ctx.verbose = Boolean(opts.verbose ?? opts.v);
+    if (typeof opts['api-base'] === 'string')
+        ctx.apiBaseOverride = opts['api-base'];
+    else if (typeof opts.apiBase === 'string')
+        ctx.apiBaseOverride = opts.apiBase;
+}
+registerAuthCommands(cli, deps, ctx);
+registerConnectionCommands(cli, deps, ctx);
+registerConnectCommands(cli, deps, ctx);
+registerContactCommands(cli, deps, ctx);
+registerEmailCommands(cli, deps, ctx);
+registerCampaignCommands(cli, deps, ctx);
+registerTemplateCommands(cli, deps, ctx);
+registerCatalogCommands(cli, deps, ctx);
+registerOperationCommands(cli, deps, ctx);
+registerStatusCommand(cli, deps, ctx);
+cli.command('').action(() => {
+    cli.outputHelp();
+});
+const parsed = cli.parse(process.argv, { run: false });
+bindCtxFromParsed(parsed);
+try {
+    await cli.runMatchedCommand();
+}
+catch (err) {
+    // Last-resort handler for anything a command's try/catch missed.
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/client.js

@@ -0,0 +1,148 @@
+import ky from 'ky';
+import { newIdempotencyKey } from './idempotency.js';
+/**
+ * Phase 1.5.3 — typed API wrapper around `ky`. Every method either returns
+ * `data` from a SuccessEnvelope or throws `ApiError` carrying the server's
+ * error envelope (code/message/category/request_id). Callers decide how
+ * to render — the CLI's command handlers (1.5.4+) translate ApiError to
+ * exit codes per spec § 11.
+ */
+export const DEFAULT_API_BASE = 'https://api.vorlek.com';
+export class ApiError extends Error {
+    status;
+    envelope;
+    constructor(status, envelope) {
+        super(`${envelope.error.code}: ${envelope.error.message}`);
+        this.name = 'ApiError';
+        this.status = status;
+        this.envelope = envelope;
+    }
+    get code() {
+        return this.envelope.error.code;
+    }
+    get requestId() {
+        return this.envelope.meta.request_id;
+    }
+}
+export function createApiClient(opts) {
+    const headers = {};
+    if (opts.apiKey)
+        headers.Authorization = `Bearer ${opts.apiKey}`;
+    const http = ky.create({
+        prefixUrl: opts.apiBase,
+        timeout: opts.timeoutMs ?? 15_000,
+        retry: { limit: 2, methods: ['get'] },
+        headers,
+        throwHttpErrors: false, // we'll inspect status + envelope ourselves
+        hooks: {
+            beforeError: [
+            // Defensive — if throwHttpErrors flips on, ky pre-consumes body so
+            // err.response.text() can't be re-read. We're not relying on this
+            // path, but keep ky from doing surprising things on retry-failure.
+            ],
+        },
+    });
+    async function call(path, init) {
+        const res = await http(path, init);
+        const text = await res.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Server returned non-JSON (status ${res.status}): ${text.slice(0, 200)}`);
+        }
+        // The API uses two response shapes today (caught by 1.5 smoke):
+        //   - Enveloped: { status: 'success' | 'error', data?, error?, meta }
+        //   - Flat:      { ...fields } directly (signup, account, connections list/delete)
+        // Detect by `.status` and `.error` presence rather than route, so a future
+        // server refactor that envelopes everything Just Works.
+        if (typeof body === 'object' && body !== null) {
+            const obj = body;
+            if (obj.status === 'error') {
+                throw new ApiError(res.status, body);
+            }
+            if (obj.status === 'success' && 'data' in obj) {
+                return body.data;
+            }
+            // Non-2xx without an error envelope = something unusual; surface it.
+            if (res.status < 200 || res.status >= 300) {
+                throw new Error(`Server returned status ${res.status} without an error envelope: ${text.slice(0, 200)}`);
+            }
+            // Flat success — body itself is the response.
+            return body;
+        }
+        throw new Error(`Server returned a non-object response: ${text.slice(0, 200)}`);
+    }
+    function toolPostInit(input) {
+        const { idempotencyKey, detail, ...json } = input;
+        return {
+            method: 'POST',
+            json,
+            headers: { 'Idempotency-Key': idempotencyKey ?? newIdempotencyKey() },
+            ...(detail ? { searchParams: { detail } } : {}),
+        };
+    }
+    return {
+        signup(input) {
+            return call('v1/accounts/signup', { method: 'POST', json: input });
+        },
+        rotateKey() {
+            return call('v1/account/api-keys/rotate', { method: 'POST' });
+        },
+        getAccount() {
+            return call('v1/account', { method: 'GET' });
+        },
+        createConnection(input) {
+            return call('v1/connections', { method: 'POST', json: input });
+        },
+        listConnections() {
+            return call('v1/connections', { method: 'GET' });
+        },
+        removeConnection(provider) {
+            return call(`v1/connections/${provider}`, {
+                method: 'DELETE',
+            });
+        },
+        getCatalog() {
+            return call('v1/catalog', { method: 'GET' });
+        },
+        getOperation(requestId) {
+            return call(`v1/operations/${encodeURIComponent(requestId)}`, {
+                method: 'GET',
+            });
+        },
+        upsertContact(input) {
+            return call('v1/tools/upsert_contact', toolPostInit(input));
+        },
+        getContact(input) {
+            return call('v1/tools/get_contact', toolPostInit(input));
+        },
+        getConnectionStatus(input) {
+            return call('v1/tools/get_connection_status', toolPostInit(input));
+        },
+        sendTransactional(input) {
+            return call('v1/tools/send_transactional', toolPostInit(input));
+        },
+        getCampaignStats(input) {
+            return call('v1/tools/get_campaign_stats', toolPostInit(input));
+        },
+        template: {
+            list(input) {
+                return call('v1/tools/list_templates', toolPostInit(input));
+            },
+        },
+        campaign: {
+            list(input) {
+                return call('v1/tools/list_campaigns', toolPostInit(input));
+            },
+        },
+        cleanupTestProfiles(input) {
+            return call(`v1/connections/${input.provider}/cleanup-test-profiles`, { method: 'POST', json: { pattern: input.pattern } });
+        },
+        getUsage() {
+            return call('v1/account/usage', { method: 'GET' });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/commands/auth.js

@@ -0,0 +1,157 @@
+import pc from 'picocolors';
+import { DEFAULT_API_BASE } from '../client.js';
+import { ConfigMissingError, renderError, renderSuccess } from '../run-context.js';
+export async function runSignup(deps, ctx) {
+    try {
+        const apiBase = ctx.apiBaseOverride ?? DEFAULT_API_BASE;
+        if (!ctx.json) {
+            deps.stdout.write(`${pc.bold('Vorlek signup')} — ${pc.dim(apiBase)}\n`);
+        }
+        const email = (await deps.prompts.text({
+            message: 'Email',
+            placeholder: 'you@example.com',
+            validate: (v) => (/^.+@.+\..+$/.test(v) ? undefined : 'Enter a valid email.'),
+        }));
+        if (deps.prompts.isCancel(email))
+            deps.exit(1);
+        const password = (await deps.prompts.password({
+            message: 'Password (min 8 chars)',
+            validate: (v) => (v && v.length >= 8 ? undefined : 'Password must be at least 8 chars.'),
+        }));
+        if (deps.prompts.isCancel(password))
+            deps.exit(1);
+        const confirm = (await deps.prompts.password({
+            message: 'Confirm password',
+            validate: (v) => (v === password ? undefined : 'Passwords do not match.'),
+        }));
+        if (deps.prompts.isCancel(confirm))
+            deps.exit(1);
+        const client = deps.createApiClient({ apiBase });
+        const data = await client.signup({ email: email, password: password });
+        await deps.saveConfig({
+            api_base: apiBase,
+            api_key: data.live_api_key,
+            account_id: data.account_id,
+            email: data.email,
+            created_at: data.created_at,
+        });
+        renderSuccess(deps, ctx, {
+            account_id: data.account_id,
+            email: data.email,
+            test_api_key: data.test_api_key,
+        }, () => [
+            `${pc.green('✓')} Signed up as ${pc.bold(data.email)}.`,
+            `Live key saved to ${pc.cyan('~/.vorlek/config.json')}.`,
+            '',
+            `${pc.yellow('!')} Save your ${pc.bold('test API key')} now — it is shown ONCE:`,
+            `  ${pc.bold(data.test_api_key)}`,
+        ].join('\n'));
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export async function runUse(deps, ctx, opts) {
+    try {
+        if (!opts.apiKey) {
+            throw new Error('Missing --api-key flag.');
+        }
+        if (!/^vk_(live|test)_/.test(opts.apiKey)) {
+            throw new Error('API key must start with vk_live_ or vk_test_.');
+        }
+        const apiBase = ctx.apiBaseOverride ?? DEFAULT_API_BASE;
+        const client = deps.createApiClient({ apiBase, apiKey: opts.apiKey });
+        const account = await client.getAccount();
+        await deps.saveConfig({
+            api_base: apiBase,
+            api_key: opts.apiKey,
+            account_id: account.account_id,
+            email: account.email,
+            created_at: account.created_at,
+        });
+        renderSuccess(deps, ctx, { account_id: account.account_id, email: account.email }, () => `${pc.green('✓')} Active API key set for ${pc.bold(account.email)} (${pc.dim(account.account_id)}).`);
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export async function runWhoami(deps, ctx) {
+    try {
+        const cfg = await deps.loadConfig();
+        if (!cfg)
+            throw new ConfigMissingError();
+        const apiBase = ctx.apiBaseOverride ?? cfg.api_base;
+        const client = deps.createApiClient({ apiBase, apiKey: cfg.api_key });
+        const [identity, usage] = await Promise.all([client.getAccount(), client.getUsage()]);
+        renderSuccess(deps, ctx, {
+            account_id: identity.account_id,
+            email: identity.email,
+            plan: identity.plan,
+            quota: usage.quota,
+            recent_operations: usage.recent_operations,
+        }, () => [
+            `${pc.bold('account')}  ${identity.email} ${pc.dim(`(${identity.account_id})`)}`,
+            `${pc.bold('plan')}     ${identity.plan}`,
+            `${pc.bold('usage')}    ${usage.quota.used} / ${usage.quota.limit} this period (resets ${pc.dim(usage.quota.resets_at)})`,
+            `${pc.bold('errors')}   ${usage.recent_operations.errors} of ${usage.recent_operations.total}`,
+        ].join('\n'));
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export async function runLogout(deps, ctx) {
+    try {
+        const removed = await deps.deleteConfig();
+        renderSuccess(deps, ctx, { removed }, () => removed
+            ? `${pc.green('✓')} Local config deleted. ${pc.yellow('Note:')} the API key is still active on the server — use ${pc.bold('vorlek auth rotate')} to invalidate it.`
+            : `${pc.dim('No config to remove.')}`);
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export async function runRotate(deps, ctx) {
+    try {
+        const cfg = await deps.loadConfig();
+        if (!cfg)
+            throw new ConfigMissingError();
+        const apiBase = ctx.apiBaseOverride ?? cfg.api_base;
+        const client = deps.createApiClient({ apiBase, apiKey: cfg.api_key });
+        const data = await client.rotateKey();
+        await deps.saveConfig({ ...cfg, api_key: data.live_api_key });
+        renderSuccess(deps, ctx, { rotated_at: data.rotated_at, test_api_key: data.test_api_key }, () => [
+            `${pc.green('✓')} Keys rotated at ${pc.dim(data.rotated_at)}.`,
+            `New live key saved to ${pc.cyan('~/.vorlek/config.json')}.`,
+            '',
+            `${pc.yellow('!')} New ${pc.bold('test API key')} — shown ONCE:`,
+            `  ${pc.bold(data.test_api_key)}`,
+        ].join('\n'));
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export function registerAuthCommands(cli, deps, ctx) {
+    cli
+        .command('auth <action>', 'Auth: signup | use | whoami | logout | rotate')
+        .option('--api-key <key>', 'API key (vk_live_... or vk_test_...) — required by `use`')
+        .action(async (action, opts) => {
+        switch (action) {
+            case 'signup':
+                return runSignup(deps, ctx);
+            case 'use':
+                return runUse(deps, ctx, opts);
+            case 'whoami':
+                return runWhoami(deps, ctx);
+            case 'logout':
+                return runLogout(deps, ctx);
+            case 'rotate':
+                return runRotate(deps, ctx);
+            default:
+                deps.stderr.write(`${pc.red('error')} Unknown auth action: ${action}. Try: signup | use | whoami | logout | rotate\n`);
+                deps.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/campaign.js

@@ -0,0 +1,108 @@
+import pc from 'picocolors';
+import { ConfigMissingError, renderError, renderSuccess } from '../run-context.js';
+import { parseDetail } from './detail.js';
+import { resolveProvider } from './provider.js';
+import { renderTable } from './table.js';
+const ALL_PAGE_CAP = 100;
+export async function runCampaignStats(deps, ctx, opts) {
+    try {
+        if (!opts.campaignId)
+            throw new Error('Missing --campaign-id flag.');
+        const cfg = await deps.loadConfig();
+        if (!cfg)
+            throw new ConfigMissingError();
+        const apiBase = ctx.apiBaseOverride ?? cfg.api_base;
+        const client = deps.createApiClient({ apiBase, apiKey: cfg.api_key });
+        if (!client.getCampaignStats)
+            throw new Error('Configured API client does not support get_campaign_stats.');
+        const provider = await resolveProvider(client, opts.provider);
+        const detail = parseDetail(opts.detail);
+        const result = await client.getCampaignStats({
+            provider,
+            campaign_id: opts.campaignId,
+            ...(detail ? { detail } : {}),
+            ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+        });
+        renderSuccess(deps, ctx, result, () => `${pc.green('✓')} ${pc.bold(result.provider)} campaign ${pc.bold(result.campaign_id)}: ${result.sent} sent, ${result.opens} opens, ${result.clicks} clicks.`);
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export async function runCampaignList(deps, ctx, opts) {
+    try {
+        const cfg = await deps.loadConfig();
+        if (!cfg)
+            throw new ConfigMissingError();
+        const apiBase = ctx.apiBaseOverride ?? cfg.api_base;
+        const client = deps.createApiClient({ apiBase, apiKey: cfg.api_key });
+        if (!client.campaign?.list)
+            throw new Error('Configured API client does not support list_campaigns.');
+        const provider = await resolveProvider(client, opts.provider);
+        const status = opts.status ?? 'all';
+        const limit = parseLimit(opts.limit);
+        const detail = parseDetail(opts.detail);
+        const campaigns = [];
+        let cursor = opts.cursor ?? null;
+        let nextCursor = null;
+        for (let page = 0;; page++) {
+            if (page >= ALL_PAGE_CAP) {
+                throw new Error('--all reached the 100-page safety cap. Use --cursor to continue from the last seen page.');
+            }
+            const result = await client.campaign.list({
+                provider,
+                status,
+                ...(limit ? { limit } : {}),
+                ...(cursor ? { cursor } : {}),
+                ...(detail ? { detail } : {}),
+                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+            });
+            campaigns.push(...result.campaigns);
+            nextCursor = result.next_cursor;
+            if (!opts.all || !nextCursor)
+                break;
+            cursor = nextCursor;
+        }
+        renderSuccess(deps, ctx, { provider, campaigns, next_cursor: nextCursor }, () => renderCampaigns(provider, campaigns, nextCursor));
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export function registerCampaignCommands(cli, deps, ctx) {
+    cli
+        .command('campaign <action>', 'Campaign operations: stats, list')
+        .option('--campaign-id <id>', 'Provider campaign id')
+        .option('--provider <name>', 'Provider override (defaults to auto-detect)')
+        .option('--status <status>', 'Campaign status: draft, scheduled, sent, all')
+        .option('--limit <n>', 'Page size, 1-100')
+        .option('--cursor <cursor>', 'Pagination cursor returned by the previous page')
+        .option('--all', 'Follow next_cursor until exhausted (max 100 pages)')
+        .option('--detail <level>', 'Response detail: minimal, standard, full')
+        .option('--idempotency-key <key>', 'Override the auto-generated idempotency key')
+        .action(async (action, opts) => {
+        if (action === 'stats')
+            return runCampaignStats(deps, ctx, opts);
+        if (action === 'list')
+            return runCampaignList(deps, ctx, opts);
+        deps.stderr.write(`${pc.red('error')} Unknown campaign action: ${action}. Try: stats, list\n`);
+        deps.exit(1);
+    });
+}
+function parseLimit(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = typeof raw === 'number' ? raw : Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+        throw new Error('--limit must be an integer between 1 and 100.');
+    }
+    return parsed;
+}
+function renderCampaigns(provider, campaigns, nextCursor) {
+    if (campaigns.length === 0)
+        return pc.dim(`No campaigns found for ${provider}.`);
+    const table = renderTable(['id', 'name', 'status', 'updated_at'], campaigns.map((campaign) => [campaign.id, campaign.name, campaign.status, campaign.updated_at]));
+    const cursorHint = nextCursor ? `\n${pc.dim(`next_cursor: ${nextCursor}`)}` : '';
+    return `${pc.green('✓')} ${pc.bold(provider)} campaigns\n${table}${cursorHint}`;
+}
+//# sourceMappingURL=campaign.js.map

package/dist/commands/catalog.js

@@ -0,0 +1,53 @@
+import pc from 'picocolors';
+import { ConfigMissingError, renderError, renderSuccess } from '../run-context.js';
+import { renderTable } from './table.js';
+export async function runCatalogGet(deps, ctx) {
+    try {
+        const cfg = await deps.loadConfig();
+        if (!cfg)
+            throw new ConfigMissingError();
+        const apiBase = ctx.apiBaseOverride ?? cfg.api_base;
+        const client = deps.createApiClient({ apiBase, apiKey: cfg.api_key });
+        if (!client.getCatalog)
+            throw new Error('Configured API client does not support catalog.');
+        const result = await client.getCatalog();
+        renderSuccess(deps, ctx, result, () => renderCatalog(result));
+    }
+    catch (err) {
+        deps.exit(renderError(deps, ctx, err));
+    }
+}
+export function registerCatalogCommands(cli, deps, ctx) {
+    cli
+        .command('catalog [action]', 'Show account-aware provider and tool catalog')
+        .action(async (action) => {
+        if (action === undefined || action === 'get')
+            return runCatalogGet(deps, ctx);
+        deps.stderr.write(`${pc.red('error')} Unknown catalog action: ${action}. Try: get\n`);
+        deps.exit(1);
+    });
+}
+function renderCatalog(catalog) {
+    const providerTable = renderTable(['provider', 'status', 'tools'], catalog.providers.map((provider) => [
+        provider.provider,
+        provider.connection.status,
+        provider.supported_tools.join(', '),
+    ]));
+    const toolTable = renderTable(['tool', 'supported providers'], catalog.tools.map((tool) => [
+        tool.name,
+        tool.providers
+            .filter((provider) => provider.supported)
+            .map((provider) => provider.provider)
+            .join(', '),
+    ]));
+    return [
+        `${pc.green('✓')} Catalog ${pc.dim(`(${catalog.mode}, generated ${catalog.generated_at})`)}`,
+        '',
+        pc.bold('providers'),
+        providerTable,
+        '',
+        pc.bold('tools'),
+        toolTable,
+    ].join('\n');
+}
+//# sourceMappingURL=catalog.js.map