@sendoka/cli 0.2.2

package/README.md

@@ -0,0 +1,88 @@
+# sendoka CLI
+
+Developer tools for the Sendoka API — send messages, tail messages as they are created, forward webhook deliveries locally, trigger synthetic events.
+
+Five commands, all of them below. There is no key management, no domain management and no interactive login; use the [dashboard](https://www.sendoka.com/overview) or the REST API for the rest. Full reference: [docs/developer-tools/cli.md](https://www.sendoka.com/docs/guides/developer-tools/cli).
+
+## Install
+
+Not published to npm yet, and Sendoka does not hold the `sendoka` name there:
+a package installed under that name from the registry is not this one. From a
+checkout of the repository:
+
+```bash
+cd packages/cli
+npm install && npm run build
+npm link   # puts `sendoka` on your PATH
+```
+
+Requires Node 20+.
+
+## Configure
+
+Every command authenticates with an API key.
+
+```bash
+export SENDOKA_API_KEY=sok_test_...
+
+# For `listen` only: the endpoint's whsec_ signing secret, so forwarded
+# deliveries are re-signed. --secret works too.
+export SENDOKA_WEBHOOK_SECRET=whsec_...
+
+# Optional. Defaults to https://www.sendoka.com.
+export SENDOKA_BASE_URL=https://www.sendoka.com
+```
+
+The key needs the scope its endpoint needs: `send:email` / `send:sms` for the sends, `read:messages` for `logs tail`, `read:webhooks` for `listen`, `write:webhooks` for `events trigger`. A full-access key has all of them.
+
+With a `sok_test_*` key, `listen` forwards only deliveries of test-mode events (test sends and `events trigger` fires): an endpoint also receives live traffic, and a test key cannot read it. Its list pages can come back empty with more to follow; `listen` starts below the first such page rather than forwarding older deliveries as new. To forward live deliveries, use a live key scoped to `read:webhooks` alone.
+
+Every request counts against your org's `/api/v1` rate limit (60/min on Free), the same budget your production sends use. `listen` makes 12 requests a minute and `logs tail` 24 at the default 5-second interval; on a Free org raise `--interval`, or give the CLI a key with its own per-key limit. Both wait out a `429`'s `Retry-After` and resume without skipping anything.
+
+`SENDOKA_SESSION_COOKIE` is no longer read. `listen` and `events trigger` used to send it to `/api/internal/*` under the cookie name NextAuth uses over plain http, which the https host never reads — both answered 401 against www.sendoka.com. They now use the public `/api/v1/webhooks` routes with the key.
+
+## Usage
+
+### Send
+
+```bash
+sendoka send email \
+  --from hello@yourdomain.com \
+  --to user@example.com \
+  --subject "Hello" \
+  --html "<p>From the CLI</p>"
+
+sendoka send sms --from +15551234567 --to +15559876543 --body "Test"
+```
+
+`--to` is comma-separated for several recipients; the flag is not repeatable. `--template` + `--variables '{"name":"Mira"}'` render a stored template instead of an inline body. Attachments, tags, scheduling and `Idempotency-Key` are not exposed here — use an HTTP client for those.
+
+### Tail messages
+
+```bash
+sendoka logs tail
+sendoka logs tail --channel sms --interval 15
+```
+
+Polls `GET /api/v1/emails` and `GET /api/v1/sms` by `created_after` and prints one line per **new** message, starting from now, for the key's environment. Each message is printed once, with its status when first seen; later transitions (`delivered`, `bounced`) are what webhooks are for. `--days` from the old aggregate version is ignored.
+
+### Forward webhook deliveries to a local URL
+
+```bash
+sendoka listen --endpoint whk_xxx --forward-to http://localhost:3001/hooks
+```
+
+Polls `GET /api/v1/webhooks/{id}/deliveries?include=payload` for that endpoint and re-POSTs each delivery created after the command started to `--forward-to` — body and headers as production sends them, **signed with the endpoint secret** (`--secret` or `SENDOKA_WEBHOOK_SECRET`), so the SDK's `verifyWebhookSignature` passes and your handler can keep verification on. Without a secret it warns and forwards unsigned. Avoids ngrok for local webhook dev.
+
+### Trigger a synthetic event
+
+```bash
+sendoka events trigger message.bounced --endpoint whk_xxx
+sendoka events trigger message.bounced --endpoint whk_xxx --data '{"channel":"sms"}'
+```
+
+`POST /api/v1/webhooks/{id}/test-fire`: fires a properly-signed test delivery at one of your webhook endpoints. Payloads carry `data.test: true` and `"environment": "test"` so your handler can distinguish them; `--data` (a JSON object) is merged over the synthetic data but cannot change those markers or the synthetic `message_id`. `--event message.bounced` is accepted as an equivalent to the positional form. Combine with `listen` for a fully local loop.
+
+## Exit codes
+
+`0` success, `1` the command threw (HTTP error, missing env var, bad `--variables` / `--data` JSON), `2` unknown command. There are no per-status codes — an HTTP error prints `HTTP <status>: <message> (<CODE>)` on stderr; branch on the code.

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Sendoka CLI — minimal developer loop over the REST API.
+ *
+ *   sendoka send email --from a --to b --subject hi --html "<p>…</p>"
+ *   sendoka send sms   --from +1 --to +1 --body hi
+ *   sendoka logs tail            (polls /api/v1/emails + /api/v1/sms by created_after)
+ *   sendoka listen --endpoint whk_xxx --forward-to http://localhost:3001/hook
+ *                               (polls /api/v1/webhooks/:id/deliveries and forwards
+ *                                each new payload, re-signed with --secret)
+ *   sendoka events trigger message.bounced --endpoint whk_xxx
+ *                               (hits /api/v1/webhooks/:id/test-fire)
+ *
+ * Auth: every command reads SENDOKA_API_KEY from the environment. There is no
+ * session-cookie path any more — see client.ts for why it never worked on https.
+ */
+import { resolveCommand } from "./commands/index.js";
+import { parseFlags, splitInvocation } from "./flags.js";
+import { CLI_VERSION } from "./version.js";
+async function main(argv) {
+    const [, , ...rest] = argv;
+    if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
+        printUsage();
+        return;
+    }
+    if (rest[0] === "--version" || rest[0] === "-v") {
+        console.log(`sendoka ${CLI_VERSION}`);
+        return;
+    }
+    const { group, action, args } = splitInvocation(rest);
+    const cmd = resolveCommand(group, action);
+    if (!cmd) {
+        console.error(`Unknown command: ${group}${action ? " " + action : ""}`);
+        printUsage();
+        process.exit(2);
+    }
+    try {
+        await cmd(parseFlags(args));
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
+}
+function printUsage() {
+    console.log(`sendoka — developer CLI
+
+Usage:
+  sendoka send email --from <addr> --to <addr> [--subject] [--html|--text] [--template]
+  sendoka send sms   --from <num>  --to <num>  --body <text>
+  sendoka logs tail  [--channel email|sms] [--interval 5]
+  sendoka listen     --endpoint <whk_id> --forward-to <url> [--secret <whsec_...>] [--interval 5]
+  sendoka events trigger <event> --endpoint <whk_id> [--data <json>]
+
+Env:
+  SENDOKA_API_KEY        sok_live_* or sok_test_* — every command
+  SENDOKA_BASE_URL       defaults to https://www.sendoka.com
+  SENDOKA_WEBHOOK_SECRET the endpoint's whsec_ secret, for \`listen\` (or --secret)
+
+Run with --help on any subcommand for details.`);
+}
+main(process.argv).catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,70 @@
+export function baseUrl() {
+    return (process.env.SENDOKA_BASE_URL ?? "https://www.sendoka.com").replace(/\/$/, "");
+}
+export function apiKey() {
+    const k = process.env.SENDOKA_API_KEY;
+    if (!k)
+        throw new Error("Set SENDOKA_API_KEY to an sok_live_* / sok_test_* key.");
+    return k;
+}
+/**
+ * A non-2xx answer from `/api/v1`. The message keeps the `HTTP <status>:
+ * <message> (<CODE>)` shape the CLI prints; `status` and `retryAfterSeconds`
+ * are there so a polling command can tell a 429 — back off, the rows are
+ * still there — from an answer that will not change on retry.
+ */
+export class ApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    constructor(message, status, code, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "ApiError";
+    }
+}
+export function isRateLimited(err) {
+    return err instanceof ApiError && err.status === 429;
+}
+/** `Retry-After` in seconds, or null. Only the delta-seconds form is sent by /v1. */
+function retryAfter(res) {
+    const raw = typeof res.headers?.get === "function" ? res.headers.get("retry-after") : null;
+    const n = raw === null ? NaN : Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/**
+ * Every command goes through here, with the API key. There used to be a second
+ * client for `/api/internal/*` that sent `Cookie: next-auth.session-token=…`,
+ * for `listen` and `events trigger` — and it could not authenticate against
+ * the default host. NextAuth v4 names the cookie
+ * `__Secure-next-auth.session-token` whenever it is served over https, so the
+ * unprefixed name the CLI sent was never read and both commands answered 401
+ * on www.sendoka.com. Both now use the public `/v1/webhooks` routes instead.
+ */
+export async function callV1(method, path, body) {
+    const res = await fetch(`${baseUrl()}/api/v1${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${apiKey()}`,
+            "Content-Type": "application/json",
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = text;
+    }
+    if (!res.ok) {
+        const error = parsed?.error;
+        const message = error?.message ?? text;
+        // The code is what a script branches on — the message is prose and moves.
+        throw new ApiError(`HTTP ${res.status}: ${message}${error?.code ? ` (${error.code})` : ""}`, res.status, error?.code ?? null, retryAfter(res));
+    }
+    return parsed;
+}

package/dist/commands/events.js

@@ -0,0 +1,47 @@
+import { callV1 } from "../client.js";
+const USAGE = "Usage: sendoka events trigger <message.bounced|...> --endpoint <whk_id> [--data '<json object>']";
+/**
+ * Fire a synthetic, signed delivery at one of your endpoints —
+ * `POST /api/v1/webhooks/{id}/test-fire` with the API key (`write:webhooks`).
+ *
+ * This used to call `/api/internal/webhooks/{id}/trigger-test` with a session
+ * cookie under the name NextAuth only uses over plain http, so it answered 401
+ * against the default https host on every run. The v1 route is the same
+ * operation — same payload shape, same signing, same 20/min budget shared with
+ * the dashboard's test button — reachable with the key every other command
+ * already reads.
+ */
+export async function eventsTrigger(flags) {
+    // `--event` and the positional form are equivalent; the flag wins if both
+    // are given, since it is the one that cannot be a mistyped stray word.
+    const eventName = typeof flags.event === "string" ? flags.event : typeof flags._ === "string" ? flags._ : null;
+    const endpoint = typeof flags.endpoint === "string" ? flags.endpoint : null;
+    if (!eventName || !endpoint)
+        throw new Error(USAGE);
+    const data = parseDataFlag(flags.data);
+    const res = await callV1("POST", `/webhooks/${encodeURIComponent(endpoint)}/test-fire`, data ? { event: eventName, data } : { event: eventName });
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+}
+/**
+ * `--data` is merged over the synthetic `data` object server-side, so it has
+ * to be a JSON object: the route validates it as a record and would answer an
+ * array or a scalar with a 422 after the round trip. Refused here instead.
+ */
+function parseDataFlag(v) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new Error(`--data needs a JSON object, e.g. --data '{"channel":"sms"}'`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(v);
+    }
+    catch {
+        throw new Error(`--data must be JSON (got ${JSON.stringify(v)})`);
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`--data must be a JSON object (got ${JSON.stringify(v)})`);
+    }
+    return parsed;
+}

package/dist/commands/index.js

@@ -0,0 +1,30 @@
+import { sendEmail, sendSms } from "./send.js";
+import { logsTail } from "./logs.js";
+import { listen } from "./listen.js";
+import { eventsTrigger } from "./events.js";
+const TABLE = {
+    send: {
+        email: sendEmail,
+        sms: sendSms,
+    },
+    logs: {
+        tail: logsTail,
+    },
+    listen: {
+        "": listen,
+    },
+    events: {
+        trigger: eventsTrigger,
+    },
+};
+export function resolveCommand(group, action) {
+    const grp = TABLE[group];
+    if (!grp)
+        return null;
+    // A flag where the action would be means the group itself is the command —
+    // `sendoka listen --forward-to <url>`. Treating `--forward-to` as an action
+    // resolved nothing and made the only group-only command unreachable.
+    if (!action || action.startsWith("-"))
+        return grp[""] ?? null;
+    return grp[action] ?? null;
+}

package/dist/commands/listen.js

@@ -0,0 +1,379 @@
+import { createHmac } from "node:crypto";
+import { ApiError, callV1, isRateLimited } from "../client.js";
+const PAGE_SIZE = 50;
+/** Pages walked per poll before giving up on reaching already-seen rows. */
+const MAX_PAGES = 10;
+/**
+ * Upper bound on remembered delivery ids. The list is newest-first and a poll
+ * stops at the first page holding a remembered id, so only the newest ids ever
+ * matter; dropping the oldest keeps a day-long session from growing without
+ * bound.
+ */
+const SEEN_CAP = 5000;
+/**
+ * Polls a delivery's payload may fail to load (5xx, network) before it is
+ * skipped. A 429 is not a failure and never counts: the row is still there,
+ * the org's budget is not.
+ */
+const MAX_FETCH_ATTEMPTS = 3;
+/** Pause after a 429 that carried no usable `Retry-After`. */
+const DEFAULT_BACKOFF_MS = 30_000;
+/**
+ * How far behind the newest delivery a poll has read the floor is kept. A
+ * row's `created_at` is stamped when it is inserted, and one can become
+ * visible a moment after a newer one; rows inside this margin are still
+ * walked, and the seen-set keeps them from being forwarded twice.
+ */
+const LATE_COMMIT_SLACK_MS = 60_000;
+const USAGE = "Usage: sendoka listen --endpoint <whk_id> --forward-to <url> [--secret <whsec_...>] [--interval 5]";
+/**
+ * The request `attemptDelivery` (src/lib/api/webhook-fanout.ts) would have
+ * sent, rebuilt from a stored delivery. Byte-for-byte the same shape: the body
+ * is the stored payload with `delivery_id` stamped on, and the three signature
+ * headers are computed exactly as the server computes them —
+ *
+ *   X-Sendoka-Signature     HMAC-SHA256(secret, body)                 legacy
+ *   X-Sendoka-Timestamp     unix seconds
+ *   X-Sendoka-Signature-V2  HMAC-SHA256(secret, `${timestamp}.${body}`)
+ *
+ * so a local handler calling the SDK's `verifyWebhookSignature` (or the
+ * hand-rolled check in docs/recipes/verify-webhooks.md) accepts it unchanged.
+ * The timestamp is the moment of forwarding, not of the original attempt, or
+ * the SDK's five-minute replay window would reject anything older.
+ *
+ * Without a secret the signature headers are omitted rather than faked: a
+ * handler that verifies then rejects the request, which is the honest outcome.
+ */
+export function buildForwardRequest(delivery, secret, nowMs = Date.now()) {
+    const payload = delivery.payload ?? {};
+    const body = JSON.stringify({ ...payload, delivery_id: delivery.id });
+    const timestamp = Math.floor(nowMs / 1000).toString();
+    const headers = {
+        "Content-Type": "application/json",
+        "X-Sendoka-Timestamp": timestamp,
+        "X-Sendoka-Event": delivery.event,
+        "X-Sendoka-Delivery-Id": delivery.id,
+        "X-Sendoka-Forwarded": "cli",
+    };
+    if (secret) {
+        headers["X-Sendoka-Signature"] = createHmac("sha256", secret).update(body).digest("hex");
+        headers["X-Sendoka-Signature-V2"] = createHmac("sha256", secret)
+            .update(`${timestamp}.${body}`)
+            .digest("hex");
+    }
+    if (typeof payload.environment === "string") {
+        headers["X-Sendoka-Environment"] = payload.environment;
+    }
+    if (typeof payload.tenant_id === "string" && payload.tenant_id) {
+        headers["X-Sendoka-Tenant-Id"] = payload.tenant_id;
+    }
+    return { body, headers };
+}
+/**
+ * The instant a `next_cursor` resumes below, as an ISO string, or null when it
+ * cannot be read.
+ *
+ * Cursors are opaque to API clients, but this CLI ships from the same
+ * repository as the API: a cursor is base64url(`{ISO}|{id}`)
+ * (src/lib/api/cursor.ts). It is read because of a test key's list: a page
+ * stops after reading a bounded slice of the endpoint (mostly live rows it may
+ * not see), so it can come back short or EMPTY with `has_more`, and then only
+ * its cursor says how far back it read. Anything unreadable answers null and
+ * is treated as unknown, never as a time.
+ */
+export function cursorTime(cursor) {
+    if (!cursor)
+        return null;
+    try {
+        const [iso, id] = Buffer.from(cursor, "base64url").toString("utf8").split("|");
+        if (!iso || !id)
+            return null;
+        const ms = Date.parse(iso);
+        return Number.isFinite(ms) && /^\d{4}-\d{2}-\d{2}T/.test(iso) ? new Date(ms).toISOString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The polling state machine behind `sendoka listen`, separated from the
+ * infinite loop so it can be driven one step at a time.
+ *
+ * `prime()` records what already exists and forwards none of it — the command
+ * starts from now. The old version seeded an empty seen-set, so its first poll
+ * re-POSTed the twenty most recent deliveries, whatever their age, and every
+ * restart replayed them again. What it records is a FLOOR: the newest
+ * delivery the key can see, everything older than which is history. A test
+ * key's page can be empty with more to follow (it read a slice of the
+ * endpoint's live traffic and found none of its own), so prime follows the
+ * list until it has one — from the first row it finds, or, for a page that
+ * found none, from the page's cursor, below which everything it did not see
+ * lies — and failing both, starts from the current time.
+ *
+ * `poll()` walks the newest-first list until it reaches a delivery it has
+ * already seen or one older than the floor — or a cursor that resumes below
+ * the floor, which is how a walk through empty pages ends — then forwards
+ * everything new oldest-first. Within that last page it keeps scanning rather
+ * than stopping at the first known row, so a row that committed slightly out
+ * of `created_at` order is still caught. A walk that got to the end raises the
+ * floor to a minute behind the newest point it read (never past a delivery
+ * still waiting to be forwarded), so the next one does not re-read the
+ * endpoint's traffic since startup.
+ *
+ * Every request here counts against the org-wide `/v1` rate limit — the same
+ * budget the org's production sends draw on (60/min on Free), test keys
+ * included. So the list is read with `include=payload`, one request per page
+ * rather than one more per delivery, and a 429 pauses the loop for the
+ * server's `Retry-After` instead of pressing on. A delivery is only
+ * remembered once its payload is in hand (or the server says it is gone), so
+ * one that could not be loaded is still new on the next poll; the ones behind
+ * it wait too, which keeps them in order. Failing to reach `--forward-to` is
+ * different: that is reported once and not retried.
+ */
+export function createForwarder(opts) {
+    const log = opts.log ?? ((l) => console.log(l));
+    const warn = opts.warn ?? ((l) => console.error(l));
+    const now = opts.now ?? Date.now;
+    const base = `/webhooks/${encodeURIComponent(opts.endpoint)}/deliveries`;
+    const seen = new Set();
+    const failures = new Map();
+    let floor = null;
+    let backoffUntil = 0;
+    function remember(id) {
+        seen.add(id);
+        failures.delete(id);
+        if (seen.size > SEEN_CAP) {
+            const oldest = seen.values().next().value;
+            if (oldest !== undefined)
+                seen.delete(oldest);
+        }
+    }
+    function backOff(err, pending) {
+        const ms = err.retryAfterSeconds !== null ? err.retryAfterSeconds * 1000 : DEFAULT_BACKOFF_MS;
+        backoffUntil = Math.max(backoffUntil, now() + ms);
+        warn(`Rate limited (429) — this org's /v1 budget is spent. Pausing ${Math.ceil(ms / 1000)}s` +
+            (pending > 0 ? `; ${pending} ${pending === 1 ? "delivery waits" : "deliveries wait"} for the next poll.` : "."));
+    }
+    function listPath(cursor) {
+        return `${base}?limit=${PAGE_SIZE}&include=payload${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+    }
+    async function prime() {
+        let cursor = null;
+        for (let pages = 0; pages < MAX_PAGES; pages++) {
+            // Ids only: nothing here is forwarded, so its payloads are not asked for.
+            const page = await callV1("GET", `${base}?limit=${PAGE_SIZE}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
+            if (page.data.length > 0) {
+                // Newest first, so the first row found is the newest the key can see.
+                // Oldest first into the set, so the newest ids are the last evicted.
+                for (const row of [...page.data].reverse())
+                    remember(row.id);
+                floor = page.data[0].created_at;
+                return page.data.length;
+            }
+            // Nothing visible, and nothing more to read: there is no history to
+            // skip, and every delivery from here on is new.
+            if (!page.has_more || !page.next_cursor)
+                return 0;
+            // An empty page with more to follow read everything newer than its
+            // cursor and found nothing this key may see, so anything older is all
+            // there is. That is the floor.
+            const below = cursorTime(page.next_cursor);
+            if (below) {
+                floor = below;
+                return 0;
+            }
+            cursor = page.next_cursor;
+        }
+        // A server whose cursor this cannot read, and pages of nothing: start
+        // from now rather than forward whatever lies further back.
+        floor = new Date(now()).toISOString();
+        return 0;
+    }
+    /**
+     * How long to wait before the next poll: the interval, or longer while a
+     * 429's `Retry-After` is still running.
+     */
+    function delayBeforeNextPoll(intervalMs) {
+        return Math.max(intervalMs, backoffUntil - now());
+    }
+    async function poll() {
+        const fresh = [];
+        let cursor = null;
+        // The newest point this walk read: its newest row, or where an empty
+        // first page's slice ended. Null until known.
+        let newest = null;
+        // Whether the walk reached what was already known (or the list's end).
+        let complete = false;
+        for (let pages = 0;; pages++) {
+            if (pages === MAX_PAGES) {
+                // Only what is true: pages of a test key's list can be short or empty,
+                // so a page count says nothing about how many deliveries were new.
+                warn(`Read ${MAX_PAGES} pages without reaching deliveries already seen; forwarding the ${fresh.length} new ${fresh.length === 1 ? "one" : "ones"} found, and skipping anything older.`);
+                break;
+            }
+            let page;
+            try {
+                page = await callV1("GET", listPath(cursor));
+            }
+            catch (err) {
+                if (!isRateLimited(err))
+                    throw err;
+                // Nothing is remembered yet, so the whole walk simply happens again.
+                backOff(err, 0);
+                return 0;
+            }
+            let reachedKnown = false;
+            for (const row of page.data) {
+                if (newest === null || row.created_at > newest)
+                    newest = row.created_at;
+                if (seen.has(row.id) || (floor !== null && row.created_at < floor)) {
+                    reachedKnown = true;
+                    continue;
+                }
+                fresh.push(row);
+            }
+            const next = page.has_more ? page.next_cursor : null;
+            const below = cursorTime(next);
+            if (pages === 0 && page.data.length === 0 && below)
+                newest = below;
+            // Past the floor, everything is history: the end of a walk through
+            // empty pages, which have no row to compare.
+            if (reachedKnown || !next || (floor !== null && below !== null && below < floor)) {
+                complete = true;
+                break;
+            }
+            cursor = next;
+        }
+        fresh.sort((a, b) => a.created_at === b.created_at ? a.id.localeCompare(b.id) : a.created_at.localeCompare(b.created_at));
+        let forwarded = 0;
+        let waiting = null;
+        for (const [i, row] of fresh.entries()) {
+            const detail = await load(row, fresh.length - i);
+            if (detail === "stop") {
+                // This row and every newer one wait for the next poll.
+                waiting = row.created_at;
+                break;
+            }
+            // Remembered once the payload is in hand, before the local POST: a
+            // handler that is down is reported once rather than retried every
+            // interval.
+            remember(row.id);
+            if (detail === "skip")
+                continue;
+            await forward(row, detail);
+            forwarded++;
+        }
+        if (complete)
+            raiseFloor(newest, waiting);
+        return forwarded;
+    }
+    /**
+     * After a complete walk: move the floor up to LATE_COMMIT_SLACK_MS behind
+     * the newest point read, but never past a delivery still waiting, and never
+     * down.
+     */
+    function raiseFloor(newest, waiting) {
+        if (newest === null)
+            return;
+        let candidate = new Date(Date.parse(newest) - LATE_COMMIT_SLACK_MS).toISOString();
+        if (waiting !== null && waiting < candidate)
+            candidate = waiting;
+        if (floor === null || candidate > floor)
+            floor = candidate;
+    }
+    /**
+     * The payload for one row: from the list when the server sent it, else the
+     * drill-down. "stop" ends this poll with the row (and every newer one)
+     * unremembered, so the next poll finds them again; "skip" drops the row.
+     */
+    async function load(row, pending) {
+        if (row.payload !== undefined) {
+            return { id: row.id, event: row.event, payload: row.payload, created_at: row.created_at };
+        }
+        try {
+            return await callV1("GET", `${base}/${encodeURIComponent(row.id)}`);
+        }
+        catch (err) {
+            if (isRateLimited(err)) {
+                backOff(err, pending);
+                return "stop";
+            }
+            if (err instanceof ApiError && err.status === 404) {
+                // Deleted with its endpoint, or no longer in scope: it will not come back.
+                warn(`[${row.id}] no longer exists; skipped.`);
+                return "skip";
+            }
+            const attempts = (failures.get(row.id) ?? 0) + 1;
+            failures.set(row.id, attempts);
+            if (attempts >= MAX_FETCH_ATTEMPTS) {
+                warn(`[${row.id}] could not fetch payload after ${attempts} polls; skipped: ${err.message}`);
+                return "skip";
+            }
+            warn(`[${row.id}] could not fetch payload (retrying next poll): ${err.message}`);
+            return "stop";
+        }
+    }
+    async function forward(row, detail) {
+        const { body, headers } = buildForwardRequest(detail, opts.secret);
+        try {
+            const res = await fetch(opts.forwardTo, { method: "POST", headers, body });
+            log(`[${row.created_at}] ${row.event.padEnd(22)} ${row.id} → ${res.status}`);
+        }
+        catch (err) {
+            warn(`[${row.id}] forward failed: ${err.message}`);
+        }
+    }
+    return { prime, poll, delayBeforeNextPoll };
+}
+/**
+ * `sendoka listen` — forward one endpoint's webhook deliveries to a local URL,
+ * re-signed with the endpoint's secret, so a local handler receives real
+ * events, signature check included, without a public tunnel.
+ *
+ * Reads `GET /api/v1/webhooks/{id}/deliveries` (`read:webhooks`) with the API
+ * key, one request per page per interval — against the same org-wide `/v1`
+ * rate limit as production traffic, which is why `--interval` exists and a 429
+ * pauses the loop. It used to read `/api/internal/webhook-deliveries` with a session cookie
+ * under the unprefixed NextAuth name, which the https host never reads — a 401
+ * on every poll against www.sendoka.com.
+ */
+export async function listen(flags) {
+    const endpoint = typeof flags.endpoint === "string" ? flags.endpoint : null;
+    const forwardTo = typeof flags["forward-to"] === "string" ? flags["forward-to"] : null;
+    if (!endpoint || !forwardTo)
+        throw new Error(USAGE);
+    // `new URL("localhost:3001")` parses — as scheme `localhost:` — so the
+    // protocol is checked, not just that it parses.
+    let protocol = null;
+    try {
+        protocol = new URL(forwardTo).protocol;
+    }
+    catch {
+        // reported below
+    }
+    if (protocol !== "http:" && protocol !== "https:") {
+        throw new Error(`--forward-to must be an absolute http(s) URL, e.g. http://localhost:3001/hooks (got ${JSON.stringify(forwardTo)})`);
+    }
+    const intervalSeconds = typeof flags.interval === "string" ? Number(flags.interval) : 5;
+    if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+        throw new Error("--interval must be a positive number of seconds");
+    }
+    const secret = typeof flags.secret === "string" ? flags.secret : process.env.SENDOKA_WEBHOOK_SECRET || null;
+    const forwarder = createForwarder({ endpoint, forwardTo, secret });
+    // Outside the loop on purpose: a bad key, a missing scope or an unknown
+    // endpoint is a setup error and exits, rather than printing forever.
+    await forwarder.prime();
+    if (!secret) {
+        console.error("No --secret or SENDOKA_WEBHOOK_SECRET: forwarding UNSIGNED. A handler that verifies signatures will reject these.");
+    }
+    console.log(`Forwarding new deliveries for ${endpoint} → ${forwardTo} every ${intervalSeconds}s. Ctrl+C to stop.`);
+    for (;;) {
+        await new Promise((r) => setTimeout(r, forwarder.delayBeforeNextPoll(intervalSeconds * 1000)));
+        try {
+            await forwarder.poll();
+        }
+        catch (err) {
+            console.error(err.message);
+        }
+    }
+}

package/dist/commands/logs.js

@@ -0,0 +1,157 @@
+import { callV1, isRateLimited } from "../client.js";
+const PAGE_SIZE = 100;
+const MAX_PAGES = 10;
+/**
+ * How far back each poll re-reads behind the newest row it has printed.
+ * `created_at` is stamped at insert, not at commit, so a send that commits a
+ * moment after a later one lands *behind* the watermark; without the overlap
+ * it would never be printed. Duplicates from the overlap are dropped by id.
+ */
+const OVERLAP_MS = 5_000;
+const PATHS = { email: "/emails", sms: "/sms" };
+const USAGE = "Usage: sendoka logs tail [--channel email|sms] [--interval 5]";
+export function formatMessage(row) {
+    const route = `${row.from ?? "?"} → ${row.to ?? "?"}`;
+    const subject = row.channel === "email" && row.subject ? `  ${JSON.stringify(row.subject)}` : "";
+    return `[${row.created_at}] ${row.channel.padEnd(5)} ${row.status.padEnd(10)} ${row.id}  ${route}${subject}`;
+}
+/**
+ * One channel's tail: the list endpoint's `created_after` filter from a
+ * watermark taken off the server's own clock, so client clock skew cannot drop
+ * or replay messages. `prime()` records what already exists and prints
+ * nothing — the tail starts from now.
+ */
+export function createTail(channel, print, warn = (line) => console.error(line)) {
+    const path = PATHS[channel];
+    // id → created_at of every row inside the overlap window, printed or not.
+    const seen = new Map();
+    let watermark = null;
+    function overlapStart(at, factor = 1) {
+        return new Date(new Date(at).getTime() - factor * OVERLAP_MS).toISOString();
+    }
+    /** Every row created at or after `after` (all rows when null), newest first. */
+    async function fetchSince(after) {
+        const rows = [];
+        let cursor = null;
+        for (let pages = 0; pages < MAX_PAGES; pages++) {
+            const qs = new URLSearchParams({ limit: String(PAGE_SIZE) });
+            if (after)
+                qs.set("created_after", after);
+            if (cursor)
+                qs.set("cursor", cursor);
+            const page = await callV1("GET", `${path}?${qs}`);
+            rows.push(...page.data.map((r) => ({ ...r, channel })));
+            if (!page.has_more || !page.next_cursor)
+                return { rows, truncated: false };
+            cursor = page.next_cursor;
+        }
+        return { rows, truncated: true };
+    }
+    /**
+     * The watermark and the seen-set come from ONE read. The first page, with
+     * no filter, fixes the watermark; any further pages follow its keyset
+     * cursor, which only ever returns rows older than that page's last. So a
+     * message created while the tail is starting cannot be marked seen here and
+     * then never printed — it used to be, when a `limit=1` read set the
+     * watermark and a second, later `created_after` read filled the seen-set.
+     */
+    async function prime() {
+        let cursor = null;
+        for (let pages = 0; pages < MAX_PAGES; pages++) {
+            const qs = new URLSearchParams({ limit: String(PAGE_SIZE) });
+            if (cursor)
+                qs.set("cursor", cursor);
+            const page = await callV1("GET", `${path}?${qs}`);
+            if (watermark === null) {
+                const newest = page.data[0];
+                if (!newest)
+                    return;
+                watermark = newest.created_at;
+            }
+            // The first poll re-reads the overlap behind the watermark, so every row
+            // already in it is history too — not only the single newest one.
+            const from = overlapStart(watermark);
+            for (const row of page.data)
+                if (row.created_at >= from)
+                    seen.set(row.id, row.created_at);
+            const last = page.data[page.data.length - 1];
+            if (!last || last.created_at < from || !page.has_more || !page.next_cursor)
+                return;
+            cursor = page.next_cursor;
+        }
+    }
+    async function poll() {
+        const { rows, truncated } = await fetchSince(watermark ? overlapStart(watermark) : null);
+        const fresh = rows.filter((row) => !seen.has(row.id));
+        if (truncated) {
+            warn(`More than ${MAX_PAGES * PAGE_SIZE} new ${channel} messages since the last poll; printing the newest ${fresh.length}.`);
+        }
+        fresh.sort((a, b) => a.created_at === b.created_at ? a.id.localeCompare(b.id) : a.created_at.localeCompare(b.created_at));
+        for (const row of fresh) {
+            seen.set(row.id, row.created_at);
+            if (!watermark || row.created_at > watermark)
+                watermark = row.created_at;
+            print(formatMessage(row));
+        }
+        // Only ids inside the next poll's overlap window can come back.
+        if (watermark) {
+            const keepFrom = overlapStart(watermark, 2);
+            for (const [id, at] of seen)
+                if (at < keepFrom)
+                    seen.delete(id);
+        }
+        return fresh.length;
+    }
+    return { prime, poll };
+}
+/**
+ * `sendoka logs tail` — print each message as it is created.
+ *
+ * Polls `GET /api/v1/emails` and `GET /api/v1/sms` (`read:messages`) with
+ * `created_after`. It used to poll `/api/v1/activity` and print daily
+ * aggregate rows — one line per (date, channel, status), reprinted whenever a
+ * count moved — which answered "how many" but never "what just happened".
+ * Status changes after a message is first printed are not re-printed; that is
+ * what webhooks and `sendoka listen` are for.
+ *
+ * One request per channel per interval (24/min at the defaults), all counted
+ * against the org-wide `/v1` rate limit that production sends also draw on.
+ */
+export async function logsTail(flags) {
+    const intervalSeconds = typeof flags.interval === "string" ? Number(flags.interval) : 5;
+    if (!Number.isFinite(intervalSeconds) || intervalSeconds <= 0) {
+        throw new Error("--interval must be a positive number of seconds");
+    }
+    let channels = ["email", "sms"];
+    if (flags.channel !== undefined) {
+        if (flags.channel !== "email" && flags.channel !== "sms")
+            throw new Error(USAGE);
+        channels = [flags.channel];
+    }
+    if (flags.days !== undefined) {
+        console.error("--days is no longer used: logs tail now prints individual messages as they are created, starting now.");
+    }
+    const tails = channels.map((c) => createTail(c, (line) => console.log(line)));
+    // A bad key or a missing read:messages scope is a setup error: exit on it
+    // rather than printing the same 403 every interval.
+    await Promise.all(tails.map((t) => t.prime()));
+    console.log(`Tailing new ${channels.join(" + ")} messages. Ctrl+C to stop.`);
+    let pauseMs = 0;
+    for (;;) {
+        await new Promise((r) => setTimeout(r, Math.max(intervalSeconds * 1000, pauseMs)));
+        pauseMs = 0;
+        for (const tail of tails) {
+            try {
+                await tail.poll();
+            }
+            catch (err) {
+                console.error(err.message);
+                // Each poll spends the org-wide /v1 budget production sends share; on
+                // a 429, wait out the server's Retry-After rather than the interval.
+                if (isRateLimited(err)) {
+                    pauseMs = Math.max(pauseMs, (err.retryAfterSeconds ?? 30) * 1000);
+                }
+            }
+        }
+    }
+}

package/dist/commands/send.js

@@ -0,0 +1,46 @@
+import { callV1 } from "../client.js";
+function str(flags, key) {
+    const v = flags[key];
+    return typeof v === "string" ? v : undefined;
+}
+export async function sendEmail(flags) {
+    const from = str(flags, "from");
+    const to = str(flags, "to");
+    if (!from || !to)
+        throw new Error("--from and --to are required");
+    const res = await callV1("POST", "/emails", {
+        from,
+        to: to.split(",").map((s) => s.trim()),
+        subject: str(flags, "subject"),
+        html: str(flags, "html"),
+        text: str(flags, "text"),
+        template: str(flags, "template"),
+        variables: parseJson(str(flags, "variables")),
+    });
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+}
+export async function sendSms(flags) {
+    const from = str(flags, "from");
+    const to = str(flags, "to");
+    const body = str(flags, "body");
+    if (!to || !body)
+        throw new Error("--to and --body are required");
+    const res = await callV1("POST", "/sms", {
+        from,
+        to,
+        body,
+        template: str(flags, "template"),
+        variables: parseJson(str(flags, "variables")),
+    });
+    process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+}
+function parseJson(v) {
+    if (!v)
+        return undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        throw new Error(`--variables must be JSON (got ${JSON.stringify(v)})`);
+    }
+}

package/dist/flags.js

@@ -0,0 +1,63 @@
+/**
+ * Argv → flag bag for everything after `<group> <action>`.
+ *
+ * It used to skip anything not starting with `--` outright, which silently
+ * threw away every positional argument. Only one command takes one — and it is
+ * the shape the CLI's own usage text advertises:
+ *
+ *     sendoka events trigger message.bounced --endpoint whk_01HN...
+ *
+ * `message.bounced` was dropped on the floor, `eventsTrigger` found no event
+ * name in the bag, and the command's only outcome was the usage error telling
+ * you to run exactly what you had just run. The documented invocation could
+ * never succeed.
+ *
+ * The first positional now lands under `_`, which is where `eventsTrigger` was
+ * already looking for it. No command takes a second one, so later positionals
+ * are collected under `_1`, `_2`, … rather than overwriting `_` — a mistyped
+ * extra word must not silently change which event is fired.
+ */
+export function parseFlags(args) {
+    const out = {};
+    let positional = 0;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("--")) {
+            out[positional === 0 ? "_" : `_${positional}`] = a;
+            positional++;
+            continue;
+        }
+        const key = a.slice(2);
+        const next = args[i + 1];
+        if (!next || next.startsWith("--")) {
+            out[key] = true;
+        }
+        else {
+            out[key] = next;
+            i++;
+        }
+    }
+    return out;
+}
+/**
+ * Splits everything after the node binary and the script — `<group> [action]
+ * [...args]` — into the three pieces `main` dispatches on.
+ *
+ * The second token counts as an action only when it does not look like a flag.
+ * `sendoka listen --forward-to http://localhost:3001/hooks` used to be read as
+ * group `listen`, action `--forward-to`: `listen` is the one group-only
+ * command (keyed `""` in the table), no `--forward-to` entry exists, so the
+ * CLI printed `Unknown command: listen --forward-to` and exited 2 — while the
+ * URL that followed was swallowed as the action's argument. Bare `sendoka
+ * listen` then failed its own `--forward-to <url> is required` check, so the
+ * command was unusable in every shape the docs advertise.
+ */
+export function splitInvocation(rest) {
+    const [group, ...tail] = rest;
+    const flagFirst = tail.length > 0 && tail[0].startsWith("-");
+    return {
+        group,
+        action: flagFirst ? undefined : tail[0],
+        args: flagFirst ? tail : tail.slice(1),
+    };
+}

package/dist/version.js

@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+/**
+ * Read from package.json rather than restated, the way @sendoka/dev-mcp does:
+ * `--version` printed a hard-coded "0.1.0" that nothing kept in step with the
+ * published version. `../package.json` resolves from both `dist/version.js`
+ * and `src/version.ts`, and npm always ships package.json.
+ */
+export const CLI_VERSION = (() => {
+    try {
+        const require = createRequire(import.meta.url);
+        return require("../package.json").version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@sendoka/cli",
+  "version": "0.2.2",
+  "description": "Sendoka command-line tools for developer workflows.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sendoka": "dist/cli.js"
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fareed010/Sendoka.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}