@pay-skill/sdk 0.1.7 → 0.1.10

package/src/models.ts

@@ -1,77 +0,0 @@
-/** 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

@@ -1,223 +0,0 @@
-/**
- * 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

@@ -1,147 +0,0 @@
-/**
- * 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;
-}

package/tests/test_ows_integration.ts

@@ -1,92 +0,0 @@
-/**
- * OWS Signer integration test.
- *
- * Requires real @open-wallet-standard/core installed with native binaries.
- * Auto-skips if OWS is not available — safe to run in CI without OWS.
- *
- * Tests:
- * - Creating a real OWS wallet
- * - Constructing OwsSigner from it
- * - Signing EIP-712 Permit typed data
- * - Verifying signature recovers to correct address (ecrecover round-trip)
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-
-// Check if OWS is available before running tests
-let owsAvailable = false;
-try {
-  const ows = await import("@open-wallet-standard/core");
-  ows.listWallets();
-  owsAvailable = true;
-} catch {
-  // OWS not installed — tests will be skipped
-}
-
-describe("OwsSigner integration (real OWS)", { skip: !owsAvailable }, () => {
-  it("creates signer from real OWS wallet and signs EIP-712 data", async () => {
-    const { OwsSigner } = await import("../src/ows-signer.js");
-    const { verifyTypedData } = await import("viem");
-
-    // Import OWS module
-    const ows = await import("@open-wallet-standard/core");
-
-    // Create a test wallet (unique name to avoid collisions)
-    const walletName = `pay-test-${Date.now()}`;
-    const walletInfo = ows.createWallet(walletName);
-    const evmAccount = walletInfo.accounts.find(
-      (a: { chainId: string }) =>
-        a.chainId === "evm" || a.chainId.startsWith("eip155:"),
-    );
-    assert.ok(evmAccount, "OWS wallet must have an EVM account");
-
-    // Create OwsSigner from the real wallet
-    const signer = await OwsSigner.create({ walletId: walletName });
-    assert.equal(
-      signer.address.toLowerCase(),
-      evmAccount.address.toLowerCase(),
-    );
-
-    // Sign an EIP-712 Permit (the most common signing operation in Pay)
-    const domain = {
-      name: "USD Coin",
-      version: "2",
-      chainId: 84532,
-      verifyingContract:
-        "0x036CbD53842c5426634e7929541eC2318f3dCF7e" as `0x${string}`,
-    };
-    const types = {
-      Permit: [
-        { name: "owner", type: "address" },
-        { name: "spender", type: "address" },
-        { name: "value", type: "uint256" },
-        { name: "nonce", type: "uint256" },
-        { name: "deadline", type: "uint256" },
-      ],
-    };
-    const message = {
-      owner: signer.address,
-      spender: "0x0000000000000000000000000000000000000001",
-      value: "5000000",
-      nonce: "0",
-      deadline: "999999999999",
-    };
-
-    const signature = await signer.signTypedData(domain, types, message);
-
-    // Verify the signature recovers to the signer's address
-    assert.ok(signature.startsWith("0x"), "signature must be 0x-prefixed");
-    assert.equal(signature.length, 132, "signature must be 65 bytes (132 hex)");
-
-    const valid = await verifyTypedData({
-      address: signer.address as `0x${string}`,
-      domain,
-      types,
-      primaryType: "Permit",
-      message: message as Record<string, unknown>,
-      signature: signature as `0x${string}`,
-    });
-    assert.ok(valid, "ecrecover must recover signer address");
-  });
-});