@funnelfox/billing 0.9.1 → 0.9.3-feat-defer-session-on-interaction.34

package/dist/chunk-index.cjs.js

@@ -491,7 +491,7 @@ exports.PaymentMethod = void 0;
 /**
  * @fileoverview Constants for Funnefox SDK
  */
-const SDK_VERSION = '0.9.1';
+const SDK_VERSION = '0.9.3-feat-defer-session-on-interaction.34';
 const DEFAULTS = {
     BASE_URL: 'https://billing.funnelfox.com',
     REGION: 'default',
@@ -628,6 +628,141 @@ function requireString(value, fieldName) {
     return true;
 }
 
+/**
+ * @fileoverview Support for Apple's official <apple-pay-button> custom element.
+ *
+ * Primer's checkout-web v2 renders the Apple Pay button through the CSS
+ * approach (-webkit-appearance: -apple-pay-button), and WebKit only accepts
+ * the 7 legacy values for -apple-pay-button-type. Newer types such as
+ * 'continue' are silently dropped and fall back to 'plain' (verified in
+ * Safari 26 on macOS and iOS — see PRD-1426).
+ *
+ * Apple's official custom element supports the full set of button types, so
+ * for "native-only" types we overlay it on top of the (visually hidden)
+ * Primer button and forward clicks, keeping Primer's payment flow untouched.
+ */
+const APPLE_PAY_SDK_URL = 'https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js';
+/** How long to wait for the <apple-pay-button> element definition before
+ * giving up and falling back to Primer's own button. */
+const ELEMENT_DEFINITION_TIMEOUT_MS = 4000;
+/**
+ * Button types WebKit can render through Primer's CSS approach.
+ * Everything outside this list requires the native <apple-pay-button> element.
+ */
+const CSS_RENDERABLE_APPLE_PAY_TYPES = [
+    'plain',
+    'buy',
+    'set-up',
+    'donate',
+    'check-out',
+    'book',
+    'subscribe',
+];
+/**
+ * Returns true when the requested Apple Pay buttonType can only be rendered
+ * with Apple's native <apple-pay-button> element.
+ */
+function isNativeOnlyApplePayButtonType(type) {
+    return !!type && !CSS_RENDERABLE_APPLE_PAY_TYPES.includes(type);
+}
+/**
+ * Loads Apple's apple-pay-sdk.js (defines the <apple-pay-button> custom
+ * element). Resolves to true when the element is available.
+ */
+async function loadApplePayButtonElement() {
+    if (typeof window === 'undefined' || !window.customElements) {
+        return false;
+    }
+    if (window.customElements.get('apple-pay-button')) {
+        return true;
+    }
+    try {
+        await loadScript$1({
+            src: APPLE_PAY_SDK_URL,
+            crossOrigin: 'anonymous',
+            appendTo: 'head',
+        });
+        // Never hang on a script that loaded but did not define the element —
+        // fall back to Primer's own button instead.
+        const defined = window.customElements
+            .whenDefined('apple-pay-button')
+            .then(() => true);
+        const timeout = new Promise(resolve => {
+            setTimeout(() => resolve(false), ELEMENT_DEFINITION_TIMEOUT_MS);
+        });
+        return await Promise.race([defined, timeout]);
+    }
+    catch {
+        return false;
+    }
+}
+function createNativeApplePayElement(options) {
+    const native = document.createElement('apple-pay-button');
+    native.setAttribute('type', options.buttonType);
+    native.setAttribute('buttonstyle', options.buttonStyle || 'black');
+    native.setAttribute('locale', (typeof navigator !== 'undefined' && navigator.language) || 'en-US');
+    native.style.cssText = [
+        'position:absolute',
+        'inset:0',
+        'width:100%',
+        'height:100%',
+        '--apple-pay-button-width:100%',
+        '--apple-pay-button-height:100%',
+        '--apple-pay-button-border-radius:28px',
+        'display:block',
+        'cursor:pointer',
+        'z-index:1',
+    ].join(';');
+    return native;
+}
+/**
+ * Renders Apple's native <apple-pay-button> stretched over `wrapper` and
+ * forwards clicks to the Primer-rendered <button> inside it. The synchronous
+ * forwarded click preserves the user activation required by ApplePaySession.
+ *
+ * Returns the overlay element, or null when the Apple Pay SDK could not be
+ * loaded (callers should keep Primer's own button visible as a fallback).
+ */
+async function overlayNativeApplePayButton(wrapper, options) {
+    const available = await loadApplePayButtonElement();
+    if (!available) {
+        return null;
+    }
+    // The overlay is only safe when Primer's own clickable button is present —
+    // otherwise there is nothing to forward the click to.
+    if (!wrapper.querySelector('button')) {
+        return null;
+    }
+    const native = createNativeApplePayElement(options);
+    wrapper.style.position = 'relative';
+    native.addEventListener('click', () => {
+        const primerButton = wrapper.querySelector('button');
+        primerButton?.click();
+    });
+    wrapper.appendChild(native);
+    return native;
+}
+/**
+ * Renders the native button with no Primer button behind it, for the deferred
+ * flow: the visitor sees the real Apple Pay button immediately while the
+ * client session is still un-created. `onActivate` fires on tap so the caller
+ * can start (or await) initialization.
+ *
+ * Returns null when Apple's SDK is unavailable — callers must fall back to
+ * creating the session eagerly so a button of some kind is always rendered.
+ */
+async function renderPlaceholderApplePayButton(wrapper, options) {
+    const available = await loadApplePayButtonElement();
+    if (!available) {
+        return null;
+    }
+    const native = createNativeApplePayElement(options);
+    wrapper.style.position = 'relative';
+    native.addEventListener('click', options.onActivate);
+    wrapper.appendChild(native);
+    return native;
+}
+
 /**
  * @fileoverview Primer SDK integration wrapper
  */
@@ -666,6 +801,7 @@ class PrimerWrapper {
     }
     async createHeadlessCheckout(clientToken, options, method) {
         await this.ensurePrimerLoaded();
+        this.applePayOptions = options.applePay;
         this.currentHeadless = PrimerWrapper.headlessManager.getOrCreate(clientToken, options, method);
         return this.currentHeadless;
     }
@@ -712,16 +848,53 @@ class PrimerWrapper {
             }
             htmlNode.appendChild(wrapper);
             /* end hack */
+            /* PRD-1426: WebKit cannot render newer Apple Pay button types (e.g.
+             * 'continue') through the CSS approach Primer v2 uses. For those types
+             * we overlay Apple's official <apple-pay-button> element on top of the
+             * visually hidden Primer button and forward clicks, keeping Primer's
+             * payment flow untouched. The Primer button is hidden BEFORE it renders
+             * to avoid a flash of the plain button; if the Apple SDK fails to load,
+             * the rule is removed and Primer's own button stays visible (graceful
+             * fallback to 'plain'). */
+            const applePayConfig = this.applePayOptions;
+            const nativeButtonType = allowedPaymentMethod === exports.PaymentMethod.APPLE_PAY &&
+                applePayConfig?.buttonType &&
+                isNativeOnlyApplePayButtonType(applePayConfig.buttonType)
+                ? applePayConfig.buttonType
+                : null;
+            let hideRuleIndex = null;
+            if (nativeButtonType && sheet) {
+                hideRuleIndex = sheet.insertRule(`
+          .${wrapper.className} > button {
+            opacity: 0 !important;
+          }
+        `);
+            }
             button = pmManager.createButton();
             await button.render(wrapper, {});
+            let nativeOverlay = null;
+            if (nativeButtonType) {
+                nativeOverlay = await overlayNativeApplePayButton(wrapper, {
+                    buttonType: nativeButtonType,
+                    buttonStyle: applePayConfig?.buttonStyle,
+                });
+                if (!nativeOverlay && sheet && hideRuleIndex !== null) {
+                    sheet.deleteRule(hideRuleIndex);
+                }
+            }
             this.destroyCallbacks.push(() => button.clean());
             onMethodRender(allowedPaymentMethod);
             return {
                 setDisabled: (disabled) => {
                     button.setDisabled(disabled);
+                    if (nativeOverlay) {
+                        nativeOverlay.style.pointerEvents = disabled ? 'none' : '';
+                        nativeOverlay.style.opacity = disabled ? '0.5' : '';
+                    }
                 },
                 destroy: () => {
                     styleEl.remove();
+                    nativeOverlay?.remove();
                     button.clean();
                 },
             };
@@ -1068,6 +1241,32 @@ class PrimerWrapper {
 }
 PrimerWrapper.headlessManager = new HeadlessManager();
 
+/**
+ * @fileoverview Tags the deferred session request so the warm-up trigger can
+ * be measured without adding a single extra network call.
+ *
+ * The backend already logs every request header, so `X-FF-Warmup` lands in
+ * Elasticsearch for free. That gives us, per session actually created:
+ *   - which signal started it (dwell vs interaction vs a cold tap)
+ *   - how long after mount it fired
+ *
+ * Which is what tells us whether the dwell can be lengthened (more savings)
+ * or must stay short (cold-tap risk), instead of guessing at an interaction
+ * rate nobody has measured.
+ */
+const WARMUP_HEADER = 'X-FF-Warmup';
+let pendingTag = null;
+/** Records the trigger for the session request that is about to be sent. */
+function setWarmupTag(trigger, msSinceMount) {
+    pendingTag = `${trigger};${Math.max(0, Math.round(msSinceMount))}`;
+}
+/** Consumes the tag — it describes one request only. */
+function takeWarmupTag() {
+    const tag = pendingTag;
+    pendingTag = null;
+    return tag;
+}
+
 /**
  * @fileoverview API client for Funnefox backend integration
  */
@@ -1085,6 +1284,7 @@ class APIClient {
             headers: {
                 'Content-Type': 'application/json',
                 'X-SDK-Version': SDK_VERSION,
+                ...warmupHeader(),
                 ...(options.headers || {}),
             },
             ...options,
@@ -1299,6 +1499,10 @@ class APIClient {
         }));
     }
 }
+function warmupHeader() {
+    const tag = takeWarmupTag();
+    return tag ? { [WARMUP_HEADER]: tag } : {};
+}
 
 class SessionService {
     constructor() {
@@ -1381,6 +1585,96 @@ const hideLoader = () => {
     }
 };
 
+/**
+ * @fileoverview Decides when a deferred client session should be created.
+ *
+ * Fires on whichever comes first: the visitor's first interaction, or a short
+ * dwell once the page is actually visible. The dwell is what makes the
+ * deferral safe — ApplePaySession must be constructed inside the tap gesture,
+ * so the session has to exist *before* the first tap. A human cannot read a
+ * price and tap in under ~800ms, whereas prerenders, background tabs, crawlers
+ * and instant bounces never reach the dwell at all and so never cost a
+ * session (nor the order row behind it).
+ */
+const INTERACTION_EVENTS = [
+    'pointerdown',
+    'touchstart',
+    'keydown',
+    'wheel',
+    'scroll',
+];
+/** Long enough to filter prerenders and instant bounces, far shorter than
+ * any realistic time-to-tap on a paywall. */
+const DEFAULT_WARMUP_DWELL_MS = 800;
+/** True while the page is prerendering or not visible to the user. */
+function isPageHidden() {
+    if (typeof document === 'undefined') {
+        return true;
+    }
+    if (document.prerendering) {
+        return true;
+    }
+    return document.visibilityState === 'hidden';
+}
+/**
+ * Invokes `handler` once — on first interaction, or after `dwellMs` of visible
+ * time, whichever happens first. Returns a cleanup for the un-fired case.
+ */
+function onSessionWarmup(handler, dwellMs = DEFAULT_WARMUP_DWELL_MS) {
+    if (typeof document === 'undefined') {
+        return () => { };
+    }
+    let fired = false;
+    let timer;
+    const cleanup = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        for (const event of INTERACTION_EVENTS) {
+            document.removeEventListener(event, onInteraction, true);
+        }
+        document.removeEventListener('visibilitychange', onVisibilityChange);
+        document.removeEventListener('prerenderingchange', onVisibilityChange);
+    };
+    const fire = (source) => {
+        if (fired) {
+            return;
+        }
+        fired = true;
+        cleanup();
+        handler(source);
+    };
+    function onInteraction() {
+        if (!isPageHidden()) {
+            fire('interaction');
+        }
+    }
+    function startDwell() {
+        if (fired || timer !== undefined) {
+            return;
+        }
+        timer = setTimeout(() => fire('dwell'), dwellMs);
+    }
+    function onVisibilityChange() {
+        if (!isPageHidden()) {
+            startDwell();
+        }
+    }
+    for (const event of INTERACTION_EVENTS) {
+        document.addEventListener(event, onInteraction, {
+            capture: true,
+            passive: true,
+        });
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    document.addEventListener('prerenderingchange', onVisibilityChange);
+    if (!isPageHidden()) {
+        startDwell();
+    }
+    return cleanup;
+}
+
 var V3_URL = 'https://js.stripe.com/v3';
 var V3_URL_REGEX = /^https:\/\/js\.stripe\.com\/v3\/?(\?.*)?$/;
 var EXISTING_SCRIPT_MESSAGE = 'loadStripe.setLoadParameters was called but an existing Stripe.js script already exists in the document; existing script parameters will be used';
@@ -2538,6 +2832,98 @@ class CheckoutInstance extends EventEmitter {
     }
     async initMethod(method, element, callbacks) {
         this._ensureNotDestroyed();
+        const deferred = await this.initMethodDeferred(method, element, callbacks);
+        if (deferred) {
+            return deferred;
+        }
+        return await this.initMethodNow(method, element, callbacks);
+    }
+    /**
+     * Renders Apple's native button immediately and postpones session creation
+     * until the visitor interacts. Returns null when deferral does not apply, so
+     * the caller falls back to creating the session on mount.
+     */
+    async initMethodDeferred(method, element, callbacks) {
+        const applePay = this.checkoutConfig.applePay;
+        const buttonType = applePay?.buttonType;
+        if (this.checkoutConfig.sessionCreation !== 'onInteraction' ||
+            method !== exports.PaymentMethod.APPLE_PAY ||
+            this.isReady() ||
+            !buttonType ||
+            !isNativeOnlyApplePayButtonType(buttonType)) {
+            return null;
+        }
+        let started = null;
+        let real = null;
+        let disabled = false;
+        let stopWaiting = () => { };
+        let placeholder = null;
+        const mountedAt = Date.now();
+        const start = (trigger) => {
+            const fromTap = trigger === 'tap';
+            if (!started) {
+                setWarmupTag(trigger, Date.now() - mountedAt);
+                started = (async () => {
+                    stopWaiting();
+                    if (fromTap) {
+                        callbacks.onLoaderChange?.(true);
+                    }
+                    try {
+                        placeholder?.remove();
+                        placeholder = null;
+                        const methodInterface = await this.initMethodNow(method, element, callbacks);
+                        real = methodInterface;
+                        if (disabled) {
+                            methodInterface.setDisabled(true);
+                        }
+                        return methodInterface;
+                    }
+                    finally {
+                        if (fromTap) {
+                            callbacks.onLoaderChange?.(false);
+                        }
+                    }
+                })();
+            }
+            return started;
+        };
+        placeholder = await renderPlaceholderApplePayButton(element, {
+            buttonType,
+            buttonStyle: applePay?.buttonStyle,
+            // Cold tap: the visitor's first interaction is the button itself, so the
+            // session cannot exist yet and ApplePaySession would lose the gesture.
+            // Start now and let the loader cover the (rare) second tap.
+            onActivate: () => void start('tap'),
+        });
+        if (!placeholder) {
+            return null;
+        }
+        // Free head start: Primer's SDK is a static asset on their CDN, so
+        // fetching it now costs no backend call and leaves only the session
+        // request to complete before the first tap.
+        void loadPrimerSDK().catch(() => { });
+        stopWaiting = onSessionWarmup(trigger => void start(trigger));
+        return {
+            setDisabled: (value) => {
+                disabled = value;
+                real?.setDisabled(value);
+                if (placeholder) {
+                    placeholder.style.pointerEvents = value ? 'none' : '';
+                    placeholder.style.opacity = value ? '0.5' : '';
+                }
+            },
+            destroy: async () => {
+                stopWaiting();
+                placeholder?.remove();
+                placeholder = null;
+                if (started) {
+                    await (await started).destroy?.();
+                }
+                await this.destroy();
+            },
+        };
+    }
+    async initMethodNow(method, element, callbacks) {
         if (!this.isReady()) {
             await this.createSession();
         }
@@ -2755,6 +3141,7 @@ async function initMethod(method, element, options) {
                     ...DEFAULT_BUTTONS_OPTIONS[exports.PaymentMethod.GOOGLE_PAY],
                     ...(options.googlePay || {}),
                 },
+                sessionCreation: options.sessionCreation,
             },
         });
         return await checkoutInstance.initMethod(method, element, {