@blockrun/llm 3.24.8 → 3.24.9

package/dist/index.js

@@ -423,13 +423,44 @@ function readSettlement(response, quotedUsd, scheme) {
   };
   return { costUsd, settlement };
 }
+function settlementSkipReason(response) {
+  const headers = response.headers;
+  if (typeof headers?.get !== "function") return void 0;
+  const reason = [headers.get("X-Settlement-Skipped"), headers.get("X-Payment-Waived")].map((value) => value?.trim()).find((value) => !!value && !NOT_A_SKIP.test(value));
+  if (reason === void 0) return void 0;
+  const evidence = settlementEvidence(response);
+  if (evidence !== void 0) {
+    console.error(
+      `[@blockrun/llm] settlement: the gateway named a skipped settlement (${JSON.stringify(reason)}) on a response that also carries ${evidence}; booked as charged`
+    );
+    return void 0;
+  }
+  return reason;
+}
+var NOT_A_SKIP = /^(false|0|no|none)$/i;
+function settlementEvidence(response) {
+  const header = response.headers.get("PAYMENT-RESPONSE") ?? response.headers.get("X-PAYMENT-RESPONSE");
+  const receipt = header ? decode(header) : void 0;
+  if (receipt && receipt.success !== false) {
+    if (typeof receipt.transaction === "string" && receipt.transaction) return "a settlement receipt with a transaction";
+    const extra = receipt.extra;
+    const charged = receiptChargedUsd({
+      amount: receipt.amount,
+      extra: extra && typeof extra === "object" ? extra : void 0
+    });
+    if (charged !== void 0 && charged > 0) return "a settlement receipt with a charge";
+  }
+  if (response.headers.get("X-Payment-Receipt")?.trim()) return "an X-Payment-Receipt transaction";
+  return void 0;
+}
 function settlementSkipped(response) {
-  return response.headers.get("X-Settlement-Skipped") === "free-fallback";
+  return settlementSkipReason(response) !== void 0;
 }
 function withCost(body, response, bookedUsd, scheme) {
-  if (settlementSkipped(response)) {
+  const skipped = settlementSkipReason(response);
+  if (skipped !== void 0) {
     body.costUsd = 0;
-    body.settlement = { ...readSettlement(response, bookedUsd, scheme).settlement, skipped: "free-fallback" };
+    body.settlement = { ...readSettlement(response, bookedUsd, scheme).settlement, skipped };
     return body;
   }
   body.costUsd = bookedUsd;
@@ -4958,7 +4989,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.24.8";
+var SDK_VERSION = "3.24.9";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5554,9 +5585,9 @@ var LLMClient = class _LLMClient {
     return this.bookPaid(url, body, details, retryResponse);
   }
   /**
-   * Book a served, paid chat call and attach its cost. A response the gateway
-   * served from a free fallback with settlement skipped
-   * (`X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
+   * Book a served, paid chat call and attach its cost. A response whose
+   * settlement the gateway skipped ({@link settlementSkipped}: e.g.
+   * `X-Settlement-Skipped: free-fallback`) moved nothing on chain, so it is
    * not added to `getSpending()` or the cost log, and reports `costUsd: 0`.
    */
   async bookPaid(url, body, details, response) {
@@ -5568,6 +5599,21 @@ var LLMClient = class _LLMClient {
     }
     return withCost(await this.parseChatResponse(response), response, costUsd, "exact");
   }
+  /**
+   * Book a served, paid raw (non-chat) call: the signed amount goes to
+   * `getSpending()` and the cost log, unless the gateway skipped settlement
+   * ({@link settlementSkipped}: e.g. `X-Settlement-Skipped: empty-result` on an
+   * empty prediction-market search, `unexecuted` on a JSON-RPC call that never
+   * ran, or `X-Payment-Waived`), in which case nothing moved and nothing is
+   * booked. `X-Payment-Settled: false` alone is still booked: it is owed.
+   */
+  bookPaidRaw(url, details, response, body) {
+    if (settlementSkipped(response)) return;
+    const costUsd = parseFloat(details.amount) / 1e6;
+    this.sessionCalls += 1;
+    this.sessionTotalUsd += costUsd;
+    this.recordCost(url, costUsd, body ? { body, network: details.network } : { network: details.network });
+  }
   /**
    * Sign a payment header and return the PAYMENT-SIGNATURE value.
    * Extracted to share logic between streaming and non-streaming flows.
@@ -5668,8 +5714,10 @@ var LLMClient = class _LLMClient {
           throw withDisposition(err, "paid-or-in-doubt");
         }
         if (preAuthResp.ok) {
-          this.sessionCalls += 1;
-          this.sessionTotalUsd += signed.costUsd;
+          if (!settlementSkipped(preAuthResp)) {
+            this.sessionCalls += 1;
+            this.sessionTotalUsd += signed.costUsd;
+          }
           return preAuthResp;
         }
         this.preAuthCache.delete(cacheKey2);
@@ -5734,8 +5782,10 @@ var LLMClient = class _LLMClient {
       }
       throw new APIError(`API error after payment: ${streamResp.status}`, streamResp.status, sanitizeErrorResponse(errorBody));
     }
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    if (!settlementSkipped(streamResp)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += costUsd;
+    }
     return streamResp;
   }
   /**
@@ -5859,10 +5909,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error after payment: ${retryResp2.status}`, retryResp2.status, sanitizeErrorResponse(errorBody));
         }
-        const costUsd2 = parseFloat(details.amount) / 1e6;
-        this.sessionCalls += 1;
-        this.sessionTotalUsd += costUsd2;
-        this.recordCost(url, costUsd2, { body, network: details.network });
+        this.bookPaidRaw(url, details, retryResp2, body);
         return retryResp2.json();
       }
     }
@@ -5882,10 +5929,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
-    this.recordCost(url, costUsd, { body, network: details.network });
+    this.bookPaidRaw(url, details, retryResponse, body);
     return retryResponse.json();
   }
   /**
@@ -6005,10 +6049,7 @@ var LLMClient = class _LLMClient {
           }
           throw new APIError(`API error after payment: ${retryResp2.status}`, retryResp2.status, sanitizeErrorResponse(errorBody));
         }
-        const costUsd2 = parseFloat(details.amount) / 1e6;
-        this.sessionCalls += 1;
-        this.sessionTotalUsd += costUsd2;
-        this.recordCost(url, costUsd2, { network: details.network });
+        this.bookPaidRaw(url, details, retryResp2);
         return retryResp2.json();
       }
     }
@@ -6028,10 +6069,7 @@ var LLMClient = class _LLMClient {
         sanitizeErrorResponse(errorBody)
       );
     }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
-    this.recordCost(url, costUsd, { network: details.network });
+    this.bookPaidRaw(url, details, retryResponse);
     return retryResponse.json();
   }
   /**
@@ -7044,8 +7082,10 @@ var MusicClient = class {
       throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
     }
     const data = await retryResponse.json();
-    this.sessionCalls++;
-    this.sessionTotalUsd += 0.1575;
+    if (!settlementSkipped(retryResponse)) {
+      this.sessionCalls++;
+      this.sessionTotalUsd += 0.1575;
+    }
     const txHash = retryResponse.headers.get("x-payment-receipt") || retryResponse.headers.get("X-Payment-Receipt");
     if (txHash) data.txHash = txHash;
     return data;
@@ -7257,9 +7297,11 @@ var SpeechClient = class {
       throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
     }
     const data = await retryResponse.json();
-    this.sessionCalls++;
-    const paidUsd = Number(details.amount) / 1e6;
-    if (Number.isFinite(paidUsd)) this.sessionTotalUsd += paidUsd;
+    if (!settlementSkipped(retryResponse)) {
+      this.sessionCalls++;
+      const paidUsd = Number(details.amount) / 1e6;
+      if (Number.isFinite(paidUsd)) this.sessionTotalUsd += paidUsd;
+    }
     const txHash = retryResponse.headers.get("x-payment-receipt") || retryResponse.headers.get("X-Payment-Receipt");
     if (txHash) data.txHash = txHash;
     return data;
@@ -7556,8 +7598,10 @@ var VideoClient = class {
       }
       if (lastStatus === "completed") {
         const data = pollData;
-        this.sessionCalls++;
-        this.sessionTotalUsd += Number(details.amount) / 1e6;
+        if (!settlementSkipped(pollResp)) {
+          this.sessionCalls++;
+          this.sessionTotalUsd += Number(details.amount) / 1e6;
+        }
         const txHash = pollResp.headers.get("x-payment-receipt") || pollResp.headers.get("X-Payment-Receipt");
         if (txHash) data.txHash = txHash;
         return data;
@@ -7852,8 +7896,10 @@ var VoiceClient = class {
       throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
     }
     const data = await retryResponse.json();
-    this.sessionCalls++;
-    this.sessionTotalUsd += CALL_PRICE_USD;
+    if (!settlementSkipped(retryResponse)) {
+      this.sessionCalls++;
+      this.sessionTotalUsd += CALL_PRICE_USD;
+    }
     const txHash = retryResponse.headers.get("x-payment-receipt") || retryResponse.headers.get("X-Payment-Receipt");
     if (txHash) data.txHash = txHash;
     return data;
@@ -8073,9 +8119,10 @@ var PhoneClient = class {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
     const data = await this.unwrap(retry, true);
-    const costUsd = Number.parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    if (!settlementSkipped(retry)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += Number.parseFloat(details.amount) / 1e6;
+    }
     const txHash = retry.headers.get("x-payment-receipt") || retry.headers.get("X-Payment-Receipt");
     if (txHash && data && typeof data === "object" && !("txHash" in data)) {
       data.txHash = txHash;
@@ -8240,9 +8287,10 @@ var PortraitClient = class {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
     const data = await this.unwrap(retry, true);
-    const costUsd = Number.parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    if (!settlementSkipped(retry)) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += Number.parseFloat(details.amount) / 1e6;
+    }
     if (data && typeof data === "object" && !("txHash" in data)) {
       const settlement = data.settlement;
       if (settlement?.tx_hash) {
@@ -9059,9 +9107,11 @@ var RpcClient = class {
       }
       throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
     }
-    this.sessionCalls++;
-    const paidUsd = Number(details.amount) / 1e6;
-    if (Number.isFinite(paidUsd)) this.sessionTotalUsd += paidUsd;
+    if (!settlementSkipped(retryResponse)) {
+      this.sessionCalls++;
+      const paidUsd = Number(details.amount) / 1e6;
+      if (Number.isFinite(paidUsd)) this.sessionTotalUsd += paidUsd;
+    }
     return { data: await retryResponse.json(), headers: retryResponse.headers };
   }
   async fetchWithTimeout(url, options) {
@@ -9208,7 +9258,7 @@ var BlockrunClient = class {
     if (resp402.status !== 402) {
       await this.throwApiError(resp402, `poll submit failed (${submitUrl})`);
     }
-    const paymentPayload = await this.signFrom402(resp402, submitUrl, {
+    const { paymentPayload, costUsd } = await this.signFrom402(resp402, submitUrl, {
       description: "BlockRun async job",
       maxTimeoutSeconds: MAX_SIGNED_AUTH_SECONDS
     });
@@ -9227,7 +9277,7 @@ var BlockrunClient = class {
       await this.throwApiError(submitResp, `poll submit failed (${submitUrl})`);
     }
     if (submitResp.status === 200) {
-      this.recordSpending();
+      this.recordSpending(submitResp, costUsd);
       return submitResp.json();
     }
     const submitData = await submitResp.json();
@@ -9264,7 +9314,7 @@ var BlockrunClient = class {
         );
       }
       if (pollResp.status === 200 && lastStatus === "completed") {
-        this.recordSpending();
+        this.recordSpending(pollResp, costUsd);
         return pollData;
       }
       if (pollResp.status !== 200 && pollResp.status !== 202 && pollResp.status !== 504) {
@@ -9305,7 +9355,7 @@ var BlockrunClient = class {
     if (resp402.status === 200) {
       streamResp = resp402;
     } else if (resp402.status === 402) {
-      const paymentPayload = await this.signFrom402(resp402, url, {
+      const { paymentPayload, costUsd } = await this.signFrom402(resp402, url, {
         description: "BlockRun stream"
       });
       streamResp = await this.fetchWithTimeout(url, {
@@ -9324,7 +9374,7 @@ var BlockrunClient = class {
       if (!streamResp.ok) {
         await this.throwApiError(streamResp, `stream failed after payment (${url})`);
       }
-      this.recordSpending();
+      this.recordSpending(streamResp, costUsd);
     } else {
       await this.throwApiError(resp402, `stream failed (${url})`);
       return;
@@ -9380,7 +9430,7 @@ var BlockrunClient = class {
     return response.json();
   }
   async handlePaymentAndRetry(url, method, body, response) {
-    const paymentPayload = await this.signFrom402(response, url, {
+    const { paymentPayload, costUsd } = await this.signFrom402(response, url, {
       description: "BlockRun"
     });
     const retryInit = {
@@ -9403,13 +9453,14 @@ var BlockrunClient = class {
     if (!retry.ok) {
       await this.throwApiError(retry, `${method} ${url} failed after payment`);
     }
-    this.recordSpending();
+    this.recordSpending(retry, costUsd);
     return retry.json();
   }
   /**
    * Read a 402 response's payment requirements (header or body), then sign and
-   * return the base64 PAYMENT-SIGNATURE payload. Also records the cost-to-be
-   * onto the response context (settled on `recordSpending`).
+   * return the base64 PAYMENT-SIGNATURE payload with what it pays, in USD.
+   * The cost stays with the call that signed it (booked by `recordSpending`):
+   * concurrent calls on one client never share it.
    */
   async signFrom402(response, url, opts) {
     let paymentHeader = response.headers.get("payment-required");
@@ -9427,8 +9478,8 @@ var BlockrunClient = class {
     }
     const paymentRequired = parsePaymentRequired(paymentHeader);
     const details = extractPaymentDetails(paymentRequired);
-    this.pendingCostUsd = parseFloat(details.amount) / 1e6;
-    return createPaymentPayload(
+    const costUsd = parseFloat(details.amount) / 1e6;
+    const paymentPayload = await createPaymentPayload(
       this.privateKey,
       this.account.address,
       details.recipient,
@@ -9445,14 +9496,20 @@ var BlockrunClient = class {
         asset: details.asset
       }
     );
+    return { paymentPayload, costUsd };
   }
-  /** Accumulates the most-recent pending cost; settled by recordSpending. */
-  pendingCostUsd = 0;
-  recordSpending() {
-    if (this.pendingCostUsd > 0) {
+  /**
+   * Book `costUsd`, what the call that `response` answered signed. A response
+   * whose settlement the gateway skipped ({@link settlementSkipped}:
+   * `X-Settlement-Skipped: <reason>` or `X-Payment-Waived`) moved nothing, so
+   * nothing is booked. `X-Payment-Settled: false` alone is still booked: the
+   * payment is owed.
+   */
+  recordSpending(response, costUsd) {
+    if (settlementSkipped(response)) return;
+    if (costUsd > 0) {
       this.sessionCalls += 1;
-      this.sessionTotalUsd += this.pendingCostUsd;
-      this.pendingCostUsd = 0;
+      this.sessionTotalUsd += costUsd;
     }
   }
   async throwApiError(resp, prefix) {
@@ -11671,6 +11728,8 @@ var SolanaBatchPayer = class {
                 wallet.refusedFor = outcome.errorReason;
               }
             }
+          } else if (built.key && outcome.reason === "payment_required" && outcome.refusedForMs === void 0) {
+            await this.recheckRefusedChannel(wallet, built.key, built.reclaimAnchor);
           }
           sent = void 0;
           release();
@@ -11938,6 +11997,13 @@ var SolanaBatchPayer = class {
   }
   /** Build a new batch payment for a 402: the payload, its headers and its kind. */
   async buildPayment(wallet, paymentRequired) {
+    const acceptKey = channelKeyOf(trustedBatchAccept(paymentRequired, this.init.options.operators));
+    let reclaimAnchor;
+    try {
+      const stored = acceptKey ? await wallet.book.base.get(acceptKey) : void 0;
+      reclaimAnchor = stored ? savedReclaimAnchor(stored) : void 0;
+    } catch {
+    }
     const { http, payload } = await this.createPayload(wallet, paymentRequired);
     const scope = payScope.getStore();
     if (scope?.afterError) {
@@ -11959,7 +12025,16 @@ var SolanaBatchPayer = class {
       const record = known?.record;
       kind = record && (record.pending === void 0 || record.hasConfirmedState) ? "top-up" : "open";
     }
-    return { http, payload, headers, kind, key: known?.key, sentAt: Date.now(), sends: 0 };
+    return {
+      http,
+      payload,
+      headers,
+      kind,
+      key: known?.key,
+      ...reclaimAnchor !== void 0 && known?.key === acceptKey ? { reclaimAnchor } : {},
+      sentAt: Date.now(),
+      sends: 0
+    };
   }
   /**
    * Write a deposit's intent to the wallet's journal before it is sent
@@ -12193,6 +12268,84 @@ var SolanaBatchPayer = class {
       }
     }
   }
+  /**
+   * Queue a re-read of a stored channel whose account is gone at finalized
+   * and at confirmed commitment (closed, its account reclaimed), anchored at
+   * the SDK's own `getBlockHeight` at confirmed. The anchor is saved in the
+   * record (`reclaimAnchorHeight`), so a short-lived process finishes the
+   * wait instead of starting it over; a failed read leaves resync to take it,
+   * and a failed save only costs that. resync pays exact until finality is
+   * LANDING_MARGIN_BLOCKS past the anchor, then drops the record if the
+   * finalized chain still has no account (a lagging read finds the channel
+   * and rewrites the record, without the anchor).
+   */
+  async queueReclaimed(wallet, key, record, channelId, savedAnchor) {
+    let anchorHeight = savedReclaimAnchor(record) ?? savedAnchor;
+    if (anchorHeight === void 0) {
+      try {
+        anchorHeight = rpcInteger(
+          await rpcRequest(this.init.rpcUrl, "getBlockHeight", [{ commitment: "confirmed" }], this.init.rpcHeaders),
+          "getBlockHeight"
+        );
+      } catch {
+      }
+    }
+    if (anchorHeight !== void 0 && savedReclaimAnchor(record) !== anchorHeight) {
+      try {
+        await wallet.book.set(key, { ...record, reclaimAnchorHeight: anchorHeight });
+      } catch {
+      }
+    }
+    addResyncTarget(wallet, {
+      key,
+      channelId,
+      channelConfig: record.channelConfig,
+      cumulative: parseAtomic(record.chargedCumulativeAmount),
+      knownDeposit: parseAtomic(record.deposit),
+      ...anchorHeight !== void 0 ? { anchorHeight } : {},
+      reason: "channel_unusable"
+    });
+  }
+  /**
+   * After the gateway refused an authorization with a plain 402 (no receipt,
+   * not an admission refusal), check the channel it paid into. That is how
+   * the gateway answers an authorization into a channel the facilitator
+   * closed (its verify rejects it), and a channel with deposit to spare is
+   * otherwise never read again: every call would sign another authorization
+   * into it and pay exact. A channel the finalized chain shows closing,
+   * closed or not this wallet's is re-read through resync (record dropped,
+   * or kept and paid exact); one gone at every commitment is queued as
+   * {@link queueReclaimed}; an open one of this wallet's, or one only at
+   * confirmed (not finalized yet), is left as it is. A queued re-read is run
+   * at once. Best effort: a failed read changes nothing, and the next
+   * refusal checks again.
+   */
+  async recheckRefusedChannel(wallet, key, savedAnchor) {
+    try {
+      const record = await wallet.book.get(key);
+      if (!record || record.pending || typeof record.channelId !== "string" || wallet.resyncs.has(key)) return;
+      const channelId = record.channelId;
+      const channel = await readChannelAccount(this.init.rpcUrl, channelId, this.init.rpcHeaders);
+      if (channel !== void 0) {
+        if (channel.open && channel.payer === await this.init.address() && channel.authorizedSigner === record.channelConfig.payerAuthorizer && channel.mint === record.channelConfig.token) {
+          return;
+        }
+        addResyncTarget(wallet, {
+          key,
+          channelId,
+          channelConfig: record.channelConfig,
+          cumulative: parseAtomic(record.chargedCumulativeAmount),
+          knownDeposit: parseAtomic(record.deposit),
+          reason: "channel_unusable"
+        });
+      } else {
+        if (await readChannelAccount(this.init.rpcUrl, channelId, this.init.rpcHeaders, { commitment: "confirmed" }) !== void 0) return;
+        await this.queueReclaimed(wallet, key, record, channelId, savedAnchor);
+      }
+      await this.resync(wallet);
+    } catch {
+    }
+  }
   /**
    * When this payment will top up the wallet's channel, read how much of its
    * deposit is already settled on-chain (at `finalized` commitment, so never
@@ -12246,31 +12399,7 @@ var SolanaBatchPayer = class {
     }
     if (channel === void 0 && unfinalized) return;
     if (channel === void 0) {
-      let anchorHeight = savedReclaimAnchor(record);
-      if (anchorHeight === void 0) {
-        try {
-          anchorHeight = rpcInteger(
-            await rpcRequest(this.init.rpcUrl, "getBlockHeight", [{ commitment: "confirmed" }], this.init.rpcHeaders),
-            "getBlockHeight"
-          );
-        } catch {
-        }
-        if (anchorHeight !== void 0) {
-          try {
-            await wallet.book.set(key, { ...record, reclaimAnchorHeight: anchorHeight });
-          } catch {
-          }
-        }
-      }
-      addResyncTarget(wallet, {
-        key,
-        channelId: record.channelId,
-        channelConfig: record.channelConfig,
-        cumulative: parseAtomic(record.chargedCumulativeAmount),
-        knownDeposit: deposit,
-        ...anchorHeight !== void 0 ? { anchorHeight } : {},
-        reason: "channel_unusable"
-      });
+      await this.queueReclaimed(wallet, key, record, record.channelId);
       throw new ChannelResyncRequiredError(record.channelId);
     }
     if (!channel.open || channel.payer !== await this.init.address() || channel.authorizedSigner !== record.channelConfig.payerAuthorizer || channel.mint !== record.channelConfig.token) {
@@ -12907,7 +13036,7 @@ var SolanaLLMClient = class {
           body: requestBody
         });
         await this.assertPaid(paid);
-        this.recordSettlement(costUsd);
+        this.recordSettlement(costUsd, paid);
         return paid;
       } catch (error) {
         if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
@@ -13294,7 +13423,7 @@ var SolanaLLMClient = class {
               closesAtStart
             );
             if (batch.kind === "paid") {
-              this.recordSettlement(batch.chargedUsd);
+              this.recordSettlement(batch.chargedUsd, batch.response);
               const paid = await this.readPaidJson(batch.response);
               return withCost(paid, batch.response, batch.chargedUsd, "batch");
             }
@@ -13411,7 +13540,7 @@ var SolanaLLMClient = class {
     };
     const deliver = (data, response) => {
       if (kind === "video") {
-        if (videoCostUsd !== void 0) this.recordSettlement(videoCostUsd);
+        if (videoCostUsd !== void 0) this.recordSettlement(videoCostUsd, response);
         const txHash = response.headers.get("x-payment-receipt");
         if (txHash) data.txHash = txHash;
       }
@@ -13658,7 +13787,7 @@ var SolanaLLMClient = class {
       throw withDisposition(error, "paid-or-in-doubt");
     }
     await this.assertPaid(retryResponse);
-    if (!settlementSkipped(retryResponse)) this.recordSettlement(costUsd);
+    this.recordSettlement(costUsd, retryResponse);
     const paid = await this.readPaidJson(retryResponse);
     return withCost(paid, retryResponse, costUsd, "exact");
   }
@@ -13718,11 +13847,11 @@ var SolanaLLMClient = class {
     await this.assertPaid(retryResponse);
     if (retryResponse.status === 202) {
       const kind = pollKindFor(url);
-      if (kind !== "video") this.recordSettlement(costUsd);
+      if (kind !== "video") this.recordSettlement(costUsd, retryResponse);
       const submitted = await retryResponse.json();
       return this.followSolanaJob(submitted, media.pollBudgetMs ?? this.timeout, kind);
     }
-    this.recordSettlement(costUsd);
+    this.recordSettlement(costUsd, retryResponse);
     return retryResponse.json();
   }
   async getWithPaymentRaw(endpoint, params) {
@@ -13766,7 +13895,7 @@ var SolanaLLMClient = class {
       }
     });
     await this.assertPaid(retryResponse);
-    this.recordSettlement(costUsd);
+    this.recordSettlement(costUsd, retryResponse);
     return retryResponse.json();
   }
   /**
@@ -13804,8 +13933,17 @@ var SolanaLLMClient = class {
       );
     }
   }
-  /** Count one settled x402 payment against the session total. */
-  recordSettlement(costUsd) {
+  /**
+   * Count one settled x402 payment against the session total.
+   *
+   * Takes the paid response so no booking site can forget the check: a
+   * response whose settlement the gateway skipped ({@link settlementSkipped}:
+   * `X-Settlement-Skipped: free-fallback | empty-result | unexecuted | …`, or
+   * `X-Payment-Waived`) moved nothing on chain and books nothing.
+   * `X-Payment-Settled: false` alone is still booked: the payment is owed.
+   */
+  recordSettlement(costUsd, response) {
+    if (settlementSkipped(response)) return;
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.24.8",
+  "version": "3.24.9",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",