@remitmd/sdk 0.1.0

package/tests/test_a2a.ts

@@ -0,0 +1,151 @@
+import { describe, it, mock, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { discoverAgent, getTaskTxHash, A2AClient } from "../src/a2a.js";
+import type { AgentCard, A2ATask } from "../src/a2a.js";
+import { PrivateKeySigner } from "../src/signer.js";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const CARD_DATA: AgentCard = {
+  protocolVersion: "0.6",
+  name: "remit.md",
+  description: "USDC payment protocol for AI agents.",
+  url: "https://remit.md/a2a",
+  version: "0.1.0",
+  documentationUrl: "https://remit.md/docs",
+  capabilities: {
+    streaming: false,
+    pushNotifications: false,
+    stateTransitionHistory: true,
+    extensions: [
+      {
+        uri: "https://ap2-protocol.org/ext/payment-processor",
+        description: "AP2 payment processor",
+        required: false,
+      },
+    ],
+  },
+  authentication: [],
+  skills: [
+    {
+      id: "direct-payment",
+      name: "Direct Payment",
+      description: "Send USDC directly.",
+      tags: ["payment", "usdc"],
+    },
+    {
+      id: "x402-paywall",
+      name: "x402 Paywall",
+      description: "HTTP 402 payment rail.",
+      tags: ["x402", "paywall"],
+    },
+  ],
+  x402: {
+    settleEndpoint: "https://remit.md/api/v0/x402/settle",
+    assets: { "eip155:8453": "0xUSDC" },
+    fees: { standardBps: 100, preferredBps: 50, cliffUsd: 10000 },
+  },
+};
+
+// ─── discoverAgent ─────────────────────────────────────────────────────────────
+
+describe("discoverAgent", () => {
+  let fetchMock: ReturnType<typeof mock.fn>;
+
+  beforeEach(() => {
+    fetchMock = mock.fn(async (_url: string) => ({
+      ok: true,
+      status: 200,
+      json: async () => CARD_DATA,
+    }));
+    (globalThis as unknown as { fetch: unknown }).fetch = fetchMock;
+  });
+
+  afterEach(() => {
+    mock.restoreAll();
+  });
+
+  it("fetches from /.well-known/agent-card.json", async () => {
+    const card = await discoverAgent("https://remit.md");
+    assert.equal(fetchMock.mock.calls.length, 1);
+    const url = fetchMock.mock.calls[0]!.arguments[0] as string;
+    assert.equal(url, "https://remit.md/.well-known/agent-card.json");
+  });
+
+  it("strips trailing slash from base URL", async () => {
+    await discoverAgent("https://remit.md/");
+    const url = fetchMock.mock.calls[0]!.arguments[0] as string;
+    assert.equal(url, "https://remit.md/.well-known/agent-card.json");
+  });
+
+  it("returns parsed agent card", async () => {
+    const card = await discoverAgent("https://remit.md");
+    assert.equal(card.name, "remit.md");
+    assert.equal(card.url, "https://remit.md/a2a");
+    assert.equal(card.protocolVersion, "0.6");
+    assert.equal(card.skills.length, 2);
+    assert.equal(card.x402.fees.standardBps, 100);
+  });
+
+  it("throws on non-200 response", async () => {
+    fetchMock = mock.fn(async () => ({ ok: false, status: 404, statusText: "Not Found" }));
+    (globalThis as unknown as { fetch: unknown }).fetch = fetchMock;
+    await assert.rejects(
+      () => discoverAgent("https://notfound.example"),
+      /404/,
+    );
+  });
+});
+
+// ─── getTaskTxHash ─────────────────────────────────────────────────────────────
+
+describe("getTaskTxHash", () => {
+  it("extracts txHash from artifacts", () => {
+    const task: A2ATask = {
+      id: "task_1",
+      status: { state: "completed" },
+      artifacts: [
+        { parts: [{ kind: "data", data: { txHash: "0xdeadbeef" } }] },
+      ],
+    };
+    assert.equal(getTaskTxHash(task), "0xdeadbeef");
+  });
+
+  it("returns undefined when no artifacts", () => {
+    const task: A2ATask = {
+      id: "task_2",
+      status: { state: "completed" },
+      artifacts: [],
+    };
+    assert.equal(getTaskTxHash(task), undefined);
+  });
+
+  it("returns undefined when artifacts have no txHash", () => {
+    const task: A2ATask = {
+      id: "task_3",
+      status: { state: "failed" },
+      artifacts: [{ parts: [{ kind: "data", data: { foo: "bar" } }] }],
+    };
+    assert.equal(getTaskTxHash(task), undefined);
+  });
+});
+
+// ─── A2AClient constructor ────────────────────────────────────────────────────
+
+describe("A2AClient", () => {
+  const TEST_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+  it("fromCard creates client with correct path", () => {
+    const signer = new PrivateKeySigner(TEST_KEY);
+    const client = A2AClient.fromCard(CARD_DATA, signer);
+    // Access internal path (private field — test via behavior or cast)
+    assert.ok(client instanceof A2AClient);
+  });
+
+  it("fromCard accepts chain option", () => {
+    const signer = new PrivateKeySigner(TEST_KEY);
+    const client = A2AClient.fromCard(CARD_DATA, signer, { chain: "base-sepolia" });
+    assert.ok(client instanceof A2AClient);
+  });
+});

package/tests/test_errors.ts

@@ -0,0 +1,80 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  fromErrorCode,
+  RemitError,
+  InsufficientBalanceError,
+  EscrowNotFoundError,
+  InvalidSignatureError,
+  TabNotFoundError,
+  StreamNotFoundError,
+  BountyNotFoundError,
+  RateLimitedError,
+  ChainMismatchError,
+} from "../src/errors.js";
+
+describe("Error classes", () => {
+  it("RemitError base has code and httpStatus", () => {
+    const e = new RemitError("test", "MY_CODE", 418);
+    assert.equal(e.code, "MY_CODE");
+    assert.equal(e.httpStatus, 418);
+    assert.equal(e.message, "test");
+    assert(e instanceof Error);
+  });
+
+  it("typed subclasses have correct codes", () => {
+    assert.equal(new InsufficientBalanceError().code, "INSUFFICIENT_BALANCE");
+    assert.equal(new EscrowNotFoundError().code, "ESCROW_NOT_FOUND");
+    assert.equal(new InvalidSignatureError().code, "INVALID_SIGNATURE");
+    assert.equal(new TabNotFoundError().code, "TAB_NOT_FOUND");
+    assert.equal(new StreamNotFoundError().code, "STREAM_NOT_FOUND");
+    assert.equal(new BountyNotFoundError().code, "BOUNTY_NOT_FOUND");
+    assert.equal(new RateLimitedError().code, "RATE_LIMITED");
+    assert.equal(new ChainMismatchError().code, "CHAIN_MISMATCH");
+  });
+
+  it("typed subclasses are instanceof RemitError", () => {
+    assert(new InsufficientBalanceError() instanceof RemitError);
+    assert(new EscrowNotFoundError() instanceof RemitError);
+    assert(new RateLimitedError() instanceof RemitError);
+  });
+
+  it("fromErrorCode returns correct subclass", () => {
+    const e = fromErrorCode("INSUFFICIENT_BALANCE", "custom message");
+    assert(e instanceof InsufficientBalanceError);
+    assert.equal(e.message, "custom message");
+  });
+
+  it("fromErrorCode with unknown code returns base RemitError", () => {
+    const e = fromErrorCode("TOTALLY_UNKNOWN_CODE");
+    assert(e instanceof RemitError);
+    assert.equal(e.code, "TOTALLY_UNKNOWN_CODE");
+  });
+
+  it("fromErrorCode uses default message when none provided", () => {
+    const e = fromErrorCode("ESCROW_NOT_FOUND");
+    assert(e.message.length > 0);
+  });
+
+  it("error name equals class name", () => {
+    const e = new InsufficientBalanceError();
+    assert.equal(e.name, "InsufficientBalanceError");
+  });
+
+  it("errors all have positive httpStatus", () => {
+    const codes = [
+      "INSUFFICIENT_BALANCE",
+      "ESCROW_NOT_FOUND",
+      "TAB_NOT_FOUND",
+      "RATE_LIMITED",
+      "CHAIN_MISMATCH",
+      "DISPUTE_ALREADY_FILED",
+      "VERSION_MISMATCH",
+    ];
+    for (const code of codes) {
+      const e = fromErrorCode(code);
+      assert(e.httpStatus >= 400 && e.httpStatus < 600, `${code} has invalid httpStatus ${e.httpStatus}`);
+    }
+  });
+});

package/tests/test_golden_vectors.ts

@@ -0,0 +1,162 @@
+/**
+ * Golden vector tests: TypeScript SDK must reproduce the server's EIP-712 hashes exactly.
+ *
+ * Loads test-vectors/eip712.json (generated by `cargo run --bin gen_vectors` in remit-server)
+ * and verifies that viem's hashTypedData produces the same EIP-712 hash for each vector.
+ * Also verifies the ECDSA signature matches when signing with the same key.
+ *
+ * If any assertion fails, the TypeScript SDK's EIP-712 implementation diverges from the
+ * server and authentication WILL fail in production.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hashTypedData } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+// ─── Test fixtures ────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VECTORS_PATH = join(__dirname, "../../test-vectors/eip712.json");
+
+// Anvil test wallet #0 — same key used by gen_vectors in remit-server.
+const TEST_PRIVATE_KEY =
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" as const;
+
+// EIP-712 typed struct — must match server's auth.rs exactly.
+const EIP712_TYPES = {
+  APIRequest: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    { name: "timestamp", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+interface VectorDomain {
+  name: string;
+  version: string;
+  chain_id: number;
+  verifying_contract: string;
+}
+
+interface VectorMessage {
+  method: string;
+  path: string;
+  timestamp: number;
+  nonce: string;
+}
+
+interface Vector {
+  description: string;
+  domain: VectorDomain;
+  message: VectorMessage;
+  signer: string;
+  expected_domain_separator: string;
+  expected_struct_hash: string;
+  expected_hash: string;
+  expected_signature: string;
+}
+
+interface VectorFile {
+  version: string;
+  vectors: Vector[];
+}
+
+interface VectorWithBigint extends Vector {
+  /** Timestamp as BigInt — JSON.parse loses precision for u64::MAX in JS. */
+  timestampBigint: bigint;
+}
+
+function loadVectors(): VectorWithBigint[] {
+  const raw = readFileSync(VECTORS_PATH, "utf8");
+  const file = JSON.parse(raw) as VectorFile;
+  assert.ok(file.vectors.length > 0, "vectors array must not be empty");
+
+  // Extract timestamps as exact BigInts from the raw JSON string to avoid
+  // IEEE 754 precision loss for very large values (e.g. u64::MAX).
+  const timestampMatches = [...raw.matchAll(/"timestamp":\s*(\d+)/g)];
+  assert.equal(
+    timestampMatches.length,
+    file.vectors.length,
+    "Each vector must have exactly one timestamp field",
+  );
+
+  return file.vectors.map((v, i) => ({
+    ...v,
+    timestampBigint: BigInt(timestampMatches[i]![1]),
+  }));
+}
+
+const vectors: VectorWithBigint[] = loadVectors();
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("Golden vector: EIP-712 hash matches server", () => {
+  for (const vector of vectors) {
+    it(vector.description, () => {
+      const domain = {
+        name: vector.domain.name,
+        version: vector.domain.version,
+        chainId: vector.domain.chain_id,
+        verifyingContract: vector.domain.verifying_contract as `0x${string}`,
+      };
+      const message = {
+        method: vector.message.method,
+        path: vector.message.path,
+        timestamp: vector.timestampBigint,
+        nonce: vector.message.nonce as `0x${string}`,
+      };
+
+      const gotHash = hashTypedData({
+        domain,
+        types: EIP712_TYPES,
+        primaryType: "APIRequest",
+        message,
+      });
+
+      assert.equal(
+        gotHash,
+        vector.expected_hash,
+        `EIP-712 hash mismatch for '${vector.description}'`,
+      );
+    });
+  }
+});
+
+describe("Golden vector: signature matches server", () => {
+  const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+
+  for (const vector of vectors) {
+    it(vector.description, async () => {
+      const domain = {
+        name: vector.domain.name,
+        version: vector.domain.version,
+        chainId: vector.domain.chain_id,
+        verifyingContract: vector.domain.verifying_contract as `0x${string}`,
+      };
+      const message = {
+        method: vector.message.method,
+        path: vector.message.path,
+        timestamp: vector.timestampBigint,
+        nonce: vector.message.nonce as `0x${string}`,
+      };
+
+      const gotSig = await account.signTypedData({
+        domain,
+        types: EIP712_TYPES,
+        primaryType: "APIRequest",
+        message,
+      });
+
+      assert.equal(
+        gotSig,
+        vector.expected_signature,
+        `Signature mismatch for '${vector.description}'`,
+      );
+    });
+  }
+});

package/tests/test_integrations.ts

@@ -0,0 +1,115 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { MockRemit } from "../src/testing/mock.js";
+import { remitTools } from "../src/integrations/vercel-ai.js";
+
+describe("Vercel AI integration", () => {
+  let mock: MockRemit;
+
+  beforeEach(() => {
+    mock = new MockRemit();
+  });
+
+  it("remitTools returns all expected tool names", () => {
+    const payer = mock.createWallet(1000);
+    const tools = remitTools(payer);
+    const names = Object.keys(tools);
+
+    const expected = [
+      "remit_pay_direct",
+      "remit_check_balance",
+      "remit_get_status",
+      "remit_create_escrow",
+      "remit_release_escrow",
+      "remit_open_tab",
+      "remit_close_tab",
+      "remit_open_stream",
+      "remit_close_stream",
+      "remit_post_bounty",
+      "remit_place_deposit",
+    ];
+
+    for (const name of expected) {
+      assert(names.includes(name), `Missing tool: ${name}`);
+    }
+  });
+
+  it("each tool has description and execute function", () => {
+    const payer = mock.createWallet(1000);
+    const tools = remitTools(payer);
+
+    for (const [name, tool] of Object.entries(tools)) {
+      assert(tool.description.length > 10, `${name} description too short`);
+      assert(typeof tool.execute === "function", `${name} execute is not a function`);
+    }
+  });
+
+  it("remit_check_balance returns balance", async () => {
+    const payer = mock.createWallet(750);
+    const tools = remitTools(payer);
+    const result = (await tools["remit_check_balance"]!.execute()) as { balance: number };
+    assert.equal(result.balance, 750);
+  });
+
+  it("remit_pay_direct transfers funds", async () => {
+    const payer = mock.createWallet(100);
+    const payee = mock.createWallet(0);
+    const tools = remitTools(payer);
+
+    await tools["remit_pay_direct"]!.execute(payee.address, 20, "test payment");
+    assert.equal(await payer.balance(), 80);
+    assert.equal(await payee.balance(), 20);
+  });
+
+  it("remit_create_escrow creates an escrow", async () => {
+    const payer = mock.createWallet(200);
+    const payee = mock.createWallet(0);
+    const tools = remitTools(payer);
+
+    const tx = (await tools["remit_create_escrow"]!.execute(
+      payee.address,
+      50,
+      "Build a widget",
+    )) as { status: string };
+    assert.equal(tx.status, "funded");
+    assert.equal(await payer.balance(), 150);
+  });
+
+  it("remit_open_tab opens a tab", async () => {
+    const payer = mock.createWallet(100);
+    const payee = mock.createWallet(0);
+    const tools = remitTools(payer);
+
+    const tab = (await tools["remit_open_tab"]!.execute(payee.address, 40, 2)) as {
+      status: string;
+      id: string;
+    };
+    assert.equal(tab.status, "open");
+    assert(tab.id.length > 0);
+  });
+
+  it("remit_open_stream opens a stream", async () => {
+    const payer = mock.createWallet(1000);
+    const payee = mock.createWallet(0);
+    const tools = remitTools(payer);
+
+    const stream = (await tools["remit_open_stream"]!.execute(payee.address, 0.1, 3600)) as {
+      status: string;
+      id: string;
+    };
+    assert.equal(stream.status, "active");
+    assert(stream.id.length > 0);
+  });
+
+  it("remit_post_bounty posts a bounty", async () => {
+    const poster = mock.createWallet(100);
+    const tools = remitTools(poster);
+    const deadline = Math.floor(Date.now() / 1000) + 86400;
+
+    const bounty = (await tools["remit_post_bounty"]!.execute(30, "Analyze this dataset", deadline)) as {
+      status: string;
+    };
+    assert.equal(bounty.status, "open");
+  });
+});