/** * Server Adapter Types * Comprehensive type system for NeuroLink server adapters */ import type { ExternalServerManager } from "../mcp/externalServerManager.js"; import type { MCPToolRegistry } from "../mcp/toolRegistry.js"; import type { NeuroLink } from "../neurolink.js"; import type { JsonObject, JsonValue } from "./common.js"; import type { ExternalMCPServerStatus } from "./externalMcp.js"; /** * Server adapter configuration */ export type ServerAdapterConfig = { /** Server port (default: 3000) */ port?: number; /** Server host (default: "0.0.0.0") */ host?: string; /** Base path for all routes (default: "/api") */ basePath?: string; /** CORS configuration */ cors?: CORSConfig; /** Rate limiting configuration */ rateLimit?: RateLimitConfig; /** Body parser configuration */ bodyParser?: BodyParserConfig; /** Logging configuration */ logging?: LoggingConfig; /** Request timeout in milliseconds (default: 30000) */ timeout?: number; /** Enable metrics endpoint (default: true) */ enableMetrics?: boolean; /** Enable Swagger/OpenAPI documentation (default: false) */ enableSwagger?: boolean; /** Disable built-in health routes (use when registering healthRoutes separately) */ disableBuiltInHealth?: boolean; /** Stream redaction configuration (disabled by default) */ redaction?: RedactionConfig; /** Shutdown configuration for graceful shutdown behavior */ shutdown?: ShutdownConfig; }; /** * Required server adapter configuration (with defaults applied) */ export type RequiredServerAdapterConfig = { port: number; host: string; basePath: string; cors: RequiredCORSConfig; rateLimit: RequiredRateLimitConfig; bodyParser: RequiredBodyParserConfig; logging: RequiredLoggingConfig; timeout: number; enableMetrics: boolean; enableSwagger: boolean; disableBuiltInHealth: boolean; redaction?: RequiredRedactionConfig; shutdown: RequiredShutdownConfig; }; /** * CORS configuration */ export type CORSConfig = { /** Enable CORS (default: true) */ enabled?: boolean; /** Allowed origins (default: ["*"]) */ origins?: string[]; /** Allowed HTTP methods */ methods?: string[]; /** Allowed headers */ headers?: string[]; /** Allow credentials */ credentials?: boolean; /** Preflight cache max age in seconds */ maxAge?: number; }; /** * Required CORS configuration */ export type RequiredCORSConfig = { enabled: boolean; origins: string[]; methods: string[]; headers: string[]; credentials: boolean; maxAge: number; }; /** * Rate limiting configuration */ export type RateLimitConfig = { /** Enable rate limiting (default: true) */ enabled?: boolean; /** Time window in milliseconds (default: 15 minutes) */ windowMs?: number; /** Maximum requests per window (default: 100) */ maxRequests?: number; /** Custom error message */ message?: string; /** Skip rate limiting for certain paths */ skipPaths?: string[]; /** Custom key generator function */ keyGenerator?: (ctx: ServerContext) => string; }; /** * Required rate limit configuration */ export type RequiredRateLimitConfig = { enabled: boolean; windowMs: number; maxRequests: number; message: string; skipPaths?: string[]; keyGenerator?: (ctx: ServerContext) => string; }; /** * Body parser configuration */ export type BodyParserConfig = { /** Enable body parsing (default: true) */ enabled?: boolean; /** Maximum body size (default: "10mb") */ maxSize?: string; /** JSON body limit (default: "10mb") */ jsonLimit?: string; /** Enable URL-encoded body parsing */ urlEncoded?: boolean; }; /** * Required body parser configuration */ export type RequiredBodyParserConfig = { enabled: boolean; maxSize: string; jsonLimit: string; urlEncoded: boolean; }; /** * Logging configuration */ export type LoggingConfig = { /** Enable request logging (default: true) */ enabled?: boolean; /** Log level */ level?: "debug" | "info" | "warn" | "error"; /** Include request body in logs */ includeBody?: boolean; /** Include response body in logs */ includeResponse?: boolean; }; /** * Required logging configuration */ export type RequiredLoggingConfig = { enabled: boolean; level: "debug" | "info" | "warn" | "error"; includeBody: boolean; includeResponse: boolean; }; /** * Configuration for stream redaction * * IMPORTANT: Redaction is DISABLED by default (enabled: false) * This is an opt-in security feature to prevent accidental data exposure. */ export type RedactionConfig = { /** * Enable stream redaction (default: false) * * When false, redactStreamChunk() returns chunks unchanged. * Must be explicitly set to true to enable redaction. */ enabled?: boolean; /** Additional field names to redact (case-insensitive) */ additionalFields?: string[]; /** Field names to preserve (not redact) */ preserveFields?: string[]; /** Whether to redact tool arguments when enabled (default: true) */ redactToolArgs?: boolean; /** Whether to redact tool results when enabled (default: true) */ redactToolResults?: boolean; /** Custom redaction placeholder (default: "[REDACTED]") */ placeholder?: string; }; /** * Required redaction configuration (with defaults applied) */ export type RequiredRedactionConfig = { enabled: boolean; additionalFields: string[]; preserveFields: string[]; redactToolArgs: boolean; redactToolResults: boolean; placeholder: string; }; /** * Server request context * Passed to all route handlers and middleware */ export type ServerContext = { /** Unique request ID */ requestId: string; /** HTTP method */ method: string; /** Request path */ path: string; /** Request headers */ headers: Record; /** Query parameters */ query: Record; /** Path parameters */ params: Record; /** Request body (parsed) */ body?: unknown; /** NeuroLink SDK instance */ neurolink: NeuroLink; /** Tool registry instance */ toolRegistry: MCPToolRegistry; /** External server manager (optional) */ externalServerManager?: ExternalServerManager; /** Request timestamp */ timestamp: number; /** Additional metadata */ metadata: Record; /** User information (if authenticated) */ user?: AuthenticatedUser; /** Session information */ session?: { id: string; data?: Record; }; /** Abort signal for cancellation (set by abort signal middleware) */ abortSignal?: AbortSignal; /** Abort controller for manual cancellation (set by abort signal middleware) */ abortController?: AbortController; /** Raw framework response object (for framework-specific operations) */ rawResponse?: unknown; /** Raw framework request object (for framework-specific operations) */ rawRequest?: unknown; /** Response headers to be set (used by middleware to add headers) */ responseHeaders?: Record; /** Redaction configuration (for stream redaction support) */ redaction?: RedactionConfig; }; /** * Server response object */ export type ServerResponse = { /** Response data */ data?: T; /** Error information */ error?: { code: string; message: string; details?: Record; }; /** Response metadata */ metadata?: { requestId: string; timestamp: string; duration?: number; }; }; /** * Streaming response configuration */ export type StreamingConfig = { /** Enable streaming response */ enabled: boolean; /** Content type for streaming */ contentType?: "text/event-stream" | "application/x-ndjson"; /** Keep-alive interval in milliseconds */ keepAliveInterval?: number; }; /** * HTTP methods supported by server adapters */ export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS"; /** * Route deprecation information */ export type RouteDeprecation = { /** Whether the route is deprecated */ enabled: boolean; /** Version when deprecated */ since?: string; /** Version when route will be removed */ removeIn?: string; /** Alternative route to use */ alternative?: string; /** Deprecation message */ message?: string; }; /** * Route definition */ export type RouteDefinition = { /** HTTP method */ method: HttpMethod; /** Route path (supports parameters like :id) */ path: string; /** Route handler function */ handler: RouteHandler; /** Route description (for documentation) */ description?: string; /** Request schema (for validation) */ requestSchema?: JsonObject; /** Response schema (for documentation) */ responseSchema?: JsonObject; /** Authentication required */ auth?: boolean; /** Required roles */ roles?: string[]; /** Rate limit override for this route */ rateLimit?: RateLimitConfig; /** Streaming configuration */ streaming?: StreamingConfig; /** Route tags (for documentation) */ tags?: string[]; /** Route deprecation information */ deprecated?: RouteDeprecation; }; /** * Route handler function */ export type RouteHandler = (ctx: ServerContext) => Promise | AsyncIterable>; /** * Route group for organizing related routes */ export type RouteGroup = { /** Group prefix */ prefix: string; /** Routes in this group */ routes: RouteDefinition[]; /** Middleware specific to this group */ middleware?: MiddlewareDefinition[]; /** Group-level authentication */ auth?: boolean; /** Group-level roles */ roles?: string[]; }; /** * Middleware definition */ export type MiddlewareDefinition = { /** Middleware name */ name: string; /** Execution order (lower = earlier) */ order?: number; /** Middleware handler */ handler: MiddlewareHandler; /** Paths to apply middleware to (default: all) */ paths?: string[]; /** Paths to exclude from middleware */ excludePaths?: string[]; }; /** * Middleware handler function */ export type MiddlewareHandler = (ctx: ServerContext, next: () => Promise) => Promise; /** * Server adapter events */ export type ServerAdapterEvents = { /** Server initialized */ initialized: { config: ServerAdapterConfig; routeCount: number; middlewareCount: number; }; /** Server started */ started: { port: number; host: string; timestamp: Date; }; /** Server stopped */ stopped: { uptime: number; timestamp: Date; }; /** Request received */ request: { requestId: string; method: string; path: string; timestamp: Date; }; /** Response sent */ response: { requestId: string; statusCode: number; duration: number; timestamp: Date; }; /** Error occurred */ error: { requestId?: string; error: Error; timestamp: Date; }; }; /** * Agent execution request */ export type AgentExecuteRequest = { /** Input prompt or message */ input: string | { text: string; images?: string[]; files?: string[]; }; /** Provider to use (optional) */ provider?: string; /** Model to use (optional) */ model?: string; /** System prompt (optional) */ systemPrompt?: string; /** Temperature (0-1) */ temperature?: number; /** Maximum tokens */ maxTokens?: number; /** Tools to enable */ tools?: string[]; /** Enable streaming */ stream?: boolean; /** Session ID for conversation memory */ sessionId?: string; /** User ID for context */ userId?: string; }; /** * Agent execution response */ export type AgentExecuteResponse = { /** Generated content */ content: string; /** Provider used */ provider: string; /** Model used */ model: string; /** Token usage */ usage?: { /** Input tokens (also known as prompt tokens) */ input: number; /** Output tokens (also known as completion tokens) */ output: number; /** Total tokens used */ total: number; /** Cache creation tokens (if applicable) */ cacheCreationTokens?: number; /** Cache read tokens (if applicable) */ cacheReadTokens?: number; /** Reasoning tokens (if applicable) */ reasoning?: number; /** Cache savings percentage */ cacheSavingsPercent?: number; }; /** Tool calls made */ toolCalls?: Array<{ name: string; arguments: Record; result?: unknown; }>; /** Finish reason */ finishReason?: string; /** Response metadata */ metadata?: Record; }; /** * Embed request (single text) */ export type EmbedRequest = { /** Text to embed */ text: string; /** Provider to use (optional) */ provider?: string; /** Embedding model to use (optional) */ model?: string; }; /** * Embed response (single text) */ export type EmbedResponse = { /** The embedding vector */ embedding: number[]; /** Provider used */ provider: string; /** Model used */ model: string; /** Embedding dimension */ dimension: number; }; /** * Embed many request (batch texts) */ export type EmbedManyRequest = { /** Texts to embed */ texts: string[]; /** Provider to use (optional) */ provider?: string; /** Embedding model to use (optional) */ model?: string; }; /** * Embed many response (batch texts) */ export type EmbedManyResponse = { /** The embedding vectors */ embeddings: number[][]; /** Provider used */ provider: string; /** Model used */ model: string; /** Number of embeddings */ count: number; /** Embedding dimension */ dimension: number; }; /** * Tool execution request */ export type ToolExecuteRequest = { /** Tool name */ name: string; /** Tool arguments */ arguments: Record; /** Session context */ sessionId?: string; /** User context */ userId?: string; }; /** * Tool execution response */ export type ToolExecuteResponse = { /** Whether execution was successful */ success: boolean; /** Result data */ data?: unknown; /** Error message if failed */ error?: string; /** Execution duration in ms */ duration: number; /** Tool metadata */ metadata?: Record; }; /** * MCP server status response */ export type MCPServerStatusResponse = { /** Server ID */ serverId: string; /** Server name */ name: string; /** Connection status */ status: ExternalMCPServerStatus; /** Available tools count */ toolCount: number; /** Last health check time */ lastHealthCheck?: string; /** Error message if failed */ error?: string; }; /** * Health check response */ export type HealthResponse = { /** Health status */ status: "ok" | "degraded" | "unhealthy"; /** Timestamp */ timestamp: string; /** Server uptime in milliseconds */ uptime: number; /** Version information */ version: string; }; /** * Ready check response */ export type ReadyResponse = { /** Ready status */ ready: boolean; /** Timestamp */ timestamp: string; /** Service status */ services: { neurolink: boolean; tools: boolean; externalServers: boolean; }; }; /** * Supported server frameworks */ export type ServerFramework = "hono" | "express" | "fastify" | "koa"; /** * Server adapter factory options */ export type ServerAdapterFactoryOptions = { /** Framework to use */ framework: ServerFramework; /** NeuroLink instance */ neurolink: NeuroLink; /** Server configuration */ config?: ServerAdapterConfig; }; /** * Server status information */ export type ServerStatus = { /** Whether server is running */ running: boolean; /** Server port */ port: number; /** Server host */ host: string; /** Server uptime in milliseconds */ uptime: number; /** Number of registered routes */ routes: number; /** Number of registered middleware */ middlewares: number; /** Current lifecycle state */ lifecycleState?: ServerLifecycleState; /** Number of active connections */ activeConnections?: number; }; /** * SSE write options */ export type SSEWriteOptions = { /** Event name */ event?: string; /** Event data (will be JSON stringified if object) */ data: string | object; /** Event ID */ id?: string; /** Retry interval in milliseconds */ retry?: number; }; /** * Data stream writer interface */ export type DataStreamWriter = { /** Write text start event */ writeTextStart(id: string): Promise; /** Write text delta event */ writeTextDelta(id: string, delta: string): Promise; /** Write text end event */ writeTextEnd(id: string): Promise; /** Write tool call event */ writeToolCall(toolCall: { id: string; name: string; arguments: Record; }): Promise; /** Write tool result event */ writeToolResult(toolResult: { id: string; name: string; result: unknown; }): Promise; /** Write arbitrary data event */ writeData(data: unknown): Promise; /** Write error event */ writeError(error: { message: string; code?: string; }): Promise; /** Close the stream */ close(): Promise; }; /** * WebSocket message types */ export type WebSocketMessageType = "text" | "binary" | "ping" | "pong" | "close"; /** * WebSocket message */ export type WebSocketMessage = { type: WebSocketMessageType; data: string | ArrayBuffer; timestamp: number; }; /** * Authenticated user information */ export type AuthenticatedUser = { id: string; email?: string; name?: string; roles?: string[]; permissions?: string[]; metadata?: Record; }; /** * WebSocket connection */ export type WebSocketConnection = { id: string; socket: unknown; user?: AuthenticatedUser; metadata: Record; createdAt: number; lastActivity: number; }; /** * Authentication strategy types */ export type AuthStrategy = "bearer" | "apiKey" | "basic" | "custom" | "none"; /** * Authentication configuration */ export type ServerAuthConfig = { strategy: AuthStrategy; required?: boolean; headerName?: string; queryParam?: string; validate?: (token: string) => Promise; roles?: string[]; permissions?: string[]; }; /** * WebSocket handler interface */ export type WebSocketHandler = { onOpen?: (connection: WebSocketConnection) => void | Promise; onMessage?: (connection: WebSocketConnection, message: WebSocketMessage) => void | Promise; onClose?: (connection: WebSocketConnection, code: number, reason: string) => void | Promise; onError?: (connection: WebSocketConnection, error: Error) => void | Promise; }; /** * WebSocket server configuration */ export type WebSocketConfig = { path?: string; maxConnections?: number; pingInterval?: number; pongTimeout?: number; maxMessageSize?: number; auth?: ServerAuthConfig; }; /** * Server lifecycle states * Represents the current state of the server adapter */ export type ServerLifecycleState = "uninitialized" | "initializing" | "initialized" | "starting" | "running" | "draining" | "stopping" | "stopped" | "error"; /** * Configuration for graceful shutdown behavior */ export type ShutdownConfig = { /** * Maximum time to wait for graceful shutdown in milliseconds * Default: 30000 (30 seconds) */ gracefulShutdownTimeoutMs?: number; /** * Maximum time to wait for connections to drain in milliseconds * Default: 15000 (15 seconds) */ drainTimeoutMs?: number; /** * Whether to force close connections after timeout * Default: true */ forceClose?: boolean; }; /** * Required shutdown configuration (with defaults applied) */ export type RequiredShutdownConfig = { gracefulShutdownTimeoutMs: number; drainTimeoutMs: number; forceClose: boolean; }; /** * Tracked connection for graceful shutdown */ export type TrackedConnection = { /** Unique connection identifier */ id: string; /** Timestamp when connection was created */ createdAt: number; /** Underlying socket or connection object */ socket?: unknown; /** Request ID if associated with a request */ requestId?: string; /** Whether the connection is currently processing a request */ isActive?: boolean; }; /** * Error categories for server adapter errors */ export declare const ErrorCategory: { readonly CONFIG: "CONFIG"; readonly VALIDATION: "VALIDATION"; readonly EXECUTION: "EXECUTION"; readonly EXTERNAL: "EXTERNAL"; readonly RATE_LIMIT: "RATE_LIMIT"; readonly AUTHENTICATION: "AUTHENTICATION"; readonly AUTHORIZATION: "AUTHORIZATION"; readonly STREAMING: "STREAMING"; readonly WEBSOCKET: "WEBSOCKET"; }; export type ErrorCategoryType = (typeof ErrorCategory)[keyof typeof ErrorCategory]; /** * Error severity levels */ export declare const ErrorSeverity: { readonly LOW: "LOW"; readonly MEDIUM: "MEDIUM"; readonly HIGH: "HIGH"; readonly CRITICAL: "CRITICAL"; }; export type ErrorSeverityType = (typeof ErrorSeverity)[keyof typeof ErrorSeverity]; /** * Server adapter error codes */ export declare const ServerAdapterErrorCode: { readonly INVALID_CONFIG: "SERVER_ADAPTER_INVALID_CONFIG"; readonly MISSING_DEPENDENCY: "SERVER_ADAPTER_MISSING_DEPENDENCY"; readonly FRAMEWORK_INIT_FAILED: "SERVER_ADAPTER_FRAMEWORK_INIT_FAILED"; readonly ROUTE_NOT_FOUND: "SERVER_ADAPTER_ROUTE_NOT_FOUND"; readonly ROUTE_CONFLICT: "SERVER_ADAPTER_ROUTE_CONFLICT"; readonly INVALID_ROUTE: "SERVER_ADAPTER_INVALID_ROUTE"; readonly HANDLER_ERROR: "SERVER_ADAPTER_HANDLER_ERROR"; readonly TIMEOUT: "SERVER_ADAPTER_TIMEOUT"; readonly MIDDLEWARE_ERROR: "SERVER_ADAPTER_MIDDLEWARE_ERROR"; readonly RATE_LIMIT_EXCEEDED: "SERVER_ADAPTER_RATE_LIMIT_EXCEEDED"; readonly AUTH_REQUIRED: "SERVER_ADAPTER_AUTH_REQUIRED"; readonly AUTH_INVALID: "SERVER_ADAPTER_AUTH_INVALID"; readonly FORBIDDEN: "SERVER_ADAPTER_FORBIDDEN"; readonly STREAM_ERROR: "SERVER_ADAPTER_STREAM_ERROR"; readonly STREAM_ABORTED: "SERVER_ADAPTER_STREAM_ABORTED"; readonly WEBSOCKET_ERROR: "SERVER_ADAPTER_WEBSOCKET_ERROR"; readonly WEBSOCKET_CONNECTION_FAILED: "SERVER_ADAPTER_WEBSOCKET_CONNECTION_FAILED"; readonly VALIDATION_ERROR: "SERVER_ADAPTER_VALIDATION_ERROR"; readonly SCHEMA_ERROR: "SERVER_ADAPTER_SCHEMA_ERROR"; readonly START_FAILED: "SERVER_ADAPTER_START_FAILED"; readonly STOP_FAILED: "SERVER_ADAPTER_STOP_FAILED"; readonly ALREADY_RUNNING: "SERVER_ADAPTER_ALREADY_RUNNING"; readonly NOT_RUNNING: "SERVER_ADAPTER_NOT_RUNNING"; }; export type ServerAdapterErrorCodeType = (typeof ServerAdapterErrorCode)[keyof typeof ServerAdapterErrorCode]; /** * Error context for server adapter errors */ export type ServerAdapterErrorContext = { category: ErrorCategoryType; severity: ErrorSeverityType; retryable: boolean; retryAfterMs?: number; requestId?: string; path?: string; method?: string; details?: Record; cause?: Error; }; export type Frame = { type: "audio"; data: Int16Array; } | { type: "vad_start"; } | { type: "vad_stop"; } | { type: "transcript"; text: string; final: boolean; } | { type: "llm_token"; text: string; } | { type: "tts_audio"; data: Buffer; } | { type: "interrupt"; }; /** * Standardized error response format */ export type ErrorResponse = { error: { code: string; message: string; details?: unknown; }; metadata?: { timestamp: string; requestId?: string; }; httpStatus?: number; }; /** * Generic validation result with type-safe data or error. * Named ServerValidationResult to avoid collision with tools.ts ValidationResult. */ export type ServerValidationResult = { success: true; data: T; error?: undefined; } | { success: false; error: ErrorResponse; data?: undefined; }; /** * Authentication configuration */ export type ServerServerAuthConfig = { /** Authentication type */ type: "bearer" | "api-key" | "basic" | "custom"; /** * Token validation function * Returns user information if valid, throws or returns null if invalid */ validate: (token: string, ctx: ServerContext) => Promise; /** Header name for token (default: "Authorization" for bearer, "X-API-Key" for api-key) */ headerName?: string; /** Skip authentication for certain paths */ skipPaths?: string[]; /** Custom error message */ errorMessage?: string; /** * Optional token extractor for custom authentication schemes * Only used when type is "custom" */ extractToken?: (ctx: ServerContext) => string | null; /** * Skip authentication for dev playground requests in non-production. * When true (default), requests with x-neurolink-dev-playground or * x-neurolink-playground header set to "true" will bypass authentication * and receive a default developer user context. * * Only applies when NODE_ENV is not "production". * * @default true */ skipDevPlayground?: boolean; }; /** * Cache configuration */ export type ServerCacheConfig = { /** Default TTL in milliseconds */ ttlMs: number; /** Maximum cache size (number of entries) */ maxSize?: number; /** * Custom key generator * Default: method + path + sorted query params */ keyGenerator?: (ctx: ServerContext) => string; /** * Methods to cache (default: GET only) */ methods?: string[]; /** * Paths to cache (default: all paths) */ paths?: string[]; /** * Paths to exclude from caching */ excludePaths?: string[]; /** * Custom cache store * Default: in-memory store */ store?: CacheStore; /** * Whether to include query params in cache key * Default: true */ includeQuery?: boolean; /** * Custom TTL per path pattern */ ttlByPath?: Record; }; /** * Base data stream event */ export type DataStreamEvent = { type: DataStreamEventType; id?: string; timestamp: number; data: unknown; }; export type AuthResult = { /** User ID */ id: string; /** User email (optional) */ email?: string; /** User roles (optional) */ roles?: string[]; /** Additional user data */ metadata?: Record; }; export type CacheStore = { get(key: string): Promise; set(key: string, entry: CacheEntry): Promise; delete(key: string): Promise; clear(): Promise; }; export type DataStreamEventType = "text-start" | "text-delta" | "text-end" | "tool-call" | "tool-result" | "data" | "error" | "finish"; export type CacheEntry = { data: unknown; createdAt: number; ttlMs: number; headers?: Record; }; /** Voice-server conversation turn — superset role set. */ export type Message = { role: "system" | "user" | "assistant"; content: string; }; /** Subset of Message that excludes the system role (assistant+user only). */ export type ConversationMessage = { role: "user" | "assistant"; content: string; }; /** Configuration passed to the OpenAPI spec generator. */ export type OpenAPIGeneratorConfig = { info?: { title?: string; version?: string; description?: string; }; servers?: Array<{ url: string; description?: string; }>; includeSecurity?: boolean; basePath?: string; additionalTags?: Array<{ name: string; description: string; }>; customSchemas?: Record; routes?: RouteDefinition[]; }; /** Structured OpenAPI 3.1 specification object. */ export type OpenAPISpec = { openapi: "3.1.0"; info: JsonObject; servers: JsonObject[]; tags: JsonObject[]; paths: Record; components: { schemas: Record; securitySchemes?: Record; parameters?: Record; }; security?: JsonObject[]; }; /** Options for createAllRoutes / createRoutes. */ export type CreateRoutesOptions = { enableSwagger?: boolean; getRoutes?: () => RouteDefinition[]; claudeProxy?: boolean; }; /** Data stream finish event. */ export type FinishEvent = DataStreamEvent & { type: "finish"; data: { reason?: string; usage?: { input: number; output: number; total: number; }; }; }; /** Configuration for DataStreamWriter. */ export type DataStreamWriterConfig = { write: (chunk: string) => void | Promise; close?: () => void | Promise; format?: "sse" | "ndjson"; includeTimestamps?: boolean; }; /** Configuration for the DataStreamResponse wrapper. */ export type DataStreamResponseConfig = { contentType?: "text/event-stream" | "application/x-ndjson"; headers?: Record; keepAliveInterval?: number; includeTimestamps?: boolean; }; /** Options for a single SSE message. */ export type SSEEventOptions = { event?: string; data: string; id?: string; retry?: number; }; /** Single token emitted by the Soniox STT stream. */ export type SonioxToken = { is_final?: boolean; text?: string; }; /** Envelope received from the Soniox STT WebSocket. */ export type SonioxMessage = { error?: string; status?: string; type?: string; tokens?: SonioxToken[]; }; /** Control message received from the voice client over WebSocket. */ export type ClientControlMessage = { type?: string; }; /** * Structural type for Picovoice Cobra VAD instance. * Defined here so the optional `@picovoice/cobra-node` package * is not required at typecheck time. */ export type CobraInstance = { frameLength: number; process: (pcm: Int16Array) => number; release: () => void; }; /** * Per-WebSocket-connection context object passed to the voice connection * handler. Holds shared singletons that all per-connection state derives from. * * (Server-prefixed per CLAUDE.md Rule 9 — server-tier type.) */ export type ServerVoiceConnectionCtx = { neurolink: NeuroLink; accessKey: string; }; /** * Per-session mutable state for one voice WebSocket connection. * * Threaded through the voice connection helper functions so each connection * has fully isolated turn / TTS / VAD / barge-in state. The class types * (`FrameBus`, `TurnManager`, `CartesiaStream`) are imported as types here so * that this file remains the single source of truth — consumers import this * type via the barrel and do not redefine it locally. * * (Server-prefixed per CLAUDE.md Rule 9 — server-tier type.) */ export type ServerVoiceSessionState = { cobra: CobraInstance | null; FRAME_LENGTH: number; FRAME_BYTES: number; bus: import("../server/voice/frameBus.js").FrameBus; turnManager: import("../server/voice/turnManager.js").TurnManager; sonioxWs: import("ws").WebSocket | null; keepAliveTimer: NodeJS.Timeout | null; sonioxReconnectTimer: ReturnType | null; sessionClosed: boolean; transcriptBuffer: string; activeTTS: import("../adapters/tts/cartesiaHandler.js").CartesiaStream | null; conversation: ConversationMessage[]; currentTurnId: number; activePipelineTurnId: number | null; turnAborters: Set<{ aborted: boolean; }>; playbackResetTimer: NodeJS.Timeout | null; bargeInLockedUntil: number; isSpeaking: boolean; silenceFrameCount: number; voiceFrameCount: number; frameRemainder: Buffer; }; /** * Options accepted by `setupWebSocket()` in `server/voice/voiceWebSocketHandler.ts`. * * (Server-prefixed per CLAUDE.md Rule 9 — server-tier type. Lives in * `server.ts` rather than `cli.ts` because it configures a server-side * WebSocket upgrade handler, not CLI argument parsing.) */ export type ServerVoiceWebSocketOptions = { /** * Optional shared-secret bearer token. When set, the WebSocket upgrade * handshake must include `Authorization: Bearer ` or * `?token=` in the URL. Without this, anyone reachable on the * network can open a session and consume Soniox / Cartesia / LLM credits. */ authToken?: string; /** * Maximum WebSocket message size in bytes. Defaults to 1 MiB. Caps both * inbound audio frames and any client control messages — guards against * OOM via oversized uploads. */ maxPayload?: number; };