Skip to main content

TypeScript Types

This page documents all exported types from @waitify-io/fanfare-sdk-core.

Importing Types

import type {
  FanfareConfig,
  FanfareSDK,
  Session,
  Queue,
  QueueConsumerState,
  Draw,
  DrawResult,
  AuctionDetails,
  BidResult,
  ExperienceJourney,
  JourneySnapshot,
} from "@waitify-io/fanfare-sdk-core";

Configuration Types

FanfareConfig

interface FanfareConfig {
  organizationId: string;
  publishableKey: string;
  environment?: "production" | "staging" | "development";
  apiUrl?: string;
  debug?: boolean;
  auth?: {
    persistSession?: boolean;
    sessionDuration?: number;
  };
  logging?: {
    level?: "error" | "warn" | "info" | "debug" | "metrics";
  };
  sync?:
    | boolean
    | {
        enabled?: boolean;
        syncKeys?: string[];
        channelName?: string;
      };
  features?: {
    fingerprinting?: boolean;
  };
  beacon?: BeaconConfig;
}

BeaconConfig

interface BeaconConfig {
  enabled?: boolean;
  batchSize?: number;
  flushInterval?: number;
  maxRetries?: number;
}

Session Types

Session

interface Session {
  type: "guest" | "authenticated";
  consumerId: string;
  email?: string;
  phone?: string;
  expiresAt: string;
  deviceFingerprint?: string;
}

GuestSession

interface GuestSession extends Session {
  type: "guest";
  guestId: string;
  email: undefined;
}

AuthenticatedSession

interface AuthenticatedSession extends Session {
  type: "authenticated";
  email?: string;
  phone?: string;
}

AuthStatus

interface AuthStatus {
  isAuthenticated: boolean;
  isGuest?: boolean;
  session?: Session;
}

OtpRequest

interface OtpRequest {
  email?: string;
  phone?: string;
  defaultCountry?: string;
  name?: string;
}

OtpVerify

interface OtpVerify {
  email?: string;
  phone?: string;
  code: string;
  defaultCountry?: string;
}

ExternalExchange

interface ExternalExchange {
  exchangeCode: string;
}

LoginOptions

interface LoginOptions {
  email: string;
}

Queue Types

Queue

interface Queue {
  id: string;
  experienceId: string;
  name: string;
  status: "pending" | "open" | "closed" | "paused";
  capacity?: number;
  currentSize: number;
  estimatedWaitTime?: number;
  openAt?: string;
  closeAt?: string;
}

QueueEnterResult

interface QueueEnterResult {
  position: number;
  estimatedWaitTimeInSeconds: number;
  status: "QUEUED";
}

QueueConsumerState

type QueueConsumerState =
  | QueuedConsumerState
  | AdmittedConsumerState
  | CompletedConsumerState
  | LeftConsumerState
  | DeniedConsumerState
  | NotQueuedConsumerState
  | ExpiredConsumerState;

QueuedConsumerState

interface QueuedConsumerState {
  status: "QUEUED";
  position: number;
  estimatedWaitTimeInSeconds: number;
}

AdmittedConsumerState

interface AdmittedConsumerState {
  status: "ADMITTED";
  admissionToken: string;
  position?: number;
  dequeuedAt?: string;
  expiresAt?: string;
}

CompletedConsumerState

interface CompletedConsumerState {
  status: "COMPLETED";
  admissionToken: string;
  completedAt?: string;
  position?: number;
}

LeftConsumerState

interface LeftConsumerState {
  status: "LEFT";
  dequeuedAt?: string;
  position?: number;
}

DeniedConsumerState

interface DeniedConsumerState {
  status: "DENIED";
  reason: string;
  dequeuedAt?: string;
  position?: number;
}

NotQueuedConsumerState

interface NotQueuedConsumerState {
  status: "NOT_QUEUED";
  dequeuedAt?: string;
  position?: number;
}

ExpiredConsumerState

interface ExpiredConsumerState {
  status: "EXPIRED";
  expiredAt?: string;
  position?: number;
}

QueueParticipation

interface QueueParticipation {
  queueId: string;
  enteredAt: string;
  status: "QUEUED" | "ADMITTED" | "COMPLETED" | "LEFT" | "DENIED" | "NOT_QUEUED" | "EXPIRED";
  position?: number;
  estimatedWaitTime?: number;
  metadata?: Record<string, unknown>;
  admissionToken?: string;
  admittedAt?: string;
  expiresAt?: string;
}

Draw Types

Draw

interface Draw {
  id: string;
  openAt?: string | null;
  closeAt?: string | null;
  timeZone: string;
  supportsGuest: boolean;
  drawAt: string;
  capacity?: number | null;
  continueSelectingUntilCompleted?: boolean | null;
}

DrawConsumerState

type DrawConsumerState = DrawNotEnteredState | DrawEnteredState | DrawWonState | DrawCompletedState | DrawDeniedState;

DrawNotEnteredState

interface DrawNotEnteredState {
  status: "NOT_ENTERED";
}

DrawEnteredState

interface DrawEnteredState {
  status: "ENTERED";
}

DrawWonState

interface DrawWonState {
  status: "WON";
  wonAt: string;
  admissionToken: string;
  fingerprint?: string;
}

DrawCompletedState

interface DrawCompletedState {
  status: "COMPLETED";
  completedAt: string;
  admissionToken: string;
  fingerprint?: string;
}

DrawDeniedState

interface DrawDeniedState {
  status: "DENIED";
  reason: string;
  deniedAt: string;
}

DrawResult

interface DrawResult {
  won: boolean;
  drawTime: string;
  admissionToken?: string;
  prizeDetails?: Record<string, unknown>;
  nextSteps?: string;
}

DrawParticipation

interface DrawParticipation {
  drawId: string;
  enteredAt: string;
  status: "entered" | "drawn" | "won" | "lost" | "expired";
  entryNumber?: string;
  metadata?: Record<string, unknown>;
  result?: DrawResult;
  checkedAt?: string;
  fingerprint?: string;
}

Auction Types

AuctionDetails

interface AuctionDetails {
  id: string;
  openAt?: string | null;
  closeAt?: string | null;
  settleAt: string;
  currencyCode: string;
  reservePrice?: string | null;
  minBidIncrement?: string | null;
  autoExtendSeconds?: number | null;
  timeZone: string;
  supportsGuest: boolean;
}

AuctionStatus

interface AuctionStatus {
  auctionId: string;
  status: "winning" | "outbid" | "watching";
  currentBid?: string;
  highestBid: string;
  timeRemaining: number;
  bidCount?: number;
  position?: number;
}

Bid

interface Bid {
  id?: string;
  amount: string;
  timestamp: string;
  isWinning: boolean;
  bidderAlias?: string;
  isYours?: boolean;
}

BidResult

interface BidResult {
  status: "winning" | "outbid" | "accepted";
  amount: string;
  highestBid: string;
  bidCount: number;
  position?: number;
}

AutoRebidConfig

interface AutoRebidConfig {
  enabled: boolean;
  maxBid: string;
  increment: string;
  remainingBudget?: string;
  lastRebidAt?: string;
  rebidCount?: number;
}

AuctionParticipation

interface AuctionParticipation {
  auctionId: string;
  enteredAt: string;
  status: "watching" | "bidding" | "winning" | "outbid" | "won" | "lost";
  currentBid?: string;
  highestBid?: string;
  bidCount?: number;
  lastBidAt?: string;
  metadata?: Record<string, unknown>;
  fingerprint?: string;
}

Waitlist Types

WaitlistStatus

interface WaitlistStatus {
  waitlistId: string;
  isEntered: boolean;
  enteredAt?: string;
}

WaitlistEntry

interface WaitlistEntry {
  id: string;
  waitlistId: string;
  sequenceId: string;
  consumerId: string;
  enteredAt: string;
}

WaitlistParticipation

interface WaitlistParticipation {
  id: string;
  waitlistId: string;
  sequenceId: string;
  isEntered: boolean;
  enteredAt?: string;
}

Timed Release Types

TimedRelease

interface TimedRelease {
  id: string;
  openAt?: string;
  closeAt?: string;
  timeZone: string;
  supportsGuest: boolean;
}

TimedReleaseConsumerState

type TimedReleaseConsumerState =
  | TimedReleaseNotEnteredState
  | TimedReleaseEnteredState
  | TimedReleaseCompletedState
  | TimedReleaseLeftState;

TimedReleaseNotEnteredState

interface TimedReleaseNotEnteredState {
  status: "NOT_ENTERED";
}

TimedReleaseEnteredState

interface TimedReleaseEnteredState {
  status: "ENTERED";
  enteredAt: string;
  selectedVariantId?: string;
}

TimedReleaseCompletedState

interface TimedReleaseCompletedState {
  status: "COMPLETED";
  completedAt: string;
  selectedVariantId?: string;
}

TimedReleaseLeftState

interface TimedReleaseLeftState {
  status: "LEFT";
  leftAt: string;
}

TimedReleaseParticipation

interface TimedReleaseParticipation {
  timedReleaseId: string;
  enteredAt: string;
  status: "entered" | "completed" | "left";
  selectedVariantId?: string;
  metadata?: Record<string, unknown>;
}

Experience Journey Types

JourneyStage

type JourneyStage = "not_started" | "entering" | "needs_auth" | "needs_access_code" | "routing" | "routed";

SequenceStage

type SequenceStage =
  | "none"
  | "upcoming"
  | "waitlist_entered"
  | "active_enterable"
  | "participating"
  | "admitted"
  | "admission_expired"
  | "ended";

JourneySnapshot

interface JourneySnapshot {
  revision: number;
  updatedAt: number;
  journeyStage: JourneyStage;
  sequenceStage: SequenceStage;
  requirements: Requirement[];
  availableActions: {
    journey: JourneyAction[];
    sequence: SequenceAction[];
  };
  context: JourneyContext;
  events: JourneyEvent[];
  lastSeenEventId?: string;
}

Requirement

interface Requirement {
  type: "authentication" | "access_code" | "bot_check";
  required: boolean;
  reason?: string;
  metadata?: Record<string, unknown>;
}

JourneyContext

interface JourneyContext {
  experienceId: string;
  experience?: ExperienceSession;
  sequenceId?: string;
  distribution?: DistributionSummary;
  participation?: {
    id: string;
    type: "queue" | "draw" | "auction" | "waitlist" | "timed_release";
  };
  accessCode?: string;
  admittanceToken?: string;
  admittanceExpiresAt?: number;
}

JourneyEvent

interface JourneyEvent {
  id: string;
  ts: number;
  kind: "reroute" | "sequence_change" | "distribution_change" | "requirement" | "error" | "info";
  severity: "info" | "success" | "warning" | "error";
  audience: "user" | "system" | "analytics";
  message: string;
  detail?: Record<string, unknown>;
}

JourneyAction

type JourneyAction =
  | "start"
  | "authenticate"
  | "provide_access_code"
  | "skip_access_code"
  | "request_reroute"
  | "retry"
  | "complete_bot_check"
  | "refresh_distribution";

SequenceAction

type SequenceAction =
  | "enter_waitlist"
  | "leave_waitlist"
  | "enter_queue"
  | "enter_draw"
  | "enter_auction"
  | "enter_timed_release"
  | "complete_timed_release"
  | "leave_participation";

SDK Instance Type

FanfareSDK

interface FanfareSDK {
  readonly auth: AuthModule;
  readonly queues: QueueModule;
  readonly draws: DrawModule;
  readonly auctions: AuctionModule;
  readonly experiences: ExperienceModule;
  readonly waitlists: WaitlistModule;
  readonly timedReleases: TimedReleaseModule;
  readonly beacon: BeaconModule;

  restore(): Promise<RestoreResult>;
  resume(): Promise<void>;
  getActiveExperiences(): Promise<ActiveExperiences>;
  on<K extends keyof SDKEvents>(event: K, handler: (data: SDKEvents[K]) => void): () => void;
  destroy(): Promise<void>;
}

RestoreResult

interface RestoreResult {
  session: Session | null;
  experiences: {
    queues: Record<string, QueueParticipation>;
    draws: Record<string, DrawParticipation>;
    auctions: Record<string, AuctionParticipation>;
    appointments: Record<string, unknown>;
    waitlists: Record<string, WaitlistParticipation>;
    timedReleases: Record<string, TimedReleaseParticipation>;
    experiences: Record<string, ExperienceSession>;
  };
}

ActiveExperiences

interface ActiveExperiences {
  queues: string[];
  draws: string[];
  auctions: string[];
  appointments: string[];
  waitlists: string[];
  timedReleases: string[];
  experiences: string[];
}

Consumer Types

Consumer

interface Consumer {
  id: string;
  email?: string;
  createdAt: string;
  metadata?: Record<string, unknown>;
}

Error Types

See Error Handling for error types.