@funnelsgrove/payments

Shared billing and checkout helpers for funnels.

Read this file before editing checkout code. Deeper implementation docs:

• Shared Payments
• Funnel SDK runtime service

Owns provider-backed checkout primitives

@funnelsgrove/payments owns reusable payment contracts, provider adapters, checkout-session helpers, wallet slots, and checkout UI primitives. Funnel code owns paywall layout, copy, when an offer opens, post-payment navigation, and funnel-specific analytics timing.

Current Checkout Path

Use these for new subscription paywalls:

• useStripeSubscriptionCheckoutSession
• SharedStripeCheckoutV2Dialog
• ApplePaySubscriptionCheckoutSlot
• GooglePaySubscriptionCheckoutSlot
• WalletSubscriptionCheckoutSlot
• trackPaidStripeSubscriptionCheckoutCompleted

Use these for new one-time paywall plans:

• createStripeOneTimeCheckout
• SharedStripeCheckoutV2Dialog

Use chargeStripeOneClickPayment for post-checkout one-click upsells when the shared client helper fits the funnel. It delegates to funnelSdkService.chargeOneClickPayment.

Compatibility-Only Surfaces

Keep these exports available for saved drafts, old published artifacts, and controlled migrations. Do not use them for new subscription checkout work:

• createStripePaymentIntent
• SharedStripeCheckoutDialog
• ApplePaySubscribeButton
• GooglePaySubscribeButton
• APPLE_PAY_QR_CODE_URL

When a live funnel still uses one of these, migrate the funnel deliberately with its own tests before removing the export.

Use This Package For

• billing catalog types and normalization helpers
• runtime-mode-aware plan catalog selection
• Stripe SDK and public payment API client helpers
• subscription checkout-session preparation, reuse, update, and recovery
• reusable plan-selector UI
• shared embedded checkout dialogs
• Stripe Express Checkout wallet slots and lower-level wallet primitives
• generic timed-offer display helpers
• checkout completion analytics handoff to @funnelsgrove/analytics

Do Not Use This Package For

• funnel routing
• manifest validation
• funnel-owned billing catalog entries
• funnel-specific paywall layout or copy
• funnel-specific decisions about when to activate, upgrade, or recover an offer
• analytics transport internals
• direct provider SDK calls inside funnel paywall steps; add provider adapters here first, then wire the funnel to the shared session or slot

Public Surfaces

• config/billing.config: billing catalog, mapping, plan, and discount contracts.
• services/planCatalog.service: plan resolution and selection helpers.
• services/runtimeBillingPlanCatalog.service: test/live runtime catalog selection.
• services/paywallOffer.service: timed discount and display-plan helpers.
• services/stripe.service: Stripe loader, Checkout Session, hosted checkout, one-click, one-time Checkout Session clients, and deprecated PaymentIntent compatibility clients.
• providers/*: provider-neutral checkout state and Stripe subscription checkout slots.
• components/shared/*: plan selector, checkout dialogs, Express Checkout wrappers, wallet placeholders, and trust assets.
• testing/walletCheckoutSmoke: wallet checkout smoke assertions.

Engineering Rules

• Keep provider-specific implementation under src/providers/<provider>.
• Stripe owns real card fields and wallet controls. Local wallet buttons are placeholders until Stripe confirms availability.
• Wallet unavailable state must fall back to card/manual checkout or disappear.
• Do not count checkout intent until the visitor taps or confirms a visible checkout CTA.
• Wallet slots may create render-only Checkout Sessions on mount so Apple Pay and Google Pay render before the visitor taps. These sessions must use checkoutStartSource: 'wallet_render'; trusted server checkout_started analytics ignores that source.
• 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.
• Checkout metadata must avoid sensitive raw query params and use @funnelsgrove/analytics metadata helpers.

Build, Test, Publish

npm run test:run --workspace @funnelsgrove/payments
npm run build --workspace @funnelsgrove/payments
npm publish --workspace @funnelsgrove/payments --access public

The build normalizes generated relative ESM imports to explicit .js files for published package consumers.