@appfunnel-dev/sdk 2.0.0-canary.0 → 2.0.0-canary.2

package/dist/capabilities-7_hy5f5G.d.cts

@@ -0,0 +1,114 @@
+/**
+ * The provider capability matrix + checkout error taxonomy — the PURE half of the
+ * checkout seam, extracted from checkout.tsx so it ships through the **manifest
+ * entry** (no React): the API's publish validation, the editor, AI authoring, and
+ * local dev all run the SAME checks the runtime primitives use (phase-3 §3.1b —
+ * "the SDK ships this as data"). The React half (driver seam, `useCheckout`,
+ * `<Checkout>`/`<Upsell>`) stays in ./checkout, which re-exports everything here.
+ */
+type CheckoutSurface = 'express' | 'element' | 'embedded' | 'sheet' | 'popup' | 'redirect';
+type CheckoutProvider = 'stripe' | 'paddle' | 'whop' | 'primer' | 'solidgate';
+type CheckoutIntent = 'purchase' | 'upsell';
+/** Surfaces that render inline (vs. those that open on click). */
+declare const INLINE_SURFACES: ReadonlySet<CheckoutSurface>;
+declare function isInlineSurface(surface: CheckoutSurface): boolean;
+/**
+ * The kind of off-session upsell (researched against Funnelfox's changelog, which
+ * ships these as distinct features). The discriminating real-world constraint is
+ * **stacking a 2nd concurrent subscription** — Paddle can't, SolidGate/Stripe can.
+ */
+type UpsellKind = 'subscription' | 'one-time' | 'upgrade';
+/** Reliability of an off-session upsell charge AFTER a purchase on a surface. */
+type OffSessionReliability = 'reliable' | 'conditional' | 'none';
+interface SurfaceCapability {
+    purchase: boolean;
+    /** Apple/Google Pay available on this surface. */
+    wallets: boolean;
+    /** Reliability of an off-session upsell after a purchase on this surface. */
+    offSession: OffSessionReliability;
+}
+interface ProviderProfile {
+    /** Merchant-of-Record (handles tax/compliance) vs. a PSP you settle through. */
+    isMoR: boolean;
+    /** Upsell kinds this provider can charge off-session (one-click, no re-entry). */
+    offSessionUpsells: UpsellKind[];
+    /** Who charges the saved method off-session: you (PSP) or the provider (MoR/managed). */
+    tokenModel: 'merchant' | 'provider';
+    /** Routes across multiple processors (Primer; SolidGate also offers this) vs. a single acquirer. */
+    orchestrator: boolean;
+    /**
+     * Driver tier (Wave-4 decision, Simon 2026-07-02): `full` = a real driver ships
+     * (Stripe, Paddle); `planned` = profile only — authoring/publish validate against
+     * it, but no charge path exists yet (Whop, Primer, SolidGate). A new provider
+     * becomes buildable by writing a driver; its profile already gates what authors
+     * can express, so funnels written today stay valid when the driver lands.
+     */
+    status: 'full' | 'planned';
+    /** Supported surfaces → per-surface capabilities. **Absent = not supported.** */
+    surfaces: Partial<Record<CheckoutSurface, SurfaceCapability>>;
+}
+/**
+ * Provider capabilities (researched 2026-06-23 against provider docs + Funnelfox;
+ * trial mechanics re-verified 2026-07-02, doc 09 §4.4).
+ *
+ * Three real-world corrections to the naive model:
+ *  1. **Off-session upsell support is per-provider by *kind*** (`offSessionUpsells`):
+ *     Paddle can't stack a 2nd concurrent subscription (upgrade + one-time only);
+ *     Stripe/SolidGate/Whop/Primer can do all kinds.
+ *  2. **Off-session *reliability* varies by the paywall surface** (`SurfaceCapability.
+ *     offSession`): Stripe **managed** checkout (`embedded`/`redirect`) upsells as a
+ *     direct charge against Stripe's vault → `conditional` (may decline); Elements
+ *     surfaces are `reliable`. Primer is `conditional` everywhere (PSP-dependent).
+ *  3. **Surface availability is a hard constraint.** MoR/managed providers can't
+ *     expose a raw card field to your own UI: Paddle has no `express`/`element`/your
+ *     `sheet`; Whop has no raw `element`/`express`; Primer has no hosted `redirect`;
+ *     Stripe/SolidGate have no `popup`. A missing entry means "not possible."
+ */
+declare const PROVIDER_PROFILES: Record<CheckoutProvider, ProviderProfile>;
+interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+    /** Non-fatal caveat (e.g. Paddle upgrade-only). */
+    note?: string;
+}
+/** Surfaces a provider supports, for the editor/AI to steer authors. */
+declare function surfacesFor(provider: CheckoutProvider): CheckoutSurface[];
+/** Whether a provider is a Merchant of Record (it owns tax/compliance). */
+declare function isMerchantOfRecord(provider: CheckoutProvider): boolean;
+/** Whether a provider routes across multiple processors (Primer, SolidGate). */
+declare function isOrchestrator(provider: CheckoutProvider): boolean;
+/**
+ * Validate a (provider, surface) for a **purchase**: the surface must exist for
+ * the provider and accept a payment. Surface availability is the real constraint
+ * (e.g. Paddle has no `element`).
+ */
+declare function validateCheckout(provider: CheckoutProvider, surface: CheckoutSurface): ValidationResult;
+/**
+ * Validate an **off-session upsell** of `kind` after a purchase made on
+ * `paywallSurface`. Combines provider support for the kind (Paddle can't stack a
+ * 2nd subscription) with the paywall surface's off-session reliability (Stripe
+ * managed checkout is `conditional` — returned as a `note`, not a hard block).
+ */
+declare function validateUpsell(provider: CheckoutProvider, paywallSurface: CheckoutSurface, kind?: UpsellKind): ValidationResult;
+/**
+ * Normalized failure category — the driver/platform maps each provider's decline
+ * codes into one of these so funnels can route/recover by reason. `authentication_
+ * required` (3DS/SCA) and `requires_payment_method` are the cases an **off-session**
+ * upsell can't satisfy → recover on-session (re-collect a card).
+ */
+type CheckoutErrorCategory = 'card_declined' | 'insufficient_funds' | 'expired_card' | 'prepaid_card' | 'authentication_required' | 'requires_payment_method' | 'processing_error' | 'canceled' | 'unknown';
+interface CheckoutError {
+    category: CheckoutErrorCategory;
+    message: string;
+    /** Raw provider decline code, if any (e.g. Stripe `card_declined`/`insufficient_funds`). */
+    declineCode?: string;
+    /** Whether re-attempting (e.g. an on-session re-collection) may succeed. */
+    retryable: boolean;
+}
+/** Build a {@link CheckoutError} (driver/test helper). */
+declare function checkoutError(category: CheckoutErrorCategory, message: string, extra?: {
+    declineCode?: string;
+    retryable?: boolean;
+}): CheckoutError;
+
+export { type CheckoutError as C, INLINE_SURFACES as I, type OffSessionReliability as O, PROVIDER_PROFILES as P, type SurfaceCapability as S, type UpsellKind as U, type ValidationResult as V, type CheckoutErrorCategory as a, type CheckoutIntent as b, type CheckoutProvider as c, type CheckoutSurface as d, type ProviderProfile as e, checkoutError as f, isMerchantOfRecord as g, isOrchestrator as h, isInlineSurface as i, validateUpsell as j, surfacesFor as s, validateCheckout as v };

package/dist/capabilities-7_hy5f5G.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The provider capability matrix + checkout error taxonomy — the PURE half of the
+ * checkout seam, extracted from checkout.tsx so it ships through the **manifest
+ * entry** (no React): the API's publish validation, the editor, AI authoring, and
+ * local dev all run the SAME checks the runtime primitives use (phase-3 §3.1b —
+ * "the SDK ships this as data"). The React half (driver seam, `useCheckout`,
+ * `<Checkout>`/`<Upsell>`) stays in ./checkout, which re-exports everything here.
+ */
+type CheckoutSurface = 'express' | 'element' | 'embedded' | 'sheet' | 'popup' | 'redirect';
+type CheckoutProvider = 'stripe' | 'paddle' | 'whop' | 'primer' | 'solidgate';
+type CheckoutIntent = 'purchase' | 'upsell';
+/** Surfaces that render inline (vs. those that open on click). */
+declare const INLINE_SURFACES: ReadonlySet<CheckoutSurface>;
+declare function isInlineSurface(surface: CheckoutSurface): boolean;
+/**
+ * The kind of off-session upsell (researched against Funnelfox's changelog, which
+ * ships these as distinct features). The discriminating real-world constraint is
+ * **stacking a 2nd concurrent subscription** — Paddle can't, SolidGate/Stripe can.
+ */
+type UpsellKind = 'subscription' | 'one-time' | 'upgrade';
+/** Reliability of an off-session upsell charge AFTER a purchase on a surface. */
+type OffSessionReliability = 'reliable' | 'conditional' | 'none';
+interface SurfaceCapability {
+    purchase: boolean;
+    /** Apple/Google Pay available on this surface. */
+    wallets: boolean;
+    /** Reliability of an off-session upsell after a purchase on this surface. */
+    offSession: OffSessionReliability;
+}
+interface ProviderProfile {
+    /** Merchant-of-Record (handles tax/compliance) vs. a PSP you settle through. */
+    isMoR: boolean;
+    /** Upsell kinds this provider can charge off-session (one-click, no re-entry). */
+    offSessionUpsells: UpsellKind[];
+    /** Who charges the saved method off-session: you (PSP) or the provider (MoR/managed). */
+    tokenModel: 'merchant' | 'provider';
+    /** Routes across multiple processors (Primer; SolidGate also offers this) vs. a single acquirer. */
+    orchestrator: boolean;
+    /**
+     * Driver tier (Wave-4 decision, Simon 2026-07-02): `full` = a real driver ships
+     * (Stripe, Paddle); `planned` = profile only — authoring/publish validate against
+     * it, but no charge path exists yet (Whop, Primer, SolidGate). A new provider
+     * becomes buildable by writing a driver; its profile already gates what authors
+     * can express, so funnels written today stay valid when the driver lands.
+     */
+    status: 'full' | 'planned';
+    /** Supported surfaces → per-surface capabilities. **Absent = not supported.** */
+    surfaces: Partial<Record<CheckoutSurface, SurfaceCapability>>;
+}
+/**
+ * Provider capabilities (researched 2026-06-23 against provider docs + Funnelfox;
+ * trial mechanics re-verified 2026-07-02, doc 09 §4.4).
+ *
+ * Three real-world corrections to the naive model:
+ *  1. **Off-session upsell support is per-provider by *kind*** (`offSessionUpsells`):
+ *     Paddle can't stack a 2nd concurrent subscription (upgrade + one-time only);
+ *     Stripe/SolidGate/Whop/Primer can do all kinds.
+ *  2. **Off-session *reliability* varies by the paywall surface** (`SurfaceCapability.
+ *     offSession`): Stripe **managed** checkout (`embedded`/`redirect`) upsells as a
+ *     direct charge against Stripe's vault → `conditional` (may decline); Elements
+ *     surfaces are `reliable`. Primer is `conditional` everywhere (PSP-dependent).
+ *  3. **Surface availability is a hard constraint.** MoR/managed providers can't
+ *     expose a raw card field to your own UI: Paddle has no `express`/`element`/your
+ *     `sheet`; Whop has no raw `element`/`express`; Primer has no hosted `redirect`;
+ *     Stripe/SolidGate have no `popup`. A missing entry means "not possible."
+ */
+declare const PROVIDER_PROFILES: Record<CheckoutProvider, ProviderProfile>;
+interface ValidationResult {
+    ok: boolean;
+    reason?: string;
+    /** Non-fatal caveat (e.g. Paddle upgrade-only). */
+    note?: string;
+}
+/** Surfaces a provider supports, for the editor/AI to steer authors. */
+declare function surfacesFor(provider: CheckoutProvider): CheckoutSurface[];
+/** Whether a provider is a Merchant of Record (it owns tax/compliance). */
+declare function isMerchantOfRecord(provider: CheckoutProvider): boolean;
+/** Whether a provider routes across multiple processors (Primer, SolidGate). */
+declare function isOrchestrator(provider: CheckoutProvider): boolean;
+/**
+ * Validate a (provider, surface) for a **purchase**: the surface must exist for
+ * the provider and accept a payment. Surface availability is the real constraint
+ * (e.g. Paddle has no `element`).
+ */
+declare function validateCheckout(provider: CheckoutProvider, surface: CheckoutSurface): ValidationResult;
+/**
+ * Validate an **off-session upsell** of `kind` after a purchase made on
+ * `paywallSurface`. Combines provider support for the kind (Paddle can't stack a
+ * 2nd subscription) with the paywall surface's off-session reliability (Stripe
+ * managed checkout is `conditional` — returned as a `note`, not a hard block).
+ */
+declare function validateUpsell(provider: CheckoutProvider, paywallSurface: CheckoutSurface, kind?: UpsellKind): ValidationResult;
+/**
+ * Normalized failure category — the driver/platform maps each provider's decline
+ * codes into one of these so funnels can route/recover by reason. `authentication_
+ * required` (3DS/SCA) and `requires_payment_method` are the cases an **off-session**
+ * upsell can't satisfy → recover on-session (re-collect a card).
+ */
+type CheckoutErrorCategory = 'card_declined' | 'insufficient_funds' | 'expired_card' | 'prepaid_card' | 'authentication_required' | 'requires_payment_method' | 'processing_error' | 'canceled' | 'unknown';
+interface CheckoutError {
+    category: CheckoutErrorCategory;
+    message: string;
+    /** Raw provider decline code, if any (e.g. Stripe `card_declined`/`insufficient_funds`). */
+    declineCode?: string;
+    /** Whether re-attempting (e.g. an on-session re-collection) may succeed. */
+    retryable: boolean;
+}
+/** Build a {@link CheckoutError} (driver/test helper). */
+declare function checkoutError(category: CheckoutErrorCategory, message: string, extra?: {
+    declineCode?: string;
+    retryable?: boolean;
+}): CheckoutError;
+
+export { type CheckoutError as C, INLINE_SURFACES as I, type OffSessionReliability as O, PROVIDER_PROFILES as P, type SurfaceCapability as S, type UpsellKind as U, type ValidationResult as V, type CheckoutErrorCategory as a, type CheckoutIntent as b, type CheckoutProvider as c, type CheckoutSurface as d, type ProviderProfile as e, checkoutError as f, isMerchantOfRecord as g, isOrchestrator as h, isInlineSurface as i, validateUpsell as j, surfacesFor as s, validateCheckout as v };

package/dist/checkout-CZmEvWfC.d.cts

@@ -0,0 +1,317 @@
+import { ReactNode, ComponentType } from 'react';
+import { c as CheckoutProvider, b as CheckoutIntent, d as CheckoutSurface, U as UpsellKind, C as CheckoutError, a as CheckoutErrorCategory } from './capabilities-7_hy5f5G.cjs';
+
+/**
+ * v2 commerce primitives — the two intents from phase-3, made trivial.
+ *
+ *  - `<Checkout product surface>` — the **purchase** primitive. The `surface`
+ *    prop picks presentation; some surfaces render **inline** (express wallets,
+ *    inline card, provider iframe), some **open on click** (sheet/popup/redirect).
+ *    `<Checkout>` covers both: it renders inline surfaces and renders a trigger
+ *    button for the rest (`asChild` to use your own button).
+ *  - `<Upsell product>` — the **upsell** primitive. Off-session charge to the
+ *    saved method, no card re-entry, one tap.
+ *  - `useCheckout()` — the headless hook under both, always available for a
+ *    fully-custom CTA.
+ *
+ * The SDK never talks to a provider. It owns the state machine + the analytics
+ * (`checkout.start` / `purchase.complete`) + post-charge navigation, and
+ * delegates the actual charge/render to an injected {@link CheckoutDriver}
+ * (the real one is platform-side; tests use {@link createMockDriver}).
+ *
+ * Which product is charged is the author's bound variable, captured at render
+ * (inline surfaces) or at `open()` time (trigger surfaces).
+ */
+
+type CheckoutStatus = 'idle' | 'loading' | 'requires_action' | 'success' | 'error';
+interface CheckoutRequest {
+    product: string;
+    intent: CheckoutIntent;
+    surface?: CheckoutSurface;
+    /** For `upsell` intent — which kind of off-session charge (default `subscription`). */
+    kind?: UpsellKind;
+    /**
+     * Buyer email at attempt time, read from the funnel's `user.email` namespace value
+     * (injected by `FunnelProvider` via {@link driverWithEmail} — no author wiring).
+     * Drivers forward it into the wire `CheckoutSessionRequest.email` (Stripe Customer
+     * creation / receipts / Paddle prefill).
+     */
+    email?: string;
+}
+interface CheckoutResult {
+    ok: boolean;
+    error?: CheckoutError;
+    /** Charged amount in minor units (for the purchase event). */
+    amountMinor?: number;
+    currency?: string;
+    /**
+     * The **server-minted** dedup id for the purchase event — the platform creates it
+     * when the charge settles and fires CAPI with it; the SDK emits `purchase.complete`
+     * with the same id so the browser pixel dedupes against the server. (Server is the
+     * source of truth for payment events; the SDK doesn't mint these.)
+     */
+    eventId?: string;
+}
+interface CheckoutCallbacks {
+    onSuccess: (result: CheckoutResult) => void;
+    onError: (error: CheckoutError) => void;
+    /**
+     * The buyer SUBMITTED an inline surface (Stripe confirm click / wallet
+     * authorization; Paddle inline checkout opening). This is when `checkout.start`
+     * fires and the status machine enters `loading` for inline attempts — trigger
+     * surfaces fire it at click time instead. It also marks fresh user intent, so
+     * the once-per-chain recovery guard resets. Optional: drivers that can't
+     * observe submit simply never call it, and the SHEET host deliberately doesn't
+     * forward it (the sheet's own open already began the attempt — re-firing would
+     * double-count starts and un-arm the recovery guard mid-chain).
+     */
+    onStart?: () => void;
+    /**
+     * The inline surface reports a valid payment method was entered (e.g. Stripe's
+     * Payment Element became `complete`), before the charge. Drives the
+     * `checkout.payment_added` analytics step; optional — drivers that can't observe
+     * it (or off-session charges) simply never call it.
+     */
+    onPaymentAdded?: () => void;
+}
+/**
+ * What a driver factory (`stripeCheckoutDriver` et al. from the
+ * `@appfunnel-dev/sdk/driver-*` entries) receives to construct a
+ * {@link CheckoutDriver}. Derived by `createFunnelTree` from the SAME
+ * renderer-injected mount data the platform tracker uses (tracking config +
+ * identity), so checkout wire calls land on the exact campaign/funnel/session
+ * the analytics do — there is no second config channel to drift.
+ *
+ * Serializable on purpose, and factories must be **construction-safe on the
+ * server too**: a factory only closes over this ctx (no provider SDK, no
+ * `window`) — all provider work belongs in effects/event handlers, so SSR can
+ * render the driver's stable inline placeholder and hydration matches.
+ */
+interface CheckoutDriverContext {
+    /** Public API origin, e.g. `https://api.appfunnel.net` (no trailing slash). */
+    apiBase: string;
+    /** Campaign DB id (the checkout route key, same as the ingestion route key). */
+    campaignId: string;
+    /** WebFunnel DB id (NOT the funnel.ts config id). */
+    funnelId: string;
+    /** Render-time mode — the server resolves the product binding + store credentials by it. */
+    mode: 'test' | 'live';
+    /** Funnel session id when one exists (analytics + customer continuity). */
+    sessionId?: string | null;
+    /** Signed-cookie-verified bare visitor id, when known. */
+    visitorId?: string | null;
+}
+/**
+ * The provider seam. The platform injects the real one (Stripe/Paddle/Whop/…);
+ * tests use {@link createMockDriver}.
+ *
+ * Most providers ship their **own React SDK** (`@stripe/react-stripe-js`,
+ * `@paddle/paddle-js`, Primer's React components, …). A driver's `renderInline`
+ * returns exactly that: the provider's React element mounted in our chrome (inline,
+ * or inside the `<Sheet>`). Those provider SDKs live in the **driver/platform**
+ * package, not our core funnel SDK — which is why the driver is injected: the core
+ * stays lean and provider-agnostic, and you only pull the SDK for the provider you use.
+ */
+interface CheckoutDriver {
+    provider: CheckoutProvider;
+    /** Trigger a charge (trigger surfaces + programmatic). Resolves when settled. */
+    start(req: CheckoutRequest): Promise<CheckoutResult>;
+    /** Render an inline surface (e.g. the provider's React payment element); report via callbacks. */
+    renderInline?(req: CheckoutRequest, cb: CheckoutCallbacks): ReactNode;
+    /**
+     * Verify an EXISTING attempt with the server (`POST /complete`, bounded re-poll on
+     * `pending`) — the redirect-return resume leg: hosted-checkout success URLs carry
+     * `?af_checkout={correlationId}` back into the funnel, and {@link CheckoutResume}
+     * hands the id here so the settlement (server-verified) resolves into the normal
+     * success/failure paths. Never charges; only verifies.
+     */
+    resume?(correlationId: string): Promise<CheckoutResult>;
+}
+interface MockDriverOptions {
+    /** The result a successful charge resolves with. */
+    result?: CheckoutResult;
+    /** Make **off-session** charges (no surface) fail — to exercise the upsell fallback. */
+    failOffSession?: CheckoutError | boolean;
+}
+/** A console/no-op driver — tests, preview, local dev. Succeeds unless configured to fail. */
+declare function createMockDriver(provider?: CheckoutProvider, options?: MockDriverOptions): CheckoutDriver;
+/**
+ * Wrap a driver so every attempt carries the buyer email the funnel has collected
+ * (`user.email`), read at ATTEMPT time — `start()` for trigger surfaces, the
+ * `renderInline` request for mounted surfaces. Applied by `FunnelProvider` around
+ * the injected driver, so `useCheckout`, `<Checkout>` inline branches and the
+ * checkout sheet all forward it without wiring; drivers pass it into the wire's
+ * `CheckoutSessionRequest.email`. An explicit `req.email` always wins.
+ */
+declare function driverWithEmail(driver: CheckoutDriver, getEmail: () => string | undefined): CheckoutDriver;
+/** One declarative recovery route for a failure category. */
+type FailureRoute = {
+    go: string;
+} | {
+    modal: string | ComponentType<any>;
+} | {
+    fallback: CheckoutSurface;
+} | ((error: CheckoutError) => void);
+/**
+ * What a `{ modal }` failure route hands the modal — the error AND the actions,
+ * because registry modals mount outside the flow's nav context and a recovery
+ * modal that can't act is just an error toast. Type your modal with this:
+ *
+ * ```tsx
+ * const Declined = defineModal<FailureModalProps>(({ error, go, retry }) => (
+ *   <Sheet>
+ *     <p>{error.category === 'prepaid_card' ? 'Prepaid cards can't start a trial.' : 'Payment didn't go through.'}</p>
+ *     <button onClick={() => retry('sheet')}>Try another card</button>
+ *     <button onClick={() => go('downsell')}>See the lite plan</button>
+ *   </Sheet>
+ * ))
+ * ```
+ *
+ * A modal can also host a whole `<Checkout product="…" surface="element" />` for
+ * an inline downsell — the driver context is app-level, so checkout works inside
+ * modals as-is.
+ */
+interface FailureModalProps {
+    error: CheckoutError;
+    /** The product whose charge failed (absent only for product-less failures). */
+    product?: string;
+    /** Navigate the flow to a page key (modals can't call useNavigation themselves). */
+    go: (pageKey: string) => void;
+    /**
+     * Re-attempt the SAME product. `retry()` re-runs an upsell off-session; for a
+     * purchase (which needs UI to re-collect) it opens the payment sheet.
+     * `retry('sheet')` re-collects on the SDK sheet; an inline surface
+     * (`element`/`express`/`embedded`) is COERCED to the sheet when the provider
+     * supports it — a retry has no page slot to mount into, so the sheet hosts the
+     * element. On sheet-less MoR providers (Paddle) inline retries run through the
+     * driver, whose provider checkout opens its own overlay. `retry('popup')` /
+     * `retry('redirect')` hand off to the provider. A failed retry routes through
+     * `onFailed` again (the modal reopens) — the loop is user-driven, never
+     * automatic. Hide the modal first (`useModal().hide()`) when retrying into a
+     * surface that opens its own overlay.
+     */
+    retry: (surface?: CheckoutSurface) => void;
+}
+/**
+ * Declarative failure recovery — route each failure **category** to what happens
+ * next, instead of hand-wiring `onError`:
+ *
+ * ```tsx
+ * <Checkout product="monthly" surface="element" onFailed={{
+ *   prepaid_card: { go: 'real-card' },
+ *   insufficient_funds: { modal: DownsellModal },
+ *   default: { modal: TryAgainModal },
+ * }} />
+ * ```
+ *
+ * Resolution: exact category → `default` → nothing (the error state + `checkout.
+ * failed` event stand, as today). Two built-in judgments:
+ *  - `canceled` only routes when mapped EXPLICITLY — a deliberately dismissed
+ *    sheet/popup is not a failure to recover from, so `default` never catches it;
+ *  - a `{ fallback }` recovery runs at most once per attempt chain (its own
+ *    failure routes through the non-fallback routes), so declines can't loop.
+ *
+ * `checkout.failed` fires with category + declineCode on every failure regardless
+ * of routing — recovery pages are measurable, and being ordinary flow pages they
+ * are A/B-able with page experiments like anything else.
+ */
+type OnFailedMap = Partial<Record<CheckoutErrorCategory | 'default', FailureRoute>>;
+interface UseCheckoutOptions {
+    intent?: CheckoutIntent;
+    /** For `upsell` intent — which kind of off-session charge (default `subscription`). */
+    kind?: UpsellKind;
+    /** Advance to the next page after a successful charge (default: true). */
+    advanceOnSuccess?: boolean;
+    onSuccess?: (result: CheckoutResult) => void;
+    onError?: (error: CheckoutError) => void;
+    /** Declarative failure recovery — see {@link OnFailedMap}. Runs AFTER `onError`. */
+    onFailed?: OnFailedMap;
+    /**
+     * Try this surface ON-SESSION once on any first failure, before `onFailed`
+     * routing — the generalized `<Upsell fallback>`: the off-session (or first)
+     * charge fails, the surface re-collects a card, the retry's failure then goes
+     * through `onFailed`. Never re-triggered by its own failure; never triggered
+     * by a user-`canceled` checkout.
+     */
+    recoverySurface?: CheckoutSurface;
+}
+interface CheckoutHandle {
+    /** Start the charge for a product; resolves with the result (no surface = off-session). */
+    open: (product: string, surface?: CheckoutSurface) => Promise<CheckoutResult>;
+    status: CheckoutStatus;
+    /** The last failure, structured so you can route/recover by `category`. */
+    error: CheckoutError | null;
+    isLoading: boolean;
+    reset: () => void;
+    /** Build the callbacks an inline surface reports through (used by `<Checkout>`). */
+    callbacksFor: (product?: string, surface?: CheckoutSurface) => CheckoutCallbacks & {
+        onStart: () => void;
+    };
+}
+/**
+ * The headless checkout hook. Owns the state machine + analytics + post-charge
+ * navigation; delegates the charge to the injected {@link CheckoutDriver}.
+ */
+declare function useCheckout(opts?: UseCheckoutOptions): CheckoutHandle;
+interface CheckoutProps extends UseCheckoutOptions {
+    /** Logical product id (the author's bound selection). */
+    product: string;
+    surface: CheckoutSurface;
+    /** Render your own trigger element instead of the default button (trigger surfaces). */
+    asChild?: boolean;
+    /** Trigger label / your trigger element. */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The purchase primitive. Three presentation modes by `surface`:
+ *  - **inline** (`express`/`element`/`embedded`) — the driver renders the
+ *    provider UI in place (keyed by product so a selection change remounts it);
+ *  - **SDK sheet** (`sheet`) — a trigger opens the AppFunnel-owned {@link Sheet}
+ *    and the driver renders the provider element inside it;
+ *  - **provider-hosted** (`popup`/`redirect`) — a trigger hands off to the
+ *    provider's own overlay/page.
+ */
+declare function Checkout({ product, surface, asChild, children, className, ...options }: CheckoutProps): ReactNode;
+interface UpsellProps extends Omit<UseCheckoutOptions, 'intent'> {
+    product: string;
+    /**
+     * If the off-session charge fails, present this surface **on-session** to
+     * re-collect a card and charge again — e.g. `fallback="sheet"` opens the
+     * payment sheet, `fallback="popup"` the provider overlay. Omit to just report
+     * the failure (via `onError` / the `checkout.failed` event).
+     */
+    fallback?: CheckoutSurface;
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * The upsell primitive — an off-session, one-tap charge to the saved method (no
+ * surface, no card re-entry). On failure, optionally `fallback` to an on-session
+ * surface to re-collect and retry — `fallback` IS the hook's `recoverySurface`,
+ * so the retry's own failure routes through `onFailed` (e.g. prepaid_card → a
+ * recapture page) instead of dead-ending.
+ */
+declare function Upsell({ product, fallback, asChild, children, className, ...options }: UpsellProps): ReactNode;
+/**
+ * The dangling settle leg of the `redirect` surface. The server appends
+ * `af_checkout={correlationId}` to hosted-checkout success URLs; when the buyer
+ * lands back in the funnel this component detects the param, has the server
+ * VERIFY the attempt (`driver.resume` → `POST /complete`, bounded re-poll while
+ * `pending`), and resolves it into the normal machinery:
+ *
+ *  - `settled` → `purchase.complete` fires with the settlement's server-minted
+ *    `eventId` (pixel↔CAPI dedup), the flow advances, and the param is stripped
+ *    (`history.replaceState`) so a reload can't re-run the leg;
+ *  - `failed` → the normal failure path (`checkout.failed` + status `error`;
+ *    any `onFailed` maps passed as props apply — product-less, so only
+ *    `go`/handler routes can act).
+ *
+ * SSR-safe (effect-only) and runs once per correlationId per page load. Mounted
+ * automatically by `createFunnelTree` inside the nav context; needs a driver
+ * with `resume` (both platform drivers ship it; the mock resolves its result).
+ */
+declare function CheckoutResume(options?: UseCheckoutOptions): ReactNode;
+
+export { type CheckoutDriverContext as C, type FailureModalProps as F, type MockDriverOptions as M, type OnFailedMap as O, Upsell as U, type CheckoutDriver as a, Checkout as b, type CheckoutCallbacks as c, type CheckoutHandle as d, type CheckoutProps as e, type CheckoutRequest as f, type CheckoutResult as g, CheckoutResume as h, type CheckoutStatus as i, type FailureRoute as j, type UpsellProps as k, type UseCheckoutOptions as l, createMockDriver as m, driverWithEmail as n, useCheckout as u };