waba-toolkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robin Biju Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# waba-toolkit
+
+A minimal, type-safe toolkit for WhatsApp Business API webhook processing and media handling.
+
+> **Note:** This is not an official Meta/WhatsApp package, nor is it a full API wrapper. It is a utility toolkit derived from patterns across several production projects that interface directly with the WhatsApp Business API (Cloud API).
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [WABAClient](#wabaclient)
+  - [Webhook Functions](#webhook-functions)
+  - [Helper Functions](#helper-functions)
+  - [Error Classes](#error-classes)
+- [Types](#types)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install waba-toolkit
+```
+
+---
+
+## Requirements
+
+- Node.js 20+
+- A valid Meta access token with `whatsapp_business_messaging` permission
+
+---
+
+## Quick Start
+
+```typescript
+import {
+  WABAClient,
+  verifyWebhookSignature,
+  classifyWebhook,
+  classifyMessage,
+  isMediaMessage,
+  extractMediaId,
+} from 'waba-toolkit';
+
+// Initialize client
+const client = new WABAClient({
+  accessToken: process.env.META_ACCESS_TOKEN,
+});
+
+// In your webhook handler
+app.post('/webhook', async (req, res) => {
+  // 1. Verify signature
+  const isValid = verifyWebhookSignature({
+    signature: req.headers['x-hub-signature-256'],
+    rawBody: req.rawBody,
+    appSecret: process.env.META_APP_SECRET,
+  });
+
+  if (!isValid) {
+    return res.status(401).send('Invalid signature');
+  }
+
+  // 2. Classify webhook type
+  const webhook = classifyWebhook(req.body);
+
+  if (webhook.type === 'message') {
+    const message = webhook.payload.messages?.[0];
+    if (!message) return res.sendStatus(200);
+
+    // 3. Classify message type
+    const classified = classifyMessage(message);
+
+    if (classified.type === 'text') {
+      console.log('Text:', classified.message.text.body);
+    }
+
+    // 4. Handle media messages
+    if (isMediaMessage(message)) {
+      const mediaId = extractMediaId(message);
+      const { stream, mimeType } = await client.getMedia(mediaId);
+      // Process stream...
+    }
+  }
+
+  res.sendStatus(200);
+});
+```
+
+---
+
+## API Reference
+
+### WABAClient
+
+Client for downloading media from WhatsApp Business API.
+
+#### Constructor
+
+```typescript
+const client = new WABAClient({
+  accessToken: string,      // Required: Meta access token
+  apiVersion?: string,      // Optional: API version (default: 'v22.0')
+  baseUrl?: string,         // Optional: Base URL (default: 'https://graph.facebook.com')
+});
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `getMedia(mediaId)` | Downloads media, returns `ReadableStream` |
+| `getMedia(mediaId, { asBuffer: true })` | Downloads media, returns `ArrayBuffer` |
+
+```typescript
+// Stream (default)
+const { stream, mimeType, sha256, fileSize, url } = await client.getMedia(mediaId);
+
+// Buffer
+const { buffer, mimeType, sha256, fileSize, url } = await client.getMedia(mediaId, {
+  asBuffer: true,
+});
+```
+
+---
+
+### Webhook Functions
+
+| Function | Description |
+|----------|-------------|
+| `verifyWebhookSignature(options)` | Verifies `X-Hub-Signature-256` header using HMAC-SHA256 |
+| `classifyWebhook(payload)` | Returns discriminated union: `message` \| `status` \| `call` \| `unknown` |
+| `classifyMessage(message)` | Returns discriminated union for 15 message types |
+
+#### verifyWebhookSignature
+
+```typescript
+const isValid = verifyWebhookSignature({
+  signature: req.headers['x-hub-signature-256'],  // X-Hub-Signature-256 header
+  rawBody: req.rawBody,                            // Raw body as Buffer or string
+  appSecret: process.env.META_APP_SECRET,          // Meta App Secret
+});
+```
+
+#### classifyWebhook
+
+```typescript
+const result = classifyWebhook(webhookPayload);
+
+switch (result.type) {
+  case 'message':
+    // result.payload: MessageWebhookValue
+    break;
+  case 'status':
+    // result.payload: StatusWebhookValue
+    break;
+  case 'call':
+    // result.payload: CallWebhookValue
+    break;
+  case 'unknown':
+    // Unrecognized webhook
+    break;
+}
+```
+
+#### classifyMessage
+
+```typescript
+const result = classifyMessage(message);
+
+switch (result.type) {
+  case 'text':
+    console.log(result.message.text.body);
+    break;
+  case 'image':
+  case 'video':
+  case 'audio':
+  case 'document':
+  case 'sticker':
+    console.log(result.message[result.type].id);
+    break;
+  case 'location':
+    console.log(result.message.location.latitude);
+    break;
+  case 'contacts':
+    console.log(result.message.contacts[0].name);
+    break;
+  case 'interactive':
+    console.log(result.message.interactive.type);
+    break;
+  case 'reaction':
+    console.log(result.message.reaction.emoji);
+    break;
+  // ... button, order, system, referral, unsupported
+}
+```
+
+---
+
+### Helper Functions
+
+| Function | Description |
+|----------|-------------|
+| `isMediaMessage(message)` | Type guard: returns `true` if message has downloadable media |
+| `extractMediaId(message)` | Extracts media ID from image/audio/video/document/sticker messages |
+| `getContactInfo(webhook)` | Extracts sender's `waId`, `profileName`, and `phoneNumberId` |
+| `getMessageTimestamp(message)` | Parses timestamp string to `Date` object |
+
+```typescript
+import {
+  isMediaMessage,
+  extractMediaId,
+  getContactInfo,
+  getMessageTimestamp,
+} from 'waba-toolkit';
+
+// Check if message has media
+if (isMediaMessage(message)) {
+  const mediaId = extractMediaId(message);  // guaranteed non-undefined
+  const media = await client.getMedia(mediaId);
+}
+
+// Get sender info
+const contact = getContactInfo(webhookPayload);
+if (contact) {
+  console.log(contact.waId);          // e.g., '14155551234'
+  console.log(contact.profileName);   // e.g., 'John Doe' (may be undefined)
+  console.log(contact.phoneNumberId); // Your business phone number ID
+}
+
+// Parse timestamp
+const sentAt = getMessageTimestamp(message);
+console.log(sentAt.toISOString());
+```
+
+---
+
+### Error Classes
+
+| Class | Description |
+|-------|-------------|
+| `WABAError` | Base error class |
+| `WABAMediaError` | Media download failures (includes `mediaId` and `code`) |
+| `WABANetworkError` | Network/connection failures (includes `cause`) |
+| `WABASignatureError` | Invalid webhook signature |
+
+```typescript
+import { WABAMediaError, WABANetworkError } from 'waba-toolkit';
+
+try {
+  const media = await client.getMedia(mediaId);
+} catch (error) {
+  if (error instanceof WABAMediaError) {
+    console.error(`Media error for ${error.mediaId}: ${error.code}`);
+  } else if (error instanceof WABANetworkError) {
+    console.error('Network error:', error.cause);
+  }
+}
+```
+
+---
+
+## Types
+
+All types are exported for use in your application:
+
+```typescript
+import type {
+  // Client
+  WABAClientOptions,
+  GetMediaOptions,
+
+  // Media
+  MediaMetadata,
+  MediaStreamResult,
+  MediaBufferResult,
+
+  // Webhooks
+  WebhookPayload,
+  WebhookClassification,
+  MessageWebhookValue,
+  StatusWebhookValue,
+  CallWebhookValue,
+
+  // Messages
+  IncomingMessage,
+  MessageClassification,
+  TextMessage,
+  ImageMessage,
+  AudioMessage,
+  VideoMessage,
+  DocumentMessage,
+  StickerMessage,
+  LocationMessage,
+  ContactsMessage,
+  InteractiveMessage,
+  ReactionMessage,
+  MediaMessage,
+  // ... and more
+} from 'waba-toolkit';
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,554 @@
+interface WABAClientOptions {
+    /** Meta access token with whatsapp_business_messaging permission */
+    accessToken: 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 apiVersion;
+    private readonly baseUrl;
+    constructor(options: WABAClientOptions);
+    /**
+     * 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 entry in call webhooks */
+interface CallEntry {
+    id: string;
+    from: string;
+    to: string;
+    /** Present on connect webhooks */
+    event?: 'connect';
+    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;
+    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;
+}
+/**
+ * Verifies webhook signature using HMAC-SHA256.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @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 undefined if the webhook doesn't contain message contact info.
+ */
+declare function getContactInfo(webhook: WebhookPayload): ContactInfo | undefined;
+/**
+ * Parses message timestamp to Date object.
+ * WhatsApp timestamps are Unix epoch seconds as strings.
+ */
+declare function getMessageTimestamp(message: IncomingMessage): Date;
+
+/** 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, getContactInfo, getMessageTimestamp, isMediaMessage, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,260 @@
+// src/errors.ts
+var WABAError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "WABAError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var WABAMediaError = class extends WABAError {
+  constructor(message, mediaId, code) {
+    super(message, code);
+    this.mediaId = mediaId;
+    this.name = "WABAMediaError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var WABANetworkError = class extends WABAError {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "WABANetworkError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var WABASignatureError = class extends WABAError {
+  constructor(message = "Invalid webhook signature") {
+    super(message);
+    this.name = "WABASignatureError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/client.ts
+var DEFAULT_API_VERSION = "v22.0";
+var DEFAULT_BASE_URL = "https://graph.facebook.com";
+var WABAClient = class {
+  accessToken;
+  apiVersion;
+  baseUrl;
+  constructor(options) {
+    this.accessToken = options.accessToken;
+    this.apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+  }
+  async getMedia(mediaId, options) {
+    const metadata = await this.fetchMediaMetadata(mediaId);
+    const response = await this.downloadMedia(metadata.url, mediaId);
+    if (options?.asBuffer) {
+      const buffer = await response.arrayBuffer();
+      return {
+        ...metadata,
+        buffer
+      };
+    }
+    if (!response.body) {
+      throw new WABAMediaError("Response body is null", mediaId);
+    }
+    return {
+      ...metadata,
+      stream: response.body
+    };
+  }
+  async fetchMediaMetadata(mediaId) {
+    const url = `${this.baseUrl}/${this.apiVersion}/${mediaId}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${this.accessToken}`
+        }
+      });
+    } catch (error) {
+      throw new WABANetworkError(
+        `Failed to fetch media metadata: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (!response.ok) {
+      const errorBody = await response.text().catch(() => "Unknown error");
+      throw new WABAMediaError(
+        `Failed to fetch media metadata: ${response.status} ${errorBody}`,
+        mediaId,
+        response.status
+      );
+    }
+    const data = await response.json();
+    return {
+      id: data.id,
+      mimeType: data.mime_type,
+      sha256: data.sha256,
+      fileSize: parseInt(data.file_size, 10),
+      url: data.url
+    };
+  }
+  async downloadMedia(url, mediaId) {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${this.accessToken}`
+        }
+      });
+    } catch (error) {
+      throw new WABANetworkError(
+        `Failed to download media: ${error instanceof Error ? error.message : "Unknown error"}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (!response.ok) {
+      throw new WABAMediaError(
+        `Failed to download media: ${response.status}`,
+        mediaId,
+        response.status
+      );
+    }
+    return response;
+  }
+};
+
+// src/webhooks/classify.ts
+function classifyWebhook(payload) {
+  const entry = payload.entry?.[0];
+  const change = entry?.changes?.[0];
+  const value = change?.value;
+  if (!value) {
+    return { type: "unknown", payload };
+  }
+  if ("calls" in value && Array.isArray(value.calls)) {
+    return { type: "call", payload: value };
+  }
+  if ("statuses" in value && Array.isArray(value.statuses)) {
+    return { type: "status", payload: value };
+  }
+  if ("messages" in value && Array.isArray(value.messages)) {
+    return { type: "message", payload: value };
+  }
+  if ("errors" in value && Array.isArray(value.errors)) {
+    return { type: "message", payload: value };
+  }
+  return { type: "unknown", payload };
+}
+
+// src/webhooks/messages.ts
+function classifyMessage(message) {
+  switch (message.type) {
+    case "text":
+      return { type: "text", message };
+    case "image":
+      return { type: "image", message };
+    case "audio":
+      return { type: "audio", message };
+    case "video":
+      return { type: "video", message };
+    case "document":
+      return { type: "document", message };
+    case "sticker":
+      return { type: "sticker", message };
+    case "location":
+      return { type: "location", message };
+    case "contacts":
+      return { type: "contacts", message };
+    case "interactive":
+      return { type: "interactive", message };
+    case "reaction":
+      return { type: "reaction", message };
+    case "button":
+      return { type: "button", message };
+    case "order":
+      return { type: "order", message };
+    case "system":
+      return { type: "system", message };
+    case "referral":
+      return { type: "referral", message };
+    default:
+      return { type: "unsupported", message };
+  }
+}
+
+// src/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(options) {
+  const { signature, rawBody, appSecret } = options;
+  if (!signature) {
+    return false;
+  }
+  const signatureHash = signature.startsWith("sha256=") ? signature.slice(7) : signature;
+  const hmac = createHmac("sha256", appSecret);
+  const bodyBuffer = typeof rawBody === "string" ? Buffer.from(rawBody, "utf-8") : rawBody;
+  const expectedHash = hmac.update(bodyBuffer).digest("hex");
+  const signatureBuffer = Buffer.from(signatureHash, "utf-8");
+  const expectedBuffer = Buffer.from(expectedHash, "utf-8");
+  if (signatureBuffer.length !== expectedBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(signatureBuffer, expectedBuffer);
+}
+
+// src/helpers.ts
+var MEDIA_TYPES = /* @__PURE__ */ new Set(["image", "audio", "video", "document", "sticker"]);
+function isMediaMessage(message) {
+  return MEDIA_TYPES.has(message.type);
+}
+function extractMediaId(message) {
+  if (!isMediaMessage(message)) {
+    return void 0;
+  }
+  switch (message.type) {
+    case "image":
+      return message.image.id;
+    case "audio":
+      return message.audio.id;
+    case "video":
+      return message.video.id;
+    case "document":
+      return message.document.id;
+    case "sticker":
+      return message.sticker.id;
+    default:
+      return void 0;
+  }
+}
+function getContactInfo(webhook) {
+  const entry = webhook.entry?.[0];
+  const change = entry?.changes?.[0];
+  const value = change?.value;
+  if (!value || !("contacts" in value) || !value.contacts?.length) {
+    return void 0;
+  }
+  const contact = value.contacts[0];
+  const metadata = value.metadata;
+  return {
+    waId: contact.wa_id,
+    profileName: contact.profile?.name,
+    phoneNumberId: metadata.phone_number_id
+  };
+}
+function getMessageTimestamp(message) {
+  const epochSeconds = parseInt(message.timestamp, 10);
+  return new Date(epochSeconds * 1e3);
+}
+export {
+  WABAClient,
+  WABAError,
+  WABAMediaError,
+  WABANetworkError,
+  WABASignatureError,
+  classifyMessage,
+  classifyWebhook,
+  extractMediaId,
+  getContactInfo,
+  getMessageTimestamp,
+  isMediaMessage,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts","../src/webhooks/classify.ts","../src/webhooks/messages.ts","../src/verify.ts","../src/helpers.ts"],"sourcesContent":["/** Base error class for all WABA errors */\nexport class WABAError extends Error {\n  constructor(\n    message: string,\n    public readonly code?: number,\n    public readonly details?: unknown\n  ) {\n    super(message);\n    this.name = 'WABAError';\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Error for media-related failures (404, access denied) */\nexport class WABAMediaError extends WABAError {\n  constructor(\n    message: string,\n    public readonly mediaId: string,\n    code?: number\n  ) {\n    super(message, code);\n    this.name = 'WABAMediaError';\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Error for network/connection failures */\nexport class WABANetworkError extends WABAError {\n  override readonly cause?: Error;\n\n  constructor(message: string, cause?: Error) {\n    super(message);\n    this.name = 'WABANetworkError';\n    this.cause = cause;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Error for invalid webhook signatures */\nexport class WABASignatureError extends WABAError {\n  constructor(message: string = 'Invalid webhook signature') {\n    super(message);\n    this.name = 'WABASignatureError';\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n","import type { WABAClientOptions, GetMediaOptions } from './types/client.js';\nimport type {\n  MediaMetadata,\n  MediaStreamResult,\n  MediaBufferResult,\n  RawMediaResponse,\n} from './types/media.js';\nimport { WABAMediaError, WABANetworkError } from './errors.js';\n\nconst DEFAULT_API_VERSION = 'v22.0';\nconst DEFAULT_BASE_URL = 'https://graph.facebook.com';\n\n/**\n * Client for WhatsApp Business API media operations.\n */\nexport class WABAClient {\n  private readonly accessToken: string;\n  private readonly apiVersion: string;\n  private readonly baseUrl: string;\n\n  constructor(options: WABAClientOptions) {\n    this.accessToken = options.accessToken;\n    this.apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;\n    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;\n  }\n\n  /**\n   * Fetches media by ID from WhatsApp Business API.\n   *\n   * Step 1: GET /{apiVersion}/{mediaId} → retrieves temporary URL + metadata\n   * Step 2: GET {temporaryUrl} → downloads binary content\n   *\n   * @throws {WABAMediaError} - Media not found (404) or access denied\n   * @throws {WABANetworkError} - Network/connection failures\n   */\n  async getMedia(mediaId: string): Promise<MediaStreamResult>;\n  async getMedia(\n    mediaId: string,\n    options: { asBuffer: true }\n  ): Promise<MediaBufferResult>;\n  async getMedia(\n    mediaId: string,\n    options?: GetMediaOptions\n  ): Promise<MediaStreamResult | MediaBufferResult>;\n  async getMedia(\n    mediaId: string,\n    options?: GetMediaOptions\n  ): Promise<MediaStreamResult | MediaBufferResult> {\n    // Step 1: Get media metadata and temporary URL\n    const metadata = await this.fetchMediaMetadata(mediaId);\n\n    // Step 2: Download the actual media\n    const response = await this.downloadMedia(metadata.url, mediaId);\n\n    if (options?.asBuffer) {\n      const buffer = await response.arrayBuffer();\n      return {\n        ...metadata,\n        buffer,\n      };\n    }\n\n    if (!response.body) {\n      throw new WABAMediaError('Response body is null', mediaId);\n    }\n\n    return {\n      ...metadata,\n      stream: response.body,\n    };\n  }\n\n  private async fetchMediaMetadata(mediaId: string): Promise<MediaMetadata> {\n    const url = `${this.baseUrl}/${this.apiVersion}/${mediaId}`;\n\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          Authorization: `Bearer ${this.accessToken}`,\n        },\n      });\n    } catch (error) {\n      throw new WABANetworkError(\n        `Failed to fetch media metadata: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        error instanceof Error ? error : undefined\n      );\n    }\n\n    if (!response.ok) {\n      const errorBody = await response.text().catch(() => 'Unknown error');\n      throw new WABAMediaError(\n        `Failed to fetch media metadata: ${response.status} ${errorBody}`,\n        mediaId,\n        response.status\n      );\n    }\n\n    const data = (await response.json()) as RawMediaResponse;\n\n    // Normalize snake_case to camelCase\n    return {\n      id: data.id,\n      mimeType: data.mime_type,\n      sha256: data.sha256,\n      fileSize: parseInt(data.file_size, 10),\n      url: data.url,\n    };\n  }\n\n  private async downloadMedia(url: string, mediaId: string): Promise<Response> {\n    let response: Response;\n    try {\n      response = await fetch(url, {\n        method: 'GET',\n        headers: {\n          Authorization: `Bearer ${this.accessToken}`,\n        },\n      });\n    } catch (error) {\n      throw new WABANetworkError(\n        `Failed to download media: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        error instanceof Error ? error : undefined\n      );\n    }\n\n    if (!response.ok) {\n      throw new WABAMediaError(\n        `Failed to download media: ${response.status}`,\n        mediaId,\n        response.status\n      );\n    }\n\n    return response;\n  }\n}\n","import type {\n  WebhookPayload,\n  WebhookClassification,\n  MessageWebhookValue,\n  StatusWebhookValue,\n  CallWebhookValue,\n} from '../types/webhooks.js';\n\n/**\n * Classifies a webhook payload into its type.\n * Returns a discriminated union for type-safe handling.\n */\nexport function classifyWebhook(payload: WebhookPayload): WebhookClassification {\n  const entry = payload.entry?.[0];\n  const change = entry?.changes?.[0];\n  const value = change?.value;\n\n  if (!value) {\n    return { type: 'unknown', payload };\n  }\n\n  // Check for calls array (call webhooks)\n  if ('calls' in value && Array.isArray(value.calls)) {\n    return { type: 'call', payload: value as CallWebhookValue };\n  }\n\n  // Check for statuses array (status webhooks)\n  if ('statuses' in value && Array.isArray(value.statuses)) {\n    return { type: 'status', payload: value as StatusWebhookValue };\n  }\n\n  // Check for messages array (message webhooks)\n  if ('messages' in value && Array.isArray(value.messages)) {\n    return { type: 'message', payload: value as MessageWebhookValue };\n  }\n\n  // Check for errors without messages (error webhook)\n  if ('errors' in value && Array.isArray(value.errors)) {\n    return { type: 'message', payload: value as MessageWebhookValue };\n  }\n\n  return { type: 'unknown', payload };\n}\n","import type {\n  IncomingMessage,\n  MessageClassification,\n  TextMessage,\n  ImageMessage,\n  AudioMessage,\n  VideoMessage,\n  DocumentMessage,\n  StickerMessage,\n  LocationMessage,\n  ContactsMessage,\n  InteractiveMessage,\n  ReactionMessage,\n  ButtonMessage,\n  OrderMessage,\n  SystemMessage,\n  ReferralMessage,\n  UnsupportedMessage,\n} from '../types/messages.js';\n\n/**\n * Classifies an incoming message by its type.\n * Returns a discriminated union for type-safe handling.\n */\nexport function classifyMessage(message: IncomingMessage): MessageClassification {\n  switch (message.type) {\n    case 'text':\n      return { type: 'text', message: message as TextMessage };\n    case 'image':\n      return { type: 'image', message: message as ImageMessage };\n    case 'audio':\n      return { type: 'audio', message: message as AudioMessage };\n    case 'video':\n      return { type: 'video', message: message as VideoMessage };\n    case 'document':\n      return { type: 'document', message: message as DocumentMessage };\n    case 'sticker':\n      return { type: 'sticker', message: message as StickerMessage };\n    case 'location':\n      return { type: 'location', message: message as LocationMessage };\n    case 'contacts':\n      return { type: 'contacts', message: message as ContactsMessage };\n    case 'interactive':\n      return { type: 'interactive', message: message as InteractiveMessage };\n    case 'reaction':\n      return { type: 'reaction', message: message as ReactionMessage };\n    case 'button':\n      return { type: 'button', message: message as ButtonMessage };\n    case 'order':\n      return { type: 'order', message: message as OrderMessage };\n    case 'system':\n      return { type: 'system', message: message as SystemMessage };\n    case 'referral':\n      return { type: 'referral', message: message as ReferralMessage };\n    default:\n      return { type: 'unsupported', message: message as UnsupportedMessage };\n  }\n}\n","import { createHmac, timingSafeEqual } from 'node:crypto';\n\nexport interface VerifyWebhookSignatureOptions {\n  /** X-Hub-Signature-256 header value */\n  signature: string | undefined;\n  /** Raw request body (NOT parsed JSON) */\n  rawBody: Buffer | string;\n  /** Meta App Secret */\n  appSecret: string;\n}\n\n/**\n * Verifies webhook signature using HMAC-SHA256.\n * Uses timing-safe comparison to prevent timing attacks.\n *\n * @returns true if signature is valid, false otherwise\n */\nexport function verifyWebhookSignature(\n  options: VerifyWebhookSignatureOptions\n): boolean {\n  const { signature, rawBody, appSecret } = options;\n\n  if (!signature) {\n    return false;\n  }\n\n  // Remove 'sha256=' prefix if present\n  const signatureHash = signature.startsWith('sha256=')\n    ? signature.slice(7)\n    : signature;\n\n  // Compute expected signature\n  const hmac = createHmac('sha256', appSecret);\n  const bodyBuffer =\n    typeof rawBody === 'string' ? Buffer.from(rawBody, 'utf-8') : rawBody;\n  const expectedHash = hmac.update(bodyBuffer).digest('hex');\n\n  // Convert to buffers for timing-safe comparison\n  const signatureBuffer = Buffer.from(signatureHash, 'utf-8');\n  const expectedBuffer = Buffer.from(expectedHash, 'utf-8');\n\n  // Ensure same length before comparison\n  if (signatureBuffer.length !== expectedBuffer.length) {\n    return false;\n  }\n\n  return timingSafeEqual(signatureBuffer, expectedBuffer);\n}\n","import type {\n  IncomingMessage,\n  MediaMessage,\n  ImageMessage,\n  AudioMessage,\n  VideoMessage,\n  DocumentMessage,\n  StickerMessage,\n} from './types/messages.js';\nimport type { WebhookPayload } from './types/webhooks.js';\n\nconst MEDIA_TYPES = new Set(['image', 'audio', 'video', 'document', 'sticker']);\n\n/**\n * Type guard: returns true if message contains downloadable media.\n * Narrows type to messages with image/audio/video/document/sticker.\n */\nexport function isMediaMessage(message: IncomingMessage): message is MediaMessage {\n  return MEDIA_TYPES.has(message.type);\n}\n\n/**\n * Extracts media ID from any media message type.\n * Returns undefined if message has no media.\n */\nexport function extractMediaId(message: IncomingMessage): string | undefined {\n  if (!isMediaMessage(message)) {\n    return undefined;\n  }\n\n  switch (message.type) {\n    case 'image':\n      return (message as ImageMessage).image.id;\n    case 'audio':\n      return (message as AudioMessage).audio.id;\n    case 'video':\n      return (message as VideoMessage).video.id;\n    case 'document':\n      return (message as DocumentMessage).document.id;\n    case 'sticker':\n      return (message as StickerMessage).sticker.id;\n    default:\n      return undefined;\n  }\n}\n\nexport interface ContactInfo {\n  waId: string;\n  profileName: string | undefined;\n  phoneNumberId: string;\n}\n\n/**\n * Extracts sender info from webhook payload.\n * Returns undefined if the webhook doesn't contain message contact info.\n */\nexport function getContactInfo(webhook: WebhookPayload): ContactInfo | undefined {\n  const entry = webhook.entry?.[0];\n  const change = entry?.changes?.[0];\n  const value = change?.value;\n\n  if (!value || !('contacts' in value) || !value.contacts?.length) {\n    return undefined;\n  }\n\n  const contact = value.contacts[0];\n  const metadata = value.metadata;\n\n  return {\n    waId: contact.wa_id,\n    profileName: contact.profile?.name,\n    phoneNumberId: metadata.phone_number_id,\n  };\n}\n\n/**\n * Parses message timestamp to Date object.\n * WhatsApp timestamps are Unix epoch seconds as strings.\n */\nexport function getMessageTimestamp(message: IncomingMessage): Date {\n  const epochSeconds = parseInt(message.timestamp, 10);\n  return new Date(epochSeconds * 1000);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "waba-toolkit",
+  "version": "0.1.0",
+  "description": "Minimal, type-safe toolkit for WhatsApp Business API webhook processing and media handling",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "whatsapp",
+    "waba",
+    "whatsapp-business-api",
+    "webhook",
+    "meta"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}