btechworks-sdk 1.0.2 → 1.0.3

package/README.md

@@ -40,146 +40,148 @@ const client = new BTechWorksClient({
 
 ## Methods
 
-### sendMessage
-
-Send a text message to a phone number. Contact and conversation are auto-created.
+### Messaging
 
 ```typescript
-const result = await client.sendMessage({
-  phone: '+1234567890',
-  message: 'Hello World!',
-});
-// { success: true, message: 'Message sent successfully' }
-```
+// Send text message
+await client.sendMessage({ phone: '+1234567890', message: 'Hello!' });
 
-### sendPhoto
+// Send photo
+await client.sendPhoto({ phone: '+1234567890', imageUrl: 'https://example.com/photo.jpg', caption: 'Photo' });
 
-Send an image with an optional caption.
+// Send video
+await client.sendVideo({ phone: '+1234567890', videoUrl: 'https://example.com/video.mp4', caption: 'Video' });
 
-```typescript
-const result = await client.sendPhoto({
-  phone: '+1234567890',
-  imageUrl: 'https://example.com/photo.jpg',
-  caption: 'Check out this photo!',
-});
-// { success: true, message: 'Photo sent successfully' }
+// Send document
+await client.sendDocument({ phone: '+1234567890', documentUrl: 'https://example.com/file.pdf', filename: 'file.pdf' });
 ```
 
-### sendVideo
-
-Send a video with an optional caption.
+### Templates
 
 ```typescript
-const result = await client.sendVideo({
+// Check template variables first
+const check = await client.checkTemplate({ templateName: 'order_confirm' });
+console.log(check.variables); // [{ name: 'name', example: 'John' }]
+
+// Send template
+const result = await client.sendTemplate({
   phone: '+1234567890',
-  videoUrl: 'https://example.com/video.mp4',
-  caption: 'Watch this video!',
+  templateName: 'order_confirm',
+  templateLanguage: 'en_US',
+  templateParams: ['John', 'Order #12345'],
 });
-// { success: true, message: 'Video sent successfully' }
+// { success: true, sent_as: 'template', balance: 99 }
+// OR if 24h window open:
+// { success: true, sent_as: 'text', message: 'Service window open - sent as free text' }
 ```
 
-### sendDocument
-
-Send a document (PDF, DOC, etc.) with an optional caption.
+### Broadcast
 
 ```typescript
-const result = await client.sendDocument({
-  phone: '+1234567890',
-  documentUrl: 'https://example.com/invoice.pdf',
-  filename: 'invoice.pdf',
-  caption: 'Your invoice for this month',
+const result = await client.broadcast({
+  name: 'Summer Sale',
+  templateName: 'summer_offer',
+  templateLanguage: 'en_US',
+  recipients: ['+1234567890', '+0987654321'],
 });
-// { success: true, message: 'Document sent successfully' }
+// { success: true, message: 'Template "summer_offer" processed: 20 sent, 5 failed' }
 ```
 
-### sendTemplate
-
-Send a WhatsApp template message with variables.
+### Wallet
 
 ```typescript
-// Simple template with body variables
-const result = await client.sendTemplate({
-  phone: '+1234567890',
-  templateName: 'order_confirmation',
-  templateLanguage: 'en_US',
-  templateParams: ['John', 'Order #12345'],
+// Check balance
+const balance = await client.getBalance();
+// { success: true, balance: 100, can_send: 100 }
+
+// Estimate cost before sending
+const estimate = await client.estimateCost(50);
+// { success: true, balance: 100, can_send: 100, estimated_templates: 50 }
+
+// Generate payment link (user opens link to pay)
+const link = await client.rechargeViaLink({ 
+  amount: 500, 
+  email: 'user@example.com',
+  phone: '+919999999999'
 });
-// { success: true, message: 'Template sent successfully' }
+// { success: true, link_url: 'https://cashfree.com/pay/...', order_amount: 500 }
+// User opens link_url and pays via Card/UPI
 
-// Template with header media and button params
-const result2 = await client.sendTemplate({
-  phone: '+1234567890',
-  templateName: 'promo_template',
-  templateLanguage: 'en_US',
-  templateMessageParams: {
-    header: { type: 'image', url: 'https://example.com/promo.jpg' },
-    body: ['John', '50%'],
-    buttons: [{ type: 'url', suffix: 'promo50' }],
-  },
-});
+// Get transaction history
+const txns = await client.getTransactions(10, 0);
+// { success: true, transactions: [...] }
 ```
 
-### broadcast
-
-Send a template message to multiple recipients.
+### Analytics
 
 ```typescript
-const result = await client.broadcast({
-  name: 'Summer Sale Campaign',
-  templateName: 'summer_sale',
-  templateLanguage: 'en_US',
-  templateVariables: { code: 'SUMMER50' },
-  recipients: ['+1234567890', '+0987654321', '+1122334455'],
-});
-// { success: true, message: 'Template "summer_sale" processed: 20 sent, 5 failed' }
-
-// Or use audience filter by tags
-const result2 = await client.broadcast({
-  name: 'VIP Customers',
-  templateName: 'vip_offer',
-  recipients: [],
-  audienceFilter: { tags: ['vip', 'premium'] },
-});
-// { success: true, message: 'Template "vip_offer" processed: 50 sent, 10 skipped, 3 failed' }
+const analytics = await client.getAnalytics();
+// {
+//   success: true,
+//   analytics: {
+//     contacts: 1250,
+//     conversations: 890,
+//     messages: { today: 45, this_week: 312, this_month: 1250 },
+//     templates: 15,
+//     recent_broadcasts: [...]
+//   }
+// }
 ```
 
 ## Response Format
 
-All methods return a simple response:
+All methods return a simple response object. **No exceptions are thrown.**
 
 ```typescript
-// Single message
+// Success
 { success: true, message: 'Message sent successfully' }
 
+// Error
+{ success: false, message: 'Invalid phone number format' }
+
+// Template with balance
+{ success: true, sent_as: 'template', balance: 99 }
+
 // Broadcast
 { success: true, message: 'Template "promo" processed: 20 sent, 10 skipped, 5 failed' }
-
-// Error (throws BTechWorksError)
-{ success: false, message: 'Invalid phone number format' }
 ```
 
 ## Error Handling
 
-All methods throw `BTechWorksError` on failure:
+All methods return response objects with `success: false` on error. No try-catch needed:
 
 ```typescript
-import { BTechWorksClient, BTechWorksError } from 'btechworks-sdk';
-
-try {
-  await client.sendMessage({ phone: '+1234567890', message: 'Hello!' });
-} catch (error) {
-  if (error instanceof BTechWorksError) {
-    console.log(error.message);      // Error message
-    console.log(error.statusCode);   // HTTP status code
-  }
+const result = await client.sendMessage({ phone: 'invalid', message: 'Hello!' });
+
+if (result.success) {
+  console.log('Sent!');
+} else {
+  console.log('Failed:', result.message);
 }
 ```
 
-## How It Works
+## Template Flow
+
+1. **Check template** - See what variables are needed
+2. **Send template** - Auto-deducts balance OR sends as free text if 24h window open
+
+```typescript
+// Step 1: Check
+const check = await client.checkTemplate({ templateName: 'welcome' });
+if (!check.ready_to_send) {
+  console.log('Missing variables:', check.variables);
+}
 
-1. **Phone number se sab kuch hota hai** - Contact aur conversation automatically create ho jaate hain
-2. **API key + Secret key se auth hota hai** - Dashboard se API key banao, SDK mein daalo, kaam shuru
-3. **Server sab handle karta hai** - Contact lookup, conversation creation, Meta API calls, message storage
+// Step 2: Send (handles everything automatically)
+const result = await client.sendTemplate({
+  phone: '+1234567890',
+  templateName: 'welcome',
+  templateParams: ['John']
+});
+
+// sent_as: 'text' = Free (24h window open)
+// sent_as: 'template' = Paid (balance deducted)
+```
 
 ## Getting API Keys
 

package/dist/index.d.mts

@@ -60,6 +60,112 @@ interface BroadcastResponse {
     success: boolean;
     message: string;
 }
+interface CheckTemplateOptions {
+    templateName: string;
+    templateLanguage?: string;
+}
+interface TemplateVariable {
+    name: string;
+    example: string;
+    required: boolean;
+}
+interface CheckTemplateResponse {
+    success: boolean;
+    exists?: boolean;
+    template?: {
+        name: string;
+        language: string;
+        status: string;
+    };
+    variables?: TemplateVariable[];
+    ready_to_send?: boolean;
+    message: string;
+}
+interface WalletBalanceResponse {
+    success: boolean;
+    balance?: number;
+    template_rate?: number;
+    is_active?: boolean;
+    message: string;
+}
+interface AddCreditsOptions {
+    amount: number;
+    description?: string;
+}
+interface AddCreditsResponse {
+    success: boolean;
+    balance?: number;
+    message: string;
+}
+interface Transaction {
+    type: 'credit' | 'debit' | 'refund';
+    amount: number;
+    balance_after: number;
+    description: string;
+    created_at: string;
+}
+interface TransactionsResponse {
+    success: boolean;
+    transactions?: Transaction[];
+    message: string;
+}
+interface SendTemplateResponse {
+    success: boolean;
+    sent_as?: 'text' | 'template';
+    balance?: number;
+    message: string;
+}
+interface RechargeOptions {
+    amount: number;
+    email?: string;
+    phone?: string;
+}
+interface RechargeResponse {
+    success: boolean;
+    order_id?: string;
+    payment_session_id?: string;
+    order_amount?: number;
+    message: string;
+}
+interface RechargeViaLinkResponse {
+    success: boolean;
+    link_id?: string;
+    link_url?: string;
+    link_status?: string;
+    order_amount?: number;
+    message: string;
+}
+interface EstimateCostResponse {
+    success: boolean;
+    balance?: number;
+    template_rate?: number;
+    can_send?: number;
+    estimated_templates?: number;
+    message: string;
+}
+interface Broadcast {
+    name: string;
+    status: string;
+    sent_count: number;
+    failed_count: number;
+    created_at: string;
+}
+interface Analytics {
+    contacts: number;
+    conversations: number;
+    messages: {
+        today: number;
+        this_week: number;
+        this_month: number;
+    };
+    templates: number;
+    recent_broadcasts: Broadcast[];
+}
+interface AnalyticsResponse {
+    success: boolean;
+    analytics?: Analytics;
+    message: string;
+}
 
 declare class BTechWorksClient {
     private apiKey;
@@ -68,12 +174,20 @@ declare class BTechWorksClient {
     private timeout;
     constructor(config: BTechWorksConfig);
     private request;
+    getAnalytics(): Promise<AnalyticsResponse>;
+    checkTemplate(options: CheckTemplateOptions): Promise<CheckTemplateResponse>;
     sendMessage(options: SendMessageOptions): Promise<ApiResponse>;
     sendPhoto(options: SendPhotoOptions): Promise<ApiResponse>;
     sendVideo(options: SendVideoOptions): Promise<ApiResponse>;
     sendDocument(options: SendDocumentOptions): Promise<ApiResponse>;
-    sendTemplate(options: SendTemplateOptions): Promise<ApiResponse>;
+    sendTemplate(options: SendTemplateOptions): Promise<SendTemplateResponse>;
     broadcast(options: BroadcastOptions): Promise<BroadcastResponse>;
+    getBalance(): Promise<WalletBalanceResponse>;
+    estimateCost(count?: number): Promise<EstimateCostResponse>;
+    addCredits(options: AddCreditsOptions): Promise<AddCreditsResponse>;
+    recharge(options: RechargeOptions): Promise<RechargeResponse>;
+    rechargeViaLink(options: RechargeOptions): Promise<RechargeViaLinkResponse>;
+    getTransactions(limit?: number, offset?: number): Promise<TransactionsResponse>;
 }
 
-export { type ApiResponse, BTechWorksClient, type BTechWorksConfig, type BroadcastOptions, type BroadcastResponse, type SendDocumentOptions, type SendMessageOptions, type SendPhotoOptions, type SendTemplateOptions, type SendVideoOptions };
+export { type AddCreditsOptions, type AddCreditsResponse, type ApiResponse, BTechWorksClient, type BTechWorksConfig, type BroadcastOptions, type BroadcastResponse, type CheckTemplateOptions, type CheckTemplateResponse, type SendDocumentOptions, type SendMessageOptions, type SendPhotoOptions, type SendTemplateOptions, type SendTemplateResponse, type SendVideoOptions, type TemplateVariable, type Transaction, type TransactionsResponse, type WalletBalanceResponse };

package/dist/index.d.ts

@@ -60,6 +60,112 @@ interface BroadcastResponse {
     success: boolean;
     message: string;
 }
+interface CheckTemplateOptions {
+    templateName: string;
+    templateLanguage?: string;
+}
+interface TemplateVariable {
+    name: string;
+    example: string;
+    required: boolean;
+}
+interface CheckTemplateResponse {
+    success: boolean;
+    exists?: boolean;
+    template?: {
+        name: string;
+        language: string;
+        status: string;
+    };
+    variables?: TemplateVariable[];
+    ready_to_send?: boolean;
+    message: string;
+}
+interface WalletBalanceResponse {
+    success: boolean;
+    balance?: number;
+    template_rate?: number;
+    is_active?: boolean;
+    message: string;
+}
+interface AddCreditsOptions {
+    amount: number;
+    description?: string;
+}
+interface AddCreditsResponse {
+    success: boolean;
+    balance?: number;
+    message: string;
+}
+interface Transaction {
+    type: 'credit' | 'debit' | 'refund';
+    amount: number;
+    balance_after: number;
+    description: string;
+    created_at: string;
+}
+interface TransactionsResponse {
+    success: boolean;
+    transactions?: Transaction[];
+    message: string;
+}
+interface SendTemplateResponse {
+    success: boolean;
+    sent_as?: 'text' | 'template';
+    balance?: number;
+    message: string;
+}
+interface RechargeOptions {
+    amount: number;
+    email?: string;
+    phone?: string;
+}
+interface RechargeResponse {
+    success: boolean;
+    order_id?: string;
+    payment_session_id?: string;
+    order_amount?: number;
+    message: string;
+}
+interface RechargeViaLinkResponse {
+    success: boolean;
+    link_id?: string;
+    link_url?: string;
+    link_status?: string;
+    order_amount?: number;
+    message: string;
+}
+interface EstimateCostResponse {
+    success: boolean;
+    balance?: number;
+    template_rate?: number;
+    can_send?: number;
+    estimated_templates?: number;
+    message: string;
+}
+interface Broadcast {
+    name: string;
+    status: string;
+    sent_count: number;
+    failed_count: number;
+    created_at: string;
+}
+interface Analytics {
+    contacts: number;
+    conversations: number;
+    messages: {
+        today: number;
+        this_week: number;
+        this_month: number;
+    };
+    templates: number;
+    recent_broadcasts: Broadcast[];
+}
+interface AnalyticsResponse {
+    success: boolean;
+    analytics?: Analytics;
+    message: string;
+}
 
 declare class BTechWorksClient {
     private apiKey;
@@ -68,12 +174,20 @@ declare class BTechWorksClient {
     private timeout;
     constructor(config: BTechWorksConfig);
     private request;
+    getAnalytics(): Promise<AnalyticsResponse>;
+    checkTemplate(options: CheckTemplateOptions): Promise<CheckTemplateResponse>;
     sendMessage(options: SendMessageOptions): Promise<ApiResponse>;
     sendPhoto(options: SendPhotoOptions): Promise<ApiResponse>;
     sendVideo(options: SendVideoOptions): Promise<ApiResponse>;
     sendDocument(options: SendDocumentOptions): Promise<ApiResponse>;
-    sendTemplate(options: SendTemplateOptions): Promise<ApiResponse>;
+    sendTemplate(options: SendTemplateOptions): Promise<SendTemplateResponse>;
     broadcast(options: BroadcastOptions): Promise<BroadcastResponse>;
+    getBalance(): Promise<WalletBalanceResponse>;
+    estimateCost(count?: number): Promise<EstimateCostResponse>;
+    addCredits(options: AddCreditsOptions): Promise<AddCreditsResponse>;
+    recharge(options: RechargeOptions): Promise<RechargeResponse>;
+    rechargeViaLink(options: RechargeOptions): Promise<RechargeViaLinkResponse>;
+    getTransactions(limit?: number, offset?: number): Promise<TransactionsResponse>;
 }
 
-export { type ApiResponse, BTechWorksClient, type BTechWorksConfig, type BroadcastOptions, type BroadcastResponse, type SendDocumentOptions, type SendMessageOptions, type SendPhotoOptions, type SendTemplateOptions, type SendVideoOptions };
+export { type AddCreditsOptions, type AddCreditsResponse, type ApiResponse, BTechWorksClient, type BTechWorksConfig, type BroadcastOptions, type BroadcastResponse, type CheckTemplateOptions, type CheckTemplateResponse, type SendDocumentOptions, type SendMessageOptions, type SendPhotoOptions, type SendTemplateOptions, type SendTemplateResponse, type SendVideoOptions, type TemplateVariable, type Transaction, type TransactionsResponse, type WalletBalanceResponse };

package/dist/index.js

@@ -38,6 +38,7 @@ var BTechWorksClient = class {
     this.baseUrl = (config.baseUrl || "https://api.btechworks.io").replace(/\/+$/, "");
     this.timeout = config.timeout || 3e4;
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -74,6 +75,20 @@ var BTechWorksClient = class {
       clearTimeout(timeoutId);
     }
   }
+  async getAnalytics() {
+    return this.request("/api/sdk/analytics", {
+      method: "GET"
+    });
+  }
+  async checkTemplate(options) {
+    return this.request("/api/sdk/check-template", {
+      method: "POST",
+      body: JSON.stringify({
+        template_name: options.templateName,
+        template_language: options.templateLanguage
+      })
+    });
+  }
   async sendMessage(options) {
     return this.request("/api/sdk/send-message", {
       method: "POST",
@@ -139,6 +154,55 @@ var BTechWorksClient = class {
       })
     });
   }
+  async getBalance() {
+    return this.request("/api/sdk/wallet/balance", {
+      method: "GET"
+    });
+  }
+  async estimateCost(count = 1) {
+    return this.request(`/api/sdk/wallet/balance?count=${count}`, {
+      method: "GET"
+    });
+  }
+  async addCredits(options) {
+    return this.request("/api/sdk/wallet/add-credits", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        description: options.description
+      })
+    });
+  }
+  async recharge(options) {
+    return this.request("/api/sdk/wallet/recharge", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        email: options.email,
+        phone: options.phone
+      })
+    });
+  }
+  async rechargeViaLink(options) {
+    return this.request("/api/sdk/wallet/recharge-via-link", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        email: options.email,
+        phone: options.phone
+      })
+    });
+  }
+  async getTransactions(limit, offset) {
+    const params = new URLSearchParams();
+    if (limit) params.set("limit", limit.toString());
+    if (offset) params.set("offset", offset.toString());
+    const query = params.toString();
+    const path = `/api/sdk/wallet/transactions${query ? `?${query}` : ""}`;
+    return this.request(path, {
+      method: "GET"
+    });
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -12,6 +12,7 @@ var BTechWorksClient = class {
     this.baseUrl = (config.baseUrl || "https://api.btechworks.io").replace(/\/+$/, "");
     this.timeout = config.timeout || 3e4;
   }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async request(path, options = {}) {
     const url = `${this.baseUrl}${path}`;
     const headers = {
@@ -48,6 +49,20 @@ var BTechWorksClient = class {
       clearTimeout(timeoutId);
     }
   }
+  async getAnalytics() {
+    return this.request("/api/sdk/analytics", {
+      method: "GET"
+    });
+  }
+  async checkTemplate(options) {
+    return this.request("/api/sdk/check-template", {
+      method: "POST",
+      body: JSON.stringify({
+        template_name: options.templateName,
+        template_language: options.templateLanguage
+      })
+    });
+  }
   async sendMessage(options) {
     return this.request("/api/sdk/send-message", {
       method: "POST",
@@ -113,6 +128,55 @@ var BTechWorksClient = class {
       })
     });
   }
+  async getBalance() {
+    return this.request("/api/sdk/wallet/balance", {
+      method: "GET"
+    });
+  }
+  async estimateCost(count = 1) {
+    return this.request(`/api/sdk/wallet/balance?count=${count}`, {
+      method: "GET"
+    });
+  }
+  async addCredits(options) {
+    return this.request("/api/sdk/wallet/add-credits", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        description: options.description
+      })
+    });
+  }
+  async recharge(options) {
+    return this.request("/api/sdk/wallet/recharge", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        email: options.email,
+        phone: options.phone
+      })
+    });
+  }
+  async rechargeViaLink(options) {
+    return this.request("/api/sdk/wallet/recharge-via-link", {
+      method: "POST",
+      body: JSON.stringify({
+        amount: options.amount,
+        email: options.email,
+        phone: options.phone
+      })
+    });
+  }
+  async getTransactions(limit, offset) {
+    const params = new URLSearchParams();
+    if (limit) params.set("limit", limit.toString());
+    if (offset) params.set("offset", offset.toString());
+    const query = params.toString();
+    const path = `/api/sdk/wallet/transactions${query ? `?${query}` : ""}`;
+    return this.request(path, {
+      method: "GET"
+    });
+  }
 };
 export {
   BTechWorksClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "btechworks-sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Official BatchWorks WhatsApp CRM SDK - Send messages, photos, videos, documents, templates, and broadcasts via API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",