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

package/dist/index.js

@@ -0,0 +1,192 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toWhatsappFormat = void 0;
+exports.whatsappPlugin = whatsappPlugin;
+const crypto = __importStar(require("crypto"));
+const flink_1 = require("@flink-app/flink");
+const autoRegisteredWhatsappHandlers_1 = require("./autoRegisteredWhatsappHandlers");
+const WhatsappConnectionManager_1 = require("./WhatsappConnectionManager");
+const whatsappContext_1 = require("./whatsappContext");
+const whatsappRouter_1 = require("./whatsappRouter");
+const WhatsappTransport_1 = require("./WhatsappTransport");
+const log = flink_1.FlinkLogFactory.createLogger("flink.whatsapp-plugin");
+__exportStar(require("./types"), exports);
+__exportStar(require("./autoRegisteredWhatsappHandlers"), exports);
+__exportStar(require("./whatsappRouter"), exports);
+var whatsappFormatting_1 = require("./whatsappFormatting");
+Object.defineProperty(exports, "toWhatsappFormat", { enumerable: true, get: function () { return whatsappFormatting_1.toWhatsappFormat; } });
+function whatsappPlugin(options) {
+    var _a;
+    const manager = new WhatsappConnectionManager_1.WhatsappConnectionManager();
+    let appCtx;
+    const webhookPath = (_a = options.webhookPath) !== null && _a !== void 0 ? _a : "/webhooks/whatsapp";
+    const handleIncomingMessage = async (message) => {
+        var _a;
+        const user = options.resolveUser
+            ? await options.resolveUser(message, appCtx)
+            : undefined;
+        const permissions = user && options.resolvePermissions
+            ? await options.resolvePermissions(user, appCtx)
+            : [];
+        const scopedWhatsapp = (0, whatsappContext_1.createScopedWhatsappContext)(manager, message.connectionId);
+        let handled = false;
+        for (const h of autoRegisteredWhatsappHandlers_1.autoRegisteredWhatsappHandlers) {
+            if (!(0, whatsappRouter_1.matchesRoute)(message, (_a = h.Route) !== null && _a !== void 0 ? _a : {}))
+                continue;
+            handled = true;
+            try {
+                await flink_1.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, connection) => {
+        manager.add(id, connection);
+    };
+    const pluginCtx = (0, whatsappContext_1.createWhatsappContext)(manager, addConnection);
+    return {
+        id: "whatsapp",
+        ctx: pluginCtx,
+        init: async (app) => {
+            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, res) => {
+                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, res) => {
+                var _a, _b, _c;
+                // Always respond 200 quickly to avoid Meta retries
+                res.sendStatus(200);
+                try {
+                    // Verify signature
+                    const signature = req.headers["x-hub-signature-256"];
+                    if (signature) {
+                        const rawBody = (_a = req.rawBody) !== null && _a !== void 0 ? _a : JSON.stringify(req.body);
+                        const secrets = manager.getAppSecrets();
+                        const verified = secrets.some((secret) => (0, WhatsappTransport_1.verifySignature)(rawBody, signature, secret));
+                        if (!verified) {
+                            log.warn("Webhook signature verification failed");
+                            return;
+                        }
+                    }
+                    const payload = req.body;
+                    if (!(payload === null || payload === void 0 ? void 0 : payload.entry))
+                        return;
+                    // Extract phone number ID from the payload to resolve connection
+                    for (const entry of payload.entry) {
+                        for (const change of (_b = entry === null || entry === void 0 ? void 0 : entry.changes) !== null && _b !== void 0 ? _b : []) {
+                            if ((change === null || change === void 0 ? void 0 : change.field) !== "messages")
+                                continue;
+                            const value = change === null || change === void 0 ? void 0 : change.value;
+                            if (!((_c = value === null || value === void 0 ? void 0 : value.metadata) === null || _c === void 0 ? void 0 : _c.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 } = (0, WhatsappTransport_1.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) => {
+                                        log.error("Error handling WhatsApp status update", err);
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    log.error("Error processing WhatsApp webhook", err);
+                }
+            });
+            log.info(`WhatsApp webhook registered at ${webhookPath}`);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,252 @@
+/** Connection options for a single WhatsApp Business phone number */
+export interface WhatsappConnectionOptions {
+    /** Permanent access token from Meta System User */
+    accessToken: string;
+    /** The business phone number ID */
+    phoneNumberId: string;
+    /** Token for webhook verification challenge */
+    verifyToken: string;
+    /** App secret for HMAC-SHA256 signature verification */
+    appSecret: string;
+    /** Graph API version (default: "v21.0") */
+    graphApiVersion?: string;
+}
+/** Plugin options */
+export interface WhatsappPluginOptions<TCtx> {
+    /** Single connection (stored as "default"). Mutually exclusive with `connections`. */
+    connection?: WhatsappConnectionOptions;
+    /** Multiple named connections at startup. Mutually exclusive with `connection`. */
+    connections?: Record<string, WhatsappConnectionOptions>;
+    /** Load connections dynamically at init time (receives app context with repos, plugins, etc.) */
+    loadConnections?: (ctx: TCtx) => Promise<Record<string, WhatsappConnectionOptions>>;
+    /** Webhook path for receiving messages (default: "/webhooks/whatsapp") */
+    webhookPath?: string;
+    /** Resolve authenticated user from a WhatsApp message */
+    resolveUser?: (message: WhatsappMessage, ctx: TCtx) => Promise<any>;
+    /** Resolve permissions for a resolved user */
+    resolvePermissions?: (user: any, ctx: TCtx) => Promise<string[]>;
+    /** Called when no WhatsappHandler matched the incoming message */
+    onUnhandled?: (message: WhatsappMessage, ctx: TCtx) => Promise<void>;
+    /** Called when a status update is received (sent, delivered, read, failed) */
+    onStatusUpdate?: (status: WhatsappStatusUpdate, ctx: TCtx) => Promise<void>;
+}
+/** WhatsApp message types */
+export type WhatsappMessageType = "text" | "image" | "video" | "audio" | "document" | "sticker" | "location" | "contacts" | "interactive" | "reaction" | "order" | "unknown";
+/** Media info from incoming messages */
+export interface WhatsappMedia {
+    /** Media ID (use downloadMedia to fetch content) */
+    id: string;
+    mimeType: string;
+    sha256?: string;
+    caption?: string;
+    filename?: string;
+}
+/** Location from incoming messages */
+export interface WhatsappLocation {
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+}
+/** Contact from incoming messages */
+export interface WhatsappContact {
+    name: {
+        formatted_name: string;
+        first_name?: string;
+        last_name?: string;
+    };
+    phones?: Array<{
+        phone: string;
+        type?: string;
+        wa_id?: string;
+    }>;
+}
+/** Interactive reply (button or list selection) from incoming messages */
+export interface WhatsappInteractiveReply {
+    type: "button_reply" | "list_reply";
+    /** Button reply ID */
+    buttonReplyId?: string;
+    /** Button reply title */
+    buttonReplyTitle?: string;
+    /** List reply ID */
+    listReplyId?: string;
+    /** List reply title */
+    listReplyTitle?: string;
+    /** List reply description */
+    listReplyDescription?: string;
+}
+/** Reaction from incoming messages */
+export interface WhatsappReaction {
+    /** Message ID being reacted to */
+    messageId: string;
+    /** Emoji used as reaction (empty string means reaction removed) */
+    emoji: string;
+}
+/** Normalized inbound WhatsApp message */
+export interface WhatsappMessage {
+    /** Connection that received this message ("default" for single-connection mode) */
+    connectionId: string;
+    /** WhatsApp message ID (wamid.XX) */
+    messageId: string;
+    /** Sender phone number (wa_id) */
+    from: string;
+    /** Recipient phone number ID */
+    to: string;
+    /** Sender display name from contacts[].profile.name */
+    senderName: string;
+    /** Unix timestamp */
+    timestamp: number;
+    /** Message type */
+    type: WhatsappMessageType;
+    /** Text content (for type "text") */
+    text?: string;
+    /** Media info (for image/video/audio/document/sticker) */
+    media?: WhatsappMedia;
+    /** Location (for type "location") */
+    location?: WhatsappLocation;
+    /** Contacts (for type "contacts") */
+    contacts?: WhatsappContact[];
+    /** Interactive reply (for button/list replies) */
+    interactive?: WhatsappInteractiveReply;
+    /** Reaction (for type "reaction") */
+    reaction?: WhatsappReaction;
+    /** Raw webhook payload */
+    raw: Record<string, any>;
+}
+/** Route matching criteria for a WhatsappHandler */
+export interface WhatsappRouteProps {
+    /** Match by message type */
+    type?: WhatsappMessageType | WhatsappMessageType[];
+    /** Match by sender phone number */
+    from?: string | RegExp | ((msg: WhatsappMessage) => boolean);
+    /** Match message text */
+    pattern?: string | RegExp | ((msg: WhatsappMessage) => boolean);
+    /** Only match messages from specific connection(s). Omit to match all connections. */
+    connectionId?: string | string[];
+}
+/** Handler function type */
+export type WhatsappHandler<TCtx> = (args: {
+    ctx: TCtx;
+    message: WhatsappMessage;
+    user?: any;
+    permissions?: string[];
+    whatsapp: ScopedWhatsappContext;
+}) => Promise<void>;
+/** Handler file shape (populated by compiler) */
+export interface WhatsappHandlerFile<TCtx = any> {
+    Route?: WhatsappRouteProps;
+    default: WhatsappHandler<TCtx>;
+    __file?: string;
+}
+/** Send options for the raw send method */
+export interface WhatsappSendOptions {
+    /** Recipient phone number */
+    to: string;
+    /** Message type */
+    type: string;
+    /** Message payload (type-specific) */
+    [key: string]: any;
+}
+/** Result from sending a message */
+export interface WhatsappSendResult {
+    messageId: string;
+}
+/** Media payload for sending images/documents/etc */
+export interface WhatsappMediaPayload {
+    /** Media ID (from uploadMedia) */
+    id?: string;
+    /** Public URL to the media */
+    link?: string;
+}
+/** Interactive button */
+export interface WhatsappButton {
+    id: string;
+    title: string;
+}
+/** List section for interactive list messages */
+export interface WhatsappListSection {
+    title: string;
+    rows: Array<{
+        id: string;
+        title: string;
+        description?: string;
+    }>;
+}
+/** Template for sending template messages */
+export interface WhatsappTemplate {
+    name: string;
+    language: {
+        code: string;
+    };
+    components?: Array<Record<string, any>>;
+}
+/** Status update from webhook */
+export interface WhatsappStatusUpdate {
+    connectionId: string;
+    messageId: string;
+    recipientId: string;
+    status: "sent" | "delivered" | "read" | "failed";
+    timestamp: number;
+    errors?: WhatsappError[];
+}
+/** WhatsApp API error */
+export interface WhatsappError {
+    code: number;
+    title: string;
+    message?: string;
+    href?: string;
+}
+/** Scoped context bound to a specific connection — no management methods */
+export interface ScopedWhatsappContext {
+    /** Send a raw message payload */
+    send(opts: WhatsappSendOptions): Promise<WhatsappSendResult>;
+    /** Send a text message */
+    sendText(to: string, text: string): Promise<WhatsappSendResult>;
+    /** Send a template message (required outside 24h window) */
+    sendTemplate(to: string, template: WhatsappTemplate): Promise<WhatsappSendResult>;
+    /** Send an image */
+    sendImage(to: string, image: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult>;
+    /** Send a document */
+    sendDocument(to: string, doc: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult>;
+    /** Send interactive buttons (max 3) */
+    sendInteractiveButtons(to: string, body: string, buttons: WhatsappButton[]): Promise<WhatsappSendResult>;
+    /** Send interactive list */
+    sendInteractiveList(to: string, body: string, buttonText: string, sections: WhatsappListSection[]): Promise<WhatsappSendResult>;
+    /** Send a location */
+    sendLocation(to: string, location: WhatsappLocation): Promise<WhatsappSendResult>;
+    /** Send a reaction emoji to a message */
+    sendReaction(to: string, messageId: string, emoji: string): Promise<WhatsappSendResult>;
+    /** Reply to a message with text */
+    reply(message: WhatsappMessage, text: string): Promise<WhatsappSendResult>;
+    /** Mark a message as read */
+    markAsRead(messageId: string): Promise<void>;
+    /** Upload media and return the media ID */
+    uploadMedia(file: Buffer, mimeType: string, filename: string): Promise<string>;
+    /** Download media by ID */
+    downloadMedia(mediaId: string): Promise<Buffer>;
+}
+/** Full WhatsApp API — exposed at runtime as ctx.plugins.whatsapp */
+export interface WhatsappApi extends ScopedWhatsappContext {
+    /** Add a new connection at runtime */
+    addConnection(id: string, connection: WhatsappConnectionOptions): void;
+    /** Remove a connection */
+    removeConnection(id: string): void;
+    /** Get a scoped context bound to a specific connection */
+    withConnection(id: string): ScopedWhatsappContext;
+    /** List active connection IDs */
+    listConnections(): string[];
+}
+/**
+ * Plugin context type — extend your app Ctx with this to get typed access to ctx.plugins.whatsapp.
+ *
+ * @example
+ * import { FlinkContext } from "@flink-app/flink";
+ * import { WhatsappPluginCtx } from "@flink-app/whatsapp-plugin";
+ *
+ * export interface Ctx extends FlinkContext<WhatsappPluginCtx> {
+ *   repos: { ... };
+ * }
+ */
+export interface WhatsappPluginCtx {
+    whatsapp: WhatsappApi;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/whatsappContext.d.ts

@@ -0,0 +1,4 @@
+import { WhatsappConnectionManager } from "./WhatsappConnectionManager";
+import { WhatsappApi, WhatsappConnectionOptions, ScopedWhatsappContext } from "./types";
+export declare function createWhatsappContext(manager: WhatsappConnectionManager, addConnectionFn: (id: string, connection: WhatsappConnectionOptions) => void): WhatsappApi;
+export declare function createScopedWhatsappContext(manager: WhatsappConnectionManager, connectionId: string): ScopedWhatsappContext;