@remitmd/sdk 0.1.0

package/tests/acceptance/tab.test.ts

@@ -0,0 +1,108 @@
+/**
+ * SDK acceptance: Tab lifecycle via wallet.openTab(), chargeTab(), closeTab().
+ * Verifies SDK permit signing + tab charge signing + full lifecycle balances.
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import type { Wallet } from "../../src/wallet.js";
+import {
+  createWallet,
+  fundWallet,
+  getUsdcBalance,
+  getFeeWalletBalance,
+  assertBalanceChange,
+  waitForBalanceChange,
+} from "./setup.js";
+
+describe("SDK: Tab Lifecycle", { timeout: 180_000 }, () => {
+  let agent: Wallet;
+  let provider: Wallet;
+
+  before(async () => {
+    agent = await createWallet();
+    provider = await createWallet();
+    await fundWallet(agent, 100);
+  });
+
+  it("openTab → chargeTab → closeTab with correct balances", async () => {
+    const limit = 10.0;
+    const chargeAmount = 2.0;
+    const chargeUnits = BigInt(Math.round(chargeAmount * 1e6));
+    const fee = chargeAmount * 0.01; // 1% = $0.02
+    const providerReceives = chargeAmount - fee; // $1.98
+
+    const agentBefore = await getUsdcBalance(agent.address);
+    const providerBefore = await getUsdcBalance(provider.address);
+    const feeBefore = await getFeeWalletBalance();
+
+    // Step 1: Open tab (agent, with permit for Tab contract)
+    const contracts = await agent.getContracts();
+    const permit = await agent.signPermit(contracts.tab, limit + 1);
+
+    const tab = await agent.openTab({
+      to: provider.address,
+      limit,
+      perUnit: 0.1,
+      permit,
+    });
+
+    assert.ok(tab.id, "tab should have an id");
+
+    // Wait for on-chain lock (agent USDC moves to Tab contract)
+    await waitForBalanceChange(agent.address, agentBefore);
+
+    // Step 2: Provider charges $2 (off-chain with TabCharge EIP-712 sig)
+    const callCount = 1;
+    const chargeSig = await provider.signTabCharge(
+      contracts.tab,
+      tab.id,
+      chargeUnits,
+      callCount,
+    );
+
+    const charge = await provider.chargeTab(tab.id, {
+      amount: chargeAmount,
+      cumulative: chargeAmount,
+      callCount,
+      providerSig: chargeSig,
+    });
+
+    const chargeTabId = charge.tabId ?? (charge as unknown as Record<string, string>).tab_id;
+    assert.equal(chargeTabId, tab.id, "charge should reference the tab");
+
+    // Step 3: Close tab (agent, with provider's close signature on final state)
+    const closeSig = await provider.signTabCharge(
+      contracts.tab,
+      tab.id,
+      chargeUnits,
+      callCount,
+    );
+
+    const closed = await agent.closeTab(tab.id, {
+      finalAmount: chargeAmount,
+      providerSig: closeSig,
+    });
+
+    const closedStatus = closed.status ?? (closed as unknown as Record<string, string>).status;
+    assert.equal(closedStatus, "closed", "tab should be closed");
+
+    const closedTxHash =
+      closed.txHash ??
+      (closed as unknown as Record<string, string>).closedTxHash ??
+      (closed as unknown as Record<string, string>).closed_tx_hash;
+    assert.ok(closedTxHash?.startsWith("0x"), `close should return tx hash, got: ${closedTxHash}`);
+
+    // Verify balances
+    const providerAfter = await waitForBalanceChange(provider.address, providerBefore);
+    const feeAfter = await getFeeWalletBalance();
+    const agentAfter = await getUsdcBalance(agent.address);
+
+    // Agent: locked $10, refunded $8, net change = -$2
+    assertBalanceChange("agent", agentBefore, agentAfter, -chargeAmount);
+    // Provider: received $2 minus 1% fee = $1.98
+    assertBalanceChange("provider", providerBefore, providerAfter, providerReceives);
+    // Fee wallet: received 1% of $2 = $0.02
+    assertBalanceChange("fee wallet", feeBefore, feeAfter, fee);
+  });
+});

package/tests/acceptance/x402.test.ts

@@ -0,0 +1,140 @@
+/**
+ * SDK acceptance: x402 auto-payment via wallet.x402Fetch().
+ *
+ * Spins up a local test server that returns 402 with a PAYMENT-REQUIRED header.
+ * The SDK's x402Fetch() auto-signs EIP-3009 and retries with PAYMENT-SIGNATURE.
+ * We verify the payment signature is structurally valid and the retry succeeds.
+ *
+ * On-chain settlement is tested separately in the API acceptance tests (C2).
+ * This test focuses on the SDK client-side flow: 402 detection → EIP-3009 signing → retry.
+ */
+
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { createServer, type Server } from "node:http";
+import type { Wallet } from "../../src/wallet.js";
+import { createWallet, fundWallet, API_URL } from "./setup.js";
+
+describe("SDK: x402 Auto-Payment", { timeout: 120_000 }, () => {
+  let agent: Wallet;
+  let server: Server;
+  let serverUrl: string;
+
+  /** Fetch contracts to get USDC + Router addresses for the paywall header. */
+  async function getContractAddrs(): Promise<{ usdc: string; router: string }> {
+    const res = await fetch(`${API_URL}/contracts`);
+    const data = (await res.json()) as { usdc: string; router: string };
+    return data;
+  }
+
+  before(async () => {
+    agent = await createWallet();
+    await fundWallet(agent, 100);
+
+    const contracts = await getContractAddrs();
+
+    // Create a local x402 paywall server
+    server = createServer((req, res) => {
+      const paymentSig = req.headers["payment-signature"];
+
+      if (!paymentSig) {
+        // First request: return 402 with payment requirements
+        const paymentRequired = {
+          scheme: "exact",
+          network: "eip155:84532",
+          amount: "100000", // $0.10 USDC (within default maxAutoPayUsdc)
+          asset: contracts.usdc,
+          payTo: contracts.router,
+          maxTimeoutSeconds: 60,
+          resource: "/test-resource",
+          description: "x402 acceptance test",
+          mimeType: "text/plain",
+        };
+        const encoded = Buffer.from(JSON.stringify(paymentRequired)).toString("base64");
+        res.writeHead(402, {
+          "Content-Type": "text/plain",
+          "payment-required": encoded,
+        });
+        res.end("Payment Required");
+        return;
+      }
+
+      // Second request: has PAYMENT-SIGNATURE — validate structure then return 200
+      try {
+        const decoded = JSON.parse(
+          Buffer.from(paymentSig as string, "base64").toString("utf8"),
+        ) as {
+          scheme: string;
+          network: string;
+          x402Version: number;
+          payload: {
+            signature: string;
+            authorization: {
+              from: string;
+              to: string;
+              value: string;
+              validAfter: string;
+              validBefore: string;
+              nonce: string;
+            };
+          };
+        };
+
+        // Validate payment structure
+        if (decoded.scheme !== "exact") throw new Error("wrong scheme");
+        if (decoded.network !== "eip155:84532") throw new Error("wrong network");
+        if (!decoded.payload.signature.startsWith("0x")) throw new Error("bad signature");
+        if (decoded.payload.authorization.from.toLowerCase() !== agent.address.toLowerCase()) {
+          throw new Error("wrong payer");
+        }
+        if (decoded.payload.authorization.value !== "100000") throw new Error("wrong amount");
+
+        res.writeHead(200, { "Content-Type": "text/plain" });
+        res.end("paid content");
+      } catch (e) {
+        res.writeHead(400);
+        res.end(`Invalid payment: ${(e as Error).message}`);
+      }
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address() as { port: number };
+        serverUrl = `http://127.0.0.1:${addr.port}`;
+        resolve();
+      });
+    });
+  });
+
+  after(() => {
+    server?.close();
+  });
+
+  it("x402Fetch auto-pays 402 and returns 200 with content", async () => {
+    const { response, lastPayment } = await agent.x402Fetch(`${serverUrl}/test-resource`);
+
+    assert.equal(response.status, 200, "should get 200 after auto-payment");
+    const body = await response.text();
+    assert.equal(body, "paid content", "should receive paid content");
+
+    // Verify lastPayment metadata (V2 fields)
+    assert.ok(lastPayment, "lastPayment should be set");
+    assert.equal(lastPayment.scheme, "exact");
+    assert.equal(lastPayment.amount, "100000");
+    assert.equal(lastPayment.resource, "/test-resource");
+    assert.equal(lastPayment.description, "x402 acceptance test");
+    assert.equal(lastPayment.mimeType, "text/plain");
+  });
+
+  it("x402Fetch rejects payment above maxAutoPayUsdc", async () => {
+    // The default limit is $0.10, and the paywall asks for $0.10 — right at the edge.
+    // Test with a lower limit ($0.01) to verify rejection.
+    await assert.rejects(
+      () => agent.x402Fetch(`${serverUrl}/test-resource`, 0.01),
+      (err: Error) => {
+        assert.ok(err.message.includes("exceeds auto-pay limit"), `wrong error: ${err.message}`);
+        return true;
+      },
+    );
+  });
+});

package/tests/compliance/auth.ts

@@ -0,0 +1,69 @@
+/**
+ * Compliance: EIP-712 authentication against a real server.
+ *
+ * Proves the TypeScript SDK can authenticate — 200 responses, not 401s.
+ * Requires the compliance server to be running (docker-compose.compliance.yml).
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  SERVER_URL,
+  ROUTER_ADDRESS,
+  serverIsReachable,
+  makeWallet,
+} from "./helpers.js";
+
+let skip = false;
+
+before(async () => {
+  skip = !(await serverIsReachable());
+  if (skip) {
+    console.warn(
+      `[compliance] Server not reachable at ${SERVER_URL}. Skipping auth tests.`,
+    );
+  }
+});
+
+describe("TypeScript compliance: authentication", () => {
+  it("authenticated GET /status returns 200", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const wallet = await makeWallet();
+    // status() uses #auth.get — if EIP-712 is wrong this returns 401 not 200.
+    // Server returns { wallet, tier, monthly_volume, fee_rate_bps, ... }.
+    const status = await wallet.status();
+    // Server uses "wallet" key (not "address"), cast to access it.
+    const raw = status as unknown as Record<string, unknown>;
+    assert.equal(
+      (raw["wallet"] as string).toLowerCase(),
+      wallet.address.toLowerCase(),
+      "Server must return our wallet address",
+    );
+    assert.ok(typeof status.tier === "string" && status.tier.length > 0, "tier must be set");
+  });
+
+  it("unauthenticated POST /payments/direct returns 401", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const resp = await fetch(`${SERVER_URL}/api/v0/payments/direct`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        to: ROUTER_ADDRESS,
+        amount: 1.0,
+      }),
+    });
+    assert.equal(resp.status, 401, `Expected 401, got ${resp.status}`);
+  });
+
+  it("mint credits testnet funds", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const wallet = await makeWallet();
+    const tx = await wallet.mint(100);
+    assert.ok(tx.tx_hash, "tx_hash must be set after mint");
+  });
+
+});

package/tests/compliance/escrows.ts

@@ -0,0 +1,96 @@
+/**
+ * Compliance: escrow lifecycle against a real server.
+ *
+ * Verifies: create escrow (pay) → funded state → cancel → cancelled state.
+ * Requires the compliance server to be running (docker-compose.compliance.yml).
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+
+import { SERVER_URL, serverIsReachable, makeFundedPair } from "./helpers.js";
+import type { Invoice } from "../../src/models/invoice.js";
+
+let skip = false;
+
+before(async () => {
+  skip = !(await serverIsReachable());
+  if (skip) {
+    console.warn(
+      `[compliance] Server not reachable at ${SERVER_URL}. Skipping escrow tests.`,
+    );
+  }
+});
+
+describe("TypeScript compliance: escrow lifecycle", () => {
+  it("pay (escrow create) returns tx with invoiceId", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+
+    const tx = await payer.pay({
+      id: "",
+      from: payer.address,
+      to: payeeAddress,
+      amount: 10.0,
+      chain: "base-sepolia",
+      status: "pending",
+      paymentType: "escrow",
+      createdAt: 0,
+      memo: "compliance escrow test",
+    } as Invoice);
+
+    assert.ok(tx.invoiceId, "invoiceId must be set after pay");
+    assert.ok(tx.txHash, "txHash must be set after pay");
+  });
+
+  it("getEscrow returns funded escrow immediately after pay", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+
+    const tx = await payer.pay({
+      id: "",
+      from: payer.address,
+      to: payeeAddress,
+      amount: 10.0,
+      chain: "base-sepolia",
+      status: "pending",
+      paymentType: "escrow",
+      createdAt: 0,
+      memo: "compliance escrow funded check",
+    } as Invoice);
+
+    const escrow = await payer.getEscrow(tx.invoiceId!);
+    assert.equal(escrow.invoiceId, tx.invoiceId);
+    assert.equal(escrow.status, "funded");
+    assert.ok(
+      Math.abs(escrow.amount - 10.0) < 0.01,
+      `Expected ~10 USDC, got ${escrow.amount}`,
+    );
+  });
+
+  it("cancelEscrow transitions escrow to cancelled", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+
+    const tx = await payer.pay({
+      id: "",
+      from: payer.address,
+      to: payeeAddress,
+      amount: 10.0,
+      chain: "base-sepolia",
+      status: "pending",
+      paymentType: "escrow",
+      createdAt: 0,
+      memo: "compliance escrow cancel test",
+    } as Invoice);
+
+    const cancelTx = await payer.cancelEscrow(tx.invoiceId!);
+    assert.ok(cancelTx.txHash, "cancelTx must have txHash");
+
+    const escrow = await payer.getEscrow(tx.invoiceId!);
+    assert.equal(escrow.status, "cancelled");
+  });
+});

package/tests/compliance/helpers.ts

@@ -0,0 +1,90 @@
+/**
+ * Compliance test helpers: register operators, create funded Wallet instances.
+ *
+ * Environment variables (set by CI; defaults match docker-compose.compliance.yml):
+ *   REMIT_TEST_SERVER_URL   Server base URL (default: http://localhost:3000)
+ *   REMIT_ROUTER_ADDRESS    Router contract address for EIP-712 domain
+ *   REMIT_CHAIN_ID          Chain ID for EIP-712 domain (default: 84532)
+ */
+
+import { Wallet } from "../../src/wallet.js";
+
+export const SERVER_URL =
+  process.env["REMIT_TEST_SERVER_URL"] ?? "http://localhost:3000";
+export const ROUTER_ADDRESS =
+  process.env["REMIT_ROUTER_ADDRESS"] ??
+  "0x70997970C51812dc3A010C7d01b50e0d17dc79C8";
+export const CHAIN_ID = Number(process.env["REMIT_CHAIN_ID"] ?? "84532");
+
+/** Returns true if the compliance server is reachable and healthy. */
+export async function serverIsReachable(): Promise<boolean> {
+  try {
+    const resp = await fetch(`${SERVER_URL}/health`, { signal: AbortSignal.timeout(3000) });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Register a new operator and return (privateKey, walletAddress). */
+export async function registerAndGetWallet(): Promise<{
+  privateKey: string;
+  walletAddress: string;
+}> {
+  const email = `compliance.ts.${Date.now()}@test.remitmd.local`;
+  const password = "ComplianceTestPass1!";
+
+  const regResp = await fetch(`${SERVER_URL}/api/v0/auth/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email, password }),
+  });
+  if (!regResp.ok) {
+    throw new Error(`register failed: ${regResp.status} ${await regResp.text()}`);
+  }
+  const reg = (await regResp.json()) as { token: string; wallet_address: string };
+
+  const keyResp = await fetch(`${SERVER_URL}/api/v0/auth/agent-key`, {
+    headers: { Authorization: `Bearer ${reg.token}` },
+  });
+  if (!keyResp.ok) {
+    throw new Error(`agent-key failed: ${keyResp.status} ${await keyResp.text()}`);
+  }
+  const keyData = (await keyResp.json()) as { private_key: string };
+
+  return { privateKey: keyData.private_key, walletAddress: reg.wallet_address };
+}
+
+/** Create a Wallet backed by a freshly registered operator. */
+export async function makeWallet(): Promise<Wallet> {
+  const { privateKey } = await registerAndGetWallet();
+  return new Wallet({
+    privateKey,
+    chain: "base-sepolia",
+    apiUrl: `${SERVER_URL}/api/v0`,
+    routerAddress: ROUTER_ADDRESS,
+  });
+}
+
+/** Create two wallets (payer + payee) and fund the payer via mint. */
+export async function makeFundedPair(): Promise<{
+  payer: Wallet;
+  payee: Wallet;
+  payeeAddress: string;
+}> {
+  const { privateKey: pkA } = await registerAndGetWallet();
+  const { privateKey: pkB, walletAddress: addrB } = await registerAndGetWallet();
+
+  const walletOpts = {
+    chain: "base-sepolia" as const,
+    apiUrl: `${SERVER_URL}/api/v0`,
+    routerAddress: ROUTER_ADDRESS,
+  };
+
+  const payer = new Wallet({ privateKey: pkA, ...walletOpts });
+  const payee = new Wallet({ privateKey: pkB, ...walletOpts });
+
+  await payer.mint(100);
+
+  return { payer, payee, payeeAddress: addrB };
+}

package/tests/compliance/payments.ts

@@ -0,0 +1,69 @@
+/**
+ * Compliance: pay_direct against a real server.
+ *
+ * Verifies end-to-end direct payment: mint → payDirect → invoice exists.
+ * Requires the compliance server to be running (docker-compose.compliance.yml).
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+
+import { SERVER_URL, serverIsReachable, makeFundedPair } from "./helpers.js";
+import { RemitError } from "../../src/errors.js";
+
+let skip = false;
+
+before(async () => {
+  skip = !(await serverIsReachable());
+  if (skip) {
+    console.warn(
+      `[compliance] Server not reachable at ${SERVER_URL}. Skipping payment tests.`,
+    );
+  }
+});
+
+describe("TypeScript compliance: payDirect", () => {
+  it("happy path: payDirect returns tx with txHash and invoiceId", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+    const tx = await payer.payDirect(payeeAddress, 5.0, "compliance test");
+
+    assert.ok(tx.txHash, "txHash must be set");
+    assert.ok(tx.invoiceId, "invoiceId must be set");
+  });
+
+  it("below minimum amount returns 400/422 error", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+    await assert.rejects(
+      () => payer.payDirect(payeeAddress, 0.001, "too small"),
+      (err: unknown) => {
+        assert.ok(err instanceof RemitError, "must throw RemitError");
+        assert.ok(
+          err.httpStatus === 422 || err.httpStatus === 400,
+          `Expected 400/422, got ${err.httpStatus}`,
+        );
+        return true;
+      },
+    );
+  });
+
+  it("self-payment returns 400/422 error", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer } = await makeFundedPair();
+    await assert.rejects(
+      () => payer.payDirect(payer.address, 1.0, "self pay"),
+      (err: unknown) => {
+        assert.ok(err instanceof RemitError, "must throw RemitError");
+        assert.ok(
+          err.httpStatus === 422 || err.httpStatus === 400,
+          `Expected 400/422, got ${err.httpStatus}`,
+        );
+        return true;
+      },
+    );
+  });
+});

package/tests/compliance/tabs.ts

@@ -0,0 +1,52 @@
+/**
+ * Compliance: tab lifecycle against a real server.
+ *
+ * Verifies: openTab → tab in open state → closeTab → tab no longer open.
+ * Requires the compliance server to be running (docker-compose.compliance.yml).
+ */
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+
+import { SERVER_URL, serverIsReachable, makeFundedPair } from "./helpers.js";
+
+let skip = false;
+
+before(async () => {
+  skip = !(await serverIsReachable());
+  if (skip) {
+    console.warn(
+      `[compliance] Server not reachable at ${SERVER_URL}. Skipping tab tests.`,
+    );
+  }
+});
+
+describe("TypeScript compliance: tab lifecycle", () => {
+  it("openTab returns tab in open state", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+    const tab = await payer.openTab({ to: payeeAddress, limit: 20.0, perUnit: 0.10 });
+
+    assert.ok(tab.id, "tab must have an id");
+    assert.equal(tab.status, "open");
+    // Server returns 'limit_amount' which after camelCase transform becomes 'limitAmount'.
+    // The TypeScript Tab interface uses 'limit' (a naming mismatch tracked separately).
+    // We verify the tab was created in open state, which is the key compliance assertion.
+    const raw = tab as unknown as Record<string, unknown>;
+    assert.ok(raw["limitAmount"] !== undefined || raw["limit"] !== undefined, "limit field must be present");
+  });
+
+  it("closeTab returns tx and tab is no longer open", async (t) => {
+    if (skip) return t.skip("server not available");
+
+    const { payer, payeeAddress } = await makeFundedPair();
+    const tab = await payer.openTab({ to: payeeAddress, limit: 50.0, perUnit: 1.0 });
+
+    const closeTx = await payer.closeTab(tab.id);
+    assert.ok(closeTx.txHash, "closeTx must have txHash");
+
+    const closedTab = await payer.getTab(tab.id);
+    assert.notEqual(closedTab.status, "open", "tab must not be open after close");
+  });
+});