@ariaflowagents/messaging-meta 0.8.1

package/dist/webhook/normalizer.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @module webhook/normalizer
+ *
+ * Normalize raw Meta webhook payloads into a flat, platform-agnostic shape.
+ *
+ * Meta delivers webhooks with a deeply nested structure that varies between
+ * WhatsApp Business, Messenger, and Instagram. This module flattens the
+ * nesting into three simple arrays — `messages`, `statuses`, and `reactions`
+ * — so downstream consumers can process events uniformly regardless of the
+ * originating platform.
+ *
+ * Inspired by the normalization approach used by Kapso and other Meta SDK
+ * wrappers.
+ */
+/** Aggregated result of normalizing a single webhook delivery. */
+export interface NormalizedWebhookEvents {
+    /** Inbound messages from users. */
+    messages: NormalizedMessage[];
+    /** Delivery / read / failure status updates. */
+    statuses: NormalizedStatus[];
+    /** Emoji reactions on existing messages. */
+    reactions: NormalizedReaction[];
+}
+/** A single inbound message extracted from the webhook payload. */
+export interface NormalizedMessage {
+    /** Platform message ID. */
+    id: string;
+    /** Sender identifier (phone number for WhatsApp, PSID for Messenger/Instagram). */
+    from: string;
+    /** Unix timestamp (seconds) as a string. */
+    timestamp: string;
+    /** Message type (e.g. `"text"`, `"image"`, `"interactive"`, `"postback"`). */
+    type: string;
+    /** Phone number ID or page ID that received the message. */
+    phoneNumberId: string;
+    /** Display name of the contact, when available. */
+    contactName?: string;
+    text?: {
+        body: string;
+    };
+    image?: {
+        id: string;
+        caption?: string;
+        mime_type?: string;
+    };
+    video?: {
+        id: string;
+        caption?: string;
+        mime_type?: string;
+    };
+    audio?: {
+        id: string;
+        mime_type?: string;
+    };
+    document?: {
+        id: string;
+        filename?: string;
+        caption?: string;
+        mime_type?: string;
+    };
+    sticker?: {
+        id: string;
+        mime_type?: string;
+    };
+    location?: {
+        latitude: number;
+        longitude: number;
+        name?: string;
+        address?: string;
+    };
+    contacts?: unknown[];
+    interactive?: {
+        type: string;
+        button_reply?: {
+            id: string;
+            title: string;
+        };
+        list_reply?: {
+            id: string;
+            title: string;
+            description?: string;
+        };
+    };
+    button?: {
+        text: string;
+        payload: string;
+    };
+    /** Quoted/replied-to message context. */
+    context?: {
+        message_id: string;
+        from?: string;
+    };
+    /** Reaction (only set for WhatsApp reaction messages before they're split out). */
+    reaction?: {
+        message_id: string;
+        emoji: string;
+    };
+    /** Click-to-WhatsApp ad referral data. */
+    referral?: unknown;
+}
+/** A delivery status update. */
+export interface NormalizedStatus {
+    /** Message ID this status refers to. */
+    id: string;
+    /** Recipient identifier. */
+    recipientId: string;
+    /** Status value. */
+    status: 'sent' | 'delivered' | 'read' | 'failed';
+    /** Unix timestamp (seconds) as a string. */
+    timestamp: string;
+    /** Phone number ID or page ID that sent the original message. */
+    phoneNumberId: string;
+    /** Conversation metadata (WhatsApp-specific). */
+    conversation?: {
+        id: string;
+        expiration_timestamp?: string;
+        origin?: {
+            type: string;
+        };
+    };
+    /** Pricing information (WhatsApp-specific). */
+    pricing?: {
+        billable: boolean;
+        pricing_model: string;
+        category: string;
+    };
+    /** Error details when `status === "failed"`. */
+    errors?: Array<{
+        code: number;
+        title?: string;
+        message?: string;
+    }>;
+}
+/** An emoji reaction on an existing message. */
+export interface NormalizedReaction {
+    /** ID of the message that was reacted to. */
+    messageId: string;
+    /** Sender of the reaction. */
+    from: string;
+    /** Emoji used in the reaction (empty string means reaction was removed). */
+    emoji: string;
+    /** Phone number ID or page ID that received the reaction. */
+    phoneNumberId: string;
+    /** Unix timestamp (seconds) as a string. */
+    timestamp: string;
+}
+/**
+ * Normalize a raw Meta webhook payload into flat arrays of messages,
+ * statuses, and reactions.
+ *
+ * Supports:
+ * - **WhatsApp Business** (`object === "whatsapp_business_account"`)
+ * - **Messenger / Instagram** (`object === "page"` or `object === "instagram"`)
+ *
+ * Unknown `object` types return empty arrays without throwing.
+ *
+ * @param payload - Parsed JSON body from the webhook POST request.
+ * @returns Normalized events grouped by type.
+ *
+ * @example
+ * ```ts
+ * const events = normalizeWebhook(JSON.parse(rawBody));
+ * for (const msg of events.messages) {
+ *   console.log(`${msg.from}: ${msg.text?.body}`);
+ * }
+ * ```
+ */
+export declare function normalizeWebhook(payload: unknown): NormalizedWebhookEvents;
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/webhook/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/webhook/normalizer.ts"],"names":[],"mappings":"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"}

package/dist/webhook/normalizer.js

@@ -0,0 +1,301 @@
+/**
+ * @module webhook/normalizer
+ *
+ * Normalize raw Meta webhook payloads into a flat, platform-agnostic shape.
+ *
+ * Meta delivers webhooks with a deeply nested structure that varies between
+ * WhatsApp Business, Messenger, and Instagram. This module flattens the
+ * nesting into three simple arrays — `messages`, `statuses`, and `reactions`
+ * — so downstream consumers can process events uniformly regardless of the
+ * originating platform.
+ *
+ * Inspired by the normalization approach used by Kapso and other Meta SDK
+ * wrappers.
+ */
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a raw Meta webhook payload into flat arrays of messages,
+ * statuses, and reactions.
+ *
+ * Supports:
+ * - **WhatsApp Business** (`object === "whatsapp_business_account"`)
+ * - **Messenger / Instagram** (`object === "page"` or `object === "instagram"`)
+ *
+ * Unknown `object` types return empty arrays without throwing.
+ *
+ * @param payload - Parsed JSON body from the webhook POST request.
+ * @returns Normalized events grouped by type.
+ *
+ * @example
+ * ```ts
+ * const events = normalizeWebhook(JSON.parse(rawBody));
+ * for (const msg of events.messages) {
+ *   console.log(`${msg.from}: ${msg.text?.body}`);
+ * }
+ * ```
+ */
+export function normalizeWebhook(payload) {
+    const result = {
+        messages: [],
+        statuses: [],
+        reactions: [],
+    };
+    if (!payload || typeof payload !== 'object') {
+        return result;
+    }
+    const p = payload;
+    if (p.object === 'whatsapp_business_account') {
+        return normalizeWhatsAppWebhook(p);
+    }
+    if (p.object === 'page' || p.object === 'instagram') {
+        return normalizePageWebhook(p);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// WhatsApp Business normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a WhatsApp Business Account webhook payload.
+ *
+ * Structure: `entry[].changes[]` where `field === "messages"`.
+ * Each change's `value` contains `messages[]`, `statuses[]`, and `contacts[]`.
+ */
+function normalizeWhatsAppWebhook(payload) {
+    const result = {
+        messages: [],
+        statuses: [],
+        reactions: [],
+    };
+    const entries = payload.entry ?? [];
+    for (const entry of entries) {
+        const changes = entry.changes ?? [];
+        for (const change of changes) {
+            if (change.field !== 'messages')
+                continue;
+            const value = change.value;
+            if (!value)
+                continue;
+            const phoneNumberId = value.metadata?.phone_number_id ?? '';
+            // Build a contact-name lookup from the contacts array.
+            const contactNames = new Map();
+            for (const contact of value.contacts ?? []) {
+                if (contact.wa_id && contact.profile?.name) {
+                    contactNames.set(contact.wa_id, contact.profile.name);
+                }
+            }
+            // --- Messages ---
+            for (const msg of value.messages ?? []) {
+                // Reactions are delivered as messages with type "reaction" — split them out.
+                if (msg.type === 'reaction' && msg.reaction) {
+                    result.reactions.push({
+                        messageId: msg.reaction.message_id ?? '',
+                        from: msg.from ?? '',
+                        emoji: msg.reaction.emoji ?? '',
+                        phoneNumberId,
+                        timestamp: msg.timestamp ?? '',
+                    });
+                    continue;
+                }
+                const normalized = {
+                    id: msg.id ?? '',
+                    from: msg.from ?? '',
+                    timestamp: msg.timestamp ?? '',
+                    type: msg.type ?? 'unknown',
+                    phoneNumberId,
+                    contactName: contactNames.get(msg.from ?? ''),
+                };
+                // Attach type-specific payload.
+                if (msg.text)
+                    normalized.text = { body: msg.text.body ?? '' };
+                if (msg.image)
+                    normalized.image = msg.image;
+                if (msg.video)
+                    normalized.video = msg.video;
+                if (msg.audio)
+                    normalized.audio = msg.audio;
+                if (msg.document)
+                    normalized.document = msg.document;
+                if (msg.sticker)
+                    normalized.sticker = msg.sticker;
+                if (msg.location)
+                    normalized.location = msg.location;
+                if (msg.contacts)
+                    normalized.contacts = msg.contacts;
+                if (msg.interactive)
+                    normalized.interactive = msg.interactive;
+                if (msg.button)
+                    normalized.button = msg.button;
+                if (msg.context)
+                    normalized.context = msg.context;
+                if (msg.referral)
+                    normalized.referral = msg.referral;
+                result.messages.push(normalized);
+            }
+            // --- Statuses ---
+            for (const status of value.statuses ?? []) {
+                const normalizedStatus = {
+                    id: status.id ?? '',
+                    recipientId: status.recipient_id ?? '',
+                    status: normalizeStatusValue(status.status),
+                    timestamp: status.timestamp ?? '',
+                    phoneNumberId,
+                };
+                if (status.conversation) {
+                    normalizedStatus.conversation = status.conversation;
+                }
+                if (status.pricing) {
+                    normalizedStatus.pricing = status.pricing;
+                }
+                if (status.errors) {
+                    normalizedStatus.errors = status.errors;
+                }
+                result.statuses.push(normalizedStatus);
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Page / Instagram normalization
+// ---------------------------------------------------------------------------
+/**
+ * Normalize a Messenger or Instagram webhook payload.
+ *
+ * Structure: `entry[].messaging[]` where each event has `sender.id`,
+ * `recipient.id`, and a timestamp.
+ */
+function normalizePageWebhook(payload) {
+    const result = {
+        messages: [],
+        statuses: [],
+        reactions: [],
+    };
+    const entries = payload.entry ?? [];
+    for (const entry of entries) {
+        const pageId = entry.id ?? '';
+        const events = entry.messaging ?? [];
+        for (const event of events) {
+            const senderId = event.sender?.id ?? '';
+            const timestamp = String(event.timestamp ?? '');
+            // --- Inbound message ---
+            if (event.message && !event.message.is_echo) {
+                const msg = event.message;
+                const normalized = {
+                    id: msg.mid ?? '',
+                    from: senderId,
+                    timestamp,
+                    type: resolvePageMessageType(msg),
+                    phoneNumberId: pageId,
+                };
+                if (msg.text) {
+                    normalized.text = { body: msg.text };
+                }
+                // Attachments (images, video, audio, files).
+                if (msg.attachments && msg.attachments.length > 0) {
+                    const first = msg.attachments[0];
+                    const attachType = first.type ?? 'unknown';
+                    if (attachType === 'image' && first.payload) {
+                        normalized.image = { id: '', ...first.payload };
+                    }
+                    else if (attachType === 'video' && first.payload) {
+                        normalized.video = { id: '', ...first.payload };
+                    }
+                    else if (attachType === 'audio' && first.payload) {
+                        normalized.audio = { id: '', ...first.payload };
+                    }
+                    else if (attachType === 'file' && first.payload) {
+                        normalized.document = { id: '', ...first.payload };
+                    }
+                }
+                // Reply context.
+                if (msg.reply_to?.mid) {
+                    normalized.context = { message_id: msg.reply_to.mid };
+                }
+                result.messages.push(normalized);
+                continue;
+            }
+            // --- Postback (button tap / get-started) ---
+            if (event.postback) {
+                const pb = event.postback;
+                result.messages.push({
+                    id: pb.mid ?? `postback_${timestamp}`,
+                    from: senderId,
+                    timestamp,
+                    type: 'postback',
+                    phoneNumberId: pageId,
+                    button: {
+                        text: pb.title ?? '',
+                        payload: pb.payload ?? '',
+                    },
+                });
+                continue;
+            }
+            // --- Reaction ---
+            if (event.reaction) {
+                const r = event.reaction;
+                result.reactions.push({
+                    messageId: r.mid ?? '',
+                    from: senderId,
+                    emoji: r.emoji ?? r.reaction ?? '',
+                    phoneNumberId: pageId,
+                    timestamp,
+                });
+                continue;
+            }
+            // --- Delivery receipt ---
+            if (event.delivery) {
+                for (const mid of event.delivery.mids ?? []) {
+                    result.statuses.push({
+                        id: mid,
+                        recipientId: senderId,
+                        status: 'delivered',
+                        timestamp,
+                        phoneNumberId: pageId,
+                    });
+                }
+                continue;
+            }
+            // --- Read receipt ---
+            if (event.read) {
+                result.statuses.push({
+                    id: `read_${timestamp}`,
+                    recipientId: senderId,
+                    status: 'read',
+                    timestamp,
+                    phoneNumberId: pageId,
+                });
+                continue;
+            }
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Resolve the message type for a Messenger / Instagram message. */
+function resolvePageMessageType(msg) {
+    if (msg.attachments && msg.attachments.length > 0) {
+        return msg.attachments[0]?.type ?? 'attachment';
+    }
+    if (msg.text) {
+        return 'text';
+    }
+    return 'unknown';
+}
+/** Normalise a status string to the union type, defaulting to `"sent"`. */
+function normalizeStatusValue(raw) {
+    switch (raw) {
+        case 'sent':
+        case 'delivered':
+        case 'read':
+        case 'failed':
+            return raw;
+        default:
+            return 'sent';
+    }
+}
+//# sourceMappingURL=normalizer.js.map

package/dist/webhook/normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.js","sourceRoot":"","sources":["../../src/webhook/normalizer.ts"],"names":[],"mappings":"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"}

package/dist/webhook/verifier.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module webhook/verifier
+ *
+ * HMAC-SHA256 signature verification for Meta webhook payloads.
+ *
+ * Meta signs every webhook delivery with a `X-Hub-Signature-256` header
+ * containing `sha256=<hex>`. This module validates that signature using
+ * the app secret, ensuring the payload was not tampered with in transit.
+ *
+ * @see https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
+ */
+/** Options for {@link verifySignature}. */
+export interface VerifySignatureOptions {
+    /** The Meta app secret used as the HMAC key. */
+    appSecret: string;
+    /** Raw request body exactly as received (before any JSON parsing). */
+    rawBody: Buffer | string;
+    /** Value of the `X-Hub-Signature-256` header (e.g. `"sha256=abcdef..."`). */
+    signatureHeader: string;
+}
+/**
+ * Verify the HMAC-SHA256 signature of a Meta webhook payload.
+ *
+ * Uses timing-safe comparison to prevent timing attacks. Returns `false`
+ * (rather than throwing) when the signature is missing, malformed, or invalid
+ * so that callers can respond with an appropriate HTTP status.
+ *
+ * @param options - Verification parameters.
+ * @returns `true` if the signature is valid, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const valid = verifySignature({
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   rawBody: request.rawBody,
+ *   signatureHeader: request.headers['x-hub-signature-256'] ?? '',
+ * });
+ *
+ * if (!valid) {
+ *   return new Response('Invalid signature', { status: 403 });
+ * }
+ * ```
+ */
+export declare function verifySignature(options: VerifySignatureOptions): boolean;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/webhook/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/webhook/verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CA6BxE"}

package/dist/webhook/verifier.js

@@ -0,0 +1,62 @@
+/**
+ * @module webhook/verifier
+ *
+ * HMAC-SHA256 signature verification for Meta webhook payloads.
+ *
+ * Meta signs every webhook delivery with a `X-Hub-Signature-256` header
+ * containing `sha256=<hex>`. This module validates that signature using
+ * the app secret, ensuring the payload was not tampered with in transit.
+ *
+ * @see https://developers.facebook.com/docs/graph-api/webhooks/getting-started#verification-requests
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify the HMAC-SHA256 signature of a Meta webhook payload.
+ *
+ * Uses timing-safe comparison to prevent timing attacks. Returns `false`
+ * (rather than throwing) when the signature is missing, malformed, or invalid
+ * so that callers can respond with an appropriate HTTP status.
+ *
+ * @param options - Verification parameters.
+ * @returns `true` if the signature is valid, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const valid = verifySignature({
+ *   appSecret: process.env.META_APP_SECRET!,
+ *   rawBody: request.rawBody,
+ *   signatureHeader: request.headers['x-hub-signature-256'] ?? '',
+ * });
+ *
+ * if (!valid) {
+ *   return new Response('Invalid signature', { status: 403 });
+ * }
+ * ```
+ */
+export function verifySignature(options) {
+    const { appSecret, rawBody, signatureHeader } = options;
+    // The header must start with the `sha256=` prefix.
+    if (!signatureHeader || !signatureHeader.startsWith('sha256=')) {
+        return false;
+    }
+    const expectedSignature = signatureHeader.slice(7); // Strip `sha256=` prefix.
+    // Validate that the expected signature is plausible hex (64 hex chars for SHA-256).
+    if (!/^[0-9a-f]{64}$/i.test(expectedSignature)) {
+        return false;
+    }
+    const actualSignature = createHmac('sha256', appSecret)
+        .update(typeof rawBody === 'string' ? rawBody : rawBody)
+        .digest('hex');
+    // Use timing-safe comparison to prevent timing side-channel attacks.
+    try {
+        return timingSafeEqual(Buffer.from(expectedSignature, 'hex'), Buffer.from(actualSignature, 'hex'));
+    }
+    catch {
+        // `timingSafeEqual` throws if buffers have different lengths.
+        return false;
+    }
+}
+//# sourceMappingURL=verifier.js.map

package/dist/webhook/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../src/webhook/verifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAgB1D,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAExD,mDAAmD;IACnD,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,iBAAiB,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,0BAA0B;IAE9E,oFAAoF;IACpF,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,eAAe,GAAG,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC;SACpD,MAAM,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;SACvD,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjB,qEAAqE;IACrE,IAAI,CAAC;QACH,OAAO,eAAe,CACpB,MAAM,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,EACrC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,CACpC,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}