@pay-skill/sdk 0.1.1

package/dist/wallet.js

@@ -0,0 +1,328 @@
+/**
+ * Wallet — high-level write client for agents.
+ * Wraps PayClient with private key signing and balance tracking.
+ *
+ * This is the primary entry point for the playground and agent integrations.
+ * The PayClient is lower-level (HTTP only); Wallet adds signing + state.
+ */
+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,
+};
+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;
+    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;
+        try {
+            this._basePath = new URL(options.apiUrl).pathname.replace(/\/+$/, "");
+        }
+        catch {
+            this._basePath = "";
+        }
+    }
+    get _authConfig() {
+        return {
+            chainId: this._chainId,
+            routerAddress: this._routerAddress,
+        };
+    }
+    /** Build authenticated fetch headers for an API request. */
+    async _authFetch(path, init = {}) {
+        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}`, {
+            ...init,
+            headers: {
+                "Content-Type": "application/json",
+                ...authHeaders,
+                ...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;
+    }
+    /**
+     * 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 hash locally
+        const signature = await this._account.signMessage({
+            message: { raw: 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}`);
+        }
+        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,
+            }),
+        });
+        if (!resp.ok) {
+            const err = (await resp.json().catch(() => ({})));
+            throw new Error(err.error ?? `createFundLink failed: ${resp.status}`);
+        }
+        const data = (await resp.json());
+        return data.url;
+    }
+    /** 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}`);
+        }
+        const data = (await resp.json());
+        return data.url;
+    }
+    /** 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),
+        });
+        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") {
+            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),
+                permit,
+            }),
+        });
+        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),
+        });
+        if (!resp.ok)
+            throw new Error(`chargeTab failed: ${resp.status}`);
+        return (await resp.json());
+    }
+    /** 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),
+        });
+        if (!resp.ok)
+            throw new Error(`closeTab failed: ${resp.status}`);
+        return (await resp.json());
+    }
+    /** 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;
+    }
+    /** 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),
+            },
+        });
+    }
+    /** Sign a raw hash with the wallet's private key. */
+    async _signHash(hash) {
+        const signature = await this._account.signMessage({
+            message: { raw: 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 { v, r, s };
+    }
+}
+/** 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,
+        });
+    }
+}
+/** Normalize a private key to 0x-prefixed Hex. */
+function normalizeKey(key) {
+    if (key.startsWith("0x"))
+        return key;
+    return ("0x" + key);
+}
+//# sourceMappingURL=wallet.js.map

package/dist/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"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"}

package/eslint.config.js

@@ -0,0 +1,22 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import globals from "globals";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.strict,
+  {
+    languageOptions: {
+      globals: globals.node,
+    },
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" },
+      ],
+    },
+  },
+  {
+    ignores: ["dist/", "tests/", "node_modules/"],
+  }
+);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pay-skill/sdk",
+  "version": "0.1.1",
+  "description": "TypeScript SDK for pay — payment infrastructure for AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test tests/*.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@open-wallet-standard/core": ">=1.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@open-wallet-standard/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "@types/node": "^25.5.2",
+    "eslint": "^10.2.0",
+    "globals": "^17.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT"
+}

package/src/auth.ts

@@ -0,0 +1,200 @@
+/**
+ * EIP-712 authentication for pay API requests.
+ *
+ * Every authenticated request includes four headers:
+ *   X-Pay-Agent     — wallet address (0x-prefixed, checksummed)
+ *   X-Pay-Signature — EIP-712 signature (0x-prefixed hex, 65 bytes)
+ *   X-Pay-Timestamp — unix timestamp in seconds
+ *   X-Pay-Nonce     — random 32-byte hex (0x-prefixed)
+ *
+ * The EIP-712 domain:
+ *   name: "pay"
+ *   version: "0.1"
+ *   chainId: <from config>
+ *   verifyingContract: <router address>
+ *
+ * The typed data:
+ *   APIRequest(string method, string path, uint256 timestamp, bytes32 nonce)
+ */
+
+import { type Hex, keccak256, encodePacked, type Address } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { randomBytes } from "node:crypto";
+
+export interface AuthConfig {
+  chainId: number;
+  routerAddress: Address;
+}
+
+export interface AuthHeaders {
+  "X-Pay-Agent": string;
+  "X-Pay-Signature": string;
+  "X-Pay-Timestamp": string;
+  "X-Pay-Nonce": string;
+}
+
+const EIP712_DOMAIN = {
+  name: "pay",
+  version: "0.1",
+} as const;
+
+const API_REQUEST_TYPES = {
+  APIRequest: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    { name: "timestamp", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+/**
+ * Build auth headers for an API request using a private key.
+ */
+export async function buildAuthHeaders(
+  privateKey: Hex,
+  method: string,
+  path: string,
+  config: AuthConfig
+): Promise<AuthHeaders> {
+  const account = privateKeyToAccount(privateKey);
+  const timestamp = BigInt(Math.floor(Date.now() / 1000));
+  const nonce = ("0x" + randomBytes(32).toString("hex")) as Hex;
+
+  const signature = await account.signTypedData({
+    domain: {
+      ...EIP712_DOMAIN,
+      chainId: config.chainId,
+      verifyingContract: config.routerAddress,
+    },
+    types: API_REQUEST_TYPES,
+    primaryType: "APIRequest",
+    message: {
+      method: method.toUpperCase(),
+      path,
+      timestamp,
+      nonce,
+    },
+  });
+
+  return {
+    "X-Pay-Agent": account.address,
+    "X-Pay-Signature": signature,
+    "X-Pay-Timestamp": timestamp.toString(),
+    "X-Pay-Nonce": nonce,
+  };
+}
+
+/**
+ * Build auth headers using a generic signer (Signer interface).
+ * Computes the EIP-712 hash manually and delegates signing to the signer.
+ */
+export function buildAuthHeadersWithSigner(
+  signer: { sign(hash: Uint8Array): Uint8Array; address: string },
+  method: string,
+  path: string,
+  config: AuthConfig
+): AuthHeaders {
+  const timestamp = BigInt(Math.floor(Date.now() / 1000));
+  const nonce = ("0x" + randomBytes(32).toString("hex")) as Hex;
+
+  const hash = computeEip712Hash(
+    method.toUpperCase(),
+    path,
+    timestamp,
+    nonce,
+    config.chainId,
+    config.routerAddress
+  );
+
+  const sigBytes = signer.sign(hash);
+  const signature = ("0x" + Buffer.from(sigBytes).toString("hex")) as Hex;
+
+  return {
+    "X-Pay-Agent": signer.address,
+    "X-Pay-Signature": signature,
+    "X-Pay-Timestamp": timestamp.toString(),
+    "X-Pay-Nonce": nonce,
+  };
+}
+
+/**
+ * Compute the EIP-712 hash for an APIRequest.
+ * Must match the server's computation exactly.
+ */
+export function computeEip712Hash(
+  method: string,
+  path: string,
+  timestamp: bigint,
+  nonce: Hex,
+  chainId: number,
+  verifyingContract: Address
+): Uint8Array {
+  // Type hashes
+  const domainTypehash = keccak256(
+    encodePacked(
+      ["string"],
+      [
+        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)",
+      ]
+    )
+  );
+  const structTypehash = keccak256(
+    encodePacked(
+      ["string"],
+      [
+        "APIRequest(string method,string path,uint256 timestamp,bytes32 nonce)",
+      ]
+    )
+  );
+
+  // Domain separator
+  const nameHash = keccak256(encodePacked(["string"], ["pay"]));
+  const versionHash = keccak256(encodePacked(["string"], ["0.1"]));
+
+  const domainSeparator = keccak256(
+    encodePacked(
+      ["bytes32", "bytes32", "bytes32", "uint256", "bytes32"],
+      [
+        domainTypehash,
+        nameHash,
+        versionHash,
+        BigInt(chainId),
+        ("0x000000000000000000000000" + verifyingContract.slice(2)) as Hex,
+      ]
+    )
+  );
+
+  // Struct hash
+  const methodHash = keccak256(encodePacked(["string"], [method]));
+  const pathHash = keccak256(encodePacked(["string"], [path]));
+
+  // Pad nonce to bytes32
+  const nonceClean = nonce.startsWith("0x") ? nonce.slice(2) : nonce;
+  const noncePadded = ("0x" + nonceClean.padEnd(64, "0")) as Hex;
+
+  const structHash = keccak256(
+    encodePacked(
+      ["bytes32", "bytes32", "bytes32", "uint256", "bytes32"],
+      [structTypehash, methodHash, pathHash, timestamp, noncePadded]
+    )
+  );
+
+  // Final hash: keccak256("\x19\x01" || domainSeparator || structHash)
+  const finalHash = keccak256(
+    encodePacked(
+      ["bytes2", "bytes32", "bytes32"],
+      ["0x1901" as Hex, domainSeparator, structHash]
+    )
+  );
+
+  return hexToBytes(finalHash);
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}