@juspay/neurolink 7.14.2 → 7.14.3

package/dist/lib/utils/transformationUtils.js

@@ -0,0 +1,334 @@
+/**
+ * Object Transformation Utilities
+ * Centralizes repeated object transformation patterns to improve code reuse and maintainability
+ */
+// ============================================================================
+// TOOL EXECUTION TRANSFORMATIONS
+// ============================================================================
+/**
+ * Transform tool execution results from AI SDK format to NeuroLink GenerateResult format
+ * Handles both single execution and array formats with robust type checking
+ *
+ * @param toolExecutions - Array of tool execution results from AI SDK (optional)
+ * @returns Array of standardized tool execution objects with name, input, output, and duration
+ *
+ * @example
+ * ```typescript
+ * const executions = transformToolExecutions([
+ *   { name: "calculator", input: { a: 5, b: 3 }, output: 8, duration: 150 }
+ * ]);
+ * // Returns: [{ name: "calculator", input: { a: 5, b: 3 }, output: 8, duration: 150 }]
+ * ```
+ */
+export function transformToolExecutions(toolExecutions) {
+    if (!toolExecutions || !Array.isArray(toolExecutions)) {
+        return [];
+    }
+    return toolExecutions.map((te) => {
+        const teRecord = te;
+        return {
+            name: teRecord.name || "",
+            input: teRecord.input || {},
+            output: teRecord.output || "success",
+            duration: teRecord.duration || 0,
+        };
+    });
+}
+/**
+ * Transform tool execution results from AI SDK format to internal format (for MCP generation)
+ * Used in tryMCPGeneration method
+ */
+export function transformToolExecutionsForMCP(toolExecutions) {
+    if (!toolExecutions || !Array.isArray(toolExecutions)) {
+        return [];
+    }
+    return toolExecutions.map((te) => {
+        const teRecord = te;
+        return {
+            toolName: teRecord.name || "",
+            executionTime: teRecord.duration || 0,
+            success: true, // Assume success if tool executed (AI providers handle failures differently)
+            serverId: teRecord.serverId || undefined,
+        };
+    });
+}
+// ============================================================================
+// AVAILABLE TOOLS TRANSFORMATIONS
+// ============================================================================
+/**
+ * Transform available tools from internal format to GenerateResult format
+ * Ensures consistent tool information structure across the API with schema normalization
+ *
+ * @param availableTools - Array of tool definitions from various sources (MCP servers, builtin tools, etc.)
+ * @returns Array of normalized tool descriptions with consistent schema format
+ *
+ * @example
+ * ```typescript
+ * const tools = transformAvailableTools([
+ *   { name: "calculator", description: "Math tool", server: "builtin", inputSchema: {...} }
+ * ]);
+ * // Returns: [{ name: "calculator", description: "Math tool", serverId: "builtin", schema: {...} }]
+ * ```
+ */
+export function transformAvailableTools(availableTools) {
+    if (!availableTools || !Array.isArray(availableTools)) {
+        return [];
+    }
+    return availableTools.map((tool) => {
+        const toolRecord = tool;
+        return {
+            name: tool.name || "",
+            description: tool.description || "",
+            server: tool.server || "",
+            parameters: toolRecord.inputSchema ||
+                toolRecord.parameters ||
+                toolRecord.schema ||
+                {},
+        };
+    });
+}
+/**
+ * Transform tools for MCP generation format
+ * Simple transformation for internal MCP tool lists
+ */
+export function transformToolsForMCP(availableTools) {
+    return availableTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        server: tool.server,
+        category: tool.category,
+    }));
+}
+/**
+ * Transform tools to expected format with required properties
+ * Used in getAllAvailableTools method for final output
+ */
+export function transformToolsToExpectedFormat(tools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description || "No description available",
+        server: tool.serverId || "unknown",
+        category: tool.category,
+        inputSchema: tool.inputSchema,
+    }));
+}
+// ============================================================================
+// STRING AND ARRAY TRANSFORMATIONS
+// ============================================================================
+/**
+ * Extract tool names from tool objects
+ * Common pattern for creating arrays of tool names
+ */
+export function extractToolNames(tools) {
+    return tools.map((tool) => tool.name);
+}
+/**
+ * Extract object keys as a comma-separated string
+ * Common pattern for logging and debugging
+ */
+export function getKeysAsString(obj, fallback = "none") {
+    const keys = Object.keys(obj);
+    return keys.length > 0 ? keys.join(", ") : fallback;
+}
+/**
+ * Count object properties
+ * Common pattern for metrics and logging
+ */
+export function getKeyCount(obj) {
+    return Object.keys(obj).length;
+}
+// ============================================================================
+// SCHEMA TRANSFORMATIONS
+// ============================================================================
+/**
+ * Transform schema properties to parameter descriptions
+ * Used in tool-aware system prompt generation
+ */
+export function transformSchemaToParameterDescription(schema) {
+    if (!schema?.properties) {
+        return "";
+    }
+    const requiredParams = new Set(schema.required || []);
+    return Object.entries(schema.properties)
+        .map(([key, value]) => {
+        const typedValue = value;
+        const required = requiredParams.has(key) ? " (required)" : "";
+        return `  - ${key}: ${typedValue.type || "unknown"}${required}`;
+    })
+        .join("\n");
+}
+/**
+ * Transform tools to tool descriptions for system prompts
+ * Consolidated pattern for creating tool-aware prompts
+ */
+export function transformToolsToDescriptions(availableTools) {
+    return availableTools
+        .map((tool) => {
+        const schema = tool.inputSchema;
+        let params = "";
+        if (schema?.properties) {
+            params = transformSchemaToParameterDescription(schema);
+        }
+        return `- ${tool.name}: ${tool.description} (from ${tool.server})\n${params}`;
+    })
+        .join("\n\n");
+}
+// ============================================================================
+// VALIDATION TRANSFORMATIONS
+// ============================================================================
+/**
+ * Transform parameters for validation
+ * Common pattern when logging or checking parameter structures
+ */
+export function transformParamsForLogging(params) {
+    if (!params || typeof params !== "object") {
+        return String(params);
+    }
+    const record = params;
+    return `${Object.keys(record).length} params`;
+}
+/**
+ * Safe property extraction from unknown objects
+ * Common pattern for safely accessing properties from unknown structures
+ */
+export function safeExtractProperty(obj, key, fallback) {
+    if (!obj || typeof obj !== "object" || obj === null) {
+        return fallback;
+    }
+    const record = obj;
+    const value = record[key];
+    return value !== undefined ? value : fallback;
+}
+/**
+ * Safe extraction of string properties
+ * Specialized version for string properties with fallback
+ */
+export function safeExtractString(obj, key, fallback = "") {
+    const value = safeExtractProperty(obj, key, fallback);
+    return typeof value === "string" ? value : fallback;
+}
+/**
+ * Safe extraction of number properties
+ * Specialized version for number properties with fallback
+ */
+export function safeExtractNumber(obj, key, fallback = 0) {
+    const value = safeExtractProperty(obj, key, fallback);
+    return typeof value === "number" ? value : fallback;
+}
+/**
+ * Safe extraction of boolean properties
+ * Specialized version for boolean properties with fallback
+ */
+export function safeExtractBoolean(obj, key, fallback = false) {
+    const value = safeExtractProperty(obj, key, fallback);
+    return typeof value === "boolean" ? value : fallback;
+}
+// ============================================================================
+// COLLECTION TRANSFORMATIONS
+// ============================================================================
+/**
+ * Transform Map to array of values
+ * Common pattern for converting tool maps to arrays
+ */
+export function mapToArray(map) {
+    return Array.from(map.values());
+}
+/**
+ * Transform Map to array of key-value pairs
+ * Common pattern for processing map entries
+ */
+export function mapToEntries(map) {
+    return Array.from(map.entries());
+}
+/**
+ * Group array items by a key
+ * Common pattern for organizing tools or other objects by category
+ */
+export function groupBy(items, keyFn) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        const existing = groups.get(key) || [];
+        existing.push(item);
+        groups.set(key, existing);
+    }
+    return groups;
+}
+/**
+ * Remove undefined properties from objects
+ * Common pattern for cleaning up object structures
+ */
+export function removeUndefinedProperties(obj) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}
+/**
+ * Merge objects with undefined handling
+ * Common pattern for combining configuration objects
+ */
+export function mergeWithUndefinedHandling(target, ...sources) {
+    const result = { ...target };
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source)) {
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+// ============================================================================
+// TOOL OPTIMIZATION UTILITIES
+// ============================================================================
+/**
+ * Optimize tool information for collection with minimal object creation
+ * Consolidates repeated optimization patterns across different tool sources
+ *
+ * @param tool - Tool information to optimize
+ * @param defaults - Default values to apply if missing
+ * @returns Optimized tool with minimal object creation
+ *
+ * @example
+ * ```typescript
+ * const optimized = optimizeToolForCollection(tool, {
+ *   serverId: "builtin",
+ *   category: "math"
+ * });
+ * ```
+ */
+export function optimizeToolForCollection(tool, defaults) {
+    // Check what properties actually need modification
+    const needsDescription = !tool.description && defaults.description;
+    const needsServerId = !tool.serverId && defaults.serverId;
+    const needsCategory = !tool.category && defaults.category;
+    const needsInputSchema = !tool.inputSchema && defaults.inputSchema;
+    const hasParametersConflict = tool.inputSchema && "parameters" in tool;
+    // Only create new object if modifications are actually needed
+    if (!needsDescription &&
+        !needsServerId &&
+        !needsCategory &&
+        !needsInputSchema &&
+        !hasParametersConflict) {
+        return tool; // Return original tool without modification
+    }
+    // Create optimized tool with only necessary changes
+    const optimizedTool = {
+        ...tool,
+        ...(needsDescription && { description: defaults.description }),
+        ...(needsServerId && { serverId: defaults.serverId }),
+        ...(needsCategory && { category: defaults.category }),
+        ...(needsInputSchema && { inputSchema: defaults.inputSchema }),
+    };
+    // Clean up schema conflicts if present
+    if (hasParametersConflict) {
+        const cleanedTool = { ...optimizedTool };
+        delete cleanedTool.parameters;
+        return cleanedTool;
+    }
+    return optimizedTool;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Type Utilities - Centralized type checking functions
+ *
+ * Consolidates common type checking patterns to reduce code duplication
+ * and provide consistent type guards across the codebase.
+ */
+/**
+ * Type guard to check if a value is a non-null object
+ * Excludes arrays and null values
+ *
+ * @param value - Value to check
+ * @returns true if value is a non-null object (excluding arrays)
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is a non-null object (including arrays)
+ *
+ * @param value - Value to check
+ * @returns true if value is a non-null object (including arrays)
+ */
+export declare function isNonNullObject(value: unknown): value is object;
+/**
+ * Type guard to check if a value is a plain object with string keys
+ *
+ * @param value - Value to check
+ * @returns true if value is a plain object with string keys
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is an array
+ *
+ * @param value - Value to check
+ * @returns true if value is an array
+ */
+export declare function isArray(value: unknown): value is unknown[];
+/**
+ * Type guard to check if a value is a string
+ *
+ * @param value - Value to check
+ * @returns true if value is a string
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a number
+ *
+ * @param value - Value to check
+ * @returns true if value is a number and not NaN
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Type guard to check if a value is a boolean
+ *
+ * @param value - Value to check
+ * @returns true if value is a boolean
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Type guard to check if a value is a function
+ *
+ * @param value - Value to check
+ * @returns true if value is a function
+ */
+export declare function isFunction(value: unknown): value is Function;
+/**
+ * Type guard to check if a value is null or undefined
+ *
+ * @param value - Value to check
+ * @returns true if value is null or undefined
+ */
+export declare function isNullish(value: unknown): value is null | undefined;
+/**
+ * Type guard to check if a value is defined (not undefined)
+ *
+ * @param value - Value to check
+ * @returns true if value is not undefined
+ */
+export declare function isDefined<T>(value: T | undefined): value is T;

package/dist/lib/utils/typeUtils.js

@@ -0,0 +1,97 @@
+/**
+ * Type Utilities - Centralized type checking functions
+ *
+ * Consolidates common type checking patterns to reduce code duplication
+ * and provide consistent type guards across the codebase.
+ */
+/**
+ * Type guard to check if a value is a non-null object
+ * Excludes arrays and null values
+ *
+ * @param value - Value to check
+ * @returns true if value is a non-null object (excluding arrays)
+ */
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard to check if a value is a non-null object (including arrays)
+ *
+ * @param value - Value to check
+ * @returns true if value is a non-null object (including arrays)
+ */
+export function isNonNullObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Type guard to check if a value is a plain object with string keys
+ *
+ * @param value - Value to check
+ * @returns true if value is a plain object with string keys
+ */
+export function isPlainObject(value) {
+    return isObject(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+/**
+ * Type guard to check if a value is an array
+ *
+ * @param value - Value to check
+ * @returns true if value is an array
+ */
+export function isArray(value) {
+    return Array.isArray(value);
+}
+/**
+ * Type guard to check if a value is a string
+ *
+ * @param value - Value to check
+ * @returns true if value is a string
+ */
+export function isString(value) {
+    return typeof value === "string";
+}
+/**
+ * Type guard to check if a value is a number
+ *
+ * @param value - Value to check
+ * @returns true if value is a number and not NaN
+ */
+export function isNumber(value) {
+    return typeof value === "number" && !isNaN(value);
+}
+/**
+ * Type guard to check if a value is a boolean
+ *
+ * @param value - Value to check
+ * @returns true if value is a boolean
+ */
+export function isBoolean(value) {
+    return typeof value === "boolean";
+}
+/**
+ * Type guard to check if a value is a function
+ *
+ * @param value - Value to check
+ * @returns true if value is a function
+ */
+export function isFunction(value) {
+    return typeof value === "function";
+}
+/**
+ * Type guard to check if a value is null or undefined
+ *
+ * @param value - Value to check
+ * @returns true if value is null or undefined
+ */
+export function isNullish(value) {
+    return value === null || value === undefined;
+}
+/**
+ * Type guard to check if a value is defined (not undefined)
+ *
+ * @param value - Value to check
+ * @returns true if value is not undefined
+ */
+export function isDefined(value) {
+    return value !== undefined;
+}

package/dist/mcp/contracts/mcpContract.d.ts

@@ -2,15 +2,16 @@
  * MCP Contract - Core Type Definitions
  * Industry standard camelCase interfaces for maximum flexibility
  */
+import type { StandardRecord } from "../../types/typeAliases.js";
 /**
  * Generic execution context for MCP operations
  * All properties optional for maximum flexibility
  */
-export interface ExecutionContext<T = Record<string, unknown>> {
+export interface ExecutionContext<T = StandardRecord> {
     sessionId?: string;
     userId?: string;
     config?: T;
-    metadata?: Record<string, unknown>;
+    metadata?: StandardRecord;
     cacheOptions?: CacheOptions;
     fallbackOptions?: FallbackOptions;
     timeoutMs?: number;
@@ -41,14 +42,14 @@ export interface ToolInfo {
     description?: string;
     category?: string;
     serverId?: string;
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
+    inputSchema?: StandardRecord;
+    outputSchema?: StandardRecord;
     [key: string]: unknown;
 }
 /**
  * Discovered MCP server/plugin definition
  */
-export interface DiscoveredMcp<TTools = Record<string, unknown>> {
+export interface DiscoveredMcp<TTools = StandardRecord> {
     metadata: McpMetadata;
     tools?: TTools;
     capabilities?: string[];
@@ -68,20 +69,6 @@ export interface McpMetadata {
     repository?: string;
     category?: string;
 }
-/**
- * Tool definition schema
- */
-export interface ToolDefinition {
-    description?: string;
-    inputSchema?: Record<string, unknown>;
-    outputSchema?: Record<string, unknown>;
-    category?: string;
-    examples?: Array<{
-        input: Record<string, unknown>;
-        output: Record<string, unknown>;
-        description?: string;
-    }>;
-}
 /**
  * Tool execution result
  */

package/dist/mcp/externalServerManager.d.ts

@@ -11,6 +11,7 @@ import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import type { ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPManagerConfig, ExternalMCPToolInfo } from "../types/externalMcp.js";
 import type { MCPServerInfo } from "../types/mcpTypes.js";
 import type { JsonObject } from "../types/common.js";
+import type { ServerLoadResult } from "../types/typeAliases.js";
 export declare class ExternalServerManager extends EventEmitter {
     private servers;
     private config;
@@ -26,10 +27,7 @@ export declare class ExternalServerManager extends EventEmitter {
      * @param configPath Optional path to config file (defaults to .mcp-config.json in cwd)
      * @returns Promise resolving to number of servers loaded
      */
-    loadMCPConfiguration(configPath?: string): Promise<{
-        serversLoaded: number;
-        errors: string[];
-    }>;
+    loadMCPConfiguration(configPath?: string): Promise<ServerLoadResult>;
     /**
      * Validate external MCP server configuration
      */

package/dist/mcp/externalServerManager.js

@@ -12,11 +12,12 @@ import { MCPClientFactory } from "./mcpClientFactory.js";
 import { ToolDiscoveryService } from "./toolDiscoveryService.js";
 import { toolRegistry } from "./toolRegistry.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
+import { isObject, isNonNullObject } from "../utils/typeUtils.js";
 /**
  * Type guard to validate if an object can be safely used as Record<string, JsonValue>
  */
 function isValidJsonRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    if (!isObject(value)) {
         return false;
     }
     const record = value;
@@ -35,7 +36,7 @@ function isValidJsonRecord(value) {
                 typeof item === "boolean" ||
                 item === null);
         }
-        if (typeof val === "object" && val !== null) {
+        if (isNonNullObject(val)) {
             return isValidJsonRecord(val);
         }
         return false;
@@ -51,14 +52,13 @@ function safeMetadataConversion(metadata) {
  * Type guard to validate external MCP server configuration
  */
 function isValidExternalMCPServerConfig(config) {
-    if (typeof config !== "object" || config === null) {
+    if (!isNonNullObject(config)) {
         return false;
     }
     const record = config;
     return (typeof record.command === "string" &&
         (record.args === undefined || Array.isArray(record.args)) &&
-        (record.env === undefined ||
-            (typeof record.env === "object" && record.env !== null)) &&
+        (record.env === undefined || isNonNullObject(record.env)) &&
         (record.transport === undefined || typeof record.transport === "string") &&
         (record.timeout === undefined || typeof record.timeout === "number") &&
         (record.retries === undefined || typeof record.retries === "number") &&
@@ -68,8 +68,7 @@ function isValidExternalMCPServerConfig(config) {
             typeof record.autoRestart === "boolean") &&
         (record.cwd === undefined || typeof record.cwd === "string") &&
         (record.url === undefined || typeof record.url === "string") &&
-        (record.metadata === undefined ||
-            (typeof record.metadata === "object" && record.metadata !== null)));
+        (record.metadata === undefined || isNonNullObject(record.metadata)));
 }
 export class ExternalServerManager extends EventEmitter {
     servers = new Map();
@@ -150,7 +149,7 @@ export class ExternalServerManager extends EventEmitter {
                         args: Array.isArray(serverConfig.args)
                             ? serverConfig.args
                             : [],
-                        env: typeof serverConfig.env === "object" && serverConfig.env !== null
+                        env: isNonNullObject(serverConfig.env)
                             ? serverConfig.env
                             : {},
                         timeout: typeof serverConfig.timeout === "number"