@whatsapi.sh/sdk 0.1.0

package/src/generated/operations.ts

@@ -0,0 +1,371 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: apps/api/src/routes/v1 (the mounted operations)
+//
+// One method per capability, named the way its MCP tool is named, returning
+// the DTO the operation declares. `Whatsapi` in ../client.ts supplies request().
+
+import type { RequestSpec } from "../client.ts";
+import type {
+    BatchMessageDto,
+    DeletedNumberDto,
+    DeletedWebhookDto,
+    MarkReadDto,
+    MessageDto,
+    NumberCheckDto,
+    NumberDto,
+    OtpCheckDto,
+    OtpDto,
+    PairNumberDto,
+    SavedWebhookDto,
+    TypingDto,
+    UnpairedNumberDto,
+    UsageDto,
+    WebhookDeliveryDto,
+    WebhookEndpointDto,
+    WebhookTestResultDto,
+} from "./contract.ts";
+import type {
+    CheckNumberParams,
+    CheckOtpParams,
+    CreateNumberParams,
+    DeleteNumberParams,
+    ListWebhookDeliveriesParams,
+    MarkReadParams,
+    NumberStatusParams,
+    PairNumberParams,
+    SendBatchParams,
+    SendContactParams,
+    SendLocationParams,
+    SendMediaParams,
+    SendMessageParams,
+    SendOtpParams,
+    SetWebhookParams,
+    TypingParams,
+    UnpairNumberParams,
+} from "./params.ts";
+
+/** The version this client reports in `x-whatsapi-client`. */
+export const SDK_VERSION = "0.1.0";
+
+/** The hosted API. */
+export const DEFAULT_BASE_URL = "https://api.whatsapi.sh/v1";
+
+export abstract class GeneratedOperations {
+    protected abstract request<T>(spec: RequestSpec, params?: object): Promise<T>;
+
+    /**
+     * Send a WhatsApp message
+     *
+     * Send a text message to a phone number over WhatsApp. Counts as one message against the
+     * account's monthly quota. The reply carries WhatsApp's message id — delivery and read
+     * receipts arrive later on the account's webhook, not here.
+     *
+     * `POST /messages`
+     */
+    sendMessage(params: SendMessageParams): Promise<MessageDto> {
+        return this.request({ method: "POST", path: "/messages" }, params);
+    }
+
+    /**
+     * Send a photo, video, voice note or file
+     *
+     * Send media over WhatsApp from a public URL or base64 data. `type` picks the bubble the
+     * recipient sees: `image` and `video` support a caption, `document` is a file attachment named
+     * by `fileName`, and `audio` becomes a voice note when the file is ogg/opus — any other audio
+     * format is sent as a playable attachment instead, because WhatsApp will not render a voice
+     * note that is not opus. Files are capped at 16MB, and `url` beats `base64` for anything
+     * sizeable. Counts as one message.
+     *
+     * `POST /messages/media`
+     */
+    sendMedia(params: SendMediaParams): Promise<MessageDto> {
+        return this.request({ method: "POST", path: "/messages/media" }, params);
+    }
+
+    /**
+     * Send one text to many recipients
+     *
+     * Send the same text to up to 25 recipients in one call — one message, and one message's worth
+     * of quota, per recipient. The answer reports each recipient separately: a batch where some
+     * land and some do not is the normal case, not an error. If something systemic stops the run
+     * (the number drops its session, the quota or rate limit refuses) the remaining recipients
+     * come back as `skipped` rather than being attempted, so they can be sent again once that is
+     * cleared. Sends inside a batch leave back-to-back, so keep lists small and space calls
+     * minutes apart — pacing keeps your number off WhatsApp's spam radar (see the avoiding-bans
+     * guide). Paid plans only.
+     *
+     * `POST /messages/batch`
+     */
+    sendBatch(params: SendBatchParams): Promise<BatchMessageDto> {
+        return this.request({ method: "POST", path: "/messages/batch" }, params);
+    }
+
+    /**
+     * Send a location pin
+     *
+     * Send a map pin over WhatsApp. Counts as one message.
+     *
+     * `POST /messages/location`
+     */
+    sendLocation(params: SendLocationParams): Promise<MessageDto> {
+        return this.request({ method: "POST", path: "/messages/location" }, params);
+    }
+
+    /**
+     * Send a contact card
+     *
+     * Send a contact card (vCard) over WhatsApp, so the recipient can save the number with one
+     * tap. Counts as one message.
+     *
+     * `POST /messages/contact`
+     */
+    sendContact(params: SendContactParams): Promise<MessageDto> {
+        return this.request({ method: "POST", path: "/messages/contact" }, params);
+    }
+
+    /**
+     * Send a verification code
+     *
+     * Generate a 6-digit code, send it over WhatsApp and return it. Returning the code is
+     * deliberate: verify it yourself, or hand it back to check_otp and keep nothing. Codes expire
+     * in 5 minutes by default and one number can only be sent a new code once a minute. Counts as
+     * one message.
+     *
+     * `POST /otp`
+     */
+    sendOtp(params: SendOtpParams): Promise<OtpDto> {
+        return this.request({ method: "POST", path: "/otp" }, params);
+    }
+
+    /**
+     * Check a verification code
+     *
+     * Verify a code sent with send_otp and consume it, so it can never be used twice. A wrong or
+     * expired code answers 400 OTP_INVALID — deliberately an error, not a `verified: false`, so a
+     * missing check at the caller can never read as success. Five wrong guesses kill the code.
+     * Free.
+     *
+     * `POST /otp/check`
+     */
+    checkOtp(params: CheckOtpParams): Promise<OtpCheckDto> {
+        return this.request({ method: "POST", path: "/otp/check" }, params);
+    }
+
+    /**
+     * List your WhatsApp numbers
+     *
+     * Every WhatsApp number on the account with its connection status. Start here when you do not
+     * know which number to send from, or to check whether one needs re-pairing. Free.
+     *
+     * `GET /numbers`
+     */
+    listNumbers(): Promise<NumberDto[]> {
+        return this.request({ method: "GET", path: "/numbers" });
+    }
+
+    /**
+     * Add a WhatsApp number
+     *
+     * Create a new WhatsApp number slot on the account and return it. This is step one of two: the
+     * slot starts `disconnected` and cannot send until pair_number links a real WhatsApp account
+     * to it. How many can exist at once is what the plan sells. Free.
+     *
+     * `POST /numbers`
+     */
+    createNumber(params: CreateNumberParams): Promise<NumberDto> {
+        return this.request({ method: "POST", path: "/numbers" }, params);
+    }
+
+    /**
+     * Check whether a phone is on WhatsApp
+     *
+     * Ask WhatsApp whether a phone number has an account, and get its profile picture when it
+     * does. Brazilian mobiles are checked with and without the extra 9 and the answer reports the
+     * form that actually matched. If WhatsApp cannot be reached the answer assumes yes and sets
+     * `verified: false` — an outage must not block sends to real people. Free.
+     *
+     * `GET /numbers/check/:phone`
+     */
+    checkNumber(params: CheckNumberParams): Promise<NumberCheckDto> {
+        return this.request(
+            { method: "GET", path: "/numbers/check/:phone", pathParams: ["phone"] },
+            params,
+        );
+    }
+
+    /**
+     * Get one number's status
+     *
+     * One number's current state: `connected` (ready to send), `pairing` (waiting for a scan),
+     * `disconnected` (session dropped — pair it again) or `banned` (WhatsApp restricted it; wait
+     * out the 24h window before reconnecting). Free.
+     *
+     * `GET /numbers/:id`
+     */
+    numberStatus(params: NumberStatusParams): Promise<NumberDto> {
+        return this.request(
+            { method: "GET", path: "/numbers/:numberId", pathParams: ["numberId"] },
+            params,
+        );
+    }
+
+    /**
+     * Pair a number with WhatsApp
+     *
+     * Start (or resume) linking a WhatsApp account to one of your numbers. `qr` returns a QR code
+     * to scan from WhatsApp → Linked devices; `code` returns an 8-character linking code to type
+     * there instead, and needs the phone number being linked. A QR lives ~90 seconds and a new one
+     * can only be minted every few minutes, so call again to poll: `state: "pairing"` with no code
+     * yet simply means it is still being minted. Free.
+     *
+     * `POST /numbers/:id/pair`
+     */
+    pairNumber(params: PairNumberParams): Promise<PairNumberDto> {
+        return this.request(
+            { method: "POST", path: "/numbers/:numberId/pair", pathParams: ["numberId"] },
+            params,
+        );
+    }
+
+    /**
+     * Disconnect a number from WhatsApp
+     *
+     * Log the linked WhatsApp account out of this number, keeping the number itself. Use it to
+     * link a different phone: a connected number cannot be re-paired until it is unpaired. Free.
+     *
+     * `POST /numbers/:id/unpair`
+     */
+    unpairNumber(params: UnpairNumberParams): Promise<UnpairedNumberDto> {
+        return this.request(
+            { method: "POST", path: "/numbers/:numberId/unpair", pathParams: ["numberId"] },
+            params,
+        );
+    }
+
+    /**
+     * Delete a number
+     *
+     * Remove a number from the account for good, logging its WhatsApp session out on the way. This
+     * frees a slot against the plan's limit. Messages already sent are unaffected, and the usage
+     * they cost stays on the bill. Free, and not reversible.
+     *
+     * `DELETE /numbers/:id`
+     */
+    deleteNumber(params: DeleteNumberParams): Promise<DeletedNumberDto> {
+        return this.request(
+            { method: "DELETE", path: "/numbers/:numberId", pathParams: ["numberId"] },
+            params,
+        );
+    }
+
+    /**
+     * Show the typing indicator
+     *
+     * Show (or clear) the “typing…” indicator in a chat. Free — it is not a message. WhatsApp
+     * clears it on its own after a few seconds, so call it again for a long reply.
+     *
+     * `POST /chats/:phone/typing`
+     */
+    typing(params: TypingParams): Promise<TypingDto> {
+        return this.request(
+            { method: "POST", path: "/chats/:to/typing", pathParams: ["to"] },
+            params,
+        );
+    }
+
+    /**
+     * Mark messages as read
+     *
+     * Put blue ticks on messages your number received in a chat. Free. Message ids come from the
+     * inbound webhook.
+     *
+     * `POST /chats/:phone/read`
+     */
+    markRead(params: MarkReadParams): Promise<MarkReadDto> {
+        return this.request(
+            { method: "POST", path: "/chats/:to/read", pathParams: ["to"] },
+            params,
+        );
+    }
+
+    /**
+     * Get your webhook endpoint
+     *
+     * The endpoint events are being POSTed to, which ones it is subscribed to, and whether it is
+     * still healthy. `null` when none is registered. `disabledReason: "failures"` means we stopped
+     * delivering after a long run of dead attempts — fix the endpoint and set it again (or fire a
+     * test) to switch it back on. Free.
+     *
+     * `GET /webhooks`
+     */
+    getWebhook(): Promise<WebhookEndpointDto | null> {
+        return this.request({ method: "GET", path: "/webhooks" });
+    }
+
+    /**
+     * Register your webhook endpoint
+     *
+     * Point whatsapi.sh at an https URL and start receiving events there. The answer carries the
+     * signing secret ONCE, on first registration: keep it — every delivery is signed with it in
+     * the `x-whatsapi-signature` header (`t=<unix>,v1=<hmac-sha256 of "<t>.<body>">`), and that
+     * signature is how you know a request is really from us. Calling this again updates the URL or
+     * the subscription and keeps the same secret unless you ask to rotate it. Saving also
+     * re-enables an endpoint we had disabled. Free.
+     *
+     * `PUT /webhooks`
+     */
+    setWebhook(params: SetWebhookParams): Promise<SavedWebhookDto> {
+        return this.request({ method: "PUT", path: "/webhooks" }, params);
+    }
+
+    /**
+     * Fire a test event at your endpoint
+     *
+     * Send a `ping` event to your registered endpoint right now and wait for the answer, so you
+     * can verify the URL and your signature check without waiting for a real message. The result
+     * is the actual outcome: `ok: false` carries the HTTP status your server answered, or why we
+     * could not reach it. A successful ping also revives an endpoint we had auto-disabled. Free.
+     *
+     * `POST /webhooks/test`
+     */
+    testWebhook(): Promise<WebhookTestResultDto> {
+        return this.request({ method: "POST", path: "/webhooks/test" });
+    }
+
+    /**
+     * Recent webhook deliveries
+     *
+     * The last deliveries we attempted, newest first — what we sent, what your endpoint answered,
+     * and how many attempts it took. This is the answer to “the event never arrived”. Deliveries
+     * are kept for a week. Free.
+     *
+     * `GET /webhooks/deliveries`
+     */
+    listWebhookDeliveries(params?: ListWebhookDeliveriesParams): Promise<WebhookDeliveryDto[]> {
+        return this.request({ method: "GET", path: "/webhooks/deliveries" }, params);
+    }
+
+    /**
+     * Remove your webhook endpoint
+     *
+     * Stop sending events and forget the endpoint, its secret and its delivery history.
+     * Registering again mints a new secret. Free.
+     *
+     * `DELETE /webhooks`
+     */
+    deleteWebhook(): Promise<DeletedWebhookDto> {
+        return this.request({ method: "DELETE", path: "/webhooks" });
+    }
+
+    /**
+     * Check quota and usage
+     *
+     * Messages sent this month against the plan quota, today against the daily fair-use cap, the
+     * leftover credit balance, and the per-key breakdown. Read this before a bulk send. Free.
+     *
+     * `GET /usage`
+     */
+    getUsage(): Promise<UsageDto> {
+        return this.request({ method: "GET", path: "/usage" });
+    }
+}

package/src/generated/params.ts

@@ -0,0 +1,203 @@
+// GENERATED FILE — do not edit. Run `bun run sdk:gen`.
+// Source: apps/api/src/operations/*.ts (zod input schemas)
+//
+// What each call takes. These are the same schemas the API validates with,
+// so a value TypeScript accepts here is a value the server accepts too.
+
+/** Arguments for `sendMessage()`. */
+export interface SendMessageParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** The message body. */
+    text: string;
+    /** Render a preview card for the first link in the text. Default: on. */
+    linkPreview?: boolean;
+}
+
+/** Arguments for `sendMedia()`. */
+export interface SendMediaParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** Which kind of media bubble to send. */
+    type: "image" | "video" | "audio" | "document";
+    /** Public https URL of the file — the better option. We stream the download and forward the
+     *  bytes, so the size of the file never rides in your request. */
+    url?: string;
+    /** The file as base64, bare or as a `data:<mime>;base64,…` URI. Base64 inflates a request by a
+     *  third, so prefer `url` for anything but small files. */
+    base64?: string;
+    /** Overrides the detected content type, e.g. `image/webp`. */
+    mimeType?: string;
+    /** Text shown under the media. Images and videos only — WhatsApp has no caption field for
+     *  documents or audio. */
+    caption?: string;
+    /** Documents: the filename WhatsApp shows on the bubble. */
+    fileName?: string;
+    /** Voice notes: duration, so the bubble shows the right length. */
+    seconds?: number;
+}
+
+/** Arguments for `sendBatch()`. */
+export interface SendBatchParams {
+    /** Recipients, up to 25. Each gets its own message; no duplicates. */
+    to: string[];
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** The message body — the same for everyone. */
+    text: string;
+}
+
+/** Arguments for `sendLocation()`. */
+export interface SendLocationParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    latitude: number;
+    longitude: number;
+    /** Label shown on the pin. */
+    name?: string;
+}
+
+/** Arguments for `sendContact()`. */
+export interface SendContactParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** Display name on the card. */
+    name: string;
+    /** The vCard payload, e.g. `BEGIN:VCARD\nVERSION:3.0\n…\nEND:VCARD`. */
+    vcard: string;
+}
+
+/** Arguments for `sendOtp()`. */
+export interface SendOtpParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** Message body. Must contain `{code}`; `{minutes}` expands to the expiry. Default: “{code} is
+     *  your verification code. It expires in {minutes} minutes.” */
+    template?: string;
+    /** How long the code stays valid. Default 300 (5 minutes). */
+    expiresInSeconds?: number;
+}
+
+/** Arguments for `checkOtp()`. */
+export interface CheckOtpParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** The code the user typed. */
+    code: string;
+}
+
+/** Arguments for `createNumber()`. */
+export interface CreateNumberParams {
+    /** A label you choose, e.g. “Support” — only you ever see it. */
+    name: string;
+    /** Pull the phone's existing chat history on pairing. Off by default: it copies conversations
+     *  we otherwise never see. */
+    historySync?: boolean;
+}
+
+/** Arguments for `checkNumber()`. */
+export interface CheckNumberParams {
+    /** The phone number to look up, e.g. +5511988887777. */
+    phone: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+}
+
+/** Arguments for `numberStatus()`. */
+export interface NumberStatusParams {
+    /** Id of the number, from list_numbers. */
+    numberId: string;
+}
+
+/** Arguments for `pairNumber()`. */
+export interface PairNumberParams {
+    /** Id of the number to pair, from list_numbers. */
+    numberId: string;
+    /** `qr` (default) or `code` for the type-in linking code. */
+    mode?: "qr" | "code";
+    /** Required with `mode: "code"` — the phone number being linked. */
+    phone?: string;
+}
+
+/** Arguments for `unpairNumber()`. */
+export interface UnpairNumberParams {
+    /** Id of the number, from list_numbers. */
+    numberId: string;
+}
+
+/** Arguments for `deleteNumber()`. */
+export interface DeleteNumberParams {
+    /** Id of the number to delete, from list_numbers. */
+    numberId: string;
+}
+
+/** Arguments for `typing()`. */
+export interface TypingParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** `composing` shows the indicator, `paused` clears it. Default: composing. */
+    state?: "composing" | "paused";
+    /** Show “recording audio…” instead of “typing…”. */
+    recording?: boolean;
+}
+
+/** Arguments for `markRead()`. */
+export interface MarkReadParams {
+    /** Recipient — a phone number in international format (+5511988887777) or a WhatsApp address
+     *  (5511988887777@s.whatsapp.net, an @lid contact, or a @g.us group). */
+    to: string;
+    /** Which of your WhatsApp numbers sends this — its id or its phone number. Optional: with a
+     *  single connected number it is resolved for you. */
+    from?: string;
+    /** Ids of the received messages to acknowledge. */
+    messageIds: string[];
+}
+
+/** Arguments for `setWebhook()`. */
+export interface SetWebhookParams {
+    /** Where to POST events, e.g. https://api.yourapp.com/webhooks/whatsapp. */
+    url: string;
+    /** Which events to receive: message.created, message.status, number.connected,
+     *  number.disconnected, number.logged_out. Defaults to all of them. */
+    events?:
+        | "message.created"
+        | "message.status"
+        | "number.connected"
+        | "number.disconnected"
+        | "number.logged_out"[];
+    /** Mint a new signing secret and return it — the old one stops working. */
+    rotateSecret?: boolean;
+}
+
+/** Arguments for `listWebhookDeliveries()`. */
+export interface ListWebhookDeliveriesParams {
+    /** How many to return, newest first. Up to 50 (the default). */
+    limit?: number;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// The published surface of `whatsapi`.
+export { Whatsapi } from "./client.ts";
+export type { RequestSpec, WhatsapiOptions } from "./client.ts";
+export { WebhookSignatureError, WhatsapiError } from "./errors.ts";
+export type { ClientErrorCode, WhatsapiErrorInit } from "./errors.ts";
+export { verifyWebhook } from "./webhooks.ts";
+export type { VerifyWebhookInput } from "./webhooks.ts";
+export { DEFAULT_BASE_URL, SDK_VERSION } from "./generated/operations.ts";
+// Every DTO, error code and event shape the API speaks.
+export * from "./generated/contract.ts";
+export type * from "./generated/params.ts";

package/src/webhooks.ts

@@ -0,0 +1,96 @@
+// Receiving events: check the signature, then hand back a typed event.
+//
+// Verifying is not optional. The URL is public, so anything can POST to it —
+// the `x-whatsapi-signature` header is the only thing that separates our
+// delivery from someone else's forgery, and it signs the TIMESTAMP alongside
+// the body so a captured payload cannot be replayed at you later.
+import { WebhookSignatureError } from "./errors.ts";
+import type { WebhookEvent } from "./generated/contract.ts";
+
+export interface VerifyWebhookInput {
+    /** The RAW request body — the exact bytes we signed. A body that has been
+     *  parsed and re-serialized will not match, even when it looks identical. */
+    payload: string | Uint8Array;
+    /** The `x-whatsapi-signature` header. */
+    signature: string | null | undefined;
+    /** The `whsec_` secret, shown once when the endpoint was registered. */
+    secret: string;
+    /** How old a delivery may be, in seconds. Default 300. */
+    toleranceSeconds?: number;
+}
+
+const encoder = new TextEncoder();
+
+function hex(buffer: ArrayBuffer): string {
+    return Array.from(new Uint8Array(buffer), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Constant time in the length that matters: comparing hex digit by digit with
+ *  `===` leaks how much of a guess was right through timing. */
+function timingSafeEqual(a: string, b: string): boolean {
+    if (a.length !== b.length) return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+
+/** `t=<unix seconds>,v1=<hex>` — tolerant of spacing and of future `vN=` parts. */
+function parseHeader(header: string): { timestamp: number; v1: string } | null {
+    let timestamp = NaN;
+    let v1 = "";
+    for (const part of header.split(",")) {
+        const [key, value = ""] = part.trim().split("=", 2);
+        if (key === "t") timestamp = Number(value);
+        if (key === "v1") v1 = value;
+    }
+    return Number.isFinite(timestamp) && v1 ? { timestamp, v1 } : null;
+}
+
+/**
+ * Verify a delivery and parse it.
+ *
+ * Throws `WebhookSignatureError` for anything that does not check out — answer
+ * 400 and log it. On success you get the event, discriminated on `type`:
+ *
+ * ```ts
+ * const event = await verifyWebhook({ payload: rawBody, signature: req.headers["x-whatsapi-signature"], secret });
+ * if (event.type === "message.created") reply(event.data.message.text);
+ * ```
+ *
+ * Deliveries retry, so the same `event.id` (also the `x-whatsapi-delivery`
+ * header) can arrive twice: record it and drop repeats.
+ */
+export async function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent> {
+    const { payload, signature, secret, toleranceSeconds = 300 } = input;
+    if (!signature) throw new WebhookSignatureError("Missing x-whatsapi-signature header.");
+    if (!secret) throw new WebhookSignatureError("Missing webhook secret.");
+
+    const parsed = parseHeader(signature);
+    if (!parsed) throw new WebhookSignatureError("Malformed x-whatsapi-signature header.");
+
+    const age = Math.abs(Date.now() / 1000 - parsed.timestamp);
+    if (age > toleranceSeconds)
+        throw new WebhookSignatureError(
+            `Delivery is ${Math.round(age)}s old, outside the ${toleranceSeconds}s tolerance.`,
+        );
+
+    const body = typeof payload === "string" ? payload : new TextDecoder().decode(payload);
+    const key = await crypto.subtle.importKey(
+        "raw",
+        encoder.encode(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+    );
+    const expected = hex(
+        await crypto.subtle.sign("HMAC", key, encoder.encode(`${parsed.timestamp}.${body}`)),
+    );
+    if (!timingSafeEqual(expected, parsed.v1))
+        throw new WebhookSignatureError("Signature does not match — the body is not from us.");
+
+    try {
+        return JSON.parse(body) as WebhookEvent;
+    } catch {
+        throw new WebhookSignatureError("Delivery body is not JSON.");
+    }
+}