# 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](/docs/examples/javascript-typescript), 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.

```bash
npm install @otp-ps/sdk
```

```ts
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

| | |
|---|---|
| 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](/docs/sandbox). |
| Numbers | `normalizePhone(raw)` → `+9705XXXXXXXX` or `null`, the API's rules. |

## Account information

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

## Options

```ts
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

```ts
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

```ts
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"
```
