@bitpal/checkout 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -37,13 +37,23 @@ __export(index_exports, {
   PaymentLinksResource: () => PaymentLinksResource,
   PricesResource: () => PricesResource,
   ProductsResource: () => ProductsResource,
+  TRANSFER_WITH_AUTHORIZATION_TYPES: () => TRANSFER_WITH_AUTHORIZATION_TYPES,
   WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
+  X402Gate: () => X402Gate,
+  X402_PAYMENT_HEADER: () => X402_PAYMENT_HEADER,
+  X402_PAYMENT_RESPONSE_HEADER: () => X402_PAYMENT_RESPONSE_HEADER,
+  createMemoryReplayStore: () => createMemoryReplayStore,
+  createX402Payment: () => createX402Payment,
+  decodePaymentHeader: () => decodePaymentHeader,
+  encodePaymentHeader: () => encodePaymentHeader,
   fromAtomic: () => fromAtomic,
   fromAtomicUSDC: () => fromAtomicUSDC,
   parseWebhookEvent: () => parseWebhookEvent,
+  splitSignature: () => splitSignature,
   toAtomic: () => toAtomic,
   toAtomicUSDC: () => toAtomicUSDC,
-  verifyWebhookSignature: () => verifyWebhookSignature
+  verifyWebhookSignature: () => verifyWebhookSignature,
+  x402: () => x402
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -305,12 +315,23 @@ var BitPalCheckoutClient = class {
     );
   }
   /* ─── Fees ─── */
-  /** 수수료 미리보기 — `/v1/checkout/fee-preview` (Phase 1 credit system 폐기 후 canonical path) */
+  /**
+   * 수수료 미리보기 — `/v1/checkout/fee-preview`.
+   *
+   * `amount` 는 **사람 표기**다("100", "0.5") — line item / Price / x402 와 같은 모델이라
+   * decimals 를 계산할 필요가 없다. raw μUSD 를 직접 넣으려면 `amountAtomic` 을 쓴다(상호 배타).
+   * 응답은 계속 atomic 이다(계산 결과라 정밀도가 곧 계약이다).
+   *
+   * @example
+   * const { data } = await bp.checkout.previewFee('100');       // $100
+   * const { data } = await bp.checkout.previewFee({ amountAtomic: '100000000' });
+   */
   async previewFee(amount) {
-    return this.request(
-      "GET",
-      `/v1/checkout/fee-preview?amount=${encodeURIComponent(amount)}`
-    );
+    const qs = typeof amount === "string" ? `amount=${encodeURIComponent(amount)}` : `amount_atomic=${encodeURIComponent(amount.amountAtomic)}`;
+    if (typeof amount === "string" && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(amount)) {
+      throw new Error('[BitPal] previewFee: amount must be a decimal string like "100" or "0.5" (max 6 decimals). For raw \u03BCUSD use { amountAtomic }.');
+    }
+    return this.request("GET", `/v1/checkout/fee-preview?${qs}`);
   }
 };
 var BitPalError = class extends Error {
@@ -408,6 +429,549 @@ function fromAtomicUSDC(atomic) {
   return fromAtomic(atomic, 6);
 }
 
+// src/x402.ts
+var X402_PAYMENT_HEADER = "x-payment";
+var X402_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+var RESIGN_REQUIRED_STATUSES = /* @__PURE__ */ new Set(["reverted", "expired", "failed"]);
+var DEFAULT_BASE_URL2 = "https://api.bitpal.io";
+var DEFAULT_TIMEOUT2 = 6e4;
+var DEFAULT_MAX_TIMEOUT_SECONDS = 300;
+var MIN_VALIDITY_SECONDS = 60;
+var MAX_VALIDITY_SECONDS = 3600;
+var CONSUMED_TTL_SECONDS = 24 * 60 * 60;
+var MEMORY_STORE_MAX_ENTRIES = 5e4;
+var MAX_PAYMENT_HEADER_BYTES = 8192;
+function createMemoryReplayStore() {
+  const entries = /* @__PURE__ */ new Map();
+  const prune = (now) => {
+    for (const [k, v] of entries) {
+      if (v.expiresAt <= now) entries.delete(k);
+    }
+    if (entries.size <= MEMORY_STORE_MAX_ENTRIES) return;
+    for (const [k, v] of entries) {
+      if (entries.size <= MEMORY_STORE_MAX_ENTRIES) break;
+      if (v.state === "inflight") entries.delete(k);
+    }
+  };
+  return {
+    claim(key, inflightTtlSeconds) {
+      const now = Date.now();
+      prune(now);
+      const found = entries.get(key);
+      if (found) return found.state;
+      if (entries.size >= MEMORY_STORE_MAX_ENTRIES) {
+        throw new BitPalError(
+          "[BitPal] x402: replay store is full. Pass a shared replayStore (Redis/DB) for this traffic level.",
+          503
+        );
+      }
+      entries.set(key, { state: "inflight", expiresAt: now + inflightTtlSeconds * 1e3 });
+      return "ok";
+    },
+    commit(key) {
+      entries.set(key, { state: "used", expiresAt: Date.now() + CONSUMED_TTL_SECONDS * 1e3 });
+    },
+    release(key) {
+      entries.delete(key);
+    }
+  };
+}
+var X402Gate = class {
+  opts;
+  baseUrl;
+  timeout;
+  store;
+  maxTimeoutSeconds;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("[BitPal] x402: apiKey is required.");
+    if (!/^0x[a-fA-F0-9]{40}$/.test(opts.payTo)) {
+      throw new Error("[BitPal] x402: payTo must be a 0x EVM address (your registered payout wallet).");
+    }
+    const hasHuman = opts.amount != null;
+    const hasAtomic = opts.amountAtomic != null;
+    if (hasHuman === hasAtomic) {
+      throw new Error('[BitPal] x402: provide exactly one of `amount` ("0.1") or `amountAtomic` ("100000").');
+    }
+    if (hasHuman && !/^(0|[1-9]\d*)(\.\d{1,6})?$/.test(opts.amount)) {
+      throw new Error('[BitPal] x402: amount must be a decimal string like "0.1" or "29" (max 6 decimals).');
+    }
+    if (hasAtomic && !/^\d+$/.test(opts.amountAtomic)) {
+      throw new Error('[BitPal] x402: amountAtomic must be an integer string (USDC 6dp, $1 = "1000000").');
+    }
+    const timeoutSeconds = opts.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+    if (timeoutSeconds < MIN_VALIDITY_SECONDS || timeoutSeconds > MAX_VALIDITY_SECONDS) {
+      throw new Error(
+        `[BitPal] x402: maxTimeoutSeconds must be between ${MIN_VALIDITY_SECONDS} and ${MAX_VALIDITY_SECONDS} (got ${timeoutSeconds}).`
+      );
+    }
+    this.opts = opts;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL2).replace(/\/$/, "");
+    this.timeout = opts.timeout ?? DEFAULT_TIMEOUT2;
+    this.store = opts.replayStore ?? createMemoryReplayStore();
+    this.maxTimeoutSeconds = opts.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+  }
+  /** 이 리소스의 402 바디를 서버에서 받아온다(수수료 분해 포함). */
+  async requirements(resource) {
+    return this.request("POST", "/v1/x402/requirements", {
+      payTo: this.opts.payTo,
+      // 사람 표기 → atomic 변환은 **서버가** 한다. SDK 가 decimals 를 알 필요가 없다.
+      ...this.opts.amount != null ? { amount: this.opts.amount } : { amountAtomic: this.opts.amountAtomic },
+      resource,
+      ...this.opts.network ? { network: this.opts.network } : {},
+      ...this.opts.asset ? { asset: this.opts.asset } : {},
+      ...this.opts.description ? { description: this.opts.description } : {},
+      ...this.opts.mimeType ? { mimeType: this.opts.mimeType } : {},
+      maxTimeoutSeconds: this.maxTimeoutSeconds
+    });
+  }
+  /**
+   * `X-PAYMENT` 헤더 1건을 처리한다. 헤더가 없거나 깨졌으면 402, 정산까지 끝나면 `settled`.
+   *
+   * 순서가 중요하다: **점유 → verify → settle → 소진 기록**. 점유를 verify 앞에 두어야 같은
+   * authorization 을 동시에 밀어 넣어도 한 요청만 리소스를 받는다.
+   */
+  async collect(input) {
+    const { header, resource } = input;
+    if (!header) return this.paymentRequired(resource);
+    let payload;
+    try {
+      payload = decodePaymentHeader(header);
+    } catch {
+      return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
+    }
+    const merchant = payload?.payload?.merchant;
+    if (!merchant?.from || !merchant?.nonce) {
+      return this.paymentRequired(resource, "MALFORMED_PAYMENT_HEADER");
+    }
+    const key = `${payload.network}:${merchant.from.toLowerCase()}:${merchant.nonce.toLowerCase()}`;
+    const claim = await this.store.claim(key, this.maxTimeoutSeconds);
+    if (claim === "used") {
+      return {
+        kind: "already_used",
+        status: 409,
+        body: {
+          error: "PAYMENT_ALREADY_USED",
+          message: "This payment has already been redeemed. One payment unlocks one response."
+        }
+      };
+    }
+    if (claim === "inflight") {
+      return {
+        kind: "unconfirmed",
+        status: 503,
+        body: {
+          error: "PAYMENT_IN_PROGRESS",
+          message: "This payment is still being settled. Retry with the same X-PAYMENT header."
+        }
+      };
+    }
+    let accept;
+    try {
+      accept = await this.firstAccept(resource);
+    } catch (err) {
+      await this.store.release(key);
+      throw err;
+    }
+    const body = {
+      x402Version: 1,
+      paymentPayload: {
+        scheme: "exact",
+        network: payload.network,
+        payload: payload.payload
+      },
+      paymentRequirements: {
+        asset: accept.asset,
+        payTo: accept.payTo,
+        maxAmountRequired: accept.maxAmountRequired,
+        resource: accept.resource
+      }
+    };
+    try {
+      await this.request("POST", "/v1/x402/verify", body);
+    } catch (err) {
+      await this.store.release(key);
+      if (err instanceof BitPalError && err.statusCode < 500) {
+        return this.paymentRequired(resource, err.message, accept);
+      }
+      throw err;
+    }
+    let settled;
+    try {
+      settled = await this.request("POST", "/v1/x402/settle", body);
+    } catch (err) {
+      if (err instanceof BitPalError && err.statusCode < 500) {
+        await this.store.release(key);
+        return this.paymentRequired(resource, err.message, accept);
+      }
+      await this.store.release(key);
+      return {
+        kind: "unconfirmed",
+        status: 503,
+        body: {
+          error: "SETTLEMENT_UNCONFIRMED",
+          message: "Payment settlement is not confirmed yet. Retry this request with the same X-PAYMENT header \u2014 settlement is idempotent."
+        }
+      };
+    }
+    if (settled.status !== "confirmed") {
+      await this.store.release(key);
+      if (RESIGN_REQUIRED_STATUSES.has(settled.status)) {
+        return this.paymentRequired(resource, `PAYMENT_${settled.status.toUpperCase()}`, accept);
+      }
+      return {
+        kind: "unconfirmed",
+        status: 503,
+        body: {
+          error: "SETTLEMENT_UNCONFIRMED",
+          message: `Payment is still settling (${settled.status}). Retry with the same X-PAYMENT header \u2014 do not create a new payment.`,
+          paymentId: settled.payment_id
+        }
+      };
+    }
+    const payment = {
+      paymentId: settled.payment_id,
+      txHash: settled.tx_hash,
+      feeTxHash: settled.fee_tx_hash ?? null,
+      network: settled.network,
+      payer: merchant.from,
+      amount: accept.maxAmountRequired,
+      idempotent: settled.idempotent ?? false
+    };
+    return {
+      kind: "settled",
+      status: 200,
+      payment,
+      paymentResponseHeader: encodeBase64Json({
+        success: true,
+        transaction: settled.tx_hash,
+        network: settled.network,
+        payer: merchant.from,
+        paymentId: settled.payment_id
+      }),
+      // 소진 확정은 **응답을 실제로 내준 뒤**다. 핸들러가 throw 하거나 프로세스가 죽으면 결제만 하고
+      //   리소스를 못 받는데, 그때 commit 되어 있으면 재시도가 409 로 막힌다.
+      commit: () => Promise.resolve(this.store.commit(key)),
+      release: () => Promise.resolve(this.store.release(key))
+    };
+  }
+  /* ─── 내부 ─── */
+  async firstAccept(resource) {
+    const requirements = await this.requirements(resource);
+    const accept = requirements.accepts[0];
+    if (!accept) {
+      throw new BitPalError("[BitPal] x402: no payment option available for this API key mode.", 500);
+    }
+    return accept;
+  }
+  async paymentRequired(resource, error, known) {
+    const requirements = known ? { x402Version: 1, accepts: [known] } : await this.requirements(resource);
+    return {
+      kind: "payment_required",
+      status: 402,
+      body: error ? { ...requirements, error } : requirements
+    };
+  }
+  async request(method, path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.opts.apiKey}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      const json = await res.json();
+      if (!res.ok) {
+        throw new BitPalError(String(json.error ?? `HTTP ${res.status}`), res.status);
+      }
+      return json.data;
+    } catch (err) {
+      if (err instanceof BitPalError) throw err;
+      throw new BitPalError(err instanceof Error ? err.message : String(err), 599);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+function x402(options) {
+  const gate = new X402Gate(options);
+  return async function x402Middleware(req, res, next) {
+    try {
+      const result = await gate.collect({
+        header: readHeader(req, X402_PAYMENT_HEADER),
+        resource: resolveResource(req, options.resource)
+      });
+      if (result.kind !== "settled") {
+        res.status(result.status).json(result.body);
+        return;
+      }
+      res.setHeader(X402_PAYMENT_RESPONSE_HEADER, result.paymentResponseHeader);
+      req.x402Payment = result.payment;
+      if (typeof res.once === "function") {
+        let finalized = false;
+        const finalize = (delivered) => {
+          if (finalized) return;
+          finalized = true;
+          const done = delivered ? result.commit() : result.release();
+          void done.catch(() => void 0);
+        };
+        res.once("finish", () => finalize((res.statusCode ?? 200) < 500));
+        res.once("close", () => finalize(res.writableEnded === true && (res.statusCode ?? 200) < 500));
+      } else {
+        await result.commit();
+      }
+      if (options.onSettled) await options.onSettled(result.payment, req);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+function readHeader(req, name) {
+  const direct = req.headers?.[name] ?? req.headers?.[name.toUpperCase()];
+  const value = Array.isArray(direct) ? direct[0] : direct;
+  if (value) return value;
+  return req.get?.(name);
+}
+function resolveResource(req, override) {
+  if (typeof override === "function") return override(req);
+  if (override) return override;
+  const host = req.get?.("host") ?? readHeader(req, "host") ?? "localhost";
+  const protocol = req.protocol ?? "https";
+  const raw = req.path != null ? `${req.baseUrl ?? ""}${req.path}` : req.originalUrl ?? req.url ?? "/";
+  const path = raw.split("?")[0] || "/";
+  return `${protocol}://${host}${path}`;
+}
+function decodePaymentHeader(header) {
+  if (header.length > MAX_PAYMENT_HEADER_BYTES) {
+    throw new Error("[BitPal] x402: X-PAYMENT header too large.");
+  }
+  const trimmed = header.trim();
+  const json = trimmed.startsWith("{") ? trimmed : decodeBase64(trimmed);
+  const parsed = JSON.parse(json);
+  return assertPaymentPayload(parsed);
+}
+var ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+var HEX32_RE = /^0x[a-fA-F0-9]{64}$/;
+var DECIMAL_RE = /^\d{1,78}$/;
+function assertPaymentPayload(value) {
+  const root = asObject(value, "payment payload");
+  if (root.x402Version !== 1) throw new Error("[BitPal] x402: unsupported x402Version.");
+  if (root.scheme !== "exact") throw new Error("[BitPal] x402: unsupported scheme.");
+  if (typeof root.network !== "string" || root.network.length === 0 || root.network.length > 64) {
+    throw new Error("[BitPal] x402: invalid network.");
+  }
+  const inner = asObject(root.payload, "payload");
+  const merchant = assertAuthorization(inner.merchant, "merchant");
+  const fee = inner.fee === void 0 ? void 0 : assertAuthorization(inner.fee, "fee");
+  return {
+    x402Version: 1,
+    scheme: "exact",
+    network: root.network,
+    payload: fee ? { merchant, fee } : { merchant }
+  };
+}
+function assertAuthorization(value, label) {
+  const a = asObject(value, `${label} authorization`);
+  const sig = asObject(a.signature, `${label} signature`);
+  const check = (ok, field) => {
+    if (!ok) throw new Error(`[BitPal] x402: invalid ${label}.${field}.`);
+  };
+  check(typeof a.from === "string" && ADDRESS_RE.test(a.from), "from");
+  check(typeof a.to === "string" && ADDRESS_RE.test(a.to), "to");
+  check(typeof a.value === "string" && DECIMAL_RE.test(a.value), "value");
+  check(typeof a.validAfter === "string" && DECIMAL_RE.test(a.validAfter), "validAfter");
+  check(typeof a.validBefore === "string" && DECIMAL_RE.test(a.validBefore), "validBefore");
+  check(typeof a.nonce === "string" && HEX32_RE.test(a.nonce), "nonce");
+  check(typeof sig.v === "number" && Number.isInteger(sig.v), "signature.v");
+  check(typeof sig.r === "string" && HEX32_RE.test(sig.r), "signature.r");
+  check(typeof sig.s === "string" && HEX32_RE.test(sig.s), "signature.s");
+  return {
+    from: a.from,
+    to: a.to,
+    value: a.value,
+    validAfter: a.validAfter,
+    validBefore: a.validBefore,
+    nonce: a.nonce,
+    signature: { v: sig.v, r: sig.r, s: sig.s }
+  };
+}
+function asObject(value, label) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`[BitPal] x402: ${label} must be an object.`);
+  }
+  return value;
+}
+function encodePaymentHeader(payload) {
+  return encodeBase64Json(payload);
+}
+function encodeBase64Json(value) {
+  const json = JSON.stringify(value);
+  const g = globalThis;
+  if (typeof g.btoa === "function") {
+    const bytes = new TextEncoder().encode(json);
+    let binary = "";
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return g.btoa(binary);
+  }
+  return bufferFrom(json, "utf8").toString("base64");
+}
+function decodeBase64(value) {
+  const g = globalThis;
+  if (typeof g.atob === "function") {
+    const binary = g.atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  return bufferFrom(value, "base64").toString("utf8");
+}
+function bufferFrom(value, encoding) {
+  const g = globalThis;
+  if (!g.Buffer) throw new Error("[BitPal] x402: no base64 implementation available in this runtime.");
+  return g.Buffer.from(value, encoding);
+}
+
+// src/x402-pay.ts
+var TRANSFER_WITH_AUTHORIZATION_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" }
+  ]
+};
+var CLOCK_SKEW_MARGIN_SECONDS = 30;
+var SERVER_MIN_VALIDITY_SECONDS = 60;
+var MIN_VALIDITY_SECONDS2 = SERVER_MIN_VALIDITY_SECONDS + CLOCK_SKEW_MARGIN_SECONDS;
+var MAX_VALIDITY_SECONDS2 = 3600;
+async function createX402Payment(options) {
+  const accept = resolveAccept(options.requirements);
+  const now = Math.floor((options.now?.() ?? Date.now()) / 1e3);
+  const validFor = options.validForSeconds ?? accept.maxTimeoutSeconds;
+  if (validFor < MIN_VALIDITY_SECONDS2 || validFor > MAX_VALIDITY_SECONDS2) {
+    throw new Error(
+      `[BitPal] x402: validForSeconds must be between ${MIN_VALIDITY_SECONDS2} and ${MAX_VALIDITY_SECONDS2} (got ${validFor}). The server requires ${SERVER_MIN_VALIDITY_SECONDS}s minimum; the extra ${CLOCK_SKEW_MARGIN_SECONDS}s absorbs clock skew and round-trip latency.`
+    );
+  }
+  const domain = {
+    name: accept.extra.name,
+    version: accept.extra.version,
+    chainId: accept.extra.chainId,
+    verifyingContract: accept.asset
+  };
+  if (!domain.chainId) {
+    throw new Error("[BitPal] x402: the 402 response is missing extra.chainId \u2014 cannot build the EIP-712 domain.");
+  }
+  const validAfter = "0";
+  const validBefore = String(now + validFor);
+  const nextNonce = options.randomNonce ?? randomNonce;
+  const fee = accept.feeBreakdown;
+  const feeAmount = fee ? BigInt(fee.feeAmount) : 0n;
+  const merchantValue = fee ? fee.netAmount : accept.maxAmountRequired;
+  const merchant = await signAuthorization({
+    domain,
+    signTypedData: options.signTypedData,
+    from: options.from,
+    to: accept.payTo,
+    value: merchantValue,
+    validAfter,
+    validBefore,
+    nonce: nextNonce()
+  });
+  let feeLeg;
+  if (feeAmount > 0n) {
+    if (!fee?.feeRecipient) {
+      throw new Error("[BitPal] x402: feeAmount > 0 but feeRecipient is missing in the 402 response.");
+    }
+    feeLeg = await signAuthorization({
+      domain,
+      signTypedData: options.signTypedData,
+      from: options.from,
+      to: fee.feeRecipient,
+      value: fee.feeAmount,
+      validAfter,
+      validBefore,
+      nonce: nextNonce()
+    });
+    if (feeLeg.nonce.toLowerCase() === merchant.nonce.toLowerCase()) {
+      throw new Error("[BitPal] x402: the two authorizations must use different nonces.");
+    }
+  }
+  const payload = {
+    x402Version: 1,
+    scheme: "exact",
+    network: accept.network,
+    payload: feeLeg ? { merchant, fee: feeLeg } : { merchant }
+  };
+  return {
+    header: encodePaymentHeader(payload),
+    payload,
+    totalAmount: (BigInt(merchantValue) + feeAmount).toString()
+  };
+}
+function resolveAccept(input) {
+  if ("accepts" in input) {
+    const first = input.accepts?.[0];
+    if (!first) throw new Error("[BitPal] x402: the 402 response has no accepts[] entry.");
+    return first;
+  }
+  return input;
+}
+async function signAuthorization(args) {
+  const message = {
+    from: args.from,
+    to: args.to,
+    value: args.value,
+    validAfter: args.validAfter,
+    validBefore: args.validBefore,
+    nonce: args.nonce
+  };
+  const signature = await args.signTypedData({
+    domain: args.domain,
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message
+  });
+  return { ...message, signature: splitSignature(signature) };
+}
+function splitSignature(signature) {
+  const hex = signature.startsWith("0x") ? signature.slice(2) : signature;
+  if (!/^[0-9a-fA-F]+$/.test(hex) || hex.length !== 130 && hex.length !== 128) {
+    throw new Error(
+      `[BitPal] x402: expected a 65-byte or 64-byte (EIP-2098) hex signature, got ${signature.length} chars.`
+    );
+  }
+  const r = `0x${hex.slice(0, 64)}`;
+  if (hex.length === 128) {
+    const yParityAndS = BigInt(`0x${hex.slice(64, 128)}`);
+    const yParity = Number(yParityAndS >> 255n & 1n);
+    const s2 = yParityAndS & (1n << 255n) - 1n;
+    return { v: 27 + yParity, r, s: `0x${s2.toString(16).padStart(64, "0")}` };
+  }
+  const s = `0x${hex.slice(64, 128)}`;
+  const raw = parseInt(hex.slice(128, 130), 16);
+  if (raw === 27 || raw === 28) return { v: raw, r, s };
+  if (raw === 0 || raw === 1) return { v: raw + 27, r, s };
+  throw new Error(`[BitPal] x402: unexpected signature v=${raw} (expected 0, 1, 27 or 28).`);
+}
+function randomNonce() {
+  const g = globalThis;
+  if (!g.crypto?.getRandomValues) {
+    throw new Error("[BitPal] x402: crypto.getRandomValues is unavailable \u2014 pass randomNonce explicitly.");
+  }
+  const bytes = g.crypto.getRandomValues(new Uint8Array(32));
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return `0x${hex}`;
+}
+
 // src/index.ts
 var BitPal = class {
   checkout;
@@ -425,11 +989,21 @@ var BitPal = class {
   PaymentLinksResource,
   PricesResource,
   ProductsResource,
+  TRANSFER_WITH_AUTHORIZATION_TYPES,
   WEBHOOK_HEADERS,
+  X402Gate,
+  X402_PAYMENT_HEADER,
+  X402_PAYMENT_RESPONSE_HEADER,
+  createMemoryReplayStore,
+  createX402Payment,
+  decodePaymentHeader,
+  encodePaymentHeader,
   fromAtomic,
   fromAtomicUSDC,
   parseWebhookEvent,
+  splitSignature,
   toAtomic,
   toAtomicUSDC,
-  verifyWebhookSignature
+  verifyWebhookSignature,
+  x402
 });