@appfunnel-dev/sdk 2.0.0-canary.1 → 2.0.0-canary.11

package/dist/checkout-ClaO5IYV.d.ts

@@ -0,0 +1,333 @@
+import { ReactNode, ComponentType } from 'react';
+import { c as CheckoutProvider, b as CheckoutIntent, d as CheckoutSurface, U as UpsellKind, C as CheckoutError, a as CheckoutErrorCategory, f as SurfacePreference } from './capabilities-Dq22RCr_.js';
+
+/**
+ * v2 commerce primitives — the two intents from phase-3, made trivial.
+ *
+ *  - `<Checkout offering 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 offering>` — 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 offering 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 {
+    /** The offering SLOT the page named (`<Checkout offering="primary">`) — the display/analytics identity. Kept as the wire field `product` at the provider boundary. */
+    product: string;
+    /** The catalog charge KEY charged — the CHARGE identity, resolved from `product` by {@link driverWithCatalog}. */
+    catalogKey?: 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 offering="…" 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 offering="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 offering slot (the author's bound selection). */
+    offering: string;
+    /**
+     * Presentation preference. A concrete {@link CheckoutSurface} pins it; `'auto'` lets the platform
+     * pick the best surface for the store's provider and the buyer's device — wallet-first on mobile
+     * (Stripe → ExpressCheckoutElement, Paddle → its Express Checkout variant), inline card/embedded
+     * on desktop (see {@link resolveSurface}). NOTE: `surface` has no default (kept required) so pinned
+     * funnels don't change behavior this canary; `'auto'` is opt-in. New authoring (editor + AI) should
+     * emit `surface="auto"` going forward so wallet-first is a funnel intent, not a provider prop.
+     */
+    surface: SurfacePreference;
+    /** 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 the RESOLVED `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.
+ *
+ * The `surface` prop is a {@link SurfacePreference}: a concrete surface (pinned) or `'auto'`, which
+ * {@link resolveSurface} maps to the best surface for the driver's provider + this device — ONCE per
+ * mount (frozen so the surface can't change mid-attempt and remount the provider element into a new
+ * charge). The resolved literal is what flows onto the wire; the server re-validates it.
+ */
+declare function Checkout({ offering, surface: surfacePreference, asChild, children, className, ...options }: CheckoutProps): ReactNode;
+interface UpsellProps extends Omit<UseCheckoutOptions, 'intent'> {
+    offering: 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({ offering, 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 };

package/dist/checkout-DBp4bCpC.d.cts

@@ -0,0 +1,333 @@
+import { ReactNode, ComponentType } from 'react';
+import { c as CheckoutProvider, b as CheckoutIntent, d as CheckoutSurface, U as UpsellKind, C as CheckoutError, a as CheckoutErrorCategory, f as SurfacePreference } from './capabilities-Dq22RCr_.cjs';
+
+/**
+ * v2 commerce primitives — the two intents from phase-3, made trivial.
+ *
+ *  - `<Checkout offering 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 offering>` — 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 offering 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 {
+    /** The offering SLOT the page named (`<Checkout offering="primary">`) — the display/analytics identity. Kept as the wire field `product` at the provider boundary. */
+    product: string;
+    /** The catalog charge KEY charged — the CHARGE identity, resolved from `product` by {@link driverWithCatalog}. */
+    catalogKey?: 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 offering="…" 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 offering="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 offering slot (the author's bound selection). */
+    offering: string;
+    /**
+     * Presentation preference. A concrete {@link CheckoutSurface} pins it; `'auto'` lets the platform
+     * pick the best surface for the store's provider and the buyer's device — wallet-first on mobile
+     * (Stripe → ExpressCheckoutElement, Paddle → its Express Checkout variant), inline card/embedded
+     * on desktop (see {@link resolveSurface}). NOTE: `surface` has no default (kept required) so pinned
+     * funnels don't change behavior this canary; `'auto'` is opt-in. New authoring (editor + AI) should
+     * emit `surface="auto"` going forward so wallet-first is a funnel intent, not a provider prop.
+     */
+    surface: SurfacePreference;
+    /** 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 the RESOLVED `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.
+ *
+ * The `surface` prop is a {@link SurfacePreference}: a concrete surface (pinned) or `'auto'`, which
+ * {@link resolveSurface} maps to the best surface for the driver's provider + this device — ONCE per
+ * mount (frozen so the surface can't change mid-attempt and remount the provider element into a new
+ * charge). The resolved literal is what flows onto the wire; the server re-validates it.
+ */
+declare function Checkout({ offering, surface: surfacePreference, asChild, children, className, ...options }: CheckoutProps): ReactNode;
+interface UpsellProps extends Omit<UseCheckoutOptions, 'intent'> {
+    offering: 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({ offering, 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 };