@siymo/otp-sdk-react 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# siymo-otp-react-sdk
+
+React hooks SDK for inbound OTP client flows, powered by `@siymo/otp-sdk-core`.
+
+## What It Provides
+
+- `useInboundCallOtp()` for inbound call OTP sessions
+- `useInboundSmsOtp()` for inbound SMS OTP sessions
+- Build-time or browser default base URL resolution
+- Live WebSocket events for attempts, lock, verification, and expiry
+- Optional long-poll mode if a React client prefers HTTP waiting
+
+## Install
+
+```bash
+npm install siymo-otp-react-sdk @siymo/otp-sdk-core react
+```
+
+## Default Behavior
+
+If you do not pass a `baseUrl`, the hooks resolve it like this:
+
+1. Build-time env value from `SIYMO_OTP_REACT_BASE_URL`
+2. Build-time env value from `SIYMO_OTP_BASE_URL`
+3. Build-time env value from `OTP_BASE_URL`
+4. Build-time env value from `baseURL`
+5. Browser `location.origin`
+6. Fallback to `http://localhost:3000`
+
+That lets you bake a service URL into the built package, while still keeping same-origin React apps working without extra configuration.
+
+To build the package with a default service URL:
+
+```bash
+SIYMO_OTP_REACT_BASE_URL=http://localhost:3000 npm run build
+```
+
+## Basic Usage
+
+```tsx
+import { useInboundSmsOtp } from 'siymo-otp-react-sdk';
+
+export function InboundSmsWidget() {
+  const { data, error, loading, create, eventLog } = useInboundSmsOtp({
+    onTried(event) {
+      console.log('Try number:', event.data.attempts);
+    },
+    onSuccess() {
+      console.log('OTP verified');
+    },
+  });
+
+  async function handleStart() {
+    await create({
+      phone: '+998990649000',
+      expiration: 60,
+      maxTries: 3,
+      qrCode: true,
+    });
+  }
+
+  return (
+    <div>
+      <button onClick={handleStart}>Create session</button>
+      <p>Loading: {loading ? 'yes' : 'no'}</p>
+      <p>Status: {data.status}</p>
+      <p>Attempts: {data.attempts}</p>
+      <p>Tries left: {data.triesLeft ?? '-'}</p>
+      <p>Decoded SMS: {data.decodedText ?? '-'}</p>
+      {data.qrCodeImage ? <img src={data.qrCodeImage} alt="Inbound SMS QR code" width={180} /> : null}
+      <p>Latest event: {eventLog.at(-1)?.description ?? '-'}</p>
+      {error ? <p>{error.message}</p> : null}
+    </div>
+  );
+}
+```
+
+## Hook Return Shape
+
+Both hooks expose:
+
+- `data` as the primary, flattened payload for the hook
+- `loading`, `error`, `message`, and `called` for easy UI state
+- `create(request)`, `restart(request?)`, `wait(sessionId?)`, `stop()`, and `clear()`
+- Legacy aliases are still available: `start`, `waitForSession`, `cancel`, `reset`
+- `eventLog` with pre-described entries ready for rendering
+- Raw escape hatches when needed: `session`, `events`, `lastEvent`, `lastAttemptEvent`, `verifiedEvent`, `lockedEvent`, `expiredEvent`
+- `attempts`, `triesLeft`, `status`, `isWaiting`, `isVerified`, `isLocked`, `isExpired`
+
+`useInboundCallOtp()` also exposes `otpCode`, `callHref`, and `qrCodeImage`.
+
+`useInboundSmsOtp()` also exposes `decodedText` and `qrCodeImage`.
+
+The `data` shape is channel-specific:
+
+- Call hook data: `servicePhone`, `callerPhone`, `qrCodeImage`, `otpCode`, `callHref`
+- SMS hook data: `servicePhone`, `senderPhone`, `qrCodeImage`, `rawText`, `decodedText`
+
+## Options
+
+```ts
+type UseInboundCallOtpOptions = {
+  autoWait?: boolean;
+  waitMode?: 'websocket' | 'long-poll';
+  timeoutMs?: number;
+  baseUrl?: string;
+  websocketBaseUrl?: string;
+  client?: SiymoOtpClient;
+  clientOptions?: Omit<SiymoOtpClientOptions, 'baseUrl' | 'websocketBaseUrl'>;
+  onCreated?: (session, result) => void;
+  onSubscribed?: (event, result) => void;
+  onTried?: (event, result) => void;
+  onSuccess?: (event, result) => void;
+  onLocked?: (event, result) => void;
+  onExpired?: (event, result) => void;
+  onError?: (error, result) => void;
+  onStatusChange?: (status, result) => void;
+};
+```
+
+Notes:
+
+- `waitMode` defaults to `websocket`
+- `autoWait` defaults to `true`
+- `baseUrl` still overrides any build-time default when you want a per-hook override
+- Pass `qrCode: true` in `create()` when you want the API to return a scannable `qrCodeImage` data URL
+- WebSocket mode is the only mode that can stream `otp.attempt` events live
+- Long-poll mode still updates verified / locked / expired state, but it cannot stream intermediate attempts
+- Callback handlers receive the latest hook result, including the derived `data` object
+
+## Examples
+
+The package includes two basic React examples:
+
+- [`examples/inbound-call-client`](./examples/inbound-call-client)
+- [`examples/inbound-sms-client`](./examples/inbound-sms-client)
+
+Each example consumes this React package plus the core `@siymo/otp-sdk-core`.

package/dist/buildConfig.d.ts

@@ -0,0 +1,2 @@
+export declare const BUILD_TIME_SIYMO_OTP_REACT_BASE_URL: string | undefined;
+export declare const BUILD_TIME_SIYMO_OTP_REACT_BASE_URL_ENV_VARS: readonly ["SIYMO_OTP_REACT_BASE_URL", "SIYMO_OTP_BASE_URL", "OTP_BASE_URL", "baseURL"];

package/dist/buildConfig.js

@@ -0,0 +1,8 @@
+// This file is updated by `npm run build` to capture any build-time base URL.
+export const BUILD_TIME_SIYMO_OTP_REACT_BASE_URL = "https://otp.inadullaev.com";
+export const BUILD_TIME_SIYMO_OTP_REACT_BASE_URL_ENV_VARS = [
+    "SIYMO_OTP_REACT_BASE_URL",
+    "SIYMO_OTP_BASE_URL",
+    "OTP_BASE_URL",
+    "baseURL"
+];

package/dist/defaults.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_SIYMO_OTP_REACT_BASE_URL = "http://localhost:3000";
+export declare function resolveDefaultSiymoOtpBaseUrl(): string;

package/dist/defaults.js

@@ -0,0 +1,16 @@
+import { BUILD_TIME_SIYMO_OTP_REACT_BASE_URL } from './buildConfig.js';
+export const DEFAULT_SIYMO_OTP_REACT_BASE_URL = 'http://localhost:3000';
+export function resolveDefaultSiymoOtpBaseUrl() {
+    const configuredBaseUrl = BUILD_TIME_SIYMO_OTP_REACT_BASE_URL?.trim();
+    if (configuredBaseUrl && configuredBaseUrl.length > 0) {
+        return configuredBaseUrl;
+    }
+    const origin = globalThis.location?.origin;
+    if (typeof origin === 'string') {
+        const trimmed = origin.trim();
+        if (trimmed.length > 0 && trimmed !== 'null') {
+            return trimmed;
+        }
+    }
+    return DEFAULT_SIYMO_OTP_REACT_BASE_URL;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { SiymoOtpApiError, SiymoOtpClient, SiymoOtpConfigurationError, SiymoOtpError, SiymoOtpWebSocketError, } from '@siymo/otp-sdk-core';
+export type { InboundReceiptType, InitiateInboundCallResponse, InitiateInboundRequest, InitiateInboundSmsResponse, OtpAttemptEvent, OtpExpiredEvent, OtpLockedEvent, OtpLongPollFailureResponse, OtpLongPollSuccessResponse, OtpSessionEvent, OtpSubscribedEvent, OtpVerifiedEvent, SiymoOtpClientOptions, } from '@siymo/otp-sdk-core';
+export { DEFAULT_SIYMO_OTP_REACT_BASE_URL, resolveDefaultSiymoOtpBaseUrl, } from './defaults.js';
+export type { InboundCallOtpData, InboundOtpActivityItem, InboundOtpActivityPayload, InboundOtpData, InboundOtpExpiredPayload, InboundOtpHookResult, InboundOtpHookStatus, InboundOtpLockedPayload, InboundOtpSuccessPayload, InboundOtpWaitMode, InboundSmsOtpData, UseInboundCallOtpOptions, UseInboundCallOtpResult, UseInboundSmsOtpOptions, UseInboundSmsOtpResult, UseSiymoOtpHookOptions, } from './types.js';
+export { useInboundCallOtp } from './useInboundCallOtp.js';
+export { useInboundSmsOtp } from './useInboundSmsOtp.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SiymoOtpApiError, SiymoOtpClient, SiymoOtpConfigurationError, SiymoOtpError, SiymoOtpWebSocketError, } from '@siymo/otp-sdk-core';
+export { DEFAULT_SIYMO_OTP_REACT_BASE_URL, resolveDefaultSiymoOtpBaseUrl, } from './defaults.js';
+export { useInboundCallOtp } from './useInboundCallOtp.js';
+export { useInboundSmsOtp } from './useInboundSmsOtp.js';

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+import type { InitiateInboundCallResponse, InitiateInboundRequest, InitiateInboundSmsResponse, OtpAttemptEvent, OtpExpiredEvent, OtpLockedEvent, OtpLongPollFailureResponse, OtpLongPollSuccessResponse, OtpSessionEvent, OtpSubscribedEvent, OtpVerifiedEvent, SiymoOtpClient, SiymoOtpClientOptions } from '@siymo/otp-sdk-core';
+type InboundOtpSession = InitiateInboundCallResponse | InitiateInboundSmsResponse;
+export type InboundOtpHookStatus = 'idle' | 'starting' | 'pending' | 'verified' | 'locked' | 'expired' | 'error';
+export type InboundOtpWaitMode = 'websocket' | 'long-poll';
+export type InboundOtpSuccessPayload = OtpVerifiedEvent | OtpLongPollSuccessResponse;
+export type InboundOtpLockedPayload = OtpLockedEvent | (OtpLongPollFailureResponse & {
+    status: 'LOCKED';
+});
+export type InboundOtpExpiredPayload = OtpExpiredEvent | (OtpLongPollFailureResponse & {
+    status: 'EXPIRED';
+});
+export type InboundOtpActivityPayload = OtpSessionEvent | OtpLongPollSuccessResponse | OtpLongPollFailureResponse;
+export interface InboundOtpActivityItem<TPayload extends InboundOtpActivityPayload = InboundOtpActivityPayload> {
+    type: 'otp.subscribed' | 'otp.attempt' | 'otp.locked' | 'otp.verified' | 'otp.expired';
+    description: string;
+    occurredAt: number | string | null;
+    payload: TPayload;
+}
+export interface InboundOtpData<TSession extends InboundOtpSession = InboundOtpSession> {
+    session: TSession | null;
+    sessionId: string | null;
+    channel: TSession['channel'] | null;
+    direction: TSession['direction'] | null;
+    status: InboundOtpHookStatus;
+    attempts: number;
+    triesLeft: number | null;
+    length: number | null;
+    expiresIn: number | null;
+    maxTries: number | null;
+    subscribedExpiresAt: number | null;
+    lastEvent: OtpSessionEvent | null;
+    lastEventText: string | null;
+}
+export interface InboundCallOtpData extends InboundOtpData<InitiateInboundCallResponse> {
+    channel: 'call' | null;
+    servicePhone: string | null;
+    callerPhone: string | null;
+    qrCodeImage: string | null;
+    otpCode: string | null;
+    callHref: string | null;
+}
+export interface InboundSmsOtpData extends InboundOtpData<InitiateInboundSmsResponse> {
+    channel: 'sms' | null;
+    servicePhone: string | null;
+    senderPhone: string | null;
+    qrCodeImage: string | null;
+    rawText: string | null;
+    decodedText: string | null;
+}
+export interface InboundOtpHookResult<TSession extends InboundOtpSession = InboundOtpSession, TData extends InboundOtpData<TSession> = InboundOtpData<TSession>> {
+    data: TData;
+    loading: boolean;
+    called: boolean;
+    hasSession: boolean;
+    message: string | null;
+    latestEventText: string | null;
+    eventLog: InboundOtpActivityItem[];
+    lastRequest: InitiateInboundRequest | null;
+    waitMode: InboundOtpWaitMode;
+    status: InboundOtpHookStatus;
+    sessionId: string | null;
+    session: TSession | null;
+    events: OtpSessionEvent[];
+    lastEvent: OtpSessionEvent | null;
+    subscribedEvent: OtpSubscribedEvent | null;
+    subscribedExpiresAt: number | null;
+    lastAttemptEvent: OtpAttemptEvent | null;
+    lockedEvent: OtpLockedEvent | null;
+    verifiedEvent: OtpVerifiedEvent | null;
+    expiredEvent: OtpExpiredEvent | null;
+    longPollResult: OtpLongPollSuccessResponse | null;
+    longPollFailure: OtpLongPollFailureResponse | null;
+    attempts: number;
+    triesLeft: number | null;
+    error: Error | null;
+    isIdle: boolean;
+    isStarting: boolean;
+    isWaiting: boolean;
+    isVerified: boolean;
+    isLocked: boolean;
+    isExpired: boolean;
+    create(request: InitiateInboundRequest): Promise<TSession>;
+    restart(request?: InitiateInboundRequest): Promise<TSession>;
+    wait(sessionId?: string): Promise<void>;
+    stop(): Promise<void>;
+    clear(): Promise<void>;
+    start(request: InitiateInboundRequest): Promise<TSession>;
+    waitForSession(sessionId?: string): Promise<void>;
+    cancel(): Promise<void>;
+    reset(): Promise<void>;
+}
+export interface UseInboundCallOtpResult extends InboundOtpHookResult<InitiateInboundCallResponse, InboundCallOtpData> {
+    otpCode: string | null;
+    callHref: string | null;
+    qrCodeImage: string | null;
+}
+export interface UseInboundSmsOtpResult extends InboundOtpHookResult<InitiateInboundSmsResponse, InboundSmsOtpData> {
+    decodedText: string | null;
+    qrCodeImage: string | null;
+}
+export interface UseSiymoOtpHookOptions<TSession extends InboundOtpSession = InboundOtpSession, TData extends InboundOtpData<TSession> = InboundOtpData<TSession>> {
+    autoWait?: boolean;
+    waitMode?: InboundOtpWaitMode;
+    timeoutMs?: number;
+    baseUrl?: string;
+    websocketBaseUrl?: string;
+    client?: SiymoOtpClient;
+    clientOptions?: Omit<SiymoOtpClientOptions, 'baseUrl' | 'websocketBaseUrl'>;
+    onCreated?: (session: TSession, result: InboundOtpHookResult<TSession, TData>) => void;
+    onEvent?: (event: OtpSessionEvent, result: InboundOtpHookResult<TSession, TData>) => void;
+    onSubscribed?: (event: OtpSubscribedEvent, result: InboundOtpHookResult<TSession, TData>) => void;
+    onTried?: (event: OtpAttemptEvent, result: InboundOtpHookResult<TSession, TData>) => void;
+    onLocked?: (event: InboundOtpLockedPayload, result: InboundOtpHookResult<TSession, TData>) => void;
+    onSuccess?: (event: InboundOtpSuccessPayload, result: InboundOtpHookResult<TSession, TData>) => void;
+    onExpired?: (event: InboundOtpExpiredPayload, result: InboundOtpHookResult<TSession, TData>) => void;
+    onError?: (error: Error, result: InboundOtpHookResult<TSession, TData>) => void;
+    onStatusChange?: (status: InboundOtpHookStatus, result: InboundOtpHookResult<TSession, TData>) => void;
+}
+export type UseInboundCallOtpOptions = UseSiymoOtpHookOptions<InitiateInboundCallResponse, InboundCallOtpData>;
+export type UseInboundSmsOtpOptions = UseSiymoOtpHookOptions<InitiateInboundSmsResponse, InboundSmsOtpData>;
+export {};

package/dist/types.js

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

package/dist/useInboundCallOtp.d.ts

@@ -0,0 +1,2 @@
+import type { UseInboundCallOtpOptions, UseInboundCallOtpResult } from './types.js';
+export declare function useInboundCallOtp(options?: UseInboundCallOtpOptions): UseInboundCallOtpResult;

package/dist/useInboundCallOtp.js

@@ -0,0 +1,53 @@
+import { useInboundOtpSession } from './useInboundOtp.js';
+export function useInboundCallOtp(options = {}) {
+    const result = useInboundOtpSession({
+        options,
+        initiate(client, request) {
+            return client.initiateInboundCall(request);
+        },
+        selectData(input) {
+            const servicePhone = input.session?.phone ??
+                input.verifiedEvent?.data.serverPhone ??
+                input.lockedEvent?.data.serverPhone ??
+                input.longPollResult?.serverPhone ??
+                input.longPollFailure?.serverPhone ??
+                null;
+            const callerPhone = input.session?.from ??
+                input.verifiedEvent?.data.phone ??
+                input.lockedEvent?.data.phone ??
+                input.longPollResult?.phone ??
+                input.longPollFailure?.phone ??
+                null;
+            const otpCode = input.session?.code ?? null;
+            return {
+                session: input.session,
+                sessionId: input.sessionId,
+                channel: input.session?.channel ?? null,
+                direction: input.session?.direction ?? null,
+                status: input.status,
+                attempts: input.attempts,
+                triesLeft: input.triesLeft,
+                length: input.session?.length ?? null,
+                expiresIn: input.session?.expiresIn ?? null,
+                maxTries: input.session?.maxTries ??
+                    input.lockedEvent?.data.maxTries ??
+                    input.longPollFailure?.maxTries ??
+                    null,
+                subscribedExpiresAt: input.subscribedExpiresAt,
+                lastEvent: input.lastEvent,
+                lastEventText: input.latestEventText,
+                servicePhone,
+                callerPhone,
+                qrCodeImage: input.session?.qrCodeImage ?? null,
+                otpCode,
+                callHref: servicePhone && otpCode ? `tel:${servicePhone},${otpCode}` : null,
+            };
+        },
+    });
+    return {
+        ...result,
+        otpCode: result.data.otpCode,
+        callHref: result.data.callHref,
+        qrCodeImage: result.data.qrCodeImage,
+    };
+}

package/dist/useInboundOtp.d.ts

@@ -0,0 +1,42 @@
+import { SiymoOtpClient, type InitiateInboundCallResponse, type InitiateInboundRequest, type InitiateInboundSmsResponse, type OtpAttemptEvent, type OtpExpiredEvent, type OtpLockedEvent, type OtpLongPollFailureResponse, type OtpLongPollSuccessResponse, type OtpSessionEvent, type OtpSubscribedEvent, type OtpVerifiedEvent } from '@siymo/otp-sdk-core';
+import type { InboundOtpActivityItem, InboundOtpData, InboundOtpHookResult, InboundOtpHookStatus, UseSiymoOtpHookOptions } from './types.js';
+type InboundOtpSession = InitiateInboundCallResponse | InitiateInboundSmsResponse;
+interface InboundOtpResultInput<TSession extends InboundOtpSession> {
+    loading: boolean;
+    called: boolean;
+    hasSession: boolean;
+    message: string | null;
+    latestEventText: string | null;
+    eventLog: InboundOtpActivityItem[];
+    lastRequest: InitiateInboundRequest | null;
+    waitMode: 'websocket' | 'long-poll';
+    status: InboundOtpHookStatus;
+    sessionId: string | null;
+    session: TSession | null;
+    events: OtpSessionEvent[];
+    lastEvent: OtpSessionEvent | null;
+    subscribedEvent: OtpSubscribedEvent | null;
+    subscribedExpiresAt: number | null;
+    lastAttemptEvent: OtpAttemptEvent | null;
+    lockedEvent: OtpLockedEvent | null;
+    verifiedEvent: OtpVerifiedEvent | null;
+    expiredEvent: OtpExpiredEvent | null;
+    longPollResult: OtpLongPollSuccessResponse | null;
+    longPollFailure: OtpLongPollFailureResponse | null;
+    attempts: number;
+    triesLeft: number | null;
+    error: Error | null;
+    isIdle: boolean;
+    isStarting: boolean;
+    isWaiting: boolean;
+    isVerified: boolean;
+    isLocked: boolean;
+    isExpired: boolean;
+}
+interface UseInboundOtpSessionConfig<TSession extends InboundOtpSession, TData extends InboundOtpData<TSession>> {
+    initiate(client: SiymoOtpClient, request: InitiateInboundRequest): Promise<TSession>;
+    options: UseSiymoOtpHookOptions<TSession, TData>;
+    selectData(input: InboundOtpResultInput<TSession>): TData;
+}
+export declare function useInboundOtpSession<TSession extends InboundOtpSession, TData extends InboundOtpData<TSession>>(config: UseInboundOtpSessionConfig<TSession, TData>): InboundOtpHookResult<TSession, TData>;
+export {};

package/dist/useInboundOtp.js

@@ -0,0 +1,646 @@
+import { useEffect, useRef, useState, } from 'react';
+import { SiymoOtpApiError, SiymoOtpClient, } from '@siymo/otp-sdk-core';
+import { resolveDefaultSiymoOtpBaseUrl } from './defaults.js';
+export function useInboundOtpSession(config) {
+    const waitMode = config.options.waitMode ?? 'websocket';
+    const [state, setState] = useState(() => createInitialState());
+    const stateRef = useRef(state);
+    const previousStateRef = useRef(state);
+    const callbacksRef = useRef(config.options);
+    const activeWaitRef = useRef(null);
+    const lastRequestRef = useRef(null);
+    const nextActiveWaitIdRef = useRef(0);
+    callbacksRef.current = config.options;
+    const updateState = (updater) => {
+        setState((current) => {
+            const next = typeof updater === 'function' ? updater(current) : updater;
+            stateRef.current = next;
+            return next;
+        });
+    };
+    useEffect(() => {
+        return () => {
+            void stopActiveWait(activeWaitRef);
+        };
+    }, []);
+    async function start(request) {
+        lastRequestRef.current = { ...request };
+        await stopActiveWait(activeWaitRef);
+        updateState({
+            ...createInitialState(),
+            status: 'starting',
+        });
+        const client = resolveClient(config.options);
+        const session = await config.initiate(client, request).catch((error) => {
+            const normalized = normalizeError(error);
+            updateState({
+                ...createInitialState(),
+                status: 'error',
+                error: normalized,
+            });
+            throw normalized;
+        });
+        updateState({
+            ...createInitialState(),
+            status: 'pending',
+            session,
+            triesLeft: session.maxTries,
+        });
+        if (config.options.autoWait ?? true) {
+            try {
+                await waitForSession(session.sessionId);
+            }
+            catch (error) {
+                const normalized = normalizeError(error);
+                updateState((current) => ({
+                    ...current,
+                    status: 'error',
+                    error: normalized,
+                    isWaiting: false,
+                }));
+                throw normalized;
+            }
+        }
+        return session;
+    }
+    async function restart(request) {
+        const nextRequest = request ?? lastRequestRef.current;
+        if (!nextRequest) {
+            throw new Error('No previous inbound OTP request is available to restart.');
+        }
+        return start(nextRequest);
+    }
+    async function waitForSession(sessionId) {
+        const targetSessionId = sessionId ?? stateRef.current.session?.sessionId;
+        if (!targetSessionId) {
+            throw new Error('No inbound OTP session is available to wait for.');
+        }
+        await stopActiveWait(activeWaitRef);
+        const activeWait = {
+            id: nextActiveWaitIdRef.current + 1,
+            controller: new AbortController(),
+        };
+        nextActiveWaitIdRef.current = activeWait.id;
+        activeWaitRef.current = activeWait;
+        updateState((current) => ({
+            ...current,
+            status: 'pending',
+            isWaiting: true,
+            error: null,
+            longPollResult: null,
+            longPollFailure: null,
+        }));
+        const client = resolveClient(config.options);
+        scheduleWaitTimeout(activeWaitRef, activeWait, config.options.timeoutMs, targetSessionId, updateState);
+        if (waitMode === 'long-poll') {
+            void client
+                .waitForConfirmationLongPoll(targetSessionId, {
+                signal: activeWait.controller.signal,
+            })
+                .then((result) => {
+                if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                    return;
+                }
+                finalizeActiveWait(activeWaitRef, activeWait);
+                updateState((current) => ({
+                    ...current,
+                    status: 'verified',
+                    longPollResult: result,
+                    error: null,
+                    isWaiting: false,
+                }));
+            })
+                .catch((error) => {
+                if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                    return;
+                }
+                finalizeActiveWait(activeWaitRef, activeWait);
+                if (isAbortLikeError(error)) {
+                    updateState((current) => ({
+                        ...current,
+                        isWaiting: false,
+                    }));
+                    return;
+                }
+                const failure = extractLongPollFailure(error);
+                if (failure?.status === 'LOCKED') {
+                    updateState((current) => ({
+                        ...current,
+                        status: 'locked',
+                        longPollFailure: failure,
+                        attempts: failure.attempts ?? current.attempts,
+                        triesLeft: failure.triesLeft ?? current.triesLeft,
+                        error: null,
+                        isWaiting: false,
+                    }));
+                    return;
+                }
+                if (failure?.status === 'EXPIRED') {
+                    updateState((current) => ({
+                        ...current,
+                        status: 'expired',
+                        longPollFailure: failure,
+                        error: null,
+                        isWaiting: false,
+                    }));
+                    return;
+                }
+                updateState((current) => ({
+                    ...current,
+                    status: 'error',
+                    error: normalizeError(error),
+                    isWaiting: false,
+                }));
+            });
+            return;
+        }
+        try {
+            activeWait.subscription = client.subscribeToSession(targetSessionId, {
+                signal: activeWait.controller.signal,
+                onSubscribed: (event) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    updateState((current) => recordEvent(current, event, {
+                        subscribedEvent: event,
+                        subscribedExpiresAt: event.data.expiresAt,
+                    }));
+                },
+                onAttempt: (event) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    updateState((current) => recordEvent(current, event, {
+                        attempts: event.data.attempts,
+                        triesLeft: event.data.triesLeft,
+                        lastAttemptEvent: event,
+                    }));
+                },
+                onLocked: (event) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    finalizeActiveWait(activeWaitRef, activeWait);
+                    updateState((current) => recordEvent(current, event, {
+                        status: 'locked',
+                        attempts: event.data.attempts,
+                        triesLeft: event.data.triesLeft,
+                        lockedEvent: event,
+                        isWaiting: false,
+                    }));
+                },
+                onVerified: (event) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    finalizeActiveWait(activeWaitRef, activeWait);
+                    updateState((current) => recordEvent(current, event, {
+                        status: 'verified',
+                        verifiedEvent: event,
+                        isWaiting: false,
+                    }));
+                },
+                onExpired: (event) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    finalizeActiveWait(activeWaitRef, activeWait);
+                    updateState((current) => recordEvent(current, event, {
+                        status: 'expired',
+                        expiredEvent: event,
+                        isWaiting: false,
+                    }));
+                },
+                onError: (error) => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    finalizeActiveWait(activeWaitRef, activeWait);
+                    updateState((current) => ({
+                        ...current,
+                        status: 'error',
+                        error: normalizeError(error),
+                        isWaiting: false,
+                    }));
+                },
+                onClose: () => {
+                    if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+                        return;
+                    }
+                    finalizeActiveWait(activeWaitRef, activeWait);
+                    if (activeWait.controller.signal.aborted) {
+                        updateState((current) => ({
+                            ...current,
+                            isWaiting: false,
+                        }));
+                        return;
+                    }
+                    updateState((current) => ({
+                        ...current,
+                        status: current.status === 'pending' || current.status === 'starting'
+                            ? 'error'
+                            : current.status,
+                        error: current.status === 'pending' || current.status === 'starting'
+                            ? new Error(`WebSocket closed before session ${targetSessionId} completed.`)
+                            : current.error,
+                        isWaiting: false,
+                    }));
+                },
+            });
+        }
+        catch (error) {
+            finalizeActiveWait(activeWaitRef, activeWait);
+            const normalized = normalizeError(error);
+            updateState((current) => ({
+                ...current,
+                status: 'error',
+                error: normalized,
+                isWaiting: false,
+            }));
+            throw normalized;
+        }
+    }
+    async function cancel() {
+        await stopActiveWait(activeWaitRef);
+        updateState((current) => ({
+            ...current,
+            isWaiting: false,
+            error: null,
+        }));
+    }
+    async function reset() {
+        await stopActiveWait(activeWaitRef);
+        updateState(createInitialState());
+    }
+    const resultInput = createResultInput(state, waitMode, lastRequestRef.current);
+    const result = createHookResult(resultInput, config.selectData(resultInput), {
+        start,
+        restart,
+        waitForSession,
+        cancel,
+        reset,
+    });
+    const resultRef = useRef(result);
+    resultRef.current = result;
+    useEffect(() => {
+        const previousState = previousStateRef.current;
+        const callbacks = callbacksRef.current;
+        const currentResult = resultRef.current;
+        if (state.session !== previousState.session && state.session) {
+            callbacks.onCreated?.(state.session, currentResult);
+        }
+        if (state.lastEvent !== previousState.lastEvent && state.lastEvent) {
+            callbacks.onEvent?.(state.lastEvent, currentResult);
+            switch (state.lastEvent.event) {
+                case 'otp.subscribed':
+                    callbacks.onSubscribed?.(state.lastEvent, currentResult);
+                    break;
+                case 'otp.attempt':
+                    callbacks.onTried?.(state.lastEvent, currentResult);
+                    break;
+                case 'otp.locked':
+                    callbacks.onLocked?.(state.lastEvent, currentResult);
+                    break;
+                case 'otp.verified':
+                    callbacks.onSuccess?.(state.lastEvent, currentResult);
+                    break;
+                case 'otp.expired':
+                    callbacks.onExpired?.(state.lastEvent, currentResult);
+                    break;
+            }
+        }
+        if (state.longPollResult !== previousState.longPollResult && state.longPollResult) {
+            callbacks.onSuccess?.(state.longPollResult, currentResult);
+        }
+        if (state.longPollFailure !== previousState.longPollFailure && state.longPollFailure) {
+            if (state.longPollFailure.status === 'LOCKED') {
+                callbacks.onLocked?.(state.longPollFailure, currentResult);
+            }
+            if (state.longPollFailure.status === 'EXPIRED') {
+                callbacks.onExpired?.(state.longPollFailure, currentResult);
+            }
+        }
+        if (state.error !== previousState.error && state.error) {
+            callbacks.onError?.(state.error, currentResult);
+        }
+        if (state.status !== previousState.status) {
+            callbacks.onStatusChange?.(state.status, currentResult);
+        }
+        previousStateRef.current = state;
+    }, [state]);
+    return result;
+}
+function createInitialState() {
+    return {
+        status: 'idle',
+        session: null,
+        events: [],
+        lastEvent: null,
+        subscribedEvent: null,
+        subscribedExpiresAt: null,
+        lastAttemptEvent: null,
+        lockedEvent: null,
+        verifiedEvent: null,
+        expiredEvent: null,
+        longPollResult: null,
+        longPollFailure: null,
+        attempts: 0,
+        triesLeft: null,
+        error: null,
+        isWaiting: false,
+    };
+}
+function createResultInput(state, waitMode, lastRequest) {
+    const sessionId = resolveSessionId(state);
+    const eventLog = createEventLog(state);
+    const latestEventText = eventLog.at(-1)?.description ?? null;
+    const message = createMessage(state, sessionId, latestEventText);
+    const called = state.status !== 'idle' ||
+        sessionId !== null ||
+        state.events.length > 0 ||
+        state.error !== null ||
+        state.longPollResult !== null ||
+        state.longPollFailure !== null;
+    return {
+        loading: state.status === 'starting' || state.isWaiting,
+        called,
+        hasSession: state.session !== null,
+        message,
+        latestEventText,
+        eventLog,
+        lastRequest,
+        waitMode,
+        status: state.status,
+        sessionId,
+        session: state.session,
+        events: state.events,
+        lastEvent: state.lastEvent,
+        subscribedEvent: state.subscribedEvent,
+        subscribedExpiresAt: state.subscribedExpiresAt,
+        lastAttemptEvent: state.lastAttemptEvent,
+        lockedEvent: state.lockedEvent,
+        verifiedEvent: state.verifiedEvent,
+        expiredEvent: state.expiredEvent,
+        longPollResult: state.longPollResult,
+        longPollFailure: state.longPollFailure,
+        attempts: state.attempts,
+        triesLeft: state.triesLeft,
+        error: state.error,
+        isIdle: state.status === 'idle',
+        isStarting: state.status === 'starting',
+        isWaiting: state.isWaiting,
+        isVerified: state.status === 'verified',
+        isLocked: state.status === 'locked',
+        isExpired: state.status === 'expired',
+    };
+}
+function createHookResult(input, data, actions) {
+    return {
+        data,
+        loading: input.loading,
+        called: input.called,
+        hasSession: input.hasSession,
+        message: input.message,
+        latestEventText: input.latestEventText,
+        eventLog: input.eventLog,
+        lastRequest: input.lastRequest,
+        waitMode: input.waitMode,
+        status: input.status,
+        sessionId: input.sessionId,
+        session: input.session,
+        events: input.events,
+        lastEvent: input.lastEvent,
+        subscribedEvent: input.subscribedEvent,
+        subscribedExpiresAt: input.subscribedExpiresAt,
+        lastAttemptEvent: input.lastAttemptEvent,
+        lockedEvent: input.lockedEvent,
+        verifiedEvent: input.verifiedEvent,
+        expiredEvent: input.expiredEvent,
+        longPollResult: input.longPollResult,
+        longPollFailure: input.longPollFailure,
+        attempts: input.attempts,
+        triesLeft: input.triesLeft,
+        error: input.error,
+        isIdle: input.isIdle,
+        isStarting: input.isStarting,
+        isWaiting: input.isWaiting,
+        isVerified: input.isVerified,
+        isLocked: input.isLocked,
+        isExpired: input.isExpired,
+        create: actions.start,
+        restart: actions.restart,
+        wait: actions.waitForSession,
+        stop: actions.cancel,
+        clear: actions.reset,
+        start: actions.start,
+        waitForSession: actions.waitForSession,
+        cancel: actions.cancel,
+        reset: actions.reset,
+    };
+}
+function createMessage(state, sessionId, latestEventText) {
+    if (state.error) {
+        return state.error.message;
+    }
+    if (latestEventText) {
+        return latestEventText;
+    }
+    if (state.isWaiting && sessionId) {
+        return `Waiting for session ${sessionId} to finish.`;
+    }
+    if (state.session && sessionId) {
+        return `Session ${sessionId} is ready.`;
+    }
+    return null;
+}
+function createEventLog(state) {
+    const log = state.events.map((event) => createEventLogItem(event));
+    if (state.longPollResult) {
+        log.push({
+            type: 'otp.verified',
+            description: describeLongPollSuccess(state.longPollResult),
+            occurredAt: state.longPollResult.verifiedAt,
+            payload: state.longPollResult,
+        });
+    }
+    if (state.longPollFailure?.status === 'LOCKED') {
+        log.push({
+            type: 'otp.locked',
+            description: describeLongPollFailure(state.longPollFailure),
+            occurredAt: state.longPollFailure.lockedAt ?? null,
+            payload: state.longPollFailure,
+        });
+    }
+    if (state.longPollFailure?.status === 'EXPIRED') {
+        log.push({
+            type: 'otp.expired',
+            description: describeLongPollFailure(state.longPollFailure),
+            occurredAt: state.longPollFailure.expiredAt ?? null,
+            payload: state.longPollFailure,
+        });
+    }
+    return log;
+}
+function createEventLogItem(event) {
+    return {
+        type: event.event,
+        description: describeSessionEvent(event),
+        occurredAt: getSessionEventOccurredAt(event),
+        payload: event,
+    };
+}
+function describeSessionEvent(event) {
+    if (event.event === 'otp.subscribed') {
+        return `session ${event.data.sessionId} subscribed`;
+    }
+    if (event.event === 'otp.attempt') {
+        return `attempt ${event.data.attempts} of ${event.data.maxTries}, ${event.data.triesLeft} left`;
+    }
+    if (event.event === 'otp.locked') {
+        return `locked after ${event.data.attempts} attempt(s)`;
+    }
+    if (event.event === 'otp.verified') {
+        return `verified at ${event.data.verifiedAt}`;
+    }
+    return `expired session ${event.data.sessionId}`;
+}
+function describeLongPollSuccess(result) {
+    return `verified at ${result.verifiedAt}`;
+}
+function describeLongPollFailure(result) {
+    if (result.status === 'LOCKED') {
+        const attempts = typeof result.attempts === 'number' ? result.attempts : '?';
+        return `locked after ${attempts} attempt(s)`;
+    }
+    return `expired session ${result.sessionId}`;
+}
+function getSessionEventOccurredAt(event) {
+    if (event.event === 'otp.subscribed') {
+        return event.data.expiresAt;
+    }
+    if (event.event === 'otp.attempt') {
+        return event.data.attemptedAt;
+    }
+    if (event.event === 'otp.locked') {
+        return event.data.lockedAt;
+    }
+    if (event.event === 'otp.verified') {
+        return event.data.verifiedAt;
+    }
+    return null;
+}
+function resolveSessionId(state) {
+    return (state.session?.sessionId ??
+        state.verifiedEvent?.data.sessionId ??
+        state.lockedEvent?.data.sessionId ??
+        state.expiredEvent?.data.sessionId ??
+        state.longPollResult?.sessionId ??
+        state.longPollFailure?.sessionId ??
+        null);
+}
+function recordEvent(current, event, updates = {}) {
+    return {
+        ...current,
+        ...updates,
+        events: [...current.events, event],
+        lastEvent: event,
+        error: updates.error ?? current.error,
+    };
+}
+function resolveClient(options) {
+    if (options.client) {
+        return options.client;
+    }
+    return new SiymoOtpClient({
+        ...options.clientOptions,
+        baseUrl: options.baseUrl ?? resolveDefaultSiymoOtpBaseUrl(),
+        websocketBaseUrl: options.websocketBaseUrl,
+    });
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(typeof error === 'string' ? error : 'Unknown OTP hook error');
+}
+function isAbortLikeError(error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+        return true;
+    }
+    if (error instanceof SiymoOtpApiError && error.status === 0) {
+        const cause = getErrorCause(error);
+        return cause instanceof Error && cause.name === 'AbortError';
+    }
+    return false;
+}
+function getErrorCause(error) {
+    const value = error;
+    return value.cause;
+}
+function extractLongPollFailure(error) {
+    if (!(error instanceof SiymoOtpApiError)) {
+        return null;
+    }
+    if (isLongPollFailureResponse(error.body)) {
+        return error.body;
+    }
+    return null;
+}
+function isLongPollFailureResponse(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.sessionId === 'string' &&
+        typeof value.message === 'string' &&
+        (value.status === 'LOCKED' || value.status === 'EXPIRED'));
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isCurrentActiveWait(activeWaitRef, activeWait) {
+    return activeWaitRef.current?.id === activeWait.id;
+}
+async function stopActiveWait(activeWaitRef) {
+    const activeWait = activeWaitRef.current;
+    if (!activeWait) {
+        return;
+    }
+    finalizeActiveWait(activeWaitRef, activeWait);
+    activeWait.controller.abort();
+    activeWait.subscription?.close(1000, 'Cancelled');
+    if (activeWait.subscription) {
+        try {
+            await activeWait.subscription.closed;
+        }
+        catch {
+            // No extra handling needed during local hook cleanup.
+        }
+    }
+}
+function finalizeActiveWait(activeWaitRef, activeWait) {
+    if (activeWait.timeoutId) {
+        clearTimeout(activeWait.timeoutId);
+    }
+    if (activeWaitRef.current?.id === activeWait.id) {
+        activeWaitRef.current = null;
+    }
+}
+function scheduleWaitTimeout(activeWaitRef, activeWait, timeoutMs, sessionId, updateState) {
+    if (typeof timeoutMs !== 'number' || timeoutMs <= 0) {
+        return;
+    }
+    activeWait.timeoutId = setTimeout(() => {
+        if (!isCurrentActiveWait(activeWaitRef, activeWait)) {
+            return;
+        }
+        finalizeActiveWait(activeWaitRef, activeWait);
+        activeWait.controller.abort();
+        activeWait.subscription?.close(1000, 'Timed out');
+        updateState((current) => ({
+            ...current,
+            status: 'error',
+            error: new Error(`Timed out after ${timeoutMs} ms while waiting for session ${sessionId}.`),
+            isWaiting: false,
+        }));
+    }, timeoutMs);
+}

package/dist/useInboundSmsOtp.d.ts

@@ -0,0 +1,2 @@
+import type { UseInboundSmsOtpOptions, UseInboundSmsOtpResult } from './types.js';
+export declare function useInboundSmsOtp(options?: UseInboundSmsOtpOptions): UseInboundSmsOtpResult;

package/dist/useInboundSmsOtp.js

@@ -0,0 +1,65 @@
+import { useInboundOtpSession } from './useInboundOtp.js';
+export function useInboundSmsOtp(options = {}) {
+    const result = useInboundOtpSession({
+        options,
+        initiate(client, request) {
+            return client.initiateInboundSms(request);
+        },
+        selectData(input) {
+            return {
+                session: input.session,
+                sessionId: input.sessionId,
+                channel: input.session?.channel ?? null,
+                direction: input.session?.direction ?? null,
+                status: input.status,
+                attempts: input.attempts,
+                triesLeft: input.triesLeft,
+                length: input.session?.length ?? null,
+                expiresIn: input.session?.expiresIn ?? null,
+                maxTries: input.session?.maxTries ??
+                    input.lockedEvent?.data.maxTries ??
+                    input.longPollFailure?.maxTries ??
+                    null,
+                subscribedExpiresAt: input.subscribedExpiresAt,
+                lastEvent: input.lastEvent,
+                lastEventText: input.latestEventText,
+                servicePhone: input.session?.phone ??
+                    input.verifiedEvent?.data.serverPhone ??
+                    input.lockedEvent?.data.serverPhone ??
+                    input.longPollResult?.serverPhone ??
+                    input.longPollFailure?.serverPhone ??
+                    null,
+                senderPhone: input.session?.from ??
+                    input.verifiedEvent?.data.phone ??
+                    input.lockedEvent?.data.phone ??
+                    input.longPollResult?.phone ??
+                    input.longPollFailure?.phone ??
+                    null,
+                qrCodeImage: input.session?.qrCodeImage ?? null,
+                rawText: input.session?.text ?? null,
+                decodedText: decodeBase64Text(input.session?.text),
+            };
+        },
+    });
+    return {
+        ...result,
+        decodedText: result.data.decodedText,
+        qrCodeImage: result.data.qrCodeImage,
+    };
+}
+function decodeBase64Text(value) {
+    if (!value) {
+        return null;
+    }
+    if (typeof globalThis.atob !== 'function') {
+        return null;
+    }
+    try {
+        const binary = globalThis.atob(value);
+        const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+        return new TextDecoder().decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@siymo/otp-sdk-react",
+  "version": "0.1.0",
+  "description": "React hooks SDK for inbound call and inbound SMS OTP flows built on top of @siymo/otp-sdk-core",
+  "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": {
+    "prebuild": "node ./scripts/write-build-config.mjs",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "otp",
+    "react",
+    "hooks",
+    "sdk",
+    "websocket"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@siymo/otp-sdk-core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@siymo/otp-sdk-core": "^1.0.0",
+    "@types/react": "^18.3.3",
+    "react": "^18.3.1",
+    "typescript": "^5.0.0"
+  }
+}