wuzapi 1.2.0 → 1.4.0

package/README.md

@@ -26,6 +26,8 @@ yarn add wuzapi
 
 ## Quick Start
 
+### Traditional Usage (Global Token)
+
 ```typescript
 import WuzapiClient from "wuzapi";
 
@@ -52,6 +54,48 @@ console.log("Connected:", status.Connected);
 console.log("Logged In:", status.LoggedIn);
 ```
 
+### Flexible Token Usage
+
+```typescript
+import WuzapiClient from "wuzapi";
+
+// Create client without token (or with admin token)
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  token: "admin-token", // Optional: admin token as default
+});
+
+// Use specific user token for operations
+const userToken = "user-specific-token";
+
+// Connect with user token
+await client.session.connect(
+  {
+    Subscribe: ["Message", "ReadReceipt"],
+    Immediate: false,
+  },
+  { token: userToken }
+);
+
+// Send message with user token
+await client.chat.sendText(
+  {
+    Phone: "5491155554444",
+    Body: "Hello from user-specific token!",
+  },
+  { token: userToken }
+);
+
+// Admin operations with admin token (uses default)
+const users = await client.admin.listUsers();
+
+// Or explicitly use admin token
+const newUser = await client.admin.addUser(
+  { name: "John", token: "new-user-token" },
+  { token: "admin-token" }
+);
+```
+
 ## Configuration
 
 The client requires a configuration object with the following properties:
@@ -59,8 +103,45 @@ The client requires a configuration object with the following properties:
 ```typescript
 interface WuzapiConfig {
   apiUrl: string; // The WuzAPI server URL
-  token: string; // Your user authentication token
+  token?: string; // Your user authentication token (optional)
 }
+
+interface RequestOptions {
+  token?: string; // Token override for specific requests
+}
+```
+
+### Authentication Options
+
+You have two ways to handle authentication:
+
+1. **Global Token**: Set a default token in the client configuration
+2. **Per-Request Token**: Override the token for specific API calls
+
+```typescript
+// Option 1: Global token (traditional usage)
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  token: "your-default-token",
+});
+
+// Option 2: No global token, specify per request
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  // token is optional
+});
+
+// Option 3: Global token with per-request overrides
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  token: "admin-token", // Default admin token
+});
+
+// Use different token for specific operations
+await client.chat.sendText(
+  { Phone: "5491155554444", Body: "Hello!" },
+  { token: "user-specific-token" }
+);
 ```
 
 ## API Modules
@@ -109,13 +190,22 @@ await client.session.configureS3({
 Send messages and manage chat interactions.
 
 ```typescript
-// Send text message
+// Send text message (using global token)
 await client.chat.sendText({
   Phone: "5491155554444",
   Body: "Hello World!",
   Id: "optional-message-id",
 });
 
+// Send with specific token override
+await client.chat.sendText(
+  {
+    Phone: "5491155554444",
+    Body: "Hello with custom token!",
+  },
+  { token: "user-specific-token" }
+);
+
 // Reply to a message
 await client.chat.sendText({
   Phone: "5491155554444",
@@ -247,7 +337,7 @@ await client.group.removePhoto("120362023605733675@g.us");
 Manage users (requires admin token).
 
 ```typescript
-// Create admin client
+// Option 1: Create dedicated admin client
 const adminClient = new WuzapiClient({
   apiUrl: "http://localhost:8080",
   token: "your-admin-token",
@@ -256,31 +346,43 @@ const adminClient = new WuzapiClient({
 // List all users
 const users = await adminClient.admin.listUsers();
 
+// Option 2: Use shared client with token override
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  // No default token or user token as default
+});
+
+// Admin operations with explicit admin token
+const users = await client.admin.listUsers({ token: "admin-token" });
+
 // Add new user
-const newUser = await adminClient.admin.addUser({
-  name: "John Doe",
-  token: "user-token-123",
-  webhook: "https://example.com/webhook",
-  events: "Message,ReadReceipt",
-  proxyConfig: {
-    enabled: true,
-    proxyURL: "socks5://user:pass@proxy:port",
-  },
-  s3Config: {
-    enabled: true,
-    endpoint: "https://s3.amazonaws.com",
-    region: "us-east-1",
-    bucket: "user-media-bucket",
-    accessKey: "AKIA...",
-    secretKey: "secret...",
-    pathStyle: false,
-    mediaDelivery: "both",
-    retentionDays: 30,
+const newUser = await client.admin.addUser(
+  {
+    name: "John Doe",
+    token: "user-token-123",
+    webhook: "https://example.com/webhook",
+    events: "Message,ReadReceipt",
+    proxyConfig: {
+      enabled: true,
+      proxyURL: "socks5://user:pass@proxy:port",
+    },
+    s3Config: {
+      enabled: true,
+      endpoint: "https://s3.amazonaws.com",
+      region: "us-east-1",
+      bucket: "user-media-bucket",
+      accessKey: "AKIA...",
+      secretKey: "secret...",
+      pathStyle: false,
+      mediaDelivery: "both",
+      retentionDays: 30,
+    },
   },
-});
+  { token: "admin-token" }
+);
 
 // Delete user
-await adminClient.admin.deleteUser(2);
+await client.admin.deleteUser(2, { token: "admin-token" });
 ```
 
 ### Webhook Module
@@ -301,11 +403,128 @@ console.log("Subscribed events:", webhookConfig.subscribe);
 
 WuzAPI sends real-time events to your webhook endpoint. Here's how to handle different types of events:
 
+## Webhook Payload Structure
+
+When S3 is enabled, webhook payloads will include S3 information based on the `media_delivery` setting configured in your WuzAPI instance.
+
+### Standard Event Payload
+
+```json
+{
+  "event": {
+    "Info": {
+      "ID": "3EB06F9067F80BAB89FF",
+      "Type": "text",
+      "PushName": "John Doe",
+      "Timestamp": "2024-12-25T10:30:00Z",
+      "Source": {
+        "Chat": "5491155553934@s.whatsapp.net",
+        "Sender": "5491155553934@s.whatsapp.net",
+        "IsFromMe": false,
+        "IsGroup": false
+      }
+    },
+    "Message": {
+      "conversation": "Hello, this is a test message!"
+    },
+    "IsEphemeral": false,
+    "IsViewOnce": false,
+    "IsDocumentWithCaption": false,
+    "IsEdit": false
+  }
+}
+```
+
+### S3 Only (`media_delivery: "s3"`)
+
+```json
+{
+  "event": {
+    "Info": {
+      "ID": "3EB06F9067F80BAB89FF",
+      "Type": "image",
+      "PushName": "John Doe",
+      "Timestamp": "2024-12-25T10:30:00Z",
+      "Source": {
+        "Chat": "5491155553934@s.whatsapp.net",
+        "Sender": "5491155553934@s.whatsapp.net",
+        "IsFromMe": false,
+        "IsGroup": false
+      }
+    },
+    "Message": {
+      "imageMessage": {
+        "caption": "Check out this photo!",
+        "mimetype": "image/jpeg",
+        "width": 1920,
+        "height": 1080,
+        "fileLength": 245632
+      }
+    },
+    "IsEphemeral": false,
+    "IsViewOnce": false
+  },
+  "s3": {
+    "url": "https://my-bucket.s3.us-east-1.amazonaws.com/users/abc123/inbox/5491155553934/2024/12/25/images/3EB06F9067F80BAB89FF.jpg",
+    "key": "users/abc123/inbox/5491155553934/2024/12/25/images/3EB06F9067F80BAB89FF.jpg",
+    "bucket": "my-bucket",
+    "size": 245632,
+    "mimeType": "image/jpeg",
+    "fileName": "3EB06F9067F80BAB89FF.jpg"
+  }
+}
+```
+
+### Both S3 and Base64 (`media_delivery: "both"`)
+
+```json
+{
+  "event": {
+    "Info": { "..." },
+    "Message": {
+      "imageMessage": {
+        "caption": "Check out this photo!",
+        "mimetype": "image/jpeg",
+        "width": 1920,
+        "height": 1080
+      }
+    }
+  },
+  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k=",
+  "mimeType": "image/jpeg",
+  "fileName": "3EB06F9067F80BAB89FF.jpg",
+  "s3": {
+    "url": "https://my-bucket.s3.us-east-1.amazonaws.com/users/abc123/inbox/5491155553934/2024/12/25/images/3EB06F9067F80BAB89FF.jpg",
+    "key": "users/abc123/inbox/5491155553934/2024/12/25/images/3EB06F9067F80BAB89FF.jpg",
+    "bucket": "my-bucket",
+    "size": 245632,
+    "mimeType": "image/jpeg",
+    "fileName": "3EB06F9067F80BAB89FF.jpg"
+  }
+}
+```
+
+### Base64 Only (`media_delivery: "base64"`)
+
+```json
+{
+  "event": { "..." },
+  "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAv/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAAAAX/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABmX/9k=",
+  "mimeType": "image/jpeg",
+  "fileName": "3EB06F9067F80BAB89FF.jpg"
+}
+```
+
 ### Basic Webhook Setup
 
 ```typescript
 import express from "express";
-import WuzapiClient from "wuzapi";
+import WuzapiClient, {
+  EventType,
+  hasS3Media,
+  hasBase64Media,
+  WebhookPayload,
+} from "wuzapi";
 
 const app = express();
 app.use(express.json());
@@ -315,18 +534,43 @@ const client = new WuzapiClient({
   token: "your-token",
 });
 
-// Webhook endpoint
+// Webhook endpoint with S3 media support
 app.post("/webhook", async (req, res) => {
   try {
-    const event = req.body;
-
-    // Handle different event types
-    if (event.Message) {
-      await handleMessage(event);
-    } else if (event.MessageIDs && event.Type) {
-      await handleReceipt(event);
-    } else if (event.From && typeof event.Unavailable !== "undefined") {
-      await handlePresence(event);
+    const webhookPayload: WebhookPayload = req.body;
+
+    // Handle S3 media information if present
+    if (hasS3Media(webhookPayload)) {
+      console.log("☁️ S3 Media:", {
+        url: webhookPayload.s3.url,
+        bucket: webhookPayload.s3.bucket,
+        size: webhookPayload.s3.size,
+        type: webhookPayload.s3.mimeType,
+      });
+    }
+
+    if (hasBase64Media(webhookPayload)) {
+      console.log("📦 Base64 media included");
+      // Process base64 media: webhookPayload.base64
+    }
+
+    // Extract the actual event data
+    const event = webhookPayload.event || webhookPayload;
+    const eventType = detectEventType(event);
+
+    // Handle different event types using EventType enum
+    switch (eventType) {
+      case EventType.MESSAGE:
+        await handleMessage(event);
+        break;
+      case EventType.RECEIPT:
+        await handleReceipt(event);
+        break;
+      case EventType.PRESENCE:
+        await handlePresence(event);
+        break;
+      default:
+        console.log(`Unhandled event type: ${eventType}`);
     }
 
     res.status(200).json({ success: true });
@@ -336,6 +580,18 @@ app.post("/webhook", async (req, res) => {
   }
 });
 
+// Helper function to detect event type
+function detectEventType(event: any): EventType | string {
+  if (event.Message && event.Info) return EventType.MESSAGE;
+  if (event.MessageIDs && event.Type) return EventType.RECEIPT;
+  if (event.From && typeof event.Unavailable !== "undefined")
+    return EventType.PRESENCE;
+  if (event.State && event.MessageSource) return EventType.CHAT_PRESENCE;
+  if (event.Codes) return EventType.QR;
+  // Add more detection logic as needed
+  return "Unknown";
+}
+
 app.listen(3000, () => {
   console.log("Webhook server running on port 3000");
 });
@@ -823,23 +1079,23 @@ app.get("/health", (req, res) => {
 // Initialize
 async function initialize() {
   try {
-    // Connect to WhatsApp with all events
+    // Connect to WhatsApp with all events using EventType enum
     await client.session.connect({
       Subscribe: [
-        "Message",
-        "ReadReceipt",
-        "Presence",
-        "ChatPresence",
-        "GroupInfo",
-        "Contact",
-        "PushName",
-        "Picture",
-        "QR",
-        "Connected",
-        "Disconnected",
-        "LoggedOut",
-        "UndecryptableMessage",
-        "StreamError",
+        EventType.MESSAGE,
+        EventType.RECEIPT,
+        EventType.PRESENCE,
+        EventType.CHAT_PRESENCE,
+        EventType.GROUP_INFO,
+        EventType.CONTACT,
+        EventType.PUSH_NAME,
+        EventType.PICTURE,
+        EventType.QR,
+        EventType.CONNECTED,
+        EventType.DISCONNECTED,
+        EventType.LOGGED_OUT,
+        EventType.UNDECRYPTABLE_MESSAGE,
+        EventType.STREAM_ERROR,
       ],
       Immediate: false,
     });
@@ -868,6 +1124,9 @@ All webhook events are fully typed. Import the specific event types you need:
 
 ```typescript
 import {
+  // Event type enum for all possible events
+  EventType,
+
   // Core message types
   Message,
   MessageEvent,
@@ -887,6 +1146,16 @@ import {
   PollCreationMessage,
   ReactionMessage,
 
+  // Webhook payload types
+  WebhookPayload,
+  S3MediaInfo,
+  S3OnlyWebhookPayload,
+  Base64OnlyWebhookPayload,
+  BothMediaWebhookPayload,
+  hasS3Media,
+  hasBase64Media,
+  hasBothMedia,
+
   // Event types
   Receipt,
   Presence,
@@ -904,33 +1173,64 @@ import {
   WhatsAppEvent,
 } from "wuzapi";
 
-// Type-safe event handling with full message structure
-async function handleTypedMessage(event: MessageEvent) {
-  const messageContent = getMessageContent(event.Message);
+// Type-safe event handling with EventType enum
+async function handleTypedWebhook(webhookPayload: WebhookPayload) {
+  const event = webhookPayload.event;
 
-  if (messageContent?.type === "image") {
-    // TypeScript knows this is an ImageMessage
-    const imageMsg: ImageMessage = messageContent.content;
-    console.log(`Image dimensions: ${imageMsg.width}x${imageMsg.height}`);
-    console.log(`File size: ${imageMsg.fileLength} bytes`);
+  // Type-safe event detection using EventType enum
+  const eventType = detectEventType(event);
 
-    // Full type safety and autocompletion
-    if (imageMsg.caption) {
-      console.log(`Caption: ${imageMsg.caption}`);
-    }
-  }
+  switch (eventType) {
+    case EventType.MESSAGE:
+      const messageEvent = event as MessageEvent;
+      const messageContent = getMessageContent(messageEvent.Message);
 
-  if (messageContent?.type === "buttons") {
-    // TypeScript knows this is a ButtonsMessage
-    const buttonsMsg: ButtonsMessage = messageContent.content;
-    console.log(`Button message: ${buttonsMsg.contentText}`);
+      if (messageContent?.type === "image") {
+        // TypeScript knows this is an ImageMessage
+        const imageMsg: ImageMessage = messageContent.content;
+        console.log(`Image dimensions: ${imageMsg.width}x${imageMsg.height}`);
 
-    buttonsMsg.buttons?.forEach((button, index) => {
-      console.log(`Button ${index + 1}: ${button.buttonText?.displayText}`);
-    });
+        // Handle S3 media if available
+        if (hasS3Media(webhookPayload)) {
+          console.log(`S3 URL: ${webhookPayload.s3.url}`);
+          // Download from S3 or process as needed
+        }
+
+        // Handle Base64 media if available
+        if (hasBase64Media(webhookPayload)) {
+          console.log("Processing base64 image data");
+          // Process base64 data: webhookPayload.base64
+        }
+      }
+      break;
+
+    case EventType.RECEIPT:
+      const receiptEvent = event as Receipt;
+      console.log(`Receipt type: ${receiptEvent.Type}`);
+      break;
+
+    case EventType.PRESENCE:
+      const presenceEvent = event as Presence;
+      console.log(`User ${presenceEvent.From.User} presence update`);
+      break;
+
+    default:
+      console.log(`Unhandled event: ${eventType}`);
   }
 }
 
+// Complete webhook server with S3 support
+app.post("/webhook", async (req, res) => {
+  try {
+    const payload: WebhookPayload = req.body;
+    await handleTypedWebhook(payload);
+    res.status(200).json({ success: true });
+  } catch (error) {
+    console.error("Webhook error:", error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
 // Helper function to handle all message types generically
 function processMessageContent(content: MessageContent) {
   switch (content.type) {
@@ -1037,6 +1337,42 @@ try {
 }
 ```
 
+### Token Authentication Errors
+
+When no token is provided (either globally or per-request), the library will throw a specific error:
+
+```typescript
+import { WuzapiError } from "wuzapi";
+
+// Client without global token
+const client = new WuzapiClient({
+  apiUrl: "http://localhost:8080",
+  // No token provided
+});
+
+try {
+  // This will fail - no token provided
+  await client.chat.sendText({
+    Phone: "5491155554444",
+    Body: "This will fail",
+  });
+} catch (error) {
+  if (error instanceof WuzapiError && error.code === 401) {
+    console.error("Authentication required:", error.message);
+    // "No authentication token provided. Either set a token in the client config or provide one in the request options."
+  }
+}
+
+// Fix by providing token
+await client.chat.sendText(
+  {
+    Phone: "5491155554444",
+    Body: "Now it works!",
+  },
+  { token: "your-token" }
+);
+```
+
 ### Error Types
 
 - **Network Errors**: Connection issues, timeouts

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from 'axios';
-import { WuzapiConfig } from './types/common.js';
+import { WuzapiConfig, RequestOptions } from './types/common.js';
 export declare class WuzapiError extends Error {
     code: number;
     details?: unknown;
@@ -9,8 +9,13 @@ export declare class BaseClient {
     protected axios: AxiosInstance;
     protected config: WuzapiConfig;
     constructor(config: WuzapiConfig);
-    protected request<T>(method: "GET" | "POST" | "DELETE", endpoint: string, data?: unknown): Promise<T>;
-    protected get<T>(endpoint: string): Promise<T>;
-    protected post<T>(endpoint: string, data?: unknown): Promise<T>;
-    protected delete<T>(endpoint: string): Promise<T>;
+    /**
+     * Resolve the token from request options or instance config
+     * Throws an error if no token is available
+     */
+    private resolveToken;
+    protected request<T>(method: "GET" | "POST" | "DELETE", endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    protected get<T>(endpoint: string, options?: RequestOptions): Promise<T>;
+    protected post<T>(endpoint: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    protected delete<T>(endpoint: string, options?: RequestOptions): Promise<T>;
 }