@funnelsgrove/payments 0.1.46 → 0.1.47

package/README.md

@@ -2,70 +2,88 @@
 
 Shared billing and checkout helpers for funnels.
 
-Detailed implementation docs:
+Read this file before editing checkout code. Deeper 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
+## Owns provider-backed checkout primitives
 
-- 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.
+`@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.
 
-## Use This Package For
+## Current Checkout Path
 
-- 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
+Use these for new subscription paywalls:
+
+- `useStripeSubscriptionCheckoutSession`
+- `SharedStripeCheckoutV2Dialog`
+- `ApplePaySubscriptionCheckoutSlot`
+- `GooglePaySubscriptionCheckoutSlot`
+- `WalletSubscriptionCheckoutSlot`
+- `trackPaidStripeSubscriptionCheckoutCompleted`
+
+Use `chargeStripeOneClickPayment` for post-checkout one-click upsells when the shared client helper fits the funnel. The API endpoint is `/sdk/public/payments/one-click`.
+
+## Compatibility-Only Surfaces
 
-## Responsibilities
+Keep these exports available for saved drafts, old published artifacts, and controlled migrations. Do not use them for new subscription checkout work:
 
-- 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
+- `createStripePaymentIntent`
+- `SharedStripeCheckoutDialog`
+- `ApplePaySubscribeButton`
+- `GooglePaySubscribeButton`
+- `APPLE_PAY_QR_CODE_URL`
 
-## What Belongs Here
+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
-- 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.
-- `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.
-- 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
+- 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
-- 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
 - 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, and compatibility PaymentIntent 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 create checkout sessions until the visitor taps a visible checkout CTA.
+- 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
+
+```bash
+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.

package/dist/index.d.ts

@@ -13,13 +13,13 @@ export * from './providers/stripe/WalletSubscriptionCheckoutSlot.js';
 export * from './providers/stripe/ApplePaySubscriptionCheckoutSlot.js';
 export * from './providers/stripe/GooglePaySubscriptionCheckoutSlot.js';
 export { ManageSubscriptionScreen, type ManageSubscriptionContent, type ManageSubscriptionScreenProps, } from './components/ManageSubscriptionScreen.js';
-export * from './components/shared/SharedStripeCheckoutDialog.js';
 export * from './components/shared/SharedStripeCheckoutV2Dialog.js';
-export * from './components/shared/ApplePaySubscribeButton.js';
-export * from './components/shared/GooglePaySubscribeButton.js';
-export * from './components/shared/StripeCheckoutExpressCheckoutButton.js';
-export * from './components/shared/StripeExpressCheckoutButton.js';
 export * from './components/shared/StripeExpressCheckoutElement.js';
 export * from './components/shared/StripePlanSelector.js';
 export * from './components/shared/walletPlatform.js';
+export * from './components/shared/StripeCheckoutExpressCheckoutButton.js';
+export * from './components/shared/StripeExpressCheckoutButton.js';
+export * from './components/shared/SharedStripeCheckoutDialog.js';
+export * from './components/shared/ApplePaySubscribeButton.js';
+export * from './components/shared/GooglePaySubscribeButton.js';
 export * from './testing/walletCheckoutSmoke.js';

package/dist/index.js

@@ -1,25 +1,31 @@
+// Billing contracts and plan resolution.
 export * from './config/billing.config.js';
 export * from './services/preview-frame.service.js';
 export * from './services/runtime-mode.service.js';
 export * from './services/planCatalog.service.js';
 export * from './services/runtimeBillingPlanCatalog.service.js';
 export * from './services/paywallOffer.service.js';
+// Stripe API clients and checkout completion handoff.
 export * from './services/stripe.service.js';
 export * from './services/checkoutCompletionAnalytics.service.js';
 export * from './hooks/useResolvedPaywallPlans.js';
+// Provider-neutral and Stripe subscription checkout primitives.
 export * from './providers/paymentProvider.types.js';
 export * from './providers/stripe/useStripeSubscriptionCheckoutSession.js';
 export * from './providers/stripe/WalletSubscriptionCheckoutSlot.js';
 export * from './providers/stripe/ApplePaySubscriptionCheckoutSlot.js';
 export * from './providers/stripe/GooglePaySubscriptionCheckoutSlot.js';
+// Shared checkout and subscription-management UI.
 export { ManageSubscriptionScreen, } from './components/ManageSubscriptionScreen.js';
-export * from './components/shared/SharedStripeCheckoutDialog.js';
 export * from './components/shared/SharedStripeCheckoutV2Dialog.js';
-export * from './components/shared/ApplePaySubscribeButton.js';
-export * from './components/shared/GooglePaySubscribeButton.js';
-export * from './components/shared/StripeCheckoutExpressCheckoutButton.js';
-export * from './components/shared/StripeExpressCheckoutButton.js';
 export * from './components/shared/StripeExpressCheckoutElement.js';
 export * from './components/shared/StripePlanSelector.js';
 export * from './components/shared/walletPlatform.js';
+export * from './components/shared/StripeCheckoutExpressCheckoutButton.js';
+export * from './components/shared/StripeExpressCheckoutButton.js';
+// Compatibility-only surfaces kept for saved drafts and published artifacts.
+export * from './components/shared/SharedStripeCheckoutDialog.js';
+export * from './components/shared/ApplePaySubscribeButton.js';
+export * from './components/shared/GooglePaySubscribeButton.js';
+// QA helpers.
 export * from './testing/walletCheckoutSmoke.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/payments",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",
@@ -27,8 +27,8 @@
     "test:run": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@funnelsgrove/analytics": "^0.1.15",
-    "@funnelsgrove/runtime": "^0.1.18",
+    "@funnelsgrove/analytics": "^0.1.28",
+    "@funnelsgrove/runtime": "^0.1.45",
     "@stripe/react-stripe-js": "^5.6.0",
     "@stripe/stripe-js": "^8.7.0",
     "react": "19.2.3",