@fanfare-io/fanfare-sdk-core 0.2.0 → 0.4.0

package/dist/experiences/journey.types.d.ts

@@ -1,100 +1,114 @@
-import { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, DistributionLifecycle, DistributionType, DrawConsumerStatus, JourneyStage, QueueConsumerStatus, SequenceOutcome, SequenceOutcomeType, SequencePhase, TimedReleaseConsumerStatus, WaitlistConsumerStatus } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, WaitlistAttachment as ContractWaitlistAttachment, DistributionLifecycle, DistributionType, DrawConsumerStatus, JourneyStage, QueueConsumerStatus, SequenceOutcome, SequenceOutcomeType, SequencePhase, TimedReleaseConsumerStatus, WaitlistConsumerStatus } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
 import { ReadableAtom } from 'nanostores';
+import { AppointmentEnded, AppointmentEnterable, AppointmentEnterableView, AppointmentParticipating, AppointmentParticipatingView, AppointmentScheduled, AppointmentScheduledView, AppointmentSequence, AppointmentSequenceConsumerState, AppointmentSequenceView } from '../appointments/appointment.sequence';
+import { AuctionEnded, AuctionEnterable, AuctionEnterableView, AuctionGranted, AuctionParticipating, AuctionParticipatingView, AuctionScheduled, AuctionScheduledView, AuctionSequence, AuctionSequenceConsumerState, AuctionSequenceView, AuctionSettling } from '../auctions/auction.sequence';
 import { BotMitigationState, RoutingChallenge } from '../challenges/types';
+import { DrawEnded, DrawEnterable, DrawEnterableView, DrawGranted, DrawParticipating, DrawParticipatingView, DrawScheduled, DrawScheduledView, DrawSequence, DrawSequenceConsumerState, DrawSequenceView, DrawSettling } from '../draws/draw.sequence';
+import { QueueEnded, QueueEnterable, QueueEnterableView, QueueGranted, QueueParticipating, QueueParticipatingView, QueueScheduled, QueueScheduledView, QueueSequence, QueueSequenceConsumerState, QueueSequenceView } from '../queues/queue.sequence';
+import { TimedReleaseEnded, TimedReleaseEnterable, TimedReleaseEnterableView, TimedReleaseGranted, TimedReleaseParticipating, TimedReleaseParticipatingView, TimedReleaseScheduled, TimedReleaseScheduledView, TimedReleaseSequence, TimedReleaseSequenceConsumerState, TimedReleaseSequenceView } from '../timed-releases/timed-release.sequence';
 import { SdkJourneyParticipationType } from '../types/distribution-type';
-import { AppointmentDisplayState, AuctionDisplayState, DrawDisplayState, QueueDisplayState, TimedReleaseDisplayState } from './distribution-monitor.types';
 import { DistributionDetails, ExperienceSession, Sequence } from './types';
+export type { AppointmentEnded, AppointmentEndedView, AppointmentEnterable, AppointmentEnterableView, AppointmentParticipating, AppointmentParticipatingView, AppointmentScheduled, AppointmentScheduledView, AppointmentSequence, AppointmentSequenceConsumerState, AppointmentSequenceView, } from '../appointments/appointment.sequence';
+export type { AuctionEnded, AuctionEndedView, AuctionEnterable, AuctionEnterableView, AuctionGranted, AuctionGrantedView, AuctionParticipating, AuctionParticipatingView, AuctionScheduled, AuctionScheduledView, AuctionSequence, AuctionSequenceConsumerState, AuctionSequenceView, AuctionSettling, AuctionSettlingView, } from '../auctions/auction.sequence';
+export type { DrawEnded, DrawEndedView, DrawEnterable, DrawEnterableView, DrawGranted, DrawGrantedView, DrawParticipating, DrawParticipatingView, DrawScheduled, DrawScheduledView, DrawSequence, DrawSequenceConsumerState, DrawSequenceView, DrawSettling, DrawSettlingView, } from '../draws/draw.sequence';
+export type { QueueEnded, QueueEndedView, QueueEnterable, QueueEnterableView, QueueGranted, QueueGrantedView, QueueParticipating, QueueParticipatingView, QueueScheduled, QueueScheduledView, QueueSequence, QueueSequenceConsumerState, QueueSequenceView, } from '../queues/queue.sequence';
+export type { TimedReleaseEnded, TimedReleaseEndedView, TimedReleaseEnterable, TimedReleaseEnterableView, TimedReleaseGranted, TimedReleaseGrantedView, TimedReleaseParticipating, TimedReleaseParticipatingView, TimedReleaseScheduled, TimedReleaseScheduledView, TimedReleaseSequence, TimedReleaseSequenceConsumerState, TimedReleaseSequenceView, } from '../timed-releases/timed-release.sequence';
 export type { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, DistributionLifecycle, DistributionType, DrawConsumerStatus, JourneyStage, QueueConsumerStatus, SequenceOutcome, SequenceOutcomeType, SequencePhase, TimedReleaseConsumerStatus, WaitlistConsumerStatus, };
-export type SequenceMechanism = DistributionType | "waitlist";
+/**
+ * Any sequence mechanism that can appear in a journey sequence.
+ */
+export type SequenceMechanism = DistributionType;
+/**
+ * Distribution-backed mechanisms that carry a `distribution` object.
+ */
 export type PrimarySequenceMechanism = DistributionType;
-export type GrantProducingSequenceMechanism = Exclude<PrimarySequenceMechanism, "appointment">;
+/**
+ * Primary mechanisms that can issue an admission grant.
+ */
+export type GrantProducingSequenceMechanism = "queue" | "draw" | "auction" | "timed_release";
+/**
+ * Primary mechanisms that can enter the server-driven settling phase.
+ */
 export type SettlingSequenceMechanism = "draw" | "auction";
+/**
+ * Distribution facts attached to a routed sequence.
+ *
+ * These values come from the journey projector and describe the distribution
+ * currently driving the sequence. Timestamps are ISO 8601 strings; `updatedAt`
+ * is a millisecond epoch version used for ordering projector updates.
+ */
 export interface DistributionSummary {
+    /** Mechanism discriminator for the distribution. */
     type: DistributionType;
+    /** Server distribution identifier. */
     id: string;
+    /** Sequence identifier that owns this distribution, when supplied by the projector. */
     sequenceId?: string;
+    /** Server lifecycle for opening, closing, and settlement. */
     lifecycle: DistributionLifecycle;
+    /** ISO 8601 scheduled start timestamp, when distinct from opening. */
     startsAt?: string;
+    /** ISO 8601 timestamp when consumers may enter or participate. */
     opensAt?: string;
+    /** ISO 8601 timestamp when participation closes. */
     closesAt?: string;
+    /** ISO 8601 timestamp when server settlement is expected. */
     settlesAt?: string;
+    /** Waitlist identifier attached while the distribution is scheduled. */
     waitlistId?: string;
+    /** Mechanism-specific configuration and display details from the server. */
     details?: DistributionDetails;
+    /** Millisecond epoch update time used to order projector snapshots. */
     updatedAt?: number;
 }
-export interface DistributionTarget {
-    type: DistributionType;
-    id: string;
-    sequenceId?: string;
-    lifecycle: DistributionLifecycle;
-    opensAt?: string;
-    closesAt?: string;
-    waitlistId?: string;
-    details?: Record<string, unknown>;
-    updatedAt?: number;
-}
+/**
+ * Internal alias for distribution facts on sequence states.
+ *
+ * Drivers use this name while preserving the public `DistributionSummary`
+ * shape. It carries the same server-authoritative fields and timestamp formats.
+ */
 export type SequenceDistributionState = DistributionSummary;
-export type SequenceTargetState = DistributionTarget;
-export interface QueueSequenceConsumerState {
-    status: QueueConsumerStatus;
-    id?: string;
-    distributionId?: string;
-    enteredAt?: string;
-    admissionGrant?: string;
-    grantedAt?: string;
-    deniedReason?: string;
-    position?: number;
-}
-export interface DrawSequenceConsumerState {
-    status: DrawConsumerStatus;
-    id?: string;
-    distributionId?: string;
-    enteredAt?: string;
-    admissionGrant?: string;
-    grantedAt?: string;
-    deniedReason?: string;
-}
-export interface AuctionSequenceConsumerState {
-    status: AuctionConsumerStatus;
-    id?: string;
-    distributionId?: string;
-    enteredAt?: string;
-    admissionGrant?: string;
-    grantedAt?: string;
-    deniedReason?: string;
-    highestBid?: string;
-    currentBid?: string;
-}
-export interface TimedReleaseSequenceConsumerState {
-    status: TimedReleaseConsumerStatus;
-    id?: string;
-    distributionId?: string;
-    enteredAt?: string;
-    admissionGrant?: string;
-    grantedAt?: string;
-    deniedReason?: string;
-}
-export interface AppointmentSequenceConsumerState {
-    status: AppointmentConsumerStatus;
-    id?: string;
-    distributionId?: string;
-    slotId?: string;
-    locationId?: string;
-    bookedAt?: string;
-    checkedInAt?: string;
-    completedAt?: string;
-    cancelledAt?: string;
-    noShowAt?: string;
-}
-export interface WaitlistSequenceConsumerState {
+/**
+ * Scheduled waitlist attachment facts for one consumer.
+ *
+ * Attachments exist only on scheduled primary sequence variants. They do not
+ * grant access on their own, are cleared when the primary distribution opens,
+ * and are restored only from `/consumers/me`.
+ */
+export type WaitlistAttachment = ContractWaitlistAttachment;
+/**
+ * Scheduled waitlist actions exposed on sequence views.
+ *
+ * The sub-view is present only while the primary distribution is scheduled.
+ * `join()` and `leave()` call the SDK waitlist module; `/consumers/me` remains
+ * the only source that can restore a `notified` status.
+ */
+export interface WaitlistAttachmentView {
+    /** Server waitlist attachment status for this consumer. */
     status: WaitlistConsumerStatus;
-    id?: string;
-    waitlistId?: string;
-    enteredAt?: string;
-    notifiedAt?: string;
+    /** Join the scheduled distribution's waitlist. */
+    join(): Promise<void>;
+    /** Leave the scheduled distribution's waitlist. */
+    leave(): Promise<void>;
 }
-export type ConsumerSequenceState = QueueSequenceConsumerState | DrawSequenceConsumerState | AuctionSequenceConsumerState | TimedReleaseSequenceConsumerState | AppointmentSequenceConsumerState | WaitlistSequenceConsumerState;
-export type SequenceConsumerFor<M extends SequenceMechanism> = M extends "queue" ? QueueSequenceConsumerState : M extends "draw" ? DrawSequenceConsumerState : M extends "auction" ? AuctionSequenceConsumerState : M extends "timed_release" ? TimedReleaseSequenceConsumerState : M extends "appointment" ? AppointmentSequenceConsumerState : WaitlistSequenceConsumerState;
+/**
+ * Consumer facts for any sequence mechanism.
+ */
+export type ConsumerSequenceState = QueueSequenceConsumerState | DrawSequenceConsumerState | AuctionSequenceConsumerState | TimedReleaseSequenceConsumerState | AppointmentSequenceConsumerState;
+/**
+ * Internal helper mapping a mechanism discriminator to its consumer state.
+ *
+ * This keeps driver and machine code correlated without reintroducing public
+ * mechanism x phase type generation. Integrators should narrow `SequenceState`
+ * or `SequenceView` by `mechanism` instead.
+ */
+export type SequenceConsumerFor<M extends SequenceMechanism> = M extends "queue" ? QueueSequenceConsumerState : M extends "draw" ? DrawSequenceConsumerState : M extends "auction" ? AuctionSequenceConsumerState : M extends "timed_release" ? TimedReleaseSequenceConsumerState : M extends "appointment" ? AppointmentSequenceConsumerState : never;
+/**
+ * Internal consumer payload tagged with the mechanism it came from.
+ *
+ * The tag is added while normalizing `/consumers/me` and routing payloads so
+ * generic shell code can pass the correct consumer facts to mechanism drivers.
+ */
 export type MechanismConsumerState = (QueueSequenceConsumerState & {
     mechanism: "queue";
 }) | (DrawSequenceConsumerState & {
@@ -105,291 +119,482 @@ export type MechanismConsumerState = (QueueSequenceConsumerState & {
     mechanism: "timed_release";
 }) | (AppointmentSequenceConsumerState & {
     mechanism: "appointment";
-}) | (WaitlistSequenceConsumerState & {
-    mechanism: "waitlist";
 });
-interface PrimarySequenceContext<M extends PrimarySequenceMechanism> {
-    mechanism: M;
-    distribution: DistributionSummary & {
-        type: M;
-    };
-    consumer: SequenceConsumerFor<M>;
-}
-interface WaitlistSequenceContext {
-    mechanism: "waitlist";
-    target: DistributionTarget;
-    consumer: WaitlistSequenceConsumerState;
-}
+/**
+ * Sequence placeholder used when the server selects no usable distribution.
+ *
+ * Render this as unavailable content and offer a retry or reroute from the
+ * surrounding `RoutedView` when appropriate.
+ */
 export type UnavailableSequenceState = {
+    /** Phase discriminator for an unavailable routed sequence. */
     phase: "unavailable";
+    /** Server or SDK reason suitable for diagnostics; not guaranteed localized. */
     reason?: string;
 };
-export type ScheduledSequenceState = {
-    [M in PrimarySequenceMechanism]: {
-        phase: "scheduled";
-    } & PrimarySequenceContext<M>;
-}[PrimarySequenceMechanism];
-export type EnterableSequenceState = {
-    [M in PrimarySequenceMechanism]: {
-        phase: "enterable";
-    } & PrimarySequenceContext<M>;
-}[PrimarySequenceMechanism] | ({
-    phase: "enterable";
-} & WaitlistSequenceContext);
-export type ParticipatingSequenceState = {
-    [M in PrimarySequenceMechanism]: {
-        phase: "participating";
-    } & PrimarySequenceContext<M>;
-}[PrimarySequenceMechanism] | ({
-    phase: "participating";
-} & WaitlistSequenceContext);
-export type SettlingSequenceState = {
-    [M in SettlingSequenceMechanism]: {
-        phase: "settling";
-    } & PrimarySequenceContext<M>;
-}[SettlingSequenceMechanism];
-export type GrantedSequenceState = {
-    [M in GrantProducingSequenceMechanism]: {
-        phase: "granted";
-        grant: AdmissionGrant;
-    } & PrimarySequenceContext<M>;
-}[GrantProducingSequenceMechanism];
-export type EndedSequenceState = {
-    [M in PrimarySequenceMechanism]: {
-        phase: "ended";
-        outcome: SequenceOutcome;
-    } & PrimarySequenceContext<M>;
-}[PrimarySequenceMechanism] | ({
-    phase: "ended";
-    outcome: SequenceOutcome;
-} & WaitlistSequenceContext);
-export type SequenceState = UnavailableSequenceState | ScheduledSequenceState | EnterableSequenceState | ParticipatingSequenceState | SettlingSequenceState | GrantedSequenceState | EndedSequenceState;
-export type ActiveSequenceState = Exclude<SequenceState, UnavailableSequenceState>;
+/**
+ * Sequence states that exist before a primary distribution opens.
+ */
+export type ScheduledSequenceState = QueueScheduled | DrawScheduled | AuctionScheduled | TimedReleaseScheduled | AppointmentScheduled;
+/**
+ * Sequence states where the consumer can enter, bid, book, or join a waitlist.
+ */
+export type EnterableSequenceState = QueueEnterable | DrawEnterable | AuctionEnterable | TimedReleaseEnterable | AppointmentEnterable;
+/**
+ * Sequence states where the consumer is actively participating.
+ */
+export type ParticipatingSequenceState = QueueParticipating | DrawParticipating | AuctionParticipating | TimedReleaseParticipating | AppointmentParticipating;
+/**
+ * Sequence states where a draw or auction is being settled by the server.
+ */
+export type SettlingSequenceState = DrawSettling | AuctionSettling;
+/**
+ * Sequence states where the consumer has an admission grant.
+ */
+export type GrantedSequenceState = QueueGranted | DrawGranted | AuctionGranted | TimedReleaseGranted;
+/**
+ * Sequence states where the sequence is terminal for the consumer.
+ */
+export type EndedSequenceState = QueueEnded | DrawEnded | AuctionEnded | TimedReleaseEnded | AppointmentEnded;
+/**
+ * Serializable sequence state for a routed journey.
+ */
+export type SequenceState = UnavailableSequenceState | QueueSequence | DrawSequence | AuctionSequence | TimedReleaseSequence | AppointmentSequence;
+/**
+ * Mechanism-backed sequence state, excluding the unavailable placeholder.
+ *
+ * Internal driver code uses this alias when a concrete mechanism is required.
+ * Integrator code can usually work with the broader `SequenceState` union.
+ */
+export type ActiveSequenceState = QueueSequence | DrawSequence | AuctionSequence | TimedReleaseSequence | AppointmentSequence;
+/**
+ * Internal helper selecting the sequence union for one mechanism.
+ *
+ * Used by driver code that is already mechanism-specific. Public rendering
+ * should narrow `SequenceState` or `SequenceView` by the `mechanism` field.
+ */
 export type SequenceStateFor<M extends SequenceMechanism> = Extract<ActiveSequenceState, {
     mechanism: M;
 }>;
-export type PrimarySequenceState = Extract<ActiveSequenceState, {
-    distribution: DistributionSummary;
-}>;
-export type ConsumerJourneyState = {
+/**
+ * Mechanism-backed sequence state for primary journey distributions.
+ *
+ * This is equivalent to `ActiveSequenceState` while every shipped mechanism is
+ * primary. It remains as an internal constraint for code that excludes
+ * `unavailable`.
+ */
+export type PrimarySequenceState = QueueSequence | DrawSequence | AuctionSequence | TimedReleaseSequence | AppointmentSequence;
+/**
+ * Serializable journey state rebuilt from `/consumers/me`.
+ *
+ * This is the server-facing snapshot shape used by resume and parity tests, not
+ * the render view. Use `JourneySnapshot` for client persistence and
+ * `JourneyView` for UI rendering.
+ */
+export type ConsumerJourneyState = 
+/** The consumer has no selected sequence and can begin routing. */
+{
     journeyStage: "ready";
     experienceId: string;
     updatedAt?: string;
-} | {
+}
+/** The SDK is actively routing the consumer through the experience. */
+ | {
     journeyStage: "routing";
     experienceId: string;
     updatedAt?: string;
-} | {
+}
+/** The selected route requires gates such as auth, access code, or bot mitigation. */
+ | {
+    /** Stage discriminator for a gated server journey. */
     journeyStage: "gated";
+    /** Experience identifier for this journey. */
     experienceId: string;
+    /** ISO 8601 server update timestamp, when supplied. */
     updatedAt?: string;
+    /** Server gate payloads; narrowed client gates are exposed through `RoutingGate`. */
     gates: unknown[];
+    /** Selected sequence id that is gated, when the server chose one. */
     selected?: {
         sequenceId: string;
     };
-} | {
+}
+/** The consumer is routed to a concrete sequence state. */
+ | {
+    /** Stage discriminator for a routed server journey. */
     journeyStage: "routed";
+    /** Experience identifier for this journey. */
     experienceId: string;
+    /** ISO 8601 server update timestamp, when supplied. */
     updatedAt?: string;
+    /** Selected sequence identifier. */
     sequenceId: string;
+    /** Mechanism-first sequence state for the selected sequence. */
     sequence: SequenceState;
+    /** Additional route offers from the server, when supplied. */
     offers?: unknown[];
 };
+/**
+ * Server journey states that require active service handling.
+ *
+ * Internal resume code uses this to distinguish gated/routed server responses
+ * from ready/routing placeholders.
+ */
 export type ServiceJourneyState = Extract<ConsumerJourneyState, {
     journeyStage: "gated" | "routed";
 }>;
+/** Stage discriminator for server states that carry gates or sequence state. */
 export type ServiceJourneyStage = ServiceJourneyState["journeyStage"];
-export type RoutingGate = {
+/**
+ * Gate that prevents a selected sequence from becoming renderable.
+ *
+ * Gates are returned by routing. UIs should render the required action and then
+ * call `retry()` or `reroute()` on the current journey view after the gate is
+ * satisfied.
+ */
+export type RoutingGate = 
+/** The consumer must authenticate before the route can continue. */
+{
     type: "authentication";
     status: "required";
-} | {
+}
+/** The route requires an access code or rejected the submitted one. */
+ | {
     type: "access_code";
     status: "missing" | "invalid";
-} | {
+}
+/** The route requires bot mitigation or has been blocked by it. */
+ | {
+    /** Gate discriminator for bot mitigation. */
     type: "bot_check";
+    /** Current mitigation status. */
     status: "required" | "blocked";
+    /** Challenge payload to render when mitigation is required. */
     challenge?: RoutingChallenge;
+    /** Bot-risk state supplied by the mitigation service. */
     mitigation?: BotMitigationState;
 };
+/**
+ * Alternative gated route returned by the server.
+ *
+ * Offers let an integrator show other sequences the consumer could unlock.
+ * They are informational until a reroute selects one.
+ */
 export interface RoutingOffer {
+    /** Offered sequence metadata from the experience service. */
     sequence: Sequence;
+    /** Offer status; currently only gated offers are exposed. */
     status: "gated";
+    /** Gates that must be satisfied before this offer can be routed. */
     gates: RoutingGate[];
 }
+/**
+ * Consumer participation reference attached to journey events or analytics.
+ *
+ * `id` is the server participation identifier. `type` identifies the
+ * participation mechanism, including waitlist attachments.
+ */
 export interface Participation {
+    /** Server participation identifier. */
     id: string;
+    /** Participation mechanism discriminator. */
     type: SdkJourneyParticipationType;
 }
+/**
+ * Category for a journey event emitted by the SDK shell.
+ */
 export type JourneyEventKind = "reroute" | "sequence_change" | "distribution_change" | "requirement" | "error" | "info";
+/**
+ * Presentation severity for a journey event.
+ */
 export type JourneyEventSeverity = "info" | "success" | "warning" | "error";
+/**
+ * Intended consumer for a journey event.
+ */
 export type JourneyEventAudience = "user" | "system" | "analytics";
+/**
+ * Event emitted by the journey shell for UI, diagnostics, or analytics.
+ *
+ * `ts` is a millisecond epoch timestamp generated by the SDK. Events are
+ * ordered by id and timestamp within one journey handle.
+ */
 export interface JourneyEvent {
+    /** Stable event identifier generated by the SDK. */
     id: string;
+    /** Millisecond epoch timestamp when the SDK emitted the event. */
     ts: number;
+    /** Event category. */
     kind: JourneyEventKind;
+    /** Presentation severity. */
     severity: JourneyEventSeverity;
+    /** Intended audience for rendering or forwarding. */
     audience: JourneyEventAudience;
+    /** Human-readable message suitable for logs or simple UI. */
     message: string;
+    /** Structured diagnostics or analytics context. */
     detail?: Record<string, unknown>;
 }
 interface JourneyBase {
+    /** Monotonic SDK revision used for cross-tab ordering. */
     revision: number;
+    /** Millisecond epoch timestamp when the snapshot was last updated. */
     updatedAt: number;
+    /** Experience identifier for this journey handle. */
     experienceId: string;
+    /** Last access code used for routing, when one has been supplied. */
     accessCode?: string;
+    /** Session details returned by the experience entry endpoint, when available. */
     experience?: ExperienceSession;
+    /** Buffered SDK events emitted for this journey. */
     events: JourneyEvent[];
+    /** Last acknowledged event id for UI notification state. */
     lastSeenEventId?: string;
 }
+/**
+ * Persistable journey snapshot before routing has started.
+ */
 export interface ReadySnapshot extends JourneyBase {
+    /** Stage discriminator; call `start()` on the matching view to route. */
     journeyStage: "ready";
 }
+/**
+ * Persistable journey snapshot while routing is in flight.
+ */
 export interface RoutingSnapshot extends JourneyBase {
+    /** Stage discriminator for an in-flight route request. */
     journeyStage: "routing";
 }
+/**
+ * Persistable journey snapshot when routing is blocked by gates.
+ */
 export interface GatedSnapshot extends JourneyBase {
+    /** Stage discriminator for a gated route. */
     journeyStage: "gated";
+    /** Gates that must be satisfied before the sequence can render. */
     gates: RoutingGate[];
+    /** Selected gated sequence, when routing chose one. */
     selected?: {
+        /** Selected sequence metadata. */
         sequence: Sequence;
+        /** Selected sequence status; currently always gated. */
         status: "gated";
     };
 }
+/**
+ * Persistable journey snapshot after routing selects a sequence.
+ */
 export interface RoutedSnapshot extends JourneyBase {
+    /** Stage discriminator for a routed sequence. */
     journeyStage: "routed";
+    /** Selected sequence identifier. */
     sequenceId: string;
+    /** Additional gated route offers supplied by the server. */
     offers: RoutingOffer[];
+    /** Current mechanism-first sequence state. */
     sequence: SequenceState;
+    /** Selected sequence metadata; `sequence` is runtime state, while `sequenceRef` identifies the routed sequence. */
+    sequenceRef?: Sequence;
 }
+/**
+ * Versioned, persistable state for one journey handle.
+ *
+ * Snapshots are a cache for reload/cross-tab handoff. On restore, the SDK
+ * validates the stored version and rebuilds stale or incompatible snapshots
+ * from `/consumers/me`.
+ */
 export type JourneySnapshot = ReadySnapshot | RoutingSnapshot | GatedSnapshot | RoutedSnapshot;
+/**
+ * Render view before routing has started.
+ */
 export interface ReadyView {
+    /** Stage discriminator; only `start()` is legal in this view. */
     journeyStage: "ready";
+    /**
+     * Start routing the consumer through the experience.
+     *
+     * `accessCode`, when provided, is sent to the routing endpoint. The promise
+     * rejects if routing fails before the journey can move to a new view.
+     */
     start(opts?: {
         accessCode?: string;
     }): Promise<void>;
 }
+/**
+ * Render view while routing is in flight.
+ */
 export interface RoutingView {
+    /** Stage discriminator for an in-flight route request. */
     journeyStage: "routing";
 }
+/**
+ * Render view when routing requires gates before a sequence is usable.
+ */
 export interface GatedView {
+    /** Stage discriminator for a gated route. */
     journeyStage: "gated";
+    /** Gates the integrator should satisfy or explain to the consumer. */
     gates: RoutingGate[];
+    /** Selected gated sequence, when routing chose one. */
     selected?: {
         sequence: Sequence;
         status: "gated";
     };
+    /**
+     * Attempt routing again, optionally with a new access code. Omitting
+     * `accessCode` re-sends the journey's stored code; passing
+     * `accessCode: undefined` explicitly clears the stored code first.
+     *
+     * Use after a gate changes state. The promise rejects if the route request or
+     * gate validation fails.
+     */
     reroute(opts?: {
         accessCode?: string;
     }): Promise<void>;
+    /**
+     * Retry the current gated route without changing the access code.
+     *
+     * Use after completing auth or bot mitigation. The promise rejects if routing
+     * still cannot proceed.
+     */
     retry(): Promise<void>;
 }
+/**
+ * Result of `RoutedView.submitAccessCode`.
+ * - `advanced`: the code unlocked a higher-priority offered sequence; the
+ *   journey moved into it and the code became the journey's stored code.
+ * - `unchanged`: the code unlocked nothing; the journey remains in (or was
+ *   restored toward) its previous sequence and the stored code is untouched.
+ * - `gated`: routing no longer yields an admissible sequence; the journey is
+ *   now gated and the gate UI should take over.
+ */
+export type AccessCodeSubmitResult = {
+    outcome: "advanced";
+    sequenceId: string;
+} | {
+    outcome: "unchanged";
+} | {
+    outcome: "gated";
+};
+/**
+ * Render view after routing selects a sequence.
+ */
 export interface RoutedView {
+    /** Stage discriminator for a routed sequence. */
     journeyStage: "routed";
+    /** Selected sequence identifier. */
     sequenceId: string;
+    /** Additional gated offers the consumer could route to. */
     offers: RoutingOffer[];
+    /**
+     * Route the consumer again with the journey's stored access code.
+     *
+     * Use when the selected sequence changes or an offer should be reconsidered.
+     */
     reroute(): Promise<void>;
+    /**
+     * Attempts an upgrade into a higher-priority offered sequence. Routing is
+     * stateless and single-code, so the candidate replaces the stored code for
+     * the attempt only: it is committed as the stored code when the journey
+     * advances, and if it instead displaces the consumer from a code-held
+     * sequence, the previously stored code is re-applied automatically.
+     */
+    submitAccessCode(accessCode: string): Promise<AccessCodeSubmitResult>;
+    /**
+     * Retry the current routed state after a transient failure.
+     */
     retry(): Promise<void>;
+    /** Mechanism-first sequence view containing the legal phase actions. */
     sequence: SequenceView;
 }
-export type ParticipatingSequenceView = {
-    phase: "participating";
-    mechanism: "queue";
-    consumer: QueueSequenceConsumerState;
-    state$: ReadableAtom<QueueDisplayState>;
-    leave(): Promise<void>;
-} | {
-    phase: "participating";
-    mechanism: "draw";
-    consumer: DrawSequenceConsumerState;
-    state$: ReadableAtom<DrawDisplayState>;
-    leave(): Promise<void>;
-} | {
-    phase: "participating";
-    mechanism: "auction";
-    consumer: AuctionSequenceConsumerState;
-    state$: ReadableAtom<AuctionDisplayState>;
-    bid(amount: string): Promise<void>;
-    leave(): Promise<void>;
-} | {
-    phase: "participating";
-    mechanism: "timed_release";
-    consumer: TimedReleaseSequenceConsumerState;
-    state$: ReadableAtom<TimedReleaseDisplayState>;
-    leave(): Promise<void>;
-    complete(): Promise<void>;
-} | {
-    phase: "participating";
-    mechanism: "appointment";
-    consumer: AppointmentSequenceConsumerState;
-    state$: ReadableAtom<AppointmentDisplayState>;
-    cancel(reason?: string): Promise<void>;
-    reschedule(newSlotId: string, newLocationId?: string): Promise<void>;
-} | {
-    phase: "participating";
-    mechanism: "waitlist";
-    consumer: WaitlistSequenceConsumerState;
-    leave(): Promise<void>;
-};
-export type EnterableSequenceView = {
-    phase: "enterable";
-    mechanism: Exclude<PrimarySequenceMechanism, "appointment" | "auction">;
-    distribution: DistributionSummary;
-    consumer: Exclude<ConsumerSequenceState, AppointmentSequenceConsumerState | WaitlistSequenceConsumerState>;
-    enter(): Promise<void>;
-} | {
-    phase: "enterable";
-    mechanism: "auction";
-    distribution: DistributionSummary;
-    consumer: AuctionSequenceConsumerState;
-    bid(amount: string): Promise<void>;
-} | {
-    phase: "enterable";
-    mechanism: "appointment";
-    distribution: DistributionSummary;
-    consumer: AppointmentSequenceConsumerState;
-    book(slotId: string, locationId?: string): Promise<void>;
-} | {
-    phase: "enterable";
-    mechanism: "waitlist";
-    target: DistributionTarget;
-    consumer: WaitlistSequenceConsumerState;
-    enter(): Promise<void>;
-};
-export type ScheduledSequenceView = {
-    phase: "scheduled";
-    mechanism: PrimarySequenceMechanism;
-    distribution: DistributionSummary;
-    consumer: Exclude<ConsumerSequenceState, WaitlistSequenceConsumerState>;
-    startsAt?: string;
-};
-export type SequenceView = {
-    phase: "unavailable";
-    reason?: string;
-} | ScheduledSequenceView | EnterableSequenceView | ParticipatingSequenceView | {
+interface SettlingSequenceView {
+    /** Phase discriminator for server-driven settlement. */
     phase: "settling";
+    /** Mechanism discriminator; only draw and auction settle. */
     mechanism: SettlingSequenceMechanism;
+    /** Distribution facts from the journey projector. */
     distribution: DistributionSummary;
+    /** Consumer facts being settled by the server. */
     consumer: DrawSequenceConsumerState | AuctionSequenceConsumerState;
-} | {
+}
+interface GrantedSequenceView {
+    /** Phase discriminator; `claim()` is legal in this view. */
     phase: "granted";
+    /** Mechanism discriminator for grant-producing distributions. */
     mechanism: GrantProducingSequenceMechanism;
+    /** Distribution facts from the journey projector. */
     distribution: DistributionSummary;
+    /** Consumer facts associated with the grant. */
     consumer: QueueSequenceConsumerState | DrawSequenceConsumerState | AuctionSequenceConsumerState | TimedReleaseSequenceConsumerState;
+    /** Admission credential issued by the server. */
     grant: AdmissionGrant;
+    /** Return the current admission credential for checkout handoff. */
     claim(): AdmissionGrant;
-} | {
+}
+interface EndedSequenceView {
+    /** Phase discriminator; no sequence actions are legal after this phase. */
     phase: "ended";
+    /** Mechanism discriminator for the terminal sequence. */
     mechanism: SequenceMechanism;
+    /** Consumer facts at the terminal outcome. */
     consumer: ConsumerSequenceState;
+    /** Server-derived terminal outcome. */
     outcome: SequenceOutcome;
-};
+}
+interface UnavailableSequenceView {
+    /** Phase discriminator for an unavailable routed sequence. */
+    phase: "unavailable";
+    /** Server or SDK reason suitable for diagnostics; not guaranteed localized. */
+    reason?: string;
+}
+type PrimarySequenceView = QueueSequenceView | DrawSequenceView | AuctionSequenceView | TimedReleaseSequenceView | AppointmentSequenceView;
+/**
+ * Scheduled sequence views for primary distribution mechanisms.
+ */
+export type ScheduledSequenceView = QueueScheduledView | DrawScheduledView | AuctionScheduledView | TimedReleaseScheduledView | AppointmentScheduledView;
+/**
+ * Enterable sequence views. The action exposed by each variant is the only
+ * legal entry action for that phase and mechanism.
+ */
+export type EnterableSequenceView = QueueEnterableView | DrawEnterableView | AuctionEnterableView | TimedReleaseEnterableView | AppointmentEnterableView;
+/**
+ * Participating sequence views. Live display atoms are exposed as `display$`
+ * on the five primary mechanisms.
+ */
+export type ParticipatingSequenceView = QueueParticipatingView | DrawParticipatingView | AuctionParticipatingView | TimedReleaseParticipatingView | AppointmentParticipatingView;
+/**
+ * Renderable sequence view for a routed journey.
+ */
+export type SequenceView = UnavailableSequenceView | PrimarySequenceView | SettlingSequenceView | GrantedSequenceView | EndedSequenceView;
+/**
+ * Renderable journey view exposed by `JourneyHandle.view$`.
+ *
+ * Render from this union rather than from snapshots. The current
+ * `journeyStage` determines which methods are legal.
+ */
 export type JourneyView = ReadyView | RoutingView | GatedView | RoutedView;
+/**
+ * Runtime handle for one consumer's journey through one experience.
+ *
+ * Subscribe to `view$` for rendering, call methods only on the current view,
+ * and call `destroy()` when the embedding UI no longer owns the journey.
+ */
 export interface JourneyHandle {
+    /** Reactive render view for the journey. */
     view$: ReadableAtom<JourneyView>;
+    /** Reactive buffer of journey events emitted by the SDK shell. */
     events$: ReadableAtom<JourneyEvent[]>;
+    /** Most recent unacknowledged event, or null when none remain. */
     latestEvent$: ReadableAtom<JourneyEvent | null>;
+    /** Reactive persistable snapshot cache for reload and cross-tab sync. */
     snapshot$: ReadableAtom<JourneySnapshot>;
+    /** Mark one event as seen so it no longer appears as latest. */
     ackEvent(eventId: string): void;
+    /** Mark all currently buffered events as seen. */
     ackAllEvents(): void;
+    /**
+     * Tear down monitors, timers, and cross-tab listeners owned by this handle,
+     * and remove the journey's persisted snapshot. A later `journeys.get` starts
+     * fresh and rebuilds state from the server.
+     */
     destroy(): void;
 }