@pay-skill/sdk 0.1.8 → 0.1.10

package/dist/wallet.js

@@ -1,331 +1,734 @@
 /**
- * Wallet — high-level write client for agents.
- * Wraps PayClient with private key signing and balance tracking.
+ * Wallet — the single entry point for the pay SDK.
  *
- * This is the primary entry point for the playground and agent integrations.
- * The PayClient is lower-level (HTTP only); Wallet adds signing + state.
+ * Zero-config for agents:  new Wallet()          (reads PAYSKILL_KEY env)
+ * Explicit key:            new Wallet({ privateKey: "0x..." })
+ * OS keychain (CLI key):   await Wallet.create()
+ * OWS wallet extension:    await Wallet.fromOws({ walletId: "..." })
  */
 import { privateKeyToAccount } from "viem/accounts";
-import { buildAuthHeaders } from "./auth.js";
-/** Map well-known chain names to numeric IDs. */
-const CHAIN_IDS = {
-    "base": 8453,
-    "base-sepolia": 84532,
-};
+import { buildAuthHeaders, buildAuthHeadersSigned } from "./auth.js";
+import { signTransferAuthorization, combinedSignature } from "./eip3009.js";
+import { readFromKeychain } from "./keychain.js";
+import { PayError, PayValidationError, PayNetworkError, PayServerError, PayInsufficientFundsError, } from "./errors.js";
+// ── Constants ────────────────────────────────────────────────────────
+const MAINNET_API_URL = "https://pay-skill.com/api/v1";
+const TESTNET_API_URL = "https://testnet.pay-skill.com/api/v1";
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const KEY_RE = /^0x[0-9a-fA-F]{64}$/;
+const DIRECT_MIN_MICRO = 1_000_000; // $1.00
+const TAB_MIN_MICRO = 5_000_000; // $5.00
+const TAB_MULTIPLIER = 10;
+const DEFAULT_TIMEOUT = 30_000;
+// Internal sentinel for OWS construction
+const _OWS_INIT = Symbol("ows-init");
+// ── Helpers ──────────────────────────────────────────────────────────
+function normalizeKey(key) {
+    const clean = key.startsWith("0x") ? key : "0x" + key;
+    if (!KEY_RE.test(clean)) {
+        throw new PayValidationError("Invalid private key: must be 32 bytes hex", "privateKey");
+    }
+    return clean;
+}
+function validateAddress(address) {
+    if (!ADDRESS_RE.test(address)) {
+        throw new PayValidationError(`Invalid Ethereum address: ${address}`, "address");
+    }
+}
+function toMicro(amount) {
+    if (typeof amount === "number") {
+        if (!Number.isFinite(amount) || amount < 0) {
+            throw new PayValidationError("Amount must be a positive finite number", "amount");
+        }
+        return Math.round(amount * 1_000_000);
+    }
+    if (!Number.isInteger(amount.micro) || amount.micro < 0) {
+        throw new PayValidationError("Micro amount must be a non-negative integer", "amount");
+    }
+    return amount.micro;
+}
+function toDollars(micro) {
+    return micro / 1_000_000;
+}
+function parseTab(raw) {
+    return {
+        id: raw.tab_id,
+        provider: raw.provider,
+        amount: toDollars(raw.amount),
+        balanceRemaining: toDollars(raw.balance_remaining),
+        totalCharged: toDollars(raw.total_charged),
+        chargeCount: raw.charge_count,
+        maxChargePerCall: toDollars(raw.max_charge_per_call),
+        totalWithdrawn: toDollars(raw.total_withdrawn),
+        status: raw.status,
+        pendingChargeCount: raw.pending_charge_count,
+        pendingChargeTotal: toDollars(raw.pending_charge_total),
+        effectiveBalance: toDollars(raw.effective_balance),
+    };
+}
+function parseSig(signature) {
+    const sig = signature.startsWith("0x")
+        ? signature.slice(2)
+        : signature;
+    return {
+        v: parseInt(sig.slice(128, 130), 16),
+        r: "0x" + sig.slice(0, 64),
+        s: "0x" + sig.slice(64, 128),
+    };
+}
+function resolveApiUrl(testnet) {
+    return (process.env.PAYSKILL_API_URL ??
+        (testnet ? TESTNET_API_URL : MAINNET_API_URL));
+}
+function createOwsSignTypedData(ows, walletId, owsApiKey) {
+    return async (params) => {
+        // Build EIP712Domain type from domain fields
+        const domainType = [];
+        const d = params.domain;
+        if (d.name !== undefined)
+            domainType.push({ name: "name", type: "string" });
+        if (d.version !== undefined)
+            domainType.push({ name: "version", type: "string" });
+        if (d.chainId !== undefined)
+            domainType.push({ name: "chainId", type: "uint256" });
+        if (d.verifyingContract !== undefined)
+            domainType.push({ name: "verifyingContract", type: "address" });
+        const fullTypedData = {
+            types: {
+                EIP712Domain: domainType,
+                ...Object.fromEntries(Object.entries(params.types).map(([k, v]) => [k, [...v]])),
+            },
+            primaryType: params.primaryType,
+            domain: params.domain,
+            message: params.message,
+        };
+        const json = JSON.stringify(fullTypedData, (_key, v) => typeof v === "bigint" ? v.toString() : v);
+        const result = ows.signTypedData(walletId, "evm", json, owsApiKey);
+        const sig = result.signature.startsWith("0x")
+            ? result.signature.slice(2)
+            : result.signature;
+        if (sig.length === 130)
+            return `0x${sig}`;
+        const v = (result.recoveryId ?? 0) + 27;
+        return `0x${sig}${v.toString(16).padStart(2, "0")}`;
+    };
+}
+// ── Standalone discover (no wallet needed) ───────────────────────────
+export async function discover(query, options) {
+    const testnet = options?.testnet ?? !!process.env.PAYSKILL_TESTNET;
+    const apiUrl = resolveApiUrl(testnet);
+    return discoverImpl(apiUrl, DEFAULT_TIMEOUT, query, options);
+}
+async function discoverImpl(apiUrl, timeout, query, options) {
+    const params = new URLSearchParams();
+    if (query)
+        params.set("q", query);
+    if (options?.sort)
+        params.set("sort", options.sort);
+    if (options?.category)
+        params.set("category", options.category);
+    if (options?.settlement)
+        params.set("settlement", options.settlement);
+    const qs = params.toString();
+    const url = `${apiUrl}/discover${qs ? `?${qs}` : ""}`;
+    const resp = await fetch(url, { signal: AbortSignal.timeout(timeout) });
+    if (!resp.ok) {
+        throw new PayServerError(`discover failed: ${resp.status}`, resp.status);
+    }
+    const data = (await resp.json());
+    return data.services.map((s) => ({
+        name: String(s.name ?? ""),
+        description: String(s.description ?? ""),
+        baseUrl: String(s.base_url ?? s.baseUrl ?? ""),
+        category: String(s.category ?? ""),
+        keywords: s.keywords ?? [],
+        routes: s.routes ?? [],
+        docsUrl: s.docs_url != null || s.docsUrl != null
+            ? String(s.docs_url ?? s.docsUrl)
+            : undefined,
+    }));
+}
+// ── Wallet ───────────────────────────────────────────────────────────
 export class Wallet {
     address;
-    _privateKey;
-    _apiUrl;
-    _chain;
-    _chainId;
-    _routerAddress;
-    _account;
-    /** URL path prefix extracted from apiUrl (e.g., "/api/v1"). */
-    _basePath;
-    /** Cached contracts response. */
-    _contractsCache = null;
+    // Signing: signTypedData works for both private key and OWS.
+    // rawKey is non-null only for private-key wallets (needed for x402 direct / EIP-3009).
+    #signTypedData;
+    #rawKey;
+    #apiUrl;
+    #basePath;
+    #testnet;
+    #timeout;
+    #contracts = null;
+    /**
+     * Sync constructor. Resolves key from: privateKey arg -> PAYSKILL_KEY env -> error.
+     * For OS keychain, use `await Wallet.create()`.
+     * For OWS, use `await Wallet.fromOws({ walletId })`.
+     */
     constructor(options) {
-        this._privateKey = normalizeKey(options.privateKey);
-        this._apiUrl = options.apiUrl;
-        this._chain = options.chain;
-        this._chainId = options.chainId ?? CHAIN_IDS[options.chain] ?? (parseInt(options.chain, 10) || 8453);
-        this._routerAddress = options.routerAddress;
-        this._account = privateKeyToAccount(this._privateKey);
-        this.address = this._account.address;
+        // Check for internal OWS init (symbol key hidden from public API)
+        const raw = options;
+        if (raw && raw[_OWS_INIT]) {
+            const init = raw;
+            this.address = init._address;
+            this.#signTypedData = init._signTypedData;
+            this.#rawKey = null;
+            this.#testnet = init._testnet;
+            this.#timeout = init._timeout;
+            this.#apiUrl = resolveApiUrl(this.#testnet);
+            try {
+                this.#basePath = new URL(this.#apiUrl).pathname.replace(/\/+$/, "");
+            }
+            catch {
+                this.#basePath = "";
+            }
+            return;
+        }
+        const key = options?.privateKey ?? process.env.PAYSKILL_KEY;
+        if (!key) {
+            throw new PayError("No private key found. Provide { privateKey }, set PAYSKILL_KEY env var, " +
+                "or use Wallet.create() to read from OS keychain.");
+        }
+        this.#rawKey = normalizeKey(key);
+        const account = privateKeyToAccount(this.#rawKey);
+        this.address = account.address;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.#signTypedData = (p) => account.signTypedData(p);
+        this.#testnet = options?.testnet ?? !!process.env.PAYSKILL_TESTNET;
+        this.#timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+        this.#apiUrl = resolveApiUrl(this.#testnet);
         try {
-            this._basePath = new URL(options.apiUrl).pathname.replace(/\/+$/, "");
+            this.#basePath = new URL(this.#apiUrl).pathname.replace(/\/+$/, "");
         }
         catch {
-            this._basePath = "";
+            this.#basePath = "";
         }
     }
-    get _authConfig() {
-        return {
-            chainId: this._chainId,
-            routerAddress: this._routerAddress,
+    /** Async factory. Resolves key from: privateKey arg -> OS keychain -> PAYSKILL_KEY env -> error. */
+    static async create(options) {
+        if (options?.privateKey)
+            return new Wallet(options);
+        const keychainKey = await readFromKeychain();
+        if (keychainKey) {
+            return new Wallet({ ...options, privateKey: keychainKey });
+        }
+        return new Wallet(options);
+    }
+    /** Sync factory. Reads key from PAYSKILL_KEY env var only. */
+    static fromEnv(options) {
+        const key = process.env.PAYSKILL_KEY;
+        if (!key)
+            throw new PayError("PAYSKILL_KEY env var not set");
+        return new Wallet({ privateKey: key, testnet: options?.testnet });
+    }
+    /** Async factory. Creates a wallet backed by an OWS (Open Wallet Standard) wallet. */
+    static async fromOws(options) {
+        let owsModule;
+        if (options._owsModule) {
+            owsModule = options._owsModule;
+        }
+        else {
+            try {
+                const moduleName = "@open-wallet-standard/core";
+                owsModule = (await import(moduleName));
+            }
+            catch {
+                throw new PayError("@open-wallet-standard/core is not installed. " +
+                    "Install it with: npm install @open-wallet-standard/core");
+            }
+        }
+        const walletInfo = owsModule.getWallet(options.walletId);
+        const evmAccount = walletInfo.accounts.find((a) => a.chainId === "evm" || a.chainId.startsWith("eip155:"));
+        if (!evmAccount) {
+            throw new PayError(`No EVM account found in OWS wallet '${options.walletId}'. ` +
+                `Available chains: ${walletInfo.accounts.map((a) => a.chainId).join(", ") || "none"}.`);
+        }
+        const signFn = createOwsSignTypedData(owsModule, options.walletId, options.owsApiKey);
+        // Use the internal init path through the constructor
+        return new Wallet({
+            [_OWS_INIT]: true,
+            _address: evmAccount.address,
+            _signTypedData: signFn,
+            _testnet: options.testnet ?? !!process.env.PAYSKILL_TESTNET,
+            _timeout: options.timeout ?? DEFAULT_TIMEOUT,
+        });
+    }
+    // ── Internal: contracts ──────────────────────────────────────────
+    async ensureContracts() {
+        if (this.#contracts)
+            return this.#contracts;
+        let resp;
+        try {
+            resp = await fetch(`${this.#apiUrl}/contracts`, {
+                signal: AbortSignal.timeout(this.#timeout),
+            });
+        }
+        catch (e) {
+            throw new PayNetworkError(`Failed to reach server: ${e}`);
+        }
+        if (!resp.ok) {
+            throw new PayNetworkError(`Failed to fetch contracts: ${resp.status}`);
+        }
+        const data = (await resp.json());
+        this.#contracts = {
+            router: String(data.router ?? ""),
+            tab: String(data.tab ?? ""),
+            direct: String(data.direct ?? ""),
+            fee: String(data.fee ?? ""),
+            usdc: String(data.usdc ?? ""),
+            chainId: Number(data.chain_id ?? 0),
+            relayer: String(data.relayer ?? ""),
         };
+        return this.#contracts;
     }
-    /** Build authenticated fetch headers for an API request. */
-    async _authFetch(path, init = {}) {
+    // ── Internal: HTTP ───────────────────────────────────────────────
+    async authFetch(path, init = {}) {
+        const contracts = await this.ensureContracts();
         const method = (init.method ?? "GET").toUpperCase();
-        // Sign only the path portion (no query string) — server verifies against uri.path().
         const pathOnly = path.split("?")[0];
-        const signPath = this._basePath + pathOnly;
-        const authHeaders = await buildAuthHeaders(this._privateKey, method, signPath, this._authConfig);
-        const resp = await fetch(`${this._apiUrl}${path}`, {
+        const signPath = this.#basePath + pathOnly;
+        const config = {
+            chainId: contracts.chainId,
+            routerAddress: contracts.router,
+        };
+        const headers = this.#rawKey
+            ? await buildAuthHeaders(this.#rawKey, method, signPath, config)
+            : await buildAuthHeadersSigned(this.address, this.#signTypedData, method, signPath, config);
+        return fetch(`${this.#apiUrl}${path}`, {
             ...init,
+            signal: init.signal ?? AbortSignal.timeout(this.#timeout),
             headers: {
                 "Content-Type": "application/json",
-                ...authHeaders,
+                ...headers,
                 ...init.headers,
             },
         });
-        return resp;
     }
-    /** Get USDC balance in human-readable units (e.g., 142.50). */
-    async balance() {
-        const resp = await this._authFetch("/status");
-        if (!resp.ok)
-            throw new Error(`balance fetch failed: ${resp.status}`);
-        const data = (await resp.json());
-        if (!data.balance_usdc)
-            return 0;
-        const raw = parseFloat(data.balance_usdc);
-        // Server returns raw micro-units (USDC 6 decimals). Convert to dollars.
-        return raw / 1_000_000;
+    async get(path) {
+        let resp;
+        try {
+            resp = await this.authFetch(path);
+        }
+        catch (e) {
+            if (e instanceof PayError)
+                throw e;
+            throw new PayNetworkError(String(e));
+        }
+        return this.handleResponse(resp);
     }
-    /**
-     * Sign an EIP-2612 permit for a given spender and amount.
-     * Uses the server's /permit/prepare endpoint to get the nonce and hash,
-     * then signs the hash locally.
-     * @param flow — "direct" or "tab" (used to look up the spender contract address)
-     * @param amount — micro-USDC amount
-     */
-    async signPermit(flow, amount) {
-        const contracts = await this.getContracts();
-        const spender = flow === "tab" ? contracts.tab : contracts.direct;
-        // Server prepares the permit: reads nonce via its own RPC, computes EIP-712 hash
-        const prepResp = await this._authFetch("/permit/prepare", {
-            method: "POST",
-            body: JSON.stringify({ amount, spender }),
-        });
-        if (!prepResp.ok) {
-            const err = (await prepResp.json().catch(() => ({})));
-            throw new Error(err.error ?? `permit/prepare failed: ${prepResp.status}`);
-        }
-        const prep = (await prepResp.json());
-        // Sign the pre-computed EIP-712 hash locally (raw ECDSA, no EIP-191 prefix)
-        const signature = await this._account.sign({
-            hash: prep.hash,
-        });
-        // Parse 65-byte signature into v, r, s
-        const sigClean = signature.startsWith("0x") ? signature.slice(2) : signature;
-        const r = "0x" + sigClean.slice(0, 64);
-        const s = "0x" + sigClean.slice(64, 128);
-        const v = parseInt(sigClean.slice(128, 130), 16);
-        return { nonce: prep.nonce, deadline: prep.deadline, v, r, s };
-    }
-    /** Send a direct payment. Auto-signs permit if not provided. */
-    async payDirect(to, amount, memo, options) {
-        const microAmount = Math.round(amount * 1_000_000);
-        // Auto-sign permit if not provided
-        let permit = options?.permit;
-        if (!permit) {
-            permit = await this.signPermit("direct", microAmount);
-        }
-        const resp = await this._authFetch("/direct", {
-            method: "POST",
-            body: JSON.stringify({
-                to,
-                amount: microAmount,
-                memo,
-                permit,
-            }),
-        });
-        if (!resp.ok) {
-            const err = (await resp.json().catch(() => ({})));
-            throw new Error(err.error ?? `payDirect failed: ${resp.status}`);
+    async post(path, body) {
+        let resp;
+        try {
+            resp = await this.authFetch(path, {
+                method: "POST",
+                body: JSON.stringify(body),
+            });
+        }
+        catch (e) {
+            if (e instanceof PayError)
+                throw e;
+            throw new PayNetworkError(String(e));
+        }
+        return this.handleResponse(resp);
+    }
+    async del(path) {
+        let resp;
+        try {
+            resp = await this.authFetch(path, { method: "DELETE" });
         }
+        catch (e) {
+            if (e instanceof PayError)
+                throw e;
+            throw new PayNetworkError(String(e));
+        }
+        if (resp.status >= 400) {
+            const text = await resp.text();
+            throw new PayServerError(text, resp.status);
+        }
+    }
+    async handleResponse(resp) {
+        if (resp.status >= 400) {
+            let msg;
+            try {
+                const body = (await resp.json());
+                msg = body.error ?? `Server error: ${resp.status}`;
+                if (body.code === "insufficient_funds" ||
+                    msg.toLowerCase().includes("insufficient")) {
+                    throw new PayInsufficientFundsError(msg);
+                }
+            }
+            catch (e) {
+                if (e instanceof PayInsufficientFundsError)
+                    throw e;
+                msg = `Server error: ${resp.status}`;
+            }
+            throw new PayServerError(msg, resp.status);
+        }
+        if (resp.status === 204)
+            return undefined;
         return (await resp.json());
     }
-    /** Create a one-time fund link via the server. Returns the dashboard URL. */
-    async createFundLink(options) {
-        const resp = await this._authFetch("/links/fund", {
-            method: "POST",
-            body: JSON.stringify({
-                messages: options?.messages ?? [],
-                agent_name: options?.agentName,
-            }),
+    // ── Internal: permits ────────────────────────────────────────────
+    async signPermit(flow, microAmount) {
+        const contracts = await this.ensureContracts();
+        const spender = flow === "tab"
+            ? contracts.tab
+            : flow === "withdraw"
+                ? contracts.relayer
+                : contracts.direct;
+        const prep = await this.post("/permit/prepare", { amount: microAmount, spender });
+        if (this.#rawKey) {
+            // Private key path: sign the pre-computed hash directly
+            const account = privateKeyToAccount(this.#rawKey);
+            const signature = await account.sign({
+                hash: prep.hash,
+            });
+            return { nonce: prep.nonce, deadline: prep.deadline, ...parseSig(signature) };
+        }
+        // OWS path: sign full EIP-2612 permit typed data
+        const signature = await this.#signTypedData({
+            domain: {
+                name: "USD Coin",
+                version: "2",
+                chainId: contracts.chainId,
+                verifyingContract: contracts.usdc,
+            },
+            types: {
+                Permit: [
+                    { name: "owner", type: "address" },
+                    { name: "spender", type: "address" },
+                    { name: "value", type: "uint256" },
+                    { name: "nonce", type: "uint256" },
+                    { name: "deadline", type: "uint256" },
+                ],
+            },
+            primaryType: "Permit",
+            message: {
+                owner: this.address,
+                spender: spender,
+                value: BigInt(microAmount),
+                nonce: BigInt(prep.nonce),
+                deadline: BigInt(prep.deadline),
+            },
         });
-        if (!resp.ok) {
-            const err = (await resp.json().catch(() => ({})));
-            throw new Error(err.error ?? `createFundLink failed: ${resp.status}`);
+        return { nonce: prep.nonce, deadline: prep.deadline, ...parseSig(signature) };
+    }
+    // ── Internal: x402 ───────────────────────────────────────────────
+    async parse402(resp) {
+        const prHeader = resp.headers.get("payment-required");
+        if (prHeader) {
+            try {
+                const decoded = JSON.parse(atob(prHeader));
+                return extract402(decoded);
+            }
+            catch {
+                /* fall through to body */
+            }
         }
-        const data = (await resp.json());
-        return data.url;
+        const body = (await resp.json());
+        return extract402((body.requirements ?? body));
     }
-    /** Create a one-time withdraw link via the server. Returns the dashboard URL. */
-    async createWithdrawLink(options) {
-        const resp = await this._authFetch("/links/withdraw", {
-            method: "POST",
-            body: JSON.stringify({
-                messages: options?.messages ?? [],
-                agent_name: options?.agentName,
-            }),
-        });
-        if (!resp.ok) {
-            const err = (await resp.json().catch(() => ({})));
-            throw new Error(err.error ?? `createWithdrawLink failed: ${resp.status}`);
+    async handle402(resp, url, method, body, headers) {
+        const reqs = await this.parse402(resp);
+        if (reqs.settlement === "tab") {
+            return this.settleViaTab(url, method, body, headers, reqs);
         }
-        const data = (await resp.json());
-        return data.url;
+        return this.settleViaDirect(url, method, body, headers, reqs);
     }
-    /** Register a webhook for this wallet. */
-    async registerWebhook(url, events, secret) {
-        const payload = { url, events };
-        if (secret)
-            payload.secret = secret;
-        const resp = await this._authFetch("/webhooks", {
-            method: "POST",
-            body: JSON.stringify(payload),
+    async settleViaDirect(url, method, body, headers, reqs) {
+        if (!this.#rawKey) {
+            throw new PayError("x402 direct settlement requires a private key. " +
+                "OWS wallets only support tab settlement. " +
+                "Ask the provider to enable tab settlement, or use a private key wallet.");
+        }
+        const contracts = await this.ensureContracts();
+        const auth = await signTransferAuthorization(this.#rawKey, reqs.to, reqs.amount, contracts.chainId, contracts.usdc);
+        const paymentPayload = {
+            x402Version: 2,
+            accepted: reqs.accepted ?? {
+                scheme: "exact",
+                network: `eip155:${contracts.chainId}`,
+                amount: String(reqs.amount),
+                payTo: reqs.to,
+            },
+            payload: {
+                signature: combinedSignature(auth),
+                authorization: {
+                    from: auth.from,
+                    to: auth.to,
+                    value: String(reqs.amount),
+                    validAfter: "0",
+                    validBefore: "0",
+                    nonce: auth.nonce,
+                },
+            },
+            extensions: {},
+        };
+        return fetch(url, {
+            method,
+            body,
+            signal: AbortSignal.timeout(this.#timeout),
+            headers: {
+                ...headers,
+                "Content-Type": "application/json",
+                "PAYMENT-SIGNATURE": btoa(JSON.stringify(paymentPayload)),
+            },
         });
-        if (!resp.ok)
-            throw new Error(`registerWebhook failed: ${resp.status}`);
-        return (await resp.json());
     }
-    /** Open a tab with a provider (positional or object form). */
-    async openTab(providerOrOpts, amount, maxChargePerCall, options) {
-        let provider;
-        let amt;
-        let maxCharge;
-        let permit;
-        if (typeof providerOrOpts === "string") {
-            if (amount === undefined || maxChargePerCall === undefined) {
-                throw new Error("amount and maxChargePerCall are required when provider is a string");
+    async settleViaTab(url, method, body, headers, reqs) {
+        const contracts = await this.ensureContracts();
+        const rawTabs = await this.get("/tabs");
+        let tab = rawTabs.find((t) => t.provider === reqs.to && t.status === "open");
+        if (!tab) {
+            const tabMicro = Math.max(reqs.amount * TAB_MULTIPLIER, TAB_MIN_MICRO);
+            const bal = await this.balance();
+            const tabDollars = toDollars(tabMicro);
+            if (bal.available < tabDollars) {
+                throw new PayInsufficientFundsError(`Insufficient balance for tab: have $${bal.available.toFixed(2)}, need $${tabDollars.toFixed(2)}`, bal.available, tabDollars);
             }
-            provider = providerOrOpts;
-            amt = amount;
-            maxCharge = maxChargePerCall;
-            permit = options?.permit;
-        }
-        else {
-            provider = providerOrOpts.to;
-            amt = providerOrOpts.limit;
-            maxCharge = providerOrOpts.perUnit;
-            permit = providerOrOpts.permit;
-        }
-        const microAmount = Math.round(amt * 1_000_000);
-        // Auto-sign permit if not provided
-        if (!permit) {
-            permit = await this.signPermit("tab", microAmount);
-        }
-        const resp = await this._authFetch("/tabs", {
-            method: "POST",
-            body: JSON.stringify({
-                provider,
-                amount: microAmount,
-                max_charge_per_call: Math.round(maxCharge * 1_000_000),
+            const permit = await this.signPermit("tab", tabMicro);
+            tab = await this.post("/tabs", {
+                provider: reqs.to,
+                amount: tabMicro,
+                max_charge_per_call: reqs.amount,
                 permit,
-            }),
+            });
+        }
+        const charge = await this.post(`/tabs/${tab.tab_id}/charge`, { amount: reqs.amount });
+        const paymentPayload = {
+            x402Version: 2,
+            accepted: reqs.accepted ?? {
+                scheme: "exact",
+                network: `eip155:${contracts.chainId}`,
+                amount: String(reqs.amount),
+                payTo: reqs.to,
+            },
+            payload: {
+                authorization: { from: this.address },
+            },
+            extensions: {
+                pay: {
+                    settlement: "tab",
+                    tabId: tab.tab_id,
+                    chargeId: charge.charge_id ?? "",
+                },
+            },
+        };
+        return fetch(url, {
+            method,
+            body,
+            signal: AbortSignal.timeout(this.#timeout),
+            headers: {
+                ...headers,
+                "Content-Type": "application/json",
+                "PAYMENT-SIGNATURE": btoa(JSON.stringify(paymentPayload)),
+            },
         });
-        if (!resp.ok)
-            throw new Error(`openTab failed: ${resp.status}`);
-        const data = (await resp.json());
-        return { id: data.tab_id, tab_id: data.tab_id };
-    }
-    /** Charge a tab (provider-side). */
-    async chargeTab(tabId, amountOrOpts) {
-        const body = typeof amountOrOpts === "number"
-            ? { amount: Math.round(amountOrOpts * 1_000_000) }
-            : {
-                amount: Math.round(amountOrOpts.amount * 1_000_000),
-                cumulative: Math.round(amountOrOpts.cumulative * 1_000_000),
-                call_count: amountOrOpts.callCount,
-                provider_sig: amountOrOpts.providerSig,
-            };
-        const resp = await this._authFetch(`/tabs/${tabId}/charge`, {
-            method: "POST",
-            body: JSON.stringify(body),
+    }
+    // ── Public: Direct Payment ───────────────────────────────────────
+    async send(to, amount, memo) {
+        validateAddress(to);
+        const micro = toMicro(amount);
+        if (micro < DIRECT_MIN_MICRO) {
+            throw new PayValidationError("Amount below minimum ($1.00)", "amount");
+        }
+        const permit = await this.signPermit("direct", micro);
+        const raw = await this.post("/direct", {
+            to,
+            amount: micro,
+            memo: memo ?? "",
+            permit,
         });
-        if (!resp.ok)
-            throw new Error(`chargeTab failed: ${resp.status}`);
-        return (await resp.json());
+        return {
+            txHash: raw.tx_hash,
+            status: raw.status,
+            amount: toDollars(raw.amount),
+            fee: toDollars(raw.fee),
+        };
     }
-    /** Close a tab. */
-    async closeTab(tabId, options) {
-        const body = {};
-        if (options?.finalAmount !== undefined)
-            body.final_amount = Math.round(options.finalAmount * 1_000_000);
-        if (options?.providerSig)
-            body.provider_sig = options.providerSig;
-        const resp = await this._authFetch(`/tabs/${tabId}/close`, {
-            method: "POST",
-            body: JSON.stringify(body),
+    // ── Public: Tabs ─────────────────────────────────────────────────
+    async openTab(provider, amount, maxChargePerCall) {
+        validateAddress(provider);
+        const microAmount = toMicro(amount);
+        const microMax = toMicro(maxChargePerCall);
+        if (microAmount < TAB_MIN_MICRO) {
+            throw new PayValidationError("Tab amount below minimum ($5.00)", "amount");
+        }
+        if (microMax <= 0) {
+            throw new PayValidationError("maxChargePerCall must be positive", "maxChargePerCall");
+        }
+        const permit = await this.signPermit("tab", microAmount);
+        const raw = await this.post("/tabs", {
+            provider,
+            amount: microAmount,
+            max_charge_per_call: microMax,
+            permit,
         });
-        if (!resp.ok)
-            throw new Error(`closeTab failed: ${resp.status}`);
-        return (await resp.json());
+        return parseTab(raw);
     }
-    /** Fetch contract addresses from the API (public, no auth). */
-    async getContracts() {
-        if (this._contractsCache)
-            return this._contractsCache;
-        const resp = await fetch(`${this._apiUrl}/contracts`);
-        if (!resp.ok)
-            throw new Error(`getContracts failed: ${resp.status}`);
-        const data = (await resp.json());
-        this._contractsCache = {
-            router: data.router ?? "",
-            tab: data.tab ?? "",
-            direct: data.direct ?? "",
-            fee: data.fee ?? "",
-            usdc: data.usdc ?? "",
-            chainId: data.chain_id ?? 0,
-        };
-        return this._contractsCache;
+    async closeTab(tabId) {
+        const raw = await this.post(`/tabs/${tabId}/close`, {});
+        return parseTab(raw);
     }
-    /** Sign a tab charge (provider-side EIP-712 signature). */
-    async signTabCharge(contractAddr, tabId, cumulativeUnits, callCount) {
-        return this._account.signTypedData({
-            domain: {
-                name: "pay",
-                version: "0.1",
-                chainId: this._chainId,
-                verifyingContract: contractAddr,
-            },
-            types: {
-                TabCharge: [
-                    { name: "tabId", type: "string" },
-                    { name: "cumulativeUnits", type: "uint256" },
-                    { name: "callCount", type: "uint256" },
-                ],
-            },
-            primaryType: "TabCharge",
-            message: {
-                tabId,
-                cumulativeUnits: BigInt(cumulativeUnits),
-                callCount: BigInt(callCount),
-            },
+    async topUpTab(tabId, amount) {
+        const micro = toMicro(amount);
+        if (micro <= 0) {
+            throw new PayValidationError("Amount must be positive", "amount");
+        }
+        const permit = await this.signPermit("tab", micro);
+        const raw = await this.post(`/tabs/${tabId}/topup`, {
+            amount: micro,
+            permit,
         });
+        return parseTab(raw);
+    }
+    async listTabs() {
+        const raw = await this.get("/tabs");
+        return raw.map(parseTab);
     }
-    /** Sign a raw hash with the wallet's private key. */
-    async _signHash(hash) {
-        const signature = await this._account.signMessage({
-            message: { raw: hash },
+    async getTab(tabId) {
+        const raw = await this.get(`/tabs/${tabId}`);
+        return parseTab(raw);
+    }
+    async chargeTab(tabId, amount) {
+        const micro = toMicro(amount);
+        const raw = await this.post(`/tabs/${tabId}/charge`, { amount: micro });
+        return { chargeId: raw.charge_id ?? "", status: raw.status };
+    }
+    // ── Public: x402 ─────────────────────────────────────────────────
+    async request(url, options) {
+        const method = options?.method ?? "GET";
+        const headers = options?.headers ?? {};
+        const bodyStr = options?.body
+            ? JSON.stringify(options.body)
+            : undefined;
+        const resp = await fetch(url, {
+            method,
+            body: bodyStr,
+            headers,
+            signal: AbortSignal.timeout(this.#timeout),
         });
-        // Parse 65-byte signature into v, r, s
-        const sigClean = signature.startsWith("0x")
-            ? signature.slice(2)
-            : signature;
-        const r = "0x" + sigClean.slice(0, 64);
-        const s = "0x" + sigClean.slice(64, 128);
-        const v = parseInt(sigClean.slice(128, 130), 16);
-        return { v, r, s };
+        if (resp.status !== 402)
+            return resp;
+        return this.handle402(resp, url, method, bodyStr, headers);
     }
-}
-/** PrivateKeySigner — for manual EIP-712 signing in the playground. */
-export class PrivateKeySigner {
-    _account;
-    address;
-    constructor(privateKey) {
-        const key = normalizeKey(privateKey);
-        this._account = privateKeyToAccount(key);
-        this.address = this._account.address;
-    }
-    /** Sign EIP-712 typed data. Returns hex signature. */
-    async signTypedData(domain, types, message) {
-        return this._account.signTypedData({
-            domain: domain,
-            types: types,
-            primaryType: Object.keys(types)[0],
-            message,
+    // ── Public: Wallet ───────────────────────────────────────────────
+    async balance() {
+        const raw = await this.get("/status");
+        const total = raw.balance_usdc
+            ? Number(raw.balance_usdc) / 1_000_000
+            : 0;
+        const locked = (raw.total_locked ?? 0) / 1_000_000;
+        return { total, locked, available: total - locked };
+    }
+    async status() {
+        const raw = await this.get("/status");
+        const total = raw.balance_usdc
+            ? Number(raw.balance_usdc) / 1_000_000
+            : 0;
+        const locked = (raw.total_locked ?? 0) / 1_000_000;
+        return {
+            address: raw.wallet,
+            balance: { total, locked, available: total - locked },
+            openTabs: raw.open_tabs,
+        };
+    }
+    // ── Public: Discovery ────────────────────────────────────────────
+    async discover(query, options) {
+        return discoverImpl(this.#apiUrl, this.#timeout, query, options);
+    }
+    // ── Public: Funding ──────────────────────────────────────────────
+    async createFundLink(options) {
+        // Sign permit so dashboard withdraw tab works from any link.
+        const payload = {
+            messages: options?.message ? [{ text: options.message }] : [],
+            agent_name: options?.agentName,
+        };
+        try {
+            const st = await this.status();
+            const microBalance = Math.round(st.balance.total * 1_000_000);
+            if (microBalance > 0) {
+                const permit = await this.signPermit("withdraw", microBalance);
+                payload.permit = {
+                    value: microBalance,
+                    deadline: permit.deadline,
+                    v: permit.v,
+                    r: permit.r,
+                    s: permit.s,
+                };
+            }
+        }
+        catch {
+            // Best effort — fund link still works without permit
+        }
+        const data = await this.post("/links/fund", payload);
+        return data.url;
+    }
+    async createWithdrawLink(options) {
+        // Sign a USDC permit granting the relayer allowance for the full balance.
+        const status = await this.status();
+        const microBalance = Math.round(status.balance.total * 1_000_000);
+        if (microBalance <= 0) {
+            throw new PayError("no USDC balance to create withdraw link");
+        }
+        const permit = await this.signPermit("withdraw", microBalance);
+        const data = await this.post("/links/withdraw", {
+            messages: options?.message ? [{ text: options.message }] : [],
+            agent_name: options?.agentName,
+            permit: {
+                value: microBalance,
+                deadline: permit.deadline,
+                v: permit.v,
+                r: permit.r,
+                s: permit.s,
+            },
         });
+        return data.url;
+    }
+    // ── Public: Webhooks ─────────────────────────────────────────────
+    async registerWebhook(url, events, secret) {
+        const payload = { url };
+        if (events)
+            payload.events = events;
+        if (secret)
+            payload.secret = secret;
+        const raw = await this.post("/webhooks", payload);
+        return { id: raw.id, url: raw.url, events: raw.events };
+    }
+    async listWebhooks() {
+        const raw = await this.get("/webhooks");
+        return raw.map((w) => ({ id: w.id, url: w.url, events: w.events }));
+    }
+    async deleteWebhook(webhookId) {
+        await this.del(`/webhooks/${webhookId}`);
+    }
+    // ── Public: Testnet ──────────────────────────────────────────────
+    async mint(amount) {
+        if (!this.#testnet) {
+            throw new PayError("mint is only available on testnet");
+        }
+        const micro = toMicro(amount);
+        const raw = await this.post("/mint", { amount: micro });
+        return { txHash: raw.tx_hash, amount: toDollars(raw.amount) };
     }
 }
-/** Normalize a private key to 0x-prefixed Hex. */
-function normalizeKey(key) {
-    if (key.startsWith("0x"))
-        return key;
-    return ("0x" + key);
+// ── x402 helpers ─────────────────────────────────────────────────────
+function extract402(obj) {
+    const accepts = obj.accepts;
+    if (Array.isArray(accepts) && accepts.length > 0) {
+        const offer = accepts[0];
+        const extra = (offer.extra ?? {});
+        return {
+            settlement: String(extra.settlement ?? "direct"),
+            amount: Number(offer.amount ?? 0),
+            to: String(offer.payTo ?? ""),
+            accepted: offer,
+        };
+    }
+    return {
+        settlement: String(obj.settlement ?? "direct"),
+        amount: Number(obj.amount ?? 0),
+        to: String(obj.to ?? ""),
+    };
 }
 //# sourceMappingURL=wallet.js.map