@whatsapi.sh/sdk 0.1.0

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@whatsapi.sh/sdk",
+    "version": "0.1.0",
+    "description": "Official TypeScript client for whatsapi.sh — send WhatsApp messages, OTPs and media over a flat REST API.",
+    "license": "MIT",
+    "homepage": "https://whatsapi.sh",
+    "keywords": [
+        "whatsapp",
+        "whatsapp-api",
+        "messaging",
+        "otp",
+        "webhooks",
+        "sdk"
+    ],
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "!src/__tests__"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "prepack": "bun run build",
+        "release": "bun run typecheck && bun run test && bun publish",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint .",
+        "test": "vitest --run"
+    },
+    "devDependencies": {
+        "@types/node": "^24.12.0",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.2"
+    }
+}

package/src/client.ts

@@ -0,0 +1,204 @@
+// The transport under every generated method: one request, one `{ data }`
+// unwrap, one error taxonomy.
+//
+// The retry policy is the opinionated part, and it is deliberately narrow:
+// READS retry, WRITES never do. There is no idempotency key on /v1, so a
+// retried send is a second WhatsApp message to a real person and a second unit
+// off the quota — worse than the failure it was papering over. Writes come back
+// as a WhatsapiError carrying `code` and `retryAfter`, and the caller decides.
+import { WhatsapiError, type ClientErrorCode } from "./errors.ts";
+import type { ErrorCode } from "./generated/contract.ts";
+import { DEFAULT_BASE_URL, GeneratedOperations, SDK_VERSION } from "./generated/operations.ts";
+
+export interface WhatsapiOptions {
+    /** A `wa_` key from the dashboard. */
+    apiKey: string;
+    /** Defaults to the hosted API; point it at a self-hosted deployment if you run one. */
+    baseUrl?: string;
+    /** Per-attempt timeout in ms. Default 30000. */
+    timeout?: number;
+    /** Extra attempts for READ calls only. Default 2, 0 disables. */
+    maxRetries?: number;
+    /** Swap the fetch implementation (tests, proxies, a custom agent). */
+    fetch?: typeof globalThis.fetch;
+}
+
+/** What a generated method hands the transport. */
+export interface RequestSpec {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Template with `:name` placeholders naming the params that fill them. */
+    path: string;
+    pathParams?: readonly string[];
+    /** Values the ROUTE fixes rather than the caller. */
+    fixed?: Readonly<Record<string, unknown>>;
+}
+
+type Params = Record<string, unknown>;
+
+/** A Retry-After we would honor beyond this is not a retry, it is a hang — the
+ *  caller gets the error (with `retryAfter` on it) and schedules it themselves. */
+const MAX_RETRY_DELAY_MS = 10_000;
+
+/** How the API answers when it never got to answer at all. */
+function statusCode(status: number): ErrorCode {
+    if (status === 503) return "SERVICE_UNAVAILABLE";
+    if (status === 404) return "NOT_FOUND";
+    if (status === 401) return "UNAUTHORIZED";
+    return "INTERNAL_ERROR";
+}
+
+/** Seconds from `Retry-After` (delta form) or the error's own details. */
+function retryAfterOf(header: string | null, details: unknown): number | undefined {
+    const fromDetails =
+        typeof details === "object" && details !== null
+            ? (details as { retryAfterSecs?: unknown }).retryAfterSecs
+            : undefined;
+    if (typeof fromDetails === "number" && Number.isFinite(fromDetails)) return fromDetails;
+    const seconds = header === null ? NaN : Number(header);
+    return Number.isFinite(seconds) ? seconds : undefined;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class Whatsapi extends GeneratedOperations {
+    private readonly apiKey: string;
+    private readonly baseUrl: string;
+    private readonly timeout: number;
+    private readonly maxRetries: number;
+    private readonly fetchImpl: typeof globalThis.fetch;
+
+    constructor(options: WhatsapiOptions | string) {
+        super();
+        const opts = typeof options === "string" ? { apiKey: options } : options;
+        if (!opts.apiKey)
+            throw new TypeError(
+                "whatsapi: an API key is required — create one at https://app.whatsapi.sh/keys",
+            );
+        this.apiKey = opts.apiKey;
+        // Trailing slashes would double up against the leading slash of a path.
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = opts.timeout ?? 30_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        const impl = opts.fetch ?? globalThis.fetch;
+        if (typeof impl !== "function")
+            throw new TypeError(
+                "whatsapi: no global fetch — use Node 20+, or pass `fetch` in the options.",
+            );
+        // Bound: an unbound global fetch throws "Illegal invocation" in browsers.
+        this.fetchImpl = opts.fetch ?? impl.bind(globalThis);
+    }
+
+    protected async request<T>(spec: RequestSpec, params: object = {}): Promise<T> {
+        // Reads are the only calls we may repeat: a re-sent message is a second
+        // message to a real person, and no header on /v1 makes it idempotent.
+        const retries = spec.method === "GET" ? this.maxRetries : 0;
+        for (let attempt = 0; ; attempt++) {
+            try {
+                return await this.attempt<T>(spec, params);
+            } catch (error) {
+                if (!(error instanceof WhatsapiError) || attempt >= retries) throw error;
+                const delay = this.retryDelay(error, attempt);
+                if (delay === undefined) throw error;
+                await sleep(delay);
+            }
+        }
+    }
+
+    /** How long to wait before repeating a read, or undefined to give up now. */
+    private retryDelay(error: WhatsapiError, attempt: number): number | undefined {
+        const worthRepeating =
+            error.code === "NETWORK_ERROR" ||
+            error.code === "TIMEOUT" ||
+            error.code === "RATE_LIMIT_EXCEEDED" ||
+            // A quota clears when the month rolls over and a pairing cooldown
+            // runs for minutes: both are answers, not hiccups.
+            (error.status >= 500 && error.code !== "GATEWAY_TIMEOUT");
+        if (!worthRepeating) return undefined;
+        if (error.retryAfter !== undefined) {
+            const ms = error.retryAfter * 1000;
+            return ms > MAX_RETRY_DELAY_MS ? undefined : ms;
+        }
+        // Exponential with jitter, so a fleet of clients does not resynchronize
+        // onto the same second after an outage.
+        return Math.min(250 * 2 ** attempt, 4_000) * (0.5 + Math.random());
+    }
+
+    private async attempt<T>(spec: RequestSpec, params: object): Promise<T> {
+        const rest: Params = { ...params };
+        let path = spec.path;
+        for (const name of spec.pathParams ?? []) {
+            const value = rest[name];
+            if (value === undefined || value === null || value === "")
+                throw new TypeError(`whatsapi: \`${name}\` is required`);
+            delete rest[name];
+            path = path.replace(`:${name}`, encodeURIComponent(String(value)));
+        }
+
+        const url = new URL(this.baseUrl + path);
+        const hasBody = spec.method === "POST" || spec.method === "PUT";
+        if (!hasBody)
+            for (const [key, value] of Object.entries(rest))
+                if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+
+        const headers: Record<string, string> = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json",
+            "x-whatsapi-client": `whatsapi-js/${SDK_VERSION}`,
+        };
+        if (hasBody) headers["content-type"] = "application/json";
+
+        let response: Response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method: spec.method,
+                headers,
+                ...(hasBody
+                    ? { body: JSON.stringify({ ...rest, ...(spec.fixed ?? {}) }) }
+                    : undefined),
+                signal: AbortSignal.timeout(this.timeout),
+            });
+        } catch (cause) {
+            const timedOut = cause instanceof Error && cause.name === "TimeoutError";
+            throw new WhatsapiError({
+                code: (timedOut ? "TIMEOUT" : "NETWORK_ERROR") satisfies ClientErrorCode,
+                status: 0,
+                message: timedOut
+                    ? `whatsapi: no answer within ${this.timeout}ms — the call may still have gone through.`
+                    : `whatsapi: could not reach ${url.host}.`,
+                cause,
+            });
+        }
+
+        const requestId = response.headers.get("x-request-id") ?? undefined;
+        const text = await response.text();
+        let payload: unknown;
+        try {
+            payload = text ? (JSON.parse(text) as unknown) : undefined;
+        } catch {
+            payload = undefined;
+        }
+
+        if (response.ok) return (payload as { data: T }).data;
+
+        const envelope =
+            typeof payload === "object" && payload !== null
+                ? (payload as { error?: Record<string, unknown> }).error
+                : undefined;
+        const details = envelope?.details;
+        throw new WhatsapiError({
+            code: (envelope?.code as ErrorCode | undefined) ?? statusCode(response.status),
+            status: response.status,
+            // A proxy or a cold start can answer HTML; say what actually came back
+            // rather than pretending the body was ours.
+            message:
+                typeof envelope?.message === "string"
+                    ? envelope.message
+                    : `whatsapi: ${spec.method} ${path} failed with ${response.status}.`,
+            messageKey: typeof envelope?.messageKey === "string" ? envelope.messageKey : undefined,
+            params: envelope?.params as Record<string, string | number> | undefined,
+            details: envelope ? details : text.slice(0, 500) || undefined,
+            retryAfter: retryAfterOf(response.headers.get("retry-after"), details),
+            requestId,
+        });
+    }
+}

package/src/errors.ts

@@ -0,0 +1,71 @@
+// Every failure this client can raise, as one class.
+//
+// The API answers refusals with a machine-readable code (see ErrorCode), and
+// acting on the code is the whole point: some clear by waiting, one clears only
+// by paying, and one — GATEWAY_TIMEOUT — must never be retried at all. Collapse
+// that into `Error("Request failed")` and the caller is left guessing, which in
+// practice means re-sending a message that already arrived.
+import type { ErrorCode } from "./generated/contract.ts";
+
+/** Failures that never reached the API, so they carry no server code. */
+export type ClientErrorCode = "NETWORK_ERROR" | "TIMEOUT";
+
+export interface WhatsapiErrorInit {
+    code: ErrorCode | ClientErrorCode;
+    message: string;
+    /** HTTP status, or 0 when no answer arrived. */
+    status: number;
+    messageKey?: string;
+    params?: Record<string, string | number>;
+    details?: unknown;
+    /** Seconds until the call is worth making again, when the API said. */
+    retryAfter?: number;
+    /** `X-Request-ID` — quote it in a support request and we can find the call. */
+    requestId?: string;
+    cause?: unknown;
+}
+
+export class WhatsapiError extends Error {
+    readonly code: ErrorCode | ClientErrorCode;
+    readonly status: number;
+    readonly messageKey?: string;
+    readonly params?: Record<string, string | number>;
+    readonly details?: unknown;
+    readonly retryAfter?: number;
+    readonly requestId?: string;
+
+    constructor(init: WhatsapiErrorInit) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "WhatsapiError";
+        this.code = init.code;
+        this.status = init.status;
+        this.messageKey = init.messageKey;
+        this.params = init.params;
+        this.details = init.details;
+        this.retryAfter = init.retryAfter;
+        this.requestId = init.requestId;
+    }
+
+    /** The id a timed-out send went out with.
+     *
+     *  `GATEWAY_TIMEOUT` means WhatsApp did not confirm in time — NOT that the
+     *  message failed. It was accepted upstream and most likely delivered, so
+     *  sending it again sends it twice. Watch for this id on the
+     *  `message.status` webhook instead. */
+    get messageId(): string | undefined {
+        const details = this.details;
+        if (this.code !== "GATEWAY_TIMEOUT" || typeof details !== "object" || details === null)
+            return undefined;
+        const id = (details as { messageId?: unknown }).messageId;
+        return typeof id === "string" ? id : undefined;
+    }
+}
+
+/** A delivery whose signature did not check out — treat the body as hostile and
+ *  answer 400. Never a WhatsapiError: nothing here came from a call we made. */
+export class WebhookSignatureError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "WebhookSignatureError";
+    }
+}