@juspay/neurolink 12.48.2 → 12.49.1

package/dist/server/utils/rawBody.js

@@ -0,0 +1,76 @@
+/**
+ * Raw request bodies and raw responses for the server adapters.
+ *
+ * The adapters parse JSON (and url-encoded forms) into `ctx.body`. Routes that
+ * take uploads — `POST /v1/audio/transcriptions` takes `multipart/form-data`
+ * the way OpenAI's API does — need the bytes instead, so for the content types
+ * below every adapter hands the route the unparsed body as a `Buffer`, bounded
+ * by `bodyParser.maxSize`. A route that must answer in a wire format other than
+ * the adapters' `{ data, metadata }` envelope (an OpenAI-compatible route, a
+ * plain-text response) returns a web `Response`, which every adapter sends as is.
+ *
+ * @module server/utils/rawBody
+ */
+/** Content types whose body reaches the route as a `Buffer`. */
+const RAW_BODY_CONTENT_TYPE = /^\s*(multipart\/form-data|application\/octet-stream|audio\/[\w.+-]+)\s*(;|$)/i;
+/** `true` for a content type whose body the adapters pass through unparsed. */
+export function isRawBodyContentType(contentType) {
+    return (typeof contentType === "string" && RAW_BODY_CONTENT_TYPE.test(contentType));
+}
+/** "10mb" / "512kb" / "1gb" / a byte count → bytes. Falls back to 10 MB. */
+export function parseByteLimit(limit) {
+    if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
+        return limit;
+    }
+    const match = typeof limit === "string"
+        ? limit.trim().match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i)
+        : null;
+    if (!match) {
+        return 10 * 1024 * 1024;
+    }
+    const units = {
+        b: 1,
+        kb: 1024,
+        mb: 1024 * 1024,
+        gb: 1024 * 1024 * 1024,
+    };
+    return Math.floor(Number(match[1]) * units[(match[2] ?? "b").toLowerCase()]);
+}
+/** Thrown when a raw body grows past the adapter's `maxSize`. */
+export class RawBodyTooLargeError extends Error {
+    status = 413;
+    constructor(limit) {
+        super(`Request body exceeds the server's ${limit}-byte limit`);
+        this.name = "RawBodyTooLargeError";
+    }
+}
+/** Read a Node request stream into one `Buffer`, refusing more than `maxBytes`. */
+export async function readRawBody(stream, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        total += buffer.length;
+        if (total > maxBytes) {
+            throw new RawBodyTooLargeError(maxBytes);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+/** A web `Response` returned by a route handler. */
+export function isWebResponse(value) {
+    return typeof Response !== "undefined" && value instanceof Response;
+}
+/** Status, headers and body bytes of a web `Response`, for adapters that write to a Node response. */
+export async function readWebResponse(response) {
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    return {
+        status: response.status,
+        headers,
+        body: Buffer.from(await response.arrayBuffer()),
+    };
+}

package/dist/server/utils/validation.d.ts

@@ -165,6 +165,198 @@ export declare const SkillUpdateRequestSchema: z.ZodObject<{
     scopeIds: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     requestedBy: z.ZodOptional<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * One dictionary entry for transcription: correct spelling, mis-hearings, meaning.
+ */
+export declare const TranscribeDictionaryEntrySchema: z.ZodObject<{
+    term: z.ZodString;
+    heardAs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    meaning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Engine and correction settings shared by `POST /agent/transcribe`, the
+ * OpenAI-compatible route's extension fields and the transcribe WebSocket's
+ * config frame. Unknown keys (including `credentials`) are stripped: a caller
+ * cannot swap in its own key or point an engine at another host.
+ */
+export declare const TranscribeConfigSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    dictionary: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        term: z.ZodString;
+        heardAs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        meaning: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    correction: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        guard: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            decide: "decide";
+        }>>;
+        decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
+        transliterate: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            latin: "latin";
+        }>>;
+        punctuate: z.ZodOptional<z.ZodBoolean>;
+        secondOpinion: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        context: z.ZodOptional<z.ZodString>;
+        maxDropRatio: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    fallback: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            error: "error";
+            empty: "empty";
+            unsure: "unsure";
+        }>>>;
+    }, z.core.$strip>>;
+    diarization: z.ZodOptional<z.ZodBoolean>;
+    wordTimestamps: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * `POST /agent/transcribe` body: the config plus exactly one audio source.
+ */
+export declare const TranscribeRequestSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    dictionary: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        term: z.ZodString;
+        heardAs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        meaning: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    correction: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        guard: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            decide: "decide";
+        }>>;
+        decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
+        transliterate: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            latin: "latin";
+        }>>;
+        punctuate: z.ZodOptional<z.ZodBoolean>;
+        secondOpinion: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        context: z.ZodOptional<z.ZodString>;
+        maxDropRatio: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    fallback: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            error: "error";
+            empty: "empty";
+            unsure: "unsure";
+        }>>>;
+    }, z.core.$strip>>;
+    diarization: z.ZodOptional<z.ZodBoolean>;
+    wordTimestamps: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    audio: z.ZodOptional<z.ZodString>;
+    audioUrl: z.ZodOptional<z.ZodString>;
+    audioPath: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<{
+        mp3: "mp3";
+        wav: "wav";
+        ogg: "ogg";
+        opus: "opus";
+        m4a: "m4a";
+        flac: "flac";
+        webm: "webm";
+        mp4: "mp4";
+        mpeg: "mpeg";
+        mpga: "mpga";
+        pcm16: "pcm16";
+    }>>;
+}, z.core.$strip>;
+/**
+ * The transcribe WebSocket's first text frame: the config plus streaming tuning.
+ */
+export declare const TranscribeStreamConfigSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    dictionary: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        term: z.ZodString;
+        heardAs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        meaning: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    correction: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        guard: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            decide: "decide";
+        }>>;
+        decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+            provider: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
+        transliterate: z.ZodOptional<z.ZodEnum<{
+            native: "native";
+            latin: "latin";
+        }>>;
+        punctuate: z.ZodOptional<z.ZodBoolean>;
+        secondOpinion: z.ZodOptional<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        context: z.ZodOptional<z.ZodString>;
+        maxDropRatio: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    fallback: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodOptional<z.ZodString>;
+        when: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            error: "error";
+            empty: "empty";
+            unsure: "unsure";
+        }>>>;
+    }, z.core.$strip>>;
+    diarization: z.ZodOptional<z.ZodBoolean>;
+    wordTimestamps: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    streaming: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            native: "native";
+            chunked: "chunked";
+        }>>;
+        sampleRate: z.ZodOptional<z.ZodNumber>;
+        endSilenceMs: z.ZodOptional<z.ZodNumber>;
+        intervalMs: z.ZodOptional<z.ZodNumber>;
+        softCutSeconds: z.ZodOptional<z.ZodNumber>;
+        maxUtteranceSeconds: z.ZodOptional<z.ZodNumber>;
+        onsetRms: z.ZodOptional<z.ZodNumber>;
+        prerollMs: z.ZodOptional<z.ZodNumber>;
+        minSpeechMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 /**
  * Type guard to check if a value is an ErrorResponse
  */

package/dist/server/utils/validation.js

@@ -171,6 +171,106 @@ export const SkillCreateRequestSchema = z.object({
  * Skill update request schema — all fields optional (patch semantics)
  */
 export const SkillUpdateRequestSchema = SkillCreateRequestSchema.partial();
+/**
+ * One dictionary entry for transcription: correct spelling, mis-hearings, meaning.
+ */
+export const TranscribeDictionaryEntrySchema = z.object({
+    term: z.string().trim().min(1, "term is required"),
+    heardAs: z.array(z.string()).max(64).optional(),
+    meaning: z.string().max(2000).optional(),
+});
+const sttProviderName = z.string().min(1).max(100);
+/**
+ * Engine and correction settings shared by `POST /agent/transcribe`, the
+ * OpenAI-compatible route's extension fields and the transcribe WebSocket's
+ * config frame. Unknown keys (including `credentials`) are stripped: a caller
+ * cannot swap in its own key or point an engine at another host.
+ */
+export const TranscribeConfigSchema = z.object({
+    provider: sttProviderName.optional(),
+    model: z.string().min(1).max(200).optional(),
+    language: z.string().min(1).max(35).optional(),
+    prompt: z.string().max(4000).optional(),
+    dictionary: z.array(TranscribeDictionaryEntrySchema).max(500).optional(),
+    correction: z
+        .object({
+        enabled: z.boolean().optional(),
+        guard: z.enum(["decide", "none"]).optional(),
+        decideTimeoutMs: z.number().int().positive().max(60_000).optional(),
+        rewrite: z
+            .union([
+            z.literal(false),
+            z.object({
+                provider: z.string().min(1).max(100).optional(),
+                model: z.string().min(1).max(200).optional(),
+                timeoutMs: z.number().int().positive().max(120_000).optional(),
+            }),
+        ])
+            .optional(),
+        transliterate: z.enum(["latin", "native"]).optional(),
+        punctuate: z.boolean().optional(),
+        secondOpinion: z
+            .object({
+            provider: sttProviderName,
+            model: z.string().min(1).max(200).optional(),
+        })
+            .optional(),
+        context: z.string().max(1000).optional(),
+        maxDropRatio: z.number().min(0).max(1).optional(),
+    })
+        .optional(),
+    fallback: z
+        .object({
+        provider: sttProviderName,
+        model: z.string().min(1).max(200).optional(),
+        when: z.array(z.enum(["unsure", "empty", "error"])).optional(),
+    })
+        .optional(),
+    diarization: z.boolean().optional(),
+    wordTimestamps: z.boolean().optional(),
+    timeoutMs: z.number().int().positive().max(600_000).optional(),
+});
+/**
+ * `POST /agent/transcribe` body: the config plus exactly one audio source.
+ */
+export const TranscribeRequestSchema = TranscribeConfigSchema.extend({
+    audio: z.string().min(1).optional(),
+    audioUrl: z.string().url().optional(),
+    audioPath: z.string().min(1).optional(),
+    format: z
+        .enum([
+        "mp3",
+        "wav",
+        "ogg",
+        "opus",
+        "m4a",
+        "flac",
+        "webm",
+        "mp4",
+        "mpeg",
+        "mpga",
+        "pcm16",
+    ])
+        .optional(),
+}).refine((body) => [body.audio, body.audioUrl, body.audioPath].filter((source) => source !== undefined).length === 1, { message: "Pass exactly one of audio, audioUrl or audioPath" });
+/**
+ * The transcribe WebSocket's first text frame: the config plus streaming tuning.
+ */
+export const TranscribeStreamConfigSchema = TranscribeConfigSchema.extend({
+    streaming: z
+        .object({
+        mode: z.enum(["auto", "native", "chunked"]).optional(),
+        sampleRate: z.number().int().min(8000).max(48000).optional(),
+        endSilenceMs: z.number().positive().optional(),
+        intervalMs: z.number().positive().optional(),
+        softCutSeconds: z.number().positive().optional(),
+        maxUtteranceSeconds: z.number().positive().optional(),
+        onsetRms: z.number().positive().optional(),
+        prerollMs: z.number().nonnegative().optional(),
+        minSpeechMs: z.number().nonnegative().optional(),
+    })
+        .optional(),
+});
 // ============================================
 // Error Response Type Guards / Helpers
 // ============================================

package/dist/server/websocket/transcribeWebSocket.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Transcribe WebSocket — `transcribeStream()` over a socket.
+ *
+ * Protocol (one transcription per connection):
+ * 1. The client's first frame is TEXT: a JSON config with the fields of
+ *    `POST /agent/transcribe` minus the audio (`provider`, `model`,
+ *    `language`, `dictionary`, `correction`, `fallback`, `streaming` …).
+ * 2. Then BINARY frames of PCM16LE mono audio at `streaming.sampleRate`
+ *    (default 16000).
+ * 3. A TEXT frame `{"type":"end"}` (or closing the socket) ends the audio; the
+ *    server flushes the last utterance.
+ *
+ * The server sends one TEXT frame per `TranscribeStreamEvent` (JSON), then
+ * closes with 1000. A bad config is answered with an `error` event and close
+ * code 1008.
+ *
+ * The route adapters do not handle upgrades, so this attaches to the Node
+ * `http.Server` the caller owns, next to whatever else is listening there; it
+ * answers only upgrades on its own path.
+ *
+ * @module server/websocket/transcribeWebSocket
+ */
+import type { Server as HttpServer } from "node:http";
+import type { NeuroLink } from "../../neurolink.js";
+import type { ServerTranscribeWebSocketOptions } from "../../types/index.js";
+/**
+ * Serve `transcribeStream()` on `path` (default
+ * `/v1/audio/transcriptions/stream`) of an existing HTTP server.
+ *
+ * @example
+ * ```typescript
+ * const server = http.createServer(app);
+ * const ws = await attachTranscribeWebSocket(server, neurolink, {
+ *   authToken: process.env.NEUROLINK_SERVER_API_KEY?.split(","),
+ * });
+ * server.listen(3000);
+ * // later: ws.close();
+ * ```
+ */
+export declare function attachTranscribeWebSocket(server: HttpServer, neurolink: NeuroLink, options?: ServerTranscribeWebSocketOptions): Promise<{
+    close: () => void;
+}>;

package/dist/server/websocket/transcribeWebSocket.js

@@ -0,0 +1,264 @@
+/**
+ * Transcribe WebSocket — `transcribeStream()` over a socket.
+ *
+ * Protocol (one transcription per connection):
+ * 1. The client's first frame is TEXT: a JSON config with the fields of
+ *    `POST /agent/transcribe` minus the audio (`provider`, `model`,
+ *    `language`, `dictionary`, `correction`, `fallback`, `streaming` …).
+ * 2. Then BINARY frames of PCM16LE mono audio at `streaming.sampleRate`
+ *    (default 16000).
+ * 3. A TEXT frame `{"type":"end"}` (or closing the socket) ends the audio; the
+ *    server flushes the last utterance.
+ *
+ * The server sends one TEXT frame per `TranscribeStreamEvent` (JSON), then
+ * closes with 1000. A bad config is answered with an `error` event and close
+ * code 1008.
+ *
+ * The route adapters do not handle upgrades, so this attaches to the Node
+ * `http.Server` the caller owns, next to whatever else is listening there; it
+ * answers only upgrades on its own path.
+ *
+ * @module server/websocket/transcribeWebSocket
+ */
+import { logger } from "../../utils/logger.js";
+import { timingSafeEqualString } from "../voice/tokenCompare.js";
+import { TranscribeStreamConfigSchema } from "../utils/validation.js";
+const DEFAULT_PATH = "/v1/audio/transcriptions/stream";
+/** Audio waiting for the engine beyond this (about 8.5 min at 16 kHz) closes the socket. */
+const MAX_QUEUED_BYTES = 16 * 1024 * 1024;
+/** Push-driven async iterable: socket frames in, `transcribeStream()` pulls. */
+class FrameQueue {
+    frames = [];
+    waiting;
+    ended = false;
+    queuedBytes = 0;
+    push(frame) {
+        if (this.ended) {
+            return;
+        }
+        if (this.waiting) {
+            const resolve = this.waiting;
+            this.waiting = undefined;
+            resolve({ value: frame, done: false });
+            return;
+        }
+        this.frames.push(frame);
+        this.queuedBytes += frame.length;
+    }
+    end() {
+        this.ended = true;
+        if (this.waiting) {
+            const resolve = this.waiting;
+            this.waiting = undefined;
+            resolve({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const frame = this.frames.shift();
+                if (frame) {
+                    this.queuedBytes -= frame.length;
+                    return Promise.resolve({ value: frame, done: false });
+                }
+                if (this.ended) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.waiting = resolve;
+                });
+            },
+            return: () => {
+                this.end();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}
+/**
+ * `true` when the upgrade's `Origin` is on the allow-list, the list allows
+ * any origin, or the request carries no `Origin` (not a browser).
+ */
+function isOriginAllowed(req, allowed) {
+    if (!allowed || allowed.includes("*")) {
+        return true;
+    }
+    const origin = req.headers.origin;
+    if (typeof origin !== "string" || origin.length === 0) {
+        return true;
+    }
+    const wanted = origin.trim().toLowerCase();
+    return allowed.some((o) => o.trim().toLowerCase() === wanted);
+}
+function isAuthorized(req, token) {
+    const tokens = (typeof token === "string" ? [token] : (token ?? [])).filter((t) => t.length > 0);
+    if (tokens.length === 0) {
+        return true;
+    }
+    const header = req.headers.authorization;
+    const headerToken = typeof header === "string" && header.startsWith("Bearer ")
+        ? header.slice(7)
+        : undefined;
+    let urlToken;
+    try {
+        urlToken =
+            new URL(req.url ?? "/", "http://localhost").searchParams.get("token") ??
+                undefined;
+    }
+    catch {
+        urlToken = undefined;
+    }
+    const provided = headerToken ?? urlToken;
+    return (provided !== undefined &&
+        tokens.some((t) => timingSafeEqualString(provided, t)));
+}
+function pathOf(req) {
+    try {
+        return new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Serve `transcribeStream()` on `path` (default
+ * `/v1/audio/transcriptions/stream`) of an existing HTTP server.
+ *
+ * @example
+ * ```typescript
+ * const server = http.createServer(app);
+ * const ws = await attachTranscribeWebSocket(server, neurolink, {
+ *   authToken: process.env.NEUROLINK_SERVER_API_KEY?.split(","),
+ * });
+ * server.listen(3000);
+ * // later: ws.close();
+ * ```
+ */
+export async function attachTranscribeWebSocket(server, neurolink, options = {}) {
+    // Loaded on use so `ws` stays off the package's static import graph.
+    const { WebSocketServer, WebSocket } = await import("ws");
+    const path = options.path ?? DEFAULT_PATH;
+    const wss = new WebSocketServer({
+        noServer: true,
+        maxPayload: options.maxPayload ?? 1_048_576,
+    });
+    const onUpgrade = (req, socket, head) => {
+        if (pathOf(req) !== path) {
+            return; // Someone else's upgrade.
+        }
+        if (!isOriginAllowed(req, options.allowedOrigins)) {
+            socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (!isAuthorized(req, options.authToken)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (client) => {
+            wss.emit("connection", client, req);
+        });
+    };
+    server.on("upgrade", onUpgrade);
+    wss.on("connection", (client) => {
+        const queue = new FrameQueue();
+        let started = false;
+        const send = (event) => {
+            if (client.readyState !== WebSocket.OPEN) {
+                return false;
+            }
+            client.send(JSON.stringify(event));
+            return true;
+        };
+        const run = async (config) => {
+            try {
+                for await (const event of neurolink.transcribeStream({
+                    ...config,
+                    audio: queue,
+                })) {
+                    if (!send(event)) {
+                        break; // The client is gone; stop pulling.
+                    }
+                }
+                if (client.readyState === WebSocket.OPEN) {
+                    client.close(1000, "done");
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.warn("[TranscribeWebSocket] stream failed", { error: message });
+                send({ type: "error", message, recoverable: false });
+                if (client.readyState === WebSocket.OPEN) {
+                    client.close(1011, "transcription failed");
+                }
+            }
+        };
+        client.on("message", (data, isBinary) => {
+            const frame = Buffer.isBuffer(data)
+                ? data
+                : Array.isArray(data)
+                    ? Buffer.concat(data)
+                    : Buffer.from(data);
+            if (!started) {
+                if (isBinary) {
+                    send({
+                        type: "error",
+                        message: "The first frame must be a JSON config (text), before any audio",
+                        recoverable: false,
+                    });
+                    client.close(1008, "config first");
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(frame.toString("utf-8"));
+                }
+                catch {
+                    parsed = undefined;
+                }
+                const config = TranscribeStreamConfigSchema.safeParse(parsed);
+                if (!config.success) {
+                    send({
+                        type: "error",
+                        message: `Invalid config: ${config.error.issues
+                            .map((issue) => `${issue.path.join(".") || "config"} ${issue.message}`)
+                            .join("; ")}`,
+                        recoverable: false,
+                    });
+                    client.close(1008, "invalid config");
+                    return;
+                }
+                started = true;
+                void run(config.data);
+                return;
+            }
+            if (isBinary) {
+                queue.push(frame);
+                if (queue.queuedBytes > MAX_QUEUED_BYTES) {
+                    send({
+                        type: "error",
+                        message: "Audio is arriving faster than it can be transcribed",
+                        recoverable: false,
+                    });
+                    queue.end();
+                    client.close(1009, "backlog");
+                }
+                return;
+            }
+            // Any text frame after the config ends the audio ({"type":"end"}).
+            queue.end();
+        });
+        client.on("close", () => queue.end());
+        client.on("error", () => queue.end());
+    });
+    return {
+        close: () => {
+            server.off("upgrade", onUpgrade);
+            for (const client of wss.clients) {
+                client.terminate();
+            }
+            wss.close();
+        },
+    };
+}