A powerful, fully type-safe TypeScript SDK for the Termii V3 API, optimized for Node.js and Bun.
- Full Parity: Supports SMS, Voice, Token (OTP), Insights, WhatsApp, Email, Campaigns, and eSIM.
- Strictly Typed: Powered by Zod for runtime validation and precise IDE autocompletion.
- eSIM Lifecycle: Comprehensive management of Sotel eSIMs including provisioning, top-ups, and usage tracking.
- Secure Webhooks: Built-in HMAC-SHA512 signature verification and event parsing.
- Smart Routing: Automated handling of single and bulk SMS endpoints.
- Pagination Support: Built-in utilities for handling Spring-style paginated API responses.
Install the package via your preferred package manager:
npm install @emmanuelapabiekun/termii
# or
bun add @emmanuelapabiekun/termii
# or
yarn add @emmanuelapabiekun/termiiInitialize the SDK by providing your API key and configuration options.
import { Termii } from 'termii';
const termii = new Termii(
'YOUR_API_KEY',
'YOUR_SECRET_KEY', // Optional: Required for Webhook verification
'https://v3.api.termii.com', // Optional: Custom Base URL
true // Optional: Enable debug logging
);The SDK is organized into specialized modules accessible via the main Termii instance.
Send single or bulk SMS messages across different channels.
const response = await termii.sms.send({
to: "2348000000000",
from: "Termii",
sms: "Hello from the TypeScript SDK",
type: "plain",
channel: "generic"
});Generate and verify multi-channel One-Time Passwords (SMS, Voice, Email, WhatsApp).
// Send an OTP
const otp = await termii.token.send({
to: "2348000000000",
from: "Termii",
message_type: "NUMERIC",
pin_attempts: 3,
pin_time_to_live: 5,
pin_length: 6,
pin_placeholder: "< 1234 >",
message_text: "Your confirmation code is < 1234 >",
pin_type: "NUMERIC"
});
// Verify an OTP
const verification = await termii.token.verify({
pin_id: otp.pinId,
pin: "123456"
});Complete management of the eSIM lifecycle.
// 1. Authenticate to secure a session token
await termii.esim.authenticate();
// 2. Search for available data plans
const plans = await termii.esim.fetchPlans({
country: "Nigeria",
type: "LOCAL"
});
// 3. Provision an eSIM for a customer
const sim = await termii.esim.create(plans.data.content[0].productId, "NGA");
// 4. Monitor data usage
const usage = await termii.esim.getUsage(sim.data.sim.iccid);
console.log(`Usage: ${usage.data.data_used_gigabyte}GB of ${usage.data.data_total_gigabyte}GB`);Send interactive and template-based WhatsApp messages.
await termii.whatsapp.sendTemplate({
phone_number: "2348000000000",
template_id: "order_confirmation",
device_id: "YOUR_DEVICE_ID",
data: {
customer_name: "John Doe",
order_id: "ABC-123"
}
});The SDK provides a secure way to verify and parse incoming webhooks using HMAC-SHA512.
import express from 'express';
const app = express();
app.use(express.json());
app.post('/webhooks/termii', (req, res) => {
const signature = req.headers['x-termii-signature'] as string;
try {
// Verifies the signature and returns a strictly typed event object
const event = termii.webhooks.construct(req.body, signature);
if (event.type === 'inbound') {
console.log(`Received message from ${event.sender}: ${event.message}`);
}
res.status(200).send('OK');
} catch (err) {
res.status(401).send('Unauthorized: Invalid Signature');
}
});Monitor your wallet balance and query message history.
const balance = await termii.insights.balance();
console.log(`Balance: ${balance.balance} ${balance.currency}`);Every class and method in the SDK is documented with JSDoc. You can hover over any method in your IDE to see its purpose, parameters, and return types.
The SDK exposes custom error classes for robust error management:
TermiiHttpError: Thrown when the API returns a non-2xx status code.TermiiValidationError: Thrown when the API response fails schema validation.
try {
await termii.insights.balance();
} catch (error) {
if (error instanceof TermiiHttpError) {
console.error(`Status: ${error.status}, Message: ${error.message}`);
}
}MIT