@pay-skill/sdk 0.1.1

package/src/eip3009.ts

@@ -0,0 +1,79 @@
+/**
+ * EIP-3009 TransferWithAuthorization signing for x402 direct settlement.
+ *
+ * Unlike EIP-2612 permits (which need a nonce from the USDC contract),
+ * EIP-3009 uses a random nonce chosen by the signer. Fully local — no
+ * server round-trip needed.
+ *
+ * Domain: { name: "USD Coin", version: "2", chainId, verifyingContract: usdcAddress }
+ * Type: TransferWithAuthorization(address from, address to, uint256 value,
+ *       uint256 validAfter, uint256 validBefore, bytes32 nonce)
+ */
+
+import { type Hex, type Address } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { randomBytes } from "node:crypto";
+
+export interface TransferAuthorization {
+  from: string;
+  to: string;
+  amount: number;
+  nonce: string;
+  v: number;
+  r: string;
+  s: string;
+}
+
+const TRANSFER_AUTH_TYPES = {
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+export async function signTransferAuthorization(
+  privateKey: Hex,
+  to: Address,
+  amount: number,
+  chainId: number,
+  usdcAddress: Address,
+): Promise<TransferAuthorization> {
+  const account = privateKeyToAccount(privateKey);
+  const nonce = ("0x" + randomBytes(32).toString("hex")) as Hex;
+
+  const signature = await account.signTypedData({
+    domain: {
+      name: "USD Coin",
+      version: "2",
+      chainId,
+      verifyingContract: usdcAddress,
+    },
+    types: TRANSFER_AUTH_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: account.address,
+      to,
+      value: BigInt(amount),
+      validAfter: 0n,
+      validBefore: 0n,
+      nonce,
+    },
+  });
+
+  const sigHex = signature.slice(2);
+  const r = `0x${sigHex.slice(0, 64)}`;
+  const s = `0x${sigHex.slice(64, 128)}`;
+  const v = parseInt(sigHex.slice(128, 130), 16);
+
+  return { from: account.address, to, amount, nonce, v, r, s };
+}
+
+export function combinedSignature(auth: TransferAuthorization): string {
+  const r = auth.r.startsWith("0x") ? auth.r.slice(2) : auth.r;
+  const s = auth.s.startsWith("0x") ? auth.s.slice(2) : auth.s;
+  return `0x${r}${s}${auth.v.toString(16).padStart(2, "0")}`;
+}

package/src/errors.ts

@@ -0,0 +1,48 @@
+/** Base error for all pay SDK errors. */
+export class PayError extends Error {
+  readonly code: string;
+
+  constructor(message: string, code = "pay_error") {
+    super(message);
+    this.name = "PayError";
+    this.code = code;
+  }
+}
+
+/** Input validation failed. */
+export class PayValidationError extends PayError {
+  readonly field?: string;
+
+  constructor(message: string, field?: string) {
+    super(message, "validation_error");
+    this.name = "PayValidationError";
+    this.field = field;
+  }
+}
+
+/** Network or server communication failed. */
+export class PayNetworkError extends PayError {
+  constructor(message: string) {
+    super(message, "network_error");
+    this.name = "PayNetworkError";
+  }
+}
+
+/** Server returned an error response. */
+export class PayServerError extends PayError {
+  readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message, "server_error");
+    this.name = "PayServerError";
+    this.statusCode = statusCode;
+  }
+}
+
+/** Insufficient USDC balance. */
+export class PayInsufficientFundsError extends PayError {
+  constructor(message = "Insufficient USDC balance") {
+    super(message, "insufficient_funds");
+    this.name = "PayInsufficientFundsError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+export { PayClient, DEFAULT_API_URL } from "./client.js";
+export type { PayClientOptions } from "./client.js";
+
+export {
+  PayError,
+  PayValidationError,
+  PayNetworkError,
+  PayServerError,
+  PayInsufficientFundsError,
+} from "./errors.js";
+
+export type {
+  DirectPaymentResult,
+  DiscoverOptions,
+  DiscoverService,
+  Tab,
+  TabStatus,
+  StatusResponse,
+  WebhookRegistration,
+} from "./models.js";
+
+export type { Signer } from "./signer.js";
+export {
+  CliSigner,
+  RawKeySigner,
+  CallbackSigner,
+  createSigner,
+} from "./signer.js";
+
+export { OwsSigner } from "./ows-signer.js";
+export type { OwsSignerOptions } from "./ows-signer.js";
+
+export { Wallet, PrivateKeySigner } from "./wallet.js";
+export type {
+  WalletOptions,
+  FundLinkOptions,
+  PermitResult,
+} from "./wallet.js";
+
+export {
+  buildAuthHeaders,
+  buildAuthHeadersWithSigner,
+  computeEip712Hash,
+} from "./auth.js";
+export type { AuthConfig, AuthHeaders } from "./auth.js";
+
+export {
+  signTransferAuthorization,
+  combinedSignature,
+} from "./eip3009.js";
+export type { TransferAuthorization } from "./eip3009.js";

package/src/models.ts

@@ -0,0 +1,77 @@
+/** Tab lifecycle states. */
+export type TabStatus = "open" | "closed";
+
+/** Result of a direct payment. */
+export interface DirectPaymentResult {
+  txHash: string;
+  status: string;
+  /** Amount in USDC micro-units (6 decimals). */
+  amount: number;
+  /** Fee deducted in USDC micro-units. */
+  fee: number;
+}
+
+/** Tab state. */
+export interface Tab {
+  tabId: string;
+  provider: string;
+  /** Total locked amount in USDC micro-units. */
+  amount: number;
+  /** Remaining balance in USDC micro-units. */
+  balanceRemaining: number;
+  /** Total charged so far in USDC micro-units. */
+  totalCharged: number;
+  /** Number of charges made. */
+  chargeCount: number;
+  /** Max per-charge limit in USDC micro-units. */
+  maxChargePerCall: number;
+  /** Total withdrawn so far in USDC micro-units. */
+  totalWithdrawn: number;
+  status: TabStatus;
+  /** Number of charges buffered awaiting batch settlement. */
+  pendingChargeCount: number;
+  /** Total amount of pending charges in USDC micro-units. */
+  pendingChargeTotal: number;
+  /** balance_remaining minus pending charges — the true available balance. */
+  effectiveBalance: number;
+}
+
+/** Wallet status. */
+export interface StatusResponse {
+  address: string;
+  /** USDC balance in micro-units. */
+  balance: number;
+  openTabs: Tab[];
+}
+
+/** Discoverable service from the facilitator catalog. */
+export interface DiscoverService {
+  name: string;
+  description: string;
+  /** Public base URL for pay request (e.g. "https://weather.example.com"). */
+  baseUrl: string;
+  category: string;
+  keywords: string[];
+  routes: { path: string; method?: string; price?: string; settlement?: string; free?: boolean }[];
+  /** URL to API documentation (OpenAPI spec, docs page, etc). */
+  docsUrl?: string;
+}
+
+/** Options for discover search. */
+export interface DiscoverOptions {
+  /** Search query (matches keywords and description). */
+  query?: string;
+  /** Sort order: "volume" (default), "newest", "price_asc", "price_desc". */
+  sort?: string;
+  /** Filter by category. */
+  category?: string;
+  /** Filter by settlement mode: "direct" or "tab". */
+  settlement?: string;
+}
+
+/** Registered webhook. */
+export interface WebhookRegistration {
+  webhookId: string;
+  url: string;
+  events: string[];
+}

package/src/ows-signer.ts

@@ -0,0 +1,223 @@
+/**
+ * OWS (Open Wallet Standard) signer adapter.
+ *
+ * Wraps the @open-wallet-standard/core FFI module to implement the Pay
+ * Signer interface. OWS handles encrypted key storage + policy-gated signing;
+ * this adapter translates between Pay's (domain, types, value) EIP-712
+ * calling convention and OWS's JSON string convention.
+ *
+ * Priority: Pay's own CLI signer is #1, OWS is #2. OWS only activates when
+ * OWS_WALLET_ID is set AND @open-wallet-standard/core is installed. If the
+ * env var is set but the package is missing, creation fails loud with
+ * install instructions.
+ *
+ * Usage:
+ *   const signer = await OwsSigner.create({ walletId: "pay-my-agent" });
+ *   const wallet = new Wallet({ signer });
+ */
+
+import type { Signer } from "./signer.js";
+
+/** Subset of @open-wallet-standard/core we call at runtime. */
+interface OwsModule {
+  getWallet(nameOrId: string, vaultPath?: string): {
+    id: string;
+    name: string;
+    accounts: Array<{
+      chainId: string;
+      address: string;
+      derivationPath: string;
+    }>;
+    createdAt: string;
+  };
+  signTypedData(
+    wallet: string,
+    chain: string,
+    typedDataJson: string,
+    passphrase?: string,
+    index?: number,
+    vaultPath?: string,
+  ): { signature: string; recoveryId?: number };
+}
+
+/** EIP-712 domain fields. */
+export interface TypedDataDomain {
+  name?: string;
+  version?: string;
+  chainId?: number | bigint;
+  verifyingContract?: string;
+}
+
+/** EIP-712 type definitions. */
+export interface TypedDataTypes {
+  [typeName: string]: Array<{ name: string; type: string }>;
+}
+
+/** Options for {@link OwsSigner.create}. */
+export interface OwsSignerOptions {
+  /** OWS wallet name or UUID (e.g. "pay-my-agent"). */
+  walletId: string;
+  /** Chain name - only used for logging, not passed to OWS. Default: "base". */
+  chain?: string;
+  /** OWS API key token (passed as passphrase to OWS signing calls). */
+  owsApiKey?: string;
+  /** @internal Inject OWS module for testing - bypasses dynamic import. */
+  _owsModule?: unknown;
+}
+
+/**
+ * Signer backed by the Open Wallet Standard.
+ *
+ * - Keys live in OWS's encrypted vault (~/.ows/wallets/), never in env vars.
+ * - Signing calls go through OWS FFI, which evaluates policy rules before signing.
+ * - Use the static {@link create} factory - the constructor is private because
+ *   address resolution requires a synchronous FFI call that must happen before
+ *   sign() can work.
+ */
+export class OwsSigner implements Signer {
+  readonly #walletId: string;
+  readonly #address: string;
+  readonly #owsApiKey: string | undefined;
+  readonly #ows: OwsModule;
+
+  private constructor(
+    walletId: string,
+    address: string,
+    owsModule: OwsModule,
+    owsApiKey?: string,
+  ) {
+    this.#walletId = walletId;
+    this.#address = address;
+    this.#ows = owsModule;
+    this.#owsApiKey = owsApiKey;
+  }
+
+  /**
+   * Create an OwsSigner by resolving the wallet address from OWS.
+   *
+   * Lazily imports @open-wallet-standard/core so the module is only required
+   * when OWS is actually used (keeps it an optional peer dependency).
+   */
+  static async create(options: OwsSignerOptions): Promise<OwsSigner> {
+    let owsModule: OwsModule;
+    if (options._owsModule) {
+      owsModule = options._owsModule as OwsModule;
+    } else {
+      try {
+        // Dynamic string prevents TypeScript from statically resolving this
+        // optional peer dependency at compile time.
+        const moduleName = "@open-wallet-standard/core";
+        owsModule = (await import(moduleName)) as unknown as OwsModule;
+      } catch {
+        throw new Error(
+          "OWS_WALLET_ID is set but @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 Error(
+        `No EVM account found in OWS wallet '${options.walletId}'. ` +
+          `Available chains: ${walletInfo.accounts.map((a) => a.chainId).join(", ") || "none"}.`,
+      );
+    }
+
+    return new OwsSigner(
+      options.walletId,
+      evmAccount.address,
+      owsModule,
+      options.owsApiKey,
+    );
+  }
+
+  get address(): string {
+    return this.#address;
+  }
+
+  sign(_hash: Uint8Array): Uint8Array {
+    throw new Error(
+      "OwsSigner does not support raw hash signing. " +
+        "OWS only supports EIP-712 typed data signing. " +
+        "Use CliSigner or RawKeySigner for operations that require sign().",
+    );
+  }
+
+  /**
+   * Sign EIP-712 typed data via OWS FFI.
+   *
+   * This is the primary signing method for OWS. Pay's auth module should
+   * call this instead of sign() when an OwsSigner is detected.
+   */
+  async signTypedData(
+    domain: TypedDataDomain,
+    types: TypedDataTypes,
+    value: Record<string, unknown>,
+  ): Promise<string> {
+    // 1. Derive primaryType: first key in types that is NOT "EIP712Domain".
+    const primaryType =
+      Object.keys(types).filter((k) => k !== "EIP712Domain")[0] ?? "Request";
+
+    // 2. Build EIP712Domain type array dynamically from domain object fields.
+    const eip712DomainType: Array<{ name: string; type: string }> = [];
+    if (domain.name !== undefined)
+      eip712DomainType.push({ name: "name", type: "string" });
+    if (domain.version !== undefined)
+      eip712DomainType.push({ name: "version", type: "string" });
+    if (domain.chainId !== undefined)
+      eip712DomainType.push({ name: "chainId", type: "uint256" });
+    if (domain.verifyingContract !== undefined)
+      eip712DomainType.push({
+        name: "verifyingContract",
+        type: "address",
+      });
+
+    // 3. Assemble full EIP-712 typed data structure.
+    const fullTypedData = {
+      types: { EIP712Domain: eip712DomainType, ...types },
+      primaryType,
+      domain,
+      message: value,
+    };
+
+    // 4. Serialize - handle BigInt values.
+    const json = JSON.stringify(fullTypedData, (_key, v) =>
+      typeof v === "bigint" ? v.toString() : (v as unknown),
+    );
+
+    // 5. Call OWS FFI. Chain is always "evm" for EVM signing.
+    const result = this.#ows.signTypedData(
+      this.#walletId,
+      "evm",
+      json,
+      this.#owsApiKey,
+    );
+
+    // 6. Concatenate r+s+v into 65-byte Ethereum signature.
+    const sig = result.signature.startsWith("0x")
+      ? result.signature.slice(2)
+      : result.signature;
+
+    // If OWS already returns r+s+v (130 hex chars), use as-is.
+    if (sig.length === 130) {
+      return `0x${sig}`;
+    }
+
+    // Otherwise it's r+s (128 hex chars), append v.
+    const v = (result.recoveryId ?? 0) + 27;
+    return `0x${sig}${v.toString(16).padStart(2, "0")}`;
+  }
+
+  /** Prevent wallet ID / key leakage in serialization. */
+  toJSON(): Record<string, string> {
+    return { address: this.#address, walletId: this.#walletId };
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return `OwsSigner { address: '${this.#address}', wallet: '${this.#walletId}' }`;
+  }
+}

package/src/signer.ts

@@ -0,0 +1,147 @@
+/**
+ * Signer interface and implementations.
+ *
+ * Three modes:
+ * 1. CLI signer (default): subprocess call to `pay sign`
+ * 2. Raw key: from PAYSKILL_KEY environment variable (dev/testing only)
+ * 3. Custom: user provides a sign(hash) -> signature callback
+ */
+
+import { execFileSync } from "node:child_process";
+import { type Hex } from "viem";
+import {
+  privateKeyToAccount,
+  sign as viemSign,
+  serializeSignature,
+} from "viem/accounts";
+
+/** Abstract signer interface. */
+export interface Signer {
+  /** Sign a 32-byte hash. Returns 65-byte signature (r || s || v). */
+  sign(hash: Uint8Array): Uint8Array;
+  /** The signer's Ethereum address (0x-prefixed, checksummed). */
+  readonly address: string;
+}
+
+/** Signs via the `pay sign` CLI subprocess. */
+export class CliSigner implements Signer {
+  private readonly command: string;
+  readonly address: string;
+
+  constructor(command = "pay", address = "") {
+    this.command = command;
+    if (address) {
+      this.address = address;
+    } else {
+      try {
+        this.address = execFileSync(this.command, ["address"], {
+          encoding: "utf-8",
+          timeout: 10_000,
+        }).trim();
+      } catch {
+        this.address = "";
+      }
+    }
+  }
+
+  sign(hash: Uint8Array): Uint8Array {
+    const hexHash = Buffer.from(hash).toString("hex");
+    const result = execFileSync(this.command, ["sign"], {
+      input: hexHash,
+      encoding: "utf-8",
+      timeout: 30_000,
+    });
+    return Buffer.from(result.trim(), "hex");
+  }
+}
+
+/** Signs with a raw private key using viem. Dev/testing only. */
+export class RawKeySigner implements Signer {
+  private readonly _key: Hex;
+  readonly address: string;
+
+  constructor(key?: string) {
+    const rawKey = key ?? process.env.PAYSKILL_KEY ?? "";
+    if (!rawKey) {
+      throw new Error("No key provided and PAYSKILL_KEY not set");
+    }
+    this._key = rawKey.startsWith("0x")
+      ? (rawKey as Hex)
+      : (`0x${rawKey}` as Hex);
+    const account = privateKeyToAccount(this._key);
+    this.address = account.address;
+  }
+
+  sign(_hash: Uint8Array): Uint8Array {
+    // viem's sign() does raw ECDSA signing (no EIP-191 prefix)
+    // sign() is async but Signer interface is sync — we use the sync internal
+    // For the sync interface, we need a workaround. Since RawKeySigner is
+    // dev/testing only, we'll do a sync computation via signSync.
+    // viem doesn't expose sync sign, but we can construct manually.
+    // Use the async path via signAsync helper pattern.
+    throw new Error(
+      "RawKeySigner.sign() is synchronous but viem signing is async. " +
+        "Use RawKeySigner.signAsync() or use buildAuthHeaders() directly with the private key."
+    );
+  }
+
+  /** Async sign — preferred over sync sign(). */
+  async signAsync(hash: Uint8Array): Promise<Uint8Array> {
+    const hashHex = ("0x" + Buffer.from(hash).toString("hex")) as Hex;
+    const raw = await viemSign({ hash: hashHex, privateKey: this._key });
+    const sigHex = serializeSignature(raw);
+    return hexToBytes(sigHex);
+  }
+}
+
+/** Delegates signing to a user-provided callback. */
+export class CallbackSigner implements Signer {
+  private readonly callback: (hash: Uint8Array) => Uint8Array;
+  readonly address: string;
+
+  constructor(
+    callback: (hash: Uint8Array) => Uint8Array,
+    address = ""
+  ) {
+    this.callback = callback;
+    this.address = address;
+  }
+
+  sign(hash: Uint8Array): Uint8Array {
+    return this.callback(hash);
+  }
+}
+
+/** Factory for creating signers. */
+export function createSigner(
+  mode: "cli" | "raw" | "custom" = "cli",
+  options: {
+    command?: string;
+    key?: string;
+    address?: string;
+    callback?: (hash: Uint8Array) => Uint8Array;
+  } = {}
+): Signer {
+  switch (mode) {
+    case "cli":
+      return new CliSigner(options.command, options.address);
+    case "raw":
+      return new RawKeySigner(options.key);
+    case "custom":
+      if (!options.callback) {
+        throw new Error("custom signer requires a callback");
+      }
+      return new CallbackSigner(options.callback, options.address);
+    default:
+      throw new Error(`Unknown signer mode: ${mode as string}`);
+  }
+}
+
+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;
+}