@juspay/neurolink 7.14.2 → 7.14.3

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

@@ -0,0 +1,412 @@
+/**
+ * Comprehensive Type Alias Library
+ * Centralizes commonly used complex types to improve readability and maintainability
+ */
+import type { ZodType, ZodTypeDef } from "zod";
+import type { Schema } from "ai";
+import type { JsonValue, JsonObject } from "./common.js";
+/**
+ * Type alias for complex Zod schema type to improve readability
+ * Used across providers and validation systems
+ */
+export type ZodUnknownSchema = ZodType<unknown, ZodTypeDef, unknown>;
+/**
+ * Union type for schema validation (Zod or AI SDK schema)
+ * Commonly used in provider interfaces and validation functions
+ */
+export type ValidationSchema = ZodUnknownSchema | Schema<unknown>;
+/**
+ * Optional validation schema type
+ * Used in optional schema parameters across the codebase
+ */
+export type OptionalValidationSchema = ValidationSchema | undefined;
+/**
+ * Standard unknown record type for flexible object structures
+ * Most commonly used record type across the codebase
+ */
+export type StandardRecord = Record<string, unknown>;
+/**
+ * String-valued record for configuration and metadata
+ * Common in environment variables and config objects
+ */
+export type StringRecord = Record<string, string>;
+/**
+ * Number-valued record for metrics and counters
+ * Used in performance monitoring and statistics
+ */
+export type NumberRecord = Record<string, number>;
+/**
+ * Boolean-valued record for feature flags and settings
+ * Common in configuration and capability objects
+ */
+export type BooleanRecord = Record<string, boolean>;
+/**
+ * Mixed primitive record for configuration objects
+ * Allows string, number, boolean values
+ */
+export type PrimitiveRecord = Record<string, string | number | boolean>;
+/**
+ * JSON-safe record type for API communication
+ * Ensures values are JSON-serializable
+ */
+export type JsonRecord = Record<string, JsonValue>;
+/**
+ * Optional record types for flexible parameters
+ */
+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
+ */
+export type ToolExecutionFunction<TParams = unknown, TResult = unknown> = (params: TParams, context?: StandardRecord) => Promise<TResult>;
+/**
+ * Event handler function type
+ * Common in event-driven architectures
+ */
+export type EventHandler<TEvent = unknown> = (event: TEvent) => void | Promise<void>;
+/**
+ * Async event handler function type
+ */
+export type AsyncEventHandler<TEvent = unknown> = (event: TEvent) => Promise<void>;
+/**
+ * Validation function type
+ * Common pattern for input validation
+ */
+export type ValidationFunction<T = unknown> = (value: T) => boolean;
+/**
+ * Transformation function type
+ * Common in data processing pipelines
+ */
+export type TransformFunction<TInput = unknown, TOutput = unknown> = (input: TInput) => TOutput;
+/**
+ * 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.
+ */
+export type StringArray = string[];
+/**
+ * Number array type
+ * Common for metrics, coordinates, etc.
+ */
+export type NumberArray = number[];
+/**
+ * Optional array types
+ */
+export type OptionalStringArray = StringArray | undefined;
+export type OptionalRecordArray = RecordArray | undefined;
+/**
+ * Provider configuration type
+ * Common structure for AI provider settings
+ */
+export type ProviderConfig = {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    timeout?: number;
+    retries?: number;
+    metadata?: StandardRecord;
+};
+/**
+ * API response structure
+ * Standard response format across providers
+ */
+export type ApiResponse<TData = unknown> = {
+    success: boolean;
+    data?: TData;
+    error?: string;
+    metadata?: StandardRecord;
+};
+/**
+ * Async API response type
+ */
+export type AsyncApiResponse<TData = unknown> = Promise<ApiResponse<TData>>;
+/**
+ * Paginated response structure
+ * Common in list APIs
+ */
+export type PaginatedResponse<TData = unknown> = ApiResponse<TData> & {
+    pagination?: {
+        page: number;
+        limit: number;
+        total: number;
+        hasNext: boolean;
+    };
+};
+/**
+ * Basic execution context
+ * Minimal context for tool execution
+ */
+export type BasicContext = {
+    sessionId?: string;
+    userId?: string;
+    timestamp?: number;
+};
+/**
+ * Enhanced execution context
+ * Extended context with additional metadata
+ */
+export type EnhancedContext = BasicContext & {
+    requestId?: string;
+    metadata?: StandardRecord;
+    timeout?: number;
+};
+/**
+ * Tool execution context with capabilities
+ * Full context for complex tool operations
+ */
+export type ToolContext = EnhancedContext & {
+    capabilities?: StringArray;
+    permissions?: StringArray;
+    environment?: string;
+};
+/**
+ * Standard error structure
+ * Consistent error format across the codebase
+ */
+export type StandardError = {
+    message: string;
+    code?: string;
+    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
+ */
+export type AsyncResult<TData = unknown, TError = StandardError> = Promise<Result<TData, TError>>;
+/**
+ * Operation result with metadata
+ * Enhanced result type with additional context
+ */
+export type OperationResult<TData = unknown> = Result<TData> & {
+    duration?: number;
+    metadata?: StandardRecord;
+};
+/**
+ * Nullable type alias
+ * Common pattern for optional values
+ */
+export type Nullable<T> = T | null;
+/**
+ * Optional type alias (more explicit than T | undefined)
+ */
+export type Optional<T> = T | undefined;
+/**
+ * Maybe type (combines null and undefined)
+ */
+export type Maybe<T> = T | null | undefined;
+/**
+ * Non-empty string type
+ * Useful for validated string inputs
+ */
+export type NonEmptyString = string & {
+    readonly __brand: unique symbol;
+};
+/**
+ * Positive number type
+ * Useful for validated numeric inputs
+ */
+export type PositiveNumber = number & {
+    readonly __brand: unique symbol;
+};
+/**
+ * Timestamp type (number representing milliseconds since epoch)
+ */
+export type Timestamp = number & {
+    readonly __brand: unique symbol;
+};
+/**
+ * ID type for entity identifiers
+ */
+export type EntityId = string & {
+    readonly __brand: unique symbol;
+};
+/**
+ * Feature flag configuration
+ * Common structure for feature toggles
+ */
+export type FeatureConfig = BooleanRecord & {
+    enabled?: boolean;
+    metadata?: StandardRecord;
+};
+/**
+ * Service configuration
+ * Standard structure for service settings
+ */
+export type ServiceConfig = {
+    enabled?: boolean;
+    timeout?: number;
+    retries?: number;
+    endpoint?: string;
+    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
+ */
+export type RateLimitConfig = {
+    enabled?: boolean;
+    requestsPerMinute?: number;
+    requestsPerHour?: number;
+    burstLimit?: number;
+};
+/**
+ * Simple success/error result (different from generic OperationResult)
+ * Used for basic operation feedback without data payload
+ */
+export type SimpleResult = {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Connectivity test result for providers
+ * Standard format for testing provider connections
+ */
+export type ConnectivityResult = {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Connection result with latency information
+ * Used for detailed connection testing with performance metrics
+ */
+export type ConnectionResult = {
+    connected: boolean;
+    latency?: number;
+    error?: string;
+};
+/**
+ * Provider pair result for fallback configurations
+ * Used when creating primary/fallback provider setups
+ */
+export type ProviderPairResult<T = unknown> = {
+    primary: T;
+    fallback: T;
+};
+/**
+ * Tool execution result with enhanced prompt
+ * Common pattern in tool orchestration scenarios
+ */
+export type ToolExecutionResult = {
+    toolResults: unknown[];
+    enhancedPrompt: string;
+};
+/**
+ * Batch operation result with count and errors
+ * Standard pattern for operations that process multiple items
+ */
+export type BatchOperationResult = {
+    success: boolean;
+    error?: string;
+    toolCount?: number;
+};
+/**
+ * Server loading result with detailed feedback
+ * Used when loading multiple servers with error tracking
+ */
+export type ServerLoadResult = {
+    serversLoaded: number;
+    errors: string[];
+};
+/**
+ * Transport connection result for MCP operations
+ * Standard format for MCP transport establishment
+ * Note: Using proper types instead of unknown to fix TypeScript compilation
+ */
+export type TransportResult = {
+    transport: unknown;
+    process?: unknown;
+};
+/**
+ * Transport result with required process (for stdio transport)
+ * Used when process is guaranteed to be present
+ */
+export type TransportWithProcessResult = {
+    transport: unknown;
+    process: unknown;
+};
+/**
+ * Transport result without process (for network transports)
+ * Used for SSE and WebSocket transports that don't spawn processes
+ */
+export type NetworkTransportResult = {
+    transport: unknown;
+};
+/**
+ * Re-export commonly used types from other modules
+ * Provides one-stop shop for type imports
+ */
+export type { JsonValue, JsonObject, UnknownRecord } from "./common.js";
+/**
+ * Type guard for checking if value is a StandardRecord
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-null object (but not an array)
+ *
+ * @example
+ * ```typescript
+ * if (isStandardRecord(data)) {
+ *   // TypeScript now knows data is Record<string, unknown>
+ *   console.log(data.someProperty);
+ * }
+ * ```
+ */
+export declare function isStandardRecord(value: unknown): value is StandardRecord;
+/**
+ * Type guard for checking if value is a JsonRecord
+ */
+export declare function isJsonRecord(value: unknown): value is JsonRecord;
+/**
+ * Type guard for checking if value is a StringArray
+ */
+export declare function isStringArray(value: unknown): value is StringArray;
+/**
+ * Type guard for checking if value is an AsyncFunction
+ */
+export declare function isAsyncFunction(value: unknown): value is AsyncFunction;

package/dist/lib/types/typeAliases.js

@@ -0,0 +1,48 @@
+/**
+ * Comprehensive Type Alias Library
+ * Centralizes commonly used complex types to improve readability and maintainability
+ */
+// ============================================================================
+// TYPE GUARDS AND UTILITIES
+// ============================================================================
+/**
+ * Type guard for checking if value is a StandardRecord
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-null object (but not an array)
+ *
+ * @example
+ * ```typescript
+ * if (isStandardRecord(data)) {
+ *   // TypeScript now knows data is Record<string, unknown>
+ *   console.log(data.someProperty);
+ * }
+ * ```
+ */
+export function isStandardRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard for checking if value is a JsonRecord
+ */
+export function isJsonRecord(value) {
+    return (isStandardRecord(value) &&
+        Object.values(value).every((val) => val === null ||
+            typeof val === "string" ||
+            typeof val === "number" ||
+            typeof val === "boolean" ||
+            Array.isArray(val) ||
+            isJsonRecord(val)));
+}
+/**
+ * Type guard for checking if value is a StringArray
+ */
+export function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+/**
+ * Type guard for checking if value is an AsyncFunction
+ */
+export function isAsyncFunction(value) {
+    return typeof value === "function";
+}

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

@@ -7,6 +7,7 @@ import type { GenerateOptions } from "../types/generateTypes.js";
 import type { StreamOptions } from "../types/streamTypes.js";
 import type { TextGenerationOptions } from "../core/types.js";
 import type { UnknownRecord, JsonValue } from "../types/common.js";
+import type { StandardRecord } from "../types/typeAliases.js";
 /**
  * Process factory configuration from enhanced options (with caching)
  * Extracts and validates factory config for provider integration
@@ -14,7 +15,7 @@ import type { UnknownRecord, JsonValue } from "../types/common.js";
 export declare function processFactoryOptions(options: GenerateOptions | StreamOptions): {
     hasFactoryConfig: boolean;
     domainType?: string;
-    domainConfig?: Record<string, unknown>;
+    domainConfig?: StandardRecord;
     enhancementType?: string;
     processedContext?: Record<string, JsonValue>;
 };

package/dist/lib/utils/factoryProcessing.js

@@ -4,6 +4,7 @@
  * Processes factory configuration and ensures it flows through to AI providers
  */
 import { logger } from "./logger.js";
+import { isNonNullObject } from "./typeUtils.js";
 // Removed crypto import - using faster string-based hash instead
 /**
  * LRU Cache for factory processing results
@@ -48,7 +49,7 @@ class FactoryProcessingCache {
      */
     generateCacheKey(options) {
         // Use object identity cache if possible for performance
-        if (typeof options === "object" && options !== null) {
+        if (isNonNullObject(options)) {
             const cachedKey = this.objectKeyCache.get(options);
             if (cachedKey) {
                 this.stats.keysCacheHits++;
@@ -63,7 +64,7 @@ class FactoryProcessingCache {
             const combinedHash = this.combineHashes(factoryConfigHash, contextHash);
             const key = combinedHash.toString(16);
             // Cache the computed key for future use (WeakMap auto-cleans on GC)
-            if (typeof options === "object" && options !== null) {
+            if (isNonNullObject(options)) {
                 this.objectKeyCache.set(options, key);
             }
             return key;
@@ -351,7 +352,7 @@ function isJsonValue(value) {
     if (Array.isArray(value)) {
         return value.every((item) => isJsonValue(item));
     }
-    if (typeof value === "object" && value !== null) {
+    if (isNonNullObject(value)) {
         const obj = value;
         return Object.values(obj).every((val) => isJsonValue(val));
     }

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

@@ -0,0 +1,97 @@
+/**
+ * Parameter Validation Utilities
+ * Provides consistent parameter validation across all tool interfaces
+ */
+import type { ValidationSchema, StringArray } from "../types/typeAliases.js";
+/**
+ * Custom error class for parameter validation failures
+ * Provides detailed information about validation errors including field context and suggestions
+ */
+export declare class ValidationError extends Error {
+    field?: string | undefined;
+    code?: string | undefined;
+    suggestions?: StringArray | undefined;
+    /**
+     * Creates a new ValidationError
+     * @param message - Human-readable error message
+     * @param field - Name of the field that failed validation (optional)
+     * @param code - Error code for programmatic handling (optional)
+     * @param suggestions - Array of suggested fixes (optional)
+     */
+    constructor(message: string, field?: string | undefined, code?: string | undefined, suggestions?: StringArray | undefined);
+}
+/**
+ * Result of a validation operation
+ * Contains validation status, errors, warnings, and suggestions for improvement
+ */
+export interface ValidationResult {
+    /** Whether the validation passed without errors */
+    isValid: boolean;
+    /** Array of validation errors that must be fixed */
+    errors: ValidationError[];
+    /** Array of warning messages that should be addressed */
+    warnings: string[];
+    /** Array of suggestions to improve the validated object */
+    suggestions: StringArray;
+}
+/**
+ * Validate that a string parameter is present and non-empty
+ */
+export declare function validateRequiredString(value: unknown, fieldName: string, minLength?: number): ValidationError | null;
+/**
+ * Validate that a number parameter is within acceptable range
+ */
+export declare function validateNumberRange(value: unknown, fieldName: string, min: number, max: number, required?: boolean): ValidationError | null;
+/**
+ * Validate that a function parameter is async and has correct signature
+ */
+export declare function validateAsyncFunction(value: unknown, fieldName: string, expectedParams?: StringArray): ValidationError | null;
+/**
+ * Validate object structure with required properties
+ */
+export declare function validateObjectStructure(value: unknown, fieldName: string, requiredProperties: StringArray, optionalProperties?: StringArray): ValidationError | null;
+/**
+ * Validate tool name according to naming conventions
+ */
+export declare function validateToolName(name: unknown): ValidationError | null;
+/**
+ * Validate tool description for clarity and usefulness
+ */
+export declare function validateToolDescription(description: unknown): ValidationError | null;
+/**
+ * Validate MCP tool structure comprehensively
+ */
+export declare function validateMCPTool(tool: unknown): ValidationResult;
+/**
+ * Validate text generation options
+ */
+export declare function validateTextGenerationOptions(options: unknown): ValidationResult;
+/**
+ * Validate stream options
+ */
+export declare function validateStreamOptions(options: unknown): ValidationResult;
+/**
+ * Validate generate options (unified interface)
+ */
+export declare function validateGenerateOptions(options: unknown): ValidationResult;
+/**
+ * Validate tool execution parameters
+ */
+export declare function validateToolExecutionParams(toolName: string, params: unknown, expectedSchema?: ValidationSchema): ValidationResult;
+/**
+ * Validate multiple tools at once
+ */
+export declare function validateToolBatch(tools: Record<string, unknown>): {
+    isValid: boolean;
+    validTools: string[];
+    invalidTools: string[];
+    results: Record<string, ValidationResult>;
+};
+/**
+ * Create a validation error summary for logging
+ */
+export declare function createValidationSummary(result: ValidationResult): string;
+/**
+ * Check if validation result has only warnings (no errors)
+ */
+export declare function hasOnlyWarnings(result: ValidationResult): boolean;