@blockrun/llm 3.24.8 → 3.24.9

package/dist/index.d.cts

@@ -231,12 +231,13 @@ interface Settlement {
     /** Present and false only when the gateway reported a failed settlement. */
     success?: false;
     /**
-     * `"free-fallback"` when the gateway served a paid request from a free
-     * fallback model and skipped settlement (`X-Settlement-Skipped`): nothing
+     * Why the gateway served this paid request without settling it, from
+     * `X-Settlement-Skipped` (else `X-Payment-Waived`): `"free-fallback"` when a
+     * free fallback model answered, or another reason the gateway names. Nothing
      * moved on chain, so `costUsd` is 0 and nothing was added to `getSpending()`.
      * `quotedUsd` still states what was signed.
      */
-    skipped?: "free-fallback";
+    skipped?: "free-fallback" | (string & {});
 }
 interface FunctionCall {
     name: string;
@@ -1491,12 +1492,21 @@ declare class LLMClient {
     /** Send the signed payment and read the answer. The payment may settle from here on. */
     private sendPaid;
     /**
-     * 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`.
      */
     private bookPaid;
+    /**
+     * 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.
+     */
+    private bookPaidRaw;
     /**
      * Sign a payment header and return the PAYMENT-SIGNATURE value.
      * Extracted to share logic between streaming and non-streaming flows.
@@ -2517,12 +2527,18 @@ declare class BlockrunClient {
     private handlePaymentAndRetry;
     /**
      * 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.
      */
     private signFrom402;
-    /** Accumulates the most-recent pending cost; settled by recordSpending. */
-    private pendingCostUsd;
+    /**
+     * 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.
+     */
     private recordSpending;
     private throwApiError;
     private fetchWithTimeout;
@@ -3492,6 +3508,33 @@ declare class SolanaBatchPayer {
      * once.
      */
     private createPayload;
+    /**
+     * 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).
+     */
+    private queueReclaimed;
+    /**
+     * 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.
+     */
+    private recheckRefusedChannel;
     /**
      * 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
@@ -4016,7 +4059,15 @@ declare class SolanaLLMClient {
      *   first is marked `"paid-or-in-doubt"`: the payment may have settled.
      */
     private assertPaid;
-    /** Count one settled x402 payment against the session total. */
+    /**
+     * 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.
+     */
     private recordSettlement;
     private fetchWithTimeout;
 }

package/dist/index.d.ts

@@ -231,12 +231,13 @@ interface Settlement {
     /** Present and false only when the gateway reported a failed settlement. */
     success?: false;
     /**
-     * `"free-fallback"` when the gateway served a paid request from a free
-     * fallback model and skipped settlement (`X-Settlement-Skipped`): nothing
+     * Why the gateway served this paid request without settling it, from
+     * `X-Settlement-Skipped` (else `X-Payment-Waived`): `"free-fallback"` when a
+     * free fallback model answered, or another reason the gateway names. Nothing
      * moved on chain, so `costUsd` is 0 and nothing was added to `getSpending()`.
      * `quotedUsd` still states what was signed.
      */
-    skipped?: "free-fallback";
+    skipped?: "free-fallback" | (string & {});
 }
 interface FunctionCall {
     name: string;
@@ -1491,12 +1492,21 @@ declare class LLMClient {
     /** Send the signed payment and read the answer. The payment may settle from here on. */
     private sendPaid;
     /**
-     * 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`.
      */
     private bookPaid;
+    /**
+     * 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.
+     */
+    private bookPaidRaw;
     /**
      * Sign a payment header and return the PAYMENT-SIGNATURE value.
      * Extracted to share logic between streaming and non-streaming flows.
@@ -2517,12 +2527,18 @@ declare class BlockrunClient {
     private handlePaymentAndRetry;
     /**
      * 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.
      */
     private signFrom402;
-    /** Accumulates the most-recent pending cost; settled by recordSpending. */
-    private pendingCostUsd;
+    /**
+     * 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.
+     */
     private recordSpending;
     private throwApiError;
     private fetchWithTimeout;
@@ -3492,6 +3508,33 @@ declare class SolanaBatchPayer {
      * once.
      */
     private createPayload;
+    /**
+     * 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).
+     */
+    private queueReclaimed;
+    /**
+     * 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.
+     */
+    private recheckRefusedChannel;
     /**
      * 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
@@ -4016,7 +4059,15 @@ declare class SolanaLLMClient {
      *   first is marked `"paid-or-in-doubt"`: the payment may have settled.
      */
     private assertPaid;
-    /** Count one settled x402 payment against the session total. */
+    /**
+     * 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.
+     */
     private recordSettlement;
     private fetchWithTimeout;
 }