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

package/src/types.ts

@@ -0,0 +1,284 @@
+/** 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/src/whatsappContext.ts

@@ -0,0 +1,385 @@
+import { WhatsappConnectionManager } from "./WhatsappConnectionManager";
+import * as transport from "./WhatsappTransport";
+import {
+    WhatsappApi,
+    WhatsappButton,
+    WhatsappConnectionOptions,
+    WhatsappListSection,
+    WhatsappLocation,
+    WhatsappMediaPayload,
+    WhatsappMessage,
+    WhatsappSendOptions,
+    WhatsappSendResult,
+    WhatsappTemplate,
+    ScopedWhatsappContext,
+} from "./types";
+
+const DEFAULT_VERSION = "v21.0";
+
+function getVersion(conn: WhatsappConnectionOptions): string {
+    return conn.graphApiVersion ?? DEFAULT_VERSION;
+}
+
+function createScopedContext(getConn: () => WhatsappConnectionOptions): ScopedWhatsappContext {
+    return {
+        async send(opts: WhatsappSendOptions): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            const { to, ...rest } = opts;
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, ...rest },
+                getVersion(conn)
+            );
+        },
+
+        async sendText(to: string, text: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "text", text: { body: text } },
+                getVersion(conn)
+            );
+        },
+
+        async sendTemplate(to: string, template: WhatsappTemplate): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "template", template },
+                getVersion(conn)
+            );
+        },
+
+        async sendImage(to: string, image: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "image", image: { ...image, ...(caption ? { caption } : {}) } },
+                getVersion(conn)
+            );
+        },
+
+        async sendDocument(to: string, doc: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "document", document: { ...doc, ...(caption ? { caption } : {}) } },
+                getVersion(conn)
+            );
+        },
+
+        async sendInteractiveButtons(to: string, body: string, buttons: WhatsappButton[]): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to,
+                    type: "interactive",
+                    interactive: {
+                        type: "button",
+                        body: { text: body },
+                        action: {
+                            buttons: buttons.map((b) => ({
+                                type: "reply",
+                                reply: { id: b.id, title: b.title },
+                            })),
+                        },
+                    },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async sendInteractiveList(
+            to: string,
+            body: string,
+            buttonText: string,
+            sections: WhatsappListSection[]
+        ): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to,
+                    type: "interactive",
+                    interactive: {
+                        type: "list",
+                        body: { text: body },
+                        action: {
+                            button: buttonText,
+                            sections,
+                        },
+                    },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async sendLocation(to: string, location: WhatsappLocation): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "location", location },
+                getVersion(conn)
+            );
+        },
+
+        async sendReaction(to: string, messageId: string, emoji: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "reaction", reaction: { message_id: messageId, emoji } },
+                getVersion(conn)
+            );
+        },
+
+        async reply(message: WhatsappMessage, text: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to: message.from,
+                    type: "text",
+                    text: { body: text },
+                    context: { message_id: message.messageId },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async markAsRead(messageId: string): Promise<void> {
+            const conn = getConn();
+            await transport.markAsRead(
+                conn.phoneNumberId,
+                conn.accessToken,
+                messageId,
+                getVersion(conn)
+            );
+        },
+
+        async uploadMedia(file: Buffer, mimeType: string, filename: string): Promise<string> {
+            const conn = getConn();
+            return transport.uploadMedia(
+                conn.phoneNumberId,
+                conn.accessToken,
+                file,
+                mimeType,
+                filename,
+                getVersion(conn)
+            );
+        },
+
+        async downloadMedia(mediaId: string): Promise<Buffer> {
+            const conn = getConn();
+            return transport.downloadMedia(mediaId, conn.accessToken, getVersion(conn));
+        },
+    };
+}
+
+export function createWhatsappContext(
+    manager: WhatsappConnectionManager,
+    addConnectionFn: (id: string, connection: WhatsappConnectionOptions) => void
+): WhatsappApi {
+    const getConn = (connectionId?: string): WhatsappConnectionOptions => {
+        return manager.get(connectionId ?? "default");
+    };
+
+    // Build the full object directly — do NOT spread a scoped context,
+    // because spreading eagerly evaluates getters before any connections have been added.
+    return {
+        async send(opts: WhatsappSendOptions): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            const { to, ...rest } = opts;
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, ...rest },
+                getVersion(conn)
+            );
+        },
+
+        async sendText(to: string, text: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "text", text: { body: text } },
+                getVersion(conn)
+            );
+        },
+
+        async sendTemplate(to: string, template: WhatsappTemplate): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "template", template },
+                getVersion(conn)
+            );
+        },
+
+        async sendImage(to: string, image: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "image", image: { ...image, ...(caption ? { caption } : {}) } },
+                getVersion(conn)
+            );
+        },
+
+        async sendDocument(to: string, doc: WhatsappMediaPayload, caption?: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "document", document: { ...doc, ...(caption ? { caption } : {}) } },
+                getVersion(conn)
+            );
+        },
+
+        async sendInteractiveButtons(to: string, body: string, buttons: WhatsappButton[]): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to,
+                    type: "interactive",
+                    interactive: {
+                        type: "button",
+                        body: { text: body },
+                        action: {
+                            buttons: buttons.map((b) => ({
+                                type: "reply",
+                                reply: { id: b.id, title: b.title },
+                            })),
+                        },
+                    },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async sendInteractiveList(
+            to: string,
+            body: string,
+            buttonText: string,
+            sections: WhatsappListSection[]
+        ): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to,
+                    type: "interactive",
+                    interactive: {
+                        type: "list",
+                        body: { text: body },
+                        action: {
+                            button: buttonText,
+                            sections,
+                        },
+                    },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async sendLocation(to: string, location: WhatsappLocation): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "location", location },
+                getVersion(conn)
+            );
+        },
+
+        async sendReaction(to: string, messageId: string, emoji: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                { to, type: "reaction", reaction: { message_id: messageId, emoji } },
+                getVersion(conn)
+            );
+        },
+
+        async reply(message: WhatsappMessage, text: string): Promise<WhatsappSendResult> {
+            const conn = getConn();
+            return transport.sendMessage(
+                conn.phoneNumberId,
+                conn.accessToken,
+                {
+                    to: message.from,
+                    type: "text",
+                    text: { body: text },
+                    context: { message_id: message.messageId },
+                },
+                getVersion(conn)
+            );
+        },
+
+        async markAsRead(messageId: string): Promise<void> {
+            const conn = getConn();
+            await transport.markAsRead(
+                conn.phoneNumberId,
+                conn.accessToken,
+                messageId,
+                getVersion(conn)
+            );
+        },
+
+        async uploadMedia(file: Buffer, mimeType: string, filename: string): Promise<string> {
+            const conn = getConn();
+            return transport.uploadMedia(
+                conn.phoneNumberId,
+                conn.accessToken,
+                file,
+                mimeType,
+                filename,
+                getVersion(conn)
+            );
+        },
+
+        async downloadMedia(mediaId: string): Promise<Buffer> {
+            const conn = getConn();
+            return transport.downloadMedia(mediaId, conn.accessToken, getVersion(conn));
+        },
+
+        addConnection(id: string, connection: WhatsappConnectionOptions): void {
+            addConnectionFn(id, connection);
+        },
+
+        removeConnection(id: string): void {
+            manager.remove(id);
+        },
+
+        withConnection(id: string): ScopedWhatsappContext {
+            return createScopedContext(() => manager.get(id));
+        },
+
+        listConnections(): string[] {
+            return manager.list();
+        },
+    };
+}
+
+export function createScopedWhatsappContext(
+    manager: WhatsappConnectionManager,
+    connectionId: string
+): ScopedWhatsappContext {
+    return createScopedContext(() => manager.get(connectionId));
+}