botcast-sdk 1.0.8 → 1.0.9

package/README.md

@@ -273,7 +273,7 @@ await client.messages.delete("201012345678", msgKey);
 await client.messages.markAsRead(msgKey);
 
 // 4. Emoji reaction
-await client.messages.react("201012345678", msgKey, "👍");
+await client.messages.react("201012345678", msgKey, "STAR");
 
 // 5. Pin message
 await client.messages.pin("201012345678", msgKey, 1, 86400);
@@ -286,7 +286,59 @@ await client.messages.forward("201012345678", {
 
 ---
 
-### 4. Chats, Contacts, and History (`client.chats`)
+### 4. Real-Time Socket.io Event Gateway (`client.socket`)
+
+Stream real-time instance events directly with zero latency over **Socket.io**:
+
+```typescript
+import { BotcastClient } from "botcast-sdk";
+
+const client = new BotcastClient({
+  baseUrl: "https://botcast.site",
+  instanceId: "your_instance_id",
+  instanceToken: "your_instance_token",
+  autoConnectSocket: true, // or call client.socket.connect() manually
+});
+
+// 1. Listen for new incoming/outgoing messages
+client.socket.onMessage((msg) => {
+  console.log("Real-time message:", msg);
+});
+
+// 2. Listen for delivery status & read receipts
+client.socket.onMessageStatus((status) => {
+  console.log("Message status update:", status);
+});
+
+// 3. Listen for emoji reactions
+client.socket.onReaction((reaction) => {
+  console.log("Reaction event:", reaction);
+});
+
+// 4. Listen for deleted/revoked messages
+client.socket.onMessageDeleted((del) => {
+  console.log("Message deleted:", del);
+});
+
+// 5. Listen for user presence (typing, recording, online state)
+client.socket.onPresence((presence) => {
+  console.log("Presence update:", presence);
+});
+
+// 6. Listen for instance connection & QR updates
+client.socket.onConnectionUpdate((conn) => {
+  console.log("Connection state:", conn.status, conn.qr || conn.pairingCode);
+});
+
+// 7. Generic event listener
+client.socket.onEvent((event) => {
+  console.log("Instance event received:", event.event, event);
+});
+```
+
+---
+
+### 5. Chats, Contacts, and History (`client.chats`)
 
 ```typescript
 // 1. List chats / dialogs
@@ -309,7 +361,7 @@ await client.chats.pin("201012345678@s.whatsapp.net");
 
 ---
 
-### 5. Webhook Event Handling
+### 6. Webhook Event Handling
 
 The SDK includes a built-in event dispatcher and middleware for handling inbound webhooks from both WhatsApp and Telegram:
 

package/dist/client.cjs

@@ -8,6 +8,7 @@ const groups_js_1 = require("./modules/groups.js");
 const profile_js_1 = require("./modules/profile.js");
 const broadcast_js_1 = require("./modules/broadcast.js");
 const index_js_1 = require("./webhooks/index.js");
+const index_js_2 = require("./socket/index.js");
 class BotcastClient {
     config;
     /** Instance Lifecycle & Connection Management */
@@ -24,10 +25,13 @@ class BotcastClient {
     broadcast;
     /** Webhook Handler & Middleware */
     webhook;
+    /** Real-Time Socket.io Event Gateway Client */
+    socket;
     /**
      * Initializes a new Botcast API Client.
      *
      * @param config Client configuration options
+     * @param socketOptions Optional Socket.io client overrides
      *
      * @example
      * ```ts
@@ -39,11 +43,16 @@ class BotcastClient {
      *   instanceToken: 'token_xyz789'
      * });
      *
+     * // Listen for real-time events via Socket.io
+     * botcast.socket.onMessage((msg) => {
+     *   console.log('Incoming message:', msg);
+     * });
+     *
      * // Send a text message
      * await botcast.messages.sendText('201000000000', 'Hello from Botcast SDK!');
      * ```
      */
-    constructor(config) {
+    constructor(config, socketOptions) {
         if (!config.instanceId) {
             throw new Error('BotcastClient requires a valid "instanceId"');
         }
@@ -58,6 +67,7 @@ class BotcastClient {
             timeout: config.timeout || 30000,
             maxRetries: config.maxRetries ?? 2,
             headers: config.headers || {},
+            autoConnectSocket: config.autoConnectSocket ?? false,
         };
         this.instances = new instances_js_1.InstancesModule(this.config);
         this.messages = new messages_js_1.MessagesModule(this.config);
@@ -66,6 +76,10 @@ class BotcastClient {
         this.profile = new profile_js_1.ProfileModule(this.config);
         this.broadcast = new broadcast_js_1.BroadcastModule(this.config);
         this.webhook = new index_js_1.BotcastWebhook();
+        this.socket = new index_js_2.BotcastSocketClient(this.config, {
+            autoConnect: config.autoConnectSocket,
+            ...socketOptions,
+        });
     }
     // =========================================================================
     // Top-Level Convenience Shortcuts

package/dist/client.d.ts

@@ -6,6 +6,7 @@ import { GroupsModule } from './modules/groups.js';
 import { ProfileModule } from './modules/profile.js';
 import { BroadcastModule } from './modules/broadcast.js';
 import { BotcastWebhook } from './webhooks/index.js';
+import { BotcastSocketClient, BotcastSocketOptions } from './socket/index.js';
 export declare class BotcastClient {
     private config;
     /** Instance Lifecycle & Connection Management */
@@ -22,10 +23,13 @@ export declare class BotcastClient {
     broadcast: BroadcastModule;
     /** Webhook Handler & Middleware */
     webhook: BotcastWebhook;
+    /** Real-Time Socket.io Event Gateway Client */
+    socket: BotcastSocketClient;
     /**
      * Initializes a new Botcast API Client.
      *
      * @param config Client configuration options
+     * @param socketOptions Optional Socket.io client overrides
      *
      * @example
      * ```ts
@@ -37,11 +41,16 @@ export declare class BotcastClient {
      *   instanceToken: 'token_xyz789'
      * });
      *
+     * // Listen for real-time events via Socket.io
+     * botcast.socket.onMessage((msg) => {
+     *   console.log('Incoming message:', msg);
+     * });
+     *
      * // Send a text message
      * await botcast.messages.sendText('201000000000', 'Hello from Botcast SDK!');
      * ```
      */
-    constructor(config: BotcastClientConfig);
+    constructor(config: BotcastClientConfig, socketOptions?: BotcastSocketOptions);
     /**
      * Shortcut to send a text message.
      */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgC;IAE9C,iDAAiD;IAC1C,SAAS,EAAE,eAAe,CAAC;IAElC,6EAA6E;IACtE,QAAQ,EAAE,cAAc,CAAC;IAEhC,0DAA0D;IACnD,KAAK,EAAE,WAAW,CAAC;IAE1B,iDAAiD;IAC1C,MAAM,EAAE,YAAY,CAAC;IAE5B,0DAA0D;IACnD,OAAO,EAAE,aAAa,CAAC;IAE9B,gDAAgD;IACzC,SAAS,EAAE,eAAe,CAAC;IAElC,mCAAmC;IAC5B,OAAO,EAAE,cAAc,CAAC;IAE/B;;;;;;;;;;;;;;;;;;OAkBG;gBACS,MAAM,EAAE,mBAAmB;IA+BvC;;OAEG;IACU,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIrD;;OAEG;IACU,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAI7G;;OAEG;IACU,SAAS;IAItB;;OAEG;IACU,KAAK;IAIlB;;;;OAIG;IACU,YAAY,CAAC,WAAW,EAAE,MAAM;IAI7C;;;;OAIG;IACU,WAAW,CAAC,WAAW,EAAE,MAAM;CAG7C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9E,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgC;IAE9C,iDAAiD;IAC1C,SAAS,EAAE,eAAe,CAAC;IAElC,6EAA6E;IACtE,QAAQ,EAAE,cAAc,CAAC;IAEhC,0DAA0D;IACnD,KAAK,EAAE,WAAW,CAAC;IAE1B,iDAAiD;IAC1C,MAAM,EAAE,YAAY,CAAC;IAE5B,0DAA0D;IACnD,OAAO,EAAE,aAAa,CAAC;IAE9B,gDAAgD;IACzC,SAAS,EAAE,eAAe,CAAC;IAElC,mCAAmC;IAC5B,OAAO,EAAE,cAAc,CAAC;IAE/B,+CAA+C;IACxC,MAAM,EAAE,mBAAmB,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;gBACS,MAAM,EAAE,mBAAmB,EAAE,aAAa,CAAC,EAAE,oBAAoB;IAoC7E;;OAEG;IACU,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAIrD;;OAEG;IACU,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAI7G;;OAEG;IACU,SAAS;IAItB;;OAEG;IACU,KAAK;IAIlB;;;;OAIG;IACU,YAAY,CAAC,WAAW,EAAE,MAAM;IAI7C;;;;OAIG;IACU,WAAW,CAAC,WAAW,EAAE,MAAM;CAG7C"}

package/dist/client.js

@@ -5,6 +5,7 @@ import { GroupsModule } from './modules/groups.js';
 import { ProfileModule } from './modules/profile.js';
 import { BroadcastModule } from './modules/broadcast.js';
 import { BotcastWebhook } from './webhooks/index.js';
+import { BotcastSocketClient } from './socket/index.js';
 export class BotcastClient {
     config;
     /** Instance Lifecycle & Connection Management */
@@ -21,10 +22,13 @@ export class BotcastClient {
     broadcast;
     /** Webhook Handler & Middleware */
     webhook;
+    /** Real-Time Socket.io Event Gateway Client */
+    socket;
     /**
      * Initializes a new Botcast API Client.
      *
      * @param config Client configuration options
+     * @param socketOptions Optional Socket.io client overrides
      *
      * @example
      * ```ts
@@ -36,11 +40,16 @@ export class BotcastClient {
      *   instanceToken: 'token_xyz789'
      * });
      *
+     * // Listen for real-time events via Socket.io
+     * botcast.socket.onMessage((msg) => {
+     *   console.log('Incoming message:', msg);
+     * });
+     *
      * // Send a text message
      * await botcast.messages.sendText('201000000000', 'Hello from Botcast SDK!');
      * ```
      */
-    constructor(config) {
+    constructor(config, socketOptions) {
         if (!config.instanceId) {
             throw new Error('BotcastClient requires a valid "instanceId"');
         }
@@ -55,6 +64,7 @@ export class BotcastClient {
             timeout: config.timeout || 30000,
             maxRetries: config.maxRetries ?? 2,
             headers: config.headers || {},
+            autoConnectSocket: config.autoConnectSocket ?? false,
         };
         this.instances = new InstancesModule(this.config);
         this.messages = new MessagesModule(this.config);
@@ -63,6 +73,10 @@ export class BotcastClient {
         this.profile = new ProfileModule(this.config);
         this.broadcast = new BroadcastModule(this.config);
         this.webhook = new BotcastWebhook();
+        this.socket = new BotcastSocketClient(this.config, {
+            autoConnect: config.autoConnectSocket,
+            ...socketOptions,
+        });
     }
     // =========================================================================
     // Top-Level Convenience Shortcuts

package/dist/index.cjs

@@ -14,13 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BotcastWebhook = exports.BotcastAdminClient = exports.BotcastClient = void 0;
+exports.BotcastSocketClient = exports.BotcastWebhook = exports.BotcastAdminClient = exports.BotcastClient = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "BotcastClient", { enumerable: true, get: function () { return client_js_1.BotcastClient; } });
 var admin_js_1 = require("./admin.js");
 Object.defineProperty(exports, "BotcastAdminClient", { enumerable: true, get: function () { return admin_js_1.BotcastAdminClient; } });
 var index_js_1 = require("./webhooks/index.js");
 Object.defineProperty(exports, "BotcastWebhook", { enumerable: true, get: function () { return index_js_1.BotcastWebhook; } });
+var index_js_2 = require("./socket/index.js");
+Object.defineProperty(exports, "BotcastSocketClient", { enumerable: true, get: function () { return index_js_2.BotcastSocketClient; } });
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./types/index.js"), exports);
 // Default export

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { BotcastClient } from './client.js';
 export { BotcastAdminClient, BotcastAdminConfig, CreateAdminInstanceOptions, AdminInstanceRecord } from './admin.js';
 export { BotcastWebhook } from './webhooks/index.js';
+export { BotcastSocketClient, BotcastSocketOptions } from './socket/index.js';
 export * from './errors.js';
 export * from './types/index.js';
 import { BotcastClient } from './client.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACrH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,eAAe,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACrH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,eAAe,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { BotcastClient } from './client.js';
 export { BotcastAdminClient } from './admin.js';
 export { BotcastWebhook } from './webhooks/index.js';
+export { BotcastSocketClient } from './socket/index.js';
 export * from './errors.js';
 export * from './types/index.js';
 // Default export

package/dist/socket/index.cjs

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotcastSocketClient = void 0;
+const socket_io_client_1 = require("socket.io-client");
+/**
+ * BotcastSocketClient
+ * Real-time event streaming client powered by Socket.io.
+ * Provides authenticated multi-tenant real-time subscriptions to WhatsApp and Telegram instance events.
+ */
+class BotcastSocketClient {
+    socket = null;
+    config;
+    socketOptions;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.socketOptions = options;
+        if (options.autoConnect) {
+            this.connect();
+        }
+    }
+    /**
+     * Establish the real-time Socket.io connection to the Botcast Gateway.
+     */
+    connect() {
+        if (this.socket && this.socket.connected) {
+            return this.socket;
+        }
+        const { baseUrl, instanceId, instanceToken } = this.config;
+        const cleanBaseUrl = baseUrl.replace(/\/+$/, '');
+        this.socket = (0, socket_io_client_1.io)(cleanBaseUrl, {
+            path: '/socket.io',
+            transports: ['websocket', 'polling'],
+            autoConnect: true,
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 5000,
+            auth: {
+                instanceId,
+                token: instanceToken,
+            },
+            query: {
+                instanceId,
+                token: instanceToken,
+            },
+            extraHeaders: {
+                'x-instance-id': instanceId,
+                'x-instance-token': instanceToken,
+            },
+            ...this.socketOptions,
+        });
+        return this.socket;
+    }
+    /**
+     * Disconnect the active Socket.io connection.
+     */
+    disconnect() {
+        if (this.socket) {
+            this.socket.disconnect();
+        }
+        return this;
+    }
+    /**
+     * Check whether the socket is currently connected.
+     */
+    isConnected() {
+        return Boolean(this.socket && this.socket.connected);
+    }
+    /**
+     * Retrieve the underlying Socket.io-client Socket instance.
+     */
+    getRawSocket() {
+        return this.socket;
+    }
+    /**
+     * Register a typed event listener for instance events.
+     *
+     * @param event The event name
+     * @param handler The event callback function
+     */
+    on(event, handler) {
+        const s = this.ensureSocket();
+        s.on(event, handler);
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     */
+    once(event, handler) {
+        const s = this.ensureSocket();
+        s.once(event, handler);
+        return this;
+    }
+    /**
+     * Remove an event listener.
+     */
+    off(event, handler) {
+        if (this.socket) {
+            if (handler) {
+                this.socket.off(event, handler);
+            }
+            else {
+                this.socket.off(event);
+            }
+        }
+        return this;
+    }
+    /**
+     * Register a wildcard listener for all incoming events.
+     */
+    onAny(handler) {
+        const s = this.ensureSocket();
+        s.onAny(handler);
+        return this;
+    }
+    /**
+     * Remove a wildcard listener.
+     */
+    offAny(handler) {
+        if (this.socket) {
+            this.socket.offAny(handler);
+        }
+        return this;
+    }
+    // =========================================================================
+    // High-Level Convenience Event Listeners
+    // =========================================================================
+    /**
+     * Listen for incoming and outgoing messages (messages.upsert or chat_message).
+     */
+    onMessage(handler) {
+        this.on('messages.upsert', handler);
+        this.on('chat_message', handler);
+        return this;
+    }
+    /**
+     * Listen for message delivery status updates (sent, delivered, read receipts).
+     */
+    onMessageStatus(handler) {
+        return this.on('message_status', handler);
+    }
+    /**
+     * Listen for message reactions (emoji added/removed).
+     */
+    onReaction(handler) {
+        return this.on('message_reaction', handler);
+    }
+    /**
+     * Listen for message revocations/deletions.
+     */
+    onMessageDeleted(handler) {
+        return this.on('message_deleted', handler);
+    }
+    /**
+     * Listen for user presence changes (composing, recording, online, offline).
+     */
+    onPresence(handler) {
+        this.on('presence.update', handler);
+        this.on('presence_update', handler);
+        return this;
+    }
+    /**
+     * Listen for instance connection changes, QR code generation, and pairing codes.
+     */
+    onConnectionUpdate(handler) {
+        this.on('connection.update', handler);
+        this.on('instance_update', handler);
+        return this;
+    }
+    /**
+     * Listen for WhatsApp group participant changes (add, remove, promote, demote).
+     */
+    onGroupParticipants(handler) {
+        return this.on('group-participants.update', handler);
+    }
+    /**
+     * Listen for incoming WhatsApp calls.
+     */
+    onCall(handler) {
+        return this.on('call', handler);
+    }
+    /**
+     * Listen for generic instance event stream.
+     */
+    onEvent(handler) {
+        return this.on('instance_event', handler);
+    }
+    // =========================================================================
+    // Telegram-Specific Event Listeners
+    // =========================================================================
+    /**
+     * Listen for Telegram new messages.
+     */
+    onTelegramMessage(handler) {
+        return this.on('telegram.message', handler);
+    }
+    /**
+     * Listen for Telegram message edits.
+     */
+    onTelegramMessageEdited(handler) {
+        return this.on('telegram.message_edited', handler);
+    }
+    /**
+     * Listen for Telegram message deletions.
+     */
+    onTelegramMessageDeleted(handler) {
+        return this.on('telegram.message_deleted', handler);
+    }
+    /**
+     * Listen for Telegram message read receipts.
+     */
+    onTelegramMessageRead(handler) {
+        return this.on('telegram.message_read', handler);
+    }
+    /**
+     * Listen for Telegram user updates (presence, typing, online status).
+     */
+    onTelegramUserUpdate(handler) {
+        return this.on('telegram.user_update', handler);
+    }
+    /**
+     * Listen for Telegram chat actions (user joined, user left, etc.).
+     */
+    onTelegramChatAction(handler) {
+        return this.on('telegram.chat_action', handler);
+    }
+    /**
+     * Listen for Telegram inline & callback button queries.
+     */
+    onTelegramCallbackQuery(handler) {
+        return this.on('telegram.callback_query', handler);
+    }
+    ensureSocket() {
+        if (!this.socket) {
+            this.connect();
+        }
+        return this.socket;
+    }
+}
+exports.BotcastSocketClient = BotcastSocketClient;

package/dist/socket/index.d.ts

@@ -0,0 +1,126 @@
+import { Socket, ManagerOptions, SocketOptions } from 'socket.io-client';
+import { BotcastSocketEventMap, SocketEventHandler, SocketMessagesUpsertEvent, SocketChatMessageEvent, SocketMessageStatusEvent, SocketMessageReactionEvent, SocketMessageDeletedEvent, SocketPresenceUpdateEvent, SocketInstanceUpdateEvent, SocketGroupParticipantsUpdateEvent, SocketCallEvent, SocketGenericEvent, SocketTelegramMessageEvent, SocketTelegramMessageEditedEvent, SocketTelegramMessageDeletedEvent, SocketTelegramMessageReadEvent, SocketTelegramUserUpdateEvent, SocketTelegramChatActionEvent, SocketTelegramCallbackQueryEvent } from '../types/socket.js';
+import { BotcastClientConfig } from '../types/index.js';
+export interface BotcastSocketOptions extends Partial<ManagerOptions & SocketOptions> {
+    /**
+     * Automatically initiate the socket connection upon client creation.
+     * Default: false
+     */
+    autoConnect?: boolean;
+}
+/**
+ * BotcastSocketClient
+ * Real-time event streaming client powered by Socket.io.
+ * Provides authenticated multi-tenant real-time subscriptions to WhatsApp and Telegram instance events.
+ */
+export declare class BotcastSocketClient {
+    private socket;
+    private config;
+    private socketOptions;
+    constructor(config: Required<BotcastClientConfig>, options?: BotcastSocketOptions);
+    /**
+     * Establish the real-time Socket.io connection to the Botcast Gateway.
+     */
+    connect(): Socket;
+    /**
+     * Disconnect the active Socket.io connection.
+     */
+    disconnect(): this;
+    /**
+     * Check whether the socket is currently connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Retrieve the underlying Socket.io-client Socket instance.
+     */
+    getRawSocket(): Socket | null;
+    /**
+     * Register a typed event listener for instance events.
+     *
+     * @param event The event name
+     * @param handler The event callback function
+     */
+    on<K extends keyof BotcastSocketEventMap>(event: K, handler: SocketEventHandler<BotcastSocketEventMap[K]>): this;
+    /**
+     * Register a one-time event listener.
+     */
+    once<K extends keyof BotcastSocketEventMap>(event: K, handler: SocketEventHandler<BotcastSocketEventMap[K]>): this;
+    /**
+     * Remove an event listener.
+     */
+    off<K extends keyof BotcastSocketEventMap>(event: K, handler?: SocketEventHandler<BotcastSocketEventMap[K]>): this;
+    /**
+     * Register a wildcard listener for all incoming events.
+     */
+    onAny(handler: (event: string, data: any) => void): this;
+    /**
+     * Remove a wildcard listener.
+     */
+    offAny(handler?: (event: string, data: any) => void): this;
+    /**
+     * Listen for incoming and outgoing messages (messages.upsert or chat_message).
+     */
+    onMessage(handler: SocketEventHandler<SocketMessagesUpsertEvent | SocketChatMessageEvent>): this;
+    /**
+     * Listen for message delivery status updates (sent, delivered, read receipts).
+     */
+    onMessageStatus(handler: SocketEventHandler<SocketMessageStatusEvent>): this;
+    /**
+     * Listen for message reactions (emoji added/removed).
+     */
+    onReaction(handler: SocketEventHandler<SocketMessageReactionEvent>): this;
+    /**
+     * Listen for message revocations/deletions.
+     */
+    onMessageDeleted(handler: SocketEventHandler<SocketMessageDeletedEvent>): this;
+    /**
+     * Listen for user presence changes (composing, recording, online, offline).
+     */
+    onPresence(handler: SocketEventHandler<SocketPresenceUpdateEvent>): this;
+    /**
+     * Listen for instance connection changes, QR code generation, and pairing codes.
+     */
+    onConnectionUpdate(handler: SocketEventHandler<SocketInstanceUpdateEvent>): this;
+    /**
+     * Listen for WhatsApp group participant changes (add, remove, promote, demote).
+     */
+    onGroupParticipants(handler: SocketEventHandler<SocketGroupParticipantsUpdateEvent>): this;
+    /**
+     * Listen for incoming WhatsApp calls.
+     */
+    onCall(handler: SocketEventHandler<SocketCallEvent>): this;
+    /**
+     * Listen for generic instance event stream.
+     */
+    onEvent(handler: SocketEventHandler<SocketGenericEvent>): this;
+    /**
+     * Listen for Telegram new messages.
+     */
+    onTelegramMessage(handler: SocketEventHandler<SocketTelegramMessageEvent>): this;
+    /**
+     * Listen for Telegram message edits.
+     */
+    onTelegramMessageEdited(handler: SocketEventHandler<SocketTelegramMessageEditedEvent>): this;
+    /**
+     * Listen for Telegram message deletions.
+     */
+    onTelegramMessageDeleted(handler: SocketEventHandler<SocketTelegramMessageDeletedEvent>): this;
+    /**
+     * Listen for Telegram message read receipts.
+     */
+    onTelegramMessageRead(handler: SocketEventHandler<SocketTelegramMessageReadEvent>): this;
+    /**
+     * Listen for Telegram user updates (presence, typing, online status).
+     */
+    onTelegramUserUpdate(handler: SocketEventHandler<SocketTelegramUserUpdateEvent>): this;
+    /**
+     * Listen for Telegram chat actions (user joined, user left, etc.).
+     */
+    onTelegramChatAction(handler: SocketEventHandler<SocketTelegramChatActionEvent>): this;
+    /**
+     * Listen for Telegram inline & callback button queries.
+     */
+    onTelegramCallbackQuery(handler: SocketEventHandler<SocketTelegramCallbackQueryEvent>): this;
+    private ensureSocket;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/socket/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"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"}

package/dist/socket/index.js

@@ -0,0 +1,236 @@
+import { io } from 'socket.io-client';
+/**
+ * BotcastSocketClient
+ * Real-time event streaming client powered by Socket.io.
+ * Provides authenticated multi-tenant real-time subscriptions to WhatsApp and Telegram instance events.
+ */
+export class BotcastSocketClient {
+    socket = null;
+    config;
+    socketOptions;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.socketOptions = options;
+        if (options.autoConnect) {
+            this.connect();
+        }
+    }
+    /**
+     * Establish the real-time Socket.io connection to the Botcast Gateway.
+     */
+    connect() {
+        if (this.socket && this.socket.connected) {
+            return this.socket;
+        }
+        const { baseUrl, instanceId, instanceToken } = this.config;
+        const cleanBaseUrl = baseUrl.replace(/\/+$/, '');
+        this.socket = io(cleanBaseUrl, {
+            path: '/socket.io',
+            transports: ['websocket', 'polling'],
+            autoConnect: true,
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 5000,
+            auth: {
+                instanceId,
+                token: instanceToken,
+            },
+            query: {
+                instanceId,
+                token: instanceToken,
+            },
+            extraHeaders: {
+                'x-instance-id': instanceId,
+                'x-instance-token': instanceToken,
+            },
+            ...this.socketOptions,
+        });
+        return this.socket;
+    }
+    /**
+     * Disconnect the active Socket.io connection.
+     */
+    disconnect() {
+        if (this.socket) {
+            this.socket.disconnect();
+        }
+        return this;
+    }
+    /**
+     * Check whether the socket is currently connected.
+     */
+    isConnected() {
+        return Boolean(this.socket && this.socket.connected);
+    }
+    /**
+     * Retrieve the underlying Socket.io-client Socket instance.
+     */
+    getRawSocket() {
+        return this.socket;
+    }
+    /**
+     * Register a typed event listener for instance events.
+     *
+     * @param event The event name
+     * @param handler The event callback function
+     */
+    on(event, handler) {
+        const s = this.ensureSocket();
+        s.on(event, handler);
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     */
+    once(event, handler) {
+        const s = this.ensureSocket();
+        s.once(event, handler);
+        return this;
+    }
+    /**
+     * Remove an event listener.
+     */
+    off(event, handler) {
+        if (this.socket) {
+            if (handler) {
+                this.socket.off(event, handler);
+            }
+            else {
+                this.socket.off(event);
+            }
+        }
+        return this;
+    }
+    /**
+     * Register a wildcard listener for all incoming events.
+     */
+    onAny(handler) {
+        const s = this.ensureSocket();
+        s.onAny(handler);
+        return this;
+    }
+    /**
+     * Remove a wildcard listener.
+     */
+    offAny(handler) {
+        if (this.socket) {
+            this.socket.offAny(handler);
+        }
+        return this;
+    }
+    // =========================================================================
+    // High-Level Convenience Event Listeners
+    // =========================================================================
+    /**
+     * Listen for incoming and outgoing messages (messages.upsert or chat_message).
+     */
+    onMessage(handler) {
+        this.on('messages.upsert', handler);
+        this.on('chat_message', handler);
+        return this;
+    }
+    /**
+     * Listen for message delivery status updates (sent, delivered, read receipts).
+     */
+    onMessageStatus(handler) {
+        return this.on('message_status', handler);
+    }
+    /**
+     * Listen for message reactions (emoji added/removed).
+     */
+    onReaction(handler) {
+        return this.on('message_reaction', handler);
+    }
+    /**
+     * Listen for message revocations/deletions.
+     */
+    onMessageDeleted(handler) {
+        return this.on('message_deleted', handler);
+    }
+    /**
+     * Listen for user presence changes (composing, recording, online, offline).
+     */
+    onPresence(handler) {
+        this.on('presence.update', handler);
+        this.on('presence_update', handler);
+        return this;
+    }
+    /**
+     * Listen for instance connection changes, QR code generation, and pairing codes.
+     */
+    onConnectionUpdate(handler) {
+        this.on('connection.update', handler);
+        this.on('instance_update', handler);
+        return this;
+    }
+    /**
+     * Listen for WhatsApp group participant changes (add, remove, promote, demote).
+     */
+    onGroupParticipants(handler) {
+        return this.on('group-participants.update', handler);
+    }
+    /**
+     * Listen for incoming WhatsApp calls.
+     */
+    onCall(handler) {
+        return this.on('call', handler);
+    }
+    /**
+     * Listen for generic instance event stream.
+     */
+    onEvent(handler) {
+        return this.on('instance_event', handler);
+    }
+    // =========================================================================
+    // Telegram-Specific Event Listeners
+    // =========================================================================
+    /**
+     * Listen for Telegram new messages.
+     */
+    onTelegramMessage(handler) {
+        return this.on('telegram.message', handler);
+    }
+    /**
+     * Listen for Telegram message edits.
+     */
+    onTelegramMessageEdited(handler) {
+        return this.on('telegram.message_edited', handler);
+    }
+    /**
+     * Listen for Telegram message deletions.
+     */
+    onTelegramMessageDeleted(handler) {
+        return this.on('telegram.message_deleted', handler);
+    }
+    /**
+     * Listen for Telegram message read receipts.
+     */
+    onTelegramMessageRead(handler) {
+        return this.on('telegram.message_read', handler);
+    }
+    /**
+     * Listen for Telegram user updates (presence, typing, online status).
+     */
+    onTelegramUserUpdate(handler) {
+        return this.on('telegram.user_update', handler);
+    }
+    /**
+     * Listen for Telegram chat actions (user joined, user left, etc.).
+     */
+    onTelegramChatAction(handler) {
+        return this.on('telegram.chat_action', handler);
+    }
+    /**
+     * Listen for Telegram inline & callback button queries.
+     */
+    onTelegramCallbackQuery(handler) {
+        return this.on('telegram.callback_query', handler);
+    }
+    ensureSocket() {
+        if (!this.socket) {
+            this.connect();
+        }
+        return this.socket;
+    }
+}

package/dist/types/index.cjs

@@ -20,3 +20,4 @@ __exportStar(require("./chats.js"), exports);
 __exportStar(require("./groups.js"), exports);
 __exportStar(require("./profile.js"), exports);
 __exportStar(require("./webhooks.js"), exports);
+__exportStar(require("./socket.js"), exports);

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './chats.js';
 export * from './groups.js';
 export * from './profile.js';
 export * from './webhooks.js';
+export * from './socket.js';
 export interface BotcastClientConfig {
     /**
      * The base URL of your Botcast instance or cloud gateway.
@@ -34,5 +35,9 @@ export interface BotcastClientConfig {
      * Custom HTTP headers to include with every request.
      */
     headers?: Record<string, string>;
+    /**
+     * Auto-connect the Socket.io real-time client upon initialization (default: false).
+     */
+    autoConnectSocket?: boolean;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAE9B,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAEnC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B"}

package/dist/types/index.js

@@ -4,3 +4,4 @@ export * from './chats.js';
 export * from './groups.js';
 export * from './profile.js';
 export * from './webhooks.js';
+export * from './socket.js';

package/dist/types/socket.cjs

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Socket.io Real-Time Event Types for Botcast SDK
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/socket.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Socket.io Real-Time Event Types for Botcast SDK
+ */
+export interface SocketAuthenticatedEvent {
+    success: boolean;
+    instanceId: string;
+    instanceName?: string;
+    platform?: string;
+    status?: string;
+    phoneNumber?: string | null;
+    timestamp: string;
+}
+export interface SocketMessagesUpsertEvent {
+    instanceId: string;
+    type: string;
+    messages: any[];
+    timestamp?: number;
+}
+export interface SocketMessagesUpdateEvent {
+    instanceId: string;
+    updates: Array<{
+        key: {
+            remoteJid?: string;
+            fromMe?: boolean;
+            id?: string;
+            participant?: string;
+        };
+        update: {
+            status?: number | string;
+            pollUpdates?: any;
+            [key: string]: any;
+        };
+    }>;
+    timestamp?: number;
+}
+export interface SocketMessageStatusEvent {
+    instanceId: string;
+    key: {
+        remoteJid?: string;
+        fromMe?: boolean;
+        id?: string;
+        participant?: string;
+    };
+    status: number | string;
+    update: Record<string, any>;
+    timestamp?: number;
+}
+export interface SocketMessageReactionEvent {
+    instanceId: string;
+    chatJid: string;
+    messageId: string;
+    emoji: string;
+    senderJid: string;
+    fromMe: boolean;
+    timestamp?: number;
+}
+export interface SocketMessageDeletedEvent {
+    instanceId: string;
+    chatJid: string;
+    messageId: string;
+    timestamp?: number;
+}
+export interface SocketChatMessageEvent {
+    instanceId: string;
+    chatJid?: string;
+    fromMe?: number | boolean;
+    body?: string;
+    messageType?: string;
+    timestamp?: number;
+    id?: string;
+}
+export interface SocketChatsUpsertEvent {
+    instanceId: string;
+    chats: any[];
+    timestamp?: number;
+}
+export interface SocketChatsUpdateEvent {
+    instanceId: string;
+    updates: any[];
+    timestamp?: number;
+}
+export interface SocketChatsDeleteEvent {
+    instanceId: string;
+    deletions: any[];
+    timestamp?: number;
+}
+export interface SocketContactsUpsertEvent {
+    instanceId: string;
+    contacts?: any[];
+    timestamp?: number;
+}
+export interface SocketContactsUpdateEvent {
+    instanceId: string;
+    updates?: any[];
+    timestamp?: number;
+}
+export interface SocketPresenceUpdateEvent {
+    instanceId: string;
+    id?: string;
+    presences?: Record<string, {
+        lastKnownPresence?: string;
+        lastSeen?: number;
+    }>;
+    presence?: any;
+    timestamp?: number;
+}
+export interface SocketGroupParticipantsUpdateEvent {
+    instanceId: string;
+    update: {
+        id: string;
+        author?: string;
+        participants: string[];
+        action: "add" | "remove" | "promote" | "demote";
+    };
+    timestamp?: number;
+}
+export interface SocketGroupsUpdateEvent {
+    instanceId: string;
+    updates: any[];
+    timestamp?: number;
+}
+export interface SocketInstanceUpdateEvent {
+    instanceId: string;
+    status?: "disconnected" | "connecting" | "qr_ready" | "connected" | "stopped";
+    qr?: string | null;
+    pairingCode?: string | null;
+    phoneNumber?: string | null;
+    profileName?: string | null;
+    profilePicUrl?: string | null;
+    profileBio?: string | null;
+    expired?: boolean;
+    expires_at?: string | null;
+    timestamp?: number;
+}
+export interface SocketCallEvent {
+    instanceId: string;
+    calls: any[];
+    timestamp?: number;
+}
+export interface SocketPollUpdateEvent {
+    instanceId: string;
+    key: any;
+    pollUpdates: any;
+    timestamp?: number;
+}
+export interface SocketGenericEvent {
+    instanceId: string;
+    event: string;
+    timestamp: number;
+    [key: string]: any;
+}
+export interface SocketTelegramMessageEvent {
+    instanceId: string;
+    messageId: number | string;
+    chatId: string;
+    senderId: string;
+    text: string;
+    fromMe: boolean;
+    timestamp: number;
+}
+export interface SocketTelegramMessageEditedEvent {
+    instanceId: string;
+    messageId: number | string;
+    chatId: string;
+    text: string;
+}
+export interface SocketTelegramMessageDeletedEvent {
+    instanceId: string;
+    deletedIds: Array<number | string>;
+}
+export interface SocketTelegramMessageReadEvent {
+    instanceId: string;
+    chatId: string;
+    maxId?: string | null;
+    out: boolean;
+}
+export interface SocketTelegramUserUpdateEvent {
+    instanceId: string;
+    userId: string;
+    online: boolean;
+    typing: boolean;
+    lastSeen?: any;
+}
+export interface SocketTelegramChatActionEvent {
+    instanceId: string;
+    chatId: string;
+    participants: string[];
+    userJoined: boolean;
+    userLeft: boolean;
+}
+export interface SocketTelegramCallbackQueryEvent {
+    instanceId: string;
+    queryId?: string | null;
+    chatId?: string | null;
+    data?: string | null;
+    senderId?: string | null;
+}
+/**
+ * Event Map for Strong Typing in Socket Listeners
+ */
+export interface BotcastSocketEventMap {
+    authenticated: SocketAuthenticatedEvent;
+    "messages.upsert": SocketMessagesUpsertEvent;
+    "messages.update": SocketMessagesUpdateEvent;
+    "messages.delete": {
+        instanceId: string;
+        item: any;
+        timestamp?: number;
+    };
+    "messages.reaction": {
+        instanceId: string;
+        reactions: any[];
+        timestamp?: number;
+    };
+    message_status: SocketMessageStatusEvent;
+    message_reaction: SocketMessageReactionEvent;
+    message_deleted: SocketMessageDeletedEvent;
+    chat_message: SocketChatMessageEvent;
+    "chats.upsert": SocketChatsUpsertEvent;
+    "chats.update": SocketChatsUpdateEvent;
+    "chats.delete": SocketChatsDeleteEvent;
+    chats_update: {
+        instanceId: string;
+        timestamp?: number;
+    };
+    "contacts.upsert": SocketContactsUpsertEvent;
+    "contacts.update": SocketContactsUpdateEvent;
+    contacts_update: {
+        instanceId: string;
+        timestamp?: number;
+    };
+    "presence.update": SocketPresenceUpdateEvent;
+    presence_update: SocketPresenceUpdateEvent;
+    "group-participants.update": SocketGroupParticipantsUpdateEvent;
+    "groups.update": SocketGroupsUpdateEvent;
+    "connection.update": SocketInstanceUpdateEvent;
+    instance_update: SocketInstanceUpdateEvent;
+    call: SocketCallEvent;
+    poll_update: SocketPollUpdateEvent;
+    instance_event: SocketGenericEvent;
+    "telegram.message": SocketTelegramMessageEvent;
+    "telegram.message_edited": SocketTelegramMessageEditedEvent;
+    "telegram.message_deleted": SocketTelegramMessageDeletedEvent;
+    "telegram.message_read": SocketTelegramMessageReadEvent;
+    "telegram.user_update": SocketTelegramUserUpdateEvent;
+    "telegram.chat_action": SocketTelegramChatActionEvent;
+    "telegram.callback_query": SocketTelegramCallbackQueryEvent;
+    connect: void;
+    disconnect: string;
+    connect_error: Error;
+}
+export type SocketEventHandler<T = any> = (data: T) => void | Promise<void>;
+//# sourceMappingURL=socket.d.ts.map

package/dist/types/socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.d.ts","sourceRoot":"","sources":["../../../src/types/socket.ts"],"names":[],"mappings":"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"}

package/dist/types/socket.js

@@ -0,0 +1,4 @@
+/**
+ * Socket.io Real-Time Event Types for Botcast SDK
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botcast-sdk",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Official TypeScript/JavaScript SDK for Botcast WhatsApp & Telegram MTProto Multi-Instance API Gateway",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -16,6 +16,11 @@
       "types": "./dist/webhooks/index.d.ts",
       "import": "./dist/webhooks/index.js",
       "require": "./dist/webhooks/index.cjs"
+    },
+    "./socket": {
+      "types": "./dist/socket/index.d.ts",
+      "import": "./dist/socket/index.js",
+      "require": "./dist/socket/index.cjs"
     }
   },
   "files": [
@@ -62,5 +67,8 @@
   },
   "devDependencies": {
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.3"
   }
 }