@blockrun/llm 2.5.0 → 2.8.0

package/dist/index.d.ts

@@ -494,6 +494,13 @@ interface VideoGenerateOptions {
     model?: "xai/grok-imagine-video" | string;
     /** Optional seed image URL for image-to-video */
     imageUrl?: string;
+    /**
+     * Virtual Portrait asset ID (`ta_xxxxxx`) — keeps the same AI character
+     * across multiple Seedance videos. Enroll via `POST /v1/portrait/enroll`
+     * ($0.01 USDC promo, no KYC). **Seedance 2.0 fast/pro only.** Mutually exclusive
+     * with `imageUrl`. Real-person likeness is not supported on BlockRun.
+     */
+    realFaceAssetId?: string;
     /** Duration to bill for (defaults to model's default duration) */
     durationSeconds?: number;
     /** Output aspect ratio. Token360 / Seedance only — silently ignored by xAI Grok. */
@@ -501,11 +508,12 @@ interface VideoGenerateOptions {
     /** Output resolution. Token360 / Seedance only. */
     resolution?: "360p" | "480p" | "540p" | "720p" | "1080p" | "1K" | "2K" | "4K";
     /**
-     * Whether the model should produce an audio track. Token360 / Seedance only.
-     * When omitted, the gateway does not send the flag — Token360 then applies
-     * its own upstream default (typically off, occasionally on depending on
-     * model variant / prompt). Audio generation is usually a paid surcharge,
-     * so callers should expose this as a visible toggle to their users.
+     * Whether the model should produce a synced audio track. Token360 / Seedance
+     * only — silently ignored by xAI Grok. When omitted, the gateway defaults to
+     * `true` for text-to-video and `false` for image- or face-conditioned
+     * generation (the t2v / i2v split that matches Token360's quality profile).
+     * Pass an explicit boolean to override. Audio generation may be a paid
+     * surcharge upstream, so callers should expose this as a visible toggle.
      */
     generateAudio?: boolean;
     /** Reproducibility seed when supported by the model. */
@@ -790,6 +798,132 @@ interface SurfClientOptions {
     apiUrl?: string;
     timeout?: number;
 }
+interface PhoneClientOptions {
+    /** 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: 60000) */
+    timeout?: number;
+}
+/**
+ * Twilio Lookup passthrough — shape comes from upstream and varies by feature
+ * (basic vs `line_type_intelligence`, `sim_swap`, `call_forwarding`).
+ * Typed as a permissive record so future Twilio fields don't require an SDK release.
+ */
+interface PhoneLookupResponse {
+    phone_number?: string;
+    country_code?: string;
+    national_format?: string;
+    caller_name?: Record<string, unknown> | null;
+    carrier?: Record<string, unknown> | null;
+    line_type_intelligence?: Record<string, unknown> | null;
+    sim_swap?: Record<string, unknown> | null;
+    call_forwarding?: Record<string, unknown> | null;
+    /** Pass-through for anything Twilio adds. */
+    [key: string]: unknown;
+}
+interface PhoneBuyOptions {
+    /** ISO country code, "US" or "CA" (default "US"). */
+    country?: "US" | "CA";
+    /**
+     * Optional 3-digit area-code hint. Availability is not guaranteed — the
+     * backend falls back to any number in the country if the area code
+     * can't be matched.
+     */
+    areaCode?: string;
+}
+interface PhoneBuyResponse {
+    /** The E.164 number now bound to your wallet. */
+    phone_number: string;
+    /** ISO-8601 expiry (30 days out from purchase). */
+    expires_at: string;
+    /** "base" | "solana" — settlement chain. */
+    chain: string;
+    /** Human-readable note. */
+    message?: string;
+    /** On-chain payment receipt (tx hash). */
+    txHash?: string;
+}
+interface PhoneRenewResponse {
+    phone_number: string;
+    /** Extended expiry (30 days from previous expiry). */
+    expires_at: string;
+    txHash?: string;
+}
+interface PhoneNumberRecord {
+    phone_number: string;
+    chain: string;
+    expires_at: string;
+    active: boolean;
+}
+interface PhoneListResponse {
+    numbers: PhoneNumberRecord[];
+    count: number;
+    txHash?: string;
+}
+interface PhoneReleaseResponse {
+    released: true;
+    phone_number: string;
+    txHash?: string;
+}
+interface PortraitClientOptions {
+    /** 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: 60000) */
+    timeout?: number;
+}
+interface PortraitEnrollOptions {
+    /** Display name for the portrait (1–64 chars). */
+    name: string;
+    /**
+     * Public HTTPS URL to a JPG/PNG/WEBP face image (≤10 MB). The gateway fetches
+     * it server-side and forwards it to Token360 as multipart — only the URL is sent.
+     */
+    imageUrl: string;
+}
+/**
+ * Response from `POST /v1/portrait/enroll`. The `asset_id` (`ta_xxxxxx`) is what
+ * you pass as `realFaceAssetId` on a Seedance 2.0 video generation to keep the
+ * same AI character across clips.
+ */
+interface PortraitEnrollResponse {
+    object: "virtual_portrait";
+    /** Token360 asset id (`ta_xxxxxx`) — pass as `realFaceAssetId` in VideoGenerateOptions. */
+    asset_id: string;
+    /** Token360 asset-group id (internal/debugging). */
+    group_id: string;
+    name: string;
+    /**
+     * Persisted thumbnail URL. The gateway mirrors your source image to its own
+     * storage when possible (so the listing thumbnail survives a dead source
+     * host); falls back to the original URL if mirroring fails. See `mirrored`.
+     */
+    image_url: string;
+    /** The original URL you supplied (before any mirroring). */
+    source_image_url?: string;
+    /** Whether `image_url` is the gateway-mirrored copy (true) or your original (false). */
+    mirrored?: boolean;
+    /** ISO-8601 creation timestamp. */
+    created_at: string;
+    usage: {
+        compatible_models: string[];
+        how_to_use: string;
+    };
+    price: {
+        amount: string;
+        currency: string;
+    };
+    settlement: {
+        success: boolean;
+        tx_hash: string | null;
+        network: string;
+    };
+    /** On-chain payment receipt (tx hash), surfaced from the response header. */
+    txHash?: string;
+}
 interface BlockrunClientOptions {
     privateKey?: `0x${string}` | string;
     apiUrl?: string;
@@ -1597,6 +1731,175 @@ declare class VoiceClient {
     getSpending(): Spending;
 }
 
+/**
+ * BlockRun Phone Client — Twilio-backed phone lookup + number provisioning via x402.
+ *
+ * Endpoints (all under /v1/phone/...):
+ *   POST /lookup            $0.01    Carrier + line-type lookup
+ *   POST /lookup/fraud      $0.05    Carrier + SIM-swap / call-forwarding signals
+ *   POST /numbers/buy       $5.00    Provision a US/CA number (30-day lease, bound to wallet)
+ *   POST /numbers/renew     $5.00    Extend an existing number by 30 days
+ *   POST /numbers/list      $0.001   List the wallet's active numbers
+ *   POST /numbers/release   free     Release a provisioned number (still flows through x402
+ *                                    so the backend can verify wallet identity)
+ *
+ * After buying a number you can use it as the `from` caller ID in VoiceClient.call().
+ *
+ * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
+ * signatures are sent in the PAYMENT-SIGNATURE header.
+ *
+ * @example
+ *   import { PhoneClient } from '@blockrun/llm';
+ *
+ *   const client = new PhoneClient({ privateKey: '0x...' });
+ *
+ *   // Lookup a number
+ *   const info = await client.lookup('+14155552671');
+ *
+ *   // Buy a number (US, optional area code)
+ *   const bought = await client.buyNumber({ country: 'US', areaCode: '415' });
+ *   console.log(bought.phone_number, bought.expires_at);
+ *
+ *   // List your active numbers
+ *   console.log(await client.listNumbers());
+ *
+ *   // Renew / release
+ *   await client.renewNumber(bought.phone_number);
+ *   await client.releaseNumber(bought.phone_number);
+ */
+
+/** Per-endpoint price in USD — mirrors the backend's `PHONE_PRICES`. */
+declare const PHONE_PRICES: Readonly<Record<string, number>>;
+/**
+ * BlockRun Phone Client.
+ *
+ * Wraps the `/v1/phone/*` x402 endpoints — phone-number lookup (carrier + fraud)
+ * and provisioning of the caller-ID numbers required by VoiceClient.call().
+ */
+declare class PhoneClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: PhoneClientOptions);
+    /** EVM wallet address used for payments. */
+    getWalletAddress(): string;
+    /** Session-cumulative USD spend + call count across this client instance. */
+    getSpending(): Spending;
+    /**
+     * Carrier + line-type lookup. ~$0.01.
+     *
+     * @param phoneNumber E.164 number (e.g. "+14155552671").
+     */
+    lookup(phoneNumber: string): Promise<PhoneLookupResponse>;
+    /**
+     * Lookup + fraud signals (SIM swap, call forwarding). ~$0.05.
+     *
+     * @param phoneNumber E.164 number.
+     */
+    lookupFraud(phoneNumber: string): Promise<PhoneLookupResponse>;
+    /**
+     * Provision a dedicated phone number for 30 days. $5.00.
+     *
+     * Payment is settled only after Twilio confirms the purchase, so failed
+     * buys never charge your wallet.
+     *
+     * @param options.country  ISO country code, "US" or "CA" (default "US").
+     * @param options.areaCode Optional 3-digit area-code hint. Availability is
+     *   not guaranteed — the backend falls back to any number in the country if
+     *   the area code can't be matched.
+     */
+    buyNumber(options?: PhoneBuyOptions): Promise<PhoneBuyResponse>;
+    /**
+     * Extend an existing provisioned number by 30 days. $5.00.
+     *
+     * @throws {APIError} 403 when the wallet doesn't own the number or it has expired.
+     */
+    renewNumber(phoneNumber: string): Promise<PhoneRenewResponse>;
+    /** List the wallet's active phone numbers. ~$0.001. */
+    listNumbers(): Promise<PhoneListResponse>;
+    /**
+     * Release a provisioned number back to the Twilio pool. Free, but still
+     * flows through x402 so the backend can verify ownership.
+     */
+    releaseNumber(phoneNumber: string): Promise<PhoneReleaseResponse>;
+    private request;
+    private handlePaymentAndRetry;
+    private unwrap;
+    private fetchWithTimeout;
+}
+
+/**
+ * BlockRun Portrait Client — enroll a Virtual Portrait via x402.
+ *
+ * Wraps `POST /v1/portrait/enroll` ($0.01 USDC promo, no KYC). You upload a face image
+ * by URL and get back a Token360 asset id (`ta_xxxxxx`). Pass that id as
+ * `realFaceAssetId` on a Seedance 2.0 video generation (VideoClient.generate)
+ * to keep the same AI character across clips.
+ *
+ * SECURITY NOTE — your private key never leaves your machine. Only EIP-712
+ * signatures are sent in the PAYMENT-SIGNATURE header.
+ *
+ * @example
+ *   import { PortraitClient, VideoClient } from '@blockrun/llm';
+ *
+ *   const portraits = new PortraitClient({ privateKey: '0x...' });
+ *   const { asset_id } = await portraits.enroll({
+ *     name: 'Spokesperson',
+ *     imageUrl: 'https://example.com/face.jpg',
+ *   });
+ *
+ *   const video = new VideoClient({ privateKey: '0x...' });
+ *   const clip = await video.generate('she waves and smiles', {
+ *     model: 'bytedance/seedance-2.0-fast',
+ *     realFaceAssetId: asset_id,
+ *   });
+ */
+
+/**
+ * Flat enrollment price in USD — mirrors the backend's `ENROLLMENT_PRICE_USD`.
+ * Currently $0.01 (promotional, parity with RealFace). The authoritative price
+ * is whatever the gateway quotes in the 402; this constant is informational.
+ */
+declare const PORTRAIT_ENROLLMENT_PRICE_USD = 0.01;
+/**
+ * BlockRun Portrait Client.
+ *
+ * Enrolls a Virtual Portrait from a face image URL and returns the `ta_xxxxxx`
+ * asset id consumed by Seedance 2.0 video generation. Real-person likeness is
+ * not supported on BlockRun — enrolled portraits are AI characters.
+ */
+declare class PortraitClient {
+    private account;
+    private privateKey;
+    private apiUrl;
+    private timeout;
+    private sessionTotalUsd;
+    private sessionCalls;
+    constructor(options?: PortraitClientOptions);
+    /** EVM wallet address used for payments. */
+    getWalletAddress(): string;
+    /** Session-cumulative USD spend + call count across this client instance. */
+    getSpending(): Spending;
+    /**
+     * Enroll a Virtual Portrait from a face image URL. $0.01 (promo).
+     *
+     * Payment is settled only after Token360 confirms the enrollment, so failed
+     * enrollments never charge your wallet.
+     *
+     * @param options.name     Display name (1–64 chars).
+     * @param options.imageUrl Public HTTPS URL to a JPG/PNG/WEBP image (≤10 MB).
+     * @returns The enrollment record, including `asset_id` (`ta_xxxxxx`).
+     */
+    enroll(options: PortraitEnrollOptions): Promise<PortraitEnrollResponse>;
+    private request;
+    private handlePaymentAndRetry;
+    private unwrap;
+    private fetchWithTimeout;
+}
+
 /**
  * BlockRun Search Client - Standalone Grok Live Search via x402 micropayments.
  *
@@ -1963,6 +2266,11 @@ interface CreateSolanaPaymentOptions {
     extra?: Record<string, unknown>;
     extensions?: Record<string, unknown>;
     rpcUrl?: string;
+    /**
+     * Optional HTTP headers forwarded to the Solana RPC endpoint
+     * (e.g. `{ "x-api-key": "..." }` for Tatum / header-auth gateways).
+     */
+    rpcHeaders?: Record<string, string>;
 }
 /**
  * Create a signed Solana x402 v2 payment payload.
@@ -2152,8 +2460,21 @@ interface SolanaLLMClientOptions {
     privateKey?: string;
     /** API endpoint URL (default: https://sol.blockrun.ai/api) */
     apiUrl?: string;
-    /** Solana RPC URL (default: https://api.mainnet-beta.solana.com) */
+    /**
+     * Solana JSON-RPC URL. Defaults to BlockRun's own Tatum-backed proxy
+     * (`https://sol.blockrun.ai/api/v1/solana/rpc`), free for SDK users.
+     * Override to point at your own Helius / Tatum / QuickNode account, or
+     * fall back to the env vars `SOLANA_RPC_URL` /
+     * `SOLANA_RPC_API_KEY` / `SOLANA_RPC_HEADERS`.
+     */
     rpcUrl?: string;
+    /**
+     * Optional headers forwarded to the Solana RPC endpoint. Use this for
+     * header-auth gateways (Tatum's `x-api-key`, some Triton tiers). Falls
+     * back to `SOLANA_RPC_HEADERS` (JSON dict) or `SOLANA_RPC_API_KEY`
+     * (shortcut for `{ "x-api-key": "..." }`) env vars when omitted.
+     */
+    rpcHeaders?: Record<string, string>;
     /** Request timeout in milliseconds (default: 60000) */
     timeout?: number;
 }
@@ -2162,6 +2483,7 @@ declare class SolanaLLMClient {
     private privateKey;
     private apiUrl;
     private rpcUrl;
+    private rpcHeaders?;
     private timeout;
     private sessionTotalUsd;
     private sessionCalls;
@@ -2566,4 +2888,4 @@ declare function validateTemperature(temperature?: number): void;
  */
 declare function validateTopP(topP?: number): void;
 
-export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, 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 PollOptions, 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, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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, validateMaxTokens, validateModel, validateTemperature, validateTopP };
+export { APIError, AnthropicClient, type AudioModel, type AudioTrack, BASE_CHAIN_ID, type BarResolution, type BlockRunAnthropicOptions, BlockrunClient, type BlockrunClientOptions, BlockrunError, type CallInitiatedResponse, type CallModel, type CallOptions, type CallStatusResponse, 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, PHONE_PRICES, PORTRAIT_ENROLLMENT_PRICE_USD, PaymentError, type PaymentLinks, type PhoneBuyOptions, type PhoneBuyResponse, PhoneClient, type PhoneClientOptions, type PhoneListResponse, type PhoneLookupResponse, type PhoneNumberRecord, type PhoneReleaseResponse, type PhoneRenewResponse, type PollOptions, PortraitClient, type PortraitClientOptions, type PortraitEnrollOptions, type PortraitEnrollResponse, 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, SurfClient, type SurfClientOptions, type SymbolListResponse, type Tool, type ToolCall, type ToolChoice, USDC_BASE, USDC_BASE_CONTRACT, USDC_SOLANA, VideoClient, type VideoClientOptions, type VideoClip, type VideoGenerateOptions, type VideoModel, type VideoResponse, VoiceClient, type VoiceClientOptions, type VoicePreset, 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, validateMaxTokens, validateModel, validateTemperature, validateTopP };