@hermeticacomms/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Hermetica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @hermeticacomms/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `hermetica` command: sign in from the terminal, keep workspace setup in a file, send sandbox test mail and call any API operation. Node 20+.
+
+```sh
+npm i -g @hermeticacomms/cli
+```
+
+## Quickstart
+
+```sh
+hermetica login                         # shows a code, opens the browser; approve there
+hermetica whoami                        # the key's workspace and scopes
+hermetica status                        # what blocks sending, and the API call that fixes each step
+hermetica send --sandbox --outcome bounce   # test mail to bounce@sandbox.hermeticor.test, no provider needed
+hermetica plan -f hermetica.json        # what apply would change
+hermetica apply -f hermetica.json       # make the workspace match the file (run it twice: the second run changes nothing)
+```
+
+`login` stores the key in `~/.config/hermetica/credentials` (mode 0600), one entry per `--profile` (default `default`; or set `HERMETICA_PROFILE`). The key is never printed. `login --scopes profiles:read,consent:write` asks for specific scopes; `login --key hm_sk_...` or `login --paste` stores a key you already have. `--url` (or `HERMETICA_API_URL`) points at another instance; the default is `https://hermeticor.com`. `HERMETICA_API_KEY` overrides the stored key, for CI.
+
+Missing a scope? `hermetica scopes request connections:write --reason "connect SES"` prints a link for a workspace owner and waits for the decision.
+
+## Config as code
+
+`plan` / `apply` send the file to `PUT /v1/config`. The file is YAML (`.yaml`/`.yml`) or JSON, same shape (shown as JSON):
+
+```json
+{
+  "topics": [{ "channel": "email", "key": "product-news", "name": "Product news" }],
+  "fields": [{ "key": "plan", "label": "Plan", "type": "text" }],
+  "lists": [{ "name": "Customers", "topicKey": "product-news" }],
+  "webhookEndpoints": [{ "url": "https://example.com/hooks/hermetica", "topics": ["profile.*"], "secret": "<32+ random characters>" }],
+  "postalAddress": "1 Main St, Springfield"
+}
+```
+
+Topics match on `channel` + `key`, fields on `key`, lists on `name`, webhook endpoints on `url`. Only the properties written in the file are compared and changed. Nothing is deleted: `apply --prune` archives the topics, fields and lists (and disables the webhook endpoints) that a section of the file leaves out; sections not in the file are left alone. A webhook `secret` you choose is used on create, replaces the current one when it differs, and is never shown back (the plan prints `secret` only), so verify deliveries with the value from your own secret store. `senders` (`[{ "connection": "main", "fromEmail": "hello@example.com" }]`) declares From addresses per connection; the plan shows whether each is verified.
+
+## Everything else
+
+```sh
+hermetica profiles list email=ada@example.com
+hermetica campaigns create --data @campaign.json
+hermetica events tail name=signed_up
+hermetica export lists > lists.jsonl
+hermetica openapi list segments            # every operation of the server's OpenAPI document
+hermetica openapi getV1SegmentsByIdMembers id=<segmentId> limit=10
+hermetica help
+```
+
+Every write sends a fresh `Idempotency-Key`. Errors print the API's status, code and details and exit 1.

package/dist/account.d.ts

@@ -0,0 +1,27 @@
+import { type Client } from './client.ts';
+import type { Io } from './commands.ts';
+type Granted = {
+    key: string;
+    prefix: string;
+    scopes: string[];
+    workspaceId: string;
+};
+/** What the CLI's own commands need (status, sequences/mailboxes/leads/inbox, plan/apply, send); the approver sees and may trim them. */
+export declare const DEFAULT_LOGIN_SCOPES: string[];
+export interface LoginFlags {
+    key?: string | undefined;
+    url?: string | undefined;
+    paste?: boolean | undefined;
+    scopes?: string | undefined;
+    profile?: string | undefined;
+}
+/** OAuth-style device flow: show the code, open the browser, poll at the server's pace until approved, denied or expired. */
+export declare function deviceLogin(io: Io, baseUrl: string, scopes?: string[]): Promise<Granted>;
+/** Device login by default; `--key` / `--paste` store an existing secret key instead. The key itself is never printed. */
+export declare function login(io: Io, f: LoginFlags): Promise<void>;
+export declare function logout(io: Io, profile?: string): Promise<void>;
+export declare function whoami(io: Io, client: Client): Promise<void>;
+export declare function status(io: Io, client: Client): Promise<void>;
+/** Asks an owner for more scopes on this key, then waits for the decision (Ctrl-C stops waiting; the request stays open). */
+export declare function requestScopes(io: Io, client: Client, scopes: string[], reason: string | undefined, intervalSec?: number): Promise<void>;
+export {};

package/dist/account.js

@@ -0,0 +1,82 @@
+import { ApiError, makeClient } from './client.js';
+import { baseUrlOf, clearConfig, profileOf, saveConfig, savedBaseUrl } from './config.js';
+/** What the CLI's own commands need (status, sequences/mailboxes/leads/inbox, plan/apply, send); the approver sees and may trim them. */
+export const DEFAULT_LOGIN_SCOPES = ['settings:read', 'workflows:read', 'outbound:read', 'leads:read', 'profiles:read', 'profiles:write', 'consent:read', 'consent:write', 'integrations:read', 'integrations:write', 'messages:send'];
+const reasonOf = (e) => e instanceof ApiError && e.status === 400 ? e.details?.reason : undefined;
+/** OAuth-style device flow: show the code, open the browser, poll at the server's pace until approved, denied or expired. */
+export async function deviceLogin(io, baseUrl, scopes) {
+    const anon = makeClient({ apiKey: '', baseUrl }, io.fetch);
+    const d = (await anon.request('POST', '/v1/auth/device', { body: { scopes: scopes?.length ? scopes : DEFAULT_LOGIN_SCOPES } }));
+    io.out(`Open ${d.verificationUrl} and enter the code ${d.userCode}`);
+    io.openUrl?.(d.verificationUrlComplete ?? d.verificationUrl);
+    let every = Math.max(1, d.interval ?? 5) * 1000;
+    for (let waited = 0; waited < d.expiresIn * 1000; waited += every) {
+        await io.sleep(every);
+        try {
+            return (await anon.request('POST', '/v1/auth/device/token', { body: { deviceCode: d.deviceCode } }));
+        }
+        catch (e) {
+            const reason = reasonOf(e);
+            if (reason === 'authorization_pending')
+                continue;
+            if (reason === 'slow_down') {
+                every += 5000;
+                continue;
+            }
+            if (reason === 'access_denied')
+                throw new Error('The login was denied in the browser.', { cause: e });
+            if (reason === 'expired_token')
+                break;
+            throw e;
+        }
+    }
+    throw new Error('The login code expired. Run "hermetica login" again.');
+}
+/** Device login by default; `--key` / `--paste` store an existing secret key instead. The key itself is never printed. */
+export async function login(io, f) {
+    const profile = profileOf(io.env, f.profile);
+    const baseUrl = baseUrlOf(io.env, await savedBaseUrl(io.env, profile), f.url);
+    if (f.key || f.paste) {
+        const apiKey = (f.key ?? (await io.askKey())).trim();
+        if (!apiKey.startsWith('hm_sk_'))
+            throw new Error('That is not a secret key (hm_sk_...)');
+        const ws = (await makeClient({ apiKey, baseUrl }, io.fetch).request('GET', '/v1/workspace'));
+        const file = await saveConfig({ apiKey, baseUrl }, io.env, profile);
+        return io.out(`Logged in to ${ws.name ?? ws.id ?? 'the workspace'} at ${baseUrl}. Key stored in ${file} (0600), profile ${profile}.`);
+    }
+    const g = await deviceLogin(io, baseUrl, f.scopes?.split(',').map((s) => s.trim()).filter(Boolean));
+    const file = await saveConfig({ apiKey: g.key, baseUrl }, io.env, profile);
+    io.out(`Logged in to workspace ${g.workspaceId} with key ${g.prefix}... (scopes: ${g.scopes.join(', ') || 'none'}). Stored in ${file} (0600), profile ${profile}.`);
+}
+export async function logout(io, profile) {
+    await clearConfig(io.env, profileOf(io.env, profile));
+    io.out(`Logged out (profile ${profileOf(io.env, profile)}).`);
+}
+export async function whoami(io, client) {
+    const me = (await client.request('GET', '/v1/me'));
+    io.out(`${me.user?.email ?? `${me.actor.type} ${me.actor.id}`}${me.actor.role ? ` (${me.actor.role})` : ''}\nworkspace ${me.actor.workspaceId}\nscopes ${me.actor.scopes.join(' ') || '(none)'}`);
+}
+export async function status(io, client) {
+    const r = (await client.request('GET', '/v1/readiness'));
+    io.out(Object.entries(r.canSend).map(([k, v]) => `${k}: ${v ? 'yes' : 'no'}`).join('  '));
+    for (const c of r.checks.filter((x) => !x.ok)) {
+        io.out(`- ${c.key}${c.blocks.length ? ` (blocks ${c.blocks.join(', ')})` : ''}: ${c.fix}`);
+        if (c.api)
+            io.out(`    ${c.api.method} ${c.api.path}${c.requiredScope && c.callerHasScope === false ? `  (needs ${c.requiredScope}: hermetica scopes request ${c.requiredScope} --reason ...)` : ''}`);
+    }
+    if (r.checks.every((x) => x.ok))
+        io.out('Nothing blocks sending.');
+}
+/** Asks an owner for more scopes on this key, then waits for the decision (Ctrl-C stops waiting; the request stays open). */
+export async function requestScopes(io, client, scopes, reason, intervalSec = 5) {
+    if (!scopes.length || !reason)
+        throw new Error('Usage: hermetica scopes request <scope> [<scope> ...] --reason "why you need them"');
+    let r = (await client.request('POST', '/v1/api-keys/requests', { body: { scopes, reason } }));
+    if (r.approveUrl)
+        io.out(`Ask a workspace owner to approve: ${r.approveUrl}`);
+    for (let i = 0; r.status === 'pending' && i < 720; i++) {
+        await io.sleep(intervalSec * 1000);
+        r = (await client.request('GET', `/v1/api-keys/requests/${encodeURIComponent(r.id)}`));
+    }
+    io.out(r.status === 'pending' ? `Still pending; check later with: hermetica openapi list api-keys/requests (request ${r.id})` : `Request ${r.status}.`);
+}

package/dist/args.d.ts

@@ -0,0 +1,4 @@
+/** `key=value` words into a record; any other word is an error, so a typo never becomes a silent positional. */
+export declare function pairs(words: string[]): Record<string, string>;
+/** `--data` as inline JSON, `@file.json`, or `-` for stdin. */
+export declare function readData(raw: string | undefined): Promise<unknown>;

package/dist/args.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+/** `key=value` words into a record; any other word is an error, so a typo never becomes a silent positional. */
+export function pairs(words) {
+    const out = {};
+    for (const w of words) {
+        const i = w.indexOf('=');
+        if (i < 1)
+            throw new Error(`Expected key=value, got "${w}"`);
+        out[w.slice(0, i)] = w.slice(i + 1);
+    }
+    return out;
+}
+const readStdin = async () => { let s = ''; for await (const c of process.stdin)
+    s += String(c); return s; };
+/** `--data` as inline JSON, `@file.json`, or `-` for stdin. */
+export async function readData(raw) {
+    if (raw === undefined)
+        return undefined;
+    const text = raw === '-' ? await readStdin() : raw.startsWith('@') ? await readFile(raw.slice(1), 'utf8') : raw;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('--data is not valid JSON');
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import type { CliConfig } from './config.ts';
+export type Query = Record<string, string | number | boolean | undefined>;
+export interface Client {
+    request: (method: string, path: string, o?: {
+        query?: Query;
+        body?: unknown;
+    }) => Promise<unknown>;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/** Bearer-key client over the REST API (no key: anonymous, for the device login). Writes carry a fresh Idempotency-Key, so a retried command never repeats the action server-side. */
+export declare function makeClient(cfg: CliConfig, fetchFn?: typeof fetch): Client;

package/dist/client.js

@@ -0,0 +1,35 @@
+import { randomUUID } from 'node:crypto';
+export class ApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) { super(message); this.status = status; this.code = code; this.details = details; }
+}
+/** Bearer-key client over the REST API (no key: anonymous, for the device login). Writes carry a fresh Idempotency-Key, so a retried command never repeats the action server-side. */
+export function makeClient(cfg, fetchFn = fetch) {
+    return {
+        async request(method, path, o = {}) {
+            const url = new URL(`${cfg.baseUrl}${path}`); // keeps a base path such as https://host/api
+            for (const [k, v] of Object.entries(o.query ?? {}))
+                if (v !== undefined)
+                    url.searchParams.set(k, String(v));
+            const write = method !== 'GET' && method !== 'HEAD';
+            const res = await fetchFn(url, {
+                method,
+                headers: { ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}), accept: 'application/json', ...(o.body === undefined ? {} : { 'content-type': 'application/json' }), ...(write ? { 'idempotency-key': randomUUID() } : {}) },
+                ...(o.body === undefined ? {} : { body: JSON.stringify(o.body) }),
+            });
+            const text = await res.text();
+            let data = text;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch { /* plain text body */ }
+            if (!res.ok) {
+                const e = data?.error;
+                throw new ApiError(res.status, e?.code ?? 'http_error', e?.message ?? `${res.status} ${res.statusText}`, e?.details);
+            }
+            return data;
+        },
+    };
+}

package/dist/commands.d.ts

@@ -0,0 +1,21 @@
+import { type Client } from './client.ts';
+export declare const RESOURCES: Record<string, string>;
+/** list/get only: creating these goes through flows (connect a mailbox, a lead search, a received reply) the CLI does not model. */
+export declare const READ_ONLY: Record<string, string>;
+export declare const HELP: string;
+export interface Io {
+    env: NodeJS.ProcessEnv;
+    fetch: typeof fetch;
+    out: (s: string) => void;
+    sleep: (ms: number) => Promise<void>;
+    askKey: () => Promise<string>;
+    openUrl?: (url: string) => void;
+}
+/** Newest-first event pages until a seen id: UUIDv7 ids sort by arrival, so everything above `lastId` is new. Returned oldest first. */
+export declare function newEvents(client: Client, lastId: string | null, query: Record<string, string>): Promise<{
+    id: string;
+}[]>;
+/** Runs one command line. Throws on bad input or an API error; main.ts prints it and sets the exit code. */
+export declare function run(argv: string[], io: Io): Promise<void>;
+/** Reads the key from the terminal so it never lands in shell history. */
+export declare function askKey(): Promise<string>;

package/dist/commands.js

@@ -0,0 +1,166 @@
+import { parseArgs } from 'node:util';
+import { createInterface } from 'node:readline/promises';
+import { pairs, readData } from './args.js';
+import { makeClient } from './client.js';
+import { loadConfig } from './config.js';
+import { login, logout, requestScopes, status, whoami } from './account.js';
+import { planOrApply, sendSandbox } from './declare.js';
+import { buildCall, fetchSpec, findOperation, operations } from './openapi.js';
+export const RESOURCES = {
+    profiles: '/v1/profiles', lists: '/v1/lists', campaigns: '/v1/campaigns', sequences: '/v1/outbound/sequences', templates: '/v1/templates',
+};
+/** list/get only: creating these goes through flows (connect a mailbox, a lead search, a received reply) the CLI does not model. */
+export const READ_ONLY = { mailboxes: '/v1/outbound/mailboxes', leads: '/v1/leads', inbox: '/v1/outbound/inbox' };
+const LISTABLE = { ...RESOURCES, ...READ_ONLY };
+export const HELP = `hermetica <command>
+
+  login [--scopes a:read,b:write] [--url https://...]     sign in through the browser (device code); the key is stored, never shown
+  login --key hm_sk_... | --paste                           store an existing secret key instead
+  logout                                                    forget the stored key of this profile
+  whoami                                                    who the stored key acts as, and its scopes
+  status                                                    what blocks sending, with the API call that fixes each step
+  plan -f hermetica.yaml [--prune]                          show what apply would change (config as code, YAML or JSON)
+  apply -f hermetica.yaml [--prune]                         create/update to match the file; --prune archives what it leaves out
+  send --sandbox [--outcome bounce|soft-bounce|complaint]   test email to <outcome>@sandbox.hermeticor.test, no provider needed
+  scopes request <scope> [...] --reason "..."               ask an owner for more scopes and wait for the answer
+  <resource> list [key=value ...]                            resources: ${Object.keys(RESOURCES).join(', ')}
+  <resource> get <id>
+  <resource> create --data '<json>' | @file.json | -
+  ${Object.keys(READ_ONLY).join(', ')} list [key=value ...] | get <id>
+  enrollments list <sequenceId> [key=value ...]              prospects enrolled in a sequence or workflow
+  enrollments get <sequenceId> <enrollmentId>                the step trail of one enrollment
+  send-test campaign <id> --to a@x.com[,b@y.com]             or --data '<json>' (templates need seedListId and connectionId)
+  send-test template <id> --data '<json>'
+  events tail [name=<event>] [--interval 5]                  print new events as JSON lines until Ctrl-C
+  export <resource> [key=value ...]                          every page as JSON lines
+  openapi list [search]                                      operations of the server's OpenAPI document
+  openapi <operationId> [key=value ...] [--data ...]          call any operation: path {params} first, the rest as query
+
+  --profile <name> (or HERMETICA_PROFILE) picks a stored login; HERMETICA_API_KEY and HERMETICA_API_URL override it.`;
+const json = (x) => JSON.stringify(x, null, 2);
+async function* pages(client, path, query) {
+    let cursor;
+    do {
+        const p = (await client.request('GET', path, { query: { limit: 200, ...query, ...(cursor ? { cursor } : {}) } }));
+        yield p.items ?? [];
+        cursor = p.nextCursor ?? undefined;
+    } while (cursor);
+}
+/** Newest-first event pages until a seen id: UUIDv7 ids sort by arrival, so everything above `lastId` is new. Returned oldest first. */
+export async function newEvents(client, lastId, query) {
+    const fresh = [];
+    let cursor;
+    for (let i = 0; i < 10; i++) {
+        const p = (await client.request('GET', '/v1/events', { query: { limit: 100, ...query, ...(cursor ? { cursor } : {}) } }));
+        const mine = lastId ? p.items.filter((e) => e.id > lastId) : p.items;
+        fresh.push(...mine);
+        // The first poll only shows the latest page, like tail.
+        if (!lastId || mine.length < p.items.length || !p.nextCursor)
+            break;
+        cursor = p.nextCursor;
+    }
+    return fresh.toReversed();
+}
+/** Runs one command line. Throws on bad input or an API error; main.ts prints it and sets the exit code. */
+export async function run(argv, io) {
+    const { values: f, positionals: [cmd, ...rest] } = parseArgs({
+        args: argv, allowPositionals: true,
+        options: {
+            key: { type: 'string' }, url: { type: 'string' }, data: { type: 'string', short: 'd' }, to: { type: 'string' }, interval: { type: 'string' }, help: { type: 'boolean', short: 'h' },
+            profile: { type: 'string' }, scopes: { type: 'string' }, paste: { type: 'boolean' }, file: { type: 'string', short: 'f' }, prune: { type: 'boolean' },
+            sandbox: { type: 'boolean' }, outcome: { type: 'string' }, from: { type: 'string' }, subject: { type: 'string' }, text: { type: 'string' }, reason: { type: 'string' },
+        },
+    });
+    if (!cmd || f.help || cmd === 'help')
+        return io.out(HELP);
+    if (cmd === 'login')
+        return login(io, f);
+    if (cmd === 'logout')
+        return logout(io, f.profile);
+    const cfg = await loadConfig(io.env, f.profile || undefined);
+    if (!cfg)
+        throw new Error('Not logged in. Run "hermetica login" or set HERMETICA_API_KEY.');
+    const client = makeClient(cfg, io.fetch);
+    const [a, b, ...more] = rest;
+    if (cmd === 'whoami')
+        return whoami(io, client);
+    if (cmd === 'status')
+        return status(io, client);
+    if (cmd === 'plan' || cmd === 'apply')
+        return planOrApply(io, client, cmd === 'apply', f);
+    if (cmd === 'send')
+        return sendSandbox(io, client, f);
+    if (cmd === 'scopes' && a === 'request')
+        return requestScopes(io, client, [b, ...more].filter((x) => !!x), f.reason, Math.max(1, Number(f.interval ?? 5)));
+    if (cmd in LISTABLE) {
+        const base = LISTABLE[cmd];
+        if (a === 'list')
+            return io.out(json(await client.request('GET', base, { query: pairs([b, ...more].filter((x) => !!x)) })));
+        if (a === 'get' && b)
+            return io.out(json(await client.request('GET', `${base}/${encodeURIComponent(b)}`)));
+        if (a === 'create' && cmd in RESOURCES)
+            return io.out(json(await client.request('POST', base, { body: (await readData(f.data)) ?? {} })));
+        throw new Error(`Usage: hermetica ${cmd} list | get <id>${cmd in RESOURCES ? ' | create --data ...' : ''}`);
+    }
+    if (cmd === 'enrollments') {
+        // A sequence is a workflow in sequence mode, so its enrollments live under /v1/workflows/:id.
+        const [id, enrollmentId] = [b, more[0]];
+        const base = id && `/v1/workflows/${encodeURIComponent(id)}/enrollments`;
+        if (a === 'list' && base)
+            return io.out(json(await client.request('GET', base, { query: pairs(more.filter((x) => !!x)) })));
+        if (a === 'get' && base && enrollmentId)
+            return io.out(json(await client.request('GET', `${base}/${encodeURIComponent(enrollmentId)}/steps`)));
+        throw new Error('Usage: hermetica enrollments list <sequenceId> [key=value ...] | get <sequenceId> <enrollmentId>');
+    }
+    if (cmd === 'send-test') {
+        if ((a !== 'campaign' && a !== 'template') || !b)
+            throw new Error('Usage: hermetica send-test campaign|template <id> --to ... | --data ...');
+        const body = (await readData(f.data)) ?? (f.to ? { emails: f.to.split(',').map((s) => s.trim()).filter(Boolean) } : undefined);
+        if (!body)
+            throw new Error('Give --to or --data');
+        return io.out(json(await client.request('POST', `${RESOURCES[`${a}s`]}/${encodeURIComponent(b)}/test-send`, { body })));
+    }
+    if (cmd === 'events' && a === 'tail') {
+        const query = pairs([b, ...more].filter((x) => !!x));
+        const every = Math.max(1, Number(f.interval ?? 5)) * 1000;
+        let last = null;
+        for (;;) {
+            for (const e of await newEvents(client, last, query)) {
+                io.out(JSON.stringify(e));
+                if (!last || e.id > last)
+                    last = e.id;
+            }
+            await io.sleep(every);
+        }
+    }
+    if (cmd === 'export' && a && a in LISTABLE) {
+        for await (const items of pages(client, LISTABLE[a], pairs([b, ...more].filter((x) => !!x))))
+            for (const x of items)
+                io.out(JSON.stringify(x));
+        return;
+    }
+    if (cmd === 'openapi' && a) {
+        const spec = await fetchSpec(client);
+        if (a === 'list') {
+            const needle = (b ?? '').toLowerCase();
+            for (const o of operations(spec))
+                if (!needle || `${o.id} ${o.path} ${o.summary}`.toLowerCase().includes(needle))
+                    io.out(`${o.id}\t${o.method} ${o.path}${o.summary ? `\t${o.summary}` : ''}`);
+            return;
+        }
+        const call = buildCall(findOperation(spec, a), pairs([b, ...more].filter((x) => !!x)));
+        const body = await readData(f.data);
+        return io.out(json(await client.request(call.method, call.path, { query: call.query, ...(body === undefined ? {} : { body }) })));
+    }
+    throw new Error(`Unknown command "${[cmd, a].filter(Boolean).join(' ')}".\n\n${HELP}`);
+}
+/** Reads the key from the terminal so it never lands in shell history. */
+export async function askKey() {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return await rl.question('API key (hm_sk_...): ');
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface CliConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+export declare const DEFAULT_URL = "https://hermeticor.com";
+/** `$XDG_CONFIG_HOME/hermetica` (default `~/.config/hermetica`). */
+export declare const configDir: (env?: NodeJS.ProcessEnv) => string;
+/** `--profile`, else HERMETICA_PROFILE, else `default`. */
+export declare const profileOf: (env: NodeJS.ProcessEnv, flag?: string) => string;
+/** One profile's login, overridden by HERMETICA_API_KEY / HERMETICA_API_URL. Null when neither gives a key. */
+export declare function loadConfig(env?: NodeJS.ProcessEnv, profile?: string): Promise<CliConfig | null>;
+export declare const baseUrlOf: (env: NodeJS.ProcessEnv, saved?: string, flag?: string) => string;
+export declare const savedBaseUrl: (env: NodeJS.ProcessEnv, profile: string) => Promise<string | undefined>;
+export declare function saveConfig(cfg: CliConfig, env?: NodeJS.ProcessEnv, profile?: string): Promise<string>;
+export declare function clearConfig(env?: NodeJS.ProcessEnv, profile?: string): Promise<void>;

package/dist/config.js

@@ -0,0 +1,43 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const DEFAULT_URL = 'https://hermeticor.com';
+/** `$XDG_CONFIG_HOME/hermetica` (default `~/.config/hermetica`). */
+export const configDir = (env = process.env) => join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'hermetica');
+const file = (env) => join(configDir(env), 'credentials');
+/** `--profile`, else HERMETICA_PROFILE, else `default`. */
+export const profileOf = (env, flag) => flag || env.HERMETICA_PROFILE || 'default';
+async function readAll(env) {
+    try {
+        return JSON.parse(await readFile(file(env), 'utf8'));
+    }
+    catch {
+        return {};
+    } // not logged in yet
+}
+/** One profile's login, overridden by HERMETICA_API_KEY / HERMETICA_API_URL. Null when neither gives a key. */
+export async function loadConfig(env = process.env, profile = profileOf(env)) {
+    const saved = (await readAll(env))[profile] ?? {};
+    const apiKey = env.HERMETICA_API_KEY || saved.apiKey;
+    return apiKey ? { apiKey, baseUrl: baseUrlOf(env, saved.baseUrl) } : null;
+}
+export const baseUrlOf = (env, saved, flag) => (flag || env.HERMETICA_API_URL || saved || DEFAULT_URL).replace(/\/+$/, '');
+export const savedBaseUrl = async (env, profile) => (await readAll(env))[profile]?.baseUrl;
+/** The key is a secret: the directory is 0700 and the file 0600, set again on every write in case it existed with wider modes. */
+async function writeAll(all, env) {
+    await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+    await chmod(configDir(env), 0o700);
+    await writeFile(file(env), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+    await chmod(file(env), 0o600);
+    return file(env);
+}
+export async function saveConfig(cfg, env = process.env, profile = profileOf(env)) {
+    return writeAll({ ...(await readAll(env)), [profile]: cfg }, env);
+}
+export async function clearConfig(env = process.env, profile = profileOf(env)) {
+    const all = await readAll(env);
+    if (!(profile in all))
+        return;
+    delete all[profile];
+    await writeAll(all, env);
+}

package/dist/declare.d.ts

@@ -0,0 +1,18 @@
+import type { Client } from './client.ts';
+import type { Io } from './commands.ts';
+/** `plan` (dry run) or `apply` the declarative config; only differences are listed, with a count line. */
+export declare function planOrApply(io: Io, client: Client, apply: boolean, f: {
+    file?: string | undefined;
+    prune?: boolean | undefined;
+}): Promise<void>;
+export declare const SANDBOX_DOMAIN = "sandbox.hermeticor.test";
+export interface SendFlags {
+    sandbox?: boolean | undefined;
+    outcome?: string | undefined;
+    to?: string | undefined;
+    from?: string | undefined;
+    subject?: string | undefined;
+    text?: string | undefined;
+}
+/** A raw test email to a sandbox address: no provider needed, and the outcome (delivered, bounce, ...) is chosen by the address. */
+export declare function sendSandbox(io: Io, client: Client, f: SendFlags): Promise<void>;

package/dist/declare.js

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+import { parse as parseYaml } from 'yaml';
+const SIGN = { create: '+', update: '~', archive: '-', noop: '=' };
+/** `.yml`/`.yaml` files are YAML, anything else JSON (the same document shape). */
+async function readConfigFile(path) {
+    if (!path)
+        throw new Error('Give the config file: -f hermetica.yaml (or .json)');
+    const yaml = /\.ya?ml$/i.test(path);
+    const text = await readFile(path, 'utf8').catch((e) => { throw new Error(`Cannot read ${path}`, { cause: e }); });
+    let doc;
+    try {
+        doc = yaml ? parseYaml(text) : JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${path} is not valid ${yaml ? 'YAML' : 'JSON'}`, { cause: e });
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        throw new Error(`${path} must hold one object (topics, fields, lists, ...)`);
+    return doc;
+}
+/** `plan` (dry run) or `apply` the declarative config; only differences are listed, with a count line. */
+export async function planOrApply(io, client, apply, f) {
+    const doc = await readConfigFile(f.file);
+    const r = (await client.request('PUT', '/v1/config', { query: apply ? {} : { dryRun: 'true' }, body: f.prune ? { ...doc, prune: true } : doc }));
+    for (const c of r.changes)
+        if (c.action !== 'noop')
+            io.out(`${SIGN[c.action]} ${c.kind} ${c.key}${c.fields?.length ? ` (${c.fields.join(', ')})` : ''}`);
+    const n = (a) => r.changes.filter((c) => c.action === a).length;
+    io.out(`${apply ? 'Applied' : 'Plan'}: ${n('create')} to create, ${n('update')} to update, ${n('archive')} to archive, ${n('noop')} unchanged.`);
+}
+export const SANDBOX_DOMAIN = 'sandbox.hermeticor.test';
+const OUTCOMES = ['delivered', 'bounce', 'soft-bounce', 'complaint'];
+/** A raw test email to a sandbox address: no provider needed, and the outcome (delivered, bounce, ...) is chosen by the address. */
+export async function sendSandbox(io, client, f) {
+    if (!f.sandbox)
+        throw new Error('Only sandbox sends for now: hermetica send --sandbox [--outcome bounce] (use "openapi" for real sends)');
+    if (f.outcome && !OUTCOMES.includes(f.outcome))
+        throw new Error(`--outcome is one of ${OUTCOMES.join(', ')}`);
+    const to = f.to ?? `${f.outcome ?? 'delivered'}@${SANDBOX_DOMAIN}`;
+    if (!to.toLowerCase().endsWith(`@${SANDBOX_DOMAIN}`))
+        throw new Error(`--sandbox sends only to <outcome>@${SANDBOX_DOMAIN}`);
+    const rawMime = [
+        `From: ${f.from ?? `cli@${SANDBOX_DOMAIN}`}`, `To: ${to}`, `Subject: ${f.subject ?? 'Hermetica CLI sandbox test'}`, 'MIME-Version: 1.0', 'Content-Type: text/plain; charset=utf-8', '',
+        f.text ?? 'Sent with hermetica send --sandbox.',
+    ].join('\r\n');
+    io.out(JSON.stringify(await client.request('POST', '/v1/transactional/send-raw', { body: { rawMime, to: [to] } }), null, 2));
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { run, HELP, RESOURCES, type Io } from './commands.ts';
+export { makeClient, ApiError, type Client } from './client.ts';
+export { loadConfig, saveConfig, clearConfig, configDir, profileOf, type CliConfig } from './config.ts';
+export { buildCall, operations, type Operation } from './openapi.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { run, HELP, RESOURCES } from './commands.js';
+export { makeClient, ApiError } from './client.js';
+export { loadConfig, saveConfig, clearConfig, configDir, profileOf } from './config.js';
+export { buildCall, operations } from './openapi.js';

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ApiError } from './client.js';
+import { askKey, run } from './commands.js';
+/** Best effort: with no desktop opener the printed URL is enough. */
+const openUrl = (url) => {
+    const [cmd, ...args] = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => { }).unref();
+    }
+    catch { /* no opener */ }
+};
+try {
+    await run(process.argv.slice(2), { env: process.env, fetch, out: (s) => process.stdout.write(`${s}\n`), sleep: (ms) => sleep(ms), askKey, openUrl });
+}
+catch (e) {
+    const msg = e instanceof ApiError ? `${e.status} ${e.code}: ${e.message}${e.details ? `\n${JSON.stringify(e.details, null, 2)}` : ''}` : e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${msg}\n`);
+    process.exitCode = 1;
+}

package/dist/openapi.d.ts

@@ -0,0 +1,25 @@
+import type { Client, Query } from './client.ts';
+type Op = {
+    operationId?: string;
+    summary?: string;
+};
+export interface Spec {
+    paths?: Record<string, Record<string, Op>>;
+}
+export interface Operation {
+    id: string;
+    method: string;
+    path: string;
+    summary: string;
+}
+/** Every operation in the server's OpenAPI document, in document order. */
+export declare const operations: (spec: Spec) => Operation[];
+/** `key=value` pairs fill the path's `{key}` placeholders; the rest become the query string. A placeholder left unfilled is an error. */
+export declare function buildCall(op: Operation, pairs: Record<string, string>): {
+    method: string;
+    path: string;
+    query: Query;
+};
+export declare const fetchSpec: (client: Client) => Promise<Spec>;
+export declare function findOperation(spec: Spec, id: string): Operation;
+export {};

package/dist/openapi.js

@@ -0,0 +1,23 @@
+const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+/** Every operation in the server's OpenAPI document, in document order. */
+export const operations = (spec) => Object.entries(spec.paths ?? {}).flatMap(([path, ops]) => Object.entries(ops).filter(([m, op]) => METHODS.has(m) && op?.operationId).map(([m, op]) => ({ id: op.operationId, method: m.toUpperCase(), path, summary: op.summary ?? '' })));
+/** `key=value` pairs fill the path's `{key}` placeholders; the rest become the query string. A placeholder left unfilled is an error. */
+export function buildCall(op, pairs) {
+    const query = { ...pairs };
+    const path = op.path.replace(/\{([^}]+)\}/g, (_m, name) => {
+        const v = pairs[name];
+        if (v === undefined)
+            throw new Error(`${op.id} needs ${name}=<value>`);
+        delete query[name];
+        return encodeURIComponent(v);
+    });
+    return { method: op.method, path, query };
+}
+export const fetchSpec = async (client) => (await client.request('GET', '/openapi.json'));
+export function findOperation(spec, id) {
+    const all = operations(spec);
+    const op = all.find((o) => o.id === id) ?? all.find((o) => o.id.toLowerCase() === id.toLowerCase());
+    if (!op)
+        throw new Error(`No operation ${id}. Run "hermetica openapi list ${id.slice(0, 12)}" to search.`);
+    return op;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@hermeticacomms/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Hermetica command line: device login, config as code, sandbox sends, any API operation",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hermeticacomms/hermetica-cli.git"
+  },
+  "homepage": "https://github.com/hermeticacomms/hermetica-cli#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "hermetica": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}