@remitmd/sdk 0.1.0

package/dist/x402.js

@@ -0,0 +1,151 @@
+/**
+ * x402 client middleware for auto-paying HTTP 402 Payment Required responses.
+ *
+ * x402 is an open payment standard where resource servers return HTTP 402 with
+ * a `PAYMENT-REQUIRED` header describing the cost. This module provides a
+ * `fetch` wrapper that intercepts those responses, signs an EIP-3009
+ * authorization, and retries the request with a `PAYMENT-SIGNATURE` header.
+ *
+ * Usage:
+ *   ```typescript
+ *   import { PrivateKeySigner } from "@remitmd/sdk";
+ *   import { X402Client } from "@remitmd/sdk/x402";
+ *
+ *   const signer = new PrivateKeySigner("0x...");
+ *   const client = new X402Client({
+ *     signer,
+ *     address: signer.getAddress(),
+ *     maxAutoPayUsdc: 0.10,
+ *   });
+ *
+ *   const response = await client.fetch("https://api.provider.com/v1/data");
+ *   ```
+ */
+import { randomBytes } from "node:crypto";
+/** EIP-712 type definitions for USDC's transferWithAuthorization (EIP-3009). */
+const EIP3009_TYPES = {
+    TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+/** Raised when an x402 payment amount exceeds the configured auto-pay limit. */
+export class AllowanceExceededError extends Error {
+    amountUsdc;
+    limitUsdc;
+    constructor(amountUsdc, limitUsdc) {
+        super(`x402 payment ${amountUsdc.toFixed(6)} USDC exceeds auto-pay limit ${limitUsdc.toFixed(6)} USDC`);
+        this.name = "AllowanceExceededError";
+        this.amountUsdc = amountUsdc;
+        this.limitUsdc = limitUsdc;
+    }
+}
+/**
+ * `fetch` wrapper that auto-handles HTTP 402 Payment Required responses.
+ *
+ * On receiving a 402, the client:
+ * 1. Decodes the `PAYMENT-REQUIRED` header (base64 JSON)
+ * 2. Checks the amount is within `maxAutoPayUsdc`
+ * 3. Builds and signs an EIP-3009 `transferWithAuthorization`
+ * 4. Base64-encodes the `PAYMENT-SIGNATURE` header
+ * 5. Retries the original request with payment attached
+ *
+ * V2: The decoded `PAYMENT-REQUIRED` may include `resource`, `description`,
+ * and `mimeType` fields. Access the last payment via `lastPayment`.
+ */
+export class X402Client {
+    #signer;
+    #address;
+    #maxAutoPayUsdc;
+    /** The last PAYMENT-REQUIRED decoded before payment. Useful for logging/display. */
+    lastPayment = null;
+    constructor({ signer, address, maxAutoPayUsdc = 0.1 }) {
+        this.#signer = signer;
+        this.#address = address;
+        this.#maxAutoPayUsdc = maxAutoPayUsdc;
+    }
+    /** Make a fetch request, auto-paying any 402 responses within the configured limit. */
+    async fetch(url, init) {
+        const response = await globalThis.fetch(url, init);
+        if (response.status === 402) {
+            return this.#handle402(url, response, init);
+        }
+        return response;
+    }
+    async #handle402(url, response, init) {
+        // 1. Decode PAYMENT-REQUIRED header (header names are case-insensitive per HTTP spec).
+        const raw = response.headers.get("payment-required");
+        if (!raw) {
+            throw new Error("402 response missing PAYMENT-REQUIRED header");
+        }
+        const required = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+        // 2. Only the "exact" scheme is supported in V5.
+        if (required.scheme !== "exact") {
+            throw new Error(`Unsupported x402 scheme: ${required.scheme}`);
+        }
+        // Store for caller inspection (V2 fields: resource, description, mimeType).
+        this.lastPayment = required;
+        // 3. Check auto-pay limit.
+        const amountBaseUnits = BigInt(required.amount);
+        const amountUsdc = Number(amountBaseUnits) / 1_000_000;
+        if (amountUsdc > this.#maxAutoPayUsdc) {
+            throw new AllowanceExceededError(amountUsdc, this.#maxAutoPayUsdc);
+        }
+        // 4. Parse chainId from CAIP-2 network string (e.g. "eip155:84532" → 84532).
+        const chainId = parseInt(required.network.split(":")[1], 10);
+        // 5. Build EIP-3009 authorization fields.
+        const nowSecs = Math.floor(Date.now() / 1000);
+        const validBefore = nowSecs + (required.maxTimeoutSeconds ?? 60);
+        const nonce = `0x${randomBytes(32).toString("hex")}`;
+        const domain = {
+            name: "USD Coin",
+            version: "2",
+            chainId,
+            verifyingContract: required.asset,
+        };
+        // viem requires uint256 values as bigint.
+        const message = {
+            from: this.#address,
+            to: required.payTo,
+            value: amountBaseUnits,
+            validAfter: BigInt(0),
+            validBefore: BigInt(validBefore),
+            nonce,
+        };
+        // 6. Sign EIP-712 typed data.
+        const signature = await this.#signer.signTypedData(domain, 
+        // Cast: EIP3009_TYPES satisfies TypedDataTypes but has readonly arrays.
+        EIP3009_TYPES, message);
+        // 7. Build PAYMENT-SIGNATURE JSON payload.
+        const paymentPayload = {
+            scheme: required.scheme,
+            network: required.network,
+            x402Version: 1,
+            payload: {
+                signature,
+                authorization: {
+                    from: this.#address,
+                    to: required.payTo,
+                    value: required.amount, // string (base units)
+                    validAfter: "0",
+                    validBefore: String(validBefore),
+                    nonce,
+                },
+            },
+        };
+        const paymentHeader = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+        // 8. Retry with PAYMENT-SIGNATURE header.
+        const newHeaders = new Headers(init?.headers);
+        newHeaders.set("PAYMENT-SIGNATURE", paymentHeader);
+        return globalThis.fetch(url, { ...init, headers: newHeaders });
+    }
+    /** Prevent address leakage via structured cloning / serialisation. */
+    toJSON() {
+        return { address: this.#address };
+    }
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}

package/eslint.config.js

@@ -0,0 +1,27 @@
+import js from "@eslint/js";
+import tsPlugin from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+  {
+    files: ["src/**/*.ts"],
+    plugins: { "@typescript-eslint": tsPlugin },
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { project: "./tsconfig.json" },
+      globals: {
+        ...globals.node,
+        fetch: "readonly",
+      },
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "no-undef": "off", // TypeScript handles this via strict type checking
+    },
+  },
+];

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@remitmd/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the remit.md universal AI payment protocol",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test tests/*.ts",
+    "compliance": "node --import tsx --test tests/compliance/*.ts",
+    "acceptance": "node --import tsx --test --test-concurrency=1 tests/acceptance/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^17.4.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT"
+}

package/src/a2a.ts

@@ -0,0 +1,241 @@
+/**
+ * A2A / AP2 — agent card discovery and A2A JSON-RPC task client.
+ *
+ * Spec: https://google.github.io/A2A/specification/
+ * AP2:  https://ap2-protocol.org/
+ */
+
+import type { Signer } from "./signer.js";
+import { AuthenticatedClient } from "./http.js";
+import { CHAIN_IDS } from "./client.js";
+
+// ─── Agent Card types ─────────────────────────────────────────────────────────
+
+export interface A2AExtension {
+  uri: string;
+  description: string;
+  required: boolean;
+}
+
+export interface A2ACapabilities {
+  streaming: boolean;
+  pushNotifications: boolean;
+  stateTransitionHistory: boolean;
+  extensions: A2AExtension[];
+}
+
+export interface A2ASkill {
+  id: string;
+  name: string;
+  description: string;
+  tags: string[];
+}
+
+export interface A2AFees {
+  standardBps: number;
+  preferredBps: number;
+  cliffUsd: number;
+}
+
+export interface A2AX402 {
+  settleEndpoint: string;
+  assets: Record<string, string>;
+  fees: A2AFees;
+}
+
+export interface AgentCard {
+  protocolVersion: string;
+  name: string;
+  description: string;
+  /** A2A JSON-RPC endpoint URL (POST). */
+  url: string;
+  version: string;
+  documentationUrl: string;
+  capabilities: A2ACapabilities;
+  authentication: unknown[];
+  skills: A2ASkill[];
+  x402: A2AX402;
+}
+
+/**
+ * Fetch and parse the A2A agent card from `baseUrl`/.well-known/agent-card.json.
+ *
+ * @example
+ * ```ts
+ * const card = await discoverAgent("https://remit.md");
+ * console.log(card.name, card.url);
+ * ```
+ */
+export async function discoverAgent(baseUrl: string): Promise<AgentCard> {
+  const url = baseUrl.replace(/\/$/, "") + "/.well-known/agent-card.json";
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    throw new Error(`Agent card discovery failed: HTTP ${res.status} ${res.statusText}`);
+  }
+  return (await res.json()) as AgentCard;
+}
+
+// ─── A2A task types ───────────────────────────────────────────────────────────
+
+export interface A2ATaskStatus {
+  state: "completed" | "failed" | "canceled" | "working" | string;
+  message?: { text?: string };
+}
+
+export interface A2AArtifactPart {
+  kind: string;
+  data?: Record<string, unknown>;
+}
+
+export interface A2AArtifact {
+  name?: string;
+  parts: A2AArtifactPart[];
+}
+
+export interface A2ATask {
+  id: string;
+  status: A2ATaskStatus;
+  artifacts: A2AArtifact[];
+}
+
+/** Extract `txHash` from task artifacts, if present. */
+export function getTaskTxHash(task: A2ATask): string | undefined {
+  for (const artifact of task.artifacts) {
+    for (const part of artifact.parts) {
+      const tx = part.data?.["txHash"];
+      if (typeof tx === "string") return tx;
+    }
+  }
+  return undefined;
+}
+
+// ─── IntentMandate ────────────────────────────────────────────────────────────
+
+export interface IntentMandate {
+  mandateId: string;
+  expiresAt: string;
+  issuer: string;
+  allowance: {
+    maxAmount: string;
+    currency: string;
+  };
+}
+
+// ─── A2A client options ───────────────────────────────────────────────────────
+
+export interface A2AClientOptions {
+  /** Full A2A endpoint URL from the agent card (e.g. ``"https://remit.md/a2a"``). */
+  endpoint: string;
+  signer: Signer;
+  chainId: number;
+  verifyingContract?: string;
+}
+
+export interface SendOptions {
+  to: string;
+  amount: number;
+  memo?: string;
+  mandate?: IntentMandate;
+}
+
+// ─── A2A client ───────────────────────────────────────────────────────────────
+
+/**
+ * A2A JSON-RPC client — send payments and manage tasks via the A2A protocol.
+ *
+ * @example
+ * ```ts
+ * import { discoverAgent, A2AClient } from "@remitmd/sdk";
+ * import { PrivateKeySigner } from "@remitmd/sdk";
+ *
+ * const card = await discoverAgent("https://remit.md");
+ * const signer = new PrivateKeySigner(process.env.REMITMD_KEY!);
+ * const client = A2AClient.fromCard(card, signer);
+ * const task = await client.send({ to: "0xRecipient...", amount: 10 });
+ * console.log(task.status.state, getTaskTxHash(task));
+ * ```
+ */
+export class A2AClient {
+  private readonly _http: AuthenticatedClient;
+  private readonly _path: string;
+
+  constructor(opts: A2AClientOptions) {
+    const { endpoint, signer, chainId, verifyingContract = "" } = opts;
+    const parsed = new URL(endpoint);
+    const baseUrl = `${parsed.protocol}//${parsed.host}`;
+    this._path = parsed.pathname || "/a2a";
+    this._http = new AuthenticatedClient({ signer, baseUrl, chainId, verifyingContract });
+  }
+
+  /** Convenience constructor from an :class:`AgentCard` and a signer. */
+  static fromCard(
+    card: AgentCard,
+    signer: Signer,
+    opts?: { chain?: string; verifyingContract?: string },
+  ): A2AClient {
+    const chain = opts?.chain ?? "base";
+    const chainId = CHAIN_IDS[chain] ?? CHAIN_IDS["base"]!;
+    return new A2AClient({
+      endpoint: card.url,
+      signer,
+      chainId,
+      verifyingContract: opts?.verifyingContract ?? "",
+    });
+  }
+
+  /**
+   * Send a direct USDC payment via ``message/send``.
+   *
+   * @returns :interface:`A2ATask` with ``status.state === "completed"`` on success.
+   */
+  async send(opts: SendOptions): Promise<A2ATask> {
+    const { to, amount, memo = "", mandate } = opts;
+    const nonce = crypto.randomUUID().replace(/-/g, "");
+    const messageId = crypto.randomUUID().replace(/-/g, "");
+
+    const message: Record<string, unknown> = {
+      messageId,
+      role: "user",
+      parts: [
+        {
+          kind: "data",
+          data: {
+            model: "direct",
+            to,
+            amount: amount.toFixed(2),
+            memo,
+            nonce,
+          },
+        },
+      ],
+    };
+
+    if (mandate) {
+      message["metadata"] = { mandate };
+    }
+
+    return this._rpc<A2ATask>("message/send", { message }, messageId);
+  }
+
+  /** Fetch the current state of an A2A task by ID. */
+  async getTask(taskId: string): Promise<A2ATask> {
+    return this._rpc<A2ATask>("tasks/get", { id: taskId }, taskId.slice(0, 16));
+  }
+
+  /** Cancel an in-progress A2A task. */
+  async cancelTask(taskId: string): Promise<A2ATask> {
+    return this._rpc<A2ATask>("tasks/cancel", { id: taskId }, taskId.slice(0, 16));
+  }
+
+  private async _rpc<T>(method: string, params: unknown, callId: string): Promise<T> {
+    const body = { jsonrpc: "2.0", id: callId, method, params };
+    const data = await this._http.post<{ result?: T; error?: { message?: string } }>(
+      this._path,
+      body,
+    );
+    if (data.error) {
+      throw new Error(`A2A error: ${data.error.message ?? JSON.stringify(data.error)}`);
+    }
+    return (data.result ?? (data as unknown as T)) as T;
+  }
+}

package/src/client.ts

@@ -0,0 +1,104 @@
+/**
+ * RemitClient — read-only operations, no private key required.
+ */
+
+import type { WalletStatus, Reputation, ContractAddresses } from "./models/index.js";
+import type { Invoice } from "./models/invoice.js";
+import type { Escrow } from "./models/escrow.js";
+import type { Tab } from "./models/tab.js";
+import type { Stream } from "./models/stream.js";
+import type { Bounty } from "./models/bounty.js";
+import type { Deposit } from "./models/deposit.js";
+const DEFAULT_API_URLS: Record<string, string> = {
+  base: "https://api.remit.md/api/v0",
+  "base-sepolia": "https://testnet.remit.md/api/v0",
+  localhost: "http://localhost:3000/api/v0",
+};
+
+export const CHAIN_IDS: Record<string, number> = {
+  base: 8453,
+  "base-sepolia": 84532,
+  localhost: 31337,
+};
+
+export interface RemitClientOptions {
+  chain?: string;
+  testnet?: boolean;
+  apiUrl?: string;
+}
+
+export class RemitClient {
+  protected readonly _chain: string;
+  protected readonly _apiUrl: string;
+  protected readonly _chainId: number;
+  #contractsCache: ContractAddresses | null = null;
+
+  constructor(options: RemitClientOptions = {}) {
+    const { chain = "base", testnet = false, apiUrl } = options;
+    this._chain = testnet && !chain.includes("sepolia") ? `${chain}-sepolia` : chain;
+    this._apiUrl =
+      apiUrl ?? DEFAULT_API_URLS[this._chain] ?? DEFAULT_API_URLS["base"]!;
+    this._chainId = CHAIN_IDS[this._chain] ?? CHAIN_IDS["base"]!;
+  }
+
+  protected async _fetch<T>(path: string): Promise<T> {
+    const response = await fetch(`${this._apiUrl}${path}`, {
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return (await response.json()) as T;
+  }
+
+  getInvoice(invoiceId: string): Promise<Invoice> {
+    return this._fetch<Invoice>(`/invoices/${invoiceId}`);
+  }
+
+  getEscrow(invoiceId: string): Promise<Escrow> {
+    return this._fetch<Escrow>(`/escrows/${invoiceId}`);
+  }
+
+  getTab(tabId: string): Promise<Tab> {
+    return this._fetch<Tab>(`/tabs/${tabId}`);
+  }
+
+  getStream(streamId: string): Promise<Stream> {
+    return this._fetch<Stream>(`/streams/${streamId}`);
+  }
+
+  getBounty(bountyId: string): Promise<Bounty> {
+    return this._fetch<Bounty>(`/bounties/${bountyId}`);
+  }
+
+  getDeposit(depositId: string): Promise<Deposit> {
+    return this._fetch<Deposit>(`/deposits/${depositId}`);
+  }
+
+  getStatus(wallet: string): Promise<WalletStatus> {
+    return this._fetch<WalletStatus>(`/status/${wallet}`);
+  }
+
+  getReputation(wallet: string): Promise<Reputation> {
+    return this._fetch<Reputation>(`/reputation/${wallet}`);
+  }
+
+  /** Get deployed contract addresses. Cached for the lifetime of this client instance. */
+  async getContracts(): Promise<ContractAddresses> {
+    if (this.#contractsCache) return this.#contractsCache;
+    const contracts = await this._fetch<ContractAddresses>("/contracts");
+    this.#contractsCache = contracts;
+    return contracts;
+  }
+
+  listBounties(options: { status?: string; limit?: number; poster?: string; submitter?: string } = {}): Promise<Bounty[]> {
+    const params = new URLSearchParams();
+    if (options.status) params.set("status", options.status);
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.poster) params.set("poster", options.poster);
+    if (options.submitter) params.set("submitter", options.submitter);
+    const qs = params.toString();
+    return this._fetch<Bounty[]>(`/bounties${qs ? `?${qs}` : ""}`);
+  }
+
+}