botcast-sdk 1.0.4 → 1.0.6

package/README.md

@@ -41,7 +41,36 @@ bun add botcast-sdk
 
 ## Quick Start
 
-### 1. WhatsApp Client
+### 1. Admin & Fleet Management (Create, Manage & Renew Instances)
+
+Use `BotcastAdminClient` with your Master Partner API Key (`bcast_live_...`) to programmatically create and manage customer instances:
+
+```typescript
+import { BotcastAdminClient } from 'botcast-sdk';
+
+const admin = new BotcastAdminClient({
+  baseUrl: 'https://botcast.site',
+  apiKey: process.env.BOTCAST_API_KEY!, // Master API Key
+});
+
+// List all instances
+const { instances } = await admin.listInstances();
+
+// Create a new WhatsApp or Telegram instance for a customer
+const { instance } = await admin.createInstance({
+  name: 'Customer Store 1',
+  platform: 'whatsapp',
+  type: 'paid',
+  plan_months: 12,
+});
+
+// Renew subscription
+await admin.renewInstance(instance.id, { months: 12 });
+```
+
+---
+
+### 2. WhatsApp Client
 
 ```typescript
 import { BotcastClient } from 'botcast-sdk';

package/dist/admin.cjs

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BotcastAdminClient = void 0;
+const errors_js_1 = require("./errors.js");
+class BotcastAdminClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    headers;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('BotcastAdminClient requires a valid "apiKey" (e.g. bcast_live_...)');
+        }
+        this.baseUrl = (config.baseUrl || 'https://botcast.site').replace(/\/+$/, '');
+        this.apiKey = config.apiKey.trim();
+        this.timeout = config.timeout || 30000;
+        this.headers = config.headers || {};
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const mergedHeaders = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            ...this.headers,
+            ...(options.headers || {}),
+        };
+        try {
+            const res = await fetch(url, {
+                ...options,
+                headers: mergedHeaders,
+                signal: controller.signal,
+            });
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new errors_js_1.BotcastError(body.message || body.error || `HTTP ${res.status}: ${res.statusText}`, res.status, body);
+            }
+            return body;
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                throw new errors_js_1.BotcastError(`Request timed out after ${this.timeout}ms`, 408);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Lists all instances under this admin/partner account with live statuses and stats.
+     */
+    async listInstances() {
+        return this.request('/api/instances', { method: 'GET' });
+    }
+    /**
+     * Retrieves single instance details including QR code, pairing code, status, and expiry.
+     */
+    async getInstance(instanceId) {
+        return this.request(`/api/instances/${instanceId}`, { method: 'GET' });
+    }
+    /**
+     * Creates and immediately provisions a new WhatsApp or Telegram instance.
+     * Admins are zero-payment, so instances are provisioned as active paid instances.
+     */
+    async createInstance(options) {
+        return this.request('/api/instances', {
+            method: 'POST',
+            body: JSON.stringify({
+                name: options.name,
+                platform: options.platform || 'whatsapp',
+                type: options.type || 'paid',
+                plan_months: options.plan_months || 12,
+                allowed_numbers: options.allowed_numbers || [],
+                webhook_url: options.webhook_url || '',
+                target_user_id: options.target_user_id,
+            }),
+        });
+    }
+    /**
+     * Programmatically renews an instance's subscription without payment transactions.
+     */
+    async renewInstance(instanceId, options) {
+        return this.request(`/api/instances/${instanceId}/renew`, {
+            method: 'POST',
+            body: JSON.stringify({
+                months: options?.months || options?.plan_months || 12,
+            }),
+        });
+    }
+    /**
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     */
+    async updateInstance(instanceId, updates) {
+        return this.request(`/api/instances/${instanceId}`, {
+            method: 'PUT',
+            body: JSON.stringify(updates),
+        });
+    }
+    /**
+     * Regenerates secret instance token for an instance.
+     */
+    async regenerateInstanceToken(instanceId) {
+        return this.request(`/api/instances/${instanceId}/regenerate-token`, {
+            method: 'POST',
+        });
+    }
+    /**
+     * Deletes and cleans up an instance.
+     */
+    async deleteInstance(instanceId) {
+        return this.request(`/api/instances/${instanceId}`, {
+            method: 'DELETE',
+        });
+    }
+}
+exports.BotcastAdminClient = BotcastAdminClient;

package/dist/admin.d.ts

@@ -0,0 +1,97 @@
+export interface BotcastAdminConfig {
+    baseUrl?: string;
+    apiKey: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+export interface CreateAdminInstanceOptions {
+    name: string;
+    platform?: 'whatsapp' | 'telegram';
+    type?: 'dev' | 'paid';
+    plan_months?: number;
+    allowed_numbers?: string[];
+    webhook_url?: string;
+    target_user_id?: number;
+}
+export interface AdminInstanceRecord {
+    id: string;
+    user_id: number;
+    name: string;
+    instance_token: string;
+    platform: 'whatsapp' | 'telegram';
+    type: 'dev' | 'paid';
+    status: string;
+    allowed_numbers: string[];
+    webhook_url: string | null;
+    plan_months: number;
+    expires_at: string | null;
+    is_expired?: boolean;
+    qr?: string | null;
+    pairingCode?: string | null;
+    created_at: string;
+}
+export declare class BotcastAdminClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private headers;
+    constructor(config: BotcastAdminConfig);
+    private request;
+    /**
+     * Lists all instances under this admin/partner account with live statuses and stats.
+     */
+    listInstances(): Promise<{
+        instances: AdminInstanceRecord[];
+    }>;
+    /**
+     * Retrieves single instance details including QR code, pairing code, status, and expiry.
+     */
+    getInstance(instanceId: string): Promise<{
+        instance: AdminInstanceRecord;
+    }>;
+    /**
+     * Creates and immediately provisions a new WhatsApp or Telegram instance.
+     * Admins are zero-payment, so instances are provisioned as active paid instances.
+     */
+    createInstance(options: CreateAdminInstanceOptions): Promise<{
+        message: string;
+        instance: AdminInstanceRecord;
+    }>;
+    /**
+     * Programmatically renews an instance's subscription without payment transactions.
+     */
+    renewInstance(instanceId: string, options?: {
+        months?: number;
+        plan_months?: number;
+    }): Promise<{
+        success: boolean;
+        message: string;
+        instance: AdminInstanceRecord;
+    }>;
+    /**
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     */
+    updateInstance(instanceId: string, updates: {
+        name?: string;
+        webhook_url?: string;
+        allowed_numbers?: string[];
+    }): Promise<{
+        message: string;
+        instance: AdminInstanceRecord;
+    }>;
+    /**
+     * Regenerates secret instance token for an instance.
+     */
+    regenerateInstanceToken(instanceId: string): Promise<{
+        message: string;
+        instance_token: string;
+    }>;
+    /**
+     * Deletes and cleans up an instance.
+     */
+    deleteInstance(instanceId: string): Promise<{
+        message: string;
+        instanceId: string;
+    }>;
+}
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

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

package/dist/admin.js

@@ -0,0 +1,114 @@
+import { BotcastError } from './errors.js';
+export class BotcastAdminClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    headers;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error('BotcastAdminClient requires a valid "apiKey" (e.g. bcast_live_...)');
+        }
+        this.baseUrl = (config.baseUrl || 'https://botcast.site').replace(/\/+$/, '');
+        this.apiKey = config.apiKey.trim();
+        this.timeout = config.timeout || 30000;
+        this.headers = config.headers || {};
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const mergedHeaders = {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            ...this.headers,
+            ...(options.headers || {}),
+        };
+        try {
+            const res = await fetch(url, {
+                ...options,
+                headers: mergedHeaders,
+                signal: controller.signal,
+            });
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new BotcastError(body.message || body.error || `HTTP ${res.status}: ${res.statusText}`, res.status, body);
+            }
+            return body;
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                throw new BotcastError(`Request timed out after ${this.timeout}ms`, 408);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Lists all instances under this admin/partner account with live statuses and stats.
+     */
+    async listInstances() {
+        return this.request('/api/instances', { method: 'GET' });
+    }
+    /**
+     * Retrieves single instance details including QR code, pairing code, status, and expiry.
+     */
+    async getInstance(instanceId) {
+        return this.request(`/api/instances/${instanceId}`, { method: 'GET' });
+    }
+    /**
+     * Creates and immediately provisions a new WhatsApp or Telegram instance.
+     * Admins are zero-payment, so instances are provisioned as active paid instances.
+     */
+    async createInstance(options) {
+        return this.request('/api/instances', {
+            method: 'POST',
+            body: JSON.stringify({
+                name: options.name,
+                platform: options.platform || 'whatsapp',
+                type: options.type || 'paid',
+                plan_months: options.plan_months || 12,
+                allowed_numbers: options.allowed_numbers || [],
+                webhook_url: options.webhook_url || '',
+                target_user_id: options.target_user_id,
+            }),
+        });
+    }
+    /**
+     * Programmatically renews an instance's subscription without payment transactions.
+     */
+    async renewInstance(instanceId, options) {
+        return this.request(`/api/instances/${instanceId}/renew`, {
+            method: 'POST',
+            body: JSON.stringify({
+                months: options?.months || options?.plan_months || 12,
+            }),
+        });
+    }
+    /**
+     * Updates instance configuration (name, webhook URL, allowed recipient numbers).
+     */
+    async updateInstance(instanceId, updates) {
+        return this.request(`/api/instances/${instanceId}`, {
+            method: 'PUT',
+            body: JSON.stringify(updates),
+        });
+    }
+    /**
+     * Regenerates secret instance token for an instance.
+     */
+    async regenerateInstanceToken(instanceId) {
+        return this.request(`/api/instances/${instanceId}/regenerate-token`, {
+            method: 'POST',
+        });
+    }
+    /**
+     * Deletes and cleans up an instance.
+     */
+    async deleteInstance(instanceId) {
+        return this.request(`/api/instances/${instanceId}`, {
+            method: 'DELETE',
+        });
+    }
+}

package/dist/index.cjs

@@ -14,9 +14,11 @@ 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.BotcastClient = void 0;
+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; } });
 __exportStar(require("./errors.js"), exports);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { BotcastClient } from './client.js';
+export { BotcastAdminClient, BotcastAdminConfig, CreateAdminInstanceOptions, AdminInstanceRecord } from './admin.js';
 export { BotcastWebhook } from './webhooks/index.js';
 export * from './errors.js';
 export * from './types/index.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,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,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,eAAe,aAAa,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { BotcastClient } from './client.js';
+export { BotcastAdminClient } from './admin.js';
 export { BotcastWebhook } from './webhooks/index.js';
 export * from './errors.js';
 export * from './types/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botcast-sdk",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Official TypeScript/JavaScript SDK for Botcast WhatsApp & Telegram MTProto Multi-Instance API Gateway",
   "type": "module",
   "main": "./dist/index.cjs",