@inflowpayai/x402-buyer 0.5.0

package/dist/index.cjs

@@ -0,0 +1,592 @@
+'use strict';
+
+var client = require('@x402/core/client');
+var extensions = require('@inflowpayai/x402/extensions');
+var x402 = require('@inflowpayai/x402');
+var bs58 = require('bs58');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var bs58__default = /*#__PURE__*/_interopDefault(bs58);
+
+// src/inflow-client.ts
+
+// src/errors.ts
+var X402ApprovalFailedError = class extends Error {
+  /** The approval id the server returned from `POST /v1/transactions/x402`. */
+  approvalId;
+  /** Terminal status reported by the server. */
+  status;
+  /**
+   * @param approvalId - Server-issued approval id.
+   * @param status - Terminal status string from the polling response.
+   */
+  constructor(approvalId, status) {
+    super(`Approval ${approvalId} terminated as ${status} with no payload`);
+    this.name = "X402ApprovalFailedError";
+    this.approvalId = approvalId;
+    this.status = status;
+  }
+};
+var X402ApprovalCancelledError = class extends Error {
+  /** The approval id the server returned from `POST /v1/transactions/x402`. */
+  approvalId;
+  constructor(approvalId) {
+    super(`Approval ${approvalId} cancelled by caller`);
+    this.name = "X402ApprovalCancelledError";
+    this.approvalId = approvalId;
+  }
+};
+var X402ApprovalTimeoutError = class extends Error {
+  /** The approval id the server returned from `POST /v1/transactions/x402`. */
+  approvalId;
+  /** Effective timeout in milliseconds. */
+  timeoutMs;
+  /**
+   * @param approvalId - Server-issued approval id.
+   * @param timeoutMs - The configured timeout that elapsed.
+   */
+  constructor(approvalId, timeoutMs) {
+    super(`Approval ${approvalId} not signed within ${String(timeoutMs)}ms`);
+    this.name = "X402ApprovalTimeoutError";
+    this.approvalId = approvalId;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var X402PaymentIdFormatError = class extends Error {
+  /** The offending input. */
+  input;
+  /** @param input - The {@link SignOptions.paymentId} value that failed validation. */
+  constructor(input) {
+    super(`Invalid paymentId ${JSON.stringify(input)}; must be 16-128 chars matching ^[a-zA-Z0-9_-]+$`);
+    this.name = "X402PaymentIdFormatError";
+    this.input = input;
+  }
+};
+var X402AdapterRoutingError = class extends Error {
+  /** Scheme of the requirement the adapter could not route. */
+  scheme;
+  /** Network of the requirement the adapter could not route. */
+  network;
+  /**
+   * @param scheme - Scheme of the offending requirement.
+   * @param network - Network of the offending requirement.
+   */
+  constructor(scheme, network) {
+    super(
+      `InflowClient cannot route requirement (scheme: "${scheme}", network: "${network}"): not in the InFlow buyer capability cache and no two-phase flow exists for foundation-signed schemes`
+    );
+    this.name = "X402AdapterRoutingError";
+    this.scheme = scheme;
+    this.network = network;
+  }
+};
+var X402InvalidEvmKeyError = class extends Error {
+  /** Why the input failed validation. Never contains key bytes. */
+  reason;
+  /**
+   * @param reason - Short explanation appended to the error message. Must not contain the raw input — produce a length
+   *   / shape description instead (e.g. `'expected 32 bytes, got 31'`).
+   */
+  constructor(reason) {
+    super(`Invalid EVM private key: ${reason}`);
+    this.name = "X402InvalidEvmKeyError";
+    this.reason = reason;
+  }
+};
+var X402InvalidSolanaKeyError = class extends Error {
+  /** Why the input failed validation. Never contains key bytes. */
+  reason;
+  /**
+   * @param reason - Short explanation appended to the error message. Must not contain the raw input — produce a length
+   *   / shape description instead (e.g. `'expected 64 bytes, got 32'`).
+   */
+  constructor(reason) {
+    super(
+      `Invalid Solana private key: ${reason}. Expected a 64-byte Ed25519 secret key, supplied either as a base58 string (matches InFlow SolanaClient.Account.getSeed()) or a JSON byte array (matches solana-keygen).`
+    );
+    this.name = "X402InvalidSolanaKeyError";
+    this.reason = reason;
+  }
+};
+
+// src/_foundation-bridge.ts
+function fromFoundationRequirements(r) {
+  return r;
+}
+function toFoundationPayload(p) {
+  return p;
+}
+var SUPPORTED_PATH = "/v1/transactions/x402-supported";
+var TRANSACTIONS_PATH = "/v1/transactions/x402";
+var APPROVAL_CANCEL_PATH = (id) => `/v1/approvals/${id}/cancel`;
+var TRANSACTION_X402_PATH = (id) => `/v1/transactions/${id}/x402`;
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+var DEFAULT_POLL_INTERVAL_MS = 5e3;
+var DEFAULT_TIMEOUT_MS = 15 * 60 * 1e3;
+var DEFAULT_PREFER = ["balance", "exact"];
+var APPROVAL_APPROVED = "APPROVED";
+async function createInflowSigner(options) {
+  const http = new x402.InflowHttpClient(options);
+  const prefer = options.prefer ?? DEFAULT_PREFER;
+  const extensionsHandled = new Set(extensions.EXTENSION_REGISTRY.keys());
+  const supportedCache = {
+    value: void 0,
+    expiresAt: 0,
+    inFlight: void 0
+  };
+  async function fetchSupported() {
+    const fresh = await http.get(SUPPORTED_PATH);
+    supportedCache.value = fresh;
+    supportedCache.expiresAt = Date.now() + CACHE_TTL_MS;
+    return fresh;
+  }
+  function getSupported() {
+    if (supportedCache.value !== void 0 && Date.now() < supportedCache.expiresAt) {
+      return Promise.resolve(supportedCache.value);
+    }
+    if (supportedCache.inFlight !== void 0) return supportedCache.inFlight;
+    const inFlight = fetchSupported().finally(() => {
+      supportedCache.inFlight = void 0;
+    });
+    supportedCache.inFlight = inFlight;
+    return inFlight;
+  }
+  function refreshSupported() {
+    if (supportedCache.inFlight !== void 0) return supportedCache.inFlight;
+    const inFlight = fetchSupported().finally(() => {
+      supportedCache.inFlight = void 0;
+    });
+    supportedCache.inFlight = inFlight;
+    return inFlight;
+  }
+  function supports(requirement) {
+    const cached = supportedCache.value;
+    if (cached === void 0) return false;
+    return cached.kinds.some((k) => k.scheme === requirement.scheme && k.network === requirement.network);
+  }
+  async function prepare(requirement, context, callOptions) {
+    const merged = { ...options.signDefaults, ...callOptions };
+    if (merged.paymentId !== void 0 && !extensions.validatePaymentId(merged.paymentId)) {
+      throw new X402PaymentIdFormatError(merged.paymentId);
+    }
+    const body = {
+      accept: requirement,
+      resource: context.resource,
+      x402Version: context.x402Version,
+      ...merged.paymentId !== void 0 ? { remotePaymentId: merged.paymentId } : {}
+    };
+    const created = await http.post(TRANSACTIONS_PATH, body, {
+      retries: 0,
+      ...merged.signal !== void 0 ? { signal: merged.signal } : {}
+    });
+    return makePreparedPayment(http, created, merged);
+  }
+  async function sign(requirement, context, callOptions) {
+    const prepared = await prepare(requirement, context, callOptions);
+    try {
+      return await prepared.awaitPayload(callOptions);
+    } catch (err) {
+      void prepared.cancel();
+      throw err;
+    }
+  }
+  await fetchSupported();
+  const signer = {
+    prefer,
+    extensionsHandled,
+    supports,
+    sign,
+    prepare,
+    ready: () => Promise.resolve(),
+    getSupported,
+    refreshSupported
+  };
+  return signer;
+}
+function makePreparedPayment(http, created, preparedOptions) {
+  let awaitInFlight;
+  let cancelled = false;
+  const cancelController = new AbortController();
+  function buildEncodedPayment(encodedPayload, paymentPayload) {
+    return { encodedPayload, paymentPayload, transactionId: created.transactionId };
+  }
+  async function pollOnce(signal) {
+    return http.get(TRANSACTION_X402_PATH(created.transactionId), {
+      retries: 0,
+      ...signal !== void 0 ? { signal } : {}
+    });
+  }
+  async function awaitPayload(callOptions) {
+    if (cancelled) {
+      throw new X402ApprovalCancelledError(created.approvalId);
+    }
+    if (awaitInFlight !== void 0) return awaitInFlight;
+    const merged = { ...preparedOptions, ...callOptions };
+    const pollIntervalMs = merged.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = merged.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const callerSignal = merged.signal;
+    const signal = composeSignals(callerSignal, cancelController.signal);
+    const promise = runPollLoop({
+      pollOnce,
+      buildEncodedPayment,
+      approvalId: created.approvalId,
+      pollIntervalMs,
+      timeoutMs,
+      signal,
+      // Short-circuit for the synchronous-approval path: when the server
+      // signed during `POST /v1/transactions/x402` (approvalStatus = APPROVED),
+      // the very first GET should already have the payload; the loop is
+      // still robust to a missed first poll.
+      createdApprovalStatus: created.approvalStatus
+    }).catch((err) => {
+      if (cancelled) {
+        throw new X402ApprovalCancelledError(created.approvalId);
+      }
+      throw err;
+    });
+    awaitInFlight = promise;
+    promise.catch(() => {
+      awaitInFlight = void 0;
+    });
+    return promise;
+  }
+  async function statusFn() {
+    const payload = await pollOnce();
+    return payload.status;
+  }
+  async function cancel() {
+    cancelled = true;
+    cancelController.abort();
+    try {
+      await http.post(APPROVAL_CANCEL_PATH(created.approvalId), void 0, { retries: 0 });
+    } catch {
+    }
+  }
+  return {
+    transactionId: created.transactionId,
+    approvalId: created.approvalId,
+    awaitPayload,
+    status: statusFn,
+    cancel
+  };
+}
+function composeSignals(...signals) {
+  const live = signals.filter((s) => s !== void 0);
+  const [first, ...rest] = live;
+  if (first !== void 0 && rest.length === 0) return first;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function") return anyFn(live);
+  const controller = new AbortController();
+  const cleanups = [];
+  const fire = (reason) => {
+    controller.abort(reason);
+    for (const c of cleanups) c();
+  };
+  for (const s of live) {
+    if (s.aborted) {
+      fire(s.reason);
+      return controller.signal;
+    }
+    const handler = () => fire(s.reason);
+    s.addEventListener("abort", handler, { once: true });
+    cleanups.push(() => s.removeEventListener("abort", handler));
+  }
+  return controller.signal;
+}
+async function runPollLoop(input) {
+  const { pollOnce, buildEncodedPayment, approvalId, pollIntervalMs, timeoutMs, signal } = input;
+  const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  const isAborted = () => signal !== void 0 && signal.aborted;
+  if (isAborted()) {
+    throw new X402ApprovalTimeoutError(approvalId, timeoutMs);
+  }
+  let firstPoll = input.createdApprovalStatus === APPROVAL_APPROVED;
+  while (Date.now() < deadline) {
+    if (isAborted()) {
+      throw new X402ApprovalTimeoutError(approvalId, timeoutMs);
+    }
+    let response;
+    try {
+      response = await pollOnce(signal);
+    } catch (err) {
+      if (signal !== void 0 && signal.aborted) {
+        throw new X402ApprovalTimeoutError(approvalId, timeoutMs);
+      }
+      response = void 0;
+    }
+    if (response !== void 0) {
+      const settled = evaluatePoll(response);
+      if (settled === "pending") ; else if (settled === "failed") {
+        throw new X402ApprovalFailedError(approvalId, response.status);
+      } else {
+        return buildEncodedPayment(response.encodedPayload, response.paymentPayload);
+      }
+    }
+    if (firstPoll) {
+      firstPoll = false;
+      continue;
+    }
+    await sleep(pollIntervalMs, signal);
+  }
+  throw new X402ApprovalTimeoutError(approvalId, timeoutMs);
+}
+var TERMINAL_FAILURE_STATUSES = /* @__PURE__ */ new Set([
+  "DECLINED",
+  "EXPIRED",
+  "GENERAL_ERROR",
+  "INSUFFICIENT_FUNDS"
+]);
+function evaluatePoll(response) {
+  if (response.encodedPayload != null && response.paymentPayload != null) {
+    return "signed";
+  }
+  if (TERMINAL_FAILURE_STATUSES.has(response.status)) {
+    return "failed";
+  }
+  return "pending";
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    if (signal !== void 0) {
+      const onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      if (signal.aborted) {
+        clearTimeout(timer);
+        resolve();
+      } else {
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    }
+  });
+}
+
+// src/inflow-client.ts
+var InflowClient = class extends client.x402Client {
+  /**
+   * The InFlow-signed branch of the routing decision. Kept private — callers compose by passing the {@link InflowClient}
+   * to `x402HTTPClient` (and to `registerExactEvmScheme` / `registerExactSvmScheme` for foundation-signed networks).
+   */
+  inflowSigner;
+  /**
+   * Ordered scheme preference used when picking among multiple InFlow-acceptable requirements. Sourced from the InFlow
+   * signer at construction so the buyer's intent (`prefer: ['balance', 'exact']` by default) survives across the
+   * override.
+   */
+  preferOrder;
+  /**
+   * Construct via {@link createInflowClient}. The factory primes the buyer capability cache before resolving, so the
+   * routing decision in {@link InflowClient.createPaymentPayload} is synchronous against in-memory data. The constructor
+   * is exported only so the class is referenceable for `instanceof` checks, generic constraints, and return types.
+   *
+   * @param inflowSigner - Primed InFlow signer carrying the buyer capability cache, MPC signing flow, and prefer order.
+   * @internal
+   */
+  constructor(inflowSigner) {
+    super();
+    this.inflowSigner = inflowSigner;
+    this.preferOrder = inflowSigner.prefer;
+  }
+  /**
+   * Routing override. InFlow signs when the buyer capability cache covers a requirement (preferred-scheme order);
+   * otherwise the foundation signs and any registered extension handlers are folded into `payload.extensions`. A
+   * `required: true` extension whose handler returns `null` throws.
+   */
+  async createPaymentPayload(paymentRequired) {
+    const inflowMatch = this.pickInflowMatch(fromFoundationRequirements(paymentRequired.accepts));
+    if (inflowMatch !== null) {
+      const context = {
+        resource: paymentRequired.resource,
+        x402Version: paymentRequired.x402Version,
+        ...paymentRequired.extensions !== void 0 ? { extensions: paymentRequired.extensions } : {}
+      };
+      const result = await this.inflowSigner.sign(inflowMatch, context);
+      return toFoundationPayload(result.paymentPayload);
+    }
+    const payload = await super.createPaymentPayload(paymentRequired);
+    const folded = foldInflowExtensions(payload, paymentRequired);
+    return toFoundationPayload(folded);
+  }
+  /**
+   * Two-phase signing flow for callers that want to surface pending- approval UI before the protected request is
+   * replayed. Forwarded to the InFlow signer's `prepare()`; returns a {@link PreparedPayment} the caller can
+   * `awaitPayload()` or `cancel()` independently.
+   *
+   * Has no foundation equivalent — `x402Client.createPaymentPayload` is one-shot. The handle is InFlow-specific and
+   * only applies to requirements InFlow can sign.
+   *
+   * @param requirement - The chosen `PaymentRequirements` (re-exported from `@inflowpayai/x402`) — must match an entry
+   *   in the InFlow buyer capability cache.
+   * @param context - Seller-side {@link SigningContext}.
+   * @param options - Per-call {@link SignOptions}.
+   * @returns A {@link PreparedPayment} handle.
+   * @throws {@link X402AdapterRoutingError} When the requirement is not in the InFlow buyer capability cache
+   *   (foundation-signed requirements have no two-phase flow).
+   */
+  async prepareInflowPayment(requirement, context, options) {
+    if (!this.inflowSigner.supports(requirement)) {
+      throw new X402AdapterRoutingError(requirement.scheme, requirement.network);
+    }
+    return this.inflowSigner.prepare(requirement, context, options);
+  }
+  // The eight overrides below preserve foundation `x402Client` behavior
+  // verbatim and only narrow the return type to `this` so chaining
+  // stays in the {@link InflowClient} subclass.
+  register(network, schemeNetworkClient) {
+    super.register(network, schemeNetworkClient);
+    return this;
+  }
+  registerV1(network, schemeNetworkClient) {
+    super.registerV1(network, schemeNetworkClient);
+    return this;
+  }
+  registerPolicy(policy) {
+    super.registerPolicy(policy);
+    return this;
+  }
+  registerExtension(extension) {
+    super.registerExtension(extension);
+    return this;
+  }
+  onBeforePaymentCreation(hook) {
+    super.onBeforePaymentCreation(hook);
+    return this;
+  }
+  onAfterPaymentCreation(hook) {
+    super.onAfterPaymentCreation(hook);
+    return this;
+  }
+  onPaymentCreationFailure(hook) {
+    super.onPaymentCreationFailure(hook);
+    return this;
+  }
+  onPaymentResponse(hook) {
+    super.onPaymentResponse(hook);
+    return this;
+  }
+  /**
+   * Pick the buyer's preferred `accepts[]` entry the InFlow signer can handle. Walks {@link InflowClient.preferOrder}
+   * and returns the first entry whose `(scheme, network)` is in the InFlow capability cache; returns `null` when no
+   * entry matches (the foundation branch takes over).
+   */
+  pickInflowMatch(accepts) {
+    for (const scheme of this.preferOrder) {
+      const match = accepts.find((r) => r.scheme === scheme && this.inflowSigner.supports(r));
+      if (match !== void 0) return match;
+    }
+    return null;
+  }
+};
+async function createInflowClient(options) {
+  const inflowSigner = await createInflowSigner(options);
+  return new InflowClient(inflowSigner);
+}
+function foldInflowExtensions(paymentPayload, paymentRequired) {
+  const declared = paymentRequired.extensions;
+  if (declared === void 0) return paymentPayload;
+  const signContext = {};
+  let extensions$1 = paymentPayload.extensions;
+  for (const handler of extensions.EXTENSION_REGISTRY.values()) {
+    const declaration = extensions.getExtension(declared, handler);
+    if (declaration === void 0) continue;
+    const entry = handler.buildPayloadEntry(declaration, signContext);
+    if (entry !== null) {
+      extensions$1 = extensions.setExtension(extensions$1, handler, entry);
+      continue;
+    }
+    const required = declaration !== null && typeof declaration === "object" && "required" in declaration && declaration.required === true;
+    if (required) {
+      throw new Error(
+        `InflowClient: extension "${handler.name}" is declared as required but no payload entry was produced`
+      );
+    }
+  }
+  if (extensions$1 === void 0) return paymentPayload;
+  return { ...paymentPayload, extensions: extensions$1 };
+}
+
+// src/decode-evm-key.ts
+var HEX_RE = /^[0-9a-f]+$/;
+function parseEvmPrivateKey(value) {
+  let hex = value.trim().toLowerCase();
+  if (hex.startsWith("0x")) hex = hex.slice(2);
+  if (hex === "" || !HEX_RE.test(hex)) {
+    throw new X402InvalidEvmKeyError("expected hex characters (0x-prefixed or bare)");
+  }
+  if (hex.length === 66 && hex.startsWith("00")) {
+    hex = hex.slice(2);
+  }
+  if (hex.length < 64) hex = hex.padStart(64, "0");
+  if (hex.length !== 64) {
+    throw new X402InvalidEvmKeyError(`expected 32 bytes after normalization; got ${(hex.length / 2).toString()}`);
+  }
+  return `0x${hex}`;
+}
+var EXPECTED_LENGTH = 64;
+function decodeSolanaSecret(value) {
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    throw new X402InvalidSolanaKeyError("input is empty");
+  }
+  if (trimmed.startsWith("[")) {
+    return decodeJsonByteArray(trimmed);
+  }
+  return decodeBase58(trimmed);
+}
+function decodeJsonByteArray(trimmed) {
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    throw new X402InvalidSolanaKeyError(`JSON parse failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new X402InvalidSolanaKeyError("JSON value is not an array");
+  }
+  if (parsed.length !== EXPECTED_LENGTH) {
+    throw new X402InvalidSolanaKeyError(
+      `JSON array length is ${parsed.length.toString()}, expected ${EXPECTED_LENGTH.toString()}`
+    );
+  }
+  const bytes = new Uint8Array(EXPECTED_LENGTH);
+  for (let i = 0; i < EXPECTED_LENGTH; i += 1) {
+    const element = parsed[i];
+    if (typeof element !== "number" || !Number.isInteger(element) || element < 0 || element > 255) {
+      throw new X402InvalidSolanaKeyError(`JSON array element at index ${i.toString()} is not an integer in 0..255`);
+    }
+    bytes[i] = element;
+  }
+  return bytes;
+}
+function decodeBase58(trimmed) {
+  let decoded;
+  try {
+    decoded = bs58__default.default.decode(trimmed);
+  } catch (err) {
+    throw new X402InvalidSolanaKeyError(`base58 decode failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (decoded.length !== EXPECTED_LENGTH) {
+    throw new X402InvalidSolanaKeyError(
+      `base58 decoded to ${decoded.length.toString()} bytes, expected ${EXPECTED_LENGTH.toString()}`
+    );
+  }
+  return decoded;
+}
+
+exports.InflowClient = InflowClient;
+exports.X402AdapterRoutingError = X402AdapterRoutingError;
+exports.X402ApprovalCancelledError = X402ApprovalCancelledError;
+exports.X402ApprovalFailedError = X402ApprovalFailedError;
+exports.X402ApprovalTimeoutError = X402ApprovalTimeoutError;
+exports.X402InvalidEvmKeyError = X402InvalidEvmKeyError;
+exports.X402InvalidSolanaKeyError = X402InvalidSolanaKeyError;
+exports.X402PaymentIdFormatError = X402PaymentIdFormatError;
+exports.createInflowClient = createInflowClient;
+exports.decodeSolanaSecret = decodeSolanaSecret;
+exports.parseEvmPrivateKey = parseEvmPrivateKey;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map