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

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @flink-app/whatsapp-plugin
+
+## 2.0.0-alpha.74
+
+### Patch Changes
+
+-   feat: add WhatsApp plugin for sending and receiving WhatsApp messages
+-   Updated dependencies
+-   Updated dependencies
+    -   @flink-app/flink@2.0.0-alpha.74

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Frost Experience AB https://www.frost.se
+
+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,80 @@
+# @flink-app/whatsapp-plugin
+
+Bi-directional WhatsApp messaging plugin for [Flink](https://github.com/FrostDigital/flink-framework) via the WhatsApp Cloud API. No external SDK — uses native `fetch`.
+
+## Features
+
+- Auto-discovered `WhatsappHandler` files via Flink's compiler extension
+- Route matching by message type, sender, text pattern, and connection
+- Send text, templates, images, documents, interactive buttons/lists, locations, reactions
+- Multi-connection support (multiple WhatsApp Business phone numbers)
+- Webhook signature verification (HMAC-SHA256)
+- Message status tracking (sent, delivered, read, failed)
+- 24-hour conversation window awareness with template message support
+- Markdown to WhatsApp formatting converter
+- CLI tool for sending test messages
+
+## Quick Start
+
+```bash
+pnpm add @flink-app/whatsapp-plugin
+```
+
+```js
+// flink.config.js
+const { compilerPlugin } = require("@flink-app/whatsapp-plugin/compiler");
+module.exports = { compilerPlugins: [compilerPlugin()] };
+```
+
+```typescript
+// src/index.ts
+import { whatsappPlugin } from "@flink-app/whatsapp-plugin";
+
+new FlinkApp<Ctx>({
+    plugins: [
+        whatsappPlugin<Ctx>({
+            connection: {
+                accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+                phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+                verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+                appSecret: process.env.WHATSAPP_APP_SECRET!,
+            },
+        }),
+    ],
+});
+```
+
+```typescript
+// src/whatsapp-handlers/HandleText.ts
+import { WhatsappHandler, WhatsappRouteProps } from "@flink-app/whatsapp-plugin";
+
+export const Route: WhatsappRouteProps = { type: "text" };
+
+const handler: WhatsappHandler<Ctx> = async ({ message, whatsapp }) => {
+    await whatsapp.reply(message, `Echo: ${message.text}`);
+};
+
+export default handler;
+```
+
+## Documentation
+
+See the [skill documentation](../../skills/flink-whatsapp-plugin/SKILL.md) for complete usage guide including routing, multi-connection setup, template messages, interactive messages, media handling, and more.
+
+## Meta App Setup
+
+1. Create a Meta App at [developers.facebook.com](https://developers.facebook.com)
+2. Add the WhatsApp product
+3. Configure webhook URL to `https://your-domain.com/webhooks/whatsapp`
+4. Subscribe to the `messages` webhook field
+5. Generate a permanent access token via a System User
+
+## CLI
+
+```bash
+pnpm exec flink-whatsapp send --token <token> --phone-id <id> --to <number> "Hello!"
+```
+
+## License
+
+MIT

package/bin/flink-whatsapp.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+
+const [, , command, ...rest] = process.argv;
+
+if (!command || command === "--help" || command === "-h") {
+    console.log("Usage: flink-whatsapp <command> [options]");
+    console.log("");
+    console.log("Commands:");
+    console.log("  send --token <token> --phone-id <id> --to <number> <message>");
+    console.log("");
+    console.log("Run flink-whatsapp send --help for send options.");
+    process.exit(0);
+}
+
+// 'send' is the default (and only) command.
+if (command === "send") {
+    process.argv = [process.argv[0], process.argv[1], ...rest];
+} else {
+    process.argv = [process.argv[0], process.argv[1], command, ...rest];
+}
+require("../dist/cli/send.js");

package/dist/WhatsappConnectionManager.d.ts

@@ -0,0 +1,17 @@
+import { WhatsappConnectionOptions } from "./types";
+export declare class WhatsappConnectionManager {
+    private connections;
+    /** Reverse map: phoneNumberId → connection ID for webhook routing */
+    private phoneNumberIdMap;
+    add(id: string, options: WhatsappConnectionOptions): void;
+    remove(id: string): void;
+    get(id: string): WhatsappConnectionOptions;
+    has(id: string): boolean;
+    list(): string[];
+    /** Resolve a phone number ID from a webhook to a connection ID */
+    resolveConnectionId(phoneNumberId: string): string | undefined;
+    /** Get any connection's appSecret for signature verification */
+    getAnyAppSecret(): string | undefined;
+    /** Get all unique app secrets (for trying signature verification with multiple secrets) */
+    getAppSecrets(): string[];
+}

package/dist/WhatsappConnectionManager.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhatsappConnectionManager = void 0;
+const flink_1 = require("@flink-app/flink");
+const log = flink_1.FlinkLogFactory.createLogger("flink.whatsapp-plugin.connections");
+class WhatsappConnectionManager {
+    constructor() {
+        this.connections = new Map();
+        /** Reverse map: phoneNumberId → connection ID for webhook routing */
+        this.phoneNumberIdMap = new Map();
+    }
+    add(id, options) {
+        if (this.connections.has(id)) {
+            throw new Error(`WhatsApp connection "${id}" already exists`);
+        }
+        this.connections.set(id, options);
+        this.phoneNumberIdMap.set(options.phoneNumberId, id);
+        log.info(`Connection "${id}" added (phone number ID: ${options.phoneNumberId})`);
+    }
+    remove(id) {
+        const conn = this.connections.get(id);
+        if (!conn) {
+            throw new Error(`WhatsApp connection "${id}" not found`);
+        }
+        this.phoneNumberIdMap.delete(conn.phoneNumberId);
+        this.connections.delete(id);
+        log.info(`Connection "${id}" removed`);
+    }
+    get(id) {
+        const conn = this.connections.get(id);
+        if (!conn) {
+            throw new Error(`WhatsApp connection "${id}" not found`);
+        }
+        return conn;
+    }
+    has(id) {
+        return this.connections.has(id);
+    }
+    list() {
+        return Array.from(this.connections.keys());
+    }
+    /** Resolve a phone number ID from a webhook to a connection ID */
+    resolveConnectionId(phoneNumberId) {
+        return this.phoneNumberIdMap.get(phoneNumberId);
+    }
+    /** Get any connection's appSecret for signature verification */
+    getAnyAppSecret() {
+        const first = this.connections.values().next();
+        return first.done ? undefined : first.value.appSecret;
+    }
+    /** Get all unique app secrets (for trying signature verification with multiple secrets) */
+    getAppSecrets() {
+        const secrets = new Set();
+        for (const conn of this.connections.values()) {
+            secrets.add(conn.appSecret);
+        }
+        return Array.from(secrets);
+    }
+}
+exports.WhatsappConnectionManager = WhatsappConnectionManager;

package/dist/WhatsappTransport.d.ts

@@ -0,0 +1,18 @@
+import { WhatsappMessage, WhatsappStatusUpdate, WhatsappSendResult } from "./types";
+/** Verify HMAC-SHA256 webhook signature from Meta */
+export declare function verifySignature(rawBody: string | Buffer, signature: string, appSecret: string): boolean;
+/** Make an authenticated Graph API call */
+export declare function callApi(path: string, method: string, body: Record<string, any> | undefined, accessToken: string, version?: string): Promise<any>;
+/** Send a message via the WhatsApp Cloud API */
+export declare function sendMessage(phoneNumberId: string, accessToken: string, payload: Record<string, any>, version?: string): Promise<WhatsappSendResult>;
+/** Upload media to WhatsApp (multipart form data) */
+export declare function uploadMedia(phoneNumberId: string, accessToken: string, file: Buffer, mimeType: string, filename: string, version?: string): Promise<string>;
+/** Download media by ID (two-step: get URL, then fetch binary) */
+export declare function downloadMedia(mediaId: string, accessToken: string, version?: string): Promise<Buffer>;
+/** Mark a message as read */
+export declare function markAsRead(phoneNumberId: string, accessToken: string, messageId: string, version?: string): Promise<void>;
+/** Extract normalized messages and status updates from a webhook payload */
+export declare function normalizeWebhookPayload(payload: Record<string, any>, connectionId: string, phoneNumberId: string): {
+    messages: WhatsappMessage[];
+    statuses: WhatsappStatusUpdate[];
+};

package/dist/WhatsappTransport.js

@@ -0,0 +1,241 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySignature = verifySignature;
+exports.callApi = callApi;
+exports.sendMessage = sendMessage;
+exports.uploadMedia = uploadMedia;
+exports.downloadMedia = downloadMedia;
+exports.markAsRead = markAsRead;
+exports.normalizeWebhookPayload = normalizeWebhookPayload;
+const crypto = __importStar(require("crypto"));
+const flink_1 = require("@flink-app/flink");
+const log = flink_1.FlinkLogFactory.createLogger("flink.whatsapp-plugin.transport");
+const DEFAULT_GRAPH_API_VERSION = "v21.0";
+function graphUrl(version, path) {
+    return `https://graph.facebook.com/${version}/${path}`;
+}
+/** Verify HMAC-SHA256 webhook signature from Meta */
+function verifySignature(rawBody, signature, appSecret) {
+    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 */
+async function callApi(path, method, body, accessToken, version = DEFAULT_GRAPH_API_VERSION) {
+    var _a, _b;
+    const url = graphUrl(version, path);
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+    };
+    const response = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const data = await response.json();
+    if (!response.ok) {
+        const errMsg = (_b = (_a = data === null || data === void 0 ? void 0 : data.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : response.statusText;
+        throw new Error(`WhatsApp API error (${response.status}): ${errMsg}`);
+    }
+    return data;
+}
+/** Send a message via the WhatsApp Cloud API */
+async function sendMessage(phoneNumberId, accessToken, payload, version = DEFAULT_GRAPH_API_VERSION) {
+    var _a, _b, _c;
+    const data = await callApi(`${phoneNumberId}/messages`, "POST", Object.assign({ messaging_product: "whatsapp" }, payload), accessToken, version);
+    return { messageId: (_c = (_b = (_a = data.messages) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : "" };
+}
+/** Upload media to WhatsApp (multipart form data) */
+async function uploadMedia(phoneNumberId, accessToken, file, mimeType, filename, version = DEFAULT_GRAPH_API_VERSION) {
+    var _a, _b;
+    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 = await response.json();
+    if (!response.ok) {
+        const errMsg = (_b = (_a = data === null || data === void 0 ? void 0 : data.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : 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) */
+async function downloadMedia(mediaId, accessToken, version = DEFAULT_GRAPH_API_VERSION) {
+    // 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 */
+async function markAsRead(phoneNumberId, accessToken, messageId, version = DEFAULT_GRAPH_API_VERSION) {
+    await callApi(`${phoneNumberId}/messages`, "POST", {
+        messaging_product: "whatsapp",
+        status: "read",
+        message_id: messageId,
+    }, accessToken, version);
+}
+function resolveMessageType(msgType) {
+    const known = [
+        "text", "image", "video", "audio", "document",
+        "sticker", "location", "contacts", "interactive",
+        "reaction", "order",
+    ];
+    return known.includes(msgType)
+        ? msgType
+        : "unknown";
+}
+function extractMedia(msg, type) {
+    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) {
+    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 */
+function normalizeWebhookPayload(payload, connectionId, phoneNumberId) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+    const messages = [];
+    const statuses = [];
+    const entries = (_a = payload === null || payload === void 0 ? void 0 : payload.entry) !== null && _a !== void 0 ? _a : [];
+    for (const entry of entries) {
+        const changes = (_b = entry === null || entry === void 0 ? void 0 : entry.changes) !== null && _b !== void 0 ? _b : [];
+        for (const change of changes) {
+            if ((change === null || change === void 0 ? void 0 : change.field) !== "messages")
+                continue;
+            const value = change === null || change === void 0 ? void 0 : change.value;
+            if (!value)
+                continue;
+            const contacts = (_c = value.contacts) !== null && _c !== void 0 ? _c : [];
+            const contactMap = new Map();
+            for (const contact of contacts) {
+                contactMap.set(contact.wa_id, (_e = (_d = contact.profile) === null || _d === void 0 ? void 0 : _d.name) !== null && _e !== void 0 ? _e : "");
+            }
+            // Process messages
+            for (const msg of (_f = value.messages) !== null && _f !== void 0 ? _f : []) {
+                const type = resolveMessageType(msg.type);
+                const from = (_g = msg.from) !== null && _g !== void 0 ? _g : "";
+                const normalized = {
+                    connectionId,
+                    messageId: (_h = msg.id) !== null && _h !== void 0 ? _h : "",
+                    from,
+                    to: phoneNumberId,
+                    senderName: (_j = contactMap.get(from)) !== null && _j !== void 0 ? _j : "",
+                    timestamp: Number(msg.timestamp) || 0,
+                    type,
+                    text: (_k = msg.text) === null || _k === void 0 ? void 0 : _k.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: (_l = msg.reaction.emoji) !== null && _l !== void 0 ? _l : "",
+                        }
+                        : undefined,
+                    raw: msg,
+                };
+                messages.push(normalized);
+            }
+            // Process statuses
+            for (const status of (_m = value.statuses) !== null && _m !== void 0 ? _m : []) {
+                statuses.push({
+                    connectionId,
+                    messageId: (_o = status.id) !== null && _o !== void 0 ? _o : "",
+                    recipientId: (_p = status.recipient_id) !== null && _p !== void 0 ? _p : "",
+                    status: (_q = status.status) !== null && _q !== void 0 ? _q : "failed",
+                    timestamp: Number(status.timestamp) || 0,
+                    errors: (_r = status.errors) === null || _r === void 0 ? void 0 : _r.map((e) => ({
+                        code: e.code,
+                        title: e.title,
+                        message: e.message,
+                        href: e.href,
+                    })),
+                });
+            }
+        }
+    }
+    return { messages, statuses };
+}

package/dist/autoRegisteredWhatsappHandlers.d.ts

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

package/dist/autoRegisteredWhatsappHandlers.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoRegisteredWhatsappHandlers = void 0;
+/**
+ * Populated at compile time by the Flink compiler extension.
+ * Do not modify manually.
+ */
+exports.autoRegisteredWhatsappHandlers = [];

package/dist/cli/send.d.ts

@@ -0,0 +1,21 @@
+#!/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)
+ */
+declare function parseArgs(argv: string[]): {
+    token: string;
+    phoneNumberId: string;
+    to: string;
+    text: string;
+    apiVersion: string;
+};
+declare function main(): Promise<void>;

package/dist/cli/send.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * 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) {
+    var _a, _b;
+    const args = argv.slice(2);
+    let token = (_a = process.env.WHATSAPP_ACCESS_TOKEN) !== null && _a !== void 0 ? _a : "";
+    let phoneNumberId = (_b = process.env.WHATSAPP_PHONE_NUMBER_ID) !== null && _b !== void 0 ? _b : "";
+    let to = "";
+    let apiVersion = "v21.0";
+    const textParts = [];
+    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() {
+    var _a, _b, _c, _d, _e;
+    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 = await response.json();
+    if (!response.ok) {
+        const errMsg = (_b = (_a = data === null || data === void 0 ? void 0 : data.error) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : response.statusText;
+        throw new Error(`WhatsApp API error (${response.status}): ${errMsg}`);
+    }
+    const messageId = (_e = (_d = (_c = data.messages) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.id) !== null && _e !== void 0 ? _e : "unknown";
+    console.log(`Message sent (id: ${messageId})`);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error("Error:", msg || "unknown error");
+    process.exit(1);
+});

package/dist/compiler.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare function compilerPlugin(opts?: {
+    scanDir?: string;
+}): FlinkCompilerPlugin;
+export {};

package/dist/compiler.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * 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()],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compilerPlugin = compilerPlugin;
+function compilerPlugin(opts) {
+    var _a;
+    return {
+        package: "@flink-app/whatsapp-plugin",
+        scanDir: (_a = opts === null || opts === void 0 ? void 0 : opts.scanDir) !== null && _a !== void 0 ? _a : "src/whatsapp-handlers",
+        generatedFile: "generatedWhatsappHandlers",
+        registrationVar: "autoRegisteredWhatsappHandlers",
+        detectBy: (fileContent) => fileContent.includes("WhatsappHandler"),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { WhatsappPluginOptions } from "./types";
+export * from "./types";
+export * from "./autoRegisteredWhatsappHandlers";
+export * from "./whatsappRouter";
+export { toWhatsappFormat } from "./whatsappFormatting";
+export declare function whatsappPlugin<TCtx>(options: WhatsappPluginOptions<TCtx>): {
+    id: string;
+    ctx: import("./types").WhatsappApi;
+    init: (app: {
+        ctx: TCtx;
+        expressApp?: any;
+    }) => Promise<void>;
+};