SDKs

JavaScript / TypeScript SDK

@otp-ps/sdk: typed client with safe retries, timeouts, sandbox helpers and phone validation.

Status: ready, not yet published. @otp-ps/sdk will be on npm once OTP.ps releases it. Until then, use the TypeScript example client, which has the same calls.

Server-side only: Node.js 20+, Bun, Deno, Cloudflare Workers, Vercel and Next.js server code. No dependencies. It refuses to start in a browser, where the key would be public.

npm install @otp-ps/sdk
import { OtpPs, OtpPsError } from "@otp-ps/sdk";

const otp = new OtpPs(); // reads OTP_PS_API_KEY (and OTP_PS_BASE_URL)

const v = await otp.verify.send({ phone: "0599123456", purpose: "order", locale: "ar" });
// keep v.id on your server

const r = await otp.verify.check({ id: v.id, code: codeFromCustomer });
if (r.valid) {
  // verified
}

What it handles for you

TypesVerification, SendResult, CheckResult, Balance and ApiErrorCode match the API contract exactly (checked by OTP.ps's tests at compile time).
ErrorsEvery failure is an OtpPsError with code (an API error code, or network_error, timeout, server_error), status, retryAfter and retryable.
TimeoutstimeoutMs, default 15 seconds per attempt.
Safe retriesSends always carry an Idempotency-Key (yours or a generated one), so after a network failure or server error the SDK retries them (maxRetries, default 2) without sending or charging twice. Checks are never retried: a lost answer may already have used an attempt or approved the code.
Sandboxotp.mode is "test" with a test key; SANDBOX_NUMBERS and SANDBOX_CODE give the sandbox numbers.
NumbersnormalizePhone(raw) → +9705XXXXXXXX or null, the API's rules.

Account information

const usage = await otp.usage();   // today, this month, last 30 days
const limits = await otp.limits(); // permissions, spending limits and what's used

Options

new OtpPs({
  apiKey: "otp_test_…",        // default: OTP_PS_API_KEY
  baseUrl: "https://otp.ps",      // default: OTP_PS_BASE_URL, else https://otp.ps
  timeoutMs: 15_000,
  maxRetries: 2,
  fetch: customFetch,           // optional
});

Errors

try {
  await otp.verify.send({ phone, idempotencyKey: `order-${orderId}-otp-1` });
} catch (e) {
  if (!(e instanceof OtpPsError)) throw e;
  switch (e.code) {
    case "invalid_phone":
    case "unsupported_network":
      return showError("Please check the number (Jawwal or Ooredoo only).");
    case "rate_limited":
      return showCountdown(e.retryAfter ?? 30);
    default:
      alertTeam(e); // insufficient_balance, unauthorized, network_error…
      return showError("Verification isn't available right now.");
  }
}

Testing with the sandbox

import { OtpPs, SANDBOX_CODE, SANDBOX_NUMBERS } from "@otp-ps/sdk";

const otp = new OtpPs({ apiKey: process.env.OTP_PS_TEST_KEY });
const v = await otp.verify.send({ phone: SANDBOX_NUMBERS.success });
const r = await otp.verify.check({ id: v.id, code: SANDBOX_CODE }); // r.valid === true
await otp.verify.send({ phone: SANDBOX_NUMBERS.smsFailed }); // throws OtpPsError "sms_failed"

View as Markdown