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

package/README.md

@@ -1,6 +1,6 @@
 # @appfunnel-dev/sdk
 
-Headless SDK for building AppFunnel pages with React. Write funnel pages as React components while the SDK handles payments, tracking, navigation, and variable state.
+Headless SDK for building Appfunnel pages with React. Write funnel pages as React components while the SDK handles payments, tracking, navigation, and variable state.
 
 ## Installation
 

package/dist/capabilities-Dq22RCr_.d.cts

@@ -0,0 +1,180 @@
+/**
+ * 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;
+    /**
+     * Per-surface DRIVER readiness. Absent = renderable now (the provider's driver mounts it).
+     * `'planned'` = the provider genuinely ships this surface (cite it in the profile) but OUR
+     * driver doesn't render it yet — publish validation FAILS CLOSED on it so we never promise a
+     * surface the runtime can't produce. Mirrors the provider-level {@link ProviderProfile.status}
+     * seam at surface granularity: implement the driver, drop the flag, and it flips on cleanly.
+     */
+    driver?: 'planned';
+}
+/**
+ * How a provider composes a TRIAL — the scattered provider `if`s made a matrix dimension
+ * (§7 item 4). Stripe trials are **composed** (a separate fee/vault step precedes the sub);
+ * Paddle trials are **native** (the price itself carries the trial, MoR collects up front):
+ *  - `paid_composed` — Stripe: trial-fee PaymentIntent → subscription with `trial_period_days`.
+ *  - `free_vault`    — Stripe: SetupIntent vaults the card (no charge) → trial subscription.
+ *  - `paid_native`   — Paddle: the price carries the paid trial; one item, collected up front.
+ *  - `free_native`   — Paddle: native free trial on the price.
+ * A provider with an EMPTY `trialShapes` can't run a trial offer (planned providers → fail closed).
+ */
+type TrialShape = 'paid_composed' | 'free_vault' | 'paid_native' | 'free_native';
+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';
+    /**
+     * TRIAL shapes this provider can run (§7 item 4). Empty = no trial path (fail closed at
+     * publish — a paid/free-trial funnel on this provider can't be produced yet).
+     */
+    trialShapes: TrialShape[];
+    /** 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;
+}
+/** Device class the surface resolver picks against — mobile gets the wallet-first surface. */
+type DeviceClass = 'mobile' | 'desktop';
+/**
+ * What an author writes on `<Checkout surface>`: either a concrete {@link CheckoutSurface} (pinned,
+ * validated as today) or `'auto'` — a declarative "give me the best surface for this store's
+ * provider and this device". The platform resolves `'auto'` to a concrete surface via
+ * {@link resolveSurface}; `'auto'` never crosses the checkout wire (the client resolves first, the
+ * server re-validates the concrete surface through {@link validateCheckout}).
+ */
+type SurfacePreference = 'auto' | CheckoutSurface;
+/** A surface the provider offers, can take a purchase on, AND our driver renders now (not `'planned'`). */
+declare function isRenderableSurface(provider: CheckoutProvider, surface: CheckoutSurface): boolean;
+/** The provider's renderable purchase surfaces (drives the `'auto'` fallbacks + the publish gate). */
+declare function renderableSurfaces(provider: CheckoutProvider): CheckoutSurface[];
+/**
+ * Resolve a {@link SurfacePreference} to the concrete surface the runtime will actually mount, for a
+ * given provider and device class (§7 item 3). PURE — the client resolves once per mount and puts the
+ * result on the wire (the wire stays surface-literal; the server re-validates via {@link
+ * validateCheckout}), and the publish gate resolves it the same way. Deterministic:
+ *
+ *  - an EXPLICIT surface resolves to ITSELF — the author's pin is never silently rewritten (an
+ *    unsupported pin, e.g. `express` on a provider that can't render it, is caught by
+ *    `validateCheckout` at publish, exactly as today);
+ *  - `'auto'` → mobile picks the provider's best wallet-first RENDERABLE surface (express where the
+ *    driver ships it, else the best inline/embedded frame); desktop picks the inline card
+ *    field/embedded frame. Only driver-ready surfaces are considered, so the result always renders.
+ *
+ * Totality guard: a provider with NO driver-ready surface (every surface `'planned'`, or unknown
+ * provider) falls back to its first declared surface (unknown → a nominal default) so the function is
+ * total; downstream `validateCheckout`/flow-select then fail that closed. In practice `'auto'` is only
+ * authored on a funnel's ONE resolved (full-status) provider, which always has a renderable surface.
+ */
+declare function resolveSurface(provider: CheckoutProvider, preference: SurfacePreference, deviceClass: DeviceClass): CheckoutSurface;
+/** 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;
+/** Trial shapes a provider can compose (empty = it can't run a trial offer yet). */
+declare function trialShapesFor(provider: CheckoutProvider): TrialShape[];
+/**
+ * Validate that a provider can run a TRIAL (§7 item 4). Pass a specific {@link TrialShape} to
+ * check that exact shape; omit it to assert the provider supports *any* trial (the cheap gate
+ * check when only the offering's TRIAL-role binding existence is known). A provider with no
+ * trial shapes (every planned provider) fails closed.
+ */
+declare function validateTrial(provider: CheckoutProvider, shape?: TrialShape): 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, type DeviceClass as D, INLINE_SURFACES as I, type OffSessionReliability as O, PROVIDER_PROFILES as P, type SurfaceCapability as S, type TrialShape as T, 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, type SurfacePreference as f, checkoutError as g, isMerchantOfRecord as h, isInlineSurface as i, isOrchestrator as j, isRenderableSurface as k, resolveSurface as l, validateUpsell as m, validateTrial as n, renderableSurfaces as r, surfacesFor as s, trialShapesFor as t, validateCheckout as v };

package/dist/capabilities-Dq22RCr_.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 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;
+    /**
+     * Per-surface DRIVER readiness. Absent = renderable now (the provider's driver mounts it).
+     * `'planned'` = the provider genuinely ships this surface (cite it in the profile) but OUR
+     * driver doesn't render it yet — publish validation FAILS CLOSED on it so we never promise a
+     * surface the runtime can't produce. Mirrors the provider-level {@link ProviderProfile.status}
+     * seam at surface granularity: implement the driver, drop the flag, and it flips on cleanly.
+     */
+    driver?: 'planned';
+}
+/**
+ * How a provider composes a TRIAL — the scattered provider `if`s made a matrix dimension
+ * (§7 item 4). Stripe trials are **composed** (a separate fee/vault step precedes the sub);
+ * Paddle trials are **native** (the price itself carries the trial, MoR collects up front):
+ *  - `paid_composed` — Stripe: trial-fee PaymentIntent → subscription with `trial_period_days`.
+ *  - `free_vault`    — Stripe: SetupIntent vaults the card (no charge) → trial subscription.
+ *  - `paid_native`   — Paddle: the price carries the paid trial; one item, collected up front.
+ *  - `free_native`   — Paddle: native free trial on the price.
+ * A provider with an EMPTY `trialShapes` can't run a trial offer (planned providers → fail closed).
+ */
+type TrialShape = 'paid_composed' | 'free_vault' | 'paid_native' | 'free_native';
+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';
+    /**
+     * TRIAL shapes this provider can run (§7 item 4). Empty = no trial path (fail closed at
+     * publish — a paid/free-trial funnel on this provider can't be produced yet).
+     */
+    trialShapes: TrialShape[];
+    /** 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;
+}
+/** Device class the surface resolver picks against — mobile gets the wallet-first surface. */
+type DeviceClass = 'mobile' | 'desktop';
+/**
+ * What an author writes on `<Checkout surface>`: either a concrete {@link CheckoutSurface} (pinned,
+ * validated as today) or `'auto'` — a declarative "give me the best surface for this store's
+ * provider and this device". The platform resolves `'auto'` to a concrete surface via
+ * {@link resolveSurface}; `'auto'` never crosses the checkout wire (the client resolves first, the
+ * server re-validates the concrete surface through {@link validateCheckout}).
+ */
+type SurfacePreference = 'auto' | CheckoutSurface;
+/** A surface the provider offers, can take a purchase on, AND our driver renders now (not `'planned'`). */
+declare function isRenderableSurface(provider: CheckoutProvider, surface: CheckoutSurface): boolean;
+/** The provider's renderable purchase surfaces (drives the `'auto'` fallbacks + the publish gate). */
+declare function renderableSurfaces(provider: CheckoutProvider): CheckoutSurface[];
+/**
+ * Resolve a {@link SurfacePreference} to the concrete surface the runtime will actually mount, for a
+ * given provider and device class (§7 item 3). PURE — the client resolves once per mount and puts the
+ * result on the wire (the wire stays surface-literal; the server re-validates via {@link
+ * validateCheckout}), and the publish gate resolves it the same way. Deterministic:
+ *
+ *  - an EXPLICIT surface resolves to ITSELF — the author's pin is never silently rewritten (an
+ *    unsupported pin, e.g. `express` on a provider that can't render it, is caught by
+ *    `validateCheckout` at publish, exactly as today);
+ *  - `'auto'` → mobile picks the provider's best wallet-first RENDERABLE surface (express where the
+ *    driver ships it, else the best inline/embedded frame); desktop picks the inline card
+ *    field/embedded frame. Only driver-ready surfaces are considered, so the result always renders.
+ *
+ * Totality guard: a provider with NO driver-ready surface (every surface `'planned'`, or unknown
+ * provider) falls back to its first declared surface (unknown → a nominal default) so the function is
+ * total; downstream `validateCheckout`/flow-select then fail that closed. In practice `'auto'` is only
+ * authored on a funnel's ONE resolved (full-status) provider, which always has a renderable surface.
+ */
+declare function resolveSurface(provider: CheckoutProvider, preference: SurfacePreference, deviceClass: DeviceClass): CheckoutSurface;
+/** 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;
+/** Trial shapes a provider can compose (empty = it can't run a trial offer yet). */
+declare function trialShapesFor(provider: CheckoutProvider): TrialShape[];
+/**
+ * Validate that a provider can run a TRIAL (§7 item 4). Pass a specific {@link TrialShape} to
+ * check that exact shape; omit it to assert the provider supports *any* trial (the cheap gate
+ * check when only the offering's TRIAL-role binding existence is known). A provider with no
+ * trial shapes (every planned provider) fails closed.
+ */
+declare function validateTrial(provider: CheckoutProvider, shape?: TrialShape): 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, type DeviceClass as D, INLINE_SURFACES as I, type OffSessionReliability as O, PROVIDER_PROFILES as P, type SurfaceCapability as S, type TrialShape as T, 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, type SurfacePreference as f, checkoutError as g, isMerchantOfRecord as h, isInlineSurface as i, isOrchestrator as j, isRenderableSurface as k, resolveSurface as l, validateUpsell as m, validateTrial as n, renderableSurfaces as r, surfacesFor as s, trialShapesFor as t, validateCheckout as v };