@blockrun/llm 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -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);
 }
@@ -301,7 +452,7 @@ declare class LLMClient {
      * ```ts
      * const result = await client.smartChat('What is 2+2?');
      * console.log(result.response); // '4'
-     * console.log(result.model); // 'google/gemini-2.5-flash'
+     * console.log(result.model); // 'google/gemini-2.5-flash-lite'
      * console.log(result.routing.savings); // 0.78 (78% savings)
      * ```
      *
@@ -344,6 +495,15 @@ 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;
     /**
      * Fetch with timeout.
      */
@@ -372,6 +532,165 @@ 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>;
     /**
      * Get current session spending.
      *
@@ -467,6 +786,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.
      */
@@ -502,6 +834,33 @@ declare class ImageClient {
 
 declare const BASE_CHAIN_ID = 8453;
 declare const USDC_BASE: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+declare const SOLANA_NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+declare const USDC_SOLANA = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+interface CreateSolanaPaymentOptions {
+    resourceUrl?: string;
+    resourceDescription?: string;
+    maxTimeoutSeconds?: number;
+    extra?: Record<string, unknown>;
+    extensions?: Record<string, unknown>;
+    rpcUrl?: string;
+}
+/**
+ * Create a signed Solana x402 v2 payment payload.
+ *
+ * This creates an SPL TransferChecked transaction for USDC payment
+ * that the CDP facilitator can verify and settle.
+ *
+ * Requires @solana/web3.js and @solana/spl-token dependencies.
+ *
+ * @param secretKey - Solana secret key (Uint8Array, 64 bytes)
+ * @param fromAddress - Sender wallet address (base58)
+ * @param recipient - Payment recipient address (base58)
+ * @param amount - Amount in micro USDC (6 decimals)
+ * @param feePayer - CDP facilitator fee payer address (base58)
+ * @param options - Additional options
+ * @returns Base64-encoded signed payment payload
+ */
+declare function createSolanaPaymentPayload(secretKey: Uint8Array, fromAddress: string, recipient: string, amount: string, feePayer: string, options?: CreateSolanaPaymentOptions): Promise<string>;
 
 /**
  * BlockRun Wallet Management - Auto-create and manage wallets.
@@ -602,6 +961,116 @@ declare function formatFundingMessageCompact(address: string): string;
 declare const WALLET_FILE_PATH: string;
 declare const WALLET_DIR_PATH: string;
 
+/**
+ * BlockRun Solana LLM Client.
+ *
+ * Usage:
+ *   import { SolanaLLMClient } from '@blockrun/llm';
+ *
+ *   // SOLANA_WALLET_KEY env var (bs58-encoded Solana secret key)
+ *   const client = new SolanaLLMClient();
+ *
+ *   // Or pass key directly
+ *   const client = new SolanaLLMClient({ privateKey: 'your-bs58-key' });
+ *
+ *   const response = await client.chat('openai/gpt-4o', 'gm Solana');
+ */
+
+interface SolanaLLMClientOptions {
+    /** bs58-encoded Solana secret key (64 bytes). Optional if SOLANA_WALLET_KEY env var is set. */
+    privateKey?: string;
+    /** API endpoint URL (default: https://sol.blockrun.ai/api) */
+    apiUrl?: string;
+    /** Solana RPC URL (default: https://api.mainnet-beta.solana.com) */
+    rpcUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+declare class SolanaLLMClient {
+    static readonly SOLANA_API_URL = "https://sol.blockrun.ai/api";
+    private privateKey;
+    private apiUrl;
+    private rpcUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    private addressCache;
+    constructor(options?: SolanaLLMClientOptions);
+    /** Get Solana wallet address (public key in base58). */
+    getWalletAddress(): Promise<string>;
+    /** Simple 1-line chat. */
+    chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /** Full chat completion (OpenAI-compatible). */
+    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>;
+    /** Get session spending. */
+    getSpending(): Spending;
+    /** True if using sol.blockrun.ai. */
+    isSolana(): boolean;
+    private requestWithPayment;
+    private handlePaymentAndRetry;
+    private requestWithPaymentRaw;
+    private handlePaymentAndRetryRaw;
+    private fetchWithTimeout;
+}
+/**
+ * Convenience function: create SolanaLLMClient for sol.blockrun.ai.
+ */
+declare function solanaClient(options?: SolanaLLMClientOptions): SolanaLLMClient;
+
+declare const SOLANA_WALLET_FILE: string;
+interface SolanaWalletInfo {
+    privateKey: string;
+    address: string;
+    isNew: boolean;
+}
+/**
+ * Create a new Solana wallet.
+ * Requires @solana/web3.js (optional dep).
+ */
+declare function createSolanaWallet(): {
+    address: string;
+    privateKey: string;
+};
+/**
+ * Convert a bs58 private key string to Uint8Array (64 bytes).
+ * Accepts: bs58-encoded 64-byte key (standard Solana format).
+ */
+declare function solanaKeyToBytes(privateKey: string): Promise<Uint8Array>;
+/**
+ * Get Solana public key (address) from bs58 private key.
+ */
+declare function solanaPublicKey(privateKey: string): Promise<string>;
+declare function saveSolanaWallet(privateKey: string): string;
+declare function loadSolanaWallet(): string | null;
+declare function getOrCreateSolanaWallet(): Promise<SolanaWalletInfo>;
+
 /**
  * OpenAI-compatible API wrapper for BlockRun LLM SDK.
  *
@@ -741,4 +1210,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, type SearchParameters, type SearchSource, type SmartChatOptions, type SmartChatResponse, type Spending, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, WALLET_DIR_PATH, WALLET_FILE_PATH, type WalletInfo, type WebSearchSource, type XSearchSource, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadWallet, saveWallet, testnetClient };
+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 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, createSolanaPaymentPayload, createSolanaWallet, createWallet, LLMClient as default, formatFundingMessageCompact, formatNeedsFundingMessage, formatWalletCreatedMessage, getEip681Uri, getOrCreateSolanaWallet, getOrCreateWallet, getPaymentLinks, getWalletAddress, loadSolanaWallet, loadWallet, saveSolanaWallet, saveWallet, solanaClient, solanaKeyToBytes, solanaPublicKey, testnetClient };