{"_id":"@benaah/talksasa-sms-client","_rev":"2-5bef9520380525a1d9502a786bb3a104","name":"@benaah/talksasa-sms-client","dist-tags":{"latest":"2.0.0"},"versions":{"1.1.0":{"name":"@benaah/talksasa-sms-client","version":"1.1.0","keywords":["sms","gateway","talksasa","api","client","typescript","javascript","messaging"],"author":{"name":"TalkSASA SMS Client Contributors"},"license":"MIT","_id":"@benaah/talksasa-sms-client@1.1.0","maintainers":[{"name":"benaah","email":"b14.09353.22@gmail.com"}],"homepage":"https://github.com/Benaah/talksasa-sms-client#readme","bugs":{"url":"https://github.com/Benaah/talksasa-sms-client/issues"},"os":["darwin","linux","win32"],"cpu":["x64","arm64"],"dist":{"shasum":"4fa054660b41a663f561736b97a260bd8bf4835d","tarball":"https://registry.npmjs.org/@benaah/talksasa-sms-client/-/talksasa-sms-client-1.1.0.tgz","fileCount":43,"integrity":"sha512-fhVt69PjcRWEjpp1T3DTggGpxttEO3sYJOe56PgXJ0Z50lTdVuDsIvdhluSo6b38QDVgG9gjcKd+jz5P5m6OrQ==","signatures":[{"sig":"MEUCIDC4x2/9QrUNFyxnppHWyydUCEC7gydRJ3MRPe1fSWsnAiEAxJiCmNQQGeQw+rNubymufoFLvoyDMLLvve1nM5zDpsg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":270753},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"npm":">=8.0.0","node":">=18.0.0"},"gitHead":"5d41577bc380379d6040530e8be2342d5af7efd4","scripts":{"dev":"tsc --watch","lint":"eslint src/**/*.ts","test":"jest","build":"tsc","lint:fix":"eslint src/**/*.ts --fix","test:watch":"jest --watch","prepublishOnly":"npm run lint && npm run build","security:audit":"npm audit","security:check":"npm audit && npm run lint","security:update":"npm update","security:audit:fix":"npm audit fix"},"_npmUser":{"name":"benaah","email":"b14.09353.22@gmail.com"},"repository":{"url":"git+https://github.com/Benaah/talksasa-sms-client.git","type":"git"},"_npmVersion":"11.6.1","description":"A comprehensive JavaScript/TypeScript client for the TalkSASA SMS Gateway API","directories":{},"_nodeVersion":"22.20.0","dependencies":{"axios":"^1.12.2"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","eslint":"^9.36.0","ts-jest":"^29.4.4","typescript":"^5.9.3","@types/jest":"^30.0.0","@types/node":"^24.6.2","eslint-plugin-security":"^2.1.0","@typescript-eslint/parser":"^8.45.0","@typescript-eslint/eslint-plugin":"^8.45.0"},"_npmOperationalInternal":{"tmp":"tmp/talksasa-sms-client_1.1.0_1763314479213_0.24525848048120302","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@benaah/talksasa-sms-client","version":"2.0.0","description":"A comprehensive JavaScript/TypeScript client for the TalkSASA SMS Gateway API","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"jest","test:watch":"jest --watch","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","security:audit":"npm audit","security:audit:fix":"npm audit fix","security:check":"npm audit && npm run lint","security:update":"npm update","prepublishOnly":"npm run lint && npm run build"},"keywords":["sms","gateway","talksasa","api","client","typescript","javascript","messaging"],"author":{"name":"TalkSASA SMS Client Contributors"},"license":"MIT","type":"commonjs","engines":{"node":">=18.0.0","npm":">=8.0.0"},"os":["darwin","linux","win32"],"cpu":["x64","arm64"],"repository":{"type":"git","url":"git+https://github.com/Benaah/talksasa-sms-client.git"},"bugs":{"url":"https://github.com/Benaah/talksasa-sms-client/issues"},"homepage":"https://github.com/Benaah/talksasa-sms-client#readme","dependencies":{"axios":"^1.12.2"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^24.6.2","@typescript-eslint/eslint-plugin":"^8.45.0","@typescript-eslint/parser":"^8.45.0","eslint":"^9.36.0","eslint-plugin-security":"^2.1.0","jest":"^30.2.0","ts-jest":"^29.4.4","typescript":"^5.9.3"},"gitHead":"5d41577bc380379d6040530e8be2342d5af7efd4","_id":"@benaah/talksasa-sms-client@2.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-oJSTd+xtc518M47llvpRqrehsk0D+VtPQW19zV8z9WlGR2X5tbNdzmf3eYoYuKcY54MSgNXWALUIrVpMRlmpHg==","shasum":"adf842d2bbd076d68f9437c032befabedace97f9","tarball":"https://registry.npmjs.org/@benaah/talksasa-sms-client/-/talksasa-sms-client-2.0.0.tgz","fileCount":43,"unpackedSize":270858,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFoNJSw0pvh7IfKxsUvrEDj4GRP4mQXasmAWahK1SesgAiEA4yqI/YoMIOzKBclsqD6HWHImW3iObUss7Uv8eFdhK6o="}]},"_npmUser":{"name":"benaah","email":"b14.09353.22@gmail.com"},"directories":{},"maintainers":[{"name":"benaah","email":"b14.09353.22@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/talksasa-sms-client_2.0.0_1763546239751_0.2874705135495439"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-16T17:34:39.121Z","modified":"2025-11-19T09:57:20.157Z","1.1.0":"2025-11-16T17:34:39.396Z","2.0.0":"2025-11-19T09:57:19.957Z"},"bugs":{"url":"https://github.com/Benaah/talksasa-sms-client/issues"},"author":{"name":"TalkSASA SMS Client Contributors"},"license":"MIT","homepage":"https://github.com/Benaah/talksasa-sms-client#readme","keywords":["sms","gateway","talksasa","api","client","typescript","javascript","messaging"],"repository":{"type":"git","url":"git+https://github.com/Benaah/talksasa-sms-client.git"},"description":"A comprehensive JavaScript/TypeScript client for the TalkSASA SMS Gateway API","maintainers":[{"name":"benaah","email":"b14.09353.22@gmail.com"}],"readme":"# TalkSASA SMS Client\r\n\r\nA comprehensive JavaScript/TypeScript client for the TalkSASA SMS Gateway API. This package provides an easy-to-use interface for sending SMS, Voice, MMS, and WhatsApp messages, managing templates, contacts, profiles, and handling delivery reports.\r\n\r\n## Features\r\n\r\n-  **Send SMS** - Send individual and bulk SMS messages\r\n-  **Send Voice** - Send voice messages with language and gender selection\r\n-  **Send MMS** - Send multimedia messages with images\r\n-  **Send WhatsApp** - Send WhatsApp messages\r\n-  **Campaigns** - Send messages to contact lists\r\n-  **Scheduled Messages** - Schedule all message types for future delivery\r\n-  **Template Management** - Create, read, update, and delete SMS templates\r\n-  **Delivery Reports** - Track message delivery status\r\n-  **Account Management** - Check balance and account information\r\n-  **Profile Management** - Get user profile and SMS unit information\r\n-  **Contacts Management** - Create, read, update, and delete contacts\r\n-  **Contact Groups** - Organize contacts into groups\r\n-  **OAuth 2.0 Authentication** - Secure authentication with automatic token refresh\r\n-  **Retry Logic** - Automatic retry with exponential backoff\r\n-  **TypeScript Support** - Full TypeScript definitions included\r\n-  **Input Validation** - Comprehensive validation for all inputs\r\n-  **Error Handling** - Detailed error classes and messages\r\n-  **Logging** - Built-in request/response logging\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install talksasa-sms-client\r\n```\r\n\r\n## Quick Start\r\n\r\n```javascript\r\nconst { TalkSASAClient } = require('talksasa-sms-client');\r\n\r\n// Initialize the client\r\nconst client = new TalkSASAClient({\r\n  apiKey: 'your-api-key-here',\r\n  baseUrl: 'https://bulksms.talksasa.com/api/v3/',\r\n  timeout: 30000, // Optional, defaults to 30 seconds\r\n  retries: 3 // Optional, defaults to 3 retries\r\n});\r\n\r\n// Send different types of messages\r\nasync function sendMessages() {\r\n  try {\r\n    // Send SMS\r\n    const smsResponse = await client.sendSMS({\r\n      recipient: '+1234567890',\r\n      sender_id: 'YourApp',\r\n      type: 'plain',\r\n      message: 'Hello from TalkSASA!'\r\n    });\r\n    console.log('SMS sent:', smsResponse);\r\n\r\n    // Send Voice\r\n    const voiceResponse = await client.sendVoice({\r\n      recipient: '+1234567890',\r\n      sender_id: 'YourApp',\r\n      type: 'voice',\r\n      language: 'en-us',\r\n      gender: 'female',\r\n      message: 'Hello! This is a voice message.'\r\n    });\r\n    console.log('Voice sent:', voiceResponse);\r\n\r\n    // Send MMS\r\n    const mmsResponse = await client.sendMMS({\r\n      recipient: '+1234567890',\r\n      sender_id: 'YourApp',\r\n      type: 'mms',\r\n      media_url: 'https://via.placeholder.com/150.jpg',\r\n      message: 'Check out this image!'\r\n    });\r\n    console.log('MMS sent:', mmsResponse);\r\n\r\n    // Send WhatsApp\r\n    const whatsappResponse = await client.sendWhatsApp({\r\n      recipient: '+1234567890',\r\n      sender_id: 'YourApp',\r\n      type: 'whatsapp',\r\n      message: 'Hello via WhatsApp!'\r\n    });\r\n    console.log('WhatsApp sent:', whatsappResponse);\r\n\r\n  } catch (error) {\r\n    console.error('Failed to send message:', error.message);\r\n  }\r\n}\r\n```\r\n\r\n## TypeScript Usage\r\n\r\n```typescript\r\nimport { TalkSASAClient, SMSMessage, SMSResponse } from 'talksasa-sms-client';\r\n\r\nconst client = new TalkSASAClient({\r\n  apiKey: 'your-api-key-here'\r\n});\r\n\r\nconst message: SMSMessage = {\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Hello from TalkSASA!'\r\n};\r\n\r\nconst response: SMSResponse = await client.sendSMS(message);\r\n```\r\n\r\n## API Reference\r\n\r\n### Constructor\r\n\r\n```javascript\r\nnew TalkSASAClient(config)\r\n```\r\n\r\n**Parameters:**\r\n- `config.apiKey` (string, required): Your TalkSASA API key\r\n- `config.baseUrl` (string, optional): API base URL (default: 'https://bulksms.talksasa.com/api/v3/')\r\n- `config.timeout` (number, optional): Request timeout in milliseconds (default: 30000)\r\n- `config.retries` (number, optional): Number of retry attempts (default: 3)\r\n\r\n### Methods\r\n\r\n#### Send Single SMS\r\n\r\n```javascript\r\nawait client.sendSMS(message)\r\n```\r\n\r\n**Parameters:**\r\n- `message.recipient` (string|string[]): Recipient phone number(s)\r\n- `message.sender_id` (string): Sender ID (max 11 characters)\r\n- `message.type` (string): Message type ('plain' for SMS)\r\n- `message.message` (string): SMS content\r\n- `message.schedule_time` (string, optional): RFC3339 date string for scheduled sending\r\n- `message.dlt_template_id` (string, optional): DLT template ID\r\n\r\n#### Send Campaign SMS\r\n\r\n```javascript\r\nawait client.sendCampaign(campaign)\r\n```\r\n\r\n**Parameters:**\r\n- `campaign.contact_list_id` (string|string[]): Contact list ID(s)\r\n- `campaign.sender_id` (string): Sender ID (max 11 characters)\r\n- `campaign.type` (string): Message type ('plain' for SMS)\r\n- `campaign.message` (string): SMS content\r\n- `campaign.schedule_time` (string, optional): RFC3339 date string for scheduled sending\r\n- `campaign.dlt_template_id` (string, optional): DLT template ID\r\n\r\n#### Send Voice Message\r\n\r\n```javascript\r\nawait client.sendVoice(message)\r\n```\r\n\r\n**Parameters:**\r\n- `message.recipient` (string): Recipient phone number\r\n- `message.sender_id` (string): Sender ID (max 11 characters)\r\n- `message.type` (string): Message type ('voice' for voice messages)\r\n- `message.language` (string): Voice language (e.g., 'en-us', 'en-gb', 'fr-fr')\r\n- `message.gender` (string): Voice gender ('male' or 'female')\r\n- `message.message` (string): Message content to be spoken\r\n- `message.schedule_time` (string, optional): RFC3339 date string for scheduled sending\r\n\r\n#### Send MMS Message\r\n\r\n```javascript\r\nawait client.sendMMS(message)\r\n```\r\n\r\n**Parameters:**\r\n- `message.recipient` (string): Recipient phone number\r\n- `message.sender_id` (string): Sender ID (max 11 characters)\r\n- `message.type` (string): Message type ('mms' for MMS messages)\r\n- `message.media_url` (string): URL of the image to send (supports jpg, jpeg, png, gif, bmp, webp)\r\n- `message.message` (string, optional): Text message to accompany the image\r\n- `message.schedule_time` (string, optional): RFC3339 date string for scheduled sending\r\n\r\n#### Send WhatsApp Message\r\n\r\n```javascript\r\nawait client.sendWhatsApp(message)\r\n```\r\n\r\n**Parameters:**\r\n- `message.recipient` (string): Recipient phone number\r\n- `message.sender_id` (string): Sender ID (max 11 characters)\r\n- `message.type` (string): Message type ('whatsapp' for WhatsApp messages)\r\n- `message.message` (string): Message content to send\r\n- `message.schedule_time` (string, optional): RFC3339 date string for scheduled sending\r\n\r\n#### Get SMS Message\r\n\r\n```javascript\r\nawait client.getSMS(uid)\r\n```\r\n\r\n**Parameters:**\r\n- `uid` (string): SMS UID returned from send operation\r\n\r\n#### Get All SMS Messages\r\n\r\n```javascript\r\nawait client.getAllSMS()\r\n```\r\n\r\n**Returns:** Object with `messages` array and optional `pagination` info\r\n\r\n#### Get User Profile\r\n\r\n```javascript\r\nawait client.getProfile()\r\n```\r\n\r\n**Returns:** User profile information including name, email, status, etc.\r\n\r\n#### Get SMS Units\r\n\r\n```javascript\r\nawait client.getSMSUnits()\r\n```\r\n\r\n**Returns:** SMS unit balance information including total, used, and remaining units\r\n\r\n#### Get Delivery Report\r\n\r\n```javascript\r\nawait client.getDeliveryReport(messageId)\r\n```\r\n\r\n**Parameters:**\r\n- `messageId` (string): Message ID returned from send operation\r\n\r\n#### Account Management\r\n\r\n```javascript\r\n// Get account balance\r\nconst balance = await client.getAccountBalance();\r\n\r\n// Get account information\r\nconst info = await client.getAccountInfo();\r\n```\r\n\r\n#### Template Management\r\n\r\n```javascript\r\n// Create template\r\nconst template = await client.createTemplate({\r\n  name: 'Welcome Message',\r\n  content: 'Welcome {{name}}! Your code is {{code}}.',\r\n  variables: ['name', 'code']\r\n});\r\n\r\n// Get all templates\r\nconst templates = await client.getTemplates();\r\n\r\n// Get specific template\r\nconst template = await client.getTemplate(templateId);\r\n\r\n// Update template\r\nconst updatedTemplate = await client.updateTemplate(templateId, {\r\n  content: 'Updated welcome message for {{name}}!'\r\n});\r\n\r\n// Delete template\r\nawait client.deleteTemplate(templateId);\r\n\r\n// Send SMS using template\r\nconst response = await client.sendTemplateSMS(templateId, '+1234567890', {\r\n  name: 'John',\r\n  code: '12345'\r\n});\r\n```\r\n\r\n## Error Handling\r\n\r\nThe client provides specific error classes for different scenarios:\r\n\r\n```javascript\r\nconst {\r\n  TalkSASAAPIError,\r\n  TalkSASAValidationError,\r\n  TalkSASANetworkError,\r\n  TalkSASAAuthenticationError,\r\n  TalkSASAQuotaExceededError,\r\n  TalkSASAInsufficientBalanceError\r\n} = require('talksasa-sms-client');\r\n\r\ntry {\r\n  await client.sendSMS(message);\r\n} catch (error) {\r\n  if (error instanceof TalkSASAAuthenticationError) {\r\n    console.error('Invalid API key');\r\n  } else if (error instanceof TalkSASAInsufficientBalanceError) {\r\n    console.error('Insufficient account balance');\r\n  } else if (error instanceof TalkSASAValidationError) {\r\n    console.error('Invalid input:', error.message);\r\n  } else if (error instanceof TalkSASANetworkError) {\r\n    console.error('Network error:', error.message);\r\n  } else {\r\n    console.error('API error:', error.message);\r\n  }\r\n}\r\n```\r\n\r\n## Examples\r\n\r\n### Basic SMS Sending\r\n\r\n```javascript\r\nconst { TalkSASAClient } = require('talksasa-sms-client');\r\n\r\nconst client = new TalkSASAClient({\r\n  apiKey: process.env.TALKSASA_API_KEY\r\n});\r\n\r\n// Send to single recipient\r\nawait client.sendSMS({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Hello World!'\r\n});\r\n\r\n// Send to multiple recipients\r\nawait client.sendSMS({\r\n  recipient: ['+1234567890', '+0987654321'],\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Hello Everyone!'\r\n});\r\n```\r\n\r\n### Scheduled SMS\r\n\r\n```javascript\r\n// Send SMS tomorrow at 9 AM\r\nconst tomorrow = new Date();\r\ntomorrow.setDate(tomorrow.getDate() + 1);\r\ntomorrow.setHours(9, 0, 0, 0);\r\n\r\nawait client.sendSMS({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Reminder: Meeting tomorrow at 10 AM',\r\n  schedule_time: tomorrow.toISOString()\r\n});\r\n```\r\n\r\n### Campaign SMS\r\n\r\n```javascript\r\n// Send campaign to contact lists\r\nawait client.sendCampaign({\r\n  contact_list_id: '6415907d0d37a',\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Special offer for our customers!'\r\n});\r\n\r\n// Send to multiple contact lists\r\nawait client.sendCampaign({\r\n  contact_list_id: ['6415907d0d37a', '6415907d0d7a6'],\r\n  sender_id: 'YourApp',\r\n  type: 'plain',\r\n  message: 'Special offer for our customers!'\r\n});\r\n```\r\n\r\n### View SMS Messages\r\n\r\n```javascript\r\n// Get specific SMS by UID\r\nconst sms = await client.getSMS('606812e63f78b');\r\nconsole.log('SMS status:', sms.status);\r\n\r\n// Get all SMS messages\r\nconst { messages, pagination } = await client.getAllSMS();\r\nconsole.log(`Found ${messages.length} messages`);\r\n```\r\n\r\n### Profile Management\r\n\r\n```javascript\r\n// Get user profile information\r\nconst profile = await client.getProfile();\r\nconsole.log('User:', profile.name, profile.email);\r\nconsole.log('Status:', profile.status);\r\nconsole.log('Country:', profile.country);\r\n\r\n// Get SMS unit balance\r\nconst smsUnits = await client.getSMSUnits();\r\nconsole.log(`SMS Units - Total: ${smsUnits.total_units}, Used: ${smsUnits.used_units}, Remaining: ${smsUnits.remaining_units}`);\r\nconsole.log('Unit Type:', smsUnits.unit_type);\r\n```\r\n\r\n### Voice Messages\r\n\r\n```javascript\r\n// Send a voice message\r\nawait client.sendVoice({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'voice',\r\n  language: 'en-us',\r\n  gender: 'female',\r\n  message: 'Hello! This is a voice message from TalkSASA.'\r\n});\r\n\r\n// Send scheduled voice message\r\nconst tomorrow = new Date();\r\ntomorrow.setDate(tomorrow.getDate() + 1);\r\ntomorrow.setHours(9, 0, 0, 0);\r\n\r\nawait client.sendVoice({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'voice',\r\n  language: 'en-gb',\r\n  gender: 'male',\r\n  message: 'Good morning! This is your scheduled voice reminder.',\r\n  schedule_time: tomorrow.toISOString()\r\n});\r\n```\r\n\r\n### MMS Messages\r\n\r\n```javascript\r\n// Send an MMS message with image\r\nawait client.sendMMS({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'mms',\r\n  media_url: 'https://via.placeholder.com/150.jpg',\r\n  message: 'Check out this image!'\r\n});\r\n\r\n// Send MMS without text message\r\nawait client.sendMMS({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'mms',\r\n  media_url: 'https://example.com/image.png'\r\n});\r\n\r\n// Send scheduled MMS\r\nconst tomorrow = new Date();\r\ntomorrow.setDate(tomorrow.getDate() + 1);\r\ntomorrow.setHours(10, 0, 0, 0);\r\n\r\nawait client.sendMMS({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'mms',\r\n  media_url: 'https://example.com/promotional-image.jpg',\r\n  message: 'Special offer starting tomorrow!',\r\n  schedule_time: tomorrow.toISOString()\r\n});\r\n```\r\n\r\n### WhatsApp Messages\r\n\r\n```javascript\r\n// Send a WhatsApp message\r\nawait client.sendWhatsApp({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'whatsapp',\r\n  message: 'Hello! This is a WhatsApp message from TalkSASA.'\r\n});\r\n\r\n// Send scheduled WhatsApp message\r\nconst tomorrow = new Date();\r\ntomorrow.setDate(tomorrow.getDate() + 1);\r\ntomorrow.setHours(14, 0, 0, 0);\r\n\r\nawait client.sendWhatsApp({\r\n  recipient: '+1234567890',\r\n  sender_id: 'YourApp',\r\n  type: 'whatsapp',\r\n  message: 'Reminder: Your appointment is tomorrow at 2 PM.',\r\n  schedule_time: tomorrow.toISOString()\r\n});\r\n```\r\n\r\n### Using Templates\r\n\r\n```javascript\r\n// Create a template\r\nconst template = await client.createTemplate({\r\n  name: 'OTP Message',\r\n  content: 'Your verification code is {{code}}. Valid for {{minutes}} minutes.',\r\n  variables: ['code', 'minutes']\r\n});\r\n\r\n// Send using template\r\nawait client.sendTemplateSMS(template.id, '+1234567890', {\r\n  code: '123456',\r\n  minutes: '5'\r\n});\r\n```\r\n\r\n### Bulk SMS with Different Messages\r\n\r\n```javascript\r\nawait client.sendBulkSMS({\r\n  messages: [\r\n    {\r\n      to: '+1234567890',\r\n      message: 'Hello John!',\r\n      from: 'Company'\r\n    },\r\n    {\r\n      to: '+0987654321',\r\n      message: 'Hello Jane!',\r\n      from: 'Company'\r\n    }\r\n  ]\r\n});\r\n```\r\n\r\n### Error Handling with Retry\r\n\r\n```javascript\r\nconst client = new TalkSASAClient({\r\n  apiKey: 'your-api-key',\r\n  retries: 5, // Retry up to 5 times\r\n  timeout: 60000 // 60 second timeout\r\n});\r\n\r\ntry {\r\n  const response = await client.sendSMS({\r\n    to: '+1234567890',\r\n    message: 'Important message'\r\n  });\r\n  console.log('Message sent:', response.messageId);\r\n} catch (error) {\r\n  if (error.isRetryable) {\r\n    console.log('Error is retryable, will retry automatically');\r\n  } else {\r\n    console.error('Non-retryable error:', error.message);\r\n  }\r\n}\r\n```\r\n\r\n### OAuth 2.0 Authentication\r\n\r\n```javascript\r\nconst { TalkSASAClient } = require('talksasa-sms-client');\r\n\r\n// Initialize with OAuth 2.0\r\nconst client = new TalkSASAClient({\r\n  oauth2: {\r\n    clientId: 'your-client-id',\r\n    clientSecret: 'your-client-secret'\r\n  }\r\n});\r\n\r\n// Send SMS (OAuth token is automatically managed)\r\nawait client.sendSMS({\r\n  to: '+1234567890',\r\n  message: 'Hello from TalkSASA with OAuth!'\r\n});\r\n\r\n// Check OAuth token status\r\nif (client.isUsingOAuth2()) {\r\n  const tokenInfo = client.getOAuth2TokenInfo();\r\n  console.log('Token expires at:', new Date(tokenInfo.expires_at));\r\n}\r\n```\r\n\r\n### Contacts Management\r\n\r\n```javascript\r\n// Create a contact group\r\nconst group = await client.createContactGroup({\r\n  name: 'VIP Customers'\r\n});\r\n\r\n// Add contacts to the group\r\nconst contact1 = await client.createContact(group.uid, {\r\n  phone: '+1234567890',\r\n  first_name: 'John',\r\n  last_name: 'Doe'\r\n});\r\n\r\nconst contact2 = await client.createContact(group.uid, {\r\n  phone: '+0987654321',\r\n  first_name: 'Jane',\r\n  last_name: 'Smith'\r\n});\r\n\r\n// Get all contacts in a group\r\nconst { contacts, pagination } = await client.getContacts(group.uid);\r\nconsole.log(`Found ${contacts.length} contacts`);\r\n\r\n// Update a contact\r\nconst updatedContact = await client.updateContact(group.uid, contact1.uid, {\r\n  phone: '+1111111111',\r\n  first_name: 'Johnny'\r\n});\r\n\r\n// Send SMS to all contacts in a group\r\nfor (const contact of contacts) {\r\n  await client.sendSMS({\r\n    to: contact.phone,\r\n    message: `Hello ${contact.first_name}! Special offer just for you.`\r\n  });\r\n}\r\n```\r\n\r\n### Advanced OAuth 2.0 Usage\r\n\r\n```javascript\r\nconst { TalkSASAClient, TalkSASAOAuth2Client } = require('talksasa-sms-client');\r\n\r\n// Create OAuth 2.0 client directly\r\nconst oauthClient = new TalkSASAOAuth2Client({\r\n  clientId: 'your-client-id',\r\n  clientSecret: 'your-client-secret'\r\n});\r\n\r\n// Get access token manually\r\nconst accessToken = await oauthClient.getAccessToken();\r\nconsole.log('Access token:', accessToken);\r\n\r\n// Check token validity\r\nif (oauthClient.isTokenValid()) {\r\n  console.log('Token is valid');\r\n} else {\r\n  console.log('Token is expired or invalid');\r\n}\r\n\r\n// Refresh token\r\nconst newToken = await oauthClient.refreshToken();\r\nconsole.log('New token:', newToken.access_token);\r\n\r\n// Revoke token\r\nawait oauthClient.revokeToken();\r\nconsole.log('Token revoked');\r\n\r\n// Use with main client\r\nconst client = new TalkSASAClient({\r\n  oauth2: {\r\n    clientId: 'your-client-id',\r\n    clientSecret: 'your-client-secret'\r\n  }\r\n});\r\n```\r\n\r\n## Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\nTALKSASA_API_KEY=your-api-key-here\r\nTALKSASA_BASE_URL=https://bulksms.talksasa.com/api/v3/\r\nTALKSASA_TIMEOUT=30000\r\nTALKSASA_RETRIES=3\r\n```\r\n\r\n### Using Environment Variables\r\n\r\n```javascript\r\nconst client = new TalkSASAClient({\r\n  apiKey: process.env.TALKSASA_API_KEY,\r\n  baseUrl: process.env.TALKSASA_BASE_URL,\r\n  timeout: parseInt(process.env.TALKSASA_TIMEOUT) || 30000,\r\n  retries: parseInt(process.env.TALKSASA_RETRIES) || 3\r\n});\r\n```\r\n\r\n## Account Management Dashboard\r\n\r\nThis package includes a professional web-based dashboard for managing your TalkSASA account without visiting the TalkSASA website directly.\r\n\r\n### Dashboard Features\r\n\r\n- **Dashboard Overview**: View account statistics, balance, and group counts\r\n- **Profile Management**: View and manage your account profile\r\n- **SMS Balance**: Monitor SMS units with visual progress indicator\r\n- **Contact Groups**: Create, view, and delete contact groups\r\n- **Contact Management**: Add, view, and delete contacts within groups\r\n- **SMS Sending**: Send SMS messages with character counter and scheduling\r\n- **Templates**: Create and manage SMS templates with variables\r\n- **Settings**: Configure API authentication (API Key or OAuth 2.0) and default Sender ID\r\n\r\n### Dashboard Configuration\r\n\r\nThe dashboard allows you to configure:\r\n\r\n1. **API Key or OAuth 2.0 credentials** for authentication\r\n2. **Default Sender ID** - Your preferred sender ID that will be automatically filled when sending SMS (max 11 characters)\r\n3. **Base URL** - API endpoint (default: `https://bulksms.talksasa.com/api/v3`)\r\n\r\nAll settings are saved in browser localStorage for convenience.\r\n\r\n### Using the Dashboard\r\n\r\nThe dashboard files are included in the `dashboard/` folder of the package.\r\n\r\n#### Option 1: Serve from node_modules\r\n\r\n```bash\r\n# Using npx serve\r\nnpx serve node_modules/@benaah/talksasa-sms-client/dashboard\r\n\r\n# Using Python\r\ncd node_modules/@benaah/talksasa-sms-client/dashboard\r\npython -m http.server 8080\r\n\r\n# Using Node.js http-server\r\nnpx http-server node_modules/@benaah/talksasa-sms-client/dashboard\r\n```\r\n\r\n#### Option 2: Copy to Your Project\r\n\r\n```bash\r\n# Copy dashboard to your public folder\r\ncp -r node_modules/@benaah/talksasa-sms-client/dashboard ./public/talksasa-admin\r\n\r\n# Or on Windows\r\nxcopy /E /I node_modules\\@benaah\\talksasa-sms-client\\dashboard public\\talksasa-admin\r\n```\r\n\r\n#### Option 3: Integrate with Your Application\r\n\r\nCopy the dashboard files (`index.html`, `styles.css`, `dashboard.js`) to your application's static assets and serve them through your web server.\r\n\r\n### Dashboard Configuration\r\n\r\n1. Open the dashboard in your browser\r\n2. Click the Settings icon in the sidebar\r\n3. Choose authentication method (API Key or OAuth 2.0)\r\n4. Enter your credentials\r\n5. Save configuration\r\n\r\n**Security Note**: For production deployments, implement a server-side proxy to avoid exposing API credentials in the browser. See `dashboard/README.md` for detailed security recommendations.\r\n\r\n### Dashboard Files\r\n\r\n- `dashboard/index.html` - Main dashboard interface\r\n- `dashboard/styles.css` - Professional styling\r\n- `dashboard/dashboard.js` - JavaScript functionality\r\n- `dashboard/README.md` - Detailed dashboard documentation\r\n\r\n## Development\r\n\r\n### Building the Package\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\nnpm test\r\n```\r\n\r\n### Linting\r\n\r\n```bash\r\nnpm run lint\r\nnpm run lint:fix\r\n```\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests for new functionality\r\n5. Run the test suite\r\n6. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## Support\r\n\r\n-  Email: support@talksasa.com\r\n-  Issues: [GitHub Issues](https://github.com/Benaah/talksasa-sms-client/issues)\r\n-  Documentation: [TalkSASA API Docs](https://docs.talksasa.com)\r\n\r\n## Changelog\r\n\r\n### 1.1.0\r\n- Fixed API key validation to support TalkSASA API key format with pipe character \r\n- Improved API key validation to accept all printable ASCII characters\r\n- Enhanced security while maintaining compatibility with various API key formats\r\n\r\n### 1.0.0\r\n- Initial release\r\n- Single and bulk SMS sending\r\n- Template management\r\n- Delivery reports\r\n- Account management\r\n- TypeScript support\r\n- Comprehensive error handling\r\n- Retry logic with exponential backoff\r\n","readmeFilename":"README.md"}