@juspay/neurolink 12.6.1 → 12.7.0

package/dist/proxy/clientAttribution.d.ts

@@ -16,6 +16,46 @@
  *   client is then still attributable by its own User-Agent rather than
  *   collapsing into one bucket with every other unknown.
  */
+/**
+ * Deliberately NOT mapped, with the measurement that ruled each one out.
+ *
+ * Copilot CLI is the one client here that cannot be identified from its
+ * User-Agent, and both of the strings it sends are actively unsafe to key on:
+ *
+ * - `OpenAI/JS 5.20.1` — the stock OpenAI JS SDK UA, sent by every caller of
+ *   that SDK. Mapping it to Copilot would file unrelated OpenAI-SDK traffic
+ *   under Copilot's name, which is worse than leaving it unattributed.
+ - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — not a
+ *   CLI's User-Agent at all. This is what `curl` sends on a machine whose
+ *   `~/.curlrc` sets `user-agent`, so every curl-driven caller on such a host
+ *   shares it: scripts, agents, health probes. It accounted for the largest
+ *   single block of `unknown` rows in the log this table was measured against,
+ *   which is exactly what made it tempting.
+ *
+ *   Recorded because the first pass got this wrong in a way worth naming. The
+ *   string was seen arriving at two capture servers during Copilot CLI and
+ *   Gemini CLI runs and was written up as "sent by both CLIs". It was neither:
+ *   it was the aliveness `curl` fired at each capture server moments before
+ *   the CLI, picking up that host's curlrc. The paths gave it away on review —
+ *   the Gemini-side hit was a bare `GET /v1beta/models`, which is the probe's
+ *   URL and not one the CLI requests. A shared string across two unrelated
+ *   clients should have read as "shared dependency or shared tooling", not as
+ *   a property of either client.
+ *
+ * Copilot does send `x-initiator` and `x-interaction-type`, but neither is
+ * exclusive to it either. Attributing it needs a signal nobody has found yet,
+ * so it stays `unknown` and remains traceable through the stored raw header.
+ */
+/**
+ * The client names this table can produce.
+ *
+ * Exported so a test can check the roster of CLIs the proxy configures against
+ * the roster it can actually name. Those two lists drifted apart silently once
+ * already: five configurators shipped while the table still knew only Claude
+ * Code, and nothing failed, because an unattributed client looks exactly like
+ * a quiet one.
+ */
+export declare function getMappedClientNames(): ReadonlySet<string>;
 /**
  * Derive a stable client name, or "unknown" when the header is absent or
  * unrecognised. Never throws: attribution must not be able to fail a request.

package/dist/proxy/clientAttribution.js

@@ -49,16 +49,39 @@ const CLIENT_PREFIXES = [
  * - `OpenAI/JS 5.20.1` — the stock OpenAI JS SDK UA, sent by every caller of
  *   that SDK. Mapping it to Copilot would file unrelated OpenAI-SDK traffic
  *   under Copilot's name, which is worse than leaving it unattributed.
- * - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — a
- *   spoofed browser string. It looks like a fingerprint and is not one: it was
- *   captured from **both** Copilot CLI and Gemini CLI, so it identifies no
- *   client at all. (It also accounts for the largest single block of
- *   `unknown` rows in this machine's log, which is what made it tempting.)
+ - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — not a
+ *   CLI's User-Agent at all. This is what `curl` sends on a machine whose
+ *   `~/.curlrc` sets `user-agent`, so every curl-driven caller on such a host
+ *   shares it: scripts, agents, health probes. It accounted for the largest
+ *   single block of `unknown` rows in the log this table was measured against,
+ *   which is exactly what made it tempting.
+ *
+ *   Recorded because the first pass got this wrong in a way worth naming. The
+ *   string was seen arriving at two capture servers during Copilot CLI and
+ *   Gemini CLI runs and was written up as "sent by both CLIs". It was neither:
+ *   it was the aliveness `curl` fired at each capture server moments before
+ *   the CLI, picking up that host's curlrc. The paths gave it away on review —
+ *   the Gemini-side hit was a bare `GET /v1beta/models`, which is the probe's
+ *   URL and not one the CLI requests. A shared string across two unrelated
+ *   clients should have read as "shared dependency or shared tooling", not as
+ *   a property of either client.
  *
  * Copilot does send `x-initiator` and `x-interaction-type`, but neither is
  * exclusive to it either. Attributing it needs a signal nobody has found yet,
  * so it stays `unknown` and remains traceable through the stored raw header.
  */
+/**
+ * The client names this table can produce.
+ *
+ * Exported so a test can check the roster of CLIs the proxy configures against
+ * the roster it can actually name. Those two lists drifted apart silently once
+ * already: five configurators shipped while the table still knew only Claude
+ * Code, and nothing failed, because an unattributed client looks exactly like
+ * a quiet one.
+ */
+export function getMappedClientNames() {
+    return new Set(CLIENT_PREFIXES.map(([, name]) => name));
+}
 /** Cap stored User-Agents. They are attacker-influenced and unbounded. */
 const MAX_USER_AGENT_CHARS = 200;
 /**

package/dist/types/common.d.ts

@@ -352,6 +352,93 @@ export type TTSHandler = {
      * @throws {TTSError} On synthesis failure, timeout, or configuration issues
      */
     synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Stream provider-native audio for one pre-validated text segment.
+     *
+     * Return `undefined` when the requested options cannot be delivered
+     * incrementally. The processor then uses `synthesize()` and preserves the
+     * buffered fallback for handlers and formats without native support.
+     * Provider-local indexes, cumulative sizes, and finality are normalized by
+     * the processor before chunks reach the public stream — an implementation
+     * may leave `isFinal` false on every chunk rather than hold a fragment back
+     * to label the last one, and the processor discards reported finality
+     * either way.
+     *
+     * Yield `TTSChunk` fragments. The member is declared `unknown` — not a
+     * method signature — on purpose, and that is a deliberate trade.
+     *
+     * This is an OPTIONAL member added to a public structural type that
+     * consumers already implement. Any type narrower than `unknown` rejects some
+     * existing handler that already carries a member of this name, which is a
+     * source break under Critical Rule 5 whatever that other shape happens to
+     * be. That is not hypothetical: a member returning a sync `Generator`, an
+     * `async` method returning a `Promise` of an async iterable, a
+     * callback-style member returning `void` or `Promise<void>`, and a plain
+     * boolean capability flag all compile against `origin/release` today, and
+     * every one of them is rejected by a declared method signature — including
+     * an intentionally wide one such as `(...args: never[]) => unknown`, which
+     * still cannot accept the boolean. Only `unknown` accepts them all.
+     *
+     * The cost is that this member cannot contextually type an implementation's
+     * parameters. Authors annotate their own signature instead — OpenAI TTS
+     * declares `synthesizeStream(text: string, options: TTSOptions):
+     * AsyncIterable<TTSChunk> | undefined` on the class — which keeps full
+     * compiler checking of what that implementation yields. Nothing is checked
+     * at this member; usability is decided at runtime by the processor.
+     *
+     * The processor validates each fragment at runtime instead. A fragment is
+     * audio only when it carries a non-empty `data` `Buffer` (or `Uint8Array`);
+     * its `format` is honoured only when it names a real `TTSAudioFormat`, and
+     * the requested format is used otherwise. A fragment that fails that test —
+     * including an empty (`data.length === 0`) read — is skipped and never
+     * reaches the consumer. A native stream that completes without yielding a
+     * single deliverable fragment is treated as "no incremental delivery after
+     * all" and falls back to `synthesize()` for that segment.
+     *
+     * That filtering is specific to this native path. The buffered path
+     * forwards whatever `synthesize()` returns, a zero-byte buffer included, so
+     * a consumer of the public stream can still observe an empty chunk when a
+     * handler produces one.
+     *
+     * `undefined` is the only capability signal. Everything the processor does
+     * to decide whether this capability exists is asked BEFORE the segment's
+     * work starts, and every way that question can fail is a handler bug that
+     * the processor answers the same way: it serves that segment from
+     * `synthesize()` rather than losing it (the throwing modes also log a
+     * warning; a member that is merely not callable falls back silently). None
+     * of them should be used as a deliberate fallback mechanism. The modes it
+     * anticipates cover each read as well as each call, because reading a
+     * property can run a getter or a `Proxy` trap that throws just as a call
+     * can:
+     *
+     * - reading `synthesizeStream` off the handler throws;
+     * - the member is present but not callable;
+     * - reading `isConfigured` off the handler throws, or calling it throws —
+     *   the segment falls back to the buffered path, where `synthesize()` asks
+     *   again and a throw there fails the segment shaped, exactly as it would
+     *   for a handler with no native member (a handler that merely reports
+     *   itself unconfigured is not a bug: that segment fails with
+     *   `TTS_PROVIDER_NOT_CONFIGURED`, as it always has);
+     * - calling the member throws;
+     * - the returned value's async-iterability cannot be established, including
+     *   a value whose `Symbol.asyncIterator` property cannot even be read.
+     *
+     * An error raised once the segment's own work has started, by contrast,
+     * fails that segment like any other synthesis failure — it is not re-served
+     * from the buffered path. Iteration begins at the `[Symbol.asyncIterator]()`
+     * call, so that call throwing, that call handing back something that is not
+     * an iterator, and a first read that rejects are all segment failures rather
+     * than fallbacks.
+     *
+     * Implementations MUST enforce their own timeout and cancel any active
+     * transport when the returned iterable is closed.
+     *
+     * The value the processor looks for is a callable of the shape
+     * `(text: string, options: TTSOptions) => AsyncIterable<TTSChunk> | undefined`,
+     * invoked with the handler as `this`. `text` is one buffered text segment
+     * within the provider's length limit.
+     */
+    synthesizeStream?: unknown;
     /**
      * Get available voices for the provider
      *

package/dist/types/voice.d.ts

@@ -134,6 +134,14 @@ export type VoiceTurn = {
 };
 /**
  * TTS-capable voice provider type
+ *
+ * @deprecated Use the canonical `TTSHandler` contract instead. Nothing in
+ * this package consumes `TTSProvider`; it is kept at its original shape so
+ * existing external callers keep compiling. `TTSHandler` is not a drop-in
+ * replacement — it requires `isConfigured()`, makes `getVoices` and
+ * `maxTextLength` optional, and its `synthesizeStream` may return `undefined`
+ * to select the buffered path — so this is a distinct legacy shape, not an
+ * alias.
  */
 export type TTSProvider = {
     /**
@@ -155,6 +163,11 @@ export type TTSProvider = {
 };
 /**
  * TTS stream chunk for streaming synthesis
+ *
+ * @deprecated Use the canonical `TTSChunk` type instead. Kept at its
+ * original shape so existing external callers keep compiling: `TTSChunk`
+ * narrows `format` to `TTSAudioFormat` and has no `timestampMs`, so it
+ * is not a drop-in replacement.
  */
 export type TTSStreamChunk = {
     /** Audio data chunk */

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>;
 }