@pay-skill/sdk 0.1.8 → 0.2.0

package/tests/test_e2e.ts

@@ -1,158 +1,99 @@
-/**
- * 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
-    );
-  });
-});
+/**
+ * E2E acceptance tests — run against live testnet.
+ *
+ * Skip unless PAYSKILL_TESTNET_KEY is set.
+ *
+ * Usage:
+ *   PAYSKILL_TESTNET_KEY=0xdead... 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 { Wallet, PayValidationError } from "../src/index.js";
+
+const TESTNET_KEY = process.env.PAYSKILL_TESTNET_KEY ?? "";
+const skip = !TESTNET_KEY;
+
+function makeWallet(): Wallet {
+  return new Wallet({ privateKey: TESTNET_KEY, testnet: true });
+}
+
+describe("E2E: Status + Balance", { skip }, () => {
+  let wallet: Wallet;
+  before(() => { wallet = makeWallet(); });
+
+  it("status returns valid response", async () => {
+    const status = await wallet.status();
+    assert.ok(status.address.startsWith("0x"));
+    assert.ok(status.balance.total >= 0);
+    assert.ok(typeof status.openTabs === "number");
+  });
+
+  it("balance returns total/locked/available", async () => {
+    const bal = await wallet.balance();
+    assert.ok(typeof bal.total === "number");
+    assert.ok(typeof bal.locked === "number");
+    assert.ok(typeof bal.available === "number");
+    assert.ok(bal.available <= bal.total);
+  });
+});
+
+describe("E2E: Mint testnet USDC", { skip }, () => {
+  let wallet: Wallet;
+  before(() => { wallet = makeWallet(); });
+
+  it("mints $10 USDC", async () => {
+    const result = await wallet.mint(10);
+    assert.ok(result.txHash);
+    assert.equal(result.amount, 10);
+  });
+});
+
+describe("E2E: Webhook CRUD", { skip }, () => {
+  let wallet: Wallet;
+  let hookId = "";
+  before(() => { wallet = makeWallet(); });
+
+  it("registers a webhook", async () => {
+    const slug = randomUUID().slice(0, 8);
+    const wh = await wallet.registerWebhook(
+      `https://example.com/hook/${slug}`,
+      ["payment.completed"],
+      `whsec_test_${slug}`,
+    );
+    assert.ok(wh.id);
+    assert.ok(wh.url.startsWith("https://"));
+    hookId = wh.id;
+  });
+
+  it("lists webhooks", async () => {
+    const hooks = await wallet.listWebhooks();
+    assert.ok(hooks.some((h) => h.id === hookId));
+  });
+
+  it("deletes the webhook", async () => {
+    await wallet.deleteWebhook(hookId);
+    const hooks = await wallet.listWebhooks();
+    assert.ok(!hooks.some((h) => h.id === hookId));
+  });
+});
+
+describe("E2E: Validation still works", { skip }, () => {
+  let wallet: Wallet;
+  before(() => { wallet = makeWallet(); });
+
+  it("rejects invalid address", async () => {
+    await assert.rejects(
+      () => wallet.send("not-an-address", 5),
+      PayValidationError,
+    );
+  });
+
+  it("rejects amount below minimum", async () => {
+    await assert.rejects(
+      () => wallet.send("0x" + "a1".repeat(20), 0.5),
+      PayValidationError,
+    );
+  });
+});

package/tests/test_errors.ts

@@ -1,36 +1,44 @@
-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");
-  });
-});
+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("x") 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");
+  });
+
+  it("PayInsufficientFundsError includes fund link hint", () => {
+    const err = new PayInsufficientFundsError("low balance", 5, 10);
+    assert.ok(err.message.includes("createFundLink"));
+    assert.equal(err.balance, 5);
+    assert.equal(err.required, 10);
+    assert.equal(err.code, "insufficient_funds");
+  });
+});

package/tests/test_ows.ts

@@ -0,0 +1,153 @@
+/**
+ * OWS (Open Wallet Standard) integration tests.
+ * Uses a mock OWS module — no real @open-wallet-standard/core needed.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { Wallet, PayError } from "../src/index.js";
+
+// ── Mock OWS module ──────────────────────────────────────────────────
+
+interface SignCall {
+  wallet: string;
+  chain: string;
+  json: string;
+  passphrase?: string;
+}
+
+function createMockOws(options?: {
+  accounts?: Array<{
+    chainId: string;
+    address: string;
+    derivationPath: string;
+  }>;
+  signature?: string;
+  recoveryId?: number;
+}) {
+  const calls: SignCall[] = [];
+  const accounts = options?.accounts ?? [
+    {
+      chainId: "eip155:8453",
+      address: "0x1234567890abcdef1234567890abcdef12345678",
+      derivationPath: "m/44'/60'/0'/0/0",
+    },
+  ];
+
+  // Default: 65-byte hex sig (r+s+v)
+  const sig = options?.signature ?? "ab".repeat(64) + "1b";
+
+  return {
+    calls,
+    getWallet(nameOrId: string) {
+      return {
+        id: `id-${nameOrId}`,
+        name: nameOrId,
+        accounts,
+        createdAt: "2026-04-01T00:00:00Z",
+      };
+    },
+    signTypedData(
+      wallet: string,
+      chain: string,
+      typedDataJson: string,
+      passphrase?: string,
+    ) {
+      calls.push({ wallet, chain, json: typedDataJson, passphrase });
+      return {
+        signature: sig,
+        recoveryId: options?.recoveryId,
+      };
+    },
+  };
+}
+
+// ── Construction ──────────────────────────────────────────────────────
+
+describe("Wallet.fromOws construction", () => {
+  it("creates wallet with correct address from mock OWS", async () => {
+    const ows = createMockOws();
+    const wallet = await Wallet.fromOws({
+      walletId: "test-agent",
+      _owsModule: ows,
+    });
+    assert.equal(
+      wallet.address,
+      "0x1234567890abcdef1234567890abcdef12345678",
+    );
+  });
+
+  it("finds evm chain account", async () => {
+    const ows = createMockOws({
+      accounts: [
+        {
+          chainId: "evm",
+          address: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          derivationPath: "m/44'/60'/0'/0/0",
+        },
+      ],
+    });
+    const wallet = await Wallet.fromOws({
+      walletId: "test",
+      _owsModule: ows,
+    });
+    assert.equal(
+      wallet.address,
+      "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    );
+  });
+
+  it("throws when no EVM account found", async () => {
+    const ows = createMockOws({
+      accounts: [
+        {
+          chainId: "solana",
+          address: "SoLaNa...",
+          derivationPath: "m/44'/501'/0'",
+        },
+      ],
+    });
+    await assert.rejects(
+      () => Wallet.fromOws({ walletId: "test", _owsModule: ows }),
+      PayError,
+    );
+  });
+
+  it("throws when OWS module not installed (no mock)", async () => {
+    await assert.rejects(
+      () =>
+        Wallet.fromOws({
+          walletId: "test",
+          // _owsModule not provided -> tries dynamic import, fails
+        }),
+      PayError,
+    );
+  });
+
+  it("passes owsApiKey to signTypedData", async () => {
+    const ows = createMockOws();
+    const wallet = await Wallet.fromOws({
+      walletId: "agent-1",
+      owsApiKey: "secret-key",
+      _owsModule: ows,
+    });
+    // Trigger a signing call (will fail on network but the mock captures the call)
+    // We can't easily trigger signing without a server, so just verify construction
+    assert.equal(wallet.address, "0x1234567890abcdef1234567890abcdef12345678");
+  });
+});
+
+// ── Serialization safety ──────────────────────────────────────────────
+
+describe("Wallet.fromOws does not leak keys", () => {
+  it("JSON.stringify does not expose private fields", async () => {
+    const ows = createMockOws();
+    const wallet = await Wallet.fromOws({
+      walletId: "secret-agent",
+      _owsModule: ows,
+    });
+    const json = JSON.stringify(wallet);
+    assert.ok(!json.includes("secret-agent"));
+    assert.ok(!json.includes("signTypedData"));
+  });
+});

package/tests/test_wallet.ts

@@ -0,0 +1,194 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import type { Hex } from "viem";
+import { Wallet, PayError, PayValidationError } from "../src/index.js";
+
+// Anvil account #0 — well-known test key
+const ANVIL_PK =
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+const ANVIL_ADDRESS = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266";
+const VALID_ADDR = "0x" + "a1".repeat(20);
+
+// Save/restore env for tests that modify it
+let savedEnv: Record<string, string | undefined>;
+
+function saveEnv() {
+  savedEnv = {
+    PAYSKILL_KEY: process.env.PAYSKILL_KEY,
+    PAYSKILL_TESTNET: process.env.PAYSKILL_TESTNET,
+    PAYSKILL_API_URL: process.env.PAYSKILL_API_URL,
+  };
+}
+
+function restoreEnv() {
+  for (const [k, v] of Object.entries(savedEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+}
+
+// ── Construction ──────────────────────────────────────────────────────
+
+describe("Wallet construction", () => {
+  beforeEach(saveEnv);
+  afterEach(restoreEnv);
+
+  it("constructs with explicit private key", () => {
+    const wallet = new Wallet({ privateKey: ANVIL_PK });
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("constructs without 0x prefix", () => {
+    const wallet = new Wallet({ privateKey: ANVIL_PK.slice(2) });
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("constructs from PAYSKILL_KEY env var", () => {
+    process.env.PAYSKILL_KEY = ANVIL_PK;
+    const wallet = new Wallet();
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("throws without key", () => {
+    delete process.env.PAYSKILL_KEY;
+    assert.throws(() => new Wallet(), PayError);
+  });
+
+  it("throws on invalid key (too short)", () => {
+    assert.throws(
+      () => new Wallet({ privateKey: "0xdead" }),
+      PayValidationError,
+    );
+  });
+
+  it("throws on invalid key (non-hex)", () => {
+    assert.throws(
+      () => new Wallet({ privateKey: "0x" + "zz".repeat(32) }),
+      PayValidationError,
+    );
+  });
+
+  it("Wallet.fromEnv reads PAYSKILL_KEY", () => {
+    process.env.PAYSKILL_KEY = ANVIL_PK;
+    const wallet = Wallet.fromEnv();
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("Wallet.fromEnv throws without env var", () => {
+    delete process.env.PAYSKILL_KEY;
+    assert.throws(() => Wallet.fromEnv(), PayError);
+  });
+
+  it("Wallet.create falls back to env var when keychain unavailable", async () => {
+    process.env.PAYSKILL_KEY = ANVIL_PK;
+    const wallet = await Wallet.create();
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("respects testnet option", () => {
+    process.env.PAYSKILL_KEY = ANVIL_PK;
+    // Just verify it doesn't throw — testnet flag affects API URL only
+    const wallet = new Wallet({ testnet: true });
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+
+  it("respects PAYSKILL_TESTNET env var", () => {
+    process.env.PAYSKILL_KEY = ANVIL_PK;
+    process.env.PAYSKILL_TESTNET = "1";
+    const wallet = new Wallet();
+    assert.equal(wallet.address, ANVIL_ADDRESS);
+  });
+});
+
+// ── Validation ──────────────────────────────────────────────────────
+
+describe("Wallet input validation", () => {
+  let wallet: Wallet;
+
+  beforeEach(() => {
+    wallet = new Wallet({ privateKey: ANVIL_PK });
+  });
+
+  it("send rejects invalid address", async () => {
+    await assert.rejects(
+      () => wallet.send("not-an-address", 5),
+      PayValidationError,
+    );
+  });
+
+  it("send rejects amount below $1 minimum", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, 0.5),
+      PayValidationError,
+    );
+  });
+
+  it("send rejects negative amount", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, -5),
+      PayValidationError,
+    );
+  });
+
+  it("send rejects NaN", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, NaN),
+      PayValidationError,
+    );
+  });
+
+  it("send rejects Infinity", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, Infinity),
+      PayValidationError,
+    );
+  });
+
+  it("openTab rejects amount below $5 minimum", async () => {
+    await assert.rejects(
+      () => wallet.openTab(VALID_ADDR, 3, 1),
+      PayValidationError,
+    );
+  });
+
+  it("openTab rejects zero maxChargePerCall", async () => {
+    await assert.rejects(
+      () => wallet.openTab(VALID_ADDR, 10, 0),
+      PayValidationError,
+    );
+  });
+
+  it("openTab rejects invalid provider address", async () => {
+    await assert.rejects(
+      () => wallet.openTab("bad-addr", 10, 1),
+      PayValidationError,
+    );
+  });
+
+  it("mint rejects on mainnet", async () => {
+    await assert.rejects(() => wallet.mint(10), PayError);
+  });
+
+  it("micro amount conversion works", async () => {
+    // $5 micro amount should not fail validation for tab (need network for full test)
+    await assert.rejects(
+      () => wallet.openTab(VALID_ADDR, { micro: 5_000_000 }, { micro: 100_000 }),
+      // Will fail on network (can't reach server), not validation
+      (err: Error) => !(err instanceof PayValidationError),
+    );
+  });
+
+  it("micro amount rejects negative", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, { micro: -1 }),
+      PayValidationError,
+    );
+  });
+
+  it("micro amount rejects non-integer", async () => {
+    await assert.rejects(
+      () => wallet.send(VALID_ADDR, { micro: 1.5 }),
+      PayValidationError,
+    );
+  });
+});