@juspay/neurolink 11.13.0 → 11.13.2

package/dist/lib/utils/async/retry.js

@@ -1,172 +0,0 @@
-/**
- * Retry Utilities
- *
- * Provides retry logic with exponential backoff for resilient async operations.
- */
-import { delay } from "./delay.js";
-/**
- * Default retry configuration.
- */
-export const DEFAULT_RETRY_OPTIONS = {
-    maxAttempts: 3,
-    initialDelay: 1000,
-    maxDelay: 30000,
-    backoffMultiplier: 2,
-};
-/**
- * Calculate exponential backoff delay with optional jitter.
- *
- * Uses the formula: min(baseDelay * 2^(attempt-1) + jitter, maxDelay)
- *
- * @param attempt - Current attempt number (1-based)
- * @param baseDelayMs - Base delay in milliseconds
- * @param maxDelayMs - Maximum delay cap in milliseconds
- * @param addJitter - Whether to add random jitter (default: true)
- * @returns Calculated delay in milliseconds
- *
- * @example
- * ```typescript
- * // Without jitter
- * calculateBackoff(1, 1000, 30000, false); // 1000ms
- * calculateBackoff(2, 1000, 30000, false); // 2000ms
- * calculateBackoff(3, 1000, 30000, false); // 4000ms
- *
- * // With jitter (adds up to 10% random delay)
- * calculateBackoff(3, 1000, 30000, true); // ~4000-4400ms
- * ```
- */
-export function calculateBackoff(attempt, baseDelayMs, maxDelayMs, addJitter = true) {
-    const exponentialDelay = baseDelayMs * 2 ** (attempt - 1);
-    if (addJitter) {
-        // Add up to 10% jitter to prevent thundering herd
-        const jitter = Math.random() * 0.1 * exponentialDelay;
-        return Math.min(exponentialDelay + jitter, maxDelayMs);
-    }
-    return Math.min(exponentialDelay, maxDelayMs);
-}
-/**
- * Error thrown when all retry attempts are exhausted.
- */
-export class RetryExhaustedError extends Error {
-    attempts;
-    lastError;
-    /**
-     * Creates a new RetryExhaustedError.
-     *
-     * @param message - Error message
-     * @param attempts - Total number of attempts made
-     * @param lastError - The last error that caused the final failure
-     */
-    constructor(message, attempts, lastError) {
-        super(message);
-        this.attempts = attempts;
-        this.lastError = lastError;
-        this.name = "RetryExhaustedError";
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, RetryExhaustedError);
-        }
-    }
-}
-/**
- * Retry an async function with exponential backoff.
- *
- * Executes the provided function and retries on failure according to
- * the specified options. Uses exponential backoff between retries.
- *
- * @param fn - Async function to execute
- * @param options - Retry configuration (merged with defaults)
- * @returns Promise that resolves with the function result
- * @throws The last error if all retries are exhausted
- *
- * @example
- * ```typescript
- * // Basic usage with defaults
- * const data = await retry(() => fetchFromAPI());
- * ```
- *
- * @example
- * ```typescript
- * // With custom options
- * const data = await retry(
- *   () => fetchFromAPI(),
- *   {
- *     maxRetries: 5,
- *     baseDelayMs: 500,
- *     maxDelayMs: 10000,
- *     onRetry: (err, attempt, delay) => {
- *       console.log(`Retry ${attempt} after ${delay}ms: ${err.message}`);
- *     },
- *     shouldRetry: (err) => {
- *       // Only retry on network errors
- *       return err.name === 'NetworkError';
- *     }
- *   }
- * );
- * ```
- */
-export async function retry(fn, options = {}) {
-    const config = {
-        ...DEFAULT_RETRY_OPTIONS,
-        ...options,
-    };
-    const { maxAttempts, initialDelay, maxDelay, backoffMultiplier, retryCondition = () => true, onRetry, } = config;
-    let lastError = new Error("Retry failed");
-    let currentDelay = initialDelay;
-    // Total attempts = initial attempt + retries
-    const totalAttempts = maxAttempts + 1;
-    for (let attempt = 1; attempt <= totalAttempts; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            lastError = err;
-            // Check if we've exhausted all retries
-            if (attempt >= totalAttempts) {
-                throw new RetryExhaustedError(`All ${totalAttempts} retry attempts exhausted`, totalAttempts, err);
-            }
-            // Check if we should retry this error
-            if (!retryCondition(err)) {
-                throw err;
-            }
-            // Calculate delay with exponential backoff (capped at maxDelay)
-            const delayMs = Math.min(currentDelay, maxDelay);
-            // Notify about retry
-            if (onRetry) {
-                onRetry(attempt, err);
-            }
-            // Wait before next attempt
-            await delay(delayMs);
-            // Increase delay for next iteration
-            currentDelay = currentDelay * backoffMultiplier;
-        }
-    }
-    // This should never be reached, but TypeScript needs it
-    throw new RetryExhaustedError(`All ${totalAttempts} retry attempts exhausted`, totalAttempts, lastError || new Error("Unknown retry failure"));
-}
-/**
- * Create a retry wrapper with pre-configured options.
- *
- * Useful for creating reusable retry strategies.
- *
- * @param defaultOptions - Default retry options for the wrapper
- * @returns A retry function with the specified defaults
- *
- * @example
- * ```typescript
- * const apiRetry = createRetry({
- *   maxRetries: 5,
- *   baseDelayMs: 100,
- *   onRetry: (err, attempt) => logger.warn(`API retry ${attempt}`)
- * });
- *
- * // Use the configured retry
- * const data = await apiRetry(() => fetchFromAPI());
- * ```
- */
-export function createRetry(defaultOptions) {
-    return (fn, overrideOptions) => {
-        return retry(fn, { ...defaultOptions, ...overrideOptions });
-    };
-}
-//# sourceMappingURL=retry.js.map

package/dist/lib/utils/async/withTimeout.d.ts

@@ -1,85 +0,0 @@
-/**
- * Timeout Utilities
- *
- * Wrapper functions for adding timeout protection to async operations.
- */
-/**
- * Error thrown when an operation times out.
- */
-export declare class TimeoutError extends Error {
-    readonly timeoutMs: number;
-    /**
-     * Creates a new TimeoutError.
-     *
-     * @param message - Error message describing the timeout
-     * @param timeoutMs - The timeout duration that was exceeded
-     */
-    constructor(message: string, timeoutMs: number);
-}
-/**
- * Execute a promise with timeout protection.
- *
- * Wraps a promise and rejects with a TimeoutError if the operation
- * takes longer than the specified duration.
- *
- * @param promise - The promise to wrap with timeout
- * @param ms - Maximum time to wait in milliseconds
- * @param message - Optional custom error message for timeout
- * @returns Promise that resolves with the result or rejects on timeout
- * @throws {TimeoutError} If the operation exceeds the timeout duration
- *
- * @example
- * ```typescript
- * const result = await withTimeout(
- *   fetchData(),
- *   5000,
- *   'Data fetch timed out'
- * );
- * ```
- *
- * @example
- * ```typescript
- * try {
- *   const data = await withTimeout(slowOperation(), 3000);
- * } catch (error) {
- *   if (error instanceof TimeoutError) {
- *     console.log(`Timed out after ${error.timeoutMs}ms`);
- *   }
- * }
- * ```
- */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
-/**
- * Race a promise against an AbortSignal so the caller observes an abort
- * IMMEDIATELY instead of waiting for the operation to settle (or for a
- * separate timeout to expire). Rejects with an abort-shaped error
- * (`name === "AbortError"`) so provider loops route it to their existing
- * cancellation handling.
- *
- * The underlying operation is NOT cancelled — it continues as a bounded
- * ghost (the same tradeoff as {@link withTimeout}); its eventual settlement
- * is swallowed so it can never surface as an unhandled rejection.
- */
-export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
-/**
- * Execute a function with timeout protection.
- *
- * Alternative signature that accepts a function instead of a promise,
- * useful when you want to delay starting the operation.
- *
- * @param fn - Async function to execute
- * @param ms - Maximum time to wait in milliseconds
- * @param message - Optional custom error message for timeout
- * @returns Promise that resolves with the function result or rejects on timeout
- * @throws {TimeoutError} If the operation exceeds the timeout duration
- *
- * @example
- * ```typescript
- * const result = await withTimeoutFn(
- *   () => fetchData(),
- *   5000,
- *   'Data fetch timed out'
- * );
- * ```
- */
-export declare function withTimeoutFn<T>(fn: () => Promise<T>, ms: number, message?: string): Promise<T>;

package/dist/lib/utils/async/withTimeout.js

@@ -1,144 +0,0 @@
-/**
- * Timeout Utilities
- *
- * Wrapper functions for adding timeout protection to async operations.
- */
-/**
- * Error thrown when an operation times out.
- */
-export class TimeoutError extends Error {
-    timeoutMs;
-    /**
-     * Creates a new TimeoutError.
-     *
-     * @param message - Error message describing the timeout
-     * @param timeoutMs - The timeout duration that was exceeded
-     */
-    constructor(message, timeoutMs) {
-        super(message);
-        this.timeoutMs = timeoutMs;
-        this.name = "TimeoutError";
-        // Maintains proper stack trace for where error was thrown (V8 engines)
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, TimeoutError);
-        }
-    }
-}
-/**
- * Execute a promise with timeout protection.
- *
- * Wraps a promise and rejects with a TimeoutError if the operation
- * takes longer than the specified duration.
- *
- * @param promise - The promise to wrap with timeout
- * @param ms - Maximum time to wait in milliseconds
- * @param message - Optional custom error message for timeout
- * @returns Promise that resolves with the result or rejects on timeout
- * @throws {TimeoutError} If the operation exceeds the timeout duration
- *
- * @example
- * ```typescript
- * const result = await withTimeout(
- *   fetchData(),
- *   5000,
- *   'Data fetch timed out'
- * );
- * ```
- *
- * @example
- * ```typescript
- * try {
- *   const data = await withTimeout(slowOperation(), 3000);
- * } catch (error) {
- *   if (error instanceof TimeoutError) {
- *     console.log(`Timed out after ${error.timeoutMs}ms`);
- *   }
- * }
- * ```
- */
-export async function withTimeout(promise, ms, message) {
-    let timeoutId;
-    const timeoutPromise = new Promise((_, reject) => {
-        timeoutId = setTimeout(() => {
-            reject(new TimeoutError(message || `Operation timed out after ${ms}ms`, ms));
-        }, ms);
-    });
-    try {
-        return await Promise.race([promise, timeoutPromise]);
-    }
-    finally {
-        if (timeoutId !== undefined) {
-            clearTimeout(timeoutId);
-        }
-    }
-}
-/**
- * Race a promise against an AbortSignal so the caller observes an abort
- * IMMEDIATELY instead of waiting for the operation to settle (or for a
- * separate timeout to expire). Rejects with an abort-shaped error
- * (`name === "AbortError"`) so provider loops route it to their existing
- * cancellation handling.
- *
- * The underlying operation is NOT cancelled — it continues as a bounded
- * ghost (the same tradeoff as {@link withTimeout}); its eventual settlement
- * is swallowed so it can never surface as an unhandled rejection.
- */
-export async function raceWithAbort(promise, signal) {
-    if (!signal || typeof signal.addEventListener !== "function") {
-        return promise;
-    }
-    const makeAbortError = () => {
-        const e = new Error("Operation aborted");
-        e.name = "AbortError";
-        return e;
-    };
-    if (signal.aborted) {
-        promise.catch(() => {
-            // Swallow the abandoned settlement — it must never surface as an
-            // unhandled rejection after the race has already been decided.
-        });
-        return Promise.reject(makeAbortError());
-    }
-    return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            promise.catch(() => {
-                // Swallow the abandoned settlement — it must never surface as an
-                // unhandled rejection after the race has already been decided.
-            });
-            reject(makeAbortError());
-        };
-        signal.addEventListener("abort", onAbort, { once: true });
-        promise.then((value) => {
-            signal.removeEventListener("abort", onAbort);
-            resolve(value);
-        }, (error) => {
-            signal.removeEventListener("abort", onAbort);
-            reject(error);
-        });
-    });
-}
-/**
- * Execute a function with timeout protection.
- *
- * Alternative signature that accepts a function instead of a promise,
- * useful when you want to delay starting the operation.
- *
- * @param fn - Async function to execute
- * @param ms - Maximum time to wait in milliseconds
- * @param message - Optional custom error message for timeout
- * @returns Promise that resolves with the function result or rejects on timeout
- * @throws {TimeoutError} If the operation exceeds the timeout duration
- *
- * @example
- * ```typescript
- * const result = await withTimeoutFn(
- *   () => fetchData(),
- *   5000,
- *   'Data fetch timed out'
- * );
- * ```
- */
-export async function withTimeoutFn(fn, ms, message) {
-    return withTimeout(fn(), ms, message);
-}
-//# sourceMappingURL=withTimeout.js.map

package/dist/lib/utils/asyncMutex.d.ts

@@ -1,14 +0,0 @@
-/**
- * Promise-based async mutex for serializing concurrent async operations.
- * No external dependencies — uses a simple FIFO queue of pending resolvers.
- */
-export declare class AsyncMutex {
-    /** Default timeout for lock-held operations: 30 seconds */
-    private static readonly DEFAULT_TIMEOUT_MS;
-    private _locked;
-    private _queue;
-    isLocked(): boolean;
-    runExclusive<T>(fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
-    private _acquire;
-    private _release;
-}

package/dist/lib/utils/asyncMutex.js

@@ -1,61 +0,0 @@
-/**
- * Promise-based async mutex for serializing concurrent async operations.
- * No external dependencies — uses a simple FIFO queue of pending resolvers.
- */
-export class AsyncMutex {
-    /** Default timeout for lock-held operations: 30 seconds */
-    static DEFAULT_TIMEOUT_MS = 30_000;
-    _locked = false;
-    _queue = [];
-    isLocked() {
-        return this._locked;
-    }
-    async runExclusive(fn, timeoutMs = AsyncMutex.DEFAULT_TIMEOUT_MS) {
-        await this._acquire();
-        let timer;
-        // Store fn()'s promise so we can ensure it settles before releasing the lock,
-        // even when the timeout fires first.
-        const fnPromise = fn();
-        try {
-            return await Promise.race([
-                fnPromise,
-                new Promise((_resolve, reject) => {
-                    timer = setTimeout(() => reject(new Error(`AsyncMutex: lock-held operation timed out after ${timeoutMs}ms`)), timeoutMs);
-                }),
-            ]);
-        }
-        finally {
-            if (timer !== undefined) {
-                clearTimeout(timer);
-            }
-            // Wait for fn() to settle before releasing the lock.
-            // If the timeout fired, fn() may still be running — we must not
-            // let another caller acquire the lock until fn() completes.
-            await fnPromise.catch((_settleErr) => {
-                // Intentionally swallowed — we only await settlement to keep
-                // the lock held until fn() finishes. The caller already received
-                // the timeout rejection from Promise.race above.
-            });
-            this._release();
-        }
-    }
-    _acquire() {
-        if (!this._locked) {
-            this._locked = true;
-            return Promise.resolve();
-        }
-        return new Promise((resolve) => {
-            this._queue.push(resolve);
-        });
-    }
-    _release() {
-        const next = this._queue.shift();
-        if (next) {
-            next();
-        }
-        else {
-            this._locked = false;
-        }
-    }
-}
-//# sourceMappingURL=asyncMutex.js.map

package/dist/lib/utils/audioFormatDetector.d.ts

@@ -1,15 +0,0 @@
-/**
- * Shared utility: infer a `TTSAudioFormat` from a file path.
- *
- * Used by the CLI generate/stream handlers (m2) to set `stt.format` so
- * `STTProcessor.transcribe()` can fail fast on incompatible provider/format
- * combinations (e.g. MP3 to azure-stt). Pulled into a single helper to
- * avoid duplicating the 11-element format list across two CLI handlers.
- */
-import type { TTSAudioFormat } from "../types/index.js";
-/**
- * Returns the `TTSAudioFormat` that matches the file extension of `path`,
- * or `undefined` when the path is missing or its extension isn't a known
- * audio format. The check is case-insensitive.
- */
-export declare function inferAudioFormatFromPath(path: string | undefined): TTSAudioFormat | undefined;

package/dist/lib/utils/audioFormatDetector.js

@@ -1,34 +0,0 @@
-/**
- * Shared utility: infer a `TTSAudioFormat` from a file path.
- *
- * Used by the CLI generate/stream handlers (m2) to set `stt.format` so
- * `STTProcessor.transcribe()` can fail fast on incompatible provider/format
- * combinations (e.g. MP3 to azure-stt). Pulled into a single helper to
- * avoid duplicating the 11-element format list across two CLI handlers.
- */
-const VALID_FORMATS = [
-    "mp3",
-    "wav",
-    "ogg",
-    "opus",
-    "m4a",
-    "flac",
-    "webm",
-    "mp4",
-    "mpeg",
-    "mpga",
-    "pcm16",
-];
-/**
- * Returns the `TTSAudioFormat` that matches the file extension of `path`,
- * or `undefined` when the path is missing or its extension isn't a known
- * audio format. The check is case-insensitive.
- */
-export function inferAudioFormatFromPath(path) {
-    if (!path) {
-        return undefined;
-    }
-    const ext = path.toLowerCase().split(".").pop();
-    return ext && VALID_FORMATS.includes(ext) ? ext : undefined;
-}
-//# sourceMappingURL=audioFormatDetector.js.map

package/dist/lib/utils/avatarProcessor.d.ts

@@ -1,78 +0,0 @@
-/**
- * Avatar / Lip-sync Generation Processing Utility
- *
- * Central registry + dispatch for avatar handlers across providers
- * (D-ID, HeyGen, Replicate-hosted MuseTalk / SadTalker / Wav2Lip).
- *
- * Mirrors the static-handler-registry pattern established by
- * `TTSProcessor` / `STTProcessor` / `VideoProcessor` / `MusicProcessor`.
- *
- * @module utils/avatarProcessor
- */
-import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
-import type { AvatarHandler, AvatarOptions, AvatarResult } from "../types/index.js";
-import { NeuroLinkError } from "./errorHandling.js";
-/**
- * Avatar-specific error codes.
- */
-export declare const AVATAR_ERROR_CODES: {
-    readonly PROVIDER_NOT_SUPPORTED: "AVATAR_PROVIDER_NOT_SUPPORTED";
-    readonly PROVIDER_NOT_CONFIGURED: "AVATAR_PROVIDER_NOT_CONFIGURED";
-    readonly GENERATION_FAILED: "AVATAR_GENERATION_FAILED";
-    readonly POLL_TIMEOUT: "AVATAR_POLL_TIMEOUT";
-    readonly INVALID_INPUT: "AVATAR_INVALID_INPUT";
-    readonly AUDIO_REQUIRED: "AVATAR_AUDIO_REQUIRED";
-    readonly IMAGE_REQUIRED: "AVATAR_IMAGE_REQUIRED";
-    readonly AUDIO_TOO_LONG: "AVATAR_AUDIO_TOO_LONG";
-};
-/**
- * Typed error class for avatar-generation failures.
- */
-export declare class AvatarError extends NeuroLinkError {
-    constructor(options: {
-        code: string;
-        message: string;
-        category?: ErrorCategory;
-        severity?: ErrorSeverity;
-        retriable?: boolean;
-        context?: Record<string, unknown>;
-        originalError?: Error;
-    });
-}
-/**
- * Static processor managing the avatar handler registry.
- */
-export declare class AvatarProcessor {
-    private static readonly registry;
-    /**
-     * Register an avatar handler for a specific provider.
-     */
-    static registerHandler(providerName: string, handler: AvatarHandler): void;
-    /**
-     * Check if a provider has a registered avatar handler.
-     */
-    static supports(providerName: string): boolean;
-    /**
-     * List the names of all registered providers.
-     */
-    static listProviders(): string[];
-    /**
-     * Get a registered avatar handler by provider name.
-     *
-     * Exposed publicly so module-level auto-registration code can reuse an
-     * already-registered primary handler when backfilling its aliases.
-     */
-    static getHandler(providerName: string): AvatarHandler | undefined;
-    /**
-     * Clear all registered handlers (for testing).
-     */
-    static clearHandlers(): void;
-    private static buildSpanAttributes;
-    /**
-     * Generate an avatar video via the registered handler.
-     *
-     * @throws AvatarError on registry miss, handler-not-configured, or
-     *         generation failure.
-     */
-    static generate(provider: string, options: AvatarOptions): Promise<AvatarResult>;
-}