@elizaos/plugin-whatsapp 0.1.7-alpha.2 → 0.1.7

package/README.md

@@ -0,0 +1,220 @@
+# @elizaos/plugin-whatsapp
+
+A plugin for integrating WhatsApp Cloud API with your application, providing comprehensive messaging capabilities and webhook handling.
+
+## Overview
+
+This plugin provides functionality to:
+- Send text and template messages via WhatsApp
+- Handle incoming webhook events
+- Manage message status updates
+- Process message delivery notifications
+- Handle authentication and session management
+
+## Installation
+
+```bash
+npm install @elizaos/plugin-whatsapp
+```
+
+## Configuration
+
+The plugin requires the following environment variables:
+
+```env
+WHATSAPP_ACCESS_TOKEN=your_access_token       # Required: WhatsApp Cloud API access token
+WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id # Required: WhatsApp business phone number ID
+WHATSAPP_WEBHOOK_TOKEN=your_webhook_token     # Optional: Webhook verification token
+WHATSAPP_BUSINESS_ID=your_business_id        # Optional: Business account ID
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { WhatsAppPlugin } from "@elizaos/plugin-whatsapp";
+
+const whatsappPlugin = new WhatsAppPlugin({
+    accessToken: 'your_access_token',
+    phoneNumberId: 'your_phone_number_id',
+    webhookVerifyToken: 'your_webhook_verify_token',
+    businessAccountId: 'your_business_account_id'
+});
+```
+
+### Sending Messages
+
+```typescript
+// Send a text message
+await whatsappPlugin.sendMessage({
+    type: 'text',
+    to: '1234567890',
+    content: 'Hello from WhatsApp!'
+});
+
+// Send a template message
+await whatsappPlugin.sendMessage({
+    type: 'template',
+    to: '1234567890',
+    content: {
+        name: 'hello_world',
+        language: {
+            code: 'en'
+        }
+    }
+});
+```
+
+### Handling Webhooks
+
+```typescript
+// Verify webhook
+app.get('/webhook', (req, res) => {
+    const verified = await whatsappPlugin.verifyWebhook(req.query['hub.verify_token']);
+    if (verified) {
+        res.send(req.query['hub.challenge']);
+    } else {
+        res.sendStatus(403);
+    }
+});
+
+// Handle webhook events
+app.post('/webhook', (req, res) => {
+    await whatsappPlugin.handleWebhook(req.body);
+    res.sendStatus(200);
+});
+```
+
+## Features
+
+- Send text messages
+- Send template messages
+- Webhook verification
+- Webhook event handling
+- Message status updates
+
+## Error Handling
+
+The plugin throws errors in the following cases:
+
+```typescript
+try {
+    await whatsappPlugin.sendMessage({
+        type: 'text',
+        to: '1234567890',
+        content: 'Hello!'
+    });
+} catch (error) {
+    console.error('Failed to send message:', error.message);
+}
+```
+
+Common error cases:
+- Invalid configuration
+- Failed message sending
+- Webhook verification failure
+- Invalid webhook payload
+
+## Best Practices
+
+1. Always validate phone numbers before sending messages
+2. Use template messages for first-time messages to users
+3. Store message IDs for tracking delivery status
+4. Implement proper error handling
+5. Set up webhook retry mechanisms
+6. Keep your access tokens secure
+
+## API Reference
+
+### Core Interfaces
+
+```typescript
+interface WhatsAppConfig {
+    accessToken: string;
+    phoneNumberId: string;
+    webhookVerifyToken?: string;
+    businessAccountId?: string;
+}
+
+interface WhatsAppMessage {
+    type: 'text' | 'template';
+    to: string;
+    content: string | WhatsAppTemplate;
+}
+
+interface WhatsAppTemplate {
+    name: string;
+    language: {
+        code: string;
+    };
+    components?: Array<{
+        type: string;
+        parameters: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }>;
+}
+```
+
+### Plugin Methods
+
+- `sendMessage`: Send WhatsApp messages
+- `handleWebhook`: Process incoming webhook events
+- `verifyWebhook`: Verify webhook authenticity
+- Message and status handlers
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm run test
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## Security Best Practices
+
+- Store credentials securely using environment variables
+- Validate all phone numbers before sending messages
+- Use template messages for first-time contacts
+- Implement proper error handling
+- Keep dependencies updated
+- Monitor API usage and rate limits
+- Use HTTPS for all API communication
+
+## Contributing
+
+Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
+
+## Credits
+
+This plugin integrates with and builds upon several key technologies:
+
+- [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api): Meta's official WhatsApp Business Platform
+- [Axios](https://axios-http.com/): Promise-based HTTP client for API requests
+- [Meta for Developers](https://developers.facebook.com/): Meta's developer platform and tools
+
+Special thanks to:
+- The Eliza community for their contributions and feedback
+
+For more information about WhatsApp Cloud API and its capabilities, visit:
+- [WhatsApp Business Platform Documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/overview)
+- [Meta for Developers Blog](https://developers.facebook.com/blog/)
+- [WhatsApp Business API GitHub](https://github.com/WhatsApp/WhatsApp-Business-API-Setup-Scripts)
+
+## License
+
+This plugin is part of the Eliza project. See the main project repository for license information.

package/dist/{index.mjs → index.js}

@@ -113,4 +113,4 @@ var WhatsAppPlugin = class {
 export {
   WhatsAppPlugin
 };
-//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,27 +1,42 @@
 {
-  "name": "@elizaos/plugin-whatsapp",
-  "version": "0.1.7-alpha.2",
-  "description": "WhatsApp Cloud API plugin",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsup --format esm --dts",
-    "dev": "tsup --format esm --dts --watch",
-    "test": "jest",
-    "lint": "eslint --fix  --cache ."
-  },
-  "dependencies": {
-    "@elizaos/core": "0.1.7-alpha.2",
-    "axios": "1.7.8"
-  },
-  "devDependencies": {
-    "@types/jest": "29.5.14",
-    "@types/node": "20.17.9",
-    "@typescript-eslint/eslint-plugin": "8.16.0",
-    "@typescript-eslint/parser": "8.16.0",
-    "jest": "29.7.0",
-    "ts-jest": "29.2.5",
-    "typescript": "5.6.3"
-  },
-  "gitHead": "256e6634696074cdb38f3f79bc383fed04376688"
+    "name": "@elizaos/plugin-whatsapp",
+    "version": "0.1.7",
+    "description": "WhatsApp Cloud API plugin",
+    "type": "module",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "import": {
+                "@elizaos/source": "./src/index.ts",
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup --format esm --dts",
+        "dev": "tsup --format esm --dts --watch",
+        "test": "jest",
+        "lint": "eslint --fix  --cache ."
+    },
+    "dependencies": {
+        "@elizaos/core": "0.1.7",
+        "axios": "1.7.8"
+    },
+    "devDependencies": {
+        "@types/jest": "29.5.14",
+        "@types/node": "20.17.9",
+        "@typescript-eslint/eslint-plugin": "8.16.0",
+        "@typescript-eslint/parser": "8.16.0",
+        "jest": "29.7.0",
+        "ts-jest": "29.2.5",
+        "typescript": "5.6.3"
+    },
+    "gitHead": "e15421524dde4f2778b529effb212eebea8c98b6"
 }

package/.turbo/turbo-build.log

@@ -1,17 +0,0 @@
-
-> @elizaos/plugin-whatsapp@0.1.7-alpha.2 build /home/runner/work/eliza/eliza/packages/plugin-whatsapp
-> tsup --format esm --dts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.3.5
-CLI Using tsup config: /home/runner/work/eliza/eliza/packages/plugin-whatsapp/tsup.config.ts
-CLI Target: esnext
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.mjs     3.06 KB
-ESM dist/index.mjs.map 7.09 KB
-ESM ⚡️ Build success in 31ms
-DTS Build start
-DTS ⚡️ Build success in 6502ms
-DTS dist/index.d.mts 1.90 KB

package/Readme.md

@@ -1,154 +0,0 @@
-# WhatsApp Cloud API Plugin
-
-A plugin for integrating WhatsApp Cloud API with your application.
-
-## Installation
-
-</file>
-
-npm install @eliza/plugin-whatsapp
-
-## Configuration
-
-typescript
-import { WhatsAppPlugin } from '@eliza/plugin-whatsapp';
-const whatsappPlugin = new WhatsAppPlugin({
-accessToken: 'your_access_token',
-phoneNumberId: 'your_phone_number_id',
-webhookVerifyToken: 'your_webhook_verify_token',
-businessAccountId: 'your_business_account_id'
-});
-
-## Usage
-
-### Sending Messages
-
-typescript
-// Send a text message
-await whatsappPlugin.sendMessage({
-type: 'text',
-to: '1234567890',
-content: 'Hello from WhatsApp!'
-});
-// Send a template message
-await whatsappPlugin.sendMessage({
-type: 'template',
-to: '1234567890',
-content: {
-name: 'hello_world',
-language: {
-code: 'en'
-}
-}
-});
-
-### Handling Webhooks
-
-typescript
-// Verify webhook
-app.get('/webhook', (req, res) => {
-const verified = await whatsappPlugin.verifyWebhook(req.query['hub.verify_token']);
-if (verified) {
-res.send(req.query['hub.challenge']);
-} else {
-res.sendStatus(403);
-}
-});
-// Handle webhook events
-app.post('/webhook', (req, res) => {
-await whatsappPlugin.handleWebhook(req.body);
-res.sendStatus(200);
-});
-
-## Features
-
--   Send text messages
--   Send template messages
--   Webhook verification
--   Webhook event handling
--   Message status updates
-
-## API Reference
-
-### WhatsAppPlugin
-
-#### Constructor
-
--   `config: WhatsAppConfig` - Configuration object for the plugin
-
-#### Methods
-
--   `sendMessage(message: WhatsAppMessage): Promise<any>` - Send a WhatsApp message
--   `handleWebhook(event: WhatsAppWebhookEvent): Promise<void>` - Process incoming webhook events
--   `verifyWebhook(token: string): Promise<boolean>` - Verify webhook token
-
-### Types
-
-typescript
-interface WhatsAppConfig {
-accessToken: string;
-phoneNumberId: string;
-webhookVerifyToken?: string;
-businessAccountId?: string;
-}
-interface WhatsAppMessage {
-type: 'text' | 'template';
-to: string;
-content: string | WhatsAppTemplate;
-}
-interface WhatsAppTemplate {
-name: string;
-language: {
-code: string;
-};
-components?: Array<{
-type: string;
-parameters: Array<{
-type: string;
-text?: string;
-}>;
-}>;
-}
-
-## Error Handling
-
-The plugin throws errors in the following cases:
-
--   Invalid configuration
--   Failed message sending
--   Webhook verification failure
--   Invalid webhook payload
-
-Example error handling:
-
-typescript
-try {
-await whatsappPlugin.sendMessage({
-type: 'text',
-to: '1234567890',
-content: 'Hello!'
-});
-} catch (error) {
-console.error('Failed to send message:', error.message);
-}
-
-## Best Practices
-
-1. Always validate phone numbers before sending messages
-2. Use template messages for first-time messages to users
-3. Store message IDs for tracking delivery status
-4. Implement proper error handling
-5. Set up webhook retry mechanisms
-6. Keep your access tokens secure
-
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
-
-MIT

package/eslint.config.mjs

@@ -1,9 +0,0 @@
-import eslintGlobalConfig from "../../eslint.config.mjs";
-
-export default [
-    ...eslintGlobalConfig,
-    {
-        files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
-        ignores: ["**/node_modules/**", "**/dist/**"],
-    },
-];

package/src/client.ts

@@ -1,38 +0,0 @@
-import axios, { AxiosInstance } from "axios";
-import { WhatsAppConfig, WhatsAppMessage } from "./types";
-
-export class WhatsAppClient {
-    private client: AxiosInstance;
-    private config: WhatsAppConfig;
-
-    constructor(config: WhatsAppConfig) {
-        this.config = config;
-        this.client = axios.create({
-            baseURL: "https://graph.facebook.com/v17.0",
-            headers: {
-                Authorization: `Bearer ${config.accessToken}`,
-                "Content-Type": "application/json",
-            },
-        });
-    }
-
-    async sendMessage(message: WhatsAppMessage): Promise<any> {
-        const endpoint = `/${this.config.phoneNumberId}/messages`;
-
-        const payload = {
-            messaging_product: "whatsapp",
-            recipient_type: "individual",
-            to: message.to,
-            type: message.type,
-            ...(message.type === "text"
-                ? { text: { body: message.content } }
-                : { template: message.content }),
-        };
-
-        return this.client.post(endpoint, payload);
-    }
-
-    async verifyWebhook(token: string): Promise<boolean> {
-        return token === this.config.webhookVerifyToken;
-    }
-}

package/src/handlers/index.ts

@@ -1,2 +0,0 @@
-export * from "./message.handler";
-export * from "./webhook.handler";

package/src/handlers/message.handler.ts

@@ -1,20 +0,0 @@
-import { WhatsAppClient } from "../client";
-import { WhatsAppMessage } from "../types";
-
-export class MessageHandler {
-    constructor(private client: WhatsAppClient) {}
-
-    async send(message: WhatsAppMessage): Promise<any> {
-        try {
-            const response = await this.client.sendMessage(message);
-            return response.data;
-        } catch (error: unknown) {
-            if (error instanceof Error) {
-                throw new Error(
-                    `Failed to send WhatsApp message: ${error.message}`
-                );
-            }
-            throw new Error('Failed to send WhatsApp message');
-        }
-    }
-}

package/src/handlers/webhook.handler.ts

@@ -1,45 +0,0 @@
-import { WhatsAppClient } from "../client";
-import { WhatsAppWebhookEvent } from "../types";
-
-export class WebhookHandler {
-    constructor(private client: WhatsAppClient) {}
-
-    async handle(event: WhatsAppWebhookEvent): Promise<void> {
-        try {
-            // Process messages
-            if (event.entry?.[0]?.changes?.[0]?.value?.messages) {
-                const messages = event.entry[0].changes[0].value.messages;
-                for (const message of messages) {
-                    await this.handleMessage(message);
-                }
-            }
-
-            // Process status updates
-            if (event.entry?.[0]?.changes?.[0]?.value?.statuses) {
-                const statuses = event.entry[0].changes[0].value.statuses;
-                for (const status of statuses) {
-                    await this.handleStatus(status);
-                }
-            }
-        } catch (error: unknown) {
-            if (error instanceof Error) {
-                throw new Error(
-                    `Failed to send WhatsApp message: ${error.message}`
-                );
-            }
-            throw new Error("Failed to send WhatsApp message");
-        }
-    }
-
-    private async handleMessage(message: any): Promise<void> {
-        // Implement message handling logic
-        // This could emit events or trigger callbacks based on your framework's needs
-        console.log("Received message:", message);
-    }
-
-    private async handleStatus(status: any): Promise<void> {
-        // Implement status update handling logic
-        // This could emit events or trigger callbacks based on your framework's needs
-        console.log("Received status update:", status);
-    }
-}

package/src/index.ts

@@ -1,36 +0,0 @@
-import { Plugin } from "@elizaos/core";
-import { WhatsAppClient } from "./client";
-import { WhatsAppConfig, WhatsAppMessage, WhatsAppWebhookEvent } from "./types";
-import { MessageHandler, WebhookHandler } from "./handlers";
-
-export class WhatsAppPlugin implements Plugin {
-    private client: WhatsAppClient;
-    private messageHandler: MessageHandler;
-    private webhookHandler: WebhookHandler;
-
-    name: string;
-    description: string;
-
-    constructor(private config: WhatsAppConfig) {
-        this.name = "WhatsApp Cloud API Plugin";
-        this.description =
-            "A plugin for integrating WhatsApp Cloud API with your application.";
-        this.client = new WhatsAppClient(config);
-        this.messageHandler = new MessageHandler(this.client);
-        this.webhookHandler = new WebhookHandler(this.client);
-    }
-
-    async sendMessage(message: WhatsAppMessage): Promise<any> {
-        return this.messageHandler.send(message);
-    }
-
-    async handleWebhook(event: WhatsAppWebhookEvent): Promise<void> {
-        return this.webhookHandler.handle(event);
-    }
-
-    async verifyWebhook(token: string): Promise<boolean> {
-        return this.client.verifyWebhook(token);
-    }
-}
-
-export * from "./types";

package/src/types.ts

@@ -1,58 +0,0 @@
-export interface WhatsAppConfig {
-    accessToken: string;
-    phoneNumberId: string;
-    webhookVerifyToken?: string;
-    businessAccountId?: string;
-}
-
-export interface WhatsAppMessage {
-    type: "text" | "template";
-    to: string;
-    content: string | WhatsAppTemplate;
-}
-
-export interface WhatsAppTemplate {
-    name: string;
-    language: {
-        code: string;
-    };
-    components?: Array<{
-        type: string;
-        parameters: Array<{
-            type: string;
-            text?: string;
-        }>;
-    }>;
-}
-
-export interface WhatsAppWebhookEvent {
-    object: string;
-    entry: Array<{
-        id: string;
-        changes: Array<{
-            value: {
-                messaging_product: string;
-                metadata: {
-                    display_phone_number: string;
-                    phone_number_id: string;
-                };
-                statuses?: Array<{
-                    id: string;
-                    status: string;
-                    timestamp: string;
-                    recipient_id: string;
-                }>;
-                messages?: Array<{
-                    from: string;
-                    id: string;
-                    timestamp: string;
-                    text?: {
-                        body: string;
-                    };
-                    type: string;
-                }>;
-            };
-            field: string;
-        }>;
-    }>;
-}

package/src/utils/index.ts

@@ -1 +0,0 @@
-export * from "./validators";

package/src/utils/validators.ts

@@ -1,44 +0,0 @@
-import { WhatsAppMessage, WhatsAppTemplate, WhatsAppConfig } from "../types";
-
-export function validateConfig(config: WhatsAppConfig): void {
-    if (!config.accessToken) {
-        throw new Error("WhatsApp access token is required");
-    }
-    if (!config.phoneNumberId) {
-        throw new Error("WhatsApp phone number ID is required");
-    }
-}
-
-export function validateMessage(message: WhatsAppMessage): void {
-    if (!message.to) {
-        throw new Error("Recipient phone number is required");
-    }
-
-    if (!message.type) {
-        throw new Error("Message type is required");
-    }
-
-    if (!message.content) {
-        throw new Error("Message content is required");
-    }
-
-    if (message.type === "template") {
-        validateTemplate(message.content as WhatsAppTemplate);
-    }
-}
-
-export function validateTemplate(template: WhatsAppTemplate): void {
-    if (!template.name) {
-        throw new Error("Template name is required");
-    }
-
-    if (!template.language || !template.language.code) {
-        throw new Error("Template language code is required");
-    }
-}
-
-export function validatePhoneNumber(phoneNumber: string): boolean {
-    // Basic phone number validation - can be enhanced based on requirements
-    const phoneRegex = /^\d{1,15}$/;
-    return phoneRegex.test(phoneNumber);
-}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-    "extends": "../core/tsconfig.json",
-    "compilerOptions": {
-        "outDir": "./dist",
-        "rootDir": "src",
-        "baseUrl": ".",
-        "types": [
-            "node",
-            "jest"
-        ]
-    },
-    "include": [
-        "src/**/*.ts"
-    ],
-    "exclude": [
-        "node_modules",
-        "dist",
-        "**/*.test.ts"
-    ]
-}

package/tsup.config.ts

@@ -1,19 +0,0 @@
-import { defineConfig } from "tsup";
-
-export default defineConfig({
-    entry: ["src/index.ts"],
-    outDir: "dist",
-    sourcemap: true,
-    clean: true,
-    format: ["esm"], // Ensure you're targeting CommonJS
-    external: [
-        "dotenv", // Externalize dotenv to prevent bundling
-        "fs", // Externalize fs to use Node.js built-in module
-        "path", // Externalize other built-ins if necessary
-        "@reflink/reflink",
-        "@node-llama-cpp",
-        "https",
-        "http",
-        "agentkeepalive",
-    ],
-});