@dojocoding/whatsapp-sdk 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,1262 @@
+import { S as Storage } from './index-CDfzGvQJ.cjs';
+export { I as InMemoryStorage } from './index-CDfzGvQJ.cjs';
+import { W as WebhookReceiver, a as WhatsAppEvent } from './receiver-DWJm571Z.cjs';
+export { A as AccountAlertEvent, b as AccountReviewEvent, B as BaseEvent, D as DeliveryStatus, E as ErrorHandler, c as EventKindMap, H as HandlePayloadResult, d as Handler, I as IncomingMessageKind, M as MessageEvent, P as PhoneNumberQualityUpdateEvent, S as StatusEvent, T as TemplateCategoryUpdateEvent, e as TemplateQualityUpdateEvent, f as TemplateStatusEvent, U as UnknownEvent, V as VerifyRequestInput, g as VerifyRequestResult, h as WebhookReceiverOptions } from './receiver-DWJm571Z.cjs';
+import { Tracer, Attributes } from '@opentelemetry/api';
+
+type TemplateCategory = "MARKETING" | "UTILITY" | "AUTHENTICATION" | (string & {});
+type TemplateStatus = "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED" | "FLAGGED" | (string & {});
+type TemplateComponentDefinitionType = "HEADER" | "BODY" | "FOOTER" | "BUTTONS" | (string & {});
+interface TemplateButtonDefinition {
+    type: "QUICK_REPLY" | "URL" | "PHONE_NUMBER" | "COPY_CODE" | "OTP" | (string & {});
+    text?: string;
+    url?: string;
+    phone_number?: string;
+    example?: ReadonlyArray<string>;
+}
+interface TemplateComponentDefinition {
+    type: TemplateComponentDefinitionType;
+    /** Header format ("TEXT" | "IMAGE" | "VIDEO" | "DOCUMENT" | "LOCATION"). */
+    format?: string;
+    /** The body / header text containing `{{1}}`, `{{2}}`, … placeholders. */
+    text?: string;
+    /** Example values Meta shows in the editor. */
+    example?: {
+        body_text?: ReadonlyArray<ReadonlyArray<string>>;
+        header_text?: ReadonlyArray<string>;
+        header_handle?: ReadonlyArray<string>;
+    };
+    /** Buttons component lists buttons here (capitalised in the API). */
+    buttons?: ReadonlyArray<TemplateButtonDefinition>;
+}
+interface TemplateDefinition {
+    id: string;
+    name: string;
+    language: string;
+    category: TemplateCategory;
+    status: TemplateStatus;
+    components: ReadonlyArray<TemplateComponentDefinition>;
+    quality_score?: {
+        score: string;
+        date?: number;
+    };
+}
+interface ListTemplatesQuery {
+    name?: string;
+    language?: string;
+    status?: TemplateStatus;
+    category?: TemplateCategory;
+    limit?: number;
+    /** Cursor pagination forward. */
+    after?: string;
+    /** Cursor pagination backward. */
+    before?: string;
+}
+interface ListTemplatesPaging {
+    cursors?: {
+        after?: string;
+        before?: string;
+    };
+    next?: string;
+    previous?: string;
+}
+interface ListTemplatesResponse {
+    data: ReadonlyArray<TemplateDefinition>;
+    paging?: ListTemplatesPaging;
+}
+
+type RecipientType = "individual";
+interface BaseMessage {
+    messaging_product: "whatsapp";
+    recipient_type: RecipientType;
+    to: string;
+    context?: {
+        message_id: string;
+    };
+}
+interface TextBody {
+    body: string;
+    preview_url?: boolean;
+}
+interface TextMessage extends BaseMessage {
+    type: "text";
+    text: TextBody;
+}
+interface MediaSource {
+    /** Pre-uploaded media id from `POST /{phone-number-id}/media`. */
+    id?: string;
+    /** Public URL Meta will fetch on send. */
+    link?: string;
+    /** Image / video / document caption. Not used for audio / sticker. */
+    caption?: string;
+    /** Document filename hint. Not used for image / video / audio / sticker. */
+    filename?: string;
+}
+type MediaKind = "image" | "video" | "audio" | "document" | "sticker";
+interface ImageMessage extends BaseMessage {
+    type: "image";
+    image: Omit<MediaSource, "filename">;
+}
+interface VideoMessage extends BaseMessage {
+    type: "video";
+    video: Omit<MediaSource, "filename">;
+}
+interface AudioMessage extends BaseMessage {
+    type: "audio";
+    /**
+     * Audio body. Setting `voice: true` makes the WhatsApp client render
+     * the message as a push-to-talk voice note (with transcription
+     * support, auto-download, and a "played" status when the recipient
+     * listens) instead of a music file. Source:
+     * https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages
+     */
+    audio: Pick<MediaSource, "id" | "link"> & {
+        voice?: boolean;
+    };
+}
+interface DocumentMessage extends BaseMessage {
+    type: "document";
+    document: MediaSource;
+}
+interface StickerMessage extends BaseMessage {
+    type: "sticker";
+    sticker: Pick<MediaSource, "id" | "link">;
+}
+interface LocationBody {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+interface LocationMessage extends BaseMessage {
+    type: "location";
+    location: LocationBody;
+}
+interface ContactName {
+    formatted_name: string;
+    first_name?: string;
+    last_name?: string;
+    middle_name?: string;
+    prefix?: string;
+    suffix?: string;
+}
+interface ContactPhone {
+    phone: string;
+    type?: "HOME" | "WORK" | "CELL" | "MAIN" | "IPHONE";
+    wa_id?: string;
+}
+interface ContactEmail {
+    email: string;
+    type?: "HOME" | "WORK";
+}
+interface Contact {
+    name: ContactName;
+    phones?: ReadonlyArray<ContactPhone>;
+    emails?: ReadonlyArray<ContactEmail>;
+    org?: {
+        company?: string;
+        department?: string;
+        title?: string;
+    };
+    birthday?: string;
+}
+interface ContactsMessage extends BaseMessage {
+    type: "contacts";
+    contacts: ReadonlyArray<Contact>;
+}
+interface InteractiveHeaderText {
+    type: "text";
+    text: string;
+}
+interface InteractiveHeaderImage {
+    type: "image";
+    image: {
+        id?: string;
+        link?: string;
+    };
+}
+interface InteractiveHeaderVideo {
+    type: "video";
+    video: {
+        id?: string;
+        link?: string;
+    };
+}
+interface InteractiveHeaderDocument {
+    type: "document";
+    document: {
+        id?: string;
+        link?: string;
+        filename?: string;
+    };
+}
+type InteractiveHeader = InteractiveHeaderText | InteractiveHeaderImage | InteractiveHeaderVideo | InteractiveHeaderDocument;
+interface InteractiveButtonReply {
+    type: "reply";
+    reply: {
+        id: string;
+        title: string;
+    };
+}
+interface InteractiveButtonAction {
+    buttons: ReadonlyArray<InteractiveButtonReply>;
+}
+interface InteractiveListRow {
+    id: string;
+    title: string;
+    description?: string;
+}
+interface InteractiveListSection {
+    title: string;
+    rows: ReadonlyArray<InteractiveListRow>;
+}
+interface InteractiveListAction {
+    button: string;
+    sections: ReadonlyArray<InteractiveListSection>;
+}
+interface InteractiveCtaUrlAction {
+    name: "cta_url";
+    parameters: {
+        display_text: string;
+        url: string;
+    };
+}
+interface InteractiveButtonBody {
+    type: "button";
+    header?: InteractiveHeader;
+    body: {
+        text: string;
+    };
+    footer?: {
+        text: string;
+    };
+    action: InteractiveButtonAction;
+}
+interface InteractiveListBody {
+    type: "list";
+    header?: InteractiveHeaderText;
+    body: {
+        text: string;
+    };
+    footer?: {
+        text: string;
+    };
+    action: InteractiveListAction;
+}
+interface InteractiveCtaUrlBody {
+    type: "cta_url";
+    header?: InteractiveHeader;
+    body: {
+        text: string;
+    };
+    footer?: {
+        text: string;
+    };
+    action: InteractiveCtaUrlAction;
+}
+type InteractiveBody = InteractiveButtonBody | InteractiveListBody | InteractiveCtaUrlBody;
+interface InteractiveMessage extends BaseMessage {
+    type: "interactive";
+    interactive: InteractiveBody;
+}
+interface TemplateLanguage {
+    code: string;
+    policy?: "deterministic";
+}
+interface TemplateParameterText {
+    type: "text";
+    text: string;
+}
+interface TemplateParameterCurrency {
+    type: "currency";
+    currency: {
+        fallback_value: string;
+        code: string;
+        amount_1000: number;
+    };
+}
+interface TemplateParameterDateTime {
+    type: "date_time";
+    date_time: {
+        fallback_value: string;
+    };
+}
+interface TemplateParameterImage {
+    type: "image";
+    image: {
+        id?: string;
+        link?: string;
+    };
+}
+interface TemplateParameterVideo {
+    type: "video";
+    video: {
+        id?: string;
+        link?: string;
+    };
+}
+interface TemplateParameterDocument {
+    type: "document";
+    document: {
+        id?: string;
+        link?: string;
+        filename?: string;
+    };
+}
+/**
+ * Limited-time-offer parameter (paired with a `type: "limited_time_offer"`
+ * component). `expiration_time_ms` is Unix epoch milliseconds. Source:
+ * https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/limited-time-offer-templates/
+ */
+interface TemplateParameterLimitedTimeOffer {
+    type: "limited_time_offer";
+    limited_time_offer: {
+        expiration_time_ms: number;
+    };
+}
+/**
+ * Coupon-code parameter (paired with a `sub_type: "copy_code"` button).
+ * Source: same Meta doc as `TemplateParameterLimitedTimeOffer`.
+ */
+interface TemplateParameterCouponCode {
+    type: "coupon_code";
+    coupon_code: string;
+}
+/**
+ * Payload parameter for `sub_type: "quick_reply"` buttons (used inside
+ * carousel cards). Source:
+ * https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/media-card-carousel-templates/
+ */
+interface TemplateParameterPayload {
+    type: "payload";
+    payload: string;
+}
+type TemplateParameter = TemplateParameterText | TemplateParameterCurrency | TemplateParameterDateTime | TemplateParameterImage | TemplateParameterVideo | TemplateParameterDocument | TemplateParameterLimitedTimeOffer | TemplateParameterCouponCode | TemplateParameterPayload;
+/**
+ * A single carousel card. The `card_index` is 0-based and assigned by
+ * the builder, never by the caller. Per Meta's docs the card's
+ * `components` array contains a required `header` plus optional
+ * `body` and `button` sub-components.
+ */
+interface CarouselCardComponent {
+    card_index: number;
+    components: ReadonlyArray<TemplateComponent>;
+}
+interface TemplateComponent {
+    type: "header" | "body" | "button" | "footer" | "carousel" | "limited_time_offer";
+    sub_type?: "quick_reply" | "url" | "copy_code";
+    /**
+     * Meta's docs use a string for auth-template buttons (`"0"`) and a
+     * number for carousel-card buttons (`0`). Both work at the API; we
+     * mirror what Meta publishes so reviewers can diff without mental
+     * conversion.
+     */
+    index?: string | number;
+    parameters?: ReadonlyArray<TemplateParameter>;
+    /** Only set when `type === "carousel"`. */
+    cards?: ReadonlyArray<CarouselCardComponent>;
+}
+interface TemplateBody {
+    name: string;
+    language: TemplateLanguage;
+    components?: ReadonlyArray<TemplateComponent>;
+}
+interface TemplateMessage extends BaseMessage {
+    type: "template";
+    template: TemplateBody;
+}
+interface ReactionBody {
+    message_id: string;
+    emoji: string;
+}
+interface ReactionMessage extends BaseMessage {
+    type: "reaction";
+    reaction: ReactionBody;
+}
+type WhatsAppMessage = TextMessage | ImageMessage | VideoMessage | AudioMessage | DocumentMessage | StickerMessage | LocationMessage | ContactsMessage | InteractiveMessage | TemplateMessage | ReactionMessage;
+interface MessageSendResponseContact {
+    input: string;
+    wa_id: string;
+}
+interface MessageSendResponseMessage {
+    id: string;
+    message_status?: string;
+}
+interface MessageSendResponse {
+    messaging_product: "whatsapp";
+    contacts: ReadonlyArray<MessageSendResponseContact>;
+    messages: ReadonlyArray<MessageSendResponseMessage>;
+}
+
+interface BuildTextInput {
+    to: string;
+    body: string;
+    previewUrl?: boolean;
+    replyTo?: string;
+}
+declare function buildText(input: BuildTextInput): TextMessage;
+interface BuildMediaInput {
+    to: string;
+    id?: string;
+    link?: string;
+    caption?: string;
+    filename?: string;
+    replyTo?: string;
+}
+declare function buildImage(input: BuildMediaInput): ImageMessage;
+declare function buildVideo(input: BuildMediaInput): VideoMessage;
+declare function buildAudio(input: BuildMediaInput): AudioMessage;
+declare function buildDocument(input: BuildMediaInput): DocumentMessage;
+declare function buildSticker(input: BuildMediaInput): StickerMessage;
+interface BuildLocationInput {
+    to: string;
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+    replyTo?: string;
+}
+declare function buildLocation(input: BuildLocationInput): LocationMessage;
+interface BuildContactsInput {
+    to: string;
+    contacts: Contact | ReadonlyArray<Contact>;
+    replyTo?: string;
+}
+declare function buildContacts(input: BuildContactsInput): ContactsMessage;
+interface BuildInteractiveButtonInput {
+    to: string;
+    header?: InteractiveHeader;
+    body: string;
+    footer?: string;
+    buttons: ReadonlyArray<{
+        id: string;
+        title: string;
+    }>;
+    replyTo?: string;
+}
+declare function buildInteractiveButton(input: BuildInteractiveButtonInput): InteractiveMessage;
+interface BuildInteractiveListInput {
+    to: string;
+    header?: {
+        type: "text";
+        text: string;
+    };
+    body: string;
+    footer?: string;
+    button: string;
+    sections: ReadonlyArray<InteractiveListSection>;
+    replyTo?: string;
+}
+declare function buildInteractiveList(input: BuildInteractiveListInput): InteractiveMessage;
+interface BuildInteractiveCtaUrlInput {
+    to: string;
+    header?: InteractiveHeader;
+    body: string;
+    footer?: string;
+    cta: {
+        displayText: string;
+        url: string;
+    };
+    replyTo?: string;
+}
+declare function buildInteractiveCtaUrl(input: BuildInteractiveCtaUrlInput): InteractiveMessage;
+type BuildInteractiveInput = ({
+    kind: "button";
+} & BuildInteractiveButtonInput) | ({
+    kind: "list";
+} & BuildInteractiveListInput) | ({
+    kind: "cta_url";
+} & BuildInteractiveCtaUrlInput);
+declare function buildInteractive(input: BuildInteractiveInput): InteractiveMessage;
+interface BuildTemplateInput {
+    to: string;
+    name: string;
+    language: string;
+    components?: ReadonlyArray<TemplateComponent>;
+    replyTo?: string;
+    /**
+     * Optional approved-template definition to cross-validate against
+     * before building. When supplied, parameter counts and component
+     * shapes are checked locally and `TemplateError` is thrown on
+     * mismatch, avoiding the wasted HTTP round-trip to Meta.
+     */
+    validateAgainst?: TemplateDefinition;
+}
+declare function buildTemplate(input: BuildTemplateInput): TemplateMessage;
+interface BuildReactionInput {
+    to: string;
+    messageId: string;
+    /** Empty string clears a previously set reaction. */
+    emoji: string;
+    replyTo?: string;
+}
+declare function buildReaction(input: BuildReactionInput): ReactionMessage;
+interface BuildAuthTemplateInput {
+    to: string;
+    /** Template name (case-sensitive, must exist as APPROVED in your WABA). */
+    name: string;
+    /** BCP-47 language code — must match the approved template's language. */
+    language: string;
+    /**
+     * The one-time password / verification code. Meta caps this at 15
+     * characters. Appears in BOTH the body and URL-button parameters of
+     * the documented wire payload — the builder duplicates it for you.
+     */
+    otp: string;
+    /**
+     * Index of the URL button on the approved template. Defaults to `"0"`
+     * (matches Meta's documented example). Override only if your approved
+     * template has the OTP button at a non-zero position.
+     */
+    otpButtonIndex?: string | number;
+    replyTo?: string;
+}
+/**
+ * Build an authentication-template (OTP) send payload. The wire shape
+ * matches Meta's documented copy-code button authentication template
+ * payload at
+ * https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/copy-code-button-authentication-templates/.
+ *
+ * The same wire shape applies to one-tap autofill and zero-tap
+ * authentication templates — the subtype distinction lives at template
+ * creation time (Meta Business Manager / the templates API), not at
+ * send time.
+ *
+ * The OTP code appears in BOTH the body component's `text` parameter
+ * AND the URL button component's `text` parameter. This is Meta's
+ * documented requirement, not an SDK quirk; the builder duplicates the
+ * code so consumers don't have to remember to pass it twice.
+ */
+declare function buildAuthTemplate(input: BuildAuthTemplateInput): TemplateMessage;
+interface BuildVoiceInput {
+    to: string;
+    /** Pre-uploaded media id from `POST /{phone-number-id}/media`. Exactly one of `id` / `link` must be supplied. */
+    id?: string;
+    /** Public URL Meta will fetch on send. Exactly one of `id` / `link` must be supplied. */
+    link?: string;
+    replyTo?: string;
+}
+/**
+ * Build a voice-note send payload — an audio message with the
+ * `voice: true` flag set. Source:
+ * https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages
+ *
+ * Setting `voice: true` triggers transcription support, auto-download,
+ * and a "played" delivery status when the recipient listens. Without
+ * the flag the same media renders as a regular audio file with the
+ * music-player UI.
+ *
+ * The media payload (`.ogg` with OPUS codec is recommended) is supplied
+ * the same way as for `buildAudio` — either a pre-uploaded media id or
+ * a public link.
+ */
+declare function buildVoice(input: BuildVoiceInput): AudioMessage;
+interface CarouselCardMediaHeader {
+    type: "image" | "video";
+    /** Pre-uploaded media id. Exactly one of `mediaId` / `link` must be supplied. */
+    mediaId?: string;
+    /** Public link. Exactly one of `mediaId` / `link` must be supplied. */
+    link?: string;
+}
+type CarouselCardButton = {
+    subType: "quick_reply";
+    payload: string;
+} | {
+    subType: "url";
+    text: string;
+};
+interface CarouselCard {
+    /** Image or video header for this card (required by Meta). */
+    header: CarouselCardMediaHeader;
+    /** Body-text variable substitutions for this card's approved-template body. */
+    bodyParameters?: ReadonlyArray<string>;
+    /**
+     * Up to two buttons per card (Meta cap). Order matters — the index
+     * in the wire payload is the position in this array.
+     */
+    buttons?: ReadonlyArray<CarouselCardButton>;
+}
+interface BuildCarouselTemplateInput {
+    to: string;
+    name: string;
+    language: string;
+    /** Top-level body-text variable substitutions for the carousel's leading body component. */
+    bodyParameters?: ReadonlyArray<string>;
+    cards: ReadonlyArray<CarouselCard>;
+    replyTo?: string;
+}
+/**
+ * Build a media-card carousel template send payload. The wire shape
+ * matches Meta's documented payload at
+ * https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/media-card-carousel-templates/.
+ *
+ * Cards are bounded to 1–10 per Meta's documented maximum. Each card's
+ * `card_index` is computed from its position in the input array so
+ * consumers cannot misorder it.
+ */
+declare function buildCarouselTemplate(input: BuildCarouselTemplateInput): TemplateMessage;
+
+declare const GRAPH_API_VERSION: "v25.0";
+declare const META_GRAPH_BASE_URL: "https://graph.facebook.com";
+declare const WEBHOOK_ACK_DEADLINE_MS: 30000;
+declare const WINDOW_TTL_MS: number;
+declare const WEBHOOK_DEDUPE_TTL_MS: number;
+type GraphApiVersion = typeof GRAPH_API_VERSION | `v${number}.${number}`;
+
+interface WindowTrackerOptions {
+    /** The phone number id this tracker scopes its keys to. */
+    phoneNumberId: string;
+    /** Async key/value store. Use `InMemoryStorage` for dev, BYO Redis for prod. */
+    storage: Storage;
+    /** Window TTL in milliseconds. Defaults to {@link WINDOW_TTL_MS} (24h). */
+    ttlMs?: number;
+}
+/**
+ * 24-hour customer-service-window tracker. Records the most recent inbound
+ * timestamp per `customerWaId`, scoped to a single `phoneNumberId`, and
+ * exposes `isWindowOpen` for pre-flight checks on outbound free-form
+ * sends.
+ *
+ * Wire it from your inbound handler:
+ *   receiver.on("message", (e) => tracker.notifyInbound(e.from));
+ *
+ * And from your outbound client:
+ *   const client = new WhatsAppClient({ ..., windowTracker: tracker });
+ */
+declare class WindowTracker {
+    #private;
+    readonly phoneNumberId: string;
+    constructor(options: WindowTrackerOptions);
+    get ttlMs(): number;
+    notifyInbound(customerWaId: string, _atMs?: number): Promise<void>;
+    isWindowOpen(customerWaId: string): Promise<boolean>;
+    /** @internal — exposed so consumers can clear a window after a hard error. */
+    clear(customerWaId: string): Promise<void>;
+}
+
+interface RetryPolicy {
+    /** Total attempts including the first call. */
+    maxAttempts: number;
+    /** Base delay used as the seed for exponential backoff. */
+    baseDelayMs: number;
+    /** Hard cap on any single delay. */
+    maxDelayMs: number;
+    /** Jitter strategy. Only "full" is supported in v1. */
+    jitter: "full";
+    /** Lower bound on every delay (avoids 0-ms hammering when jitter rolls 0). */
+    floorMs: number;
+}
+declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Marker thrown by callers (or the transport layer) to signal a transient
+ * HTTP failure that should be retried. Carries optional Retry-After hint
+ * derived from the response headers.
+ */
+declare class TransientHttpError extends Error {
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, retryAfterMs?: number);
+}
+interface RetryHooks {
+    /** Optional sleep injection — in tests we pass a `vi.advanceTimersByTime`-friendly stub. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Optional RNG injection for deterministic jitter testing. Returns a value in [0, 1). */
+    random?: () => number;
+}
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+interface RequestOptions {
+    /** Override the default retry policy for this call. */
+    retryPolicy?: RetryPolicy;
+    /** Test hooks; never set in production. */
+    retryHooks?: RetryHooks;
+    /** Per-call AbortSignal; cancellation is treated as a retryable error. */
+    signal?: AbortSignal;
+    /**
+     * Override the resolved Graph API version for this call (rare — only
+     * useful for cross-version migrations).
+     */
+    graphApiVersion?: string;
+    /**
+     * Optional caller-provided idempotency key. When omitted, the SDK
+     * generates a fresh UUID v4 per logical call and reuses it across
+     * retry attempts of that call. Sent as `X-Dojo-Idempotency-Key`.
+     *
+     * Meta does NOT honour this header — a retry of `POST /messages`
+     * creates a new send. The key is for client-side correlation only
+     * (internal logs, parity replays in the mock, future replay-buffering).
+     * See `docs/compliance.md` § 3.4.
+     */
+    idempotencyKey?: string;
+    /** Override fetch implementation — internal hook used by tests. */
+    fetchImpl?: typeof fetch;
+}
+
+interface TokenInfo {
+    /** Whether Meta considers the token currently usable. */
+    valid: boolean;
+    /**
+     * Token expiration, expressed as Unix epoch milliseconds. `null` when
+     * Meta returns 0 or omits the field (some long-lived tokens never expire).
+     */
+    expiresAt: number | null;
+    appId: string | null;
+    userId: string | null;
+    scopes: ReadonlyArray<string>;
+}
+
+/**
+ * Resolves the bearer token used for Graph API requests. Invoked
+ * exactly once per outer `request()` call; the resolved value is used
+ * for all retry attempts within that request. Throw, return an empty
+ * string, or return a non-string value to surface as `AuthenticationError`
+ * before the HTTP request is made.
+ *
+ * Use this shape when tokens rotate (System User expiry, manual
+ * rotation in Business Manager, refresh after a 401). The SDK does
+ * NOT cache the resolved value across requests; cache inside your
+ * callback if needed.
+ */
+type TokenProvider = () => string | Promise<string>;
+interface WhatsAppClientOptions {
+    /** Phone number ID for the WhatsApp Business phone (Graph API: /{phone-number-id}/messages). */
+    phoneNumberId: string;
+    /** WhatsApp Business Account ID (Graph API: /{waba-id}/message_templates). */
+    wabaId: string;
+    /**
+     * Long-lived BISU or System User token, or a `TokenProvider` callback
+     * that resolves one per request. Callback shape supports rotation
+     * without swapping the client instance.
+     */
+    token: string | TokenProvider;
+    /** App secret used to verify HMAC-SHA256 signatures on inbound webhooks. */
+    appSecret: string;
+    /** Optional override for the pinned Graph API version (default: GRAPH_API_VERSION). */
+    graphApiVersion?: GraphApiVersion;
+    /**
+     * Optional 24h-window tracker. When provided, free-form sends
+     * (sendText, sendMedia*, sendLocation, sendContacts, sendInteractive)
+     * pre-flight-check the tracker and throw `WindowClosedError` before
+     * issuing any HTTP request. `sendTemplate` and `sendReaction` are
+     * window-exempt and never consult the tracker.
+     */
+    windowTracker?: WindowTracker;
+}
+declare class WhatsAppClient {
+    #private;
+    readonly phoneNumberId: string;
+    readonly wabaId: string;
+    readonly graphApiVersion: GraphApiVersion;
+    constructor(options: WhatsAppClientOptions);
+    /**
+     * Whether the 24h customer-service window is currently open for `to`.
+     * Returns `true` when no window tracker is configured (preserving the
+     * pre-Phase-4 "ungated" behaviour); otherwise delegates to the tracker.
+     */
+    isWindowOpen(to: string): Promise<boolean>;
+    /**
+     * @internal — exposed for capability slices that need the bearer
+     * token. Resolves the configured `TokenProvider` exactly once per
+     * call; surfaces provider failures as `AuthenticationError` before
+     * the HTTP request is made.
+     */
+    _resolveBearerToken(): Promise<string>;
+    /** @internal — exposed for the webhook receiver capability (Phase 3). */
+    _getAppSecret(): string;
+    /**
+     * Issue an authenticated Graph API request.
+     *
+     * @internal — public-API surface for sends, templates, etc. lands in
+     * later phases (Phase 2 message-builders, Phase 5 template-management).
+     */
+    request<T>(method: HttpMethod, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Verify the bearer token via Meta's `/debug_token` endpoint.
+     *
+     * Resolves with the parsed token info; throws `WhatsAppError` if the
+     * token is invalid or the call fails.
+     */
+    healthCheck(options?: RequestOptions): Promise<TokenInfo>;
+    sendText(input: BuildTextInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendImage(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendVideo(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendAudio(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendDocument(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendSticker(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendLocation(input: BuildLocationInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendContacts(input: BuildContactsInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendInteractive(input: BuildInteractiveInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    /**
+     * Window-exempt: templates are the escape hatch when the window is closed.
+     * Async so any synchronous error from `buildTemplate` (e.g.,
+     * `validateAgainst` mismatch) surfaces as a rejected promise rather
+     * than a synchronous throw.
+     */
+    sendTemplate(input: BuildTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    /** Window-exempt: authentication templates are the canonical out-of-window send. */
+    sendAuthTemplate(input: BuildAuthTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    /**
+     * Send a voice note (audio with `voice: true`). Window-gated like
+     * any other free-form media send. Voice notes trigger transcription
+     * support, auto-download, and a "played" status when the recipient
+     * listens.
+     */
+    sendVoice(input: BuildVoiceInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    /** Window-exempt: carousel sends are template sends. */
+    sendCarouselTemplate(input: BuildCarouselTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    listTemplates(query?: ListTemplatesQuery, options?: RequestOptions): Promise<ListTemplatesResponse>;
+    getTemplate(templateId: string, options?: RequestOptions): Promise<TemplateDefinition>;
+    /** Window-exempt: reactions are part of an existing thread. */
+    sendReaction(input: BuildReactionInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    /**
+     * Send any pre-built `WhatsAppMessage` payload as a reply to a previous
+     * message identified by its wamid. Sets `context.message_id` and posts.
+     * Window-gated for non-template, non-reaction payloads.
+     */
+    sendReply(replyTo: string, payload: WhatsAppMessage, options?: RequestOptions): Promise<MessageSendResponse>;
+}
+
+/**
+ * POST a fully-built `WhatsAppMessage` payload to `/{phoneNumberId}/messages`.
+ * Returns the parsed response body (`{ messaging_product, contacts, messages }`).
+ */
+declare function sendMessage(client: WhatsAppClient, payload: WhatsAppMessage, options?: RequestOptions): Promise<MessageSendResponse>;
+
+type WhatsAppErrorCode = "MISSING_CREDENTIALS" | "RATE_LIMIT" | "WINDOW_CLOSED" | "WEBHOOK_SIGNATURE" | "TEMPLATE" | "MOCK_MODE" | "AUTHENTICATION" | "PERMISSION" | "CAPABILITY" | "UNKNOWN";
+interface WhatsAppErrorOptions {
+    cause?: unknown;
+}
+declare class WhatsAppError extends Error {
+    readonly code: WhatsAppErrorCode;
+    constructor(code: WhatsAppErrorCode, message: string, options?: WhatsAppErrorOptions);
+    toJSON(): {
+        name: string;
+        code: WhatsAppErrorCode;
+        message: string;
+    };
+}
+type CredentialField = "phoneNumberId" | "wabaId" | "token" | "appSecret";
+declare class MissingCredentialsError extends WhatsAppError {
+    readonly code: "MISSING_CREDENTIALS";
+    readonly missingFields: ReadonlyArray<CredentialField>;
+    constructor(missingFields: ReadonlyArray<CredentialField>, options?: WhatsAppErrorOptions);
+    toJSON(): {
+        name: string;
+        code: "MISSING_CREDENTIALS";
+        message: string;
+        missingFields: ReadonlyArray<CredentialField>;
+    };
+}
+interface RateLimitErrorMeta {
+    /** Meta error code (e.g., 131056, 130429, 131048). */
+    metaCode?: number;
+    /** Retry hint in milliseconds, derived from headers or backoff. */
+    retryAfterMs?: number;
+}
+declare class RateLimitError extends WhatsAppError {
+    readonly code: "RATE_LIMIT";
+    readonly metaCode: number | undefined;
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, meta?: RateLimitErrorMeta, options?: WhatsAppErrorOptions);
+}
+declare class WindowClosedError extends WhatsAppError {
+    readonly code: "WINDOW_CLOSED";
+    readonly customerWaId: string;
+    constructor(customerWaId: string, options?: WhatsAppErrorOptions);
+}
+declare class WebhookSignatureError extends WhatsAppError {
+    readonly code: "WEBHOOK_SIGNATURE";
+    constructor(message?: string, options?: WhatsAppErrorOptions);
+}
+declare class TemplateError extends WhatsAppError {
+    readonly code: "TEMPLATE";
+    readonly templateName: string | undefined;
+    constructor(message: string, templateName?: string, options?: WhatsAppErrorOptions);
+}
+declare class MockModeError extends WhatsAppError {
+    readonly code: "MOCK_MODE";
+    constructor(message: string, options?: WhatsAppErrorOptions);
+}
+interface AuthenticationErrorMeta {
+    /** Meta error code (typically 190). */
+    metaCode?: number;
+    /** Meta error_subcode (e.g. 463 expired, 467 invalid, 492 changed). */
+    subcode?: number;
+}
+declare class AuthenticationError extends WhatsAppError {
+    readonly code: "AUTHENTICATION";
+    readonly metaCode: number | undefined;
+    readonly subcode: number | undefined;
+    constructor(message: string, meta?: AuthenticationErrorMeta, options?: WhatsAppErrorOptions);
+}
+interface PermissionErrorMeta {
+    /** Meta error code (200, 210, 230, 294, or 299 in v1). */
+    metaCode?: number;
+}
+declare class PermissionError extends WhatsAppError {
+    readonly code: "PERMISSION";
+    readonly metaCode: number | undefined;
+    constructor(message: string, meta?: PermissionErrorMeta, options?: WhatsAppErrorOptions);
+}
+interface CapabilityErrorMeta {
+    /** Meta error code (typically 100). */
+    metaCode?: number;
+}
+declare class CapabilityError extends WhatsAppError {
+    readonly code: "CAPABILITY";
+    readonly metaCode: number | undefined;
+    constructor(message: string, meta?: CapabilityErrorMeta, options?: WhatsAppErrorOptions);
+}
+
+/**
+ * Shared interface satisfied by both `WhatsAppClient` and
+ * `MockWhatsAppClient`. Consumer code that only needs send capability
+ * can take this union and run uniformly against either backend.
+ */
+interface WhatsAppLikeClient {
+    readonly phoneNumberId: string;
+    readonly wabaId: string;
+    readonly graphApiVersion: GraphApiVersion;
+    isWindowOpen(to: string): Promise<boolean>;
+    sendText(input: BuildTextInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendImage(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendVideo(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendAudio(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendDocument(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendSticker(input: BuildMediaInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendLocation(input: BuildLocationInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendContacts(input: BuildContactsInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendInteractive(input: BuildInteractiveInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendTemplate(input: BuildTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendAuthTemplate(input: BuildAuthTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendVoice(input: BuildVoiceInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendCarouselTemplate(input: BuildCarouselTemplateInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendReaction(input: BuildReactionInput, options?: RequestOptions): Promise<MessageSendResponse>;
+    sendReply(replyTo: string, payload: WhatsAppMessage, options?: RequestOptions): Promise<MessageSendResponse>;
+    listTemplates(query?: ListTemplatesQuery, options?: RequestOptions): Promise<ListTemplatesResponse>;
+    getTemplate(templateId: string, options?: RequestOptions): Promise<TemplateDefinition>;
+}
+/** A single send recorded by the mock client. */
+interface RecordedSend {
+    wamid: string;
+    payload: WhatsAppMessage;
+    sentAt: number;
+}
+interface MockWhatsAppClientOptions {
+    phoneNumberId: string;
+    wabaId: string;
+    graphApiVersion?: GraphApiVersion;
+    windowTracker?: WindowTracker;
+    /** Optional clock injection (defaults to Date.now). */
+    now?: () => number;
+    /**
+     * Optional template registry. When supplied, `listTemplates(query?)`
+     * filters the seed in memory and `getTemplate(id)` resolves with the
+     * matching entry. When omitted, the mock preserves the v1 behaviour:
+     * `listTemplates` → `{ data: [] }` and `getTemplate` rejects.
+     */
+    templates?: ReadonlyArray<TemplateDefinition>;
+}
+
+/**
+ * In-memory implementation of `WhatsAppLikeClient`. Records every send
+ * as a `RecordedSend`, generates deterministic `wamid.mock-${counter}`
+ * ids, and never touches the network.
+ *
+ * Honours the same `windowTracker` gate as the real client.
+ */
+declare class MockWhatsAppClient implements WhatsAppLikeClient {
+    #private;
+    readonly phoneNumberId: string;
+    readonly wabaId: string;
+    readonly graphApiVersion: GraphApiVersion;
+    constructor(options: MockWhatsAppClientOptions);
+    get sentMessages(): ReadonlyArray<RecordedSend>;
+    reset(): void;
+    isWindowOpen(to: string): Promise<boolean>;
+    /**
+     * Synthesise a webhook event into a `WebhookReceiver`. Bypasses
+     * signature verification — the receiver dispatches handlers directly.
+     */
+    simulateInbound(receiver: WebhookReceiver, event: WhatsAppEvent): Promise<void>;
+    sendText(input: BuildTextInput): Promise<MessageSendResponse>;
+    sendImage(input: BuildMediaInput): Promise<MessageSendResponse>;
+    sendVideo(input: BuildMediaInput): Promise<MessageSendResponse>;
+    sendAudio(input: BuildMediaInput): Promise<MessageSendResponse>;
+    sendDocument(input: BuildMediaInput): Promise<MessageSendResponse>;
+    sendSticker(input: BuildMediaInput): Promise<MessageSendResponse>;
+    sendLocation(input: BuildLocationInput): Promise<MessageSendResponse>;
+    sendContacts(input: BuildContactsInput): Promise<MessageSendResponse>;
+    sendInteractive(input: BuildInteractiveInput): Promise<MessageSendResponse>;
+    sendTemplate(input: BuildTemplateInput): Promise<MessageSendResponse>;
+    sendAuthTemplate(input: BuildAuthTemplateInput): Promise<MessageSendResponse>;
+    sendVoice(input: BuildVoiceInput): Promise<MessageSendResponse>;
+    sendCarouselTemplate(input: BuildCarouselTemplateInput): Promise<MessageSendResponse>;
+    sendReaction(input: BuildReactionInput): Promise<MessageSendResponse>;
+    sendReply(replyTo: string, payload: WhatsAppMessage): Promise<MessageSendResponse>;
+    listTemplates(query?: ListTemplatesQuery, _options?: RequestOptions): Promise<ListTemplatesResponse>;
+    getTemplate(templateId: string, _options?: RequestOptions): Promise<TemplateDefinition>;
+}
+
+interface PickWhatsAppClientOptions extends WhatsAppClientOptions {
+    /** Force the real client even when WHATSAPP_MODE=mock is set. */
+    forceReal?: boolean;
+    /** Force the mock client regardless of env. */
+    forceMock?: boolean;
+    /**
+     * Optional template registry — only used when the factory routes to the
+     * mock backend. Forwarded to `MockWhatsAppClient` as `options.templates`.
+     * Ignored by the real client.
+     */
+    templates?: ReadonlyArray<TemplateDefinition>;
+}
+/**
+ * Choose between the real `WhatsAppClient` and `MockWhatsAppClient`
+ * based on `process.env.WHATSAPP_MODE`. Optional `forceReal` /
+ * `forceMock` overrides take precedence over env detection.
+ *
+ * Returns the shared `WhatsAppLikeClient` interface so consumer code
+ * runs uniformly against either implementation.
+ */
+declare function pickWhatsAppClient(options: PickWhatsAppClientOptions): WhatsAppLikeClient;
+
+/**
+ * Set the salt used by `hashPhoneNumberId` (and friends) for PII redaction.
+ * Production deployments SHOULD set this once at boot to a per-environment
+ * value so spans across runs / replicas correlate consistently within an
+ * environment but differ across environments.
+ */
+declare function setRedactSalt(salt: string): void;
+/**
+ * Stable, salted SHA-256 hash truncated to 16 lowercase-hex characters.
+ * Suitable for tagging OTel spans without leaking the raw phone number id.
+ *
+ * Runtime-portable: uses `crypto.subtle.digest("SHA-256", ...)` so the
+ * function runs unmodified on Node ≥ 20, Cloudflare Workers, Bun, Deno,
+ * and any WinterCG runtime.
+ */
+declare function hashPhoneNumberId(value: string): Promise<string>;
+
+/**
+ * Convenience accessor for the SDK's tracer. When no provider is
+ * registered (default), the OTel API returns a no-op tracer and the
+ * spans we emit are silent.
+ */
+declare function getTracer(): Tracer;
+/**
+ * Run `fn` inside an active OTel span. Applies `attributes` on start,
+ * records exceptions, sets the span's status to ERROR on rejection,
+ * and ends the span exactly once. Returns whatever `fn` resolves with.
+ */
+declare function withSpan<T>(name: string, fn: () => Promise<T>, attributes?: Attributes): Promise<T>;
+
+interface TokenBucketOptions {
+    /** Maximum number of tokens the bucket holds. */
+    capacity: number;
+    /** Refill rate in tokens per millisecond (e.g. `80 / 1000` for 80 MPS). */
+    refillPerMs: number;
+    /** Optional clock injection (defaults to `Date.now`). */
+    now?: () => number;
+}
+/**
+ * Continuous-refill token bucket. `acquire(count)` resolves
+ * immediately when enough tokens are available; otherwise waits
+ * (via `setTimeout`) until refill produces enough. Concurrent
+ * `acquire` calls on an empty bucket are serialised so two callers
+ * never consume the same refilled token.
+ *
+ * No background timer is scheduled; refill is computed lazily on
+ * access. Safe to construct and discard.
+ */
+declare class TokenBucket {
+    #private;
+    constructor(options: TokenBucketOptions);
+    /** Current token count after applying any pending refill. Pure read. */
+    peek(): number;
+    /** Last access timestamp (epoch ms). Used by `BucketMap` eviction. */
+    lastAccessAt(): number;
+    /** Whether the bucket currently has its full capacity worth of tokens. */
+    isFull(): boolean;
+    /**
+     * Acquire `count` tokens. Resolves once the tokens are reserved
+     * for this caller. Concurrent acquires queue behind the previous
+     * waiter so the refill is consumed in arrival order.
+     */
+    acquire(count?: number): Promise<void>;
+}
+
+interface BucketMapOptions extends TokenBucketOptions {
+    /**
+     * Buckets at full capacity AND idle for at least this many
+     * milliseconds are evicted opportunistically on the next
+     * `acquire`. Defaults to 60_000 (1 minute).
+     */
+    evictAfterMs?: number;
+}
+/**
+ * Lazily-created map of `TokenBucket`s, keyed by an arbitrary
+ * string. Buckets that have been full and idle for `evictAfterMs`
+ * are dropped on the next `acquire` sweep so the map doesn't grow
+ * unbounded under fanout workloads.
+ *
+ * No background timer is scheduled; eviction is opportunistic.
+ */
+declare class BucketMap {
+    #private;
+    constructor(options: BucketMapOptions);
+    acquire(key: string, count?: number): Promise<void>;
+    size(): number;
+}
+
+interface RateLimitOptions {
+    /**
+     * Per-pair (sender phone_number_id × recipient) ceiling.
+     * Defaults to `{ messages: 1, per: 6_000 }` — Meta's documented
+     * limit for unsolicited free-form sends.
+     */
+    perPair?: {
+        messages: number;
+        per: number;
+    };
+    /**
+     * Per-WABA ceiling. Defaults to `{ mps: 80 }`, the verified-tier
+     * starting limit. Raise as Meta grants higher tiers.
+     */
+    perWaba?: {
+        mps: number;
+    };
+    /** Optional clock injection for deterministic testing. */
+    now?: () => number;
+    /**
+     * Idle-eviction window for per-pair buckets. Buckets at full
+     * capacity AND idle for ≥ this many ms are dropped. Default
+     * 60_000.
+     */
+    evictAfterMs?: number;
+}
+/**
+ * Decorate any `WhatsAppLikeClient` with two token-bucket rate
+ * limiters so outbound sends respect Meta's per-pair and per-WABA
+ * ceilings before issuing the HTTP request.
+ *
+ * The returned client has the same shape as the input. Non-send
+ * methods (`isWindowOpen`, `listTemplates`, `getTemplate`) pass
+ * through unchanged.
+ */
+declare function withRateLimit(client: WhatsAppLikeClient, options?: RateLimitOptions): WhatsAppLikeClient;
+
+/**
+ * GET /{wabaId}/message_templates — list approved templates for a WABA.
+ * The optional `query` is encoded as URL search params.
+ */
+declare function listTemplates(client: WhatsAppClient, query?: ListTemplatesQuery, options?: RequestOptions): Promise<ListTemplatesResponse>;
+/** GET /{templateId} — fetch a single template definition by id. */
+declare function getTemplate(client: WhatsAppClient, templateId: string, options?: RequestOptions): Promise<TemplateDefinition>;
+
+/**
+ * Count the number of unique `{{N}}` placeholders in a template body / header
+ * string. Validates that placeholders are 1-INDEXED and contiguous (no gaps).
+ *
+ * Throws `TemplateError` on:
+ * - any `{{0}}` (Meta's variables are 1-indexed)
+ * - gaps (e.g., `{{1}}` and `{{3}}` without a `{{2}}`)
+ *
+ * Repeated indices are counted once.
+ */
+declare function countTemplatePlaceholders(text: string | undefined): number;
+
+/**
+ * Cross-validate a built `TemplateMessage` payload against an approved
+ * `TemplateDefinition`. Throws `TemplateError(message, definition.name)`
+ * on any mismatch:
+ *   1. payload.template.name !== definition.name
+ *   2. payload.template.language.code !== definition.language
+ *   3. for each payload component: matching definition component must
+ *      exist (by type, and for buttons also by sub_type/index)
+ *   4. parameter count must equal placeholder count in the matching
+ *      definition component
+ */
+declare function validateTemplateSend(payload: TemplateMessage, definition: TemplateDefinition): void;
+
+/**
+ * Tracks which webhook events have been seen and returns whether the
+ * current sighting is new. Backed by any `Storage` impl (in-memory,
+ * Redis, etc.).
+ *
+ * The key for a `message` event is the wamid; for a `status` event the
+ * receiver layers in the status string so transitions (sent → delivered
+ * → read → failed) are not collapsed.
+ */
+declare class WebhookDeduper {
+    #private;
+    constructor(storage: Storage, ttlMs?: number);
+    markIfNew(eventKey: string): Promise<boolean>;
+}
+
+interface VerifyHandshakeInput {
+    /** `hub.mode` query param sent by Meta. */
+    mode: string | null | undefined;
+    /** `hub.verify_token` query param sent by Meta. */
+    verifyToken: string | null | undefined;
+    /** `hub.challenge` query param sent by Meta. */
+    challenge: string | null | undefined;
+    /** The verify-token shared secret you registered in Meta's webhook UI. */
+    expectedToken: string;
+}
+/**
+ * Verify Meta's GET-based webhook handshake. Returns the `challenge`
+ * value when `mode === "subscribe"` AND `verifyToken === expectedToken`
+ * (constant-time compare). Returns `null` for every other input — the
+ * caller SHOULD respond `403 Forbidden`.
+ *
+ * Runtime-portable: uses an explicit constant-time byte-wise compare
+ * rather than `node:crypto.timingSafeEqual`, so the function runs
+ * unmodified on Cloudflare Workers, Bun, Deno, and any WinterCG runtime.
+ */
+declare function verifyHandshake({ mode, verifyToken, challenge, expectedToken, }: VerifyHandshakeInput): string | null;
+
+/**
+ * Parse a Meta webhook payload (already JSON-decoded) into a flat
+ * `ReadonlyArray<WhatsAppEvent>`. Pure, never throws, surfaces
+ * unrecognised top-level fields as `{ kind: "unknown" }` so consumers
+ * can log and the SDK can extend later without breaking changes.
+ */
+declare function parseWebhookPayload(body: unknown): ReadonlyArray<WhatsAppEvent>;
+
+interface VerifySignatureInput {
+    /** Raw body BYTES Meta sent. Strings are UTF-8 encoded; do not pre-parse. */
+    rawBody: Buffer | Uint8Array | string;
+    /** The `X-Hub-Signature-256` header value. May or may not include the `sha256=` prefix. */
+    signatureHeader: string | null | undefined;
+    /** Your Meta app secret. */
+    appSecret: string;
+}
+/**
+ * Timing-safe HMAC-SHA256 verification of an incoming webhook body.
+ *
+ * Resolves to `true` if and only if the HMAC of the raw body, keyed with
+ * `appSecret`, matches the hex value in `signatureHeader`. Resolves to
+ * `false` (without rejecting) on every other input — including missing
+ * header, malformed hex, or wrong byte length.
+ *
+ * Uses WebCrypto (`crypto.subtle.sign`) so the function runs unmodified
+ * on Node ≥ 20, Cloudflare Workers, Bun, Deno, and any WinterCG runtime.
+ */
+declare function verifySignature({ rawBody, signatureHeader, appSecret, }: VerifySignatureInput): Promise<boolean>;
+/**
+ * Throwing variant of {@link verifySignature}. Resolves to `void` on a
+ * valid signature; throws `WebhookSignatureError` on any failure (bad
+ * HMAC, missing header, malformed hex, wrong byte length).
+ *
+ * Use this when wiring your own HTTP layer (i.e. not the SDK's
+ * Express / web / Hono adapters) and you want to surface a typed
+ * error rather than branch on a boolean. The SDK's bundled adapters
+ * use the boolean variant and return `401` directly.
+ */
+declare function verifySignatureOrThrow(input: VerifySignatureInput): Promise<void>;
+/**
+ * Compute the lowercase-hex `HMAC-SHA256(appSecret, rawBody)`. Exposed
+ * primarily so test fixtures can produce the expected header value.
+ */
+declare function computeSignature(rawBody: Buffer | Uint8Array | string, appSecret: string): Promise<string>;
+
+export { type AudioMessage, AuthenticationError, type AuthenticationErrorMeta, type BaseMessage, BucketMap, type BucketMapOptions, type BuildAuthTemplateInput, type BuildCarouselTemplateInput, type BuildContactsInput, type BuildInteractiveButtonInput, type BuildInteractiveCtaUrlInput, type BuildInteractiveInput, type BuildInteractiveListInput, type BuildLocationInput, type BuildMediaInput, type BuildReactionInput, type BuildTemplateInput, type BuildTextInput, type BuildVoiceInput, CapabilityError, type CapabilityErrorMeta, type CarouselCard, type CarouselCardButton, type CarouselCardComponent, type CarouselCardMediaHeader, type Contact, type ContactEmail, type ContactName, type ContactPhone, type ContactsMessage, type CredentialField, DEFAULT_RETRY_POLICY, type DocumentMessage, GRAPH_API_VERSION, type GraphApiVersion, type HttpMethod, type ImageMessage, type InteractiveBody, type InteractiveButtonAction, type InteractiveButtonBody, type InteractiveButtonReply, type InteractiveCtaUrlAction, type InteractiveCtaUrlBody, type InteractiveHeader, type InteractiveListAction, type InteractiveListBody, type InteractiveListRow, type InteractiveListSection, type InteractiveMessage, type ListTemplatesPaging, type ListTemplatesQuery, type ListTemplatesResponse, type LocationBody, type LocationMessage, META_GRAPH_BASE_URL, type MediaKind, type MediaSource, type MessageSendResponse, type MessageSendResponseContact, type MessageSendResponseMessage, MissingCredentialsError, MockModeError, MockWhatsAppClient, type MockWhatsAppClientOptions, PermissionError, type PermissionErrorMeta, type PickWhatsAppClientOptions, RateLimitError, type RateLimitErrorMeta, type RateLimitOptions, type ReactionBody, type ReactionMessage, type RecipientType, type RecordedSend, type RequestOptions, type RetryPolicy, type StickerMessage, Storage, type TemplateBody, type TemplateButtonDefinition, type TemplateCategory, type TemplateComponent, type TemplateComponentDefinition, type TemplateComponentDefinitionType, type TemplateDefinition, TemplateError, type TemplateLanguage, type TemplateMessage, type TemplateParameter, type TemplateParameterCouponCode, type TemplateParameterCurrency, type TemplateParameterDateTime, type TemplateParameterDocument, type TemplateParameterImage, type TemplateParameterLimitedTimeOffer, type TemplateParameterPayload, type TemplateParameterText, type TemplateParameterVideo, type TemplateStatus, type TextBody, type TextMessage, TokenBucket, type TokenBucketOptions, type TokenInfo, type TokenProvider, TransientHttpError, type VerifyHandshakeInput, type VerifySignatureInput, type VideoMessage, WEBHOOK_ACK_DEADLINE_MS, WEBHOOK_DEDUPE_TTL_MS, WINDOW_TTL_MS, WebhookDeduper, WebhookReceiver, WebhookSignatureError, WhatsAppClient, type WhatsAppClientOptions, WhatsAppError, type WhatsAppErrorCode, type WhatsAppErrorOptions, WhatsAppEvent, type WhatsAppLikeClient, type WhatsAppMessage, WindowClosedError, WindowTracker, type WindowTrackerOptions, buildAudio, buildAuthTemplate, buildCarouselTemplate, buildContacts, buildDocument, buildImage, buildInteractive, buildInteractiveButton, buildInteractiveCtaUrl, buildInteractiveList, buildLocation, buildReaction, buildSticker, buildTemplate, buildText, buildVideo, buildVoice, computeSignature, countTemplatePlaceholders, getTemplate, getTracer, hashPhoneNumberId, listTemplates, parseWebhookPayload, pickWhatsAppClient, sendMessage, setRedactSalt, validateTemplateSend, verifyHandshake, verifySignature, verifySignatureOrThrow, withRateLimit, withSpan };