@chain-lens/sdk 0.1.0

package/src/recommend.ts

@@ -0,0 +1,21 @@
+import type { RankedListing } from "./types.js";
+import { ChainLensResolveError } from "./errors.js";
+
+export async function fetchRecommendations(
+  gatewayUrl: string,
+  task: string,
+  maxResults = 5,
+): Promise<RankedListing[]> {
+  const res = await fetch(`${gatewayUrl}/v1/recommend`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ task, maxResults }),
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new ChainLensResolveError(`recommend failed: ${res.status} ${body}`);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const data = (await res.json()) as any;
+  return (data.listings ?? []) as RankedListing[];
+}

package/src/telemetry.ts

@@ -0,0 +1,72 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { appendFile, mkdir } from "node:fs/promises";
+import type { FailureMetadata } from "./types.js";
+
+export interface TelemetryEntry {
+  ts: number;
+  listingId: number;
+  amountUsdc: number;
+  latencyMs: number;
+  ok: boolean;
+  failure?: FailureMetadata;
+  txHash?: string;
+  paramsHash?: string;
+}
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  upload: boolean;
+  bufferMaxEntries: number;
+  gatewayUrl: string;
+  walletAddress: string;
+}
+
+export class TelemetryRecorder {
+  private readonly cfg: TelemetryConfig;
+
+  constructor(cfg: TelemetryConfig) {
+    this.cfg = cfg;
+  }
+
+  async record(entry: TelemetryEntry): Promise<void> {
+    if (!this.cfg.enabled) return;
+
+    const line = JSON.stringify(entry) + "\n";
+    const dir = join(homedir(), ".chainlens", "telemetry");
+    const filePath = join(dir, `${sanitizeAddress(this.cfg.walletAddress)}.jsonl`);
+
+    try {
+      await mkdir(dir, { recursive: true });
+      await appendFile(filePath, line, "utf8");
+    } catch {
+      // non-blocking — ignore write failures
+    }
+
+    if (this.cfg.upload) {
+      void this.uploadAsync(entry);
+    }
+  }
+
+  private async uploadAsync(entry: TelemetryEntry): Promise<void> {
+    try {
+      await fetch(`${this.cfg.gatewayUrl}/v1/telemetry/batch`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ events: [entry] }),
+      });
+    } catch {
+      // fire-and-forget, ignore errors
+    }
+  }
+}
+
+export function hashParams(params: unknown): string {
+  const json = params != null ? JSON.stringify(params) : "";
+  return createHash("sha256").update(json, "utf8").digest("hex").slice(0, 16);
+}
+
+function sanitizeAddress(addr: string): string {
+  return addr.toLowerCase().replace(/[^a-f0-9x]/g, "").slice(0, 42);
+}

package/src/types.ts

@@ -0,0 +1,136 @@
+export 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;
+}
+
+export interface WalletAdapter {
+  address(): Promise<`0x${string}`>;
+  signTypedData(typedData: TypedData): Promise<{ v: number; r: `0x${string}`; s: `0x${string}` }>;
+  sendTransaction(tx: TxRequest): Promise<`0x${string}`>;
+}
+
+export 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>;
+}
+
+export interface TxRequest {
+  to: `0x${string}`;
+  data?: `0x${string}`;
+  value?: bigint;
+}
+
+export interface CallOptions {
+  fallback?: boolean;
+  maxUsdc?: number;
+  idempotencyKey?: string;
+  signal?: AbortSignal;
+}
+
+export 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;
+}
+
+export 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;
+  };
+}
+
+export 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;
+}
+
+export interface ListingInfo {
+  listingId: number;
+  name: string | null;
+  priceAtomic: string | null;
+  maxLatencyMs: number;
+  taskCategory: string;
+  outputSchema: unknown | null;
+  payout: string;
+  active: boolean;
+}
+
+export interface BudgetConfig {
+  perCallMaxUsdc: number;
+  dailyMaxUsdc: number;
+  monthlyMaxUsdc: number;
+}

package/src/wallet/types.ts

@@ -0,0 +1 @@
+export type { WalletAdapter, TypedData, TxRequest } from "../types.js";

package/src/wallet/viem.ts

@@ -0,0 +1,57 @@
+import type { WalletClient, Hex, TypedDataDefinition } from "viem";
+import { hexToNumber, numberToHex, parseSignature } from "viem";
+import type { WalletAdapter, TypedData, TxRequest } from "./types.js";
+
+/**
+ * WalletAdapter backed by a viem WalletClient.
+ *
+ * Usage:
+ *   const walletClient = createWalletClient({ account, chain, transport });
+ *   const wallet = new ViemWallet(walletClient);
+ */
+export class ViemWallet implements WalletAdapter {
+  constructor(private readonly client: WalletClient) {}
+
+  async address(): Promise<`0x${string}`> {
+    const accounts = await this.client.getAddresses();
+    const addr = accounts[0];
+    if (!addr) throw new Error("ViemWallet: no accounts available");
+    return addr;
+  }
+
+  async signTypedData(
+    typedData: TypedData,
+  ): Promise<{ v: number; r: `0x${string}`; s: `0x${string}` }> {
+    const { domain, types, primaryType, message } = typedData;
+
+    const sig = await this.client.signTypedData({
+      domain: {
+        name: domain.name,
+        version: domain.version,
+        chainId: domain.chainId,
+        verifyingContract: domain.verifyingContract,
+      },
+      types: types as unknown as TypedDataDefinition["types"],
+      primaryType,
+      message: message as Record<string, unknown>,
+    } as Parameters<WalletClient["signTypedData"]>[0]);
+
+    const parsed = parseSignature(sig as Hex);
+    return {
+      v: hexToNumber(numberToHex(parsed.v ?? 27n)),
+      r: parsed.r as `0x${string}`,
+      s: parsed.s as `0x${string}`,
+    };
+  }
+
+  async sendTransaction(tx: TxRequest): Promise<`0x${string}`> {
+    const from = await this.address();
+    return this.client.sendTransaction({
+      account: from,
+      to: tx.to,
+      data: tx.data,
+      value: tx.value,
+      chain: this.client.chain ?? null,
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  splitting: false,
+  clean: true,
+  external: ["viem"],
+});