@chain-lens/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,284 @@
+import { WalletClient } from 'viem';
+
+interface ChainLensConfig {
+    /** Base URL of the Gateway. Default: https://chainlens.pelicanlab.dev */
+    gatewayUrl?: string;
+    /** Wallet adapter — must be able to sign EIP-3009 typed data. */
+    wallet: WalletAdapter;
+    /** Off-chain budget enforcement. */
+    budget?: {
+        perCallMaxUsdc?: number;
+        dailyMaxUsdc?: number;
+        monthlyMaxUsdc?: number;
+    };
+    /** Local telemetry config. */
+    telemetry?: {
+        /** Default: true */
+        enabled?: boolean;
+        /** Upload to Gateway. Default: false (explicit opt-in). */
+        upload?: boolean;
+        /** Max entries in local JSONL buffer. Default: 1000. */
+        bufferMaxEntries?: number;
+    };
+    /** Auto-fallback on provider failure. */
+    fallback?: {
+        enabled: boolean;
+        /** Total attempts including primary. Default: 2. */
+        maxAttempts?: number;
+    };
+    /** Chain ID. 84532 = Base Sepolia, 8453 = Base Mainnet. */
+    chainId: 84532 | 8453;
+}
+interface WalletAdapter {
+    address(): Promise<`0x${string}`>;
+    signTypedData(typedData: TypedData): Promise<{
+        v: number;
+        r: `0x${string}`;
+        s: `0x${string}`;
+    }>;
+    sendTransaction(tx: TxRequest): Promise<`0x${string}`>;
+}
+interface TypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+interface TxRequest {
+    to: `0x${string}`;
+    data?: `0x${string}`;
+    value?: bigint;
+}
+interface CallOptions {
+    fallback?: boolean;
+    maxUsdc?: number;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+interface CallResult<T = unknown> {
+    ok: true;
+    data: T;
+    listingId: number;
+    amountUsdc: number;
+    feeUsdc: number;
+    netUsdc: number;
+    settlement: {
+        txHash: `0x${string}`;
+        blockNumber: number;
+    };
+    latencyMs: number;
+    attemptIndex: number;
+}
+interface RankedListing {
+    listingId: number | null;
+    name: string | null;
+    score: number;
+    reasons: string[];
+    source: "chainlens" | "coinbase_bazaar" | "fixture";
+    verifiedByChainLens: boolean;
+    resource?: string;
+    network?: string;
+    asset?: string;
+    payTo?: string;
+    stats: {
+        successRate: number;
+        p50LatencyMs: number;
+        p95LatencyMs: number;
+        avgCostUsdc: number;
+        sampleSize: number;
+    };
+}
+interface FailureMetadata {
+    kind: "schema_mismatch" | "http_4xx" | "http_5xx" | "timeout" | "auth" | "rate_limit" | "gateway_error" | "budget" | "sign" | "resolve" | "unknown";
+    hint: string;
+    providerStatus?: number;
+    evaluatorLayer?: 1 | 2 | 3 | 4;
+    rawProviderError?: string;
+}
+interface ListingInfo {
+    listingId: number;
+    name: string | null;
+    priceAtomic: string | null;
+    maxLatencyMs: number;
+    taskCategory: string;
+    outputSchema: unknown | null;
+    payout: string;
+    active: boolean;
+}
+interface BudgetConfig {
+    perCallMaxUsdc: number;
+    dailyMaxUsdc: number;
+    monthlyMaxUsdc: number;
+}
+
+interface ClaimableResult {
+    totalUsdc: number;
+    atomicBalance: string;
+}
+interface ListingDashboard {
+    listingId: number;
+    name: string | null;
+    totalEarnedUsdc: number;
+    claimableUsdc: number;
+    callCount: number;
+    successRate: number;
+    p50LatencyMs: number;
+}
+declare class ProviderClient {
+    private readonly gatewayUrl;
+    private readonly wallet;
+    constructor(gatewayUrl: string, wallet: WalletAdapter);
+    claimable(): Promise<ClaimableResult>;
+    claim(): Promise<{
+        txHash: `0x${string}`;
+    } | {
+        skipped: true;
+    }>;
+    listingDashboard(listingId: number): Promise<ListingDashboard>;
+}
+
+declare class ChainLens {
+    private readonly cfg;
+    private budget;
+    private telemetry;
+    private walletAddress;
+    readonly provider: ProviderClient;
+    constructor(cfg: ChainLensConfig);
+    private init;
+    call<T = unknown>(listingId: number, params: unknown, options?: CallOptions): Promise<CallResult<T>>;
+    recommend(task: string, maxResults?: number): Promise<RankedListing[]>;
+    currentSpend(): Promise<{
+        dailyUsdc: number;
+        monthlyUsdc: number;
+    }>;
+}
+
+/**
+ * WalletAdapter backed by a viem WalletClient.
+ *
+ * Usage:
+ *   const walletClient = createWalletClient({ account, chain, transport });
+ *   const wallet = new ViemWallet(walletClient);
+ */
+declare class ViemWallet implements WalletAdapter {
+    private readonly client;
+    constructor(client: WalletClient);
+    address(): Promise<`0x${string}`>;
+    signTypedData(typedData: TypedData): Promise<{
+        v: number;
+        r: `0x${string}`;
+        s: `0x${string}`;
+    }>;
+    sendTransaction(tx: TxRequest): Promise<`0x${string}`>;
+}
+
+/**
+ * Off-chain rolling-window budget controller.
+ *
+ * Persists spend records to LevelDB under ~/.chainlens/budget/<wallet>/.
+ * Falls back to in-memory when LevelDB is unavailable (browser / ephemeral).
+ */
+declare class BudgetController {
+    private readonly cfg;
+    private db;
+    private readonly walletAddress;
+    private initPromise;
+    constructor(walletAddress: string, cfg?: Partial<BudgetConfig>);
+    private getDb;
+    private openDb;
+    canSpend(amount: number): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    debit(amount: number, idempotencyKey?: string): Promise<void>;
+    currentSpend(): Promise<{
+        dailyUsdc: number;
+        monthlyUsdc: number;
+    }>;
+}
+
+declare class ChainLensError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(message: string, code: string, cause?: unknown);
+}
+/** Listing not found or task query produced no match. */
+declare class ChainLensResolveError extends ChainLensError {
+    constructor(message: string, cause?: unknown);
+}
+/** Off-chain budget limit exceeded before any signature was produced. */
+declare class BudgetExceededError extends ChainLensError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** EIP-3009 signing failed. */
+declare class ChainLensSignError extends ChainLensError {
+    constructor(message: string, cause?: unknown);
+}
+/** Gateway returned a non-200 HTTP status. */
+declare class ChainLensGatewayError extends ChainLensError {
+    readonly status: number;
+    constructor(message: string, status: number, cause?: unknown);
+}
+/** The call completed but the provider reported failure (no settlement). */
+declare class ChainLensCallError extends ChainLensError {
+    readonly failure: FailureMetadata;
+    constructor(failure: FailureMetadata);
+}
+
+/** Chain-specific USDC contract addresses. */
+declare const USDC_ADDRESSES: Record<number, `0x${string}`>;
+/** ChainLensMarket addresses per chain. */
+declare const CHAIN_LENS_MARKET_ADDRESSES: Record<number, `0x${string}`>;
+interface Eip3009Auth {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    amount: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: `0x${string}`;
+    v: number;
+    r: `0x${string}`;
+    s: `0x${string}`;
+}
+declare function signReceiveWithAuthorization(opts: {
+    wallet: WalletAdapter;
+    chainId: number;
+    amount: bigint;
+    to: `0x${string}`;
+    signal?: AbortSignal;
+}): Promise<Eip3009Auth>;
+/** Convert USDC display units (e.g. 0.05) to atomic units (50000). */
+declare function usdcToAtomic(usdc: number): bigint;
+/** Convert atomic USDC units to display units. */
+declare function atomicToUsdc(atomic: bigint | string): number;
+
+interface TelemetryEntry {
+    ts: number;
+    listingId: number;
+    amountUsdc: number;
+    latencyMs: number;
+    ok: boolean;
+    failure?: FailureMetadata;
+    txHash?: string;
+    paramsHash?: string;
+}
+interface TelemetryConfig {
+    enabled: boolean;
+    upload: boolean;
+    bufferMaxEntries: number;
+    gatewayUrl: string;
+    walletAddress: string;
+}
+
+export { type BudgetConfig, BudgetController, BudgetExceededError, CHAIN_LENS_MARKET_ADDRESSES, type CallOptions, type CallResult, ChainLens, ChainLensCallError, type ChainLensConfig, ChainLensError, ChainLensGatewayError, ChainLensResolveError, ChainLensSignError, type ClaimableResult, type FailureMetadata, type ListingDashboard, type ListingInfo, ProviderClient, type RankedListing, type TelemetryConfig, type TelemetryEntry, type TxRequest, type TypedData, USDC_ADDRESSES, ViemWallet, type WalletAdapter, atomicToUsdc, signReceiveWithAuthorization, usdcToAtomic };

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+import { WalletClient } from 'viem';
+
+interface ChainLensConfig {
+    /** Base URL of the Gateway. Default: https://chainlens.pelicanlab.dev */
+    gatewayUrl?: string;
+    /** Wallet adapter — must be able to sign EIP-3009 typed data. */
+    wallet: WalletAdapter;
+    /** Off-chain budget enforcement. */
+    budget?: {
+        perCallMaxUsdc?: number;
+        dailyMaxUsdc?: number;
+        monthlyMaxUsdc?: number;
+    };
+    /** Local telemetry config. */
+    telemetry?: {
+        /** Default: true */
+        enabled?: boolean;
+        /** Upload to Gateway. Default: false (explicit opt-in). */
+        upload?: boolean;
+        /** Max entries in local JSONL buffer. Default: 1000. */
+        bufferMaxEntries?: number;
+    };
+    /** Auto-fallback on provider failure. */
+    fallback?: {
+        enabled: boolean;
+        /** Total attempts including primary. Default: 2. */
+        maxAttempts?: number;
+    };
+    /** Chain ID. 84532 = Base Sepolia, 8453 = Base Mainnet. */
+    chainId: 84532 | 8453;
+}
+interface WalletAdapter {
+    address(): Promise<`0x${string}`>;
+    signTypedData(typedData: TypedData): Promise<{
+        v: number;
+        r: `0x${string}`;
+        s: `0x${string}`;
+    }>;
+    sendTransaction(tx: TxRequest): Promise<`0x${string}`>;
+}
+interface TypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: `0x${string}`;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+interface TxRequest {
+    to: `0x${string}`;
+    data?: `0x${string}`;
+    value?: bigint;
+}
+interface CallOptions {
+    fallback?: boolean;
+    maxUsdc?: number;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+interface CallResult<T = unknown> {
+    ok: true;
+    data: T;
+    listingId: number;
+    amountUsdc: number;
+    feeUsdc: number;
+    netUsdc: number;
+    settlement: {
+        txHash: `0x${string}`;
+        blockNumber: number;
+    };
+    latencyMs: number;
+    attemptIndex: number;
+}
+interface RankedListing {
+    listingId: number | null;
+    name: string | null;
+    score: number;
+    reasons: string[];
+    source: "chainlens" | "coinbase_bazaar" | "fixture";
+    verifiedByChainLens: boolean;
+    resource?: string;
+    network?: string;
+    asset?: string;
+    payTo?: string;
+    stats: {
+        successRate: number;
+        p50LatencyMs: number;
+        p95LatencyMs: number;
+        avgCostUsdc: number;
+        sampleSize: number;
+    };
+}
+interface FailureMetadata {
+    kind: "schema_mismatch" | "http_4xx" | "http_5xx" | "timeout" | "auth" | "rate_limit" | "gateway_error" | "budget" | "sign" | "resolve" | "unknown";
+    hint: string;
+    providerStatus?: number;
+    evaluatorLayer?: 1 | 2 | 3 | 4;
+    rawProviderError?: string;
+}
+interface ListingInfo {
+    listingId: number;
+    name: string | null;
+    priceAtomic: string | null;
+    maxLatencyMs: number;
+    taskCategory: string;
+    outputSchema: unknown | null;
+    payout: string;
+    active: boolean;
+}
+interface BudgetConfig {
+    perCallMaxUsdc: number;
+    dailyMaxUsdc: number;
+    monthlyMaxUsdc: number;
+}
+
+interface ClaimableResult {
+    totalUsdc: number;
+    atomicBalance: string;
+}
+interface ListingDashboard {
+    listingId: number;
+    name: string | null;
+    totalEarnedUsdc: number;
+    claimableUsdc: number;
+    callCount: number;
+    successRate: number;
+    p50LatencyMs: number;
+}
+declare class ProviderClient {
+    private readonly gatewayUrl;
+    private readonly wallet;
+    constructor(gatewayUrl: string, wallet: WalletAdapter);
+    claimable(): Promise<ClaimableResult>;
+    claim(): Promise<{
+        txHash: `0x${string}`;
+    } | {
+        skipped: true;
+    }>;
+    listingDashboard(listingId: number): Promise<ListingDashboard>;
+}
+
+declare class ChainLens {
+    private readonly cfg;
+    private budget;
+    private telemetry;
+    private walletAddress;
+    readonly provider: ProviderClient;
+    constructor(cfg: ChainLensConfig);
+    private init;
+    call<T = unknown>(listingId: number, params: unknown, options?: CallOptions): Promise<CallResult<T>>;
+    recommend(task: string, maxResults?: number): Promise<RankedListing[]>;
+    currentSpend(): Promise<{
+        dailyUsdc: number;
+        monthlyUsdc: number;
+    }>;
+}
+
+/**
+ * WalletAdapter backed by a viem WalletClient.
+ *
+ * Usage:
+ *   const walletClient = createWalletClient({ account, chain, transport });
+ *   const wallet = new ViemWallet(walletClient);
+ */
+declare class ViemWallet implements WalletAdapter {
+    private readonly client;
+    constructor(client: WalletClient);
+    address(): Promise<`0x${string}`>;
+    signTypedData(typedData: TypedData): Promise<{
+        v: number;
+        r: `0x${string}`;
+        s: `0x${string}`;
+    }>;
+    sendTransaction(tx: TxRequest): Promise<`0x${string}`>;
+}
+
+/**
+ * Off-chain rolling-window budget controller.
+ *
+ * Persists spend records to LevelDB under ~/.chainlens/budget/<wallet>/.
+ * Falls back to in-memory when LevelDB is unavailable (browser / ephemeral).
+ */
+declare class BudgetController {
+    private readonly cfg;
+    private db;
+    private readonly walletAddress;
+    private initPromise;
+    constructor(walletAddress: string, cfg?: Partial<BudgetConfig>);
+    private getDb;
+    private openDb;
+    canSpend(amount: number): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    debit(amount: number, idempotencyKey?: string): Promise<void>;
+    currentSpend(): Promise<{
+        dailyUsdc: number;
+        monthlyUsdc: number;
+    }>;
+}
+
+declare class ChainLensError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(message: string, code: string, cause?: unknown);
+}
+/** Listing not found or task query produced no match. */
+declare class ChainLensResolveError extends ChainLensError {
+    constructor(message: string, cause?: unknown);
+}
+/** Off-chain budget limit exceeded before any signature was produced. */
+declare class BudgetExceededError extends ChainLensError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** EIP-3009 signing failed. */
+declare class ChainLensSignError extends ChainLensError {
+    constructor(message: string, cause?: unknown);
+}
+/** Gateway returned a non-200 HTTP status. */
+declare class ChainLensGatewayError extends ChainLensError {
+    readonly status: number;
+    constructor(message: string, status: number, cause?: unknown);
+}
+/** The call completed but the provider reported failure (no settlement). */
+declare class ChainLensCallError extends ChainLensError {
+    readonly failure: FailureMetadata;
+    constructor(failure: FailureMetadata);
+}
+
+/** Chain-specific USDC contract addresses. */
+declare const USDC_ADDRESSES: Record<number, `0x${string}`>;
+/** ChainLensMarket addresses per chain. */
+declare const CHAIN_LENS_MARKET_ADDRESSES: Record<number, `0x${string}`>;
+interface Eip3009Auth {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    amount: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: `0x${string}`;
+    v: number;
+    r: `0x${string}`;
+    s: `0x${string}`;
+}
+declare function signReceiveWithAuthorization(opts: {
+    wallet: WalletAdapter;
+    chainId: number;
+    amount: bigint;
+    to: `0x${string}`;
+    signal?: AbortSignal;
+}): Promise<Eip3009Auth>;
+/** Convert USDC display units (e.g. 0.05) to atomic units (50000). */
+declare function usdcToAtomic(usdc: number): bigint;
+/** Convert atomic USDC units to display units. */
+declare function atomicToUsdc(atomic: bigint | string): number;
+
+interface TelemetryEntry {
+    ts: number;
+    listingId: number;
+    amountUsdc: number;
+    latencyMs: number;
+    ok: boolean;
+    failure?: FailureMetadata;
+    txHash?: string;
+    paramsHash?: string;
+}
+interface TelemetryConfig {
+    enabled: boolean;
+    upload: boolean;
+    bufferMaxEntries: number;
+    gatewayUrl: string;
+    walletAddress: string;
+}
+
+export { type BudgetConfig, BudgetController, BudgetExceededError, CHAIN_LENS_MARKET_ADDRESSES, type CallOptions, type CallResult, ChainLens, ChainLensCallError, type ChainLensConfig, ChainLensError, ChainLensGatewayError, ChainLensResolveError, ChainLensSignError, type ClaimableResult, type FailureMetadata, type ListingDashboard, type ListingInfo, ProviderClient, type RankedListing, type TelemetryConfig, type TelemetryEntry, type TxRequest, type TypedData, USDC_ADDRESSES, ViemWallet, type WalletAdapter, atomicToUsdc, signReceiveWithAuthorization, usdcToAtomic };