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

package/dist/auctions/auction.sequence.d.ts

@@ -0,0 +1,263 @@
+import { AdmissionGrant, AuctionConsumerStatus, SequenceOutcome } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { ReadableAtom } from 'nanostores';
+import { AuctionDisplayState } from '../experiences/distribution-monitor.types';
+import { DistributionSummary, WaitlistAttachment, WaitlistAttachmentView } from '../experiences/journey.types';
+/**
+ * Auction participation facts for one consumer.
+ *
+ * The server is authoritative for every field. Timestamps are ISO 8601 strings,
+ * and bid amounts are decimal money strings. Optional fields are present only
+ * after the matching auction lifecycle event has occurred.
+ */
+export interface AuctionSequenceConsumerState {
+    /** Server auction status for this consumer. */
+    status: AuctionConsumerStatus;
+    /** Auction participation id, when the server has created one. */
+    id?: string;
+    /** Distribution id this auction participation belongs to. */
+    distributionId?: string;
+    /** ISO 8601 timestamp for when the consumer first bid. */
+    enteredAt?: string;
+    /** Opaque admission credential token, when one has been issued inline. */
+    admissionGrant?: string;
+    /** ISO 8601 timestamp for when the consumer won and was granted admission. */
+    grantedAt?: string;
+    /** Server-provided denial reason for denied auction outcomes. */
+    deniedReason?: string;
+    /** Highest known auction bid as a decimal money string. */
+    highestBid?: string;
+    /** Consumer's current bid as a decimal money string. */
+    currentBid?: string;
+}
+/**
+ * An auction sequence as seen by one consumer.
+ *
+ * Lifecycle: scheduled -> enterable -> participating -> settling -> granted or
+ * ended. The first bid is the entry: `bid()` from `enterable` creates the
+ * participation. Settlement is server-driven; the client observes `settling`
+ * and waits.
+ */
+export type AuctionSequence = AuctionScheduled | AuctionEnterable | AuctionParticipating | AuctionSettling | AuctionGranted | AuctionEnded;
+/**
+ * The auction exists but bidding has not opened yet.
+ */
+export interface AuctionScheduled {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; scheduled auctions cannot be bid on yet. */
+    phase: "scheduled";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Scheduled-only waitlist attachment, cleared when the auction opens. */
+    waitlist?: WaitlistAttachment;
+}
+/**
+ * Bidding is open and this consumer has not bid yet.
+ */
+export interface AuctionEnterable {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; `bid()` is legal on the matching view. */
+    phase: "enterable";
+    /** Open auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction facts before the first bid. */
+    consumer: AuctionSequenceConsumerState;
+}
+/**
+ * The consumer has bid and is participating in the auction.
+ */
+export interface AuctionParticipating {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; auction display and bidding are live. */
+    phase: "participating";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction participation facts. */
+    consumer: AuctionSequenceConsumerState;
+}
+/**
+ * The auction has closed and the server is determining the outcome.
+ */
+export interface AuctionSettling {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; no consumer action is legal while settling. */
+    phase: "settling";
+    /** Settling auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction participation facts during settlement. */
+    consumer: AuctionSequenceConsumerState;
+}
+/**
+ * The auction has issued an admission grant to this consumer.
+ */
+export interface AuctionGranted {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; `claim()` is legal on the matching view. */
+    phase: "granted";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction facts associated with the grant. */
+    consumer: AuctionSequenceConsumerState;
+    /** Admission credential issued by the server for this auction win. */
+    grant: AdmissionGrant;
+}
+/**
+ * The auction journey is terminal for this consumer.
+ */
+export interface AuctionEnded {
+    /** Mechanism discriminator for auction narrowing. */
+    mechanism: "auction";
+    /** Phase discriminator; no auction actions are legal after this phase. */
+    phase: "ended";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction facts at the terminal outcome. */
+    consumer: AuctionSequenceConsumerState;
+    /** Server-derived terminal outcome for the auction participation. */
+    outcome: SequenceOutcome;
+}
+/**
+ * Auction views exposed by `JourneyView.sequence`.
+ *
+ * The view lifecycle mirrors the auction sequence lifecycle. Actions exist only
+ * on the phases where they are legal, and each action may reject if the server
+ * has moved the sequence before the request is handled.
+ */
+export type AuctionSequenceView = AuctionScheduledView | AuctionEnterableView | AuctionParticipatingView | AuctionSettlingView | AuctionGrantedView | AuctionEndedView;
+/**
+ * Scheduled auction view rendered before bidding opens.
+ */
+export interface AuctionScheduledView {
+    /** Phase discriminator; no auction action is legal yet. */
+    phase: "scheduled";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** ISO 8601 opening timestamp chosen from the distribution start/open time. */
+    startsAt?: string;
+    /** Scheduled-only waitlist actions; this attachment never grants access. */
+    waitlist?: WaitlistAttachmentView;
+}
+/**
+ * Enterable auction view rendered when the first bid can be placed.
+ */
+export interface AuctionEnterableView {
+    /** Phase discriminator; `bid()` is legal on this view. */
+    phase: "enterable";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Open auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction facts before the first bid. */
+    consumer: AuctionSequenceConsumerState;
+    /**
+     * Place the first auction bid.
+     *
+     * Legal only while this view is current. `amount` is a decimal money string.
+     * The promise rejects if bidding is closed, the amount is invalid, or the
+     * server rejects the bid.
+     */
+    bid(amount: string): Promise<void>;
+}
+/**
+ * Participating auction view rendered while the consumer is bidding.
+ */
+export interface AuctionParticipatingView {
+    /** Phase discriminator; `bid()` and `leave()` are legal on this view. */
+    phase: "participating";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Consumer auction participation facts. */
+    consumer: AuctionSequenceConsumerState;
+    /** Live auction display facts, such as highest bid, bid count, and close time. */
+    display$: ReadableAtom<AuctionDisplayState>;
+    /**
+     * Place or raise an auction bid.
+     *
+     * Legal only while this view is current. `amount` is a decimal money string.
+     * The promise rejects if the amount is below the minimum increment, bidding is
+     * closed, or the server rejects the bid.
+     */
+    bid(amount: string): Promise<void>;
+    /**
+     * Leave the auction participation.
+     *
+     * Legal only while this view is current. The promise rejects if the consumer
+     * is no longer participating or the server rejects the leave request.
+     */
+    leave(): Promise<void>;
+}
+/**
+ * Settling auction view rendered while the server computes the auction result.
+ */
+export interface AuctionSettlingView {
+    /** Phase discriminator; no auction action is legal while settling. */
+    phase: "settling";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Settling auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction participation facts during settlement. */
+    consumer: AuctionSequenceConsumerState;
+}
+/**
+ * Granted auction view rendered for a winning auction participation.
+ */
+export interface AuctionGrantedView {
+    /** Phase discriminator; `claim()` is legal on this view. */
+    phase: "granted";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Auction distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "auction";
+    };
+    /** Consumer auction facts associated with the grant. */
+    consumer: AuctionSequenceConsumerState;
+    /** Admission credential issued by the server for this auction win. */
+    grant: AdmissionGrant;
+    /**
+     * Claim the auction admission credential for handoff.
+     *
+     * Legal only while this view is current. It returns the credential
+     * synchronously and may throw if the journey has already left the granted
+     * phase.
+     */
+    claim(): AdmissionGrant;
+}
+/**
+ * Ended auction view rendered once the auction journey is terminal.
+ */
+export interface AuctionEndedView {
+    /** Phase discriminator; no auction action is legal after this phase. */
+    phase: "ended";
+    /** Mechanism discriminator for auction rendering. */
+    mechanism: "auction";
+    /** Consumer auction facts at the terminal outcome. */
+    consumer: AuctionSequenceConsumerState;
+    /** Server-derived terminal outcome for the auction participation. */
+    outcome: SequenceOutcome;
+}

package/dist/core/client.js

@@ -1,2 +1,2 @@
 import{AppointmentManagementModule as e}from"../appointments/appointment.module.js";import{AuctionManagementModule as t}from"../auctions/auction.module.js";import{AuthenticationModule as r}from"../auth/auth.module.js";import{BeaconTrackingModule as n}from"../beacon/beacon.module.js";import{ChallengeManagementModule as i}from"../challenges/challenge.module.js";import{Config as o}from"../config/index.js";import{DrawManagementModule as s}from"../draws/draw.module.js";import{ExperienceManagementModule as a}from"../experiences/experience.module.js";import{ExperienceJourney as d}from"../experiences/journey.js";import{QueueManagementModule as l}from"../queues/queue.module.js";import{resolveCapabilityOptions as c}from"../state/capability-token-registry.js";import{getEventBus as u}from"../state/events.js";import{getSDKStore as g}from"../state/store.js";import{CrossTabCoordinator as y}from"../sync/cross-tab-coordinator.js";import{TimedReleaseManagementModule as f}from"../timed-releases/timed-release.module.js";import{version as p}from"../version.js";import{WaitlistManagementModule as m}from"../waitlists/waitlist.module.js";import{FanfareError as b,ErrorCodes as w}from"./errors.js";import{createHttpClient as h}from"./http.js";import{createLogger as v}from"./logger.js";let M=null;async function I(I){const S=new o(I),j=S.get(),A=v({enabled:j.debug||!1,level:j.debug?"debug":"warn",prefix:"Fanfare"});if(A.info("Initializing Fanfare SDK",{organizationId:I.organizationId,environment:j.environment}),M)throw new b("Fanfare SDK is already initialized. The SDK uses a shared event bus and store; multiple concurrent instances will corrupt state and analytics. Call destroy() on the existing instance before initializing a new one.",w.ALREADY_INITIALIZED);const k=/* @__PURE__ */Symbol("fanfare-sdk"),x=h({baseUrl:S.apiUrl,credentials:j.credentials,headers:{"X-Organization-Id":I.organizationId,"X-Publishable-Key":I.publishableKey,"X-Fanfare-API-Version":"2025-01-15","X-Fanfare-SDK-Version":p,"X-Fanfare-Client-Type":"browser"},timeout:3e4,retryConfig:{maxRetries:3,delayTimer:1e3,retryOnNetworkError:!0}},j),D=h({baseUrl:S.beaconUrl,credentials:j.credentials,headers:{"X-Organization-Id":I.organizationId,"X-Publishable-Key":I.publishableKey,"X-Fanfare-API-Version":"2025-01-15","X-Fanfare-SDK-Version":p,"X-Fanfare-Client-Type":"browser"},timeout:3e4,retryConfig:{maxRetries:3,delayTimer:1e3,retryOnNetworkError:!0}},j),E=new r(x,D),q=new i(x),C=new l(x),R=new s(x),z=new t(x),F=new e(x),O=new m(x),K=new f(x),X=new a(x,C,R,z,O,K),P=new n(D,j.beacon||{}),T=u(),J=g(),$=/* @__PURE__ */new Map,N=/* @__PURE__ */new Map,V=/* @__PURE__ */new Map;let B,U;const L=e=>{const t=N.get(e);if(t)return A.debug("Returning existing journey handle",{experienceId:e}),t;A.info("Creating new journey",{experienceId:e});const r=new d(e,B);$.set(e,r),U?.registerJourney(r);const n={view$:r.view$,events$:r.events$,latestEvent$:r.latestEvent$,snapshot$:r.state,ackEvent:e=>r.ackEvent(e),ackAllEvents:()=>r.ackAllEvents(),destroy:()=>{r.destroy(),U?.unregisterJourney(e),$.delete(e),N.delete(e)}};return N.set(e,n),n},G=async e=>{const t=e??await X.getMe(),r=/* @__PURE__ */new Set,n=new Set(t.active.journeys.map(e=>e.experienceId));for(const i of n)L(i);for(const i of n){const e=$.get(i);e&&await e.resumeFromMe(t)&&r.add(i)}return[...r]},H={check:()=>E.check(),guest:()=>E.guest(),requestOtp:e=>E.requestOtp(e),verifyOtp:e=>E.verifyOtp(e),exchangeExternal:e=>E.exchangeExternal(e),login:e=>E.login(e),logout:()=>E.logout(),getSession:()=>E.getSession(),refresh:()=>E.refresh()},_={initiate:e=>q.initiate(e),verify:e=>q.verify(e)},Y={get:e=>L(e),list:()=>Array.from(
-/* @__PURE__ */new Set([...N.keys(),...$.keys(),...Object.keys(J.activeJourneys)])),resumeAll:e=>(async e=>{const t=/* @__PURE__ */new Set;for(const r of Object.keys(J.activeJourneys))L(r),t.add(r);if(!e&&!E.getSession())return[...t];for(const r of await G(e))t.add(r);return[...t]})(e)},Z={track:e=>P.track(e),trackBatch:e=>P.trackBatch(e),flush:()=>P.flush()},Q=(e,t)=>{if(V.has(e.id))A.warn("CDP adapter already registered, skipping",{adapterId:e.id});else{try{e.init(T,t)}catch(r){return void A.error("CDP adapter failed to initialize",{adapterId:e.id,error:r})}V.set(e.id,e),A.info("CDP adapter registered",{adapterId:e.id})}},W=(e,t)=>T.on(e,t),ee=async()=>{A.info("Destroying SDK instance");for(const t of V.values())try{t.destroy()}catch(e){A.error("CDP adapter failed to destroy",{adapterId:t.id,error:e})}V.clear();for(const t of Array.from(N.values()))try{t.destroy()}catch(e){A.error("Journey handle failed to destroy",{error:e})}$.clear(),N.clear(),"destroy"in E&&"function"==typeof E.destroy&&E.destroy(),C.destroy(),R.destroy(),z.destroy(),F.destroy(),O.destroy(),K.destroy(),X.destroy(),P.destroy(),U?.close(),T.off(),M===k&&(M=null)};B={auth:H,challenges:_,journeys:Y,queues:{get:e=>C.get(e),enter:(e,t,r)=>C.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>C.leave(e,c({distributionId:e},t)),status:e=>C.status(e),startMonitoring:(e,t,r)=>C.startMonitoring(e,t,r),stopMonitoring:e=>C.stopMonitoring(e),isMonitoring:e=>C.isMonitoring(e)},draws:{get:e=>R.get(e),enter:(e,t,r)=>R.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>R.leave(e,c({distributionId:e},t)),status:e=>R.status(e),startMonitoring:(e,t,r)=>R.startMonitoring(e,t,r),stopMonitoring:e=>R.stopMonitoring(e),isMonitoring:e=>R.isMonitoring(e)},auctions:{get:e=>z.get(e),bid:(e,t,r)=>z.bid(e,t,c({distributionId:e},r)),enter:(e,t,r)=>z.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>z.leave(e,c({distributionId:e},t)),status:e=>z.status(e),getBidHistory:e=>z.getBidHistory(e),enableAutoRebid:(e,t,r)=>z.enableAutoRebid(e,t,r),disableAutoRebid:e=>z.disableAutoRebid(e),getAutoRebidConfig:e=>z.getAutoRebidConfig(e),startMonitoring:(e,t,r)=>z.startMonitoring(e,t,r),stopMonitoring:e=>z.stopMonitoring(e),isMonitoring:e=>z.isMonitoring(e),destroy:()=>z.destroy()},experiences:{get:e=>X.get(e),enter:e=>X.enter(e),leave:e=>X.leave(e),getMe:()=>X.getMe(),findSequence:(e,t)=>X.findSequence(e,t),validateSequenceAccess:(e,t)=>X.validateSequenceAccess(e,t),selectSequence:e=>X.selectSequence(e),getCurrentDistributions:e=>X.getCurrentDistributions(e),enterDistribution:e=>{if(!e)throw new b("Distribution is required",w.VALIDATION_ERROR);return X.enterDistribution(e)},getActiveSession:()=>X.getActiveSession(),isInExperience:e=>X.isInExperience(e),getSelectedSequence:()=>X.getSelectedSequence(),createJourney:e=>L(e),resumeJourneysFromMe:e=>G(e),destroy:()=>X.destroy()},waitlists:{enter:(e,t)=>O.enter(e,c({distributionId:e},t)),leave:(e,t)=>O.leave(e,c({distributionId:e},t)),getStatus:e=>O.getStatus(e),destroy:()=>O.destroy()},timedReleases:{get:e=>K.get(e),enter:(e,t,r)=>K.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>K.leave(e,c({distributionId:e},t)),complete:(e,t)=>K.complete(e,c({distributionId:e},t)),status:e=>K.status(e),startMonitoring:(e,t,r)=>K.startMonitoring(e,t,r),stopMonitoring:e=>K.stopMonitoring(e),isMonitoring:e=>K.isMonitoring(e)},appointments:{get:e=>F.get(e),getSlots:(e,t)=>F.getSlots(e,t),getMe:e=>F.getMe(e),book:(e,t,r)=>F.book(e,t,r),cancel:(e,t,r,n)=>F.cancel(e,t,r,n),reschedule:(e,t,r)=>F.reschedule(e,t,r),startMonitoring:(e,t,r)=>F.startMonitoring(e,t,r),stopMonitoring:e=>F.stopMonitoring(e),isMonitoring:e=>F.isMonitoring(e),bumpMonitorGeneration:e=>F.bumpMonitorGeneration(e),destroy:()=>F.destroy()},beacon:Z,use:Q,on:W,destroy:ee};const te=!1!==I.sync&&"object"==typeof I.sync?I.sync:{};U=new y({enabled:!1!==I.sync&&!1!==te.enabled,channelName:te.channelName}),A.info("Inter-tab sync initialized",{tabId:U.getTabId(),enabled:U.isEnabled()});const re={auth:H,challenges:_,journeys:Y,beacon:Z,appointments:B.appointments,use:Q,on:W,destroy:ee};if(J.session)try{await E.refresh()}catch(ne){A.warn("Failed to refresh persisted session during init",ne),J.clearAll()}return M=k,A.info("SDK initialized successfully"),re}export{I as init};
+/* @__PURE__ */new Set([...N.keys(),...$.keys(),...Object.keys(J.activeJourneys)])),resumeAll:e=>(async e=>{const t=/* @__PURE__ */new Set;for(const r of Object.keys(J.activeJourneys))L(r),t.add(r);if(!e&&!E.getSession())return[...t];for(const r of await G(e))t.add(r);return[...t]})(e)},Z={track:e=>P.track(e),trackBatch:e=>P.trackBatch(e),flush:()=>P.flush()},Q=(e,t)=>{if(V.has(e.id))A.warn("CDP adapter already registered, skipping",{adapterId:e.id});else{try{e.init(T,t)}catch(r){return void A.error("CDP adapter failed to initialize",{adapterId:e.id,error:r})}V.set(e.id,e),A.info("CDP adapter registered",{adapterId:e.id})}},W=(e,t)=>T.on(e,t),ee=async()=>{A.info("Destroying SDK instance");for(const t of V.values())try{t.destroy()}catch(e){A.error("CDP adapter failed to destroy",{adapterId:t.id,error:e})}V.clear();for(const t of Array.from(N.values()))try{t.destroy()}catch(e){A.error("Journey handle failed to destroy",{error:e})}$.clear(),N.clear(),"destroy"in E&&"function"==typeof E.destroy&&E.destroy(),C.destroy(),R.destroy(),z.destroy(),F.destroy(),O.destroy(),K.destroy(),X.destroy(),P.destroy(),U?.close(),T.off(),M===k&&(M=null)};B={auth:H,challenges:_,journeys:Y,queues:{get:e=>C.get(e),enter:(e,t,r)=>C.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>C.leave(e,c({distributionId:e},t)),status:e=>C.status(e),startMonitoring:(e,t,r)=>C.startMonitoring(e,t,r),stopMonitoring:e=>C.stopMonitoring(e),isMonitoring:e=>C.isMonitoring(e)},draws:{get:e=>R.get(e),enter:(e,t,r)=>R.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>R.leave(e,c({distributionId:e},t)),status:e=>R.status(e),startMonitoring:(e,t,r)=>R.startMonitoring(e,t,r),stopMonitoring:e=>R.stopMonitoring(e),isMonitoring:e=>R.isMonitoring(e)},auctions:{get:e=>z.get(e),bid:(e,t,r)=>z.bid(e,t,c({distributionId:e},r)),enter:(e,t,r)=>z.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>z.leave(e,c({distributionId:e},t)),status:e=>z.status(e),getBidHistory:e=>z.getBidHistory(e),enableAutoRebid:(e,t,r)=>z.enableAutoRebid(e,t,r),disableAutoRebid:e=>z.disableAutoRebid(e),getAutoRebidConfig:e=>z.getAutoRebidConfig(e),startMonitoring:(e,t,r)=>z.startMonitoring(e,t,r),stopMonitoring:e=>z.stopMonitoring(e),isMonitoring:e=>z.isMonitoring(e),destroy:()=>z.destroy()},experiences:{get:e=>X.get(e),enter:e=>X.enter(e),leave:e=>X.leave(e),getMe:()=>X.getMe(),findSequence:(e,t)=>X.findSequence(e,t),validateSequenceAccess:(e,t)=>X.validateSequenceAccess(e,t),selectSequence:e=>X.selectSequence(e),getCurrentDistributions:e=>X.getCurrentDistributions(e),enterDistribution:e=>{if(!e)throw new b("Distribution is required",w.VALIDATION_ERROR);return X.enterDistribution(e)},getActiveSession:()=>X.getActiveSession(),isInExperience:e=>X.isInExperience(e),getSelectedSequence:()=>X.getSelectedSequence(),createJourney:e=>L(e),resumeJourneysFromMe:e=>G(e),destroy:()=>X.destroy()},waitlists:{enter:(e,t)=>O.enter(e,c({distributionId:e},t)),leave:(e,t)=>O.leave(e,c({distributionId:e},t)),getStatus:e=>O.getStatus(e),destroy:()=>O.destroy()},timedReleases:{get:e=>K.get(e),enter:(e,t,r)=>K.enter(e,t,c({distributionId:e},r)),leave:(e,t)=>K.leave(e,c({distributionId:e},t)),complete:e=>K.complete(e),status:e=>K.status(e),startMonitoring:(e,t,r)=>K.startMonitoring(e,t,r),stopMonitoring:e=>K.stopMonitoring(e),isMonitoring:e=>K.isMonitoring(e)},appointments:{get:e=>F.get(e),getSlots:(e,t)=>F.getSlots(e,t),getMe:e=>F.getMe(e),book:(e,t,r)=>F.book(e,t,r),cancel:(e,t,r,n)=>F.cancel(e,t,r,n),reschedule:(e,t,r)=>F.reschedule(e,t,r),startMonitoring:(e,t,r)=>F.startMonitoring(e,t,r),stopMonitoring:e=>F.stopMonitoring(e),isMonitoring:e=>F.isMonitoring(e),bumpMonitorGeneration:e=>F.bumpMonitorGeneration(e),destroy:()=>F.destroy()},beacon:Z,use:Q,on:W,destroy:ee};const te=!1!==I.sync&&"object"==typeof I.sync?I.sync:{};U=new y({enabled:!1!==I.sync&&!1!==te.enabled,channelName:te.channelName}),A.info("Inter-tab sync initialized",{tabId:U.getTabId(),enabled:U.isEnabled()});const re={auth:H,challenges:_,journeys:Y,beacon:Z,appointments:B.appointments,use:Q,on:W,destroy:ee};if(J.session)try{await E.refresh()}catch(ne){A.warn("Failed to refresh persisted session during init",ne),J.clearAll()}return M=k,A.info("SDK initialized successfully"),re}export{I as init};

package/dist/draws/draw.driver.d.ts

@@ -0,0 +1,45 @@
+import { DistributionMonitor, MonitorUpdate } from '../experiences/distribution-monitor.types';
+import { DistributionSummary, JourneyEvent, JourneyEventAudience, JourneyEventKind, JourneyEventSeverity, MechanismConsumerState, Participation, SequenceOutcome, SequenceState } from '../experiences/journey.types';
+import { SequenceDriver, SequenceProjectionFacts } from '../experiences/sequence-driver';
+import { DrawModule } from './types';
+type DrawMonitorModule = DrawModule & Pick<DistributionMonitor, "startMonitoring" | "stopMonitoring">;
+/**
+ * Narrow shell and module capabilities required by the draw driver.
+ */
+export interface DrawDriverDependencies {
+    /** Draw module functions used by draw actions and monitoring. */
+    draws: Pick<DrawMonitorModule, "enter" | "leave" | "startMonitoring" | "stopMonitoring">;
+    /** Serialize a draw action with the shell's operation queue. */
+    runSerializedOperation(operation: () => Promise<void>): Promise<void>;
+    /** Read the current routed sequence before validating a draw action. */
+    getCurrentSequence(): SequenceState | undefined;
+    /** Commit a concrete next draw sequence into the shell. */
+    commit(next: SequenceState, opts?: {
+        events?: JourneyEvent[];
+    }): void;
+    /** Apply shell-owned grant and terminal lifecycle side effects. */
+    applyMonitorUpdate(update: MonitorUpdate): void;
+    /** Ensure the shell-owned display atom exists for this draw participation. */
+    ensureDisplayAtom(participation: Participation): void;
+    /** Stop shell runtime monitoring and optionally clear display state. */
+    stopRuntimeMonitoring(clearDisplay?: boolean): void;
+    /** Append a shell-visible journey event to the snapshot. */
+    emitEvent(kind: JourneyEventKind, severity: JourneyEventSeverity, audience: JourneyEventAudience, message: string, detail?: Record<string, unknown>): void;
+}
+/**
+ * Create the draw sequence driver for one journey instance.
+ */
+export declare function createDrawDriver(deps: DrawDriverDependencies): SequenceDriver;
+/**
+ * Project draw server facts into a draw sequence state.
+ */
+export declare function projectDrawSequence(facts: SequenceProjectionFacts): SequenceState;
+/**
+ * Return the draw consumer state that represents an issued grant.
+ */
+export declare function withDrawGrantedConsumer(consumer: MechanismConsumerState | undefined, distribution: DistributionSummary): MechanismConsumerState;
+/**
+ * Return the draw consumer state that represents a terminal outcome.
+ */
+export declare function withDrawTerminalConsumer(consumer: MechanismConsumerState | undefined, outcome?: SequenceOutcome): MechanismConsumerState | undefined;
+export {};

package/dist/draws/draw.driver.js

@@ -0,0 +1 @@
+import{createError as t}from"../core/errors.js";function e(t){return new r(t)}function i(e){const{distribution:i,consumer:n,waitlist:s,grant:r,outcome:o}=e;if(!i)return{phase:"unavailable"};const u=function(e){if("draw"!==e.type)throw t.validationError("Draw driver received a non-draw distribution");return e}(i),c=n&&"draw"===n.mechanism?function(t){const{mechanism:e,...i}=t;return i}(n):a(i);if(r)return"completed"===o?.type?d(u,c,o):r.expiresAt&&Date.now()>new Date(r.expiresAt).getTime()?"open"===u.lifecycle?{phase:"enterable",mechanism:"draw",distribution:u,consumer:a(u)}:d(u,c,{type:"expired"}):{phase:"granted",mechanism:"draw",distribution:u,consumer:c,grant:r};if(!o&&"draw"===n?.mechanism&&"closed"===u.lifecycle)return d(u,c,{type:"lost"});const p=o??function(t){return"completed"===t.status?{type:"completed"}:"denied"===t.status?{type:"denied",reason:t.deniedReason}:void 0}(c);if(p)return d(u,c,p);if(function(t){return"entered"===t.status}(c))return{phase:"participating",mechanism:"draw",distribution:u,consumer:c};if("scheduled"===u.lifecycle){const t=s&&s.waitlistId===u.waitlistId?s:u.waitlistId?{waitlistId:u.waitlistId,status:"not_waitlisted"}:void 0;return{phase:"scheduled",mechanism:"draw",distribution:u,...t?{waitlist:t}:{}}}return"open"===u.lifecycle?{phase:"enterable",mechanism:"draw",distribution:u,consumer:c}:"settling"===u.lifecycle?{phase:"settling",mechanism:"draw",distribution:u,consumer:c}:d(u,c,{type:"closed"})}function n(t,e){return"draw"===t?.mechanism?{...t,status:"won"}:{mechanism:"draw",status:"won",id:e.id,distributionId:e.id}}function s(t,e){return t&&"draw"===t.mechanism&&e?"denied"===e.type?{...t,status:"denied",deniedReason:e.reason}:"completed"===e.type?{...t,status:"completed"}:"won"===e.type?{...t,status:"won"}:{...t,status:"not_entered"}:t}class r{constructor(t){this.deps=t,this.mechanism="draw"}project(t){return i(t)}buildView(e,i){if("unavailable"===e.phase)return{phase:"unavailable",reason:e.reason};const n=function(e){if(!("mechanism"in e)||"draw"!==e.mechanism)throw t.validationError("Draw driver received a non-draw sequence");return e}(e);switch(n.phase){case"scheduled":return{phase:"scheduled",mechanism:"draw",distribution:n.distribution,startsAt:n.distribution.startsAt??n.distribution.opensAt,waitlist:n.waitlist?{status:n.waitlist.status,join:()=>i.joinWaitlist(),leave:()=>i.exitWaitlist()}:void 0};case"enterable":return{phase:"enterable",mechanism:"draw",distribution:n.distribution,consumer:n.consumer,enter:()=>this.enter()};case"participating":return{phase:"participating",mechanism:"draw",consumer:n.consumer,display$:i.displayAtom,leave:()=>this.leave()};case"settling":return{phase:"settling",mechanism:"draw",distribution:n.distribution,consumer:n.consumer};case"granted":return{phase:"granted",mechanism:"draw",distribution:n.distribution,consumer:n.consumer,grant:n.grant,claim:()=>i.claim()};case"ended":return{phase:"ended",mechanism:"draw",consumer:n.consumer,outcome:n.outcome}}}startMonitoring(t){this.activeMonitorId=t.participation.id;const e=this.deps.getCurrentSequence(),i=e&&"participating"===e.phase&&"mechanism"in e&&"draw"===e.mechanism&&"draw"===e.distribution.details?.type?e.distribution.details.drawTime:void 0;this.deps.draws.startMonitoring(t.participation.id,{displayAtom:t.displayAtom,drawTime:i},t.onUpdate)}stopMonitoring(){this.activeMonitorId&&(this.deps.draws.stopMonitoring(this.activeMonitorId),this.activeMonitorId=void 0)}async enter(){await this.deps.runSerializedOperation(async()=>{await this.enterWithinOperation()})}async enterWithinOperation(){const t=this.currentDrawSequence("enterable","No open draw to enter").distribution,e=function(t){if("ENTERED"===t.status)return null;if("COMPLETED"===t.status)return{type:"ended",outcome:{type:"completed"}};if("WON"===t.status)return{type:"granted",token:t.admissionGrant,expiresAt:t.expiresAt?new Date(t.expiresAt).getTime():void 0};return{type:"ended",outcome:{type:"DENIED"===t.status?"denied":"lost",reason:"reason"in t?t.reason:void 0}}}(await this.deps.draws.enter(t.id,void 0));if(e)return void this.deps.applyMonitorUpdate(e);const n={mechanism:"draw",status:"entered",id:s=t.id,distributionId:s};var s;this.deps.ensureDisplayAtom({id:t.id,type:"draw"}),this.deps.commit(i({distribution:t,consumer:n})),this.deps.emitEvent("sequence_change","success","user","Entered draw",{distributionId:t.id})}async leave(){await this.deps.runSerializedOperation(async()=>{await this.leaveWithinOperation()})}async leaveWithinOperation(){const t=this.currentDrawSequence("participating"),e=t.consumer.distributionId??t.consumer.id??t.distribution.id;this.deps.stopRuntimeMonitoring(!0),await this.deps.draws.leave(e),this.deps.applyMonitorUpdate({type:"ended",outcome:{type:"left"}}),this.deps.emitEvent("sequence_change","info","user","Left participation",{type:"draw"})}currentDrawSequence(e,i="Not participating in a draw"){const n=this.deps.getCurrentSequence();if(!n||n.phase!==e||!("mechanism"in n)||"draw"!==n.mechanism)throw t.validationError(i);return n}}function a(t){return{status:"not_entered",distributionId:t.id}}function d(t,e,i){return{phase:"ended",mechanism:"draw",distribution:t,consumer:e,outcome:{...i,distributionType:i.distributionType??t.type,distributionId:i.distributionId??t.id,at:i.at??/* @__PURE__ */(new Date).toISOString()}}}export{e as createDrawDriver,i as projectDrawSequence,n as withDrawGrantedConsumer,s as withDrawTerminalConsumer};

package/dist/draws/draw.module.js

@@ -1 +1 @@
-import{createError as t,isFanfareError as e}from"../core/errors.js";import{getLogger as i}from"../core/logger.js";import{DistributionMonitorRuntime as r}from"../experiences/distribution-monitor.runtime.js";import{getEventBus as s}from"../state/events.js";import{getSDKStore as a}from"../state/store.js";class n{constructor(t){this.logger=i(),this.events=s(),this.trackedParticipations=/* @__PURE__ */new Map,this.inFlightRequests=/* @__PURE__ */new Map,this.scheduledChecks=/* @__PURE__ */new Map,this.monitorRuntime=new r,this.monitorGenerations=/* @__PURE__ */new Map,this.operationGenerations=/* @__PURE__ */new Map,this.initialCheckBufferMs=5e3,this.retryCheckDelayMs=5e3,this.destroyed=!1,this.lifecycleGeneration=0,this.http=t}get store(){return a()}async get(t){try{return await this.http.get(`/draws/${t}`)}catch(e){throw this.logger.error("Failed to get draw",{drawId:t,error:e}),e}}async enter(e,i,r){try{const s=this.lifecycleGeneration;if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");const a=this.bumpOperationGeneration(e);this.logger.info("Entering draw",{drawId:e});const n=await this.http.post(`/draws/${e}/enter`,{metadata:i},r),o=this.buildTransition(e,n,{source:"enter",enteredAt:/* @__PURE__ */(new Date).toISOString(),metadata:i});return this.canApplyAsyncResult(e,s,void 0,a)?(this.applyTransition(e,o),n):n}catch(s){throw this.logger.error("Failed to enter draw",{drawId:e,error:s}),this.events.emit("draw:error",{drawId:e,error:s}),s}}async leave(t,e){try{const i=this.lifecycleGeneration,r=this.bumpOperationGeneration(t);if(this.logger.info("Leaving draw",{drawId:t}),await this.http.post(`/draws/${t}/leave`,void 0,e),!this.canApplyAsyncResult(t,i,void 0,r))return;this.trackedParticipations.delete(t),this.stopMonitoring(t),this.events.emit("draw:left",{drawId:t})}catch(i){throw this.logger.error("Failed to leave draw",{drawId:t,error:i}),this.events.emit("draw:error",{drawId:t,error:i}),i}}async status(t){const e=this.inFlightRequests.get(t);if(e)return this.logger.debug("Returning existing in-flight request",{drawId:t}),e;const i=this.lifecycleGeneration,r=this.bumpOperationGeneration(t),s=this.doStatus(t,i,void 0,r).finally(()=>{this.inFlightRequests.delete(t)});return this.inFlightRequests.set(t,s),s}async doStatus(t,e,i,r){try{const s=await this.http.get(`/draws/${t}/status`);if(!this.canApplyAsyncResult(t,e,i,r))return s;const a=this.buildTransition(t,s,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,a),this.events.emit("draw:status-updated",{drawId:t,status:s.status}),s}catch(s){if(s&&"object"==typeof s&&"status"in s&&404===s.status){const s={status:"NOT_ENTERED"};if(!this.canApplyAsyncResult(t,e,i,r))return s;const a=this.buildTransition(t,s,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,a),this.events.emit("draw:status-updated",{drawId:t,status:s.status}),s}if(!this.canApplyAsyncResult(t,e,i,r))return this.trackedParticipations.has(t)?{status:"ENTERED"}:{status:"NOT_ENTERED"};throw this.logger.error("Failed to get draw status",{drawId:t,error:s}),this.events.emit("draw:error",{drawId:t,error:s}),s}}startMonitoring(t,e,i){this.monitorRuntime.start(t,e,i),this.bumpMonitorGeneration(t);const r="string"==typeof e?.drawTime?e.drawTime:void 0,s=this.monitorRuntime.getDisplayAtom(t);s&&s.set({type:"draw",drawTime:r,entryNumber:this.trackedParticipations.get(t)?.entryNumber}),r&&this.scheduleInitialStatusCheck(t,r)}stopMonitoring(t){this.bumpMonitorGeneration(t),this.cancelScheduledCheck(t),this.monitorRuntime.stop(t)}isMonitoring(t){return this.monitorRuntime.has(t)||this.scheduledChecks.has(t)}buildTransition(t,e,{source:i,previousParticipation:r,enteredAt:s,metadata:a}){switch(e.status){case"ENTERED":return{trackedParticipation:{drawId:t,enteredAt:r?.enteredAt??s??/* @__PURE__ */(new Date).toISOString(),entryNumber:r?.entryNumber,metadata:r?.metadata??a},events:"enter"===i?[{type:"draw:entered",payload:{drawId:t}}]:[],monitorUpdate:null,stopMonitoring:!1,retryStatusCheck:"status"===i};case"WON":return{trackedParticipation:null,events:[{type:"draw:won",payload:{drawId:t,result:{won:!0,drawTime:e.wonAt}}}],monitorUpdate:"status"===i?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"COMPLETED":return{trackedParticipation:null,events:[{type:"draw:won",payload:{drawId:t,result:{won:!0,drawTime:e.completedAt}}}],monitorUpdate:"status"===i?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"DENIED":return{trackedParticipation:null,events:[{type:"draw:expired",payload:{drawId:t}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"denied",reason:e.reason}}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"NOT_ENTERED":return{trackedParticipation:null,events:r?[{type:"draw:lost",payload:{drawId:t,result:this.buildLostResult()}}]:[],monitorUpdate:"status"===i?{type:"ended",outcome:r?{type:"lost"}:{type:"closed",reason:"not_entered"}}:null,stopMonitoring:"status"===i,retryStatusCheck:!1}}}applyTransition(t,e){e.trackedParticipation?this.trackedParticipations.set(t,e.trackedParticipation):this.trackedParticipations.delete(t);for(const i of e.events)this.events.emit(i.type,i.payload);e.monitorUpdate&&this.monitorRuntime.notify(t,e.monitorUpdate),e.stopMonitoring?this.stopMonitoring(t):e.retryStatusCheck&&this.monitorRuntime.has(t)&&this.scheduleRetryStatusCheck(t)}scheduleInitialStatusCheck(t,e){const i=new Date(e).getTime(),r=Math.max(0,i-Date.now()+this.initialCheckBufferMs);this.scheduleStatusCheck(t,r)}scheduleRetryStatusCheck(t){this.scheduleStatusCheck(t,this.retryCheckDelayMs)}scheduleStatusCheck(t,i){if(i>2147483647)return void this.logger.warn("Draw time too far in future to schedule",{drawId:t,delayMs:i});this.cancelScheduledCheck(t);const r=this.monitorGenerations.get(t),s=this.getOperationGeneration(t),a=setTimeout(async()=>{this.scheduledChecks.delete(t);try{if(void 0===r)return;await this.doStatus(t,this.lifecycleGeneration,r,s)}catch(i){if(!this.canApplyAsyncResult(t,this.lifecycleGeneration,r,s))return;if(e(i)&&i.retryable&&this.monitorRuntime.has(t))return void this.scheduleRetryStatusCheck(t);this.stopMonitoring(t)}},i);this.scheduledChecks.set(t,a)}cancelScheduledCheck(t){const e=this.scheduledChecks.get(t);e&&(clearTimeout(e),this.scheduledChecks.delete(t))}buildLostResult(){return{won:!1,drawTime:/* @__PURE__ */(new Date).toISOString()}}bumpMonitorGeneration(t){const e=(this.monitorGenerations.get(t)??0)+1;return this.monitorGenerations.set(t,e),e}getOperationGeneration(t){return this.operationGenerations.get(t)??0}bumpOperationGeneration(t){const e=this.getOperationGeneration(t)+1;return this.operationGenerations.set(t,e),e}canApplyAsyncResult(t,e,i,r){return!this.destroyed&&this.lifecycleGeneration===e&&((void 0===i||this.monitorGenerations.get(t)===i)&&(void 0===r||this.getOperationGeneration(t)===r))}destroy(){this.destroyed=!0,this.lifecycleGeneration+=1,this.scheduledChecks.forEach(t=>clearTimeout(t)),this.scheduledChecks.clear(),this.inFlightRequests.clear(),this.trackedParticipations.clear(),this.monitorGenerations.clear(),this.operationGenerations.clear(),this.monitorRuntime.clear()}}export{n as DrawManagementModule};
+import{createError as t,isFanfareError as e}from"../core/errors.js";import{getLogger as i}from"../core/logger.js";import{DistributionMonitorRuntime as r}from"../experiences/distribution-monitor.runtime.js";import{getEventBus as s}from"../state/events.js";import{getSDKStore as n}from"../state/store.js";class a{constructor(t){this.logger=i(),this.events=s(),this.trackedParticipations=/* @__PURE__ */new Map,this.inFlightRequests=/* @__PURE__ */new Map,this.scheduledChecks=/* @__PURE__ */new Map,this.monitorRuntime=new r,this.monitorGenerations=/* @__PURE__ */new Map,this.operationGenerations=/* @__PURE__ */new Map,this.initialCheckBufferMs=5e3,this.retryCheckDelayMs=5e3,this.destroyed=!1,this.lifecycleGeneration=0,this.http=t}get store(){return n()}async get(t){try{return await this.http.get(`/draws/${t}`)}catch(e){throw this.logger.error("Failed to get draw",{drawId:t,error:e}),e}}async enter(e,i,r){try{const s=this.lifecycleGeneration;if(!this.store.session)throw t.unauthorized("Not authenticated. Call auth.guest() or auth.login() first");const n=this.bumpOperationGeneration(e);this.logger.info("Entering draw",{drawId:e});const a=await this.http.post(`/draws/${e}/enter`,{metadata:i},r),o=this.buildTransition(e,a,{source:"enter",enteredAt:/* @__PURE__ */(new Date).toISOString(),metadata:i});return this.canApplyAsyncResult(e,s,void 0,n)?(this.applyTransition(e,o),a):a}catch(s){throw this.logger.error("Failed to enter draw",{drawId:e,error:s}),this.events.emit("draw:error",{drawId:e,error:s}),s}}async leave(t,e){try{const i=this.lifecycleGeneration,r=this.bumpOperationGeneration(t);if(this.logger.info("Leaving draw",{drawId:t}),await this.http.post(`/draws/${t}/leave`,void 0,e),!this.canApplyAsyncResult(t,i,void 0,r))return;this.trackedParticipations.delete(t),this.stopMonitoring(t),this.events.emit("draw:left",{drawId:t})}catch(i){throw this.logger.error("Failed to leave draw",{drawId:t,error:i}),this.events.emit("draw:error",{drawId:t,error:i}),i}}async status(t){const e=this.inFlightRequests.get(t);if(e)return this.logger.debug("Returning existing in-flight request",{drawId:t}),e;const i=this.lifecycleGeneration,r=this.bumpOperationGeneration(t),s=this.doStatus(t,i,void 0,r).finally(()=>{this.inFlightRequests.delete(t)});return this.inFlightRequests.set(t,s),s}async doStatus(t,e,i,r){try{const s=await this.http.get(`/draws/${t}/status`);if(!this.canApplyAsyncResult(t,e,i,r))return s;const n=this.buildTransition(t,s,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,n),this.events.emit("draw:status-updated",{drawId:t,status:s.status}),s}catch(s){if(s&&"object"==typeof s&&"status"in s&&404===s.status){const s={status:"NOT_ENTERED"};if(!this.canApplyAsyncResult(t,e,i,r))return s;const n=this.buildTransition(t,s,{source:"status",previousParticipation:this.trackedParticipations.get(t)});return this.applyTransition(t,n),this.events.emit("draw:status-updated",{drawId:t,status:s.status}),s}if(!this.canApplyAsyncResult(t,e,i,r))return this.trackedParticipations.has(t)?{status:"ENTERED"}:{status:"NOT_ENTERED"};throw this.logger.error("Failed to get draw status",{drawId:t,error:s}),this.events.emit("draw:error",{drawId:t,error:s}),s}}startMonitoring(t,e,i){this.monitorRuntime.start(t,e,i),this.bumpMonitorGeneration(t);const r="string"==typeof e?.drawTime?e.drawTime:void 0,s=this.monitorRuntime.getDisplayAtom(t);s&&s.set({type:"draw",drawTime:r,entryNumber:this.trackedParticipations.get(t)?.entryNumber}),r&&this.scheduleInitialStatusCheck(t,r)}stopMonitoring(t){this.bumpMonitorGeneration(t),this.cancelScheduledCheck(t),this.monitorRuntime.stop(t)}isMonitoring(t){return this.monitorRuntime.has(t)||this.scheduledChecks.has(t)}buildTransition(t,e,{source:i,previousParticipation:r,enteredAt:s,metadata:n}){switch(e.status){case"ENTERED":return{trackedParticipation:{drawId:t,enteredAt:r?.enteredAt??s??/* @__PURE__ */(new Date).toISOString(),entryNumber:r?.entryNumber,metadata:r?.metadata??n},events:"enter"===i?[{type:"draw:entered",payload:{drawId:t}}]:[],monitorUpdate:null,stopMonitoring:!1,retryStatusCheck:"status"===i};case"WON":return{trackedParticipation:null,events:[{type:"draw:won",payload:{drawId:t,result:{won:!0,drawTime:e.wonAt}}}],monitorUpdate:"status"===i?{type:"granted",token:e.admissionGrant,expiresAt:e.expiresAt?new Date(e.expiresAt).getTime():void 0}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"COMPLETED":return{trackedParticipation:null,events:[],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"completed"}}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"DENIED":return{trackedParticipation:null,events:[{type:"draw:expired",payload:{drawId:t}}],monitorUpdate:"status"===i?{type:"ended",outcome:{type:"denied",reason:e.reason}}:null,stopMonitoring:"status"===i,retryStatusCheck:!1};case"NOT_ENTERED":return{trackedParticipation:null,events:r?[{type:"draw:lost",payload:{drawId:t,result:this.buildLostResult()}}]:[],monitorUpdate:"status"===i?{type:"ended",outcome:r?{type:"lost"}:{type:"closed",reason:"not_entered"}}:null,stopMonitoring:"status"===i,retryStatusCheck:!1}}}applyTransition(t,e){e.trackedParticipation?this.trackedParticipations.set(t,e.trackedParticipation):this.trackedParticipations.delete(t);for(const i of e.events)this.events.emit(i.type,i.payload);e.monitorUpdate&&this.monitorRuntime.notify(t,e.monitorUpdate),e.stopMonitoring?this.stopMonitoring(t):e.retryStatusCheck&&this.monitorRuntime.has(t)&&this.scheduleRetryStatusCheck(t)}scheduleInitialStatusCheck(t,e){const i=new Date(e).getTime(),r=Math.max(0,i-Date.now()+this.initialCheckBufferMs);this.scheduleStatusCheck(t,r)}scheduleRetryStatusCheck(t){this.scheduleStatusCheck(t,this.retryCheckDelayMs)}scheduleStatusCheck(t,i){if(i>2147483647)return void this.logger.warn("Draw time too far in future to schedule",{drawId:t,delayMs:i});this.cancelScheduledCheck(t);const r=this.monitorGenerations.get(t),s=this.getOperationGeneration(t),n=setTimeout(async()=>{this.scheduledChecks.delete(t);try{if(void 0===r)return;await this.doStatus(t,this.lifecycleGeneration,r,s)}catch(i){if(!this.canApplyAsyncResult(t,this.lifecycleGeneration,r,s))return;if(e(i)&&i.retryable&&this.monitorRuntime.has(t))return void this.scheduleRetryStatusCheck(t);this.stopMonitoring(t)}},i);this.scheduledChecks.set(t,n)}cancelScheduledCheck(t){const e=this.scheduledChecks.get(t);e&&(clearTimeout(e),this.scheduledChecks.delete(t))}buildLostResult(){return{won:!1,drawTime:/* @__PURE__ */(new Date).toISOString()}}bumpMonitorGeneration(t){const e=(this.monitorGenerations.get(t)??0)+1;return this.monitorGenerations.set(t,e),e}getOperationGeneration(t){return this.operationGenerations.get(t)??0}bumpOperationGeneration(t){const e=this.getOperationGeneration(t)+1;return this.operationGenerations.set(t,e),e}canApplyAsyncResult(t,e,i,r){return!this.destroyed&&this.lifecycleGeneration===e&&((void 0===i||this.monitorGenerations.get(t)===i)&&(void 0===r||this.getOperationGeneration(t)===r))}destroy(){this.destroyed=!0,this.lifecycleGeneration+=1,this.scheduledChecks.forEach(t=>clearTimeout(t)),this.scheduledChecks.clear(),this.inFlightRequests.clear(),this.trackedParticipations.clear(),this.monitorGenerations.clear(),this.operationGenerations.clear(),this.monitorRuntime.clear()}}export{a as DrawManagementModule};

package/dist/draws/draw.sequence.d.ts

@@ -0,0 +1,249 @@
+import { AdmissionGrant, DrawConsumerStatus, SequenceOutcome } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { ReadableAtom } from 'nanostores';
+import { DrawDisplayState } from '../experiences/distribution-monitor.types';
+import { DistributionSummary, WaitlistAttachment, WaitlistAttachmentView } from '../experiences/journey.types';
+/**
+ * Draw participation facts for one consumer.
+ *
+ * The server is authoritative for every field. Timestamps are ISO 8601 strings.
+ * Optional fields are present only after the matching draw lifecycle event has
+ * occurred.
+ */
+export interface DrawSequenceConsumerState {
+    /** Server draw status for this consumer. */
+    status: DrawConsumerStatus;
+    /** Draw participation id, when the server has created one. */
+    id?: string;
+    /** Distribution id this draw participation belongs to. */
+    distributionId?: string;
+    /** ISO 8601 timestamp for when the consumer entered the draw. */
+    enteredAt?: string;
+    /** Opaque admission credential token, when one has been issued inline. */
+    admissionGrant?: string;
+    /** ISO 8601 timestamp for when the consumer was granted admission. */
+    grantedAt?: string;
+    /** Server-provided denial reason for denied draw outcomes. */
+    deniedReason?: string;
+}
+/**
+ * A draw sequence as seen by one consumer.
+ *
+ * Lifecycle: scheduled -> enterable -> participating -> settling -> granted or
+ * ended. The consumer enters before the draw closes, settlement is server-driven,
+ * and a winning consumer receives a grant.
+ */
+export type DrawSequence = DrawScheduled | DrawEnterable | DrawParticipating | DrawSettling | DrawGranted | DrawEnded;
+/**
+ * The draw exists but entry has not opened yet.
+ */
+export interface DrawScheduled {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; scheduled draws cannot be entered yet. */
+    phase: "scheduled";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Scheduled-only waitlist attachment, cleared when the draw opens. */
+    waitlist?: WaitlistAttachment;
+}
+/**
+ * The draw is open and this consumer has not entered it.
+ */
+export interface DrawEnterable {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; `enter()` is legal on the matching view. */
+    phase: "enterable";
+    /** Open draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw facts before entry. */
+    consumer: DrawSequenceConsumerState;
+}
+/**
+ * The consumer has entered the draw and is awaiting settlement.
+ */
+export interface DrawParticipating {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; the draw display is live while participating. */
+    phase: "participating";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw participation facts. */
+    consumer: DrawSequenceConsumerState;
+}
+/**
+ * The draw has closed and the server is choosing outcomes.
+ */
+export interface DrawSettling {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; no consumer action is legal while settling. */
+    phase: "settling";
+    /** Settling draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw participation facts during settlement. */
+    consumer: DrawSequenceConsumerState;
+}
+/**
+ * The draw has issued an admission grant to this consumer.
+ */
+export interface DrawGranted {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; `claim()` is legal on the matching view. */
+    phase: "granted";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw facts associated with the grant. */
+    consumer: DrawSequenceConsumerState;
+    /** Admission credential issued by the server for this draw win. */
+    grant: AdmissionGrant;
+}
+/**
+ * The draw journey is terminal for this consumer.
+ */
+export interface DrawEnded {
+    /** Mechanism discriminator for draw narrowing. */
+    mechanism: "draw";
+    /** Phase discriminator; no draw actions are legal after this phase. */
+    phase: "ended";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw facts at the terminal outcome. */
+    consumer: DrawSequenceConsumerState;
+    /** Server-derived terminal outcome for the draw participation. */
+    outcome: SequenceOutcome;
+}
+/**
+ * Draw views exposed by `JourneyView.sequence`.
+ *
+ * The view lifecycle mirrors the draw sequence lifecycle. Actions exist only on
+ * the phases where they are legal, and each action may reject if the server has
+ * moved the sequence before the request is handled.
+ */
+export type DrawSequenceView = DrawScheduledView | DrawEnterableView | DrawParticipatingView | DrawSettlingView | DrawGrantedView | DrawEndedView;
+/**
+ * Scheduled draw view rendered before entry opens.
+ */
+export interface DrawScheduledView {
+    /** Phase discriminator; no draw action is legal yet. */
+    phase: "scheduled";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** ISO 8601 opening timestamp chosen from the distribution start/open time. */
+    startsAt?: string;
+    /** Scheduled-only waitlist actions; this attachment never grants access. */
+    waitlist?: WaitlistAttachmentView;
+}
+/**
+ * Enterable draw view rendered when the consumer can enter.
+ */
+export interface DrawEnterableView {
+    /** Phase discriminator; `enter()` is legal on this view. */
+    phase: "enterable";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Open draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw facts before entry. */
+    consumer: DrawSequenceConsumerState;
+    /**
+     * Enter the draw.
+     *
+     * Legal only while this view is current. The promise rejects if draw entry is
+     * no longer allowed or the server rejects the participation request.
+     */
+    enter(): Promise<void>;
+}
+/**
+ * Participating draw view rendered while the consumer is entered.
+ */
+export interface DrawParticipatingView {
+    /** Phase discriminator; `leave()` is legal on this view. */
+    phase: "participating";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Consumer draw participation facts. */
+    consumer: DrawSequenceConsumerState;
+    /** Live draw display facts, such as participant counts and draw timing. */
+    display$: ReadableAtom<DrawDisplayState>;
+    /**
+     * Leave the draw.
+     *
+     * Legal only while this view is current. The promise rejects if the consumer
+     * is no longer participating or the server rejects the leave request.
+     */
+    leave(): Promise<void>;
+}
+/**
+ * Settling draw view rendered while the server computes the draw result.
+ */
+export interface DrawSettlingView {
+    /** Phase discriminator; no draw action is legal while settling. */
+    phase: "settling";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Settling draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw participation facts during settlement. */
+    consumer: DrawSequenceConsumerState;
+}
+/**
+ * Granted draw view rendered for a winning draw participation.
+ */
+export interface DrawGrantedView {
+    /** Phase discriminator; `claim()` is legal on this view. */
+    phase: "granted";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Draw distribution facts from the journey projector. */
+    distribution: DistributionSummary & {
+        type: "draw";
+    };
+    /** Consumer draw facts associated with the grant. */
+    consumer: DrawSequenceConsumerState;
+    /** Admission credential issued by the server for this draw win. */
+    grant: AdmissionGrant;
+    /**
+     * Claim the draw admission credential for handoff.
+     *
+     * Legal only while this view is current. It returns the credential
+     * synchronously and may throw if the journey has already left the granted
+     * phase.
+     */
+    claim(): AdmissionGrant;
+}
+/**
+ * Ended draw view rendered once the draw journey is terminal.
+ */
+export interface DrawEndedView {
+    /** Phase discriminator; no draw action is legal after this phase. */
+    phase: "ended";
+    /** Mechanism discriminator for draw rendering. */
+    mechanism: "draw";
+    /** Consumer draw facts at the terminal outcome. */
+    consumer: DrawSequenceConsumerState;
+    /** Server-derived terminal outcome for the draw participation. */
+    outcome: SequenceOutcome;
+}