@juspay/neurolink 9.63.1 → 9.65.0

package/dist/utils/avatarProcessor.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
+import { NeuroLinkError } from "./errorHandling.js";
+import { logger } from "./logger.js";
+/**
+ * Avatar-specific error codes.
+ */
+export const AVATAR_ERROR_CODES = {
+    PROVIDER_NOT_SUPPORTED: "AVATAR_PROVIDER_NOT_SUPPORTED",
+    PROVIDER_NOT_CONFIGURED: "AVATAR_PROVIDER_NOT_CONFIGURED",
+    GENERATION_FAILED: "AVATAR_GENERATION_FAILED",
+    POLL_TIMEOUT: "AVATAR_POLL_TIMEOUT",
+    INVALID_INPUT: "AVATAR_INVALID_INPUT",
+    AUDIO_REQUIRED: "AVATAR_AUDIO_REQUIRED",
+    IMAGE_REQUIRED: "AVATAR_IMAGE_REQUIRED",
+    AUDIO_TOO_LONG: "AVATAR_AUDIO_TOO_LONG",
+};
+/**
+ * Typed error class for avatar-generation failures.
+ */
+export class AvatarError extends NeuroLinkError {
+    constructor(options) {
+        super({
+            code: options.code,
+            message: options.message,
+            category: options.category ?? ErrorCategory.EXECUTION,
+            severity: options.severity ?? ErrorSeverity.HIGH,
+            retriable: options.retriable ?? false,
+            context: options.context,
+            originalError: options.originalError,
+        });
+        this.name = "AvatarError";
+    }
+}
+/**
+ * Static processor managing the avatar handler registry.
+ */
+export class AvatarProcessor {
+    static handlers = new Map();
+    /**
+     * Register an avatar handler for a specific provider.
+     */
+    static registerHandler(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            logger.warn(`[AvatarProcessor] Overwriting existing handler for provider: ${key}`);
+        }
+        this.handlers.set(key, handler);
+        logger.debug(`[AvatarProcessor] Registered avatar handler: ${key}`);
+    }
+    /**
+     * Check if a provider has a registered avatar handler.
+     */
+    static supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    /**
+     * List the names of all registered providers.
+     */
+    static listProviders() {
+        return Array.from(this.handlers.keys());
+    }
+    static getHandler(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    static buildSpanAttributes(provider, options) {
+        return {
+            "avatar.operation": "generate",
+            "avatar.provider": provider,
+            "avatar.quality": options.quality,
+            "avatar.format": options.format,
+            "avatar.has_text": options.text !== undefined,
+            "avatar.has_audio": options.audio !== undefined,
+        };
+    }
+    /**
+     * Generate an avatar video via the registered handler.
+     *
+     * @throws AvatarError on registry miss, handler-not-configured, or
+     *         generation failure.
+     */
+    static async generate(provider, options) {
+        const span = SpanSerializer.createSpan(SpanType.MEDIA_GENERATION, "avatar.generate", this.buildSpanAttributes(provider, options));
+        try {
+            if (!options.image) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.IMAGE_REQUIRED,
+                    message: "Avatar generation requires an `image` (Buffer, path, or URL)",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            if (!options.audio && !options.text) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: "Avatar generation requires either `audio` (a Buffer/URL) or `text` (to be TTS'd by the provider).",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            const handler = this.getHandler(provider);
+            if (!handler) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.PROVIDER_NOT_SUPPORTED,
+                    message: `Avatar provider "${provider}" is not registered. Available: ${this.listProviders().join(", ")}`,
+                    category: ErrorCategory.CONFIGURATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider, available: this.listProviders() },
+                });
+            }
+            if (!handler.isConfigured()) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                    message: `Avatar provider "${provider}" is not configured. Set the required credentials.`,
+                    category: ErrorCategory.CONFIGURATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { provider },
+                });
+            }
+            logger.debug(`[AvatarProcessor] Starting avatar generation with provider: ${provider}`);
+            const result = await handler.generate(options);
+            const ended = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(ended);
+            logger.info(`[AvatarProcessor] Generated ${result.size} bytes (${provider})`);
+            return result;
+        }
+        catch (err) {
+            const ended = SpanSerializer.endSpan(span, SpanStatus.ERROR, err instanceof Error ? err.message : String(err));
+            getMetricsAggregator().recordSpan(ended);
+            if (err instanceof AvatarError) {
+                throw err;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `Avatar generation failed for provider "${provider}": ${message}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: { provider },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+}

package/dist/utils/cloneOptions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The set of top-level branches on a `StreamOptions` / `GenerateOptions`
+ * / `DynamicOptions` bag that downstream prep stages mutate. Listed here
+ * once so the runtime clone (`cloneOptionsForCallIsolation`) and any
+ * future test that wants to assert call isolation reference the same
+ * source of truth.
+ *
+ * If you add a new top-level field to `StreamOptions` that gets mutated
+ * by prepareStreamOptions / applyStreamOrchestration / RAG/MCP injection
+ * / memory retrieval / etc., add it here AND add an entry to
+ * `test/helpers/cloneOptions.test.ts` so the isolation guarantee gets
+ * exercised.
+ *
+ * Branches that are deliberately NOT cloned (and why):
+ *   - `signal` / `abortSignal` — `AbortSignal` can't be `structuredClone`d
+ *     and a shallow copy would strip the listener wiring.
+ *   - `tools[name].execute` — function identity is used as a cache key
+ *     downstream; cloning would break that.
+ *   - schema objects (zod / JSON Schema) — large, frequently frozen,
+ *     and not mutated by NeuroLink internals.
+ */
+export declare const CLONE_MUTABLE_OPTION_BRANCHES: readonly ["input", "context", "memory", "tools", "middleware", "rag", "csvOptions", "stt", "tts"];
+/**
+ * Defensive call-isolation clone for stream() / generate()-shaped inputs.
+ *
+ * Shallow-clones the top-level options bag plus every branch listed in
+ * `CLONE_MUTABLE_OPTION_BRANCHES`. Caller-supplied objects can be reused
+ * across calls without accumulating cross-call mutations from
+ * prepareStreamOptions, applyStreamOrchestration, memory retrieval, or
+ * RAG/MCP tool injection.
+ *
+ * Unclonable / by-reference values are deliberately kept by-reference —
+ * cloning them would either fail outright (`structuredClone(AbortSignal)`)
+ * or strip behavior (function identity used as a cache key).
+ */
+export declare function cloneOptionsForCallIsolation<T>(options: T): T;

package/dist/utils/cloneOptions.js

@@ -0,0 +1,61 @@
+/**
+ * The set of top-level branches on a `StreamOptions` / `GenerateOptions`
+ * / `DynamicOptions` bag that downstream prep stages mutate. Listed here
+ * once so the runtime clone (`cloneOptionsForCallIsolation`) and any
+ * future test that wants to assert call isolation reference the same
+ * source of truth.
+ *
+ * If you add a new top-level field to `StreamOptions` that gets mutated
+ * by prepareStreamOptions / applyStreamOrchestration / RAG/MCP injection
+ * / memory retrieval / etc., add it here AND add an entry to
+ * `test/helpers/cloneOptions.test.ts` so the isolation guarantee gets
+ * exercised.
+ *
+ * Branches that are deliberately NOT cloned (and why):
+ *   - `signal` / `abortSignal` — `AbortSignal` can't be `structuredClone`d
+ *     and a shallow copy would strip the listener wiring.
+ *   - `tools[name].execute` — function identity is used as a cache key
+ *     downstream; cloning would break that.
+ *   - schema objects (zod / JSON Schema) — large, frequently frozen,
+ *     and not mutated by NeuroLink internals.
+ */
+export const CLONE_MUTABLE_OPTION_BRANCHES = [
+    "input",
+    "context",
+    "memory",
+    "tools",
+    "middleware",
+    "rag",
+    "csvOptions",
+    "stt",
+    "tts",
+];
+/**
+ * Defensive call-isolation clone for stream() / generate()-shaped inputs.
+ *
+ * Shallow-clones the top-level options bag plus every branch listed in
+ * `CLONE_MUTABLE_OPTION_BRANCHES`. Caller-supplied objects can be reused
+ * across calls without accumulating cross-call mutations from
+ * prepareStreamOptions, applyStreamOrchestration, memory retrieval, or
+ * RAG/MCP tool injection.
+ *
+ * Unclonable / by-reference values are deliberately kept by-reference —
+ * cloning them would either fail outright (`structuredClone(AbortSignal)`)
+ * or strip behavior (function identity used as a cache key).
+ */
+export function cloneOptionsForCallIsolation(options) {
+    if (!options || typeof options !== "object") {
+        return options;
+    }
+    const cloned = { ...options };
+    const o = cloned;
+    for (const branch of CLONE_MUTABLE_OPTION_BRANCHES) {
+        const value = o[branch];
+        if (value && typeof value === "object") {
+            o[branch] = Array.isArray(value)
+                ? [...value]
+                : { ...value };
+        }
+    }
+    return cloned;
+}

package/dist/utils/lifecycleCallbacks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Lifecycle callback firing + dedupe.
+ *
+ * The same thrown error can travel through multiple layers that each
+ * want to surface it to the consumer's `onError`:
+ *   - LifecycleMiddleware's `wrapGenerate` / `wrapStream` catch
+ *   - `BaseProvider.wrapStreamWithLifecycleCallbacks` (raw-fetch
+ *     streaming providers that bypass AI SDK middleware)
+ *   - `BaseProvider.fireLifecycleErrorCallback` (top-level provider catch)
+ *   - `NeuroLink.generate()` / `NeuroLink.stream()` (early-resolution
+ *     failures, before the language model is wrapped)
+ *
+ * Without a shared dedupe these layers would fire `onError` multiple
+ * times for one logical failure. This module stamps a non-enumerable
+ * `Symbol.for("neurolink.onErrorFired")` on the error the first time
+ * a firing site is reached; subsequent sites observe the stamp and
+ * skip their own fire.
+ *
+ * `Symbol.for` (rather than a local Symbol) so the same key works
+ * across modules — anyone who can read the symbol can read the stamp.
+ *
+ * Frozen / sealed / non-extensible errors: `Object.defineProperty`
+ * throws, we catch and proceed. Worst case is a single duplicate fire
+ * (the pre-shared-marker behaviour). `WeakSet`-based bookkeeping
+ * would handle this case cleanly but the symbol stamp is preferred
+ * for cross-realm consistency: a Symbol.for-keyed property survives
+ * structuredClone / cross-realm postMessage where a closed-over
+ * WeakSet does not.
+ */
+import type { LifecycleErrorPayload, OnErrorCallback } from "../types/index.js";
+/**
+ * Returns true when `markLifecycleErrorFired` or a previous
+ * `fireOnErrorOnce` call has already stamped this error.
+ */
+export declare function hasLifecycleErrorFired(error: unknown): boolean;
+/**
+ * Stamps the error as already-fired without invoking any callback.
+ * Use this from sites that already invoked `onError` via their own
+ * path (e.g. a provider-specific raw-fetch stream wrapper) so the
+ * shared dedupe still works.
+ */
+export declare function markLifecycleErrorFired(error: unknown): void;
+/**
+ * Fire the consumer's `onError` once per logical failure.
+ *
+ * - No-op when `onError` is missing.
+ * - No-op when the error is already stamped (any prior layer fired).
+ * - Otherwise: stamps the error, then invokes the callback.
+ *
+ * The callback is fire-and-forget; rejections are swallowed so a
+ * faulty handler can't mask the original throw. Callers that need
+ * to AWAIT the callback (e.g. to enforce a timeout) should use
+ * `hasLifecycleErrorFired` + `markLifecycleErrorFired` directly and
+ * run the callback themselves.
+ */
+export declare function fireOnErrorOnce(onError: OnErrorCallback | undefined, error: unknown, payload: LifecycleErrorPayload): void;

package/dist/utils/lifecycleCallbacks.js

@@ -0,0 +1,99 @@
+/**
+ * Lifecycle callback firing + dedupe.
+ *
+ * The same thrown error can travel through multiple layers that each
+ * want to surface it to the consumer's `onError`:
+ *   - LifecycleMiddleware's `wrapGenerate` / `wrapStream` catch
+ *   - `BaseProvider.wrapStreamWithLifecycleCallbacks` (raw-fetch
+ *     streaming providers that bypass AI SDK middleware)
+ *   - `BaseProvider.fireLifecycleErrorCallback` (top-level provider catch)
+ *   - `NeuroLink.generate()` / `NeuroLink.stream()` (early-resolution
+ *     failures, before the language model is wrapped)
+ *
+ * Without a shared dedupe these layers would fire `onError` multiple
+ * times for one logical failure. This module stamps a non-enumerable
+ * `Symbol.for("neurolink.onErrorFired")` on the error the first time
+ * a firing site is reached; subsequent sites observe the stamp and
+ * skip their own fire.
+ *
+ * `Symbol.for` (rather than a local Symbol) so the same key works
+ * across modules — anyone who can read the symbol can read the stamp.
+ *
+ * Frozen / sealed / non-extensible errors: `Object.defineProperty`
+ * throws, we catch and proceed. Worst case is a single duplicate fire
+ * (the pre-shared-marker behaviour). `WeakSet`-based bookkeeping
+ * would handle this case cleanly but the symbol stamp is preferred
+ * for cross-realm consistency: a Symbol.for-keyed property survives
+ * structuredClone / cross-realm postMessage where a closed-over
+ * WeakSet does not.
+ */
+const ON_ERROR_FIRED = Symbol.for("neurolink.onErrorFired");
+function stampFired(error) {
+    try {
+        Object.defineProperty(error, ON_ERROR_FIRED, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    catch {
+        // Non-extensible — fall through; worst case is a duplicate fire.
+    }
+}
+/**
+ * Returns true when `markLifecycleErrorFired` or a previous
+ * `fireOnErrorOnce` call has already stamped this error.
+ */
+export function hasLifecycleErrorFired(error) {
+    if (error === null || typeof error !== "object") {
+        return false;
+    }
+    return error[ON_ERROR_FIRED] === true;
+}
+/**
+ * Stamps the error as already-fired without invoking any callback.
+ * Use this from sites that already invoked `onError` via their own
+ * path (e.g. a provider-specific raw-fetch stream wrapper) so the
+ * shared dedupe still works.
+ */
+export function markLifecycleErrorFired(error) {
+    if (error === null || typeof error !== "object") {
+        return;
+    }
+    if (error[ON_ERROR_FIRED] === true) {
+        return;
+    }
+    stampFired(error);
+}
+/**
+ * Fire the consumer's `onError` once per logical failure.
+ *
+ * - No-op when `onError` is missing.
+ * - No-op when the error is already stamped (any prior layer fired).
+ * - Otherwise: stamps the error, then invokes the callback.
+ *
+ * The callback is fire-and-forget; rejections are swallowed so a
+ * faulty handler can't mask the original throw. Callers that need
+ * to AWAIT the callback (e.g. to enforce a timeout) should use
+ * `hasLifecycleErrorFired` + `markLifecycleErrorFired` directly and
+ * run the callback themselves.
+ */
+export function fireOnErrorOnce(onError, error, payload) {
+    if (typeof onError !== "function") {
+        return;
+    }
+    if (hasLifecycleErrorFired(error)) {
+        return;
+    }
+    if (error !== null && typeof error === "object") {
+        stampFired(error);
+    }
+    try {
+        const result = onError(payload);
+        Promise.resolve(result).catch(() => undefined);
+    }
+    catch {
+        // Consumer callback errors must not poison the original throw.
+    }
+}

package/dist/utils/lifecycleTimeout.d.ts

@@ -0,0 +1,25 @@
+import type { LifecycleMiddlewareConfig } from "../types/index.js";
+/**
+ * Default deadline applied to consumer-supplied lifecycle callbacks
+ * (`onChunk`, `onFinish`, `onError`) when neither
+ * `LifecycleMiddlewareConfig.timeoutMs` nor the
+ * `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env var is set.
+ *
+ * 5s is generous — far longer than legitimate sync logging, far
+ * shorter than a stuck network call. Callers with slow telemetry
+ * sinks should set `timeoutMs` explicitly.
+ */
+export declare const DEFAULT_LIFECYCLE_TIMEOUT_MS = 5000;
+/**
+ * Resolve the deadline for a single lifecycle callback invocation.
+ *
+ * Order of precedence:
+ *   1. `lifecycle.timeoutMs` from the per-call SDK config
+ *   2. `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env var (also honored by the CLI)
+ *   3. `DEFAULT_LIFECYCLE_TIMEOUT_MS` (5_000)
+ *
+ * Negative / non-finite values fall through to the next source. `0`
+ * is accepted and means "no wait" (the consumer's async work is
+ * effectively fire-and-forget).
+ */
+export declare function resolveLifecycleTimeoutMs(lifecycle?: Pick<LifecycleMiddlewareConfig, "timeoutMs"> | null): number;

package/dist/utils/lifecycleTimeout.js

@@ -0,0 +1,38 @@
+/**
+ * Default deadline applied to consumer-supplied lifecycle callbacks
+ * (`onChunk`, `onFinish`, `onError`) when neither
+ * `LifecycleMiddlewareConfig.timeoutMs` nor the
+ * `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env var is set.
+ *
+ * 5s is generous — far longer than legitimate sync logging, far
+ * shorter than a stuck network call. Callers with slow telemetry
+ * sinks should set `timeoutMs` explicitly.
+ */
+export const DEFAULT_LIFECYCLE_TIMEOUT_MS = 5_000;
+/**
+ * Resolve the deadline for a single lifecycle callback invocation.
+ *
+ * Order of precedence:
+ *   1. `lifecycle.timeoutMs` from the per-call SDK config
+ *   2. `NEUROLINK_LIFECYCLE_TIMEOUT_MS` env var (also honored by the CLI)
+ *   3. `DEFAULT_LIFECYCLE_TIMEOUT_MS` (5_000)
+ *
+ * Negative / non-finite values fall through to the next source. `0`
+ * is accepted and means "no wait" (the consumer's async work is
+ * effectively fire-and-forget).
+ */
+export function resolveLifecycleTimeoutMs(lifecycle) {
+    if (lifecycle && typeof lifecycle.timeoutMs === "number") {
+        if (Number.isFinite(lifecycle.timeoutMs) && lifecycle.timeoutMs >= 0) {
+            return lifecycle.timeoutMs;
+        }
+    }
+    const raw = process.env.NEUROLINK_LIFECYCLE_TIMEOUT_MS;
+    if (raw) {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_LIFECYCLE_TIMEOUT_MS;
+}

package/dist/utils/logSanitize.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared log-sanitization helpers.
+ *
+ * Centralises truncate + secret-redaction patterns so every provider stays
+ * consistent and any regex improvements only need one change.
+ *
+ * Coverage:
+ *   - `Authorization: Bearer <token>` (with required whitespace)
+ *   - `Authorization: Token <token>` (Replicate uses this, not Bearer)
+ *   - `Authorization: Basic <base64>` (D-ID and similar)
+ *   - Bare tokens by known provider prefix:
+ *     sk-/pk- (OpenAI, Anthropic, Stability),
+ *     r8_ (Replicate), gsk_ (Groq), xai- (xAI), tgp_ (Together),
+ *     fw_ (Fireworks), pplx- (Perplexity), pa- (Voyage),
+ *     jina_ (Jina), fish- (Fish Audio)
+ *   - Generic key=value pairs: api_key=…, access_token: …, secret_key=…
+ */
+/**
+ * Truncate `text` to `maxLen` chars then replace embedded secrets with `***`.
+ *
+ * Use this for free-form text logged from response/request bodies. For
+ * structured data (records, headers) prefer {@link sanitizeRecord} and
+ * {@link sanitizeHeaders} which know to redact by key name as well.
+ *
+ * @param text   - Raw text to sanitize (typically an HTTP response body).
+ * @param maxLen - Maximum number of characters to keep (default 500).
+ */
+export declare function sanitizeForLog(text: string, maxLen?: number): string;
+/**
+ * Recursively sanitize a record/array, returning a structurally identical
+ * value with sensitive keys redacted and string values run through
+ * {@link sanitizeForLog}.
+ *
+ * Safe to call on any JSON-shaped data. Cycles are detected and replaced
+ * with the string `"[Circular]"` to avoid infinite recursion when logging
+ * mid-stream objects that reference themselves.
+ *
+ * @param value - The value to sanitize.
+ * @param maxStringLen - Per-string truncation cap (default 1000).
+ */
+export declare function sanitizeRecord<T>(value: T, maxStringLen?: number): T;
+/**
+ * Sanitize an HTTP headers object — redacts sensitive header names entirely
+ * (`***`) and applies {@link sanitizeForLog} to remaining values.
+ *
+ * Accepts both `Headers` instances and plain-object header maps so providers
+ * can log either shape uniformly.
+ */
+export declare function sanitizeHeaders(headers: Headers | Record<string, string | undefined> | undefined): Record<string, string>;