@relai-fi/x402 0.5.8 → 0.5.10

package/dist/client.js

@@ -96,12 +96,32 @@ function createX402Client(config) {
     wallets = {},
     wallet: legacyWallet,
     facilitatorUrl = RELAI_FACILITATOR_URL,
+    relayWs,
     preferredNetwork,
     solanaRpcUrl = "https://api.mainnet-beta.solana.com",
     evmRpcUrls = {},
     maxAmountAtomic,
+    integritas,
     verbose = false
   } = config;
+  const relayWsEnabled = relayWs?.enabled === true;
+  const relayWsPreflightTimeoutMs = relayWs?.preflightTimeoutMs ?? 5e3;
+  const relayWsPaymentTimeoutMs = relayWs?.paymentTimeoutMs ?? 1e4;
+  const relayWsFallbackToHttp = relayWs?.fallbackToHttp ?? true;
+  const defaultIntegritas = normalizeIntegritasOptions(integritas);
+  const relayWsReservedSubdomains = /* @__PURE__ */ new Set([
+    "www",
+    "api",
+    "localhost",
+    "admin",
+    "app",
+    "dashboard",
+    "docs",
+    "documentation",
+    "status",
+    "blog",
+    "facilitator"
+  ]);
   const log = verbose ? console.log.bind(console, "[relai-x402]") : () => {
   };
   const effectiveWallets = { ...wallets };
@@ -112,6 +132,408 @@ function createX402Client(config) {
     effectiveWallets.solana?.publicKey && effectiveWallets.solana?.signTransaction
   );
   if (hasSolanaWallet) log("Solana wallet ready");
+  function isRecord(value) {
+    return typeof value === "object" && value !== null;
+  }
+  function parseJsonSafe(value) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  function addSocketListener(socket, eventName, listener) {
+    if (socket.addEventListener) {
+      socket.addEventListener(eventName, listener);
+      return;
+    }
+    if (socket.on) {
+      socket.on(eventName, listener);
+    }
+  }
+  function removeSocketListener(socket, eventName, listener) {
+    if (socket.removeEventListener) {
+      socket.removeEventListener(eventName, listener);
+      return;
+    }
+    if (socket.off) {
+      socket.off(eventName, listener);
+      return;
+    }
+    if (socket.removeListener) {
+      socket.removeListener(eventName, listener);
+    }
+  }
+  function resolveRelayWsUrl(relayUrl) {
+    if (relayWs?.wsUrl && relayWs.wsUrl.trim() !== "") {
+      return relayWs.wsUrl.trim();
+    }
+    const parsedRelayUrl = new URL(relayUrl);
+    const wsProtocol = parsedRelayUrl.protocol === "https:" ? "wss:" : "ws:";
+    return `${wsProtocol}//${parsedRelayUrl.host}/api/ws/relay`;
+  }
+  function resolveRelayWhitelabel(parsedRelayUrl) {
+    const hostParts = parsedRelayUrl.hostname.toLowerCase().split(".").filter(Boolean);
+    if (hostParts.length < 2) {
+      return null;
+    }
+    const candidate = decodeURIComponent(hostParts[0] || "").trim();
+    if (!candidate) {
+      return null;
+    }
+    if (relayWsReservedSubdomains.has(candidate.toLowerCase())) {
+      return null;
+    }
+    const lastPart = hostParts[hostParts.length - 1];
+    const secondLastPart = hostParts[hostParts.length - 2];
+    const isX402WhitelabelHost = hostParts.length >= 3 && secondLastPart === "x402" && lastPart === "fi";
+    const isLocalWhitelabelHost = hostParts.length === 2 && lastPart === "localhost";
+    if (!isX402WhitelabelHost && !isLocalWhitelabelHost) {
+      return null;
+    }
+    return candidate;
+  }
+  function resolveRelayTarget(relayUrl) {
+    const parsedRelayUrl = new URL(relayUrl);
+    const match = parsedRelayUrl.pathname.match(/\/relay\/([^/]+)(\/.*)?$/);
+    if (match) {
+      const apiId = decodeURIComponent(match[1]);
+      const pathPart2 = match[2] || "/";
+      return {
+        apiId,
+        path: `${pathPart2}${parsedRelayUrl.search || ""}`
+      };
+    }
+    const whitelabel = resolveRelayWhitelabel(parsedRelayUrl);
+    if (!whitelabel) {
+      throw new Error(
+        `[relai-x402] Unsupported relay URL format for WS transport: ${relayUrl}. Expected /relay/:apiId/... or <whitelabel>.x402.fi/...`
+      );
+    }
+    const pathPart = parsedRelayUrl.pathname && parsedRelayUrl.pathname !== "" ? parsedRelayUrl.pathname : "/";
+    return {
+      apiId: whitelabel,
+      path: `${pathPart}${parsedRelayUrl.search || ""}`
+    };
+  }
+  function isRelayRequestUrl(requestUrl) {
+    try {
+      resolveRelayTarget(requestUrl);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function headersToRecord(headersInit) {
+    if (!headersInit) return {};
+    const output = {};
+    if (typeof Headers !== "undefined" && headersInit instanceof Headers) {
+      headersInit.forEach((value, key) => {
+        output[key] = value;
+      });
+      return output;
+    }
+    if (Array.isArray(headersInit)) {
+      for (const [key, value] of headersInit) {
+        output[key] = value;
+      }
+      return output;
+    }
+    for (const [key, value] of Object.entries(headersInit)) {
+      if (typeof value === "string") {
+        output[key] = value;
+      } else if (Array.isArray(value)) {
+        output[key] = value.join(", ");
+      } else if (value !== void 0 && value !== null) {
+        output[key] = String(value);
+      }
+    }
+    return output;
+  }
+  function hasHeaderCaseInsensitive(headers, headerName) {
+    const normalized = headerName.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+  }
+  function normalizeIntegritasFlow(value) {
+    const normalized = String(value || "").trim().toLowerCase();
+    if (normalized === "single") return "single";
+    if (normalized === "dual") return "dual";
+    return void 0;
+  }
+  function normalizeIntegritasOptions(value) {
+    if (value === true) return { enabled: true };
+    if (value === false || value == null) return { enabled: false };
+    const flow = normalizeIntegritasFlow(value.flow);
+    const enabled = typeof value.enabled === "boolean" ? value.enabled : true;
+    return {
+      enabled,
+      ...flow ? { flow } : {}
+    };
+  }
+  function resolveIntegritasOptions(override) {
+    if (override === void 0) {
+      return defaultIntegritas;
+    }
+    if (typeof override === "boolean") {
+      return {
+        enabled: override,
+        ...override && defaultIntegritas.flow ? { flow: defaultIntegritas.flow } : {}
+      };
+    }
+    const flow = normalizeIntegritasFlow(override.flow) || defaultIntegritas.flow;
+    const enabled = typeof override.enabled === "boolean" ? override.enabled : defaultIntegritas.enabled;
+    return {
+      enabled,
+      ...enabled && flow ? { flow } : {}
+    };
+  }
+  function stripInternalInit(init) {
+    if (!init) return void 0;
+    const { x402: _x402, ...requestInit } = init;
+    return requestInit;
+  }
+  function applyIntegritasHeaders(headers, options) {
+    if (!options.enabled) return headers;
+    if (!hasHeaderCaseInsensitive(headers, "x-integritas")) {
+      headers["X-Integritas"] = "true";
+    }
+    if (options.flow && !hasHeaderCaseInsensitive(headers, "x-integritas-flow")) {
+      headers["X-Integritas-Flow"] = options.flow;
+    }
+    return headers;
+  }
+  function getRequestMethod(input, init) {
+    const inputMethod = input instanceof Request ? input.method : void 0;
+    return (init?.method || inputMethod || "GET").toUpperCase();
+  }
+  async function bodyInitToWsPayload(bodyInit) {
+    if (bodyInit === void 0 || bodyInit === null) {
+      return void 0;
+    }
+    if (typeof bodyInit === "string") {
+      const parsed = parseJsonSafe(bodyInit);
+      return parsed === null ? bodyInit : parsed;
+    }
+    if (typeof URLSearchParams !== "undefined" && bodyInit instanceof URLSearchParams) {
+      return bodyInit.toString();
+    }
+    if (typeof FormData !== "undefined" && bodyInit instanceof FormData) {
+      const entries = {};
+      for (const [key, value] of bodyInit.entries()) {
+        entries[key] = typeof value === "string" ? value : value.name;
+      }
+      return entries;
+    }
+    if (typeof Blob !== "undefined" && bodyInit instanceof Blob) {
+      const text = await bodyInit.text();
+      if (!text) return void 0;
+      const parsed = parseJsonSafe(text);
+      return parsed === null ? text : parsed;
+    }
+    if (bodyInit instanceof ArrayBuffer) {
+      return Array.from(new Uint8Array(bodyInit));
+    }
+    if (ArrayBuffer.isView(bodyInit)) {
+      return Array.from(new Uint8Array(bodyInit.buffer, bodyInit.byteOffset, bodyInit.byteLength));
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(bodyInit)) {
+      return Array.from(bodyInit.values());
+    }
+    if (isRecord(bodyInit)) {
+      return bodyInit;
+    }
+    return String(bodyInit);
+  }
+  async function resolveRequestBody(input, init) {
+    if (init && Object.prototype.hasOwnProperty.call(init, "body")) {
+      return bodyInitToWsPayload(init.body);
+    }
+    if (input instanceof Request) {
+      const method = getRequestMethod(input, init);
+      if (method === "GET" || method === "HEAD") {
+        return void 0;
+      }
+      try {
+        const cloned = input.clone();
+        const text = await cloned.text();
+        if (!text) return void 0;
+        const parsed = parseJsonSafe(text);
+        return parsed === null ? text : parsed;
+      } catch {
+        return void 0;
+      }
+    }
+    return void 0;
+  }
+  function getRequestHeaders(input, init) {
+    const fromInput = input instanceof Request ? headersToRecord(input.headers) : {};
+    const fromInit = headersToRecord(init?.headers);
+    const merged = {
+      ...fromInput,
+      ...fromInit
+    };
+    if (!merged.Accept && !merged.accept) {
+      merged.Accept = "application/json";
+    }
+    return merged;
+  }
+  function toMessageString(data) {
+    if (typeof data === "string") {
+      return data;
+    }
+    if (isRecord(data) && typeof data.data !== "undefined") {
+      return toMessageString(data.data);
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(data)) {
+      return data.toString("utf8");
+    }
+    if (data instanceof ArrayBuffer) {
+      const bytes = new Uint8Array(data);
+      if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("utf8");
+      }
+      if (typeof TextDecoder !== "undefined") {
+        return new TextDecoder().decode(bytes);
+      }
+      throw new Error("Unsupported WebSocket message data type");
+    }
+    if (ArrayBuffer.isView(data)) {
+      const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+      if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("utf8");
+      }
+      if (typeof TextDecoder !== "undefined") {
+        return new TextDecoder().decode(bytes);
+      }
+      throw new Error("Unsupported WebSocket message data type");
+    }
+    throw new Error("Unsupported WebSocket message data type");
+  }
+  function getWebSocketFactory() {
+    if (relayWs?.webSocketFactory) {
+      return relayWs.webSocketFactory;
+    }
+    if (typeof WebSocket !== "undefined") {
+      return (wsUrl) => new WebSocket(wsUrl);
+    }
+    throw new Error(
+      "[relai-x402] WebSocket is not available in this runtime. Provide relayWs.webSocketFactory."
+    );
+  }
+  async function relayCallOverWebSocket(request) {
+    const wsFactory = getWebSocketFactory();
+    const wsUrl = resolveRelayWsUrl(request.relayUrl);
+    const target = resolveRelayTarget(request.relayUrl);
+    const requestId = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const socket = wsFactory(wsUrl);
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const settleResolve = (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        try {
+          socket.close();
+        } catch {
+        }
+        resolve(value);
+      };
+      const settleReject = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        try {
+          socket.close();
+        } catch {
+        }
+        reject(error);
+      };
+      const timeoutId = setTimeout(() => {
+        settleReject(new Error(`[relai-x402] Timed out waiting for WS relay response after ${request.timeoutMs}ms`));
+      }, request.timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        removeSocketListener(socket, "open", onOpen);
+        removeSocketListener(socket, "message", onMessage);
+        removeSocketListener(socket, "error", onError);
+        removeSocketListener(socket, "close", onClose);
+      };
+      const onOpen = () => {
+        const envelope = {
+          id: requestId,
+          method: "relay.call",
+          params: {
+            apiId: target.apiId,
+            path: target.path,
+            requestMethod: request.requestMethod,
+            requestHeaders: request.requestHeaders,
+            ...request.requestBody !== void 0 ? { requestBody: request.requestBody } : {}
+          }
+        };
+        if (request.paymentPayload !== void 0) {
+          envelope.payment = request.paymentPayload;
+        }
+        try {
+          socket.send(JSON.stringify(envelope));
+        } catch {
+          settleReject(new Error("[relai-x402] Failed to send WS relay request"));
+        }
+      };
+      const onMessage = (...args) => {
+        const payload = args.length > 0 ? args[0] : void 0;
+        let parsed;
+        try {
+          parsed = parseJsonSafe(toMessageString(payload));
+        } catch {
+          return;
+        }
+        if (!isRecord(parsed)) return;
+        const responseId = typeof parsed.id === "string" || typeof parsed.id === "number" ? String(parsed.id) : "";
+        if (responseId !== requestId) return;
+        settleResolve(parsed);
+      };
+      const onError = () => {
+        settleReject(new Error("[relai-x402] WebSocket relay transport error"));
+      };
+      const onClose = () => {
+        settleReject(new Error("[relai-x402] WebSocket relay connection closed before response"));
+      };
+      addSocketListener(socket, "open", onOpen);
+      addSocketListener(socket, "message", onMessage);
+      addSocketListener(socket, "error", onError);
+      addSocketListener(socket, "close", onClose);
+    });
+  }
+  function extractPaymentRequirementsFromWsError(error) {
+    const candidates = [error.paymentRequired, error.data];
+    for (const candidate of candidates) {
+      if (!isRecord(candidate)) continue;
+      if (Array.isArray(candidate.accepts)) {
+        return candidate;
+      }
+      if (isRecord(candidate.paymentRequired) && Array.isArray(candidate.paymentRequired.accepts)) {
+        return candidate.paymentRequired;
+      }
+      if (isRecord(candidate.data) && Array.isArray(candidate.data.accepts)) {
+        return candidate.data;
+      }
+    }
+    return null;
+  }
+  function buildWsResponse(wsResponse) {
+    const statusFromMetadata = isRecord(wsResponse.metadata) && typeof wsResponse.metadata.status === "number" ? wsResponse.metadata.status : 200;
+    const status = Number.isInteger(statusFromMetadata) && statusFromMetadata >= 100 && statusFromMetadata <= 599 ? statusFromMetadata : 200;
+    const headers = new Headers();
+    headers.set("Content-Type", "application/json");
+    if (wsResponse.paymentResponse !== void 0) {
+      headers.set("PAYMENT-RESPONSE", encodeBase64Json(wsResponse.paymentResponse));
+    }
+    const bodyPayload = wsResponse.result === void 0 ? null : wsResponse.result;
+    return new Response(JSON.stringify(bodyPayload), {
+      status,
+      headers
+    });
+  }
   function selectAccept(accepts) {
     if (preferredNetwork) {
       const caip2 = NETWORK_CAIP2[preferredNetwork];
@@ -223,7 +645,7 @@ function createX402Client(config) {
         amount: paymentAmount
       }
     };
-    return btoa(JSON.stringify(paymentPayload));
+    return encodeBase64Json(paymentPayload);
   }
   async function buildEvmPayment(accept, requirements, url) {
     const evmWallet = effectiveWallets.evm;
@@ -291,7 +713,7 @@ function createX402Client(config) {
       },
       facilitatorUrl
     };
-    return btoa(JSON.stringify(paymentPayload));
+    return encodeBase64Json(paymentPayload);
   }
   async function buildSolanaPayment(accept, requirements, url) {
     const solWallet = effectiveWallets.solana;
@@ -355,7 +777,17 @@ function createX402Client(config) {
         transaction: serializedTx
       }
     };
-    return btoa(JSON.stringify(paymentPayload));
+    return encodeBase64Json(paymentPayload);
+  }
+  function encodeBase64Json(payload) {
+    const serialized = JSON.stringify(payload);
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(serialized, "utf8").toString("base64");
+    }
+    if (typeof btoa !== "undefined") {
+      return btoa(serialized);
+    }
+    throw new Error("[relai-x402] Base64 encoding is not available in this runtime");
   }
   function decodeBase64Json(encoded) {
     try {
@@ -396,7 +828,101 @@ function createX402Client(config) {
   async function x402Fetch(input, init) {
     const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
     log("Request:", url);
-    const response = await fetch(input, init);
+    const requestInit = stripInternalInit(init);
+    const integritasOptions = resolveIntegritasOptions(init?.x402?.integritas);
+    const requestMethod = getRequestMethod(input, requestInit);
+    const requestHeaders = applyIntegritasHeaders(
+      getRequestHeaders(input, requestInit),
+      integritasOptions
+    );
+    const requestInitWithHeaders = {
+      ...requestInit || {},
+      headers: requestHeaders
+    };
+    const requestBody = await resolveRequestBody(input, requestInitWithHeaders);
+    if (relayWsEnabled && isRelayRequestUrl(url)) {
+      let wsPaymentPhaseStarted = false;
+      try {
+        log("Using WebSocket relay transport");
+        const wsPreflightResponse = await relayCallOverWebSocket({
+          relayUrl: url,
+          requestMethod,
+          requestHeaders,
+          requestBody,
+          timeoutMs: relayWsPreflightTimeoutMs
+        });
+        if (!wsPreflightResponse.error) {
+          return buildWsResponse(wsPreflightResponse);
+        }
+        if (Number(wsPreflightResponse.error.code) !== 402) {
+          throw new Error(wsPreflightResponse.error.message || "[relai-x402] WebSocket relay request failed");
+        }
+        const wsRequirements = extractPaymentRequirementsFromWsError(wsPreflightResponse.error);
+        if (!wsRequirements) {
+          throw new Error(
+            wsPreflightResponse.error.message || "[relai-x402] No payment requirements in WS 402 response"
+          );
+        }
+        const wsAccepts = getAccepts(wsRequirements);
+        if (!wsAccepts.length) {
+          throw new Error("[relai-x402] No payment options in WS 402 response");
+        }
+        if (wsAccepts.length > 1) {
+          throw new Error(
+            "[relai-x402] WS relay currently supports a single payment payload; use HTTP flow for multi-accept payments"
+          );
+        }
+        const wsSelected = selectAccept(wsAccepts);
+        if (!wsSelected) {
+          const networks = wsAccepts.map((a) => a.network).join(", ");
+          throw new Error(`[relai-x402] No wallet available for WS networks: ${networks}`);
+        }
+        const { accept: accept2, chain: chain2 } = wsSelected;
+        const amount2 = accept2.amount || accept2.maxAmountRequired;
+        if (maxAmountAtomic && BigInt(amount2) > BigInt(maxAmountAtomic)) {
+          throw new Error(`[relai-x402] Amount ${amount2} exceeds max ${maxAmountAtomic}`);
+        }
+        wsPaymentPhaseStarted = true;
+        let paymentHeader = null;
+        if (chain2 === "solana" && hasSolanaWallet) {
+          paymentHeader = await buildSolanaPayment(accept2, wsRequirements, url);
+        } else if (chain2 === "evm") {
+          const evmNetwork = normalizeNetwork(accept2.network || "");
+          const usePermit = evmNetwork && PERMIT_NETWORKS.has(evmNetwork);
+          paymentHeader = usePermit ? await buildEvmPermitPayment(accept2, wsRequirements, url) : await buildEvmPayment(accept2, wsRequirements, url);
+        }
+        if (!paymentHeader) {
+          throw new Error("[relai-x402] Unexpected state - no WS payment handler matched");
+        }
+        const paymentPayload = decodeBase64Json(paymentHeader);
+        if (!paymentPayload) {
+          throw new Error("[relai-x402] Failed to decode payment payload for WS relay call");
+        }
+        const wsPaidResponse = await relayCallOverWebSocket({
+          relayUrl: url,
+          requestMethod,
+          requestHeaders,
+          requestBody,
+          paymentPayload,
+          timeoutMs: relayWsPaymentTimeoutMs
+        });
+        if (wsPaidResponse.error) {
+          throw new Error(wsPaidResponse.error.message || "[relai-x402] WebSocket paid relay request failed");
+        }
+        return buildWsResponse(wsPaidResponse);
+      } catch (wsError) {
+        const wsMessage = wsError instanceof Error ? wsError.message : String(wsError);
+        log("WebSocket relay transport failed:", wsMessage);
+        if (wsPaymentPhaseStarted) {
+          throw wsError instanceof Error ? wsError : new Error(`[relai-x402] ${wsMessage}`);
+        }
+        if (!relayWsFallbackToHttp) {
+          throw wsError instanceof Error ? wsError : new Error(`[relai-x402] ${wsMessage}`);
+        }
+        log("Falling back to HTTP x402 flow");
+      }
+    }
+    const response = await fetch(input, requestInitWithHeaders);
     if (response.status !== 402) return response;
     log("Got 402 Payment Required");
     let requirementsFromBody = null;
@@ -434,9 +960,9 @@ function createX402Client(config) {
       const paymentHeader = await buildSolanaPayment(accept, requirements, url);
       log("Retrying with X-PAYMENT header (Solana)");
       return fetch(input, {
-        ...init,
+        ...requestInitWithHeaders,
         headers: {
-          ...init?.headers || {},
+          ...requestHeaders,
           "X-PAYMENT": paymentHeader
         }
       });
@@ -447,14 +973,14 @@ function createX402Client(config) {
       const paymentHeader = usePermit ? await buildEvmPermitPayment(accept, requirements, url) : await buildEvmPayment(accept, requirements, url);
       log("Retrying with X-PAYMENT header");
       return fetch(input, {
-        ...init,
+        ...requestInitWithHeaders,
         headers: {
-          ...init?.headers || {},
+          ...requestHeaders,
           "X-PAYMENT": paymentHeader
         }
       });
     }
-    throw new Error("[relai-x402] Unexpected state \u2014 no payment handler matched");
+    throw new Error("[relai-x402] Unexpected state - no payment handler matched");
   }
   return { fetch: x402Fetch };
 }