@blockrun/llm 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,587 @@
+/**
+ * Type definitions for BlockRun LLM SDK
+ */
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason?: string;
+}
+interface ChatUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    num_sources_used?: number;
+}
+interface ChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: ChatUsage;
+    citations?: string[];
+}
+interface Model {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    inputPrice: number;
+    outputPrice: number;
+    contextWindow: number;
+    maxOutput: number;
+    available: boolean;
+    type?: "llm" | "image";
+}
+interface ImageData {
+    url: string;
+    revised_prompt?: string;
+    b64_json?: string;
+}
+interface ImageResponse {
+    created: number;
+    data: ImageData[];
+}
+interface ImageModel {
+    id: string;
+    name: string;
+    provider: string;
+    description: string;
+    pricePerImage: number;
+    supportedSizes?: string[];
+    maxPromptLength?: number;
+    available: boolean;
+    type?: "llm" | "image";
+}
+interface ImageClientOptions {
+    /** 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: 120000 for images) */
+    timeout?: number;
+}
+interface ImageGenerateOptions {
+    /** Model ID (default: "google/nano-banana") */
+    model?: string;
+    /** Image size (default: "1024x1024") */
+    size?: string;
+    /** Number of images to generate (default: 1) */
+    n?: number;
+    /** Image quality (for supported models) */
+    quality?: "standard" | "hd";
+}
+interface WebSearchSource {
+    type: "web";
+    country?: string;
+    excludedWebsites?: string[];
+    allowedWebsites?: string[];
+    safeSearch?: boolean;
+}
+interface XSearchSource {
+    type: "x";
+    includedXHandles?: string[];
+    excludedXHandles?: string[];
+    postFavoriteCount?: number;
+    postViewCount?: number;
+}
+interface NewsSearchSource {
+    type: "news";
+    country?: string;
+    excludedWebsites?: string[];
+    allowedWebsites?: string[];
+    safeSearch?: boolean;
+}
+interface RssSearchSource {
+    type: "rss";
+    links: string[];
+}
+type SearchSource = WebSearchSource | XSearchSource | NewsSearchSource | RssSearchSource;
+interface SearchParameters {
+    mode?: "off" | "auto" | "on";
+    sources?: SearchSource[];
+    returnCitations?: boolean;
+    fromDate?: string;
+    toDate?: string;
+    maxSearchResults?: number;
+}
+interface Spending {
+    totalUsd: number;
+    calls: number;
+}
+interface LLMClientOptions {
+    /** EVM wallet private key (hex string starting with 0x). Optional if BASE_CHAIN_WALLET_KEY env var is set. */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+interface ChatOptions {
+    /** System prompt */
+    system?: string;
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    search?: boolean;
+    /** Full xAI Live Search configuration (for Grok models) */
+    searchParameters?: SearchParameters;
+}
+interface ChatCompletionOptions {
+    /** Max tokens to generate */
+    maxTokens?: number;
+    /** Sampling temperature */
+    temperature?: number;
+    /** Nucleus sampling parameter */
+    topP?: number;
+    /** Enable xAI Live Search (shortcut for searchParameters.mode = "on") */
+    search?: boolean;
+    /** Full xAI Live Search configuration (for Grok models) */
+    searchParameters?: SearchParameters;
+}
+declare class BlockrunError extends Error {
+    constructor(message: string);
+}
+declare class PaymentError extends BlockrunError {
+    constructor(message: string);
+}
+declare class APIError extends BlockrunError {
+    statusCode: number;
+    response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+
+/**
+ * BlockRun LLM Client - Main SDK entry point.
+ *
+ * Usage:
+ *   import { LLMClient } from '@blockrun/llm';
+ *
+ *   // Option 1: Use BASE_CHAIN_WALLET_KEY env var
+ *   const client = new LLMClient();
+ *
+ *   // Option 2: Pass private key directly
+ *   const client = new LLMClient({ privateKey: '0x...' });
+ *
+ *   const response = await client.chat('openai/gpt-4o', 'Hello!');
+ *   console.log(response);
+ */
+
+/**
+ * BlockRun LLM Gateway Client.
+ *
+ * Provides access to multiple LLM providers (OpenAI, Anthropic, Google, etc.)
+ * with automatic x402 micropayments on Base chain.
+ */
+declare class LLMClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    /**
+     * Initialize the BlockRun LLM client.
+     *
+     * @param options - Client configuration options (optional if BASE_CHAIN_WALLET_KEY env var is set)
+     */
+    constructor(options?: LLMClientOptions);
+    /**
+     * Simple 1-line chat interface.
+     *
+     * @param model - Model ID (e.g., 'openai/gpt-4o', 'anthropic/claude-sonnet-4')
+     * @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?');
+     * console.log(response); // 'The capital of France is Paris.'
+     */
+    chat(model: string, prompt: string, options?: ChatOptions): Promise<string>;
+    /**
+     * Full chat completion interface (OpenAI-compatible).
+     *
+     * @param model - Model ID
+     * @param messages - Array of messages with role and content
+     * @param options - Optional completion parameters
+     * @returns ChatResponse object with choices and usage
+     */
+    chatCompletion(model: string, messages: ChatMessage[], options?: ChatCompletionOptions): Promise<ChatResponse>;
+    /**
+     * Make a request with automatic x402 payment handling.
+     */
+    private requestWithPayment;
+    /**
+     * Handle 402 response: parse requirements, sign payment, retry.
+     */
+    private handlePaymentAndRetry;
+    /**
+     * Fetch with timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * List available LLM models with pricing.
+     */
+    listModels(): Promise<Model[]>;
+    /**
+     * List available image generation models with pricing.
+     */
+    listImageModels(): Promise<ImageModel[]>;
+    /**
+     * List all available models (both LLM and image) with pricing.
+     *
+     * @returns Array of all models with 'type' field ('llm' or 'image')
+     *
+     * @example
+     * const models = await client.listAllModels();
+     * for (const model of models) {
+     *   if (model.type === 'llm') {
+     *     console.log(`LLM: ${model.id} - $${model.inputPrice}/M input`);
+     *   } else {
+     *     console.log(`Image: ${model.id} - $${model.pricePerImage}/image`);
+     *   }
+     * }
+     */
+    listAllModels(): Promise<(Model | ImageModel)[]>;
+    /**
+     * Get current session spending.
+     *
+     * @returns Object with totalUsd and calls count
+     *
+     * @example
+     * const spending = client.getSpending();
+     * console.log(`Spent $${spending.totalUsd.toFixed(4)} across ${spending.calls} calls`);
+     */
+    getSpending(): Spending;
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+/**
+ * BlockRun Image Client - Generate images 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 { ImageClient } from '@blockrun/llm';
+ *
+ *   const client = new ImageClient({ privateKey: '0x...' });
+ *   const result = await client.generate('A cute cat in space');
+ *   console.log(result.data[0].url);
+ */
+
+/**
+ * BlockRun Image Generation Client.
+ *
+ * Generate images using Nano Banana (Google Gemini), DALL-E 3, or GPT Image
+ * with automatic x402 micropayments on Base chain.
+ */
+declare class ImageClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    /**
+     * Initialize the BlockRun Image client.
+     *
+     * @param options - Client configuration options
+     */
+    constructor(options?: ImageClientOptions);
+    /**
+     * Generate an image from a text prompt.
+     *
+     * @param prompt - Text description of the image to generate
+     * @param options - Optional generation parameters
+     * @returns ImageResponse with generated image URLs
+     *
+     * @example
+     * const result = await client.generate('A sunset over mountains');
+     * console.log(result.data[0].url);
+     */
+    generate(prompt: string, options?: ImageGenerateOptions): Promise<ImageResponse>;
+    /**
+     * List available image generation models with pricing.
+     */
+    listImageModels(): Promise<ImageModel[]>;
+    /**
+     * Make a request with automatic x402 payment handling.
+     */
+    private requestWithPayment;
+    /**
+     * Handle 402 response: parse requirements, sign payment, retry.
+     */
+    private handlePaymentAndRetry;
+    /**
+     * Fetch with timeout.
+     */
+    private fetchWithTimeout;
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+    /**
+     * Get session spending information.
+     */
+    getSpending(): Spending;
+}
+
+/**
+ * x402 Payment Protocol v2 Implementation for BlockRun.
+ *
+ * This module handles creating signed payment payloads for the x402 v2 protocol.
+ * The private key is used ONLY for local signing and NEVER leaves the client.
+ */
+
+declare const BASE_CHAIN_ID = 8453;
+declare const USDC_BASE: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+
+/**
+ * BlockRun Wallet Management - Auto-create and manage wallets.
+ *
+ * Provides frictionless wallet setup for new users:
+ * - Auto-creates wallet if none exists
+ * - Stores key securely at ~/.blockrun/.session
+ * - Generates EIP-681 URIs for easy MetaMask funding
+ */
+declare const USDC_BASE_CONTRACT = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+interface WalletInfo {
+    privateKey: string;
+    address: string;
+    isNew: boolean;
+}
+interface PaymentLinks {
+    basescan: string;
+    walletLink: string;
+    ethereum: string;
+    blockrun: string;
+}
+/**
+ * Create a new Ethereum wallet.
+ *
+ * @returns Object with address and privateKey
+ */
+declare function createWallet(): {
+    address: string;
+    privateKey: string;
+};
+/**
+ * Save wallet private key to ~/.blockrun/.session
+ *
+ * @param privateKey - Private key string (with 0x prefix)
+ * @returns Path to saved wallet file
+ */
+declare function saveWallet(privateKey: string): string;
+/**
+ * Load wallet private key from file.
+ *
+ * @returns Private key string or null if not found
+ */
+declare function loadWallet(): string | null;
+/**
+ * Get existing wallet or create new one.
+ *
+ * Priority:
+ * 1. BLOCKRUN_WALLET_KEY environment variable
+ * 2. ~/.blockrun/.session file
+ * 3. ~/.blockrun/wallet.key file (legacy)
+ * 4. Create new wallet
+ *
+ * @returns WalletInfo with address, privateKey, and isNew flag
+ */
+declare function getOrCreateWallet(): WalletInfo;
+/**
+ * Get wallet address without exposing private key.
+ *
+ * @returns Wallet address or null if no wallet configured
+ */
+declare function getWalletAddress(): string | null;
+/**
+ * Generate EIP-681 URI for USDC transfer on Base.
+ *
+ * @param address - Recipient Ethereum address
+ * @param amountUsdc - Amount in USDC (default 1.0)
+ * @returns EIP-681 URI string for MetaMask/wallet scanning
+ */
+declare function getEip681Uri(address: string, amountUsdc?: number): string;
+/**
+ * Generate payment links for the wallet address.
+ *
+ * @param address - Ethereum address
+ * @returns Object with various payment links
+ */
+declare function getPaymentLinks(address: string): PaymentLinks;
+/**
+ * Format the message shown when a new wallet is created.
+ *
+ * @param address - New wallet address
+ * @returns Formatted message string
+ */
+declare function formatWalletCreatedMessage(address: string): string;
+/**
+ * Format the message shown when wallet needs more funds.
+ *
+ * @param address - Wallet address
+ * @returns Formatted message string
+ */
+declare function formatNeedsFundingMessage(address: string): string;
+/**
+ * Compact funding message (no QR) for repeated displays.
+ *
+ * @param address - Wallet address
+ * @returns Short formatted message string
+ */
+declare function formatFundingMessageCompact(address: string): string;
+declare const WALLET_FILE_PATH: string;
+declare const WALLET_DIR_PATH: string;
+
+/**
+ * OpenAI-compatible API wrapper for BlockRun LLM SDK.
+ *
+ * Drop-in replacement for OpenAI SDK - just change the import and use walletKey instead of apiKey.
+ *
+ * @example
+ * // Before (OpenAI)
+ * import OpenAI from 'openai';
+ * const client = new OpenAI({ apiKey: 'sk-...' });
+ *
+ * // After (BlockRun)
+ * import { OpenAI } from '@blockrun/llm';
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * // Rest of your code stays exactly the same!
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ */
+
+interface OpenAIClientOptions {
+    /** EVM wallet private key (replaces apiKey) */
+    walletKey?: `0x${string}` | string;
+    /** Alternative: use privateKey like LLMClient */
+    privateKey?: `0x${string}` | string;
+    /** API endpoint URL (default: https://blockrun.ai/api) */
+    baseURL?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface OpenAIChatCompletionParams {
+    model: string;
+    messages: Array<{
+        role: "system" | "user" | "assistant";
+        content: string;
+    }>;
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stream?: boolean;
+    n?: number;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+}
+interface OpenAIChatCompletionChoice {
+    index: number;
+    message: {
+        role: "assistant";
+        content: string;
+    };
+    finish_reason: string | null;
+}
+interface OpenAIChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: OpenAIChatCompletionChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+interface OpenAIChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: "assistant";
+            content?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+/**
+ * Chat completions API (OpenAI-compatible)
+ */
+declare class ChatCompletions {
+    private client;
+    private apiUrl;
+    private timeout;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+    /**
+     * Create a chat completion (OpenAI-compatible).
+     */
+    create(params: OpenAIChatCompletionParams): Promise<OpenAIChatCompletionResponse>;
+    create(params: OpenAIChatCompletionParams & {
+        stream: true;
+    }): Promise<AsyncIterable<OpenAIChatCompletionChunk>>;
+    private createStream;
+    private transformResponse;
+}
+/**
+ * Chat API namespace
+ */
+declare class Chat {
+    completions: ChatCompletions;
+    constructor(client: LLMClient, apiUrl: string, timeout: number);
+}
+/**
+ * OpenAI-compatible client for BlockRun.
+ *
+ * Drop-in replacement for the OpenAI SDK.
+ *
+ * @example
+ * import { OpenAI } from '@blockrun/llm';
+ *
+ * const client = new OpenAI({ walletKey: '0x...' });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ *
+ * console.log(response.choices[0].message.content);
+ */
+declare class OpenAI {
+    chat: Chat;
+    private client;
+    constructor(options?: OpenAIClientOptions);
+    /**
+     * Get the wallet address being used for payments.
+     */
+    getWalletAddress(): string;
+}
+
+export { APIError, BASE_CHAIN_ID, BlockrunError, type ChatChoice, type ChatCompletionOptions, type ChatMessage, type ChatOptions, type ChatResponse, type ChatUsage, 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 RssSearchSource, type SearchParameters, type SearchSource, type Spending, 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 };