@blockrun/llm 2.3.0 → 2.5.0

package/dist/index.js

@@ -3215,8 +3215,541 @@ function buildUrl(base, query) {
   return `${base}?${qs}`;
 }
 
+// src/surf.ts
+import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
+var DEFAULT_API_URL9 = "https://blockrun.ai/api";
+var DEFAULT_TIMEOUT9 = 6e4;
+var SURF_PREFIX = "/v1/surf";
+var SurfClient = class {
+  account;
+  privateKey;
+  apiUrl;
+  timeout;
+  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 = privateKeyToAccount9(privateKey);
+    const apiUrl = options.apiUrl || DEFAULT_API_URL9;
+    validateApiUrl(apiUrl);
+    this.apiUrl = apiUrl.replace(/\/$/, "");
+    this.timeout = options.timeout || DEFAULT_TIMEOUT9;
+  }
+  /**
+   * GET a Surf endpoint. `path` is everything after `/v1/surf` (a leading
+   * `/v1/surf` is tolerated and stripped). Query params are URL-encoded;
+   * arrays become repeated keys (`?a=1&a=2`).
+   */
+  async get(path5, params) {
+    const url = this.buildUrl(path5, params);
+    return this.requestWithPayment(url, "GET");
+  }
+  /**
+   * POST a Surf endpoint with a JSON body. Same path normalization as `get`.
+   */
+  async post(path5, body) {
+    const url = this.buildUrl(path5);
+    return this.requestWithPayment(url, "POST", body);
+  }
+  buildUrl(path5, params) {
+    let normalized = path5.startsWith("/") ? path5 : `/${path5}`;
+    if (!normalized.startsWith(SURF_PREFIX)) {
+      normalized = `${SURF_PREFIX}${normalized}`;
+    }
+    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;
+  }
+  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, `Surf request failed (${method} ${url})`);
+    }
+    return response.json();
+  }
+  async handlePaymentAndRetry(url, method, body, response) {
+    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);
+    const paymentPayload = await createPaymentPayload(
+      this.privateKey,
+      this.account.address,
+      details.recipient,
+      details.amount,
+      details.network || "eip155:8453",
+      {
+        resourceUrl: details.resource?.url || url,
+        resourceDescription: details.resource?.description || "BlockRun Surf",
+        maxTimeoutSeconds: details.maxTimeoutSeconds || 300,
+        extra: details.extra
+      }
+    );
+    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, `Surf request failed after payment (${method} ${url})`);
+    }
+    return retry.json();
+  }
+  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);
+    }
+  }
+  getWalletAddress() {
+    return this.account.address;
+  }
+};
+
+// src/blockrun.ts
+import { privateKeyToAccount as privateKeyToAccount10 } from "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 = privateKeyToAccount10(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
-import { privateKeyToAccount as privateKeyToAccount9, generatePrivateKey } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount11, generatePrivateKey } from "viem/accounts";
 import * as fs2 from "fs";
 import * as path2 from "path";
 import * as os2 from "os";
@@ -3226,7 +3759,7 @@ var WALLET_DIR = path2.join(os2.homedir(), ".blockrun");
 var WALLET_FILE = path2.join(WALLET_DIR, ".session");
 function createWallet() {
   const privateKey = generatePrivateKey();
-  const account = privateKeyToAccount9(privateKey);
+  const account = privateKeyToAccount11(privateKey);
   return {
     address: account.address,
     privateKey
@@ -3282,12 +3815,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 = privateKeyToAccount9(envKey);
+    const account = privateKeyToAccount11(envKey);
     return { address: account.address, privateKey: envKey, isNew: false };
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    const account = privateKeyToAccount9(fileKey);
+    const account = privateKeyToAccount11(fileKey);
     return { address: account.address, privateKey: fileKey, isNew: false };
   }
   const { address, privateKey } = createWallet();
@@ -3297,11 +3830,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 privateKeyToAccount9(envKey).address;
+    return privateKeyToAccount11(envKey).address;
   }
   const fileKey = loadWallet();
   if (fileKey) {
-    return privateKeyToAccount9(fileKey).address;
+    return privateKeyToAccount11(fileKey).address;
   }
   return null;
 }
@@ -3481,7 +4014,7 @@ async function getOrCreateSolanaWallet() {
 // src/solana-client.ts
 var SOLANA_API_URL = "https://sol.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS2 = 1024;
-var DEFAULT_TIMEOUT9 = 6e4;
+var DEFAULT_TIMEOUT11 = 6e4;
 var SDK_VERSION2 = "0.3.0";
 var USER_AGENT2 = `blockrun-ts/${SDK_VERSION2}`;
 var SolanaLLMClient = class {
@@ -3506,7 +4039,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_TIMEOUT9;
+    this.timeout = options.timeout || DEFAULT_TIMEOUT11;
   }
   /** Get Solana wallet address (public key in base58). */
   async getWalletAddress() {
@@ -4413,7 +4946,7 @@ var OpenAI = class {
 };
 
 // src/anthropic-compat.ts
-import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount12 } from "viem/accounts";
 var AnthropicClient = class {
   _client = null;
   _clientPromise = null;
@@ -4426,7 +4959,7 @@ var AnthropicClient = class {
     const key = options.privateKey ?? wallet.privateKey;
     validatePrivateKey(key);
     this._privateKey = key;
-    this._account = privateKeyToAccount10(this._privateKey);
+    this._account = privateKeyToAccount12(this._privateKey);
     const apiUrl = options.apiUrl ?? "https://blockrun.ai/api";
     validateApiUrl(apiUrl);
     this._apiUrl = apiUrl.replace(/\/$/, "");
@@ -4524,6 +5057,7 @@ export {
   APIError,
   AnthropicClient,
   BASE_CHAIN_ID,
+  BlockrunClient,
   BlockrunError,
   ImageClient,
   KNOWN_PROVIDERS,
@@ -4536,6 +5070,7 @@ export {
   SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH,
   SearchClient,
   SolanaLLMClient,
+  SurfClient,
   USDC_BASE,
   USDC_BASE_CONTRACT,
   USDC_SOLANA,

package/package.json

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