@fanfare-io/fanfare-sdk-core 0.1.0

package/dist/draws/types.d.ts

@@ -0,0 +1,90 @@
+import { RequestOptions } from '../core/http';
+/**
+ * Known draw deny reasons.
+ *
+ * When a consumer is denied entry to a draw, the `reason` field
+ * will contain one of these values (or a custom reason).
+ */
+export declare const DrawDenyReason: {
+    /** Consumer has exceeded their order limit for this experience */
+    readonly ORDER_LIMIT_EXCEEDED: "ORDER_LIMIT_EXCEEDED";
+    /** Draw has reached maximum entries */
+    readonly CAPACITY_EXCEEDED: "CAPACITY_EXCEEDED";
+    /** Consumer validation failed */
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    /** Consumer is not part of the required audience */
+    readonly AUDIENCE_MISMATCH: "AUDIENCE_MISMATCH";
+    /** Draw is closed */
+    readonly DRAW_CLOSED: "DRAW_CLOSED";
+    /** Consumer did not win the draw */
+    readonly NOT_SELECTED: "NOT_SELECTED";
+};
+export type DrawDenyReason = (typeof DrawDenyReason)[keyof typeof DrawDenyReason];
+/**
+ * Draw participation stored in state
+ */
+export interface DrawParticipation {
+    drawId: string;
+    enteredAt: string;
+    entryNumber?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Draw result details
+ */
+export interface DrawResult {
+    won: boolean;
+    drawTime: string;
+    prizeDetails?: Record<string, unknown>;
+    nextSteps?: string;
+}
+/**
+ * Draw consumer states (from backend)
+ */
+export type DrawConsumerState = DrawNotEnteredState | DrawEnteredState | DrawWonState | DrawCompletedState | DrawDeniedState;
+export interface DrawNotEnteredState {
+    status: "NOT_ENTERED";
+}
+export interface DrawEnteredState {
+    status: "ENTERED";
+}
+export interface DrawWonState {
+    status: "WON";
+    wonAt: string;
+    admissionGrant: string;
+    fingerprint?: string;
+    expiresAt?: string;
+}
+export interface DrawCompletedState {
+    status: "COMPLETED";
+    completedAt: string;
+    admissionGrant: string;
+    fingerprint?: string;
+    expiresAt?: string;
+}
+export interface DrawDeniedState {
+    status: "DENIED";
+    reason: string;
+    deniedAt: string;
+}
+/**
+ * Draw module interface
+ */
+export interface DrawModule {
+    get(drawId: string): Promise<Draw>;
+    enter(drawId: string, metadata?: Record<string, unknown>, options?: RequestOptions): Promise<DrawConsumerState>;
+    leave(drawId: string, options?: RequestOptions): Promise<void>;
+    status(drawId: string): Promise<DrawConsumerState>;
+}
+/**
+ * Draw entity
+ */
+export interface Draw {
+    id: string;
+    openAt?: string | null;
+    closeAt?: string | null;
+    timeZone: string;
+    drawAt: string;
+    capacity?: number | null;
+    continueSelectingUntilCompleted?: boolean | null;
+}

package/dist/draws/types.js

@@ -0,0 +1 @@
+const E={ORDER_LIMIT_EXCEEDED:"ORDER_LIMIT_EXCEEDED",CAPACITY_EXCEEDED:"CAPACITY_EXCEEDED",VALIDATION_FAILED:"VALIDATION_FAILED",AUDIENCE_MISMATCH:"AUDIENCE_MISMATCH",DRAW_CLOSED:"DRAW_CLOSED",NOT_SELECTED:"NOT_SELECTED"};export{E as DrawDenyReason};

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Public error surface. `classifyHttpError` is an internal helper and is not exported here.
+ */
+export { ErrorCodes, FanfareError, ProtocolError, createError, isCapabilityGrantError, isCapabilityGrantRerouteError, isCapabilityTokenError, isCapabilityTokenRerouteError, isFanfareError, isProtocolError, } from './core/errors';
+export type { ErrorCode } from './core/errors';

package/dist/errors.js

@@ -0,0 +1 @@
+import{ErrorCodes as r,FanfareError as o,ProtocolError as e,createError as m,isCapabilityGrantError as p,isCapabilityGrantRerouteError as s,isCapabilityTokenError as t,isCapabilityTokenRerouteError as c,isFanfareError as f,isProtocolError as i}from"./core/errors.js";export{r as ErrorCodes,o as FanfareError,e as ProtocolError,m as createError,p as isCapabilityGrantError,s as isCapabilityGrantRerouteError,t as isCapabilityTokenError,c as isCapabilityTokenRerouteError,f as isFanfareError,i as isProtocolError};

package/dist/events.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Public event type surface: the SDK event maps {@link SDKEvents} and {@link JourneyEvents}.
+ * The runtime `EventBus`/`getEventBus` internals in `state/events.ts` are not exported here.
+ */
+export type { JourneyEvents, SDKEvents } from './state/events';

package/dist/events.js

@@ -0,0 +1 @@
+

package/dist/experiences/distribution-monitor.runtime.d.ts

@@ -0,0 +1,12 @@
+import { WritableAtom } from 'nanostores';
+import { DistributionDisplayState, MonitorUpdate } from './distribution-monitor.types';
+export declare class DistributionMonitorRuntime {
+    private callbacks;
+    private displayAtoms;
+    start(id: string, context?: Record<string, unknown>, onUpdate?: (update: MonitorUpdate) => void): void;
+    stop(id: string): void;
+    has(id: string): boolean;
+    getDisplayAtom(id: string): WritableAtom<DistributionDisplayState> | undefined;
+    notify(id: string, update: MonitorUpdate, once?: boolean): void;
+    clear(): void;
+}

package/dist/experiences/distribution-monitor.runtime.js

@@ -0,0 +1 @@
+class s{constructor(){this.callbacks=/* @__PURE__ */new Map,this.displayAtoms=/* @__PURE__ */new Map}start(s,t,a){a&&this.callbacks.set(s,a),t?.displayAtom&&this.displayAtoms.set(s,t.displayAtom)}stop(s){this.callbacks.delete(s),this.displayAtoms.delete(s)}has(s){return this.callbacks.has(s)||this.displayAtoms.has(s)}getDisplayAtom(s){return this.displayAtoms.get(s)}notify(s,t,a=!0){const l=this.callbacks.get(s);l&&(l(t),a&&this.callbacks.delete(s))}clear(){this.callbacks.clear(),this.displayAtoms.clear()}}export{s as DistributionMonitorRuntime};

package/dist/experiences/distribution-monitor.types.d.ts

@@ -0,0 +1,62 @@
+import { SequenceOutcome } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+export type MonitorUpdate = {
+    type: "granted";
+    token: string;
+    expiresAt?: number;
+} | {
+    type: "ended";
+    outcome: SequenceOutcome;
+};
+export interface DistributionMonitor {
+    startMonitoring(id: string, context?: Record<string, unknown>, onUpdate?: (update: MonitorUpdate) => void): void;
+    stopMonitoring(id: string): void;
+    isMonitoring(id: string): boolean;
+}
+export interface QueueDisplayState {
+    position?: number;
+    estimatedWaitTime?: number;
+    positionDisplayMode?: "precise" | "qualitative";
+}
+export interface DrawDisplayState {
+    drawTime?: string;
+    entryNumber?: string;
+}
+export interface AuctionDisplayState {
+    highestBid?: string;
+    currentBid?: string;
+    bidCount?: number;
+    closeAt?: string;
+    status?: string;
+    currencyCode?: string;
+    minNextBid?: string;
+    bidIncrement?: string;
+}
+export interface TimedReleaseDisplayState {
+    enteredAt?: string;
+    checkoutUrl?: string;
+}
+export interface AppointmentDisplayState {
+    booking?: {
+        slotId: string;
+        locationId?: string;
+        locationName?: string;
+        /** Join URL for online appointments. Absent for in-person bookings. */
+        joinUrl?: string;
+        startTime: string;
+        endTime: string;
+        confirmationCode?: string;
+        consumerStatus: "booked" | "checked_in" | "completed";
+    };
+    msUntilStart?: number;
+}
+export type DistributionDisplayState = (QueueDisplayState & {
+    type: "queue";
+}) | (DrawDisplayState & {
+    type: "draw";
+}) | (AuctionDisplayState & {
+    type: "auction";
+}) | (TimedReleaseDisplayState & {
+    type: "timed_release";
+}) | (AppointmentDisplayState & {
+    type: "appointment";
+});

package/dist/experiences/experience.module.d.ts

@@ -0,0 +1,88 @@
+import { AuctionModule } from '../auctions/types';
+import { HttpClient } from '../core/http';
+import { DrawModule } from '../draws/types';
+import { QueueModule } from '../queues/types';
+import { TimedReleaseModule } from '../timed-releases/types';
+import { WaitlistModule } from '../waitlists/types';
+import { DistributionContext, ExperienceDetails, ExperienceModule, ExperienceSession, RoutingResult, Sequence, SequenceAccessResult } from './types';
+/**
+ * Custom errors for experience operations
+ */
+export declare class NoSequenceAvailableError extends Error {
+    constructor(message: string);
+}
+export declare class SequenceFullError extends Error {
+    constructor(message: string);
+}
+/**
+ * Experience Management Module
+ * Orchestrates experience-centric customer journeys and delegates to distribution modules
+ */
+export declare class ExperienceManagementModule implements ExperienceModule {
+    private readonly http;
+    private readonly logger;
+    private readonly events;
+    private get store();
+    private readonly queues;
+    private readonly draws;
+    private readonly auctions;
+    private readonly waitlists;
+    private readonly timedReleases;
+    constructor(http: HttpClient, queues: QueueModule, draws: DrawModule, auctions: AuctionModule, waitlists: WaitlistModule, timedReleases: TimedReleaseModule);
+    /**
+     * Get experience details
+     */
+    get(experienceId: string): Promise<ExperienceDetails>;
+    /**
+     * Enter an experience and start a session
+     */
+    enter(experienceId: string): Promise<ExperienceSession>;
+    /**
+     * Leave an experience and clean up state
+     */
+    leave(experienceId: string): Promise<void>;
+    /** Map a server routing gate to the SDK's {@link RoutingGate}. */
+    private mapGate;
+    /** Map a routing candidate sequence to a {@link Sequence}. */
+    private mapSequence;
+    /** Map a validated routing decision into the SDK's {@link RoutingResult}. */
+    private mapRoutingResult;
+    /** Find eligible sequences for an experience. */
+    findSequence(experienceId: string, accessCode?: string): Promise<RoutingResult>;
+    /**
+     * Validate access to a specific sequence
+     */
+    validateSequenceAccess(sequenceId: string, accessCode?: string): Promise<SequenceAccessResult>;
+    /**
+     * Select and assign a sequence to the user
+     */
+    selectSequence(sequenceId: string): Promise<void>;
+    /**
+     * Get current distribution context with timing awareness
+     */
+    getCurrentDistributions(sequenceId: string): Promise<DistributionContext>;
+    /**
+     * Enter an active distribution by delegating to appropriate module
+     */
+    enterDistribution(distribution: NonNullable<DistributionContext["active"]>): Promise<void>;
+    /**
+     * Get current active experience session
+     */
+    getActiveSession(): ExperienceSession | null;
+    /**
+     * Check if user is in a specific experience
+     */
+    isInExperience(experienceId: string): boolean;
+    /**
+     * Get currently assigned sequence
+     */
+    getSelectedSequence(): Sequence | null;
+    /**
+     * Fetch authenticated consumer participations (used for journey resume)
+     */
+    getMe(): Promise<import('./types').ConsumerMe>;
+    /**
+     * Clean up module resources
+     */
+    destroy(): void;
+}

package/dist/experiences/experience.module.js

@@ -0,0 +1 @@
+import{ConsumerMeResponseSchema as e}from"@fanfare-io/fanfare-sdk-contracts/consumer-me";import{RoutingDecisionV1Schema as t}from"@fanfare-io/fanfare-sdk-contracts/routing";import{createError as r}from"../core/errors.js";import{getLogger as s}from"../core/logger.js";import{parseResponse as i}from"../core/parse-response.js";import{getEventBus as n}from"../state/events.js";import{getSDKStore as c}from"../state/store.js";class a extends Error{constructor(e){super(e),this.name="NoSequenceAvailableError"}}class o extends Error{constructor(e){super(e),this.name="SequenceFullError"}}class u{constructor(e,t,r,i,c,a){this.logger=s(),this.events=n(),this.http=e,this.queues=t,this.draws=r,this.auctions=i,this.waitlists=c,this.timedReleases=a}get store(){return c()}async get(e){try{return this.logger.info("Getting experience details",{experienceId:e}),await this.http.get(`/experiences/${e}`)}catch(t){throw this.logger.error("Failed to get experience",{experienceId:e,error:t}),this.events.emit("experience:error",{experienceId:e,error:t instanceof Error?t.message:"Unknown error"}),t}}async enter(e){try{const t=this.store.activeExperiences[e];if(t)return this.logger.info("Already in experience",{experienceId:e}),t;if(!this.store.session)throw r.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");this.logger.info("Entering experience",{experienceId:e});const s=await this.http.post(`/experiences/${e}/enter`);return this.store.addActiveExperience(e,s),this.events.emit("experience:entered",{experienceId:e,enteredAt:s.enteredAt}),s}catch(t){if(t&&"object"==typeof t&&"message"in t){const r=t.message.toLowerCase();if(r.includes("already entered")||r.includes("already in experience"))return this.logger.info("Already in experience (from API)",{experienceId:e}),this.store.activeExperiences[e]||{experienceId:e,enteredAt:/* @__PURE__ */(new Date).toISOString()}}throw this.logger.error("Failed to enter experience",{experienceId:e,error:t}),this.events.emit("experience:error",{experienceId:e,error:t instanceof Error?t.message:"Unknown error"}),t}}async leave(e){try{const r=this.store.activeExperiences[e];if(!r)return void this.logger.warn("Not in experience",{experienceId:e});if(this.logger.info("Leaving experience",{experienceId:e}),r.currentDistribution){const{type:e,id:s}=r.currentDistribution;try{switch(e){case"queue":await this.queues.leave(s);break;case"draw":await this.draws.leave(s)}}catch(t){this.logger.warn("Failed to leave distribution during experience leave",{type:e,id:s,error:t})}}if(r.waitlistId)try{await this.waitlists.leave(r.waitlistId)}catch(t){this.logger.warn("Failed to leave waitlist during experience leave",{waitlistId:r.waitlistId,error:t})}await this.http.delete(`/experiences/${e}/leave`),this.store.removeActiveExperience(e),this.events.emit("experience:left",{experienceId:e})}catch(t){throw this.logger.error("Failed to leave experience",{experienceId:e,error:t}),this.events.emit("experience:error",{experienceId:e,error:t instanceof Error?t.message:"Unknown error"}),t}}mapGate(e){switch(e.type){case"authentication":return{type:"authentication",status:"required"};case"access_code":return{type:"access_code",status:e.status};case"bot_check":return{type:"bot_check",status:e.status,challenge:e.challenge,mitigation:e.mitigation}}}mapSequence(e){return{id:e.id,name:e.name,experienceId:e.experienceId,priority:e.priority,color:e.color??""}}mapRoutingResult(e){const t=e.offers.filter(e=>"gated"===e.status).map(e=>({sequence:this.mapSequence(e.sequence),status:"gated",gates:e.gates.map(e=>this.mapGate(e))}));if("no_access"===e.outcome)return{outcome:"no_access",offers:t};const r=e.selected;return{outcome:e.outcome,selected:{sequence:this.mapSequence(r.sequence),status:r.status,gates:r.gates.map(e=>this.mapGate(e)),capabilityGrant:r.sequenceCapabilityGrant,capabilityGrantExpiresAt:r.sequenceCapabilityGrantExpiresAt},offers:t}}async findSequence(e,r){try{this.logger.info("Finding sequence",{experienceId:e,hasAccessCode:!!r});const s=await this.http.post(`/experiences/${e}/route`,r?{accessCode:r}:{}),n=i(t,s,{endpoint:`/experiences/${e}/route`},{throwOnFailure:!0});if(!n.ok)throw n.error;return this.mapRoutingResult(n.value)}catch(s){throw this.logger.error("Failed to find sequence",{experienceId:e,error:s}),s}}async validateSequenceAccess(e,t){try{this.logger.info("Validating sequence access",{sequenceId:e,hasAccessCode:!!t});const r=await this.http.post(`/sequences/${e}/validate`,t?{accessCode:t}:{});return{sequenceId:e,hasAccess:r.hasAccess,accessReasons:r.accessReasons,deniedReasons:r.deniedReasons}}catch(r){throw this.logger.error("Failed to validate sequence access",{sequenceId:e,error:r}),r}}async selectSequence(e){try{this.logger.info("Selecting sequence",{sequenceId:e});const t=Object.keys(this.store.activeExperiences)[0];if(!t)throw r.internalError("No active experience found for sequence selection");this.store.updateExperienceSession(t,{assignedSequenceId:e}),this.events.emit("experience:sequence-selected",{sequenceId:e})}catch(t){if(t&&"object"==typeof t&&"message"in t){const e=t.message.toLowerCase();if(e.includes("sequence full")||e.includes("capacity reached"))throw new o("Sequence is full")}throw this.logger.error("Failed to select sequence",{sequenceId:e,error:t}),t}}async getCurrentDistributions(e){try{this.logger.info("Getting distribution context",{sequenceId:e});return await this.http.get(`/sequences/${e}/distributions`)}catch(t){throw this.logger.error("Failed to get distribution context",{sequenceId:e,error:t}),t}}async enterDistribution(e){try{this.logger.info("Entering distribution",{type:e.type,id:e.id});const t=c(),r=Object.keys(t.activeExperiences)[0],s=r?t.activeExperiences[r]:null;let i;switch(e.type){case"queue":{const t=await this.queues.enter(e.id);i="DENIED"===t.status||"EXPIRED"===t.status||"LEFT"===t.status?"ended":"active";break}case"draw":{const t=await this.draws.enter(e.id);i="DENIED"===t.status||"NOT_ENTERED"===t.status?"ended":"active";break}case"auction":await this.auctions.enter(e.id),i="active";break;case"appointment":this.logger.warn("Appointment distribution not yet implemented",{id:e.id});break;case"timed_release":i="ENTERED"===(await this.timedReleases.enter(e.id)).status?"active":"ended";break;default:this.logger.warn("Unknown distribution type",{type:e.type})}s&&r&&t.updateExperienceSession(r,{currentDistribution:i?{type:e.type,id:e.id,status:i}:void 0})}catch(t){throw this.logger.error("Failed to enter distribution",{type:e.type,id:e.id,error:t}),t}}getActiveSession(){const e=Object.values(this.store.activeExperiences);return e.length>0?e[0]:null}isInExperience(e){return!!this.store.activeExperiences[e]}getSelectedSequence(){const e=this.getActiveSession();return e&&e.assignedSequenceId?{id:e.assignedSequenceId,name:"",experienceId:e.experienceId,priority:0,color:"#000000"}:null}async getMe(){const t=await this.http.get("/consumers/me"),r=i(e,t,{endpoint:"/consumers/me"},{throwOnFailure:!0});if(!r.ok)throw r.error;return r.value}destroy(){this.logger.debug("ExperienceManagementModule destroyed")}}export{u as ExperienceManagementModule,a as NoSequenceAvailableError,o as SequenceFullError};

package/dist/experiences/index.d.ts

@@ -0,0 +1,3 @@
+export { ExperienceManagementModule, NoSequenceAvailableError, SequenceFullError } from './experience.module';
+export { ExperienceJourney } from './journey';
+export * from './types';

package/dist/experiences/index.js

@@ -0,0 +1 @@
+import{ExperienceManagementModule as e,NoSequenceAvailableError as o,SequenceFullError as r}from"./experience.module.js";import{ExperienceJourney as m}from"./journey.js";export{m as ExperienceJourney,e as ExperienceManagementModule,o as NoSequenceAvailableError,r as SequenceFullError};

package/dist/experiences/journey-contract.fixtures.d.ts

@@ -0,0 +1,9 @@
+export declare function canonicalReadySnapshot(experienceId?: string): import('./journey.types').ReadySnapshot;
+export declare function canonicalGatedSnapshot(experienceId?: string): import('./journey.types').GatedSnapshot;
+export declare function canonicalUpcomingQueueSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalActiveSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalParticipatingAuctionSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalEnterableAuctionSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalParticipatingTimedReleaseSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalDeniedActiveSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;
+export declare function canonicalDeniedClosedSnapshot(experienceId?: string): import('./journey.types').RoutedSnapshot;

package/dist/experiences/journey-view.d.ts

@@ -0,0 +1,22 @@
+import { ReadableAtom } from 'nanostores';
+import { DistributionDisplayState } from './distribution-monitor.types';
+import { AdmissionGrant, JourneySnapshot, JourneyView } from './journey.types';
+export interface JourneyViewHandlers {
+    start(opts?: {
+        accessCode?: string;
+        reset?: boolean;
+    }): Promise<void>;
+    reroute(opts?: {
+        accessCode?: string;
+    }): Promise<void>;
+    retry(): Promise<void>;
+    enter(): Promise<void>;
+    leave(): Promise<void>;
+    bid(amount: string): Promise<void>;
+    complete(): Promise<void>;
+    book(slotId: string, locationId?: string): Promise<void>;
+    cancel(reason?: string): Promise<void>;
+    reschedule(newSlotId: string, newLocationId?: string): Promise<void>;
+    claim(): AdmissionGrant;
+}
+export declare function buildJourneyView(snapshot: JourneySnapshot, handlers: JourneyViewHandlers, displayAtom: ReadableAtom<DistributionDisplayState> | null): JourneyView;

package/dist/experiences/journey-view.js

@@ -0,0 +1 @@
+function e(e,n,a){switch(e.journeyStage){case"ready":return{journeyStage:"ready",start:e=>n.start(e)};case"routing":return{journeyStage:"routing"};case"gated":return{journeyStage:"gated",gates:e.gates,selected:e.selected,reroute:e=>n.reroute(e),retry:()=>n.retry()};case"routed":return{journeyStage:"routed",sequenceId:e.sequenceId,offers:e.offers,reroute:()=>n.reroute(),retry:()=>n.retry(),sequence:t(e,n,a)}}}function t(e,t,n){const a=e.sequence;switch(a.phase){case"unavailable":return{phase:"unavailable",reason:a.reason};case"scheduled":return{phase:"scheduled",mechanism:a.mechanism,distribution:a.distribution,consumer:a.consumer,startsAt:a.distribution.startsAt??a.distribution.opensAt};case"enterable":return"appointment"===a.mechanism?{phase:"enterable",mechanism:"appointment",distribution:a.distribution,consumer:a.consumer,book:(e,n)=>t.book(e,n)}:"waitlist"===a.mechanism?{phase:"enterable",mechanism:"waitlist",target:a.target,consumer:a.consumer,enter:()=>t.enter()}:"auction"===a.mechanism?{phase:"enterable",mechanism:"auction",distribution:a.distribution,consumer:a.consumer,bid:e=>t.bid(e)}:{phase:"enterable",mechanism:a.mechanism,distribution:a.distribution,consumer:a.consumer,enter:()=>t.enter()};case"participating":return"waitlist"===a.mechanism?{phase:"participating",mechanism:"waitlist",consumer:a.consumer,leave:()=>t.leave()}:"appointment"===a.mechanism?{phase:"participating",mechanism:"appointment",consumer:a.consumer,state$:n,cancel:e=>t.cancel(e),reschedule:(e,n)=>t.reschedule(e,n)}:"auction"===a.mechanism?{phase:"participating",mechanism:"auction",consumer:a.consumer,state$:n,bid:e=>t.bid(e),leave:()=>t.leave()}:"timed_release"===a.mechanism?{phase:"participating",mechanism:"timed_release",consumer:a.consumer,state$:n,leave:()=>t.leave(),complete:()=>t.complete()}:"queue"===a.mechanism?{phase:"participating",mechanism:"queue",consumer:a.consumer,state$:n,leave:()=>t.leave()}:{phase:"participating",mechanism:"draw",consumer:a.consumer,state$:n,leave:()=>t.leave()};case"settling":return{phase:"settling",mechanism:a.mechanism,distribution:a.distribution,consumer:a.consumer};case"granted":return{phase:"granted",mechanism:a.mechanism,distribution:a.distribution,consumer:a.consumer,grant:a.grant,claim:()=>t.claim()};case"ended":return{phase:"ended",mechanism:a.mechanism,consumer:a.consumer,outcome:a.outcome}}throw new Error("Unknown sequence phase")}export{e as buildJourneyView};

package/dist/experiences/journey.d.ts

@@ -0,0 +1,89 @@
+import { ReadableAtom, WritableAtom } from 'nanostores';
+import { InternalFanfareSDK } from '../types';
+import { DistributionDisplayState, MonitorUpdate } from './distribution-monitor.types';
+import { JourneyEvent, JourneySnapshot, JourneyView, Participation } from './journey.types';
+import { ConsumerMe } from './types';
+export declare class ExperienceJourney {
+    private readonly experienceId;
+    private readonly sdk;
+    private readonly stateAtom;
+    private readonly store;
+    readonly state: ReadableAtom<JourneySnapshot>;
+    readonly view$: ReadableAtom<JourneyView>;
+    readonly latestEvent$: ReadableAtom<JourneyEvent | null>;
+    readonly events$: ReadableAtom<JourneyEvent[]>;
+    private pollTimer?;
+    private activeMonitor;
+    private grantExpiryTimer?;
+    private displayAtom;
+    private destroyed;
+    private operationQueue;
+    private readonly EVENT_BUFFER_LIMIT;
+    constructor(experienceId: string, sdk: InternalFanfareSDK);
+    getExperienceId(): string;
+    private start;
+    private reroute;
+    private retry;
+    destroy(): void;
+    resumeFromMe(me: ConsumerMe): Promise<boolean>;
+    refreshDistribution(): Promise<void>;
+    private enterDistributionInternal;
+    private enterActiveDistribution;
+    private bookAppointmentSlot;
+    private cancelAppointmentBooking;
+    private rescheduleAppointmentBooking;
+    private completeTimedRelease;
+    private bid;
+    private enterWait;
+    private leaveWait;
+    private enter;
+    private leave;
+    private leaveParticipation;
+    private claim;
+    ackEvent(eventId: string): void;
+    ackAllEvents(): void;
+    private routeAndLoadDistribution;
+    private resolveRouting;
+    private enterExperienceIfReady;
+    private buildView;
+    private mutate;
+    private flattenSnapshot;
+    private emitEvent;
+    private emitIfDistributionChanged;
+    private buildDistributionSummary;
+    private normalizeOffers;
+    private restoreFromStore;
+    private persist;
+    private setSnapshot;
+    private emitPhaseChanged;
+    private runSerializedOperation;
+    private transitionToParticipating;
+    private transitionToGranted;
+    private transitionToEnded;
+    applyMonitorUpdate(update: MonitorUpdate): void;
+    private startMonitorForParticipation;
+    private getDistributionModule;
+    stopRuntimeMonitoring(clearDisplay?: boolean): void;
+    private clearGrantExpiryTimer;
+    private rearmTimersIfNeeded;
+    getRuntimeBinding(): {
+        experienceId: string;
+        sequenceId: string;
+        participationId: string;
+        participationType: Exclude<Participation["type"], "waitlist">;
+    } | null;
+    startRuntimeMonitoring(): void;
+    getRuntimeDisplayAtom(): WritableAtom<DistributionDisplayState> | null;
+    applyRuntimeState(state: DistributionDisplayState | null): void;
+    reconcileSyncedSnapshot(snapshot: JourneySnapshot | null): void;
+    private ensureDisplayAtom;
+    private resetDisplayAtom;
+    private clearRuntimeDisplayState;
+    private enteredConsumer;
+    private mapEnterResultToUpdate;
+    private queueOutcome;
+    private deriveTerminalOutcomeForClosedDistribution;
+    private withGrantedConsumer;
+    private withTerminalConsumer;
+    private stopPolling;
+}

package/dist/experiences/journey.js

@@ -0,0 +1 @@
+import{atom as e,computed as t}from"nanostores";import{createError as i}from"../core/errors.js";import{isMoneyString as s,addMoney as n}from"../core/money.js";import{generateId as o}from"../core/utils.js";import{clearExperienceContext as r,clearSequenceContext as a,bindDistributionContext as d,upsertSequenceToken as c}from"../state/capability-token-registry.js";import{getEventBus as u}from"../state/events.js";import{getSDKStore as p}from"../state/store.js";import{NoSequenceAvailableError as h}from"./experience.module.js";import{buildJourneyView as m}from"./journey-view.js";import{createInitialSnapshot as l,getParticipation as y,getSequencePhase as g,normalizeSequenceState as I,getSequenceId as f,getDistribution as w,getConsumer as v,getOutcome as b,deriveSequenceState as A,getGrant as E,getSequenceState as q,getTarget as x,getGates as T,buildSnapshot as S,getOffers as D,createGrant as k,getAdmissionGrantExpiresAt as C}from"./journey.machine.js";class j{constructor(i,s){this.experienceId=i,this.sdk=s,this.store=p(),this.activeMonitor=null,this.displayAtom=null,this.destroyed=!1,this.operationQueue=Promise.resolve(),this.EVENT_BUFFER_LIMIT=20;const n=this.restoreFromStore(),o=n??l(this.experienceId),r=n?y(n):void 0;r&&"participating"===g(o)&&this.ensureDisplayAtom(r),this.stateAtom=e(o),this.state=this.stateAtom,this.view$=t(this.stateAtom,e=>this.buildView(e)),this.events$=t(this.stateAtom,e=>e.events),this.latestEvent$=t(this.stateAtom,e=>{if(!e.events.length)return null;const t=e.lastSeenEventId??"",i=e.events.filter(e=>e.id>t);return i.length?i[i.length-1]:null}),n?this.rearmTimersIfNeeded():this.persist()}getExperienceId(){return this.experienceId}async start(e){await this.runSerializedOperation(async()=>{e?.reset&&this.setSnapshot(l(this.experienceId)),"accessCode"in(e??{})&&this.mutate({accessCode:e?.accessCode??null}),await this.routeAndLoadDistribution(this.stateAtom.get().accessCode)})}async reroute(e={}){await this.runSerializedOperation(async()=>{"accessCode"in e&&this.mutate({accessCode:e.accessCode??null}),await this.routeAndLoadDistribution(e.accessCode??this.stateAtom.get().accessCode)})}async retry(){await this.runSerializedOperation(()=>this.routeAndLoadDistribution(this.stateAtom.get().accessCode))}destroy(){this.destroyed||(this.destroyed=!0,this.stopRuntimeMonitoring(!0),this.clearGrantExpiryTimer(),this.stopPolling(),r(this.experienceId),this.store.removeJourney(this.experienceId),this.stateAtom.set(l(this.experienceId)))}async resumeFromMe(e){const t=e.active.journeys.find(e=>e.experienceId===this.experienceId&&"routed"===e.journeyStage);if(!t||"routed"!==t.journeyStage)return!1;const i=this.stateAtom.get(),s=I({sequence:t.sequence});this.mutate({journeyStage:"routed",sequenceId:t.sequenceId,sequence:s,offers:this.normalizeOffers(t.offers)}),"routed"===i.journeyStage&&i.sequenceId!==t.sequenceId&&a(this.experienceId,i.sequenceId);try{await this.reroute()}catch{}return this.rearmTimersIfNeeded(),!0}async refreshDistribution(){await this.runSerializedOperation(async()=>{const e=this.stateAtom.get(),t=f(e);if(!t)throw i.validationError("Cannot refresh distribution before routing to a sequence");const s=await this.sdk.experiences.getCurrentDistributions(t),n=this.buildDistributionSummary(s,t),o=w(e);n&&d({experienceId:this.experienceId,sequenceId:t,distributionContext:n});const r=v(e);let a="open"===n?.lifecycle&&"waitlist"===r?.mechanism?void 0:r;const c=this.deriveTerminalOutcomeForClosedDistribution(a,n,b(e));a=this.withTerminalConsumer(a,c);const u=A({distribution:n,consumer:a,grant:E(e),outcome:c});this.mutate({sequence:u,distribution:n,consumer:a,outcome:c}),this.emitIfDistributionChanged(o,n)})}async enterDistributionInternal(e){const t=this.stateAtom.get(),s=w(t);if(!s||"open"!==s.lifecycle||s.type!==e)throw i.validationError(`No open ${e.replace(/_/g," ")} to enter`);const n={queue:this.sdk.queues,draw:this.sdk.draws,auction:this.sdk.auctions,timed_release:this.sdk.timedReleases},o=await n[e].enter(s.id,void 0),r=this.mapEnterResultToUpdate(e,o);if(r)return void this.applyMonitorUpdate(r);const a=this.enteredConsumer(e,s.id);"auction"===e&&await this.sdk.auctions.status(s.id),this.ensureDisplayAtom({id:s.id,type:e}),this.transitionToParticipating(a,s),this.emitEvent("sequence_change","success","user",`Entered ${e.replace(/_/g," ")}`,{distributionId:s.id})}async enterActiveDistribution(){await this.runSerializedOperation(async()=>{const e=w(this.stateAtom.get());if(!e||"open"!==e.lifecycle)throw i.validationError("No open distribution to enter");if("appointment"===e.type)throw i.validationError("Appointments are entered via bookAppointmentSlot()");await this.enterDistributionInternal(e.type)})}async bookAppointmentSlot(e,t){await this.runSerializedOperation(async()=>{const s=w(this.stateAtom.get());if(!s||"open"!==s.lifecycle||"appointment"!==s.type)throw i.validationError("No open appointment to book");const n=await this.sdk.appointments.book(s.id,e,t);this.sdk.appointments.bumpMonitorGeneration(s.id);const o=this.ensureDisplayAtom({id:s.id,type:"appointment"}),r=Math.max(0,Date.parse(n.startTime)-Date.now());o.set({type:"appointment",booking:{slotId:n.slotId,locationId:n.locationId,locationName:n.locationName,joinUrl:n.joinUrl,startTime:n.startTime,endTime:n.endTime,confirmationCode:n.confirmationCode,consumerStatus:n.consumerStatus},msUntilStart:r});const a={mechanism:"appointment",status:"booked",id:s.id,distributionId:s.id,slotId:n.slotId,locationId:n.locationId};this.transitionToParticipating(a,s),this.emitEvent("sequence_change","success","user","Booked appointment slot",{appointmentId:s.id,slotId:e,locationId:t})})}async cancelAppointmentBooking(e){await this.runSerializedOperation(async()=>{const t=this.stateAtom.get(),s=v(t);if("appointment"!==s?.mechanism)throw i.validationError("Not participating in an appointment");const n=this.displayAtom?.get(),o=n&&"appointment"===n.type?n.booking:void 0;if(!o)throw i.validationError("No booking details available to cancel");this.stopRuntimeMonitoring(!0),await this.sdk.appointments.cancel(s.distributionId??s.id??"",o.slotId,o.locationId??"",e),this.transitionToEnded({type:"cancelled",reason:e})})}async rescheduleAppointmentBooking(e,t){await this.runSerializedOperation(async()=>{const s=v(this.stateAtom.get());if("appointment"!==s?.mechanism)throw i.validationError("Not participating in an appointment");const n=await this.sdk.appointments.reschedule(s.distributionId??s.id??"",e,t);this.sdk.appointments.bumpMonitorGeneration(s.distributionId??s.id??"");const o=this.ensureDisplayAtom({id:s.distributionId??s.id??"",type:"appointment"}),r=Math.max(0,Date.parse(n.startTime)-Date.now());o.set({type:"appointment",booking:{slotId:n.slotId,locationId:n.locationId,locationName:n.locationName,joinUrl:n.joinUrl,startTime:n.startTime,endTime:n.endTime,confirmationCode:n.confirmationCode,consumerStatus:n.consumerStatus},msUntilStart:r}),this.emitEvent("sequence_change","info","user","Rescheduled appointment",{appointmentId:s.distributionId??s.id,newSlotId:e,newLocationId:t})})}async completeTimedRelease(){await this.runSerializedOperation(async()=>{const e=this.stateAtom.get(),t=v(e);if("timed_release"!==t?.mechanism||"entered"!==t.status)throw i.validationError("Not participating in a timed release");const s=await this.sdk.timedReleases.complete(t.distributionId??t.id??"");s?this.transitionToGranted(s):this.transitionToEnded({type:"completed"}),this.emitEvent("sequence_change","success","user","Completed timed release",{timedReleaseId:t.distributionId??t.id})})}async bid(e){await this.runSerializedOperation(async()=>{const t=this.stateAtom.get(),o=v(t);if("auction"!==o?.mechanism)throw i.validationError("No auction is available to bid on");const r=w(t),a=q(t),d=o.distributionId??o.id??r?.id??"",c=await this.sdk.auctions.bid(d,e),u="winning"===c.status?"winning":"outbid"===c.status?"outbid":"bidding",p="auction"===r?.details?.type?r.details:void 0,h=p?.bidIncrement,m=c.highestBid&&h&&s(c.highestBid)&&s(h)?n(c.highestBid,h):void 0,l=this.ensureDisplayAtom({id:d,type:"auction"});"enterable"===a?.phase&&r&&this.transitionToParticipating({mechanism:"auction",status:u,id:d,distributionId:d,currentBid:e,highestBid:c.highestBid},r),l.set({type:"auction",currentBid:e,highestBid:c.highestBid,bidCount:c.bidCount,status:u,currencyCode:p?.currencyCode,bidIncrement:h,minNextBid:m,closeAt:p?.closeAt??p?.endsAt})})}async enterWait(){await this.runSerializedOperation(async()=>{const e=this.stateAtom.get(),t=f(e),s=w(e),n=x(e),o=n?.waitlistId??s?.waitlistId,r="string"==typeof o?o:void 0;if(!t||!r)throw i.validationError("Waitlist is not available for this sequence");const a={mechanism:"waitlist",status:"waitlisted",id:(await this.sdk.waitlists.enter(r)).id,waitlistId:r},d=A({distribution:s,target:n,consumer:a});this.mutate({sequence:d,consumer:a}),this.emitEvent("sequence_change","info","user","Entered waitlist",{waitlistId:r})})}async leaveWait(){await this.runSerializedOperation(async()=>{const e=this.stateAtom.get(),t=v(e),i=x(e),s="waitlist"===t?.mechanism?t.waitlistId??i?.waitlistId??t.id:void 0;if(!s)return;await this.sdk.waitlists.leave(s);const n=w(e),o=A({distribution:n,target:i});this.mutate({sequence:o}),this.emitEvent("sequence_change","info","user","Left waitlist",{waitlistId:s})})}async enter(){const e=q(this.stateAtom.get());"enterable"!==e?.phase||"waitlist"!==e.mechanism?await this.enterActiveDistribution():await this.enterWait()}async leave(){const e=v(this.stateAtom.get());"waitlist"!==e?.mechanism?await this.leaveParticipation():await this.leaveWait()}async leaveParticipation(){await this.runSerializedOperation(async()=>{const e=this.stateAtom.get(),t=y(e);t&&(this.stopRuntimeMonitoring(!0),"queue"===t.type?await this.sdk.queues.leave(t.id):"draw"===t.type?await this.sdk.draws.leave(t.id):"auction"===t.type?await this.sdk.auctions.leave(t.id):"timed_release"===t.type&&await this.sdk.timedReleases.leave(t.id),this.transitionToEnded({type:"left"}),this.emitEvent("sequence_change","info","user","Left participation",{type:t.type}))})}claim(){const e=E(this.stateAtom.get());if(!e)throw i.validationError("No grant is available to claim");return this.emitEvent("sequence_change","success","user","Grant claimed",{distributionType:e.distributionType,distributionId:e.distributionId,sequenceId:e.sequenceId}),u().emit("journey:grant-claimed",{experienceId:this.experienceId,sequenceId:e.sequenceId,grant:e.token}),e}ackEvent(e){this.stateAtom.get().events.some(t=>t.id===e)&&this.mutate({lastSeenEventId:e})}ackAllEvents(){const e=this.stateAtom.get();if(!e.events.length)return;const t=e.events[e.events.length-1];this.mutate({lastSeenEventId:t.id})}async routeAndLoadDistribution(e){const t=this.stateAtom.get(),i=f(t),s=await this.resolveRouting(e);if(!s||this.destroyed)return;if(await this.enterExperienceIfReady(),this.destroyed)return;const n=await this.sdk.experiences.getCurrentDistributions(s.sequenceId);if(this.destroyed)return;const o=this.buildDistributionSummary(n,s.sequenceId);o&&d({experienceId:this.experienceId,sequenceId:s.sequenceId,distributionContext:o});const r=i===s.sequenceId,a=r?v(t):void 0;let c="open"===o?.lifecycle&&"waitlist"===a?.mechanism?void 0:a;const u=r?E(t):void 0,p=r?this.deriveTerminalOutcomeForClosedDistribution(c,o,b(t)):void 0;c=this.withTerminalConsumer(c,p);const h=!o&&r&&"routed"===t.journeyStage&&("granted"===t.sequence.phase||"ended"===t.sequence.phase||"mechanism"in t.sequence&&"waitlist"===t.sequence.mechanism)?t.sequence:A({distribution:o,consumer:c,grant:u,outcome:p});this.mutate({journeyStage:"routed",sequenceId:s.sequenceId,distribution:o,offers:s.offers,sequence:h,consumer:c,grant:u,outcome:p});const m=r?w(t):void 0;this.emitIfDistributionChanged(m,o)}async resolveRouting(e){const t=this.stateAtom.get(),i=f(t);let s;this.mutate({journeyStage:"routing"});try{s=await this.sdk.experiences.findSequence(this.experienceId,e)}catch(o){throw this.setSnapshot(t),this.emitEvent("error","error","user","Failed to route experience"),o}if(this.destroyed)return null;if("gated"===s.outcome&&s.selected){const e=s.selected.gates;return this.mutate({journeyStage:"gated",gates:e,selected:{sequence:s.selected.sequence,status:"gated"}}),this.emitEvent("requirement","info","user","Gates required",{gates:e}),null}if("no_access"===s.outcome||!s.selected)throw this.setSnapshot(t),this.emitEvent("error","error","user","No access available for this experience"),new h("No access available for this experience");const n=s.selected.sequence.id;return i&&i!==n&&a(this.experienceId,i),s.selected.capabilityGrant&&c({experienceId:this.experienceId,sequenceId:n,token:s.selected.capabilityGrant,expiresAt:s.selected.capabilityGrantExpiresAt}),i!==n&&this.emitEvent("reroute","info","user","Sequence changed",{previousSequenceId:i,sequenceId:n}),{sequenceId:n,offers:s.offers}}async enterExperienceIfReady(){const e=this.stateAtom.get();if(T(e).length>0)return;if(e.experience)return;const t=await this.sdk.experiences.enter(this.experienceId);this.destroyed||this.mutate({experience:t})}buildView(e){return m(e,{start:e=>this.start(e),reroute:e=>this.reroute(e),retry:()=>this.retry(),enter:()=>this.enter(),leave:()=>this.leave(),bid:e=>this.bid(e),complete:()=>this.completeTimedRelease(),book:(e,t)=>this.bookAppointmentSlot(e,t),cancel:e=>this.cancelAppointmentBooking(e),reschedule:(e,t)=>this.rescheduleAppointmentBooking(e,t),claim:()=>this.claim()},this.displayAtom)}mutate(e){if(this.destroyed)return;const t=this.stateAtom.get(),i={...this.flattenSnapshot(t),...e},s=Object.prototype.hasOwnProperty.call(e,"accessCode")?i.accessCode??void 0:t.accessCode,n=Object.prototype.hasOwnProperty.call(e,"target")||"waitlist"===i.consumer?.mechanism?i.target??void 0:void 0,o=S({base:{revision:t.revision,updatedAt:t.updatedAt,experienceId:t.experienceId,accessCode:s,experience:i.experience,events:i.events??t.events,lastSeenEventId:i.lastSeenEventId??t.lastSeenEventId},journeyStage:i.journeyStage??t.journeyStage,gates:i.gates,selected:i.selected,sequenceId:i.sequenceId,distribution:i.distribution,target:n,offers:i.offers,sequence:i.sequence,consumer:i.consumer,grant:i.grant,outcome:i.outcome});this.setSnapshot(o)}flattenSnapshot(e){return{journeyStage:e.journeyStage,gates:T(e),selected:"gated"===e.journeyStage?e.selected:void 0,sequenceId:f(e),distribution:w(e),target:x(e),offers:D(e),sequence:"routed"===e.journeyStage?e.sequence:void 0,consumer:v(e),grant:E(e),outcome:b(e),accessCode:e.accessCode,experience:e.experience,events:e.events,lastSeenEventId:e.lastSeenEventId}}emitEvent(e,t,i,s,n){const r=this.stateAtom.get(),a={id:o(),ts:Date.now(),kind:e,severity:t,audience:i,message:s,detail:n},d=[...r.events,a],c=d.length>this.EVENT_BUFFER_LIMIT?d.slice(d.length-this.EVENT_BUFFER_LIMIT):d;this.mutate({events:c})}emitIfDistributionChanged(e,t){e?.id===t?.id&&e?.lifecycle===t?.lifecycle||this.emitEvent("distribution_change","info","user","Distribution context changed",{previous:e,next:t})}buildDistributionSummary(e,t){return e.active?{type:e.active.type,id:e.active.id,sequenceId:t,lifecycle:"open",details:e.active.details,opensAt:e.active.details.openAt,closesAt:e.active.details.closeAt,updatedAt:Date.now()}:e.upcoming?{type:e.upcoming.type,id:e.upcoming.id,sequenceId:t,lifecycle:"scheduled",startsAt:e.upcoming.startsAt,opensAt:e.upcoming.startsAt,waitlistId:e.upcoming.waitlistId,updatedAt:Date.now()}:e.recentPast?{type:e.recentPast.type,id:e.recentPast.id,sequenceId:t,lifecycle:"closed",closesAt:e.recentPast.endedAt,updatedAt:Date.now()}:void 0}normalizeOffers(e){return Array.isArray(e)?e.filter(Boolean):[]}restoreFromStore(){const e=this.store.activeJourneys;if(!e||!e[this.experienceId])return null;const t=e[this.experienceId];return z(t)?t:(this.store.removeJourney(this.experienceId),null)}persist(){this.store.setJourneyState(this.experienceId,this.stateAtom.get())}setSnapshot(e,t={}){if(this.destroyed)return;const i=this.stateAtom.get();this.stateAtom.set(e),!1!==t.persist&&this.persist(),this.emitPhaseChanged(i,e)}emitPhaseChanged(e,t){const i=e.journeyStage,s="routed"===i?g(e):void 0,n=t.journeyStage,o="routed"===n?g(t):void 0;i===n&&s===o||u().emit("journey:phase-changed",{experienceId:this.experienceId,journeyStage:n,sequencePhase:o})}runSerializedOperation(e){const t=this.operationQueue.then(async()=>{if(this.destroyed)throw i.notInitialized("Journey has been destroyed");return e()});return this.operationQueue=t.then(()=>{},()=>{}),t}transitionToParticipating(e,t){const i=A({distribution:t,consumer:e});this.mutate({sequence:i,consumer:e,distribution:t})}transitionToGranted(e,t){if(this.destroyed)return;const i=this.stateAtom.get(),s=w(i),n=f(i);if(!s||!n)return void this.transitionToEnded({type:"closed",reason:"missing_distribution"});if(void 0!==t&&Date.now()>=t)return void this.transitionToEnded({type:"expired"});const o=k({token:e,distribution:s,sequenceId:n,experienceId:this.experienceId,expiresAt:t}),r=this.withGrantedConsumer(v(i),s),a=A({distribution:s,consumer:r,grant:o});this.mutate({sequence:a,consumer:r,grant:o,outcome:void 0}),this.stopRuntimeMonitoring(!0),this.clearGrantExpiryTimer(),void 0!==t&&(this.grantExpiryTimer=setTimeout(()=>this.transitionToEnded({type:"expired"}),t-Date.now())),this.emitEvent("sequence_change","success","user","Grant issued",{grant:e}),u().emit("journey:granted",{experienceId:this.experienceId,sequenceId:n,grant:e})}transitionToEnded(e){if(this.destroyed)return;const t=this.stateAtom.get(),i=w(t),s={...e,distributionType:e.distributionType??i?.type,distributionId:e.distributionId??i?.id,at:e.at??/* @__PURE__ */(new Date).toISOString()},n=this.withTerminalConsumer(v(t),s),o=A({distribution:i,consumer:n,outcome:s});this.mutate({sequence:o,outcome:s,grant:void 0,consumer:n}),this.stopRuntimeMonitoring(!0),this.clearGrantExpiryTimer(),this.emitEvent("sequence_change","expired"===s.type?"warning":"info","user","Sequence ended",{outcome:s}),u().emit("journey:ended",{experienceId:this.experienceId,sequenceId:f(this.stateAtom.get()),outcome:s})}applyMonitorUpdate(e){this.destroyed||("granted"!==e.type?this.transitionToEnded(e.outcome):this.transitionToGranted(e.token,e.expiresAt))}startMonitorForParticipation(e){if("waitlist"===e.type)return;const t=this.stateAtom.get(),i=w(t),s={displayAtom:this.ensureDisplayAtom(e)};"draw"===e.type&&"draw"===i?.details?.type&&i.details.drawTime&&(s.drawTime=i.details.drawTime);const n=this.getDistributionModule(e.type);n.startMonitoring(e.id,s,e=>this.applyMonitorUpdate(e)),this.activeMonitor={type:e.type,id:e.id,stop:()=>n.stopMonitoring(e.id)}}getDistributionModule(e){switch(e){case"queue":return this.sdk.queues;case"draw":return this.sdk.draws;case"auction":return this.sdk.auctions;case"timed_release":return this.sdk.timedReleases;case"appointment":return this.sdk.appointments;default:throw new Error(`Unknown distribution type: ${e}`)}}stopRuntimeMonitoring(e=!1){this.activeMonitor&&(this.activeMonitor.stop(),this.activeMonitor=null),e&&this.clearRuntimeDisplayState()}clearGrantExpiryTimer(){this.grantExpiryTimer&&(clearTimeout(this.grantExpiryTimer),this.grantExpiryTimer=void 0)}rearmTimersIfNeeded(){if(this.destroyed)return;const e=this.stateAtom.get();if("granted"!==g(e)||this.grantExpiryTimer)return;const t=C(e);if(!t)return;const i=t-Date.now();i<=0?this.transitionToEnded({type:"expired"}):this.grantExpiryTimer=setTimeout(()=>this.transitionToEnded({type:"expired"}),i)}getRuntimeBinding(){const e=this.stateAtom.get(),t=g(e),i=y(e),s=f(e);return"participating"===t&&i&&s&&"waitlist"!==i.type?{experienceId:this.experienceId,sequenceId:s,participationId:i.id,participationType:i.type}:null}startRuntimeMonitoring(){const e=this.getRuntimeBinding();if(!e)return;const t=this.activeMonitor;t&&t.id===e.participationId&&t.type===e.participationType&&this.displayAtom||(this.stopRuntimeMonitoring(!1),this.startMonitorForParticipation({id:e.participationId,type:e.participationType}))}getRuntimeDisplayAtom(){return this.displayAtom}applyRuntimeState(e){if(!e)return void this.clearRuntimeDisplayState();const t=this.getRuntimeBinding();if(!t)return;this.ensureDisplayAtom({id:t.participationId,type:t.participationType}).set(e)}reconcileSyncedSnapshot(e){if(this.destroyed)return;const t=this.getRuntimeBinding();if(!e)return this.stopRuntimeMonitoring(!0),this.clearGrantExpiryTimer(),void this.setSnapshot(l(this.experienceId),{persist:!1});if(!z(e))return;const i=this.stateAtom.get();if(i.revision===e.revision&&i.updatedAt===e.updatedAt)return;const s=y(e),n=g(e),o="participating"===n&&s&&"waitlist"!==s.type?{sequenceId:f(e),participationId:s.id,participationType:s.type}:null;o?t&&t.sequenceId===o.sequenceId&&t.participationId===o.participationId&&t.participationType===o.participationType||this.resetDisplayAtom(o.participationType):this.displayAtom=null,this.setSnapshot(e,{persist:!1}),"participating"===n&&s?this.ensureDisplayAtom(s):this.stopRuntimeMonitoring(!0),this.clearGrantExpiryTimer(),this.rearmTimersIfNeeded()}ensureDisplayAtom(e){return this.resetDisplayAtom(e.type),this.displayAtom}resetDisplayAtom(t){this.displayAtom&&this.displayAtom.get().type===t?this.displayAtom.set({type:t}):this.displayAtom=e({type:t})}clearRuntimeDisplayState(){const e=this.getRuntimeBinding();e?this.resetDisplayAtom(e.participationType):this.displayAtom=null}enteredConsumer(e,t){switch(e){case"queue":return{mechanism:"queue",status:"queued",id:t,distributionId:t};case"draw":return{mechanism:"draw",status:"entered",id:t,distributionId:t};case"auction":return{mechanism:"auction",status:"bidding",id:t,distributionId:t};case"timed_release":return{mechanism:"timed_release",status:"entered",id:t,distributionId:t}}}mapEnterResultToUpdate(e,t){if("auction"===e||void 0===t)return null;if("queue"===e){const e=t;return"QUEUED"===e.status?null:"GRANTED"===e.status||"COMPLETED"===e.status?{type:"granted",token:e.admissionGrant,expiresAt:"expiresAt"in e&&e.expiresAt?new Date(e.expiresAt).getTime():void 0}:{type:"ended",outcome:{type:this.queueOutcome(e),reason:"reason"in e?e.reason:void 0}}}if("draw"===e){const e=t;return"ENTERED"===e.status?null:"WON"===e.status||"COMPLETED"===e.status?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:{type:"ended",outcome:{type:"DENIED"===e.status?"denied":"lost",reason:"reason"in e?e.reason:void 0}}}const i=t;return"ENTERED"===i.status?null:"COMPLETED"===i.status?{type:"ended",outcome:{type:"completed"}}:{type:"ended",outcome:{type:"LEFT"===i.status?"left":"denied",reason:"reason"in i?i.reason:void 0}}}queueOutcome(e){return"LEFT"===e.status?"left":"EXPIRED"===e.status?"expired":"COMPLETED"===e.status?"completed":"DENIED"===e.status?"denied":"closed"}deriveTerminalOutcomeForClosedDistribution(e,t,i){if(i)return i;if(t&&"closed"===t.lifecycle&&e)switch(e.mechanism){case"draw":case"auction":return{type:"lost",distributionType:t.type,distributionId:t.id};case"waitlist":return{type:"expired",distributionType:t.type,distributionId:t.id};default:return{type:"closed",distributionType:t.type,distributionId:t.id}}}withGrantedConsumer(e,t){switch(e?.mechanism){case"queue":return{...e,status:"granted"};case"draw":case"auction":return{...e,status:"won"};case"timed_release":return{...e,status:"completed"};case void 0:if("queue"===t.type)return{mechanism:"queue",status:"granted",id:t.id,distributionId:t.id};if("draw"===t.type)return{mechanism:"draw",status:"won",id:t.id,distributionId:t.id};if("auction"===t.type)return{mechanism:"auction",status:"won",id:t.id,distributionId:t.id};if("timed_release"===t.type)return{mechanism:"timed_release",status:"completed",id:t.id,distributionId:t.id};throw i.validationError("Distribution does not produce grants");default:if(!e)throw i.validationError("Grant requires a consumer state");return e}}withTerminalConsumer(e,t){if(e){if(!t)return e;switch(e.mechanism){case"queue":return"left"===t.type?{...e,status:"left"}:"denied"===t.type?{...e,status:"denied",deniedReason:t.reason}:"completed"===t.type?{...e,status:"completed"}:{...e,status:"not_queued"};case"draw":return"denied"===t.type?{...e,status:"denied",deniedReason:t.reason}:"completed"===t.type?{...e,status:"completed"}:"won"===t.type?{...e,status:"won"}:{...e,status:"not_entered"};case"auction":return"won"===t.type?{...e,status:"won"}:{...e,status:"lost"};case"timed_release":return"left"===t.type?{...e,status:"left"}:"denied"===t.type?{...e,status:"denied",deniedReason:t.reason}:"completed"===t.type?{...e,status:"completed"}:{...e,status:"not_entered"};case"appointment":return"cancelled"===t.type?{...e,status:"cancelled"}:"no_show"===t.type?{...e,status:"no_show"}:"completed"===t.type?{...e,status:"completed"}:{...e,status:"not_booked"};case"waitlist":return"left"===t.type?{...e,status:"left"}:{...e,status:"expired"}}}}stopPolling(){this.pollTimer&&(clearInterval(this.pollTimer),this.pollTimer=void 0)}}const R=["revision","updatedAt","experienceId","accessCode","experience","events","lastSeenEventId","journeyStage"],M={ready:new Set(R),routing:new Set(R),gated:/* @__PURE__ */new Set([...R,"gates","selected"]),routed:/* @__PURE__ */new Set([...R,"sequenceId","offers","sequence"])},_=/* @__PURE__ */new Set(["sequence","status"]),O=/* @__PURE__ */new Set(["phase","reason","mechanism","distribution","target","consumer","grant","outcome"]),N=/* @__PURE__ */new Set(["type","id","sequenceId","lifecycle","startsAt","opensAt","closesAt","settlesAt","waitlistId","details","updatedAt"]),B=/* @__PURE__ */new Set(["status","id","distributionId","waitlistId","enteredAt","admissionGrant","grantedAt","deniedReason","position","highestBid","currentBid","slotId","locationId","bookedAt","checkedInAt","completedAt","cancelledAt","noShowAt","notifiedAt"]),P=/* @__PURE__ */new Set(["token","distributionType","distributionId","sequenceId","experienceId","issuedAt","expiresAt","handoffUrl"]),G=/* @__PURE__ */new Set(["type","reason","at","distributionType","distributionId"]);function U(e,t){return!!e&&"object"==typeof e&&!Array.isArray(e)&&Object.keys(e).every(e=>t.has(e))}function z(e){if(!e||"object"!=typeof e)return!1;const t=e,i=t.journeyStage;if("ready"!==i&&"routing"!==i&&"gated"!==i&&"routed"!==i)return!1;if(!U(t,M[i]))return!1;if(void 0!==t.selected&&!U(t.selected,_))return!1;if("routed"!==i)return!0;const s=t.sequence;if(!function(e){return!(!U(e,O)||"distribution"in e&&!U(e.distribution,N)||"target"in e&&!U(e.target,N)||"consumer"in e&&!U(e.consumer,B)||"grant"in e&&!U(e.grant,P)||"outcome"in e&&!U(e.outcome,G))}(s))return!1;const n=s.phase;return"unavailable"===n||"scheduled"===n||"enterable"===n||"participating"===n||"settling"===n||"granted"===n||"ended"===n}export{j as ExperienceJourney};

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

@@ -0,0 +1,79 @@
+import { AdmissionGrant, DistributionSummary, GatedSnapshot, JourneySnapshot, JourneyStage, MechanismConsumerState, Participation, ReadySnapshot, RoutedSnapshot, RoutingGate, RoutingOffer, SequenceMechanism, SequenceOutcome, SequenceState, SequenceTargetState } from './journey.types';
+import { ExperienceSession, Sequence } from './types';
+export declare class SnapshotInvariantError extends Error {
+    constructor(phase: string, missing: string);
+}
+export declare function isGateState(state: JourneySnapshot): state is GatedSnapshot;
+export declare function isRoutedState(state: JourneySnapshot): state is RoutedSnapshot;
+export declare function getGates(state: JourneySnapshot): RoutingGate[];
+export declare function getSequenceId(state: JourneySnapshot): string | undefined;
+export declare function getDistribution(state: JourneySnapshot): DistributionSummary | undefined;
+export declare function getTarget(state: JourneySnapshot): SequenceTargetState | undefined;
+export declare function getConsumer(state: JourneySnapshot): MechanismConsumerState | undefined;
+export declare function getParticipation(state: JourneySnapshot): Participation | undefined;
+export declare function getAdmissionGrant(state: JourneySnapshot): string | undefined;
+export declare function getGrant(state: JourneySnapshot): AdmissionGrant | undefined;
+export declare function getAdmissionGrantExpiresAt(state: JourneySnapshot): number | undefined;
+export declare function getOutcome(state: JourneySnapshot): SequenceOutcome | undefined;
+export declare function getSelected(state: JourneySnapshot): GatedSnapshot["selected"] | undefined;
+export declare function getOffers(state: JourneySnapshot): RoutingOffer[];
+export declare function getSequencePhase(state: JourneySnapshot): SequenceState["phase"];
+export declare function getSequenceState(state: JourneySnapshot): SequenceState | undefined;
+export declare function createInitialSnapshot(experienceId: string): ReadySnapshot;
+interface SnapshotBase {
+    revision: number;
+    updatedAt: number;
+    experienceId: string;
+    accessCode?: string;
+    experience?: ExperienceSession;
+    events: JourneySnapshot["events"];
+    lastSeenEventId?: string;
+}
+export declare function extractBase(state: JourneySnapshot): SnapshotBase;
+export declare function buildSnapshot(params: {
+    base: SnapshotBase;
+    journeyStage: JourneyStage;
+    gates?: RoutingGate[];
+    selected?: {
+        sequence: Sequence;
+        status: "gated";
+    };
+    sequenceId?: string;
+    offers?: RoutingOffer[];
+    sequence?: SequenceState;
+    distribution?: DistributionSummary;
+    target?: SequenceTargetState;
+    consumer?: MechanismConsumerState;
+    grant?: AdmissionGrant;
+    outcome?: SequenceOutcome;
+}): JourneySnapshot;
+export declare function validateSequenceState(data: SequenceState): SequenceState;
+export declare function createGrant(params: {
+    token: string;
+    distribution: DistributionSummary;
+    sequenceId: string;
+    experienceId: string;
+    expiresAt?: number;
+}): AdmissionGrant;
+export declare function deriveSequenceState(params: {
+    distribution?: DistributionSummary;
+    target?: SequenceTargetState;
+    consumer?: MechanismConsumerState;
+    grant?: AdmissionGrant;
+    outcome?: SequenceOutcome;
+}): SequenceState;
+export declare function normalizeSequenceState(params: {
+    sequence: SequenceState;
+    distribution?: DistributionSummary;
+    target?: SequenceTargetState;
+    consumer?: MechanismConsumerState;
+    grant?: AdmissionGrant;
+    outcome?: SequenceOutcome;
+}): SequenceState;
+export declare function sequenceDistribution(sequence: SequenceState): DistributionSummary | undefined;
+export declare function sequenceTarget(sequence: SequenceState): SequenceTargetState | undefined;
+export declare function withMechanism(mechanism: SequenceMechanism, consumer: unknown): MechanismConsumerState;
+export declare function stripMechanism<T extends {
+    mechanism: SequenceMechanism;
+}>(consumer: T): Omit<T, "mechanism">;
+export {};

package/dist/experiences/journey.machine.js

@@ -0,0 +1 @@
+class e extends Error{constructor(e,t){super(`SnapshotInvariantError: phase '${e}' requires ${t}`),this.name="SnapshotInvariantError"}}function t(e){return"gated"===e.journeyStage}function n(e){return"routed"===e.journeyStage}function i(e){return t(e)?e.gates:[]}function r(e){return n(e)?e.sequenceId:void 0}function s(e){if(!n(e))return;const t=e.sequence;return"distribution"in t?t.distribution:void 0}function o(e){if(!n(e))return;const t=e.sequence;return"target"in t?t.target:void 0}function u(e){if(!n(e))return;const t=e.sequence;return"mechanism"in t?S(t.mechanism,t.consumer):void 0}function a(e){if(!n(e))return;if("participating"!==e.sequence.phase)return;const t=e.sequence,i=t.consumer,r="waitlist"===t.mechanism?D(i.waitlistId)??D(i.id)??o(e)?.waitlistId:D(i.distributionId)??D(i.id)??s(e)?.id;return r?{id:r,type:t.mechanism}:void 0}function c(e){return d(e)?.token}function d(e){return n(e)&&"granted"===e.sequence.phase?e.sequence.grant:void 0}function m(e){const t=d(e);if(t?.expiresAt)return new Date(t.expiresAt).getTime()}function h(e){return n(e)&&"ended"===e.sequence.phase?e.sequence.outcome:void 0}function p(e){return t(e)?e.selected:void 0}function l(e){return n(e)?e.offers:[]}function w(e){return n(e)?e.sequence.phase:"unavailable"}function f(e){return n(e)?e.sequence:void 0}function g(e){return{revision:1,updatedAt:Date.now(),journeyStage:"ready",experienceId:e,events:[],lastSeenEventId:void 0}}function b(t){const n=function(e){return{...e,revision:e.revision+1,updatedAt:Date.now()}}(t.base);switch(t.journeyStage){case"ready":return{...n,journeyStage:"ready"};case"routing":return{...n,journeyStage:"routing"};case"gated":return{...n,journeyStage:"gated",gates:t.gates??[],selected:t.selected};case"routed":{if(!t.sequenceId)throw new e("routed","sequenceId");const i=t.sequence??q({distribution:t.distribution,target:t.target,consumer:t.consumer,grant:t.grant,outcome:t.outcome});return y(i),{...n,journeyStage:"routed",sequenceId:t.sequenceId,offers:t.offers??[],sequence:i}}}throw new e(String(t.journeyStage),"known journeyStage")}function y(t){const n=t;switch(t.phase){case"unavailable":default:return t;case"scheduled":if(!("mechanism"in n))throw new e("scheduled","mechanism");if("waitlist"===n.mechanism)throw new e("scheduled","primary mechanism");if(!("distribution"in n))throw new e("scheduled","distribution");if(!("consumer"in n))throw new e("scheduled","consumer");return t;case"enterable":case"participating":if(!("mechanism"in n))throw new e(t.phase,"mechanism");if("waitlist"===n.mechanism){if(!("target"in n))throw new e(t.phase,"target")}else if(!("distribution"in n))throw new e(t.phase,"distribution");if(!("consumer"in n))throw new e(t.phase,"consumer");return t;case"settling":if(!("mechanism"in n))throw new e("settling","mechanism");if("draw"!==t.mechanism&&"auction"!==t.mechanism)throw new e("settling","draw or auction mechanism");if(!("distribution"in n))throw new e("settling","distribution");if(!("consumer"in n))throw new e("settling","consumer");return t;case"granted":if(!("mechanism"in n))throw new e("granted","mechanism");if("appointment"===n.mechanism||"waitlist"===n.mechanism)throw new e("granted","grant-producing mechanism");if(!("distribution"in n))throw new e("granted","distribution");if(!("consumer"in n))throw new e("granted","consumer");if(!("grant"in n))throw new e("granted","grant");return t;case"ended":if(!("mechanism"in n))throw new e("ended","mechanism");if("waitlist"===n.mechanism){if(!("target"in n))throw new e("ended","target")}else if(!("distribution"in n))throw new e("ended","distribution");if(!("consumer"in n))throw new e("ended","consumer");if(!t.outcome)throw new e("ended","outcome");return t}}function I(t){if("appointment"===t.distribution.type)throw new e("granted","grant-producing mechanism");return{token:t.token,distributionType:t.distribution.type,distributionId:t.distribution.id,sequenceId:t.sequenceId,experienceId:t.experienceId,expiresAt:t.expiresAt?new Date(t.expiresAt).toISOString():void 0}}function q(e){const{distribution:t,target:n,consumer:i,grant:r,outcome:s}=e;if("waitlist"===i?.mechanism||n){const e=n??A(t);if(!e)return{phase:"unavailable",reason:"missing_waitlist"};const r="waitlist"===i?.mechanism?x(i):{status:"not_waitlisted"},o=s??k("waitlist",r);return o?{phase:"ended",mechanism:"waitlist",target:e,consumer:r,outcome:o}:{phase:"not_waitlisted"===r.status?"enterable":"participating",mechanism:"waitlist",target:e,consumer:r}}if(!t)return{phase:"unavailable"};const o=t.type,u=i&&i.mechanism===o?x(i):j(t);if(r)return r.expiresAt&&Date.now()>new Date(r.expiresAt).getTime()?"open"===t.lifecycle?{phase:"enterable",mechanism:o,distribution:t,consumer:j(t)}:_(o,t,u,{type:"expired"}):{phase:"granted",mechanism:o,distribution:t,consumer:u,grant:r};const a=s??k(o,u);if(a)return _(o,t,u,a);if(function(e,t){const n=t.status;switch(e){case"queue":return"queued"===n;case"draw":case"timed_release":return"entered"===n;case"auction":return"bidding"===n||"winning"===n||"outbid"===n;case"appointment":return"booked"===n||"checked_in"===n}}(o,u))return{phase:"participating",mechanism:o,distribution:t,consumer:u};if("scheduled"===t.lifecycle&&t.waitlistId){const e=A(t);if(e)return{phase:"enterable",mechanism:"waitlist",target:e,consumer:{status:"not_waitlisted"}}}return"scheduled"===t.lifecycle?{phase:"scheduled",mechanism:o,distribution:t,consumer:u}:"open"===t.lifecycle?{phase:"enterable",mechanism:o,distribution:t,consumer:u}:"settling"!==t.lifecycle||"draw"!==o&&"auction"!==o?_(o,t,u,{type:"closed"}):{phase:"settling",mechanism:o,distribution:t,consumer:u}}function v(e){try{return y(e.sequence)}catch{return q({distribution:e.distribution,target:e.target,consumer:e.consumer,grant:e.grant,outcome:e.outcome})}}function S(e,t){return{...t,mechanism:e}}function x(e){const{mechanism:t,...n}=e;return n}function _(e,t,n,i){return{phase:"ended",mechanism:e,distribution:t,consumer:n,outcome:{...i,distributionType:i.distributionType??t.type,distributionId:i.distributionId??t.id,at:i.at??/* @__PURE__ */(new Date).toISOString()}}}function A(e){if(e?.waitlistId)return{type:e.type,id:e.id,sequenceId:e.sequenceId,lifecycle:e.lifecycle,opensAt:e.opensAt,closesAt:e.closesAt,waitlistId:e.waitlistId}}function j(e){switch(e.type){case"queue":return{status:"not_queued",distributionId:e.id};case"draw":case"timed_release":return{status:"not_entered",distributionId:e.id};case"auction":return{status:"not_bid",distributionId:e.id};case"appointment":return{status:"not_booked",distributionId:e.id}}}function k(e,t){const n=t.status,i=t.deniedReason;switch(e){case"queue":case"timed_release":return"completed"===n?{type:"completed"}:"denied"===n?{type:"denied",reason:i}:"left"===n?{type:"left"}:void 0;case"draw":return"completed"===n?{type:"completed"}:"denied"===n?{type:"denied",reason:i}:void 0;case"auction":return"lost"===n?{type:"lost"}:void 0;case"appointment":return"completed"===n?{type:"completed"}:"cancelled"===n?{type:"cancelled"}:"no_show"===n?{type:"no_show"}:void 0;case"waitlist":return"expired"===n?{type:"expired"}:"left"===n?{type:"left"}:void 0}}function D(e){return"string"==typeof e&&e.length>0?e:void 0}export{e as SnapshotInvariantError,b as buildSnapshot,I as createGrant,g as createInitialSnapshot,q as deriveSequenceState,c as getAdmissionGrant,m as getAdmissionGrantExpiresAt,u as getConsumer,s as getDistribution,i as getGates,d as getGrant,l as getOffers,h as getOutcome,a as getParticipation,p as getSelected,r as getSequenceId,w as getSequencePhase,f as getSequenceState,o as getTarget,t as isGateState,n as isRoutedState,v as normalizeSequenceState,x as stripMechanism,y as validateSequenceState,S as withMechanism};