@juspay/neurolink 12.6.0 → 12.7.0

package/dist/utils/ttsProcessor.d.ts

@@ -162,17 +162,142 @@ export declare class TTSProcessor {
      * ```
      */
     static synthesize(text: string, provider: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Normalize a provider failure into the public `TTSError` shape.
+     *
+     * Extracted from `synthesize()` so the native streaming path can shape its
+     * transport errors identically. A raw provider error reaching the public
+     * surface unwrapped loses `retriable` (and the provider-qualified message),
+     * which is exactly what a caller keying retry logic off
+     * `ttsMetadata.error.retriable` reads.
+     */
+    private static toSynthesisError;
+    /**
+     * Open the `tts.synthesize` span that `synthesize()` opens, so a segment
+     * served by a handler's native stream emits the same telemetry a buffered
+     * segment does.
+     */
+    private static startSynthesisSpan;
+    private static finishSynthesisSpan;
+    /**
+     * `TTSHandler.synthesizeStream` is declared `unknown`, so a handler may
+     * carry anything at all under that name — including a legacy member of an
+     * unrelated shape. The native capability is discovered structurally instead:
+     * the member must be callable, and what it returns must be async-iterable.
+     *
+     * Discovery reads consumer-controlled properties, and a property read can
+     * itself execute user code (a Proxy trap, a throwing getter) — the member on
+     * the handler and the well-known symbol on what it returns alike. Every one
+     * of those reads therefore happens inside a try: `resolveNativeStream`
+     * guards the whole preflight in one region, and `cancelStream`/
+     * `releaseIterator` in `streamCancellation.ts` guard the symbol read they
+     * each perform on the unwind path.
+     */
+    private static isCallableMember;
+    private static isNativeStream;
+    /**
+     * Coerce one fragment yielded by a handler's native stream into the fields
+     * this processor forwards, or `undefined` when the fragment is not audio.
+     *
+     * `TTSHandler.synthesizeStream` is declared `unknown` because ANY narrower
+     * type rejects some existing consumer that already carries a member of that
+     * name — a Critical Rule 5 break. The type therefore checks nothing at all,
+     * and every check happens at runtime instead. Here that means: a
+     * fragment must carry a non-empty binary payload, and a reported `format` is
+     * honoured only when it names a real audio format, falling back to the
+     * requested one. The caller skips an `undefined` result exactly as it skips
+     * a zero-length transport read.
+     */
+    private static normalizeNativeChunk;
+    /**
+     * Ask a handler for a native stream for one segment, or `undefined` to serve
+     * the segment from `synthesize()`.
+     *
+     * `undefined` is the documented "not incrementally deliverable" signal. A
+     * handler that throws instead, or hands back something that is not
+     * async-iterable, is buggy — but that is a reason to serve the segment from
+     * the buffered path, not to lose it.
+     *
+     * **Every failure this method anticipates answers `undefined` instead of
+     * throwing, and the caller's catch backstops what no code that must
+     * describe a hostile thrown value can rule out.** Everything it does is a question ABOUT the
+     * handler, asked before any of the segment's work has begun, and every one
+     * of those questions can run consumer code: reading `synthesizeStream` or
+     * `isConfigured` can hit an accessor or a `Proxy` trap, calling
+     * `isConfigured()` and calling the member run handler code outright, and
+     * reading `Symbol.asyncIterator` off whatever comes back can hit a getter or
+     * a trap of its own. A throw from ANY of them means the same thing — the
+     * capability could not be established — so they all sit inside the single
+     * guarded region below and every failure answers `undefined`. The segment
+     * then goes to `synthesize()`, which re-runs the identical preflight inside
+     * its own `tts.synthesize` span and normalizes whatever it raises, exactly
+     * as it did before native streaming existed. Reporting a preflight failure
+     * from here instead would open a second span for one segment, or drop a
+     * segment the buffered path can still serve.
+     *
+     * Two ordering rules make that equivalence exact:
+     *
+     * - The member is read FIRST and exactly ONCE per segment. An accessor-
+     *   defined member runs consumer code on every read, so a second read can
+     *   answer differently from the one that was tested — and reading it before
+     *   `isConfigured()` keeps a handler that does not offer the capability at
+     *   all on precisely the call sequence it had before this method existed.
+     * - `isConfigured()` runs only once a callable member has been found, which
+     *   is the only case where this method is about to invoke the handler.
+     *
+     * The one measured departure from `origin/release` is a call count, not an
+     * outcome: a segment that starts down the native path and falls back calls
+     * the handler's `isConfigured()` twice — here, and again inside
+     * `synthesize()`. That is inherent to attempting native delivery at all and
+     * predates this method's current shape; `isConfigured()` is specified as a
+     * configuration predicate, and for any implementation that behaves as one —
+     * a pure predicate — every observable of such a segment (chunks, spans,
+     * error code and `retriable`) is identical either way. A handler whose
+     * answer CHANGES between the two calls changes the outcome with it: the
+     * second answer, taken on the path that actually synthesizes, decides.
+     */
+    private static resolveNativeStream;
     /**
      * 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.
+     * A segment is served by the handler's `synthesizeStream()` when it offers
+     * one and returns a stream, and by `synthesize()` otherwise — including
+     * when the native stream produces no deliverable audio at all, and including
+     * every way capability discovery itself can fail. The preflight reads and
+     * calls that decide whether a native stream exists all sit inside one
+     * guarded region in `resolveNativeStream`, with the call site's own catch
+     * backstopping it, so a handler that misbehaves while being ASKED lands on
+     * the buffered path rather than costing the segment. That is what makes the
+     * next sentence true of every segment rather than only of the ones that got
+     * that far.
+     *
+     * Either way the segment keeps the same handler registry, validation, error
+     * normalization and `tts.synthesize` telemetry seam — exactly one span per
+     * segment, opened by whichever path served it — cancellation included: a
+     * segment whose stream is still in flight when the consumer stops records
+     * its span from the unwind path rather than dropping it. Failures that
+     * originate in the native segment's own work, once a stream has been
+     * established, are a different case and keep the shaped failed-segment
+     * semantics every synthesis failure has.
+     *
+     * Provider-reported indexes, cumulative sizes and finality are discarded and
+     * recomputed globally. A native fragment is dropped unless it carries a
+     * non-empty binary payload, so no native read reaches the consumer as an
+     * empty chunk; the buffered path is unfiltered and forwards whatever
+     * `synthesize()` returns, so a handler that produces a zero-byte buffer
+     * still yields an empty chunk and a repeated `cumulativeSize`. 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.
+     *
+     * Segment production and per-segment synthesis are deliberately inline
+     * rather than nested async generators: each additional generator layer costs
+     * every chunk several microtask turns, which is directly observable at
+     * `NeuroLink.stream()` as audio interleaving one text chunk later than it
+     * does without native streaming.
      */
     static synthesizeStream(textChunks: AsyncIterable<string>, provider: string, options: TTSOptions, shouldStop?: () => boolean): AsyncGenerator<TTSChunk>;
 }