@blockrun/llm 2.4.0 → 2.5.0

package/README.md

@@ -41,6 +41,53 @@ const response = await client.chat('openai/gpt-4o', 'Hello!');
 
 That's it. The SDK handles x402 payment automatically.
 
+## `BlockrunClient` — the universal primitive (recommended for new code)
+
+Starting in `2.5.0`, the SDK ships a single `BlockrunClient` that speaks to
+**every** BlockRun endpoint over x402. New API surfaces are intended to be
+distributed as [Claude Code skills](https://github.com/anthropics/skills)
+that drive this primitive — no SDK release required to add an endpoint.
+
+```typescript
+import { BlockrunClient } from '@blockrun/llm';
+
+const br = new BlockrunClient();
+
+// Sync GET — Surf market price (Tier 1, $0.001)
+const btc = await br.get('/v1/surf/market/price', { symbol: 'BTC' });
+
+// Sync POST — raw on-chain SQL (Tier 3, $0.020)
+const rows = await br.post('/v1/surf/onchain/sql', {
+  query: 'SELECT block_number FROM ethereum.blocks ORDER BY block_number DESC LIMIT 1',
+});
+
+// Submit + poll — long-running video gen (settled only on completion)
+const video = await br.poll('/v1/videos/generations', {
+  model: 'xai/grok-imagine-video',
+  prompt: 'a red apple spinning',
+});
+
+// Streaming SSE — chat completions
+for await (const chunk of br.stream('/v1/chat/completions', {
+  model: 'anthropic/claude-sonnet-4-6',
+  messages: [{ role: 'user', content: 'Hi' }],
+  stream: true,
+})) {
+  process.stdout.write(chunk?.choices?.[0]?.delta?.content ?? '');
+}
+```
+
+Four call shapes cover every endpoint type:
+- `get<T>(path, params?)` — synchronous GET (price, ranking, list, news)
+- `post<T>(path, body?)` — synchronous POST (on-chain SQL, search)
+- `poll<T>(path, body?, { budgetMs, intervalMs })` — submit + poll (image, video, music, voice)
+- `stream<T>(path, body?)` — async iterator over SSE chunks (chat)
+
+The per-API client classes (`LLMClient`, `ImageClient`, `VideoClient`,
+`VoiceClient`, `MusicClient`, `SearchClient`, `XClient`, `PriceClient`,
+`SurfClient`) all remain — they will be soft-deprecated in 2.6 (rewritten as
+shims over `BlockrunClient`) and removed in 3.0.
+
 ### Try It Free (No USDC Required)
 
 Want to kick the tires before funding a wallet? Route to BlockRun's free NVIDIA tier:

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   APIError: () => APIError,
   AnthropicClient: () => AnthropicClient,
   BASE_CHAIN_ID: () => BASE_CHAIN_ID,
+  BlockrunClient: () => BlockrunClient,
   BlockrunError: () => BlockrunError,
   ImageClient: () => ImageClient,
   KNOWN_PROVIDERS: () => KNOWN_PROVIDERS,
@@ -3468,8 +3469,386 @@ var SurfClient = class {
   }
 };
 
-// src/wallet.ts
+// src/blockrun.ts
 var import_accounts11 = require("viem/accounts");
+var DEFAULT_API_URL10 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT10 = 6e4;
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_POLL_BUDGET_MS = 3e5;
+var MAX_SIGNED_AUTH_SECONDS = 600;
+var BlockrunClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  sessionTotalUsd = 0;
+  sessionCalls = 0;
+  constructor(options = {}) {
+    const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
+    const privateKey = options.privateKey || envKey;
+    if (!privateKey) {
+      throw new Error(
+        "Private key required. Pass privateKey in options or set BLOCKRUN_WALLET_KEY environment variable."
+      );
+    }
+    validatePrivateKey(privateKey);
+    this.privateKey = privateKey;
+    this.account = (0, import_accounts11.privateKeyToAccount)(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL10;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
+  }
+  /**
+   * GET a BlockRun endpoint. `path` is everything after `/api` (a leading
+   * `/api` is tolerated and stripped). Query params are URL-encoded; arrays
+   * become repeated keys (`?a=1&a=2`); undefined/null are dropped.
+   */
+  async get(path5, params) {
+    const url = this.buildUrl(path5, params);
+    return this.requestWithPayment(url, "GET");
+  }
+  /**
+   * POST a BlockRun endpoint with a JSON body.
+   */
+  async post(path5, body) {
+    const url = this.buildUrl(path5);
+    return this.requestWithPayment(url, "POST", body);
+  }
+  /**
+   * Submit a long-running job and poll until it completes.
+   *
+   * Pattern: submit → 402 → sign → 202 `{ id, poll_url, status }` → loop GET
+   * the poll_url with the SAME `PAYMENT-SIGNATURE` until status=completed (or
+   * deadline exceeded). Settlement happens only when upstream returns 200 +
+   * completed — upstream failure or caller giving up = no charge.
+   *
+   * If the gateway returns 200 directly on submit (no async surface), this
+   * short-circuits and returns the body. Most long-running endpoints (image,
+   * video, music, voice) return 202 with a poll_url.
+   */
+  async poll(path5, body, options) {
+    const submitUrl = this.buildUrl(path5);
+    const budgetMs = options?.budgetMs ?? DEFAULT_POLL_BUDGET_MS;
+    const intervalMs = options?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const resp402 = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body ?? {})
+    });
+    if (resp402.status === 200) {
+      return resp402.json();
+    }
+    if (resp402.status !== 402) {
+      await this.throwApiError(resp402, `poll submit failed (${submitUrl})`);
+    }
+    const paymentPayload = await this.signFrom402(resp402, submitUrl, {
+      description: "BlockRun async job",
+      maxTimeoutSeconds: MAX_SIGNED_AUTH_SECONDS
+    });
+    const submitResp = await this.fetchWithTimeout(submitUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "PAYMENT-SIGNATURE": paymentPayload
+      },
+      body: JSON.stringify(body ?? {})
+    });
+    if (submitResp.status === 402) {
+      throw new PaymentError("Payment was rejected. Check your wallet balance.");
+    }
+    if (submitResp.status !== 200 && submitResp.status !== 202) {
+      await this.throwApiError(submitResp, `poll submit failed (${submitUrl})`);
+    }
+    if (submitResp.status === 200) {
+      this.recordSpending();
+      return submitResp.json();
+    }
+    const submitData = await submitResp.json();
+    if (!submitData.id || !submitData.poll_url) {
+      throw new APIError(
+        "Async submit response missing id/poll_url",
+        submitResp.status,
+        { response: submitData }
+      );
+    }
+    const pollUrl = this.absolute(submitData.poll_url);
+    const deadline = Date.now() + budgetMs;
+    let lastStatus = submitData.status || "queued";
+    while (Date.now() < deadline) {
+      await sleep(intervalMs);
+      const pollResp = await this.fetchWithTimeout(pollUrl, {
+        method: "GET",
+        headers: { "PAYMENT-SIGNATURE": paymentPayload }
+      });
+      let pollData = {};
+      try {
+        pollData = await pollResp.json();
+      } catch {
+      }
+      lastStatus = pollData.status || lastStatus;
+      if (pollResp.status === 202 && (lastStatus === "queued" || lastStatus === "in_progress")) {
+        continue;
+      }
+      if (lastStatus === "failed") {
+        throw new APIError(
+          `Upstream job failed: ${pollData.error || "unknown"}`,
+          pollResp.status,
+          sanitizeErrorResponse(pollData)
+        );
+      }
+      if (pollResp.status === 200 && lastStatus === "completed") {
+        this.recordSpending();
+        return pollData;
+      }
+      if (pollResp.status !== 200 && pollResp.status !== 202 && pollResp.status !== 504) {
+        await this.throwApiError(pollResp, `poll failed (${pollUrl})`);
+      }
+    }
+    throw new APIError(
+      `Job did not complete within ${Math.round(budgetMs / 1e3)}s (last status: ${lastStatus}). No payment was taken.`,
+      504,
+      { id: submitData.id, last_status: lastStatus }
+    );
+  }
+  /**
+   * Stream a Server-Sent Events endpoint.
+   *
+   * Yields each `data: …` line parsed as JSON. Stops when the upstream emits
+   * `data: [DONE]` or closes the connection. Caller is responsible for typing
+   * the chunk shape; pass a generic for typed yields.
+   *
+   * Example — streaming chat:
+   *   for await (const chunk of br.stream<ChatChunk>("/v1/chat/completions", {
+   *     model: "anthropic/claude-sonnet-4-6",
+   *     messages: [{ role: "user", content: "Hi" }],
+   *     stream: true,
+   *   })) {
+   *     process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
+   *   }
+   */
+  async *stream(path5, body) {
+    const url = this.buildUrl(path5);
+    const requestBody = JSON.stringify(body ?? {});
+    const resp402 = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: requestBody
+    });
+    let streamResp;
+    if (resp402.status === 200) {
+      streamResp = resp402;
+    } else if (resp402.status === 402) {
+      const paymentPayload = await this.signFrom402(resp402, url, {
+        description: "BlockRun stream"
+      });
+      streamResp = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: requestBody
+      });
+      if (streamResp.status === 402) {
+        throw new PaymentError(
+          "Payment was rejected. Check your wallet balance."
+        );
+      }
+      if (!streamResp.ok) {
+        await this.throwApiError(streamResp, `stream failed after payment (${url})`);
+      }
+      this.recordSpending();
+    } else {
+      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();
+    }
+  }
+  // --------------------------------------------------------------------
+  // Internal: shared infrastructure
+  // --------------------------------------------------------------------
+  buildUrl(path5, params) {
+    let normalized = path5.startsWith("/") ? path5 : `/${path5}`;
+    if (normalized.startsWith("/api/")) {
+      normalized = normalized.slice(4);
+    }
+    const base = `${this.apiUrl}${normalized}`;
+    if (!params) return base;
+    const qs = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) {
+          if (v === void 0 || v === null) continue;
+          qs.append(key, String(v));
+        }
+      } else {
+        qs.append(key, String(value));
+      }
+    }
+    const query = qs.toString();
+    return query ? `${base}?${query}` : base;
+  }
+  absolute(url) {
+    if (url.startsWith("http://") || url.startsWith("https://")) return url;
+    const base = this.apiUrl.endsWith("/api") ? this.apiUrl.slice(0, -"/api".length) : this.apiUrl;
+    return `${base}${url}`;
+  }
+  async requestWithPayment(url, method, body) {
+    const init = { method };
+    if (method === "POST") {
+      init.headers = { "Content-Type": "application/json" };
+      init.body = JSON.stringify(body ?? {});
+    }
+    const response = await this.fetchWithTimeout(url, init);
+    if (response.status === 402) {
+      return this.handlePaymentAndRetry(url, method, body, response);
+    }
+    if (!response.ok) {
+      await this.throwApiError(response, `${method} ${url} failed`);
+    }
+    return response.json();
+  }
+  async handlePaymentAndRetry(url, method, body, response) {
+    const paymentPayload = await this.signFrom402(response, url, {
+      description: "BlockRun"
+    });
+    const retryInit = {
+      method,
+      headers: { "PAYMENT-SIGNATURE": paymentPayload }
+    };
+    if (method === "POST") {
+      retryInit.headers = {
+        ...retryInit.headers,
+        "Content-Type": "application/json"
+      };
+      retryInit.body = JSON.stringify(body ?? {});
+    }
+    const retry = await this.fetchWithTimeout(url, retryInit);
+    if (retry.status === 402) {
+      throw new PaymentError(
+        "Payment was rejected. Check your wallet balance."
+      );
+    }
+    if (!retry.ok) {
+      await this.throwApiError(retry, `${method} ${url} failed after payment`);
+    }
+    this.recordSpending();
+    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`).
+   */
+  async signFrom402(response, url, opts) {
+    let paymentHeader = response.headers.get("payment-required");
+    if (!paymentHeader) {
+      try {
+        const respBody = await response.json();
+        if (respBody.x402Version !== void 0 || respBody.accepts !== void 0) {
+          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);
+    this.pendingCostUsd = parseFloat(details.amount) / 1e6;
+    return createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || opts.description,
+        maxTimeoutSeconds: Math.max(
+          details.maxTimeoutSeconds || 0,
+          opts.maxTimeoutSeconds || 300
+        ),
+        extra: details.extra
+      }
+    );
+  }
+  /** Accumulates the most-recent pending cost; settled by recordSpending. */
+  pendingCostUsd = 0;
+  recordSpending() {
+    if (this.pendingCostUsd > 0) {
+      this.sessionCalls += 1;
+      this.sessionTotalUsd += this.pendingCostUsd;
+      this.pendingCostUsd = 0;
+    }
+  }
+  async throwApiError(resp, prefix) {
+    let errorBody;
+    try {
+      errorBody = await resp.json();
+    } catch {
+      errorBody = { error: "Request failed" };
+    }
+    throw new APIError(
+      `${prefix}: HTTP ${resp.status}`,
+      resp.status,
+      sanitizeErrorResponse(errorBody)
+    );
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  // --------------------------------------------------------------------
+  // Public surface: wallet + spending
+  // --------------------------------------------------------------------
+  getWalletAddress() {
+    return this.account.address;
+  }
+  getSpending() {
+    return { totalUsd: this.sessionTotalUsd, calls: this.sessionCalls };
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/wallet.ts
+var import_accounts12 = require("viem/accounts");
 var fs2 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 var os2 = __toESM(require("os"), 1);
@@ -3478,8 +3857,8 @@ var BASE_CHAIN_ID2 = "8453";
 var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
-  const privateKey = (0, import_accounts11.generatePrivateKey)();
-  const account = (0, import_accounts11.privateKeyToAccount)(privateKey);
+  const privateKey = (0, import_accounts12.generatePrivateKey)();
+  const account = (0, import_accounts12.privateKeyToAccount)(privateKey);
   return {
     address: account.address,
     privateKey
@@ -3535,12 +3914,12 @@ function loadWallet() {
 function getOrCreateWallet() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    const account = (0, import_accounts11.privateKeyToAccount)(envKey);
+    const account = (0, import_accounts12.privateKeyToAccount)(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = (0, import_accounts11.privateKeyToAccount)(fileKey);
+    const account = (0, import_accounts12.privateKeyToAccount)(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -3550,11 +3929,11 @@ function getOrCreateWallet() {
 function getWalletAddress() {
   const envKey = typeof process !== "undefined" && process.env ? process.env.BLOCKRUN_WALLET_KEY || process.env.BASE_CHAIN_WALLET_KEY : void 0;
   if (envKey) {
-    return (0, import_accounts11.privateKeyToAccount)(envKey).address;
+    return (0, import_accounts12.privateKeyToAccount)(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return (0, import_accounts11.privateKeyToAccount)(fileKey).address;
+    return (0, import_accounts12.privateKeyToAccount)(fileKey).address;
   }
   return null;
 }
@@ -3734,7 +4113,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT10 = 6e4;
+var DEFAULT_TIMEOUT11 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3759,7 +4138,7 @@ var SolanaLLMClient = class {
     validateApiUrl(apiUrl);
     this.apiUrl = apiUrl.replace(/\/$/, "");
     this.rpcUrl = options.rpcUrl || "https://api.mainnet-beta.solana.com";
-    this.timeout = options.timeout || DEFAULT_TIMEOUT10;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4666,7 +5045,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-var import_accounts12 = require("viem/accounts");
+var import_accounts13 = require("viem/accounts");
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4679,7 +5058,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = (0, import_accounts12.privateKeyToAccount)(this._privateKey);
+    this._account = (0, import_accounts13.privateKeyToAccount)(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4778,6 +5157,7 @@ var AnthropicClient = class {
   APIError,
   AnthropicClient,
   BASE_CHAIN_ID,
+  BlockrunClient,
   BlockrunError,
   ImageClient,
   KNOWN_PROVIDERS,