Skip to main content

​
Core SDK Overview

The @waitify-io/fanfare-sdk-core package provides the foundation for integrating Fanfare experiences into your application. It is a framework-agnostic TypeScript library that handles all communication with the Fanfare API.

​
When to Use the Core SDK

The Core SDK is ideal when you need:
  • Full control over your UI and user experience
  • Framework flexibility - works with React, Vue, Solid, Svelte, or vanilla JavaScript
  • Server-side rendering compatibility
  • Custom state management integration
  • Minimal bundle size without UI components
For most React or SolidJS applications, we recommend using the framework-specific SDKs (@waitify-io/fanfare-sdk-react or @waitify-io/fanfare-sdk-solid) which provide pre-built hooks and components. These packages use the Core SDK internally.

​
Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                         │
├─────────────────────────────────────────────────────────────┤
│  React SDK / Solid SDK (optional)                           │
│  - Hooks (useQueue, useDraw, useAuction, etc.)              │
│  - Components (QueueWidget, DrawWidget, etc.)               │
├─────────────────────────────────────────────────────────────┤
│  Core SDK (@waitify-io/fanfare-sdk-core)                    │
│  ┌─────────────┬─────────────┬─────────────┬──────────────┐ │
│  │    Auth     │   Queues    │    Draws    │   Auctions   │ │
│  ├─────────────┼─────────────┼─────────────┼──────────────┤ │
│  │  Waitlists  │   Timed     │ Experiences │    Beacon    │ │
│  │             │  Releases   │  (Journey)  │  (Analytics) │ │
│  └─────────────┴─────────────┴─────────────┴──────────────┘ │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  State Store  │  Event Bus  │  Tab Sync  │  HTTP Client │ │
│  └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                     Fanfare API                             │
└─────────────────────────────────────────────────────────────┘

​
Key Concepts

​
FanfareSDK Instance

The SDK is initialized once and provides access to all modules: 
import Fanfare from "@waitify-io/fanfare-sdk-core";

const fanfare = await Fanfare.init({
  organizationId: "org_xxx",
  publishableKey: "pk_live_xxx",
});

// Access modules
fanfare.auth; // Authentication
fanfare.queues; // Queue management
fanfare.draws; // Draw/raffle management
fanfare.auctions; // Auction management
fanfare.waitlists; // Waitlist signups
fanfare.timedReleases; // Time-based releases
fanfare.experiences; // Journey orchestration
fanfare.beacon; // Analytics tracking

​
Modules

Each module encapsulates a specific domain:
ModuleDescription
authSession management, guest/authenticated flows
queuesVirtual waiting room with position tracking
drawsLottery-style random selection
auctionsReal-time bidding experiences
waitlistsPre-launch notification signups
timedReleasesTime-window based access
experiencesMulti-stage journey orchestration
beaconClient-side event tracking

​
Experience Journey

The ExperienceJourney class provides a state machine for orchestrating complex consumer journeys through multiple stages: 
const journey = fanfare.experiences.createJourney("exp_123");

// Start the journey
await journey.start({ accessCode: "VIP2024" });

// Subscribe to state changes
journey.state.listen((snapshot) => {
  console.log("Stage:", snapshot.journeyStage);
  console.log("Sequence:", snapshot.sequenceStage);
});

// Perform actions based on available actions
if (snapshot.availableActions.sequence.includes("enter_queue")) {
  await journey.enterQueue();
}

​
Event System

The SDK emits events for all significant state changes: 
// Subscribe to queue events
const unsubscribe = fanfare.on("queue:admitted", (data) => {
  console.log("Admitted to queue:", data.queueId);
  console.log("Token:", data.token);
});

// Clean up when done
unsubscribe();

​
Tab Synchronization

The SDK automatically synchronizes state across browser tabs, ensuring consumers maintain their position even when switching tabs: 
const fanfare = await Fanfare.init({
  organizationId: "org_xxx",
  publishableKey: "pk_live_xxx",
  sync: {
    enabled: true, // Default
    syncKeys: ["session", "activeQueues", "activeDraws"],
  },
});

​
Installation

npm install @waitify-io/fanfare-sdk-core
# or
pnpm add @waitify-io/fanfare-sdk-core
# or
yarn add @waitify-io/fanfare-sdk-core

​
Basic Usage

import Fanfare from "@waitify-io/fanfare-sdk-core";

async function main() {
  // Initialize the SDK
  const fanfare = await Fanfare.init({
    organizationId: "org_xxx",
    publishableKey: "pk_live_xxx",
  });

  // Restore any existing session
  const { session } = await fanfare.restore();

  // Create a guest session if needed
  if (!session) {
    await fanfare.auth.guest();
  }

  // Enter a queue
  const result = await fanfare.queues.enter("queue_123");
  console.log("Position:", result.position);

  // Start polling for updates
  fanfare.queues.startPolling("queue_123");

  // Listen for admission
  fanfare.on("queue:admitted", ({ token }) => {
    console.log("Admitted! Token:", token);
    // Redirect to checkout with token
  });
}

main();

​
TypeScript Support

The Core SDK is written in TypeScript and exports all types: 
import type {
  FanfareConfig,
  FanfareSDK,
  Queue,
  QueueConsumerState,
  Draw,
  DrawResult,
  AuctionDetails,
  BidResult,
  ExperienceJourney,
  JourneySnapshot,
} from "@waitify-io/fanfare-sdk-core";

​
Browser Support

The Core SDK supports all modern browsers:
  • Chrome 80+
  • Firefox 75+
  • Safari 13.1+
  • Edge 80+
For older browsers, ensure you have polyfills for:
  • fetch
  • Promise
  • BroadcastChannel (for tab sync)
  • localStorage

​
Next Steps