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/sdkwill 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/sdkimport { 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
| Types | Verification, SendResult, CheckResult, Balance and ApiErrorCode match the API contract exactly (checked by OTP.ps's tests at compile time). |
| Errors | Every failure is an OtpPsError with code (an API error code, or network_error, timeout, server_error), status, retryAfter and retryable. |
| Timeouts | timeoutMs, default 15 seconds per attempt. |
| Safe retries | Sends 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. |
| Sandbox | otp.mode is "test" with a test key; SANDBOX_NUMBERS and SANDBOX_CODE give the sandbox numbers. |
| Numbers | normalizePhone(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 usedOptions
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"