GateWire Node.js SDK

The official Node.js library for the GateWire SMS Infrastructure.

Send OTPs, alerts, and notifications to North African carriers (Mobilis, Djezzy, Ooredoo) using our decentralized mesh network.

Features

• TypeScript Support: Fully typed for better DX.
• Promise-based: Works with async/await.
• Error Handling: Clean error messages for API failures via GateWireError.

Installation

npm install gatewire
# or
yarn add gatewire

Quick Start

import { GateWireClient, GateWireError } from 'gatewire';

const gw = new GateWireClient({ apiKey: 'sk_live_YOUR_API_KEY' });

// 1. Send OTP
const { reference_id } = await gw.sendOtp({ phone: '+213770123456' });

// 2. (optional) Poll until sent
const status = await gw.getStatus(reference_id);

// 3. Verify code entered by the user
try {
  await gw.verifyOtp(reference_id, userEnteredCode);
  console.log('Verified!');
} catch (err) {
  if (err instanceof GateWireError) {
    console.error(err.message, err.statusCode);
  }
}

API Reference

gw.sendOtp(options)

Send an OTP to a phone number.

| Field | Type | Required | Description | |---|---|---|---| | phone | string | Yes | E.164 format, e.g. +213770123456 | | template_key | string | No | Dashboard template key (omit for default) |

Returns { reference_id: string, status: 'pending' }.

gw.verifyOtp(referenceId, code)

Verify the code entered by the end-user.

Returns { status: 'verified', message: string }. Throws GateWireError on invalid/expired codes.

gw.getStatus(referenceId)

Poll the delivery status of a previously sent OTP.

Returns { reference_id, status, created_at } where status is one of: pending | dispatched | sent | verified | failed | expired | cancelled

Error Handling

All API errors throw a GateWireError with:

| Property | Type | Description | |---|---|---| | message | string | Human-readable error from the API | | statusCode | number \| undefined | HTTP status code | | body | unknown | Raw response body |

Notable status codes: 402 (insufficient balance), 429 (rate limited), 503 (no devices available).

Development

Running tests

npm test              # run all tests
npm run test:coverage # run with coverage report

Tests use Jest + ts-jest. Axios is mocked — no real HTTP requests are made.

Building

npm run build   # compiles TypeScript to dist/

License

The GateWire Node.js SDK is open-sourced software licensed under the MIT license.