@chainpearc/sdk 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @chainpearc/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@chainpearc/sdk.svg)](https://www.npmjs.com/package/@chainpearc/sdk)
+
+**Let any app or AI agent find, pay for and rate APIs per call, in USDC on Arc.**
+
+```bash
+npm install @chainpearc/sdk
+```
+
+> **Use Arc testnet for now.** It is the default. ChainPe has not been tested with real USDC on Arc mainnet.
+
+## Quickstart
+
+Get free test USDC at https://faucet.circle.com (pick Arc Testnet). On Arc, gas is also paid in USDC.
+
+```ts
+import { ChainPe } from '@chainpearc/sdk'
+
+const cp = new ChainPe({ privateKey: process.env.PRIVATE_KEY! })
+const res = await cp.fetch('https://chainpe-arc-demo-production.up.railway.app/forecast?city=Mumbai')
+const data = await res.json()
+```
+
+`cp.fetch` works like `fetch`. If the server answers `402 Payment Required`, it checks the price against your limit, signs a USDC payment, retries and returns the final `Response`.
+
+## Find, pay and rate
+
+```ts
+const services = await cp.discover({ query: 'weather', maxPrice: '0.01' })
+
+const result = await cp.pay('https://chainpe-arc-demo-production.up.railway.app/forecast?city=Mumbai')
+console.log(result.data)     // the parsed response
+console.log(result.payment)  // { amount, recipient, network, rail, txHash or transferId }
+
+await cp.giveFeedback(services[0].agentId!, 90)
+```
+
+`discover` searches Circle's Discovery API and the `ChainPeAccounts` contract, so it also finds ChainPe providers Circle has not listed yet. A service's `endpoint` is either a full route (Circle) or the provider's base URL (ChainPe). For a base URL, read `<endpoint>/openapi.json` for its paths.
+
+## Two ways to pay
+
+| Rail | How it works | Needs |
+|---|---|---|
+| `exact` | Moves USDC from your wallet for each call, starting at $0.01. Circle settles it on Arc. | USDC in your wallet |
+| `gateway` | Pays from a prepaid Circle Gateway deposit with no gas, from fractions of a cent. Circle settles in batches. | A deposit: `await cp.depositGateway('1')` |
+
+By default ChainPe uses Gateway when your deposit covers the price, and your wallet otherwise. To change that, pass `rails`, in order of preference.
+
+## API
+
+`new ChainPe(options)`
+
+| Option | Default | Purpose |
+|---|---|---|
+| `privateKey` | required | The key that signs payments and ratings |
+| `network` | `'arc-testnet'` | `'arc-testnet'` or `'arc'` |
+| `rails` | `['gateway', 'exact']` | Payment rails, in order of preference |
+| `maxPerCall` | `'1'` | Most USDC to pay for one call. A higher price is refused before signing |
+| `autoFeedback` | `false` | Rate the provider 100 after a paid call. This costs gas |
+| `accountsAddress` | the deployed contract | `ChainPeAccounts`. Also read from `CHAINPE_ACCOUNTS_ADDRESS` |
+| `reputationRegistry` | Arc's registry | ERC-8004 registry. Also read from `ERC8004_REPUTATION_REGISTRY` |
+
+| Method | Returns | What it does |
+|---|---|---|
+| `fetch(url, opts?)` | `Response` | Calls a URL, paying a 402 |
+| `pay(url, opts?)` | `PaidResult` | The same, with the parsed body and payment details |
+| `request(url, opts?)` | `{ response, payment, agentId }` | The same, with the unread `Response` |
+| `discover(query?)` | `RankedService[]` | Finds services. Takes a search string or `{ query, tags, maxPrice, category, gatewayOnly, limit }` |
+| `balance()` | `{ usdc, gateway }` | Your wallet and Gateway balances |
+| `depositGateway(amount)` | `{ txHash, amount }` | Deposits USDC into Circle Gateway |
+| `getReputation(agentId)` | `{ count, score }` or `null` | Reads a provider's rating |
+| `giveFeedback(agentId, score, opts?)` | tx hash | Posts a 0 to 100 rating. You can't rate your own agent |
+| `getAddress()` | `string` | Your wallet address |
+
+`PolicyVaultClient` is also exported. No `PolicyVault` contract is deployed on Arc yet, so it needs a `vaultAddress` of your own.
+
+## Errors
+
+- A price above `maxPerCall` throws before anything is signed.
+- A server that refuses a signed payment throws `ChainPePaymentError`, with the cause in `.reason`, such as `insufficient_funds`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import { PaymentPolicy } from '@x402/fetch';
+import { Hex, Chain, PublicClient } from 'viem';
+
+/** Arc network the SDK operates on. */
+type ChainPeNetwork = 'arc-testnet' | 'arc';
+/**
+ * How a call is paid. `exact` moves USDC from the wallet for each call. `gateway`
+ * pays from a prepaid Circle Gateway deposit, with no gas, and is settled in batches.
+ */
+type PaymentRail = 'gateway' | 'exact';
+/**
+ * Error thrown when an x402 payment fails (e.g. insufficient USDC, settlement
+ * refused). Provides `.txHash` and `.reason` for debugging.
+ */
+declare class ChainPePaymentError extends Error {
+    readonly txHash?: string;
+    readonly reason?: string;
+    constructor(message: string, { txHash, reason }?: {
+        txHash?: string;
+        reason?: string;
+    });
+}
+/** Options for constructing a {@link ChainPe} client. */
+interface ChainPeOptions {
+    /** EOA private key (0x-prefixed or bare hex) used to sign payments + feedback. */
+    privateKey: string;
+    /** Arc network. Defaults to `'arc-testnet'`. */
+    network?: ChainPeNetwork;
+    /**
+     * Payment rails to use, in order of preference. Defaults to
+     * `['gateway', 'exact']`: Gateway when the deposit covers the price, else the wallet.
+     */
+    rails?: PaymentRail[];
+    /** ChainPeAccounts address. Defaults to the deployed contract for the network. */
+    accountsAddress?: string;
+    /** ERC-8004 Reputation Registry address. Defaults to Arc's registry. */
+    reputationRegistry?: string;
+    /**
+     * Max USDC to auto-pay for a single 402 (human units, e.g. `"1.00"`). A higher
+     * price is refused before anything is signed. Defaults to `"1"`.
+     */
+    maxPerCall?: string;
+    /**
+     * When true, `.fetch()`/`.pay()` post positive ERC-8004 feedback to the
+     * provider's agent after a successful paid call. It costs gas, paid in USDC.
+     * Defaults to `false`. `.pay()` returns the feedback result; use
+     * `.giveFeedback()` for explicit control.
+     */
+    autoFeedback?: boolean;
+}
+/** Per-request options for {@link ChainPe.fetch} / {@link ChainPe.pay}. */
+interface FetchOptions extends RequestInit {
+    /** Override the constructor `autoFeedback` for this call. */
+    autoFeedback?: boolean;
+    /**
+     * Timeout per HTTP attempt in milliseconds. Defaults to 30 000 ms (30 s).
+     */
+    timeout?: number;
+}
+/** A service found by {@link ChainPe.discover}. */
+interface ChainPeService {
+    /** Stable id: the resource URL (Circle) or the service key (ChainPeAccounts). */
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    /** The URL to call. */
+    endpoint: string;
+    /** The HTTP method, when the listing names one. */
+    method?: string;
+    /** Human USDC units. */
+    pricePerRequest: string;
+    paymentToken: 'USDC';
+    /** Address that receives payment (the 402 `payTo`). */
+    walletAddress: string;
+    network: ChainPeNetwork;
+    /** Payment rails this service accepts on this network. */
+    rails: PaymentRail[];
+    /** Where the listing came from. */
+    source: 'circle' | 'chainpe';
+    /** Circle Discovery category, when listed there. */
+    category?: string;
+    /** The provider's address, for services on ChainPeAccounts. */
+    developer?: string;
+    /** ERC-8004 agent id, when the service is linked to an identity. */
+    agentId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Filters for {@link ChainPe.discover}. */
+interface DiscoverOptions {
+    /** Free-text search. */
+    query?: string;
+    tags?: string[];
+    /** Max price per request (human USDC units). */
+    maxPrice?: string;
+    /** Circle Discovery category, e.g. `DATA_ENRICHMENT`. */
+    category?: string;
+    /** Only services that accept Circle Gateway. */
+    gatewayOnly?: boolean;
+    /** Max results. Defaults to 20. */
+    limit?: number;
+}
+/** Aggregated ERC-8004 reputation for an agent. */
+interface ReputationSummary {
+    /** Number of feedback entries counted. */
+    count: number;
+    /** Aggregate score (typically 0–100), or null when unscored. */
+    score: number | null;
+}
+/** A service annotated with its reputation (returned by {@link ChainPe.discover}). */
+interface RankedService extends ChainPeService {
+    reputation: ReputationSummary | null;
+}
+/** Details of a payment that was made. */
+interface PaymentInfo {
+    /** Human USDC units. */
+    amount: string;
+    recipient: string;
+    network: ChainPeNetwork;
+    rail: PaymentRail;
+    /** On-chain tx hash. Set on the exact rail. */
+    txHash?: string;
+    /** Circle transfer id. Set on the Gateway rail, which settles in a later batch. */
+    transferId?: string;
+    /** The provider's decoded settlement response. */
+    settlement?: unknown;
+}
+/** Result of {@link ChainPe.request}: a live, unread Response + metadata. */
+interface PaidResponse {
+    response: Response;
+    /** Set when a payment was actually made. */
+    payment?: PaymentInfo;
+    /** The provider's ERC-8004 agent id, when it advertises one. */
+    agentId?: string;
+}
+/** Result of {@link ChainPe.pay} — a parsed, structured paid response. */
+interface PaidResult<T = unknown> {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    /** Parsed body (JSON when the content-type is JSON, else text). */
+    data: T;
+    /** Present when a payment was made + settled. */
+    payment?: PaymentInfo;
+    /** Present when feedback was posted (autoFeedback). */
+    reputation?: {
+        agentId: string;
+        score: number;
+        txHash: string;
+    };
+}
+/** Wallet balances (human USDC units). */
+interface Balances {
+    /** USDC in the wallet. It also pays gas on Arc. */
+    usdc: string;
+    /** USDC available in Circle Gateway. `'0'` if it could not be read. */
+    gateway: string;
+}
+
+/**
+ * Keeps the options of the first usable rail. Gateway only counts when the
+ * deposit covers the price, so a wallet with no deposit falls back to `exact`.
+ */
+declare function railPolicy(rails: PaymentRail[], gatewayAvailable: bigint): PaymentPolicy;
+declare class ChainPe {
+    readonly network: ChainPeNetwork;
+    readonly rails: PaymentRail[];
+    readonly accountsAddress?: `0x${string}`;
+    readonly reputationRegistry: `0x${string}`;
+    private readonly privateKey;
+    private readonly account;
+    private readonly maxPerCallAtomic;
+    private readonly autoFeedback;
+    private gatewayClient?;
+    constructor(options: ChainPeOptions);
+    /** Echoes the resolved configuration (no secrets). */
+    get config(): {
+        network: ChainPeNetwork;
+        address: `0x${string}`;
+        rails: PaymentRail[];
+        accountsAddress: `0x${string}` | undefined;
+        reputationRegistry: `0x${string}`;
+        maxPerCall: string;
+    };
+    /** The wallet address that signs payments and feedback. */
+    getAddress(): string;
+    /** Reads the wallet's USDC and the Circle Gateway deposit (human units). */
+    balance(): Promise<Balances>;
+    /** Deposits USDC into Circle Gateway, to pay on the Gateway rail with no gas. */
+    depositGateway(amount: string): Promise<{
+        txHash: string;
+        amount: string;
+    }>;
+    /**
+     * Drop-in `fetch` that automatically pays an x402 `402 Payment Required` in
+     * USDC and returns the final live {@link Response}.
+     */
+    fetch(url: string, opts?: FetchOptions): Promise<Response>;
+    /**
+     * Like {@link fetch}, but returns the live, unread {@link Response} together
+     * with the payment details. Never posts feedback.
+     */
+    request(url: string, opts?: FetchOptions): Promise<PaidResponse>;
+    /**
+     * Like {@link fetch}, but returns a structured, body-parsed result with the
+     * payment + (optional) reputation details. Convenient for agents.
+     */
+    pay<T = unknown>(url: string, opts?: FetchOptions): Promise<PaidResult<T>>;
+    /**
+     * Finds services through Circle's Discovery API and ChainPeAccounts, annotated
+     * with ERC-8004 reputation and ranked. ChainPeAccounts also covers providers
+     * Circle has not listed yet. Throws only when neither source can be read.
+     */
+    discover(query?: string | DiscoverOptions): Promise<RankedService[]>;
+    /** Reads a provider agent's aggregate ERC-8004 reputation. */
+    getReputation(agentId: string): Promise<ReputationSummary | null>;
+    /** Posts ERC-8004 feedback (0–100) for a provider agent. Returns the tx hash. */
+    giveFeedback(agentId: string, score: number, opts?: {
+        endpoint?: string;
+        tag?: string;
+        waitConfirm?: boolean;
+    }): Promise<string>;
+    private gateway;
+    /** A deposit we cannot read counts as empty, so payment falls back to the wallet. */
+    private gatewayAvailable;
+    /**
+     * Runs the x402 flow: request → on 402, cap the price, choose a rail, sign →
+     * retry. Spend limits run before anything is signed.
+     */
+    private execute;
+    private paymentInfo;
+    private explainPaymentError;
+    /**
+     * Best-effort positive feedback for the provider's agent after a paid call.
+     * Prefers the agent id the provider advertises; otherwise looks for its `payTo`
+     * in ChainPeAccounts. Never throws (self-feedback, no gas, etc. are swallowed).
+     */
+    private tryAutoFeedback;
+    private parseBody;
+}
+
+declare const CIRCLE_DISCOVERY_URL = "https://api.circle.com/v2/x402/discovery/resources";
+interface CircleAccept {
+    network: string;
+    amount: string;
+    payTo: string;
+    extra?: {
+        name?: string;
+    };
+}
+interface CircleItem {
+    resource: string;
+    lastUpdated?: string;
+    accepts?: CircleAccept[];
+    metadata?: {
+        provider?: {
+            name?: string;
+            description?: string;
+            category?: string;
+            tags?: string[];
+        };
+        method?: string;
+        description?: string;
+    };
+}
+/** Maps one listing to a service on this network, or undefined if it has no option here. Pure. */
+declare function mapCircleItem(item: CircleItem, network: ChainPeNetwork): ChainPeService | undefined;
+/** Throws when Circle cannot be reached, so a caller can tell that apart from no results. */
+declare function searchCircle(network: ChainPeNetwork, options: DiscoverOptions): Promise<ChainPeService[]>;
+/**
+ * Circle's search can return listings that share no word with the query. Keeps a
+ * listing only when one of its words is a query word, or that word plus "s". Pure.
+ */
+declare function isRelevant(service: ChainPeService, query?: string): boolean;
+/** Drops a ChainPe listing when Circle already lists that provider on the same host. Pure. */
+declare function mergeListings(circle: ChainPeService[], chainpe: ChainPeService[]): ChainPeService[];
+/**
+ * Finds services through Circle's Discovery API and ChainPeAccounts, annotated
+ * with ERC-8004 reputation and ranked. Needs no wallet. ChainPeAccounts also covers
+ * providers Circle has not listed yet. Throws only when neither source can be read.
+ */
+declare function discoverServices(network: ChainPeNetwork, query?: string | DiscoverOptions, addresses?: {
+    accountsAddress?: string;
+    reputationRegistry?: string;
+}): Promise<RankedService[]>;
+
+interface RawService {
+    key: string;
+    provider: string;
+    payTo: string;
+    agentId: bigint;
+    name: string;
+    description: string;
+    tags: string;
+    endpoint: string;
+    pricePerRequest: string;
+    network: string;
+    acceptsExact: boolean;
+    acceptsGateway: boolean;
+    active: boolean;
+    createdAt: bigint;
+    updatedAt: bigint;
+}
+/** Decodes an on-chain service tuple into the public {@link ChainPeService}. */
+declare function decodeService(raw: RawService, network: ChainPeNetwork): ChainPeService;
+/** Filters services by free-text query, tags, max price and rail. Pure. */
+declare function filterServices(services: ChainPeService[], options: DiscoverOptions): ChainPeService[];
+/**
+ * Ranks services by reputation: scored before unscored, higher score first,
+ * then more feedback, then cheaper. Stable for equal keys. Pure.
+ */
+declare function rankByReputation(services: RankedService[]): RankedService[];
+/** Reads the on-chain ChainPeAccounts contract. */
+declare class RegistryClient {
+    private readonly network;
+    private readonly address;
+    constructor(network: ChainPeNetwork, address: `0x${string}`);
+    getAddress(): string;
+    /** Lists every active service. Deactivated listings stay on-chain, so they are dropped here. */
+    listAllServices(): Promise<ChainPeService[]>;
+}
+
+/** Converts the on-chain (value, decimals) summary into a human score. Pure. */
+declare function summaryToScore(summaryValue: bigint, decimals: number): number;
+/**
+ * Reads a provider agent's aggregate reputation. Returns null when the agent is
+ * unlinked (`agentId` 0/empty) or no registry is configured; `count: 0` when the
+ * agent exists but has no feedback yet.
+ */
+declare function getReputation(network: ChainPeNetwork, registry: `0x${string}` | undefined, agentId: string): Promise<ReputationSummary | null>;
+interface GiveFeedbackParams {
+    agentId: string;
+    /** Score, typically 0–100 (valueDecimals 0). */
+    value: number;
+    endpoint?: string;
+    tag?: string;
+    /** Await the receipt before returning. Defaults to false. */
+    waitConfirm?: boolean;
+}
+/** Posts ERC-8004 feedback for a provider agent. Returns the tx hash. */
+declare function giveFeedback(network: ChainPeNetwork, registry: `0x${string}` | undefined, privateKey: string, params: GiveFeedbackParams): Promise<string>;
+
+/**
+ * PolicyVault client — programmable, gasless agent spending.
+ *
+ * Three roles, one client (whichever key you construct it with):
+ *  - **owner**   funds the vault + sets the policy/allowlist (`deposit`,
+ *    `setPolicy`, `setAllowlist`, `revokeSession`) — owner pays gas.
+ *  - **agent**   holds the session key and only *signs* spends (`signSpend`) —
+ *    no gas, no tx.
+ *  - **relayer** submits a signed spend (`relaySpend`) and pays the gas.
+ *
+ * The on-chain `PolicyVault` enforces every limit; an over-cap or non-allowlisted
+ * spend reverts (the rejection reason is surfaced as the thrown error).
+ */
+
+interface PolicyVaultOptions {
+    privateKey: string;
+    network?: ChainPeNetwork;
+    vaultAddress: string;
+}
+interface PolicyParams {
+    sessionKey: string;
+    /** Human USDC strings. */
+    maxPerCall: string;
+    dailyCap: string;
+    totalBudget: string;
+    /** Unix seconds the session is valid until. */
+    expiry: number;
+    allowlistOnly?: boolean;
+}
+/** A session-signed spend authorization, ready for a relayer to submit. */
+interface SpendAuthorization {
+    owner: string;
+    to: string;
+    /** Human USDC string. */
+    amount: string;
+    amountAtomic: string;
+    nonce: string;
+    deadline: number;
+    signature: Hex;
+}
+declare class PolicyVaultClient {
+    readonly network: ChainPeNetwork;
+    readonly vault: `0x${string}`;
+    private readonly account;
+    constructor(options: PolicyVaultOptions);
+    getAddress(): string;
+    private wallet;
+    private usdc;
+    balanceOf(owner: string): Promise<string>;
+    dailyRemaining(owner: string): Promise<string>;
+    budgetRemaining(owner: string): Promise<string>;
+    nonce(owner: string): Promise<bigint>;
+    deposit(human: string): Promise<Hex>;
+    withdraw(human: string): Promise<Hex>;
+    setPolicy(p: PolicyParams): Promise<Hex>;
+    setAllowlist(to: string, allowed: boolean): Promise<Hex>;
+    revokeSession(): Promise<Hex>;
+    /**
+     * Signs a spend authorization with this key (the session key). Reads the
+     * owner's current nonce so the relayer can submit it. `ttlSeconds` bounds how
+     * long the authorization stays valid (default 5 min).
+     */
+    signSpend(params: {
+        owner: string;
+        to: string;
+        amount: string;
+        ttlSeconds?: number;
+    }): Promise<SpendAuthorization>;
+    /**
+     * Submits a session-signed spend. Throws with the on-chain revert reason if a
+     * policy limit is violated (e.g. "over per-call cap").
+     */
+    relaySpend(auth: SpendAuthorization): Promise<Hex>;
+}
+
+/**
+ * Network constants for Circle's Arc.
+ *
+ * Arc pays gas in USDC. The native balance has 18 decimals while the ERC-20
+ * interface at the USDC address has 6, so amounts always go through the ERC-20.
+ */
+
+declare const USDC_DECIMALS = 6;
+declare function getCaip2(network: ChainPeNetwork): string;
+declare function rpcUrlFor(network: ChainPeNetwork): string;
+declare function explorerFor(network: ChainPeNetwork): string;
+/** Arc's USDC, through its 6-decimal ERC-20 interface. */
+declare function getUsdcAddress(network: ChainPeNetwork): `0x${string}`;
+declare function chainFor(network: ChainPeNetwork): Chain;
+declare function publicClientFor(network: ChainPeNetwork): PublicClient;
+/** ChainPeAccounts: explicit arg → env → built-in. Undefined where it is not deployed. */
+declare function resolveAccountsAddress(network: ChainPeNetwork, explicit?: string): `0x${string}` | undefined;
+/** Arc's ERC-8004 Reputation Registry: explicit arg → env → built-in. */
+declare function resolveReputationRegistry(network: ChainPeNetwork, explicit?: string): `0x${string}`;
+declare function normalizeKey(key: string): `0x${string}`;
+
+export { type Balances, CIRCLE_DISCOVERY_URL, ChainPe, type ChainPeNetwork, type ChainPeOptions, ChainPePaymentError, type ChainPeService, type DiscoverOptions, type FetchOptions, type GiveFeedbackParams, type PaidResponse, type PaidResult, type PaymentInfo, type PaymentRail, type PolicyParams, PolicyVaultClient, type PolicyVaultOptions, type RankedService, type RawService, RegistryClient, type ReputationSummary, type SpendAuthorization, USDC_DECIMALS, chainFor, decodeService, discoverServices, explorerFor, filterServices, getCaip2, getReputation, getUsdcAddress, giveFeedback, isRelevant, mapCircleItem, mergeListings, normalizeKey, publicClientFor, railPolicy, rankByReputation, resolveAccountsAddress, resolveReputationRegistry, rpcUrlFor, searchCircle, summaryToScore };