@appfunnel-dev/sdk 2.0.0-canary.5 → 2.0.0-canary.7

package/dist/{manifest-Dl7faaKe.d.cts → manifest-CMe8yVkr.d.cts}

@@ -140,16 +140,20 @@ interface SessionContext {
 }
 /**
  * Durable identity for **stable experiment bucketing** (phase-4 §4.2). The
- * preferred seed is `customerId` once known; before identification it's the
- * signed anonymous `visitorId` (P1). It is deliberately **not** the session id or
- * fingerprint — a returning visitor (e.g. via winback) must keep their variant
- * across sessions/devices (landmine #4). Both null = unidentifiable traffic, and
- * the experiment layer falls back to control rather than bucket on nothing.
+ * preferred seed is the signed anonymous `visitorId` (stable from the first
+ * pageload, matching the server-side FUNNEL split in resolve.ts); `customerId` is
+ * only the fallback for cookieless SDK embeds. visitorId-FIRST is deliberate — the
+ * anon customerId is minted server-side AFTER the first tracked event, so seeding
+ * on it would flip a returning visitor's arm between visit 1 and 2 (see
+ * {@link ../flow/experiments}.bucketingSeed). It is deliberately **not** the
+ * session id or fingerprint — a returning visitor (e.g. via winback) must keep
+ * their variant across sessions (landmine #4). Both null = unidentifiable traffic,
+ * and the experiment layer falls back to control rather than bucket on nothing.
  */
 interface IdentityContext {
-    /** Known customer id (post-identification). The preferred bucketing seed. */
+    /** Known customer id (post-identification). The fallback bucketing seed (cookieless embeds). */
     customerId: string | null;
-    /** Signed anonymous visitor id. The fallback bucketing seed. */
+    /** Signed anonymous visitor id. The preferred bucketing seed (stable from visit 1). */
     visitorId: string | null;
 }
 interface SystemContext {
@@ -203,14 +207,14 @@ declare function buildContext(opts?: BuildContextOptions): FunnelContext;
 /**
  * Pure catalog math — no React, no I/O. Split out of {@link ./catalog} so the
  * server/tooling entry (`@appfunnel-dev/sdk/manifest`) can compile/resolve
- * products without pulling react-dom or any component code into its graph.
+ * offerings without pulling react-dom or any component code into its graph.
  * {@link ./catalog} re-exports everything here and adds the React wiring.
  */
 type Interval = 'day' | 'week' | 'month' | 'year' | 'one_time';
-/** What the platform hands the funnel per product (a single provider-resolved price). */
-interface ProductInput {
+/** What the platform hands the funnel per offering (a single provider-resolved price). */
+interface OfferingInput {
     id: string;
-    /** The catalog product KEY this input charges (the slot's assignment). Defaults to `id` (legacy/identity slots). */
+    /** The catalog charge KEY this input charges (the slot's assignment). Defaults to `id` (legacy/identity slots). */
     catalogKey?: string;
     name?: string;
     displayName?: string;
@@ -237,12 +241,12 @@ interface Money {
     formatted: string;
 }
 /**
- * The product with its amounts resolved (currency + period math), **before**
- * locale formatting — what the catalog stores. `useProduct` formats it.
+ * The offering with its amounts resolved (currency + period math), **before**
+ * locale formatting — what the catalog stores. `useOffering` formats it.
  */
-interface ResolvedProduct {
+interface ResolvedOffering {
     id: string;
-    /** The catalog product KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
+    /** The catalog charge KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
     catalogKey: string;
     name: string;
     displayName: string;
@@ -259,10 +263,10 @@ interface ResolvedProduct {
     trialDays: number;
     trialMinor: number;
 }
-/** Display-ready product the author reads (every amount locale-formatted). */
-interface Product {
+/** Display-ready offering the author reads (every amount locale-formatted). */
+interface Offering {
     id: string;
-    /** The catalog product KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
+    /** The catalog charge KEY charged (the CHARGE identity; `id` is the SLOT/display identity). */
     catalogKey: string;
     name: string;
     displayName: string;
@@ -282,13 +286,13 @@ interface Product {
     trialPrice: Money | null;
 }
 /**
- * Resolve a {@link ProductInput} into amounts + period math (no formatting yet).
+ * Resolve an {@link OfferingInput} into amounts + period math (no formatting yet).
  * Per-period amounts are **integer minor units** (each derived from the exact
  * daily rate, then rounded — never round-then-multiply, so error doesn't compound).
  */
-declare function resolveProduct(input: ProductInput): ResolvedProduct;
-/** Build the id → {@link ResolvedProduct} catalog. Formatting happens at read time. */
-declare function buildCatalog(inputs: ProductInput[]): Map<string, ResolvedProduct>;
+declare function resolveOffering(input: OfferingInput): ResolvedOffering;
+/** Build the id → {@link ResolvedOffering} catalog. Formatting happens at read time. */
+declare function buildCatalog(inputs: OfferingInput[]): Map<string, ResolvedOffering>;
 /**
  * The minor-unit exponent for a currency (`USD`→2, `JPY`→0, `KWD`/`BHD`→3),
  * derived from `Intl.NumberFormat(...).resolvedOptions().maximumFractionDigits`
@@ -297,8 +301,8 @@ declare function buildCatalog(inputs: ProductInput[]): Map<string, ResolvedProdu
 declare function currencyExponent(currency: string): number;
 /** Format minor units of `currency` in `locale` (exponent-aware: 7900 JPY = ¥7,900). */
 declare function formatMoney(minor: number, currency: string, locale: string): Money;
-/** Format a {@link ResolvedProduct} into a display {@link Product} in `locale`. */
-declare function formatProduct(r: ResolvedProduct, locale: string): Product;
+/** Format a {@link ResolvedOffering} into a display {@link Offering} in `locale`. */
+declare function formatOffering(r: ResolvedOffering, locale: string): Offering;
 
 /**
  * The funnel **spine** — the constrained, declarative configuration authored as
@@ -372,6 +376,13 @@ interface PageMeta {
     /**
      * Ordered routing edges out of this page (first match wins). Each has a static
      * `to` key + an optional `when` gate. Omit for the default linear flow.
+     *
+     * OPTIONAL per-variant routing: a `@variant` page (`paywall@b`) MAY carry its own
+     * `next`. When that variant is the one served for its slot, its `next` governs
+     * routing for that visitor; absent, the variant inherits the slot's routing (the
+     * default — a pure superset, no behavior change for existing funnels). Assignment,
+     * exposure, and progress still anchor on the slot; only the next-page lookup
+     * consults the served variant's routes. See {@link FunnelPage}.
      */
     next?: Route[];
     /**
@@ -425,6 +436,15 @@ interface FlowPage {
  * AUTHORED shape (funnel.ts owns the page list, order, and routing); the build generates
  * the code-split `mount.tsx` from it. Routing (`next`) must stay DECLARATIVE (Route[] with
  * `{ to, when }` conditions, no predicate functions) so the web builder UI can edit it.
+ *
+ * OPTIONAL variant routing (default off): a served variant's OWN routing is authored by
+ * declaring the variant here with its `@` key and a `next`, e.g.
+ * `{ key: 'paywall@b', next: [{ to: 'special-offer' }] }`. A variant declared this way keys
+ * on the `@` marker, so it still collapses out of the linear flow (it is NOT a linear step);
+ * its `next` is consulted only when that variant is the one served for its slot. Omit the
+ * declaration (leave the variant an undeclared `pages/<slot>@<v>.tsx` file) to inherit the
+ * slot's routing — the existing behavior, unchanged. The slot's control keeps owning
+ * assignment/exposure/progress; only the next-page lookup for a branched variant differs.
  */
 interface FunnelPage extends PageMeta {
     key: string;
@@ -483,19 +503,19 @@ interface FunnelDefinition {
     /** `data.*` working/scratch variables (default values). */
     data?: Record<string, VariableConfig>;
     /**
-     * The catalog products this funnel sells, as SLOTS: a local, stable key each PAGE
-     * references (`useProduct('primary')`, `<Checkout product="primary">`) → the catalog product
+     * The catalog offerings this funnel sells, as SLOTS: a local, stable key each PAGE
+     * references (`useOffering('primary')`, `<Checkout offering="primary">`) → the catalog charge
      * KEY it's assigned to. Swap the assignment to change the offer WITHOUT touching page code;
      * `null` = a declared-but-unassigned slot. A bare `string[]` is legacy sugar for IDENTITY
      * slots (`['pro'] ≡ { pro: 'pro' }`) — every existing funnel keeps working. Prices resolve
      * from the project catalog per environment (Live/Test) at render.
      */
-    products?: string[] | Record<string, string | null>;
+    offerings?: string[] | Record<string, string | null>;
     locales?: FunnelLocales;
     /**
      * When `true`, the funnel shows the **geo-specific** currency/price the payment
      * provider resolves (Stripe `currency_options`, Paddle preview, Whop, SolidGate,
-     * …). When `false` (default), a single fixed currency is used. AppFunnel does no
+     * …). When `false` (default), a single fixed currency is used. Appfunnel does no
      * FX — this only toggles whether the platform asks the provider for the geo
      * price; the SDK just displays whatever resolved `{amount, currency}` it's handed.
      * (See docs/platform-v2 phase-3 §3.6.)
@@ -504,19 +524,19 @@ interface FunnelDefinition {
 }
 /** Identity helper for a funnel definition. */
 declare function defineFunnel(def: FunnelDefinition): FunnelDefinition;
-/** A funnel product SLOT: the local key pages reference → the assigned catalog product key (null = unassigned). */
-interface ProductSlot {
+/** A funnel offering SLOT: the local key pages reference → the assigned catalog charge key (null = unassigned). */
+interface OfferingSlot {
     slot: string;
     catalogKey: string | null;
 }
 /**
- * Normalize `FunnelDefinition.products` to a slot list. A legacy `string[]` becomes IDENTITY
+ * Normalize `FunnelDefinition.offerings` to a slot list. A legacy `string[]` becomes IDENTITY
  * slots (`['pro'] → [{ slot:'pro', catalogKey:'pro' }]`); a `{ slot: key|null }` map becomes its
- * entries (insertion order preserved, so `useProducts()` is deterministic).
+ * entries (insertion order preserved, so `useOfferings()` is deterministic).
  */
-declare function normalizeProducts(products: FunnelDefinition['products']): ProductSlot[];
+declare function normalizeOfferings(offerings: FunnelDefinition['offerings']): OfferingSlot[];
 /** The unique, ASSIGNED catalog keys a funnel charges — for the promote gate + catalog reverse-lookup. */
-declare function funnelCatalogKeys(products: FunnelDefinition['products']): string[];
+declare function funnelCatalogKeys(offerings: FunnelDefinition['offerings']): string[];
 
 /**
  * Pure locale resolution — no React. Split out of {@link ./translation} so the
@@ -610,8 +630,8 @@ declare function parseSlotKey(key: string): {
 };
 /** True if a page key is an off-flow variant (`welcome@b`), by the source-side `@` marker. */
 declare function isVariantKey(key: string): boolean;
-/** One arm of an experiment: which page renders, at what weight. */
-interface ExperimentVariant {
+/** One arm of a running experiment: which page renders, at what weight. */
+interface ExperimentArm {
     /** The page key this arm renders (the slot's control, or a `@variant` sibling). */
     page: string;
     /** Relative weight in the split (need not sum to 100; zero = paused arm). */
@@ -619,19 +639,24 @@ interface ExperimentVariant {
 }
 /**
  * A runtime experiment record — the operational wiring the **platform** owns and
- * hands to the SDK (not authored in the funnel source). The variant *pages* are
- * code in the bundle; this is the live config over them.
+ * hands to the SDK (not authored in the funnel source). Projected from the unified
+ * `Experiment`/`ExperimentArm` graph (a RUNNING PAGE experiment + its arms): the
+ * experiment's `slot` names the base page, and each arm becomes a `variants` entry
+ * `{ page: arm.pageKey, weight: arm.weight }` keyed by `arm.label`. The variant
+ * *pages* are code in the LIVE build; this is the live split over them.
+ *
+ * The serve join only ever hands over RUNNING experiments, and the server's
+ * draft-write + serve guards make every active arm's page GUARANTEED present in the
+ * LIVE build (an experiment owns its arm pages' lifecycle — you end the experiment to
+ * remove a page, you can't drift it away). So there is no lifecycle/winner state and
+ * no "arm page missing" case to resolve here.
  */
 interface RuntimeExperiment {
     id: string;
-    /** The page key holding the flow position (the anchor / control). */
+    /** The page key holding the flow position (the anchor / the control arm's base page). */
     slot: string;
-    /** label → arm. One arm's `page` is the `slot` (control); others are `@variant` siblings. */
-    variants: Record<string, ExperimentVariant>;
-    /** Lifecycle. Absent = running. */
-    status?: 'running' | 'paused' | 'stopped';
-    /** When stopped, the variant label everyone sees until promotion bakes it into the slot. */
-    winner?: string;
+    /** label → arm. The control arm's `page` is the `slot`; others are `@variant` siblings. */
+    variants: Record<string, ExperimentArm>;
     /** Primary metric (analytics only; not used for resolution). */
     metric?: string;
     /** Platform record version (immutable-while-running; reweight = new version). Rides on
@@ -661,43 +686,20 @@ declare function weightsOf(variants: Record<string, {
     weight: number;
 }>): Record<string, number>;
 /**
- * Resolve which page version each experiment slot shows for this visitor, and
- * which page keys remain in the linear flow.
+ * Resolve which page version each experiment slot shows for this visitor, and which
+ * page keys remain in the linear flow.
  *
- * Variant pages are detected structurally by the `@` in their key, so they
- * collapse out of the linear flow even for a slot with no active experiment.
- * For each *running* experiment the visitor is bucketed (stable on `seed`); a
- * *stopped* one serves its `winner`; a *paused* one (or no seed) serves the slot.
+ * Variant pages are detected structurally by the `@` in their key, so they collapse
+ * out of the linear flow even for a slot with no active experiment. Each served
+ * experiment is RUNNING with all its arm pages guaranteed present in the LIVE build
+ * (the server draft-write + serve guards enforce the experiment-owned lifecycle
+ * invariant), so the visitor is bucketed deterministically on `seed` and the assigned
+ * arm's page is swapped in with no presence check. With no `seed` there is nothing
+ * stable to bucket on, so every slot renders its own control page.
  */
 declare function resolveExperiments(pages: {
     key: string;
 }[], experiments: RuntimeExperiment[], seed: string | null): ExperimentResolution;
-/** One referential problem with an experiment record. */
-interface ExperimentIssue {
-    /** The offending experiment id (`'*'` for a cross-experiment issue). */
-    experimentId: string;
-    code: 'slot_missing' | 'slot_is_variant' | 'slot_conflict' | 'duplicate_id' | 'variant_page_missing' | 'variant_slot_mismatch' | 'no_control' | 'no_traffic' | 'negative_weight' | 'bad_winner' | 'single_arm' | 'orphan_variant';
-    message: string;
-}
-interface ExperimentValidation {
-    ok: boolean;
-    errors: ExperimentIssue[];
-    warnings: ExperimentIssue[];
-}
-/**
- * Cross-check experiment records against the funnel's pages — the publish-time /
- * experiment-edit gate that catches the dangling references the runtime can't see
- * (the experiment wiring lives in the DB; the pages live in the build, so they can
- * drift). Pure: hand it the runtime experiments + the funnel's page keys (e.g.
- * `manifest.pages`).
- *
- * Errors block; warnings inform. `orphan_variant` is a warning, not an error — a
- * `@variant` file with no running experiment is dead-but-harmless (a paused test, or
- * one not wired yet).
- */
-declare function validateExperiments(experiments: RuntimeExperiment[], pages: {
-    key: string;
-}[]): ExperimentValidation;
 
 /**
  * The **manifest** — the declarative IR a funnel project compiles to (doc 06).
@@ -773,6 +775,13 @@ interface ManifestEdge {
     kind: 'branch' | 'linear';
     /** Absent = unconditional (a fallback route, or the linear fall-through). */
     condition?: EdgeCondition;
+    /**
+     * True on a **variant-only branch**: an edge whose `from` is a `@variant` key,
+     * emitted when that served variant carries its OWN `meta.next` (optional divergent
+     * routing). Lets consumers (the editor's Flow canvas) tell a variant's private branch
+     * apart from a normal slot edge. Optional/absent on every non-variant edge.
+     */
+    variant?: true;
 }
 interface ManifestValidation {
     /**
@@ -810,9 +819,9 @@ interface ManifestValidation {
      * though every page can proceed. Hard error.
      */
     noReachableFinish: boolean;
-    /** Slot names a PAGE references (`useProduct`/`<Checkout product>`) that the funnel doesn't declare — hard error. */
-    unknownProductRefs: string[];
-    /** Declared slots a page references but which have no catalog product assigned (map value `null`) — hard error. */
+    /** Slot names a PAGE references (`useOffering`/`<Checkout offering>`) that the funnel doesn't declare — hard error. */
+    unknownOfferingRefs: string[];
+    /** Declared slots a page references but which have no catalog charge key assigned (map value `null`) — hard error. */
     unassignedSlots: string[];
 }
 interface FunnelManifest {
@@ -824,11 +833,11 @@ interface FunnelManifest {
         edges: ManifestEdge[];
     };
     /** The unique, ASSIGNED catalog keys the funnel charges (for the promote gate + catalog reverse-lookup). */
-    products: string[];
-    /** Product SLOTS: slot → assigned catalog key|null. `products` above is the unique assigned keys. */
-    productSlots: ProductSlot[];
-    /** Slot names PAGES reference (from the build's scan); validated against `productSlots`. Absent = no scan ran. */
-    productRefs?: string[];
+    offerings: string[];
+    /** Offering SLOTS: slot → assigned catalog key|null. `offerings` above is the unique assigned keys. */
+    offeringSlots: OfferingSlot[];
+    /** Slot names PAGES reference (from the build's scan); validated against `offeringSlots`. Absent = no scan ran. */
+    offeringRefs?: string[];
     locales?: FunnelLocales;
     validation: ManifestValidation;
 }
@@ -839,10 +848,10 @@ interface CompileInput {
         key: string;
         meta?: PageMeta;
     }[];
-    /** Slot names the funnel's PAGES reference (from `scanProductRefs`) — cross-checked against the declared slots. */
-    productRefs?: string[];
+    /** Slot names the funnel's PAGES reference (from `scanOfferingRefs`) — cross-checked against the declared slots. */
+    offeringRefs?: string[];
 }
 /** Compile a funnel's spine into its declarative {@link FunnelManifest} IR. */
 declare function compileManifest(input: CompileInput): FunnelManifest;
 
-export { evaluateCondition as $, type Acquisition as A, type BrowserContext as B, type ClickIdContext as C, type Direction as D, type EdgeCondition as E, type FunnelContext as F, type Gate as G, type Route as H, type IdentityContext as I, type SystemContext as J, assignVariant as K, type LocaleContext as L, type ManifestEdge as M, bucketingSeed as N, type OsContext as O, type Product as P, buildAcquisition as Q, type RuntimeExperiment as R, type SessionContext as S, buildCatalog as T, type UtmContext as U, type VariableValue as V, compileManifest as W, currencyExponent as X, defineFunnel as Y, definePage as Z, entryGuard as _, type VariableConfig as a, evaluateGate as a0, expectedPathLength as a1, fnv1a as a2, formatMoney as a3, formatProduct as a4, hashToUnit as a5, isRtl as a6, isVariantKey as a7, nextPage as a8, outgoingKeys as a9, pageMeta as aa, parseSlotKey as ab, pickByWeight as ac, resolveExperiments as ad, resolveLocale as ae, resolveProduct as af, resolveRoute as ag, validateExperiments as ah, type FunnelPage as ai, type ProductSlot as aj, funnelCatalogKeys as ak, normalizeProducts as al, weightsOf as am, type FunnelSnapshot as b, type FunnelDefinition as c, buildContext as d, type ProductInput as e, type PageMeta as f, type PageContext as g, type BuildContextOptions as h, type CompileInput as i, type Condition as j, type ConditionOp as k, type DeviceContext as l, type ExperimentIssue as m, type ExperimentResolution as n, type ExperimentValidation as o, type ExperimentVariant as p, type FlowPage as q, type FunnelLocales as r, type FunnelManifest as s, type Interval as t, type ManifestPage as u, type ManifestValidation as v, type Money as w, type PageType as x, type Predicate as y, type ResolvedProduct as z };
+export { expectedPathLength as $, type Acquisition as A, type BrowserContext as B, type ClickIdContext as C, type Direction as D, type EdgeCondition as E, type FunnelContext as F, type Gate as G, assignVariant as H, type IdentityContext as I, bucketingSeed as J, buildAcquisition as K, type LocaleContext as L, type ManifestEdge as M, buildCatalog as N, type Offering as O, type PageMeta as P, compileManifest as Q, type RuntimeExperiment as R, type SessionContext as S, currencyExponent as T, type UtmContext as U, type VariableValue as V, defineFunnel as W, definePage as X, entryGuard as Y, evaluateCondition as Z, evaluateGate as _, type VariableConfig as a, fnv1a as a0, formatMoney as a1, formatOffering as a2, hashToUnit as a3, isRtl as a4, isVariantKey as a5, nextPage as a6, outgoingKeys as a7, pageMeta as a8, parseSlotKey as a9, pickByWeight as aa, resolveExperiments as ab, resolveLocale as ac, resolveOffering as ad, resolveRoute as ae, type FunnelPage as af, type OfferingSlot as ag, funnelCatalogKeys as ah, normalizeOfferings as ai, weightsOf as aj, type FunnelSnapshot as b, type FunnelDefinition as c, buildContext as d, type OfferingInput as e, type PageContext as f, type BuildContextOptions as g, type CompileInput as h, type Condition as i, type ConditionOp as j, type DeviceContext as k, type ExperimentArm as l, type ExperimentResolution as m, type FlowPage as n, type FunnelLocales as o, type FunnelManifest as p, type Interval as q, type ManifestPage as r, type ManifestValidation as s, type Money as t, type OsContext as u, type PageType as v, type Predicate as w, type ResolvedOffering as x, type Route as y, type SystemContext as z };