@juspay/neurolink 5.0.0 → 5.2.0

package/dist/sdk/tool-extension.js

@@ -0,0 +1,283 @@
+/**
+ * NeuroLink SDK Tool Extension System
+ * Allows developers to register custom tools that integrate with AI providers
+ */
+import { z } from "zod";
+import { tool as createAISDKTool } from "ai";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { logger } from "../utils/logger.js";
+/**
+ * Converts a custom tool to Vercel AI SDK format
+ */
+export function convertToAISDKTool(name, customTool) {
+    // Convert parameters to JSON schema if needed
+    let parametersSchema = {};
+    let zodSchema;
+    if (customTool.parameters) {
+        if ("parse" in customTool.parameters && "_def" in customTool.parameters) {
+            // It's a Zod schema
+            zodSchema = customTool.parameters;
+            parametersSchema = zodToJsonSchema(zodSchema);
+        }
+        else {
+            // It's already a JSON schema - convert to Zod
+            parametersSchema = customTool.parameters;
+            zodSchema = z.object({}).passthrough(); // Allow any properties
+        }
+    }
+    else {
+        zodSchema = z.object({});
+    }
+    return createAISDKTool({
+        description: customTool.description,
+        parameters: zodSchema,
+        execute: async (args) => {
+            try {
+                // Apply timeout if configured
+                if (customTool.config?.timeout) {
+                    return await Promise.race([
+                        customTool.execute(args),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error(`Tool ${name} timed out`)), customTool.config.timeout)),
+                    ]);
+                }
+                return await customTool.execute(args);
+            }
+            catch (error) {
+                logger.error(`Tool ${name} execution failed:`, error);
+                throw error;
+            }
+        },
+    });
+}
+/**
+ * Tool registry for managing custom tools
+ */
+export class ToolRegistry {
+    tools = new Map();
+    middleware = [];
+    permissions = {};
+    rateLimits = new Map();
+    /**
+     * Simple rate limiting check with automatic cleanup
+     */
+    checkRateLimit(name, rateLimit) {
+        const now = Date.now();
+        // Clean up expired entries to prevent memory leaks
+        for (const [key, limit] of this.rateLimits.entries()) {
+            if (limit.resetTime <= now) {
+                this.rateLimits.delete(key);
+            }
+        }
+        const limit = this.rateLimits.get(name);
+        if (limit && limit.resetTime > now) {
+            if (limit.count >= rateLimit.requests) {
+                throw new Error(`Tool ${name} rate limit exceeded`);
+            }
+            limit.count++;
+        }
+        else {
+            this.rateLimits.set(name, {
+                count: 1,
+                resetTime: now + rateLimit.window,
+            });
+        }
+    }
+    /**
+     * Register a custom tool
+     */
+    register(name, tool) {
+        if (this.tools.has(name)) {
+            logger.warn(`Tool ${name} already registered, overwriting`);
+        }
+        this.tools.set(name, tool);
+        logger.info(`Registered custom tool: ${name}`);
+    }
+    /**
+     * Register multiple tools at once
+     */
+    registerMany(tools) {
+        Object.entries(tools).forEach(([name, tool]) => {
+            this.register(name, tool);
+        });
+    }
+    /**
+     * Unregister a tool
+     */
+    unregister(name) {
+        const result = this.tools.delete(name);
+        if (result) {
+            logger.info(`Unregistered tool: ${name}`);
+        }
+        return result;
+    }
+    /**
+     * Get a tool by name
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Get all registered tools
+     */
+    getAll() {
+        return new Map(this.tools);
+    }
+    /**
+     * Convert all tools to AI SDK format
+     */
+    toAISDKTools() {
+        const aiTools = {};
+        for (const [name, tool] of this.tools) {
+            if (this.isToolAllowed(name)) {
+                aiTools[name] = convertToAISDKTool(name, tool);
+            }
+        }
+        return aiTools;
+    }
+    /**
+     * Add middleware
+     */
+    use(middleware) {
+        this.middleware.push(middleware);
+    }
+    /**
+     * Set permissions
+     */
+    setPermissions(permissions) {
+        this.permissions = permissions;
+    }
+    /**
+     * Check if a tool is allowed
+     */
+    isToolAllowed(name) {
+        // Check denylist first
+        if (this.permissions.denylist?.includes(name)) {
+            return false;
+        }
+        // Check allowlist if specified
+        if (this.permissions.allowlist &&
+            !this.permissions.allowlist.includes(name)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Execute a tool with middleware
+     */
+    async execute(name, args, context) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new Error(`Tool ${name} not found`);
+        }
+        // Check permissions
+        if (!this.isToolAllowed(name)) {
+            throw new Error(`Tool ${name} is not allowed`);
+        }
+        // Check custom validator
+        if (this.permissions.customValidator) {
+            const allowed = await this.permissions.customValidator(name, args);
+            if (!allowed) {
+                throw new Error(`Tool ${name} execution denied by custom validator`);
+            }
+        }
+        // Check rate limit
+        if (tool.config?.rateLimit) {
+            this.checkRateLimit(name, tool.config.rateLimit);
+        }
+        // Build middleware chain
+        let index = 0;
+        const next = async () => {
+            if (index < this.middleware.length) {
+                const middleware = this.middleware[index++];
+                return middleware(name, args, next, context);
+            }
+            else {
+                // Execute the actual tool
+                return tool.execute(args, context);
+            }
+        };
+        return next();
+    }
+}
+/**
+ * Create a simple tool helper
+ */
+export function createTool(config) {
+    return config;
+}
+/**
+ * Create an async tool helper
+ */
+export function createAsyncTool(config) {
+    return config;
+}
+/**
+ * Create a batch tool that processes multiple items
+ */
+export function createBatchTool(config) {
+    return {
+        ...config,
+        execute: async ({ items }, context) => {
+            const batchSize = config.batchSize || 10;
+            const results = [];
+            for (let i = 0; i < items.length; i += batchSize) {
+                const batch = items.slice(i, i + batchSize);
+                const batchResults = await Promise.all(batch.map((item) => config.processItem(item, context)));
+                results.push(...batchResults);
+            }
+            return results;
+        },
+    };
+}
+/**
+ * Tool testing utilities
+ */
+export const TestUtils = {
+    /**
+     * Create a mock tool context
+     */
+    mockContext(overrides) {
+        return {
+            callTool: async (name, args) => {
+                logger.debug(`Mock tool call: ${name}`, args);
+                return {};
+            },
+            session: {
+                id: "test-session",
+                userId: "test-user",
+                provider: "test-provider",
+                model: "test-model",
+            },
+            logger,
+            ...overrides,
+        };
+    },
+    /**
+     * Test a tool with mock data
+     */
+    async testTool(tool, testCases) {
+        const context = TestUtils.mockContext();
+        const results = [];
+        for (const testCase of testCases) {
+            try {
+                const result = await tool.execute(testCase.input, context);
+                results.push({
+                    input: testCase.input,
+                    output: result,
+                    success: true,
+                    matches: testCase.expected
+                        ? JSON.stringify(result) === JSON.stringify(testCase.expected)
+                        : undefined,
+                });
+            }
+            catch (error) {
+                results.push({
+                    input: testCase.input,
+                    error: error instanceof Error ? error.message : String(error),
+                    success: false,
+                });
+            }
+        }
+        return results;
+    },
+};

package/dist/sdk/tool-registration.d.ts

@@ -0,0 +1,95 @@
+/**
+ * NeuroLink SDK Tool Registration API
+ * Simple interface for developers to register custom tools
+ */
+import { z } from "zod";
+import type { Tool } from "ai";
+import { logger } from "../utils/logger.js";
+import type { InMemoryMCPServerConfig, InMemoryToolInfo } from "../types/mcp-types.js";
+/**
+ * Context provided to tools during execution
+ */
+export interface ToolContext {
+    /**
+     * Current session ID
+     */
+    sessionId: string;
+    /**
+     * User ID if available
+     */
+    userId?: string;
+    /**
+     * AI provider being used
+     */
+    provider?: string;
+    /**
+     * Model being used
+     */
+    model?: string;
+    /**
+     * Call another tool
+     */
+    callTool?: (name: string, args: any) => Promise<any>;
+    /**
+     * Logger instance
+     */
+    logger: typeof logger;
+}
+/**
+ * Simple tool interface for SDK users
+ */
+export interface SimpleTool {
+    /**
+     * Tool description that helps AI understand when to use it
+     */
+    description: string;
+    /**
+     * Parameters schema using Zod (optional)
+     */
+    parameters?: z.ZodSchema;
+    /**
+     * Tool execution function
+     */
+    execute: (args: any, context?: ToolContext) => Promise<any> | any;
+    /**
+     * Optional metadata
+     */
+    metadata?: {
+        category?: string;
+        version?: string;
+        author?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Converts a SimpleTool to Vercel AI SDK format
+ */
+export declare function convertToAISDKTool(name: string, simpleTool: SimpleTool): Tool;
+/**
+ * Converts a SimpleTool to MCP tool format
+ */
+export declare function convertToMCPTool(simpleTool: SimpleTool): InMemoryToolInfo;
+/**
+ * Creates an in-memory MCP server configuration from a set of tools
+ */
+export declare function createMCPServerFromTools(serverId: string, tools: Record<string, SimpleTool>, metadata?: {
+    title?: string;
+    description?: string;
+    category?: string;
+    [key: string]: any;
+}): InMemoryMCPServerConfig;
+/**
+ * Helper to create a tool with type safety
+ */
+export declare function createTool<TParams = any>(config: SimpleTool): SimpleTool;
+/**
+ * Helper to create a tool with typed parameters
+ */
+export declare function createTypedTool<TParams extends z.ZodSchema>(config: Omit<SimpleTool, "execute"> & {
+    parameters: TParams;
+    execute: (args: z.infer<TParams>, context?: ToolContext) => Promise<any> | any;
+}): SimpleTool;
+/**
+ * Validate tool configuration with detailed error messages
+ */
+export declare function validateTool(name: string, tool: SimpleTool): void;

package/dist/sdk/tool-registration.js

@@ -0,0 +1,168 @@
+/**
+ * NeuroLink SDK Tool Registration API
+ * Simple interface for developers to register custom tools
+ */
+import { z } from "zod";
+import { tool as createAISDKTool } from "ai";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { logger } from "../utils/logger.js";
+/**
+ * Configuration constants for tool validation
+ */
+const envValue = parseInt(process.env.NEUROLINK_TOOL_DESCRIPTION_MAX_LENGTH || "200", 10);
+const DEFAULT_DESCRIPTION_MAX_LENGTH = Number.isInteger(envValue) && envValue > 0 ? envValue : 200;
+/**
+ * Converts a SimpleTool to Vercel AI SDK format
+ */
+export function convertToAISDKTool(name, simpleTool) {
+    return createAISDKTool({
+        description: simpleTool.description,
+        parameters: simpleTool.parameters || z.object({}),
+        execute: async (args) => {
+            try {
+                // Create a minimal context for standalone execution
+                const context = {
+                    sessionId: `tool-${name}-${Date.now()}`,
+                    logger,
+                };
+                const result = await simpleTool.execute(args, context);
+                return result;
+            }
+            catch (error) {
+                logger.error(`Tool ${name} execution failed:`, error);
+                throw error;
+            }
+        },
+    });
+}
+/**
+ * Converts a SimpleTool to MCP tool format
+ */
+export function convertToMCPTool(simpleTool) {
+    return {
+        description: simpleTool.description,
+        execute: async (params) => {
+            try {
+                const result = await simpleTool.execute(params);
+                return {
+                    success: true,
+                    data: result,
+                };
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                logger.error("MCP tool execution failed:", error);
+                return {
+                    success: false,
+                    error: errorMessage,
+                };
+            }
+        },
+        inputSchema: simpleTool.parameters,
+        isImplemented: true,
+        metadata: simpleTool.metadata,
+    };
+}
+/**
+ * Creates an in-memory MCP server configuration from a set of tools
+ */
+export function createMCPServerFromTools(serverId, tools, metadata) {
+    const mcpTools = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        mcpTools[name] = convertToMCPTool(tool);
+    }
+    return {
+        server: {
+            title: metadata?.title || serverId,
+            description: metadata?.description,
+            tools: mcpTools,
+        },
+        category: metadata?.category,
+        metadata: metadata || {},
+    };
+}
+/**
+ * Helper to create a tool with type safety
+ */
+export function createTool(config) {
+    return config;
+}
+/**
+ * Helper to create a tool with typed parameters
+ */
+export function createTypedTool(config) {
+    return config;
+}
+/**
+ * Validate tool description length
+ */
+function validateDescriptionLength(name, description) {
+    const maxDescriptionLength = Number.isInteger(DEFAULT_DESCRIPTION_MAX_LENGTH) &&
+        DEFAULT_DESCRIPTION_MAX_LENGTH > 0
+        ? DEFAULT_DESCRIPTION_MAX_LENGTH
+        : 200;
+    if (description.length > maxDescriptionLength) {
+        throw new Error(`Tool '${name}' description should be concise (max ${maxDescriptionLength} characters). ` +
+            `Current length: ${description.length}. ` +
+            `Consider shortening: "${description.substring(0, 50)}..."`);
+    }
+}
+/**
+ * Validate tool configuration with detailed error messages
+ */
+export function validateTool(name, tool) {
+    // Validate tool name
+    if (!name || typeof name !== "string" || name.trim() === "") {
+        throw new Error(`Invalid tool name: must be a non-empty string. Received: ${name}`);
+    }
+    // Validate tool name format (alphanumeric, hyphens, underscores only)
+    const validNamePattern = /^[a-zA-Z0-9_-]+$/;
+    if (!validNamePattern.test(name)) {
+        throw new Error(`Invalid tool name format: '${name}'. Tool names must contain only alphanumeric characters, hyphens, and underscores. ` +
+            `Examples: 'calculate-tax', 'get_weather', 'sendEmail123'`);
+    }
+    // Validate tool object
+    if (!tool || typeof tool !== "object") {
+        throw new Error(`Tool '${name}' must be an object with description and execute properties. Received: ${typeof tool}`);
+    }
+    // Validate description
+    if (!tool.description ||
+        typeof tool.description !== "string" ||
+        tool.description.trim() === "") {
+        throw new Error(`Tool '${name}' must have a non-empty description string. ` +
+            `Example: { description: "Calculates mathematical expressions", execute: async (params) => {...} }`);
+    }
+    // Validate execute function with signature guidance
+    if (typeof tool.execute !== "function") {
+        throw new Error(`Tool '${name}' must have an execute function. ` +
+            `Expected signature: async (params?: any) => Promise<any>. ` +
+            `Received: ${typeof tool.execute}. ` +
+            `Example: { execute: async (params) => { return { success: true, data: result }; } }`);
+    }
+    // Validate parameters schema if provided - support both Zod and custom schemas
+    if (tool.parameters) {
+        if (typeof tool.parameters !== "object") {
+            throw new Error(`Tool '${name}' parameters must be an object. ` +
+                `Received: ${typeof tool.parameters}`);
+        }
+        // Check for common schema validation methods (Zod uses 'parse', others might use 'validate')
+        const params = tool.parameters;
+        const hasValidationMethod = typeof params.parse === "function" ||
+            typeof params.validate === "function" ||
+            "_def" in params; // Zod schemas have _def property
+        if (!hasValidationMethod) {
+            const errorMessage = typeof params.parse === "function" || "_def" in params
+                ? `Tool '${name}' has a Zod-like schema but validation failed. Ensure it's a valid Zod schema: z.object({ ... })`
+                : typeof params.validate === "function"
+                    ? `Tool '${name}' has a validate method but it may not be callable. Ensure: { parameters: { validate: (data) => { ... } } }`
+                    : `Tool '${name}' parameters must be a schema object with validation. ` +
+                        `Supported formats:\n` +
+                        `• Zod schema: { parameters: z.object({ value: z.string() }) }\n` +
+                        `• Custom schema: { parameters: { validate: (data) => { ... } } }\n` +
+                        `• Custom schema: { parameters: { parse: (data) => { ... } } }`;
+            throw new Error(errorMessage);
+        }
+    }
+    // Validate description length for better UX
+    validateDescriptionLength(name, tool.description);
+}

package/dist/types/generate-types.d.ts

@@ -0,0 +1,80 @@
+import type { ZodType, ZodTypeDef } from "zod";
+import type { Tool, Schema } from "ai";
+import type { AIProviderName, AnalyticsData, EvaluationData } from "../core/types.js";
+/**
+ * Generate function options interface - Primary method for content generation
+ * Future-ready for multi-modal capabilities while maintaining text focus
+ */
+export interface GenerateOptions {
+    input: {
+        text: string;
+    };
+    output?: {
+        format?: "text" | "structured" | "json";
+    };
+    provider?: AIProviderName | string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    systemPrompt?: string;
+    schema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>;
+    tools?: Record<string, Tool>;
+    timeout?: number | string;
+    disableTools?: boolean;
+    enableEvaluation?: boolean;
+    enableAnalytics?: boolean;
+    context?: Record<string, any>;
+    evaluationDomain?: string;
+    toolUsageContext?: string;
+    conversationHistory?: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/**
+ * Generate function result interface - Primary output format
+ * Future-ready for multi-modal outputs while maintaining text focus
+ */
+export interface GenerateResult {
+    content: string;
+    outputs?: {
+        text: string;
+    };
+    provider?: string;
+    model?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    responseTime?: number;
+    toolCalls?: Array<{
+        toolCallId: string;
+        toolName: string;
+        args: Record<string, any>;
+    }>;
+    toolResults?: any[];
+    toolsUsed?: string[];
+    toolExecutions?: Array<{
+        name: string;
+        input: Record<string, any>;
+        output: any;
+        duration: number;
+    }>;
+    enhancedWithTools?: boolean;
+    availableTools?: Array<{
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+    }>;
+    analytics?: AnalyticsData;
+    evaluation?: EvaluationData;
+}
+/**
+ * Enhanced provider interface with generate method
+ */
+export interface EnhancedProvider {
+    generate(options: GenerateOptions): Promise<GenerateResult>;
+    getName(): string;
+    isAvailable(): Promise<boolean>;
+}

package/dist/types/generate-types.js

@@ -0,0 +1 @@
+export {};