@sendoka/node 0.2.0

package/README.md

@@ -0,0 +1,119 @@
+# @sendoka/node
+
+Official Node.js / TypeScript SDK for the Sendoka email + SMS API.
+
+Not published to npm yet. From a checkout of the repository, build and pack
+it, then install the tarball in your project:
+
+```bash
+cd packages/sdk-node && npm install && npm run build && npm pack
+npm install /path/to/packages/sdk-node/sendoka-node-0.2.0.tgz
+```
+
+```ts
+import { Sendoka } from "@sendoka/node";
+
+const sendoka = new Sendoka(); // reads SENDOKA_API_KEY
+
+await sendoka.emails.send({
+  from: "you@yourdomain.com",
+  to: ["dev@example.com"],
+  subject: "Hello",
+  html: "<p>Hello</p>",
+});
+```
+
+Node 20+. Zero dependencies — `fetch` and `node:crypto` are all it uses.
+
+## Why this is hand-written
+
+The generated shape of this API is a flat bag of `postV1EmailsBatch` functions. The parts callers actually get wrong are the parts a generator has nothing to say about:
+
+**Retries reuse one idempotency key.** A key minted per attempt is worse than no key at all — every retry looks like a fresh request and delivers a duplicate, which is the exact failure the retry was meant to prevent. One key is minted per logical call and reused across the whole sequence, on every endpoint that honours `Idempotency-Key`: `emails.send`, `emails.sendBatch`, `sms.send`, `sms.sendBatch`, `audiences.send`, `verifications.create`, and `POST /v1/phone-numbers`, `/v1/brands`, `/v1/campaigns` through `client.post`.
+
+**A write without a key is not resent through an ambiguous failure.** A timeout, a dropped connection, a 408 or a 5xx does not say whether the server acted — the first attempt may already have sent the message. The SDK retries through one only when a replay cannot act twice: a GET, or a write on one of the endpoints above. Any other POST, PATCH or DELETE is retried only on a 429, because the rate limiter refuses a request before anything runs. When one of those throws, find out what happened before sending it again.
+
+**409 is not retryable.** It means an idempotency key is in flight, or the body changed under one. Hammering it makes both worse. Only 408, 429 and 5xx are retried, and a server-sent `Retry-After` always wins over the exponential backoff — up to 60 seconds. A longer `Retry-After` is an hourly or daily ceiling, not a rate: the error is thrown straight away with `retryAfter` set, rather than the call blocking for an hour. A 429 that is a quota rather than a rate (`USAGE_LIMIT_EXCEEDED`, `TENANT_QUOTA_EXCEEDED`, `PLAN_RESOURCE_LIMIT`, `WARMUP_LIMIT_EXCEEDED`, `PROVIDER_QUOTA_EXCEEDED`, `SANDBOX_DAILY_LIMIT`, and for test keys `TEST_SCHEDULE_LIMIT_EXCEEDED`) is not retried at all: no backoff moves a monthly or daily ceiling.
+
+**The key comes back on the error.** `err.idempotencyKey` (on `SendokaError` and `SendokaConnectionError`) is the key the request carried, including one the SDK minted. Make the same call again with `{ idempotencyKey: err.idempotencyKey }` and the server replays what the first attempt did instead of doing it twice. For retries that outlive one call — a queue redelivery, a rerun job — derive your own key from something stable about that one call, such as an order id, and pass it every time. Never key a verification by user or destination: a replay answers with the first code's verification, expired or not, and sends nothing.
+
+**Paging stops on the cursor, not just the flag.** `paginate()` returns when either `has_more` is false or `next_cursor` is null. Trusting the flag alone is how hand-rolled paging becomes an infinite loop.
+
+## Errors
+
+```ts
+import { SendokaError, SendokaConnectionError } from "@sendoka/node";
+
+try {
+  await sendoka.emails.send({ ... });
+} catch (err) {
+  if (err instanceof SendokaError) {
+    err.status;    // 422
+    err.code;      // "SUPPRESSED"  ← branch on this
+    err.type;      // "validation_error"
+    err.retryable; // false
+  }
+}
+```
+
+Branch on `code`. `type` is a coarse family and `message` is prose that may be reworded.
+
+## Pagination
+
+```ts
+for await (const message of sendoka.emails.all({ status: "bounced" })) {
+  console.log(message.id);
+}
+```
+
+Every list method has an `all()` streaming variant alongside the single-page `list()`.
+
+## Webhooks
+
+```ts
+import { verifyWebhookSignature } from "@sendoka/node";
+
+// Express — note express.raw, not express.json
+app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
+  const ok = verifyWebhookSignature({
+    payload: req.body.toString("utf8"),
+    signature: req.header("X-Sendoka-Signature-V2")!,
+    timestamp: req.header("X-Sendoka-Timestamp")!,
+    secret: process.env.SENDOKA_WEBHOOK_SECRET!,
+  });
+  if (!ok) return res.status(400).end();
+  res.status(200).end();
+});
+```
+
+**`payload` must be the raw body as received.** `JSON.stringify` of a parsed object is a different string — key order and number formatting both move — and every check will fail in a way that looks like a wrong secret. In Next.js, call `await req.text()` before `req.json()`.
+
+Verifies `X-Sendoka-Signature-V2` (HMAC over `${timestamp}.${body}`), rejects deliveries more than 5 minutes from your clock in **either** direction, and accepts any candidate in a comma-separated list — that list is normal during a secret rotation.
+
+## Verify (OTP)
+
+```ts
+const v = await sendoka.verifications.create({ channel: "sms", to: "+14155550142" });
+const result = await sendoka.verifications.check(v.id, "123456");
+result.status; // "approved" | "denied"
+```
+
+`create` is idempotent: a retry under the same key replays the recorded verification instead of texting the user a second code. Use one key per code request, never one per user: for 24h a replay returns the first verification — even once its code has expired — and sends nothing, so a per-user key turns "resend code" into a silent no-op. Let the SDK mint the key, or pass a fresh one each time the user asks for a code.
+
+A 503 on `check` means the attempt could not be *recorded* — the user's code is still good and must not be shown as wrong. It is **not** retried for you: `check` takes no idempotency key, and a resent check whose first attempt did land would spend a second attempt, or answer `not_found` for the code the first one approved. Ask the user to submit the code again.
+
+## Audience sends
+
+```ts
+const { job_id } = await sendoka.audiences.send(
+  "aud_...",
+  { channel: "email", from: "news@yourdomain.com", template: "weekly" },
+  { idempotencyKey: "weekly-2026-w39" } // one key per blast you mean to send
+);
+```
+
+A retry under the same key replays the recorded `job_id` instead of scheduling the list again. A 10,000-recipient blast can take longer than the default 30s timeout; the SDK's retry then gets `409 IDEMPOTENCY_IN_FLIGHT` while the first request is still scheduling, and throws. The blast is running — call again later with the same key (`err.idempotencyKey`) to get its `job_id`, or give the client that sends blasts a longer `timeout`. `500 AUDIENCE_SEND_INCOMPLETE` means the job exists but scheduling stopped part-way: it is not retryable, because a new key would schedule the list again over the rows that did land. Check `GET /v1/jobs/{job_id}` first.
+
+## Test mode
+
+A `sok_test_*` key exercises every path without contacting a provider or sending anything real. Verifications work fully in test mode, which is what makes an OTP flow testable in CI without a handset.

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+export interface SendokaOptions {
+    /** `sok_live_…` or `sok_test_…`. Defaults to `process.env.SENDOKA_API_KEY`. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Per-request timeout in ms. Default 30s. */
+    timeout?: number;
+    /**
+     * Retries for RETRYABLE failures only (429, 5xx, network). Default 2.
+     *
+     * Only a request that is safe to send twice is retried through an ambiguous
+     * failure (timeout, network error, 408, 5xx): a GET, or a write to an
+     * endpoint that honours `Idempotency-Key`, which gets one minted
+     * automatically. Any other POST / PATCH / DELETE is retried only on a 429 —
+     * a rate-limited request was never processed. A retry without a key is how a
+     * timeout becomes a duplicate message, which is the failure mode this SDK
+     * exists to keep callers out of.
+     */
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Backoff before attempt N, in ms. Defaults to exponential (250ms doubling,
+     * capped at 8s) and always yields to a server-sent `Retry-After`.
+     *
+     * Injectable so a test suite is not forced to sit through real sleeps to
+     * exercise the retry path — a retry policy nobody can test cheaply is one
+     * nobody tests.
+     */
+    retryDelay?: (attempt: number, retryAfterSeconds?: number) => number;
+}
+export interface RequestOptions {
+    /**
+     * Overrides the automatic key. Pass explicitly to make a retry replay — the
+     * SDK's own key lives for one call, so a retry from your code (a queue
+     * redelivery, a rerun job) needs a key derived from something stable.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export declare class SendokaClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly retryDelay;
+    constructor(options?: SendokaOptions);
+    request<T>(method: "GET" | "POST" | "PATCH" | "DELETE", path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    /**
+     * Walk a cursor-paginated collection, yielding one item at a time.
+     *
+     * Every list endpoint uses the same `{ data, has_more, next_cursor }` envelope
+     * with a compound `(created_at, id)` cursor, so this is worth having once
+     * rather than in every caller — and hand-rolled paging is where people
+     * reliably introduce an infinite loop by ignoring `has_more`.
+     */
+    paginate<T>(path: string, query?: Record<string, string | number | boolean | undefined>): AsyncGenerator<T, void, undefined>;
+}

package/dist/client.js

@@ -0,0 +1,200 @@
+import { SendokaError, SendokaConnectionError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://www.sendoka.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+/** Endpoints where the API honours Idempotency-Key. */
+const IDEMPOTENT_PATHS = [
+    "/v1/emails",
+    "/v1/sms",
+    "/v1/emails/batch",
+    "/v1/sms/batch",
+    "/v1/phone-numbers",
+    "/v1/brands",
+    "/v1/campaigns",
+    // A billed OTP send. Retried without a key, a slow provider call answered
+    // after the timeout texted the end user a second code.
+    "/v1/verifications",
+];
+/**
+ * The same, for endpoints with an id in the path. The audience blast is the
+ * one where a blind retry costs the most: it can outlast the 30s timeout by
+ * minutes, and each retry used to schedule the whole list again.
+ */
+const IDEMPOTENT_PATH_PATTERNS = [/^\/v1\/audiences\/[^/?#]+\/send$/];
+function honoursIdempotencyKey(method, path) {
+    return (method === "POST" &&
+        (IDEMPOTENT_PATHS.includes(path) || IDEMPOTENT_PATH_PATTERNS.some((re) => re.test(path))));
+}
+/**
+ * The longest `Retry-After` the SDK will sleep through. The per-minute rate
+ * limiter never asks for more than 60s; anything longer is an hourly or daily
+ * ceiling, and a request call that silently blocks for an hour is a hang, not a
+ * retry. Past this the error goes straight to the caller, `retryAfter` intact.
+ */
+const MAX_RETRY_AFTER_SECONDS = 60;
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Whether the SDK sends a failed attempt again.
+ *
+ * `retryable` on the error says the failure is transient; this also asks
+ * whether sending the request a second time is SAFE. A timeout, a dropped
+ * connection, a 408 or a 5xx does not say whether the server acted: the first
+ * attempt may have sent the message. That is fine to retry only when a replay
+ * cannot act twice — a GET, or a write carrying an Idempotency-Key the endpoint
+ * honours. A 429 is different: the rate limiter refuses before anything runs,
+ * so any request may be retried through one.
+ */
+function shouldRetry(err, replaySafe) {
+    if (!err.retryable)
+        return false;
+    if (err instanceof SendokaError) {
+        if (err.retryAfter !== undefined && err.retryAfter > MAX_RETRY_AFTER_SECONDS)
+            return false;
+        if (err.status === 429)
+            return true;
+    }
+    return replaySafe;
+}
+export class SendokaClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    maxRetries;
+    fetchImpl;
+    retryDelay;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? process.env.SENDOKA_API_KEY;
+        if (!apiKey) {
+            throw new Error("Missing API key. Pass { apiKey } or set SENDOKA_API_KEY.");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? process.env.SENDOKA_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.retryDelay =
+            options.retryDelay ??
+                ((attempt, retryAfterSeconds) => 
+                // Honour Retry-After when the server sent one — it knows when the window
+                // rolls over, and guessing shorter just burns another attempt.
+                retryAfterSeconds !== undefined
+                    ? retryAfterSeconds * 1000
+                    : Math.min(2 ** attempt * 250, 8_000));
+    }
+    async request(method, path, body, options = {}) {
+        const url = `${this.baseUrl}/api${path}`;
+        // One key for the whole retry sequence, minted once outside the loop. A key
+        // per attempt is worse than none: each retry looks like a fresh request and
+        // sends a duplicate, which is exactly what the retry was supposed to avoid.
+        const honoured = honoursIdempotencyKey(method, path);
+        const idempotencyKey = honoured
+            ? options.idempotencyKey ?? crypto.randomUUID()
+            : options.idempotencyKey;
+        // A key on an endpoint that ignores it protects nothing, so it does not
+        // make that request safe to send twice.
+        const replaySafe = method === "GET" || honoured;
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (attempt > 0) {
+                const retryAfter = lastError instanceof SendokaError ? lastError.retryAfter : undefined;
+                const backoff = this.retryDelay(attempt, retryAfter);
+                if (backoff > 0)
+                    await sleep(backoff);
+            }
+            const timer = new AbortController();
+            const timeoutId = setTimeout(() => timer.abort(), this.timeout);
+            // Caller cancellation and our timeout both have to reach the same fetch.
+            const onAbort = () => timer.abort();
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                const res = await this.fetchImpl(url, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        "User-Agent": "sendoka-node/0.2.0",
+                        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: timer.signal,
+                });
+                if (res.ok) {
+                    if (res.status === 204)
+                        return undefined;
+                    return (await res.json());
+                }
+                const payload = (await res.json().catch(() => ({})));
+                const retryAfterHeader = res.headers.get("retry-after");
+                lastError = new SendokaError({
+                    status: res.status,
+                    type: payload.error?.type ?? "api_error",
+                    code: payload.error?.code ?? `HTTP_${res.status}`,
+                    message: payload.error?.message ?? `Request failed with ${res.status}`,
+                    retryAfter: retryAfterHeader ? Number(retryAfterHeader) : undefined,
+                    requestId: res.headers.get("x-request-id") ?? undefined,
+                    idempotencyKey,
+                });
+                if (!shouldRetry(lastError, replaySafe) || attempt === this.maxRetries)
+                    throw lastError;
+            }
+            catch (err) {
+                if (err instanceof SendokaError) {
+                    if (!shouldRetry(err, replaySafe) || attempt === this.maxRetries)
+                        throw err;
+                    lastError = err;
+                    continue;
+                }
+                // A caller-initiated abort is not a failure to retry through.
+                if (options.signal?.aborted)
+                    throw err;
+                lastError = new SendokaConnectionError(err instanceof Error ? err.message : "Network request failed", err, idempotencyKey);
+                if (!shouldRetry(lastError, replaySafe) || attempt === this.maxRetries)
+                    throw lastError;
+            }
+            finally {
+                clearTimeout(timeoutId);
+                options.signal?.removeEventListener("abort", onAbort);
+            }
+        }
+        throw lastError ?? new SendokaConnectionError("Request failed");
+    }
+    get(path, query) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined)
+                params.set(k, String(v));
+        }
+        const qs = params.size > 0 ? `?${params.toString()}` : "";
+        return this.request("GET", `${path}${qs}`);
+    }
+    post(path, body, options) {
+        return this.request("POST", path, body, options);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    delete(path) {
+        return this.request("DELETE", path);
+    }
+    /**
+     * Walk a cursor-paginated collection, yielding one item at a time.
+     *
+     * Every list endpoint uses the same `{ data, has_more, next_cursor }` envelope
+     * with a compound `(created_at, id)` cursor, so this is worth having once
+     * rather than in every caller — and hand-rolled paging is where people
+     * reliably introduce an infinite loop by ignoring `has_more`.
+     */
+    async *paginate(path, query = {}) {
+        let cursor;
+        for (;;) {
+            const page = await this.get(path, { ...query, cursor });
+            for (const item of page.data)
+                yield item;
+            if (!page.has_more || !page.next_cursor)
+                return;
+            cursor = page.next_cursor;
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+export declare class SendokaError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly type: string;
+    /** Present on 429s when the server sent Retry-After. Seconds. */
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+    /**
+     * The Idempotency-Key the request carried, including one the SDK minted.
+     * Make the same call again with `{ idempotencyKey }` set to this and the
+     * server replays the first attempt's answer instead of acting twice — the
+     * way to learn the outcome of a send whose response never arrived.
+     */
+    readonly idempotencyKey?: string;
+    constructor(args: {
+        status: number;
+        code: string;
+        type: string;
+        message: string;
+        retryAfter?: number;
+        requestId?: string;
+        idempotencyKey?: string;
+    });
+    /**
+     * Whether retrying the identical request could plausibly succeed.
+     *
+     * Not whether it is SAFE to: a 5xx on a write does not say the server did
+     * nothing. The SDK only retries one through a key the endpoint honours; on
+     * any other write, find out what happened before sending it again.
+     *
+     * 409 is deliberately NOT retryable: it means an idempotency key is in flight
+     * or the body changed under one, and hammering it makes both worse.
+     *
+     * Neither is a 429 that is a QUOTA rather than a RATE. Sendoka answers a
+     * monthly plan limit and a tenant monthly cap with 429 (see
+     * `enforceUsageLimit`), and no amount of backoff moves the calendar — so
+     * retrying burned two extra attempts, and the delay before the caller saw
+     * the real reason, on a failure that cannot succeed until next month or
+     * until someone raises the cap.
+     */
+    get retryable(): boolean;
+}
+/**
+ * Thrown when the network failed or the request timed out — no HTTP response.
+ * The server may still have processed the request; see `idempotencyKey`.
+ */
+export declare class SendokaConnectionError extends Error {
+    readonly cause?: unknown;
+    /** As on SendokaError: replay with this key to learn what the server did. */
+    readonly idempotencyKey?: string;
+    constructor(message: string, cause?: unknown, idempotencyKey?: string);
+    get retryable(): boolean;
+}

package/dist/errors.js

@@ -0,0 +1,102 @@
+/**
+ * The API's error envelope, as a typed exception.
+ *
+ * Every non-2xx carries `{ error: { type, code, message } }`, and the `code` is
+ * the part worth branching on — `type` is a coarse family and `message` is prose
+ * that may be reworded. Surfacing all three keeps a caller from having to parse
+ * strings to find out whether a send was refused for a suppression or a quota.
+ */
+/**
+ * Error codes that arrive with a retryable STATUS but are not retryable in
+ * fact. The first three are monthly counters answered with 429. The next three
+ * are daily ceilings answered with 429 and no Retry-After — a domain's warmup
+ * day cap, the provider account's 24h send quota, and the org sandbox sender's
+ * 100 recipients a UTC day — so backoff measured in seconds only repeats the
+ * work that led to the refusal (on an audience send, re-reading up to 10k
+ * contacts) and delays the real reason. TEST_SCHEDULE_LIMIT_EXCEEDED is the
+ * same shape for test keys: a cap on test messages waiting to send, freed as
+ * they send over minutes, not seconds. TEST_VOLUME_LIMIT_EXCEEDED is test
+ * mode's daily allowance of messages, which comes back at 00:00 UTC.
+ *
+ * AUDIENCE_SEND_INCOMPLETE is a 500 recorded under the request's
+ * Idempotency-Key: the blast's job exists and some of its messages may be
+ * scheduled. Retrying under the same key only replays it, and retrying under a
+ * new one schedules the list a second time over the rows that did land — what
+ * to do next is the caller's call, after looking at the job.
+ */
+const NON_RETRYABLE_CODES = new Set([
+    "USAGE_LIMIT_EXCEEDED",
+    "TENANT_QUOTA_EXCEEDED",
+    "PLAN_RESOURCE_LIMIT",
+    "WARMUP_LIMIT_EXCEEDED",
+    "PROVIDER_QUOTA_EXCEEDED",
+    "SANDBOX_DAILY_LIMIT",
+    "TEST_SCHEDULE_LIMIT_EXCEEDED",
+    "TEST_VOLUME_LIMIT_EXCEEDED",
+    "AUDIENCE_SEND_INCOMPLETE",
+]);
+export class SendokaError extends Error {
+    status;
+    code;
+    type;
+    /** Present on 429s when the server sent Retry-After. Seconds. */
+    retryAfter;
+    requestId;
+    /**
+     * The Idempotency-Key the request carried, including one the SDK minted.
+     * Make the same call again with `{ idempotencyKey }` set to this and the
+     * server replays the first attempt's answer instead of acting twice — the
+     * way to learn the outcome of a send whose response never arrived.
+     */
+    idempotencyKey;
+    constructor(args) {
+        super(args.message);
+        this.name = "SendokaError";
+        this.status = args.status;
+        this.code = args.code;
+        this.type = args.type;
+        this.retryAfter = args.retryAfter;
+        this.requestId = args.requestId;
+        this.idempotencyKey = args.idempotencyKey;
+    }
+    /**
+     * Whether retrying the identical request could plausibly succeed.
+     *
+     * Not whether it is SAFE to: a 5xx on a write does not say the server did
+     * nothing. The SDK only retries one through a key the endpoint honours; on
+     * any other write, find out what happened before sending it again.
+     *
+     * 409 is deliberately NOT retryable: it means an idempotency key is in flight
+     * or the body changed under one, and hammering it makes both worse.
+     *
+     * Neither is a 429 that is a QUOTA rather than a RATE. Sendoka answers a
+     * monthly plan limit and a tenant monthly cap with 429 (see
+     * `enforceUsageLimit`), and no amount of backoff moves the calendar — so
+     * retrying burned two extra attempts, and the delay before the caller saw
+     * the real reason, on a failure that cannot succeed until next month or
+     * until someone raises the cap.
+     */
+    get retryable() {
+        if (NON_RETRYABLE_CODES.has(this.code ?? ""))
+            return false;
+        return this.status === 408 || this.status === 429 || this.status >= 500;
+    }
+}
+/**
+ * Thrown when the network failed or the request timed out — no HTTP response.
+ * The server may still have processed the request; see `idempotencyKey`.
+ */
+export class SendokaConnectionError extends Error {
+    cause;
+    /** As on SendokaError: replay with this key to learn what the server did. */
+    idempotencyKey;
+    constructor(message, cause, idempotencyKey) {
+        super(message);
+        this.name = "SendokaConnectionError";
+        this.cause = cause;
+        this.idempotencyKey = idempotencyKey;
+    }
+    get retryable() {
+        return true;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { SendokaClient, type SendokaOptions, type RequestOptions } from "./client.js";
+import { SendokaError, SendokaConnectionError } from "./errors.js";
+import { verifyWebhookSignature } from "./webhooks.js";
+import type { SendEmailParams, SendSmsParams, BatchResult, MessageRef, Audience, AudienceSendParams, AudienceSendResult, Contact, Verification, VerificationCheck, InboundMessage, Page } from "./types.js";
+export * from "./types.js";
+export { SendokaError, SendokaConnectionError, verifyWebhookSignature };
+export type { SendokaOptions, RequestOptions };
+/**
+ * The Sendoka client.
+ *
+ * Hand-written rather than generated. The generated shape of this API is a flat
+ * bag of `postV1EmailsBatch`-style functions, and the parts a caller actually
+ * gets wrong — retry without an idempotency key, paging that ignores
+ * `has_more`, treating a 409 as retryable — are exactly the parts a generator
+ * has nothing to say about.
+ *
+ * ```ts
+ * const sendoka = new Sendoka({ apiKey: process.env.SENDOKA_API_KEY });
+ * await sendoka.emails.send({ from: "you@yours.com", to: ["a@b.com"], subject: "Hi", html: "<p>Hi</p>" });
+ * ```
+ */
+export declare class Sendoka {
+    readonly client: SendokaClient;
+    constructor(options?: SendokaOptions);
+    readonly emails: {
+        send: (params: SendEmailParams, options?: RequestOptions) => Promise<MessageRef>;
+        /**
+         * Up to 100 per call. Idempotent: a replay returns the recorded per-item
+         * outcome array verbatim rather than re-attempting, so items that failed the
+         * first time stay failed. Retry just those as a new batch.
+         */
+        sendBatch: (params: SendEmailParams[], options?: RequestOptions) => Promise<BatchResult>;
+        get: (id: string) => Promise<MessageRef>;
+        /** Only a `scheduled` message can be canceled — one already sent cannot. */
+        cancel: (id: string) => Promise<{
+            id: string;
+            status: string;
+        }>;
+        list: (query?: Record<string, string | number | undefined>) => Promise<Page<MessageRef>>;
+        all: (query?: Record<string, string | number | undefined>) => AsyncGenerator<MessageRef, void, undefined>;
+    };
+    readonly sms: {
+        send: (params: SendSmsParams, options?: RequestOptions) => Promise<MessageRef>;
+        sendBatch: (params: SendSmsParams[], options?: RequestOptions) => Promise<BatchResult>;
+        get: (id: string) => Promise<MessageRef>;
+        cancel: (id: string) => Promise<{
+            id: string;
+            status: string;
+        }>;
+        list: (query?: Record<string, string | number | undefined>) => Promise<Page<MessageRef>>;
+        all: (query?: Record<string, string | number | undefined>) => AsyncGenerator<MessageRef, void, undefined>;
+    };
+    readonly audiences: {
+        list: () => Promise<Page<Audience>>;
+        all: () => AsyncGenerator<Audience, void, undefined>;
+        create: (params: {
+            slug: string;
+            name: string;
+        }) => Promise<{
+            id: string;
+            slug: string;
+        }>;
+        get: (id: string) => Promise<Audience>;
+        update: (id: string, params: {
+            name?: string;
+            slug?: string;
+        }) => Promise<Audience>;
+        remove: (id: string) => Promise<{
+            id: string;
+            deleted: true;
+        }>;
+        contacts: (id: string, query?: {
+            subscribed?: boolean;
+        }) => AsyncGenerator<Contact, void, undefined>;
+        /**
+         * Upserts by email or phone, so re-running a sync matches rather than
+         * duplicates. Does NOT re-subscribe anyone who opted out of this list.
+         */
+        addContacts: (id: string, contacts: Partial<Contact>[]) => Promise<{
+            audience_id: string;
+            submitted: number;
+            contacts_created: number;
+            contacts_matched: number;
+        }>;
+        /**
+         * Idempotent: a retry under the same key replays the recorded `job_id`
+         * instead of scheduling the list again. A 10k-recipient blast can take
+         * longer than the default 30s timeout — the retry then gets 409
+         * IDEMPOTENCY_IN_FLIGHT while the first is still scheduling. Call again
+         * later with `{ idempotencyKey: err.idempotencyKey }` to get the job id.
+         */
+        send: (id: string, params: AudienceSendParams, options?: RequestOptions) => Promise<AudienceSendResult>;
+    };
+    readonly verifications: {
+        /**
+         * Start an OTP challenge. The destination is never echoed back.
+         *
+         * Idempotent: a retry under the same key replays the recorded verification
+         * rather than texting the user a second code. Use one key per code request,
+         * never one per user or destination: for 24h a replay returns the first
+         * verification, even after its code has expired, and sends nothing.
+         */
+        create: (params: {
+            channel: "sms" | "email";
+            to: string;
+            template?: string;
+            code_length?: number;
+            ttl_seconds?: number;
+            max_attempts?: number;
+            from?: string;
+            subject?: string;
+        }, options?: RequestOptions) => Promise<Verification>;
+        /**
+         * A 503 here means the attempt could not be RECORDED — the user's code is
+         * still good and must not be shown as wrong. It is NOT retried for you: a
+         * check takes no Idempotency-Key, and a resent check whose first attempt
+         * did land would spend a second attempt, or answer `not_found` for the
+         * code the first one approved. Ask the user to submit the code again.
+         */
+        check: (id: string, code: string) => Promise<VerificationCheck>;
+    };
+    readonly inbound: {
+        list: (query?: {
+            channel?: "email" | "sms";
+            to?: string;
+            from?: string;
+            q?: string;
+        }) => Promise<Page<InboundMessage>>;
+        all: (query?: {
+            channel?: "email" | "sms";
+        }) => AsyncGenerator<InboundMessage, void, undefined>;
+        get: (id: string) => Promise<InboundMessage>;
+    };
+    readonly suppressions: {
+        list: (query?: {
+            channel?: "email" | "sms";
+        }) => Promise<Page<unknown>>;
+        add: (params: {
+            channel: "email" | "sms";
+            value: string;
+            reason?: "manual" | "unsubscribe" | "bounce" | "complaint" | "stop";
+            /** Omit and it follows `reason`: unsubscribe blocks broadcasts only. */
+            stream?: "all" | "broadcast";
+        }) => Promise<{
+            ok: true;
+        }>;
+        remove: (channel: "email" | "sms", value: string) => Promise<{
+            ok: true;
+        }>;
+    };
+    readonly analytics: {
+        /** group_by: 1–3 of day, channel, status, domain, tag. */
+        get: (query?: {
+            group_by?: string;
+            days?: number;
+            channel?: "email" | "sms";
+        }) => Promise<{
+            group_by: string[];
+            days: number;
+            data: Record<string, unknown>[];
+        }>;
+    };
+    readonly jobs: {
+        get: (id: string) => Promise<Record<string, unknown>>;
+        cancel: (id: string) => Promise<Record<string, unknown>>;
+    };
+}
+export default Sendoka;

package/dist/index.js

@@ -0,0 +1,107 @@
+import { SendokaClient } from "./client.js";
+import { SendokaError, SendokaConnectionError } from "./errors.js";
+import { verifyWebhookSignature } from "./webhooks.js";
+export * from "./types.js";
+export { SendokaError, SendokaConnectionError, verifyWebhookSignature };
+/**
+ * The Sendoka client.
+ *
+ * Hand-written rather than generated. The generated shape of this API is a flat
+ * bag of `postV1EmailsBatch`-style functions, and the parts a caller actually
+ * gets wrong — retry without an idempotency key, paging that ignores
+ * `has_more`, treating a 409 as retryable — are exactly the parts a generator
+ * has nothing to say about.
+ *
+ * ```ts
+ * const sendoka = new Sendoka({ apiKey: process.env.SENDOKA_API_KEY });
+ * await sendoka.emails.send({ from: "you@yours.com", to: ["a@b.com"], subject: "Hi", html: "<p>Hi</p>" });
+ * ```
+ */
+export class Sendoka {
+    client;
+    constructor(options = {}) {
+        this.client = new SendokaClient(options);
+    }
+    emails = {
+        send: (params, options) => this.client.post("/v1/emails", params, options),
+        /**
+         * Up to 100 per call. Idempotent: a replay returns the recorded per-item
+         * outcome array verbatim rather than re-attempting, so items that failed the
+         * first time stay failed. Retry just those as a new batch.
+         */
+        sendBatch: (params, options) => this.client.post("/v1/emails/batch", params, options),
+        get: (id) => this.client.get(`/v1/emails/${id}`),
+        /** Only a `scheduled` message can be canceled — one already sent cannot. */
+        cancel: (id) => this.client.delete(`/v1/emails/${id}`),
+        list: (query) => this.client.get("/v1/emails", query),
+        all: (query) => this.client.paginate("/v1/emails", query),
+    };
+    sms = {
+        send: (params, options) => this.client.post("/v1/sms", params, options),
+        sendBatch: (params, options) => this.client.post("/v1/sms/batch", params, options),
+        get: (id) => this.client.get(`/v1/sms/${id}`),
+        cancel: (id) => this.client.delete(`/v1/sms/${id}`),
+        list: (query) => this.client.get("/v1/sms", query),
+        all: (query) => this.client.paginate("/v1/sms", query),
+    };
+    audiences = {
+        list: () => this.client.get("/v1/audiences"),
+        all: () => this.client.paginate("/v1/audiences"),
+        create: (params) => this.client.post("/v1/audiences", params),
+        get: (id) => this.client.get(`/v1/audiences/${id}`),
+        update: (id, params) => this.client.patch(`/v1/audiences/${id}`, params),
+        remove: (id) => this.client.delete(`/v1/audiences/${id}`),
+        contacts: (id, query) => this.client.paginate(`/v1/audiences/${id}/contacts`, query),
+        /**
+         * Upserts by email or phone, so re-running a sync matches rather than
+         * duplicates. Does NOT re-subscribe anyone who opted out of this list.
+         */
+        addContacts: (id, contacts) => this.client.post(`/v1/audiences/${id}/contacts`, { contacts }),
+        /**
+         * Idempotent: a retry under the same key replays the recorded `job_id`
+         * instead of scheduling the list again. A 10k-recipient blast can take
+         * longer than the default 30s timeout — the retry then gets 409
+         * IDEMPOTENCY_IN_FLIGHT while the first is still scheduling. Call again
+         * later with `{ idempotencyKey: err.idempotencyKey }` to get the job id.
+         */
+        send: (id, params, options) => this.client.post(`/v1/audiences/${id}/send`, params, options),
+    };
+    verifications = {
+        /**
+         * Start an OTP challenge. The destination is never echoed back.
+         *
+         * Idempotent: a retry under the same key replays the recorded verification
+         * rather than texting the user a second code. Use one key per code request,
+         * never one per user or destination: for 24h a replay returns the first
+         * verification, even after its code has expired, and sends nothing.
+         */
+        create: (params, options) => this.client.post("/v1/verifications", params, options),
+        /**
+         * A 503 here means the attempt could not be RECORDED — the user's code is
+         * still good and must not be shown as wrong. It is NOT retried for you: a
+         * check takes no Idempotency-Key, and a resent check whose first attempt
+         * did land would spend a second attempt, or answer `not_found` for the
+         * code the first one approved. Ask the user to submit the code again.
+         */
+        check: (id, code) => this.client.post(`/v1/verifications/${id}/check`, { code }),
+    };
+    inbound = {
+        list: (query) => this.client.get("/v1/inbound", query),
+        all: (query) => this.client.paginate("/v1/inbound", query),
+        get: (id) => this.client.get(`/v1/inbound/${id}`),
+    };
+    suppressions = {
+        list: (query) => this.client.get("/v1/suppressions", query),
+        add: (params) => this.client.post("/v1/suppressions", params),
+        remove: (channel, value) => this.client.delete(`/v1/suppressions?channel=${channel}&value=${encodeURIComponent(value)}`),
+    };
+    analytics = {
+        /** group_by: 1–3 of day, channel, status, domain, tag. */
+        get: (query) => this.client.get("/v1/analytics", query),
+    };
+    jobs = {
+        get: (id) => this.client.get(`/v1/jobs/${id}`),
+        cancel: (id) => this.client.delete(`/v1/jobs/${id}`),
+    };
+}
+export default Sendoka;

package/dist/types.d.ts

@@ -0,0 +1,184 @@
+/** Every list endpoint returns this envelope with a compound (created_at, id) cursor. */
+export interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+/**
+ * A value for a template `{{placeholder}}`: any JSON. Arrays feed
+ * `{{#each items}}`, objects feed dotted paths like `{{order.shipping.city}}`.
+ * The API caps nesting at 10 levels below a top-level key and the whole map at
+ * 64 KB of serialized JSON (422 VALIDATION_ERROR past either).
+ */
+export type TemplateValue = string | number | boolean | null | TemplateValue[] | {
+    [key: string]: TemplateValue;
+};
+/**
+ * The `variables` map: `TemplateValue`s by name. Typed as `unknown` values on
+ * purpose, so an interface-typed object or a `Date` (which serializes to an ISO
+ * string) can be passed without a cast; the API validates the JSON it receives.
+ */
+export type TemplateVariables = Record<string, unknown>;
+export interface SendEmailParams {
+    from: string;
+    to: string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string[];
+    headers?: Record<string, string>;
+    tags?: string[];
+    metadata?: Record<string, string>;
+    attachments?: {
+        filename: string;
+        content?: string;
+        url?: string;
+        content_type?: string;
+    }[];
+    /** ISO 8601. Pair with `scheduled_at_tz` to schedule in a local zone. */
+    scheduled_at?: string;
+    scheduled_local?: string;
+    scheduled_at_tz?: string;
+    template?: string;
+    variables?: TemplateVariables;
+    track_opens?: boolean;
+    track_clicks?: boolean;
+}
+export interface SendSmsParams {
+    from?: string;
+    to: string;
+    body: string;
+    /** MMS attachments as S3 URIs (`s3://bucket/key`). https links are rejected. */
+    media_url?: string[];
+    tags?: string[];
+    metadata?: Record<string, string>;
+    scheduled_at?: string;
+    scheduled_local?: string;
+    scheduled_at_tz?: string;
+    template?: string;
+    variables?: TemplateVariables;
+    /** Required for +91 under DLT enforcement. */
+    dlt_template_id?: string;
+    from_pool?: string;
+}
+/**
+ * Body of `audiences.send`. Each recipient's contact fields are available as
+ * `{{contact.name}}` / `{{contact.first_name}}` / `{{contact.email}}` /
+ * `{{contact.phone}}` / `{{contact.id}}` (and flat `{{name}}`, `{{first_name}}`,
+ * `{{email}}`, `{{phone}}`). Precedence, lowest first: contact fields, then
+ * `variables`, then the contact's own metadata.
+ */
+export interface AudienceSendParams {
+    channel: "email" | "sms";
+    from: string;
+    template: string;
+    variables?: TemplateVariables;
+    scheduled_at?: string;
+    scheduled_local?: string;
+    scheduled_at_tz?: string;
+    /** 0–1440. Spread the blast evenly over this many minutes. */
+    ramp_minutes?: number;
+    /** Email only, 2–5 subject lines for an A/B test. */
+    subject_variants?: string[];
+    /** Required for SMS blasts that reach +91 under DLT enforcement. */
+    dlt_template_id?: string;
+    /** Email only. Both default to true for blasts. */
+    track_opens?: boolean;
+    track_clicks?: boolean;
+}
+/** What `audiences.send` answers once the blast's rows are scheduled. */
+export interface AudienceSendResult {
+    /** Poll with `GET /v1/jobs/{id}`, stop with `DELETE /v1/jobs/{id}`. */
+    job_id: string;
+    audience_id: string;
+    /** Members still subscribed to the audience. */
+    total: number;
+    /** Messages created, one per sendable recipient. */
+    scheduled: number;
+    /** `total - scheduled`: suppressed, or no address on the blast's channel. */
+    suppressed: number;
+    /** SMS only (0 for email): rows moved out of the destination's quiet hours. Counted inside `scheduled`. */
+    deferred_quiet_hours: number;
+    starts_at: string;
+    /** When the last row fires. */
+    ends_at: string;
+}
+export interface MessageRef {
+    id: string;
+    status: "queued" | "scheduled" | "sending" | "sent" | "delivered" | "bounced" | "failed" | "canceled";
+    created_at?: string;
+    /** Present when some recipients were dropped by the suppression list. */
+    suppressed_recipients?: string[];
+}
+export interface BatchResult {
+    data: {
+        id?: string;
+        status?: string;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }[];
+    total: number;
+    succeeded: number;
+    failed: number;
+}
+export interface Audience {
+    id: string;
+    slug: string;
+    name: string;
+    tenant_id: string | null;
+    /** Only on the single-audience read. */
+    contact_count?: number;
+    /** What a blast would actually reach. The gap from contact_count is churn. */
+    subscribed_count?: number;
+    created_at: string;
+}
+export interface Contact {
+    id: string;
+    email: string | null;
+    phone: string | null;
+    name: string | null;
+    metadata: Record<string, string> | null;
+    /** Per-list. A contact can be subscribed to one audience and not another. */
+    subscribed?: boolean;
+    unsubscribed_at?: string | null;
+    unsubscribe_source?: string | null;
+    created_at: string;
+}
+export interface Verification {
+    id: string;
+    status: "pending";
+    channel: "sms" | "email";
+    expires_at: string;
+}
+export interface VerificationCheck {
+    id: string;
+    status: "approved" | "denied";
+    reason?: "invalid" | "expired" | "not_found" | "max_attempts";
+}
+export interface InboundMessage {
+    id: string;
+    channel: "email" | "sms";
+    tenant_id: string | null;
+    from: string;
+    to: string;
+    subject?: string | null;
+    /** List responses only — the detail route returns the full body instead. */
+    preview?: string | null;
+    text?: string | null;
+    html?: string | null;
+    headers?: Record<string, unknown> | null;
+    attachments?: unknown;
+    conversation_id?: string | null;
+    created_at: string;
+}
+/** Every event name the platform can deliver. */
+export type WebhookEvent = "message.sent" | "message.delivered" | "message.bounced" | "message.failed" | "message.complained" | "message.opened" | "message.clicked" | "message.unsubscribed" | "domain.verified" | "domain.unverified" | "domain.removed" | "domain.warmup_started" | "brand.verified" | "brand.unverified" | "brand.removed" | "campaign.verified" | "campaign.unverified" | "campaign.removed" | "phone_number.verified" | "phone_number.unverified" | "phone_number.released" | "inbound.sms" | "inbound.email" | "dlt.template_approved" | "dlt.template_rejected" | "job.started" | "job.completed" | "job.canceled";
+export interface WebhookPayload<T = Record<string, unknown>> {
+    event: WebhookEvent;
+    data: T;
+    timestamp: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,28 @@
+export interface VerifyWebhookOptions {
+    /** The RAW request body. Not a re-serialized object — see below. */
+    payload: string;
+    /** `X-Sendoka-Signature-V2`. May be a comma-separated list during rotation. */
+    signature: string;
+    /** `X-Sendoka-Timestamp`. */
+    timestamp: string;
+    secret: string;
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a webhook delivery.
+ *
+ * **`payload` must be the raw body bytes as received.** `JSON.stringify` of a
+ * parsed object is not the same string — key order and number formatting both
+ * move — and every signature check will fail in a way that looks like a wrong
+ * secret. In Express, that means `express.raw({ type: 'application/json' })`;
+ * in a Next.js route handler, `await req.text()` BEFORE `req.json()`.
+ *
+ * Verifies `X-Sendoka-Signature-V2` (HMAC over `${timestamp}.${body}`) rather
+ * than the legacy `X-Sendoka-Signature` (HMAC over the body alone): without the
+ * timestamp in the signed material, a captured delivery replays forever.
+ *
+ * A comma-separated signature list is normal during a secret rotation — the
+ * sender signs with both the new and previous secret so a receiver mid-deploy
+ * still verifies one of them. Any match counts.
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookOptions): boolean;

package/dist/webhooks.js

@@ -0,0 +1,49 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Default replay tolerance. Five minutes is wide enough for ordinary clock skew
+ * between two machines and narrow enough that a captured delivery is not
+ * replayable an hour later.
+ */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify a webhook delivery.
+ *
+ * **`payload` must be the raw body bytes as received.** `JSON.stringify` of a
+ * parsed object is not the same string — key order and number formatting both
+ * move — and every signature check will fail in a way that looks like a wrong
+ * secret. In Express, that means `express.raw({ type: 'application/json' })`;
+ * in a Next.js route handler, `await req.text()` BEFORE `req.json()`.
+ *
+ * Verifies `X-Sendoka-Signature-V2` (HMAC over `${timestamp}.${body}`) rather
+ * than the legacy `X-Sendoka-Signature` (HMAC over the body alone): without the
+ * timestamp in the signed material, a captured delivery replays forever.
+ *
+ * A comma-separated signature list is normal during a secret rotation — the
+ * sender signs with both the new and previous secret so a receiver mid-deploy
+ * still verifies one of them. Any match counts.
+ */
+export function verifyWebhookSignature(options) {
+    const { payload, signature, timestamp, secret } = options;
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const ts = Number(timestamp);
+    if (!Number.isFinite(ts))
+        return false;
+    // Both directions. A delivery timestamped in the future is as suspect as one
+    // timestamped in the past — a one-sided check is defeated by a clock the
+    // attacker controls.
+    const skew = Math.abs(Date.now() / 1000 - ts);
+    if (skew > tolerance)
+        return false;
+    const expected = createHmac("sha256", secret).update(`${timestamp}.${payload}`).digest("hex");
+    const expectedBuf = Buffer.from(expected);
+    // Any of the comma-separated candidates may match. Compared with
+    // timingSafeEqual, and length-checked first because timingSafeEqual throws on
+    // a length mismatch rather than returning false.
+    return signature
+        .split(",")
+        .map((s) => s.trim())
+        .some((candidate) => {
+        const candidateBuf = Buffer.from(candidate);
+        return (candidateBuf.length === expectedBuf.length && timingSafeEqual(candidateBuf, expectedBuf));
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sendoka/node",
+  "version": "0.2.0",
+  "description": "Official Node.js / TypeScript SDK for the Sendoka email + SMS API.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.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/sdk-node"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": ["sendoka", "email", "sms", "otp", "api"]
+}