@juspay/neurolink 9.57.0 → 9.58.0

package/dist/constants/enums.d.ts

@@ -594,7 +594,14 @@ export declare enum ErrorCategory {
     PERMISSION = "permission",
     CONFIGURATION = "configuration",
     EXECUTION = "execution",
-    SYSTEM = "system"
+    SYSTEM = "system",
+    /**
+     * Caller-initiated cancellation via AbortSignal. Distinct from system errors
+     * — represents a user/control-plane decision, not a SDK or provider failure.
+     * Consumers can branch on this category to differentiate "user cancelled"
+     * from "server error" without resorting to message-string matching.
+     */
+    ABORT = "abort"
 }
 export declare enum ErrorSeverity {
     LOW = "low",

package/dist/constants/enums.js

@@ -812,6 +812,13 @@ export var ErrorCategory;
     ErrorCategory["CONFIGURATION"] = "configuration";
     ErrorCategory["EXECUTION"] = "execution";
     ErrorCategory["SYSTEM"] = "system";
+    /**
+     * Caller-initiated cancellation via AbortSignal. Distinct from system errors
+     * — represents a user/control-plane decision, not a SDK or provider failure.
+     * Consumers can branch on this category to differentiate "user cancelled"
+     * from "server error" without resorting to message-string matching.
+     */
+    ErrorCategory["ABORT"] = "abort";
 })(ErrorCategory || (ErrorCategory = {}));
 // Error severity levels
 export var ErrorSeverity;

package/dist/lib/constants/enums.d.ts

@@ -594,7 +594,14 @@ export declare enum ErrorCategory {
     PERMISSION = "permission",
     CONFIGURATION = "configuration",
     EXECUTION = "execution",
-    SYSTEM = "system"
+    SYSTEM = "system",
+    /**
+     * Caller-initiated cancellation via AbortSignal. Distinct from system errors
+     * — represents a user/control-plane decision, not a SDK or provider failure.
+     * Consumers can branch on this category to differentiate "user cancelled"
+     * from "server error" without resorting to message-string matching.
+     */
+    ABORT = "abort"
 }
 export declare enum ErrorSeverity {
     LOW = "low",

package/dist/lib/constants/enums.js

@@ -812,6 +812,13 @@ export var ErrorCategory;
     ErrorCategory["CONFIGURATION"] = "configuration";
     ErrorCategory["EXECUTION"] = "execution";
     ErrorCategory["SYSTEM"] = "system";
+    /**
+     * Caller-initiated cancellation via AbortSignal. Distinct from system errors
+     * — represents a user/control-plane decision, not a SDK or provider failure.
+     * Consumers can branch on this category to differentiate "user cancelled"
+     * from "server error" without resorting to message-string matching.
+     */
+    ErrorCategory["ABORT"] = "abort";
 })(ErrorCategory || (ErrorCategory = {}));
 // Error severity levels
 export var ErrorSeverity;

package/dist/lib/neurolink.d.ts

@@ -60,6 +60,7 @@ export declare class NeuroLink {
     private pendingAuthConfig?;
     private authInitPromise?;
     private credentials?;
+    private readonly fallbackConfig;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -541,6 +542,21 @@ export declare class NeuroLink {
      * @since 1.0.0
      */
     generate(optionsOrPrompt: GenerateOptions | DynamicOptions | string): Promise<GenerateResult>;
+    /**
+     * Curator P2-3: wraps a generate/stream call with the fallback
+     * orchestration (`providerFallback` callback + `modelChain` walker).
+     *
+     * On a model-access-denied error from the inner call:
+     *  1. Resolve the effective callback (per-call > instance > synthesised
+     *     from modelChain) and the effective chain (per-call > instance).
+     *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
+     *     `model.fallback` event → re-call inner with the new {provider,
+     *     model}.
+     *  3. Stop on first success, on a callback returning null, or after
+     *     exhausting the chain (throw the most recent error).
+     */
+    private runWithFallbackOrchestration;
+    private attemptInner;
     private executeGenerateWithMetricsContext;
     private executeGenerateRequest;
     private prepareGenerateRequest;
@@ -697,6 +713,25 @@ export declare class NeuroLink {
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     stream(options: StreamOptions | DynamicOptions): Promise<StreamResult>;
+    /**
+     * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
+     * errors thrown during async iteration (e.g. LiteLLM throwing inside
+     * `createLiteLLMTransformedStream`). The standard
+     * `runWithFallbackOrchestration` only catches errors thrown while the
+     * `StreamResult` is being created — once we hand the iterator back to
+     * the caller, errors raised during consumption used to bypass
+     * `providerFallback` / `modelChain`.
+     *
+     * This wrapper runs the orchestration to get an initial StreamResult,
+     * then wraps `result.stream` so that:
+     *   - chunks are forwarded transparently while consumption succeeds
+     *   - if iteration throws a model-access-denied error AND no chunks
+     *     have been yielded yet, we resolve the next fallback target,
+     *     emit `model.fallback`, and recurse
+     *   - if chunks were already yielded, the error propagates (mid-stream
+     *     recovery isn't safe — the consumer has half a response)
+     */
+    private streamWithIterationFallback;
     private executeStreamRequest;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
@@ -881,8 +916,12 @@ export declare class NeuroLink {
      * **Generation Events:**
      * - `generation:start` - Fired when text generation begins
      *   - `{ provider: string, timestamp: number }`
-     * - `generation:end` - Fired when text generation completes
-     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number }`
+     * - `generation:end` - Fired when text generation completes (or fails / is aborted)
+     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number, success?: boolean, aborted?: boolean, error?: string }`
+     *   - `success` is `false` for both failures and client aborts; `aborted: true`
+     *     distinguishes the latter so consumers can route cancellations
+     *     differently from real errors. Pipeline B's metrics span maps
+     *     `aborted: true` events to `SpanStatus.WARNING` (not ERROR).
      *
      * **Streaming Events:**
      * - `stream:start` - Fired when streaming begins