@juspay/neurolink 9.64.0 → 9.65.1

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>;

package/dist/utils/logSanitize.js

@@ -0,0 +1,169 @@
+/**
+ * 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=…
+ */
+const TOKEN_PREFIXES = [
+    "sk",
+    "pk",
+    "r8",
+    "gsk",
+    "xai",
+    "tgp",
+    "fw",
+    "pplx",
+    "pa",
+    "jina",
+    "fish",
+];
+const PREFIX_PATTERN = TOKEN_PREFIXES.join("|");
+/**
+ * Pattern matching common bearer/API-key tokens in plain text.
+ *
+ * Case-insensitive (`i` flag) since header names ("Authorization") and scheme
+ * names ("Bearer", "Token", "Basic") are sometimes lower-cased in error
+ * bodies. `g` flag for replace-all.
+ */
+const SECRET_PATTERN = new RegExp(
+// Authorization schemes — required whitespace between scheme and value
+"\\bBearer\\s+[A-Za-z0-9_\\-\\.]{8,}\\b" +
+    "|\\bToken\\s+[A-Za-z0-9_\\-\\.]{8,}\\b" +
+    "|\\bBasic\\s+[A-Za-z0-9+/=]{12,}\\b" +
+    // Bare tokens by known prefix (e.g. `sk-abc…`, `r8_xyz…`)
+    `|\\b(?:${PREFIX_PATTERN})[_\\-][A-Za-z0-9_\\-\\.]{8,}\\b` +
+    // Generic key=value pairs (URL params, JSON bodies, header dumps)
+    "|\\b(?:api[_-]?key|access[_-]?token|secret[_-]?key|refresh[_-]?token)\\s*[:=]\\s*['\"]?[^\\s,;'\"&]+", "gi");
+/** Header names that should always be redacted regardless of value shape. */
+const SENSITIVE_HEADER_NAMES = [
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-csrf-token",
+];
+/** Object keys that should always be redacted regardless of value shape. */
+const SENSITIVE_OBJECT_KEYS = [
+    "apikey",
+    "api_key",
+    "apiKey",
+    "access_token",
+    "accessToken",
+    "refresh_token",
+    "refreshToken",
+    "secret",
+    "secretkey",
+    "secret_key",
+    "secretKey",
+    "password",
+    "authorization",
+    "oauth",
+    "oauthToken",
+    "credentials",
+];
+/**
+ * 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 function sanitizeForLog(text, maxLen = 500) {
+    if (!text) {
+        return text;
+    }
+    return text.slice(0, maxLen).replace(SECRET_PATTERN, "***");
+}
+/**
+ * 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 function sanitizeRecord(value, maxStringLen = 1000) {
+    const seen = new WeakSet();
+    const walk = (v) => {
+        if (v === null || v === undefined) {
+            return v;
+        }
+        if (typeof v === "string") {
+            return sanitizeForLog(v, maxStringLen);
+        }
+        if (typeof v !== "object") {
+            return v;
+        }
+        if (seen.has(v)) {
+            return "[Circular]";
+        }
+        seen.add(v);
+        if (Array.isArray(v)) {
+            return v.map(walk);
+        }
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (SENSITIVE_OBJECT_KEYS.some((name) => name.toLowerCase() === k.toLowerCase())) {
+                out[k] = "***";
+            }
+            else {
+                out[k] = walk(val);
+            }
+        }
+        return out;
+    };
+    return walk(value);
+}
+/**
+ * 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 function sanitizeHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    const out = {};
+    const set = (name, value) => {
+        if (value === undefined || value === null) {
+            return;
+        }
+        const lower = name.toLowerCase();
+        if (SENSITIVE_HEADER_NAMES.includes(lower)) {
+            out[name] = "***";
+            return;
+        }
+        out[name] = sanitizeForLog(value, 500);
+    };
+    if (headers instanceof Headers) {
+        headers.forEach((value, key) => set(key, value));
+        return out;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        set(key, value);
+    }
+    return out;
+}

package/dist/utils/loggingFetch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared logging-fetch wrapper.
+ *
+ * Wraps `createProxyFetch()` and logs every non-2xx upstream response with:
+ *   - provider label
+ *   - HTTP status code
+ *   - URL with embedded credentials / signed query params masked
+ *     (via `maskProxyUrl`)
+ *   - request body size (string-body only — multipart/streamed bodies
+ *     report 0)
+ *
+ * Response bodies are NOT logged by default (they can echo prompt fragments,
+ * tool payloads, or echoed auth tokens). Set `NEUROLINK_DEBUG_HTTP=1` to opt
+ * into body logging — and even then bodies are run through `sanitizeForLog`
+ * to redact `Bearer …`, `sk-…`, `Token …`, and the other 11 token formats
+ * covered by `logSanitize.SECRET_PATTERN`.
+ *
+ * Previously this same function was hand-rolled in 11 provider files
+ * (cohere, xai, groq, togetherAi, fireworks, perplexity, cloudflare,
+ * llamaCpp, lmStudio, nvidiaNim, deepseek) with subtly different bodies.
+ * Extracting it kills the drift risk and gives a single place to harden.
+ *
+ * @module utils/loggingFetch
+ */
+/**
+ * Construct a fetch-compatible function that logs upstream non-OK responses
+ * under the given provider label.
+ */
+export declare function createLoggingFetch(provider: string): typeof fetch;

package/dist/utils/loggingFetch.js

@@ -0,0 +1,59 @@
+/**
+ * Shared logging-fetch wrapper.
+ *
+ * Wraps `createProxyFetch()` and logs every non-2xx upstream response with:
+ *   - provider label
+ *   - HTTP status code
+ *   - URL with embedded credentials / signed query params masked
+ *     (via `maskProxyUrl`)
+ *   - request body size (string-body only — multipart/streamed bodies
+ *     report 0)
+ *
+ * Response bodies are NOT logged by default (they can echo prompt fragments,
+ * tool payloads, or echoed auth tokens). Set `NEUROLINK_DEBUG_HTTP=1` to opt
+ * into body logging — and even then bodies are run through `sanitizeForLog`
+ * to redact `Bearer …`, `sk-…`, `Token …`, and the other 11 token formats
+ * covered by `logSanitize.SECRET_PATTERN`.
+ *
+ * Previously this same function was hand-rolled in 11 provider files
+ * (cohere, xai, groq, togetherAi, fireworks, perplexity, cloudflare,
+ * llamaCpp, lmStudio, nvidiaNim, deepseek) with subtly different bodies.
+ * Extracting it kills the drift risk and gives a single place to harden.
+ *
+ * @module utils/loggingFetch
+ */
+import { createProxyFetch, maskProxyUrl } from "../proxy/proxyFetch.js";
+import { logger } from "./logger.js";
+import { sanitizeForLog } from "./logSanitize.js";
+/**
+ * Construct a fetch-compatible function that logs upstream non-OK responses
+ * under the given provider label.
+ */
+export function createLoggingFetch(provider) {
+    const base = createProxyFetch();
+    return (async (input, init) => {
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        const reqSize = init?.body && typeof init.body === "string" ? init.body.length : 0;
+        const response = await base(input, init);
+        if (!response.ok) {
+            const safeUrl = maskProxyUrl(url) ?? "<redacted>";
+            if (process.env.NEUROLINK_DEBUG_HTTP === "1") {
+                const clone = response.clone();
+                const raw = await clone.text().catch(() => "<unreadable>");
+                logger.warn(`[${provider}] upstream ${response.status}`, {
+                    url: safeUrl,
+                    body: sanitizeForLog(raw),
+                    reqSize,
+                });
+            }
+            else {
+                logger.warn(`[${provider}] upstream ${response.status} url=${safeUrl} reqSize=${reqSize}`);
+            }
+        }
+        return response;
+    });
+}

package/dist/utils/messageBuilder.js

@@ -602,6 +602,7 @@ export async function buildMessagesArray(options) {
  * Mutates options.input.files and options.input.text as needed.
  */
 function enforceFileBudget(options, provider, model) {
+    options.input ??= {};
     if (!options.input.files || options.input.files.length === 0) {
         return;
     }
@@ -659,6 +660,7 @@ function enforceFileBudget(options, provider, model) {
  * Handles CSV, SVG, image, PDF, video, audio, archive, xlsx, docx, pptx, text, and unknown types.
  */
 function appendDetectedFileResult(result, file, options) {
+    options.input ??= {};
     const filename = extractFilename(file);
     if (result.type === "csv") {
         const filePath = typeof file === "string" ? file : filename;
@@ -786,6 +788,7 @@ function appendDetectedFileResult(result, file, options) {
  * would silently never reach the model on those paths.
  */
 export async function processUnifiedFilesArray(options, maxSize, provider) {
+    options.input ??= {};
     if (!options.input.files || options.input.files.length === 0) {
         return;
     }
@@ -800,7 +803,12 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
         },
     }, async (span) => {
         logger.info(`[NEUROLINK] Processing ${totalFiles} file(s) with auto-detection`);
-        options.input.text = options.input.text || "";
+        // `options.input` was guaranteed non-null by the `??= {}` guard at the
+        // top of processUnifiedFilesArray; re-assert here so TypeScript is happy
+        // inside this withSpan closure (it doesn't track mutations across closures).
+        options.input ??= {};
+        const inp2 = options.input;
+        inp2.text = inp2.text || "";
         let includedCount = 0;
         const fileRegistry = options.fileRegistry;
         for (let fileIdx = 0; fileIdx < files.length; fileIdx++) {
@@ -862,16 +870,13 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
         if (fileRegistry && fileRegistry.size > 0) {
             const previewText = await fileRegistry.generatePromptPreview();
             if (previewText) {
-                options.input.text = (options.input.text || "") + previewText;
+                inp2.text = (inp2.text || "") + previewText;
                 logger.info(`[FileDetector] Injected previews for ${fileRegistry.size} lazily-registered file(s)`);
             }
             const registeredFiles = fileRegistry.list();
             for (const ref of registeredFiles) {
                 if (ref.extractedImages && ref.extractedImages.length > 0) {
-                    options.input.images = [
-                        ...(options.input.images || []),
-                        ...ref.extractedImages,
-                    ];
+                    inp2.images = [...(inp2.images || []), ...ref.extractedImages];
                     logger.info(`[FileDetector] Injected ${ref.extractedImages.length} extracted images from "${ref.filename}"`);
                 }
             }
@@ -901,6 +906,7 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
  * Process explicit CSV files array and append to options.input.text.
  */
 async function processExplicitCsvFiles(options) {
+    options.input ??= {};
     if (!options.input.csvFiles || options.input.csvFiles.length === 0) {
         return;
     }
@@ -942,6 +948,7 @@ async function processExplicitCsvFiles(options) {
  * Enforce post-processing budget on accumulated text content and log token usage.
  */
 function enforcePostProcessingBudget(options, provider, model) {
+    options.input ??= {};
     if (!options.input.text) {
         return;
     }
@@ -980,6 +987,7 @@ function enforcePostProcessingBudget(options, provider, model) {
  * Process explicit PDF files and return structured PDF entries for multimodal processing.
  */
 async function processExplicitPdfFiles(options, maxSize, provider) {
+    options.input ??= {};
     const pdfFiles = [];
     if (!options.input.pdfFiles || options.input.pdfFiles.length === 0) {
         return pdfFiles;
@@ -1015,6 +1023,7 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
  * conversation instructions, structured output instructions, and file handling guidance.
  */
 function buildMultimodalSystemPrompt(options, hasPDFFiles) {
+    options.input ??= {};
     let systemPrompt = options.systemPrompt?.trim() || "";
     const hasConversationHistory = options.conversationHistory && options.conversationHistory.length > 0;
     if (hasConversationHistory) {
@@ -1023,9 +1032,10 @@ function buildMultimodalSystemPrompt(options, hasPDFFiles) {
     if (shouldUseStructuredOutput(options)) {
         systemPrompt = `${systemPrompt.trim()}${STRUCTURED_OUTPUT_INSTRUCTIONS}`;
     }
-    const hasCSVFiles = (options.input.csvFiles && options.input.csvFiles.length > 0) ||
-        (options.input.files &&
-            options.input.files.some((f) => typeof f === "string" ? f.toLowerCase().endsWith(".csv") : false));
+    const inp = options.input;
+    const hasCSVFiles = (inp.csvFiles && inp.csvFiles.length > 0) ||
+        (inp.files &&
+            inp.files.some((f) => typeof f === "string" ? f.toLowerCase().endsWith(".csv") : false));
     if (hasCSVFiles || hasPDFFiles) {
         const fileTypes = [];
         if (hasPDFFiles) {
@@ -1049,6 +1059,16 @@ function buildMultimodalSystemPrompt(options, hasPDFFiles) {
  * Detects when images are present and routes through provider adapter
  */
 export async function buildMultimodalMessagesArray(options, provider, model) {
+    // Media-only callers (avatar / music / video) may omit `input` entirely.
+    // Normalise to an empty object so all sub-functions can access input.*
+    // without defensive null checks on every field access.
+    if (!options.input) {
+        options.input = {};
+    }
+    // After normalisation `input` is guaranteed non-undefined. Capture it in a
+    // local const so TypeScript sees the definite (non-optional) type in the
+    // rest of this function, avoiding 60+ "possibly undefined" errors.
+    const inp = options.input;
     // Compute provider-specific max PDF size once for consistent validation
     const pdfConfig = PDFProcessor.getProviderConfig(provider);
     const maxSize = pdfConfig
@@ -1065,20 +1085,19 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Process explicit PDF files
     const pdfFiles = await processExplicitPdfFiles(options, maxSize, provider);
     // Check if this is a multimodal request
-    const hasImages = (options.input.images && options.input.images.length > 0) ||
-        (options.input.content &&
-            options.input.content.some((c) => c.type === "image"));
+    const hasImages = (inp.images && inp.images.length > 0) ||
+        (inp.content && inp.content.some((c) => c.type === "image"));
     const hasPDFs = pdfFiles.length > 0;
     // If no images or PDFs, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages && !hasPDFs) {
-        if (options.input.csvFiles) {
-            options.input.csvFiles = [];
+        if (inp.csvFiles) {
+            inp.csvFiles = [];
         }
-        if (options.input.pdfFiles) {
-            options.input.pdfFiles = [];
+        if (inp.pdfFiles) {
+            inp.pdfFiles = [];
         }
-        if (options.input.files) {
-            options.input.files = [];
+        if (inp.files) {
+            inp.files = [];
         }
         const standardMessages = await buildMessagesArray(options);
         return standardMessages.map((msg) => {
@@ -1163,15 +1182,14 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Handle multimodal content
     try {
         let userContent;
-        if (options.input.content && options.input.content.length > 0) {
-            userContent = await convertContentToProviderFormat(options.input.content, provider, model);
+        if (inp.content && inp.content.length > 0) {
+            userContent = await convertContentToProviderFormat(inp.content, provider, model);
         }
-        else if ((options.input.images && options.input.images.length > 0) ||
-            pdfFiles.length > 0) {
-            userContent = await convertMultimodalToProviderFormat(options.input.text, options.input.images || [], pdfFiles, provider, model);
+        else if ((inp.images && inp.images.length > 0) || pdfFiles.length > 0) {
+            userContent = await convertMultimodalToProviderFormat(inp.text ?? "", inp.images || [], pdfFiles, provider, model);
         }
         else {
-            userContent = options.input.text;
+            userContent = inp.text;
         }
         if (typeof userContent === "string") {
             messages.push({
@@ -1195,7 +1213,7 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
             provider,
             model,
             hasImages,
-            imageCount: options.input.images?.length || 0,
+            imageCount: inp.images?.length || 0,
         });
         throw error;
     }