@hermeticacomms/cli 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Changes to `@hermeticacomms/cli`, newest first. Its version follows the Hermeticor API version (`info.version` of the OpenAPI document); the product changelog is at https://hermeticor.com/changelog.
+
+## 0.4.0 - 2026-11-13
+
+- `webhooks listen --forward-to <url> [--topics a,b]`: forwards your workspace's webhook events to a local URL, signed like real deliveries.
+- `login --paste` no longer echoes the key as you type it.
+- The package ships this changelog.
+
+## 0.1.0 - 2026-11-11
+
+- First release: `login` (device code approved in the browser, or `--key` / `--paste`), `whoami`, `status`, `scopes request`, `send --sandbox`, `plan` / `apply` for config as code (YAML or JSON), resource commands (`profiles`, `campaigns`, `events tail`, `export`) and `openapi` for any API operation.

package/README.md

@@ -37,7 +37,15 @@ Missing a scope? `hermetica scopes request connections:write --reason "connect S
 
 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
+## Test a webhook receiver locally
+
+```sh
+hermetica webhooks listen --forward-to http://localhost:3000/api/email-events/hermetica
+hermetica webhooks listen --forward-to http://localhost:3000/hooks --topics message.status,suppression.added
+```
+
+Streams the workspace's new events and POSTs each one to `--forward-to` with the body and headers of a real delivery (`Hermetica-Signature`, `Hermetica-Event-Id`, `Hermetica-Topic`), signed with a secret printed when the session starts: set it as your receiver's webhook secret while testing. One line per event shows your receiver's status code. No retries. Ctrl-C ends the session. Needs `webhooks:write` (included in the default login scopes through `integrations:write`).
+
 
 ```sh
 hermetica profiles list email=ada@example.com

package/dist/commands.d.ts

@@ -17,5 +17,5 @@ export declare function newEvents(client: Client, lastId: string | null, query:
 }[]>;
 /** 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. */
+/** Reads the key from the terminal so it never lands in shell history; the typed characters are not echoed. */
 export declare function askKey(): Promise<string>;

package/dist/commands.js

@@ -1,11 +1,13 @@
 import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
 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';
+import { listen } from './listen.js';
 export const RESOURCES = {
     profiles: '/v1/profiles', lists: '/v1/lists', campaigns: '/v1/campaigns', sequences: '/v1/outbound/sequences', templates: '/v1/templates',
 };
@@ -32,6 +34,7 @@ export const HELP = `hermetica <command>
   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
+  webhooks listen --forward-to <url> [--topics a,b]          forward live webhook events to a local receiver, signed like real deliveries
   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
@@ -69,6 +72,7 @@ export async function run(argv, io) {
             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' },
+            'forward-to': { type: 'string' }, topics: { type: 'string' },
         },
     });
     if (!cmd || f.help || cmd === 'help')
@@ -133,6 +137,19 @@ export async function run(argv, io) {
             await io.sleep(every);
         }
     }
+    if (cmd === 'webhooks' && a === 'listen') {
+        if (!f['forward-to'])
+            throw new Error('Usage: hermetica webhooks listen --forward-to http://localhost:3000/webhooks [--topics profile.*,message.event]');
+        const stop = new AbortController();
+        const onInt = () => stop.abort(); // first Ctrl-C stops cleanly (the session is deleted); a second one exits at once
+        process.once('SIGINT', onInt);
+        try {
+            return await listen(io, client, cfg, { forwardTo: f['forward-to'], topics: f.topics?.split(',').map((t) => t.trim()).filter(Boolean), signal: stop.signal });
+        }
+        finally {
+            process.off('SIGINT', onInt);
+        }
+    }
     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)
@@ -154,13 +171,19 @@ export async function run(argv, io) {
     }
     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. */
+/** Reads the key from the terminal so it never lands in shell history; the typed characters are not echoed. */
 export async function askKey() {
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let muted = false;
+    const output = new Writable({ write(chunk, _enc, done) { if (!muted)
+            process.stderr.write(chunk); done(); } });
+    const rl = createInterface({ input: process.stdin, output, terminal: Boolean(process.stdin.isTTY) });
     try {
-        return await rl.question('API key (hm_sk_...): ');
+        const answer = rl.question('API key (hm_sk_...): '); // the prompt is written before this returns
+        muted = true;
+        return await answer;
     }
     finally {
         rl.close();
+        process.stderr.write('\n');
     }
 }

package/dist/listen.d.ts

@@ -0,0 +1,24 @@
+import { type Client } from './client.ts';
+import type { CliConfig } from './config.ts';
+import type { Io } from './commands.ts';
+/** `Hermetica-Signature` as real deliveries send it: `t=<unix>,v1=<hex hmac-sha256 of "t.body">`. */
+export declare const signBody: (secret: string, body: string, nowSec: number) => string;
+/** POSTs one event body to the local receiver with the headers of a real delivery. Never throws: returns the status or the error text. */
+export declare function forwardEvent(fetchFn: typeof fetch, url: string, secret: string, body: string, nowSec: number): Promise<{
+    status: number | null;
+    error?: string;
+}>;
+/** `event:`/`data:` blocks of a server-sent event stream. */
+export declare function sseEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<{
+    event: string;
+    data: string;
+}>;
+/**
+ * `webhooks listen`: opens a listen session, streams its events and forwards each to `forwardTo`, signed with the session secret.
+ * Reconnects when the server closes the stream; ends when the session is gone (404) or on Ctrl-C (`signal`), deleting the session.
+ */
+export declare function listen(io: Io, client: Client, cfg: CliConfig, o: {
+    forwardTo: string;
+    topics?: string[] | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<void>;

package/dist/listen.js

@@ -0,0 +1,86 @@
+import { createHmac } from 'node:crypto';
+import { ApiError } from './client.js';
+/** `Hermetica-Signature` as real deliveries send it: `t=<unix>,v1=<hex hmac-sha256 of "t.body">`. */
+export const signBody = (secret, body, nowSec) => `t=${nowSec},v1=${createHmac('sha256', secret).update(`${nowSec}.${body}`).digest('hex')}`;
+/** POSTs one event body to the local receiver with the headers of a real delivery. Never throws: returns the status or the error text. */
+export async function forwardEvent(fetchFn, url, secret, body, nowSec) {
+    const e = JSON.parse(body);
+    try {
+        const res = await fetchFn(url, {
+            method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(10_000), body,
+            headers: { 'content-type': 'application/json', 'user-agent': 'Hermetica-Webhooks/1', 'hermetica-signature': signBody(secret, body, nowSec), 'hermetica-event-id': e.id, 'hermetica-topic': e.topic },
+        });
+        await res.body?.cancel();
+        return { status: res.status };
+    }
+    catch (err) {
+        return { status: null, error: err.message };
+    }
+}
+/** `event:`/`data:` blocks of a server-sent event stream. */
+export async function* sseEvents(body) {
+    let buf = '';
+    const dec = new TextDecoder();
+    for await (const bytes of body) {
+        buf += dec.decode(bytes, { stream: true });
+        for (let i = buf.indexOf('\n\n'); i >= 0; i = buf.indexOf('\n\n')) {
+            const block = buf.slice(0, i);
+            buf = buf.slice(i + 2);
+            const event = /^event: (.*)$/m.exec(block)?.[1];
+            const data = /^data: (.*)$/m.exec(block)?.[1];
+            if (event && data !== undefined)
+                yield { event, data };
+        }
+    }
+}
+/**
+ * `webhooks listen`: opens a listen session, streams its events and forwards each to `forwardTo`, signed with the session secret.
+ * Reconnects when the server closes the stream; ends when the session is gone (404) or on Ctrl-C (`signal`), deleting the session.
+ */
+export async function listen(io, client, cfg, o) {
+    if (!/^https?:\/\//.test(o.forwardTo))
+        throw new Error('--forward-to must be an http(s) URL, e.g. http://localhost:3000/webhooks');
+    const s = (await client.request('POST', '/v1/webhooks/listen', { body: o.topics?.length ? { topics: o.topics } : {} }));
+    io.out(`Ready. Forwarding ${s.topics.join(', ')} to ${o.forwardTo}`);
+    io.out(`Your webhook signing secret for this session is ${s.secret} (set it in your receiver; Ctrl-C to stop)`);
+    try {
+        while (!o.signal?.aborted) {
+            let res;
+            try {
+                res = await io.fetch(`${cfg.baseUrl}/v1/webhooks/listen/${s.id}/events`, { headers: { authorization: `Bearer ${cfg.apiKey}`, accept: 'text/event-stream' }, ...(o.signal ? { signal: o.signal } : {}) });
+            }
+            catch {
+                if (o.signal?.aborted)
+                    break;
+                await io.sleep(2000); // network blip: try again
+                continue;
+            }
+            if (res.status === 404) {
+                io.out('The listen session ended.');
+                return;
+            }
+            if (!res.ok || !res.body)
+                throw new ApiError(res.status, 'http_error', `Could not open the event stream (${res.status})`);
+            try {
+                for await (const e of sseEvents(res.body)) {
+                    if (e.event === 'done') {
+                        io.out('The listen session ended.');
+                        return;
+                    }
+                    if (e.event !== 'webhook')
+                        continue;
+                    const r = await forwardEvent(io.fetch, o.forwardTo, s.secret, e.data, Math.floor(Date.now() / 1000));
+                    const { id, topic } = JSON.parse(e.data);
+                    io.out(`${new Date().toISOString()}  ${topic}  ${id}  -> ${r.status ?? `error: ${r.error}`}`);
+                }
+            }
+            catch {
+                if (!o.signal?.aborted)
+                    await io.sleep(1000);
+            } // stream cut mid-way: reconnect, the cursor is kept server-side
+        }
+    }
+    finally {
+        await client.request('DELETE', `/v1/webhooks/listen/${s.id}`).catch(() => { }); // already gone is fine
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hermeticacomms/cli",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Hermetica command line: device login, config as code, sandbox sends, any API operation",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20"