@remitmd/sdk 0.1.0

package/src/errors.ts

@@ -0,0 +1,261 @@
+/**
+ * Typed error classes for remit.md error codes.
+ *
+ * Every API error code maps to a specific class so callers can handle precisely:
+ *
+ *   try {
+ *     await wallet.pay(invoice);
+ *   } catch (e) {
+ *     if (e instanceof InsufficientBalanceError) {
+ *       await wallet.requestTestnetFunds();
+ *     }
+ *   }
+ */
+
+export class RemitError extends Error {
+  readonly code: string;
+  readonly httpStatus: number;
+
+  constructor(message: string, code = "UNKNOWN_ERROR", httpStatus = 500) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.httpStatus = httpStatus;
+  }
+}
+
+// ─── Auth errors ─────────────────────────────────────────────────────────────
+
+export class InvalidSignatureError extends RemitError {
+  constructor(msg = "Invalid EIP-712 signature.") {
+    super(msg, "INVALID_SIGNATURE", 401);
+  }
+}
+
+export class NonceReusedError extends RemitError {
+  constructor(msg = "Nonce has already been used.") {
+    super(msg, "NONCE_REUSED", 401);
+  }
+}
+
+export class TimestampExpiredError extends RemitError {
+  constructor(msg = "Request timestamp has expired.") {
+    super(msg, "TIMESTAMP_EXPIRED", 401);
+  }
+}
+
+export class UnauthorizedError extends RemitError {
+  constructor(msg = "Authentication required.") {
+    super(msg, "UNAUTHORIZED", 401);
+  }
+}
+
+// ─── Balance / funds ──────────────────────────────────────────────────────────
+
+export class InsufficientBalanceError extends RemitError {
+  constructor(msg = "Wallet does not have enough USDC for this transaction + fee.") {
+    super(msg, "INSUFFICIENT_BALANCE", 402);
+  }
+}
+
+export class BelowMinimumError extends RemitError {
+  constructor(msg = "Transaction amount is below $0.01 minimum.") {
+    super(msg, "BELOW_MINIMUM", 400);
+  }
+}
+
+// ─── Escrow errors ────────────────────────────────────────────────────────────
+
+export class EscrowNotFoundError extends RemitError {
+  constructor(msg = "Escrow not found.") {
+    super(msg, "ESCROW_NOT_FOUND", 404);
+  }
+}
+
+export class EscrowAlreadyFundedError extends RemitError {
+  constructor(msg = "This invoice already has a funded escrow.") {
+    super(msg, "ESCROW_ALREADY_FUNDED", 409);
+  }
+}
+
+export class EscrowExpiredError extends RemitError {
+  constructor(msg = "Escrow has expired.") {
+    super(msg, "ESCROW_EXPIRED", 410);
+  }
+}
+
+// ─── Invoice errors ───────────────────────────────────────────────────────────
+
+export class InvalidInvoiceError extends RemitError {
+  constructor(msg = "Invoice is malformed or invalid.") {
+    super(msg, "INVALID_INVOICE", 400);
+  }
+}
+
+export class DuplicateInvoiceError extends RemitError {
+  constructor(msg = "An invoice with this ID already exists.") {
+    super(msg, "DUPLICATE_INVOICE", 409);
+  }
+}
+
+export class SelfPaymentError extends RemitError {
+  constructor(msg = "Cannot pay yourself.") {
+    super(msg, "SELF_PAYMENT", 400);
+  }
+}
+
+export class InvalidPaymentTypeError extends RemitError {
+  constructor(msg = "Payment type is not valid for this invoice.") {
+    super(msg, "INVALID_PAYMENT_TYPE", 400);
+  }
+}
+
+// ─── Tab errors ───────────────────────────────────────────────────────────────
+
+export class TabDepletedError extends RemitError {
+  constructor(msg = "Tab has reached its spending limit.") {
+    super(msg, "TAB_DEPLETED", 402);
+  }
+}
+
+export class TabExpiredError extends RemitError {
+  constructor(msg = "Tab has expired.") {
+    super(msg, "TAB_EXPIRED", 410);
+  }
+}
+
+export class TabNotFoundError extends RemitError {
+  constructor(msg = "Tab not found.") {
+    super(msg, "TAB_NOT_FOUND", 404);
+  }
+}
+
+// ─── Stream errors ────────────────────────────────────────────────────────────
+
+export class StreamNotFoundError extends RemitError {
+  constructor(msg = "Stream not found.") {
+    super(msg, "STREAM_NOT_FOUND", 404);
+  }
+}
+
+export class RateExceedsCapError extends RemitError {
+  constructor(msg = "Streaming rate exceeds the maximum allowed.") {
+    super(msg, "RATE_EXCEEDS_CAP", 422);
+  }
+}
+
+// ─── Bounty errors ────────────────────────────────────────────────────────────
+
+export class BountyExpiredError extends RemitError {
+  constructor(msg = "Bounty has expired.") {
+    super(msg, "BOUNTY_EXPIRED", 410);
+  }
+}
+
+export class BountyClaimedError extends RemitError {
+  constructor(msg = "Bounty has already been awarded.") {
+    super(msg, "BOUNTY_CLAIMED", 409);
+  }
+}
+
+export class BountyMaxAttemptsError extends RemitError {
+  constructor(msg = "Bounty has reached maximum submission attempts.") {
+    super(msg, "BOUNTY_MAX_ATTEMPTS", 422);
+  }
+}
+
+export class BountyNotFoundError extends RemitError {
+  constructor(msg = "Bounty not found.") {
+    super(msg, "BOUNTY_NOT_FOUND", 404);
+  }
+}
+
+// ─── Chain errors ─────────────────────────────────────────────────────────────
+
+export class ChainMismatchError extends RemitError {
+  constructor(msg = "Invoice chain does not match wallet chain.") {
+    super(msg, "CHAIN_MISMATCH", 409);
+  }
+}
+
+export class ChainUnsupportedError extends RemitError {
+  constructor(msg = "This chain is not supported.") {
+    super(msg, "CHAIN_UNSUPPORTED", 422);
+  }
+}
+
+// ─── Rate limiting ────────────────────────────────────────────────────────────
+
+export class RateLimitedError extends RemitError {
+  constructor(msg = "Rate limit exceeded. Try again later.") {
+    super(msg, "RATE_LIMITED", 429);
+  }
+}
+
+// ─── Cancellation errors ──────────────────────────────────────────────────────
+
+export class CancelBlockedClaimStartError extends RemitError {
+  constructor(msg = "Cannot cancel after claim start.") {
+    super(msg, "CANCEL_BLOCKED_CLAIM_START", 409);
+  }
+}
+
+export class CancelBlockedEvidenceError extends RemitError {
+  constructor(msg = "Cannot cancel while evidence is pending review.") {
+    super(msg, "CANCEL_BLOCKED_EVIDENCE", 409);
+  }
+}
+
+// ─── Protocol errors ──────────────────────────────────────────────────────────
+
+export class VersionMismatchError extends RemitError {
+  constructor(msg = "SDK version is not compatible with this API version.") {
+    super(msg, "VERSION_MISMATCH", 422);
+  }
+}
+
+export class NetworkError extends RemitError {
+  constructor(msg = "Network request failed.") {
+    super(msg, "NETWORK_ERROR", 503);
+  }
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+const ERROR_MAP: Record<string, new (msg?: string) => RemitError> = {
+  INVALID_SIGNATURE: InvalidSignatureError,
+  NONCE_REUSED: NonceReusedError,
+  TIMESTAMP_EXPIRED: TimestampExpiredError,
+  UNAUTHORIZED: UnauthorizedError,
+  INSUFFICIENT_BALANCE: InsufficientBalanceError,
+  BELOW_MINIMUM: BelowMinimumError,
+  ESCROW_NOT_FOUND: EscrowNotFoundError,
+  ESCROW_ALREADY_FUNDED: EscrowAlreadyFundedError,
+  ESCROW_EXPIRED: EscrowExpiredError,
+  INVALID_INVOICE: InvalidInvoiceError,
+  DUPLICATE_INVOICE: DuplicateInvoiceError,
+  SELF_PAYMENT: SelfPaymentError,
+  INVALID_PAYMENT_TYPE: InvalidPaymentTypeError,
+  TAB_DEPLETED: TabDepletedError,
+  TAB_EXPIRED: TabExpiredError,
+  TAB_NOT_FOUND: TabNotFoundError,
+  STREAM_NOT_FOUND: StreamNotFoundError,
+  RATE_EXCEEDS_CAP: RateExceedsCapError,
+  BOUNTY_EXPIRED: BountyExpiredError,
+  BOUNTY_CLAIMED: BountyClaimedError,
+  BOUNTY_MAX_ATTEMPTS: BountyMaxAttemptsError,
+  BOUNTY_NOT_FOUND: BountyNotFoundError,
+  CHAIN_MISMATCH: ChainMismatchError,
+  CHAIN_UNSUPPORTED: ChainUnsupportedError,
+  RATE_LIMITED: RateLimitedError,
+  CANCEL_BLOCKED_CLAIM_START: CancelBlockedClaimStartError,
+  CANCEL_BLOCKED_EVIDENCE: CancelBlockedEvidenceError,
+  VERSION_MISMATCH: VersionMismatchError,
+};
+
+/** Map an API error code + message into the appropriate typed error. */
+export function fromErrorCode(code: string, message?: string): RemitError {
+  const Cls = ERROR_MAP[code];
+  if (Cls) return new Cls(message);
+  return new RemitError(message ?? `Unknown error: ${code}`, code);
+}

package/src/http.ts

@@ -0,0 +1,190 @@
+/**
+ * Authenticated HTTP client.
+ * - Signs every request with EIP-712 (method, path, timestamp, nonce)
+ * - Auto-retry with exponential backoff on 429 and 5xx (up to 3 retries)
+ * - Adds idempotency key header on all POST/PATCH/PUT requests
+ * - Maps API error codes to typed RemitError subclasses
+ */
+
+import { randomBytes } from "node:crypto";
+import { fromErrorCode, NetworkError, RateLimitedError } from "./errors.js";
+import type { Signer } from "./signer.js";
+
+// EIP-712 typed struct definition — must match server's auth.rs exactly.
+// Struct name: APIRequest (not Request)
+// Timestamp type: uint256 (not uint64 or uint32)
+// Nonce type: bytes32 (not string)
+const EIP712_TYPES = {
+  APIRequest: [
+    { name: "method", type: "string" },
+    { name: "path", type: "string" },
+    { name: "timestamp", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+} as const;
+
+interface ApiErrorBody {
+  error?: { code?: string; message?: string };
+  code?: string;
+  message?: string;
+}
+
+/** 32-byte hex nonce with 0x prefix — required for bytes32 EIP-712 field. */
+function newNonce(): `0x${string}` {
+  return `0x${randomBytes(32).toString("hex")}`;
+}
+
+function newIdempotencyKey(): string {
+  return randomBytes(16).toString("hex");
+}
+
+/** Convert a snake_case key to camelCase (e.g. "tx_hash" → "txHash"). */
+function toCamel(key: string): string {
+  return key.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** Recursively transform all object keys from snake_case to camelCase.
+ *  The server (Rust/serde) emits snake_case; TypeScript SDK uses camelCase. */
+function camelizeKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(camelizeKeys);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [toCamel(k), camelizeKeys(v)]),
+    );
+  }
+  return value;
+}
+
+const RETRYABLE = new Set([429, 500, 502, 503, 504]);
+const DELAY_MS = [200, 600, 1800]; // exponential-ish
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface HttpClientOptions {
+  signer: Signer;
+  baseUrl: string;
+  chainId: number;
+  verifyingContract?: string;
+}
+
+export class AuthenticatedClient {
+  readonly #signer: Signer;
+  readonly #baseUrl: string;
+  readonly #chainId: number;
+  readonly #verifyingContract: string;
+  /** Path prefix extracted from baseUrl (e.g. "/api/v0") to prepend when signing.
+   *  The server verifies the full path (/api/v0/payments/direct) via OriginalUri,
+   *  not just the relative segment (/payments/direct). */
+  readonly #signPathPrefix: string;
+
+  constructor({ signer, baseUrl, chainId, verifyingContract = "" }: HttpClientOptions) {
+    this.#signer = signer;
+    this.#baseUrl = baseUrl.replace(/\/$/, "");
+    this.#chainId = chainId;
+    this.#verifyingContract = verifyingContract;
+    // Parse path prefix from baseUrl so signed path matches OriginalUri on server.
+    const parsedUrl = new URL(this.#baseUrl);
+    this.#signPathPrefix = parsedUrl.pathname.replace(/\/$/, "");
+  }
+
+  async get<T>(path: string): Promise<T> {
+    return this.#request<T>("GET", path);
+  }
+
+  async post<T>(path: string, body?: unknown): Promise<T> {
+    return this.#request<T>("POST", path, body);
+  }
+
+  async put<T>(path: string, body?: unknown): Promise<T> {
+    return this.#request<T>("PUT", path, body);
+  }
+
+  async delete<T>(path: string): Promise<T> {
+    return this.#request<T>("DELETE", path);
+  }
+
+  async #request<T>(method: string, path: string, body?: unknown, attempt = 0): Promise<T> {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const nonce = newNonce();
+
+    const domain = {
+      name: "remit.md",
+      version: "0.1",
+      chainId: this.#chainId,
+      verifyingContract: this.#verifyingContract,
+    };
+
+    // Sign the full path (prefix + relative path only, no query string) so it matches
+    // the path OriginalUri on the server. The server verifies only the path component.
+    // e.g. baseUrl "http://…/api/v0" + path "/events?wallet=0x…" → signed "/api/v0/events"
+    const pathOnly = path.split("?")[0];
+    const signedPath = `${this.#signPathPrefix}${pathOnly}`;
+
+    // Sign the request metadata (never body — body may be large)
+    const signature = await this.#signer.signTypedData(
+      domain,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      EIP712_TYPES as any,
+      { method, path: signedPath, timestamp: BigInt(timestamp), nonce },
+    );
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "X-Remit-Agent": this.#signer.getAddress(),
+      "X-Remit-Signature": signature,
+      "X-Remit-Timestamp": String(timestamp),
+      "X-Remit-Nonce": nonce,
+    };
+
+    if (method === "POST" || method === "PUT" || method === "PATCH") {
+      headers["X-Idempotency-Key"] = newIdempotencyKey();
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+    } catch (err) {
+      throw new NetworkError(`Network request failed: ${String(err)}`);
+    }
+
+    if (response.ok) {
+      if (response.status === 204) return undefined as T;
+      return camelizeKeys(await response.json()) as T;
+    }
+
+    // Retryable errors
+    if (RETRYABLE.has(response.status) && attempt < DELAY_MS.length) {
+      if (response.status === 429) {
+        // Respect Retry-After header if present
+        const retryAfter = response.headers.get("Retry-After");
+        const delay = retryAfter ? parseInt(retryAfter) * 1000 : DELAY_MS[attempt];
+        await sleep(delay);
+      } else {
+        await sleep(DELAY_MS[attempt]);
+      }
+      return this.#request<T>(method, path, body, attempt + 1);
+    }
+
+    // Parse error body
+    let errorBody: ApiErrorBody = {};
+    try {
+      errorBody = (await response.json()) as ApiErrorBody;
+    } catch {
+      // ignore parse failures
+    }
+
+    const code =
+      errorBody.error?.code ?? errorBody.code ?? `HTTP_${response.status}`;
+    const message =
+      errorBody.error?.message ?? errorBody.message ?? response.statusText;
+
+    if (response.status === 429) throw new RateLimitedError(message);
+    throw fromErrorCode(code, message);
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+// A2A / AP2
+export {
+  discoverAgent,
+  A2AClient,
+  getTaskTxHash,
+} from "./a2a.js";
+export type {
+  AgentCard,
+  A2ACapabilities,
+  A2AExtension,
+  A2ASkill,
+  A2AX402,
+  A2AFees,
+  A2ATask,
+  A2ATaskStatus,
+  A2AArtifact,
+  A2AArtifactPart,
+  IntentMandate,
+  SendOptions,
+  A2AClientOptions,
+} from "./a2a.js";
+
+// Core classes
+export { RemitClient } from "./client.js";
+export { Wallet } from "./wallet.js";
+export type {
+  WalletOptions,
+  OpenTabOptions,
+  CloseTabOptions,
+  ChargeTabOptions,
+  OpenStreamOptions,
+  PostBountyOptions,
+  PlaceDepositOptions,
+  PermitSignature,
+  SignPermitOptions,
+} from "./wallet.js";
+
+// Signers
+export { PrivateKeySigner } from "./signer.js";
+export type { Signer, TypedDataDomain, TypedDataTypes } from "./signer.js";
+
+// Errors
+export {
+  RemitError,
+  fromErrorCode,
+  InvalidSignatureError,
+  NonceReusedError,
+  TimestampExpiredError,
+  UnauthorizedError,
+  InsufficientBalanceError,
+  BelowMinimumError,
+  EscrowNotFoundError,
+  EscrowAlreadyFundedError,
+  EscrowExpiredError,
+  InvalidInvoiceError,
+  DuplicateInvoiceError,
+  SelfPaymentError,
+  InvalidPaymentTypeError,
+  TabDepletedError,
+  TabExpiredError,
+  TabNotFoundError,
+  StreamNotFoundError,
+  RateExceedsCapError,
+  BountyExpiredError,
+  BountyClaimedError,
+  BountyMaxAttemptsError,
+  BountyNotFoundError,
+  ChainMismatchError,
+  ChainUnsupportedError,
+  RateLimitedError,
+  CancelBlockedClaimStartError,
+  CancelBlockedEvidenceError,
+  VersionMismatchError,
+  NetworkError,
+} from "./errors.js";
+
+// Models
+export * from "./models/index.js";
+
+// Testing utilities
+export { MockRemit, MockWallet } from "./testing/mock.js";
+export { LocalChain } from "./testing/local.js";
+
+// x402 client middleware
+export { X402Client, AllowanceExceededError } from "./x402.js";
+export type { X402ClientOptions } from "./x402.js";
+
+// x402 provider middleware
+export { X402Paywall } from "./provider.js";
+export type { PaywallOptions, CheckResult } from "./provider.js";
+
+// Integrations
+export { remitTools } from "./integrations/vercel-ai.js";
+export type { RemitToolDescriptor } from "./integrations/vercel-ai.js";