Modern, zero-dependency TypeScript SDK for mNotify's Bulk Messaging Solution (BMS) API, providing seamless SMS, Voice, and contact management capabilities.
Simplify integration with mNotify's communication APIs by providing:
- Zero dependencies - No external runtime dependencies
- Type-safe interactions with full TypeScript support
- Modern functional programming style
- Developer-friendly abstractions with intuitive API
- Comprehensive API coverage
- Reliable error handling and validation
| Feature Area | Capabilities |
|---|---|
| SMS | Bulk sending, Delivery reports, Scheduled SMS |
| Contacts | CRUD operations, Contact management |
| Groups | Group creation, Contact assignment |
| Templates | Create/list/delete templates, Approval status |
| Account | Balance checks, Sender ID management |
| Utilities | Built-in validation, Automatic retries |
| Error Handling | Railway-oriented programming with Result type |
This SDK supports railway-oriented programming (inspired by Rust's Result<T, E> type) for safer, more predictable error handling. All methods have both throwing and non-throwing variants.
import { MNotify } from 'mnotify-ts-sdk';
const mnotify = new MNotify({ apiKey: process.env.MNOTIFY_API_KEY! });
// Use "Safe" methods that return Result<T, Error>
const result = await mnotify.sms.sendQuickBulkSMSSafe({
recipient: ['233200000000'],
sender: 'MyApp',
message: 'Hello!'
});
// Pattern matching
result.match({
ok: (response) => console.log('SMS sent!', response.summary),
err: (error) => console.error('Failed:', error.message)
});
// Or check explicitly
if (result.isOk()) {
console.log('Success:', result.value);
} else {
console.error('Error:', result.error);
}
// Chain operations
const balanceResult = await mnotify.account.getBalanceSafe();
const balance = balanceResult
.map(b => b.balance)
.unwrapOr(0); // Safe default// Traditional try-catch error handling
try {
const response = await mnotify.sms.sendQuickBulkSMS({
recipient: ['233200000000'],
sender: 'MyApp',
message: 'Hello!'
});
console.log('SMS sent!', response);
} catch (error) {
console.error('Failed:', error);
}- Explicit error handling - No hidden exceptions
- Type-safe - Errors are part of the type signature
- Composable - Easy to chain operations
- Predictable - No surprises in production
- Functional - Works well with modern patterns
- Smaller bundle size - No extra packages to download
- Faster installation - No dependency tree to resolve
- Better security - Fewer attack vectors
- Future-proof - No dependency breaking changes
- Better performance - Native fetch API, optimized code
npm install mnotify-ts-sdk
# or
pnpm install mnotify-ts-sdk
# or
yarn add mnotify-ts-sdkimport { MNotify } from 'mnotify-ts-sdk';
// Initialize client with API key
const mnotify = new MNotify({
apiKey: process.env.MNOTIFY_API_KEY!
});
// Send SMS
const response = await mnotify.sms.sendQuickBulkSMS({
recipient: ['233200000000'],
sender: 'MyApp',
message: 'Hello from SDK!'
});
// Check delivery status
const status = await mnotify.sms.getSMSStatus(response.summary.message_id);
// Check account balance
const balance = await mnotify.account.getBalance();
console.log(`Balance: ${balance.balance}`);// Send single or bulk SMS
await mnotify.sms.sendQuickBulkSMS({
recipient: ['233200000000', '233244444444'],
sender: 'MyApp',
message: 'Hello World!'
});
// Schedule SMS
await mnotify.sms.sendQuickBulkSMS({
recipient: ['233200000000'],
sender: 'MyApp',
message: 'Scheduled message',
is_schedule: true,
schedule_date: '2024-12-31T12:00:00Z'
});
// Get delivery status
const status = await mnotify.sms.getSMSStatus('campaign_id');// Create contact
const contact = await mnotify.contacts.createContact({
phone: '233200000000',
firstname: 'John',
lastname: 'Doe',
email: ['john@example.com']
});
// Get all contacts
const contacts = await mnotify.contacts.getContacts();// Create group
const group = await mnotify.groups.createGroup({
name: 'VIP Customers',
description: 'High-value customer segment'
});
// Add contact to group
await mnotify.groups.addContactToGroup(group.id, contact._id);
// Get all groups
const groups = await mnotify.groups.getGroups();// Create template
const template = await mnotify.templates.createTemplate({
name: 'Welcome Message',
content: 'Welcome {{name}} to our service!'
});
// Get all templates
const templates = await mnotify.templates.getTemplates();
// Delete template
await mnotify.templates.deleteTemplate(template.id);// Check balance
const balance = await mnotify.account.getBalance();
// Get sender IDs
const senderIds = await mnotify.account.getSenderIds();
// Register new sender ID
await mnotify.account.registerSenderId('MyNewApp');The SDK accepts the following configuration options:
const mnotify = new MNotify({
apiKey: 'your-api-key', // Required: Your mNotify API key
baseUrl: 'https://...', // Optional: Custom API base URL
timeout: 10000, // Optional: Request timeout in ms (default: 10000)
maxRetries: 3 // Optional: Max retry attempts (default: 3)
});The SDK provides detailed error information:
import { MNotifyError } from 'mnotify-ts-sdk';
try {
await mnotify.sms.sendQuickBulkSMS({...});
} catch (error) {
if (error instanceof MNotifyError) {
console.error('Status:', error.statusCode);
console.error('Message:', error.message);
console.error('Data:', error.data);
}
}The SDK exports several utility functions for common operations:
import {
normalizePhone,
isValidPhone,
chunk,
toArray
} from 'mnotify-ts-sdk';
// Normalize phone numbers
const normalized = normalizePhone('0200000000'); // '233200000000'
// Validate phone numbers
if (isValidPhone('+233200000000')) {
// Valid phone number
}
// Chunk recipients for batch sending
const recipients = [...]; // large array
const batches = chunk(recipients, 100); // Split into batches of 100
// Ensure value is an array
const numbers = toArray(singleNumber); // Always returns arrayThe SDK provides detailed error information through the MNotifyError class:
import { MNotifyError } from 'mnotify-ts-sdk';
try {
await mnotify.sms.sendQuickBulkSMS({...});
} catch (error) {
if (error instanceof MNotifyError) {
console.error('API Error:', {
status: error.statusCode,
message: error.message,
data: error.data
});
// Handle specific errors
if (error.statusCode === 429) {
// Rate limited - retry later
} else if (error.statusCode === 401) {
// Invalid API key
}
}
}Send SMS to large recipient lists efficiently:
import { chunk } from 'mnotify-ts-sdk';
const allRecipients = [...]; // 1000s of numbers
const batches = chunk(allRecipients, 100); // Process 100 at a time
for (const batch of batches) {
await mnotify.sms.sendQuickBulkSMS({
recipient: batch,
sender: 'MyApp',
message: 'Batch message'
});
// Optional: Add delay between batches
await new Promise(resolve => setTimeout(resolve, 1000));
}- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit changes (
git commit -m 'Add some feature') - Push to branch (
git push origin feature/your-feature) - Open a Pull Request
git clone https://github.com/adjanour/mnotify-ts-sdk.git
cd mnotify-ts-sdk
npm installnpm test
# Watch mode
npm run test:watchnpm run buildnpm run docs| Feature | v1.0.x | v2.0.0 |
|---|---|---|
| Runtime Dependencies | 4 | 0 |
| Bundle Size | ~1MB | 172KB |
| SMS Service | ✅ | ✅ |
| Contact Management | Basic | ✅ Complete |
| Group Management | ❌ | ✅ |
| Template Management | ❌ | ✅ |
| Account Operations | ❌ | ✅ |
| Functional Utilities | ❌ | ✅ |
| Railway-Oriented Programming | ❌ | ✅ New! |
| TypeScript Types | Partial | Full |
| Test Coverage | Basic | Comprehensive |
| CI/CD Pipeline | ❌ | ✅ New |
This project uses GitHub Actions for continuous integration and deployment:
- Automated Testing: Runs on every push and pull request (Node 18.x, 20.x, 22.x)
- Security Scanning: CodeQL security analysis on schedule and PR
- NPM Publishing: Automated releases when GitHub releases are created
- Code Coverage: Integrated with Codecov
| Workflow | Trigger | Description |
|---|---|---|
test.yml |
Push/PR to main/develop | Runs linting, build, and tests |
codeql.yml |
Push/PR/Schedule | Security vulnerability scanning |
publish.yml |
GitHub Release | Publishes package to NPM |
Full API reference available at:
mNotify SDK Documentation
Official mNotify API documentation:
https://developer.mnotify.com/
MIT © Bernard
Need Help?
Open an issue or contact adjanour@icloud.com