@blockrun/llm 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -781,6 +781,28 @@ var LLMClient = class _LLMClient {
     } catch {
     }
   }
+  /**
+   * Parse the chat response JSON and attach `fallback` metadata when the
+   * gateway signalled a transparent free-fallback substitution. The
+   * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+   * on the response when it served a paid request from a free model
+   * (route.ts createPaymentResponseHeader path). Without surfacing these
+   * to the caller, the user gets a different model than requested with
+   * no visibility — silent quality drop and no clue why the on-chain
+   * balance didn't change.
+   */
+  async parseChatResponse(response) {
+    const body = await response.json();
+    const used = response.headers.get("X-Fallback-Used") === "true";
+    if (used) {
+      body.fallback = {
+        used: true,
+        model: response.headers.get("X-Fallback-Model") || void 0,
+        settlementSkipped: response.headers.get("X-Settlement-Skipped") === "free-fallback"
+      };
+    }
+    return body;
+  }
   /**
    * Make a request with automatic x402 payment handling.
    */
@@ -809,7 +831,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
         }
-        return retryResp.json();
+        return this.parseChatResponse(retryResp);
       }
     }
     if (response.status === 402) {
@@ -828,7 +850,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return response.json();
+    return this.parseChatResponse(response);
   }
   /**
    * Handle 402 response: parse requirements, sign payment, retry.
@@ -903,7 +925,7 @@ var LLMClient = class _LLMClient {
         this.sessionCalls += 1;
         this.sessionTotalUsd += costUsd2;
         this.recordCost(url, costUsd2, { body, network: details.network });
-        return retryResp2.json();
+        return this.parseChatResponse(retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -926,7 +948,7 @@ var LLMClient = class _LLMClient {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
     this.recordCost(url, costUsd, { body, network: details.network });
-    return retryResponse.json();
+    return this.parseChatResponse(retryResponse);
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.

package/dist/index.d.cts

@@ -58,6 +58,25 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage?: ChatUsage;
     citations?: string[];
+    /**
+     * Populated when the gateway transparently substituted a different
+     * model for the one the caller asked for — typically because the
+     * requested model errored and the gateway routed to a free fallback
+     * to fulfil the request. When `used` is true:
+     *   - `model` is the model that actually answered (vs `ChatResponse.model`
+     *     which historically reflected the requested model id).
+     *   - `settlementSkipped` is `true` when the gateway also skipped the
+     *     on-chain settle — i.e. the user was not charged for this call
+     *     because a free fallback served it.
+     * Surfaced from the gateway's `X-Fallback-Used / X-Fallback-Model /
+     * X-Settlement-Skipped` response headers. Absent when the headers
+     * aren't present (most calls).
+     */
+    fallback?: {
+        used: true;
+        model?: string;
+        settlementSkipped?: boolean;
+    };
 }
 interface Model {
     id: string;
@@ -811,6 +830,17 @@ declare class LLMClient {
      * cost_log.jsonl is a single source of truth regardless of caller.
      */
     private recordCost;
+    /**
+     * Parse the chat response JSON and attach `fallback` metadata when the
+     * gateway signalled a transparent free-fallback substitution. The
+     * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+     * on the response when it served a paid request from a free model
+     * (route.ts createPaymentResponseHeader path). Without surfacing these
+     * to the caller, the user gets a different model than requested with
+     * no visibility — silent quality drop and no clue why the on-chain
+     * balance didn't change.
+     */
+    private parseChatResponse;
     /**
      * Make a request with automatic x402 payment handling.
      */

package/dist/index.d.ts

@@ -58,6 +58,25 @@ interface ChatResponse {
     choices: ChatChoice[];
     usage?: ChatUsage;
     citations?: string[];
+    /**
+     * Populated when the gateway transparently substituted a different
+     * model for the one the caller asked for — typically because the
+     * requested model errored and the gateway routed to a free fallback
+     * to fulfil the request. When `used` is true:
+     *   - `model` is the model that actually answered (vs `ChatResponse.model`
+     *     which historically reflected the requested model id).
+     *   - `settlementSkipped` is `true` when the gateway also skipped the
+     *     on-chain settle — i.e. the user was not charged for this call
+     *     because a free fallback served it.
+     * Surfaced from the gateway's `X-Fallback-Used / X-Fallback-Model /
+     * X-Settlement-Skipped` response headers. Absent when the headers
+     * aren't present (most calls).
+     */
+    fallback?: {
+        used: true;
+        model?: string;
+        settlementSkipped?: boolean;
+    };
 }
 interface Model {
     id: string;
@@ -811,6 +830,17 @@ declare class LLMClient {
      * cost_log.jsonl is a single source of truth regardless of caller.
      */
     private recordCost;
+    /**
+     * Parse the chat response JSON and attach `fallback` metadata when the
+     * gateway signalled a transparent free-fallback substitution. The
+     * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+     * on the response when it served a paid request from a free model
+     * (route.ts createPaymentResponseHeader path). Without surfacing these
+     * to the caller, the user gets a different model than requested with
+     * no visibility — silent quality drop and no clue why the on-chain
+     * balance didn't change.
+     */
+    private parseChatResponse;
     /**
      * Make a request with automatic x402 payment handling.
      */

package/dist/index.js

@@ -686,6 +686,28 @@ var LLMClient = class _LLMClient {
     } catch {
     }
   }
+  /**
+   * Parse the chat response JSON and attach `fallback` metadata when the
+   * gateway signalled a transparent free-fallback substitution. The
+   * gateway sets X-Fallback-Used / X-Fallback-Model / X-Settlement-Skipped
+   * on the response when it served a paid request from a free model
+   * (route.ts createPaymentResponseHeader path). Without surfacing these
+   * to the caller, the user gets a different model than requested with
+   * no visibility — silent quality drop and no clue why the on-chain
+   * balance didn't change.
+   */
+  async parseChatResponse(response) {
+    const body = await response.json();
+    const used = response.headers.get("X-Fallback-Used") === "true";
+    if (used) {
+      body.fallback = {
+        used: true,
+        model: response.headers.get("X-Fallback-Model") || void 0,
+        settlementSkipped: response.headers.get("X-Settlement-Skipped") === "free-fallback"
+      };
+    }
+    return body;
+  }
   /**
    * Make a request with automatic x402 payment handling.
    */
@@ -714,7 +736,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
         }
-        return retryResp.json();
+        return this.parseChatResponse(retryResp);
       }
     }
     if (response.status === 402) {
@@ -733,7 +755,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    return response.json();
+    return this.parseChatResponse(response);
   }
   /**
    * Handle 402 response: parse requirements, sign payment, retry.
@@ -808,7 +830,7 @@ var LLMClient = class _LLMClient {
         this.sessionCalls += 1;
         this.sessionTotalUsd += costUsd2;
         this.recordCost(url, costUsd2, { body, network: details.network });
-        return retryResp2.json();
+        return this.parseChatResponse(retryResp2);
       }
     }
     if (retryResponse.status === 402) {
@@ -831,7 +853,7 @@ var LLMClient = class _LLMClient {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
     this.recordCost(url, costUsd, { body, network: details.network });
-    return retryResponse.json();
+    return this.parseChatResponse(retryResponse);
   }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music) via x402 on Base and Solana",
   "main": "dist/index.cjs",