waba-toolkit 0.1.2 → 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,580 @@
+interface WABAClientOptions {
+    /** Meta access token with whatsapp_business_messaging permission */
+    accessToken: string;
+    /** Meta App Secret for webhook signature verification */
+    appSecret?: string;
+    /** API version (default: 'v22.0') */
+    apiVersion?: string;
+    /** Base URL (default: 'https://graph.facebook.com') */
+    baseUrl?: string;
+}
+interface GetMediaOptions {
+    /** Return ArrayBuffer instead of ReadableStream (default: false) */
+    asBuffer?: boolean;
+}
+
+/**
+ * Media metadata returned from WABA API.
+ * Field names are normalized from snake_case to camelCase.
+ */
+interface MediaMetadata {
+    id: string;
+    /** Normalized from mime_type */
+    mimeType: string;
+    sha256: string;
+    /** Normalized from file_size (string → number) */
+    fileSize: number;
+    /** Temporary URL (expires in 5 minutes) */
+    url: string;
+}
+interface MediaStreamResult extends MediaMetadata {
+    stream: ReadableStream<Uint8Array>;
+}
+interface MediaBufferResult extends MediaMetadata {
+    buffer: ArrayBuffer;
+}
+
+/**
+ * Client for WhatsApp Business API media operations.
+ */
+declare class WABAClient {
+    private readonly accessToken;
+    private readonly appSecret?;
+    private readonly apiVersion;
+    private readonly baseUrl;
+    constructor(options: WABAClientOptions);
+    /**
+     * Verifies webhook signature using HMAC-SHA256.
+     * Requires appSecret to be set in constructor options.
+     *
+     * @throws {WABASignatureError} If appSecret was not provided in constructor
+     * @returns true if signature is valid, false otherwise
+     */
+    verifyWebhook(signature: string | undefined, rawBody: Buffer | string): boolean;
+    /**
+     * Fetches media by ID from WhatsApp Business API.
+     *
+     * Step 1: GET /{apiVersion}/{mediaId} → retrieves temporary URL + metadata
+     * Step 2: GET {temporaryUrl} → downloads binary content
+     *
+     * @throws {WABAMediaError} - Media not found (404) or access denied
+     * @throws {WABANetworkError} - Network/connection failures
+     */
+    getMedia(mediaId: string): Promise<MediaStreamResult>;
+    getMedia(mediaId: string, options: {
+        asBuffer: true;
+    }): Promise<MediaBufferResult>;
+    getMedia(mediaId: string, options?: GetMediaOptions): Promise<MediaStreamResult | MediaBufferResult>;
+    private fetchMediaMetadata;
+    private downloadMedia;
+}
+
+/** Context object for replies and forwarded messages */
+interface MessageContext {
+    /** Original sender (for replies) */
+    from?: string;
+    /** Original message ID */
+    id?: string;
+    forwarded?: boolean;
+    frequently_forwarded?: boolean;
+    /** Present for product enquiry messages */
+    referred_product?: {
+        catalog_id: string;
+        product_retailer_id: string;
+    };
+}
+/** Identity object for security notifications */
+interface MessageIdentity {
+    /** State of acknowledgment for latest user_identity_changed system notification */
+    acknowledged: boolean;
+    /** Timestamp when the WhatsApp Business API detected the user potentially changed */
+    created_timestamp: string;
+    /** Identifier for the latest user_identity_changed system notification */
+    hash: string;
+}
+/** Base fields present on all incoming messages */
+interface IncomingMessageBase {
+    /** Sender's phone number */
+    from: string;
+    /** Message ID (use for mark-as-read) */
+    id: string;
+    /** Unix epoch seconds as string */
+    timestamp: string;
+    /** Message type */
+    type: string;
+    /** Present if reply or forwarded */
+    context?: MessageContext;
+    /** Present if show_security_notifications is enabled in application settings */
+    identity?: MessageIdentity;
+}
+/** Text message */
+interface TextMessage extends IncomingMessageBase {
+    type: 'text';
+    text: {
+        body: string;
+    };
+}
+/** Media object base (shared by image, audio, video, document, sticker) */
+interface MediaObject {
+    id: string;
+    mime_type: string;
+    sha256: string;
+    caption?: string;
+}
+/** Image message */
+interface ImageMessage extends IncomingMessageBase {
+    type: 'image';
+    image: MediaObject;
+}
+/** Audio message */
+interface AudioMessage extends IncomingMessageBase {
+    type: 'audio';
+    audio: MediaObject & {
+        /** True if voice note */
+        voice?: boolean;
+    };
+}
+/** Video message */
+interface VideoMessage extends IncomingMessageBase {
+    type: 'video';
+    video: MediaObject;
+}
+/** Document message */
+interface DocumentMessage extends IncomingMessageBase {
+    type: 'document';
+    document: MediaObject & {
+        filename?: string;
+    };
+}
+/** Sticker message */
+interface StickerMessage extends IncomingMessageBase {
+    type: 'sticker';
+    sticker: MediaObject & {
+        animated?: boolean;
+    };
+}
+/** Location message */
+interface LocationMessage extends IncomingMessageBase {
+    type: 'location';
+    location: {
+        latitude: number;
+        longitude: number;
+        name?: string;
+        address?: string;
+    };
+}
+/** Contact in contacts message */
+interface ContactCard {
+    name: {
+        formatted_name: string;
+        first_name?: string;
+        last_name?: string;
+        middle_name?: string;
+        suffix?: string;
+        prefix?: string;
+    };
+    phones?: Array<{
+        phone?: string;
+        type?: string;
+        wa_id?: string;
+    }>;
+    emails?: Array<{
+        email?: string;
+        type?: string;
+    }>;
+    addresses?: Array<{
+        street?: string;
+        city?: string;
+        state?: string;
+        zip?: string;
+        country?: string;
+        country_code?: string;
+        type?: string;
+    }>;
+    org?: {
+        company?: string;
+        department?: string;
+        title?: string;
+    };
+    urls?: Array<{
+        url?: string;
+        type?: string;
+    }>;
+    birthday?: string;
+}
+/** Contacts message */
+interface ContactsMessage extends IncomingMessageBase {
+    type: 'contacts';
+    contacts: ContactCard[];
+}
+/** Button reply object */
+interface ButtonReply {
+    id: string;
+    title: string;
+}
+/** List reply object */
+interface ListReply {
+    id: string;
+    title: string;
+    description?: string;
+}
+/** Flow (NFM) reply object */
+interface NfmReply {
+    /** JSON string containing the flow response data */
+    response_json: string;
+    /** Optional body text */
+    body?: string;
+    /** Flow name */
+    name?: string;
+    /** Flow token for tracking/correlation */
+    flow_token?: string;
+}
+/** Interactive message (button/list replies, flow responses) */
+interface InteractiveMessage extends IncomingMessageBase {
+    type: 'interactive';
+    interactive: {
+        type: 'button_reply' | 'list_reply' | 'nfm_reply';
+        button_reply?: ButtonReply;
+        list_reply?: ListReply;
+        nfm_reply?: NfmReply;
+    };
+}
+/** Reaction message */
+interface ReactionMessage extends IncomingMessageBase {
+    type: 'reaction';
+    reaction: {
+        message_id: string;
+        emoji: string;
+    };
+}
+/** Button message (quick reply button click) */
+interface ButtonMessage extends IncomingMessageBase {
+    type: 'button';
+    button: {
+        text: string;
+        payload: string;
+    };
+}
+/** Order message */
+interface OrderMessage extends IncomingMessageBase {
+    type: 'order';
+    order: {
+        catalog_id: string;
+        product_items: Array<{
+            product_retailer_id: string;
+            quantity: number;
+            item_price: number;
+            currency: string;
+        }>;
+        text?: string;
+    };
+}
+/** System message (number change, identity change) */
+interface SystemMessage extends IncomingMessageBase {
+    type: 'system';
+    system: {
+        body: string;
+        type: 'user_changed_number' | 'user_identity_changed';
+        new_wa_id?: string;
+        identity?: string;
+        user?: string;
+    };
+}
+/** Referral message (click-to-WhatsApp ads) */
+interface ReferralMessage extends IncomingMessageBase {
+    type: 'referral';
+    referral: {
+        source_url: string;
+        source_type: string;
+        source_id: string;
+        headline?: string;
+        body?: string;
+        media_type?: string;
+        image_url?: string;
+        video_url?: string;
+        thumbnail_url?: string;
+    };
+}
+/** Unsupported/unknown message type */
+interface UnsupportedMessage extends IncomingMessageBase {
+    type: 'unsupported' | 'unknown';
+    errors?: Array<{
+        code: number;
+        title: string;
+        details?: string;
+    }>;
+}
+/** Union of all incoming message types */
+type IncomingMessage = TextMessage | ImageMessage | AudioMessage | VideoMessage | DocumentMessage | StickerMessage | LocationMessage | ContactsMessage | InteractiveMessage | ReactionMessage | ButtonMessage | OrderMessage | SystemMessage | ReferralMessage | UnsupportedMessage;
+/** Union of media message types */
+type MediaMessage = ImageMessage | AudioMessage | VideoMessage | DocumentMessage | StickerMessage;
+/** Discriminated union for message classification results */
+type MessageClassification = {
+    type: 'text';
+    message: TextMessage;
+} | {
+    type: 'image';
+    message: ImageMessage;
+} | {
+    type: 'video';
+    message: VideoMessage;
+} | {
+    type: 'audio';
+    message: AudioMessage;
+} | {
+    type: 'document';
+    message: DocumentMessage;
+} | {
+    type: 'sticker';
+    message: StickerMessage;
+} | {
+    type: 'location';
+    message: LocationMessage;
+} | {
+    type: 'contacts';
+    message: ContactsMessage;
+} | {
+    type: 'interactive';
+    message: InteractiveMessage;
+} | {
+    type: 'reaction';
+    message: ReactionMessage;
+} | {
+    type: 'button';
+    message: ButtonMessage;
+} | {
+    type: 'order';
+    message: OrderMessage;
+} | {
+    type: 'system';
+    message: SystemMessage;
+} | {
+    type: 'referral';
+    message: ReferralMessage;
+} | {
+    type: 'unsupported';
+    message: UnsupportedMessage;
+};
+
+/** Top-level webhook payload from Meta */
+interface WebhookPayload {
+    object: 'whatsapp_business_account';
+    entry: WebhookEntry[];
+}
+interface WebhookEntry {
+    /** WABA ID */
+    id: string;
+    changes: WebhookChange[];
+}
+interface WebhookChange {
+    value: WebhookValue;
+    field: string;
+}
+/** Union of possible webhook value types */
+type WebhookValue = MessageWebhookValue | StatusWebhookValue | CallWebhookValue;
+/** Contact info included in webhooks */
+interface WebhookContact {
+    profile: {
+        /** Sender's profile name (optional per WABA docs) */
+        name?: string;
+    };
+    wa_id: string;
+}
+/** Metadata included in all webhook values */
+interface WebhookMetadata {
+    display_phone_number: string;
+    phone_number_id: string;
+}
+/** Error object in webhooks */
+interface WebhookError {
+    code: number;
+    title: string;
+    message?: string;
+    error_data?: {
+        details: string;
+    };
+}
+/** Webhook value for incoming messages */
+interface MessageWebhookValue {
+    messaging_product: 'whatsapp';
+    metadata: WebhookMetadata;
+    contacts?: WebhookContact[];
+    messages?: IncomingMessage[];
+    errors?: WebhookError[];
+}
+/** Status update types */
+type MessageStatus = 'sent' | 'delivered' | 'read' | 'failed' | 'deleted';
+/** Conversation origin types */
+type ConversationOriginType = 'business_initiated' | 'user_initiated' | 'referral_conversion';
+/** Conversation object in status webhooks */
+interface ConversationObject {
+    id: string;
+    origin: {
+        type: ConversationOriginType;
+    };
+    expiration_timestamp?: string;
+}
+/** Pricing model types */
+type PricingModel = 'CBP' | 'NBP';
+/** Pricing category types */
+type PricingCategory = 'business_initiated' | 'user_initiated' | 'referral_conversion' | 'authentication' | 'marketing' | 'utility' | 'service';
+/** Pricing object in status webhooks */
+interface PricingObject {
+    billable: boolean;
+    pricing_model: PricingModel;
+    category: PricingCategory;
+}
+/** Individual status entry */
+interface StatusEntry {
+    id: string;
+    recipient_id: string;
+    status: MessageStatus;
+    timestamp: string;
+    conversation?: ConversationObject;
+    pricing?: PricingObject;
+    errors?: WebhookError[];
+}
+/** Webhook value for message status updates */
+interface StatusWebhookValue {
+    messaging_product: 'whatsapp';
+    metadata: WebhookMetadata;
+    statuses: StatusEntry[];
+}
+/** Call event types */
+type CallEvent = 'connect' | 'terminate' | 'status';
+/** Call entry in call webhooks */
+interface CallEntry {
+    id: string;
+    from: string;
+    to: string;
+    /** Present on connect webhooks */
+    event?: CallEvent;
+    direction: 'USER_INITIATED' | 'BUSINESS_INITIATED';
+    timestamp: string;
+    session?: {
+        sdp_type: string;
+        sdp: string;
+    };
+    /** e.g. ['COMPLETED'] or ['FAILED'] on terminate */
+    status?: string[];
+    /** Present on terminate if connected */
+    start_time?: string;
+    end_time?: string;
+    /** Seconds, present on terminate if connected */
+    duration?: number;
+    /** Arbitrary tracking string that allows you to attach custom metadata to calls */
+    biz_opaque_callback_data?: string;
+    errors?: {
+        code: number;
+        message: string;
+    };
+}
+/** Webhook value for call events */
+interface CallWebhookValue {
+    messaging_product: 'whatsapp';
+    metadata: WebhookMetadata;
+    contacts?: WebhookContact[];
+    calls: CallEntry[];
+}
+/** Discriminated union for webhook classification results */
+type WebhookClassification = {
+    type: 'message';
+    payload: MessageWebhookValue;
+} | {
+    type: 'status';
+    payload: StatusWebhookValue;
+} | {
+    type: 'call';
+    payload: CallWebhookValue;
+} | {
+    type: 'unknown';
+    payload: unknown;
+};
+
+/**
+ * Classifies a webhook payload into its type.
+ * Returns a discriminated union for type-safe handling.
+ */
+declare function classifyWebhook(payload: WebhookPayload): WebhookClassification;
+
+/**
+ * Classifies an incoming message by its type.
+ * Returns a discriminated union for type-safe handling.
+ */
+declare function classifyMessage(message: IncomingMessage): MessageClassification;
+
+interface VerifyWebhookSignatureOptions {
+    /** X-Hub-Signature-256 header value */
+    signature: string | undefined;
+    /** Raw request body (NOT parsed JSON) */
+    rawBody: Buffer | string;
+    /** Meta App Secret */
+    appSecret: string | undefined;
+}
+/**
+ * Verifies webhook signature using HMAC-SHA256.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @throws {WABASignatureError} If appSecret is not provided
+ * @returns true if signature is valid, false otherwise
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): boolean;
+
+/**
+ * Type guard: returns true if message contains downloadable media.
+ * Narrows type to messages with image/audio/video/document/sticker.
+ */
+declare function isMediaMessage(message: IncomingMessage): message is MediaMessage;
+/**
+ * Extracts media ID from any media message type.
+ * Returns undefined if message has no media.
+ */
+declare function extractMediaId(message: IncomingMessage): string | undefined;
+interface ContactInfo {
+    waId: string;
+    profileName: string | undefined;
+    phoneNumberId: string;
+}
+/**
+ * Extracts sender info from webhook payload.
+ * Returns null if the webhook doesn't contain message contact info.
+ */
+declare function getContactInfo(webhook: WebhookPayload): ContactInfo | null;
+/**
+ * Parses message timestamp to Date object.
+ * WhatsApp timestamps are Unix epoch seconds as strings.
+ */
+declare function getMessageTimestamp(message: IncomingMessage): Date;
+/**
+ * Extracts message ID from message or status webhook.
+ * Returns null if not a message/status webhook or ID not present.
+ */
+declare function getMessageId(webhook: WebhookPayload): string | null;
+/**
+ * Extracts call ID from call webhook.
+ * Returns null if not a call webhook or ID not present.
+ */
+declare function getCallId(webhook: WebhookPayload): string | null;
+
+/** Base error class for all WABA errors */
+declare class WABAError extends Error {
+    readonly code?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code?: number | undefined, details?: unknown | undefined);
+}
+/** Error for media-related failures (404, access denied) */
+declare class WABAMediaError extends WABAError {
+    readonly mediaId: string;
+    constructor(message: string, mediaId: string, code?: number);
+}
+/** Error for network/connection failures */
+declare class WABANetworkError extends WABAError {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/** Error for invalid webhook signatures */
+declare class WABASignatureError extends WABAError {
+    constructor(message?: string);
+}
+
+export { type AudioMessage, type ButtonMessage, type ButtonReply, type CallEntry, type CallWebhookValue, type ContactCard, type ContactInfo, type ContactsMessage, type ConversationObject, type DocumentMessage, type GetMediaOptions, type ImageMessage, type IncomingMessage, type IncomingMessageBase, type InteractiveMessage, type ListReply, type LocationMessage, type MediaBufferResult, type MediaMessage, type MediaMetadata, type MediaObject, type MediaStreamResult, type MessageClassification, type MessageContext, type MessageStatus, type MessageWebhookValue, type OrderMessage, type PricingObject, type ReactionMessage, type ReferralMessage, type StatusEntry, type StatusWebhookValue, type StickerMessage, type SystemMessage, type TextMessage, type UnsupportedMessage, type VerifyWebhookSignatureOptions, type VideoMessage, WABAClient, type WABAClientOptions, WABAError, WABAMediaError, WABANetworkError, WABASignatureError, type WebhookChange, type WebhookClassification, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookMetadata, type WebhookPayload, type WebhookValue, classifyMessage, classifyWebhook, extractMediaId, getCallId, getContactInfo, getMessageId, getMessageTimestamp, isMediaMessage, verifyWebhookSignature };

package/dist/index.d.ts

@@ -440,13 +440,15 @@ interface StatusWebhookValue {
     metadata: WebhookMetadata;
     statuses: StatusEntry[];
 }
+/** Call event types */
+type CallEvent = 'connect' | 'terminate' | 'status';
 /** Call entry in call webhooks */
 interface CallEntry {
     id: string;
     from: string;
     to: string;
     /** Present on connect webhooks */
-    event?: 'connect';
+    event?: CallEvent;
     direction: 'USER_INITIATED' | 'BUSINESS_INITIATED';
     timestamp: string;
     session?: {
@@ -460,6 +462,8 @@ interface CallEntry {
     end_time?: string;
     /** Seconds, present on terminate if connected */
     duration?: number;
+    /** Arbitrary tracking string that allows you to attach custom metadata to calls */
+    biz_opaque_callback_data?: string;
     errors?: {
         code: number;
         message: string;
@@ -533,14 +537,24 @@ interface ContactInfo {
 }
 /**
  * Extracts sender info from webhook payload.
- * Returns undefined if the webhook doesn't contain message contact info.
+ * Returns null if the webhook doesn't contain message contact info.
  */
-declare function getContactInfo(webhook: WebhookPayload): ContactInfo | undefined;
+declare function getContactInfo(webhook: WebhookPayload): ContactInfo | null;
 /**
  * Parses message timestamp to Date object.
  * WhatsApp timestamps are Unix epoch seconds as strings.
  */
 declare function getMessageTimestamp(message: IncomingMessage): Date;
+/**
+ * Extracts message ID from message or status webhook.
+ * Returns null if not a message/status webhook or ID not present.
+ */
+declare function getMessageId(webhook: WebhookPayload): string | null;
+/**
+ * Extracts call ID from call webhook.
+ * Returns null if not a call webhook or ID not present.
+ */
+declare function getCallId(webhook: WebhookPayload): string | null;
 
 /** Base error class for all WABA errors */
 declare class WABAError extends Error {
@@ -563,4 +577,4 @@ declare class WABASignatureError extends WABAError {
     constructor(message?: string);
 }
 
-export { type AudioMessage, type ButtonMessage, type ButtonReply, type CallEntry, type CallWebhookValue, type ContactCard, type ContactInfo, type ContactsMessage, type ConversationObject, type DocumentMessage, type GetMediaOptions, type ImageMessage, type IncomingMessage, type IncomingMessageBase, type InteractiveMessage, type ListReply, type LocationMessage, type MediaBufferResult, type MediaMessage, type MediaMetadata, type MediaObject, type MediaStreamResult, type MessageClassification, type MessageContext, type MessageStatus, type MessageWebhookValue, type OrderMessage, type PricingObject, type ReactionMessage, type ReferralMessage, type StatusEntry, type StatusWebhookValue, type StickerMessage, type SystemMessage, type TextMessage, type UnsupportedMessage, type VerifyWebhookSignatureOptions, type VideoMessage, WABAClient, type WABAClientOptions, WABAError, WABAMediaError, WABANetworkError, WABASignatureError, type WebhookChange, type WebhookClassification, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookMetadata, type WebhookPayload, type WebhookValue, classifyMessage, classifyWebhook, extractMediaId, getContactInfo, getMessageTimestamp, isMediaMessage, verifyWebhookSignature };
+export { type AudioMessage, type ButtonMessage, type ButtonReply, type CallEntry, type CallWebhookValue, type ContactCard, type ContactInfo, type ContactsMessage, type ConversationObject, type DocumentMessage, type GetMediaOptions, type ImageMessage, type IncomingMessage, type IncomingMessageBase, type InteractiveMessage, type ListReply, type LocationMessage, type MediaBufferResult, type MediaMessage, type MediaMetadata, type MediaObject, type MediaStreamResult, type MessageClassification, type MessageContext, type MessageStatus, type MessageWebhookValue, type OrderMessage, type PricingObject, type ReactionMessage, type ReferralMessage, type StatusEntry, type StatusWebhookValue, type StickerMessage, type SystemMessage, type TextMessage, type UnsupportedMessage, type VerifyWebhookSignatureOptions, type VideoMessage, WABAClient, type WABAClientOptions, WABAError, WABAMediaError, WABANetworkError, WABASignatureError, type WebhookChange, type WebhookClassification, type WebhookContact, type WebhookEntry, type WebhookError, type WebhookMetadata, type WebhookPayload, type WebhookValue, classifyMessage, classifyWebhook, extractMediaId, getCallId, getContactInfo, getMessageId, getMessageTimestamp, isMediaMessage, verifyWebhookSignature };