@juspay/neurolink 7.6.1 → 7.7.1

package/dist/types/contextTypes.js

@@ -2,11 +2,123 @@
  * Context Types for NeuroLink - Factory Pattern Implementation
  * Provides type-safe context integration for AI generation
  */
-import { JsonValue, JsonObject } from "./common.js";
 /**
  * Factory for context processing
  */
 export class ContextFactory {
+    /**
+     * Default framework fields configuration
+     */
+    static DEFAULT_FRAMEWORK_FIELDS = {
+        defaultFields: [
+            "sessionId",
+            "userId",
+            "apiToken",
+            "authToken",
+            "apiEndpoint",
+            "serviceUrl",
+            "endpoint",
+            "environment",
+            "region",
+            "enabledFeatures",
+            "platformType",
+            "platformUrl",
+            "platformId",
+            "enableDemoMode",
+        ],
+        additionalFields: [],
+        includeFields: [],
+    };
+    /**
+     * Current framework fields configuration
+     */
+    static frameworkFieldsConfig = ContextFactory.DEFAULT_FRAMEWORK_FIELDS;
+    /**
+     * Flag to track if framework fields have been initialized
+     */
+    static isFrameworkFieldsInitialized = false;
+    /**
+     * Configure framework fields for exclusion from custom data
+     */
+    static configureFrameworkFields(config) {
+        ContextFactory.frameworkFieldsConfig = {
+            ...ContextFactory.DEFAULT_FRAMEWORK_FIELDS,
+            ...config,
+        };
+        ContextFactory.isFrameworkFieldsInitialized = true;
+    }
+    /**
+     * Get current framework fields configuration
+     * Ensures lazy initialization if not already loaded
+     */
+    static getFrameworkFieldsConfig() {
+        // Lazy initialization - load from environment if not explicitly configured
+        if (!ContextFactory.isFrameworkFieldsInitialized) {
+            ContextFactory.loadFrameworkFieldsFromEnv();
+            ContextFactory.isFrameworkFieldsInitialized = true;
+        }
+        return { ...ContextFactory.frameworkFieldsConfig };
+    }
+    /**
+     * Reset framework fields configuration to default
+     */
+    static resetFrameworkFieldsConfig() {
+        ContextFactory.frameworkFieldsConfig = {
+            ...ContextFactory.DEFAULT_FRAMEWORK_FIELDS,
+        };
+    }
+    /**
+     * Load framework fields configuration from environment variables
+     * Supports NEUROLINK_CONTEXT_EXCLUDE_FIELDS and NEUROLINK_CONTEXT_INCLUDE_FIELDS
+     */
+    static loadFrameworkFieldsFromEnv() {
+        const excludeFields = process.env.NEUROLINK_CONTEXT_EXCLUDE_FIELDS;
+        const includeFields = process.env.NEUROLINK_CONTEXT_INCLUDE_FIELDS;
+        const overrideFields = process.env.NEUROLINK_CONTEXT_OVERRIDE_FIELDS;
+        const config = {};
+        if (excludeFields) {
+            config.additionalFields = excludeFields
+                .split(",")
+                .map((f) => f.trim())
+                .filter(Boolean);
+        }
+        if (includeFields) {
+            config.includeFields = includeFields
+                .split(",")
+                .map((f) => f.trim())
+                .filter(Boolean);
+        }
+        if (overrideFields) {
+            config.overrideFields = overrideFields
+                .split(",")
+                .map((f) => f.trim())
+                .filter(Boolean);
+        }
+        // Optimized check: avoid creating array with Object.keys() for simple property existence check
+        const hasConfigChanges = config.additionalFields || config.includeFields || config.overrideFields;
+        if (hasConfigChanges) {
+            ContextFactory.configureFrameworkFields(config);
+        }
+        ContextFactory.isFrameworkFieldsInitialized = true;
+    }
+    /**
+     * Add additional fields to exclude
+     */
+    static addFrameworkFieldsToExclude(fields) {
+        const currentConfig = ContextFactory.frameworkFieldsConfig;
+        ContextFactory.configureFrameworkFields({
+            additionalFields: [...(currentConfig.additionalFields || []), ...fields],
+        });
+    }
+    /**
+     * Add fields to include (override exclusion)
+     */
+    static addFrameworkFieldsToInclude(fields) {
+        const currentConfig = ContextFactory.frameworkFieldsConfig;
+        ContextFactory.configureFrameworkFields({
+            includeFields: [...(currentConfig.includeFields || []), ...fields],
+        });
+    }
     /**
      * Default context configuration
      */
@@ -172,6 +284,119 @@ export class ContextFactory {
 /**
  * Type guard to check if value is valid context
  */
-export function isValidContext(value) {
+function isValidContext(value) {
     return ContextFactory.validateContext(value) !== null;
 }
+export class ContextConverter {
+    /**
+     * Convert legacy business context to generic domain context
+     * Based on business context patterns
+     */
+    static convertBusinessContext(legacyContext, domainType, options = {}) {
+        const { preserveLegacyFields = false, validateDomainData = true, includeMetadata = true, } = options;
+        return {
+            sessionId: legacyContext.sessionId,
+            userId: legacyContext.userId,
+            config: {
+                domainType,
+                providerConfig: {
+                    token: legacyContext.apiToken ||
+                        legacyContext.authToken ||
+                        legacyContext.accessToken,
+                    endpoint: legacyContext.apiEndpoint || legacyContext.serviceUrl,
+                    provider: this.inferProvider(legacyContext),
+                },
+                platformConfig: {
+                    type: legacyContext.platformType || "generic",
+                    url: legacyContext.platformUrl || legacyContext.serviceUrl,
+                    id: legacyContext.platformId || legacyContext.serviceId,
+                    integrations: legacyContext.platformIntegrations || [],
+                },
+                operationalConfig: {
+                    demoMode: legacyContext.enableDemoMode || false,
+                    environment: legacyContext.environment || "production",
+                    region: legacyContext.region,
+                    features: legacyContext.enabledFeatures || [],
+                },
+                customData: {
+                    // Preserve domain-specific fields if needed
+                    ...(preserveLegacyFields
+                        ? {
+                            entityId: legacyContext.entityId || legacyContext.organizationId,
+                            departmentId: legacyContext.departmentId,
+                            projectId: legacyContext.projectId,
+                        }
+                        : {}),
+                    // Include any additional custom data
+                    ...this.extractCustomData(legacyContext),
+                },
+            },
+            metadata: includeMetadata
+                ? {
+                    convertedFrom: "legacy-business-context",
+                    conversionTime: Date.now(),
+                    originalKeys: Object.keys(legacyContext),
+                    domainType,
+                }
+                : undefined,
+        };
+    }
+    /**
+     * Create execution context for any domain
+     */
+    static createDomainContext(domainType, domainData, sessionInfo = {}) {
+        return {
+            sessionId: sessionInfo.sessionId || `session_${Date.now()}`,
+            userId: sessionInfo.userId,
+            config: {
+                domainType,
+                customData: domainData,
+            },
+            metadata: {
+                source: "domain-context-factory",
+                createdAt: Date.now(),
+                domainType,
+            },
+        };
+    }
+    static inferProvider(context) {
+        // Generic provider inference based on context structure
+        if (context.apiToken || context.authToken) {
+            return "api-provider";
+        }
+        if (context.serviceUrl || context.endpoint) {
+            return "service-provider";
+        }
+        return "generic-provider";
+    }
+    static extractCustomData(context) {
+        // Get current framework fields configuration
+        const config = ContextFactory.getFrameworkFieldsConfig();
+        // Build the set of fields to exclude
+        let fieldsToExclude;
+        if (config.overrideFields) {
+            // Use override fields completely
+            fieldsToExclude = new Set(config.overrideFields);
+        }
+        else {
+            // Use default fields + additional fields
+            fieldsToExclude = new Set([
+                ...config.defaultFields,
+                ...(config.additionalFields || []),
+            ]);
+        }
+        // Remove any fields that should be included despite being in the exclude list
+        if (config.includeFields) {
+            config.includeFields.forEach((field) => fieldsToExclude.delete(field));
+        }
+        const customData = {};
+        Object.entries(context).forEach(([key, value]) => {
+            if (!fieldsToExclude.has(key)) {
+                customData[key] = value;
+            }
+        });
+        return customData;
+    }
+}
+// Framework fields configuration loading moved to lazy initialization
+// Call ContextFactory.loadFrameworkFieldsFromEnv() explicitly in application entrypoint or test setup

package/dist/types/domainTypes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Domain Types for Factory Pattern Implementation
+ * Provides type-safe domain configuration and factory pattern support
+ */
+import type { JsonObject } from "./common.js";
+/**
+ * Supported domain types for factory configuration
+ */
+export type DomainType = "healthcare" | "finance" | "analytics" | "ecommerce" | "education" | "legal" | "technology" | "generic";
+/**
+ * Domain evaluation criteria interface
+ */
+export interface DomainEvaluationCriteria {
+    accuracyWeight: number;
+    completenessWeight: number;
+    relevanceWeight: number;
+    terminologyWeight: number;
+    domainSpecificRules: string[];
+    failurePatterns: string[];
+    successPatterns: string[];
+}
+/**
+ * Domain configuration interface
+ */
+export interface DomainConfig {
+    domainType: DomainType;
+    domainName: string;
+    description: string;
+    evaluationCriteria: DomainEvaluationCriteria;
+    customData?: JsonObject;
+    metadata?: {
+        version: string;
+        createdAt: number;
+        updatedAt: number;
+    };
+}
+/**
+ * Domain template for factory registration
+ */
+export interface DomainTemplate {
+    domainType: DomainType;
+    template: Partial<DomainConfig>;
+    isDefault?: boolean;
+}
+/**
+ * Domain validation rule
+ */
+export interface DomainValidationRule {
+    ruleName: string;
+    ruleType: "required" | "pattern" | "range" | "custom";
+    validation: (value: unknown) => boolean;
+    errorMessage: string;
+}
+/**
+ * Domain configuration options for factory
+ */
+export interface DomainConfigOptions {
+    domainType: DomainType;
+    customConfig?: Partial<DomainConfig>;
+    validateDomainData?: boolean;
+    includeDefaults?: boolean;
+}

package/dist/types/domainTypes.js

@@ -0,0 +1,5 @@
+/**
+ * Domain Types for Factory Pattern Implementation
+ * Provides type-safe domain configuration and factory pattern support
+ */
+export {};

package/dist/types/generateTypes.d.ts

@@ -30,6 +30,20 @@ export interface GenerateOptions {
         role: string;
         content: string;
     }>;
+    factoryConfig?: {
+        domainType?: string;
+        domainConfig?: Record<string, unknown>;
+        enhancementType?: "domain-configuration" | "streaming-optimization" | "mcp-integration" | "legacy-migration" | "context-conversion";
+        preserveLegacyFields?: boolean;
+        validateDomainData?: boolean;
+    };
+    streaming?: {
+        enabled?: boolean;
+        chunkSize?: number;
+        bufferSize?: number;
+        enableProgress?: boolean;
+        fallbackToGenerate?: boolean;
+    };
 }
 /**
  * Generate function result interface - Primary output format
@@ -69,6 +83,31 @@ export interface GenerateResult {
     }>;
     analytics?: AnalyticsData;
     evaluation?: EvaluationData;
+    factoryMetadata?: {
+        enhancementApplied: boolean;
+        enhancementType?: string;
+        domainType?: string;
+        processingTime?: number;
+        configurationUsed?: Record<string, unknown>;
+        migrationPerformed?: boolean;
+        legacyFieldsPreserved?: boolean;
+    };
+    streamingMetadata?: {
+        streamingUsed: boolean;
+        fallbackToGenerate?: boolean;
+        chunkCount?: number;
+        streamingDuration?: number;
+        streamId?: string;
+        bufferOptimization?: boolean;
+    };
+}
+/**
+ * Unified options for both generation and streaming
+ * Supports factory patterns and domain configuration
+ */
+export interface UnifiedGenerationOptions extends GenerateOptions {
+    preferStreaming?: boolean;
+    streamingFallback?: boolean;
 }
 /**
  * Enhanced provider interface with generate method
@@ -78,3 +117,16 @@ export interface EnhancedProvider {
     getName(): string;
     isAvailable(): Promise<boolean>;
 }
+/**
+ * Factory-enhanced provider interface
+ * Supports domain configuration and streaming optimizations
+ */
+export interface FactoryEnhancedProvider extends EnhancedProvider {
+    generateWithFactory(options: UnifiedGenerationOptions): Promise<GenerateResult>;
+    getDomainSupport(): string[];
+    getStreamingCapabilities(): {
+        supportsStreaming: boolean;
+        maxChunkSize: number;
+        bufferOptimizations: boolean;
+    };
+}

package/dist/types/index.d.ts

@@ -13,3 +13,4 @@ export type { BaseCommandArgs, GenerateCommandArgs, MCPCommandArgs, ModelsComman
 export type { MCPTransportType, MCPServerStatus, MCPDiscoveredServer, MCPConnectedServer, MCPServerConfig, MCPToolInfo, MCPServerMetadata, MCPToolMetadata, MCPServerRegistryEntry, } from "./mcpTypes.js";
 export type { ModelCapability, ModelUseCase, ModelFilter, ModelResolutionContext, ModelStats, ModelPricing, } from "./providers.js";
 export type { ToolCallResults, ToolCalls, StreamAnalyticsData, } from "./streamTypes.js";
+export type { DomainType, DomainConfig, DomainTemplate, DomainConfigOptions, DomainEvaluationCriteria, DomainValidationRule, } from "./domainTypes.js";

package/dist/types/mcpTypes.d.ts

@@ -1,6 +1,6 @@
 /**
  * MCP Types for In-Memory Server Support
- * Enables Lighthouse and other integrations to register tools directly
+ * Enables various integrations to register tools directly
  */
 import type { JsonValue, JsonObject } from "./common.js";
 /**

package/dist/types/mcpTypes.js

@@ -1,5 +1,5 @@
 /**
  * MCP Types for In-Memory Server Support
- * Enables Lighthouse and other integrations to register tools directly
+ * Enables various integrations to register tools directly
  */
 export {};

package/dist/types/streamTypes.d.ts

@@ -93,6 +93,20 @@ export interface StreamOptions {
         role: string;
         content: string;
     }>;
+    factoryConfig?: {
+        domainType?: string;
+        domainConfig?: Record<string, unknown>;
+        enhancementType?: "domain-configuration" | "streaming-optimization" | "mcp-integration" | "legacy-migration" | "context-conversion";
+        preserveLegacyFields?: boolean;
+        validateDomainData?: boolean;
+    };
+    streaming?: {
+        enabled?: boolean;
+        chunkSize?: number;
+        bufferSize?: number;
+        enableProgress?: boolean;
+        fallbackToGenerate?: boolean;
+    };
 }
 /**
  * Stream function result interface - Primary output format for streaming

package/dist/types/universalProviderOptions.d.ts

@@ -2,7 +2,7 @@
  * Universal Provider Options Interface (Phase 1: Factory Pattern)
  * Based on TypeScript factory pattern best practices for AI provider abstraction
  */
-import { BaseContext, ContextConfig } from "./contextTypes.js";
+import type { BaseContext, ContextConfig } from "./contextTypes.js";
 /**
  * Base configuration interface for all AI providers
  * Uses Parameter Object Pattern for flexible, extensible configuration

package/dist/types/universalProviderOptions.js

@@ -2,7 +2,6 @@
  * Universal Provider Options Interface (Phase 1: Factory Pattern)
  * Based on TypeScript factory pattern best practices for AI provider abstraction
  */
-import { BaseContext, ContextConfig } from "./contextTypes.js";
 /**
  * Parameter normalization utilities
  * Converts between different parameter formats for backward compatibility

package/dist/utils/errorHandling.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Robust Error Handling Utilities for NeuroLink
+ * Provides structured error management for tool execution and system operations
+ */
+export declare enum ErrorCategory {
+    VALIDATION = "validation",
+    TIMEOUT = "timeout",
+    NETWORK = "network",
+    RESOURCE = "resource",
+    PERMISSION = "permission",
+    CONFIGURATION = "configuration",
+    EXECUTION = "execution",
+    SYSTEM = "system"
+}
+export declare enum ErrorSeverity {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+export interface StructuredError {
+    code: string;
+    message: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    retriable: boolean;
+    context?: Record<string, unknown>;
+    originalError?: Error;
+    timestamp: Date;
+    toolName?: string;
+    serverId?: string;
+}
+export declare const ERROR_CODES: {
+    readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND";
+    readonly TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED";
+    readonly TOOL_TIMEOUT: "TOOL_TIMEOUT";
+    readonly TOOL_VALIDATION_FAILED: "TOOL_VALIDATION_FAILED";
+    readonly INVALID_PARAMETERS: "INVALID_PARAMETERS";
+    readonly MISSING_REQUIRED_PARAM: "MISSING_REQUIRED_PARAM";
+    readonly MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
+    readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
+    readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
+    readonly INVALID_CONFIGURATION: "INVALID_CONFIGURATION";
+    readonly MISSING_CONFIGURATION: "MISSING_CONFIGURATION";
+};
+/**
+ * Enhanced error class with structured information
+ */
+export declare class NeuroLinkError extends Error {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly retriable: boolean;
+    readonly context: Record<string, unknown>;
+    readonly timestamp: Date;
+    readonly toolName?: string;
+    readonly serverId?: string;
+    constructor(options: {
+        code: string;
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        retriable: boolean;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+        toolName?: string;
+        serverId?: string;
+    });
+    /**
+     * Convert to JSON for logging and serialization
+     */
+    toJSON(): StructuredError;
+}
+/**
+ * Error factory for common error scenarios
+ */
+export declare class ErrorFactory {
+    /**
+     * Create a tool not found error
+     */
+    static toolNotFound(toolName: string, availableTools?: string[]): NeuroLinkError;
+    /**
+     * Create a tool execution failed error
+     */
+    static toolExecutionFailed(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
+    /**
+     * Create a tool timeout error
+     */
+    static toolTimeout(toolName: string, timeoutMs: number, serverId?: string): NeuroLinkError;
+    /**
+     * Create a parameter validation error
+     */
+    static invalidParameters(toolName: string, validationError: Error, providedParams?: unknown): NeuroLinkError;
+    /**
+     * Create a network error
+     */
+    static networkError(toolName: string, originalError: Error, serverId?: string): NeuroLinkError;
+    /**
+     * Create a memory exhaustion error
+     */
+    static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
+}
+/**
+ * Timeout wrapper for async operations
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutError?: Error): Promise<T>;
+/**
+ * Retry mechanism for retriable operations
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options: {
+    maxAttempts: number;
+    delayMs: number;
+    isRetriable?: (error: Error) => boolean;
+    onRetry?: (attempt: number, error: Error) => void;
+}): Promise<T>;
+/**
+ * Circuit breaker for preventing cascading failures
+ */
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private failures;
+    private lastFailureTime;
+    private state;
+    constructor(failureThreshold?: number, resetTimeoutMs?: number);
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): "closed" | "open" | "half-open";
+    getFailureCount(): number;
+}
+/**
+ * Error handler that decides whether to retry based on error type
+ */
+export declare function isRetriableError(error: Error): boolean;
+/**
+ * Enhanced error logger that provides structured logging
+ */
+export declare function logStructuredError(error: NeuroLinkError, context?: Record<string, unknown>): void;