@blockrun/llm 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -205,6 +205,157 @@ interface SmartChatResponse {
     /** Routing decision metadata */
     routing: RoutingDecision;
 }
+interface SearchResult {
+    query: string;
+    summary: string;
+    citations?: Array<Record<string, string>>;
+    sources_used?: number;
+    model?: string;
+}
+interface ImageEditOptions {
+    /** Model ID (default: "openai/gpt-image-1") */
+    model?: string;
+    /** Optional base64-encoded mask image */
+    mask?: string;
+    /** Image size (default: "1024x1024") */
+    size?: string;
+    /** Number of images to generate (default: 1) */
+    n?: number;
+}
+interface SearchOptions {
+    /** Source types to search (e.g. ["web", "x", "news"]) */
+    sources?: string[];
+    /** Maximum number of results (default: 10) */
+    maxResults?: number;
+    /** Start date filter (YYYY-MM-DD) */
+    fromDate?: string;
+    /** End date filter (YYYY-MM-DD) */
+    toDate?: string;
+}
+interface XUser {
+    id: string;
+    userName: string;
+    name: string;
+    profilePicture?: string;
+    description?: string;
+    followers?: number;
+    following?: number;
+    isBlueVerified?: boolean;
+    verifiedType?: string;
+    location?: string;
+    joined?: string;
+}
+interface XUserLookupResponse {
+    users: XUser[];
+    not_found?: string[];
+    total_requested?: number;
+    total_found?: number;
+}
+interface XFollower {
+    id: string;
+    name?: string;
+    screen_name?: string;
+    userName?: string;
+    location?: string;
+    description?: string;
+    protected?: boolean;
+    verified?: boolean;
+    followers_count?: number;
+    following_count?: number;
+    favourites_count?: number;
+    statuses_count?: number;
+    created_at?: string;
+    profile_image_url_https?: string;
+    can_dm?: boolean;
+}
+interface XFollowersResponse {
+    followers: XFollower[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+    username?: string;
+}
+interface XFollowingsResponse {
+    followings: XFollower[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+    username?: string;
+}
+interface XUserInfoResponse {
+    data: Record<string, unknown>;
+    username?: string;
+}
+interface XVerifiedFollowersResponse {
+    followers: XFollower[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+}
+interface XTweet {
+    id: string;
+    text?: string;
+    created_at?: string;
+    author?: Record<string, unknown>;
+    favorite_count?: number;
+    retweet_count?: number;
+    reply_count?: number;
+    view_count?: number;
+    lang?: string;
+    entities?: Record<string, unknown>;
+    media?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface XTweetsResponse {
+    tweets: XTweet[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+}
+interface XMentionsResponse {
+    tweets: XTweet[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+    username?: string;
+}
+interface XTweetLookupResponse {
+    tweets: XTweet[];
+    not_found?: string[];
+    total_requested?: number;
+    total_found?: number;
+}
+interface XTweetRepliesResponse {
+    replies: XTweet[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+}
+interface XTweetThreadResponse {
+    tweets: XTweet[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+}
+interface XSearchResponse {
+    tweets: XTweet[];
+    has_next_page?: boolean;
+    next_cursor?: string;
+    total_returned?: number;
+}
+interface XTrendingResponse {
+    data: Record<string, unknown>;
+}
+interface XArticlesRisingResponse {
+    data: Record<string, unknown>;
+}
+interface XAuthorAnalyticsResponse {
+    data: Record<string, unknown>;
+    handle?: string;
+}
+interface XCompareAuthorsResponse {
+    data: Record<string, unknown>;
+}
 declare class BlockrunError extends Error {
     constructor(message: string);
 }
@@ -344,6 +495,24 @@ declare class LLMClient {
      * Handle 402 response: parse requirements, sign payment, retry.
      */
     private handlePaymentAndRetry;
+    /**
+     * Make a request with automatic x402 payment handling, returning raw JSON.
+     * Used for non-ChatResponse endpoints (X/Twitter, search, image edit, etc.).
+     */
+    private requestWithPaymentRaw;
+    /**
+     * Handle 402 response for raw endpoints: parse requirements, sign payment, retry.
+     */
+    private handlePaymentAndRetryRaw;
+    /**
+     * GET with automatic x402 payment handling, returning raw JSON.
+     * Used for Predexon prediction market endpoints that use GET + query params.
+     */
+    private getWithPaymentRaw;
+    /**
+     * Handle 402 response for GET endpoints: parse requirements, sign payment, retry with GET.
+     */
+    private handleGetPaymentAndRetryRaw;
     /**
      * Fetch with timeout.
      */
@@ -372,6 +541,192 @@ declare class LLMClient {
      * }
      */
     listAllModels(): Promise<(Model | ImageModel)[]>;
+    /**
+     * Edit an image using img2img.
+     *
+     * @param prompt - Text description of the desired edit
+     * @param image - Base64-encoded image or URL of the source image
+     * @param options - Optional edit parameters
+     * @returns ImageResponse with edited image URLs
+     */
+    imageEdit(prompt: string, image: string, options?: ImageEditOptions): Promise<ImageResponse>;
+    /**
+     * Standalone search (web, X/Twitter, news).
+     *
+     * @param query - Search query
+     * @param options - Optional search parameters
+     * @returns SearchResult with summary and citations
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * Get USDC balance on Base network.
+     *
+     * Automatically detects mainnet vs testnet based on API URL.
+     *
+     * @returns USDC balance as a float (6 decimal places normalized)
+     *
+     * @example
+     * const balance = await client.getBalance();
+     * console.log(`Balance: $${balance.toFixed(2)} USDC`);
+     */
+    getBalance(): Promise<number>;
+    /**
+     * Look up X/Twitter user profiles by username.
+     *
+     * Powered by AttentionVC. $0.002 per user (min $0.02, max $0.20).
+     *
+     * @param usernames - Single username or array of usernames (without @)
+     */
+    xUserLookup(usernames: string | string[]): Promise<XUserLookupResponse>;
+    /**
+     * Get followers of an X/Twitter user.
+     *
+     * Powered by AttentionVC. $0.05 per page (~200 accounts).
+     *
+     * @param username - X/Twitter username (without @)
+     * @param cursor - Pagination cursor from previous response
+     */
+    xFollowers(username: string, cursor?: string): Promise<XFollowersResponse>;
+    /**
+     * Get accounts an X/Twitter user is following.
+     *
+     * Powered by AttentionVC. $0.05 per page (~200 accounts).
+     *
+     * @param username - X/Twitter username (without @)
+     * @param cursor - Pagination cursor from previous response
+     */
+    xFollowings(username: string, cursor?: string): Promise<XFollowingsResponse>;
+    /**
+     * Get detailed profile info for a single X/Twitter user.
+     *
+     * Powered by AttentionVC. $0.002 per request.
+     *
+     * @param username - X/Twitter username (without @)
+     */
+    xUserInfo(username: string): Promise<XUserInfoResponse>;
+    /**
+     * Get verified (blue-check) followers of an X/Twitter user.
+     *
+     * Powered by AttentionVC. $0.048 per page.
+     *
+     * @param userId - X/Twitter user ID (not username)
+     * @param cursor - Pagination cursor from previous response
+     */
+    xVerifiedFollowers(userId: string, cursor?: string): Promise<XVerifiedFollowersResponse>;
+    /**
+     * Get tweets posted by an X/Twitter user.
+     *
+     * Powered by AttentionVC. $0.032 per page.
+     *
+     * @param username - X/Twitter username (without @)
+     * @param includeReplies - Include reply tweets (default: false)
+     * @param cursor - Pagination cursor from previous response
+     */
+    xUserTweets(username: string, includeReplies?: boolean, cursor?: string): Promise<XTweetsResponse>;
+    /**
+     * Get tweets that mention an X/Twitter user.
+     *
+     * Powered by AttentionVC. $0.032 per page.
+     *
+     * @param username - X/Twitter username (without @)
+     * @param sinceTime - Start time filter (ISO8601 or Unix timestamp)
+     * @param untilTime - End time filter (ISO8601 or Unix timestamp)
+     * @param cursor - Pagination cursor from previous response
+     */
+    xUserMentions(username: string, sinceTime?: string, untilTime?: string, cursor?: string): Promise<XMentionsResponse>;
+    /**
+     * Fetch full tweet data for up to 200 tweet IDs.
+     *
+     * Powered by AttentionVC. $0.16 per batch.
+     *
+     * @param tweetIds - Single tweet ID or array of tweet IDs (max 200)
+     */
+    xTweetLookup(tweetIds: string | string[]): Promise<XTweetLookupResponse>;
+    /**
+     * Get replies to a specific tweet.
+     *
+     * Powered by AttentionVC. $0.032 per page.
+     *
+     * @param tweetId - The tweet ID to get replies for
+     * @param queryType - Sort order: 'Latest' or 'Default'
+     * @param cursor - Pagination cursor from previous response
+     */
+    xTweetReplies(tweetId: string, queryType?: string, cursor?: string): Promise<XTweetRepliesResponse>;
+    /**
+     * Get the full thread context for a tweet.
+     *
+     * Powered by AttentionVC. $0.032 per page.
+     *
+     * @param tweetId - The tweet ID to get thread for
+     * @param cursor - Pagination cursor from previous response
+     */
+    xTweetThread(tweetId: string, cursor?: string): Promise<XTweetThreadResponse>;
+    /**
+     * Search X/Twitter with advanced query operators.
+     *
+     * Powered by AttentionVC. $0.032 per page.
+     *
+     * @param query - Search query (supports Twitter search operators)
+     * @param queryType - Sort order: 'Latest', 'Top', or 'Default'
+     * @param cursor - Pagination cursor from previous response
+     */
+    xSearch(query: string, queryType?: string, cursor?: string): Promise<XSearchResponse>;
+    /**
+     * Get current trending topics on X/Twitter.
+     *
+     * Powered by AttentionVC. $0.002 per request.
+     */
+    xTrending(): Promise<XTrendingResponse>;
+    /**
+     * Get rising/viral articles from X/Twitter.
+     *
+     * Powered by AttentionVC intelligence layer. $0.05 per request.
+     */
+    xArticlesRising(): Promise<XArticlesRisingResponse>;
+    /**
+     * Get author analytics and intelligence metrics for an X/Twitter user.
+     *
+     * Powered by AttentionVC intelligence layer. $0.02 per request.
+     *
+     * @param handle - X/Twitter handle (without @)
+     */
+    xAuthorAnalytics(handle: string): Promise<XAuthorAnalyticsResponse>;
+    /**
+     * Compare two X/Twitter authors side-by-side with intelligence metrics.
+     *
+     * Powered by AttentionVC intelligence layer. $0.05 per request.
+     *
+     * @param handle1 - First X/Twitter handle (without @)
+     * @param handle2 - Second X/Twitter handle (without @)
+     */
+    xCompareAuthors(handle1: string, handle2: string): Promise<XCompareAuthorsResponse>;
+    /**
+     * Query Predexon prediction market data (GET endpoints).
+     *
+     * Access real-time data from Polymarket, Kalshi, dFlow, and Binance Futures.
+     * Powered by Predexon. $0.001 per request.
+     *
+     * @param path - Endpoint path, e.g. "polymarket/events", "kalshi/markets/12345"
+     * @param params - Query parameters passed to the endpoint
+     *
+     * @example
+     * const events = await client.pm("polymarket/events");
+     * const market = await client.pm("kalshi/markets/KXBTC-25MAR14");
+     * const results = await client.pm("polymarket/search", { q: "bitcoin" });
+     */
+    pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
+    /**
+     * Structured query for Predexon prediction market data (POST endpoints).
+     *
+     * For complex queries that require a JSON body. $0.005 per request.
+     *
+     * @param path - Endpoint path, e.g. "polymarket/query", "kalshi/query"
+     * @param query - JSON body for the structured query
+     *
+     * @example
+     * const data = await client.pmQuery("polymarket/query", { filter: "active", limit: 10 });
+     */
+    pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * Get current session spending.
      *
@@ -467,6 +822,19 @@ declare class ImageClient {
      * console.log(result.data[0].url);
      */
     generate(prompt: string, options?: ImageGenerateOptions): Promise<ImageResponse>;
+    /**
+     * Edit an image using img2img.
+     *
+     * @param prompt - Text description of the desired edit
+     * @param image - Base64-encoded image or URL of the source image
+     * @param options - Optional edit parameters
+     * @returns ImageResponse with edited image URLs
+     *
+     * @example
+     * const result = await client.edit('Make it a painting', imageBase64);
+     * console.log(result.data[0].url);
+     */
+    edit(prompt: string, image: string, options?: ImageEditOptions): Promise<ImageResponse>;
     /**
      * List available image generation models with pricing.
      */
@@ -566,9 +934,26 @@ declare function createWallet(): {
  * @returns Path to saved wallet file
  */
 declare function saveWallet(privateKey: string): string;
+/**
+ * Scan ~/.<dir>/wallet.json files from any provider (agentcash, etc.).
+ *
+ * Each file should contain JSON with "privateKey" and "address" fields.
+ * Results are sorted by modification time (most recent first).
+ *
+ * @returns Array of wallet objects with privateKey and address
+ */
+declare function scanWallets(): Array<{
+    privateKey: string;
+    address: string;
+}>;
 /**
  * Load wallet private key from file.
  *
+ * Priority:
+ * 1. Scan ~/.* /wallet.json (any provider)
+ * 2. Legacy ~/.blockrun/.session
+ * 3. Legacy ~/.blockrun/wallet.key
+ *
  * @returns Private key string or null if not found
  */
 declare function loadWallet(): string | null;
@@ -577,9 +962,10 @@ declare function loadWallet(): string | null;
  *
  * Priority:
  * 1. BLOCKRUN_WALLET_KEY environment variable
- * 2. ~/.blockrun/.session file
- * 3. ~/.blockrun/wallet.key file (legacy)
- * 4. Create new wallet
+ * 2. Scan wallet.json files from providers
+ * 3. ~/.blockrun/.session file
+ * 4. ~/.blockrun/wallet.key file - legacy
+ * 5. Create new wallet
  *
  * @returns WalletInfo with address, privateKey, and isNew flag
  */
@@ -672,12 +1058,43 @@ declare class SolanaLLMClient {
     chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
     /** List available models. */
     listModels(): Promise<Model[]>;
+    /**
+     * Get Solana USDC balance.
+     *
+     * @returns USDC balance as a float
+     */
+    getBalance(): Promise<number>;
+    /** Edit an image using img2img (Solana payment). */
+    imageEdit(prompt: string, image: string, options?: ImageEditOptions): Promise<ImageResponse>;
+    /** Standalone search (Solana payment). */
+    search(query: string, options?: SearchOptions): Promise<SearchResult>;
+    xUserLookup(usernames: string | string[]): Promise<XUserLookupResponse>;
+    xFollowers(username: string, cursor?: string): Promise<XFollowersResponse>;
+    xFollowings(username: string, cursor?: string): Promise<XFollowingsResponse>;
+    xUserInfo(username: string): Promise<XUserInfoResponse>;
+    xVerifiedFollowers(userId: string, cursor?: string): Promise<XVerifiedFollowersResponse>;
+    xUserTweets(username: string, includeReplies?: boolean, cursor?: string): Promise<XTweetsResponse>;
+    xUserMentions(username: string, sinceTime?: string, untilTime?: string, cursor?: string): Promise<XMentionsResponse>;
+    xTweetLookup(tweetIds: string | string[]): Promise<XTweetLookupResponse>;
+    xTweetReplies(tweetId: string, queryType?: string, cursor?: string): Promise<XTweetRepliesResponse>;
+    xTweetThread(tweetId: string, cursor?: string): Promise<XTweetThreadResponse>;
+    xSearch(query: string, queryType?: string, cursor?: string): Promise<XSearchResponse>;
+    xTrending(): Promise<XTrendingResponse>;
+    xArticlesRising(): Promise<XArticlesRisingResponse>;
+    xAuthorAnalytics(handle: string): Promise<XAuthorAnalyticsResponse>;
+    xCompareAuthors(handle1: string, handle2: string): Promise<XCompareAuthorsResponse>;
+    pm(path: string, params?: Record<string, string>): Promise<Record<string, unknown>>;
+    pmQuery(path: string, query: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Get session spending. */
     getSpending(): Spending;
     /** True if using sol.blockrun.ai. */
     isSolana(): boolean;
     private requestWithPayment;
     private handlePaymentAndRetry;
+    private requestWithPaymentRaw;
+    private handlePaymentAndRetryRaw;
+    private getWithPaymentRaw;
+    private handleGetPaymentAndRetryRaw;
     private fetchWithTimeout;
 }
 /**
@@ -709,9 +1126,60 @@ declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
  */
 declare function solanaPublicKey(privateKey: string): Promise<string>;
 declare function saveSolanaWallet(privateKey: string): string;
+/**
+ * Scan ~/.<dir>/solana-wallet.json files from any provider.
+ *
+ * Each file should contain JSON with "privateKey" and "address" fields.
+ * Also checks ~/.brcc/wallet.json for BRCC wallets.
+ * Results are sorted by modification time (most recent first).
+ *
+ * @returns Array of wallet objects with secretKey and publicKey
+ */
+declare function scanSolanaWallets(): Array<{
+    secretKey: string;
+    publicKey: string;
+}>;
 declare function loadSolanaWallet(): string | null;
 declare function getOrCreateSolanaWallet(): Promise<SolanaWalletInfo>;
 
+declare function getCached(key: string): unknown | null;
+declare function getCachedByRequest(endpoint: string, body: Record<string, unknown>): unknown | null;
+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;
+
+/**
+ * Agent wallet setup utilities.
+ *
+ * Convenience functions for agent runtimes (Claude Code skills, etc.)
+ * that auto-create wallets and return configured clients.
+ */
+
+declare function setupAgentWallet(options?: {
+    silent?: boolean;
+}): LLMClient;
+declare function setupAgentSolanaWallet(options?: {
+    silent?: boolean;
+}): Promise<SolanaLLMClient>;
+declare function status(): Promise<{
+    address: string;
+    balance: number;
+}>;
+
+interface CostEntry {
+    timestamp: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+declare function logCost(entry: CostEntry): void;
+declare function getCostSummary(): {
+    totalUsd: number;
+    calls: number;
+    byModel: Record<string, number>;
+};
+
 /**
  * OpenAI-compatible API wrapper for BlockRun LLM SDK.
  *
@@ -851,4 +1319,4 @@ declare class OpenAI {
     getWalletAddress(): string;
 }
 
-export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type FunctionCall, type FunctionDefinition, ImageClient, type ImageClientOptions, type ImageData, 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 SearchParameters, 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 XSearchSource, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, saveSolanaWallet, saveWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, testnetClient };
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, type CostEntry, 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, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getCached, getCachedByRequest, getCostSummary, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, logCost, saveSolanaWallet, saveToCache, saveWallet, scanSolanaWallets, scanWallets, setCache, setupAgentSolanaWallet, setupAgentWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, status, testnetClient };