Termii TypeScript SDK

A powerful, fully type-safe TypeScript SDK for the Termii V3 API, optimized for Node.js and Bun.

Features

• 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.

Installation

Install the package via your preferred package manager:

npm install @emmanuelapabiekun/termii
# or
bun add @emmanuelapabiekun/termii
# or
yarn add @emmanuelapabiekun/termii

Getting Started

Initialize 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
);

Resource Modules

The SDK is organized into specialized modules accessible via the main Termii instance.

SMS Messaging

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"
});

Token (OTP)

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"
});

eSIM Management (via Sotel)

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`);

WhatsApp Business

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"
  }
});

Webhook Verification

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');
  }
});

Insights and Analytics

Monitor your wallet balance and query message history.

const balance = await termii.insights.balance();
console.log(`Balance: ${balance.balance} ${balance.currency}`);

Documentation and Support

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.

Error Handling

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}`);
  }
}

License

MIT