@juspay/neurolink
Version:
The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002
231 lines (230 loc) • 9.2 kB
TypeScript
/**
* Parameter Validation Utilities
* Provides consistent parameter validation across all tool interfaces
*/
import type { AIProviderName } from "../constants/enums.js";
import type { GenerateOptions, VideoOutputOptions, EnhancedValidationResult, PPTOutputOptions, StringArray, ValidationSchema } from "../types/index.js";
import { type NeuroLinkError } from "./errorHandling.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);
}
/**
* 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): EnhancedValidationResult;
/**
* Validate text generation options
*/
export declare function validateTextGenerationOptions(options: unknown): EnhancedValidationResult;
/**
* Validate stream options
*/
export declare function validateStreamOptions(options: unknown): EnhancedValidationResult;
/**
* Validate generate options (unified interface)
*/
export declare function validateGenerateOptions(options: unknown): EnhancedValidationResult;
/**
* Validate tool execution parameters
*/
export declare function validateToolExecutionParams(toolName: string, params: unknown, expectedSchema?: ValidationSchema): EnhancedValidationResult;
/**
* Validate multiple tools at once
*/
export declare function validateToolBatch(tools: Record<string, unknown>): {
isValid: boolean;
validTools: string[];
invalidTools: string[];
results: Record<string, EnhancedValidationResult>;
};
/**
* Validate video output options (resolution, length, aspect ratio, audio)
*
* @param options - VideoOutputOptions to validate
* @returns NeuroLinkError if invalid, null if valid
*
* @example
* ```typescript
* const error = validateVideoOutputOptions({ resolution: "4K", length: 10 });
* // error.code === "INVALID_VIDEO_RESOLUTION"
* ```
*/
export declare function validateVideoOutputOptions(options: VideoOutputOptions): NeuroLinkError | null;
/**
* Validate image input for video generation
*
* Checks image format (magic bytes) and size constraints.
* Supports JPEG, PNG, and WebP formats.
*
* @param image - Image buffer to validate
* @param maxSize - Maximum allowed size in bytes (default: 10MB)
* @returns NeuroLinkError if invalid, null if valid
*
* @example
* ```typescript
* const imageBuffer = readFileSync("product.jpg");
* const error = validateImageForVideo(imageBuffer);
* if (error) throw error;
* ```
*/
export declare function validateImageForVideo(image: Buffer | string, maxSize?: number): NeuroLinkError | null;
/**
* Validate complete video generation input
*
* Validates all requirements for video generation:
* - output.mode must be "video"
* - Must have exactly one input image
* - Prompt must be within length limits
* - Video output options must be valid
*
* @param options - GenerateOptions to validate for video generation
* @returns EnhancedValidationResult with errors, warnings, and suggestions
*
* @example
* ```typescript
* const validation = validateVideoGenerationInput({
* input: { text: "Product showcase video", images: [imageBuffer] },
* output: { mode: "video", video: { resolution: "1080p" } }
* });
* if (!validation.isValid) {
* console.error(validation.errors);
* }
* ```
*/
export declare function validateVideoGenerationInput(options: GenerateOptions): EnhancedValidationResult;
/**
* Validate Director Mode input: segments, transition prompts, and durations.
*
* @param options - GenerateOptions with input.segments and output.director
* @returns EnhancedValidationResult with errors, warnings, and suggestions
*/
export declare function validateDirectorModeInput(options: GenerateOptions): EnhancedValidationResult;
export declare const MIN_PPT_PAGES = 5;
export declare const MAX_PPT_PAGES = 50;
export declare const MIN_PPT_PROMPT_LENGTH = 10;
export declare const MAX_PPT_PROMPT_LENGTH = 1000;
/**
* Validate PPT output options (pages, theme, audience, tone, etc.)
*
* @param options - PPTOutputOptions to validate
* @returns NeuroLinkError if invalid, null if valid
*
* @example
* ```typescript
* const error = validatePPTOutputOptions({ pages: 100, theme: "invalid" });
* // error.code === "INVALID_PPT_PAGES"
* ```
*/
export declare function validatePPTOutputOptions(options: PPTOutputOptions): NeuroLinkError | null;
/**
* Validate PPT provider (supports vertex, openai, azure, anthropic, google-ai, bedrock)
*
* @param provider - Provider name to validate
* @returns NeuroLinkError if invalid, null if valid
*
* @example
* ```typescript
* const error = validatePPTProvider("unsupported-provider");
* // error.code === "INVALID_PPT_PROVIDER"
* ```
*/
export declare function validatePPTProvider(provider: AIProviderName | string): NeuroLinkError | null;
/**
* Validate complete PPT generation input
*
* Validates all requirements for presentation generation:
* - output.mode must be "ppt"
* - Prompt must be within length limits
* - PPT output options must be valid
*
* @param options - GenerateOptions to validate for PPT generation
* @returns EnhancedValidationResult with errors, warnings, and suggestions
*
* @example
* ```typescript
* const validation = validatePPTGenerationInput({
* input: { text: "Introducing Our New Product" },
* output: { mode: "ppt", ppt: { pages: 10, theme: "modern" } }
* });
* if (!validation.isValid) {
* console.error(validation.errors);
* }
* ```
*/
export declare function validatePPTGenerationInput(options: GenerateOptions): EnhancedValidationResult;
/**
* Create a validation error summary for logging
*/
export declare function createValidationSummary(result: EnhancedValidationResult): string;
/**
* Check if validation result has only warnings (no errors)
*/
export declare function hasOnlyWarnings(result: EnhancedValidationResult): boolean;
/**
* Default bound on a `beforeStep` callback (ms).
*
* A boundary callback sits between two model calls, in the one place no other
* timer in the turn is watching: the request deadline has been disposed and
* the next one is not armed yet. An unbounded callback therefore stalls the
* turn silently and indefinitely.
*/
export declare const DEFAULT_BEFORE_STEP_TIMEOUT_MS = 30000;
/**
* Validate an opt-in `executionControl` object and its provider support.
*
* Rejecting rather than ignoring is the whole point. A caller that asked for
* no lifetime ceiling and got one anyway does not find out at call time — it
* finds out much later, when a long turn dies at a limit its owner believed it
* had removed, reported as an ordinary cancel. So an unsupported provider is an
* error here, and so is every shape that could be read two ways.
*
* Throws ValidationError; returns void when the control is absent or valid.
*
* @param request the sibling options on the SAME call that this control has to
* be read together with. `turnTimeoutMs`, because a combination in which one
* of the two ceilings would be silently discarded is rejected instead; and
* `toolTimeoutMs`, because removing the turn's ceiling makes the per-tool
* deadline the last thing watching a tool that never returns.
*/
export declare function validateExecutionControl(control: unknown, providerName: string, supported: boolean, request?: {
turnTimeoutMs?: unknown;
toolTimeoutMs?: unknown;
}): void;