@funnelsgrove/payments 0.37.0 → 0.39.0

package/README.md

@@ -28,6 +28,29 @@ Use these for new subscription paywalls:
 - `trackPaidStripeSubscriptionCheckoutCompleted`
 - `trackStripeSubscriptionPaymentInfoSubmitted`
 
+For an inline subscription form with the device wallet first and card second, use
+`StripeWalletFirstCheckout`. It shows one wallet, Google Pay on Android and Apple Pay
+elsewhere, preselected, with Stripe's own button, and the card form as the second method.
+
+- Pass the card hook's `clientSecret`, `checkoutSessionId` and `stripePromise`. While the
+  Checkout Session is being created, pass `clientSecret={null}`: the full layout renders
+  and the wallet slot holds a progress bar at the button's height, so nothing moves when
+  Stripe's button arrives.
+- Also pass `amountCents` and `summaryLabel` for the wallet sheet, `customerEmail` (set on
+  the session before card confirmation, since the form has no email field), `returnUrl`,
+  `checkoutAnalytics`, a complete `StripeWalletFirstCheckoutCopy` from the funnel's
+  content, and `themeColor`/`buttonColor`.
+- The card form has no ZIP or terms text.
+- Where the browser cannot pay with that wallet, the wallet stays first and its slot shows
+  `walletUnavailableNote` (`{wallet}` is replaced with the wallet name). The card remains
+  one tap away. This is deliberate: the layout must not move.
+- The component owns `checkout_shown` (once per mount, `checkout_surface: inline`),
+  `checkout_started` (when the card form opens, or on wallet intent),
+  `add_payment_info` and verified `checkout_completed`.
+- After confirmation, the payment status stays in the form until the caller replaces it.
+  With the runtime's embedded completion, the success screen takes over. Otherwise
+  `onSuccess` runs, and then the page navigates to `returnUrl`.
+
 Use these for new one-time paywall plans:
 
 - `StripeOneTimeWalletSurface`
@@ -198,11 +221,12 @@ conversion event is introduced.
 - Wallet unavailable state must fall back to card/manual checkout or disappear.
 - Count `checkout_started` only at shared UI boundaries: when a shared card dialog opens or when Stripe reports Apple Pay / Google Pay intent. Checkout Sessions use confirmation or cancellation as a fallback because Stripe omits their click callback. Cancellation recovers the start with `checkout_start_source: wallet_cancel`; its timestamp is dismissal time, not wallet-open time. Closing the browser before either callback is still unobservable. Cancel has no payment-method field, so the method is included only when the element enables exactly one method.
 - Pass `checkoutAnalytics` to every current shared dialog and wallet surface. The package then owns `checkout_started`, `add_payment_info`, and verified `checkout_completed`, all deduplicated by the actual Checkout Session.
+- The package also owns `checkout_shown`: a checkout form or payment button became visible. It is sent once per show with a new event ID and `checkout_surface`: `inline` (wallet-first form, or the V2 dialog with `presentation='inline'`), `dialog` (each V2 dialog open) or `wallet` (a standalone wallet surface, once per mount after Stripe reports a wallet available). It is not a conversion and is not sent to Meta or Google.
 - Payment submission triggers, validation, declines, and retry identity follow [AE-BR-001–004](../../docs/product-specs/analytics-events.md#payment-information-submission). Keep that behavior inside shared checkout surfaces.
 - Call funnel lifecycle `completeStep` only from the shared checkout `onSuccess` callback. Payment-info submission is not step completion.
 - Wallet slots may create render-only Checkout Sessions on mount so Apple Pay and Google Pay render before the visitor taps. Session creation is technical preparation and must never emit `checkout_started`.
 - Shared checkout analytics deduplicates `checkout_started` by Checkout Session id. Wallet confirmation and cancellation may retry the start signal when the click callback is unavailable, without creating a duplicate. Cancellation never emits payment-info or purchase completion events.
-- Do not call `publicAnalyticsSdk.trackCheckoutStarted`, `trackPaymentInfoSubmitted`, or `trackCheckoutCompleted` directly from funnel checkout components.
+- Do not call `publicAnalyticsSdk.trackCheckoutShown`, `trackCheckoutStarted`, `trackPaymentInfoSubmitted`, or `trackCheckoutCompleted` directly from funnel checkout components.
 - Funnel paywalls should style wallet buttons through the shared slot API: `className` for the Stripe button/placeholder, `slotClassName` for the outer slot, `appearance` for Stripe Elements appearance, and `options` for Stripe Express Checkout options.
 - Keep discount math reusable here, but keep offer activation timing in funnel code.
 - `SharedStripeCheckoutV2Dialog` forwards wallet-sheet cancellation to `onClose` by default; `onWalletCancel` may override that callback. Standalone wallet surfaces call their `onCancel` callback. Funnel code chooses whether either callback opens a discount offer.

package/dist/generated/package-version.d.ts

@@ -1 +1 @@
-export declare const PAYMENTS_PACKAGE_VERSION = "0.37.0";
+export declare const PAYMENTS_PACKAGE_VERSION = "0.39.0";

package/dist/generated/package-version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generate-package-version.mjs.
-export const PAYMENTS_PACKAGE_VERSION = "0.37.0";
+export const PAYMENTS_PACKAGE_VERSION = "0.39.0";

package/dist/providers/stripe/components/SharedStripeCheckoutV2Dialog.js

@@ -14,8 +14,9 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useCallback, useEffect, useMemo } from 'react';
 import { CheckoutProvider } from '@stripe/react-stripe-js/checkout';
 import { normalizeSupportedCheckoutCountries } from './checkoutCountries.js';
-import { queueStripeSubscriptionCheckoutStarted } from '../services/checkoutCompletionAnalytics.service.js';
+import { queueStripeSubscriptionCheckoutStarted, trackStripeCheckoutShown } from '../services/checkoutCompletionAnalytics.service.js';
 import { trackCheckoutCanceled } from '../../../services/checkoutObservability.service.js';
+import { useCheckoutShownOnce } from '../hooks/useCheckoutShownOnce.js';
 import { SharedStripeCheckoutV2CheckoutSessionForm, getFixedSupportedBillingCountry } from './SharedStripeCheckoutV2Form.internal.js';
 import { sharedStripeCheckoutV2Styles } from './SharedStripeCheckoutV2.styles.js';
 const stripeCheckoutV2Appearance = {
@@ -73,6 +74,11 @@ export function SharedStripeCheckoutV2Dialog(_a) {
         }
         onClose();
     }, [checkoutAnalytics, checkoutSessionId, onClose]);
+    // The dialog is mounted while open, so one mount is one show.
+    useCheckoutShownOnce(Boolean(checkoutAnalytics), () => {
+        if (checkoutAnalytics)
+            trackStripeCheckoutShown(Object.assign(Object.assign({}, checkoutAnalytics), { checkoutSessionId, checkoutSurface: presentation }));
+    });
     useEffect(() => {
         if (!checkoutAnalytics) {
             return;

package/dist/providers/stripe/components/StripeWalletFirstCheckout.d.ts

@@ -0,0 +1,36 @@
+import type { Stripe } from '@stripe/stripe-js';
+import { type PlatformWalletPaymentMethod } from './walletPlatform.js';
+import { type StripeSubscriptionCheckoutAnalyticsContext } from '../services/checkoutCompletionAnalytics.service.js';
+export type StripeWalletFirstCheckoutCopy = {
+    /** Benefit bullets under the wallet header, per wallet. */
+    walletBenefits: Record<PlatformWalletPaymentMethod, readonly string[]>;
+    walletLabels: Record<PlatformWalletPaymentMethod, string>;
+    cardLabel: string;
+    cardSubmitLabel: string;
+    processingLabel: string;
+    secureNote: string;
+    /** Shown in the wallet slot when this browser cannot pay with the wallet; `{wallet}` is the wallet name. */
+    walletUnavailableNote: string;
+    verifyingPayment: string;
+    paymentConfirmed: string;
+    paymentFailed: string;
+    formNotReady: string;
+};
+export type StripeWalletFirstCheckoutProps = {
+    amountCents: number;
+    buttonColor: string;
+    checkoutAnalytics: StripeSubscriptionCheckoutAnalyticsContext | null;
+    checkoutSessionId: string | null;
+    /** Null while the checkout session is being created; the layout shows progress meanwhile. */
+    clientSecret: string | null;
+    copy: StripeWalletFirstCheckoutCopy;
+    customerEmail: string;
+    customerName?: string | null;
+    onError?: (message: string | null) => void;
+    onSuccess?: () => void | Promise<void>;
+    returnUrl: string;
+    stripePromise: Promise<Stripe | null> | null;
+    summaryLabel: string;
+    themeColor: string;
+};
+export declare function StripeWalletFirstCheckout(props: StripeWalletFirstCheckoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/providers/stripe/components/StripeWalletFirstCheckout.js

@@ -0,0 +1,196 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Wallet-first inline Stripe checkout (Checkout Sessions).
+ *
+ * One platform wallet is the first, preselected method: Google Pay on Android,
+ * Apple Pay everywhere else, shown with Stripe's own wallet button. Card
+ * payment is always the second method. The whole layout renders immediately,
+ * even before the checkout session exists; the wallet slot holds a progress
+ * bar at the exact button height until Stripe's button replaces it, so nothing
+ * moves. Where the wallet cannot pay, the same slot explains that. The card
+ * form has no email, ZIP or terms text: the session carries the email.
+ *
+ * The caller owns the subscription Checkout Session (`clientSecret`), the copy
+ * and what happens after `onSuccess`.
+ */
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { CheckoutProvider, PaymentElement, useCheckout } from '@stripe/react-stripe-js/checkout';
+import { completePaywallCheckout } from '@funnelsgrove/runtime';
+import { StripeCheckoutExpressCheckoutButton } from './StripeCheckoutExpressCheckoutButton.js';
+import { resolveWalletPlatform } from './walletPlatform.js';
+import { stripeWalletFirstCheckoutStyles } from './StripeWalletFirstCheckout.styles.js';
+import { queueStripeSubscriptionCheckoutStarted, trackPaidStripeSubscriptionCheckoutCompleted, trackStripeCheckoutShown, trackStripeSubscriptionPaymentInfoSubmitted, } from '../services/checkoutCompletionAnalytics.service.js';
+import { trackCheckoutFailureShown } from '../../../services/checkoutObservability.service.js';
+import { useCheckoutShownOnce } from '../hooks/useCheckoutShownOnce.js';
+const appearance = {
+    labels: 'above',
+    variables: {
+        borderRadius: '12px',
+        colorBackground: '#fff',
+        colorText: '#303136',
+        colorTextPlaceholder: '#8c909a',
+        spacingUnit: '4px',
+    },
+};
+export function StripeWalletFirstCheckout(props) {
+    const { buttonColor, checkoutAnalytics, checkoutSessionId, clientSecret, copy, stripePromise, themeColor } = props;
+    const wallet = usePlatformWallet();
+    const [selected, setSelected] = useState('wallet');
+    const style = { '--wfc-theme': themeColor, '--wfc-button': buttonColor };
+    const options = useMemo(() => clientSecret ? {
+        clientSecret,
+        elementsOptions: { appearance: Object.assign(Object.assign({}, appearance), { variables: Object.assign(Object.assign({}, appearance.variables), { colorPrimary: themeColor }) }) },
+    } : null, [clientSecret, themeColor]);
+    // The whole layout shows on mount, so one mount is one show.
+    useCheckoutShownOnce(Boolean(checkoutAnalytics), () => {
+        if (checkoutAnalytics)
+            trackStripeCheckoutShown(Object.assign(Object.assign({}, checkoutAnalytics), { checkoutSessionId, checkoutSurface: 'inline' }));
+    });
+    // Session creation is preparation; the card checkout starts when the visitor opens the card form.
+    useEffect(() => {
+        if (!checkoutAnalytics || !clientSecret || selected !== 'card')
+            return;
+        queueStripeSubscriptionCheckoutStarted(Object.assign(Object.assign({}, checkoutAnalytics), { checkoutSessionId, checkoutStartSource: 'card_form_open', paymentMethod: 'card' }));
+    }, [checkoutAnalytics, checkoutSessionId, clientSecret, selected]);
+    return (_jsxs(_Fragment, { children: [options && stripePromise ? (_jsx(CheckoutProvider, { stripe: stripePromise, options: options, children: _jsx(StripeWalletFirstCheckoutForm, Object.assign({}, props, { wallet: wallet, selected: selected, onSelect: setSelected, style: style })) }, options.clientSecret)) : (_jsx(CheckoutLayout, { copy: copy, wallet: wallet, selected: selected, onSelect: setSelected, disabled: false, style: style, walletSlot: _jsx("span", { className: 'wfc-progress', role: 'status', "aria-label": copy.processingLabel }), cardBody: _jsx("span", { className: 'wfc-progress wfc-progress--form', "aria-hidden": 'true' }) })), _jsx("style", { children: stripeWalletFirstCheckoutStyles })] }));
+}
+function StripeWalletFirstCheckoutForm({ amountCents, checkoutAnalytics, checkoutSessionId, copy, customerEmail, customerName, onError, onSuccess, returnUrl, summaryLabel, wallet, selected, onSelect, style, }) {
+    const checkoutState = useCheckout();
+    // null until Stripe answers; the slot shows progress at the button's height meanwhile.
+    const [walletAvailable, setWalletAvailable] = useState(null);
+    const [walletConfirming, setWalletConfirming] = useState(false);
+    const [paymentElementReady, setPaymentElementReady] = useState(false);
+    const [paymentElementComplete, setPaymentElementComplete] = useState(false);
+    const [submitting, setSubmitting] = useState(false);
+    const [providerConfirmed, setProviderConfirmed] = useState(false);
+    const [completed, setCompleted] = useState(false);
+    const [error, setError] = useState(null);
+    const submitInFlight = useRef(false);
+    const expressOptions = useMemo(() => ({
+        buttonHeight: 55,
+        buttonTheme: { applePay: 'black', googlePay: 'black' },
+        buttonType: { applePay: 'plain', googlePay: 'plain' },
+        layout: { maxColumns: 1, maxRows: 1, overflow: 'auto' },
+        paymentMethods: {
+            amazonPay: 'never', klarna: 'never', link: 'never', paypal: 'never',
+            applePay: wallet === 'applePay' ? 'always' : 'never',
+            googlePay: wallet === 'googlePay' ? 'always' : 'never',
+        },
+    }), [wallet]);
+    const paymentElementOptions = useMemo(() => ({
+        fields: { billingDetails: { name: 'never', email: 'never', address: { country: 'auto', postalCode: 'never' } } },
+        layout: 'tabs',
+        terms: { card: 'never' },
+        wallets: { applePay: 'never', googlePay: 'never', link: 'never' },
+    }), []);
+    // A hidden Payment Element measures 0px wide; let Stripe re-layout when it opens.
+    useEffect(() => {
+        if (selected !== 'card')
+            return;
+        const timer = window.setTimeout(() => window.dispatchEvent(new Event('resize')), 0);
+        return () => window.clearTimeout(timer);
+    }, [selected]);
+    const showError = (message, providerError, alreadyTracked = false) => {
+        if (message && checkoutAnalytics && !alreadyTracked) {
+            trackCheckoutFailureShown({
+                analytics: checkoutAnalytics, checkoutSessionId, errorMessage: message,
+                failureStage: 'card_form', paymentMethod: 'card', provider: 'stripe',
+                providerDeclineCode: providerError === null || providerError === void 0 ? void 0 : providerError.decline_code, providerErrorCode: providerError === null || providerError === void 0 ? void 0 : providerError.code, providerErrorType: providerError === null || providerError === void 0 ? void 0 : providerError.type,
+            });
+        }
+        setError(message);
+        onError === null || onError === void 0 ? void 0 : onError(message);
+    };
+    const trackSuccess = async (embedded = false) => {
+        if (checkoutAnalytics)
+            await trackPaidStripeSubscriptionCheckoutCompleted(Object.assign(Object.assign({}, checkoutAnalytics), { checkoutSessionId }));
+        if (!embedded)
+            await (onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess());
+    };
+    const finishPaidCheckout = async () => {
+        if (await completePaywallCheckout('stripe', checkoutSessionId || '', {
+            beforeNotify: async () => { setCompleted(true); await trackSuccess(true); },
+        }))
+            return;
+        await trackSuccess();
+        window.location.assign(returnUrl);
+    };
+    const submitCard = async (event) => {
+        event.preventDefault();
+        if (submitInFlight.current)
+            return;
+        if (!providerConfirmed) {
+            if (checkoutState.type !== 'success') {
+                showError(checkoutState.type === 'error' ? checkoutState.error.message : copy.formNotReady);
+                return;
+            }
+            if (!paymentElementReady) {
+                showError(copy.formNotReady, undefined, true);
+                return;
+            }
+        }
+        submitInFlight.current = true;
+        setSubmitting(true);
+        showError(null);
+        let confirmed = providerConfirmed;
+        try {
+            if (!providerConfirmed && checkoutState.type === 'success') {
+                const { checkout } = checkoutState;
+                if (!checkout.email && customerEmail) {
+                    const updated = await checkout.updateEmail(customerEmail);
+                    if (updated.type === 'error')
+                        throw new Error(updated.error.message);
+                }
+                if (paymentElementComplete && checkoutAnalytics) {
+                    await trackStripeSubscriptionPaymentInfoSubmitted(Object.assign(Object.assign({}, checkoutAnalytics), { checkoutSessionId })).catch(() => 'analytics_rejected');
+                }
+                const result = await checkout.confirm({ redirect: 'if_required' });
+                if (result.type === 'error') {
+                    showError(result.error.message || copy.paymentFailed, result.error);
+                    submitInFlight.current = false;
+                    setSubmitting(false);
+                    return;
+                }
+                confirmed = true;
+                setProviderConfirmed(true);
+            }
+            await finishPaidCheckout();
+        }
+        catch (submitError) {
+            showError(submitError instanceof Error && submitError.message ? submitError.message : copy.paymentFailed, undefined, confirmed);
+            submitInFlight.current = false;
+            setSubmitting(false);
+        }
+    };
+    // After a successful confirmation the form stays in place and reports progress
+    // where the customer paid, until the success screen takes over.
+    const paymentStatus = completed ? copy.paymentConfirmed : providerConfirmed ? copy.verifyingPayment : null;
+    const locked = Boolean(paymentStatus) && !error;
+    return (_jsx(CheckoutLayout, { copy: copy, wallet: wallet, selected: selected, onSelect: onSelect, disabled: submitting || walletConfirming || locked, style: style, walletNote: selected === 'wallet' ? paymentStatus : null, walletSlot: _jsxs(_Fragment, { children: [_jsx("div", { className: 'wfc-wallet-button', "data-ready": walletAvailable === true, children: _jsx(StripeCheckoutExpressCheckoutButton, { amountCents: amountCents, availabilityPaymentMethods: [wallet], beforeConfirm: async () => { setWalletConfirming(true); return customerEmail || null; }, checkoutAnalytics: checkoutAnalytics, checkoutSessionId: checkoutSessionId, confirmEmail: false, customerEmail: customerEmail, customerName: customerName, onAvailabilityChange: setWalletAvailable, onCancel: () => setWalletConfirming(false), onEmbeddedComplete: () => setCompleted(true), onError: message => { setWalletConfirming(false); showError(message, undefined, true); }, onPaymentRejected: () => { setWalletConfirming(false); onSelect('card'); }, onSuccess: () => trackSuccess(), onVerificationPending: () => setProviderConfirmed(true), options: expressOptions, returnUrl: returnUrl, summaryLabel: summaryLabel }) }), walletAvailable === null ? _jsx("span", { className: 'wfc-progress wfc-progress--overlay', role: 'status', "aria-label": copy.processingLabel }) : null, walletAvailable === false ? _jsx("p", { className: 'wfc-wallet-unavailable', role: 'status', children: copy.walletUnavailableNote.replace('{wallet}', copy.walletLabels[wallet]) }) : null] }), cardBody: _jsxs("form", { className: 'wfc-card-form', onSubmit: event => void submitCard(event), children: [_jsx(PaymentElement, { options: paymentElementOptions, onChange: event => setPaymentElementComplete(event.complete), onReady: () => setPaymentElementReady(true) }), _jsx("button", { type: 'submit', className: 'wfc-submit', disabled: locked || submitting || !paymentElementReady, "aria-live": 'polite', children: locked && paymentStatus ? paymentStatus : submitting ? copy.processingLabel : copy.cardSubmitLabel }), _jsx("p", { className: 'wfc-secure', children: copy.secureNote })] }), footer: error ? _jsx("p", { className: 'wfc-error', role: 'alert', children: error }) : null }));
+}
+/** Shared by the loading and live states so switching between them moves nothing. */
+function CheckoutLayout({ cardBody, copy, disabled, footer, onSelect, selected, style, wallet, walletNote, walletSlot }) {
+    const WalletMark = wallet === 'applePay' ? ApplePayMark : GooglePayMark;
+    return (_jsxs("div", { className: 'wfc', style: style, children: [_jsxs(MethodCard, { checked: selected === 'wallet', disabled: disabled, label: copy.walletLabels[wallet], onSelect: () => onSelect('wallet'), header: _jsx(WalletMark, {}), children: [_jsx("ul", { className: 'wfc-benefits', children: copy.walletBenefits[wallet].map(item => _jsxs("li", { children: [_jsx(CheckIcon, {}), item] }, item)) }), _jsx("div", { className: 'wfc-wallet-slot', children: walletSlot }), _jsx("p", { className: walletNote ? 'wfc-secure is-status' : 'wfc-secure', role: walletNote ? 'status' : undefined, children: walletNote || copy.secureNote })] }), _jsx(MethodCard, { checked: selected === 'card', disabled: disabled, label: copy.cardLabel, onSelect: () => onSelect('card'), header: _jsx(CardBrandMarks, {}), children: cardBody }), footer] }));
+}
+function MethodCard({ checked, children, disabled, header, label, onSelect }) {
+    return (_jsxs("section", { className: 'wfc-method', "data-checked": checked, children: [_jsxs("button", { type: 'button', role: 'radio', "aria-checked": checked, "aria-label": label, className: 'wfc-method-head', disabled: disabled, onClick: onSelect, children: [_jsx("span", { className: 'wfc-radio', "aria-hidden": 'true' }), header] }), _jsx("div", { className: 'wfc-method-body', "data-open": checked, inert: !checked, "aria-hidden": !checked, children: _jsx("div", { className: 'wfc-method-clip', children: _jsx("div", { className: 'wfc-method-content', children: children }) }) })] }));
+}
+function CheckIcon() {
+    return _jsx("svg", { className: 'wfc-check', viewBox: '0 0 16 16', "aria-hidden": 'true', children: _jsx("path", { d: 'M3 8.5 6.5 12 13 4.5', fill: 'none', stroke: 'currentColor', strokeWidth: '2', strokeLinecap: 'round', strokeLinejoin: 'round' }) });
+}
+function ApplePayMark() {
+    return (_jsxs("svg", { className: 'wfc-mark wfc-mark--apple', viewBox: '0 0 64 26', role: 'img', "aria-label": 'Apple Pay', children: [_jsx("path", { d: 'M14.6 13.6c0-2.6 2.1-3.8 2.2-3.9-1.2-1.8-3.1-2-3.7-2-1.6-.2-3.1.9-3.9.9-.8 0-2-.9-3.4-.9-1.7 0-3.3 1-4.2 2.6-1.8 3.1-.5 7.7 1.3 10.2.9 1.2 1.9 2.6 3.2 2.6 1.3-.1 1.8-.8 3.3-.8 1.6 0 2 .8 3.4.8s2.3-1.3 3.1-2.5c1-1.4 1.4-2.8 1.4-2.9 0 0-2.7-1-2.7-4.1ZM12.1 6c.7-.9 1.2-2 1-3.2-1 0-2.3.7-3 1.6-.7.8-1.3 2-1.1 3.1 1.1.1 2.3-.6 3.1-1.5Z', fill: 'currentColor' }), _jsx("text", { x: '22', y: '20', fontSize: '17', fontWeight: '600', fill: 'currentColor', fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif', children: "Pay" })] }));
+}
+function GooglePayMark() {
+    return (_jsxs("svg", { className: 'wfc-mark wfc-mark--google', viewBox: '0 0 64 26', role: 'img', "aria-label": 'Google Pay', children: [_jsx("path", { d: 'M19.6 13.2c0-.6-.1-1.2-.2-1.8h-8.6v3.4h4.9a4.2 4.2 0 0 1-1.8 2.8v2.3h2.9c1.7-1.6 2.8-3.9 2.8-6.7Z', fill: '#4285F4' }), _jsx("path", { d: 'M10.8 22c2.4 0 4.5-.8 6-2.2l-2.9-2.3c-.8.6-1.9.9-3.1.9-2.4 0-4.4-1.6-5.1-3.7h-3v2.3A9 9 0 0 0 10.8 22Z', fill: '#34A853' }), _jsx("path", { d: 'M5.7 14.7a5.4 5.4 0 0 1 0-3.4V9H2.7a9 9 0 0 0 0 8l3-2.3Z', fill: '#FBBC04' }), _jsx("path", { d: 'M10.8 7.6c1.3 0 2.5.5 3.5 1.4l2.6-2.6A9 9 0 0 0 2.7 9l3 2.3c.7-2.1 2.7-3.7 5.1-3.7Z', fill: '#EA4335' }), _jsx("text", { x: '23', y: '20', fontSize: '17', fontWeight: '500', fill: '#3c4043', fontFamily: '"Google Sans", Roboto, -apple-system, sans-serif', children: "Pay" })] }));
+}
+function CardBrandMarks() {
+    return (_jsxs("span", { className: 'wfc-card-marks', "aria-hidden": 'true', children: [_jsx("svg", { viewBox: '0 0 48 30', className: 'wfc-brand', children: _jsx("text", { x: '24', y: '21', textAnchor: 'middle', fontSize: '17', fontWeight: '800', fontStyle: 'italic', fill: '#1a1f71', fontFamily: 'Arial, sans-serif', children: "VISA" }) }), _jsxs("svg", { viewBox: '0 0 48 30', className: 'wfc-brand', children: [_jsx("circle", { cx: '19', cy: '15', r: '10', fill: '#eb001b' }), _jsx("circle", { cx: '29', cy: '15', r: '10', fill: '#f79e1b', fillOpacity: '.9' })] }), _jsxs("svg", { viewBox: '0 0 48 30', className: 'wfc-brand wfc-brand--box', style: { background: '#1b4fa0' }, children: [_jsx("circle", { cx: '19', cy: '15', r: '9', fill: '#0099df' }), _jsx("circle", { cx: '29', cy: '15', r: '9', fill: '#e60014', fillOpacity: '.85' })] }), _jsx("svg", { viewBox: '0 0 48 30', className: 'wfc-brand wfc-brand--box', style: { background: '#2e77bc' }, children: _jsx("text", { x: '24', y: '19', textAnchor: 'middle', fontSize: '10', fontWeight: '800', fill: '#fff', fontFamily: 'Arial, sans-serif', children: "AMEX" }) })] }));
+}
+/** Google Pay on Android, Apple Pay everywhere else — read synchronously from the browser. */
+function usePlatformWallet() {
+    const platform = useSyncExternalStore(() => () => undefined, () => resolveWalletPlatform({ maxTouchPoints: navigator.maxTouchPoints, userAgent: navigator.userAgent }), () => 'ios');
+    return platform === 'android' ? 'googlePay' : 'applePay';
+}

package/dist/providers/stripe/components/StripeWalletFirstCheckout.styles.d.ts

@@ -0,0 +1,2 @@
+/** Styles for StripeWalletFirstCheckout; colors come from its `themeColor` and `buttonColor` props. */
+export declare const stripeWalletFirstCheckoutStyles = "\n.wfc { display:grid; gap:12px; }\n/* The radio marks the choice; every card keeps the same quiet border. */\n.wfc-method { border-radius:16px; background:#fff; box-shadow:0 0 0 1.5px #e6e6ec; }\n.wfc-method-head { display:flex; align-items:center; gap:14px; width:100%; min-height:60px; padding:14px 16px; border:0; background:transparent; color:inherit; text-align:left; cursor:pointer; border-radius:16px; }\n.wfc-method-head:disabled { cursor:default; }\n.wfc-method-head:focus-visible { outline:3px solid var(--wfc-theme); outline-offset:2px; }\n.wfc-radio { flex:none; width:24px; height:24px; border-radius:50%; border:2px solid #b8bac4; background:#fff; transition:border-color .2s ease, box-shadow .2s ease; }\n.wfc-method[data-checked='true'] .wfc-radio { border-color:var(--wfc-theme); box-shadow:inset 0 0 0 4px #fff, inset 0 0 0 12px var(--wfc-theme); }\n.wfc-method-body { display:grid; grid-template-rows:0fr; opacity:0; transition:grid-template-rows .34s cubic-bezier(.25,.8,.25,1), opacity .22s ease; }\n.wfc-method-body[data-open='true'] { grid-template-rows:1fr; opacity:1; transition:grid-template-rows .34s cubic-bezier(.25,.8,.25,1), opacity .28s ease .08s; }\n.wfc-method-clip { min-height:0; overflow:hidden; }\n.wfc-method-content { padding:0 16px 16px; }\n@media (prefers-reduced-motion: reduce) { .wfc-method-body, .wfc-method-body[data-open='true'] { transition:none; } }\n.wfc-mark { height:30px; width:auto; color:#000; }\n.wfc-card-marks { display:flex; gap:6px; align-items:center; }\n.wfc-brand { width:40px; height:26px; border-radius:4px; }\n.wfc-benefits { margin:0 0 16px; padding:0; list-style:none; display:grid; gap:10px; font-size:15px; line-height:1.4; color:#303136; }\n.wfc-benefits li { display:flex; gap:10px; align-items:flex-start; }\n.wfc-check { flex:none; width:16px; height:16px; margin-top:2px; color:var(--wfc-theme); }\n.wfc-wallet-slot { position:relative; height:55px; }\n.wfc-wallet-button { height:55px; overflow:hidden; border-radius:12px; }\n.wfc-progress { position:relative; display:block; height:100%; overflow:hidden; border-radius:12px; background:#eef0f6; }\n.wfc-progress::after { content:''; position:absolute; inset:0; background:linear-gradient(90deg, transparent, rgba(255,255,255,.75), transparent); transform:translateX(-100%); animation:wfc-sheen 1.3s ease-in-out infinite; }\n.wfc-progress--overlay { position:absolute; inset:0; z-index:1; }\n.wfc-progress--form { height:320px; }\n@keyframes wfc-sheen { to { transform:translateX(100%); } }\n@media (prefers-reduced-motion: reduce) { .wfc-progress::after { animation:none; } }\n.wfc-wallet-unavailable { position:absolute; inset:0; z-index:1; display:flex; align-items:center; justify-content:center; margin:0; padding:0 16px; border-radius:12px; background:#f4f5f8; color:#6b6773; font-size:14px; line-height:1.35; text-align:center; }\n.wfc-secure { margin:16px 0 0; text-align:center; font-size:14px; line-height:1.45; color:#8c909a; }\n.wfc-card-form { display:grid; gap:14px; }\n.wfc-card-form .wfc-secure { margin-top:0; }\n.wfc-submit { min-height:52px; border:0; border-radius:12px; background:var(--wfc-button); color:#fff; font:600 17px/1.2 inherit; cursor:pointer; }\n.wfc-submit:disabled { opacity:.6; cursor:default; }\n.wfc-error { margin:0; color:#c62828; font-size:14px; text-align:center; }\n.wfc-secure.is-status { color:var(--wfc-theme); font-weight:600; }\n";

package/dist/providers/stripe/components/StripeWalletFirstCheckout.styles.js

@@ -0,0 +1,38 @@
+/** Styles for StripeWalletFirstCheckout; colors come from its `themeColor` and `buttonColor` props. */
+export const stripeWalletFirstCheckoutStyles = `
+.wfc { display:grid; gap:12px; }
+/* The radio marks the choice; every card keeps the same quiet border. */
+.wfc-method { border-radius:16px; background:#fff; box-shadow:0 0 0 1.5px #e6e6ec; }
+.wfc-method-head { display:flex; align-items:center; gap:14px; width:100%; min-height:60px; padding:14px 16px; border:0; background:transparent; color:inherit; text-align:left; cursor:pointer; border-radius:16px; }
+.wfc-method-head:disabled { cursor:default; }
+.wfc-method-head:focus-visible { outline:3px solid var(--wfc-theme); outline-offset:2px; }
+.wfc-radio { flex:none; width:24px; height:24px; border-radius:50%; border:2px solid #b8bac4; background:#fff; transition:border-color .2s ease, box-shadow .2s ease; }
+.wfc-method[data-checked='true'] .wfc-radio { border-color:var(--wfc-theme); box-shadow:inset 0 0 0 4px #fff, inset 0 0 0 12px var(--wfc-theme); }
+.wfc-method-body { display:grid; grid-template-rows:0fr; opacity:0; transition:grid-template-rows .34s cubic-bezier(.25,.8,.25,1), opacity .22s ease; }
+.wfc-method-body[data-open='true'] { grid-template-rows:1fr; opacity:1; transition:grid-template-rows .34s cubic-bezier(.25,.8,.25,1), opacity .28s ease .08s; }
+.wfc-method-clip { min-height:0; overflow:hidden; }
+.wfc-method-content { padding:0 16px 16px; }
+@media (prefers-reduced-motion: reduce) { .wfc-method-body, .wfc-method-body[data-open='true'] { transition:none; } }
+.wfc-mark { height:30px; width:auto; color:#000; }
+.wfc-card-marks { display:flex; gap:6px; align-items:center; }
+.wfc-brand { width:40px; height:26px; border-radius:4px; }
+.wfc-benefits { margin:0 0 16px; padding:0; list-style:none; display:grid; gap:10px; font-size:15px; line-height:1.4; color:#303136; }
+.wfc-benefits li { display:flex; gap:10px; align-items:flex-start; }
+.wfc-check { flex:none; width:16px; height:16px; margin-top:2px; color:var(--wfc-theme); }
+.wfc-wallet-slot { position:relative; height:55px; }
+.wfc-wallet-button { height:55px; overflow:hidden; border-radius:12px; }
+.wfc-progress { position:relative; display:block; height:100%; overflow:hidden; border-radius:12px; background:#eef0f6; }
+.wfc-progress::after { content:''; position:absolute; inset:0; background:linear-gradient(90deg, transparent, rgba(255,255,255,.75), transparent); transform:translateX(-100%); animation:wfc-sheen 1.3s ease-in-out infinite; }
+.wfc-progress--overlay { position:absolute; inset:0; z-index:1; }
+.wfc-progress--form { height:320px; }
+@keyframes wfc-sheen { to { transform:translateX(100%); } }
+@media (prefers-reduced-motion: reduce) { .wfc-progress::after { animation:none; } }
+.wfc-wallet-unavailable { position:absolute; inset:0; z-index:1; display:flex; align-items:center; justify-content:center; margin:0; padding:0 16px; border-radius:12px; background:#f4f5f8; color:#6b6773; font-size:14px; line-height:1.35; text-align:center; }
+.wfc-secure { margin:16px 0 0; text-align:center; font-size:14px; line-height:1.45; color:#8c909a; }
+.wfc-card-form { display:grid; gap:14px; }
+.wfc-card-form .wfc-secure { margin-top:0; }
+.wfc-submit { min-height:52px; border:0; border-radius:12px; background:var(--wfc-button); color:#fff; font:600 17px/1.2 inherit; cursor:pointer; }
+.wfc-submit:disabled { opacity:.6; cursor:default; }
+.wfc-error { margin:0; color:#c62828; font-size:14px; text-align:center; }
+.wfc-secure.is-status { color:var(--wfc-theme); font-weight:600; }
+`;

package/dist/providers/stripe/components/StripeWalletSurface.internal.d.ts

@@ -3,7 +3,7 @@ import type { StripeWalletCheckoutSuccess } from './StripeCheckoutExpressCheckou
 import { type ReactNode } from 'react';
 import type { Appearance, StripeCheckoutExpressCheckoutElementOptions } from '@stripe/stripe-js';
 import { type PlatformWalletPaymentMethod } from './walletPlatform.js';
-import type { StripeSubscriptionCheckoutAnalyticsContext } from '../services/checkoutCompletionAnalytics.service.js';
+import { type StripeSubscriptionCheckoutAnalyticsContext } from '../services/checkoutCompletionAnalytics.service.js';
 import type { StripeWalletCheckoutSession } from './WalletSubscriptionCheckoutSlot.js';
 export type StripeWalletSurfaceAvailability = {
     anyAvailable: boolean;

package/dist/providers/stripe/components/StripeWalletSurface.internal.js

@@ -4,8 +4,10 @@ import { CheckoutEmailDialog } from '../../../components/CheckoutEmailDialog.js'
 import { isCheckoutEmailError, isValidCheckoutEmail, normalizeCheckoutEmailResult } from '../../../services/checkoutEmail.js';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { usePlatformWalletPaymentMethods, } from './walletPlatform.js';
+import { trackStripeCheckoutShown } from '../services/checkoutCompletionAnalytics.service.js';
 import { ApplePaySubscriptionCheckoutSlot } from './ApplePaySubscriptionCheckoutSlot.js';
 import { GooglePaySubscriptionCheckoutSlot } from './GooglePaySubscriptionCheckoutSlot.js';
+import { useCheckoutShownOnce } from '../hooks/useCheckoutShownOnce.js';
 export function buildStripeWalletSurfaceAnalyticsMetadata(analyticsMetadata, surfaceId) {
     return Object.assign(Object.assign({}, (analyticsMetadata !== null && analyticsMetadata !== void 0 ? analyticsMetadata : {})), { checkoutSurfaceId: surfaceId });
 }
@@ -169,6 +171,12 @@ export function StripeWalletSurface({ amountCents, appearance, applePayOptions,
         resolved: availability.resolved,
         suspended,
     });
+    const walletButtonVisible = shouldRenderSurface && availability.anyAvailable && !needsEmail;
+    useCheckoutShownOnce(walletButtonVisible && Boolean(surfaceCheckoutAnalytics), () => {
+        if (surfaceCheckoutAnalytics) {
+            trackStripeCheckoutShown(Object.assign(Object.assign({}, surfaceCheckoutAnalytics), { checkoutSessionId: session.checkoutSessionId, checkoutSurface: 'wallet' }));
+        }
+    });
     if (needsEmail && session.configured && !suspended && walletPaymentMethods.length > 0) {
         if (!emailDialogOpen || !onCustomerEmailCommit)
             return null;

package/dist/providers/stripe/components/index.d.ts

@@ -10,5 +10,6 @@ export * from './StripeExpressCheckoutElement.js';
 export * from './StripeOneTimeWalletSurface.js';
 export * from './StripePlanSelector.js';
 export * from './StripeSubscriptionWalletSurface.js';
+export * from './StripeWalletFirstCheckout.js';
 export * from './WalletSubscriptionCheckoutSlot.js';
 export * from './walletPlatform.js';

package/dist/providers/stripe/components/index.js

@@ -10,5 +10,6 @@ export * from './StripeExpressCheckoutElement.js';
 export * from './StripeOneTimeWalletSurface.js';
 export * from './StripePlanSelector.js';
 export * from './StripeSubscriptionWalletSurface.js';
+export * from './StripeWalletFirstCheckout.js';
 export * from './WalletSubscriptionCheckoutSlot.js';
 export * from './walletPlatform.js';

package/dist/providers/stripe/hooks/useCheckoutShownOnce.d.ts

@@ -0,0 +1,2 @@
+/** Calls `track` once per mount, the first time `enabled` is true; re-renders never repeat it. */
+export declare function useCheckoutShownOnce(enabled: boolean, track: () => void): void;

package/dist/providers/stripe/hooks/useCheckoutShownOnce.js

@@ -0,0 +1,11 @@
+import { useEffect, useRef } from 'react';
+/** Calls `track` once per mount, the first time `enabled` is true; re-renders never repeat it. */
+export function useCheckoutShownOnce(enabled, track) {
+    const tracked = useRef(false);
+    useEffect(() => {
+        if (!enabled || tracked.current)
+            return;
+        tracked.current = true;
+        track();
+    }, [enabled, track]);
+}

package/dist/providers/stripe/services/checkoutCompletionAnalytics.service.d.ts

@@ -23,9 +23,16 @@ export type TrackPaidStripeSubscriptionCheckoutCompletedInput = StripeSubscripti
 export type TrackStripeSubscriptionPaymentInfoSubmittedInput = StripeSubscriptionCheckoutAnalyticsContext & {
     checkoutSessionId?: string | null;
 };
+export type StripeCheckoutSurface = 'inline' | 'dialog' | 'wallet';
+export type TrackStripeCheckoutShownInput = StripeSubscriptionCheckoutAnalyticsContext & {
+    checkoutSessionId?: string | null;
+    checkoutSurface: StripeCheckoutSurface;
+};
 export type TrackStripeSubscriptionCheckoutStartedResult = 'already_tracked' | 'analytics_rejected' | 'missing_checkout_session' | 'tracked';
 export type TrackPaidStripeSubscriptionCheckoutCompletedResult = 'already_tracked' | 'analytics_rejected' | 'missing_checkout_session' | 'tracked' | 'unpaid';
 export type TrackStripeSubscriptionPaymentInfoSubmittedResult = 'already_tracked' | 'analytics_rejected' | 'missing_checkout_session' | 'tracked';
+/** Each call is one show of a checkout form or wallet button; callers own once-per-show. */
+export declare function trackStripeCheckoutShown(input: TrackStripeCheckoutShownInput): void;
 export declare function trackStripeSubscriptionCheckoutStarted(input: TrackStripeSubscriptionCheckoutStartedInput): Promise<TrackStripeSubscriptionCheckoutStartedResult>;
 export declare function queueStripeSubscriptionCheckoutStarted(input: TrackStripeSubscriptionCheckoutStartedInput): void;
 export declare function trackStripeSubscriptionPaymentInfoSubmitted(input: TrackStripeSubscriptionPaymentInfoSubmittedInput): Promise<TrackStripeSubscriptionPaymentInfoSubmittedResult>;

package/dist/providers/stripe/services/checkoutCompletionAnalytics.service.js

@@ -49,6 +49,24 @@ const markCheckoutSessionTracked = (eventName, checkoutSessionId, runtimeConfig)
         // A stable checkout-session event id still protects provider-side dedupe.
     }
 };
+/** Each call is one show of a checkout form or wallet button; callers own once-per-show. */
+export function trackStripeCheckoutShown(input) {
+    var _a;
+    const checkoutSessionId = ((_a = input.checkoutSessionId) === null || _a === void 0 ? void 0 : _a.trim()) || '';
+    try {
+        publicAnalyticsSdk.trackCheckoutShown({
+            featureFlags: input.featureFlags,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            stepType: input.stepType,
+            stepContractVersion: input.stepContractVersion,
+            metadata: Object.assign(Object.assign(Object.assign(Object.assign({}, asRecord(input.metadata)), { checkout_surface: input.checkoutSurface }), (checkoutSessionId ? { checkoutSessionId, checkout_session_id: checkoutSessionId } : {})), { environment: input.environment || asRecord(input.metadata).environment, payment_provider: 'stripe' }),
+        });
+    }
+    catch (_b) {
+        // Analytics must not affect checkout rendering.
+    }
+}
 export async function trackStripeSubscriptionCheckoutStarted(input) {
     var _a;
     const checkoutSessionId = ((_a = input.checkoutSessionId) === null || _a === void 0 ? void 0 : _a.trim()) || '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/payments",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/The-Solid-Grove/funnelsgrove.git",
@@ -46,11 +46,11 @@
     "jsdom": "20.0.3",
     "typescript": "^5",
     "vitest": "^3.2.4",
-    "@funnelsgrove/runtime": "0.30.0",
-    "@funnelsgrove/analytics": "0.12.0"
+    "@funnelsgrove/runtime": "0.31.0",
+    "@funnelsgrove/analytics": "0.13.0"
   },
   "peerDependencies": {
-    "@funnelsgrove/runtime": "^0.30.0",
-    "@funnelsgrove/analytics": "^0.12.0"
+    "@funnelsgrove/runtime": "^0.31.0",
+    "@funnelsgrove/analytics": "^0.13.0"
   }
 }