Termii NestJS SDK

A robust, well-structured, and fully-typed NestJS SDK for interacting with the Termii API. This library simplifies sending SMS and WhatsApp messages with a developer-friendly API.

Features

• ✅ Easy integration with any NestJS application
• ✅ Static (forRoot) and async (forRootAsync) module configuration
• ✅ Strongly-typed DTOs for both requests and responses
• ✅ Full Termii API Coverage:
  • Messaging: Send SMS & WhatsApp messages, manage Sender IDs, and Phone Books.
  • Token: Send, verify, and generate OTPs via SMS, Voice, and Email.
  • Insights: Check account balance, search history, and perform number lookups.

Installation

1npm install termii-nestjs

or

1yarn add termii-nestjs

This library has peer dependencies on several NestJS packages. If they are not already installed in your project, you will need to add them:

1npm install @nestjs/common @nestjs/core reflect-metadata

Getting Started

1. Import the Module

Import TermiiModule into your root AppModule.

Static Configuration (forRoot)

This method is suitable for simple configurations where credentials are not loaded dynamically.

1// src/app.module.ts
2import { Module } from '@nestjs/common';
3import { TermiiModule } from 'termii-nestjs';
4
5@Module({
6  imports: [
7    TermiiModule.forRoot({
8      apiKey: 'YOUR_TERMII_API_KEY',
9      // baseUrl: 'https://api.ng.termii.com' // Optional: Override base URL
10    }),
11  ],
12})
13export class AppModule {}

Async Configuration (forRootAsync)

This is the recommended approach, especially when using @nestjs/config to manage environment variables.

1// src/app.module.ts
2import { Module } from '@nestjs/common';
3import { ConfigModule, ConfigService } from '@nestjs/config';
4import { TermiiModule } from 'termii-nestjs';
5
6@Module({
7  imports: [
8    ConfigModule.forRoot({ isGlobal: true }),
9    TermiiModule.forRootAsync({
10      imports: [ConfigModule],
11      useFactory: (configService: ConfigService) => ({
12        apiKey: configService.get<string>('TERMII_API_KEY'),
13        // baseUrl: 'https://api.ng.termii.com' // Optional: Override base URL
14      }),
15      inject: [ConfigService],
16    }),
17  ],
18})
19export class AppModule {}

2. Inject and Use TermiiService

You can now inject TermiiService into any of your services or controllers. The service is namespaced to provide easy access to different parts of the Termii API:

• termiiService.messaging
• termiiService.token
• termiiService.insight

Below are examples for each service.

Messaging API

The messaging service handles sending messages and managing related resources like Sender IDs and Phone Books.

Example: Sending an SMS

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService, TermiiSendMessageRequest } from 'termii-nestjs';
3
4@Injectable()
5export class NotificationService {
6  private readonly logger = new Logger(NotificationService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async sendWelcomeMessage(phoneNumber: string) {
11    const payload: TermiiSendMessageRequest = {
12      to: phoneNumber,
13      from: 'YourSenderID', // This will be the sender ID displayed on the recipient's device
14      sms: 'Hi there, welcome to our service!',
15      channel: 'generic', // Use 'generic' for SMS, 'dnd' to bypass DND, or 'whatsapp'
16    };
17    try {
18      const response = await this.termiiService.messaging.sendMessage(payload);
19      this.logger.log(`Message sent. Message ID: ${response.message_id}`);
20    } catch (error) {
21      this.logger.error(
22        'Failed to send SMS',
23        error.response?.data || error.message
24      );
25    }
26  }
27}

Example: Requesting a Sender ID

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService, TermiiRequestSenderIdRequest } from 'termii-nestjs';
3
4@Injectable()
5export class OnboardingService {
6  private readonly logger = new Logger(OnboardingService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async requestNewSenderId() {
11    const payload: TermiiRequestSenderIdRequest = {
12      sender_id: 'NewBrand',
13      usecase:
14        'We will use this to send transaction notifications to our customers.',
15      company: 'My Awesome Company',
16    };
17    try {
18      const response = await this.termiiService.messaging.requestSenderId(
19        payload
20      );
21      this.logger.log(`Sender ID request successful: ${response.message}`);
22    } catch (error) {
23      this.logger.error(
24        'Failed to request Sender ID',
25        error.response?.data || error.message
26      );
27    }
28  }
29}

Token API

The token service is used for sending and verifying One-Time Passwords (OTPs) through various channels.

Example: Sending an OTP via SMS

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService, TermiiSendTokenRequest } from 'termii-nestjs';
3
4@Injectable()
5export class AuthService {
6  private readonly logger = new Logger(AuthService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async sendLoginOtp(phoneNumber: string) {
11    const payload: TermiiSendTokenRequest = {
12      message_type: 'NUMERIC',
13      to: phoneNumber,
14      from: 'YourSenderID',
15      channel: 'generic',
16      pin_attempts: 3,
17      pin_time_to_live: 5, // In minutes
18      pin_length: 6,
19      pin_placeholder: '< 1234 >',
20      message_text: 'Your login code is < 1234 >. It will expire in 5 minutes.',
21    };
22    try {
23      const response = await this.termiiService.token.sendToken(payload);
24      this.logger.log(`OTP sent. Pin ID: ${response.pinId}`);
25      return response.pinId; // Return pinId to be used for verification
26    } catch (error) {
27      this.logger.error(
28        'Failed to send OTP',
29        error.response?.data || error.message
30      );
31    }
32  }
33}

Example: Verifying an OTP

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService, TermiiVerifyTokenRequest } from 'termii-nestjs';
3
4@Injectable()
5export class AuthService {
6  private readonly logger = new Logger(AuthService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async verifyLoginOtp(pinId: string, pin: string) {
11    const payload: TermiiVerifyTokenRequest = { pin_id: pinId, pin: pin };
12    try {
13      const response = await this.termiiService.token.verifyToken(payload);
14      if (response.verified) {
15        this.logger.log(`OTP verification successful for ${response.msisdn}`);
16        return true;
17      }
18      this.logger.warn(`OTP verification failed for pinId: ${pinId}`);
19      return false;
20    } catch (error) {
21      this.logger.error(
22        'Failed to verify OTP',
23        error.response?.data || error.message
24      );
25      return false;
26    }
27  }
28}

Insight API

The insight service provides tools for checking your account status and looking up information about phone numbers.

Example: Checking Your Balance

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService } from 'termii-nestjs';
3
4@Injectable()
5export class AdminService {
6  private readonly logger = new Logger(AdminService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async checkAccountBalance() {
11    try {
12      const response = await this.termiiService.insight.getBalance();
13      this.logger.log(
14        `Account balance: ${response.balance} ${response.currency}`
15      );
16    } catch (error) {
17      this.logger.error(
18        'Failed to fetch balance',
19        error.response?.data || error.message
20      );
21    }
22  }
23}

Example: Checking DND Status of a Phone Number

1import { Injectable, Logger } from '@nestjs/common';
2import { TermiiService } from 'termii-nestjs';
3
4@Injectable()
5export class CustomerSupportService {
6  private readonly logger = new Logger(CustomerSupportService.name);
7
8  constructor(private readonly termiiService: TermiiService) {}
9
10  async checkDndStatus(phoneNumber: string) {
11    try {
12      // The search method checks the DND status of a number
13      const response = await this.termiiService.insight.search(phoneNumber);
14
15      this.logger.log(`DND status for ${response.number}:`, {
16        dndActive: response.dnd_active,
17        network: response.network_code,
18      });
19    } catch (error) {
20      this.logger.error(
21        `Failed to check DND status for ${phoneNumber}`,
22        error.response?.data || error.message
23      );
24    }
25  }
26}

License

This project is licensed under the MIT License.