@pay-skill/sdk 0.1.1

package/tests/test_crypto.ts

@@ -0,0 +1,251 @@
+/**
+ * Crypto round-trip tests — proves that:
+ * 1. Address derivation uses real secp256k1 (not FNV hash)
+ * 2. EIP-712 signing produces valid signatures that the server can recover
+ * 3. buildAuthHeaders produces valid auth headers
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { privateKeyToAccount } from "viem/accounts";
+import { recoverAddress, type Hex, type Address } from "viem";
+
+import { PrivateKeySigner, Wallet } from "../src/wallet.js";
+import { RawKeySigner } from "../src/signer.js";
+import { buildAuthHeaders, computeEip712Hash } from "../src/auth.js";
+
+// Anvil account #0 — well-known test key
+const ANVIL_PK =
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" as Hex;
+const ANVIL_ADDRESS = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" as Address;
+
+const TEST_ROUTER = "0x5FbDB2315678afecb367f032d93F642f64180aa3" as Address;
+const TEST_CHAIN_ID = 8453;
+
+describe("Address derivation", () => {
+  it("derives correct address from Anvil #0 private key via Wallet", () => {
+    const wallet = new Wallet({
+      privateKey: ANVIL_PK,
+      chain: "8453",
+      apiUrl: "http://localhost:3000/api/v1",
+      routerAddress: TEST_ROUTER,
+    });
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("derives correct address via PrivateKeySigner", () => {
+    const signer = new PrivateKeySigner(ANVIL_PK);
+    assert.equal(signer.address, ANVIL_ADDRESS);
+  });
+
+  it("derives correct address via RawKeySigner", () => {
+    const signer = new RawKeySigner(ANVIL_PK);
+    assert.equal(signer.address, ANVIL_ADDRESS);
+  });
+
+  it("works without 0x prefix", () => {
+    const signer = new PrivateKeySigner(ANVIL_PK.slice(2));
+    assert.equal(signer.address, ANVIL_ADDRESS);
+  });
+});
+
+describe("EIP-712 signing round-trip", () => {
+  it("PrivateKeySigner produces recoverable EIP-712 signature", async () => {
+    const signer = new PrivateKeySigner(ANVIL_PK);
+
+    const domain = {
+      name: "pay",
+      version: "0.1",
+      chainId: BigInt(TEST_CHAIN_ID),
+      verifyingContract: TEST_ROUTER,
+    };
+    const types = {
+      APIRequest: [
+        { name: "method", type: "string" },
+        { name: "path", type: "string" },
+        { name: "timestamp", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+      ],
+    };
+    const nonce =
+      "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef";
+    const message = {
+      method: "POST",
+      path: "/api/v1/direct",
+      timestamp: BigInt(1741400000),
+      nonce,
+    };
+
+    const signature = await signer.signTypedData(domain, types, message);
+
+    assert.ok(signature.startsWith("0x"), "signature should be hex");
+    assert.equal(signature.length, 132, "signature should be 65 bytes hex");
+    assert.notEqual(
+      signature,
+      "0x" + "0".repeat(130),
+      "signature must not be zeros (stub)"
+    );
+
+    // Recover the signer address from the signature
+    const recovered = await recoverAddress({
+      hash: (await import("viem")).hashTypedData({
+        domain,
+        types,
+        primaryType: "APIRequest",
+        message,
+      }),
+      signature: signature as Hex,
+    });
+
+    assert.equal(
+      recovered.toLowerCase(),
+      ANVIL_ADDRESS.toLowerCase(),
+      "recovered address must match signer"
+    );
+  });
+});
+
+describe("buildAuthHeaders", () => {
+  it("produces valid auth headers with correct address", async () => {
+    const headers = await buildAuthHeaders(ANVIL_PK, "POST", "/api/v1/direct", {
+      chainId: TEST_CHAIN_ID,
+      routerAddress: TEST_ROUTER,
+    });
+
+    assert.equal(headers["X-Pay-Agent"], ANVIL_ADDRESS);
+    assert.ok(
+      headers["X-Pay-Signature"].startsWith("0x"),
+      "signature should be hex"
+    );
+    assert.equal(
+      headers["X-Pay-Signature"].length,
+      132,
+      "signature should be 65 bytes"
+    );
+    assert.ok(
+      Number(headers["X-Pay-Timestamp"]) > 0,
+      "timestamp should be positive"
+    );
+    assert.ok(
+      headers["X-Pay-Nonce"].startsWith("0x"),
+      "nonce should be hex"
+    );
+    assert.equal(
+      headers["X-Pay-Nonce"].length,
+      66,
+      "nonce should be 32 bytes hex"
+    );
+  });
+
+  it("signature recovers to the correct address", async () => {
+    const headers = await buildAuthHeaders(ANVIL_PK, "POST", "/api/v1/direct", {
+      chainId: TEST_CHAIN_ID,
+      routerAddress: TEST_ROUTER,
+    });
+
+    // Recompute the hash and recover
+    const { hashTypedData } = await import("viem");
+    const hash = hashTypedData({
+      domain: {
+        name: "pay",
+        version: "0.1",
+        chainId: TEST_CHAIN_ID,
+        verifyingContract: TEST_ROUTER,
+      },
+      types: {
+        APIRequest: [
+          { name: "method", type: "string" },
+          { name: "path", type: "string" },
+          { name: "timestamp", type: "uint256" },
+          { name: "nonce", type: "bytes32" },
+        ],
+      },
+      primaryType: "APIRequest",
+      message: {
+        method: "POST",
+        path: "/api/v1/direct",
+        timestamp: BigInt(headers["X-Pay-Timestamp"]),
+        nonce: headers["X-Pay-Nonce"] as Hex,
+      },
+    });
+
+    const recovered = await recoverAddress({
+      hash,
+      signature: headers["X-Pay-Signature"] as Hex,
+    });
+
+    assert.equal(
+      recovered.toLowerCase(),
+      ANVIL_ADDRESS.toLowerCase(),
+      "recovered address must match signer"
+    );
+  });
+});
+
+describe("computeEip712Hash", () => {
+  it("produces deterministic output", () => {
+    const nonce =
+      "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" as Hex;
+    const h1 = computeEip712Hash(
+      "POST",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      TEST_CHAIN_ID,
+      TEST_ROUTER
+    );
+    const h2 = computeEip712Hash(
+      "POST",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      TEST_CHAIN_ID,
+      TEST_ROUTER
+    );
+    assert.deepEqual(h1, h2);
+  });
+
+  it("different methods produce different hashes", () => {
+    const nonce =
+      "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" as Hex;
+    const h1 = computeEip712Hash(
+      "POST",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      TEST_CHAIN_ID,
+      TEST_ROUTER
+    );
+    const h2 = computeEip712Hash(
+      "GET",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      TEST_CHAIN_ID,
+      TEST_ROUTER
+    );
+    assert.notDeepEqual(h1, h2);
+  });
+
+  it("different chain IDs produce different hashes", () => {
+    const nonce =
+      "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef" as Hex;
+    const h1 = computeEip712Hash(
+      "POST",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      8453,
+      TEST_ROUTER
+    );
+    const h2 = computeEip712Hash(
+      "POST",
+      "/api/v1/direct",
+      BigInt(1741400000),
+      nonce,
+      84531,
+      TEST_ROUTER
+    );
+    assert.notDeepEqual(h1, h2);
+  });
+});

package/tests/test_e2e.ts

@@ -0,0 +1,158 @@
+/**
+ * E2E acceptance tests — run against live testnet.
+ *
+ * Skip unless PAYSKILL_TESTNET_KEY is set. These hit the real testnet server
+ * and exercise the full SDK → server round-trip with REAL authentication.
+ *
+ * Usage:
+ *   PAYSKILL_TESTNET_KEY=0xdead... \
+ *   PAYSKILL_TESTNET_URL=http://204.168.133.111:3001/api/v1 \
+ *   node --import tsx --test tests/test_e2e.ts
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+
+import { PayClient, PayValidationError, PayServerError, buildAuthHeaders } from "../src/index.js";
+import type { WebhookRegistration, AuthHeaders } from "../src/index.js";
+import type { Hex } from "viem";
+
+const TESTNET_URL =
+  process.env.PAYSKILL_TESTNET_URL ?? "http://204.168.133.111:3001/api/v1";
+const TESTNET_KEY = process.env.PAYSKILL_TESTNET_KEY ?? "";
+
+// Testnet contract addresses (Base Sepolia)
+const CHAIN_ID = 84532;
+const ROUTER_ADDRESS = "0xE0Aa45e6937F3b9Fc0BEe457361885Cb9bfC067F";
+
+const skip = !TESTNET_KEY;
+
+function makeClient(): PayClient {
+  return new PayClient({
+    apiUrl: TESTNET_URL,
+    privateKey: TESTNET_KEY,
+    chainId: CHAIN_ID,
+    routerAddress: ROUTER_ADDRESS,
+  });
+}
+
+// ── Auth Verification ──────────────────────────────────────────────
+
+describe("E2E: Auth works with real signing", { skip }, () => {
+  let client: PayClient;
+
+  before(() => {
+    client = makeClient();
+  });
+
+  it("status endpoint returns valid response with real auth", async () => {
+    const status = await client.getStatus();
+    assert.ok(typeof status.address === "string");
+    assert.ok(status.address.startsWith("0x"));
+    assert.ok(typeof status.balance === "number");
+    assert.ok(status.balance >= 0);
+    assert.ok(Array.isArray(status.openTabs));
+  });
+
+  it("rejects request without auth headers (raw fetch)", async () => {
+    const resp = await fetch(`${TESTNET_URL}/status`);
+    assert.equal(resp.status, 400, "should reject unauthenticated request");
+    const body = (await resp.json()) as { error: string };
+    assert.equal(body.error, "auth_missing");
+  });
+});
+
+// ── Mint (Testnet Faucet) ──────────────────────────────────────────
+
+describe("E2E: Mint testnet USDC", { skip }, () => {
+  let client: PayClient;
+
+  before(() => {
+    client = makeClient();
+  });
+
+  it("mints $10 USDC to the authenticated wallet", async () => {
+    const headers = await buildAuthHeaders(
+      TESTNET_KEY as Hex,
+      "POST",
+      "/api/v1/mint",
+      { chainId: CHAIN_ID, routerAddress: ROUTER_ADDRESS }
+    );
+    const resp = await fetch(`${TESTNET_URL}/mint`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...headers },
+      body: JSON.stringify({ amount: 10_000_000 }),
+    });
+    const bodyText = await resp.text();
+    assert.equal(resp.status, 200, `mint failed: ${bodyText}`);
+    const body = JSON.parse(bodyText) as { tx_hash: string; amount: number; to: string };
+    assert.ok(body.tx_hash, "should return a tx_hash");
+    assert.equal(body.amount, 10_000_000);
+    assert.ok(body.to.startsWith("0x"));
+  });
+});
+
+// ── Webhook CRUD ───────────────────────────────────────────────────
+
+describe("E2E: Webhook CRUD with real auth", { skip }, () => {
+  let client: PayClient;
+  let whId = "";
+
+  before(() => {
+    client = makeClient();
+  });
+
+  it("registers a webhook", async () => {
+    const slug = randomUUID().slice(0, 8);
+    const wh = await client.registerWebhook(
+      `https://example.com/hook/${slug}`,
+      {
+        events: ["payment.completed"],
+        secret: `whsec_test_${slug}`,
+      }
+    );
+    assert.ok(wh.webhookId);
+    assert.ok(wh.url.startsWith("https://"));
+    assert.ok(wh.events.includes("payment.completed"));
+    whId = wh.webhookId;
+  });
+
+  it("lists webhooks including the new one", async () => {
+    const webhooks = await client.listWebhooks();
+    assert.ok(Array.isArray(webhooks));
+    const ids = webhooks.map((w: WebhookRegistration) => w.webhookId);
+    assert.ok(ids.includes(whId));
+  });
+
+  it("deletes the webhook", async () => {
+    await client.deleteWebhook(whId);
+    const webhooks = await client.listWebhooks();
+    const ids = webhooks.map((w: WebhookRegistration) => w.webhookId);
+    assert.ok(!ids.includes(whId));
+  });
+});
+
+// ── Client-side validation still works ─────────────────────────────
+
+describe("E2E: Client validation", { skip }, () => {
+  let client: PayClient;
+
+  before(() => {
+    client = makeClient();
+  });
+
+  it("rejects invalid address", async () => {
+    await assert.rejects(
+      () => client.payDirect("not-an-address", 1_000_000),
+      (err: unknown) => err instanceof PayValidationError
+    );
+  });
+
+  it("rejects amount below minimum", async () => {
+    await assert.rejects(
+      () => client.payDirect("0x" + "a1".repeat(20), 500_000),
+      (err: unknown) => err instanceof PayValidationError
+    );
+  });
+});

package/tests/test_errors.ts

@@ -0,0 +1,36 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  PayError,
+  PayValidationError,
+  PayNetworkError,
+  PayServerError,
+  PayInsufficientFundsError,
+} from "../src/errors.js";
+
+describe("error hierarchy", () => {
+  it("all errors extend PayError", () => {
+    assert.ok(new PayValidationError("x") instanceof PayError);
+    assert.ok(new PayNetworkError("x") instanceof PayError);
+    assert.ok(new PayServerError("x", 400) instanceof PayError);
+    assert.ok(new PayInsufficientFundsError() instanceof PayError);
+  });
+
+  it("PayValidationError has field and code", () => {
+    const err = new PayValidationError("bad input", "amount");
+    assert.equal(err.code, "validation_error");
+    assert.equal(err.field, "amount");
+    assert.equal(err.message, "bad input");
+  });
+
+  it("PayServerError has statusCode", () => {
+    const err = new PayServerError("not found", 404);
+    assert.equal(err.statusCode, 404);
+    assert.equal(err.code, "server_error");
+  });
+
+  it("PayNetworkError has code", () => {
+    const err = new PayNetworkError("connection refused");
+    assert.equal(err.code, "network_error");
+  });
+});

package/tests/test_ows_integration.ts

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