@fanfare-io/fanfare-sdk-core 0.1.0

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

@@ -0,0 +1,395 @@
+import { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, DistributionLifecycle, DistributionType, DrawConsumerStatus, JourneyStage, QueueConsumerStatus, SequenceOutcome, SequenceOutcomeType, SequencePhase, TimedReleaseConsumerStatus, WaitlistConsumerStatus } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { ReadableAtom } from 'nanostores';
+import { BotMitigationState, RoutingChallenge } from '../challenges/types';
+import { SdkJourneyParticipationType } from '../types/distribution-type';
+import { AppointmentDisplayState, AuctionDisplayState, DrawDisplayState, QueueDisplayState, TimedReleaseDisplayState } from './distribution-monitor.types';
+import { DistributionDetails, ExperienceSession, Sequence } from './types';
+export type { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, DistributionLifecycle, DistributionType, DrawConsumerStatus, JourneyStage, QueueConsumerStatus, SequenceOutcome, SequenceOutcomeType, SequencePhase, TimedReleaseConsumerStatus, WaitlistConsumerStatus, };
+export type SequenceMechanism = DistributionType | "waitlist";
+export type PrimarySequenceMechanism = DistributionType;
+export type GrantProducingSequenceMechanism = Exclude<PrimarySequenceMechanism, "appointment">;
+export type SettlingSequenceMechanism = "draw" | "auction";
+export interface DistributionSummary {
+    type: DistributionType;
+    id: string;
+    sequenceId?: string;
+    lifecycle: DistributionLifecycle;
+    startsAt?: string;
+    opensAt?: string;
+    closesAt?: string;
+    settlesAt?: string;
+    waitlistId?: string;
+    details?: DistributionDetails;
+    updatedAt?: number;
+}
+export interface DistributionTarget {
+    type: DistributionType;
+    id: string;
+    sequenceId?: string;
+    lifecycle: DistributionLifecycle;
+    opensAt?: string;
+    closesAt?: string;
+    waitlistId?: string;
+    details?: Record<string, unknown>;
+    updatedAt?: number;
+}
+export type SequenceDistributionState = DistributionSummary;
+export type SequenceTargetState = DistributionTarget;
+export interface QueueSequenceConsumerState {
+    status: QueueConsumerStatus;
+    id?: string;
+    distributionId?: string;
+    enteredAt?: string;
+    admissionGrant?: string;
+    grantedAt?: string;
+    deniedReason?: string;
+    position?: number;
+}
+export interface DrawSequenceConsumerState {
+    status: DrawConsumerStatus;
+    id?: string;
+    distributionId?: string;
+    enteredAt?: string;
+    admissionGrant?: string;
+    grantedAt?: string;
+    deniedReason?: string;
+}
+export interface AuctionSequenceConsumerState {
+    status: AuctionConsumerStatus;
+    id?: string;
+    distributionId?: string;
+    enteredAt?: string;
+    admissionGrant?: string;
+    grantedAt?: string;
+    deniedReason?: string;
+    highestBid?: string;
+    currentBid?: string;
+}
+export interface TimedReleaseSequenceConsumerState {
+    status: TimedReleaseConsumerStatus;
+    id?: string;
+    distributionId?: string;
+    enteredAt?: string;
+    admissionGrant?: string;
+    grantedAt?: string;
+    deniedReason?: string;
+}
+export interface AppointmentSequenceConsumerState {
+    status: AppointmentConsumerStatus;
+    id?: string;
+    distributionId?: string;
+    slotId?: string;
+    locationId?: string;
+    bookedAt?: string;
+    checkedInAt?: string;
+    completedAt?: string;
+    cancelledAt?: string;
+    noShowAt?: string;
+}
+export interface WaitlistSequenceConsumerState {
+    status: WaitlistConsumerStatus;
+    id?: string;
+    waitlistId?: string;
+    enteredAt?: string;
+    notifiedAt?: string;
+}
+export type ConsumerSequenceState = QueueSequenceConsumerState | DrawSequenceConsumerState | AuctionSequenceConsumerState | TimedReleaseSequenceConsumerState | AppointmentSequenceConsumerState | WaitlistSequenceConsumerState;
+export type SequenceConsumerFor<M extends SequenceMechanism> = M extends "queue" ? QueueSequenceConsumerState : M extends "draw" ? DrawSequenceConsumerState : M extends "auction" ? AuctionSequenceConsumerState : M extends "timed_release" ? TimedReleaseSequenceConsumerState : M extends "appointment" ? AppointmentSequenceConsumerState : WaitlistSequenceConsumerState;
+export type MechanismConsumerState = (QueueSequenceConsumerState & {
+    mechanism: "queue";
+}) | (DrawSequenceConsumerState & {
+    mechanism: "draw";
+}) | (AuctionSequenceConsumerState & {
+    mechanism: "auction";
+}) | (TimedReleaseSequenceConsumerState & {
+    mechanism: "timed_release";
+}) | (AppointmentSequenceConsumerState & {
+    mechanism: "appointment";
+}) | (WaitlistSequenceConsumerState & {
+    mechanism: "waitlist";
+});
+interface PrimarySequenceContext<M extends PrimarySequenceMechanism> {
+    mechanism: M;
+    distribution: DistributionSummary & {
+        type: M;
+    };
+    consumer: SequenceConsumerFor<M>;
+}
+interface WaitlistSequenceContext {
+    mechanism: "waitlist";
+    target: DistributionTarget;
+    consumer: WaitlistSequenceConsumerState;
+}
+export type UnavailableSequenceState = {
+    phase: "unavailable";
+    reason?: string;
+};
+export type ScheduledSequenceState = {
+    [M in PrimarySequenceMechanism]: {
+        phase: "scheduled";
+    } & PrimarySequenceContext<M>;
+}[PrimarySequenceMechanism];
+export type EnterableSequenceState = {
+    [M in PrimarySequenceMechanism]: {
+        phase: "enterable";
+    } & PrimarySequenceContext<M>;
+}[PrimarySequenceMechanism] | ({
+    phase: "enterable";
+} & WaitlistSequenceContext);
+export type ParticipatingSequenceState = {
+    [M in PrimarySequenceMechanism]: {
+        phase: "participating";
+    } & PrimarySequenceContext<M>;
+}[PrimarySequenceMechanism] | ({
+    phase: "participating";
+} & WaitlistSequenceContext);
+export type SettlingSequenceState = {
+    [M in SettlingSequenceMechanism]: {
+        phase: "settling";
+    } & PrimarySequenceContext<M>;
+}[SettlingSequenceMechanism];
+export type GrantedSequenceState = {
+    [M in GrantProducingSequenceMechanism]: {
+        phase: "granted";
+        grant: AdmissionGrant;
+    } & PrimarySequenceContext<M>;
+}[GrantProducingSequenceMechanism];
+export type EndedSequenceState = {
+    [M in PrimarySequenceMechanism]: {
+        phase: "ended";
+        outcome: SequenceOutcome;
+    } & PrimarySequenceContext<M>;
+}[PrimarySequenceMechanism] | ({
+    phase: "ended";
+    outcome: SequenceOutcome;
+} & WaitlistSequenceContext);
+export type SequenceState = UnavailableSequenceState | ScheduledSequenceState | EnterableSequenceState | ParticipatingSequenceState | SettlingSequenceState | GrantedSequenceState | EndedSequenceState;
+export type ActiveSequenceState = Exclude<SequenceState, UnavailableSequenceState>;
+export type SequenceStateFor<M extends SequenceMechanism> = Extract<ActiveSequenceState, {
+    mechanism: M;
+}>;
+export type PrimarySequenceState = Extract<ActiveSequenceState, {
+    distribution: DistributionSummary;
+}>;
+export type ConsumerJourneyState = {
+    journeyStage: "ready";
+    experienceId: string;
+    updatedAt?: string;
+} | {
+    journeyStage: "routing";
+    experienceId: string;
+    updatedAt?: string;
+} | {
+    journeyStage: "gated";
+    experienceId: string;
+    updatedAt?: string;
+    gates: unknown[];
+    selected?: {
+        sequenceId: string;
+    };
+} | {
+    journeyStage: "routed";
+    experienceId: string;
+    updatedAt?: string;
+    sequenceId: string;
+    sequence: SequenceState;
+    offers?: unknown[];
+};
+export type ServiceJourneyState = Extract<ConsumerJourneyState, {
+    journeyStage: "gated" | "routed";
+}>;
+export type ServiceJourneyStage = ServiceJourneyState["journeyStage"];
+export type RoutingGate = {
+    type: "authentication";
+    status: "required";
+} | {
+    type: "access_code";
+    status: "missing" | "invalid";
+} | {
+    type: "bot_check";
+    status: "required" | "blocked";
+    challenge?: RoutingChallenge;
+    mitigation?: BotMitigationState;
+};
+export interface RoutingOffer {
+    sequence: Sequence;
+    status: "gated";
+    gates: RoutingGate[];
+}
+export interface Participation {
+    id: string;
+    type: SdkJourneyParticipationType;
+}
+export type JourneyEventKind = "reroute" | "sequence_change" | "distribution_change" | "requirement" | "error" | "info";
+export type JourneyEventSeverity = "info" | "success" | "warning" | "error";
+export type JourneyEventAudience = "user" | "system" | "analytics";
+export interface JourneyEvent {
+    id: string;
+    ts: number;
+    kind: JourneyEventKind;
+    severity: JourneyEventSeverity;
+    audience: JourneyEventAudience;
+    message: string;
+    detail?: Record<string, unknown>;
+}
+interface JourneyBase {
+    revision: number;
+    updatedAt: number;
+    experienceId: string;
+    accessCode?: string;
+    experience?: ExperienceSession;
+    events: JourneyEvent[];
+    lastSeenEventId?: string;
+}
+export interface ReadySnapshot extends JourneyBase {
+    journeyStage: "ready";
+}
+export interface RoutingSnapshot extends JourneyBase {
+    journeyStage: "routing";
+}
+export interface GatedSnapshot extends JourneyBase {
+    journeyStage: "gated";
+    gates: RoutingGate[];
+    selected?: {
+        sequence: Sequence;
+        status: "gated";
+    };
+}
+export interface RoutedSnapshot extends JourneyBase {
+    journeyStage: "routed";
+    sequenceId: string;
+    offers: RoutingOffer[];
+    sequence: SequenceState;
+}
+export type JourneySnapshot = ReadySnapshot | RoutingSnapshot | GatedSnapshot | RoutedSnapshot;
+export interface ReadyView {
+    journeyStage: "ready";
+    start(opts?: {
+        accessCode?: string;
+    }): Promise<void>;
+}
+export interface RoutingView {
+    journeyStage: "routing";
+}
+export interface GatedView {
+    journeyStage: "gated";
+    gates: RoutingGate[];
+    selected?: {
+        sequence: Sequence;
+        status: "gated";
+    };
+    reroute(opts?: {
+        accessCode?: string;
+    }): Promise<void>;
+    retry(): Promise<void>;
+}
+export interface RoutedView {
+    journeyStage: "routed";
+    sequenceId: string;
+    offers: RoutingOffer[];
+    reroute(): Promise<void>;
+    retry(): Promise<void>;
+    sequence: SequenceView;
+}
+export type ParticipatingSequenceView = {
+    phase: "participating";
+    mechanism: "queue";
+    consumer: QueueSequenceConsumerState;
+    state$: ReadableAtom<QueueDisplayState>;
+    leave(): Promise<void>;
+} | {
+    phase: "participating";
+    mechanism: "draw";
+    consumer: DrawSequenceConsumerState;
+    state$: ReadableAtom<DrawDisplayState>;
+    leave(): Promise<void>;
+} | {
+    phase: "participating";
+    mechanism: "auction";
+    consumer: AuctionSequenceConsumerState;
+    state$: ReadableAtom<AuctionDisplayState>;
+    bid(amount: string): Promise<void>;
+    leave(): Promise<void>;
+} | {
+    phase: "participating";
+    mechanism: "timed_release";
+    consumer: TimedReleaseSequenceConsumerState;
+    state$: ReadableAtom<TimedReleaseDisplayState>;
+    leave(): Promise<void>;
+    complete(): Promise<void>;
+} | {
+    phase: "participating";
+    mechanism: "appointment";
+    consumer: AppointmentSequenceConsumerState;
+    state$: ReadableAtom<AppointmentDisplayState>;
+    cancel(reason?: string): Promise<void>;
+    reschedule(newSlotId: string, newLocationId?: string): Promise<void>;
+} | {
+    phase: "participating";
+    mechanism: "waitlist";
+    consumer: WaitlistSequenceConsumerState;
+    leave(): Promise<void>;
+};
+export type EnterableSequenceView = {
+    phase: "enterable";
+    mechanism: Exclude<PrimarySequenceMechanism, "appointment" | "auction">;
+    distribution: DistributionSummary;
+    consumer: Exclude<ConsumerSequenceState, AppointmentSequenceConsumerState | WaitlistSequenceConsumerState>;
+    enter(): Promise<void>;
+} | {
+    phase: "enterable";
+    mechanism: "auction";
+    distribution: DistributionSummary;
+    consumer: AuctionSequenceConsumerState;
+    bid(amount: string): Promise<void>;
+} | {
+    phase: "enterable";
+    mechanism: "appointment";
+    distribution: DistributionSummary;
+    consumer: AppointmentSequenceConsumerState;
+    book(slotId: string, locationId?: string): Promise<void>;
+} | {
+    phase: "enterable";
+    mechanism: "waitlist";
+    target: DistributionTarget;
+    consumer: WaitlistSequenceConsumerState;
+    enter(): Promise<void>;
+};
+export type ScheduledSequenceView = {
+    phase: "scheduled";
+    mechanism: PrimarySequenceMechanism;
+    distribution: DistributionSummary;
+    consumer: Exclude<ConsumerSequenceState, WaitlistSequenceConsumerState>;
+    startsAt?: string;
+};
+export type SequenceView = {
+    phase: "unavailable";
+    reason?: string;
+} | ScheduledSequenceView | EnterableSequenceView | ParticipatingSequenceView | {
+    phase: "settling";
+    mechanism: SettlingSequenceMechanism;
+    distribution: DistributionSummary;
+    consumer: DrawSequenceConsumerState | AuctionSequenceConsumerState;
+} | {
+    phase: "granted";
+    mechanism: GrantProducingSequenceMechanism;
+    distribution: DistributionSummary;
+    consumer: QueueSequenceConsumerState | DrawSequenceConsumerState | AuctionSequenceConsumerState | TimedReleaseSequenceConsumerState;
+    grant: AdmissionGrant;
+    claim(): AdmissionGrant;
+} | {
+    phase: "ended";
+    mechanism: SequenceMechanism;
+    consumer: ConsumerSequenceState;
+    outcome: SequenceOutcome;
+};
+export type JourneyView = ReadyView | RoutingView | GatedView | RoutedView;
+export interface JourneyHandle {
+    view$: ReadableAtom<JourneyView>;
+    events$: ReadableAtom<JourneyEvent[]>;
+    latestEvent$: ReadableAtom<JourneyEvent | null>;
+    snapshot$: ReadableAtom<JourneySnapshot>;
+    ackEvent(eventId: string): void;
+    ackAllEvents(): void;
+    destroy(): void;
+}

package/dist/experiences/public.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public experience/journey type surface.
+ *
+ * Mirrors exactly the experience symbols on the root barrel — the runtime
+ * `ExperienceManagementModule`/`ExperienceJourney`/error classes from
+ * `experience.module`/`journey` are deliberately not re-exported here.
+ *
+ * Internal routing responses from `ExperienceManagementModule` are deliberately
+ * omitted; public consumers route through `JourneyView` and `JourneySnapshot`.
+ */
+export type { JourneysModule } from '../types';
+export type { AdmissionGrant, AppointmentConsumerStatus, AuctionConsumerStatus, ConsumerJourneyState, ConsumerSequenceState, DistributionLifecycle, DistributionSummary, DistributionTarget, DistributionType, DrawConsumerStatus, EnterableSequenceView, GatedSnapshot, GatedView, JourneyEvent, JourneyEventAudience, JourneyEventKind, JourneyEventSeverity, JourneyHandle, JourneySnapshot, JourneyStage, JourneyView, ParticipatingSequenceView, Participation, PrimarySequenceMechanism, QueueConsumerStatus, ReadySnapshot, ReadyView, RoutedSnapshot, RoutedView, RoutingGate, RoutingOffer, RoutingSnapshot, RoutingView, SequenceMechanism, SequenceOutcome, SequenceOutcomeType, SequencePhase, SequenceState, SequenceTargetState, SequenceView, ServiceJourneyStage, ServiceJourneyState, TimedReleaseConsumerStatus, WaitlistConsumerStatus, } from './journey.types';
+export type { ConsumerMe, Distribution, DistributionContext, Experience, ExperienceDetails, ExperienceSession, JourneyDistributionType, JourneyParticipationType, Sequence, } from './types';

package/dist/experiences/public.js

@@ -0,0 +1 @@
+

package/dist/experiences/types.d.ts

@@ -0,0 +1,161 @@
+import { ConsumerMeResponse } from '@fanfare-io/fanfare-sdk-contracts/consumer-me';
+import { BrandTheme } from '../theme';
+import { SdkDistributionEntryType, SdkJourneyAdmissionType, SdkJourneyParticipationType } from '../types/distribution-type';
+/**
+ * Experience Module Types
+ * Orchestrates experience-centric customer journeys
+ */
+export interface Experience {
+    id: string;
+    name: string;
+    description?: string;
+    imageUrl?: string;
+    /** Organization-level currency code (ISO 4217), when available */
+    currencyCode?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ExperienceDetails extends Experience {
+    sequences?: Sequence[];
+    metadata?: Record<string, unknown>;
+    i18n?: Record<string, Record<string, string>>;
+    theme?: BrandTheme;
+}
+export interface ExperienceSession {
+    experienceId: string;
+    enteredAt: string;
+    assignedSequenceId?: string;
+    waitlistId?: string;
+    currentDistribution?: {
+        type: SdkDistributionEntryType;
+        id: string;
+        status: "upcoming" | "active" | "ended";
+    };
+    /** Full experience details including theme and i18n, returned from enter endpoint */
+    experience?: ExperienceDetails;
+}
+export interface Sequence {
+    id: string;
+    name: string;
+    experienceId: string;
+    priority: number;
+    color: string;
+    requiresAccessCode?: boolean;
+    audienceId?: string;
+}
+export type { RoutingGate, RoutingOffer } from './journey.types';
+/**
+ * Structured routing result from `findSequence()`.
+ *
+ * Server bot-risk assessment is validated as part of the routing response contract,
+ * but is intentionally not exposed here; gates carry the actionable client state.
+ */
+export interface RoutingResult {
+    outcome: "routed" | "gated" | "no_access";
+    selected?: {
+        sequence: Sequence;
+        status: "admissible" | "gated";
+        gates: import('./journey.types').RoutingGate[];
+        capabilityGrant?: string;
+        capabilityGrantExpiresAt?: string;
+    };
+    offers: import('./journey.types').RoutingOffer[];
+}
+export interface SequenceAccessResult {
+    sequenceId: string;
+    hasAccess: boolean;
+    accessReasons: string[];
+    deniedReasons: string[];
+}
+export interface Distribution {
+    id: string;
+    type: SdkDistributionEntryType;
+    sequenceId: string;
+    status: "scheduled" | "active" | "ended";
+    openAt?: string;
+    closeAt?: string;
+}
+export interface DistributionContext {
+    recentPast?: {
+        type: SdkDistributionEntryType;
+        id: string;
+        endedAt: string;
+        result?: "won" | "lost" | "participated";
+    };
+    active?: {
+        type: SdkDistributionEntryType;
+        id: string;
+        status: "active";
+        details: DistributionDetails;
+    };
+    upcoming?: {
+        type: SdkDistributionEntryType;
+        id: string;
+        startsAt: string;
+        waitlistId?: string;
+    };
+}
+export interface BaseDistributionDetails {
+    id: string;
+    type: SdkDistributionEntryType;
+    openAt?: string;
+    closeAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface QueueDetails extends BaseDistributionDetails {
+    type: "queue";
+    estimatedWaitTime?: number;
+    queueLength?: number;
+}
+export interface DrawDetails extends BaseDistributionDetails {
+    type: "draw";
+    drawTime?: string;
+    entryDeadline?: string;
+    maxEntries?: number;
+}
+export interface AuctionDetails extends BaseDistributionDetails {
+    type: "auction";
+    startsAt?: string;
+    endsAt?: string;
+    currentBid?: string;
+    reservePrice?: string;
+    bidIncrement?: string;
+    minNextBid?: string;
+    currencyCode?: string;
+}
+export interface AppointmentDetails extends BaseDistributionDetails {
+    type: "appointment";
+    slotDurationMinutes?: number;
+    bookingWindowOpenAt?: string;
+    bookingWindowCloseAt?: string;
+    timezone?: string;
+    locationId?: string;
+    totalSlots?: number;
+    availableSlots?: number;
+}
+export interface TimedReleaseDetails extends BaseDistributionDetails {
+    type: "timed_release";
+    openAt?: string;
+    closeAt?: string;
+}
+export type DistributionDetails = QueueDetails | DrawDetails | AuctionDetails | AppointmentDetails | TimedReleaseDetails;
+export interface ExperienceModule {
+    get(experienceId: string): Promise<ExperienceDetails>;
+    enter(experienceId: string): Promise<ExperienceSession>;
+    leave(experienceId: string): Promise<void>;
+    findSequence(experienceId: string, accessCode?: string): Promise<RoutingResult>;
+    validateSequenceAccess(sequenceId: string, accessCode?: string): Promise<SequenceAccessResult>;
+    selectSequence(sequenceId: string): Promise<void>;
+    getCurrentDistributions(sequenceId: string): Promise<DistributionContext>;
+    enterDistribution(distribution: DistributionContext["active"]): Promise<void>;
+    getActiveSession(): ExperienceSession | null;
+    isInExperience(experienceId: string): boolean;
+    getSelectedSequence(): Sequence | null;
+    /** Fetch authenticated consumer participations for resume flows */
+    getMe(): Promise<ConsumerMe>;
+    destroy(): void;
+}
+export type JourneyParticipationType = SdkJourneyParticipationType;
+export type JourneyDistributionType = SdkJourneyAdmissionType;
+export type ConsumerMe = ConsumerMeResponse;
+export type ResumeJourneysResult = string[];