@blockrun/llm 3.14.3 → 3.15.0

package/dist/index.js

@@ -158,6 +158,21 @@ function validateResourceUrl(url, baseUrl) {
 var TRANSIENT_STATUS = /* @__PURE__ */ new Set([502, 503, 504, 522, 524]);
 var TRANSIENT_RETRIES = 2;
 var TRANSIENT_BACKOFF_MS = 1e3;
+function retryDelay(ms, signal) {
+  signal?.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 var API_KEY_URL = "https://api.blockrun.ai";
 var PORTAL_URL = "https://user.blockrun.ai";
 function resolveApiKeyAuth(options) {
@@ -207,6 +222,7 @@ var ApiKeyAuth = class {
     headers.set("authorization", `Bearer ${this.#key}`);
     const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
     const retries = method === "GET" || method === "HEAD" ? TRANSIENT_RETRIES : 0;
+    const signal = init?.signal ?? request?.signal;
     let response;
     for (let attempt = 0; ; attempt++) {
       response = await globalThis.fetch(request ? new Request(url, request) : url, {
@@ -215,7 +231,8 @@ var ApiKeyAuth = class {
         redirect: "error"
       });
       if (attempt >= retries || !TRANSIENT_STATUS.has(response.status)) break;
-      await new Promise((resolve) => setTimeout(resolve, TRANSIENT_BACKOFF_MS * (attempt + 1)));
+      await response.body?.cancel();
+      await retryDelay(TRANSIENT_BACKOFF_MS * (attempt + 1), signal);
     }
     if (raiseErrors && !response.ok) {
       let body;
@@ -4483,7 +4500,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.14.3";
+var SDK_VERSION = "3.15.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -6744,7 +6761,7 @@ var VideoClient = class {
    * Submits an async job, then polls until the video is ready. Typical total
    * wall-time is 60-180s, but upstream status can lag several minutes behind
    * actual completion. If upstream runs past the budget (default 15min),
-   * throws without charging — the job stays claimable ~48h via poll_url.
+   * throws with the existing poll URL; check billing before submitting again.
    *
    * @param prompt - Text description of the video
    * @param options - Optional generation parameters
@@ -6944,7 +6961,7 @@ var VideoClient = class {
       }
     }
     throw new APIError(
-      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken. The job is NOT lost: it stays claimable for ~48h \u2014 re-GET poll_url with a fresh signature from the same wallet to fetch (and settle) the finished video.`,
+      `Video generation did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). A polling timeout does not confirm billing status. Resume the existing poll_url using the same account or wallet; check account Activity or wallet receipts before submitting another job.`,
       504,
       { id: submitData.id, last_status: lastStatus, poll_url: pollUrl }
     );
@@ -8436,6 +8453,35 @@ var RpcClient = class {
   }
 };
 
+// src/sse.ts
+async function* readSseFrames(response, onMissingBody) {
+  if (!response.body) throw onMissingBody(response.status);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || !trimmed.startsWith("data: ")) continue;
+        const data = trimmed.slice(6);
+        if (data === "[DONE]") return;
+        try {
+          yield JSON.parse(data);
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // src/blockrun.ts
 import { privateKeyToAccount as privateKeyToAccount13 } from "viem/accounts";
 var DEFAULT_API_URL13 = "https://blockrun.ai/api";
@@ -8645,33 +8691,10 @@ var BlockrunClient = class {
       await this.throwApiError(resp402, `stream failed (${url})`);
       return;
     }
-    if (!streamResp.body) {
-      throw new APIError("Stream response has no body", streamResp.status, {});
-    }
-    const reader = streamResp.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
-        buffer = lines.pop() || "";
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed || !trimmed.startsWith("data: ")) continue;
-          const data = trimmed.slice(6);
-          if (data === "[DONE]") return;
-          try {
-            yield JSON.parse(data);
-          } catch {
-          }
-        }
-      }
-    } finally {
-      reader.releaseLock();
-    }
+    yield* readSseFrames(
+      streamResp,
+      (status2) => new APIError("Stream response has no body", status2, {})
+    );
   }
   // --------------------------------------------------------------------
   // Internal: shared infrastructure
@@ -9602,6 +9625,123 @@ var SolanaLLMClient = class {
     response.routing = decision;
     return { response, model: decision.model, routing: decision };
   }
+  /**
+   * Stream a Server-Sent Events endpoint, paid on Solana.
+   *
+   * The Solana counterpart to `BlockrunClient.stream`, and the reason it had to
+   * exist: a streaming harness cannot use this client at all without it, so
+   * "BlockRun supports Solana" stopped being true the moment a caller streamed.
+   * `chatCompletion` buffers the whole answer, which is the wrong shape for an
+   * agent loop and for anything that shows tokens as they arrive.
+   *
+   * The handshake is the one the non-streaming paths use — `402`, sign an SPL
+   * TransferChecked authorization locally, replay with `PAYMENT-SIGNATURE` —
+   * with the same verification-phase re-sign on a stale blockhash. What differs
+   * is that the paid response is not read as JSON: it is handed to the SSE
+   * reader with its body untouched.
+   *
+   * A `200` on the first request is returned as-is and settles nothing. That is
+   * the free tier (the gateway answers a `billing_mode: "free"` model without a
+   * 402 at all) and it is also API-key mode, where billing is on the account
+   * rather than on a wallet.
+   *
+   * Yields each `data:` frame parsed as JSON, and stops at `data: [DONE]`.
+   * Malformed frames are skipped rather than thrown — see {@link readSseFrames}.
+   *
+   * @example
+   * for await (const chunk of client.stream<ChatChunk>("/v1/chat/completions", {
+   *   model: "deepseek/deepseek-chat",
+   *   messages: [{ role: "user", content: "Hi" }],
+   *   stream: true,
+   * })) {
+   *   process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+   * }
+   *
+   * @param path - endpoint after the API root; a leading `/api` is tolerated.
+   * @param body - JSON request body. Set `stream: true` yourself — this method
+   *   does not inject it, because the gateway prices a streaming and a
+   *   non-streaming request the same and silently rewriting a caller's body is
+   *   how you end up debugging a request you did not send.
+   * @returns each decoded SSE frame, in order.
+   */
+  async *stream(path6, body) {
+    const url = this.buildUrl(path6);
+    const response = await this.openPaidStream(url, JSON.stringify(body ?? {}));
+    yield* readSseFrames(
+      response,
+      (status2) => new APIError("Stream response has no body", status2, {})
+    );
+  }
+  /**
+   * Get to a streaming response, paying for it if the gateway asks.
+   *
+   * Separate from {@link SolanaLLMClient.stream} because a generator cannot
+   * retry cleanly around a `yield`: the stale-blockhash re-sign has to finish
+   * before the first frame is handed out, and putting the loop here keeps the
+   * payment decision entirely ahead of any output the caller has seen.
+   *
+   * @param url - resolved endpoint URL.
+   * @param requestBody - the serialized body, reused verbatim on the paid retry
+   *   so the gateway prices and answers the same request it quoted for.
+   * @returns a response whose body has not been read.
+   */
+  async openPaidStream(url, requestBody) {
+    for (let staleRetries = 0; ; ) {
+      const response = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: requestBody
+      });
+      if (response.ok) return response;
+      if (response.status !== 402) {
+        let errorBody;
+        try {
+          errorBody = await response.json();
+        } catch {
+          errorBody = { error: "Request failed" };
+        }
+        throw new APIError(`API error: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
+      }
+      try {
+        const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+          url,
+          response,
+          staleRetries > 0
+        );
+        const paid = await this.fetchWithTimeout(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+            "PAYMENT-SIGNATURE": paymentPayload
+          },
+          body: requestBody
+        });
+        await this.assertPaid(paid);
+        this.recordSettlement(costUsd);
+        return paid;
+      } catch (error) {
+        if (!(error instanceof SafeStaleBlockhashError) || staleRetries >= STALE_BLOCKHASH_RETRY_BACKOFFS_MS.length) throw error;
+        await waitForStaleRetry(staleRetries++);
+        continue;
+      }
+    }
+  }
+  /**
+   * Resolve an endpoint path against this client's API root.
+   *
+   * A leading `/api` is stripped for the same reason `BlockrunClient` strips
+   * it: the documented paths are written `/api/v1/…` on the website and
+   * `/v1/…` in this SDK, and a caller who copies one into the other should get
+   * their request rather than a 404.
+   * @param path - endpoint path, with or without a leading slash.
+   * @returns the absolute URL to call.
+   */
+  buildUrl(path6) {
+    let normalized = path6.startsWith("/") ? path6 : `/${path6}`;
+    if (normalized.startsWith("/api/")) normalized = normalized.slice(4);
+    return `${this.apiUrl}${normalized}`;
+  }
   /** List available models. */
   async listModels() {
     const response = await this.fetchWithTimeout(`${this.apiUrl}/v1/models`, { method: "GET" });
@@ -9872,7 +10012,25 @@ var SolanaLLMClient = class {
       return response.json();
     }
   }
-  async handlePaymentAndRetry(url, body, response, forceFreshBlockhash = false) {
+  /**
+   * Turn a `402` into a signed Solana payment payload.
+   *
+   * Extracted because four call sites need it — chat, the raw POST helpers, the
+   * raw GET helper, and {@link SolanaLLMClient.stream} — and it had been
+   * written out three times before this. That mattered more than ordinary
+   * duplication: this is the code that signs a transfer of the caller's USDC,
+   * so three copies meant every fix to it had to be applied three times or
+   * quietly apply to two thirds of the paths.
+   *
+   * @param url - the request being paid for.
+   * @param response - the gateway's `402`, not yet consumed.
+   * @param forceFreshBlockhash - set on a re-sign after a stale-blockhash
+   *   rejection, so the retry cannot produce byte-identical transaction bytes.
+   * @param resourceFallback - resource URL to claim when the 402 states none.
+   * @returns the header value to replay with, and what it will settle for.
+   * @throws PaymentError when the 402 carries no usable Solana requirements.
+   */
+  async signPaymentFrom402(url, response, forceFreshBlockhash, resourceFallback = url) {
     let paymentHeader = response.headers.get("payment-required");
     if (!paymentHeader) {
       try {
@@ -9906,7 +10064,7 @@ var SolanaLLMClient = class {
       feePayer,
       {
         resourceUrl: validateResourceUrl(
-          details.resource?.url || `${this.apiUrl}/v1/chat/completions`,
+          details.resource?.url || resourceFallback,
           this.apiUrl
         ),
         resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
@@ -9918,6 +10076,15 @@ var SolanaLLMClient = class {
         forceFreshBlockhash
       }
     );
+    return { paymentPayload, costUsd: parseFloat(details.amount) / 1e6 };
+  }
+  async handlePaymentAndRetry(url, body, response, forceFreshBlockhash = false) {
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(
+      url,
+      response,
+      forceFreshBlockhash,
+      `${this.apiUrl}/v1/chat/completions`
+    );
     const retryResponse = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: {
@@ -9927,24 +10094,8 @@ var SolanaLLMClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
-        throw new SafeStaleBlockhashError();
-      }
-      throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
-    }
-    if (!retryResponse.ok) {
-      let errorBody;
-      try {
-        errorBody = await retryResponse.json();
-      } catch {
-        errorBody = { error: "Request failed" };
-      }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
-    }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
     return retryResponse.json();
   }
   async requestWithPaymentRaw(endpoint, body) {
@@ -9978,51 +10129,7 @@ var SolanaLLMClient = class {
     }
   }
   async handlePaymentAndRetryRaw(url, body, response, forceFreshBlockhash = false) {
-    let paymentHeader = response.headers.get("payment-required");
-    if (!paymentHeader) {
-      try {
-        const respBody = await response.json();
-        if (respBody.accepts || respBody.x402Version) {
-          paymentHeader = btoa(JSON.stringify(respBody));
-        }
-      } catch {
-      }
-    }
-    if (!paymentHeader) {
-      throw new PaymentError("402 response but no payment requirements found");
-    }
-    const paymentRequired = parsePaymentRequired(paymentHeader);
-    const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
-    if (!details.network?.startsWith("solana:")) {
-      throw new PaymentError(
-        `Expected Solana payment network, got: ${details.network}. Use LLMClient for Base payments.`
-      );
-    }
-    const feePayer = details.extra?.feePayer;
-    if (!feePayer) throw new PaymentError("Missing feePayer in 402 extra field");
-    const fromAddress = await this.getWalletAddress();
-    const secretKey = await solanaKeyToBytes(this.privateKey);
-    const extensions = paymentRequired.extensions;
-    const paymentPayload = await createSolanaPaymentPayload(
-      secretKey,
-      fromAddress,
-      details.recipient,
-      details.amount,
-      feePayer,
-      {
-        resourceUrl: validateResourceUrl(
-          details.resource?.url || url,
-          this.apiUrl
-        ),
-        resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
-        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
-        extra: details.extra,
-        extensions,
-        rpcUrl: this.rpcUrl,
-        rpcHeaders: this.rpcHeaders,
-        forceFreshBlockhash
-      }
-    );
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(url, response, forceFreshBlockhash);
     const retryResponse = await this.fetchWithTimeout(url, {
       method: "POST",
       headers: {
@@ -10032,24 +10139,8 @@ var SolanaLLMClient = class {
       },
       body: JSON.stringify(body)
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
-        throw new SafeStaleBlockhashError();
-      }
-      throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
-    }
-    if (!retryResponse.ok) {
-      let errorBody;
-      try {
-        errorBody = await retryResponse.json();
-      } catch {
-        errorBody = { error: "Request failed" };
-      }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
-    }
-    const costUsd = parseFloat(details.amount) / 1e6;
-    this.sessionCalls += 1;
-    this.sessionTotalUsd += costUsd;
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
     return retryResponse.json();
   }
   async getWithPaymentRaw(endpoint, params) {
@@ -10082,51 +10173,7 @@ var SolanaLLMClient = class {
     }
   }
   async handleGetPaymentAndRetryRaw(url, endpoint, params, response, forceFreshBlockhash = false) {
-    let paymentHeader = response.headers.get("payment-required");
-    if (!paymentHeader) {
-      try {
-        const respBody = await response.json();
-        if (respBody.accepts || respBody.x402Version) {
-          paymentHeader = btoa(JSON.stringify(respBody));
-        }
-      } catch {
-      }
-    }
-    if (!paymentHeader) {
-      throw new PaymentError("402 response but no payment requirements found");
-    }
-    const paymentRequired = parsePaymentRequired(paymentHeader);
-    const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
-    if (!details.network?.startsWith("solana:")) {
-      throw new PaymentError(
-        `Expected Solana payment network, got: ${details.network}. Use LLMClient for Base payments.`
-      );
-    }
-    const feePayer = details.extra?.feePayer;
-    if (!feePayer) throw new PaymentError("Missing feePayer in 402 extra field");
-    const fromAddress = await this.getWalletAddress();
-    const secretKey = await solanaKeyToBytes(this.privateKey);
-    const extensions = paymentRequired.extensions;
-    const paymentPayload = await createSolanaPaymentPayload(
-      secretKey,
-      fromAddress,
-      details.recipient,
-      details.amount,
-      feePayer,
-      {
-        resourceUrl: validateResourceUrl(
-          details.resource?.url || url,
-          this.apiUrl
-        ),
-        resourceDescription: details.resource?.description || "BlockRun Solana AI API call",
-        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
-        extra: details.extra,
-        extensions,
-        rpcUrl: this.rpcUrl,
-        rpcHeaders: this.rpcHeaders,
-        forceFreshBlockhash
-      }
-    );
+    const { paymentPayload, costUsd } = await this.signPaymentFrom402(url, response, forceFreshBlockhash);
     const query = params ? "?" + new URLSearchParams(params).toString() : "";
     const retryUrl = `${this.apiUrl}${endpoint}${query}`;
     const retryResponse = await this.fetchWithTimeout(retryUrl, {
@@ -10136,25 +10183,44 @@ var SolanaLLMClient = class {
         "PAYMENT-SIGNATURE": paymentPayload
       }
     });
-    if (retryResponse.status === 402) {
-      if (await isSafeStaleBlockhashResponse(retryResponse)) {
+    await this.assertPaid(retryResponse);
+    this.recordSettlement(costUsd);
+    return retryResponse.json();
+  }
+  /**
+   * Fail a post-payment response, telling a re-signable rejection from a real one.
+   *
+   * A `402` here is not "pay again": it is the gateway refusing the payment we
+   * just signed. Only a rejection the gateway attributes to the VERIFICATION
+   * phase is safe to re-sign — anything settled, or ambiguous about which
+   * phase it failed in, could already have moved USDC, and re-signing it would
+   * pay twice. {@link isSafeStaleBlockhashResponse} is where that judgement
+   * lives.
+   * @param response - the reply to the paid request.
+   * @throws SafeStaleBlockhashError when the caller should re-sign, PaymentError
+   *   when it should not, APIError for any other failure.
+   */
+  async assertPaid(response) {
+    if (response.status === 402) {
+      if (await isSafeStaleBlockhashResponse(response)) {
         throw new SafeStaleBlockhashError();
       }
       throw new PaymentError("Payment was rejected. Check your Solana USDC balance.");
     }
-    if (!retryResponse.ok) {
+    if (!response.ok) {
       let errorBody;
       try {
-        errorBody = await retryResponse.json();
+        errorBody = await response.json();
       } catch {
         errorBody = { error: "Request failed" };
       }
-      throw new APIError(`API error after payment: ${retryResponse.status}`, retryResponse.status, sanitizeErrorResponse(errorBody));
+      throw new APIError(`API error after payment: ${response.status}`, response.status, sanitizeErrorResponse(errorBody));
     }
-    const costUsd = parseFloat(details.amount) / 1e6;
+  }
+  /** Count one settled x402 payment against the session total. */
+  recordSettlement(costUsd) {
     this.sessionCalls += 1;
     this.sessionTotalUsd += costUsd;
-    return retryResponse.json();
   }
   async fetchWithTimeout(url, options) {
     const controller = new AbortController();
@@ -10558,7 +10624,8 @@ var OpenAI = class {
   }
   client;
   constructor(options = {}) {
-    const privateKey = options.walletKey || options.privateKey;
+    const aliases = [options.walletKey, options.privateKey].filter((k) => k !== void 0);
+    const privateKey = aliases.find((k) => k !== "") ?? aliases[0];
     const apiUrl = resolveApiKeyAuth({ apiKey: options.apiKey, privateKey, apiUrl: options.baseURL })?.apiUrl ?? options.baseURL ?? "https://blockrun.ai/api";
     const timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.client = new LLMClient({
@@ -10617,7 +10684,9 @@ var AnthropicClient = class {
       this._client = new Anthropic({
         baseURL: this._apiUrl,
         apiKey: "blockrun",
-        fetch: this._x402Fetch.bind(this)
+        fetch: this._x402Fetch.bind(this),
+        // Account POSTs may already be billed when an upstream error arrives.
+        ...this.apiAuth ? { maxRetries: 0 } : {}
       });
       return this._client;
     })();
@@ -10626,6 +10695,10 @@ var AnthropicClient = class {
   async _x402Fetch(input, init) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this._timeout);
+    const callerSignal = init?.signal ?? (input instanceof Request ? input.signal : void 0);
+    const onAbort = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", onAbort, { once: true });
+    if (callerSignal?.aborted) onAbort();
     try {
       const mergedInit = { ...init, signal: controller.signal };
       if (this.apiAuth) return await this.apiAuth.fetch(input, mergedInit, false);
@@ -10679,6 +10752,7 @@ var AnthropicClient = class {
       }
       return response;
     } finally {
+      callerSignal?.removeEventListener("abort", onAbort);
       clearTimeout(timeoutId);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.14.3",
+  "version": "3.15.0",
   "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",
@@ -22,7 +22,8 @@
     "dev": "tsup --watch",
     "test": "vitest",
     "lint": "eslint src/",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:package": "npm run build && node scripts/check-package.mjs"
   },
   "keywords": [
     "llm",
@@ -52,9 +53,7 @@
   },
   "dependencies": {
     "bs58": "^6.0.0",
-    "viem": "^2.56.3"
-  },
-  "optionalDependencies": {
+    "viem": "^2.56.3",
     "@anthropic-ai/sdk": "^0.123.0"
   },
   "devDependencies": {