@eilya/otp-js

Official Web/JS SDK for Eilya OTP -- WhatsApp-first OTP verification with SMS fallback.

Zero dependencies. Works in browsers, Node.js 18+, and edge runtimes.

Installation

npm install @eilya/otp-js

Quick Start

import { EilyaOtp, EilyaError } from '@eilya/otp-js';

const otp = new EilyaOtp({
  apiKey: 'ek_live_your_api_key_here',
});

// 1. Request OTP
const pipeline = await otp.requestOtp({
  phone: '+964XXXXXXXXXX',
});

console.log(`OTP sent via ${pipeline.channelUsed}`);

// 2. Verify OTP (code entered by user)
try {
  const result = await otp.verifyOtp({
    pipelineId: pipeline.pipelineId,
    otp: '123456',
  });

  console.log('Verified! Auth token:', result.authToken);
} catch (err) {
  if (err instanceof EilyaError) {
    switch (err.code) {
      case 'INVALID_OTP':
        console.log(`Wrong code. ${err.attemptsRemaining} attempts remaining.`);
        break;
      case 'PIPELINE_EXPIRED':
        console.log('OTP expired. Request a new one.');
        break;
      default:
        console.error(err.message);
    }
  }
}

Sandbox Mode

Use a test API key (prefix ek_test_) for development. In sandbox mode:

• No real messages are sent
• Use OTP code 123456 to verify

const otp = new EilyaOtp({
  apiKey: 'ek_test_your_test_key_here',
});

Configuration

const otp = new EilyaOtp({
  apiKey: 'ek_live_...',
  locale: 'en',                // 'ar' (default) or 'en'
  otpLength: 6,                // 4 or 6 (default: 6)
  expirySeconds: 300,          // 60-600 (default: 300)
  fallbackChannels: ['sms'],   // Fallback if WhatsApp fails
  timeout: 30000,              // Request timeout in ms
});

API Reference

new EilyaOtp(options)

Creates a new SDK instance.

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your Eilya API key | | baseUrl | string | https://api-otp.eilyatech.com | API base URL | | locale | 'ar' \| 'en' | 'ar' | OTP message locale | | otpLength | 4 \| 6 | 6 | OTP code length | | expirySeconds | number | 300 | OTP expiry (60-600) | | fallbackChannels | ('sms' \| 'email')[] | ['sms'] | Fallback channels | | timeout | number | 30000 | Request timeout (ms) | | fetch | typeof fetch | globalThis.fetch | Custom fetch |

requestOtp(params): Promise<Pipeline>

Sends an OTP to the given phone number.

const pipeline = await otp.requestOtp({
  phone: '+964XXXXXXXXXX',
  locale: 'en',          // optional override
  otpLength: 4,          // optional override
  expirySeconds: 120,    // optional override
  metadata: { userId: '123' },
});

verifyOtp(params): Promise<VerifyResult>

Verifies the OTP code. Returns an auth token on success.

const result = await otp.verifyOtp({
  pipelineId: 'pip_abc123',
  otp: '123456',
});
// result.authToken — pass to your backend

resendOtp(params): Promise<Pipeline>

Resends the OTP. Must wait 60 seconds between resends.

const updated = await otp.resendOtp({
  pipelineId: 'pip_abc123',
  channel: 'sms', // optional: force a specific channel
});

getPipeline(pipelineId): Promise<Pipeline>

Retrieves the current status of a pipeline.

const pipeline = await otp.getPipeline('pip_abc123');

Error Handling

All errors are instances of EilyaError:

import { EilyaError } from '@eilya/otp-js';

try {
  await otp.verifyOtp({ pipelineId, otp });
} catch (err) {
  if (err instanceof EilyaError) {
    console.log(err.code);    // 'INVALID_OTP'
    console.log(err.message); // Human-readable message
    console.log(err.statusCode); // 400
  }
}

| Code | HTTP | When | |---|---|---| | INVALID_OTP | 400 | Wrong OTP code | | PIPELINE_EXPIRED | 400 | OTP timed out | | PIPELINE_NOT_FOUND | 404 | Invalid pipeline ID | | PIPELINE_NOT_PENDING | 400 | Pipeline already verified/failed | | QUOTA_EXCEEDED | 402 | Account quota reached | | RATE_LIMITED | 429 | Too many requests | | RESEND_RATE_LIMITED | 429 | Resend too soon (wait 60s) | | DELIVERY_FAILED | 502 | All delivery channels failed | | UNAUTHORIZED | 401 | Invalid API key | | FORBIDDEN | 403 | Access denied | | NETWORK_ERROR | -- | Connection failure / timeout |

TypeScript

Full TypeScript support with all types exported:

import type {
  Pipeline,
  VerifyResult,
  EilyaOtpOptions,
  RequestOtpParams,
  EilyaErrorCode,
} from '@eilya/otp-js';

License

Proprietary -- Eilya Technologies