botcast-sdk 1.0.7 → 1.0.9

package/README.md

@@ -62,10 +62,12 @@ const { instance } = await admin.createInstance({
   platform: "whatsapp",
   type: "paid",
   plan_months: 12,
+  expires_at: "2027-12-31T23:59:59.000Z", // Optional exact expiration date
 });
 
-// Renew subscription
+// Renew subscription (by months or exact date)
 await admin.renewInstance(instance.id, { months: 12 });
+// or: await admin.setExpiration(instance.id, "2028-06-30T23:59:59.000Z");
 ```
 
 ---
@@ -271,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);
@@ -284,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
@@ -307,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/admin.cjs

@@ -65,6 +65,12 @@ class BotcastAdminClient {
      * Admins are zero-payment, so instances are provisioned as active paid instances.
      */
     async createInstance(options) {
+        const rawExp = options.expires_at || options.expiresAt;
+        const expires_at = rawExp
+            ? rawExp instanceof Date
+                ? rawExp.toISOString()
+                : new Date(rawExp).toISOString()
+            : undefined;
         return this.request('/api/instances', {
             method: 'POST',
             body: JSON.stringify({
@@ -75,29 +81,60 @@ class BotcastAdminClient {
                 allowed_numbers: options.allowed_numbers || [],
                 webhook_url: options.webhook_url || '',
                 target_user_id: options.target_user_id,
+                expires_at,
             }),
         });
     }
     /**
      * Programmatically renews an instance's subscription without payment transactions.
+     * Supports either extending by months or setting an exact expiration date.
      */
     async renewInstance(instanceId, options) {
+        const rawExp = options?.expires_at || options?.expiresAt;
+        const expires_at = rawExp
+            ? rawExp instanceof Date
+                ? rawExp.toISOString()
+                : new Date(rawExp).toISOString()
+            : undefined;
         return this.request(`/api/instances/${instanceId}/renew`, {
             method: 'POST',
             body: JSON.stringify({
-                months: options?.months || options?.plan_months || 12,
+                months: options?.months || options?.plan_months || (expires_at ? undefined : 12),
+                expires_at,
             }),
         });
     }
     /**
-     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers, expiration date).
      */
     async updateInstance(instanceId, updates) {
+        const rawExp = updates.expires_at !== undefined ? updates.expires_at : updates.expiresAt;
+        let expires_at = undefined;
+        if (rawExp !== undefined) {
+            if (rawExp === null) {
+                expires_at = null;
+            }
+            else {
+                expires_at = rawExp instanceof Date ? rawExp.toISOString() : new Date(rawExp).toISOString();
+            }
+        }
         return this.request(`/api/instances/${instanceId}`, {
             method: 'PUT',
-            body: JSON.stringify(updates),
+            body: JSON.stringify({
+                ...updates,
+                expires_at,
+            }),
         });
     }
+    /**
+     * Directly sets or clears the exact expiration date for an instance.
+     *
+     * @param instanceId Target instance ID (e.g. `ins_paid_...`)
+     * @param expiresAt Date instance, ISO string (e.g. `2027-01-01T00:00:00.000Z`), or `null` to remove expiry.
+     */
+    async setExpiration(instanceId, expiresAt) {
+        return this.updateInstance(instanceId, { expires_at: expiresAt });
+    }
     /**
      * Regenerates secret instance token for an instance.
      */

package/dist/admin.d.ts

@@ -12,6 +12,8 @@ export interface CreateAdminInstanceOptions {
     allowed_numbers?: string[];
     webhook_url?: string;
     target_user_id?: number;
+    expires_at?: string | Date;
+    expiresAt?: string | Date;
 }
 export interface AdminInstanceRecord {
     id: string;
@@ -59,26 +61,41 @@ export declare class BotcastAdminClient {
     }>;
     /**
      * Programmatically renews an instance's subscription without payment transactions.
+     * Supports either extending by months or setting an exact expiration date.
      */
     renewInstance(instanceId: string, options?: {
         months?: number;
         plan_months?: number;
+        expires_at?: string | Date;
+        expiresAt?: string | Date;
     }): Promise<{
         success: boolean;
         message: string;
         instance: AdminInstanceRecord;
     }>;
     /**
-     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers, expiration date).
      */
     updateInstance(instanceId: string, updates: {
         name?: string;
         webhook_url?: string;
         allowed_numbers?: string[];
+        expires_at?: string | Date | null;
+        expiresAt?: string | Date | null;
     }): Promise<{
         message: string;
         instance: AdminInstanceRecord;
     }>;
+    /**
+     * Directly sets or clears the exact expiration date for an instance.
+     *
+     * @param instanceId Target instance ID (e.g. `ins_paid_...`)
+     * @param expiresAt Date instance, ISO string (e.g. `2027-01-01T00:00:00.000Z`), or `null` to remove expiry.
+     */
+    setExpiration(instanceId: string, expiresAt: string | Date | null): Promise<{
+        message: string;
+        instance: AdminInstanceRecord;
+    }>;
     /**
      * Regenerates secret instance token for an instance.
      */

package/dist/admin.d.ts.map

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

package/dist/admin.js

@@ -62,6 +62,12 @@ export class BotcastAdminClient {
      * Admins are zero-payment, so instances are provisioned as active paid instances.
      */
     async createInstance(options) {
+        const rawExp = options.expires_at || options.expiresAt;
+        const expires_at = rawExp
+            ? rawExp instanceof Date
+                ? rawExp.toISOString()
+                : new Date(rawExp).toISOString()
+            : undefined;
         return this.request('/api/instances', {
             method: 'POST',
             body: JSON.stringify({
@@ -72,29 +78,60 @@ export class BotcastAdminClient {
                 allowed_numbers: options.allowed_numbers || [],
                 webhook_url: options.webhook_url || '',
                 target_user_id: options.target_user_id,
+                expires_at,
             }),
         });
     }
     /**
      * Programmatically renews an instance's subscription without payment transactions.
+     * Supports either extending by months or setting an exact expiration date.
      */
     async renewInstance(instanceId, options) {
+        const rawExp = options?.expires_at || options?.expiresAt;
+        const expires_at = rawExp
+            ? rawExp instanceof Date
+                ? rawExp.toISOString()
+                : new Date(rawExp).toISOString()
+            : undefined;
         return this.request(`/api/instances/${instanceId}/renew`, {
             method: 'POST',
             body: JSON.stringify({
-                months: options?.months || options?.plan_months || 12,
+                months: options?.months || options?.plan_months || (expires_at ? undefined : 12),
+                expires_at,
             }),
         });
     }
     /**
-     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers, expiration date).
      */
     async updateInstance(instanceId, updates) {
+        const rawExp = updates.expires_at !== undefined ? updates.expires_at : updates.expiresAt;
+        let expires_at = undefined;
+        if (rawExp !== undefined) {
+            if (rawExp === null) {
+                expires_at = null;
+            }
+            else {
+                expires_at = rawExp instanceof Date ? rawExp.toISOString() : new Date(rawExp).toISOString();
+            }
+        }
         return this.request(`/api/instances/${instanceId}`, {
             method: 'PUT',
-            body: JSON.stringify(updates),
+            body: JSON.stringify({
+                ...updates,
+                expires_at,
+            }),
         });
     }
+    /**
+     * Directly sets or clears the exact expiration date for an instance.
+     *
+     * @param instanceId Target instance ID (e.g. `ins_paid_...`)
+     * @param expiresAt Date instance, ISO string (e.g. `2027-01-01T00:00:00.000Z`), or `null` to remove expiry.
+     */
+    async setExpiration(instanceId, expiresAt) {
+        return this.updateInstance(instanceId, { expires_at: expiresAt });
+    }
     /**
      * Regenerates secret instance token for an instance.
      */

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