@siymo/otp-sdk-core 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# siymo-otp-sdk
+
+TypeScript SDK for the REST and WebSocket contract exposed by `siymo-otp-service`.
+
+## Features
+
+- Typed wrappers for OTP voice, SMS, inbound call, inbound SMS, verification, direct SMS, dongles, and health endpoints
+- WebSocket subscription helper for `/ws/otp`
+- Live attempt and lockout events during OTP verification
+- `waitForConfirmation()` helper for inbound OTP confirmation flows
+- `waitForConfirmationLongPoll()` helper for one-request HTTP long polling
+- Base URL can be passed directly or resolved from environment variables
+
+## Install
+
+```bash
+npm install siymo-otp-sdk
+```
+
+## Configuration
+
+The client resolves the service base URL in this order:
+
+1. `baseUrl` passed to the constructor
+2. `SIYMO_OTP_BASE_URL`
+3. `OTP_BASE_URL`
+
+```ts
+import { SiymoOtpClient } from 'siymo-otp-sdk';
+
+const client = new SiymoOtpClient({
+  baseUrl: 'http://localhost:3000',
+});
+```
+
+Or with environment variables:
+
+```bash
+export SIYMO_OTP_BASE_URL=http://localhost:3000
+```
+
+```ts
+import { SiymoOtpClient } from 'siymo-otp-sdk';
+
+const client = new SiymoOtpClient();
+```
+
+## Usage
+
+### Outbound OTP
+
+```ts
+import { SiymoOtpClient } from 'siymo-otp-sdk';
+
+const client = new SiymoOtpClient();
+
+const session = await client.initiateVoice({
+  phone: '+998901234567',
+  languages: ['uz', 'ru', 'en'],
+  repeat: true,
+});
+
+const verification = await client.verify({
+  sessionId: session.sessionId,
+  otp: '123456',
+});
+```
+
+### Inbound OTP with WebSocket confirmation
+
+```ts
+import { SiymoOtpClient } from 'siymo-otp-sdk';
+
+const client = new SiymoOtpClient({
+  baseUrl: 'http://localhost:3000',
+});
+
+const session = await client.initiateInboundSms({
+  phone: '+998990649000',
+});
+
+const confirmed = await client.waitForConfirmation(session.sessionId, {
+  timeoutMs: session.expiresIn * 1000,
+  onAttempt(event) {
+    console.log('Invalid attempt', event.data.attempts, 'tries left', event.data.triesLeft);
+  },
+});
+
+console.log(confirmed.data.verifiedAt);
+```
+
+### Inbound OTP with HTTP long polling
+
+```ts
+import { SiymoOtpClient } from 'siymo-otp-sdk';
+
+const client = new SiymoOtpClient({
+  baseUrl: 'http://localhost:3000',
+});
+
+const session = await client.initiateInboundSms({
+  phone: '+998990649000',
+  expiration: 60,
+});
+
+const confirmed = await client.waitForConfirmationLongPoll(session.sessionId);
+
+console.log(confirmed.status, confirmed.verifiedAt);
+```
+
+### Low-level WebSocket subscription
+
+```ts
+const subscription = client.subscribeToSession(session.sessionId, {
+  onSubscribed(event) {
+    console.log('Subscribed until', event.data.expiresAt);
+  },
+  onAttempt(event) {
+    console.log('Attempts used', event.data.attempts, 'tries left', event.data.triesLeft);
+  },
+  onLocked(event) {
+    console.log('Locked after', event.data.attempts, 'attempts');
+  },
+  onVerified(event) {
+    console.log('Verified', event.data.sessionId);
+  },
+  onExpired(event) {
+    console.log('Expired', event.data.sessionId);
+  },
+});
+
+// Later, if needed:
+subscription.close();
+await subscription.closed;
+```
+
+## Notes
+
+- The SDK uses the service's existing WebSocket contract at `/ws/otp?sessionId=<uuid>`.
+- The SDK also supports the long-poll endpoint at `GET /otp/wait?sessionId=<uuid>`.
+- Inbound call and SMS initiation requests accept an optional `qrCode: true` flag. When requested, the response includes `qrCodeImage` as a data URL.
+- The WebSocket stream can emit `otp.subscribed`, `otp.attempt`, `otp.locked`, `otp.verified`, and `otp.expired`.
+- In modern Node runtimes such as Node `22.x`, `WebSocket` is available globally. If you need to override it, pass `webSocketFactory`.
+- `waitForConfirmation()` keeps waiting through `otp.attempt` events, forwards WebSocket callbacks like `onAttempt`, and rejects on `otp.locked` or `otp.expired`.
+- `waitForConfirmationLongPoll()` resolves on verification and rejects with the service error response if the session locks or expires.
+- Verification endpoints intentionally return `200 OK` for both success and logical verification failures. Inspect the typed response fields like `verified`, `message`, and `triesLeft`.

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { DongleDevice, HealthCheckResponse, InitiateInboundCallResponse, InitiateInboundRequest, InitiateInboundSmsResponse, InitiateSmsRequest, InitiateSmsResponse, InitiateVoiceRequest, InitiateVoiceResponse, OtpLongPollSuccessResponse, OtpSessionSubscription, OtpVerifiedEvent, SendSmsRequest, SendSmsResponse, SiymoOtpClientOptions, SubscribeToSessionOptions, VerifyInboundReceiptRequest, VerifyInboundResponse, VerifyOtpRequest, VerifyOtpResponse, WaitForConfirmationOptions, WaitForConfirmationLongPollOptions } from './types.js';
+export declare class SiymoOtpClient {
+    private readonly baseUrl;
+    private readonly websocketBaseUrl;
+    private readonly defaultHeaders;
+    private readonly fetchImpl;
+    private readonly webSocketFactory?;
+    constructor(options?: SiymoOtpClientOptions);
+    initiateVoice(body: InitiateVoiceRequest): Promise<InitiateVoiceResponse>;
+    initiateSms(body: InitiateSmsRequest): Promise<InitiateSmsResponse>;
+    initiateInboundCall(body: InitiateInboundRequest): Promise<InitiateInboundCallResponse>;
+    initiateInboundSms(body: InitiateInboundRequest): Promise<InitiateInboundSmsResponse>;
+    verify(body: VerifyOtpRequest): Promise<VerifyOtpResponse>;
+    verifyInbound(body: VerifyInboundReceiptRequest): Promise<VerifyInboundResponse>;
+    sendSms(body: SendSmsRequest): Promise<SendSmsResponse>;
+    listDongles(): Promise<DongleDevice[]>;
+    health(): Promise<HealthCheckResponse>;
+    subscribeToSession(sessionId: string, options?: SubscribeToSessionOptions): OtpSessionSubscription;
+    waitForConfirmation(sessionId: string, options?: WaitForConfirmationOptions): Promise<OtpVerifiedEvent>;
+    waitForConfirmationLongPoll(sessionId: string, options?: WaitForConfirmationLongPollOptions): Promise<OtpLongPollSuccessResponse>;
+    private request;
+    private buildWebSocketUrl;
+    private createWebSocket;
+    private handleSocketMessage;
+}

package/dist/client.js

@@ -0,0 +1,502 @@
+import { SiymoOtpApiError, SiymoOtpConfigurationError, SiymoOtpWebSocketError, } from './errors.js';
+const DEFAULT_BASE_URL_ENV_VARS = ['SIYMO_OTP_BASE_URL', 'OTP_BASE_URL'];
+const OTP_WEBSOCKET_PATH = '/ws/otp';
+const WS_READY_STATE_CLOSING = 2;
+const WS_READY_STATE_CLOSED = 3;
+export class SiymoOtpClient {
+    baseUrl;
+    websocketBaseUrl;
+    defaultHeaders;
+    fetchImpl;
+    webSocketFactory;
+    constructor(options = {}) {
+        this.baseUrl = normalizeBaseUrl(resolveBaseUrl(options));
+        this.websocketBaseUrl = normalizeBaseUrl(options.websocketBaseUrl ?? httpBaseUrlToWebSocketBaseUrl(this.baseUrl));
+        this.defaultHeaders = new Headers(options.defaultHeaders);
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.webSocketFactory = options.webSocketFactory;
+    }
+    initiateVoice(body) {
+        return this.request('POST', '/otp/initiate/voice', body);
+    }
+    initiateSms(body) {
+        return this.request('POST', '/otp/initiate/sms', body);
+    }
+    initiateInboundCall(body) {
+        return this.request('POST', '/otp/initiate/inbound/call', body);
+    }
+    initiateInboundSms(body) {
+        return this.request('POST', '/otp/initiate/inbound/sms', body);
+    }
+    verify(body) {
+        return this.request('POST', '/otp/verify', body);
+    }
+    verifyInbound(body) {
+        return this.request('POST', '/otp/verify/inbound', body);
+    }
+    sendSms(body) {
+        return this.request('POST', '/sms/send', body);
+    }
+    listDongles() {
+        return this.request('GET', '/dongles');
+    }
+    health() {
+        return this.request('GET', '/health');
+    }
+    subscribeToSession(sessionId, options = {}) {
+        if (options.signal?.aborted) {
+            throw new SiymoOtpWebSocketError(`Subscription aborted before connecting to session ${sessionId}.`);
+        }
+        const socket = this.createWebSocket(this.buildWebSocketUrl(sessionId));
+        let resolveClosed;
+        const closed = new Promise((resolve) => {
+            resolveClosed = resolve;
+        });
+        let closedResolved = false;
+        const handleMessage = (event) => {
+            void this.handleSocketMessage(event, options, socket).catch((error) => {
+                options.onError?.(error);
+                closeSocket(socket, 1002, 'Invalid message');
+            });
+        };
+        const handleError = () => {
+            options.onError?.(new SiymoOtpWebSocketError(`WebSocket error while listening to session ${sessionId}.`));
+        };
+        const handleClose = (event) => {
+            try {
+                options.onClose?.(event);
+            }
+            finally {
+                finalizeClose();
+            }
+        };
+        socket.addEventListener('message', handleMessage);
+        socket.addEventListener('error', handleError);
+        socket.addEventListener('close', handleClose);
+        const cleanup = () => {
+            socket.removeEventListener('message', handleMessage);
+            socket.removeEventListener('error', handleError);
+            socket.removeEventListener('close', handleClose);
+            options.signal?.removeEventListener('abort', handleAbort);
+        };
+        const finalizeClose = () => {
+            if (closedResolved) {
+                return;
+            }
+            closedResolved = true;
+            cleanup();
+            resolveClosed();
+        };
+        const handleAbort = () => {
+            closeSocket(socket, 1000, 'Aborted');
+        };
+        options.signal?.addEventListener('abort', handleAbort, { once: true });
+        return {
+            sessionId,
+            closed,
+            close(code, reason) {
+                if (socket.readyState === WS_READY_STATE_CLOSING ||
+                    socket.readyState === WS_READY_STATE_CLOSED) {
+                    finalizeClose();
+                    return;
+                }
+                closeSocket(socket, code, reason);
+            },
+        };
+    }
+    waitForConfirmation(sessionId, options = {}) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId;
+            let subscription;
+            const finish = (result) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                resolve(result);
+                subscription.close(1000, 'Confirmed');
+            };
+            const fail = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                reject(error instanceof Error
+                    ? error
+                    : new SiymoOtpWebSocketError(`Failed while waiting for confirmation for session ${sessionId}.`));
+                subscription.close(1000, 'Stopped');
+            };
+            subscription = this.subscribeToSession(sessionId, {
+                signal: options.signal,
+                onEvent: options.onEvent,
+                onSubscribed: options.onSubscribed,
+                onAttempt: (event) => {
+                    options.onAttempt?.(event);
+                },
+                onLocked: (event) => {
+                    options.onLocked?.(event);
+                    fail(new SiymoOtpWebSocketError(`${event.data.message} for session ${event.data.sessionId} after ${event.data.attempts} attempt(s).`));
+                },
+                onVerified: (event) => {
+                    options.onVerified?.(event);
+                    finish(event);
+                },
+                onExpired: (event) => {
+                    options.onExpired?.(event);
+                    fail(new SiymoOtpWebSocketError(`OTP session ${event.data.sessionId} expired before confirmation arrived.`));
+                },
+                onError: (error) => {
+                    options.onError?.(error);
+                    fail(error);
+                },
+                onClose: (event) => {
+                    options.onClose?.(event);
+                    if (!settled) {
+                        fail(new SiymoOtpWebSocketError(`WebSocket closed before confirmation arrived for session ${sessionId}.`));
+                    }
+                },
+            });
+            if (typeof options.timeoutMs === 'number' && options.timeoutMs > 0) {
+                timeoutId = setTimeout(() => {
+                    fail(new SiymoOtpWebSocketError(`Timed out after ${options.timeoutMs} ms while waiting for session ${sessionId}.`));
+                }, options.timeoutMs);
+            }
+        });
+    }
+    waitForConfirmationLongPoll(sessionId, options = {}) {
+        const query = new URLSearchParams({ sessionId }).toString();
+        return this.request('GET', `/otp/wait?${query}`, undefined, {
+            signal: options.signal,
+        });
+    }
+    async request(method, path, body, options = {}) {
+        const url = new URL(stripLeadingSlash(path), `${this.baseUrl}/`);
+        const headers = new Headers(this.defaultHeaders);
+        headers.set('accept', 'application/json');
+        let requestBody;
+        if (body !== undefined) {
+            requestBody = JSON.stringify(body);
+            if (!headers.has('content-type')) {
+                headers.set('content-type', 'application/json');
+            }
+        }
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: requestBody,
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            throw new SiymoOtpApiError({
+                message: `Request to ${url.toString()} failed before the service responded.`,
+                status: 0,
+                statusText: 'FETCH_ERROR',
+                url: url.toString(),
+                body: null,
+                cause: error,
+            });
+        }
+        const payload = await parseResponse(response);
+        if (!response.ok) {
+            throw new SiymoOtpApiError({
+                message: `Request to ${url.toString()} failed with ${response.status} ${response.statusText}.`,
+                status: response.status,
+                statusText: response.statusText,
+                url: url.toString(),
+                body: payload,
+            });
+        }
+        return payload;
+    }
+    buildWebSocketUrl(sessionId) {
+        const url = new URL(stripLeadingSlash(OTP_WEBSOCKET_PATH), `${this.websocketBaseUrl}/`);
+        url.searchParams.set('sessionId', sessionId);
+        return url.toString();
+    }
+    createWebSocket(url) {
+        if (this.webSocketFactory) {
+            return this.webSocketFactory(url);
+        }
+        if (typeof globalThis.WebSocket !== 'function') {
+            throw new SiymoOtpConfigurationError('WebSocket is not available in this runtime. Pass webSocketFactory to override it.');
+        }
+        return new globalThis.WebSocket(url);
+    }
+    async handleSocketMessage(event, options, socket) {
+        const message = event;
+        const rawPayload = await readMessagePayload(message.data);
+        const parsedPayload = parseSocketEvent(rawPayload);
+        options.onEvent?.(parsedPayload);
+        switch (parsedPayload.event) {
+            case 'otp.subscribed':
+                options.onSubscribed?.(parsedPayload);
+                return;
+            case 'otp.attempt':
+                options.onAttempt?.(parsedPayload);
+                return;
+            case 'otp.locked':
+                options.onLocked?.(parsedPayload);
+                return;
+            case 'otp.verified':
+                options.onVerified?.(parsedPayload);
+                return;
+            case 'otp.expired':
+                options.onExpired?.(parsedPayload);
+                closeSocket(socket, 1000, 'Expired');
+                return;
+            default:
+                assertNever(parsedPayload);
+        }
+    }
+}
+function resolveBaseUrl(options) {
+    if (options.baseUrl) {
+        return options.baseUrl;
+    }
+    const env = globalThis.process?.env ?? {};
+    const candidates = Array.isArray(options.baseUrlEnvVar)
+        ? options.baseUrlEnvVar
+        : options.baseUrlEnvVar
+            ? [options.baseUrlEnvVar]
+            : DEFAULT_BASE_URL_ENV_VARS;
+    for (const key of candidates) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value;
+        }
+    }
+    throw new SiymoOtpConfigurationError(`Missing service base URL. Pass baseUrl or set one of: ${candidates.join(', ')}.`);
+}
+function normalizeBaseUrl(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new SiymoOtpConfigurationError('Base URL cannot be empty.');
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch (error) {
+        throw new SiymoOtpConfigurationError(`Invalid base URL: ${trimmed}.`, {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    url.pathname = stripTrailingSlash(url.pathname);
+    url.search = '';
+    url.hash = '';
+    return url.toString().replace(/\/$/, '');
+}
+function httpBaseUrlToWebSocketBaseUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return normalizeBaseUrl(url.toString());
+}
+async function parseResponse(response) {
+    if (response.status === 204) {
+        return null;
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+        return response.json();
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function readMessagePayload(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value instanceof ArrayBuffer) {
+        return new TextDecoder().decode(value);
+    }
+    if (ArrayBuffer.isView(value)) {
+        return new TextDecoder().decode(value);
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return value.text();
+    }
+    throw new SiymoOtpWebSocketError('Received an unsupported WebSocket message payload.');
+}
+function parseSocketEvent(rawPayload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawPayload);
+    }
+    catch (error) {
+        throw new SiymoOtpWebSocketError('Failed to parse WebSocket payload as JSON.', {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (!isRecord(parsed) || typeof parsed.event !== 'string' || !isRecord(parsed.data)) {
+        throw new SiymoOtpWebSocketError('Received an invalid WebSocket event payload.');
+    }
+    if (parsed.event === 'otp.subscribed') {
+        const expiresAt = parsed.data['expiresAt'];
+        const sessionId = parsed.data['sessionId'];
+        if (typeof expiresAt !== 'number' || typeof sessionId !== 'string') {
+            throw new SiymoOtpWebSocketError('Received an invalid otp.subscribed payload.');
+        }
+        return {
+            event: 'otp.subscribed',
+            data: {
+                expiresAt,
+                sessionId,
+            },
+        };
+    }
+    if (parsed.event === 'otp.expired') {
+        const sessionId = parsed.data['sessionId'];
+        if (typeof sessionId !== 'string') {
+            throw new SiymoOtpWebSocketError('Received an invalid otp.expired payload.');
+        }
+        return {
+            event: 'otp.expired',
+            data: {
+                sessionId,
+            },
+        };
+    }
+    if (parsed.event === 'otp.attempt') {
+        const payload = parseVerificationProgressPayload(parsed.data, 'otp.attempt');
+        if (payload.status !== 'PENDING' ||
+            payload.message !== 'Invalid or expired OTP' ||
+            payload.triesLeft <= 0) {
+            throw new SiymoOtpWebSocketError('Received an invalid otp.attempt payload.');
+        }
+        return {
+            event: 'otp.attempt',
+            data: {
+                ...payload,
+                status: 'PENDING',
+                message: 'Invalid or expired OTP',
+                attemptedAt: payload.timestamp,
+            },
+        };
+    }
+    if (parsed.event === 'otp.locked') {
+        const payload = parseVerificationProgressPayload(parsed.data, 'otp.locked');
+        if (payload.status !== 'LOCKED' ||
+            payload.message !== 'Too many attempts' ||
+            payload.triesLeft !== 0) {
+            throw new SiymoOtpWebSocketError('Received an invalid otp.locked payload.');
+        }
+        return {
+            event: 'otp.locked',
+            data: {
+                ...payload,
+                triesLeft: 0,
+                status: 'LOCKED',
+                message: 'Too many attempts',
+                lockedAt: payload.timestamp,
+            },
+        };
+    }
+    if (parsed.event === 'otp.verified') {
+        const sessionId = parsed.data['sessionId'];
+        const channel = parsed.data['channel'];
+        const direction = parsed.data['direction'];
+        const phone = parsed.data['phone'];
+        const serverPhone = parsed.data['serverPhone'];
+        const verifiedAt = parsed.data['verifiedAt'];
+        if (typeof sessionId !== 'string' ||
+            typeof channel !== 'string' ||
+            typeof direction !== 'string' ||
+            typeof phone !== 'string' ||
+            typeof serverPhone !== 'string' ||
+            typeof verifiedAt !== 'string') {
+            throw new SiymoOtpWebSocketError('Received an invalid otp.verified payload.');
+        }
+        return {
+            event: 'otp.verified',
+            data: {
+                sessionId,
+                channel,
+                direction,
+                phone,
+                serverPhone,
+                verifiedAt,
+            },
+        };
+    }
+    throw new SiymoOtpWebSocketError(`Received unsupported WebSocket event: ${parsed.event}.`);
+}
+function parseVerificationProgressPayload(data, eventName) {
+    const sessionId = data['sessionId'];
+    const channel = data['channel'];
+    const direction = data['direction'];
+    const phone = data['phone'];
+    const serverPhone = data['serverPhone'];
+    const attempts = data['attempts'];
+    const maxTries = data['maxTries'];
+    const triesLeft = data['triesLeft'];
+    const status = data['status'];
+    const message = data['message'];
+    const timestampKey = eventName === 'otp.attempt' ? 'attemptedAt' : 'lockedAt';
+    const timestamp = data[timestampKey];
+    if (typeof sessionId !== 'string' ||
+        typeof channel !== 'string' ||
+        typeof direction !== 'string' ||
+        typeof phone !== 'string' ||
+        typeof serverPhone !== 'string' ||
+        typeof attempts !== 'number' ||
+        typeof maxTries !== 'number' ||
+        typeof triesLeft !== 'number' ||
+        typeof status !== 'string' ||
+        typeof message !== 'string' ||
+        typeof timestamp !== 'string') {
+        throw new SiymoOtpWebSocketError(`Received an invalid ${eventName} payload.`);
+    }
+    return {
+        sessionId,
+        channel,
+        direction,
+        phone,
+        serverPhone,
+        attempts,
+        maxTries,
+        triesLeft,
+        status,
+        message,
+        timestamp,
+    };
+}
+function closeSocket(socket, code, reason) {
+    if (socket.readyState === WS_READY_STATE_CLOSING ||
+        socket.readyState === WS_READY_STATE_CLOSED) {
+        return;
+    }
+    socket.close(code, reason);
+}
+function stripLeadingSlash(value) {
+    return value.replace(/^\/+/, '');
+}
+function stripTrailingSlash(value) {
+    if (value === '/') {
+        return '';
+    }
+    return value.replace(/\/+$/, '');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function assertNever(value) {
+    throw new SiymoOtpWebSocketError(`Unhandled WebSocket event: ${String(value)}.`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+export declare class SiymoOtpError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class SiymoOtpConfigurationError extends SiymoOtpError {
+}
+export declare class SiymoOtpApiError extends SiymoOtpError {
+    readonly status: number;
+    readonly statusText: string;
+    readonly url: string;
+    readonly body: unknown;
+    constructor(params: {
+        message: string;
+        status: number;
+        statusText: string;
+        url: string;
+        body: unknown;
+        cause?: unknown;
+    });
+}
+export declare class SiymoOtpWebSocketError extends SiymoOtpError {
+}

package/dist/errors.js

@@ -0,0 +1,23 @@
+export class SiymoOtpError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+export class SiymoOtpConfigurationError extends SiymoOtpError {
+}
+export class SiymoOtpApiError extends SiymoOtpError {
+    status;
+    statusText;
+    url;
+    body;
+    constructor(params) {
+        super(params.message, { cause: params.cause instanceof Error ? params.cause : undefined });
+        this.status = params.status;
+        this.statusText = params.statusText;
+        this.url = params.url;
+        this.body = params.body;
+    }
+}
+export class SiymoOtpWebSocketError extends SiymoOtpError {
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SiymoOtpClient } from './client.js';
+export { SiymoOtpApiError, SiymoOtpConfigurationError, SiymoOtpError, SiymoOtpWebSocketError, } from './errors.js';
+export type { DongleDevice, DongleState, HealthCheckResponse, HealthIndicatorResult, InboundReceiptType, InitiateInboundCallResponse, InitiateInboundRequest, InitiateInboundSmsResponse, InitiateSmsRequest, InitiateSmsResponse, InitiateVoiceRequest, InitiateVoiceResponse, OtpAttemptEvent, OtpChannel, OtpDirection, OtpExpiredEvent, OtpLockedEvent, OtpLongPollFailureResponse, OtpLongPollSuccessResponse, OtpSessionEvent, OtpSessionSubscription, OtpStatus, OtpSubscribedEvent, OtpVerifiedEvent, SendSmsRequest, SendSmsResponse, SiymoOtpClientOptions, SubscribeToSessionOptions, VerifyInboundFailureResponse, VerifyInboundReceiptRequest, VerifyInboundResponse, VerifyInboundSuccessResponse, VerifyOtpRequest, VerifyOtpResponse, VerifyOtpRetryableFailureResponse, VerifyOtpSuccessResponse, VerifyOtpTerminalFailureResponse, WaitForConfirmationOptions, WaitForConfirmationLongPollOptions, WebSocketFactory, WebSocketLike, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SiymoOtpClient } from './client.js';
+export { SiymoOtpApiError, SiymoOtpConfigurationError, SiymoOtpError, SiymoOtpWebSocketError, } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,273 @@
+export type OtpChannel = 'voice' | 'sms' | 'call';
+export type OtpDirection = 'outbound' | 'inbound';
+export type OtpStatus = 'PENDING' | 'VERIFIED' | 'LOCKED';
+export type InboundReceiptType = 'call' | 'sms';
+export type DongleState = 'Free' | 'Busy' | 'Not connected' | string;
+export interface InitiateVoiceRequest {
+    phone: string;
+    languages: string[];
+    length?: number;
+    repeat?: boolean;
+    expiration?: number;
+    maxTries?: number;
+}
+export interface InitiateSmsRequest {
+    phone: string;
+    language: string;
+    length?: number;
+    expiration?: number;
+    maxTries?: number;
+}
+export interface InitiateInboundRequest {
+    phone: string;
+    length?: number;
+    expiration?: number;
+    maxTries?: number;
+    qrCode?: boolean;
+}
+interface PendingOtpSessionResponseBase {
+    success: true;
+    sessionId: string;
+    channel: OtpChannel;
+    length: number;
+    expiresIn: number;
+    maxTries: number;
+    status: 'PENDING';
+}
+export interface InitiateVoiceResponse extends PendingOtpSessionResponseBase {
+    channel: 'voice';
+    phone: string;
+    languages: string[];
+    repeat: boolean;
+}
+export interface InitiateSmsResponse extends PendingOtpSessionResponseBase {
+    channel: 'sms';
+    phone: string;
+    language: string;
+}
+interface InitiateInboundResponseBase extends PendingOtpSessionResponseBase {
+    direction: 'inbound';
+    phone: string;
+    from: string;
+    qrCodeImage?: string;
+}
+export interface InitiateInboundCallResponse extends InitiateInboundResponseBase {
+    channel: 'call';
+    code: string;
+}
+export interface InitiateInboundSmsResponse extends InitiateInboundResponseBase {
+    channel: 'sms';
+    text: string;
+    textEncoding: 'base64';
+}
+export interface VerifyOtpRequest {
+    sessionId: string;
+    otp: string;
+}
+export interface VerifyOtpSuccessResponse {
+    success: true;
+    verified: true;
+    sessionId: string;
+    channel: OtpChannel;
+    direction: OtpDirection;
+    message: 'OTP verified';
+}
+export interface VerifyOtpRetryableFailureResponse {
+    success: false;
+    verified: false;
+    channel: OtpChannel;
+    direction?: OtpDirection;
+    message: 'Invalid or expired OTP';
+    triesLeft: number;
+}
+export interface VerifyOtpTerminalFailureResponse {
+    success: false;
+    verified: false;
+    message: 'Too many attempts' | 'Invalid or expired OTP';
+}
+export type VerifyOtpResponse = VerifyOtpSuccessResponse | VerifyOtpRetryableFailureResponse | VerifyOtpTerminalFailureResponse;
+export interface VerifyInboundReceiptRequest {
+    type: InboundReceiptType;
+    dongle: string;
+    from: string;
+    code?: string;
+    text?: string;
+}
+export interface VerifyInboundSuccessResponse {
+    success: true;
+    verified: true;
+    sessionId: string;
+    channel: 'call' | 'sms';
+    direction: 'inbound';
+    type: InboundReceiptType;
+    message: 'OTP verified';
+}
+export interface VerifyInboundFailureResponse {
+    success: false;
+    verified: false;
+    type: InboundReceiptType;
+    channel?: 'call' | 'sms';
+    direction?: 'inbound';
+    message: 'Invalid or expired OTP' | 'Too many attempts';
+    triesLeft?: number;
+}
+export type VerifyInboundResponse = VerifyInboundSuccessResponse | VerifyInboundFailureResponse;
+export interface SendSmsRequest {
+    phone: string;
+    text: string;
+    device?: string;
+}
+export interface SendSmsResponse {
+    success: true;
+    phone: string;
+    device: string;
+}
+export interface DongleDevice {
+    id: string;
+    group: number;
+    state: DongleState;
+    rssi: number;
+    mode: number;
+    submode: number;
+    provider: string;
+    model: string;
+    firmware: string;
+    imei: string;
+    imsi: string;
+    number: string;
+    updatedAt: string;
+}
+export interface HealthIndicatorResult {
+    status: string;
+    message?: string;
+    [key: string]: unknown;
+}
+export interface HealthCheckResponse {
+    status: string;
+    info: Record<string, HealthIndicatorResult>;
+    error: Record<string, HealthIndicatorResult>;
+    details: Record<string, HealthIndicatorResult>;
+}
+export interface OtpSubscribedEvent {
+    event: 'otp.subscribed';
+    data: {
+        sessionId: string;
+        expiresAt: number;
+    };
+}
+export interface OtpAttemptEvent {
+    event: 'otp.attempt';
+    data: {
+        sessionId: string;
+        channel: OtpChannel;
+        direction: OtpDirection;
+        phone: string;
+        serverPhone: string;
+        attempts: number;
+        maxTries: number;
+        triesLeft: number;
+        status: 'PENDING';
+        attemptedAt: string;
+        message: 'Invalid or expired OTP';
+    };
+}
+export interface OtpLockedEvent {
+    event: 'otp.locked';
+    data: {
+        sessionId: string;
+        channel: OtpChannel;
+        direction: OtpDirection;
+        phone: string;
+        serverPhone: string;
+        attempts: number;
+        maxTries: number;
+        triesLeft: 0;
+        status: 'LOCKED';
+        lockedAt: string;
+        message: 'Too many attempts';
+    };
+}
+export interface OtpVerifiedEvent {
+    event: 'otp.verified';
+    data: {
+        sessionId: string;
+        channel: OtpChannel;
+        direction: OtpDirection;
+        phone: string;
+        serverPhone: string;
+        verifiedAt: string;
+    };
+}
+export interface OtpExpiredEvent {
+    event: 'otp.expired';
+    data: {
+        sessionId: string;
+    };
+}
+export interface OtpLongPollSuccessResponse {
+    success: true;
+    verified: true;
+    sessionId: string;
+    channel: OtpChannel;
+    direction: OtpDirection;
+    phone: string;
+    serverPhone: string;
+    status: 'VERIFIED';
+    verifiedAt: string;
+    message: 'OTP verified';
+}
+export interface OtpLongPollFailureResponse {
+    success: false;
+    verified: false;
+    sessionId: string;
+    channel?: OtpChannel;
+    direction?: OtpDirection;
+    phone?: string;
+    serverPhone?: string;
+    status?: 'LOCKED' | 'EXPIRED';
+    attempts?: number;
+    maxTries?: number;
+    triesLeft?: number;
+    lockedAt?: string;
+    expiredAt?: string;
+    message: string;
+}
+export type OtpSessionEvent = OtpSubscribedEvent | OtpAttemptEvent | OtpLockedEvent | OtpVerifiedEvent | OtpExpiredEvent;
+export interface WebSocketLike extends EventTarget {
+    readonly readyState: number;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export interface SubscribeToSessionOptions {
+    signal?: AbortSignal;
+    onEvent?: (event: OtpSessionEvent) => void;
+    onSubscribed?: (event: OtpSubscribedEvent) => void;
+    onAttempt?: (event: OtpAttemptEvent) => void;
+    onLocked?: (event: OtpLockedEvent) => void;
+    onVerified?: (event: OtpVerifiedEvent) => void;
+    onExpired?: (event: OtpExpiredEvent) => void;
+    onError?: (error: unknown) => void;
+    onClose?: (event: CloseEvent) => void;
+}
+export interface WaitForConfirmationOptions extends Pick<SubscribeToSessionOptions, 'signal' | 'onEvent' | 'onSubscribed' | 'onAttempt' | 'onLocked' | 'onVerified' | 'onExpired' | 'onError' | 'onClose'> {
+    timeoutMs?: number;
+}
+export interface WaitForConfirmationLongPollOptions {
+    signal?: AbortSignal;
+}
+export interface OtpSessionSubscription {
+    readonly sessionId: string;
+    readonly closed: Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+export interface SiymoOtpClientOptions {
+    baseUrl?: string;
+    baseUrlEnvVar?: string | readonly string[];
+    websocketBaseUrl?: string;
+    defaultHeaders?: HeadersInit;
+    fetch?: typeof fetch;
+    webSocketFactory?: WebSocketFactory;
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@siymo/otp-sdk-core",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for the siymo-otp-service REST and WebSocket APIs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test ./test/**/*.test.js"
+  },
+  "keywords": [
+    "otp",
+    "sdk",
+    "typescript",
+    "websocket",
+    "nest"
+  ],
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}