@blockrun/llm 1.4.3 → 1.5.0

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   BASE_CHAIN_ID: () => BASE_CHAIN_ID,
   BlockrunError: () => BlockrunError,
   ImageClient: () => ImageClient,
+  KNOWN_PROVIDERS: () => KNOWN_PROVIDERS,
   LLMClient: () => LLMClient,
   OpenAI: () => OpenAI,
   PaymentError: () => PaymentError,
@@ -58,6 +59,7 @@ __export(index_exports, {
   formatWalletCreatedMessage: () => formatWalletCreatedMessage,
   getCached: () => getCached,
   getCachedByRequest: () => getCachedByRequest,
+  getCostLogSummary: () => getCostLogSummary,
   getCostSummary: () => getCostSummary,
   getEip681Uri: () => getEip681Uri,
   getOrCreateSolanaWallet: () => getOrCreateSolanaWallet,
@@ -80,7 +82,11 @@ __export(index_exports, {
   solanaKeyToBytes: () => solanaKeyToBytes,
   solanaPublicKey: () => solanaPublicKey,
   status: () => status,
-  testnetClient: () => testnetClient
+  testnetClient: () => testnetClient,
+  validateMaxTokens: () => validateMaxTokens,
+  validateModel: () => validateModel,
+  validateTemperature: () => validateTemperature,
+  validateTopP: () => validateTopP
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -302,6 +308,61 @@ function extractPaymentDetails(paymentRequired, preferredNetwork) {
 
 // src/validation.ts
 var LOCALHOST_DOMAINS = ["localhost", "127.0.0.1"];
+var KNOWN_PROVIDERS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "deepseek",
+  "mistralai",
+  "meta-llama",
+  "together",
+  "xai",
+  "moonshot",
+  "nvidia",
+  "minimax",
+  "zai"
+]);
+function validateModel(model) {
+  if (!model || typeof model !== "string") {
+    throw new Error("Model must be a non-empty string");
+  }
+}
+function validateMaxTokens(maxTokens) {
+  if (maxTokens === void 0 || maxTokens === null) {
+    return;
+  }
+  if (typeof maxTokens !== "number" || !Number.isInteger(maxTokens)) {
+    throw new Error("maxTokens must be an integer");
+  }
+  if (maxTokens < 1) {
+    throw new Error("maxTokens must be positive (minimum: 1)");
+  }
+  if (maxTokens > 1e5) {
+    throw new Error("maxTokens too large (maximum: 100000)");
+  }
+}
+function validateTemperature(temperature) {
+  if (temperature === void 0 || temperature === null) {
+    return;
+  }
+  if (typeof temperature !== "number") {
+    throw new Error("temperature must be a number");
+  }
+  if (temperature < 0 || temperature > 2) {
+    throw new Error("temperature must be between 0 and 2");
+  }
+}
+function validateTopP(topP) {
+  if (topP === void 0 || topP === null) {
+    return;
+  }
+  if (typeof topP !== "number") {
+    throw new Error("topP must be a number");
+  }
+  if (topP < 0 || topP > 1) {
+    throw new Error("topP must be between 0 and 1");
+  }
+}
 function validatePrivateKey(key) {
   if (typeof key !== "string") {
     throw new Error("Private key must be a string");
@@ -377,7 +438,7 @@ var DEFAULT_API_URL = "https://blockrun.ai/api";
 var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
   static DEFAULT_API_URL = DEFAULT_API_URL;
@@ -414,13 +475,13 @@ var LLMClient = class {
   /**
    * Simple 1-line chat interface.
    *
-   * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+   * @param model - Model ID (e.g., 'openai/gpt-5.2', 'anthropic/claude-sonnet-4.6')
    * @param prompt - User message
    * @param options - Optional chat parameters
    * @returns Assistant's response text
    *
    * @example
-   * const response = await client.chat('gpt-4o', 'What is the capital of France?');
+   * const response = await client.chat('gpt-5.2', 'What is the capital of France?');
    * console.log(response); // 'The capital of France is Paris.'
    */
   async chat(model, prompt, options) {
@@ -566,6 +627,27 @@ var LLMClient = class {
       headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: JSON.stringify(body)
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handlePaymentAndRetry(url, body, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handlePaymentAndRetry(url, body, response);
     }
@@ -631,6 +713,34 @@ var LLMClient = class {
       },
       body: JSON.stringify(body)
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -663,6 +773,27 @@ var LLMClient = class {
       headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: JSON.stringify(body)
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handlePaymentAndRetryRaw(url, body, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handlePaymentAndRetryRaw(url, body, response);
     }
@@ -728,6 +859,34 @@ var LLMClient = class {
       },
       body: JSON.stringify(body)
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -760,6 +919,26 @@ var LLMClient = class {
       method: "GET",
       headers: { "User-Agent": USER_AGENT }
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT }
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handleGetPaymentAndRetryRaw(url, endpoint, params, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handleGetPaymentAndRetryRaw(url, endpoint, params, response);
     }
@@ -825,6 +1004,32 @@ var LLMClient = class {
         "PAYMENT-SIGNATURE": paymentPayload
       }
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(retryUrl, {
+        method: "GET",
+        headers: {
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        }
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -2293,6 +2498,8 @@ var path3 = __toESM(require("path"), 1);
 var os3 = __toESM(require("os"), 1);
 var crypto2 = __toESM(require("crypto"), 1);
 var CACHE_DIR = path3.join(os3.homedir(), ".blockrun", "cache");
+var DATA_DIR = path3.join(os3.homedir(), ".blockrun", "data");
+var COST_LOG_FILE = path3.join(os3.homedir(), ".blockrun", "cost_log.jsonl");
 var DEFAULT_TTL = {
   "/v1/x/": 3600 * 1e3,
   "/v1/partner/": 3600 * 1e3,
@@ -2357,26 +2564,80 @@ function setCache(key, data, ttlMs) {
   } catch {
   }
 }
-function saveToCache(endpoint, body, response, costUsd = 0) {
-  const ttl = getTtl(endpoint);
-  if (ttl <= 0) return;
+function readableFilename(endpoint, body) {
+  const now = /* @__PURE__ */ new Date();
+  const ts = now.toISOString().slice(0, 10) + "_" + String(now.getHours()).padStart(2, "0") + String(now.getMinutes()).padStart(2, "0") + String(now.getSeconds()).padStart(2, "0");
+  let ep = endpoint.replace(/\/+$/, "").split("/").pop() || "";
+  if (endpoint.includes("/v1/chat/")) {
+    ep = "chat";
+  } else if (endpoint.includes("/v1/x/")) {
+    ep = "x_" + ep;
+  } else if (endpoint.includes("/v1/search")) {
+    ep = "search";
+  } else if (endpoint.includes("/v1/image")) {
+    ep = "image";
+  }
+  let label = body.query || body.username || body.handle || body.model || (typeof body.prompt === "string" ? body.prompt.slice(0, 40) : "") || "";
+  label = String(label).replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
+  return label ? `${ep}_${ts}_${label}.json` : `${ep}_${ts}.json`;
+}
+function saveReadable(endpoint, body, response, costUsd) {
   try {
-    fs3.mkdirSync(CACHE_DIR, { recursive: true });
+    fs3.mkdirSync(DATA_DIR, { recursive: true });
   } catch {
   }
-  const key = cacheKey(endpoint, body);
+  const filename = readableFilename(endpoint, body);
   const entry = {
-    cachedAt: Date.now(),
+    saved_at: (/* @__PURE__ */ new Date()).toISOString(),
     endpoint,
-    body,
-    response,
-    costUsd
+    cost_usd: costUsd,
+    request: body,
+    response
   };
   try {
-    fs3.writeFileSync(cachePath(key), JSON.stringify(entry));
+    fs3.writeFileSync(path3.join(DATA_DIR, filename), JSON.stringify(entry, null, 2));
+  } catch {
+  }
+}
+function appendCostLog(endpoint, costUsd) {
+  if (costUsd <= 0) return;
+  try {
+    fs3.mkdirSync(path3.dirname(COST_LOG_FILE), { recursive: true });
+  } catch {
+  }
+  const entry = {
+    ts: Date.now() / 1e3,
+    endpoint,
+    cost_usd: costUsd
+  };
+  try {
+    fs3.appendFileSync(COST_LOG_FILE, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
+function saveToCache(endpoint, body, response, costUsd = 0) {
+  const ttl = getTtl(endpoint);
+  if (ttl > 0) {
+    try {
+      fs3.mkdirSync(CACHE_DIR, { recursive: true });
+    } catch {
+    }
+    const key = cacheKey(endpoint, body);
+    const entry = {
+      cachedAt: Date.now(),
+      endpoint,
+      body,
+      response,
+      costUsd
+    };
+    try {
+      fs3.writeFileSync(cachePath(key), JSON.stringify(entry));
+    } catch {
+    }
+  }
+  saveReadable(endpoint, body, response, costUsd);
+  appendCostLog(endpoint, costUsd);
+}
 function clearCache() {
   if (!fs3.existsSync(CACHE_DIR)) return 0;
   let count = 0;
@@ -2395,6 +2656,32 @@ function clearCache() {
   }
   return count;
 }
+function getCostLogSummary() {
+  if (!fs3.existsSync(COST_LOG_FILE)) {
+    return { totalUsd: 0, calls: 0, byEndpoint: {} };
+  }
+  let totalUsd = 0;
+  let calls = 0;
+  const byEndpoint = {};
+  try {
+    const content = fs3.readFileSync(COST_LOG_FILE, "utf-8").trim();
+    if (!content) return { totalUsd: 0, calls: 0, byEndpoint: {} };
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        const cost = entry.cost_usd ?? 0;
+        const ep = entry.endpoint ?? "unknown";
+        totalUsd += cost;
+        calls += 1;
+        byEndpoint[ep] = (byEndpoint[ep] || 0) + cost;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return { totalUsd, calls, byEndpoint };
+}
 
 // src/setup.ts
 function setupAgentWallet(options) {
@@ -2436,27 +2723,27 @@ async function status() {
 var fs4 = __toESM(require("fs"), 1);
 var path4 = __toESM(require("path"), 1);
 var os4 = __toESM(require("os"), 1);
-var DATA_DIR = path4.join(os4.homedir(), ".blockrun", "data");
-var COST_LOG_FILE = path4.join(DATA_DIR, "costs.jsonl");
+var DATA_DIR2 = path4.join(os4.homedir(), ".blockrun", "data");
+var COST_LOG_FILE2 = path4.join(DATA_DIR2, "costs.jsonl");
 function logCost(entry) {
   try {
-    fs4.mkdirSync(DATA_DIR, { recursive: true });
+    fs4.mkdirSync(DATA_DIR2, { recursive: true });
   } catch {
   }
   try {
-    fs4.appendFileSync(COST_LOG_FILE, JSON.stringify(entry) + "\n");
+    fs4.appendFileSync(COST_LOG_FILE2, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
 function getCostSummary() {
-  if (!fs4.existsSync(COST_LOG_FILE)) {
+  if (!fs4.existsSync(COST_LOG_FILE2)) {
     return { totalUsd: 0, calls: 0, byModel: {} };
   }
   let totalUsd = 0;
   let calls = 0;
   const byModel = {};
   try {
-    const content = fs4.readFileSync(COST_LOG_FILE, "utf-8").trim();
+    const content = fs4.readFileSync(COST_LOG_FILE2, "utf-8").trim();
     if (!content) return { totalUsd: 0, calls: 0, byModel: {} };
     for (const line of content.split("\n")) {
       if (!line) continue;
@@ -2758,6 +3045,7 @@ var AnthropicClient = class {
   BASE_CHAIN_ID,
   BlockrunError,
   ImageClient,
+  KNOWN_PROVIDERS,
   LLMClient,
   OpenAI,
   PaymentError,
@@ -2780,6 +3068,7 @@ var AnthropicClient = class {
   formatWalletCreatedMessage,
   getCached,
   getCachedByRequest,
+  getCostLogSummary,
   getCostSummary,
   getEip681Uri,
   getOrCreateSolanaWallet,
@@ -2802,5 +3091,9 @@ var AnthropicClient = class {
   solanaKeyToBytes,
   solanaPublicKey,
   status,
-  testnetClient
+  testnetClient,
+  validateMaxTokens,
+  validateModel,
+  validateTemperature,
+  validateTopP
 });

package/dist/index.d.cts

@@ -140,10 +140,48 @@ interface SearchParameters {
     toDate?: string;
     maxSearchResults?: number;
 }
+/** Usage info for Live Search sources */
+interface SearchUsage {
+    /** Number of search sources used in the response */
+    numSourcesUsed?: number;
+}
 interface Spending {
     totalUsd: number;
     calls: number;
 }
+/** Pre-request cost estimate for a chat call */
+interface CostEstimate {
+    /** Model ID used for the estimate */
+    model: string;
+    /** Estimated input token count */
+    estimatedInputTokens: number;
+    /** Estimated output token count */
+    estimatedOutputTokens: number;
+    /** Estimated cost in USD */
+    estimatedCostUsd: number;
+}
+/** Per-call spending report with running session totals */
+interface SpendingReport {
+    /** Model ID used */
+    model: string;
+    /** Input tokens consumed */
+    inputTokens: number;
+    /** Output tokens consumed */
+    outputTokens: number;
+    /** Cost of this call in USD */
+    costUsd: number;
+    /** Cumulative session spend in USD */
+    sessionTotalUsd: number;
+    /** Total number of calls in this session */
+    sessionCalls: number;
+}
+/** Chat response bundled with its spending report */
+interface ChatResponseWithCost {
+    /** The chat completion response */
+    response: ChatResponse;
+    /** Spending report for this call */
+    spendingReport: SpendingReport;
+}
 interface ResourceInfo {
     url: string;
     description?: string;
@@ -184,9 +222,9 @@ interface ChatOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
 }
 interface ChatCompletionOptions {
@@ -196,9 +234,9 @@ interface ChatCompletionOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
     /** Tool definitions for function calling */
     tools?: Tool[];
@@ -406,7 +444,7 @@ declare class APIError extends BlockrunError {
  *   // Option 2: Pass private key directly
  *   const client = new LLMClient({ privateKey: '0x...' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   const response = await client.chat('openai/gpt-5.2', 'Hello!');
  *   console.log(response);
  */
 
@@ -454,13 +492,13 @@ declare class LLMClient {
     /**
      * Simple 1-line chat interface.
      *
-     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @param model - Model ID (e.g., 'openai/gpt-5.2', 'anthropic/claude-sonnet-4.6')
      * @param prompt - User message
      * @param options - Optional chat parameters
      * @returns Assistant's response text
      *
      * @example
-     * const response = await client.chat('gpt-4o', 'What is the capital of France?');
+     * const response = await client.chat('gpt-5.2', 'What is the capital of France?');
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
@@ -1108,7 +1146,7 @@ declare const WALLET_DIR_PATH: string;
  *   // Or pass key directly
  *   const client = new SolanaLLMClient({ privateKey: 'your-bs58-key' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'gm Solana');
+ *   const response = await client.chat('openai/gpt-5.2', 'gm Solana');
  */
 
 interface SolanaLLMClientOptions {
@@ -1228,6 +1266,11 @@ declare function getCachedByRequest(endpoint: string, body: Record<string, unkno
 declare function setCache(key: string, data: unknown, ttlMs: number): void;
 declare function saveToCache(endpoint: string, body: Record<string, unknown>, response: unknown, costUsd?: number): void;
 declare function clearCache(): number;
+declare function getCostLogSummary(): {
+    totalUsd: number;
+    calls: number;
+    byEndpoint: Record<string, number>;
+};
 
 /**
  * Agent wallet setup utilities.
@@ -1277,7 +1320,7 @@ declare function getCostSummary(): {
  *
  * // Rest of your code stays exactly the same!
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  */
@@ -1384,7 +1427,7 @@ declare class Chat {
  * const client = new OpenAI({ walletKey: '0x...' });
  *
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  *
@@ -1419,4 +1462,59 @@ declare class AnthropicClient {
     getWalletAddress(): string;
 }
 
-export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type CostEntry, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient };
+/**
+ * Input validation and security utilities for BlockRun LLM SDK.
+ *
+ * This module provides validation functions to ensure:
+ * - Private keys are properly formatted
+ * - API URLs use HTTPS
+ * - Server responses don't leak sensitive information
+ * - Resource URLs match expected domains
+ */
+
+/**
+ * Known LLM providers (for optional validation).
+ */
+declare const KNOWN_PROVIDERS: Set<string>;
+/**
+ * Validates that a model ID is a non-empty string.
+ *
+ * @param model - The model ID (e.g., "openai/gpt-5.2", "anthropic/claude-sonnet-4.5")
+ * @throws {Error} If the model is invalid
+ *
+ * @example
+ * validateModel("openai/gpt-5.2");
+ */
+declare function validateModel(model: string): void;
+/**
+ * Validates that max_tokens is an integer between 1 and 100,000.
+ *
+ * @param maxTokens - Maximum number of tokens to generate
+ * @throws {Error} If maxTokens is invalid
+ *
+ * @example
+ * validateMaxTokens(1000);
+ */
+declare function validateMaxTokens(maxTokens?: number): void;
+/**
+ * Validates that temperature is a number between 0 and 2.
+ *
+ * @param temperature - Sampling temperature (0-2)
+ * @throws {Error} If temperature is invalid
+ *
+ * @example
+ * validateTemperature(0.7);
+ */
+declare function validateTemperature(temperature?: number): void;
+/**
+ * Validates that top_p is a number between 0 and 1.
+ *
+ * @param topP - Top-p sampling parameter (0-1)
+ * @throws {Error} If topP is invalid
+ *
+ * @example
+ * validateTopP(0.9);
+ */
+declare function validateTopP(topP?: number): void;
+
+export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.d.ts

@@ -140,10 +140,48 @@ interface SearchParameters {
     toDate?: string;
     maxSearchResults?: number;
 }
+/** Usage info for Live Search sources */
+interface SearchUsage {
+    /** Number of search sources used in the response */
+    numSourcesUsed?: number;
+}
 interface Spending {
     totalUsd: number;
     calls: number;
 }
+/** Pre-request cost estimate for a chat call */
+interface CostEstimate {
+    /** Model ID used for the estimate */
+    model: string;
+    /** Estimated input token count */
+    estimatedInputTokens: number;
+    /** Estimated output token count */
+    estimatedOutputTokens: number;
+    /** Estimated cost in USD */
+    estimatedCostUsd: number;
+}
+/** Per-call spending report with running session totals */
+interface SpendingReport {
+    /** Model ID used */
+    model: string;
+    /** Input tokens consumed */
+    inputTokens: number;
+    /** Output tokens consumed */
+    outputTokens: number;
+    /** Cost of this call in USD */
+    costUsd: number;
+    /** Cumulative session spend in USD */
+    sessionTotalUsd: number;
+    /** Total number of calls in this session */
+    sessionCalls: number;
+}
+/** Chat response bundled with its spending report */
+interface ChatResponseWithCost {
+    /** The chat completion response */
+    response: ChatResponse;
+    /** Spending report for this call */
+    spendingReport: SpendingReport;
+}
 interface ResourceInfo {
     url: string;
     description?: string;
@@ -184,9 +222,9 @@ interface ChatOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
 }
 interface ChatCompletionOptions {
@@ -196,9 +234,9 @@ interface ChatCompletionOptions {
     temperature?: number;
     /** Nucleus sampling parameter */
     topP?: number;
-    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    /** Enable Live Search (shortcut for searchParameters.mode = "on") */
     search?: boolean;
-    /** Full xAI Live Search configuration (for Grok models) */
+    /** Full Live Search configuration (for search-enabled models) */
     searchParameters?: SearchParameters;
     /** Tool definitions for function calling */
     tools?: Tool[];
@@ -406,7 +444,7 @@ declare class APIError extends BlockrunError {
  *   // Option 2: Pass private key directly
  *   const client = new LLMClient({ privateKey: '0x...' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   const response = await client.chat('openai/gpt-5.2', 'Hello!');
  *   console.log(response);
  */
 
@@ -454,13 +492,13 @@ declare class LLMClient {
     /**
      * Simple 1-line chat interface.
      *
-     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @param model - Model ID (e.g., 'openai/gpt-5.2', 'anthropic/claude-sonnet-4.6')
      * @param prompt - User message
      * @param options - Optional chat parameters
      * @returns Assistant's response text
      *
      * @example
-     * const response = await client.chat('gpt-4o', 'What is the capital of France?');
+     * const response = await client.chat('gpt-5.2', 'What is the capital of France?');
      * console.log(response); // 'The capital of France is Paris.'
      */
     chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
@@ -1108,7 +1146,7 @@ declare const WALLET_DIR_PATH: string;
  *   // Or pass key directly
  *   const client = new SolanaLLMClient({ privateKey: 'your-bs58-key' });
  *
- *   const response = await client.chat('openai/gpt-4o', 'gm Solana');
+ *   const response = await client.chat('openai/gpt-5.2', 'gm Solana');
  */
 
 interface SolanaLLMClientOptions {
@@ -1228,6 +1266,11 @@ declare function getCachedByRequest(endpoint: string, body: Record<string, unkno
 declare function setCache(key: string, data: unknown, ttlMs: number): void;
 declare function saveToCache(endpoint: string, body: Record<string, unknown>, response: unknown, costUsd?: number): void;
 declare function clearCache(): number;
+declare function getCostLogSummary(): {
+    totalUsd: number;
+    calls: number;
+    byEndpoint: Record<string, number>;
+};
 
 /**
  * Agent wallet setup utilities.
@@ -1277,7 +1320,7 @@ declare function getCostSummary(): {
  *
  * // Rest of your code stays exactly the same!
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  */
@@ -1384,7 +1427,7 @@ declare class Chat {
  * const client = new OpenAI({ walletKey: '0x...' });
  *
  * const response = await client.chat.completions.create({
- *   model: 'gpt-4o',
+ *   model: 'gpt-5.2',
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * });
  *
@@ -1419,4 +1462,59 @@ declare class AnthropicClient {
     getWalletAddress(): string;
 }
 
-export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type CostEntry, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient };
+/**
+ * Input validation and security utilities for BlockRun LLM SDK.
+ *
+ * This module provides validation functions to ensure:
+ * - Private keys are properly formatted
+ * - API URLs use HTTPS
+ * - Server responses don't leak sensitive information
+ * - Resource URLs match expected domains
+ */
+
+/**
+ * Known LLM providers (for optional validation).
+ */
+declare const KNOWN_PROVIDERS: Set<string>;
+/**
+ * Validates that a model ID is a non-empty string.
+ *
+ * @param model - The model ID (e.g., "openai/gpt-5.2", "anthropic/claude-sonnet-4.5")
+ * @throws {Error} If the model is invalid
+ *
+ * @example
+ * validateModel("openai/gpt-5.2");
+ */
+declare function validateModel(model: string): void;
+/**
+ * Validates that max_tokens is an integer between 1 and 100,000.
+ *
+ * @param maxTokens - Maximum number of tokens to generate
+ * @throws {Error} If maxTokens is invalid
+ *
+ * @example
+ * validateMaxTokens(1000);
+ */
+declare function validateMaxTokens(maxTokens?: number): void;
+/**
+ * Validates that temperature is a number between 0 and 2.
+ *
+ * @param temperature - Sampling temperature (0-2)
+ * @throws {Error} If temperature is invalid
+ *
+ * @example
+ * validateTemperature(0.7);
+ */
+declare function validateTemperature(temperature?: number): void;
+/**
+ * Validates that top_p is a number between 0 and 1.
+ *
+ * @param topP - Top-p sampling parameter (0-1)
+ * @throws {Error} If topP is invalid
+ *
+ * @example
+ * validateTopP(0.9);
+ */
+declare function validateTopP(topP?: number): void;
+
+export { APIError, AnthropicClient, BASE_CHAIN_ID, type BlockRunAnthropicOptions, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatResponseWithCost, type ChatUsage, type CostEntry, type CostEstimate, type CreatePaymentOptions, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type Model, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsResponse, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XVerifiedFollowersResponse, clearCache, createPaymentPayload, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, extractPaymentDetails, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostLogSummary, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, parsePaymentRequired, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient, validateMaxTokens, validateModel, validateTemperature, validateTopP };

package/dist/index.js

@@ -223,6 +223,61 @@ function extractPaymentDetails(paymentRequired, preferredNetwork) {
 
 // src/validation.ts
 var LOCALHOST_DOMAINS = ["localhost", "127.0.0.1"];
+var KNOWN_PROVIDERS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google",
+  "deepseek",
+  "mistralai",
+  "meta-llama",
+  "together",
+  "xai",
+  "moonshot",
+  "nvidia",
+  "minimax",
+  "zai"
+]);
+function validateModel(model) {
+  if (!model || typeof model !== "string") {
+    throw new Error("Model must be a non-empty string");
+  }
+}
+function validateMaxTokens(maxTokens) {
+  if (maxTokens === void 0 || maxTokens === null) {
+    return;
+  }
+  if (typeof maxTokens !== "number" || !Number.isInteger(maxTokens)) {
+    throw new Error("maxTokens must be an integer");
+  }
+  if (maxTokens < 1) {
+    throw new Error("maxTokens must be positive (minimum: 1)");
+  }
+  if (maxTokens > 1e5) {
+    throw new Error("maxTokens too large (maximum: 100000)");
+  }
+}
+function validateTemperature(temperature) {
+  if (temperature === void 0 || temperature === null) {
+    return;
+  }
+  if (typeof temperature !== "number") {
+    throw new Error("temperature must be a number");
+  }
+  if (temperature < 0 || temperature > 2) {
+    throw new Error("temperature must be between 0 and 2");
+  }
+}
+function validateTopP(topP) {
+  if (topP === void 0 || topP === null) {
+    return;
+  }
+  if (typeof topP !== "number") {
+    throw new Error("topP must be a number");
+  }
+  if (topP < 0 || topP > 1) {
+    throw new Error("topP must be between 0 and 1");
+  }
+}
 function validatePrivateKey(key) {
   if (typeof key !== "string") {
     throw new Error("Private key must be a string");
@@ -298,7 +353,7 @@ var DEFAULT_API_URL = "https://blockrun.ai/api";
 var TESTNET_API_URL = "https://testnet.blockrun.ai/api";
 var DEFAULT_MAX_TOKENS = 1024;
 var DEFAULT_TIMEOUT = 6e4;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "1.5.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 var LLMClient = class {
   static DEFAULT_API_URL = DEFAULT_API_URL;
@@ -335,13 +390,13 @@ var LLMClient = class {
   /**
    * Simple 1-line chat interface.
    *
-   * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+   * @param model - Model ID (e.g., 'openai/gpt-5.2', 'anthropic/claude-sonnet-4.6')
    * @param prompt - User message
    * @param options - Optional chat parameters
    * @returns Assistant's response text
    *
    * @example
-   * const response = await client.chat('gpt-4o', 'What is the capital of France?');
+   * const response = await client.chat('gpt-5.2', 'What is the capital of France?');
    * console.log(response); // 'The capital of France is Paris.'
    */
   async chat(model, prompt, options) {
@@ -487,6 +542,27 @@ var LLMClient = class {
       headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: JSON.stringify(body)
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handlePaymentAndRetry(url, body, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handlePaymentAndRetry(url, body, response);
     }
@@ -552,6 +628,34 @@ var LLMClient = class {
       },
       body: JSON.stringify(body)
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -584,6 +688,27 @@ var LLMClient = class {
       headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
       body: JSON.stringify(body)
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "User-Agent": USER_AGENT },
+        body: JSON.stringify(body)
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handlePaymentAndRetryRaw(url, body, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handlePaymentAndRetryRaw(url, body, response);
     }
@@ -649,6 +774,34 @@ var LLMClient = class {
       },
       body: JSON.stringify(body)
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        },
+        body: JSON.stringify(body)
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -681,6 +834,26 @@ var LLMClient = class {
       method: "GET",
       headers: { "User-Agent": USER_AGENT }
     });
+    if (response.status === 502 || response.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp = await this.fetchWithTimeout(url, {
+        method: "GET",
+        headers: { "User-Agent": USER_AGENT }
+      });
+      if (retryResp.status !== 502 && retryResp.status !== 503) {
+        if (retryResp.status === 402) return this.handleGetPaymentAndRetryRaw(url, endpoint, params, retryResp);
+        if (!retryResp.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          throw new APIError(`API error: ${retryResp.status}`, retryResp.status, sanitizeErrorResponse(errorBody));
+        }
+        return retryResp.json();
+      }
+    }
     if (response.status === 402) {
       return this.handleGetPaymentAndRetryRaw(url, endpoint, params, response);
     }
@@ -746,6 +919,32 @@ var LLMClient = class {
         "PAYMENT-SIGNATURE": paymentPayload
       }
     });
+    if (retryResponse.status === 502 || retryResponse.status === 503) {
+      await new Promise((r) => setTimeout(r, 1e3));
+      const retryResp2 = await this.fetchWithTimeout(retryUrl, {
+        method: "GET",
+        headers: {
+          "User-Agent": USER_AGENT,
+          "PAYMENT-SIGNATURE": paymentPayload
+        }
+      });
+      if (retryResp2.status !== 502 && retryResp2.status !== 503) {
+        if (retryResp2.status === 402) throw new PaymentError("Payment was rejected. Check your wallet balance.");
+        if (!retryResp2.ok) {
+          let errorBody;
+          try {
+            errorBody = await retryResp2.json();
+          } catch {
+            errorBody = { error: "Request failed" };
+          }
+          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;
+        return retryResp2.json();
+      }
+    }
     if (retryResponse.status === 402) {
       throw new PaymentError("Payment was rejected. Check your wallet balance.");
     }
@@ -2214,6 +2413,8 @@ import * as path3 from "path";
 import * as os3 from "os";
 import * as crypto2 from "crypto";
 var CACHE_DIR = path3.join(os3.homedir(), ".blockrun", "cache");
+var DATA_DIR = path3.join(os3.homedir(), ".blockrun", "data");
+var COST_LOG_FILE = path3.join(os3.homedir(), ".blockrun", "cost_log.jsonl");
 var DEFAULT_TTL = {
   "/v1/x/": 3600 * 1e3,
   "/v1/partner/": 3600 * 1e3,
@@ -2278,26 +2479,80 @@ function setCache(key, data, ttlMs) {
   } catch {
   }
 }
-function saveToCache(endpoint, body, response, costUsd = 0) {
-  const ttl = getTtl(endpoint);
-  if (ttl <= 0) return;
+function readableFilename(endpoint, body) {
+  const now = /* @__PURE__ */ new Date();
+  const ts = now.toISOString().slice(0, 10) + "_" + String(now.getHours()).padStart(2, "0") + String(now.getMinutes()).padStart(2, "0") + String(now.getSeconds()).padStart(2, "0");
+  let ep = endpoint.replace(/\/+$/, "").split("/").pop() || "";
+  if (endpoint.includes("/v1/chat/")) {
+    ep = "chat";
+  } else if (endpoint.includes("/v1/x/")) {
+    ep = "x_" + ep;
+  } else if (endpoint.includes("/v1/search")) {
+    ep = "search";
+  } else if (endpoint.includes("/v1/image")) {
+    ep = "image";
+  }
+  let label = body.query || body.username || body.handle || body.model || (typeof body.prompt === "string" ? body.prompt.slice(0, 40) : "") || "";
+  label = String(label).replace(/[^a-zA-Z0-9_\-]/g, "_").slice(0, 40).replace(/^_+|_+$/g, "");
+  return label ? `${ep}_${ts}_${label}.json` : `${ep}_${ts}.json`;
+}
+function saveReadable(endpoint, body, response, costUsd) {
   try {
-    fs3.mkdirSync(CACHE_DIR, { recursive: true });
+    fs3.mkdirSync(DATA_DIR, { recursive: true });
   } catch {
   }
-  const key = cacheKey(endpoint, body);
+  const filename = readableFilename(endpoint, body);
   const entry = {
-    cachedAt: Date.now(),
+    saved_at: (/* @__PURE__ */ new Date()).toISOString(),
     endpoint,
-    body,
-    response,
-    costUsd
+    cost_usd: costUsd,
+    request: body,
+    response
   };
   try {
-    fs3.writeFileSync(cachePath(key), JSON.stringify(entry));
+    fs3.writeFileSync(path3.join(DATA_DIR, filename), JSON.stringify(entry, null, 2));
+  } catch {
+  }
+}
+function appendCostLog(endpoint, costUsd) {
+  if (costUsd <= 0) return;
+  try {
+    fs3.mkdirSync(path3.dirname(COST_LOG_FILE), { recursive: true });
+  } catch {
+  }
+  const entry = {
+    ts: Date.now() / 1e3,
+    endpoint,
+    cost_usd: costUsd
+  };
+  try {
+    fs3.appendFileSync(COST_LOG_FILE, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
+function saveToCache(endpoint, body, response, costUsd = 0) {
+  const ttl = getTtl(endpoint);
+  if (ttl > 0) {
+    try {
+      fs3.mkdirSync(CACHE_DIR, { recursive: true });
+    } catch {
+    }
+    const key = cacheKey(endpoint, body);
+    const entry = {
+      cachedAt: Date.now(),
+      endpoint,
+      body,
+      response,
+      costUsd
+    };
+    try {
+      fs3.writeFileSync(cachePath(key), JSON.stringify(entry));
+    } catch {
+    }
+  }
+  saveReadable(endpoint, body, response, costUsd);
+  appendCostLog(endpoint, costUsd);
+}
 function clearCache() {
   if (!fs3.existsSync(CACHE_DIR)) return 0;
   let count = 0;
@@ -2316,6 +2571,32 @@ function clearCache() {
   }
   return count;
 }
+function getCostLogSummary() {
+  if (!fs3.existsSync(COST_LOG_FILE)) {
+    return { totalUsd: 0, calls: 0, byEndpoint: {} };
+  }
+  let totalUsd = 0;
+  let calls = 0;
+  const byEndpoint = {};
+  try {
+    const content = fs3.readFileSync(COST_LOG_FILE, "utf-8").trim();
+    if (!content) return { totalUsd: 0, calls: 0, byEndpoint: {} };
+    for (const line of content.split("\n")) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        const cost = entry.cost_usd ?? 0;
+        const ep = entry.endpoint ?? "unknown";
+        totalUsd += cost;
+        calls += 1;
+        byEndpoint[ep] = (byEndpoint[ep] || 0) + cost;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return { totalUsd, calls, byEndpoint };
+}
 
 // src/setup.ts
 function setupAgentWallet(options) {
@@ -2357,27 +2638,27 @@ async function status() {
 import * as fs4 from "fs";
 import * as path4 from "path";
 import * as os4 from "os";
-var DATA_DIR = path4.join(os4.homedir(), ".blockrun", "data");
-var COST_LOG_FILE = path4.join(DATA_DIR, "costs.jsonl");
+var DATA_DIR2 = path4.join(os4.homedir(), ".blockrun", "data");
+var COST_LOG_FILE2 = path4.join(DATA_DIR2, "costs.jsonl");
 function logCost(entry) {
   try {
-    fs4.mkdirSync(DATA_DIR, { recursive: true });
+    fs4.mkdirSync(DATA_DIR2, { recursive: true });
   } catch {
   }
   try {
-    fs4.appendFileSync(COST_LOG_FILE, JSON.stringify(entry) + "\n");
+    fs4.appendFileSync(COST_LOG_FILE2, JSON.stringify(entry) + "\n");
   } catch {
   }
 }
 function getCostSummary() {
-  if (!fs4.existsSync(COST_LOG_FILE)) {
+  if (!fs4.existsSync(COST_LOG_FILE2)) {
     return { totalUsd: 0, calls: 0, byModel: {} };
   }
   let totalUsd = 0;
   let calls = 0;
   const byModel = {};
   try {
-    const content = fs4.readFileSync(COST_LOG_FILE, "utf-8").trim();
+    const content = fs4.readFileSync(COST_LOG_FILE2, "utf-8").trim();
     if (!content) return { totalUsd: 0, calls: 0, byModel: {} };
     for (const line of content.split("\n")) {
       if (!line) continue;
@@ -2678,6 +2959,7 @@ export {
   BASE_CHAIN_ID,
   BlockrunError,
   ImageClient,
+  KNOWN_PROVIDERS,
   LLMClient,
   OpenAI,
   PaymentError,
@@ -2701,6 +2983,7 @@ export {
   formatWalletCreatedMessage,
   getCached,
   getCachedByRequest,
+  getCostLogSummary,
   getCostSummary,
   getEip681Uri,
   getOrCreateSolanaWallet,
@@ -2723,5 +3006,9 @@ export {
   solanaKeyToBytes,
   solanaPublicKey,
   status,
-  testnetClient
+  testnetClient,
+  validateMaxTokens,
+  validateModel,
+  validateTemperature,
+  validateTopP
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "type": "module",
   "description": "BlockRun LLM Gateway SDK - Pay-per-request AI via x402 on Base and Solana",
   "main": "dist/index.cjs",
@@ -48,7 +48,7 @@
     "url": "https://github.com/BlockRunAI/blockrun-llm-ts/issues"
   },
   "dependencies": {
-    "@blockrun/clawrouter": "^0.10.18",
+    "@blockrun/clawrouter": "^0.12.71",
     "bs58": "^6.0.0",
     "viem": "^2.21.0"
   },