@funnelsgrove/payments 0.38.0 → 0.40.0

package/README.md

@@ -41,10 +41,13 @@ elsewhere, preselected, with Stripe's own button, and the card form as the secon
   `checkoutAnalytics`, a complete `StripeWalletFirstCheckoutCopy` from the funnel's
   content, and `themeColor`/`buttonColor`.
 - The card form has no ZIP or terms text.
+- `onCancel` runs when the visitor closes the Apple Pay or Google Pay sheet without paying,
+  for example to show an extra discount. The form is unlocked again by then.
 - 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_started` (when the card form opens, or on wallet intent),
+- 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
@@ -220,11 +223,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.38.0";
+export declare const PAYMENTS_PACKAGE_VERSION = "0.40.0";

package/dist/generated/package-version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generate-package-version.mjs.
-export const PAYMENTS_PACKAGE_VERSION = "0.38.0";
+export const PAYMENTS_PACKAGE_VERSION = "0.40.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

@@ -26,6 +26,8 @@ export type StripeWalletFirstCheckoutProps = {
     copy: StripeWalletFirstCheckoutCopy;
     customerEmail: string;
     customerName?: string | null;
+    /** The visitor closed the Apple Pay or Google Pay sheet without paying, e.g. to offer a discount. */
+    onCancel?: () => void;
     onError?: (message: string | null) => void;
     onSuccess?: () => void | Promise<void>;
     returnUrl: string;

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

@@ -20,8 +20,9 @@ import { completePaywallCheckout } from '@funnelsgrove/runtime';
 import { StripeCheckoutExpressCheckoutButton } from './StripeCheckoutExpressCheckoutButton.js';
 import { resolveWalletPlatform } from './walletPlatform.js';
 import { stripeWalletFirstCheckoutStyles } from './StripeWalletFirstCheckout.styles.js';
-import { queueStripeSubscriptionCheckoutStarted, trackPaidStripeSubscriptionCheckoutCompleted, trackStripeSubscriptionPaymentInfoSubmitted, } from '../services/checkoutCompletionAnalytics.service.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: {
@@ -41,6 +42,11 @@ export function StripeWalletFirstCheckout(props) {
         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')
@@ -49,7 +55,7 @@ export function StripeWalletFirstCheckout(props) {
     }, [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, }) {
+function StripeWalletFirstCheckoutForm({ amountCents, checkoutAnalytics, checkoutSessionId, copy, customerEmail, customerName, onCancel, 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);
@@ -161,7 +167,7 @@ function StripeWalletFirstCheckoutForm({ amountCents, checkoutAnalytics, checkou
     // 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 }));
+    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); onCancel === null || onCancel === void 0 ? void 0 : onCancel(); }, 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 }) {

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/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.38.0",
+  "version": "0.40.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"
   }
 }