@juspay/neurolink 12.48.1 → 12.49.0

package/dist/server/adapters/honoAdapter.js

@@ -4,13 +4,34 @@
  * Hono is chosen for its performance, TypeScript-first design, and edge compatibility
  */
 import { logger } from "../../utils/logger.js";
-import { AlreadyRunningError, ServerStopError, wrapError } from "../errors.js";
+import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, parseByteLimit, RawBodyTooLargeError, readRawBody, } from "../utils/rawBody.js";
 /**
  * Hono-specific server adapter
  * Supports multiple runtimes: Bun, Deno, Node.js
  */
+/** Raw bodies already read for a request, so a second extraction never hits a consumed stream. */
+const rawBodies = new WeakMap();
+/** A web `ReadableStream` of bytes as an async iterable of Buffers, releasing the reader on exit. */
+async function* webStreamChunks(stream) {
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done) {
+                return;
+            }
+            if (value) {
+                yield Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 export class HonoServerAdapter extends BaseServerAdapter {
     app;
     server;
@@ -132,7 +153,12 @@ export class HonoServerAdapter extends BaseServerAdapter {
         // Add CORS if enabled
         if (this.config.cors.enabled) {
             this.app.use("*", cors({
-                origin: this.config.cors.origins,
+                // Hono matches a list of origins literally, so `["*"]` (the default)
+                // matches nothing and no CORS header is sent; the string "*" is the
+                // wildcard. Pass it as such when the list contains it.
+                origin: this.config.cors.origins.includes("*")
+                    ? "*"
+                    : this.config.cors.origins,
                 allowMethods: this.config.cors.methods,
                 allowHeaders: this.config.cors.headers,
                 credentials: this.config.cors.credentials,
@@ -154,16 +180,21 @@ export class HonoServerAdapter extends BaseServerAdapter {
         // Global error handler
         this.app.onError((error, c) => {
             const requestId = c.req.header("X-Request-ID") || this.generateRequestId();
-            logger.error("[HonoAdapter] Request error", {
-                requestId,
-                error: error.message,
-                stack: error.stack,
-            });
-            this.emit("error", {
+            this.logRequestError("HonoAdapter", requestId, error);
+            this.emitRequestError({
                 requestId,
                 error,
                 timestamp: new Date(),
             });
+            if (error instanceof ServerAdapterError) {
+                return c.json({
+                    error: { code: error.code, message: error.message },
+                    metadata: {
+                        requestId,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, error.getHttpStatus());
+            }
             if (error instanceof HTTPException) {
                 return c.json({
                     error: {
@@ -237,6 +268,21 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 // Execute handler
                 const result = await route.handler(ctx);
                 const duration = Date.now() - startTime;
+                // A route that answers in its own wire format returns a web Response.
+                if (isWebResponse(result)) {
+                    this.emit("response", {
+                        requestId,
+                        statusCode: result.status,
+                        duration,
+                        timestamp: new Date(),
+                    });
+                    for (const [key, value] of Object.entries(ctx.responseHeaders ?? {})) {
+                        if (!result.headers.has(key)) {
+                            result.headers.set(key, value);
+                        }
+                    }
+                    return result;
+                }
                 // Check if result is an error response
                 if (isErrorResponse(result)) {
                     const statusCode = result.httpStatus ?? 500;
@@ -599,6 +645,10 @@ export class HonoServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        // @hono/node-server's serve() returns the http.Server; Bun/Deno do not.
+        return this.server;
+    }
     // ============================================
     // Helper Methods
     // ============================================
@@ -638,6 +688,43 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 return undefined;
             }
         }
+        // Uploads (multipart, octet-stream, audio/*) reach the route as bytes.
+        // Over the size limit the body is the error itself rather than a throw:
+        // a throw from the middleware path would land in onError, which answers
+        // 500. The route answers 413 (or a validation error) from it.
+        if (isRawBodyContentType(contentType)) {
+            const limit = parseByteLimit(this.config.bodyParser.maxSize);
+            if (Number(c.req.header("Content-Length") ?? 0) > limit) {
+                return new RawBodyTooLargeError(limit);
+            }
+            // Read the web stream chunk by chunk and stop at the limit, so a
+            // chunked upload without a Content-Length cannot be buffered whole
+            // (and that before any route logic, including the API-key check, runs).
+            // The body is extracted more than once per request (middleware and
+            // route); a web stream can only be read once, so the outcome is kept
+            // per request the way Hono caches `arrayBuffer()`.
+            const cached = rawBodies.get(c.req.raw);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const stream = c.req.raw.body;
+            if (!stream) {
+                return Buffer.alloc(0);
+            }
+            let outcome;
+            try {
+                outcome = await readRawBody(webStreamChunks(stream), limit);
+            }
+            catch (error) {
+                if (!(error instanceof RawBodyTooLargeError)) {
+                    throw error;
+                }
+                await stream.cancel().catch(() => undefined);
+                outcome = error;
+            }
+            rawBodies.set(c.req.raw, outcome);
+            return outcome;
+        }
         return undefined;
     }
 }

package/dist/server/adapters/koaAdapter.d.ts

@@ -18,6 +18,7 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
     private rateLimitStore;
     private rateLimitCleanupInterval?;
     private sockets;
+    private registeredMiddleware;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**
      * Initialize Koa framework
@@ -52,6 +53,11 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
      * Register middleware with Koa
      */
     protected registerFrameworkMiddleware(middleware: MiddlewareDefinition): void;
+    /**
+     * Run registered middleware in registration order, then continue to the
+     * router. Reads the list per request, so later registrations apply too.
+     */
+    private runRegisteredMiddleware;
     /**
      * Start the Koa server
      */
@@ -76,4 +82,5 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
      * Get the Koa app instance
      */
     getFrameworkInstance(): unknown;
+    getNativeServer(): unknown;
 }

package/dist/server/adapters/koaAdapter.js

@@ -4,9 +4,10 @@
  * Koa is known for its elegant middleware composition using async/await
  */
 import { logger } from "../../utils/logger.js";
-import { AlreadyRunningError, ServerStopError, wrapError } from "../errors.js";
+import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, parseByteLimit, RawBodyTooLargeError, readRawBody, readWebResponse, } from "../utils/rawBody.js";
 /**
  * Koa-specific server adapter
  * Leverages Koa's middleware composition for clean request handling
@@ -19,6 +20,10 @@ export class KoaServerAdapter extends BaseServerAdapter {
     rateLimitStore = new Map();
     rateLimitCleanupInterval;
     sockets = new Set();
+    // Middleware from registerMiddleware(). It runs through one dispatcher that
+    // is mounted ahead of the router: app.use() after the router is mounted
+    // would only ever see requests no route matched.
+    registeredMiddleware = [];
     constructor(neurolink, config = {}) {
         super(neurolink, config);
     }
@@ -59,21 +64,19 @@ export class KoaServerAdapter extends BaseServerAdapter {
             catch (error) {
                 const err = error;
                 const requestId = ctx.state.requestId;
-                logger.error("[KoaAdapter] Request error", {
-                    requestId,
-                    error: err.message,
-                    stack: err.stack,
-                });
-                this.emit("error", {
+                this.logRequestError("KoaAdapter", requestId, err);
+                this.emitRequestError({
                     requestId,
                     error: err,
                     timestamp: new Date(),
                 });
-                const statusCode = err.status || err.statusCode || 500;
+                const adapterError = error instanceof ServerAdapterError ? error : undefined;
+                const statusCode = adapterError?.getHttpStatus() || err.status || err.statusCode || 500;
                 ctx.status = statusCode;
                 ctx.body = {
                     error: {
-                        code: statusCode === 500 ? "INTERNAL_ERROR" : `HTTP_${statusCode}`,
+                        code: adapterError?.code ??
+                            (statusCode === 500 ? "INTERNAL_ERROR" : `HTTP_${statusCode}`),
                         message: statusCode === 500 ? "An internal error occurred" : err.message,
                     },
                     metadata: {
@@ -109,6 +112,26 @@ export class KoaServerAdapter extends BaseServerAdapter {
                 jsonLimit: this.config.bodyParser.jsonLimit,
                 enableTypes: ["json", "form", "text"],
             }));
+            // Uploads (multipart, octet-stream, audio/*) reach the route as bytes.
+            const rawLimit = parseByteLimit(this.config.bodyParser.maxSize);
+            this.app.use(async (ctx, next) => {
+                if (isRawBodyContentType(ctx.get("content-type"))) {
+                    try {
+                        ctx.request.body = await readRawBody(ctx.req, rawLimit);
+                    }
+                    catch (error) {
+                        if (error instanceof RawBodyTooLargeError) {
+                            ctx.status = 413;
+                            ctx.body = {
+                                error: { code: "PAYLOAD_TOO_LARGE", message: error.message },
+                            };
+                            return;
+                        }
+                        throw error;
+                    }
+                }
+                await next();
+            });
         }
         // Rate limiting middleware
         if (this.config.rateLimit.enabled) {
@@ -130,6 +153,7 @@ export class KoaServerAdapter extends BaseServerAdapter {
                 });
             });
         }
+        this.app.use((ctx, next) => this.runRegisteredMiddleware(ctx, next));
         // Mount router
         this.app.use(this.router.routes());
         this.app.use(this.router.allowedMethods());
@@ -251,6 +275,25 @@ export class KoaServerAdapter extends BaseServerAdapter {
             // Execute handler
             const result = await route.handler(serverCtx);
             const duration = Date.now() - startTime;
+            // A route that answers in its own wire format returns a web Response.
+            if (isWebResponse(result)) {
+                const raw = await readWebResponse(result);
+                this.emit("response", {
+                    requestId,
+                    statusCode: raw.status,
+                    duration,
+                    timestamp: new Date(),
+                });
+                for (const [key, value] of Object.entries({
+                    ...serverCtx.responseHeaders,
+                    ...raw.headers,
+                })) {
+                    ctx.set(key, value);
+                }
+                ctx.status = raw.status;
+                ctx.body = raw.body;
+                return;
+            }
             // Check if result is an error response
             if (isErrorResponse(result)) {
                 const statusCode = result.httpStatus ?? 500;
@@ -349,7 +392,7 @@ export class KoaServerAdapter extends BaseServerAdapter {
      * Register middleware with Koa
      */
     registerFrameworkMiddleware(middleware) {
-        this.app.use(async (ctx, next) => {
+        this.registeredMiddleware.push(async (ctx, next) => {
             // Skip excluded paths
             if (middleware.excludePaths?.some((p) => ctx.path.startsWith(p))) {
                 return next();
@@ -390,6 +433,21 @@ export class KoaServerAdapter extends BaseServerAdapter {
             }
         });
     }
+    /**
+     * Run registered middleware in registration order, then continue to the
+     * router. Reads the list per request, so later registrations apply too.
+     */
+    runRegisteredMiddleware(ctx, next) {
+        const dispatch = async (index) => {
+            const middleware = this.registeredMiddleware[index];
+            if (!middleware) {
+                await next();
+                return;
+            }
+            await middleware(ctx, () => dispatch(index + 1));
+        };
+        return dispatch(0);
+    }
     /**
      * Start the Koa server
      */
@@ -517,4 +575,7 @@ export class KoaServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        return this.server;
+    }
 }

package/dist/server/index.d.ts

@@ -38,9 +38,10 @@ export { createMCPBodyAttachmentMiddleware, fastifyMCPBodyHook, } from "./middle
 export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, } from "./middleware/rateLimit.js";
 export { CommonSchemas, createFieldValidator, createRequestValidationMiddleware, ValidationError, } from "./middleware/validation.js";
 export { AgentExecuteRequestSchema as OpenAPIAgentExecuteRequestSchema, AgentExecuteResponseSchema, AgentInputSchema, ApiKeySecurityScheme, BasicSecurityScheme, BearerSecurityScheme, CommonParameters, ConversationMessageSchema, createApiInfo, createDeleteOperation, createErrorResponse as createOpenAPIErrorResponse, createGetOperation, createHeaderParameter, createOpenAPIGenerator, createPathParameter, createPostOperation, createQueryParameter, createServer as createOpenAPIServer, createStreamingPostOperation, createStreamingResponse, createSuccessResponse, DefaultServers, ErrorResponseSchema, generateOpenAPIFromConfig, generateOpenAPISpec, HealthResponseSchema, MCPServerStatusSchema, MCPServersListResponseSchema, MCPServerToolSchema, MetricsResponseSchema, NeuroLinkApiInfo, OpenAPIGenerator, OpenAPISchemas, ProviderInfoSchema, ReadyResponseSchema, SessionSchema, SessionsListResponseSchema, StandardErrorResponses, StandardTags, TokenUsageSchema, ToolCallSchema, ToolDefinitionSchema, ToolExecuteRequestSchema as OpenAPIToolExecuteRequestSchema, ToolExecuteResponseSchema, ToolListResponseSchema, ToolParameterSchema, } from "./openapi/index.js";
-export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, registerAllRoutes, createClaudeProxyRoutes, createOpenAIProxyRoutes, createCodexProxyRoutes, createGeminiProxyRoutes, } from "./routes/index.js";
+export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, createTranscribeRoutes, registerAllRoutes, createClaudeProxyRoutes, createOpenAIProxyRoutes, createCodexProxyRoutes, createGeminiProxyRoutes, } from "./routes/index.js";
 export { BaseDataStreamWriter, createDataStreamResponse, createDataStreamWriter, createNDJSONHeaders, createSSEHeaders, DataStreamResponse, formatSSEEvent, pipeAsyncIterableToDataStream, WebStreamWriter, } from "./streaming/index.js";
 export { ErrorCategory, ErrorSeverity, ServerAdapterErrorCode, } from "../types/index.js";
 export { createStreamRedactor, redactStreamChunk } from "./utils/redaction.js";
-export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
+export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, TranscribeConfigSchema, TranscribeRequestSchema, TranscribeStreamConfigSchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
 export { createAgentWebSocketHandler, WebSocketConnectionManager, WebSocketMessageRouter, } from "./websocket/index.js";
+export { attachTranscribeWebSocket } from "./websocket/transcribeWebSocket.js";

package/dist/server/index.js

@@ -93,7 +93,7 @@ OpenAPIGenerator, OpenAPISchemas, ProviderInfoSchema, ReadyResponseSchema, Sessi
 // ============================================
 // Routes
 // ============================================
-export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, registerAllRoutes, 
+export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, createTranscribeRoutes, registerAllRoutes, 
 // The proxy doors. All were reachable only from the deep path
 // ./routes/index.js, which is not a package export — so a consumer of
 // "@juspay/neurolink/server" could reach them only indirectly through
@@ -120,8 +120,9 @@ export { createStreamRedactor, redactStreamChunk } from "./utils/redaction.js";
 // ============================================
 // Validation Utilities
 // ============================================
-export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
+export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, TranscribeConfigSchema, TranscribeRequestSchema, TranscribeStreamConfigSchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
 // ============================================
 // WebSocket
 // ============================================
 export { createAgentWebSocketHandler, WebSocketConnectionManager, WebSocketMessageRouter, } from "./websocket/index.js";
+export { attachTranscribeWebSocket } from "./websocket/transcribeWebSocket.js";

package/dist/server/routes/index.d.ts

@@ -13,6 +13,7 @@ export { createMCPRoutes } from "./mcpRoutes.js";
 export { createMemoryRoutes } from "./memoryRoutes.js";
 export { createOpenApiRoutes } from "./openApiRoutes.js";
 export { createToolRoutes } from "./toolRoutes.js";
+export { createTranscribeRoutes } from "./transcribeRoutes.js";
 /**
  * Create all standard routes
  * Convenience method that combines all route groups

package/dist/server/routes/index.js

@@ -13,6 +13,7 @@ import { createMCPRoutes } from "./mcpRoutes.js";
 import { createMemoryRoutes } from "./memoryRoutes.js";
 import { createOpenApiRoutes } from "./openApiRoutes.js";
 import { createToolRoutes } from "./toolRoutes.js";
+import { createTranscribeRoutes } from "./transcribeRoutes.js";
 // Re-export route builders from individual files
 export { createAgentRoutes } from "./agentRoutes.js";
 export { createClaudeProxyRoutes } from "./claudeProxyRoutes.js";
@@ -25,6 +26,7 @@ export { createMCPRoutes } from "./mcpRoutes.js";
 export { createMemoryRoutes } from "./memoryRoutes.js";
 export { createOpenApiRoutes } from "./openApiRoutes.js";
 export { createToolRoutes } from "./toolRoutes.js";
+export { createTranscribeRoutes } from "./transcribeRoutes.js";
 /**
  * Create all standard routes
  * Convenience method that combines all route groups
@@ -44,6 +46,7 @@ export function createAllRoutes(basePath = "/api", options) {
         createMCPRoutes(basePath),
         createMemoryRoutes(basePath),
         createHealthRoutes(basePath),
+        createTranscribeRoutes(basePath, options?.transcribe),
     ];
     // Conditionally add OpenAPI/Swagger routes
     if (options?.enableSwagger) {

package/dist/server/routes/transcribeRoutes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Transcribe Routes
+ *
+ * - `POST <basePath>/agent/transcribe` — JSON in (`audio` base64, `audioUrl`
+ *   or an allow-listed `audioPath`), `TranscribeResult` out, in the adapters'
+ *   usual `{ data, metadata }` envelope.
+ * - `POST /v1/audio/transcriptions` — OpenAI-compatible: `multipart/form-data`
+ *   in, OpenAI's `json` / `verbose_json` / `text` out (no envelope), with
+ *   NeuroLink's extras on `verbose_json`.
+ *
+ * Both call `neurolink.transcribe()`. Neither accepts credentials: engines use
+ * the server's own configuration.
+ */
+import type { RouteGroup, ServerTranscribeRouteOptions } from "../../types/index.js";
+/**
+ * Create the transcription routes.
+ *
+ * @param basePath - Prefix of the NeuroLink route (default `/api`).
+ * @param options - `allowedAudioRoots` (default: `audioPath` refused),
+ *   `maxAudioBytes` (default 50 MB) and `openaiBasePath` (default `""`, so the
+ *   OpenAI-compatible route is `/v1/audio/transcriptions`).
+ */
+export declare function createTranscribeRoutes(basePath?: string, options?: ServerTranscribeRouteOptions): RouteGroup;