@north-light/comms 0.0.0-stage → 0.1.0

package/dist/helpers/format.js

@@ -0,0 +1,164 @@
+/** The send API refuses a longer `text`. */
+export const MAX_TEXT_LENGTH = 10_000;
+const OPEN = "\uE000";
+const CLOSE = "\uE001";
+/**
+ * Markdown to the plain text a person should read: emphasis, headings, quotes, code fences and
+ * HTML are dropped, `[label](url)` becomes `label (url)`, images disappear, lists keep their
+ * `-` and `1.` markers and table rows become `a | b`. Text inside code stays exactly as written.
+ */
+export function toPlainText(markdown) {
+    const kept = [];
+    const keep = (text) => {
+        kept.push(text);
+        return `${OPEN}${kept.length - 1}${CLOSE}`;
+    };
+    let text = markdown
+        .replaceAll("\r\n", "\n")
+        .replaceAll(OPEN, "")
+        .replaceAll(CLOSE, "");
+    // Protected spans first: code, then backslash escapes.
+    text = text.replace(/^ {0,3}(`{3,}|~{3,})[^\n]*\n([\s\S]*?)(?:\n {0,3}\1[`~]*[ \t]*(?=\n|$)|$)/gm, (_match, _fence, body) => keep(body));
+    text = text.replace(/(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/g, (_m, _t, code) => keep(code.trim()));
+    text = text.replace(/\\([\\`*_{}[\]()#+\-.!|~>])/g, (_m, char) => keep(char));
+    // Link reference definitions.
+    const definitions = new Map();
+    text = text.replace(/^ {0,3}\[([^\]]+)\]:[ \t]*<?(\S+?)>?(?:[ \t]+["'(].*["')])?[ \t]*$/gm, (_m, id, url) => {
+        definitions.set(id.toLowerCase(), url);
+        return "";
+    });
+    text = text
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+        .replace(/!\[[^\]]*\]\[[^\]]*\]/g, "")
+        .replace(/\[([^\]]+)\]\(\s*<?([^)\s>]+)>?(?:\s+["'][^)]*["'])?\s*\)/g, (_m, label, url) => `${label} (${url})`)
+        .replace(/\[([^\]]+)\]\[([^\]]*)\]/g, (match, label, id) => {
+        const url = definitions.get((id || label).toLowerCase());
+        return url ? `${label} (${url})` : match;
+    })
+        .replace(/<((?:https?|mailto):[^>\s]+)>/g, "$1")
+        .replace(/<\/?[a-zA-Z][^>]*>/g, "");
+    const lines = text.split("\n").flatMap((line) => {
+        if (/^ {0,3}([-*_])(?:[ \t]*\1){2,}[ \t]*$/.test(line))
+            return [""];
+        // A table's separator row (`|---|---|`) carries no text.
+        if (/^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/.test(line) &&
+            line.includes("|"))
+            return [];
+        let out = line.replace(/^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/, "$1");
+        out = out.replace(/^(\s*(?:>[ \t]?)+)/, "");
+        out = out
+            .replace(/^(\s*)[*+-][ \t]+\[[ xX]\][ \t]+/, "$1- ")
+            .replace(/^(\s*)[*+][ \t]+/, "$1- ");
+        if (/^\s*\|.*\|\s*$/.test(out))
+            out = out
+                .trim()
+                .slice(1, -1)
+                .split("|")
+                .map((cell) => cell.trim())
+                .join(" | ");
+        return [out];
+    });
+    text = lines.join("\n");
+    text = text
+        .replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "$2")
+        .replace(/(?<![*\w])\*(?=\S)([^*\n]*?\S)\*(?![*\w])/g, "$1")
+        .replace(/(?<![_\w])_(?=\S)([^_\n]*?\S)_(?![_\w])/g, "$1")
+        .replace(/~~(?=\S)([\s\S]*?\S)~~/g, "$1");
+    return text
+        .replace(new RegExp(`${OPEN}(\\d+)${CLOSE}`, "g"), (_m, index) => kept[Number(index)] ?? "")
+        .replace(/[ \t]+$/gm, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * Splits a long text into parts of at most `maxLength` characters, preferring to break at a
+ * blank line, then a line, then a space. Each part is sent as its own message, in order.
+ */
+export function splitText(text, maxLength = MAX_TEXT_LENGTH) {
+    if (!(maxLength > 1))
+        throw new RangeError("maxLength must be greater than 1");
+    const parts = [];
+    let rest = text.trim();
+    while (rest.length > maxLength) {
+        let at = rest.lastIndexOf("\n\n", maxLength);
+        if (at <= 0)
+            at = rest.lastIndexOf("\n", maxLength);
+        if (at <= 0)
+            at = rest.lastIndexOf(" ", maxLength);
+        if (at <= 0) {
+            at = maxLength;
+            // Never cut a surrogate pair in half.
+            if (/[\uD800-\uDBFF]/.test(rest[at - 1] ?? ""))
+                at--;
+        }
+        parts.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at).trimStart();
+    }
+    if (rest)
+        parts.push(rest);
+    return parts;
+}
+/** An agent's markdown reply as the texts to send, in order. Empty markdown gives no texts. */
+export function formatReply(markdown) {
+    const plain = toPlainText(markdown);
+    return plain ? splitText(plain) : [];
+}
+// ---------------------------------------------------------------------------
+// Reactions and threaded replies
+// ---------------------------------------------------------------------------
+/** The six iMessage tapbacks by name. */
+export const TAPBACKS = {
+    love: "❤️",
+    like: "👍",
+    dislike: "👎",
+    laugh: "😂",
+    emphasize: "‼️",
+    question: "❓",
+};
+const withoutSelector = (emoji) => emoji.replaceAll("\uFE0F", "");
+/** The tapback name for an emoji (`❤️` → `love`), or `null` when it is not a tapback. */
+export function tapbackName(emoji) {
+    const wanted = withoutSelector(emoji);
+    for (const [name, value] of Object.entries(TAPBACKS))
+        if (withoutSelector(value) === wanted)
+            return name;
+    return null;
+}
+/** The emoji to send as a reaction, from a tapback name (`love`) or an emoji. Throws for anything else. */
+export function tapbackEmoji(nameOrEmoji) {
+    const name = nameOrEmoji.toLowerCase();
+    if (name in TAPBACKS)
+        return TAPBACKS[name];
+    const known = tapbackName(nameOrEmoji);
+    if (known)
+        return TAPBACKS[known];
+    throw new RangeError(`Not a tapback: ${nameOrEmoji} (use one of ${Object.keys(TAPBACKS).join(", ")})`);
+}
+/** What to add to a send so it threads under the message that was received. */
+export function replyTo(received) {
+    return { reply_to_message_id: received.message_id };
+}
+/**
+ * A received message as one line of text an agent can read: text as written, a reaction as
+ * `[reacted love to message <id>]`, an attachment as `[attachment: name (mime)]` followed by
+ * its caption, and a threaded message prefixed with `[replying to message <id>] `.
+ */
+export function describeReceived(received) {
+    const body = describeContent(received.content);
+    return received.reply_to_message_id
+        ? `[replying to message ${received.reply_to_message_id}] ${body}`
+        : body;
+}
+function describeContent(content) {
+    switch (content.type) {
+        case "text":
+            return content.text;
+        case "reaction":
+            return `[reacted ${tapbackName(content.reaction) ?? content.reaction} to message ${content.target_message_id}]`;
+        case "attachment": {
+            const label = `[attachment: ${content.name} (${content.mime_type})]`;
+            return content.caption ? `${label} ${content.caption}` : label;
+        }
+    }
+}

package/dist/helpers/signup.d.ts

@@ -0,0 +1,34 @@
+import type { CommsClient } from "../client.js";
+import type { ContactUserLinkedData, Environment, QueuedMessage, SignInLink, WebhookEvent } from "../types.js";
+/** The text sent with the link. `{url}` is replaced by the link. */
+export declare const DEFAULT_SIGN_IN_TEXT = "Tap to finish signing up: {url}";
+export interface SendSignInLinkOptions {
+    environment: Environment;
+    /** The message to send; it must contain `{url}`. Default `DEFAULT_SIGN_IN_TEXT`. */
+    text?: string;
+    /** Where the person lands after signing in; must be on your app's origin host. Default: your app's sign-in start URL. */
+    returnTo?: string;
+    /** Overrides the key that makes a retry of this call send the text once. */
+    idempotencyKey?: string;
+}
+export interface SentSignInLink {
+    link: SignInLink;
+    message: QueuedMessage;
+}
+/**
+ * Creates (or finds) the contact's sign-in link and texts it. Comms refuses with a
+ * `CommsError` when the contact is already a user (`already_user`), has an email handle
+ * (`no_phone`) or has sent STOP (`opted_out`); handle those before calling if you can.
+ * Calling it again while the same link is still valid sends the text only once.
+ */
+export declare function sendSignInLink(client: CommsClient, contact: {
+    id: string;
+}, options: SendSignInLinkOptions): Promise<SentSignInLink>;
+export type UserLinkedHandler = (data: ContactUserLinkedData, event: Extract<WebhookEvent, {
+    type: "contact.user_linked";
+}>) => void | Promise<void>;
+/**
+ * Wraps a handler for `contact.user_linked` into a function you call with every verified
+ * event. It runs the handler for that event type only and resolves to whether it ran.
+ */
+export declare function onUserLinked(handler: UserLinkedHandler): (event: WebhookEvent) => Promise<boolean>;

package/dist/helpers/signup.js

@@ -0,0 +1,36 @@
+/** The text sent with the link. `{url}` is replaced by the link. */
+export const DEFAULT_SIGN_IN_TEXT = "Tap to finish signing up: {url}";
+/**
+ * Creates (or finds) the contact's sign-in link and texts it. Comms refuses with a
+ * `CommsError` when the contact is already a user (`already_user`), has an email handle
+ * (`no_phone`) or has sent STOP (`opted_out`); handle those before calling if you can.
+ * Calling it again while the same link is still valid sends the text only once.
+ */
+export async function sendSignInLink(client, contact, options) {
+    const template = options.text ?? DEFAULT_SIGN_IN_TEXT;
+    if (!template.includes("{url}"))
+        throw new TypeError("The sign-in text must contain {url}");
+    const link = await client.createSignInLink(contact.id, {
+        environment: options.environment,
+        ...(options.returnTo === undefined ? {} : { return_to: options.returnTo }),
+    });
+    const message = await client.sendMessage({
+        environment: options.environment,
+        to: { contact_id: contact.id },
+        text: template.replaceAll("{url}", link.url),
+        idempotency_key: options.idempotencyKey ?? `sign-in-link:${contact.id}:${link.expires_at}`,
+    });
+    return { link, message };
+}
+/**
+ * Wraps a handler for `contact.user_linked` into a function you call with every verified
+ * event. It runs the handler for that event type only and resolves to whether it ran.
+ */
+export function onUserLinked(handler) {
+    return async (event) => {
+        if (event.type !== "contact.user_linked")
+            return false;
+        await handler(event.data, event);
+        return true;
+    };
+}

package/dist/helpers/typing.d.ts

@@ -0,0 +1,14 @@
+import type { CommsClient } from "../client.js";
+import type { Environment } from "../types.js";
+export interface KeepTypingOptions {
+    environment: Environment;
+    /** How often the indicator is renewed. Default 5000. */
+    intervalMs?: number;
+    /** Receives a failed typing call. Default: ignored. */
+    onError?: (error: unknown) => void;
+}
+export declare const DEFAULT_TYPING_INTERVAL_MS = 5000;
+/** Turns the indicator on now and keeps it on. The returned function turns it off; call it once the reply is sent. */
+export declare function keepTyping(client: CommsClient, contactId: string, options: KeepTypingOptions): () => Promise<void>;
+/** Runs `work` with the indicator on, and turns it off when `work` settles. */
+export declare function withTyping<T>(client: CommsClient, contactId: string, options: KeepTypingOptions, work: () => Promise<T>): Promise<T>;

package/dist/helpers/typing.js

@@ -0,0 +1,31 @@
+export const DEFAULT_TYPING_INTERVAL_MS = 5_000;
+/** Turns the indicator on now and keeps it on. The returned function turns it off; call it once the reply is sent. */
+export function keepTyping(client, contactId, options) {
+    const intervalMs = options.intervalMs ?? DEFAULT_TYPING_INTERVAL_MS;
+    if (!(intervalMs > 0))
+        throw new RangeError("intervalMs must be positive");
+    const set = (on) => client
+        .setTyping(contactId, { environment: options.environment, on })
+        .catch((error) => options.onError?.(error));
+    let stopped;
+    void set(true);
+    const timer = setInterval(() => void set(true), intervalMs);
+    timer.unref();
+    return () => {
+        if (!stopped) {
+            clearInterval(timer);
+            stopped = set(false);
+        }
+        return stopped;
+    };
+}
+/** Runs `work` with the indicator on, and turns it off when `work` settles. */
+export async function withTyping(client, contactId, options, work) {
+    const stop = keepTyping(client, contactId, options);
+    try {
+        return await work();
+    }
+    finally {
+        await stop();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { CommsClient, CommsError, DEFAULT_RESOURCE } from "./client.js";
+export type { CommsClientOptions, PrivateKeyJwk } from "./client.js";
+export { WEBHOOK_TOLERANCE_SECONDS, WebhookVerificationError, sign, verifyWebhook, } from "./webhooks.js";
+export type { VerifyWebhookOptions, WebhookHeaders, WebhookVerificationErrorCode, } from "./webhooks.js";
+export type * from "./types.js";
+export { startFakeServer } from "./fake/server.js";
+export type { FakeServer, FakeServerOptions } from "./fake/server.js";
+export * from "./helpers/signup.js";
+export * from "./helpers/agent-bridge.js";
+export * from "./helpers/batching.js";
+export * from "./helpers/typing.js";
+export * from "./helpers/format.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public surface of @north-light/comms.
+export { CommsClient, CommsError, DEFAULT_RESOURCE } from "./client.js";
+export { WEBHOOK_TOLERANCE_SECONDS, WebhookVerificationError, sign, verifyWebhook, } from "./webhooks.js";
+export { startFakeServer } from "./fake/server.js";
+export * from "./helpers/signup.js";
+export * from "./helpers/agent-bridge.js";
+export * from "./helpers/batching.js";
+export * from "./helpers/typing.js";
+export * from "./helpers/format.js";

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/** The environments an API call can name. The local fake server ignores the field. */
+export type Environment = "test" | "production";
+/** `user:<id>` of a Northlight user. */
+export interface UserRef {
+    id: string;
+}
+export type HandleKind = "phone" | "email";
+/** A person who texted the app's numbers, as webhooks carry them. */
+export interface WebhookContact {
+    id: string;
+    /** The Northlight user behind the handle, or `null` for a non-user. */
+    user: UserRef | null;
+    handle_kind: HandleKind;
+    /** The full E.164 phone number, or the Apple ID email. */
+    handle: string;
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+export interface AttachmentContent {
+    type: "attachment";
+    /** A Comms-signed GET, valid 24 hours. */
+    url: string;
+    mime_type: string;
+    name: string;
+    size_bytes: number;
+    caption: string | null;
+}
+export interface ReactionContent {
+    type: "reaction";
+    /** An emoji; the iMessage tapbacks are ❤️ 👍 👎 😂 ‼️ ❓. */
+    reaction: string;
+    target_message_id: string;
+}
+export type MessageContent = TextContent | AttachmentContent | ReactionContent;
+export interface MessageReceivedData {
+    message_id: string;
+    /** The app number the person texted. */
+    number: string;
+    contact: WebhookContact;
+    content: MessageContent;
+    reply_to_message_id: string | null;
+    received_at: string;
+}
+/** Statuses a `message.status` event reports. */
+export type DeliveryStatus = "sent" | "delivered" | "read" | "failed" | "suppressed_opt_out";
+/** Photon's codes for a `failed` status; any other Photon error code arrives verbatim. */
+export type FailureReason = "dailyLimitExceeded" | "recipientLimitExceeded" | "sendReceiveRatioExceeded" | (string & {});
+export interface MessageStatusData {
+    message_id: string;
+    contact_id: string;
+    status: DeliveryStatus;
+    /** Set for `failed`. */
+    reason: FailureReason | null;
+}
+export interface ContactIdData {
+    contact_id: string;
+}
+export interface ContactUserLinkedData {
+    contact_id: string;
+    user: UserRef;
+}
+interface WebhookEnvelope<Type extends string, Data> {
+    /** Unique per event; deliveries are at least once, so deduplicate on it. */
+    id: string;
+    type: Type;
+    environment: Environment;
+    occurred_at: string;
+    data: Data;
+}
+export type MessageReceivedEvent = WebhookEnvelope<"message.received", MessageReceivedData>;
+export type MessageStatusEvent = WebhookEnvelope<"message.status", MessageStatusData>;
+export type ContactOptedOutEvent = WebhookEnvelope<"contact.opted_out", ContactIdData>;
+export type ContactOptedInEvent = WebhookEnvelope<"contact.opted_in", ContactIdData>;
+export type ContactUserLinkedEvent = WebhookEnvelope<"contact.user_linked", ContactUserLinkedData>;
+/** The person's account was deleted: the contact id is retired and sends to it answer 404. */
+export type ContactDeletedEvent = WebhookEnvelope<"contact.deleted", ContactIdData>;
+export type WebhookEvent = MessageReceivedEvent | MessageStatusEvent | ContactOptedOutEvent | ContactOptedInEvent | ContactUserLinkedEvent | ContactDeletedEvent;
+export type WebhookEventType = WebhookEvent["type"];
+/** Address a person by contact id or Northlight user id, never by a raw phone number. */
+export type MessageRecipient = {
+    contact_id: string;
+} | {
+    user_id: string;
+};
+export interface SendMessageFile {
+    /** Fetched by Comms; at most 100 MiB. */
+    url: string;
+    name?: string;
+}
+/** `POST /v1/messages`. `text` or `file` must be present; `text` is at most 10,000 characters. */
+export interface SendMessageRequest {
+    environment: Environment;
+    to: MessageRecipient;
+    text?: string;
+    file?: SendMessageFile;
+    reply_to_message_id?: string;
+    /** The same key for the same app and environment returns the first answer and sends nothing. */
+    idempotency_key: string;
+}
+/** `POST /v1/messages/<message_id>/reactions`. */
+export interface SendReactionRequest {
+    environment: Environment;
+    /** An emoji; the iMessage tapbacks are ❤️ 👍 👎 😂 ‼️ ❓. */
+    reaction: string;
+    idempotency_key: string;
+}
+/** `202` answer to a send or a reaction; for a reaction, `message_id` is the reaction's own id. */
+export interface QueuedMessage {
+    message_id: string;
+    status: "queued";
+}
+/** Everything `GET /v1/messages/<id>` can report, including the pre-send `queued`. */
+export type MessageStatus = "queued" | DeliveryStatus;
+export interface MessageRecord {
+    message_id: string;
+    contact_id: string;
+    status: MessageStatus;
+    reason: FailureReason | null;
+    created_at: string;
+}
+/** `POST /v1/contacts/<id>/typing`. Best effort; never queued, never retried. */
+export interface TypingRequest {
+    environment: Environment;
+    on: boolean;
+}
+/** `GET /v1/contacts/<id>`. */
+export interface Contact {
+    id: string;
+    user: UserRef | null;
+    handle_kind: HandleKind;
+    handle: string;
+    opted_out: boolean;
+    number: string | null;
+    created_at: string;
+}
+/** `POST /v1/contacts/<id>/sign-in-link`. `return_to` must be on the app's `origin_url` host. */
+export interface SignInLinkRequest {
+    environment: Environment;
+    return_to?: string;
+}
+export interface SignInLink {
+    url: string;
+    expires_at: string;
+}
+/** `GET /v1/numbers/public`. */
+export interface PublicNumber {
+    number: string;
+}
+/** Codes the send API answers with (spec "Send API: app → Comms"). */
+export type SendApiErrorCode = "contact_not_found" | "not_texted_first" | "opted_out" | "not_tester" | "idempotency_conflict" | "message_not_found" | "invalid_target" | "already_user" | "no_phone" | "environment_not_ready" | "invalid_file_url" | "invalid_request" | "unauthorized" | "not_found" | "conflict" | "rate_limited" | "server_error" | "service_unavailable";
+/**
+ * Codes the SDK itself raises when no Comms error body arrived: a network failure, a timeout,
+ * a response that is not the error envelope, or a failed directory token request (where the
+ * directory's OAuth `error`, such as `invalid_client`, is the code).
+ */
+export type ClientErrorCode = "network_error" | "timeout" | "unexpected_response" | "token_discovery_failed" | "token_request_failed";
+/** A code Comms or the directory may add later is still a string. */
+export type CommsErrorCode = SendApiErrorCode | ClientErrorCode | (string & {});
+/** The shared error envelope body, `{error: {...}}`, with `origin: "comms"`. */
+export interface ErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        type?: string;
+        origin?: string;
+        retryable?: boolean;
+        request_id?: string;
+        details?: unknown;
+        param?: string;
+        retry_after_s?: number;
+    };
+}
+export {};

package/dist/types.js

@@ -0,0 +1,3 @@
+// Wire types of Comms: the app webhook (Comms → app) and the send API (app → Comms).
+// Field names are the wire names, so a body can be passed through without mapping.
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,30 @@
+import type { WebhookEvent } from "./types.js";
+/** Deliveries older or newer than this many seconds are refused. */
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+export type WebhookVerificationErrorCode = "missing_headers" | "invalid_timestamp" | "timestamp_too_old" | "timestamp_too_new" | "no_secrets" | "invalid_secret" | "invalid_signature" | "invalid_payload";
+/** Thrown by `verifyWebhook`; `code` says which check failed. */
+export declare class WebhookVerificationError extends Error {
+    readonly code: WebhookVerificationErrorCode;
+    readonly name = "WebhookVerificationError";
+    constructor(code: WebhookVerificationErrorCode, message: string);
+}
+/** Headers as a fetch `Headers`, a Node `IncomingHttpHeaders`, or any plain record. */
+export type WebhookHeaders = Headers | Record<string, string | readonly string[] | undefined>;
+export interface VerifyWebhookOptions {
+    /** Tolerance in seconds in both directions. Default 300. */
+    toleranceSeconds?: number;
+    /** The current time, for tests. Default `Date.now()`. */
+    now?: Date | number;
+}
+/**
+ * The `webhook-signature` header value: one `v1,<base64 HMAC-SHA256>` per secret, separated by
+ * spaces, over `${id}.${timestamp}.${body}`. `timestamp` is Unix seconds.
+ */
+export declare function sign(secrets: string | readonly string[], id: string, timestamp: number | string, body: string | Uint8Array): string;
+/**
+ * Checks a delivery and returns its parsed event. Pass the raw request body exactly as it
+ * arrived (a string or bytes, not re-serialized JSON) and every secret that may have signed
+ * it. Throws `WebhookVerificationError` on any failure; respond `400` or `401` and do not
+ * process the event.
+ */
+export declare function verifyWebhook(headers: WebhookHeaders, rawBody: string | Uint8Array, secrets: string | readonly string[], options?: VerifyWebhookOptions): WebhookEvent;

package/dist/webhooks.js

@@ -0,0 +1,111 @@
+// Standard Webhooks (https://www.standardwebhooks.com/) signing and verification.
+// Comms signs every delivery with each unretired secret of the environment, so during the
+// 24-hour rotation window the `webhook-signature` header carries two signatures; verify with
+// every secret you still trust and any one match accepts the delivery.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Deliveries older or newer than this many seconds are refused. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+/** Thrown by `verifyWebhook`; `code` says which check failed. */
+export class WebhookVerificationError extends Error {
+    code;
+    name = "WebhookVerificationError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const PREFIX = "whsec_";
+function secretKey(secret) {
+    const encoded = secret.startsWith(PREFIX)
+        ? secret.slice(PREFIX.length)
+        : secret;
+    const key = Buffer.from(encoded, "base64");
+    if (key.length === 0)
+        throw new WebhookVerificationError("invalid_secret", "A webhook secret must be `whsec_` followed by base64 key bytes");
+    return key;
+}
+function toBytes(body) {
+    return typeof body === "string"
+        ? Buffer.from(body, "utf8")
+        : Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+}
+function hmac(key, id, timestamp, body) {
+    return createHmac("sha256", key)
+        .update(`${id}.${timestamp}.`)
+        .update(body)
+        .digest();
+}
+/**
+ * The `webhook-signature` header value: one `v1,<base64 HMAC-SHA256>` per secret, separated by
+ * spaces, over `${id}.${timestamp}.${body}`. `timestamp` is Unix seconds.
+ */
+export function sign(secrets, id, timestamp, body) {
+    const list = typeof secrets === "string" ? [secrets] : secrets;
+    if (list.length === 0)
+        throw new WebhookVerificationError("no_secrets", "At least one secret is required");
+    const bytes = toBytes(body);
+    const ts = String(timestamp);
+    return list
+        .map((secret) => `v1,${hmac(secretKey(secret), id, ts, bytes).toString("base64")}`)
+        .join(" ");
+}
+function header(headers, name) {
+    if (headers instanceof Headers)
+        return headers.get(name) ?? undefined;
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        if (Array.isArray(value))
+            return value.join(" ");
+        return typeof value === "string" ? value : undefined;
+    }
+    return undefined;
+}
+/**
+ * Checks a delivery and returns its parsed event. Pass the raw request body exactly as it
+ * arrived (a string or bytes, not re-serialized JSON) and every secret that may have signed
+ * it. Throws `WebhookVerificationError` on any failure; respond `400` or `401` and do not
+ * process the event.
+ */
+export function verifyWebhook(headers, rawBody, secrets, options = {}) {
+    const list = typeof secrets === "string" ? [secrets] : secrets;
+    if (list.length === 0)
+        throw new WebhookVerificationError("no_secrets", "At least one secret is required");
+    const id = header(headers, "webhook-id");
+    const timestamp = header(headers, "webhook-timestamp");
+    const signatures = header(headers, "webhook-signature");
+    if (!id || !timestamp || !signatures)
+        throw new WebhookVerificationError("missing_headers", "Missing webhook-id, webhook-timestamp or webhook-signature header");
+    if (!/^\d{1,15}$/.test(timestamp))
+        throw new WebhookVerificationError("invalid_timestamp", "webhook-timestamp must be Unix seconds");
+    const nowMs = options.now instanceof Date
+        ? options.now.getTime()
+        : (options.now ?? Date.now());
+    const skew = Math.floor(nowMs / 1000) - Number(timestamp);
+    const tolerance = options.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    if (skew > tolerance)
+        throw new WebhookVerificationError("timestamp_too_old", "Webhook timestamp is too old");
+    if (skew < -tolerance)
+        throw new WebhookVerificationError("timestamp_too_new", "Webhook timestamp is in the future");
+    const bytes = toBytes(rawBody);
+    const expected = list.map((secret) => hmac(secretKey(secret), id, timestamp, bytes));
+    // Every candidate is compared against every expected value with no early exit.
+    let matched = false;
+    for (const candidate of signatures.split(" ")) {
+        const comma = candidate.indexOf(",");
+        if (comma < 0 || candidate.slice(0, comma) !== "v1")
+            continue;
+        const given = Buffer.from(candidate.slice(comma + 1), "base64");
+        for (const want of expected)
+            if (given.length === want.length && timingSafeEqual(given, want))
+                matched = true;
+    }
+    if (!matched)
+        throw new WebhookVerificationError("invalid_signature", "No matching signature found");
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new WebhookVerificationError("invalid_payload", "Webhook body is not valid JSON");
+    }
+}