@shoppexio/storefront 1.0.63 → 1.0.64

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.64
+
+- Resolve checkout verification challenges automatically: `checkout()` and `buildCheckoutUrl()` mount the hosted broker themselves on a challenge refusal and replay the create once with the delivered proof — no merchant wiring, no second click. `mountCheckoutChallenge()` gains an `onVisibilityChange` callback.
+
 ## 1.0.63
 
 - Keep managed checkout verification collapsed until Cloudflare requires buyer interaction.

package/README.md

@@ -66,6 +66,46 @@ currency-bound; Shoppex rejects a mismatch as
 `errors.checkout.quote_token_stale` instead of creating an invoice for a total
 the buyer did not approve.
 
+## Checkout verification on custom domains
+
+Shoppex can require human verification before it creates an invoice. Use the
+hosted verification broker from the SDK. Do not render the returned Turnstile
+site key directly on your custom domain.
+
+```ts
+import shoppex, { mountCheckoutChallenge } from '@shoppexio/storefront';
+
+const container = document.getElementById('checkout-verification');
+let frame: ReturnType<typeof mountCheckoutChallenge> | undefined;
+
+if (!container) throw new Error('Checkout verification container is missing.');
+
+async function startCheckout(turnstileToken?: string) {
+  const result = await shoppex.checkout({ turnstileToken });
+
+  if (result.success) return;
+  if (!result.challenge) throw new Error(result.message ?? 'Checkout could not be started.');
+
+  frame?.dispose();
+  frame = mountCheckoutChallenge(container, result.challenge, {
+    onSuccess(token) {
+      frame?.dispose();
+      frame = undefined;
+      void startCheckout(token);
+    },
+    onUnavailable() {
+      frame?.dispose();
+      frame = undefined;
+      console.error('Checkout verification could not load.');
+    },
+  });
+}
+```
+
+If your site sends a Content Security Policy, add
+`https://checkout.shoppex.io` to `frame-src`. Call `dispose()` when the checkout
+component unmounts or before you mount another challenge.
+
 ## Custom customer account
 
 Build your own OTP login, order history, and download UI without adding a

package/dist/index.cjs

@@ -19934,6 +19934,152 @@ async function quoteCart(coupon, currency) {
   return response;
 }
 
+// ../sdk/src/modules/checkout-challenge.ts
+var TURNSTILE_FRAME_MESSAGE_SOURCE = "shoppex-turnstile";
+var TURNSTILE_FRAME_MESSAGE_VERSION = 1;
+var TURNSTILE_FRAME_READY_TIMEOUT_MS = 1e4;
+function readFrameMessage(value, nonce) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record2 = value;
+  if (record2.source !== TURNSTILE_FRAME_MESSAGE_SOURCE || record2.version !== TURNSTILE_FRAME_MESSAGE_VERSION || record2.nonce !== nonce || !["ready", "visible", "hidden", "success", "expired", "timeout", "error"].includes(String(record2.type))) return null;
+  if (record2.type === "success" && (typeof record2.token !== "string" || !record2.token.trim())) {
+    return null;
+  }
+  return {
+    type: record2.type,
+    ...typeof record2.token === "string" ? { token: record2.token.trim() } : {}
+  };
+}
+var AUTO_CHALLENGE_INVISIBLE_TIMEOUT_MS = 3e4;
+async function resolveCheckoutChallengeProof(challenge) {
+  if (typeof document === "undefined" || challenge.provider !== "turnstile" || !challenge.siteKey.trim()) {
+    return null;
+  }
+  const host = document.createElement("div");
+  host.setAttribute("data-shoppex-checkout-challenge", "");
+  host.style.position = "fixed";
+  host.style.inset = "0";
+  host.style.display = "none";
+  host.style.alignItems = "center";
+  host.style.justifyContent = "center";
+  host.style.background = "rgba(0, 0, 0, 0.55)";
+  host.style.zIndex = "2147483646";
+  const card = document.createElement("div");
+  card.style.width = "min(340px, 90vw)";
+  card.style.background = "#ffffff";
+  card.style.borderRadius = "12px";
+  card.style.padding = "16px";
+  card.style.boxShadow = "0 12px 40px rgba(0, 0, 0, 0.35)";
+  host.appendChild(card);
+  document.body.appendChild(host);
+  return new Promise((resolve) => {
+    let settled = false;
+    let timeoutId = null;
+    let frame = null;
+    const finish = (token) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId !== null) window.clearTimeout(timeoutId);
+      frame?.dispose();
+      host.remove();
+      resolve(token);
+    };
+    const armTimeout = () => {
+      timeoutId = window.setTimeout(() => finish(null), AUTO_CHALLENGE_INVISIBLE_TIMEOUT_MS);
+    };
+    try {
+      frame = mountCheckoutChallenge(card, challenge, {
+        onSuccess: (token) => finish(token),
+        // `refresh-expired: auto` renews expired runs on its own; the
+        // invisible-run timeout stays the bound.
+        onExpired: () => {
+        },
+        onUnavailable: () => finish(null),
+        onVisibilityChange: (visible) => {
+          host.style.display = visible ? "flex" : "none";
+          if (visible) {
+            if (timeoutId !== null) {
+              window.clearTimeout(timeoutId);
+              timeoutId = null;
+            }
+          } else if (timeoutId === null && !settled) {
+            armTimeout();
+          }
+        }
+      });
+    } catch {
+      host.remove();
+      resolve(null);
+      return;
+    }
+    armTimeout();
+  });
+}
+function mountCheckoutChallenge(container, challenge, callbacks) {
+  if (challenge.provider !== "turnstile" || !challenge.siteKey.trim()) {
+    throw new Error("Checkout challenge is invalid.");
+  }
+  const win = container.ownerDocument.defaultView;
+  if (!win) throw new Error("Checkout challenge requires a browser document.");
+  const checkoutBaseUrl = getConfig().checkoutBaseUrl;
+  const frameUrl = new URL("/turnstile", checkoutBaseUrl);
+  if (frameUrl.protocol !== "https:" && frameUrl.protocol !== "http:") {
+    throw new Error("Checkout base URL must use http or https.");
+  }
+  const nonce = win.crypto.randomUUID();
+  frameUrl.searchParams.set("site_key", challenge.siteKey.trim());
+  frameUrl.searchParams.set("nonce", nonce);
+  const frame = container.ownerDocument.createElement("iframe");
+  frame.src = frameUrl.toString();
+  frame.title = "Checkout verification";
+  frame.referrerPolicy = "no-referrer";
+  frame.style.border = "0";
+  frame.style.width = "100%";
+  frame.style.height = "0";
+  let disposed = false;
+  let ready = false;
+  const readyTimeout = win.setTimeout(() => {
+    if (!disposed && !ready) callbacks.onUnavailable?.();
+  }, TURNSTILE_FRAME_READY_TIMEOUT_MS);
+  const onMessage = (event) => {
+    if (disposed || event.origin !== frameUrl.origin || event.source !== frame.contentWindow) return;
+    const message = readFrameMessage(event.data, nonce);
+    if (!message) return;
+    ready = true;
+    win.clearTimeout(readyTimeout);
+    if (message.type === "visible") {
+      frame.style.height = "72px";
+      callbacks.onVisibilityChange?.(true);
+    }
+    if (message.type === "hidden") {
+      frame.style.height = "0";
+      callbacks.onVisibilityChange?.(false);
+    }
+    if (message.type === "success") {
+      frame.style.height = "0";
+      callbacks.onVisibilityChange?.(false);
+      callbacks.onSuccess(message.token);
+    }
+    if (message.type === "expired" || message.type === "timeout") callbacks.onExpired?.();
+    if (message.type === "error") callbacks.onUnavailable?.();
+  };
+  const onFrameError = () => callbacks.onUnavailable?.();
+  win.addEventListener("message", onMessage);
+  frame.addEventListener("error", onFrameError, { once: true });
+  container.appendChild(frame);
+  return {
+    element: frame,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      win.clearTimeout(readyTimeout);
+      win.removeEventListener("message", onMessage);
+      frame.removeEventListener("error", onFrameError);
+      frame.remove();
+    }
+  };
+}
+
 // ../sdk/src/modules/checkout.ts
 var CheckoutCreateError = class _CheckoutCreateError extends Error {
   constructor(message, options = {}) {
@@ -20176,6 +20322,16 @@ function mapCartItemsForApi(items) {
 }
 async function checkout(couponOrOptions, options) {
   const resolvedOptions = resolveCheckoutOptions(couponOrOptions, options);
+  const firstAttempt = await performCheckout(resolvedOptions);
+  if (!firstAttempt.success && firstAttempt.challenge?.provider === "turnstile" && !resolvedOptions.turnstileToken && typeof document !== "undefined") {
+    const proof = await resolveCheckoutChallengeProof(firstAttempt.challenge);
+    if (proof) {
+      return performCheckout({ ...resolvedOptions, turnstileToken: proof });
+    }
+  }
+  return firstAttempt;
+}
+async function performCheckout(resolvedOptions) {
   const { autoRedirect = true, email: email3 } = resolvedOptions;
   const checkoutCodes = resolveCheckoutCodes(resolvedOptions);
   const normalizedCoupon = checkoutCodes.coupon;
@@ -20293,6 +20449,19 @@ async function checkout(couponOrOptions, options) {
 }
 async function buildCheckoutUrl(couponOrOptions, options) {
   const resolvedOptions = resolveCheckoutOptions(couponOrOptions, options);
+  try {
+    return await performBuildCheckoutUrl(resolvedOptions);
+  } catch (error51) {
+    if (error51 instanceof CheckoutCreateError && error51.challenge?.provider === "turnstile" && !resolvedOptions.turnstileToken && typeof document !== "undefined") {
+      const proof = await resolveCheckoutChallengeProof(error51.challenge);
+      if (proof) {
+        return performBuildCheckoutUrl({ ...resolvedOptions, turnstileToken: proof });
+      }
+    }
+    throw error51;
+  }
+}
+async function performBuildCheckoutUrl(resolvedOptions) {
   const { email: email3 } = resolvedOptions;
   const checkoutCodes = resolveCheckoutCodes(resolvedOptions);
   const normalizedCoupon = checkoutCodes.coupon;
@@ -20381,80 +20550,6 @@ function buildCheckoutUrlSync() {
   throw new Error("buildCheckoutUrlSync is deprecated. Use buildCheckoutUrl (async) instead.");
 }
 
-// ../sdk/src/modules/checkout-challenge.ts
-var TURNSTILE_FRAME_MESSAGE_SOURCE = "shoppex-turnstile";
-var TURNSTILE_FRAME_MESSAGE_VERSION = 1;
-var TURNSTILE_FRAME_READY_TIMEOUT_MS = 1e4;
-function readFrameMessage(value, nonce) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const record2 = value;
-  if (record2.source !== TURNSTILE_FRAME_MESSAGE_SOURCE || record2.version !== TURNSTILE_FRAME_MESSAGE_VERSION || record2.nonce !== nonce || !["ready", "visible", "hidden", "success", "expired", "timeout", "error"].includes(String(record2.type))) return null;
-  if (record2.type === "success" && (typeof record2.token !== "string" || !record2.token.trim())) {
-    return null;
-  }
-  return {
-    type: record2.type,
-    ...typeof record2.token === "string" ? { token: record2.token.trim() } : {}
-  };
-}
-function mountCheckoutChallenge(container, challenge, callbacks) {
-  if (challenge.provider !== "turnstile" || !challenge.siteKey.trim()) {
-    throw new Error("Checkout challenge is invalid.");
-  }
-  const win = container.ownerDocument.defaultView;
-  if (!win) throw new Error("Checkout challenge requires a browser document.");
-  const checkoutBaseUrl = getConfig().checkoutBaseUrl;
-  const frameUrl = new URL("/turnstile", checkoutBaseUrl);
-  if (frameUrl.protocol !== "https:" && frameUrl.protocol !== "http:") {
-    throw new Error("Checkout base URL must use http or https.");
-  }
-  const nonce = win.crypto.randomUUID();
-  frameUrl.searchParams.set("site_key", challenge.siteKey.trim());
-  frameUrl.searchParams.set("nonce", nonce);
-  const frame = container.ownerDocument.createElement("iframe");
-  frame.src = frameUrl.toString();
-  frame.title = "Checkout verification";
-  frame.referrerPolicy = "no-referrer";
-  frame.style.border = "0";
-  frame.style.width = "100%";
-  frame.style.height = "0";
-  let disposed = false;
-  let ready = false;
-  const readyTimeout = win.setTimeout(() => {
-    if (!disposed && !ready) callbacks.onUnavailable?.();
-  }, TURNSTILE_FRAME_READY_TIMEOUT_MS);
-  const onMessage = (event) => {
-    if (disposed || event.origin !== frameUrl.origin || event.source !== frame.contentWindow) return;
-    const message = readFrameMessage(event.data, nonce);
-    if (!message) return;
-    ready = true;
-    win.clearTimeout(readyTimeout);
-    if (message.type === "visible") frame.style.height = "72px";
-    if (message.type === "hidden") frame.style.height = "0";
-    if (message.type === "success") {
-      frame.style.height = "0";
-      callbacks.onSuccess(message.token);
-    }
-    if (message.type === "expired" || message.type === "timeout") callbacks.onExpired?.();
-    if (message.type === "error") callbacks.onUnavailable?.();
-  };
-  const onFrameError = () => callbacks.onUnavailable?.();
-  win.addEventListener("message", onMessage);
-  frame.addEventListener("error", onFrameError, { once: true });
-  container.appendChild(frame);
-  return {
-    element: frame,
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      win.clearTimeout(readyTimeout);
-      win.removeEventListener("message", onMessage);
-      frame.removeEventListener("error", onFrameError);
-      frame.remove();
-    }
-  };
-}
-
 // ../sdk/src/modules/coupons.ts
 async function resolveShopId() {
   const cachedShopId2 = getShopId();