@juspay/neurolink 12.48.1 → 12.49.0

package/dist/cli/commands/serve.d.ts

@@ -9,9 +9,6 @@
  *   neurolink serve status
  */
 import type { CommandModule } from "yargs";
-/**
- * Serve CLI command factory
- */
 export declare class ServeCommandFactory {
     /**
      * Create the main serve command
@@ -36,6 +33,11 @@ export declare class ServeCommandFactory {
      * Returns a mutable reference wrapper so signal handlers always access the current server.
      */
     private static createAndStartServer;
+    /**
+     * Put every route except health behind the API key(s) in
+     * NEUROLINK_SERVER_API_KEY. Must run before the routes are registered.
+     */
+    private static applyApiKeyAuth;
     /**
      * Save server state and print the startup info banner.
      */

package/dist/cli/commands/serve.js

@@ -16,7 +16,7 @@ import { NeuroLink } from "../../neurolink.js";
 import { ConfigurationError, ServerStartError, } from "../../server/errors.js";
 import { withTimeout } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
-import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
+import { clearStateOnExit, createServerApiKeyMiddleware, formatUptime, isOtherServerRunning, isProcessRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, StateFileManager, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -134,6 +134,50 @@ function createFileWatcher(onRestart, quiet) {
 /**
  * Serve CLI command factory
  */
+/** A Node `http.Server` (or `https.Server`): it can take an `upgrade` listener. */
+function isNodeHttpServer(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.on === "function" &&
+        typeof value.listen === "function");
+}
+/**
+ * Live transcription streams over a WebSocket upgrade, which the HTTP
+ * adapters cannot route; it attaches to the Node server once it listens, on
+ * the first start and on every watch-mode restart. Bun and Deno serve
+ * without one, and then the route is simply absent. Guarded by the same
+ * NEUROLINK_SERVER_API_KEY(s) as the HTTP routes.
+ */
+/** `--cors-origin` values, split on commas and trimmed; `undefined` when none were given. */
+function corsOriginsFromArgv(values) {
+    if (!values || values.length === 0) {
+        return undefined;
+    }
+    const origins = values
+        .flatMap((value) => String(value).split(","))
+        .map((origin) => origin.trim())
+        .filter((origin) => origin.length > 0);
+    return origins.length > 0 ? origins : undefined;
+}
+async function attachTranscriptionWebSocket(server, neurolink, serverConfig) {
+    const native = server.getNativeServer?.();
+    if (!isNodeHttpServer(native)) {
+        return;
+    }
+    const { attachTranscribeWebSocket } = await import("../../server/websocket/transcribeWebSocket.js");
+    const apiKeys = readServerApiKeys();
+    // The same origin allow-list as the HTTP routes: with CORS on and a list
+    // that is not "*", a page from an unlisted origin cannot open the stream.
+    const origins = serverConfig.cors?.origins;
+    const allowedOrigins = serverConfig.cors?.enabled !== false && origins && !origins.includes("*")
+        ? origins
+        : undefined;
+    await attachTranscribeWebSocket(native, neurolink, {
+        ...(apiKeys.length > 0 ? { authToken: apiKeys } : {}),
+        ...(allowedOrigins ? { allowedOrigins } : {}),
+    });
+    logger.debug("[serve] transcription WebSocket attached at /v1/audio/transcriptions/stream");
+}
 export class ServeCommandFactory {
     /**
      * Create the main serve command
@@ -143,6 +187,8 @@ export class ServeCommandFactory {
             command: "serve [subcommand]",
             describe: "Start NeuroLink HTTP server with server adapters",
             builder: (yargs) => {
+                // The server options carry no yargs defaults: a default would always
+                // win over the --config file. Defaults are applied after merging.
                 return yargs
                     .command("status", "Show server status", (yargs) => ServeCommandFactory.buildStatusOptions(yargs), (argv) => ServeCommandFactory.executeStatus(argv))
                     .command("voice", "Start the real-time voice assistant server (OpenAI Realtime / Gemini Live)", (yargs) => yargs.option("port", {
@@ -157,43 +203,43 @@ export class ServeCommandFactory {
                     .option("port", {
                     type: "number",
                     alias: "p",
-                    default: 3000,
-                    description: "Port to listen on",
+                    description: "Port to listen on (default: config file, then $PORT, then 3000)",
                 })
                     .option("host", {
                     type: "string",
                     alias: "H",
-                    default: "0.0.0.0",
-                    description: "Host to bind to",
+                    description: "Host to bind to (default: 0.0.0.0)",
                 })
                     .option("framework", {
                     type: "string",
                     alias: "f",
                     choices: ["hono", "express", "fastify", "koa"],
-                    default: "hono",
-                    description: "Web framework to use (hono recommended)",
+                    description: "Web framework to use (default: hono, recommended)",
                 })
                     .option("basePath", {
                     type: "string",
                     alias: "b",
-                    default: "/api",
-                    description: "Base path for all routes",
+                    description: "Base path for all routes (default: /api)",
                 })
                     .option("cors", {
                     type: "boolean",
-                    default: true,
-                    description: "Enable CORS middleware",
+                    description: "Enable CORS middleware (default: true)",
+                })
+                    .option("cors-origin", {
+                    type: "array",
+                    string: true,
+                    alias: "corsOrigin",
+                    description: "Browser origin allowed by CORS (repeat or comma-separate; '*' for any). " +
+                        "Default: none, so no web page can call the server cross-origin",
                 })
                     .option("rate-limit", {
                     type: "number",
                     alias: "rateLimit",
-                    default: 100,
-                    description: "Rate limit (requests per 15 min window, 0 to disable)",
+                    description: "Rate limit (requests per 15 min window, 0 to disable; default: 100)",
                 })
                     .option("swagger", {
                     type: "boolean",
-                    default: false,
-                    description: "Enable OpenAPI/Swagger documentation",
+                    description: "Enable OpenAPI/Swagger documentation (default: false)",
                 })
                     .option("config", {
                     type: "string",
@@ -224,6 +270,7 @@ export class ServeCommandFactory {
                     .example("neurolink serve --cors --rate-limit 50", "Start server with CORS and rate limiting (50 req/15min)")
                     .example("neurolink serve --swagger", "Start server with OpenAPI documentation enabled")
                     .example("neurolink serve --watch", "Start server in watch mode (restart on changes)")
+                    .example("NEUROLINK_SERVER_API_KEY=secret neurolink serve", "Require 'Authorization: Bearer secret' (or X-API-Key) on every route except health")
                     .example("neurolink serve status", "Show server status")
                     .help();
             },
@@ -266,7 +313,7 @@ export class ServeCommandFactory {
             // Load config file if provided
             const fileConfig = ServeCommandFactory.loadFileConfig(argv, spinner);
             // Merge CLI args with file config (CLI takes precedence)
-            const port = argv.port ?? fileConfig.port ?? 3000;
+            const port = resolveServerPort(argv.port, fileConfig.port);
             const host = argv.host ?? fileConfig.host ?? "0.0.0.0";
             const framework = argv.framework ?? fileConfig.framework ?? "hono";
             const basePath = argv.basePath ?? fileConfig.basePath ?? "/api";
@@ -307,7 +354,7 @@ export class ServeCommandFactory {
      */
     static guardAlreadyRunning(spinner) {
         const existingState = loadServeState();
-        if (existingState && isProcessRunning(existingState.pid)) {
+        if (existingState && isOtherServerRunning(existingState.pid)) {
             if (spinner) {
                 spinner.fail(chalk.red(`Server already running on port ${existingState.port} (PID: ${existingState.pid})`));
             }
@@ -355,6 +402,9 @@ export class ServeCommandFactory {
                 enabled: argv.cors !== undefined
                     ? argv.cors
                     : (fileConfig.cors?.enabled ?? defaultConfig.cors.enabled),
+                ...(corsOriginsFromArgv(argv.corsOrigin)
+                    ? { origins: corsOriginsFromArgv(argv.corsOrigin) }
+                    : {}),
             },
             rateLimit: {
                 ...defaultConfig.rateLimit,
@@ -370,7 +420,13 @@ export class ServeCommandFactory {
             },
             bodyParser: fileConfig.bodyParser,
             logging: fileConfig.logging,
-            timeout: fileConfig.timeout,
+            // Transcription of a long recording through a remote engine can take
+            // longer than the 30 s default, so the request timeout is also
+            // settable from the environment (milliseconds); the config file wins.
+            timeout: fileConfig.timeout ??
+                (Number(process.env.NEUROLINK_SERVER_TIMEOUT_MS) > 0
+                    ? Number(process.env.NEUROLINK_SERVER_TIMEOUT_MS)
+                    : undefined),
             enableMetrics: fileConfig.enableMetrics ?? true,
             enableSwagger: argv.swagger !== undefined
                 ? argv.swagger
@@ -391,14 +447,26 @@ export class ServeCommandFactory {
                 config: opts.serverConfig,
             }),
         };
+        ServeCommandFactory.applyApiKeyAuth(serverRef.current, opts.basePath);
         registerAllRoutes(serverRef.current, opts.basePath);
         if (spinner) {
             spinner.text = "Initializing server...";
         }
         await withTimeout(serverRef.current.initialize(), 30000, new ServerStartError("Server initialization timed out after 30 seconds", undefined, opts.port, opts.host));
         await withTimeout(serverRef.current.start(), 30000, new ServerStartError("Server startup timed out after 30 seconds", undefined, opts.port, opts.host));
+        await attachTranscriptionWebSocket(serverRef.current, neurolink, opts.serverConfig);
         return serverRef;
     }
+    /**
+     * Put every route except health behind the API key(s) in
+     * NEUROLINK_SERVER_API_KEY. Must run before the routes are registered.
+     */
+    static applyApiKeyAuth(server, basePath) {
+        const apiKeys = readServerApiKeys();
+        if (apiKeys.length > 0) {
+            server.registerMiddleware(createServerApiKeyMiddleware(apiKeys, basePath));
+        }
+    }
     /**
      * Save server state and print the startup info banner.
      */
@@ -413,11 +481,17 @@ export class ServeCommandFactory {
             configFile: opts.argv.config,
         };
         saveServeState(state);
+        clearStateOnExit(clearServeState);
         if (spinner) {
             spinner.succeed(chalk.green("NeuroLink server started successfully"));
         }
         const url = `http://${opts.host === "0.0.0.0" ? "localhost" : opts.host}:${opts.port}`;
         const corsEnabled = opts.argv.cors ?? opts.serverConfig.cors?.enabled ?? true;
+        // The origin list and the API key together decide whether any browser
+        // page may call this server; the banner says which case this is.
+        const corsOrigins = opts.serverConfig.cors?.origins ?? [];
+        const corsWildcard = corsEnabled && corsOrigins.includes("*");
+        const corsNoOrigins = corsEnabled && corsOrigins.length === 0;
         const rateLimitValue = opts.argv.rateLimit ?? opts.serverConfig.rateLimit?.maxRequests ?? 100;
         const rateLimitEnabled = rateLimitValue > 0;
         const swaggerEnabled = opts.argv.swagger ?? opts.serverConfig.enableSwagger ?? false;
@@ -428,10 +502,13 @@ export class ServeCommandFactory {
             pid: state.pid,
             configFile: opts.argv.config,
             corsEnabled,
+            corsWildcard,
+            corsNoOrigins,
             rateLimitEnabled,
             rateLimitValue,
             swaggerEnabled,
             watchEnabled: opts.argv.watch ?? false,
+            authEnabled: readServerApiKeys().length > 0,
         });
         return state;
     }
@@ -452,12 +529,22 @@ export class ServeCommandFactory {
         }
         logger.always("");
         logger.always(chalk.bold("Middleware:"));
-        logger.always(`  CORS:        ${info.corsEnabled ? chalk.green("enabled") : chalk.yellow("disabled")}`);
+        logger.always(`  CORS:        ${!info.corsEnabled
+            ? chalk.yellow("disabled")
+            : info.corsWildcard
+                ? info.authEnabled
+                    ? chalk.green("enabled (any origin; API key required)")
+                    : chalk.yellow("enabled for ANY origin and no API key — any web page can call this server; set " +
+                        SERVER_API_KEY_ENV)
+                : info.corsNoOrigins
+                    ? chalk.yellow("enabled, no origins listed — browsers cannot call this server; pass --cors-origin or set cors.origins")
+                    : chalk.green("enabled (listed origins)")}`);
         logger.always(`  Rate Limit:  ${info.rateLimitEnabled ? chalk.green(`enabled (${info.rateLimitValue} req/15min)`) : chalk.yellow("disabled")}`);
         logger.always(`  Swagger:     ${info.swaggerEnabled ? chalk.green("enabled") : chalk.yellow("disabled")}`);
         if (info.watchEnabled) {
             logger.always(`  Watch Mode:  ${chalk.green("enabled")}`);
         }
+        logger.always(`  API Key:     ${info.authEnabled ? chalk.green("required (health routes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
         logger.always("");
         logger.always(chalk.bold("Available Endpoints:"));
         logger.always(chalk.gray("  Health & Monitoring:"));
@@ -503,14 +590,20 @@ export class ServeCommandFactory {
                 const timestamp = Date.now();
                 const { createServer: createNewServer, registerAllRoutes: registerNewRoutes, } = await import(`../../server/index.js?t=${timestamp}`);
                 // Create new server
-                const newServer = await createNewServer(new NeuroLink(), {
+                const newNeurolink = new NeuroLink();
+                const newServer = await createNewServer(newNeurolink, {
                     framework: ctx.framework,
                     config: ctx.serverConfig,
                 });
+                ServeCommandFactory.applyApiKeyAuth(newServer, ctx.basePath);
                 registerNewRoutes(newServer, ctx.basePath);
                 // Initialize and start with timeouts
                 await withTimeout(newServer.initialize(), 30000, new ServerStartError("Server initialization timed out during restart", undefined, ctx.port, ctx.host));
                 await withTimeout(newServer.start(), 30000, new ServerStartError("Server startup timed out during restart", undefined, ctx.port, ctx.host));
+                // The upgrade handler lives on the old adapter's http.Server; the
+                // restarted one needs its own, or the stream route is gone after the
+                // first file change.
+                await attachTranscriptionWebSocket(newServer, newNeurolink, ctx.serverConfig);
                 // Update the reference so signal handlers use the new server instance
                 ctx.serverRef.current = newServer;
                 logger.always(chalk.green("Server restarted successfully"));

package/dist/cli/commands/server.js

@@ -9,7 +9,7 @@ import path from "path";
 import { logger } from "../../utils/logger.js";
 import { NeuroLink } from "../../neurolink.js";
 import { withTimeout } from "../../utils/errorHandling.js";
-import { isProcessRunning, formatUptime, ensureStateDir, getNeuroLinkDir, } from "../utils/serverUtils.js";
+import { isProcessRunning, formatUptime, ensureStateDir, getNeuroLinkDir, clearStateOnExit, createServerApiKeyMiddleware, isOtherServerRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -160,8 +160,7 @@ export class ServerCommandFactory {
             .option("port", {
             type: "number",
             alias: "p",
-            default: 3000,
-            description: "Port to listen on",
+            description: "Port to listen on (default: $PORT, then 3000)",
         })
             .option("host", {
             type: "string",
@@ -344,7 +343,7 @@ export class ServerCommandFactory {
         try {
             // Check if server is already running
             const existingState = loadServerState();
-            if (existingState && isProcessRunning(existingState.pid)) {
+            if (existingState && isOtherServerRunning(existingState.pid)) {
                 if (spinner) {
                     spinner.fail(chalk.red(`Server already running on port ${existingState.port} (PID: ${existingState.pid})`));
                 }
@@ -355,12 +354,13 @@ export class ServerCommandFactory {
             const neurolink = new NeuroLink();
             // Dynamically import server module
             const { createServer, registerAllRoutes } = await import("../../server/index.js");
+            const port = resolveServerPort(argv.port);
             const framework = (argv.framework ?? "hono");
             // Create server
             const server = await createServer(neurolink, {
                 framework,
                 config: {
-                    port: argv.port ?? 3000,
+                    port,
                     host: argv.host ?? "0.0.0.0",
                     basePath: argv.basePath ?? "/api",
                     cors: {
@@ -372,6 +372,11 @@ export class ServerCommandFactory {
                     disableBuiltInHealth: true, // We register health routes separately
                 },
             });
+            // API key (if configured) must be registered ahead of the routes it guards
+            const apiKeys = readServerApiKeys();
+            if (apiKeys.length > 0) {
+                server.registerMiddleware(createServerApiKeyMiddleware(apiKeys, argv.basePath ?? "/api"));
+            }
             // Register all routes
             registerAllRoutes(server, argv.basePath ?? "/api");
             // Initialize and start with timeout
@@ -380,13 +385,14 @@ export class ServerCommandFactory {
             // Save state
             const state = {
                 pid: process.pid,
-                port: argv.port ?? 3000,
+                port,
                 host: argv.host ?? "0.0.0.0",
                 framework,
                 startTime: new Date().toISOString(),
                 basePath: argv.basePath ?? "/api",
             };
             saveServerState(state);
+            clearStateOnExit(clearServerState);
             if (spinner) {
                 spinner.succeed(chalk.green("Server started successfully"));
             }
@@ -396,6 +402,7 @@ export class ServerCommandFactory {
             logger.always(`  Framework: ${chalk.cyan(framework)}`);
             logger.always(`  Base Path: ${chalk.cyan(state.basePath)}`);
             logger.always(`  PID: ${chalk.cyan(state.pid)}`);
+            logger.always(`  API Key: ${apiKeys.length > 0 ? chalk.green("required (health routes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
             logger.always(chalk.bold("\nAvailable Endpoints:"));
             logger.always(`  ${chalk.green("GET")}  ${state.basePath}/health`);
             logger.always(`  ${chalk.green("GET")}  ${state.basePath}/ready`);

package/dist/cli/commands/transcribe.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * NeuroLink CLI Transcribe Command
+ *
+ * Calls `NeuroLink.transcribe()` — audio in, text out — or, with `--stream`,
+ * `NeuroLink.transcribeStream()` over the file decoded to 16 kHz mono PCM16.
+ * See src/lib/types/transcribe.ts for the full vocabulary (dictionary,
+ * correction, second opinion, fallback).
+ *
+ * Credentials are env-only here, exactly as every other CLI command: each STT
+ * handler reads its own settings, and `NEUROLINK_STT_PROVIDER`,
+ * `NEUROLINK_STT_MODEL` and `NEUROLINK_STT_LANGUAGE` pick the defaults. With
+ * nothing configured the built-in local engine (Whistle) is used.
+ */
+import type { CommandModule } from "yargs";
+import type { CliTranscribeArgs } from "../../types/index.js";
+export declare const transcribeCommand: CommandModule<object, CliTranscribeArgs>;
+/**
+ * Create transcribe command factory for CLICommandFactory-style registration,
+ * matching the DecideCommandFactory pattern.
+ */
+export declare class TranscribeCommandFactory {
+    static createTranscribeCommand(): CommandModule;
+}