@juspay/neurolink 9.1.0 → 9.2.0

package/dist/utils/json/safeParse.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Safe JSON Parsing Utilities
+ *
+ * Centralized JSON parsing utilities that handle errors gracefully.
+ * Provides safe parsing that doesn't throw on invalid JSON.
+ */
+/**
+ * Result type for safe JSON parsing operations
+ */
+export interface SafeParseResult<T> {
+    success: boolean;
+    data: T | null;
+    error: Error | null;
+}
+/**
+ * Safely parse a JSON string without throwing.
+ *
+ * This is the preferred method for parsing JSON from external sources
+ * (user input, API responses, etc.) where invalid JSON is possible.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Object with success flag and either data or error
+ *
+ * @example
+ * ```typescript
+ * const result = safeParseJsonResult<UserData>(userInput);
+ * if (result.success) {
+ *   console.log(result.data.name);
+ * } else {
+ *   console.error('Invalid JSON:', result.error.message);
+ * }
+ * ```
+ */
+export declare function safeParseJsonResult<T = unknown>(str: string): SafeParseResult<T>;
+/**
+ * Safely parse JSON with fallback value.
+ *
+ * Useful when you need a value regardless of parse success.
+ *
+ * @param str - The string to parse as JSON
+ * @param fallback - Value to return if parsing fails
+ * @returns Parsed value or fallback
+ *
+ * @example
+ * ```typescript
+ * const config = safeParseJson(configString, { theme: 'light' });
+ * // Always returns an object, never throws
+ * ```
+ */
+export declare function safeParseJson<T>(str: string, fallback: T): T;
+/**
+ * Parse JSON or return undefined if invalid.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Parsed value or undefined
+ *
+ * @example
+ * ```typescript
+ * const data = parseJsonOrUndefined<Config>(input);
+ * if (data) {
+ *   // Use data
+ * }
+ * ```
+ */
+export declare function parseJsonOrUndefined<T>(str: string): T | undefined;
+/**
+ * Parse JSON or return null if invalid.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Parsed value or null
+ *
+ * @example
+ * ```typescript
+ * const data = parseJsonOrNull<Config>(input);
+ * if (data !== null) {
+ *   // Use data
+ * }
+ * ```
+ */
+export declare function parseJsonOrNull<T>(str: string): T | null;
+/**
+ * Check if a string is valid JSON.
+ *
+ * @param str - The string to validate
+ * @returns true if the string is valid JSON
+ *
+ * @example
+ * ```typescript
+ * if (isValidJson(userInput)) {
+ *   // Proceed with parsing
+ * }
+ * ```
+ */
+export declare function isValidJson(str: string): boolean;
+/**
+ * Safe stringify with circular reference handling.
+ *
+ * Handles circular references, BigInt values, and other edge cases gracefully.
+ *
+ * @param obj - Value to stringify
+ * @param space - Optional indentation (number of spaces)
+ * @returns JSON string, with circular references replaced by "[Circular]"
+ *
+ * @example
+ * ```typescript
+ * const obj = { name: 'test' };
+ * obj.self = obj; // Circular reference
+ *
+ * const json = safeStringify(obj);
+ * // Returns: '{"name":"test","self":"[Circular]"}'
+ *
+ * const prettyJson = safeStringify(data, 2);
+ * // Returns formatted JSON with 2-space indentation
+ * ```
+ */
+export declare function safeStringify(obj: unknown, space?: number): string;
+/**
+ * Safe stringify with options for more control.
+ *
+ * @param obj - Value to stringify
+ * @param options - Stringify options
+ * @returns JSON string or fallback string on error
+ *
+ * @example
+ * ```typescript
+ * const json = safeStringifyWithOptions(data, {
+ *   pretty: true,
+ *   fallback: '{}',
+ * });
+ * ```
+ */
+export declare function safeStringifyWithOptions(obj: unknown, options?: {
+    /** Use 2-space indentation */
+    pretty?: boolean;
+    /** Value to return if stringify fails */
+    fallback?: string;
+}): string;

package/dist/utils/json/safeParse.js

@@ -0,0 +1,190 @@
+/**
+ * Safe JSON Parsing Utilities
+ *
+ * Centralized JSON parsing utilities that handle errors gracefully.
+ * Provides safe parsing that doesn't throw on invalid JSON.
+ */
+/**
+ * Safely parse a JSON string without throwing.
+ *
+ * This is the preferred method for parsing JSON from external sources
+ * (user input, API responses, etc.) where invalid JSON is possible.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Object with success flag and either data or error
+ *
+ * @example
+ * ```typescript
+ * const result = safeParseJsonResult<UserData>(userInput);
+ * if (result.success) {
+ *   console.log(result.data.name);
+ * } else {
+ *   console.error('Invalid JSON:', result.error.message);
+ * }
+ * ```
+ */
+export function safeParseJsonResult(str) {
+    try {
+        const data = JSON.parse(str);
+        return { success: true, data, error: null };
+    }
+    catch (error) {
+        return {
+            success: false,
+            data: null,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * Safely parse JSON with fallback value.
+ *
+ * Useful when you need a value regardless of parse success.
+ *
+ * @param str - The string to parse as JSON
+ * @param fallback - Value to return if parsing fails
+ * @returns Parsed value or fallback
+ *
+ * @example
+ * ```typescript
+ * const config = safeParseJson(configString, { theme: 'light' });
+ * // Always returns an object, never throws
+ * ```
+ */
+export function safeParseJson(str, fallback) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Parse JSON or return undefined if invalid.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Parsed value or undefined
+ *
+ * @example
+ * ```typescript
+ * const data = parseJsonOrUndefined<Config>(input);
+ * if (data) {
+ *   // Use data
+ * }
+ * ```
+ */
+export function parseJsonOrUndefined(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse JSON or return null if invalid.
+ *
+ * @param str - The string to parse as JSON
+ * @returns Parsed value or null
+ *
+ * @example
+ * ```typescript
+ * const data = parseJsonOrNull<Config>(input);
+ * if (data !== null) {
+ *   // Use data
+ * }
+ * ```
+ */
+export function parseJsonOrNull(str) {
+    try {
+        return JSON.parse(str);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a string is valid JSON.
+ *
+ * @param str - The string to validate
+ * @returns true if the string is valid JSON
+ *
+ * @example
+ * ```typescript
+ * if (isValidJson(userInput)) {
+ *   // Proceed with parsing
+ * }
+ * ```
+ */
+export function isValidJson(str) {
+    try {
+        JSON.parse(str);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Safe stringify with circular reference handling.
+ *
+ * Handles circular references, BigInt values, and other edge cases gracefully.
+ *
+ * @param obj - Value to stringify
+ * @param space - Optional indentation (number of spaces)
+ * @returns JSON string, with circular references replaced by "[Circular]"
+ *
+ * @example
+ * ```typescript
+ * const obj = { name: 'test' };
+ * obj.self = obj; // Circular reference
+ *
+ * const json = safeStringify(obj);
+ * // Returns: '{"name":"test","self":"[Circular]"}'
+ *
+ * const prettyJson = safeStringify(data, 2);
+ * // Returns formatted JSON with 2-space indentation
+ * ```
+ */
+export function safeStringify(obj, space) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (_key, value) => {
+        // Handle BigInt
+        if (typeof value === "bigint") {
+            return value.toString();
+        }
+        // Handle circular references
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value)) {
+                return "[Circular]";
+            }
+            seen.add(value);
+        }
+        return value;
+    }, space);
+}
+/**
+ * Safe stringify with options for more control.
+ *
+ * @param obj - Value to stringify
+ * @param options - Stringify options
+ * @returns JSON string or fallback string on error
+ *
+ * @example
+ * ```typescript
+ * const json = safeStringifyWithOptions(data, {
+ *   pretty: true,
+ *   fallback: '{}',
+ * });
+ * ```
+ */
+export function safeStringifyWithOptions(obj, options) {
+    const { pretty = false, fallback = "[Unable to stringify]" } = options ?? {};
+    try {
+        const space = pretty ? 2 : undefined;
+        return safeStringify(obj, space);
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/utils/messageBuilder.d.ts

@@ -3,11 +3,11 @@
  * Centralized logic for building message arrays from TextGenerationOptions
  * Enhanced with multimodal support for images
  */
+import type { CoreMessage } from "ai";
 import type { MultimodalChatMessage } from "../types/conversation.js";
+import type { GenerateOptions } from "../types/generateTypes.js";
 import type { TextGenerationOptions } from "../types/index.js";
 import type { StreamOptions } from "../types/streamTypes.js";
-import type { GenerateOptions } from "../types/generateTypes.js";
-import type { CoreMessage } from "ai";
 /**
  * Type-safe conversion from MultimodalChatMessage[] to CoreMessage[]
  * Filters out invalid content and ensures strict CoreMessage contract compliance

package/dist/utils/messageBuilder.js

@@ -3,15 +3,15 @@
  * Centralized logic for building message arrays from TextGenerationOptions
  * Enhanced with multimodal support for images
  */
+import { existsSync, readFileSync } from "fs";
+import { getGlobalDispatcher, interceptors, request } from "undici";
+import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
-import { ProviderImageAdapter, MultimodalLogger, } from "../adapters/providerImageAdapter.js";
-import { logger } from "./logger.js";
 import { FileDetector } from "./fileDetector.js";
-import { PDFProcessor, PDFImageConverter } from "./pdfProcessor.js";
-import { urlDownloadRateLimiter } from "./rateLimiter.js";
-import { request, getGlobalDispatcher, interceptors } from "undici";
 import { getImageCache } from "./imageCache.js";
-import { readFileSync, existsSync } from "fs";
+import { logger } from "./logger.js";
+import { PDFImageConverter, PDFProcessor } from "./pdfProcessor.js";
+import { urlDownloadRateLimiter } from "./rateLimiter.js";
 /**
  * Type guard to check if an image input has alt text
  */
@@ -376,7 +376,7 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
             try {
                 const result = await FileDetector.detectAndProcess(file, {
                     maxSize,
-                    allowedTypes: ["csv", "image", "pdf"],
+                    allowedTypes: ["csv", "image", "pdf", "svg"],
                     csvOptions: options.csvOptions,
                     provider: provider,
                 });
@@ -396,6 +396,14 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
                     options.input.text += csvSection;
                     logger.info(`[FileDetector] ✅ CSV: ${filename}`);
                 }
+                else if (result.type === "svg") {
+                    // SVG is processed as text content (sanitized XML markup)
+                    // Inject into text prompt instead of sending as image
+                    const filename = extractFilename(file);
+                    const svgSection = `\n\n## SVG Content from "${filename}":\n\`\`\`xml\n${result.content}\n\`\`\`\n`;
+                    options.input.text += svgSection;
+                    logger.info(`[FileDetector] ✅ SVG (as text): ${filename}`);
+                }
                 else if (result.type === "image") {
                     options.input.images = [
                         ...(options.input.images || []),

package/dist/utils/sanitizers/filename.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Filename and Display Name Sanitization Utilities
+ * Prevents path traversal attacks and filesystem issues
+ *
+ * This module provides:
+ * - Filename sanitization for safe filesystem storage
+ * - Display name sanitization for user-facing content
+ * - Path traversal prevention
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
+ */
+/**
+ * Options for filename sanitization.
+ */
+export interface SanitizeFileNameOptions {
+    /** Maximum length for the filename (default: 255) */
+    maxLength?: number;
+    /** Replacement character for invalid chars (default: '_') */
+    replacement?: string;
+    /** Whether to block dangerous extensions (default: true) */
+    blockDangerousExtensions?: boolean;
+    /** Whether to allow hidden files starting with dot (default: false) */
+    allowHiddenFiles?: boolean;
+}
+/**
+ * Options for display name sanitization.
+ */
+export interface SanitizeDisplayNameOptions {
+    /** Maximum length for the name (default: 100) */
+    maxLength?: number;
+    /** Whether to allow unicode characters (default: true) */
+    allowUnicode?: boolean;
+}
+/**
+ * Sanitize a filename for safe filesystem storage.
+ * Removes characters that are invalid on various operating systems.
+ *
+ * @param filename - Raw filename to sanitize
+ * @param options - Sanitization options
+ * @returns Safe filename
+ * @throws Error if filename is empty after sanitization
+ *
+ * @example
+ * sanitizeFileName('my:file<name>.txt');
+ * // Returns: 'my_file_name_.txt'
+ *
+ * @example
+ * sanitizeFileName('../../../etc/passwd');
+ * // Returns: '______etc_passwd'
+ *
+ * @example
+ * sanitizeFileName('malware.exe', { blockDangerousExtensions: true });
+ * // Throws: Error - dangerous extension
+ */
+export declare function sanitizeFileName(filename: string, options?: SanitizeFileNameOptions): string;
+/**
+ * Sanitize a display name for safe user-facing display.
+ * Removes control characters and limits length.
+ *
+ * @param name - Raw display name to sanitize
+ * @param options - Sanitization options
+ * @returns Safe display name
+ *
+ * @example
+ * sanitizeDisplayName('  John\x00Doe  ');
+ * // Returns: 'John Doe'
+ *
+ * @example
+ * sanitizeDisplayName('User<script>alert(1)</script>');
+ * // Returns: 'User'
+ */
+export declare function sanitizeDisplayName(name: string, options?: SanitizeDisplayNameOptions): string;
+/**
+ * Validate a display name strictly.
+ * Only allows alphanumeric, spaces, and basic punctuation.
+ *
+ * @param name - Display name to validate
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * isValidDisplayName('John Doe'); // true
+ * isValidDisplayName('John<Doe'); // false
+ */
+export declare function isValidDisplayName(name: string): boolean;
+/**
+ * Validate a filename strictly.
+ * Only allows alphanumeric, dash, underscore, and period.
+ *
+ * @param filename - Filename to validate
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * isValidFileName('my-file.txt'); // true
+ * isValidFileName('../passwd'); // false
+ */
+export declare function isValidFileName(filename: string): boolean;
+/**
+ * Extract and sanitize the extension from a filename.
+ *
+ * @param filename - Filename to extract extension from
+ * @returns Lowercase extension including the dot, or empty string
+ *
+ * @example
+ * getFileExtension('document.PDF'); // '.pdf'
+ * getFileExtension('noextension'); // ''
+ */
+export declare function getFileExtension(filename: string): string;
+/**
+ * Check if a file extension is considered dangerous.
+ *
+ * @param extension - File extension to check (with or without leading dot)
+ * @returns true if extension is dangerous
+ *
+ * @example
+ * isDangerousExtension('.exe'); // true
+ * isDangerousExtension('pdf'); // false
+ */
+export declare function isDangerousExtension(extension: string): boolean;
+/**
+ * Generate a safe filename from arbitrary input.
+ * Creates a valid filename even from completely invalid input.
+ *
+ * @param input - Any string input
+ * @param defaultName - Default name if input sanitizes to empty (default: 'file')
+ * @param extension - Optional extension to append
+ * @returns Safe filename
+ *
+ * @example
+ * generateSafeFileName('My Document!@#$'); // 'My_Document_'
+ * generateSafeFileName('', 'untitled', '.txt'); // 'untitled.txt'
+ */
+export declare function generateSafeFileName(input: string, defaultName?: string, extension?: string): string;
+/**
+ * Get the list of dangerous file extensions.
+ * Useful for validation UI or documentation.
+ */
+export declare function getDangerousExtensions(): string[];