botcast-sdk 1.0.6 → 1.0.7

package/README.md

@@ -16,7 +16,7 @@ Official Node.js and TypeScript SDK for [Botcast](https://botcast.site) — a hi
 - **Strict TypeScript Types**: Fully typed request parameters, response models, error classes, and event payloads.
 - **Dual Authentication**:
   - **WhatsApp**: Scan QR code string or request an 8-digit PIN code without a camera.
-  - **Telegram**: Scan QR code via *Telegram > Settings > Devices > Link Desktop Device* or authenticate via phone verification code with optional Cloud 2FA password.
+  - **Telegram**: Scan QR code via _Telegram > Settings > Devices > Link Desktop Device_ or authenticate via phone verification code with optional Cloud 2FA password.
 - **Unified Messaging**: Send text messages, automated OTP codes, images, videos, audio, voice notes (PTT), documents, stickers, locations, contact cards, and interactive polls.
 - **Message Operations**: Edit sent messages, delete for everyone (revoke), mark as read, reactions, pin messages, and forward.
 - **Chat & History Management**: Query dialogs, contact lists, and message history for both platforms.
@@ -46,10 +46,10 @@ bun add botcast-sdk
 Use `BotcastAdminClient` with your Master Partner API Key (`bcast_live_...`) to programmatically create and manage customer instances:
 
 ```typescript
-import { BotcastAdminClient } from 'botcast-sdk';
+import { BotcastAdminClient } from "botcast-sdk";
 
 const admin = new BotcastAdminClient({
-  baseUrl: 'https://botcast.site',
+  baseUrl: "https://botcast.site",
   apiKey: process.env.BOTCAST_API_KEY!, // Master API Key
 });
 
@@ -58,9 +58,9 @@ 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',
+  name: "Customer Store 1",
+  platform: "whatsapp",
+  type: "paid",
   plan_months: 12,
 });
 
@@ -73,30 +73,35 @@ await admin.renewInstance(instance.id, { months: 12 });
 ### 2. WhatsApp Client
 
 ```typescript
-import { BotcastClient } from 'botcast-sdk';
+import { BotcastClient } from "botcast-sdk";
 
 const whatsappBot = new BotcastClient({
-  baseUrl: 'https://botcast.site', // or your self-hosted server URL
-  platform: 'whatsapp',           // 'whatsapp' (default) or 'telegram'
-  instanceId: 'your_instance_id',
-  instanceToken: 'your_instance_token',
+  baseUrl: "https://botcast.site", // or your self-hosted server URL
+  platform: "whatsapp", // 'whatsapp' (default) or 'telegram'
+  instanceId: "your_instance_id",
+  instanceToken: "your_instance_token",
 });
 
 async function main() {
   // Check connectivity
   const status = await whatsappBot.getStatus();
-  console.log(`WhatsApp state: ${status.status} (${status.phoneNumber || 'Unpaired'})`);
+  console.log(
+    `WhatsApp state: ${status.status} (${status.phoneNumber || "Unpaired"})`,
+  );
 
   // Send a text message
-  const res = await whatsappBot.messages.sendText('201012345678', 'Hello from WhatsApp via Botcast SDK!');
-  console.log('Message sent! ID:', res.messageId);
+  const res = await whatsappBot.messages.sendText(
+    "201012345678",
+    "Hello from WhatsApp via Botcast SDK!",
+  );
+  console.log("Message sent! ID:", res.messageId);
 
   // Send a secure 6-digit OTP code
-  const otp = await whatsappBot.messages.sendOTP('201012345678', {
-    appName: 'My App',
+  const otp = await whatsappBot.messages.sendOTP("201012345678", {
+    appName: "My App",
     expiryMinutes: 5,
   });
-  console.log('Dispatched OTP:', otp.codeSent);
+  console.log("Dispatched OTP:", otp.codeSent);
 }
 
 main().catch(console.error);
@@ -107,13 +112,13 @@ main().catch(console.error);
 ### 2. Telegram MTProto Client
 
 ```typescript
-import { BotcastClient } from 'botcast-sdk';
+import { BotcastClient } from "botcast-sdk";
 
 const telegramBot = new BotcastClient({
-  baseUrl: 'https://botcast.site',
-  platform: 'telegram',
-  instanceId: 'your_telegram_instance_id',
-  instanceToken: 'your_telegram_instance_token',
+  baseUrl: "https://botcast.site",
+  platform: "telegram",
+  instanceId: "your_telegram_instance_id",
+  instanceToken: "your_telegram_instance_token",
 });
 
 async function main() {
@@ -122,20 +127,23 @@ async function main() {
   console.log(`Telegram state: ${status.status}`);
 
   // Send a text message to a phone number or @username
-  const res = await telegramBot.messages.sendText('+1234567890', 'Hello from Telegram MTProto!');
-  console.log('Message ID:', res.messageId);
+  const res = await telegramBot.messages.sendText(
+    "+1234567890",
+    "Hello from Telegram MTProto!",
+  );
+  console.log("Message ID:", res.messageId);
 
   // Send a photo
-  await telegramBot.messages.sendImage('+1234567890', {
-    url: 'https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800',
-    caption: 'Welcome flyer',
+  await telegramBot.messages.sendImage("+1234567890", {
+    url: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800",
+    caption: "Welcome flyer",
   });
 
   // Send OTP
-  const otp = await telegramBot.messages.sendOTP('+1234567890', {
-    appName: 'Security Portal',
+  const otp = await telegramBot.messages.sendOTP("+1234567890", {
+    appName: "Security Portal",
   });
-  console.log('Telegram OTP sent:', otp.codeSent);
+  console.log("Telegram OTP sent:", otp.codeSent);
 }
 
 main().catch(console.error);
@@ -146,12 +154,12 @@ main().catch(console.error);
 ### CommonJS (require)
 
 ```javascript
-const { BotcastClient } = require('botcast-sdk');
+const { BotcastClient } = require("botcast-sdk");
 
 const client = new BotcastClient({
-  platform: 'telegram', // or 'whatsapp'
-  instanceId: 'your_instance_id',
-  instanceToken: 'your_instance_token',
+  platform: "telegram", // or 'whatsapp'
+  instanceId: "your_instance_id",
+  instanceToken: "your_instance_token",
 });
 ```
 
@@ -164,24 +172,24 @@ const client = new BotcastClient({
 ```typescript
 // 1. Get live status
 const status = await client.instances.getStatus();
-console.log('State:', status.status); // 'connected' | 'qr_ready' | 'stopped' | 'connecting'
+console.log("State:", status.status); // 'connected' | 'qr_ready' | 'stopped' | 'connecting'
 
 // 2. Option A: Get QR code string for camera scanning
 // (WhatsApp: Linked Devices | Telegram: Settings > Devices > Link Desktop Device)
 const qr = await client.getQR(); // or client.instances.getQR()
-console.log('QR DataURL:', qr.qr);
+console.log("QR DataURL:", qr.qr);
 
 // 3. Option B: Request Phone Pairing / Login Code
 // (WhatsApp sends 8-digit PIN | Telegram sends verification code into app)
-const pair = await client.pairWithCode('+1234567890');
-console.log('Code request status:', pair);
+const pair = await client.pairWithCode("+1234567890");
+console.log("Code request status:", pair);
 
 // 4. Complete Telegram Phone Login (with optional 2FA cloud password)
-await client.instances.verifyCode('+1234567890', '12345', 'myCloudPassword2fa');
+await client.instances.verifyCode("+1234567890", "12345", "myCloudPassword2fa");
 
 // 5. Socket engine controls
-await client.instances.start();  // Boots socket / MTProto connection
-await client.instances.stop();   // Suspends socket session
+await client.instances.start(); // Boots socket / MTProto connection
+await client.instances.stop(); // Suspends socket session
 await client.instances.logout(); // Unlinks device and clears session credentials
 ```
 
@@ -193,51 +201,51 @@ All messaging methods work across both **WhatsApp** and **Telegram**:
 
 ```typescript
 // 1. Text message
-await client.messages.sendText('+1234567890', 'Hello World', {
-  mentions: ['1234567890'], // WhatsApp mentions
+await client.messages.sendText("+1234567890", "Hello World", {
+  mentions: ["1234567890"], // WhatsApp mentions
 });
 
 // 2. Image / Photo
-await client.messages.sendImage('+1234567890', {
-  url: 'https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800',
-  caption: 'Photo preview',
+await client.messages.sendImage("+1234567890", {
+  url: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?w=800",
+  caption: "Photo preview",
 });
 
 // 3. Video
-await client.messages.sendVideo('+1234567890', {
-  url: 'https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4',
-  caption: 'Product tutorial video',
+await client.messages.sendVideo("+1234567890", {
+  url: "https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4",
+  caption: "Product tutorial video",
 });
 
 // 4. Voice note and audio
-await client.messages.sendVoice('+1234567890', {
-  url: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3',
+await client.messages.sendVoice("+1234567890", {
+  url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
 });
 
 // 5. Document / PDF / File
-await client.messages.sendDocument('+1234567890', {
-  url: 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
-  fileName: 'Invoice_2026.pdf',
-  caption: 'Monthly invoice statement',
+await client.messages.sendDocument("+1234567890", {
+  url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
+  fileName: "Invoice_2026.pdf",
+  caption: "Monthly invoice statement",
 });
 
 // 6. Location coordinates
-await client.messages.sendLocation('+1234567890', {
+await client.messages.sendLocation("+1234567890", {
   latitude: 24.7136,
   longitude: 46.6753,
-  name: 'Kingdom Tower',
-  address: 'King Fahd Rd, Riyadh, Saudi Arabia',
+  name: "Kingdom Tower",
+  address: "King Fahd Rd, Riyadh, Saudi Arabia",
 });
 
 // 7. Contact Card
-await client.messages.sendContact('+1234567890', {
-  firstName: 'Support Agent',
-  phone: '+1234567890',
+await client.messages.sendContact("+1234567890", {
+  firstName: "Support Agent",
+  phone: "+1234567890",
 });
 
 // 8. Automated OTP verification code
-const otp = await client.messages.sendOTP('+1234567890', {
-  appName: 'Botcast Portal',
+const otp = await client.messages.sendOTP("+1234567890", {
+  appName: "Botcast Portal",
   expiryMinutes: 5,
 });
 ```
@@ -248,28 +256,30 @@ const otp = await client.messages.sendOTP('+1234567890', {
 
 ```typescript
 const msgKey = {
-  remoteJid: '201012345678@s.whatsapp.net',
+  remoteJid: "201012345678@s.whatsapp.net",
   fromMe: true,
-  id: '3EB0ABCDEF1234567890',
+  id: "3EB0ABCDEF1234567890",
 };
 
 // 1. Edit sent message
-await client.messages.edit('201012345678', msgKey, 'Corrected text content');
+await client.messages.edit("201012345678", msgKey, "Corrected text content");
 
 // 2. Delete message for everyone (revoke)
-await client.messages.delete('201012345678', msgKey);
+await client.messages.delete("201012345678", msgKey);
 
 // 3. Mark message as read
 await client.messages.markAsRead(msgKey);
 
 // 4. Emoji reaction
-await client.messages.react('201012345678', msgKey, '👍');
+await client.messages.react("201012345678", msgKey, "👍");
 
 // 5. Pin message
-await client.messages.pin('201012345678', msgKey, 1, 86400);
+await client.messages.pin("201012345678", msgKey, 1, 86400);
 
 // 6. Forward message
-await client.messages.forward('201012345678', { conversation: 'Forwarded message text' });
+await client.messages.forward("201012345678", {
+  conversation: "Forwarded message text",
+});
 ```
 
 ---
@@ -284,12 +294,15 @@ const { chats } = await client.chats.list({ limit: 50 });
 const { contacts } = await client.chats.listContacts({ limit: 100 });
 
 // 3. List messages for a chat
-const { messages } = await client.chats.listMessages({ chatJid: '201012345678@s.whatsapp.net', limit: 50 });
+const { messages } = await client.chats.listMessages({
+  chatJid: "201012345678@s.whatsapp.net",
+  limit: 50,
+});
 
 // 4. Modify WhatsApp chat state (archive, mute, pin, delete)
-await client.chats.archive('201012345678@s.whatsapp.net');
-await client.chats.mute('201012345678@s.whatsapp.net', 8 * 60 * 60 * 1000); // 8 hours
-await client.chats.pin('201012345678@s.whatsapp.net');
+await client.chats.archive("201012345678@s.whatsapp.net");
+await client.chats.mute("201012345678@s.whatsapp.net", 8 * 60 * 60 * 1000); // 8 hours
+await client.chats.pin("201012345678@s.whatsapp.net");
 ```
 
 ---
@@ -301,24 +314,26 @@ The SDK includes a built-in event dispatcher and middleware for handling inbound
 #### Express Example
 
 ```typescript
-import express from 'express';
-import { BotcastClient } from 'botcast-sdk';
+import express from "express";
+import { BotcastClient } from "botcast-sdk";
 
 const app = express();
 app.use(express.json());
 
 const client = new BotcastClient({
-  platform: 'telegram', // or 'whatsapp'
-  instanceId: 'inst_123',
-  instanceToken: 'tok_abc',
+  platform: "telegram", // or 'whatsapp'
+  instanceId: "inst_123",
+  instanceToken: "tok_abc",
 });
 
 // Listen for incoming messages
 client.webhook.onMessage(async (event) => {
-  console.log(`Message from ${event.sender}: ${event.message} [Platform: ${event.platform || 'whatsapp'}]`);
+  console.log(
+    `Message from ${event.sender}: ${event.message} [Platform: ${event.platform || "whatsapp"}]`,
+  );
 
-  if (event.message.trim().toLowerCase() === 'ping') {
-    await client.messages.sendText(event.sender, 'pong');
+  if (event.message.trim().toLowerCase() === "ping") {
+    await client.messages.sendText(event.sender, "pong");
   }
 });
 
@@ -328,9 +343,9 @@ client.webhook.onConnection(async (event) => {
 });
 
 // Mount middleware on your webhook route
-app.post('/webhook/botcast', client.webhook.middleware());
+app.post("/webhook/botcast", client.webhook.middleware());
 
-app.listen(3000, () => console.log('Webhook server running on port 3000'));
+app.listen(3000, () => console.log("Webhook server running on port 3000"));
 ```
 
 ---
@@ -348,25 +363,25 @@ import {
   BotcastRateLimitError,
   BotcastValidationError,
   BotcastNotFoundError,
-} from 'botcast-sdk';
+} from "botcast-sdk";
 
 try {
-  await client.messages.sendText('+1234567890', 'Hello World');
+  await client.messages.sendText("+1234567890", "Hello World");
 } catch (error) {
   if (error instanceof BotcastAuthError) {
-    console.error('Invalid instance credentials or token.');
+    console.error("Invalid instance credentials or token.");
   } else if (error instanceof BotcastPaymentRequiredError) {
-    console.error('Instance requires payment confirmation.');
+    console.error("Instance requires payment confirmation.");
   } else if (error instanceof BotcastSubscriptionExpiredError) {
-    console.error('Subscription expired on:', error.expiresAt);
+    console.error("Subscription expired on:", error.expiresAt);
   } else if (error instanceof BotcastRateLimitError) {
-    console.error('Daily message limit reached.');
+    console.error("Daily message limit reached.");
   } else if (error instanceof BotcastValidationError) {
-    console.error('Validation error:', error.message, error.details);
+    console.error("Validation error:", error.message, error.details);
   } else if (error instanceof BotcastNotFoundError) {
-    console.error('Resource not found:', error.message);
+    console.error("Resource not found:", error.message);
   } else {
-    console.error('Unexpected error:', error);
+    console.error("Unexpected error:", error);
   }
 }
 ```
@@ -378,7 +393,7 @@ try {
 - Website: [https://botcast.site](https://botcast.site)
 - Documentation: [https://botcast.site/docs](https://botcast.site/docs)
 - NPM Package: [https://www.npmjs.com/package/botcast-sdk](https://www.npmjs.com/package/botcast-sdk)
-- GitHub Repository: [https://github.com/ANOOBALSA/Botcast](https://github.com/ANOOBALSA/Botcast)
+- GitHub Repository: [https://github.com/alsasoft-web/Botcast](https://github.com/alsasoft-web/Botcast)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botcast-sdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Official TypeScript/JavaScript SDK for Botcast WhatsApp & Telegram MTProto Multi-Instance API Gateway",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -51,7 +51,7 @@
   "homepage": "https://botcast.site",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ANOOBALSA/botcast-sdk.git",
+    "url": "git+https://github.com/alsasoft-web/botcast-sdk.git",
     "directory": "packages/botcast-sdk"
   },
   "bugs": {