@funnelsgrove/payments 0.1.37 → 0.1.39

package/README.md

@@ -2,6 +2,11 @@
 
 Shared billing and checkout helpers for funnels.
 
+Detailed implementation docs:
+
+- [Shared Payments](../../docs/funnel-sdk/shared-payments.md)
+- [Funnel API payment endpoints](../../docs/funnel-sdk/funnel-api.md#checkout-endpoints)
+
 ## Build And Publish
 
 - Build distributable output with `npm run build --workspace @funnelsgrove/payments`.
@@ -42,6 +47,7 @@ Shared billing and checkout helpers for funnels.
 - `src/providers/stripe/useStripeSubscriptionCheckoutSession.ts` for Stripe SDK initialization, publishable-key resolution, subscription client-secret preparation, card/wallet loading state, and friendly checkout errors
 - `src/providers/stripe/ApplePaySubscriptionCheckoutSlot.tsx` and `src/providers/stripe/GooglePaySubscriptionCheckoutSlot.tsx` for wallet shells that prepare Stripe Express Checkout on load, keep the loading placeholder clickable, and let Stripe's real wallet controls sit above the placeholder as soon as they mount
 - Stripe subscription checkout sessions reuse the active client secret across card checkout and paywall wallet checkout for the same intent key, so opening the embedded checkout after a paywall wallet button is ready does not create a second subscription session.
+- `trackPaidStripeSubscriptionCheckoutCompleted` verifies a Stripe custom Checkout Session is paid before delegating to `@funnelsgrove/analytics` for the canonical `checkout_completed` purchase event.
 - Stripe Express Checkout elements must stay mounted and measurable until Stripe reports availability; only hide the container after `onReady` or `onLoadError` reports that the requested wallet method is unavailable.
 - Shared checkout dialogs must switch to card checkout when Stripe reports no requested wallet availability, so an unavailable Apple Pay or Google Pay shell never leaves a fake wallet tab blocking the card form.
 - Wallet slots should not leave disabled grey placeholder shells blocking the paywall. While availability is unknown, the placeholder can sit behind Stripe's real wallet element; after Stripe reports unavailable or preparation cannot create a client secret, the placeholder must disappear instead of opening a card checkout under wallet branding.
@@ -57,7 +63,7 @@ Shared billing and checkout helpers for funnels.
 ## What Does Not Belong Here
 
 - funnel routing
-- funnel analytics
+- funnel-owned analytics event definitions outside the shared checkout completion handoff
 - funnel-owned step layout outside the shared checkout shell
 - funnel-owned billing catalog entries
 - funnel-specific decisions about when to activate or upgrade an offer

package/dist/components/shared/StripeCheckoutExpressCheckoutButton.d.ts

@@ -15,7 +15,8 @@ export type StripeCheckoutExpressCheckoutButtonProps = {
     serverUpdateKey?: string | null;
     onServerUpdate?: () => Promise<boolean>;
     onAvailabilityChange?: (available: boolean) => void;
+    onCancel?: () => void;
     onError?: (message: string | null) => void;
     onSuccess?: () => void | Promise<void>;
 };
-export declare function StripeCheckoutExpressCheckoutButton({ beforeConfirm, returnUrl, confirmEmail, customerEmail, className, options, availabilityPaymentMethods, initialAvailable, keepInitialAvailableOnReady, serverUpdateKey, onServerUpdate, onAvailabilityChange, onError, onSuccess, }: StripeCheckoutExpressCheckoutButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function StripeCheckoutExpressCheckoutButton({ beforeConfirm, returnUrl, confirmEmail, customerEmail, className, options, availabilityPaymentMethods, initialAvailable, keepInitialAvailableOnReady, serverUpdateKey, onServerUpdate, onAvailabilityChange, onCancel, onError, onSuccess, }: StripeCheckoutExpressCheckoutButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/shared/StripeCheckoutExpressCheckoutButton.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { ExpressCheckoutElement, useCheckout, } from '@stripe/react-stripe-js/checkout';
+const ExpressCheckoutElementWithCancel = ExpressCheckoutElement;
 const buildDefaultOptions = () => ({
     buttonHeight: 55,
     buttonTheme: {
@@ -25,7 +26,7 @@ const buildDefaultOptions = () => ({
         paypal: 'never',
     },
 });
-export function StripeCheckoutExpressCheckoutButton({ beforeConfirm, returnUrl, confirmEmail = true, customerEmail, className, options, availabilityPaymentMethods = ['applePay'], initialAvailable, keepInitialAvailableOnReady = false, serverUpdateKey, onServerUpdate, onAvailabilityChange, onError, onSuccess, }) {
+export function StripeCheckoutExpressCheckoutButton({ beforeConfirm, returnUrl, confirmEmail = true, customerEmail, className, options, availabilityPaymentMethods = ['applePay'], initialAvailable, keepInitialAvailableOnReady = false, serverUpdateKey, onServerUpdate, onAvailabilityChange, onCancel, onError, onSuccess, }) {
     const checkoutState = useCheckout();
     const appliedServerUpdateKeyRef = useRef('');
     const serverUpdatePromiseRef = useRef(null);
@@ -143,7 +144,7 @@ export function StripeCheckoutExpressCheckoutButton({ beforeConfirm, returnUrl,
                     effectiveWalletAvailable === false ? 'is-hidden' : '',
                 ]
                     .filter(Boolean)
-                    .join(' '), children: _jsx(ExpressCheckoutElement, { options: resolvedOptions, onConfirm: (event) => void handleConfirm(event), onLoadError: ({ error }) => {
+                    .join(' '), children: _jsx(ExpressCheckoutElementWithCancel, { options: resolvedOptions, onCancel: onCancel, onConfirm: (event) => void handleConfirm(event), onLoadError: ({ error }) => {
                         setWalletAvailable(false);
                         onAvailabilityChange === null || onAvailabilityChange === void 0 ? void 0 : onAvailabilityChange(false);
                         onError === null || onError === void 0 ? void 0 : onError(error.message || 'Unable to load wallet checkout.');

package/dist/components/shared/StripeExpressCheckoutButton.d.ts

@@ -12,7 +12,8 @@ export type StripeExpressCheckoutButtonProps = {
     initialAvailable?: boolean | null;
     keepInitialAvailableOnReady?: boolean;
     onAvailabilityChange?: (available: boolean) => void;
+    onCancel?: () => void;
     onError?: (message: string | null) => void;
     onSuccess?: () => void | Promise<void>;
 };
-export declare function StripeExpressCheckoutButton({ amountCents, beforeConfirm, summaryLabel, returnUrl, customerEmail, customerName, className, options, availabilityPaymentMethods, initialAvailable, keepInitialAvailableOnReady, onAvailabilityChange, onError, onSuccess, }: StripeExpressCheckoutButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function StripeExpressCheckoutButton({ amountCents, beforeConfirm, summaryLabel, returnUrl, customerEmail, customerName, className, options, availabilityPaymentMethods, initialAvailable, keepInitialAvailableOnReady, onAvailabilityChange, onCancel, onError, onSuccess, }: StripeExpressCheckoutButtonProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/shared/StripeExpressCheckoutButton.js

@@ -53,7 +53,7 @@ const buildDefaultOptions = (input) => {
 const isSuccessfulIntentStatus = (status) => {
     return status === 'succeeded' || status === 'processing' || status === 'requires_capture';
 };
-export function StripeExpressCheckoutButton({ amountCents, beforeConfirm, summaryLabel, returnUrl, customerEmail, customerName, className, options, availabilityPaymentMethods = ['applePay'], initialAvailable, keepInitialAvailableOnReady = false, onAvailabilityChange, onError, onSuccess, }) {
+export function StripeExpressCheckoutButton({ amountCents, beforeConfirm, summaryLabel, returnUrl, customerEmail, customerName, className, options, availabilityPaymentMethods = ['applePay'], initialAvailable, keepInitialAvailableOnReady = false, onAvailabilityChange, onCancel, onError, onSuccess, }) {
     const stripe = useStripe();
     const elements = useElements();
     const [walletAvailable, setWalletAvailable] = useState(initialAvailable !== null && initialAvailable !== void 0 ? initialAvailable : null);
@@ -139,7 +139,7 @@ export function StripeExpressCheckoutButton({ amountCents, beforeConfirm, summar
                     effectiveWalletAvailable === false ? 'is-hidden' : '',
                 ]
                     .filter(Boolean)
-                    .join(' '), children: _jsx(ExpressCheckoutElement, { options: resolvedOptions, onConfirm: (event) => void handleConfirm(event), onLoadError: ({ error }) => {
+                    .join(' '), children: _jsx(ExpressCheckoutElement, { options: resolvedOptions, onCancel: onCancel, onConfirm: (event) => void handleConfirm(event), onLoadError: ({ error }) => {
                         setWalletAvailable(false);
                         onAvailabilityChange === null || onAvailabilityChange === void 0 ? void 0 : onAvailabilityChange(false);
                         onError === null || onError === void 0 ? void 0 : onError(error.message || 'Unable to load wallet checkout.');

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './services/planCatalog.service.js';
 export * from './services/runtimeBillingPlanCatalog.service.js';
 export * from './services/paywallOffer.service.js';
 export * from './services/stripe.service.js';
+export * from './services/checkoutCompletionAnalytics.service.js';
 export * from './hooks/useResolvedPaywallPlans.js';
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/useStripeSubscriptionCheckoutSession.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './services/planCatalog.service.js';
 export * from './services/runtimeBillingPlanCatalog.service.js';
 export * from './services/paywallOffer.service.js';
 export * from './services/stripe.service.js';
+export * from './services/checkoutCompletionAnalytics.service.js';
 export * from './hooks/useResolvedPaywallPlans.js';
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/useStripeSubscriptionCheckoutSession.js';

package/dist/providers/stripe/WalletSubscriptionCheckoutSlot.d.ts

@@ -31,6 +31,7 @@ export type WalletSubscriptionCheckoutSlotProps = {
     disabled?: boolean;
     expressCheckoutAllowed?: boolean;
     onAvailabilityChange?: (available: boolean) => void;
+    onCancel?: () => void;
     onError?: (message: string | null) => void;
     onSuccess?: () => void | Promise<void>;
     onUnavailableClick?: () => Promise<void> | void;
@@ -44,5 +45,5 @@ export type WalletSubscriptionCheckoutSlotProps = {
     suspended?: boolean;
 };
 export declare function WalletSubscriptionCheckoutLoadingPlaceholder({ className, label, }: Pick<WalletPlaceholderButtonProps, 'className' | 'label'>): import("react/jsx-runtime").JSX.Element;
-export declare function WalletSubscriptionCheckoutSlot({ amountCents, availabilityPaymentMethod, beforeConfirm, className, customerEmail, customerName, disabled, expressCheckoutAllowed, onAvailabilityChange, onError, onSuccess, onUnavailableClick, options, placeholderLabel, renderPreparingPlaceholder, renderPlaceholder, returnUrl, session, summaryLabel, suspended, }: WalletSubscriptionCheckoutSlotProps): import("react/jsx-runtime").JSX.Element;
+export declare function WalletSubscriptionCheckoutSlot({ amountCents, availabilityPaymentMethod, beforeConfirm, className, customerEmail, customerName, disabled, expressCheckoutAllowed, onAvailabilityChange, onCancel, onError, onSuccess, onUnavailableClick, options, placeholderLabel, renderPreparingPlaceholder, renderPlaceholder, returnUrl, session, summaryLabel, suspended, }: WalletSubscriptionCheckoutSlotProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/providers/stripe/WalletSubscriptionCheckoutSlot.js

@@ -27,7 +27,7 @@ export function WalletSubscriptionCheckoutLoadingPlaceholder({ className, label,
             .filter(Boolean)
             .join(' '), "aria-label": label, role: 'status', children: [_jsx("span", { className: 'wallet-subscription-checkout-slot__loading-bar' }), _jsx("style", { children: walletSubscriptionCheckoutLoadingPlaceholderStyles })] }));
 }
-export function WalletSubscriptionCheckoutSlot({ amountCents, availabilityPaymentMethod, beforeConfirm, className, customerEmail, customerName, disabled = false, expressCheckoutAllowed = true, onAvailabilityChange, onError, onSuccess, onUnavailableClick, options, placeholderLabel, renderPreparingPlaceholder, renderPlaceholder, returnUrl, session, summaryLabel, suspended = false, }) {
+export function WalletSubscriptionCheckoutSlot({ amountCents, availabilityPaymentMethod, beforeConfirm, className, customerEmail, customerName, disabled = false, expressCheckoutAllowed = true, onAvailabilityChange, onCancel, onError, onSuccess, onUnavailableClick, options, placeholderLabel, renderPreparingPlaceholder, renderPlaceholder, returnUrl, session, summaryLabel, suspended = false, }) {
     const [walletAvailability, setWalletAvailability] = useState({
         available: null,
         intentKey: session.intentKey,
@@ -131,7 +131,7 @@ export function WalletSubscriptionCheckoutSlot({ amountCents, availabilityPaymen
                     .filter(Boolean)
                     .join(' '), "aria-busy": placeholderIsPreparing || undefined, children: [shouldRenderExpressCheckout &&
                         session.activeClientSecret &&
-                        session.stripePromise ? (_jsx(StripeExpressCheckoutElement, { amountCents: amountCents, availabilityPaymentMethods: [availabilityPaymentMethod], beforeConfirm: beforeConfirm, className: className, clientSecret: session.activeClientSecret, customerEmail: customerEmail, customerName: customerName, onAvailabilityChange: handleAvailabilityChange, onError: handleError, onSuccess: onSuccess, options: options, returnUrl: returnUrl, serverUpdateKey: serverUpdateKey, stripePromise: session.stripePromise, summaryLabel: summaryLabel, onServerUpdate: session.updateCheckoutSessionPlan })) : null, shouldRenderPlaceholder ? (_jsx("div", { className: 'wallet-subscription-checkout-slot__placeholder', children: placeholderRenderer({
+                        session.stripePromise ? (_jsx(StripeExpressCheckoutElement, { amountCents: amountCents, availabilityPaymentMethods: [availabilityPaymentMethod], beforeConfirm: beforeConfirm, className: className, clientSecret: session.activeClientSecret, customerEmail: customerEmail, customerName: customerName, onAvailabilityChange: handleAvailabilityChange, onCancel: onCancel, onError: handleError, onSuccess: onSuccess, options: options, returnUrl: returnUrl, serverUpdateKey: serverUpdateKey, stripePromise: session.stripePromise, summaryLabel: summaryLabel, onServerUpdate: session.updateCheckoutSessionPlan })) : null, shouldRenderPlaceholder ? (_jsx("div", { className: 'wallet-subscription-checkout-slot__placeholder', children: placeholderRenderer({
                             className,
                             disabled: slotDisabled,
                             label: placeholderLabel,

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

@@ -0,0 +1,12 @@
+import type { RuntimeMode } from '@funnelsgrove/runtime';
+import { type StripeRuntimeConfigOverrides } from './stripe.service.js';
+export type TrackPaidStripeSubscriptionCheckoutCompletedInput = {
+    checkoutSessionId?: string | null;
+    environment?: RuntimeMode;
+    metadata?: Record<string, unknown> | null;
+    runtimeConfig?: StripeRuntimeConfigOverrides;
+    stepId?: string;
+    stepName?: string;
+};
+export type TrackPaidStripeSubscriptionCheckoutCompletedResult = 'already_tracked' | 'missing_checkout_session' | 'tracked' | 'unpaid';
+export declare function trackPaidStripeSubscriptionCheckoutCompleted(input: TrackPaidStripeSubscriptionCheckoutCompletedInput): Promise<TrackPaidStripeSubscriptionCheckoutCompletedResult>;

package/dist/services/checkoutCompletionAnalytics.service.js

@@ -0,0 +1,74 @@
+import { publicAnalyticsSdk, } from '@funnelsgrove/analytics';
+import { verifyStripeSubscriptionCheckoutPayment, } from './stripe.service.js';
+const asRecord = (value) => {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+};
+const activeCheckoutCompletionKeys = new Set();
+const buildCheckoutCompletedStorageKey = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    const funnelId = ((_a = runtimeConfig === null || runtimeConfig === void 0 ? void 0 : runtimeConfig.funnelId) === null || _a === void 0 ? void 0 : _a.trim()) || 'unknown_funnel';
+    return `funnelsgrove:checkout_completed:${funnelId}:${checkoutSessionId}`;
+};
+const hasTrackedCheckoutSession = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    if (typeof window === 'undefined') {
+        return false;
+    }
+    try {
+        return Boolean((_a = window.sessionStorage) === null || _a === void 0 ? void 0 : _a.getItem(buildCheckoutCompletedStorageKey(checkoutSessionId, runtimeConfig)));
+    }
+    catch (_b) {
+        return false;
+    }
+};
+const markCheckoutSessionTracked = (checkoutSessionId, runtimeConfig) => {
+    var _a;
+    if (typeof window === 'undefined') {
+        return;
+    }
+    try {
+        (_a = window.sessionStorage) === null || _a === void 0 ? void 0 : _a.setItem(buildCheckoutCompletedStorageKey(checkoutSessionId, runtimeConfig), '1');
+    }
+    catch (_b) {
+        // A stable checkout-session event id still protects provider-side dedupe.
+    }
+};
+export async function trackPaidStripeSubscriptionCheckoutCompleted(input) {
+    var _a;
+    const checkoutSessionId = ((_a = input.checkoutSessionId) === null || _a === void 0 ? void 0 : _a.trim()) || '';
+    if (!checkoutSessionId) {
+        return 'missing_checkout_session';
+    }
+    const completionKey = buildCheckoutCompletedStorageKey(checkoutSessionId, input.runtimeConfig);
+    if (activeCheckoutCompletionKeys.has(completionKey) ||
+        hasTrackedCheckoutSession(checkoutSessionId, input.runtimeConfig)) {
+        return 'already_tracked';
+    }
+    activeCheckoutCompletionKeys.add(completionKey);
+    try {
+        const checkoutStatus = await verifyStripeSubscriptionCheckoutPayment({
+            checkoutSessionId,
+            environment: input.environment,
+            runtimeConfig: input.runtimeConfig,
+        });
+        if (!checkoutStatus.paid) {
+            return 'unpaid';
+        }
+        const analyticsMetadata = asRecord(checkoutStatus.analyticsMetadata);
+        const conversionInput = {
+            eventId: checkoutSessionId,
+            stepId: input.stepId,
+            stepName: input.stepName,
+            metadata: Object.assign(Object.assign(Object.assign({}, asRecord(input.metadata)), analyticsMetadata), { checkoutSessionId, checkout_session_id: checkoutSessionId, checkout_session_status: checkoutStatus.status || undefined, payment_status: checkoutStatus.paymentStatus || undefined, environment: checkoutStatus.environment || input.environment || analyticsMetadata.environment }),
+        };
+        publicAnalyticsSdk.trackCheckoutCompleted(conversionInput);
+        markCheckoutSessionTracked(checkoutSessionId, input.runtimeConfig);
+        await publicAnalyticsSdk.flush().catch(() => 0);
+        return 'tracked';
+    }
+    finally {
+        activeCheckoutCompletionKeys.delete(completionKey);
+    }
+}

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

@@ -119,8 +119,22 @@ type UpdateSubscriptionCheckoutPlanResponse = {
     checkoutSessionId: string;
     environment?: 'test' | 'live';
 };
+export type VerifySubscriptionCheckoutPaymentInput = {
+    checkoutSessionId: string;
+    environment?: RuntimeMode;
+    runtimeConfig?: StripeRuntimeConfigOverrides;
+};
+export type VerifySubscriptionCheckoutPaymentResponse = {
+    checkoutSessionId: string;
+    paid: boolean;
+    paymentStatus?: string | null;
+    status?: string | null;
+    environment?: 'test' | 'live';
+    analyticsMetadata?: Record<string, unknown>;
+};
 export declare function createStripeSubscriptionCheckout(input: CreateSubscriptionCheckoutInput): Promise<CreateSubscriptionCheckoutResponse>;
 export declare function updateStripeSubscriptionCheckoutPlan(input: UpdateSubscriptionCheckoutPlanInput): Promise<UpdateSubscriptionCheckoutPlanResponse>;
+export declare function verifyStripeSubscriptionCheckoutPayment(input: VerifySubscriptionCheckoutPaymentInput): Promise<VerifySubscriptionCheckoutPaymentResponse>;
 type CreateCheckoutSessionInput = {
     plan: CheckoutSessionPlanInput;
     successUrl: string;

package/dist/services/stripe.service.js

@@ -714,6 +714,31 @@ export async function updateStripeSubscriptionCheckoutPlan(input) {
     }
     return (await response.json());
 }
+export async function verifyStripeSubscriptionCheckoutPayment(input) {
+    const checkoutSessionId = input.checkoutSessionId.trim();
+    if (!checkoutSessionId) {
+        throw new Error('checkoutSessionId is required');
+    }
+    const runtimeConfig = resolveStripeRuntimeConfig(input.runtimeConfig);
+    const response = await fetch(buildStripeRuntimeApiUrl('/sdk/public/payments/subscriptions/checkout-session-status', runtimeConfig), {
+        method: 'POST',
+        headers: buildStripeRuntimeHeaders(runtimeConfig, {
+            'Content-Type': 'application/json',
+        }),
+        body: JSON.stringify({
+            publishableKey: runtimeConfig.funnelSdkPublishableKey || undefined,
+            funnelId: runtimeConfig.funnelId || undefined,
+            funnelVersionId: runtimeConfig.funnelVersionId || undefined,
+            checkoutSessionId,
+            environment: input.environment || undefined,
+        }),
+    });
+    if (!response.ok) {
+        const errorMessage = await parseErrorMessage(response, 'Unable to verify subscription checkout');
+        throw new Error(errorMessage);
+    }
+    return (await response.json());
+}
 export async function createStripeCheckoutSession(input) {
     var _a, _b, _c, _d, _e;
     const recurring = resolveCheckoutPlanRecurringConfig(input.plan);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/payments",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",
@@ -27,6 +27,7 @@
     "test:run": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@funnelsgrove/analytics": "^0.1.13",
     "@funnelsgrove/runtime": "^0.1.18",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",