@selat-ai/router-client 0.1.0

package/dist/index.js

@@ -0,0 +1,555 @@
+// src/errors/index.ts
+var RouterSdkError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RouterSdkError";
+  }
+};
+var QuoteParseError = class extends RouterSdkError {
+  constructor(message) {
+    super(message);
+    this.name = "QuoteParseError";
+  }
+};
+var RouterClientConfigError = class extends RouterSdkError {
+  constructor(message) {
+    super(message);
+    this.name = "RouterClientConfigError";
+  }
+};
+
+// src/protocols/circleNanopaymentPayloadBuilder.ts
+import { BatchEvmScheme, CHAIN_CONFIGS } from "@circle-fin/x402-batching/client";
+function selectGatewayWalletBatchedOption(quote, chain) {
+  const expectedNetwork = `eip155:${CHAIN_CONFIGS[chain].chain.id}`;
+  const selected = quote.accepts.find((accept) => {
+    const extraName = typeof accept.extra?.name === "string" ? accept.extra.name : void 0;
+    return accept.scheme === "exact" && accept.network === expectedNetwork && extraName === "GatewayWalletBatched";
+  });
+  if (!selected) {
+    throw new QuoteParseError(
+      `no GatewayWalletBatched accept for ${expectedNetwork}; available networks: ${quote.accepts.map((item) => item.network).join(",")}`
+    );
+  }
+  return selected;
+}
+var CircleNanopaymentPayloadBuilder = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async build(challenge) {
+    const selected = selectGatewayWalletBatchedOption(challenge, this.options.chain);
+    if (typeof this.options.signer.circleAgentWalletProcessor === "function") {
+      const verifyingContract = typeof selected.extra?.verifyingContract === "string" ? selected.extra.verifyingContract : void 0;
+      const version = typeof selected.extra?.version === "string" ? selected.extra.version : void 0;
+      await this.options.signer.circleAgentWalletProcessor({
+        chainId: CHAIN_CONFIGS[this.options.chain].chain.id,
+        ...verifyingContract ? { verifyingContract } : {},
+        ...version ? { version } : {}
+      });
+    }
+    const batchScheme = new BatchEvmScheme({
+      address: this.options.signer.address,
+      signTypedData: async (params) => this.options.signer.signTypedData(params)
+    });
+    const paymentPayload = await batchScheme.createPaymentPayload(challenge.x402Version, {
+      scheme: selected.scheme,
+      network: selected.network,
+      asset: selected.asset,
+      amount: selected.amount,
+      payTo: selected.payTo,
+      maxTimeoutSeconds: selected.maxTimeoutSeconds,
+      ...selected.extra ? { extra: selected.extra } : {}
+    });
+    const paymentSignature = Buffer.from(
+      JSON.stringify({
+        ...paymentPayload,
+        ...challenge.resource ? { resource: challenge.resource } : {},
+        accepted: selected
+      })
+    ).toString("base64");
+    return { paymentSignature };
+  }
+};
+
+// src/quote/QuoteParser.ts
+var ROUTER_QUOTE_TTL_SECONDS = 60;
+var QUOTE_TTL_SAFETY_SKEW_SECONDS = 5;
+var LOCAL_QUOTE_TTL_MS = (ROUTER_QUOTE_TTL_SECONDS - QUOTE_TTL_SAFETY_SKEW_SECONDS) * 1e3;
+function parsePaymentRequiredHeader(headerValue) {
+  let decoded;
+  try {
+    decoded = Buffer.from(headerValue, "base64").toString("utf8");
+  } catch {
+    throw new QuoteParseError("failed to base64 decode payment-required header");
+  }
+  let payload;
+  try {
+    payload = JSON.parse(decoded);
+  } catch {
+    throw new QuoteParseError("failed to parse payment-required header as JSON");
+  }
+  const rawVersion = payload.x402Version;
+  const x402Version = typeof rawVersion === "number" && Number.isFinite(rawVersion) ? rawVersion : 2;
+  const resource = typeof payload.resource === "object" && payload.resource !== null ? payload.resource : void 0;
+  const rawAccepts = Array.isArray(payload.accepts) ? payload.accepts : [];
+  const accepts = rawAccepts.map((entry) => {
+    if (typeof entry !== "object" || entry === null) {
+      return void 0;
+    }
+    const record = entry;
+    const scheme = typeof record.scheme === "string" ? record.scheme : void 0;
+    const network = typeof record.network === "string" ? record.network : void 0;
+    const asset = typeof record.asset === "string" ? record.asset : void 0;
+    const amount = typeof record.amount === "string" ? record.amount : void 0;
+    const payTo = typeof record.payTo === "string" ? record.payTo : void 0;
+    const maxTimeoutSeconds = typeof record.maxTimeoutSeconds === "number" ? record.maxTimeoutSeconds : void 0;
+    const extra = typeof record.extra === "object" && record.extra !== null ? record.extra : void 0;
+    if (!scheme || !network || !asset || !amount || !payTo || maxTimeoutSeconds === void 0) {
+      return void 0;
+    }
+    return {
+      scheme,
+      network,
+      asset,
+      amount,
+      payTo,
+      maxTimeoutSeconds,
+      ...extra ? { extra } : {}
+    };
+  }).filter((item) => item !== void 0);
+  if (accepts.length === 0) {
+    throw new QuoteParseError("payment-required header has no valid accepts");
+  }
+  return resource ? {
+    x402Version,
+    resource,
+    accepts
+  } : {
+    x402Version,
+    accepts
+  };
+}
+var QuoteParser = class {
+  async parse(response) {
+    if (response.status !== 402) {
+      return null;
+    }
+    const quoteId = response.headers.get("x-selat-quote-id");
+    if (!quoteId) {
+      throw new QuoteParseError("missing x-selat-quote-id in 402 response");
+    }
+    const paymentRequiredHeader = response.headers.get("payment-required");
+    if (!paymentRequiredHeader) {
+      throw new QuoteParseError("missing payment-required header in 402 response");
+    }
+    const parsed = parsePaymentRequiredHeader(paymentRequiredHeader);
+    const expiresAt = Date.now() + LOCAL_QUOTE_TTL_MS;
+    return {
+      quoteId,
+      expiresAt,
+      x402Version: parsed.x402Version,
+      ...parsed.resource ? { resource: parsed.resource } : {},
+      accepts: parsed.accepts
+    };
+  }
+};
+
+// src/signers/createViemSigner.ts
+import { privateKeyToAccount } from "viem/accounts";
+function createViemSigner(privateKey) {
+  const account = privateKeyToAccount(privateKey);
+  return {
+    address: account.address,
+    signTypedData: async (params) => account.signTypedData(params)
+  };
+}
+
+// src/client/RouterClient.ts
+var DEFAULT_ROUTER_URL = "https://router.selat.ai";
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function toHeaders(base, override) {
+  const headers = new Headers(base);
+  if (override) {
+    new Headers(override).forEach((value, key) => headers.set(key, value));
+  }
+  return headers;
+}
+function toRouterProxyUrl(routerUrl, targetUrl) {
+  const proxyUrl = new URL("/proxy", routerUrl);
+  proxyUrl.searchParams.set("target", targetUrl);
+  return proxyUrl.toString();
+}
+function withSignal(init, signal) {
+  if (!signal) {
+    return init;
+  }
+  return {
+    ...init,
+    signal
+  };
+}
+function createRequestSignal(callerSignal, requestTimeoutMs) {
+  const timeoutController = new AbortController();
+  const timeoutId = setTimeout(() => timeoutController.abort(), requestTimeoutMs);
+  const timeoutSignal = timeoutController.signal;
+  if (!callerSignal) {
+    return {
+      signal: timeoutSignal,
+      cleanup: () => clearTimeout(timeoutId)
+    };
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  const cleanup = () => {
+    clearTimeout(timeoutId);
+    callerSignal.removeEventListener("abort", abort);
+    timeoutSignal.removeEventListener("abort", abort);
+  };
+  if (callerSignal.aborted || timeoutSignal.aborted) {
+    cleanup();
+    controller.abort();
+    return {
+      signal: controller.signal,
+      cleanup
+    };
+  }
+  callerSignal.addEventListener("abort", abort);
+  timeoutSignal.addEventListener("abort", abort);
+  return {
+    signal: controller.signal,
+    cleanup
+  };
+}
+var RouterClient = class {
+  constructor(options) {
+    this.options = options;
+    this.routerUrl = options.routerUrl ?? DEFAULT_ROUTER_URL;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    if (!options.chain) {
+      throw new RouterClientConfigError(
+        "chain is required"
+      );
+    }
+    const signer = options.signer ?? (() => {
+      if (!options.privateKey) {
+        return void 0;
+      }
+      return createViemSigner(options.privateKey);
+    })();
+    if (!signer) {
+      throw new RouterClientConfigError(
+        "Provide either signer, or privateKey (with chain) for Circle nanopayments"
+      );
+    }
+    this.paymentPayloadBuilder = new CircleNanopaymentPayloadBuilder({
+      chain: options.chain,
+      signer
+    });
+  }
+  options;
+  quoteParser = new QuoteParser();
+  routerUrl;
+  requestTimeoutMs;
+  paymentPayloadBuilder;
+  createFetch(config) {
+    return (path, init) => this.fetch(new URL(path, config.baseUrl).toString(), init);
+  }
+  async fetch(input, init) {
+    const { preferProtocol, ...requestInit } = init ?? {};
+    const proxyUrl = toRouterProxyUrl(this.routerUrl, input);
+    const firstHeaders = toHeaders(this.options.defaultHeaders ?? {}, requestInit.headers);
+    firstHeaders.set("x-selat-prefer-protocol", preferProtocol ?? "mpp");
+    const firstRequest = createRequestSignal(requestInit.signal ?? void 0, this.requestTimeoutMs);
+    let firstResponse;
+    try {
+      firstResponse = await fetch(proxyUrl, withSignal({
+        ...requestInit,
+        headers: firstHeaders
+      }, firstRequest.signal));
+    } finally {
+      firstRequest.cleanup();
+    }
+    const challenge = await this.quoteParser.parse(firstResponse.clone());
+    if (!challenge) {
+      return firstResponse;
+    }
+    const payment = await this.paymentPayloadBuilder.build(challenge);
+    const paidHeaders = firstHeaders;
+    paidHeaders.set("PAYMENT-SIGNATURE", payment.paymentSignature);
+    paidHeaders.set("x-selat-quote-id", challenge.quoteId);
+    const paidRequest = createRequestSignal(requestInit.signal ?? void 0, this.requestTimeoutMs);
+    try {
+      return await fetch(proxyUrl, withSignal({
+        ...requestInit,
+        headers: paidHeaders
+      }, paidRequest.signal));
+    } finally {
+      paidRequest.cleanup();
+    }
+  }
+};
+
+// src/signers/createRemoteSigner.ts
+function createRemoteSigner(address, requester) {
+  return {
+    address,
+    signTypedData: async (params) => requester({ address, typedData: params })
+  };
+}
+
+// src/signers/createCircleAgentWalletSigner.ts
+import { spawn } from "child_process";
+import { recoverTypedDataAddress } from "viem";
+var DEFAULT_CIRCLE_CLI_COMMAND = "circle";
+var DEFAULT_CIRCLE_CLI_TIMEOUT_MS = 3e4;
+function toCliChain(chain) {
+  switch (chain) {
+    case "base":
+      return "BASE";
+    case "ethereum":
+      return "ETHEREUM";
+    case "avalanche":
+      return "AVALANCHE";
+    case "optimism":
+      return "OPTIMISM";
+    case "polygon":
+      return "POLYGON";
+    default:
+      return chain.toUpperCase();
+  }
+}
+function stringifySafeJson(value) {
+  return JSON.stringify(value, (_key, item) => {
+    if (typeof item !== "bigint") {
+      return item;
+    }
+    if (item <= BigInt(Number.MAX_SAFE_INTEGER) && item >= BigInt(Number.MIN_SAFE_INTEGER)) {
+      return Number(item);
+    }
+    return item.toString();
+  });
+}
+function ensureEip712DomainTypeForCircleCli(typedData) {
+  if (!typedData || typeof typedData !== "object") {
+    return typedData;
+  }
+  const root = typedData;
+  const domain = root.domain;
+  const types = root.types;
+  if (!domain || typeof domain !== "object" || !types || typeof types !== "object") {
+    return typedData;
+  }
+  const typesRecord = types;
+  if (Array.isArray(typesRecord.EIP712Domain)) {
+    return typedData;
+  }
+  const domainRecord = domain;
+  const eip712Domain = [];
+  if (typeof domainRecord.name === "string") {
+    eip712Domain.push({ name: "name", type: "string" });
+  }
+  if (typeof domainRecord.version === "string") {
+    eip712Domain.push({ name: "version", type: "string" });
+  }
+  if (typeof domainRecord.chainId === "number" || typeof domainRecord.chainId === "bigint" || typeof domainRecord.chainId === "string") {
+    eip712Domain.push({ name: "chainId", type: "uint256" });
+  }
+  if (typeof domainRecord.verifyingContract === "string") {
+    eip712Domain.push({ name: "verifyingContract", type: "address" });
+  }
+  if (typeof domainRecord.salt === "string") {
+    eip712Domain.push({ name: "salt", type: "bytes32" });
+  }
+  return {
+    ...root,
+    types: {
+      EIP712Domain: eip712Domain,
+      ...typesRecord
+    }
+  };
+}
+function normalizeAddress(address) {
+  return address.toLowerCase();
+}
+function extractHexSignature(text) {
+  const matches = text.match(/0x[0-9a-fA-F]{130}/g);
+  if (!matches || matches.length === 0) {
+    return null;
+  }
+  return matches[matches.length - 1];
+}
+async function ensureSignatureMatchesExpectedAddress(typedData, signature, fallbackExpectedAddress) {
+  try {
+    const typedDataRecord = typedData;
+    const message = typedDataRecord.message;
+    const expectedAddress = typeof message?.from === "string" ? normalizeAddress(message.from) : fallbackExpectedAddress;
+    const recoveredAddress = await recoverTypedDataAddress({
+      ...typedDataRecord,
+      signature
+    });
+    if (normalizeAddress(recoveredAddress) !== normalizeAddress(expectedAddress)) {
+      throw new Error(
+        `Circle CLI produced a signature for ${recoveredAddress}, but expected ${expectedAddress}. This commonly happens when an outdated Circle CLI is used or when the selected wallet signs as a different key model. Upgrade @circle-fin/cli and verify the wallet address with \`circle wallet list --chain <CHAIN>\` before running the SDK.`
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("Circle CLI produced a signature")) {
+      throw error;
+    }
+  }
+}
+async function signTypedDataWithCircleCli(command, timeoutMs, address, chain, typedData, options) {
+  const normalizedTypedData = ensureEip712DomainTypeForCircleCli(typedData);
+  const typedDataJson = stringifySafeJson(normalizedTypedData);
+  const args = [
+    "wallet",
+    "sign",
+    "typed-data",
+    typedDataJson,
+    "--address",
+    address,
+    "--chain",
+    toCliChain(chain)
+  ];
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      shell: false,
+      windowsHide: true
+    });
+    let stdout = "";
+    let stderr = "";
+    const timeout = setTimeout(() => {
+      child.kill();
+      reject(new Error(`Circle CLI signing timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      clearTimeout(timeout);
+      const message = error instanceof Error ? error.message : String(error);
+      reject(
+        new Error(
+          `Failed to execute Circle CLI ("${command}"): ${message}. Ensure @circle-fin/cli is installed and authenticated.`
+        )
+      );
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      if (code !== 0) {
+        const details = stderr.trim() || stdout.trim() || `exit code ${code}`;
+        reject(new Error(`Circle CLI signing failed: ${details}`));
+        return;
+      }
+      const signature = extractHexSignature(stdout);
+      if (!signature) {
+        reject(new Error(`Circle CLI output did not contain a valid signature: ${stdout.trim()}`));
+        return;
+      }
+      if (options?.skipSignatureAddressCheck) {
+        resolve(signature);
+        return;
+      }
+      ensureSignatureMatchesExpectedAddress(normalizedTypedData, signature, address).then(() => resolve(signature)).catch((error) => reject(error instanceof Error ? error : new Error(String(error))));
+    });
+  });
+}
+var GATEWAY_AUTH_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" }
+  ]
+};
+async function resolveGatewaySignerAddress(command, timeoutMs, walletAddress, chain, input) {
+  if (!input.verifyingContract) {
+    return walletAddress;
+  }
+  const typedData = {
+    domain: {
+      name: "GatewayWalletBatched",
+      version: input.version ?? "1",
+      chainId: input.chainId,
+      verifyingContract: input.verifyingContract
+    },
+    primaryType: "TransferWithAuthorization",
+    types: GATEWAY_AUTH_TYPES,
+    message: {
+      from: walletAddress,
+      to: "0x0000000000000000000000000000000000000000",
+      value: 0,
+      validAfter: 0,
+      validBefore: 0,
+      nonce: "0x" + "0".repeat(64)
+    }
+  };
+  const probeSignature = await signTypedDataWithCircleCli(
+    command,
+    timeoutMs,
+    walletAddress,
+    chain,
+    typedData,
+    { skipSignatureAddressCheck: true }
+  );
+  const owner = await recoverTypedDataAddress({
+    ...typedData,
+    signature: probeSignature
+  });
+  return normalizeAddress(owner);
+}
+function createCircleAgentWalletSigner(options) {
+  const command = options.cliCommand ?? DEFAULT_CIRCLE_CLI_COMMAND;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_CIRCLE_CLI_TIMEOUT_MS;
+  const walletAddress = normalizeAddress(options.address);
+  let effectiveAddress = walletAddress;
+  let resolvedOwnerAddress = null;
+  let resolveOwnerAddressInFlight = null;
+  const resolveOwnerAddress = async (input) => {
+    if (!input.verifyingContract) {
+      return walletAddress;
+    }
+    if (resolvedOwnerAddress) {
+      return resolvedOwnerAddress;
+    }
+    if (!resolveOwnerAddressInFlight) {
+      resolveOwnerAddressInFlight = resolveGatewaySignerAddress(command, timeoutMs, walletAddress, options.chain, input).then((owner2) => {
+        resolvedOwnerAddress = owner2;
+        effectiveAddress = owner2;
+        return owner2;
+      }).finally(() => {
+        resolveOwnerAddressInFlight = null;
+      });
+    }
+    const owner = await resolveOwnerAddressInFlight;
+    resolvedOwnerAddress = owner;
+    effectiveAddress = owner;
+    return owner;
+  };
+  return {
+    get address() {
+      return effectiveAddress;
+    },
+    circleAgentWalletProcessor: async (input) => {
+      await resolveOwnerAddress(input);
+    },
+    signTypedData: async (typedData) => signTypedDataWithCircleCli(command, timeoutMs, walletAddress, options.chain, typedData)
+  };
+}
+export {
+  CircleNanopaymentPayloadBuilder,
+  QuoteParseError,
+  RouterClient,
+  RouterClientConfigError,
+  RouterSdkError,
+  createCircleAgentWalletSigner,
+  createRemoteSigner,
+  createViemSigner
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@selat-ai/router-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for interacting with SELATA Router.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "example": "tsx examples/pay-with-selat.ts",
+    "prepublishOnly": "pnpm run clean && pnpm run build"
+  },
+  "keywords": [
+    "selat",
+    "router",
+    "x402",
+    "mpp",
+    "payments",
+    "circle",
+    "nanopayments"
+  ],
+  "dependencies": {
+    "@circle-fin/x402-batching": "^3.1.2",
+    "viem": "^2.48.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "dotenv": "^17.2.1",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.21.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}