Installation

npm install textwave-sdk

yarn add textwave-sdk

pnpm add textwave-sdk

Quick Start

import { TextWave } from 'textwave-sdk';

const client = new TextWave('your_api_key');

// Send SMS
const result = await client.sendSms('254712345678', 'Hello from TextWave!');
console.log(`Sent: ${result.data.totalSent}`);

Usage

Initialize the Client

import { TextWave } from 'textwave-sdk';

// With API key only (uses default API URL)
const client = new TextWave('sk_live_xxxxxxxxxxxxxxxx');

// With custom API URL
const client = new TextWave('sk_live_xxxxxxxxxxxxxxxx', 'https://api.textwave.co.ke/v1');

Send SMS

// Single recipient
await client.sendSms('254712345678', 'Hello!');

// Multiple recipients (bulk)
await client.sendSms(
  ['254712345678', '254723456789', '254734567890'],
  'Bulk message to all!'
);

// With custom sender ID
await client.sendSms('254712345678', 'Hello!', 'MyBrand');

Check Balance

const balance = await client.getBalance();
console.log(`SMS Credits: ${balance.data.smsCredits}`);

Get Message History

// Get recent messages
const history = await client.getHistory();

// With pagination and filters
const filtered = await client.getHistory({
  page: 1,
  limit: 50,
  status: 'delivered'
});

history.data.messages.forEach(msg => {
  console.log(`${msg.phone}: ${msg.status}`);
});

Get Transactions

const transactions = await client.getTransactions(1, 20);

transactions.data.transactions.forEach(tx => {
  console.log(`${tx.type}: ${tx.smsCredits} SMS - ${tx.description}`);
});

TypeScript Support

Full TypeScript support with exported types:

import { 
  TextWave,
  SendSmsResponse,
  HistoryResponse,
  BalanceResponse,
  Message,
  Transaction 
} from 'textwave-sdk';

Error Handling

try {
  await client.sendSms('254712345678', 'Hello!');
} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    console.log('Please top up your wallet');
  } else if (error.code === 'UNAUTHORIZED') {
    console.log('Invalid API key');
  } else {
    console.log('Error:', error.message);
  }
}

Error Codes

| Code | Description | |------|-------------| | UNAUTHORIZED | Invalid or missing API key | | INSUFFICIENT_CREDITS | Not enough SMS credits | | INVALID_PHONE | Invalid phone number format | | RATE_LIMITED | Too many requests | | VALIDATION_ERROR | Request validation failed |

Get Your API Key

1. Sign up at textwave.co.ke
2. Go to Dashboard → Settings → API Keys
3. Click Generate API Key
4. Copy and use in your application

Requirements

• Node.js 18+ (uses native fetch)
• Or any environment with fetch support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

See CHANGELOG.md for a list of changes.

Support

• Website: textwave.co.ke
• Email: [email protected]
• Issues: GitHub Issues

License

MIT © TextWave