@tagadapay/headless-sdk 1.20.0 → 1.21.0

package/dist/tagada-headless.js

@@ -1,5 +1,5 @@
 /**
- * @tagadapay/headless-sdk v1.20.0
+ * @tagadapay/headless-sdk v1.21.0
  * Headless checkout, payments, offers, and CRM
  * @license MIT
  */
@@ -44,8 +44,12 @@ var TagadaHeadlessBundle = (() => {
   var core_exports = {};
   __export(core_exports, {
     AVAILABLE_LANGUAGES: () => AVAILABLE_LANGUAGES,
+    CRYPTO_ONCHAIN_FINAL_PHASES: () => CRYPTO_ONCHAIN_FINAL_PHASES,
+    CRYPTO_ONCHAIN_PAYMENT_METHOD: () => CRYPTO_ONCHAIN_PAYMENT_METHOD,
+    CRYPTO_ONCHAIN_STATUS_POLL_MS: () => CRYPTO_ONCHAIN_STATUS_POLL_MS,
     CatalogModule: () => CatalogModule,
     CheckoutModule: () => CheckoutModule,
+    CryptoOnchainCheckout: () => CryptoOnchainCheckout,
     CurrencyUtils: () => CurrencyUtils,
     CustomerModule: () => CustomerModule,
     CustomerPortalModule: () => CustomerPortalModule,
@@ -67,14 +71,20 @@ var TagadaHeadlessBundle = (() => {
     TagadaValidationError: () => TagadaValidationError,
     TrackModule: () => TrackModule,
     createHeadlessClient: () => createHeadlessClient,
+    cryptoOnchainPhase: () => cryptoOnchainPhase,
+    cryptoOnchainSecondsLeft: () => cryptoOnchainSecondsLeft,
+    defaultCryptoOnchainSelection: () => defaultCryptoOnchainSelection,
     ensureGeoDataLoaded: () => ensureGeoDataLoaded,
+    formatCryptoOnchainCountdown: () => formatCryptoOnchainCountdown,
     formatMoney: () => formatMoney,
     getCountries: () => getCountries,
     getStatesForCountry: () => getStatesForCountry,
+    isCryptoOnchainMethod: () => isCryptoOnchainMethod,
     isLanguageLoaded: () => isLanguageLoaded,
     isQuestionActive: () => isQuestionActive,
     loadGoogleMapsScript: () => loadGoogleMapsScript,
     parseTokensFromUrl: () => parseTokensFromUrl,
+    selectCryptoOnchainNetwork: () => selectCryptoOnchainNetwork,
     toIntakeAnswers: () => toIntakeAnswers
   });
 
@@ -130,6 +140,10 @@ var TagadaHeadlessBundle = (() => {
     }
   };
 
+  // src/core/version.ts
+  var SDK_NAME = "headless";
+  var SDK_VERSION = "1.21.0";
+
   // src/core/http.ts
   var BASE_URLS = {
     production: "https://api.tagada.io",
@@ -163,6 +177,8 @@ var TagadaHeadlessBundle = (() => {
       }
       const reqHeaders = {
         "Content-Type": "application/json",
+        // Which SDK and version sent the call: the Payments API readiness check counts them per store.
+        "X-Tagada-SDK": `headless-sdk/${SDK_VERSION}`,
         ...headers
       };
       const authToken = token ?? this.apiKey ?? ((_a = this.getToken) == null ? void 0 : _a.call(this));
@@ -708,7 +724,8 @@ var TagadaHeadlessBundle = (() => {
         shippingAddress: this.normalizeAddress(cs.shippingAddress),
         billingAddress: this.normalizeAddress(cs.billingAddress),
         selectedShippingRateId: cs.shippingRateId ?? null,
-        metadata: cs.metadata
+        metadata: cs.metadata,
+        ...typeof cs.draft === "boolean" ? { draft: cs.draft } : {}
       };
     }
     /**
@@ -787,12 +804,8 @@ var TagadaHeadlessBundle = (() => {
     return Boolean(((_a = address.line1) == null ? void 0 : _a.trim()) && ((_b = address.country) == null ? void 0 : _b.trim()));
   }
 
-  // src/core/version.ts
-  var SDK_NAME = "headless";
-  var SDK_VERSION = "1.20.0";
-
   // src/core/modules/track.ts
-  var CDN_URL = false ? "" : "https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk@1.20.0/dist/tagada-pixels.min.js";
+  var CDN_URL = false ? "" : "https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk@1.21.0/dist/tagada-pixels.min.js";
   function loadScript(src, isReady) {
     if (isReady())
       return Promise.resolve();
@@ -1188,7 +1201,369 @@ var TagadaHeadlessBundle = (() => {
     }
   };
 
+  // src/core/helpers/cryptoOnchain.ts
+  var CRYPTO_ONCHAIN_PAYMENT_METHOD = "crypto_onchain";
+  var CRYPTO_ONCHAIN_STATUS_POLL_MS = 5e3;
+  var CRYPTO_ONCHAIN_FINAL_PHASES = ["paid", "underpaid", "failed", "expired"];
+  function isCryptoOnchainMethod(method) {
+    if (!method)
+      return false;
+    return method.trim().toLowerCase().replace(/-/g, "_").split(":")[0] === CRYPTO_ONCHAIN_PAYMENT_METHOD;
+  }
+  function defaultCryptoOnchainSelection(networks) {
+    const usable = networks.filter((network2) => network2.assets.length > 0);
+    const network = usable.find((candidate) => !candidate.testnet) ?? usable[0];
+    if (!network)
+      return null;
+    const asset = network.assets.find((candidate) => candidate.stable) ?? network.assets[0];
+    return { chainId: network.chainId, asset: asset.symbol };
+  }
+  function selectCryptoOnchainNetwork(networks, chainId, currentAsset) {
+    var _a, _b;
+    const assets = ((_a = networks.find((network) => network.chainId === chainId)) == null ? void 0 : _a.assets) ?? [];
+    const keep = assets.find((asset) => asset.symbol === currentAsset);
+    const fallback = assets.find((asset) => asset.stable) ?? assets[0];
+    return { chainId, asset: ((_b = keep ?? fallback) == null ? void 0 : _b.symbol) ?? currentAsset };
+  }
+  function cryptoOnchainPhase(status) {
+    if (!status)
+      return "waiting";
+    if (status.paid)
+      return "paid";
+    switch (status.status) {
+      case "detected":
+      case "overpaid":
+        return "confirming";
+      case "underpaid":
+        return "underpaid";
+      case "failed":
+        return "failed";
+      case "expired":
+        return "expired";
+      default:
+        return status.expired ? "expired" : "waiting";
+    }
+  }
+  function cryptoOnchainSecondsLeft(expiresAt, nowMs) {
+    if (!expiresAt)
+      return 0;
+    const end = Date.parse(expiresAt);
+    if (Number.isNaN(end))
+      return 0;
+    return Math.max(0, Math.floor((end - nowMs) / 1e3));
+  }
+  function formatCryptoOnchainCountdown(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor(s % 3600 / 60);
+    const sec = String(s % 60).padStart(2, "0");
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${sec}` : `${m}:${sec}`;
+  }
+  var UNAVAILABLE = "Crypto payments are not available right now. Choose another payment method.";
+  var CryptoOnchainCheckout = class {
+    constructor(api, options) {
+      this.api = api;
+      this.options = options;
+      this.state = {
+        options: "idle",
+        networks: [],
+        selection: null,
+        payment: null,
+        paymentStatus: null,
+        isCreating: false,
+        error: null
+      };
+      this.listeners = /* @__PURE__ */ new Set();
+      this.pollTimer = null;
+      this.stopped = false;
+      this.paidNotified = false;
+      this.subscribe = this.subscribe.bind(this);
+      this.getState = this.getState.bind(this);
+    }
+    getState() {
+      return this.state;
+    }
+    /** Listens to every state change; returns the unsubscribe function. */
+    subscribe(listener) {
+      this.listeners.add(listener);
+      return () => {
+        this.listeners.delete(listener);
+      };
+    }
+    /** What to show: the polled phase, or `expired` once an unpaid quote ran out (renew with `pay()`). */
+    getPhase(nowMs = Date.now()) {
+      const { payment, paymentStatus } = this.state;
+      const phase = cryptoOnchainPhase(paymentStatus ?? (payment ? { status: payment.status, paid: false, expired: false } : null));
+      const quoteOver = payment !== null && phase === "waiting" && cryptoOnchainSecondsLeft(payment.expiresAt, nowMs) === 0;
+      return quoteOver ? "expired" : phase;
+    }
+    /** Whole seconds left on the current quote. */
+    getSecondsLeft(nowMs = Date.now()) {
+      var _a;
+      return cryptoOnchainSecondsLeft(((_a = this.state.payment) == null ? void 0 : _a.expiresAt) ?? null, nowMs);
+    }
+    /** Loads the networks and coins and picks the default network and coin. */
+    async loadOptions() {
+      this.setState({ options: "loading", error: null });
+      try {
+        const result = await this.api.getCryptoOnchainOptions(this.options.checkoutSessionId);
+        if (!result.ok) {
+          this.setState({ options: "unavailable", networks: [], selection: null, error: result.message || UNAVAILABLE });
+          return this.state;
+        }
+        const selection = this.state.selection ?? defaultCryptoOnchainSelection(result.networks);
+        this.setState(
+          selection ? { options: "ready", networks: result.networks, selection } : { options: "unavailable", networks: result.networks, selection: null, error: UNAVAILABLE }
+        );
+      } catch (error) {
+        this.setState({ options: "unavailable", error: messageOf(error) });
+      }
+      return this.state;
+    }
+    /** Changes the pick. A new network keeps the coin when it offers it, else takes its default coin. */
+    select(next) {
+      const current = this.state.selection;
+      if (next.chainId !== void 0 && next.chainId !== (current == null ? void 0 : current.chainId)) {
+        this.setState({ selection: selectCryptoOnchainNetwork(this.state.networks, next.chainId, next.asset ?? (current == null ? void 0 : current.asset) ?? "") });
+        return;
+      }
+      if (next.asset !== void 0 && current)
+        this.setState({ selection: { ...current, asset: next.asset } });
+    }
+    /**
+     * Creates the payment for the pick (or `selection`), or re-quotes it: another coin, or a quote
+     * that expired. Save the customer and address on the session first. Starts polling.
+     */
+    async pay(selection) {
+      const target = selection ?? this.state.selection;
+      if (!target)
+        return { ok: false, code: "ASSET_NOT_AVAILABLE", message: "Choose a network and a coin" };
+      if (this.state.isCreating)
+        return { ok: false, code: "CHECKOUT_FAILED", message: "A payment is already being created" };
+      this.setState({ isCreating: true, error: null, selection: target });
+      try {
+        const result = await this.api.createCryptoOnchainPayment({
+          checkoutSessionId: this.options.checkoutSessionId,
+          chainId: target.chainId,
+          asset: target.asset
+        });
+        if (!result.ok) {
+          this.setState({ isCreating: false, error: result.message });
+          return result;
+        }
+        this.stopped = false;
+        this.setState({ isCreating: false, payment: result.payment, paymentStatus: null });
+        this.schedulePoll();
+        return result;
+      } catch (error) {
+        const message = messageOf(error);
+        this.setState({ isCreating: false, error: message });
+        return { ok: false, code: "CHECKOUT_FAILED", message };
+      }
+    }
+    /** Polls the status once now (the timer keeps polling until the payment is final). */
+    async refreshStatus() {
+      var _a, _b, _c;
+      const payment = this.state.payment;
+      if (!payment)
+        return null;
+      try {
+        const result = await this.api.getCryptoOnchainStatus({
+          checkoutSessionId: this.options.checkoutSessionId,
+          cryptoOnchainPaymentId: payment.cryptoOnchainPaymentId
+        });
+        if (!result.ok || ((_a = this.state.payment) == null ? void 0 : _a.cryptoOnchainPaymentId) !== payment.cryptoOnchainPaymentId)
+          return null;
+        const status = {
+          status: result.status,
+          paymentId: result.paymentId,
+          orderId: result.orderId,
+          confirmations: result.confirmations,
+          requiredConfirmations: result.requiredConfirmations,
+          txHash: result.txHash,
+          explorerTxUrl: result.explorerTxUrl,
+          paid: result.paid,
+          expired: result.expired,
+          redirectUrl: result.redirectUrl
+        };
+        this.setState({ paymentStatus: status });
+        if (status.paid && !this.paidNotified) {
+          this.paidNotified = true;
+          (_c = (_b = this.options).onPaid) == null ? void 0 : _c.call(_b, status);
+        }
+        return status;
+      } catch {
+        return null;
+      }
+    }
+    /** Polls again after `stop()`, while a payment is open (the customer came back to crypto). */
+    resume() {
+      if (!this.state.payment || CRYPTO_ONCHAIN_FINAL_PHASES.includes(this.getPhase()))
+        return;
+      this.stopped = false;
+      this.schedulePoll();
+    }
+    /** Stops polling (unmount, or the customer chose another payment method). */
+    stop() {
+      this.stopped = true;
+      if (this.pollTimer)
+        clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+    schedulePoll() {
+      if (this.pollTimer)
+        clearTimeout(this.pollTimer);
+      this.pollTimer = setTimeout(async () => {
+        this.pollTimer = null;
+        await this.refreshStatus();
+        if (!this.stopped && !CRYPTO_ONCHAIN_FINAL_PHASES.includes(this.getPhase()))
+          this.schedulePoll();
+      }, this.options.pollIntervalMs ?? CRYPTO_ONCHAIN_STATUS_POLL_MS);
+    }
+    setState(patch) {
+      var _a, _b;
+      this.state = { ...this.state, ...patch };
+      (_b = (_a = this.options).onChange) == null ? void 0 : _b.call(_a, this.state);
+      this.listeners.forEach((listener) => listener(this.state));
+    }
+  };
+  function messageOf(error) {
+    return error instanceof Error && error.message ? error.message : UNAVAILABLE;
+  }
+
+  // src/core/helpers/paymentsApiAnswer.ts
+  function readStartedPayment(answer) {
+    if (!answer || typeof answer !== "object" || Array.isArray(answer))
+      return null;
+    const { payment, order, paymentId, clientSecret, amount, currency, checkoutSessionId } = answer;
+    if (payment !== void 0 || order !== void 0)
+      return null;
+    if (typeof paymentId !== "string" || !paymentId || typeof clientSecret !== "string" || !clientSecret)
+      return null;
+    return {
+      paymentId,
+      clientSecret,
+      ...typeof amount === "number" ? { amount } : {},
+      ...typeof currency === "string" ? { currency } : {},
+      ...typeof checkoutSessionId === "string" ? { checkoutSessionId } : {}
+    };
+  }
+  var PENDING_KEY = "tgd_payments_api_return";
+  var PENDING_TTL_MS = 60 * 6e4;
+  function takeParkedPaymentsApiReturn(paymentId) {
+    try {
+      const raw = sessionStorage.getItem(PENDING_KEY);
+      if (!raw)
+        return null;
+      const parked = JSON.parse(raw);
+      if (parked.paymentId !== paymentId)
+        return null;
+      sessionStorage.removeItem(PENDING_KEY);
+      if (!parked.checkoutSessionId || !parked.at || Date.now() - parked.at > PENDING_TTL_MS)
+        return null;
+      return { checkoutSessionId: parked.checkoutSessionId };
+    } catch {
+      return null;
+    }
+  }
+
+  // src/core/helpers/oceanpayment.ts
+  var OCEAN_SDK_URL = "https://secure.oceanpayment.com/pages/js/oceanpayment.js";
+  var OCEAN_CONTAINER_ID = "oceanpayment-element";
+  var OCEAN_CALLBACK_TIMEOUT_MS = 12e4;
+  var OCEAN_LANGUAGE_OVERRIDES = { fi: "en" };
+  function oceanLanguage(locale) {
+    var _a;
+    const primary = (_a = locale == null ? void 0 : locale.split(/[-_]/)[0]) == null ? void 0 : _a.toLowerCase();
+    if (!primary)
+      return "en";
+    return OCEAN_LANGUAGE_OVERRIDES[primary] ?? primary;
+  }
+  var OCEAN_SDK_LOAD_TIMEOUT_MS = 3e4;
+  var oceanSdkLoading = null;
+  function loadOceanSdk() {
+    const w = window;
+    if (w.Oceanpayment)
+      return Promise.resolve(w.Oceanpayment);
+    if (oceanSdkLoading)
+      return oceanSdkLoading;
+    oceanSdkLoading = new Promise((resolve, reject) => {
+      const script2 = document.createElement("script");
+      const fail = (message) => {
+        clearTimeout(timer);
+        script2.remove();
+        oceanSdkLoading = null;
+        reject(new Error(message));
+      };
+      const timer = setTimeout(() => fail("The Ocean Payment card form took too long to load"), OCEAN_SDK_LOAD_TIMEOUT_MS);
+      script2.addEventListener("load", () => {
+        if (!w.Oceanpayment)
+          return fail("Ocean Payment script loaded without window.Oceanpayment");
+        clearTimeout(timer);
+        resolve(w.Oceanpayment);
+      });
+      script2.addEventListener("error", () => fail("Failed to load the Ocean Payment card form"));
+      script2.src = OCEAN_SDK_URL;
+      document.head.appendChild(script2);
+    });
+    return oceanSdkLoading;
+  }
+  var OCEAN_PENDING_KEY = "tgd:headless:oceanpayment:pending";
+  var OCEAN_PENDING_TTL_MS = 30 * 60 * 1e3;
+  function parkOceanPayment(paymentId) {
+    try {
+      sessionStorage.setItem(OCEAN_PENDING_KEY, JSON.stringify({ paymentId, at: Date.now() }));
+    } catch {
+    }
+  }
+  function takeParkedOceanPayment() {
+    try {
+      const raw = sessionStorage.getItem(OCEAN_PENDING_KEY);
+      if (!raw)
+        return void 0;
+      sessionStorage.removeItem(OCEAN_PENDING_KEY);
+      const { paymentId, at } = JSON.parse(raw);
+      if (!paymentId || !at || Date.now() - at > OCEAN_PENDING_TTL_MS)
+        return void 0;
+      return paymentId;
+    } catch {
+      return void 0;
+    }
+  }
+  function restoreOceanPaymentReturn() {
+    if (typeof window === "undefined")
+      return;
+    const paymentId = takeParkedOceanPayment();
+    if (!paymentId)
+      return;
+    try {
+      const url2 = new URL(window.location.href);
+      if (url2.searchParams.get("paymentId"))
+        return;
+      url2.searchParams.set("paymentId", paymentId);
+      url2.searchParams.set("paymentAction", "requireAction");
+      url2.searchParams.set("paymentActionStatus", "completed");
+      window.history.replaceState(window.history.state, "", url2.toString());
+    } catch {
+    }
+  }
+
   // src/core/modules/payment.ts
+  function loadPaymentsApiFlow() {
+    if (true) {
+      return Promise.reject(
+        new Error(
+          "This store takes payments through the Payments API, which the CDN build does not support yet: install @tagadapay/headless-sdk and @tagadapay/core-js 3.7.0 or later from npm."
+        )
+      );
+    }
+    return import("../helpers/paymentsApi.js");
+  }
+  var FAILED_PAYMENT_STATUSES = /* @__PURE__ */ new Set(["failed", "declined", "rejected", "error"]);
+  var oceanSlot = null;
+  var oceanSlotTaken = () => !!oceanSlot && (!oceanSlot.attached || oceanSlot.element.isConnected);
+  var OCEAN_TIMED_OUT = Symbol("ocean-timed-out");
+  var OCEAN_UNMOUNTED = Symbol("ocean-unmounted");
   var EXPRESS_METHOD_TYPES = /* @__PURE__ */ new Set(["apple_pay", "google_pay", "paypal", "klarna", "klarna_express", "link"]);
   function paymentMethodListEntryToConfig(entry) {
     var _a;
@@ -1247,6 +1622,11 @@ var TagadaHeadlessBundle = (() => {
        * without a second network round-trip inside Apple's authorization window.
        */
       this.lastPaymentSetup = null;
+      /**
+       * Payments API (V3) store: what the pay call knew about each payment it started (the session it
+       * pays, the shopper's method), so `finalize()` can confirm it from the bare pay answer.
+       */
+      this.paymentsApiStarts = /* @__PURE__ */ new Map();
     }
     // ---------------------------------------------------------------------------
     // Discovery: what payment methods are available?
@@ -1457,7 +1837,7 @@ var TagadaHeadlessBundle = (() => {
      */
     async pay(opts) {
       if (opts.tagadaToken && !opts.paymentInstrumentId) {
-        return this.http.post("/api/v1/payment/pay-with-token", {
+        return this.rememberPaymentsApiStart(await this.http.post("/api/v1/payment/pay-with-token", {
           tagadaToken: opts.tagadaToken,
           checkoutSessionId: opts.checkoutSessionId,
           returnUrl: opts.returnUrl,
@@ -1466,9 +1846,9 @@ var TagadaHeadlessBundle = (() => {
           paymentMethod: opts.paymentMethod,
           isExpress: opts.isExpress,
           metadata: opts.metadata
-        });
+        }), opts);
       }
-      return this.http.post("/api/public/v1/checkout/pay-v2", {
+      return this.rememberPaymentsApiStart(await this.http.post("/api/public/v1/checkout/pay-v2", {
         checkoutSessionId: opts.checkoutSessionId,
         paymentInstrumentId: opts.paymentInstrumentId,
         storeId: this.storeId,
@@ -1479,14 +1859,14 @@ var TagadaHeadlessBundle = (() => {
         isExpress: opts.isExpress,
         metadata: opts.metadata,
         returnUrl: opts.returnUrl
-      });
+      }), opts);
     }
     /**
      * Low-level pay: process payment with an existing instrument or for APM/express flows
      * where no instrument is needed (redirect-based methods).
      */
     async payDirect(opts) {
-      return this.http.post("/api/public/v1/checkout/pay-v2", {
+      return this.rememberPaymentsApiStart(await this.http.post("/api/public/v1/checkout/pay-v2", {
         checkoutSessionId: opts.checkoutSessionId,
         paymentInstrumentId: opts.paymentInstrumentId ?? "",
         storeId: this.storeId,
@@ -1496,7 +1876,7 @@ var TagadaHeadlessBundle = (() => {
         isExpress: opts.isExpress,
         threedsSessionId: opts.threedsSessionId,
         returnUrl: opts.returnUrl
-      });
+      }), opts);
     }
     /**
      * Persist a wallet contact onto the session before the charge.
@@ -1701,6 +2081,228 @@ var TagadaHeadlessBundle = (() => {
       });
     }
     // ---------------------------------------------------------------------------
+    // On-chain crypto (`crypto_onchain`)
+    // ---------------------------------------------------------------------------
+    /**
+     * Networks and coins the store accepts for on-chain crypto on this checkout session. On-chain
+     * crypto is paid from your page (address, exact amount, QR) and never through `pay()` /
+     * `processApm()`: pay-v2 refuses it with `422 CRYPTO_ONCHAIN_INLINE_ONLY`.
+     */
+    async getCryptoOnchainOptions(checkoutSessionId) {
+      return this.http.get(
+        `/api/v1/checkout-sessions/${encodeURIComponent(checkoutSessionId)}/crypto-onchain/options`
+      );
+    }
+    /**
+     * Create the order's on-chain payment for a network and a coin, or re-quote it (another coin,
+     * an expired quote): the deposit address, exact amount and wallet URI for the QR code. Save the
+     * customer and address on the session first.
+     */
+    async createCryptoOnchainPayment(opts) {
+      return this.http.post(
+        `/api/v1/checkout-sessions/${encodeURIComponent(opts.checkoutSessionId)}/crypto-onchain/session`,
+        { chainId: opts.chainId, asset: opts.asset }
+      );
+    }
+    /** The payment's state; poll it every few seconds until `paid` (or underpaid / expired / failed). */
+    async getCryptoOnchainStatus(opts) {
+      return this.http.get(
+        `/api/v1/checkout-sessions/${encodeURIComponent(opts.checkoutSessionId)}/crypto-onchain/status`,
+        { params: { cryptoOnchainPaymentId: opts.cryptoOnchainPaymentId } }
+      );
+    }
+    /**
+     * The whole inline crypto payment of a checkout session, the way the hosted checkout runs it.
+     *
+     * @example
+     * ```ts
+     * const crypto = tagada.payment.createCryptoOnchainCheckout({
+     *   checkoutSessionId: session.id,
+     *   onPaid: ({ orderId }) => showThankYou(orderId),
+     * });
+     * crypto.subscribe(render); // networks, selection, payment (address, amount, paymentUri), status
+     * await crypto.loadOptions();
+     * payButton.onclick = () => crypto.pay(); // after saving the customer and address
+     * ```
+     */
+    createCryptoOnchainCheckout(opts) {
+      return new CryptoOnchainCheckout(this, opts);
+    }
+    // ---------------------------------------------------------------------------
+    // Ocean Payment
+    // ---------------------------------------------------------------------------
+    /** Whether the store's Ocean Payment integration renders its inline card form or redirects. */
+    async getOceanPaymentConfig(checkoutSessionId) {
+      const data = await this.http.post(
+        `/api/v1/checkout-sessions/${checkoutSessionId}/oceanpayment-embedded-config`,
+        {}
+      );
+      return { embedded: !!(data == null ? void 0 : data.embedded), sandboxed: !!(data == null ? void 0 : data.sandboxed) };
+    }
+    /**
+     * Set up Ocean Payment for a checkout session, the way the hosted checkout
+     * does: Ocean's card fields render inside `container` when the integration
+     * has Ocean's public key (`embedded`), otherwise `pay()` sends the shopper
+     * to Ocean's page and back to `returnUrl` (`redirect`).
+     *
+     * @example
+     * ```ts
+     * const ocean = await tagada.payment.mountOceanPayment({
+     *   checkoutSessionId: session.id,
+     *   container: '#ocean-card',
+     * });
+     * payButton.onclick = async () => {
+     *   const result = await ocean.pay();
+     *   if (result.status === 'requires_redirect') window.location.href = result.redirectUrl;
+     *   else if (result.status === 'succeeded') showThankYou(result.order);
+     *   else if (result.status === 'failed') showError(result.error);
+     * };
+     * ```
+     */
+    async mountOceanPayment(opts) {
+      if (typeof window === "undefined")
+        throw new Error("Ocean Payment needs a browser");
+      const { checkoutSessionId, signal } = opts;
+      const aborted = () => Object.assign(new Error("Ocean Payment mount aborted"), { name: "AbortError" });
+      if (signal == null ? void 0 : signal.aborted)
+        throw aborted();
+      const host = typeof opts.container === "string" ? document.querySelector(opts.container) : opts.container;
+      if (!host && opts.mode !== "redirect") {
+        throw new Error(`Ocean Payment container not found: ${String(opts.container)}`);
+      }
+      if (oceanSlotTaken() || document.getElementById(OCEAN_CONTAINER_ID)) {
+        throw new Error("An Ocean Payment card form is already mounted on this page");
+      }
+      const w = window;
+      const element = document.createElement("div");
+      element.id = OCEAN_CONTAINER_ID;
+      const slot = { element, attached: false };
+      oceanSlot = slot;
+      const releaseSlot = () => {
+        if (oceanSlot === slot)
+          oceanSlot = null;
+      };
+      let mounted = true;
+      let pendingCallback = null;
+      const callback = (data) => {
+        const resolve = pendingCallback;
+        pendingCallback = null;
+        resolve == null ? void 0 : resolve(data);
+      };
+      const unmount = () => {
+        if (!mounted)
+          return;
+        mounted = false;
+        if (w.oceanpaymentCallBack === callback)
+          delete w.oceanpaymentCallBack;
+        element.remove();
+        releaseSlot();
+        callback(OCEAN_UNMOUNTED);
+      };
+      signal == null ? void 0 : signal.addEventListener("abort", unmount, { once: true });
+      let config;
+      let ocean;
+      try {
+        config = opts.mode === "redirect" ? { embedded: false, sandboxed: false } : await this.getOceanPaymentConfig(checkoutSessionId);
+        if (signal == null ? void 0 : signal.aborted)
+          throw aborted();
+        if (config.embedded) {
+          ocean = await loadOceanSdk();
+          if (signal == null ? void 0 : signal.aborted)
+            throw aborted();
+        }
+      } catch (error) {
+        unmount();
+        throw error;
+      }
+      let submitting = false;
+      if (!ocean) {
+        releaseSlot();
+        return {
+          mode: "redirect",
+          pay: async () => {
+            if (!mounted)
+              return { status: "failed", error: "The Ocean Payment form was removed" };
+            if (submitting)
+              return { status: "failed", error: "Payment already in progress" };
+            submitting = true;
+            try {
+              const data = await this.http.post(
+                `/api/v1/checkout-sessions/${checkoutSessionId}/oceanpayment-link`,
+                { returnUrl: opts.returnUrl ?? window.location.href }
+              );
+              if (!(data == null ? void 0 : data.url) || !data.paymentId) {
+                return { status: "failed", error: "Ocean Payment is not available for this store" };
+              }
+              return { status: "requires_redirect", redirectUrl: data.url, method: "GET", paymentId: data.paymentId };
+            } catch (error) {
+              return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+            } finally {
+              submitting = false;
+            }
+          },
+          unmount
+        };
+      }
+      const sdk = ocean;
+      host.appendChild(element);
+      slot.attached = true;
+      w.oceanpaymentCallBack = callback;
+      const backUrl = window.location.href;
+      sdk.init(config.sandboxed, "", oceanLanguage(opts.locale), { showCardName: false });
+      const pay = async () => {
+        if (!mounted)
+          return { status: "failed", error: "The Ocean Payment card form was removed" };
+        if (submitting)
+          return { status: "failed", error: "Payment already in progress" };
+        submitting = true;
+        try {
+          const created = await this.http.post(
+            `/api/v1/checkout-sessions/${checkoutSessionId}/oceanpayment-embedded-payment`,
+            { backUrl }
+          );
+          if (!(created == null ? void 0 : created.paymentId) || !created.params) {
+            return { status: "failed", error: "Failed to start the payment" };
+          }
+          const paymentId = created.paymentId;
+          const answer = await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+              pendingCallback = null;
+              resolve(OCEAN_TIMED_OUT);
+            }, OCEAN_CALLBACK_TIMEOUT_MS);
+            pendingCallback = (data) => {
+              clearTimeout(timer);
+              resolve(data);
+            };
+            sdk.checkout(created.params);
+          });
+          if (answer === OCEAN_TIMED_OUT || answer === OCEAN_UNMOUNTED) {
+            return this.pollUntilDone(paymentId);
+          }
+          if (answer && typeof answer === "object" && "msg" in answer) {
+            return { status: "failed", error: String(answer.msg || "Please check your card details.") };
+          }
+          const result = await this.http.post(
+            `/api/v1/checkout-sessions/${checkoutSessionId}/oceanpayment-embedded-result`,
+            { paymentId, response: String(answer) }
+          );
+          if ((result == null ? void 0 : result.status) === "requires_action" && result.payUrl) {
+            parkOceanPayment(paymentId);
+            return { status: "requires_redirect", redirectUrl: result.payUrl, method: "GET", paymentId };
+          }
+          if ((result == null ? void 0 : result.status) === "succeeded" || (result == null ? void 0 : result.status) === "pending") {
+            return this.pollUntilDone(paymentId);
+          }
+          return { status: "failed", error: (result == null ? void 0 : result.message) || "Payment declined" };
+        } catch (error) {
+          return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+        } finally {
+          submitting = false;
+        }
+      };
+      return { mode: "embedded", pay, unmount };
+    }
+    // ---------------------------------------------------------------------------
     // High-level orchestrator — the ONE function beginners should call
     // ---------------------------------------------------------------------------
     /**
@@ -1757,6 +2359,11 @@ var TagadaHeadlessBundle = (() => {
       var _a, _b, _c;
       const payment = input.payment;
       const returnUrl = (opts == null ? void 0 : opts.returnUrl) ?? (typeof window !== "undefined" ? window.location.href : void 0);
+      if (!payment) {
+        const started = readStartedPayment(input);
+        if (started)
+          return this.finalizeOnPaymentsApi(started, returnUrl);
+      }
       if (payment.status === "succeeded") {
         this.emitPaid((_a = input.order) == null ? void 0 : _a.id, payment);
         return { status: "succeeded", payment, order: input.order };
@@ -1777,6 +2384,11 @@ var TagadaHeadlessBundle = (() => {
      * You can also call it manually in non-React apps.
      */
     async resumeAfterRedirect(paymentId) {
+      const parked = takeParkedPaymentsApiReturn(paymentId);
+      if (parked) {
+        const url2 = typeof window !== "undefined" ? window.location.href : void 0;
+        return this.onPaymentsApi((flow, host) => flow.resumeOnPaymentsApi(host, paymentId, parked.checkoutSessionId, url2));
+      }
       return this.pollUntilDone(paymentId);
     }
     /**
@@ -1812,6 +2424,8 @@ var TagadaHeadlessBundle = (() => {
     async maybeResumeFromUrl(opts) {
       if (typeof window === "undefined" && !(opts == null ? void 0 : opts.url))
         return null;
+      if (!(opts == null ? void 0 : opts.url))
+        restoreOceanPaymentReturn();
       const href = (opts == null ? void 0 : opts.url) ?? window.location.href;
       let url2;
       try {
@@ -1867,7 +2481,7 @@ var TagadaHeadlessBundle = (() => {
       const start = Date.now();
       while (Date.now() - start < timeout) {
         const status = await this.getPaymentStatus(paymentId);
-        if (status.status === "succeeded" || status.status === "failed" || status.status === "declined") {
+        if (status.status === "succeeded" || FAILED_PAYMENT_STATUSES.has(status.status)) {
           return status;
         }
         await new Promise((r) => setTimeout(r, interval));
@@ -2050,7 +2664,7 @@ var TagadaHeadlessBundle = (() => {
           }
           return { status: "succeeded", payment: status, order: status.order };
         }
-        if (status.status === "failed" || status.status === "declined") {
+        if (FAILED_PAYMENT_STATUSES.has(status.status)) {
           return { status: "failed", error: status.status, payment: status };
         }
         if (status.requireAction && status.requireAction !== "none" && status.requireActionData && !status.requireActionData.processed) {
@@ -2064,6 +2678,48 @@ var TagadaHeadlessBundle = (() => {
       return { status: "pending", paymentId };
     }
     // ---------------------------------------------------------------------------
+    // Internal: Payments API (V3) stores
+    // ---------------------------------------------------------------------------
+    /** Keeps what a V3 pay answer does not say (its session, the method); returns the answer as is. */
+    rememberPaymentsApiStart(answer, opts) {
+      const started = answer && !answer.payment ? readStartedPayment(answer) : null;
+      if (started) {
+        this.paymentsApiStarts.set(started.paymentId, {
+          checkoutSessionId: started.checkoutSessionId ?? opts.checkoutSessionId,
+          ...opts.paymentMethod ? { paymentMethod: opts.paymentMethod } : {}
+        });
+      }
+      return answer;
+    }
+    /** Confirms a started V3 payment with payments-js and runs it to the V2-shaped result. */
+    finalizeOnPaymentsApi(started, returnUrl) {
+      const known = this.paymentsApiStarts.get(started.paymentId);
+      this.paymentsApiStarts.delete(started.paymentId);
+      return this.onPaymentsApi(
+        (flow, host) => flow.finalizeOnPaymentsApi(host, started, {
+          checkoutSessionId: known == null ? void 0 : known.checkoutSessionId,
+          paymentMethod: known == null ? void 0 : known.paymentMethod,
+          returnUrl
+        })
+      );
+    }
+    /** Runs `run` with the lazily imported V3 flow; a flow that cannot load is a failed payment. */
+    async onPaymentsApi(run) {
+      let flow;
+      try {
+        flow = await loadPaymentsApiFlow();
+      } catch (error) {
+        return { status: "failed", error: error instanceof Error ? error.message : String(error) };
+      }
+      return run(flow, {
+        http: this.http,
+        storeId: this.storeId,
+        checkout: this.checkout,
+        stepConfig: this.readInjectedStepConfigRaw(),
+        onPaid: (orderId, payment) => this.emitPaid(orderId, payment)
+      });
+    }
+    // ---------------------------------------------------------------------------
     // Internal helpers
     // ---------------------------------------------------------------------------
     /**
@@ -2083,6 +2739,19 @@ var TagadaHeadlessBundle = (() => {
         return null;
       }
     }
+    /** The whole injected step config (Tagada-hosted pages), or null. */
+    readInjectedStepConfigRaw() {
+      if (typeof window === "undefined")
+        return null;
+      const raw = window.__TGD_STEP_CONFIG__;
+      if (!raw)
+        return null;
+      try {
+        return typeof raw === "string" ? JSON.parse(raw) : raw;
+      } catch {
+        return null;
+      }
+    }
     /** Tracking hook. Never throws, never awaits: a pixel must not be able to break a payment. */
     emitPaid(orderId, payment) {
       var _a;
@@ -2115,7 +2784,7 @@ var TagadaHeadlessBundle = (() => {
 
   // src/core/modules/lazyCommerce.ts
   var script = typeof document === "undefined" ? null : document.currentScript;
-  var url = (script == null ? void 0 : script.src) ? new URL("tagada-headless-commerce.min.js", script.src).href : "https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk@1.20.0/dist/tagada-headless-commerce.min.js";
+  var url = (script == null ? void 0 : script.src) ? new URL("tagada-headless-commerce.min.js", script.src).href : "https://cdn.jsdelivr.net/npm/@tagadapay/headless-sdk@1.21.0/dist/tagada-headless-commerce.min.js";
   var loading;
   function loadCommerce() {
     if (window.TagadaHeadlessCommerce)