Send SMS & OTP in Node.js (India)

// send-sms.mjs (ES module): SMS_API_KEY=xxxx node send-sms.mjs
const res = await fetch('https://whitelabled.securesmsc.com/api/v2/sms/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SMS_API_KEY}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    sender_id: 'AVNZON',
    recipient: '919876543210',            // 91 + 10-digit mobile
    message: 'Your OTP for login is 482913. It is valid for 10 minutes. Do not share it with anyone. -AVNZON',
    route: 'transactional',
  }),
  signal: AbortSignal.timeout(15_000),    // give up after 15 s
});
console.log(res.status, await res.json());

{
  "success": true,
  "message": "SMS queued successfully",
  "data": {
    "message_id": 1849302,
    "queue_id": 1849302,
    "status": "queued",
    "estimated_delivery": "2026-10-29T10:42:05.000000Z"
  }
}

// sms-client.mjs
const BASE_URL = 'https://whitelabled.securesmsc.com/api/v2';

// fetch() rejects with a TypeError whose `cause.code` says what went wrong.
// Only these codes prove the request never reached the gateway.
const NEVER_SENT = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'UND_ERR_CONNECT_TIMEOUT']);
// Statuses returned before the gateway processed anything. 500 and 504 are NOT here:
// they can arrive after a message was queued, so a send is never retried on them.
const RETRY_STATUS = new Set([429, 502, 503]);

export class SmsError extends Error {
  constructor(status, body, retryable = false) {
    super(`HTTP ${status}: ${body.error ?? 'error'}: ${body.message ?? ''}`);
    this.name = 'SmsError';
    this.status = status;                        // 0 = could not connect
    this.errorCode = body.error_code ?? null;    // e.g. 'TEMPLATE_MISMATCH'
    this.details = body.errors ?? body.details ?? null;
    this.retryable = retryable;                  // true = provably not sent, try later
  }
}

export class SmsUncertainError extends Error {
  constructor(cause) {
    super(`Request may have been sent: ${cause.message}`, { cause });
    this.name = 'SmsUncertainError';
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export function createSmsClient({ apiKey, baseUrl = BASE_URL, timeoutMs = 15_000, maxAttempts = 3 }) {
  async function request(method, path, body) {
    for (let attempt = 1; ; attempt++) {
      let res;
      try {
        res = await fetch(baseUrl + path, {
          method,
          headers: {
            Authorization: `Bearer ${apiKey}`,
            Accept: 'application/json',
            ...(body && { 'Content-Type': 'application/json' }),
          },
          body: body && JSON.stringify(body),
          signal: AbortSignal.timeout(timeoutMs),
        });
      } catch (err) {
        // TimeoutError or a reset connection: the gateway may already have the message.
        if (!NEVER_SENT.has(err.cause?.code)) throw new SmsUncertainError(err);
        if (attempt >= maxAttempts) throw new SmsError(0, { error: 'Connection failed', message: err.cause.code }, true);
        await sleep(2 ** attempt * 250);
        continue;
      }

      const data = await res.json().catch(() => ({ error: `Non-JSON response (${res.status})` }));
      if (res.ok && data.success) return data;

      const safe = RETRY_STATUS.has(res.status) || (method === 'GET' && res.status >= 500);
      if (!safe && res.status >= 500) throw new SmsUncertainError(new Error(`HTTP ${res.status} on ${path}`));
      const error = new SmsError(res.status, data, safe);
      if (!safe || attempt >= maxAttempts) throw error;
      const retryAfter = Number(res.headers.get('retry-after'));
      await sleep(retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 250);
    }
  }

  return {
    send: (to, message, senderId, extra = {}) =>
      request('POST', '/sms/send', { sender_id: senderId, recipient: to, message, ...extra })
        .then((r) => r.data),                    // { message_id, status, ... }
    sendBulk: (recipients, message, senderId, extra = {}) =>
      request('POST', '/sms/send-bulk', { sender_id: senderId, recipients, message, ...extra }),
    status: (messageId) =>
      request('GET', `/sms/status/${encodeURIComponent(messageId)}`).then((r) => r.data.status),
    balance: () => request('GET', '/balance').then((r) => r.data),
  };
}

// templates.mjs
const PLACEHOLDER = /\{#(\w+)#\}/g;               // {#var#}, {#numeric#}, {#num#}, {#url#} ...
const MAX_LEN = { var: 30, url: 120, urlott: 120, urg: 120, uro: 120 };   // others: 40
const DIGITS_ONLY = new Set(['numeric', 'num', 'number']);

export const TPL_OTP =
  'Your OTP for login is {#numeric#}. It is valid for 10 minutes. Do not share it with anyone. -AVNZON';

export function fillTemplate(template, ...values) {
  const slots = template.match(PLACEHOLDER) ?? [];
  if (slots.length !== values.length) {
    throw new Error(`template has ${slots.length} variables, got ${values.length}`);
  }
  let i = 0;
  return template.replace(PLACEHOLDER, (_, tag) => {   // a function: "$&" in values stays literal
    const value = String(values[i++]);
    const limit = MAX_LEN[tag] ?? 40;
    if (value.length > limit) throw new Error(`{#${tag}#} value is ${value.length} chars; limit is ${limit}`);
    if (DIGITS_ONLY.has(tag) && !/^\d+$/.test(value)) throw new Error(`{#${tag}#} must be digits only`);
    return value;
  });
}

// otp-server.mjs (ES module): npm install express
import express from 'express';
import { createHmac, randomInt, timingSafeEqual } from 'node:crypto';
import { createSmsClient } from './sms-client.mjs';
import { fillTemplate, TPL_OTP } from './templates.mjs';

const sms = createSmsClient({ apiKey: process.env.SMS_API_KEY });
const PEPPER = process.env.OTP_PEPPER;             // server-side secret, never stored with codes
const OTP_TTL_MS = 10 * 60_000;
const MAX_GUESSES = 5;

// In-memory state works for ONE process. With several instances or restarts,
// keep both maps in Redis (INCR + EXPIRE for counters, SET ... EX for codes).
const counters = new Map();                         // key -> { count, resetAt }
const codes = new Map();                            // phone -> { digest, expiresAt, guesses }

function allow(key, limit, windowMs) {
  const now = Date.now();
  const entry = counters.get(key);
  if (!entry || entry.resetAt <= now) {
    counters.set(key, { count: 1, resetAt: now + windowMs });
    return true;
  }
  entry.count += 1;
  return entry.count <= limit;
}

function normalisePhone(input) {
  let digits = String(input ?? '').replace(/\D/g, '');
  if (digits.length === 11 && digits.startsWith('0')) digits = digits.slice(1);
  if (digits.length === 10) digits = `91${digits}`;
  return /^91[6-9]\d{9}$/.test(digits) ? digits : null;   // Indian mobiles start 6-9
}

const digest = (phone, code) => createHmac('sha256', PEPPER).update(`${phone}:${code}`).digest();

const app = express();
app.set('trust proxy', 1);                          // one reverse proxy in front: req.ip = client
app.use(express.json());

app.post('/otp/request', async (req, res) => {
  const phone = normalisePhone(req.body?.phone);
  if (!phone) return res.status(422).json({ error: 'Enter a valid Indian mobile number' });

  // Rate-limit BEFORE generating or sending anything.
  if (!allow(`n:${phone}`, 3, 10 * 60_000) || !allow(`ip:${req.ip}`, 20, 60 * 60_000)) {
    return res.status(429).json({ error: 'Too many requests. Try again later.' });
  }

  const code = String(randomInt(0, 1_000_000)).padStart(6, '0');   // CSPRNG, not Math.random()
  codes.set(phone, { digest: digest(phone, code), expiresAt: Date.now() + OTP_TTL_MS, guesses: 0 });

  try {
    await sms.send(phone, fillTemplate(TPL_OTP, code), 'AVNZON');
  } catch (err) {
    console.error('OTP send failed:', err.name, err.message);       // never log the code
    return res.status(502).json({ error: 'Could not send the code. Try again shortly.' });
  }
  res.json({ sent: true });
});

app.post('/otp/verify', (req, res) => {
  const phone = normalisePhone(req.body?.phone);
  const code = String(req.body?.code ?? '');
  const entry = phone && codes.get(phone);
  if (!entry || entry.expiresAt < Date.now() || entry.guesses >= MAX_GUESSES || !/^\d{6}$/.test(code)) {
    return res.status(400).json({ verified: false });
  }
  entry.guesses += 1;
  if (!timingSafeEqual(entry.digest, digest(phone, code))) {
    return res.status(400).json({ verified: false });
  }
  codes.delete(phone);                              // single use
  res.json({ verified: true });                     // start the session / issue a token here
});

// Drop expired entries so the maps do not grow forever.
setInterval(() => {
  const now = Date.now();
  for (const [k, v] of counters) if (v.resetAt <= now) counters.delete(k);
  for (const [k, v] of codes) if (v.expiresAt <= now) codes.delete(k);
}, 60_000).unref();

app.listen(3000, () => console.log('OTP service on :3000'));

// dlr-webhook.mjs: add to the Express app from the OTP example
import { timingSafeEqual } from 'node:crypto';

const DLR_TOKEN = Buffer.from(process.env.DLR_TOKEN ?? '');   // long random string

function tokenOk(supplied) {
  const given = Buffer.from(String(supplied ?? ''));
  return DLR_TOKEN.length > 0 && given.length === DLR_TOKEN.length && timingSafeEqual(given, DLR_TOKEN);
}

// Register https://your-app.example/webhooks/sms-status?token=<DLR_TOKEN> in the dashboard.
// JSON bodies are parsed by app.use(express.json()); this also accepts form posts.
app.post('/webhooks/sms-status', express.urlencoded({ extended: false }), async (req, res) => {
  if (!tokenOk(req.query.token)) return res.sendStatus(403);
  try {
    await saveRawReport(req.body);       // insert the raw payload; parse it in a worker
    res.sendStatus(200);                 // answer quickly; do the real work later
  } catch (err) {
    console.error('DLR store failed:', err.message);
    res.sendStatus(500);                 // tell the sender the report was not stored
  }
});

// bulk.mjs
export async function sendToMany(sms, numbers, message, senderId = 'AVNZON', extra = {}) {
  const unique = [...new Set(numbers)];             // de-duplicate first
  const failed = [];
  for (let i = 0; i < unique.length; i += 1000) {   // the API takes up to 1,000 per call
    const batch = unique.slice(i, i + 1000);
    try {
      await sms.sendBulk(batch, message, senderId, extra);
    } catch (err) {
      console.error(`batch starting at ${i} failed:`, err.name, err.message);
      failed.push(batch);                           // investigate, then resend only these
    }
  }
  return failed;
}

// sms-parts.mjs
const GSM7_BASIC = new Set(
  '@£$¥èéùìòÇ\nØø\rÅåΔ_ΦΓΛΩΠΨΣΘΞÆæßÉ !"#¤%&\'()*+,-./0123456789:;<=>?' +
  '¡ABCDEFGHIJKLMNOPQRSTUVWXYZÄÖÑܧ¿abcdefghijklmnopqrstuvwxyzäöñüà'
);
const GSM7_EXTENDED = new Set('^{}\\[~]|€\f');   // each costs 2 characters

export function smsParts(text) {
  const chars = [...text];                        // iterate by code point
  if (chars.every((ch) => GSM7_BASIC.has(ch) || GSM7_EXTENDED.has(ch))) {
    const length = chars.reduce((n, ch) => n + (GSM7_EXTENDED.has(ch) ? 2 : 1), 0);
    return { encoding: 'GSM-7', length, parts: length <= 160 ? 1 : Math.ceil(length / 153) };
  }
  // JS strings are UTF-16, so .length is exactly the unit UCS-2 SMS counts (emoji = 2)
  const length = text.length;
  return { encoding: 'UCS-2', length, parts: length <= 70 ? 1 : Math.ceil(length / 67) };
}

console.log(smsParts('Your OTP for login is 482913. It is valid for 10 minutes. Do not share it with anyone. -AVNZON'));
// { encoding: 'GSM-7', length: 94, parts: 1 }
console.log(smsParts('உங்கள் OTP 482913. 10 நிமிடங்கள் செல்லுபடியாகும். -AVNZON'));
// { encoding: 'UCS-2', length: 57, parts: 1 }
console.log(smsParts('Price drop: ₹1,499 on all {winter} jackets this week. -AVNZON'));
// { encoding: 'UCS-2', length: 61, parts: 1 }
console.log(smsParts('Use code {SAVE10} at checkout. -AVNZON'.repeat(5)));
// { encoding: 'GSM-7', length: 200, parts: 2 }

// sms-client.d.mts
export interface QueuedSms {
  message_id: number;
  queue_id: number;
  status: 'queued';
  estimated_delivery: string;
}
export type DeliveryStatus = 'queued' | 'sent' | 'delivered' | 'failed';

export interface SendOptions {
  route?: 'transactional' | 'promotional';
  dlt_template_id?: string;
  dlt_entity_id?: string;
  unicode?: boolean;
  flash?: boolean;
  schedule_at?: string;            // ISO 8601, in the future
}

export interface SmsClient {
  send(to: string, message: string, senderId: string, extra?: SendOptions): Promise<QueuedSms>;
  sendBulk(recipients: string[], message: string, senderId: string, extra?: SendOptions): Promise<unknown>;
  status(messageId: number | string): Promise<DeliveryStatus>;
  balance(): Promise<{ balance: number; currency: 'INR'; last_updated: string }>;
}

export function createSmsClient(opts: {
  apiKey: string; baseUrl?: string; timeoutMs?: number; maxAttempts?: number;
}): SmsClient;