@blockrun/llm 1.6.2 → 1.8.0

package/dist/index.d.cts

@@ -34,6 +34,8 @@ interface ChatMessage {
     name?: string;
     tool_call_id?: string;
     tool_calls?: ToolCall[];
+    reasoning_content?: string;
+    thinking?: string;
 }
 interface ChatChoice {
     index: number;
@@ -45,6 +47,8 @@ interface ChatUsage {
     completion_tokens: number;
     total_tokens: number;
     num_sources_used?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
 }
 interface ChatResponse {
     id: string;
@@ -60,16 +64,28 @@ interface Model {
     name: string;
     provider: string;
     description: string;
+    /** Per 1M tokens. 0 when billingMode !== "paid". */
     inputPrice: number;
+    /** Per 1M tokens. 0 when billingMode !== "paid". */
     outputPrice: number;
     contextWindow: number;
     maxOutput: number;
     categories: string[];
     available: boolean;
     type?: "llm" | "image";
+    /** One of "paid" (per-token), "flat" (flatPrice per request) or "free". */
+    billingMode?: "paid" | "flat" | "free";
+    /** Flat per-request price when billingMode === "flat". */
+    flatPrice?: number;
+    /** True for deprecated/superseded models that remain routable. */
+    hidden?: boolean;
 }
 interface ImageData {
     url: string;
+    /** Original upstream URL (e.g. imgen.x.ai). Omitted for data URIs. */
+    source_url?: string;
+    /** True when the gateway mirrored the image to its GCS bucket. Omitted for data URIs. */
+    backed_up?: boolean;
     revised_prompt?: string;
     b64_json?: string;
 }
@@ -286,6 +302,91 @@ interface ImageEditOptions {
     /** Number of images to generate (default: 1) */
     n?: number;
 }
+interface AudioTrack {
+    url: string;
+    duration_seconds?: number;
+    lyrics?: string;
+}
+interface MusicResponse {
+    created: number;
+    model: string;
+    data: AudioTrack[];
+    txHash?: string;
+}
+interface AudioModel {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    pricePerTrack: number;
+    maxDurationSeconds: number;
+    supportsLyrics: boolean;
+    supportsInstrumental: boolean;
+    available: boolean;
+    type: "audio";
+}
+interface MusicClientOptions {
+    /** EVM wallet private key (hex string starting with 0x) */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 210000 — music gen takes 1-3 min) */
+    timeout?: number;
+}
+interface MusicGenerateOptions {
+    /** Model ID (default: "minimax/music-2.5+") */
+    model?: "minimax/music-2.5+" | "minimax/music-2.5";
+    /** Generate without vocals (default: true) */
+    instrumental?: boolean;
+    /** Custom lyrics — cannot be used with instrumental: true */
+    lyrics?: string;
+}
+interface VideoClip {
+    /** Permanent blockrun-hosted URL (falls back to upstream if backup fails) */
+    url: string;
+    /** Original upstream URL (e.g. vidgen.x.ai) */
+    source_url?: string;
+    /** Duration of the generated video */
+    duration_seconds?: number;
+    /** Upstream provider's request id (xAI) */
+    request_id?: string;
+    /** True when the gateway mirrored the video to its GCS bucket */
+    backed_up?: boolean;
+}
+interface VideoResponse {
+    created: number;
+    model: string;
+    data: VideoClip[];
+    txHash?: string;
+}
+interface VideoModel {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    pricePerSecond: number;
+    defaultDurationSeconds: number;
+    maxDurationSeconds: number;
+    supportsImageInput: boolean;
+    available: boolean;
+    type: "video";
+}
+interface VideoClientOptions {
+    /** EVM wallet private key (hex string starting with 0x) */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 300000 — video gen + polling up to 3 min) */
+    timeout?: number;
+}
+interface VideoGenerateOptions {
+    /** Model ID (default: "xai/grok-imagine-video") */
+    model?: "xai/grok-imagine-video" | string;
+    /** Optional seed image URL for image-to-video */
+    imageUrl?: string;
+    /** Duration to bill for (defaults to model's default duration) */
+    durationSeconds?: number;
+}
 interface SearchOptions {
     /** Source types to search (e.g. ["web", "x", "news"]) */
     sources?: string[];
@@ -482,6 +583,80 @@ interface XAuthorAnalyticsResponse {
 interface XCompareAuthorsResponse {
     data: Record<string, unknown>;
 }
+type PriceCategory = "crypto" | "fx" | "commodity" | "usstock" | "stocks";
+type StockMarket = "us" | "hk" | "jp" | "kr" | "gb" | "de" | "fr" | "nl" | "ie" | "lu" | "cn" | "ca";
+type BarResolution = "1" | "5" | "15" | "60" | "240" | "D" | "W" | "M";
+type MarketSession = "pre" | "post" | "on";
+interface PricePoint {
+    symbol: string;
+    price: number;
+    publishTime?: number;
+    confidence?: number;
+    feedId?: string;
+    timestamp?: string;
+    assetType?: string;
+    category?: string;
+    source?: string;
+    free?: boolean;
+}
+interface PriceBar {
+    t?: number;
+    o?: number;
+    h?: number;
+    l?: number;
+    c?: number;
+    v?: number;
+}
+interface PriceHistoryResponse {
+    symbol: string;
+    resolution?: string;
+    from?: number;
+    to?: number;
+    bars: PriceBar[];
+    source?: string;
+    category?: string;
+}
+interface SymbolListResponse {
+    symbols: Array<Record<string, unknown>>;
+    count?: number;
+}
+interface PriceOptions {
+    /** Required when category === "stocks". */
+    market?: StockMarket;
+    /** Optional US-equity session hint; ignored for non-equity. */
+    session?: MarketSession;
+}
+interface HistoryOptions extends PriceOptions {
+    /** TradingView-style bar resolution. Defaults to "D". */
+    resolution?: BarResolution;
+    /** Window start, unix seconds (required). */
+    from: number;
+    /** Window end, unix seconds. Defaults to now on the backend. */
+    to?: number;
+}
+interface ListOptions extends PriceOptions {
+    /** Free-text filter (maps to ?q=). */
+    query?: string;
+    /** Page size, capped at 2000. Defaults to 100. */
+    limit?: number;
+}
+interface SearchClientOptions {
+    privateKey?: `0x${string}` | string;
+    apiUrl?: string;
+    timeout?: number;
+}
+interface XClientOptions {
+    privateKey?: `0x${string}` | string;
+    apiUrl?: string;
+    timeout?: number;
+}
+interface PriceClientOptions {
+    privateKey?: `0x${string}` | string;
+    apiUrl?: string;
+    timeout?: number;
+    /** If false, construction succeeds without a wallet (free endpoints only). */
+    requireWallet?: boolean;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -967,8 +1142,8 @@ declare function testnetClient(options?: Omit<LLMClientOptions, 'apiUrl'>): LLMC
 /**
  * BlockRun Image Generation Client.
  *
- * Generate images using Nano Banana (Google Gemini), DALL-E 3, or GPT Image
- * with automatic x402 micropayments on Base chain.
+ * Generate images using Nano Banana (Google Gemini), DALL-E 3, GPT Image,
+ * or CogView-4 (Zhipu AI) with automatic x402 micropayments on Base chain.
  */
 declare class ImageClient {
     private account;
@@ -1034,6 +1209,191 @@ declare class ImageClient {
     getSpending(): Spending;
 }
 
+/**
+ * BlockRun Music Client - Generate music tracks via x402 micropayments.
+ *
+ * SECURITY NOTE - Private Key Handling:
+ * Your private key NEVER leaves your machine. Here's what happens:
+ * 1. Key stays local - only used to sign an EIP-712 typed data message
+ * 2. Only the SIGNATURE is sent in the PAYMENT-SIGNATURE header
+ * 3. BlockRun verifies the signature on-chain via Coinbase CDP facilitator
+ *
+ * Usage:
+ *   import { MusicClient } from '@blockrun/llm';
+ *
+ *   const client = new MusicClient({ privateKey: '0x...' });
+ *   const result = await client.generate('upbeat synthwave with neon pads');
+ *   console.log(result.data[0].url); // CDN URL — download within 24h
+ */
+
+/**
+ * BlockRun Music Generation Client.
+ *
+ * Generate full-length ~3 minute music tracks using MiniMax Music 2.5+
+ * with automatic x402 micropayments on Base chain.
+ *
+ * Pricing: $0.1575/track
+ * Note: Generated URLs expire in ~24h — download immediately if needed.
+ */
+declare class MusicClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: MusicClientOptions);
+    /**
+     * Generate a music track from a text prompt.
+     *
+     * Takes 1-3 minutes. Returns a CDN URL valid for ~24h.
+     *
+     * @param prompt - Music style, mood, or description
+     * @param options - Optional generation parameters
+     * @returns MusicResponse with track URL and metadata
+     *
+     * @example
+     * const result = await client.generate('chill lo-fi beats with piano');
+     * console.log(result.data[0].url); // Download this URL — expires in 24h
+     *
+     * @example With lyrics
+     * const result = await client.generate('upbeat pop song', {
+     *   instrumental: false,
+     *   lyrics: 'Hello world, this is my song...'
+     * });
+     */
+    generate(prompt: string, options?: MusicGenerateOptions): Promise<MusicResponse>;
+    private requestWithPayment;
+    private handlePaymentAndRetry;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+    getSpending(): Spending;
+}
+
+/**
+ * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
+ *
+ * Backend endpoint: POST /api/v1/search
+ * Pricing: $0.025/source + margin (default 10 sources ≈ $0.26).
+ *
+ * Usage:
+ *   import { SearchClient } from "@blockrun/llm";
+ *
+ *   const client = new SearchClient({ privateKey: "0x..." });
+ *   const result = await client.search("Latest news on x402 adoption", {
+ *     sources: ["x", "web"],
+ *   });
+ *   console.log(result.summary);
+ */
+
+declare class SearchClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    constructor(options?: SearchClientOptions);
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    private requestWithPayment;
+    private handlePaymentAndRetry;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+}
+
+/**
+ * BlockRun X (Twitter) Client - AttentionVC-partnered X/Twitter API via x402.
+ *
+ * Wraps the /api/v1/x/* endpoint family. Every call is gated by an x402
+ * payment; the client handles the 402 → sign → retry dance automatically.
+ *
+ * Usage:
+ *   import { XClient } from "@blockrun/llm";
+ *
+ *   const x = new XClient({ privateKey: "0x..." });
+ *   const info = await x.userInfo("elonmusk");
+ *   const followers = await x.followers("paulg");
+ *   const results = await x.search("x402 micropayments", { queryType: "Latest" });
+ */
+
+interface XUserTweetsOptions {
+    username?: string;
+    userId?: string;
+    cursor?: string;
+    includeReplies?: boolean;
+}
+interface XMentionsOptions {
+    sinceTime?: string;
+    untilTime?: string;
+    cursor?: string;
+}
+interface XTweetRepliesOptions {
+    cursor?: string;
+    queryType?: "Latest" | "Default";
+}
+interface XSearchOptions {
+    queryType?: "Latest" | "Top" | "Default";
+    cursor?: string;
+}
+declare class XClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    constructor(options?: XClientOptions);
+    userLookup(usernames: string | string[]): Promise<XUserLookupResponse>;
+    userInfo(username: string): Promise<XUserInfoResponse>;
+    followers(username: string, cursor?: string): Promise<XFollowersResponse>;
+    /** `/v1/x/users/following` (singular path variant). */
+    following(username: string, cursor?: string): Promise<XFollowingsResponse>;
+    /** `/v1/x/users/followings` (plural path variant). */
+    followings(username: string, cursor?: string): Promise<XFollowingsResponse>;
+    verifiedFollowers(userId: string, cursor?: string): Promise<XVerifiedFollowersResponse>;
+    userTweets(options: XUserTweetsOptions): Promise<XTweetsResponse>;
+    mentions(username: string, options?: XMentionsOptions): Promise<XMentionsResponse>;
+    tweetLookup(tweetIds: string | string[]): Promise<XTweetLookupResponse>;
+    tweetReplies(tweetId: string, options?: XTweetRepliesOptions): Promise<XTweetRepliesResponse>;
+    tweetThread(tweetId: string, cursor?: string): Promise<XTweetThreadResponse>;
+    search(query: string, options?: XSearchOptions): Promise<XSearchResponse>;
+    trending(): Promise<XTrendingResponse>;
+    articlesRising(): Promise<XArticlesRisingResponse>;
+    private post;
+    private payAndRetry;
+    private fetchWithTimeout;
+    getWalletAddress(): string;
+}
+
+/**
+ * BlockRun Price Client - Pyth-backed market data via x402.
+ *
+ * Payment gating mirrors CategoryConfig.paid in the backend:
+ *   crypto, fx, commodity      → FREE across price + history + list
+ *   usstock, stocks/{market}   → PAID for price + history; list always free
+ *
+ * Usage:
+ *   import { PriceClient } from "@blockrun/llm";
+ *
+ *   const p = new PriceClient({ privateKey: "0x..." });
+ *   const btc = await p.price("crypto", "BTC-USD");
+ *   const aapl = await p.price("stocks", "AAPL", { market: "us" });
+ *   const bars = await p.history("stocks", "AAPL", { market: "us",
+ *     from: 1700000000, to: 1710000000 });
+ *   const symbols = await p.listSymbols("crypto", { query: "sol" });
+ */
+
+declare class PriceClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    constructor(options?: PriceClientOptions);
+    price(category: PriceCategory, symbol: string, options?: PriceOptions): Promise<PricePoint>;
+    history(category: PriceCategory, symbol: string, options: HistoryOptions): Promise<PriceHistoryResponse>;
+    listSymbols(category: PriceCategory, options?: ListOptions): Promise<SymbolListResponse>;
+    getWalletAddress(): string | null;
+    private getWithPayment;
+    private payAndRetry;
+    private fetchWithTimeout;
+}
+
 /**
  * x402 Payment Protocol v2 Implementation for BlockRun.
  *
@@ -1664,4 +2024,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 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 };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, 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, type HistoryOptions, ImageClient, type ImageClientOptions, type ImageData, type ImageEditOptions, type ImageGenerateOptions, type ImageModel, type ImageResponse, KNOWN_PROVIDERS, LLMClient, type LLMClientOptions, type ListOptions, type MarketSession, type Model, MusicClient, type MusicClientOptions, type MusicGenerateOptions, type MusicResponse, type NewsSearchSource, OpenAI, type OpenAIChatCompletionChoice, type OpenAIChatCompletionChunk, type OpenAIChatCompletionParams, type OpenAIChatCompletionResponse, type OpenAIClientOptions, PaymentError, type PaymentLinks, type PriceBar, type PriceCategory, PriceClient, type PriceClientOptions, type PriceHistoryResponse, type PriceOptions, type PricePoint, type RoutingDecision, type RoutingProfile, type RoutingTier, type RssSearchSource, SOLANA_NETWORK, SOLANA_WALLET_FILE as SOLANA_WALLET_FILE_PATH, SearchClient, type SearchClientOptions, type SearchOptions, type SearchParameters, type SearchResult, type SearchSource, type SearchUsage, type SmartChatOptions, type SmartChatResponse, SolanaLLMClient, type SolanaLLMClientOptions, type SolanaWalletInfo, type Spending, type SpendingReport, type StockMarket, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XArticlesRisingResponse, type XAuthorAnalyticsResponse, XClient, type XClientOptions, type XCompareAuthorsResponse, type XFollower, type XFollowersResponse, type XFollowingsResponse, type XMentionsOptions, type XMentionsResponse, type XSearchOptions, type XSearchResponse, type XSearchSource, type XTrendingResponse, type XTweet, type XTweetLookupResponse, type XTweetRepliesOptions, type XTweetRepliesResponse, type XTweetThreadResponse, type XTweetsResponse, type XUser, type XUserInfoResponse, type XUserLookupResponse, type XUserTweetsOptions, 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 };