@juspay/neurolink 9.44.0 → 9.48.1

package/dist/lib/types/serverTypes.js

@@ -0,0 +1,68 @@
+/**
+ * Server Adapter Types
+ * Comprehensive type system for NeuroLink server adapters
+ */
+// ============================================
+// Error Types
+// ============================================
+/**
+ * Error categories for server adapter errors
+ */
+export const ErrorCategory = {
+    CONFIG: "CONFIG",
+    VALIDATION: "VALIDATION",
+    EXECUTION: "EXECUTION",
+    EXTERNAL: "EXTERNAL",
+    RATE_LIMIT: "RATE_LIMIT",
+    AUTHENTICATION: "AUTHENTICATION",
+    AUTHORIZATION: "AUTHORIZATION",
+    STREAMING: "STREAMING",
+    WEBSOCKET: "WEBSOCKET",
+};
+/**
+ * Error severity levels
+ */
+export const ErrorSeverity = {
+    LOW: "LOW",
+    MEDIUM: "MEDIUM",
+    HIGH: "HIGH",
+    CRITICAL: "CRITICAL",
+};
+/**
+ * Server adapter error codes
+ */
+export const ServerAdapterErrorCode = {
+    // Configuration errors
+    INVALID_CONFIG: "SERVER_ADAPTER_INVALID_CONFIG",
+    MISSING_DEPENDENCY: "SERVER_ADAPTER_MISSING_DEPENDENCY",
+    FRAMEWORK_INIT_FAILED: "SERVER_ADAPTER_FRAMEWORK_INIT_FAILED",
+    // Route errors
+    ROUTE_NOT_FOUND: "SERVER_ADAPTER_ROUTE_NOT_FOUND",
+    ROUTE_CONFLICT: "SERVER_ADAPTER_ROUTE_CONFLICT",
+    INVALID_ROUTE: "SERVER_ADAPTER_INVALID_ROUTE",
+    // Execution errors
+    HANDLER_ERROR: "SERVER_ADAPTER_HANDLER_ERROR",
+    TIMEOUT: "SERVER_ADAPTER_TIMEOUT",
+    MIDDLEWARE_ERROR: "SERVER_ADAPTER_MIDDLEWARE_ERROR",
+    // Rate limit errors
+    RATE_LIMIT_EXCEEDED: "SERVER_ADAPTER_RATE_LIMIT_EXCEEDED",
+    // Authentication/Authorization errors
+    AUTH_REQUIRED: "SERVER_ADAPTER_AUTH_REQUIRED",
+    AUTH_INVALID: "SERVER_ADAPTER_AUTH_INVALID",
+    FORBIDDEN: "SERVER_ADAPTER_FORBIDDEN",
+    // Streaming errors
+    STREAM_ERROR: "SERVER_ADAPTER_STREAM_ERROR",
+    STREAM_ABORTED: "SERVER_ADAPTER_STREAM_ABORTED",
+    // WebSocket errors
+    WEBSOCKET_ERROR: "SERVER_ADAPTER_WEBSOCKET_ERROR",
+    WEBSOCKET_CONNECTION_FAILED: "SERVER_ADAPTER_WEBSOCKET_CONNECTION_FAILED",
+    // Validation errors
+    VALIDATION_ERROR: "SERVER_ADAPTER_VALIDATION_ERROR",
+    SCHEMA_ERROR: "SERVER_ADAPTER_SCHEMA_ERROR",
+    // Server lifecycle errors
+    START_FAILED: "SERVER_ADAPTER_START_FAILED",
+    STOP_FAILED: "SERVER_ADAPTER_STOP_FAILED",
+    ALREADY_RUNNING: "SERVER_ADAPTER_ALREADY_RUNNING",
+    NOT_RUNNING: "SERVER_ADAPTER_NOT_RUNNING",
+};
+//# sourceMappingURL=serverTypes.js.map

package/dist/lib/types/streamTypes.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel, StepResult, Tool, ToolChoice } from "ai";
 import type { AIProviderName } from "../constants/enums.js";
-import type { EvaluationData } from "../index.js";
-import type { RAGConfig } from "../rag/types.js";
+import type { EvaluationData } from "./evaluation.js";
+import type { RAGConfig } from "./ragTypes.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middlewareTypes.js";
 import type { TokenUsage } from "./analytics.js";

package/dist/lib/types/typeAliases.d.ts

@@ -4,7 +4,7 @@
  */
 import type { ZodTypeAny } from "zod";
 import type { Schema } from "ai";
-import type { JsonValue, JsonObject } from "./common.js";
+import type { JsonValue, Result, AsyncFunction } from "./common.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 /**
  * Type alias for complex Zod schema type to improve readability
@@ -65,11 +65,6 @@ export type JsonRecord = Record<string, JsonValue>;
 export type OptionalStandardRecord = StandardRecord | undefined;
 export type OptionalStringRecord = StringRecord | undefined;
 export type OptionalJsonRecord = JsonRecord | undefined;
-/**
- * Standard async function type for tool execution
- * Most common function signature in the codebase
- */
-export type AsyncFunction<TParams = unknown, TResult = unknown> = (params: TParams) => Promise<TResult>;
 /**
  * Tool execution function with context
  * Standard pattern for MCP tool execution
@@ -98,21 +93,11 @@ export type TransformFunction<TInput = unknown, TOutput = unknown> = (input: TIn
  * Async transformation function type
  */
 export type AsyncTransformFunction<TInput = unknown, TOutput = unknown> = (input: TInput) => Promise<TOutput>;
-/**
- * Array of unknown values
- * Common for flexible array parameters
- */
-export type UnknownArray = unknown[];
 /**
  * Array of standard records
  * Common in data collections
  */
 export type RecordArray = StandardRecord[];
-/**
- * Array of JSON objects
- * API-safe array type
- */
-export type JsonArray = JsonObject[];
 /**
  * String array type
  * Very common for lists of identifiers, names, etc.
@@ -203,17 +188,6 @@ export type StandardError = {
     details?: StandardRecord;
     stack?: string;
 };
-/**
- * Result type with success/error pattern
- * Common pattern for operation results
- */
-export type Result<TData = unknown, TError = StandardError> = {
-    success: true;
-    data: TData;
-} | {
-    success: false;
-    error: TError;
-};
 /**
  * Async result type
  */
@@ -285,16 +259,6 @@ export type ServiceConfig = {
     apiKey?: string;
     metadata?: StandardRecord;
 };
-/**
- * Cache configuration
- * Common caching parameters
- */
-export type CacheConfig = {
-    enabled?: boolean;
-    ttl?: number;
-    maxSize?: number;
-    strategy?: "memory" | "redis" | "hybrid";
-};
 /**
  * Rate limiting configuration
  * Common rate limiting parameters

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

@@ -79,6 +79,11 @@ export declare class ImageProcessor {
      */
     static processImage(image: Buffer | string, provider: string, model?: string): ProcessedImage;
 }
+/**
+ * Whitelist of valid image file extensions (lowercase, no dots).
+ * Used to validate file extensions against a known set of image formats.
+ */
+export declare const VALID_IMAGE_EXTENSIONS: string[];
 /**
  * Utility functions for image handling
  */
@@ -96,9 +101,27 @@ export declare const imageUtils: {
      */
     isBase64: (str: string) => boolean;
     /**
-     * Extract file extension from filename or URL
+     * Extract file extension from filename or URL.
+     * Strips query strings and fragments before matching so that
+     * "image.jpg?v=1" correctly returns "jpg".
+     * Returns null if no extension is found or if the extension
+     * contains non-alphanumeric characters.
      */
     getFileExtension: (filename: string) => string | null;
+    /**
+     * Validate that an extension is a recognised image format.
+     * Case-insensitive; rejects extensions with special characters.
+     */
+    isValidImageExtension: (extension: string) => boolean;
+    /**
+     * Extract and validate image file extension from a filename or URL.
+     * Returns null if the extension is missing or not a recognised image format.
+     *
+     * Security note: the last extension is used, so "malware.exe.jpg" returns
+     * "jpg". Callers should apply additional checks (e.g. content inspection)
+     * where double-extension attacks are a concern.
+     */
+    getValidatedImageExtension: (filename: string) => string | null;
     /**
      * Convert file size to human readable format
      */

package/dist/lib/utils/imageProcessor.js

@@ -364,11 +364,58 @@ export class ImageProcessor {
                 const height = buffer.readUInt32BE(20);
                 return { width, height };
             }
-            // Basic JPEG dimension extraction (simplified)
+            // JPEG dimension extraction via SOF marker parsing
             if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
-                // This is a very basic implementation
-                // For production, consider using a proper image library
-                return null;
+                // Search for SOF0 (0xFFC0) or SOF2 (0xFFC2) markers
+                let offset = 2;
+                while (offset < buffer.length - 1) {
+                    // Find next marker (0xFF followed by non-zero, non-0xFF byte)
+                    if (buffer[offset] !== 0xff) {
+                        offset++;
+                        continue;
+                    }
+                    // Skip any padding 0xFF bytes
+                    while (offset < buffer.length && buffer[offset] === 0xff) {
+                        offset++;
+                    }
+                    if (offset >= buffer.length) {
+                        break;
+                    }
+                    const marker = buffer[offset];
+                    offset++;
+                    // Check for SOF0 (0xC0 - baseline DCT) and SOF2 (0xC2 - progressive DCT)
+                    // These are the most common JPEG encoding modes
+                    if (marker === 0xc0 || marker === 0xc2) {
+                        // SOF marker found: length (2 bytes) + precision (1 byte) + height (2 bytes) + width (2 bytes)
+                        if (offset + 7 > buffer.length) {
+                            break; // Truncated file
+                        }
+                        const height = buffer.readUInt16BE(offset + 3);
+                        const width = buffer.readUInt16BE(offset + 5);
+                        return { width, height };
+                    }
+                    // Skip this marker's segment (except for markers without length)
+                    if (marker === 0xd0 ||
+                        marker === 0xd1 ||
+                        marker === 0xd2 ||
+                        marker === 0xd3 ||
+                        marker === 0xd4 ||
+                        marker === 0xd5 ||
+                        marker === 0xd6 ||
+                        marker === 0xd7 ||
+                        marker === 0xd8 ||
+                        marker === 0xd9 ||
+                        marker === 0x01) {
+                        // RST0-RST7, SOI, EOI, TEM - no length field
+                        continue;
+                    }
+                    if (offset + 2 > buffer.length) {
+                        break; // Truncated file
+                    }
+                    const segmentLength = buffer.readUInt16BE(offset);
+                    offset += segmentLength;
+                }
+                return null; // No SOF marker found
             }
             return null;
         }
@@ -437,6 +484,30 @@ export class ImageProcessor {
         }
     }
 }
+/**
+ * Whitelist of valid image file extensions (lowercase, no dots).
+ * Used to validate file extensions against a known set of image formats.
+ */
+export const VALID_IMAGE_EXTENSIONS = [
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "webp",
+    "bmp",
+    "tiff",
+    "tif",
+    "svg",
+    "avif",
+    "ico",
+    "heic",
+    "heif",
+];
+/**
+ * Set of valid image extensions for O(1) lookup.
+ * @internal
+ */
+const VALID_IMAGE_EXTENSIONS_SET = new Set(VALID_IMAGE_EXTENSIONS);
 /**
  * Utility functions for image handling
  */
@@ -466,11 +537,52 @@ export const imageUtils = {
      */
     isBase64: (str) => imageUtils.isValidBase64(str),
     /**
-     * Extract file extension from filename or URL
+     * Extract file extension from filename or URL.
+     * Strips query strings and fragments before matching so that
+     * "image.jpg?v=1" correctly returns "jpg".
+     * Returns null if no extension is found or if the extension
+     * contains non-alphanumeric characters.
      */
     getFileExtension: (filename) => {
-        const match = filename.match(/\.([^.]+)$/);
-        return match ? match[1].toLowerCase() : null;
+        const sanitized = filename.split(/[?#]/)[0];
+        const match = sanitized.match(/\.([^.]+)$/);
+        if (!match) {
+            return null;
+        }
+        const extension = match[1].toLowerCase();
+        if (!/^[a-z0-9]+$/.test(extension)) {
+            return null;
+        }
+        return extension;
+    },
+    /**
+     * Validate that an extension is a recognised image format.
+     * Case-insensitive; rejects extensions with special characters.
+     */
+    isValidImageExtension: (extension) => {
+        if (!extension || typeof extension !== "string") {
+            return false;
+        }
+        const normalizedExt = extension.toLowerCase();
+        if (!/^[a-z0-9]+$/.test(normalizedExt)) {
+            return false;
+        }
+        return VALID_IMAGE_EXTENSIONS_SET.has(normalizedExt);
+    },
+    /**
+     * Extract and validate image file extension from a filename or URL.
+     * Returns null if the extension is missing or not a recognised image format.
+     *
+     * Security note: the last extension is used, so "malware.exe.jpg" returns
+     * "jpg". Callers should apply additional checks (e.g. content inspection)
+     * where double-extension attacks are a concern.
+     */
+    getValidatedImageExtension: (filename) => {
+        const extension = imageUtils.getFileExtension(filename);
+        if (!extension) {
+            return null;
+        }
+        return imageUtils.isValidImageExtension(extension) ? extension : null;
     },
     /**
      * Convert file size to human readable format
@@ -576,7 +688,11 @@ export const imageUtils = {
                 if (!/^image\//i.test(contentType)) {
                     throw new Error(`Unsupported content-type: ${contentType || "unknown"}`);
                 }
-                const len = Number(response.headers.get("content-length") || 0);
+                const contentLengthHeader = response.headers.get("content-length");
+                const len = Number(contentLengthHeader || 0);
+                if (contentLengthHeader !== null && len === 0) {
+                    throw new Error("Empty response: content-length is 0");
+                }
                 if (len && len > maxBytes) {
                     throw new Error(`Content too large: ${len} bytes`);
                 }

package/dist/lib/utils/messageBuilder.js

@@ -1127,15 +1127,27 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
 async function convertContentToProviderFormat(content, provider, _model) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
-    if (!textContent) {
-        throw new Error("Multimodal content must include at least one text element");
-    }
-    if (imageContent.length === 0) {
-        return textContent.text;
+    const pdfContent = content.filter((c) => c.type === "pdf");
+    // Allow empty text when multimodal content is present (enables image-only or PDF-only queries)
+    const text = textContent?.text || "";
+    const hasMultimodal = imageContent.length > 0 || pdfContent.length > 0;
+    // Validate that we have at least some content
+    if (!hasMultimodal && !text) {
+        throw new Error("Content must include either text or multimodal content");
+    }
+    // Text-only case
+    if (imageContent.length === 0 && pdfContent.length === 0) {
+        return text;
     }
     // Extract images as Buffer | string array
     const images = imageContent.map((img) => img.data);
-    return await convertSimpleImagesToProviderFormat(textContent.text, images, provider, _model);
+    // Extract PDFs in the expected format
+    const pdfFiles = pdfContent.map((pdf) => ({
+        buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
+        filename: pdf.metadata?.filename || "document.pdf",
+        pageCount: pdf.metadata?.pages ?? null,
+    }));
+    return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
 /**
  * Check if a string is an internet URL

package/dist/lib/workflow/config.d.ts

@@ -41,8 +41,8 @@ export declare const JudgeConfigSchema: z.ZodObject<{
     model: z.ZodString;
     criteria: z.ZodArray<z.ZodString>;
     outputFormat: z.ZodEnum<{
-        scores: "scores";
         detailed: "detailed";
+        scores: "scores";
         ranking: "ranking";
         best: "best";
     }>;
@@ -195,8 +195,8 @@ export declare const WorkflowConfigSchema: z.ZodObject<{
         model: z.ZodString;
         criteria: z.ZodArray<z.ZodString>;
         outputFormat: z.ZodEnum<{
-            scores: "scores";
             detailed: "detailed";
+            scores: "scores";
             ranking: "ranking";
             best: "best";
         }>;
@@ -219,8 +219,8 @@ export declare const WorkflowConfigSchema: z.ZodObject<{
         model: z.ZodString;
         criteria: z.ZodArray<z.ZodString>;
         outputFormat: z.ZodEnum<{
-            scores: "scores";
             detailed: "detailed";
+            scores: "scores";
             ranking: "ranking";
             best: "best";
         }>;

package/dist/rag/errors/RAGError.d.ts

@@ -82,7 +82,7 @@ export declare const RAGErrorFactory: {
         readonly RETRY_EXHAUSTED: "RAG_RETRY_EXHAUSTED";
         readonly INVALID_CONFIGURATION: "RAG_INVALID_CONFIGURATION";
     };
-    create: (code: "INVALID_CONFIGURATION" | "CHUNKING_ERROR" | "CHUNKING_INVALID_CONFIG" | "CHUNKING_STRATEGY_NOT_FOUND" | "CHUNKING_EMPTY_CONTENT" | "CHUNKING_SIZE_EXCEEDED" | "METADATA_EXTRACTION_ERROR" | "METADATA_EXTRACTION_TIMEOUT" | "METADATA_SCHEMA_INVALID" | "METADATA_EXTRACTOR_NOT_FOUND" | "EMBEDDING_ERROR" | "EMBEDDING_DIMENSION_MISMATCH" | "EMBEDDING_RATE_LIMIT" | "EMBEDDING_PROVIDER_ERROR" | "VECTOR_QUERY_ERROR" | "VECTOR_QUERY_TIMEOUT" | "VECTOR_STORE_UNAVAILABLE" | "VECTOR_STORE_CONNECTION_ERROR" | "VECTOR_INDEX_NOT_FOUND" | "RERANKER_ERROR" | "RERANKER_NOT_FOUND" | "RERANKER_API_ERROR" | "GRAPH_RAG_ERROR" | "GRAPH_TRAVERSAL_ERROR" | "GRAPH_NODE_NOT_FOUND" | "PIPELINE_ERROR" | "PIPELINE_STAGE_FAILED" | "PIPELINE_PARTIAL_FAILURE" | "CIRCUIT_BREAKER_OPEN" | "CIRCUIT_BREAKER_HALF_OPEN_LIMIT" | "OPERATION_TIMEOUT" | "RETRY_EXHAUSTED", message: string, options?: {
+    create: (code: "CHUNKING_ERROR" | "CHUNKING_INVALID_CONFIG" | "CHUNKING_STRATEGY_NOT_FOUND" | "CHUNKING_EMPTY_CONTENT" | "CHUNKING_SIZE_EXCEEDED" | "METADATA_EXTRACTION_ERROR" | "METADATA_EXTRACTION_TIMEOUT" | "METADATA_SCHEMA_INVALID" | "METADATA_EXTRACTOR_NOT_FOUND" | "EMBEDDING_ERROR" | "EMBEDDING_DIMENSION_MISMATCH" | "EMBEDDING_RATE_LIMIT" | "EMBEDDING_PROVIDER_ERROR" | "VECTOR_QUERY_ERROR" | "VECTOR_QUERY_TIMEOUT" | "VECTOR_STORE_UNAVAILABLE" | "VECTOR_STORE_CONNECTION_ERROR" | "VECTOR_INDEX_NOT_FOUND" | "RERANKER_ERROR" | "RERANKER_NOT_FOUND" | "RERANKER_API_ERROR" | "GRAPH_RAG_ERROR" | "GRAPH_TRAVERSAL_ERROR" | "GRAPH_NODE_NOT_FOUND" | "PIPELINE_ERROR" | "PIPELINE_STAGE_FAILED" | "PIPELINE_PARTIAL_FAILURE" | "CIRCUIT_BREAKER_OPEN" | "CIRCUIT_BREAKER_HALF_OPEN_LIMIT" | "OPERATION_TIMEOUT" | "RETRY_EXHAUSTED" | "INVALID_CONFIGURATION", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/rag/types.d.ts

@@ -698,71 +698,4 @@ export type RAGCommandArgs = {
     /** Use Graph RAG */
     graph?: boolean;
 };
-/**
- * RAG configuration for generate() and stream() APIs.
- *
- * When provided, NeuroLink automatically:
- * 1. Loads the specified files
- * 2. Chunks them using the selected strategy
- * 3. Generates embeddings
- * 4. Stores in an in-memory vector store
- * 5. Creates a search tool the AI can invoke on demand
- *
- * @example
- * ```typescript
- * const result = await neurolink.generate({
- *   input: { text: "What is RAG?" },
- *   provider: "vertex",
- *   rag: {
- *     files: ["./docs/guide.md", "./docs/api.md"],
- *     strategy: "markdown",
- *     chunkSize: 512,
- *     topK: 5,
- *   }
- * });
- * ```
- */
-export type RAGConfig = {
-    /** File paths to load and index for retrieval */
-    files: string[];
-    /**
-     * Chunking strategy to use. If not specified, auto-detected from file extension.
-     * @default "recursive"
-     */
-    strategy?: ChunkingStrategy;
-    /**
-     * Maximum chunk size in characters.
-     * @default 1000
-     */
-    chunkSize?: number;
-    /**
-     * Overlap between adjacent chunks in characters.
-     * @default 200
-     */
-    chunkOverlap?: number;
-    /**
-     * Number of top results to retrieve per query.
-     * @default 5
-     */
-    topK?: number;
-    /**
-     * Tool name visible to the AI model.
-     * @default "search_knowledge_base"
-     */
-    toolName?: string;
-    /**
-     * Tool description for the AI model explaining what the knowledge base contains.
-     * @default "Search the loaded documents for relevant information to answer the user's question"
-     */
-    toolDescription?: string;
-    /**
-     * Embedding model provider for generating embeddings.
-     * Defaults to the same provider used for generation.
-     */
-    embeddingProvider?: string;
-    /**
-     * Embedding model name.
-     * Defaults to the provider's default embedding model.
-     */
-    embeddingModel?: string;
-};
+export type { RAGConfig } from "../types/ragTypes.js";