engagelab-otp 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# engagelab-otp · Node.js
+
+Official Node.js SDK for [EngageLab](https://www.engagelab.com) OTP.  
+Zero dependencies. Node.js 14+. TypeScript declarations included.
+
+## Install
+
+```bash
+npm install engagelab-otp
+```
+
+## Quick start
+
+```js
+const { OTPClient } = require('engagelab-otp');
+
+const otp = new OTPClient(
+  process.env.ENGAGELAB_DEV_KEY,
+  process.env.ENGAGELAB_DEV_SECRET
+);
+
+// Platform-generated OTP — easiest path
+const { message_id } = await otp.send('+6591234567', 'your-template-id', {}, 'en');
+const { verified }   = await otp.verify(message_id, userTypedCode);
+```
+
+## Two send modes
+
+| Mode                   | Method          | When to use |
+|------------------------|-----------------|-------------|
+| Platform-generated     | `otp.send()`    | EngageLab generates and stores the code. You only call `verify()` later. Simplest path. |
+| Caller-generated       | `otp.sendCustom()` | You generate the code yourself. EngageLab is just the carrier. Use when you need the code in your own DB. |
+
+```js
+// Platform-generated
+const r = await otp.send('+6591234567', 'tpl-id', { name: 'Alice' }, 'en');
+const v = await otp.verify(r.message_id, '123456');
+
+// Caller-generated
+await otp.sendCustom('+6591234567', 'custom-tpl', { code: '482910', name: 'Alice' });
+```
+
+## Webhook callbacks
+
+EngageLab signs callbacks with `X-CALLBACK-ID` (HMAC-SHA256). The SDK verifies signatures and parses events for you.
+
+> Whitelist source IPs in your firewall: `119.8.170.74`, `114.119.180.30`
+
+```js
+const express = require('express');
+const { WebhookVerifier } = require('engagelab-otp');
+
+const app = express();
+app.use(express.json());
+
+const verifier = new WebhookVerifier({
+  username: process.env.ENGAGELAB_WEBHOOK_USERNAME,
+  secret:   process.env.ENGAGELAB_WEBHOOK_SECRET,
+});
+
+app.post('/webhook', verifier.middleware(async (events) => {
+  for (const e of events) {
+    if (e.kind !== 'message_status') continue;
+
+    if (!e.is_terminal) {
+      // mid-flight (e.g. fallback in progress) — wait, do not act
+      continue;
+    }
+
+    if (e.status === 'delivered')        await markDelivered(e.message_id);
+    else if (e.status === 'verified')    await markVerified(e.message_id);
+    else                                  await handleFailure(e);
+  }
+}));
+```
+
+## Event types
+
+`parseEvents()` returns one of four typed objects:
+
+| `kind`           | When                                  | Key fields |
+|------------------|---------------------------------------|------------|
+| `message_status` | per-message lifecycle                 | `message_id`, `status`, `is_terminal`, `current_send_channel`, `error_code` |
+| `notification`   | account-level alert                   | `event` (`insufficient_balance`, …), `data` |
+| `uplink`         | inbound user reply                    | `from`, `to`, `body` |
+| `system_event`   | console action audit                  | `event` (`account_login`, …) |
+
+### Message status enum
+
+```
+plan · target_valid · target_invalid
+sent · sent_failed
+delivered · delivered_failed
+verified · verified_failed · verified_timeout
+```
+
+`is_terminal === true` for: `delivered`, `delivered_failed`, `sent_failed`, `verified*`, `target_invalid`.
+
+## Error handling
+
+```js
+const { EngagelabError } = require('engagelab-otp');
+
+try {
+  await otp.send('+6591234567', 'tpl', {});
+} catch (err) {
+  if (err instanceof EngagelabError) {
+    if (err.retryable) {
+      // HTTP 429/5xx, or API codes 1000/5001/5016
+      // → exponential backoff
+    } else {
+      // Permanent failure — fix your call or notify the user
+      console.log(err.code, err.httpStatus, err.message);
+    }
+  }
+}
+```
+
+## Examples
+
+See [`examples/`](./examples) for runnable code:
+
+- `01-send-and-verify.js` — platform-generated OTP, full flow
+- `02-send-custom.js` — caller-generated code, single + bulk
+- `03-webhook-express.js` — receive callbacks via Express middleware
+- `04-error-handling.js` — retry strategy and error categorization
+
+## Run tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "engagelab-otp",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for EngageLab OTP — send, verify, and parse webhook callbacks",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/engagelab/engagelab-otp-node.git"
+  },
+  "homepage": "https://www.engagelab.com",
+  "keywords": [
+    "engagelab",
+    "otp",
+    "sms",
+    "verification",
+    "webhook",
+    "two-factor",
+    "2fa"
+  ],
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "dependencies": {
+    "engagelab-otp": "file:engagelab-otp-1.0.0.tgz"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,93 @@
+export interface SendResult {
+  message_id: string;
+  send_channel: 'sms' | 'whatsapp' | 'email' | 'voice';
+}
+
+export interface VerifyResult {
+  message_id: string;
+  verify_code: string;
+  verified: boolean;
+}
+
+export type MessageStatus =
+  | 'plan'
+  | 'target_valid' | 'target_invalid'
+  | 'sent' | 'sent_failed' | 'sent_fail'
+  | 'delivered' | 'delivered_failed'
+  | 'verified' | 'verified_failed' | 'verified_timeout';
+
+export interface MessageStatusEvent {
+  kind: 'message_status';
+  message_id: string;
+  to: string;
+  server: string;
+  channel: string;
+  timestamp: number;
+  custom_args: Record<string, unknown>;
+  status: MessageStatus;
+  is_terminal: boolean;
+  current_send_channel?: string;
+  template_key?: string;
+  business_id?: string;
+  msg_time?: number;
+  billing: { cost: number; currency: string } | null;
+  error_code: number;
+  error_message?: string;
+  raw: unknown;
+}
+
+export interface NotificationEvent {
+  kind: 'notification';
+  server: string;
+  timestamp: number;
+  event: 'insufficient_verification_rate' | 'insufficient_balance' | 'template_audit_result' | string;
+  data: Record<string, unknown>;
+  raw: unknown;
+}
+
+export interface UplinkEvent {
+  kind: 'uplink';
+  server: string;
+  timestamp: number;
+  message_id: string;
+  business_id: string;
+  event: 'uplink_message' | string;
+  data: { from: string; to: string; body: string; message_sid: string; account_sid: string };
+  raw: unknown;
+}
+
+export interface SystemEvent {
+  kind: 'system_event';
+  server: string;
+  timestamp: number;
+  event: 'account_login' | 'key_manage' | 'template_manage' | 'msg_history' | 'api_call' | string;
+  data: Record<string, unknown>;
+  raw: unknown;
+}
+
+export type CallbackEvent = MessageStatusEvent | NotificationEvent | UplinkEvent | SystemEvent;
+
+export class EngagelabError extends Error {
+  code: number;
+  httpStatus: number;
+  retryable: boolean;
+}
+export class WebhookSignatureError extends Error {}
+
+export const TERMINAL_STATUSES: Set<MessageStatus>;
+
+export class OTPClient {
+  constructor(devKey: string, devSecret: string, opts?: { timeout?: number });
+  send(to: string, templateId: string, params?: Record<string, string>, language?: string): Promise<SendResult>;
+  sendCustom(to: string | string[], templateId: string, params?: Record<string, string>): Promise<SendResult>;
+  verify(messageId: string, code: string): Promise<VerifyResult>;
+}
+
+export class WebhookVerifier {
+  constructor(opts: { username: string; secret: string; toleranceSeconds?: number });
+  verify(headerValue: string, now?: number): true;
+  parseEvents(body: string | object): CallbackEvent[];
+  middleware(
+    handler: (events: CallbackEvent[], req: any) => Promise<void> | void
+  ): (req: any, res: any) => Promise<void>;
+}

package/src/index.js

@@ -0,0 +1,318 @@
+'use strict';
+
+const https = require('https');
+const crypto = require('crypto');
+const { URL } = require('url');
+
+const SDK_VERSION = '1.0.0';
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+const RETRYABLE_API_CODES = new Set([1000, 5001, 5016]);
+const RETRYABLE_HTTP      = new Set([429, 500, 502, 503, 504]);
+
+class EngagelabError extends Error {
+  constructor(message, code = 0, httpStatus = 0) {
+    super(message);
+    this.name = 'EngagelabError';
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.retryable = RETRYABLE_API_CODES.has(code) || RETRYABLE_HTTP.has(httpStatus);
+  }
+}
+
+class WebhookSignatureError extends Error {
+  constructor(message) { super(message); this.name = 'WebhookSignatureError'; }
+}
+
+// ─── HTTP helper ──────────────────────────────────────────────────────────────
+
+function request({ url, auth, body, timeout }) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const payload = JSON.stringify(body);
+    const req = https.request({
+      hostname: u.hostname,
+      port: u.port || 443,
+      path: u.pathname + u.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+        'Authorization': auth,
+        'User-Agent': `engagelab-otp-node/${SDK_VERSION}`,
+      },
+      timeout: timeout || 10000,
+    }, (res) => {
+      let data = '';
+      res.on('data', c => { data += c; });
+      res.on('end', () => {
+        let json;
+        try { json = JSON.parse(data); } catch (_) { json = { message: data }; }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(json);
+        } else {
+          reject(new EngagelabError(json.message || 'Unknown error', json.code || 0, res.statusCode));
+        }
+      });
+    });
+    req.on('timeout', () => { req.destroy(); reject(new EngagelabError('Request timed out', 0, 0)); });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+// ─── OTPClient ────────────────────────────────────────────────────────────────
+
+/**
+ * Client for the EngageLab OTP API.
+ * Covers both modes:
+ *   - send()       → platform generates the code  (POST /v1/messages)
+ *   - sendCustom() → caller supplies the code     (POST /v1/custom-messages)
+ *   - verify()     → verify user-entered code     (POST /v1/verifications)
+ */
+class OTPClient {
+  /**
+   * @param {string} devKey
+   * @param {string} devSecret
+   * @param {object} [opts]
+   * @param {number} [opts.timeout=10000]
+   */
+  constructor(devKey, devSecret, opts = {}) {
+    if (!devKey || !devSecret) throw new Error('devKey and devSecret are required');
+    this._auth    = 'Basic ' + Buffer.from(`${devKey}:${devSecret}`).toString('base64');
+    this._timeout = opts.timeout || 10000;
+    this._base    = 'https://otp.api.engagelab.cc/v1';
+  }
+
+  _post(path, body) {
+    return request({ url: this._base + path, auth: this._auth, timeout: this._timeout, body });
+  }
+
+  /**
+   * Send an OTP — platform generates the code.
+   * @param {string}   to                       E.164 phone or email
+   * @param {string}   templateId
+   * @param {object}   [params]                 extra template variables (no `code`, platform fills it)
+   * @param {string}   [language='default']     default | zh_CN | zh_HK | en | ja | th | es
+   * @returns {Promise<{ message_id: string, send_channel: string }>}
+   */
+  send(to, templateId, params = {}, language = 'default') {
+    if (!to)         throw new Error('to is required');
+    if (!templateId) throw new Error('templateId is required');
+    return this._post('/messages', {
+      to,
+      template: { id: templateId, language, params },
+    });
+  }
+
+  /**
+   * Send a custom message — caller supplies all template variables (including `code`).
+   * @param {string|string[]}        to
+   * @param {string}                 templateId
+   * @param {object}                 [params]
+   * @returns {Promise<{ message_id: string, send_channel: string }>}
+   */
+  sendCustom(to, templateId, params = {}) {
+    if (!to)         throw new Error('to is required');
+    if (!templateId) throw new Error('templateId is required');
+    return this._post('/custom-messages', {
+      to,
+      template: { id: templateId, params },
+    });
+  }
+
+  /**
+   * Verify a code the user entered.
+   * @param {string} messageId
+   * @param {string} code
+   * @returns {Promise<{ message_id: string, verify_code: string, verified: boolean }>}
+   */
+  verify(messageId, code) {
+    if (!messageId) throw new Error('messageId is required');
+    if (!code)      throw new Error('code is required');
+    return this._post('/verifications', {
+      message_id:  messageId,
+      verify_code: String(code),
+    });
+  }
+}
+
+// ─── WebhookVerifier ──────────────────────────────────────────────────────────
+
+const TERMINAL_STATUSES = new Set([
+  'delivered',
+  'delivered_failed',
+  'sent_failed',
+  'sent_fail',
+  'verified',
+  'verified_failed',
+  'verified_timeout',
+  'target_invalid',
+]);
+
+/**
+ * Verifies and parses EngageLab OTP webhook callbacks.
+ *
+ * EngageLab signs each callback with header X-CALLBACK-ID:
+ *   timestamp={ts};nonce={n};username={u};signature={sig}
+ * where signature = HMAC-SHA256(secret, `${ts}${nonce}${username}`).hexdigest()
+ *
+ * Source webhook IPs to whitelist: 119.8.170.74, 114.119.180.30
+ */
+class WebhookVerifier {
+  /**
+   * @param {object}  opts
+   * @param {string}  opts.username
+   * @param {string}  opts.secret
+   * @param {number}  [opts.toleranceSeconds=300]
+   */
+  constructor({ username, secret, toleranceSeconds = 300 } = {}) {
+    if (!username || !secret) throw new Error('username and secret are required');
+    this._username = username;
+    this._secret   = secret;
+    this._tol      = toleranceSeconds;
+  }
+
+  /**
+   * Verify the X-CALLBACK-ID header. Throws WebhookSignatureError on failure.
+   */
+  verify(headerValue, now = Math.floor(Date.now() / 1000)) {
+    if (!headerValue) throw new WebhookSignatureError('missing X-CALLBACK-ID header');
+
+    const parts = {};
+    for (const seg of headerValue.split(';')) {
+      const idx = seg.indexOf('=');
+      if (idx > 0) parts[seg.slice(0, idx).trim()] = seg.slice(idx + 1).trim();
+    }
+
+    const { timestamp, nonce, username, signature } = parts;
+    if (!timestamp || !nonce || !username || !signature) {
+      throw new WebhookSignatureError('malformed X-CALLBACK-ID header');
+    }
+    if (username !== this._username) {
+      throw new WebhookSignatureError('username mismatch');
+    }
+
+    const ts = parseInt(timestamp, 10);
+    if (!Number.isFinite(ts) || Math.abs(now - ts) > this._tol) {
+      throw new WebhookSignatureError('timestamp outside tolerance window');
+    }
+
+    const expected = crypto
+      .createHmac('sha256', this._secret)
+      .update(`${timestamp}${nonce}${username}`)
+      .digest('hex');
+
+    const a = Buffer.from(expected, 'hex');
+    const b = Buffer.from(signature, 'hex');
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
+      throw new WebhookSignatureError('signature mismatch');
+    }
+    return true;
+  }
+
+  /**
+   * Parse a callback body into typed events.
+   */
+  parseEvents(body) {
+    const obj = typeof body === 'string' ? JSON.parse(body) : body;
+    const rows = Array.isArray(obj.rows) ? obj.rows : [];
+    return rows.map(parseRow).filter(Boolean);
+  }
+
+  /**
+   * Express-style middleware factory.
+   *   app.post('/webhook', verifier.middleware(handler))
+   */
+  middleware(handler) {
+    return async (req, res) => {
+      try {
+        this.verify(req.headers['x-callback-id'] || req.headers['X-CALLBACK-ID']);
+      } catch (err) {
+        return res.status(401).end();
+      }
+      try {
+        const events = this.parseEvents(req.body);
+        await handler(events, req);
+      } catch (err) {
+        // Always 200 on internal errors to avoid retry storms.
+        if (typeof console !== 'undefined') console.error('engagelab webhook handler error:', err);
+      }
+      res.status(200).end();
+    };
+  }
+}
+
+// ─── Internal: row → typed event ──────────────────────────────────────────────
+
+function parseRow(row) {
+  if (!row || typeof row !== 'object') return null;
+
+  if (row.status && typeof row.status.message_status === 'string') {
+    const s  = row.status;
+    const sd = s.status_data || {};
+    const ed = s.error_detail || {};
+    return {
+      kind: 'message_status',
+      message_id: row.message_id,
+      to: row.to,
+      server: row.server,
+      channel: row.channel,
+      timestamp: row.itime,
+      custom_args: row.custom_args || {},
+      status: s.message_status,
+      is_terminal: TERMINAL_STATUSES.has(s.message_status),
+      current_send_channel: sd.current_send_channel,
+      template_key: sd.template_key,
+      business_id:  sd.business_id,
+      msg_time:     sd.msg_time,
+      billing: s.billing || null,
+      error_code: s.error_code || 0,
+      error_message: ed.message,
+      raw: row,
+    };
+  }
+  if (row.notification) {
+    return {
+      kind: 'notification',
+      server: row.server,
+      timestamp: row.itime,
+      event: row.notification.event,
+      data: row.notification.notification_data,
+      raw: row,
+    };
+  }
+  if (row.response) {
+    return {
+      kind: 'uplink',
+      server: row.server,
+      timestamp: row.itime,
+      message_id: row.message_id,
+      business_id: row.business_id,
+      event: row.response.event,
+      data: row.response.response_data,
+      raw: row,
+    };
+  }
+  if (row.system_event) {
+    return {
+      kind: 'system_event',
+      server: row.server,
+      timestamp: row.itime,
+      event: row.system_event.event,
+      data: row.system_event.data,
+      raw: row,
+    };
+  }
+  return null;
+}
+
+module.exports = {
+  OTPClient,
+  WebhookVerifier,
+  EngagelabError,
+  WebhookSignatureError,
+  TERMINAL_STATUSES,
+};