@funnelsgrove/payments

Shared billing and checkout helpers for funnels.

Build And Publish

• Build distributable output with npm run build --workspace @funnelsgrove/payments.
• Publish from the repo root with npm publish --workspace @funnelsgrove/payments --access public.
• The package pins @funnelsgrove/runtime to the same exact version and the build resolves against the runtime package's emitted dist contract.
• The build normalizes generated relative ESM imports to explicit .js files for published package consumers.

Use This Package For

• Stripe plan loading and checkout integration
• global funnel billing catalog contracts
• reusable plan-selector UI
• reusable shared embedded checkout dialogs
• reusable Stripe Express Checkout wrappers for funnels that need native Apple Pay or Google Pay controls outside the shared dialogs
• provider-ready checkout session primitives that keep paywalls from owning provider SDK setup, client-secret preparation, or wallet-button replacement logic
• compatibility exports for saved builder paywall drafts, including the Apple Pay subscribe fallback button
• billing catalog types and runtime helpers
• reusable paywall offer helpers for timed discounts, discounted display plans, promo labels, and renewal disclaimer text

Responsibilities

• keep paywall behavior consistent across funnels
• define the shared billing types used by funnel-local catalogs
• expose one ordered funnel-local billing catalog contract
• keep the public checkout identity contract aligned on user_id for payment intents and any remaining hosted-checkout fallbacks
• keep reusable discount math and display-plan shaping out of funnel step files
• keep provider-specific implementation under src/providers/<provider> so funnels can consume stable payment slots while future providers add their own adapters

What Belongs Here

• billing catalog types and normalization helpers
• Stripe SDK wiring
• shared checkout/plan-selector components
• generic paywall offer helpers that accept funnel-provided plans and discount catalogs
• the default embedded Stripe checkout dialog UX that funnels can feed with their own copy, pricing summary rows, guarantee note, and an optional editable customer email that is committed before card or wallet confirmation
• the StripeExpressCheckoutElement wrapper, which keeps Elements provider ownership inside this package so catalog funnels with their own dependency installs do not pass Stripe promises across duplicate local Stripe type copies
• src/providers/paymentProvider.types.ts for provider-neutral checkout preparation state and provider ids
• 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.
• 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.
• Checkout v2 owns only real Stripe Elements for card and wallet collection: Stripe controls the card-field placeholders, Stripe's ExpressCheckoutElement controls Apple Pay / Google Pay availability, desktop web can expose both wallet icons, and mobile narrows to Apple Pay on iOS or Google Pay on Android.
• Checkout v2 can receive a paywall-confirmed wallet availability hint and seed its wallet tab from that state, letting a checkout reopen keep Apple Pay or Google Pay visible while its own Express Checkout element remounts against the same client secret.
• Checkout v2 renders the wallet tab icons from the active platform wallet list and keeps Apple Pay / Google Pay marks large enough to read inside the tab.
• Checkout v2 keeps the fixed mobile dialog viewport-bound and scrolls the inner checkout shell so card fields, wallet controls, trust copy, and bottom actions remain reachable on short screens.
• Checkout v2 renders an editable email field when a funnel opens card checkout without a stored customer email, so direct preview paywall QA can complete Stripe confirmation instead of failing validation invisibly.
• The shared special-offer dialog can render a funnel-provided gift image while keeping the discount label overlaid and retaining the inline SVG fallback for funnels without a custom asset.
• the shared large-format Apple Pay and Google Pay subscribe CTAs, QR-code handoff link support, and the compact Visa / Mastercard / G Pay / Apple Pay image row used by the embedded checkout shell trust footer
• the Google Pay fallback CTA uses the downloaded Google Pay G mark paths, keeps at least 8px clear space, and matches Apple Pay's roughly 27px rendered subscribe text size until Stripe replaces it with the real wallet control

What Does Not Belong Here

• funnel routing
• funnel analytics
• 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
• manifest validation
• direct provider SDK calls inside funnel paywall steps; add provider adapters here first, then wire the funnel to the shared session or slot