@flink-app/whatsapp-plugin 2.0.0-alpha.74

package/src/WhatsappTransport.ts

@@ -0,0 +1,297 @@
+import * as crypto from "crypto";
+import { FlinkLogFactory } from "@flink-app/flink";
+import {
+    WhatsappConnectionOptions,
+    WhatsappMedia,
+    WhatsappMessage,
+    WhatsappMessageType,
+    WhatsappInteractiveReply,
+    WhatsappStatusUpdate,
+    WhatsappSendResult,
+} from "./types";
+
+const log = FlinkLogFactory.createLogger("flink.whatsapp-plugin.transport");
+
+const DEFAULT_GRAPH_API_VERSION = "v21.0";
+
+function graphUrl(version: string, path: string): string {
+    return `https://graph.facebook.com/${version}/${path}`;
+}
+
+/** Verify HMAC-SHA256 webhook signature from Meta */
+export function verifySignature(rawBody: string | Buffer, signature: string, appSecret: string): boolean {
+    if (!signature || !signature.startsWith("sha256=")) {
+        return false;
+    }
+    const expected = crypto
+        .createHmac("sha256", appSecret)
+        .update(rawBody)
+        .digest("hex");
+    return crypto.timingSafeEqual(
+        Buffer.from(signature.replace("sha256=", "")),
+        Buffer.from(expected)
+    );
+}
+
+/** Make an authenticated Graph API call */
+export async function callApi(
+    path: string,
+    method: string,
+    body: Record<string, any> | undefined,
+    accessToken: string,
+    version: string = DEFAULT_GRAPH_API_VERSION
+): Promise<any> {
+    const url = graphUrl(version, path);
+    const headers: Record<string, string> = {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+    };
+
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const data: any = await response.json();
+
+    if (!response.ok) {
+        const errMsg = data?.error?.message ?? response.statusText;
+        throw new Error(`WhatsApp API error (${response.status}): ${errMsg}`);
+    }
+
+    return data;
+}
+
+/** Send a message via the WhatsApp Cloud API */
+export async function sendMessage(
+    phoneNumberId: string,
+    accessToken: string,
+    payload: Record<string, any>,
+    version: string = DEFAULT_GRAPH_API_VERSION
+): Promise<WhatsappSendResult> {
+    const data = await callApi(
+        `${phoneNumberId}/messages`,
+        "POST",
+        { messaging_product: "whatsapp", ...payload },
+        accessToken,
+        version
+    );
+    return { messageId: data.messages?.[0]?.id ?? "" };
+}
+
+/** Upload media to WhatsApp (multipart form data) */
+export async function uploadMedia(
+    phoneNumberId: string,
+    accessToken: string,
+    file: Buffer,
+    mimeType: string,
+    filename: string,
+    version: string = DEFAULT_GRAPH_API_VERSION
+): Promise<string> {
+    const url = graphUrl(version, `${phoneNumberId}/media`);
+
+    const formData = new FormData();
+    formData.append("messaging_product", "whatsapp");
+    formData.append("file", new Blob([file], { type: mimeType }), filename);
+    formData.append("type", mimeType);
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}` },
+        body: formData,
+    });
+
+    const data: any = await response.json();
+
+    if (!response.ok) {
+        const errMsg = data?.error?.message ?? response.statusText;
+        throw new Error(`WhatsApp media upload error (${response.status}): ${errMsg}`);
+    }
+
+    return data.id;
+}
+
+/** Download media by ID (two-step: get URL, then fetch binary) */
+export async function downloadMedia(
+    mediaId: string,
+    accessToken: string,
+    version: string = DEFAULT_GRAPH_API_VERSION
+): Promise<Buffer> {
+    // Step 1: Get the media URL
+    const mediaInfo = await callApi(mediaId, "GET", undefined, accessToken, version);
+    const mediaUrl = mediaInfo.url;
+
+    if (!mediaUrl) {
+        throw new Error(`No download URL returned for media ${mediaId}`);
+    }
+
+    // Step 2: Download the binary content
+    const response = await fetch(mediaUrl, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to download media ${mediaId}: ${response.status} ${response.statusText}`);
+    }
+
+    return Buffer.from(await response.arrayBuffer());
+}
+
+/** Mark a message as read */
+export async function markAsRead(
+    phoneNumberId: string,
+    accessToken: string,
+    messageId: string,
+    version: string = DEFAULT_GRAPH_API_VERSION
+): Promise<void> {
+    await callApi(
+        `${phoneNumberId}/messages`,
+        "POST",
+        {
+            messaging_product: "whatsapp",
+            status: "read",
+            message_id: messageId,
+        },
+        accessToken,
+        version
+    );
+}
+
+function resolveMessageType(msgType: string): WhatsappMessageType {
+    const known: WhatsappMessageType[] = [
+        "text", "image", "video", "audio", "document",
+        "sticker", "location", "contacts", "interactive",
+        "reaction", "order",
+    ];
+    return known.includes(msgType as WhatsappMessageType)
+        ? (msgType as WhatsappMessageType)
+        : "unknown";
+}
+
+function extractMedia(msg: Record<string, any>, type: string): WhatsappMedia | undefined {
+    const mediaTypes = ["image", "video", "audio", "document", "sticker"];
+    if (!mediaTypes.includes(type)) return undefined;
+
+    const mediaData = msg[type];
+    if (!mediaData) return undefined;
+
+    return {
+        id: mediaData.id,
+        mimeType: mediaData.mime_type,
+        sha256: mediaData.sha256,
+        caption: mediaData.caption,
+        filename: mediaData.filename,
+    };
+}
+
+function extractInteractive(msg: Record<string, any>): WhatsappInteractiveReply | undefined {
+    const interactive = msg.interactive;
+    if (!interactive) return undefined;
+
+    const type = interactive.type === "button_reply" ? "button_reply" : "list_reply";
+
+    if (type === "button_reply" && interactive.button_reply) {
+        return {
+            type: "button_reply",
+            buttonReplyId: interactive.button_reply.id,
+            buttonReplyTitle: interactive.button_reply.title,
+        };
+    }
+
+    if (type === "list_reply" && interactive.list_reply) {
+        return {
+            type: "list_reply",
+            listReplyId: interactive.list_reply.id,
+            listReplyTitle: interactive.list_reply.title,
+            listReplyDescription: interactive.list_reply.description,
+        };
+    }
+
+    return undefined;
+}
+
+/** Extract normalized messages and status updates from a webhook payload */
+export function normalizeWebhookPayload(
+    payload: Record<string, any>,
+    connectionId: string,
+    phoneNumberId: string
+): { messages: WhatsappMessage[]; statuses: WhatsappStatusUpdate[] } {
+    const messages: WhatsappMessage[] = [];
+    const statuses: WhatsappStatusUpdate[] = [];
+
+    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 contacts = value.contacts ?? [];
+            const contactMap = new Map<string, string>();
+            for (const contact of contacts) {
+                contactMap.set(contact.wa_id, contact.profile?.name ?? "");
+            }
+
+            // Process messages
+            for (const msg of value.messages ?? []) {
+                const type = resolveMessageType(msg.type);
+                const from = msg.from ?? "";
+
+                const normalized: WhatsappMessage = {
+                    connectionId,
+                    messageId: msg.id ?? "",
+                    from,
+                    to: phoneNumberId,
+                    senderName: contactMap.get(from) ?? "",
+                    timestamp: Number(msg.timestamp) || 0,
+                    type,
+                    text: msg.text?.body,
+                    media: extractMedia(msg, msg.type),
+                    location: msg.location
+                        ? {
+                              latitude: msg.location.latitude,
+                              longitude: msg.location.longitude,
+                              name: msg.location.name,
+                              address: msg.location.address,
+                          }
+                        : undefined,
+                    contacts: msg.contacts,
+                    interactive: extractInteractive(msg),
+                    reaction: msg.reaction
+                        ? {
+                              messageId: msg.reaction.message_id,
+                              emoji: msg.reaction.emoji ?? "",
+                          }
+                        : undefined,
+                    raw: msg,
+                };
+
+                messages.push(normalized);
+            }
+
+            // Process statuses
+            for (const status of value.statuses ?? []) {
+                statuses.push({
+                    connectionId,
+                    messageId: status.id ?? "",
+                    recipientId: status.recipient_id ?? "",
+                    status: status.status ?? "failed",
+                    timestamp: Number(status.timestamp) || 0,
+                    errors: status.errors?.map((e: any) => ({
+                        code: e.code,
+                        title: e.title,
+                        message: e.message,
+                        href: e.href,
+                    })),
+                });
+            }
+        }
+    }
+
+    return { messages, statuses };
+}

package/src/autoRegisteredWhatsappHandlers.ts

@@ -0,0 +1,7 @@
+import { WhatsappHandlerFile } from "./types";
+
+/**
+ * Populated at compile time by the Flink compiler extension.
+ * Do not modify manually.
+ */
+export const autoRegisteredWhatsappHandlers: WhatsappHandlerFile[] = [];

package/src/cli/send.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * flink-whatsapp send — send a test message to a WhatsApp number.
+ *
+ * Usage:
+ *   flink-whatsapp send --token <access-token> --phone-id <phone-number-id> --to <number> "Hello world"
+ *
+ * Options:
+ *   --token <token>       Access token (or set WHATSAPP_ACCESS_TOKEN env var)
+ *   --phone-id <id>       Phone number ID (or set WHATSAPP_PHONE_NUMBER_ID env var)
+ *   --to <number>         Recipient phone number (with country code, e.g. 14155551234)
+ *   --api-version <ver>   Graph API version (default: v21.0)
+ */
+
+function parseArgs(argv: string[]): {
+    token: string;
+    phoneNumberId: string;
+    to: string;
+    text: string;
+    apiVersion: string;
+} {
+    const args = argv.slice(2);
+    let token = process.env.WHATSAPP_ACCESS_TOKEN ?? "";
+    let phoneNumberId = process.env.WHATSAPP_PHONE_NUMBER_ID ?? "";
+    let to = "";
+    let apiVersion = "v21.0";
+    const textParts: string[] = [];
+
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--token") {
+            token = args[++i];
+        } else if (a === "--phone-id") {
+            phoneNumberId = args[++i];
+        } else if (a === "--to") {
+            to = args[++i];
+        } else if (a === "--api-version") {
+            apiVersion = args[++i];
+        } else if (!a.startsWith("--")) {
+            textParts.push(a);
+        }
+    }
+
+    const text = textParts.join(" ");
+
+    if (!token) {
+        console.error("Error: --token is required (or set WHATSAPP_ACCESS_TOKEN env var)");
+        process.exit(1);
+    }
+    if (!phoneNumberId) {
+        console.error("Error: --phone-id is required (or set WHATSAPP_PHONE_NUMBER_ID env var)");
+        process.exit(1);
+    }
+    if (!to) {
+        console.error("Error: --to is required");
+        process.exit(1);
+    }
+    if (!text) {
+        console.error("Error: message text is required");
+        process.exit(1);
+    }
+
+    return { token, phoneNumberId, to, text, apiVersion };
+}
+
+async function main(): Promise<void> {
+    const { token, phoneNumberId, to, text, apiVersion } = parseArgs(process.argv);
+
+    const url = `https://graph.facebook.com/${apiVersion}/${phoneNumberId}/messages`;
+
+    console.log(`Sending to ${to}…`);
+
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            messaging_product: "whatsapp",
+            to,
+            type: "text",
+            text: { body: text },
+        }),
+    });
+
+    const data: any = await response.json();
+
+    if (!response.ok) {
+        const errMsg = data?.error?.message ?? response.statusText;
+        throw new Error(`WhatsApp API error (${response.status}): ${errMsg}`);
+    }
+
+    const messageId = data.messages?.[0]?.id ?? "unknown";
+    console.log(`Message sent (id: ${messageId})`);
+}
+
+main().catch((err: unknown) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error("Error:", msg || "unknown error");
+    process.exit(1);
+});

package/src/compiler.ts

@@ -0,0 +1,32 @@
+/**
+ * Build-time compiler plugin descriptor for @flink-app/whatsapp-plugin.
+ *
+ * Import this from flink.config.js — it MUST NOT import from @flink-app/flink
+ * to avoid circular build-time dependencies.
+ *
+ * Usage in flink.config.js:
+ * ```js
+ * const { compilerPlugin } = require("@flink-app/whatsapp-plugin/compiler");
+ * module.exports = {
+ *   compilerPlugins: [compilerPlugin()],
+ * };
+ * ```
+ */
+
+interface FlinkCompilerPlugin {
+    package: string;
+    scanDir: string;
+    generatedFile: string;
+    registrationVar: string;
+    detectBy?: (fileContent: string, filePath: string) => boolean;
+}
+
+export function compilerPlugin(opts?: { scanDir?: string }): FlinkCompilerPlugin {
+    return {
+        package: "@flink-app/whatsapp-plugin",
+        scanDir: opts?.scanDir ?? "src/whatsapp-handlers",
+        generatedFile: "generatedWhatsappHandlers",
+        registrationVar: "autoRegisteredWhatsappHandlers",
+        detectBy: (fileContent) => fileContent.includes("WhatsappHandler"),
+    };
+}

package/src/index.ts

@@ -0,0 +1,197 @@
+import * as crypto from "crypto";
+import { requestContext, FlinkLogFactory } from "@flink-app/flink";
+import { autoRegisteredWhatsappHandlers } from "./autoRegisteredWhatsappHandlers";
+import { WhatsappConnectionManager } from "./WhatsappConnectionManager";
+import { createWhatsappContext, createScopedWhatsappContext } from "./whatsappContext";
+import { matchesRoute } from "./whatsappRouter";
+import { verifySignature, normalizeWebhookPayload } from "./WhatsappTransport";
+import { WhatsappConnectionOptions, WhatsappMessage, WhatsappPluginOptions } from "./types";
+
+const log = FlinkLogFactory.createLogger("flink.whatsapp-plugin");
+
+export * from "./types";
+export * from "./autoRegisteredWhatsappHandlers";
+export * from "./whatsappRouter";
+export { toWhatsappFormat } from "./whatsappFormatting";
+
+export function whatsappPlugin<TCtx>(options: WhatsappPluginOptions<TCtx>) {
+    const manager = new WhatsappConnectionManager();
+    let appCtx: TCtx;
+
+    const webhookPath = options.webhookPath ?? "/webhooks/whatsapp";
+
+    const handleIncomingMessage = async (message: WhatsappMessage) => {
+        const user = options.resolveUser
+            ? await options.resolveUser(message, appCtx)
+            : undefined;
+
+        const permissions =
+            user && options.resolvePermissions
+                ? await options.resolvePermissions(user, appCtx)
+                : [];
+
+        const scopedWhatsapp = createScopedWhatsappContext(manager, message.connectionId);
+
+        let handled = false;
+
+        for (const h of autoRegisteredWhatsappHandlers) {
+            if (!matchesRoute(message, h.Route ?? {})) continue;
+
+            handled = true;
+
+            try {
+                await requestContext.run(
+                    {
+                        reqId: crypto.randomUUID(),
+                        user,
+                        userPermissions: permissions,
+                        timestamp: Date.now(),
+                    },
+                    () =>
+                        h.default({
+                            ctx: appCtx,
+                            message,
+                            user,
+                            permissions,
+                            whatsapp: scopedWhatsapp,
+                        })
+                );
+            } catch (err) {
+                log.error(`WhatsApp handler error for message from "${message.from}"`, err);
+            }
+        }
+
+        if (!handled && options.onUnhandled) {
+            await options.onUnhandled(message, appCtx);
+        }
+    };
+
+    const addConnection = (id: string, connection: WhatsappConnectionOptions) => {
+        manager.add(id, connection);
+    };
+
+    const pluginCtx = createWhatsappContext(manager, addConnection);
+
+    return {
+        id: "whatsapp",
+        ctx: pluginCtx,
+        init: async (app: { ctx: TCtx; expressApp?: any }) => {
+            appCtx = app.ctx;
+
+            // Add connections
+            if (options.connection) {
+                addConnection("default", options.connection);
+            }
+
+            if (options.connections) {
+                for (const [id, conn] of Object.entries(options.connections)) {
+                    addConnection(id, conn);
+                }
+            }
+
+            if (options.loadConnections) {
+                const loaded = await options.loadConnections(app.ctx);
+                for (const [id, conn] of Object.entries(loaded)) {
+                    addConnection(id, conn);
+                }
+            }
+
+            if (!app.expressApp) {
+                log.warn("No Express app available — webhook routes not registered");
+                return;
+            }
+
+            // GET webhook — Meta verification challenge
+            app.expressApp.get(webhookPath, (req: any, res: any) => {
+                const mode = req.query["hub.mode"];
+                const token = req.query["hub.verify_token"];
+                const challenge = req.query["hub.challenge"];
+
+                // Find any connection with a matching verify token
+                const connectionIds = manager.list();
+                const verified = connectionIds.some((id) => {
+                    const conn = manager.get(id);
+                    return conn.verifyToken === token;
+                });
+
+                if (mode === "subscribe" && verified) {
+                    log.info("Webhook verification successful");
+                    res.status(200).send(challenge);
+                } else {
+                    log.warn("Webhook verification failed");
+                    res.sendStatus(403);
+                }
+            });
+
+            // POST webhook — receive messages and status updates
+            app.expressApp.post(webhookPath, async (req: any, res: any) => {
+                // Always respond 200 quickly to avoid Meta retries
+                res.sendStatus(200);
+
+                try {
+                    // Verify signature
+                    const signature = req.headers["x-hub-signature-256"] as string;
+                    if (signature) {
+                        const rawBody = (req as any).rawBody ?? JSON.stringify(req.body);
+                        const secrets = manager.getAppSecrets();
+                        const verified = secrets.some((secret) =>
+                            verifySignature(rawBody, signature, secret)
+                        );
+
+                        if (!verified) {
+                            log.warn("Webhook signature verification failed");
+                            return;
+                        }
+                    }
+
+                    const payload = req.body;
+                    if (!payload?.entry) return;
+
+                    // Extract phone number ID from the payload to resolve connection
+                    for (const entry of payload.entry) {
+                        for (const change of entry?.changes ?? []) {
+                            if (change?.field !== "messages") continue;
+
+                            const value = change?.value;
+                            if (!value?.metadata?.phone_number_id) continue;
+
+                            const phoneNumberId = value.metadata.phone_number_id;
+                            const connectionId = manager.resolveConnectionId(phoneNumberId);
+
+                            if (!connectionId) {
+                                log.warn(`No connection found for phone number ID: ${phoneNumberId}`);
+                                continue;
+                            }
+
+                            const { messages, statuses } = normalizeWebhookPayload(
+                                { entry: [{ changes: [change] }] },
+                                connectionId,
+                                phoneNumberId
+                            );
+
+                            // Handle messages
+                            for (const message of messages) {
+                                handleIncomingMessage(message).catch((err) => {
+                                    log.error("Error handling WhatsApp message", err);
+                                });
+                            }
+
+                            // Handle status updates
+                            if (options.onStatusUpdate) {
+                                for (const status of statuses) {
+                                    options.onStatusUpdate(status, appCtx).catch((err: any) => {
+                                        log.error("Error handling WhatsApp status update", err);
+                                    });
+                                }
+                            }
+                        }
+                    }
+                } catch (err) {
+                    log.error("Error processing WhatsApp webhook", err);
+                }
+            });
+
+            log.info(`WhatsApp webhook registered at ${webhookPath}`);
+        },
+    };
+}