@gamastudio/sendwave-provider 1.0.2 → 1.0.4

package/.github/workflows/build.yml

@@ -1,31 +1,31 @@
-name: Build and Publish to NPM
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: 📥 Checkout code
-        uses: actions/checkout@v3
-
-      - name: 🧰 Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: https://registry.npmjs.org/
-
-      - name: 📦 Install dependencies
-        run: npm install
-
-      - name: 🛠️ Build project
-        run: npm run build
-
-      - name: 🚀 Publish to npm
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+name: Build and Publish to NPM
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📥 Checkout code
+        uses: actions/checkout@v3
+
+      - name: 🧰 Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+
+      - name: 📦 Install dependencies
+        run: npm install
+
+      - name: 🛠️ Build project
+        run: npm run build
+
+      - name: 🚀 Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

package/README.md

@@ -25,6 +25,85 @@ const provider = createSendWaveProvider({
 await provider.initAll(provider.globalVendorArgs.port);
 ```
 
+### Multi-Tenant: Multiple Instances with One Webhook
+
+You can manage multiple Sendwave instances with a single provider. The webhook will route messages automatically based on `instanceName` in the payload.
+
+```typescript
+import { createSendWaveProvider } from "@gamastudio/sendwave-provider";
+
+const provider = createSendWaveProvider({
+  port: 3000,
+  url: "https://msg.sendwaves.cloud",
+  instances: [
+    { name: "bot-sales", apiKey: "api-key-sales" },
+    { name: "bot-support", apiKey: "api-key-support" },
+    { name: "bot-marketing", apiKey: "api-key-marketing" },
+  ],
+});
+
+await provider.initAll(provider.globalVendorArgs.port);
+
+// Send message to a specific instance
+await provider.sendText(
+  { from: "573123456789", text: "Hello from sales!" },
+  "bot-sales"
+);
+
+// Or use the default (first instance)
+await provider.sendText({
+  from: "573123456789",
+  text: "Hello!",
+});
+
+// List registered instances
+console.log(provider.getInstances().map((i) => i.name));
+```
+
+**Webhook routing:** the provider reads `instanceName` from `body.instanceName`, `body.inputs.instanceName`, or `body.instance.name`. Point all your Sendwave webhooks to the same `/webhook` URL.
+
+**QR / State per instance:**
+- `/qr` → default instance
+- `/qr/bot-sales` → specific instance
+- `/state` → default instance
+- `/state/bot-sales` → specific instance
+
+## ⚙️ Configuration
+
+```typescript
+const provider = createSendWaveProvider({
+  name: "MyBot",
+  apiKey: "your-api-key-here",
+  url: "https://msg.sendwaves.cloud", // Optional
+  port: 3000,
+  host: "0.0.0.0",
+  readMessages: true, // Auto-mark incoming messages as read
+  message: {
+    mergeMessage: true,        // Merge rapid messages from same user
+    timeMergeMessage: 3,       // Base wait time in seconds
+    maxWaitTime: 30,           // Maximum wait time in seconds
+    shortMessageThreshold: 10, // Short messages merge faster
+    adaptiveTimer: true,       // Smart timing based on message patterns
+  },
+  queueFlow: {
+    enabled: true,
+    warningTimeout: 30 * 60 * 1000, // 30 minutes
+    endTimeout: 2 * 60 * 1000,      // 2 minutes after warning
+  },
+  payloadLimits: {
+    json: "50mb",
+    urlencoded: "50mb",
+    text: "10mb",
+    media: {
+      image: "10mb",
+      video: "100mb",
+      audio: "50mb",
+      document: "25mb",
+    },
+  },
+});
+```
+
 ## 📤 Sending Messages
 
 ### Text Messages
@@ -33,31 +112,75 @@ await provider.initAll(provider.globalVendorArgs.port);
 await provider.sendText({
   from: "573123456789",
   text: "Hello! Welcome to our service.",
+  delay: 2000, // Optional typing delay
 });
+
+// Send to a specific instance (multi-tenant)
+await provider.sendText(
+  { from: "573123456789", text: "Hello!" },
+  "bot-sales"
+);
 ```
 
-### Interactive Polls (New! 📊)
+### Presence Indicators
 
 ```typescript
-await provider.sendPoll({
+await provider.sendPresence({
   from: "573123456789",
-  poll: {
-    name: "¿Qué te parece el nuevo proveedor?",
-    values: ["Excelente", "Bueno", "Mejorable"],
-    selectableCount: 1 // Optional, default: 1
-  }
+  presence: "composing", // or "recording"
+  delay: 2000,
+});
+```
+
+### Media Messages
+
+```typescript
+// Image
+await provider.sendImage({
+  from: "573123456789",
+  url: "https://example.com/image.jpg",
+  text: "Optional caption",
+});
+
+// Video
+await provider.sendVideo({
+  from: "573123456789",
+  url: "https://example.com/video.mp4",
+  text: "Optional caption",
+});
+
+// Document/File
+await provider.sendFile({
+  from: "573123456789",
+  url: "https://example.com/file.pdf",
+  fileName: "document.pdf",
+  text: "Optional caption",
+});
+
+// Audio
+await provider.sendAudio({
+  from: "573123456789",
+  url: "https://example.com/audio.mp3",
+});
+
+// Voice message (PTT)
+await provider.sendVoice({
+  from: "573123456789",
+  url: "https://example.com/voice.ogg",
 });
 ```
 
-### Intelligent Buttons (Easier! 🔘)
+### Interactive Buttons
 
-The provider is now "intelligent" and accepts multiple formats for buttons.
+The provider accepts multiple formats for buttons.
 
 ```typescript
 // 1. Super Simple (Quick Replies)
 await provider.sendButton({
   from: "573123456789",
   title: "Main Menu",
+  body: "Select an option",
+  footer: "Sendwaves Provider",
   buttons: ["🛒 Catalog", "🎁 Promotions", "📞 Support"]
 });
 
@@ -69,6 +192,7 @@ await provider.sendButton({
   buttons: [
     { type: "reply", displayText: "Cash" },
     { type: "url", displayText: "Visit Web", url: "https://example.com" },
+    { type: "call", displayText: "Call Us", phoneNumber: "+573123456789" },
     { type: "copy", displayText: "Copy Coupon", copyText: "SAVE20" },
     { type: "pix", displayText: "Pay with Pix", keyType: "email", key: "pix@bot.com" }
   ]
@@ -82,7 +206,40 @@ await provider.sendButton({
 - `copy`: Copies text or code to clipboard.
 - `pix`: Brazilian payment system integration.
 
-### Intelligent Lists (Simple & Advanced 📜)
+### Carousel Messages
+
+Send a scrollable carousel with multiple cards. Each card supports its own buttons.
+
+```typescript
+await provider.sendCarousel({
+  from: "573123456789",
+  title: "Featured Products",
+  description: "Swipe to see our best offers",
+  footer: "Sendwaves Store",
+  cards: [
+    {
+      text: "Premium Plan",
+      thumbnailUrl: "https://example.com/plan1.jpg",
+      footerText: "Best value",
+      buttons: [
+        { type: "reply", displayText: "Buy Now" },
+        { type: "url", displayText: "More Info", url: "https://example.com/plan1" }
+      ]
+    },
+    {
+      text: "Basic Plan",
+      thumbnailUrl: "https://example.com/plan2.jpg",
+      footerText: "Affordable",
+      buttons: [
+        { type: "reply", displayText: "Buy Now" }
+      ]
+    }
+  ],
+  delay: 2000
+});
+```
+
+### Interactive Lists
 
 ```typescript
 // Simple List (Array of strings)
@@ -100,7 +257,9 @@ await provider.sendList({
   from: "573123456789",
   list: {
     title: "Product Categories",
+    description: "Choose a category",
     button: "Select Category",
+    footerText: "Sendwaves Provider",
     content: [
       {
         title: "Electronics",
@@ -114,24 +273,79 @@ await provider.sendList({
 });
 ```
 
-### Media Messages
+### Polls
+
+```typescript
+await provider.sendPoll({
+  from: "573123456789",
+  poll: {
+    name: "¿Qué te parece el nuevo proveedor?",
+    values: ["Excelente", "Bueno", "Mejorable"],
+    selectableCount: 1 // Optional, default: 1
+  }
+});
+```
+
+### Locations
+
+```typescript
+await provider.sendLocation({
+  from: "573123456789",
+  name: "Our Office",
+  address: "123 Main St, Bogotá",
+  latitude: 4.711,
+  longitude: -74.0721,
+});
+```
+
+### Reactions
+
+```typescript
+await provider.sendReaction({
+  key: {
+    remoteJid: "573123456789@s.whatsapp.net",
+    fromMe: false,
+    id: "MESSAGE_ID",
+  },
+  reaction: "👍",
+});
+```
+
+### Mark as Read
 
 ```typescript
-// Images, Videos, Documents, and Voice
-await provider.sendImage({ from: "573123456789", url: "https://...", text: "Caption" });
-await provider.sendVideo({ from: "573123456789", url: "https://...", text: "Caption" });
-await provider.sendFile({ from: "573123456789", url: "https://...", fileName: "file.pdf" });
-await provider.sendVoice({ from: "573123456789", url: "https://..." });
+await provider.readMessages({
+  from: "573123456789@s.whatsapp.net",
+  messageId: "MESSAGE_ID",
+});
 ```
 
-## 🔄 Queue Flow System (100% Automatic)
+## 🧠 Intelligent Message Merging
 
-The Queue Flow system manages user sessions, handling timeouts and inactive users automatically.
+When `mergeMessage` is enabled, rapid messages from the same user are merged into a single message.
+
+```typescript
+const provider = createSendWaveProvider({
+  message: {
+    mergeMessage: true,
+    timeMergeMessage: 4,
+    maxWaitTime: 30,
+    shortMessageThreshold: 10,
+    adaptiveTimer: true,
+  }
+});
+```
+
+Example:
+- User sends "Hola" then "como estas"
+- Result: single message with body `"Hola como estas"`
+
+## 🔄 Queue Flow System
+
+Automatic session management for inactive users.
 
 ```typescript
 const provider = createSendWaveProvider({
-  name: "MyBot",
-  apiKey: "your-key",
   queueFlow: {
     enabled: true,
     warningTimeout: 30 * 60 * 1000, // 30 mins
@@ -139,20 +353,42 @@ const provider = createSendWaveProvider({
     warningMessage: "⏳ You seem inactive. Still there?",
   },
 });
+
+// Listen to inactivity events
+provider.onQueueFlowEvent("userInactive-573123456789", (data) => {
+  console.log(data.isActive ? "User warned" : "Session ended");
+});
 ```
 
 ## 🎯 Event System
 
 ```typescript
-provider.on('ready', (isReady) => console.log('Connected:', isReady));
-provider.on('message', (ctx) => console.log(`From ${ctx.from}: ${ctx.body}`));
+provider.on("ready", (isReady) => console.log("Connected:", isReady));
+provider.on("message", (ctx) => console.log(`From ${ctx.from}: ${ctx.body}`));
+provider.on("user-message", (data) => console.log("User message:", data));
+provider.on("flow-message", (data) => console.log("Flow message:", data));
+provider.on("auth_failure", (payload) => console.error("Auth failed:", payload));
+provider.on("notice", ({ title, instructions }) => console.log(title, instructions));
 ```
 
 ## 🏗️ Architecture
 
-- **Provider Layer**: Main SendWaveProvider class.
-- **Sender Layer**: Intelligent message transformation.
-- **Queue Flow**: Automatic session management.
+The project is organized in modular layers:
+
+- **`config/`**: Default values and constants.
+- **`domain/`**: Pure types and interfaces.
+- **`infrastructure/`**: HTTP client, API repository, media detection, message parser.
+- **`application/`**: Business logic: message strategies, buffer merging, connection polling, queue flow.
+- **`presentation/`**: Provider and core classes, HTML pages.
+- **`shared/`**: Common utilities and exceptions.
+
+### Adding a New Message Type
+
+1. Create a strategy in `src/application/messaging/strategies/`.
+2. Implement the `SendStrategy<T>` interface.
+3. Register it in `MessageSenderService`.
+4. Add the public method to `SendWaveProvider`.
+5. Add the type to `ProviderInterface` and `message.types.ts`.
 
 ## 📜 License
 

package/build/application/connection/connection-polling.service.d.ts

@@ -0,0 +1,16 @@
+import { SendWaveApiRepository } from "../../infrastructure/persistence/sendwave-api.repository";
+export interface ConnectionStateListener {
+    onConnected: () => void;
+    onDisconnected: () => void;
+    onAuthFailure: (error: any) => void;
+}
+export declare class ConnectionPollingService {
+    private readonly api;
+    private readonly listener;
+    private timer?;
+    private lastReadyState?;
+    constructor(api: SendWaveApiRepository, listener: ConnectionStateListener);
+    check(): Promise<void>;
+    start(): void;
+    stop(): void;
+}

package/build/application/connection/connection-polling.service.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionPollingService = void 0;
+const constants_1 = require("../../config/constants");
+class ConnectionPollingService {
+    constructor(api, listener) {
+        this.api = api;
+        this.listener = listener;
+    }
+    async check() {
+        var _a;
+        try {
+            const res = await this.api.getConnectionState();
+            const data = res.data;
+            if (((_a = data === null || data === void 0 ? void 0 : data.instance) === null || _a === void 0 ? void 0 : _a.state) === "open") {
+                if (this.lastReadyState !== true) {
+                    this.listener.onConnected();
+                    this.lastReadyState = true;
+                }
+                this.stop();
+            }
+            else {
+                if (this.lastReadyState !== false) {
+                    this.listener.onDisconnected();
+                    this.lastReadyState = false;
+                }
+                this.start();
+            }
+        }
+        catch (error) {
+            this.listener.onAuthFailure(error);
+            this.lastReadyState = false;
+        }
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.check();
+        }, constants_1.CONNECTION_POLL_INTERVAL_MS);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+}
+exports.ConnectionPollingService = ConnectionPollingService;

package/build/application/message-buffer/message-buffer.service.d.ts

@@ -0,0 +1,11 @@
+import { EventEmitter } from "node:events";
+import { ParsedMessage } from "../../domain/interfaces";
+import { MessageMergeConfig } from "../../domain/types";
+export declare class MessageBufferService extends EventEmitter {
+    private readonly config;
+    private buffers;
+    constructor(config: MessageMergeConfig);
+    buffer(data: ParsedMessage, enqueue: (task: () => Promise<void>) => void): void;
+    private calculateTimeout;
+    flush(user: string, enqueue: (task: () => Promise<void>) => void): void;
+}

package/build/application/message-buffer/message-buffer.service.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageBufferService = void 0;
+const node_events_1 = require("node:events");
+class MessageBufferService extends node_events_1.EventEmitter {
+    constructor(config) {
+        super();
+        this.config = config;
+        this.buffers = {};
+    }
+    buffer(data, enqueue) {
+        const user = data.from;
+        const now = Date.now();
+        if (!this.buffers[user]) {
+            this.buffers[user] = {
+                messages: [],
+                messageTimeout: null,
+                maxWaitTimeout: null,
+                lastData: null,
+                lastMessageTime: now,
+                messageCount: 0,
+            };
+        }
+        const buffer = this.buffers[user];
+        buffer.messages.push(data.body);
+        buffer.lastData = data;
+        buffer.messageCount++;
+        const timeBetweenMessages = now - buffer.lastMessageTime;
+        buffer.lastMessageTime = now;
+        if (buffer.messageTimeout) {
+            clearTimeout(buffer.messageTimeout);
+            buffer.messageTimeout = null;
+        }
+        if (buffer.messages.length === 1) {
+            const maxWaitTime = this.config.maxWaitTime || 30;
+            buffer.maxWaitTimeout = setTimeout(() => {
+                this.flush(user, enqueue);
+            }, maxWaitTime * 1000);
+        }
+        const timeout = this.calculateTimeout(data.body, timeBetweenMessages, buffer.messageCount);
+        buffer.messageTimeout = setTimeout(() => {
+            this.flush(user, enqueue);
+        }, timeout);
+    }
+    calculateTimeout(messageText, timeBetweenMessages, messageCount) {
+        var _a;
+        const baseTimeout = (this.config.timeMergeMessage || 3) * 1000;
+        const shortThreshold = this.config.shortMessageThreshold || 10;
+        const adaptiveTimer = (_a = this.config.adaptiveTimer) !== null && _a !== void 0 ? _a : true;
+        let timeout = baseTimeout;
+        if (messageText.length < shortThreshold) {
+            timeout = Math.max(1000, timeout * 0.5);
+        }
+        if (adaptiveTimer) {
+            if (timeBetweenMessages < 2000 && messageCount > 1) {
+                timeout = Math.max(timeout, 4000);
+            }
+            if (messageCount <= 2) {
+                timeout = Math.max(2000, timeout * 0.7);
+            }
+        }
+        return timeout;
+    }
+    flush(user, enqueue) {
+        const buffer = this.buffers[user];
+        if (!buffer || buffer.messages.length === 0)
+            return;
+        if (buffer.messageTimeout)
+            clearTimeout(buffer.messageTimeout);
+        if (buffer.maxWaitTimeout)
+            clearTimeout(buffer.maxWaitTimeout);
+        const fullMessage = buffer.messages.join(" ");
+        enqueue(async () => {
+            this.emit("message", { ...buffer.lastData, body: fullMessage });
+        });
+        delete this.buffers[user];
+    }
+}
+exports.MessageBufferService = MessageBufferService;

package/build/application/messaging/message-sender.service.d.ts

@@ -0,0 +1,40 @@
+import { SendWaveApiRepository } from "../../infrastructure/persistence/sendwave-api.repository";
+import { ReadMessage, SendButton, SendCarousel, SendList, SendLocation, SendMedia, SendMessage, SendPoll, SendPresence, SendReaction } from "../../domain/types";
+import { ProviderInterface } from "../../domain/interfaces";
+export declare class MessageSenderService implements ProviderInterface {
+    private readonly api;
+    private readonly text;
+    private readonly presence;
+    private readonly image;
+    private readonly video;
+    private readonly audio;
+    private readonly file;
+    private readonly voice;
+    private readonly list;
+    private readonly button;
+    private readonly carousel;
+    private readonly poll;
+    private readonly location;
+    private readonly reaction;
+    private readonly readMessagesStrategy;
+    constructor(api: SendWaveApiRepository);
+    dispatch(from: string, text: any, options?: any): Promise<any>;
+    sendMediaByType(data: SendMedia & {
+        text?: string;
+    }): Promise<any>;
+    sendText(data: SendMessage): Promise<any>;
+    sendPresence(data: SendPresence): Promise<any>;
+    sendImage(data: SendMedia): Promise<any>;
+    sendVideo(data: SendMedia): Promise<any>;
+    sendAudio(data: SendMedia): Promise<any>;
+    sendFile(data: SendMedia): Promise<any>;
+    sendVoice(data: SendMedia): Promise<any>;
+    sendList(data: SendList): Promise<any>;
+    sendButton(data: SendButton): Promise<any>;
+    sendCarousel(data: SendCarousel): Promise<any>;
+    sendPoll(data: SendPoll): Promise<any>;
+    sendLocation(data: SendLocation): Promise<any>;
+    sendReaction(data: SendReaction): Promise<any>;
+    sendMedia(data: SendMedia): Promise<any>;
+    readMessages(data: ReadMessage): Promise<any>;
+}