@juspay/neurolink 11.25.4 → 11.26.0

package/dist/utils/ttsProcessor.d.ts

@@ -6,7 +6,7 @@
  *
  * @module utils/ttsProcessor
  */
-import type { TTSOptions, TTSResult, TTSHandler } from "../types/index.js";
+import type { TTSChunk, TTSOptions, TTSResult, TTSHandler } from "../types/index.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { NeuroLinkError } from "./errorHandling.js";
 /**
@@ -20,6 +20,12 @@ export declare const TTS_ERROR_CODES: {
     readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
     readonly INVALID_INPUT: "TTS_INVALID_INPUT";
 };
+/** Internal signal raised after all buffered segments have been attempted. */
+export declare class IncrementalTTSSynthesisError extends Error {
+    readonly firstError: unknown;
+    readonly failedSegments: readonly number[];
+    constructor(firstError: unknown, failedSegments: number[]);
+}
 /**
  * TTS Error class for text-to-speech specific errors
  */
@@ -156,4 +162,17 @@ export declare class TTSProcessor {
      * ```
      */
     static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Incrementally synthesize sentence-buffered text chunks.
+     *
+     * Text is flushed at a sentence boundary after `streamingBufferSize`
+     * characters, or hard-split before the provider's maximum text length.
+     * Each segment goes through `synthesize()`, preserving the existing handler
+     * registry, validation, error normalization, and telemetry seam.
+     *
+     * The most recent successful audio chunk is held until another succeeds or
+     * the input ends, so exactly one real audio chunk carries `isFinal: true`
+     * without emitting a separate empty terminator chunk.
+     */
+    static synthesizeStream(textChunks: AsyncIterable<string>, provider: string, options: TTSOptions, shouldStop?: () => boolean): AsyncGenerator<TTSChunk>;
 }

package/dist/utils/ttsProcessor.js

@@ -22,6 +22,75 @@ export const TTS_ERROR_CODES = {
     SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED",
     INVALID_INPUT: "TTS_INVALID_INPUT",
 };
+const DEFAULT_STREAMING_BUFFER_SIZE = 120;
+const SENTENCE_BOUNDARY = /[.!?]+(?:["')\]]+)?(?=\s|$)/g;
+/** Internal signal raised after all buffered segments have been attempted. */
+export class IncrementalTTSSynthesisError extends Error {
+    firstError;
+    failedSegments;
+    constructor(firstError, failedSegments) {
+        super(`Incremental TTS failed for ${failedSegments.length} segment${failedSegments.length === 1 ? "" : "s"}`);
+        this.name = "IncrementalTTSSynthesisError";
+        this.firstError = firstError;
+        this.failedSegments = [...failedSegments];
+    }
+}
+function findSentenceEnds(text) {
+    const ends = [];
+    for (const match of text.matchAll(SENTENCE_BOUNDARY)) {
+        ends.push((match.index ?? 0) + match[0].length);
+    }
+    return ends;
+}
+const HIGH_SURROGATE_START = 0xd800;
+const HIGH_SURROGATE_END = 0xdbff;
+const LOW_SURROGATE_START = 0xdc00;
+const LOW_SURROGATE_END = 0xdfff;
+/**
+ * Move a split index off the middle of a surrogate pair.
+ *
+ * The cap is measured in UTF-16 code units, so a hard split can land between
+ * the two halves of an astral character (emoji, rarer CJK). That would end one
+ * segment with a lone high surrogate and start the next with its low half, and
+ * providers receive U+FFFD instead of the character. Backing the split off by
+ * one code unit keeps the pair whole in the next segment.
+ *
+ * A split at index 1 is left alone: backing off would yield an empty segment
+ * with an unchanged remainder, and a cap that small cannot hold the pair anyway.
+ */
+function avoidSurrogateSplit(text, splitAt) {
+    if (splitAt <= 1 || splitAt >= text.length) {
+        return splitAt;
+    }
+    const high = text.charCodeAt(splitAt - 1);
+    const low = text.charCodeAt(splitAt);
+    const splitsPair = high >= HIGH_SURROGATE_START &&
+        high <= HIGH_SURROGATE_END &&
+        low >= LOW_SURROGATE_START &&
+        low <= LOW_SURROGATE_END;
+    return splitsPair ? splitAt - 1 : splitAt;
+}
+function takeBufferedSegment(buffer, flushBoundary, maxTextLength, inputComplete) {
+    const cappedText = buffer.slice(0, maxTextLength);
+    const sentenceEnds = findSentenceEnds(cappedText);
+    let splitAt = buffer.length >= flushBoundary ? sentenceEnds.at(-1) : undefined;
+    if (splitAt === undefined && buffer.length >= maxTextLength) {
+        splitAt = sentenceEnds.at(-1) ?? maxTextLength;
+    }
+    if (splitAt === undefined && inputComplete && buffer.trim()) {
+        splitAt = Math.min(buffer.length, maxTextLength);
+    }
+    if (splitAt === undefined) {
+        return undefined;
+    }
+    splitAt = avoidSurrogateSplit(buffer, splitAt);
+    const segment = buffer.slice(0, splitAt).trim();
+    const remainder = buffer.slice(splitAt).trimStart();
+    if (!segment) {
+        return { segment: "", remainder };
+    }
+    return { segment, remainder };
+}
 /**
  * TTS Error class for text-to-speech specific errors
  */
@@ -289,4 +358,102 @@ export class TTSProcessor {
             });
         }
     }
+    /**
+     * Incrementally synthesize sentence-buffered text chunks.
+     *
+     * Text is flushed at a sentence boundary after `streamingBufferSize`
+     * characters, or hard-split before the provider's maximum text length.
+     * Each segment goes through `synthesize()`, preserving the existing handler
+     * registry, validation, error normalization, and telemetry seam.
+     *
+     * The most recent successful audio chunk is held until another succeeds or
+     * the input ends, so exactly one real audio chunk carries `isFinal: true`
+     * without emitting a separate empty terminator chunk.
+     */
+    static async *synthesizeStream(textChunks, provider, options, shouldStop) {
+        const handler = this.getHandler(provider);
+        const maxTextLength = Math.max(1, handler?.maxTextLength ?? this.DEFAULT_MAX_TEXT_LENGTH);
+        const requestedBoundary = options.streamingBufferSize ?? DEFAULT_STREAMING_BUFFER_SIZE;
+        const flushBoundary = Math.min(Math.max(1, Math.trunc(requestedBoundary)), maxTextLength);
+        let buffer = "";
+        let chunkIndex = 0;
+        let cumulativeSize = 0;
+        let cumulativeDuration = 0;
+        let pendingChunk;
+        let segmentNumber = 0;
+        let firstFailure;
+        const failedSegments = [];
+        const synthesizeSegment = async (segment) => {
+            const currentSegment = ++segmentNumber;
+            try {
+                const result = await this.synthesize(segment, provider, options);
+                cumulativeSize += result.size;
+                cumulativeDuration += result.duration ?? 0;
+                return {
+                    data: result.buffer,
+                    format: result.format,
+                    index: chunkIndex++,
+                    isFinal: false,
+                    cumulativeSize,
+                    estimatedDuration: cumulativeDuration || undefined,
+                    voice: result.voice,
+                    sampleRate: result.sampleRate,
+                };
+            }
+            catch (error) {
+                if (failedSegments.length === 0) {
+                    firstFailure = error;
+                }
+                failedSegments.push(currentSegment);
+                logger.warn(`[TTSProcessor] Incremental synthesis skipped a buffered segment: ${error instanceof Error ? error.message : String(error)}`);
+                return undefined;
+            }
+        };
+        for await (const textChunk of textChunks) {
+            if (shouldStop?.()) {
+                break;
+            }
+            buffer += textChunk;
+            while (!shouldStop?.()) {
+                const buffered = takeBufferedSegment(buffer, flushBoundary, maxTextLength, false);
+                if (!buffered) {
+                    break;
+                }
+                buffer = buffered.remainder;
+                if (!buffered.segment) {
+                    continue;
+                }
+                const chunk = await synthesizeSegment(buffered.segment);
+                if (chunk) {
+                    if (pendingChunk) {
+                        yield pendingChunk;
+                    }
+                    pendingChunk = chunk;
+                }
+            }
+        }
+        while (!shouldStop?.()) {
+            const buffered = takeBufferedSegment(buffer, flushBoundary, maxTextLength, true);
+            if (!buffered) {
+                break;
+            }
+            buffer = buffered.remainder;
+            if (!buffered.segment) {
+                continue;
+            }
+            const chunk = await synthesizeSegment(buffered.segment);
+            if (chunk) {
+                if (pendingChunk) {
+                    yield pendingChunk;
+                }
+                pendingChunk = chunk;
+            }
+        }
+        if (pendingChunk) {
+            yield { ...pendingChunk, isFinal: true };
+        }
+        if (failedSegments.length > 0) {
+            throw new IncrementalTTSSynthesisError(firstFailure, failedSegments);
+        }
+    }
 }

package/dist/utils/ttsStream.d.ts

@@ -0,0 +1,15 @@
+import type { TTSChunk, TTSMetadata, TTSOptions, TTSResult } from "../types/index.js";
+/**
+ * Preserve source-stream backpressure while interleaving incremental TTS audio.
+ * Source chunks are yielded before their derived audio, and TTS failures degrade
+ * to the unchanged source stream.
+ */
+export declare function interleaveTTSStream<T>(params: {
+    stream: AsyncIterable<T>;
+    provider: string;
+    options: TTSOptions;
+    onComplete?: (result: TTSResult | undefined, error?: NonNullable<TTSMetadata["error"]>) => void;
+}): AsyncGenerator<T | {
+    type: "tts_audio";
+    audio: TTSChunk;
+}>;

package/dist/utils/ttsStream.js

@@ -0,0 +1,225 @@
+import { NeuroLinkError } from "./errorHandling.js";
+import { sanitizeErrorCause } from "./logSanitize.js";
+import { logger } from "./logger.js";
+import { IncrementalTTSSynthesisError, TTS_ERROR_CODES, TTSProcessor, } from "./ttsProcessor.js";
+import { TimeoutError as AsyncTimeoutError } from "./async/withTimeout.js";
+function getStreamingTTSErrorDetails(error) {
+    const incrementalFailure = error instanceof IncrementalTTSSynthesisError ? error : undefined;
+    const cause = incrementalFailure?.firstError ?? error;
+    const safeMessage = sanitizeErrorCause(cause).message;
+    let detail;
+    if (cause instanceof AsyncTimeoutError) {
+        detail = {
+            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+            message: safeMessage,
+            retriable: true,
+        };
+    }
+    else if (cause instanceof NeuroLinkError) {
+        detail = {
+            code: cause.code,
+            message: safeMessage,
+            retriable: cause.retriable,
+        };
+    }
+    else {
+        detail = {
+            code: TTS_ERROR_CODES.SYNTHESIS_FAILED,
+            message: safeMessage,
+        };
+    }
+    const failedSegments = incrementalFailure?.failedSegments;
+    const count = failedSegments?.length ?? 1;
+    const positions = failedSegments?.join(", ") ?? "unknown";
+    return {
+        ...detail,
+        message: `Incremental TTS failed for ${count} segment${count === 1 ? "" : "s"} (segment${count === 1 ? "" : "s"} ${positions}): ${detail.message}`,
+    };
+}
+class AsyncTextQueue {
+    values = [];
+    waiters = [];
+    ended = false;
+    failure;
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    next() {
+        if (this.values.length > 0) {
+            const value = this.values.shift();
+            if (value !== undefined) {
+                return Promise.resolve({ value, done: false });
+            }
+        }
+        if (this.failure !== undefined) {
+            return Promise.reject(this.failure);
+        }
+        if (this.ended) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    push(value) {
+        if (this.ended || this.failure !== undefined) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value, done: false });
+            return;
+        }
+        this.values.push(value);
+    }
+    end() {
+        if (this.ended || this.failure !== undefined) {
+            return;
+        }
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+    fail(error) {
+        if (this.ended || this.failure !== undefined) {
+            return;
+        }
+        this.failure = error;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.reject(error);
+        }
+    }
+}
+function sourceEvent(iterator) {
+    return iterator.next().then((result) => ({ kind: "source", result }), (error) => ({ kind: "source-error", error }));
+}
+function audioEvent(iterator) {
+    return iterator.next().then((result) => ({ kind: "audio", result }), (error) => ({ kind: "audio-error", error }));
+}
+function textFromChunk(chunk) {
+    if (chunk &&
+        typeof chunk === "object" &&
+        "content" in chunk &&
+        typeof chunk.content === "string" &&
+        chunk.content.length > 0) {
+        return chunk.content;
+    }
+    return undefined;
+}
+function aggregateTTSChunks(chunks) {
+    const last = chunks.at(-1);
+    if (!last) {
+        return undefined;
+    }
+    const buffer = Buffer.concat(chunks.map((chunk) => chunk.data));
+    return {
+        buffer,
+        format: last.format,
+        size: buffer.length,
+        duration: last.estimatedDuration,
+        voice: last.voice,
+        sampleRate: last.sampleRate,
+    };
+}
+/**
+ * Preserve source-stream backpressure while interleaving incremental TTS audio.
+ * Source chunks are yielded before their derived audio, and TTS failures degrade
+ * to the unchanged source stream.
+ */
+export async function* interleaveTTSStream(params) {
+    const { stream, provider, options, onComplete } = params;
+    if (!TTSProcessor.supports(provider)) {
+        try {
+            for await (const chunk of stream) {
+                yield chunk;
+            }
+        }
+        finally {
+            onComplete?.(undefined);
+        }
+        return;
+    }
+    const textQueue = new AsyncTextQueue();
+    const sourceIterator = stream[Symbol.asyncIterator]();
+    let cancelled = false;
+    const audioIterator = TTSProcessor.synthesizeStream(textQueue, provider, options, () => cancelled)[Symbol.asyncIterator]();
+    const audioChunks = [];
+    let nextSource = sourceEvent(sourceIterator);
+    let nextAudio = audioEvent(audioIterator);
+    let completed = false;
+    let preferAudio = false;
+    try {
+        while (nextSource || nextAudio) {
+            const event = nextSource && nextAudio
+                ? await Promise.race(preferAudio ? [nextAudio, nextSource] : [nextSource, nextAudio])
+                : nextSource
+                    ? await nextSource
+                    : nextAudio
+                        ? await nextAudio
+                        : undefined;
+            if (!event) {
+                break;
+            }
+            if (event.kind === "source-error") {
+                textQueue.fail(event.error);
+                throw event.error;
+            }
+            if (event.kind === "audio-error") {
+                textQueue.end();
+                const error = getStreamingTTSErrorDetails(event.error);
+                logger.warn(`[TTSProcessor] Incremental stream disabled after an audio error: ${event.error instanceof Error
+                    ? event.error.message
+                    : String(event.error)}`);
+                nextAudio = undefined;
+                preferAudio = false;
+                completed = true;
+                onComplete?.(aggregateTTSChunks(audioChunks), error);
+                continue;
+            }
+            if (event.kind === "source") {
+                if (event.result.done) {
+                    nextSource = undefined;
+                    textQueue.end();
+                    preferAudio = true;
+                    continue;
+                }
+                const text = textFromChunk(event.result.value);
+                if (text) {
+                    textQueue.push(text);
+                }
+                nextSource = sourceEvent(sourceIterator);
+                preferAudio = true;
+                yield event.result.value;
+                continue;
+            }
+            if (event.result.done) {
+                nextAudio = undefined;
+                completed = true;
+                onComplete?.(aggregateTTSChunks(audioChunks));
+                continue;
+            }
+            audioChunks.push(event.result.value);
+            nextAudio = audioEvent(audioIterator);
+            preferAudio = false;
+            yield { type: "tts_audio", audio: event.result.value };
+        }
+    }
+    finally {
+        if (!completed) {
+            cancelled = true;
+        }
+        textQueue.end();
+        const releases = [];
+        if (nextSource && sourceIterator.return) {
+            releases.push(Promise.resolve().then(() => sourceIterator.return?.(undefined)));
+        }
+        if (nextAudio && audioIterator.return) {
+            releases.push(Promise.resolve().then(() => audioIterator.return?.(undefined)));
+        }
+        await Promise.allSettled(releases);
+        if (!completed) {
+            onComplete?.(undefined);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "11.25.4",
+  "version": "11.26.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {