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

package/dist/funnelfox-billing.js

@@ -495,7 +495,7 @@
     /**
      * @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',
@@ -632,6 +632,141 @@
         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
      */
@@ -670,6 +805,7 @@
         }
         async createHeadlessCheckout(clientToken, options, method) {
             await this.ensurePrimerLoaded();
+            this.applePayOptions = options.applePay;
             this.currentHeadless = PrimerWrapper.headlessManager.getOrCreate(clientToken, options, method);
             return this.currentHeadless;
         }
@@ -716,16 +852,53 @@
                 }
                 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();
                     },
                 };
@@ -1072,6 +1245,32 @@
     }
     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
      */
@@ -1089,6 +1288,7 @@
                 headers: {
                     'Content-Type': 'application/json',
                     'X-SDK-Version': SDK_VERSION,
+                    ...warmupHeader(),
                     ...(options.headers || {}),
                 },
                 ...options,
@@ -1303,6 +1503,10 @@
             }));
         }
     }
+    function warmupHeader() {
+        const tag = takeWarmupTag();
+        return tag ? { [WARMUP_HEADER]: tag } : {};
+    }
 
     class SessionService {
         constructor() {
@@ -1385,6 +1589,96 @@
         }
     };
 
+    /**
+     * @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';
@@ -2542,6 +2836,98 @@
         }
         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();
             }
@@ -2759,6 +3145,7 @@
                         ...DEFAULT_BUTTONS_OPTIONS[exports.PaymentMethod.GOOGLE_PAY],
                         ...(options.googlePay || {}),
                     },
+                    sessionCreation: options.sessionCreation,
                 },
             });
             return await checkoutInstance.initMethod(method, element, {