@smsdora/otp 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+/** Delivery channel. Only SMS is supported at launch. */
+type OtpChannel = 'sms';
+/** Lifecycle state of an OTP challenge. */
+type OtpStatus = 'pending' | 'verified' | 'expired' | 'failed' | 'locked';
+/** Options for constructing a {@link SmsdoraOtp} client. */
+interface SmsdoraOtpOptions {
+    /** Secret API key (`smsgw_...`) with the `otp:send` / `otp:verify` scopes. */
+    apiKey: string;
+    /** Base URL of your SmsDora backend, e.g. `https://api.example.com`. */
+    baseUrl: string;
+    /**
+     * Shared `OTP_TOKEN_SECRET` from your backend. Required only if you call
+     * {@link SmsdoraOtp.verifyToken} to validate verification tokens locally.
+     */
+    tokenSecret?: string;
+    /** Per-request timeout in milliseconds. Default: 10000. */
+    timeoutMs?: number;
+    /** Max retry attempts for network / 5xx / 429 failures. Default: 2. */
+    maxRetries?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+interface SendOtpParams {
+    /** Recipient phone number (E.164 recommended, e.g. `+14155550100`). */
+    recipient: string;
+    /** Caller tag echoed back in the verification token, e.g. `"login"`. */
+    purpose?: string;
+    /** Code length, 4–8. Defaults to the backend's configured length. */
+    codeLength?: number;
+    /** Time-to-live in seconds, 60–900. Defaults to the backend's config. */
+    ttlSeconds?: number;
+    /** Override the SMS body. Must contain the `{{code}}` placeholder. */
+    templateOverride?: string;
+    /** Pin delivery to a specific device id (otherwise auto-selected). */
+    deviceId?: string;
+    /** Opaque data stored on the challenge. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Idempotency key for safe retries. Auto-generated per call if omitted.
+     * Reusing a key lets the server de-duplicate retried sends.
+     */
+    idempotencyKey?: string;
+}
+interface ResendOtpParams {
+    challengeId: string;
+}
+interface VerifyOtpParams {
+    challengeId: string;
+    /** The numeric code the user supplied. */
+    code: string;
+}
+/** A challenge as returned by send / resend / getStatus. */
+interface OtpChallenge {
+    id: string;
+    /** Masked recipient, e.g. `+141******00`. */
+    recipient: string;
+    purpose: string | null;
+    channel: OtpChannel;
+    status: OtpStatus;
+    expiresAt: string;
+    resendAvailableAt: string | null;
+    attemptsRemaining: number;
+    resendsRemaining: number;
+    createdAt: string;
+}
+/** Result of a verify attempt. */
+interface VerifyResult {
+    verified: boolean;
+    status: OtpStatus;
+    attemptsRemaining: number;
+    /** Present only when `verified` is true. */
+    verificationToken?: string;
+    verificationTokenExpiresAt?: string;
+}
+/** Decoded verification-token claims. */
+interface VerificationTokenPayload {
+    /** Subject — the verified recipient (E.164). */
+    sub: string;
+    challengeId: string;
+    purpose: string | null;
+    /** Unique token id. */
+    jti: string;
+    /** Issued-at (epoch seconds). */
+    iat?: number;
+    /** Expiry (epoch seconds). */
+    exp?: number;
+}
+/** Result of a server-side single-use token check. */
+interface TokenCheckResult {
+    recipient: string;
+    purpose: string | null;
+    challengeId: string;
+}
+
+/**
+ * Client for the SmsDora OTP API.
+ *
+ * ```ts
+ * const otp = new SmsdoraOtp({ apiKey: process.env.SMSDORA_KEY!, baseUrl });
+ * const challenge = await otp.send({ recipient: '+14155550100', purpose: 'login' });
+ * const result = await otp.verify({ challengeId: challenge.id, code });
+ * if (result.verified) { ... }
+ * ```
+ */
+declare class SmsdoraOtp {
+    private readonly http;
+    private readonly tokenSecret?;
+    constructor(options: SmsdoraOtpOptions);
+    /** Send a one-time passcode to a phone number. */
+    send(params: SendOtpParams): Promise<OtpChallenge>;
+    /** Re-deliver the code for an existing challenge (subject to cooldown/cap). */
+    resend(params: ResendOtpParams): Promise<OtpChallenge>;
+    /** Verify a code. Returns a result; does NOT throw on a wrong code. */
+    verify(params: VerifyOtpParams): Promise<VerifyResult>;
+    /** Fetch the current status of a challenge. */
+    getStatus(challengeId: string): Promise<OtpChallenge>;
+    /**
+     * Validate a verification token locally (no network). Requires `tokenSecret`
+     * in the client options. Use this in your auth flow to trust a verification
+     * without an extra round-trip.
+     *
+     * @throws {ConfigError} if no `tokenSecret` was configured.
+     * @throws {TokenVerificationError} if the token is invalid/expired.
+     */
+    verifyToken(token: string): VerificationTokenPayload;
+    /**
+     * Validate a verification token on the server with single-use enforcement.
+     * Marks the token consumed so it cannot be replayed.
+     */
+    verifyTokenRemote(token: string): Promise<TokenCheckResult>;
+}
+
+/**
+ * Verify a SmsDora verification token (HS256 JWT) locally — no network call.
+ * Checks the signature against `secret` and enforces `exp` / `nbf`.
+ *
+ * @throws {TokenVerificationError} if malformed, wrong algorithm, bad
+ *   signature, or expired.
+ */
+declare function verifyVerificationToken(token: string, secret: string): VerificationTokenPayload;
+
+/** Stable error codes — safe to branch on across SDK versions. */
+type SmsdoraOtpErrorCode = 'config_error' | 'auth_error' | 'validation_error' | 'not_found' | 'rate_limited' | 'delivery_failed' | 'server_error' | 'network_error' | 'token_invalid';
+interface SmsdoraOtpErrorContext {
+    code: SmsdoraOtpErrorCode;
+    /** HTTP status, when the error originated from a response. */
+    status?: number;
+    /** Server request id, if provided. */
+    requestId?: string;
+    /** Underlying cause (e.g. a fetch error). */
+    cause?: unknown;
+}
+/** Base class for every error the SDK throws. */
+declare class SmsdoraOtpError extends Error {
+    readonly code: SmsdoraOtpErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    constructor(message: string, ctx: SmsdoraOtpErrorContext);
+}
+/** Missing/invalid client configuration (no apiKey, no tokenSecret, …). */
+declare class ConfigError extends SmsdoraOtpError {
+    constructor(message: string);
+}
+/** 401 / 403 — bad or unauthorized API key, scope, or publishable restriction. */
+declare class AuthError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 400 — invalid request parameters. */
+declare class ValidationError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 404 — challenge/key not found. */
+declare class NotFoundError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 429 — a rate/abuse cap was hit. Inspect {@link retryAfterSeconds}. */
+declare class RateLimitError extends SmsdoraOtpError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'> & {
+        retryAfterSeconds?: number;
+    });
+}
+/** 502 — the code could not be delivered (no online device / FCM failure). */
+declare class DeliveryError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 5xx — an unexpected server error. */
+declare class ServerError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** Transport failure — connection refused, DNS, timeout, aborted. */
+declare class NetworkError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** A verification token failed local or remote validation. */
+declare class TokenVerificationError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+
+export { AuthError, ConfigError, DeliveryError, NetworkError, NotFoundError, type OtpChallenge, type OtpChannel, type OtpStatus, RateLimitError, type ResendOtpParams, type SendOtpParams, ServerError, SmsdoraOtp, SmsdoraOtpError, type SmsdoraOtpErrorCode, type SmsdoraOtpOptions, type TokenCheckResult, TokenVerificationError, ValidationError, type VerificationTokenPayload, type VerifyOtpParams, type VerifyResult, verifyVerificationToken };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+/** Delivery channel. Only SMS is supported at launch. */
+type OtpChannel = 'sms';
+/** Lifecycle state of an OTP challenge. */
+type OtpStatus = 'pending' | 'verified' | 'expired' | 'failed' | 'locked';
+/** Options for constructing a {@link SmsdoraOtp} client. */
+interface SmsdoraOtpOptions {
+    /** Secret API key (`smsgw_...`) with the `otp:send` / `otp:verify` scopes. */
+    apiKey: string;
+    /** Base URL of your SmsDora backend, e.g. `https://api.example.com`. */
+    baseUrl: string;
+    /**
+     * Shared `OTP_TOKEN_SECRET` from your backend. Required only if you call
+     * {@link SmsdoraOtp.verifyToken} to validate verification tokens locally.
+     */
+    tokenSecret?: string;
+    /** Per-request timeout in milliseconds. Default: 10000. */
+    timeoutMs?: number;
+    /** Max retry attempts for network / 5xx / 429 failures. Default: 2. */
+    maxRetries?: number;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+interface SendOtpParams {
+    /** Recipient phone number (E.164 recommended, e.g. `+14155550100`). */
+    recipient: string;
+    /** Caller tag echoed back in the verification token, e.g. `"login"`. */
+    purpose?: string;
+    /** Code length, 4–8. Defaults to the backend's configured length. */
+    codeLength?: number;
+    /** Time-to-live in seconds, 60–900. Defaults to the backend's config. */
+    ttlSeconds?: number;
+    /** Override the SMS body. Must contain the `{{code}}` placeholder. */
+    templateOverride?: string;
+    /** Pin delivery to a specific device id (otherwise auto-selected). */
+    deviceId?: string;
+    /** Opaque data stored on the challenge. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Idempotency key for safe retries. Auto-generated per call if omitted.
+     * Reusing a key lets the server de-duplicate retried sends.
+     */
+    idempotencyKey?: string;
+}
+interface ResendOtpParams {
+    challengeId: string;
+}
+interface VerifyOtpParams {
+    challengeId: string;
+    /** The numeric code the user supplied. */
+    code: string;
+}
+/** A challenge as returned by send / resend / getStatus. */
+interface OtpChallenge {
+    id: string;
+    /** Masked recipient, e.g. `+141******00`. */
+    recipient: string;
+    purpose: string | null;
+    channel: OtpChannel;
+    status: OtpStatus;
+    expiresAt: string;
+    resendAvailableAt: string | null;
+    attemptsRemaining: number;
+    resendsRemaining: number;
+    createdAt: string;
+}
+/** Result of a verify attempt. */
+interface VerifyResult {
+    verified: boolean;
+    status: OtpStatus;
+    attemptsRemaining: number;
+    /** Present only when `verified` is true. */
+    verificationToken?: string;
+    verificationTokenExpiresAt?: string;
+}
+/** Decoded verification-token claims. */
+interface VerificationTokenPayload {
+    /** Subject — the verified recipient (E.164). */
+    sub: string;
+    challengeId: string;
+    purpose: string | null;
+    /** Unique token id. */
+    jti: string;
+    /** Issued-at (epoch seconds). */
+    iat?: number;
+    /** Expiry (epoch seconds). */
+    exp?: number;
+}
+/** Result of a server-side single-use token check. */
+interface TokenCheckResult {
+    recipient: string;
+    purpose: string | null;
+    challengeId: string;
+}
+
+/**
+ * Client for the SmsDora OTP API.
+ *
+ * ```ts
+ * const otp = new SmsdoraOtp({ apiKey: process.env.SMSDORA_KEY!, baseUrl });
+ * const challenge = await otp.send({ recipient: '+14155550100', purpose: 'login' });
+ * const result = await otp.verify({ challengeId: challenge.id, code });
+ * if (result.verified) { ... }
+ * ```
+ */
+declare class SmsdoraOtp {
+    private readonly http;
+    private readonly tokenSecret?;
+    constructor(options: SmsdoraOtpOptions);
+    /** Send a one-time passcode to a phone number. */
+    send(params: SendOtpParams): Promise<OtpChallenge>;
+    /** Re-deliver the code for an existing challenge (subject to cooldown/cap). */
+    resend(params: ResendOtpParams): Promise<OtpChallenge>;
+    /** Verify a code. Returns a result; does NOT throw on a wrong code. */
+    verify(params: VerifyOtpParams): Promise<VerifyResult>;
+    /** Fetch the current status of a challenge. */
+    getStatus(challengeId: string): Promise<OtpChallenge>;
+    /**
+     * Validate a verification token locally (no network). Requires `tokenSecret`
+     * in the client options. Use this in your auth flow to trust a verification
+     * without an extra round-trip.
+     *
+     * @throws {ConfigError} if no `tokenSecret` was configured.
+     * @throws {TokenVerificationError} if the token is invalid/expired.
+     */
+    verifyToken(token: string): VerificationTokenPayload;
+    /**
+     * Validate a verification token on the server with single-use enforcement.
+     * Marks the token consumed so it cannot be replayed.
+     */
+    verifyTokenRemote(token: string): Promise<TokenCheckResult>;
+}
+
+/**
+ * Verify a SmsDora verification token (HS256 JWT) locally — no network call.
+ * Checks the signature against `secret` and enforces `exp` / `nbf`.
+ *
+ * @throws {TokenVerificationError} if malformed, wrong algorithm, bad
+ *   signature, or expired.
+ */
+declare function verifyVerificationToken(token: string, secret: string): VerificationTokenPayload;
+
+/** Stable error codes — safe to branch on across SDK versions. */
+type SmsdoraOtpErrorCode = 'config_error' | 'auth_error' | 'validation_error' | 'not_found' | 'rate_limited' | 'delivery_failed' | 'server_error' | 'network_error' | 'token_invalid';
+interface SmsdoraOtpErrorContext {
+    code: SmsdoraOtpErrorCode;
+    /** HTTP status, when the error originated from a response. */
+    status?: number;
+    /** Server request id, if provided. */
+    requestId?: string;
+    /** Underlying cause (e.g. a fetch error). */
+    cause?: unknown;
+}
+/** Base class for every error the SDK throws. */
+declare class SmsdoraOtpError extends Error {
+    readonly code: SmsdoraOtpErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    constructor(message: string, ctx: SmsdoraOtpErrorContext);
+}
+/** Missing/invalid client configuration (no apiKey, no tokenSecret, …). */
+declare class ConfigError extends SmsdoraOtpError {
+    constructor(message: string);
+}
+/** 401 / 403 — bad or unauthorized API key, scope, or publishable restriction. */
+declare class AuthError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 400 — invalid request parameters. */
+declare class ValidationError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 404 — challenge/key not found. */
+declare class NotFoundError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 429 — a rate/abuse cap was hit. Inspect {@link retryAfterSeconds}. */
+declare class RateLimitError extends SmsdoraOtpError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'> & {
+        retryAfterSeconds?: number;
+    });
+}
+/** 502 — the code could not be delivered (no online device / FCM failure). */
+declare class DeliveryError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** 5xx — an unexpected server error. */
+declare class ServerError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** Transport failure — connection refused, DNS, timeout, aborted. */
+declare class NetworkError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+/** A verification token failed local or remote validation. */
+declare class TokenVerificationError extends SmsdoraOtpError {
+    constructor(message: string, ctx?: Omit<SmsdoraOtpErrorContext, 'code'>);
+}
+
+export { AuthError, ConfigError, DeliveryError, NetworkError, NotFoundError, type OtpChallenge, type OtpChannel, type OtpStatus, RateLimitError, type ResendOtpParams, type SendOtpParams, ServerError, SmsdoraOtp, SmsdoraOtpError, type SmsdoraOtpErrorCode, type SmsdoraOtpOptions, type TokenCheckResult, TokenVerificationError, ValidationError, type VerificationTokenPayload, type VerifyOtpParams, type VerifyResult, verifyVerificationToken };