FlowsJackpot Library

A TypeScript library for integrating jackpot functionality into web applications with customizable UI widgets, real-time event handling, and player opt-in management.

Installation

npm install flowsjackpot
# or with bun
bun add flowsjackpot

Quick Start

ESM (Recommended)

// Use the default instance (similar to Wave.js)
import flowsJackpots from "flowsjackpot";

flowsJackpots.startJackpotWidget(
  "{{orgId}}",
  "{{gameId}}",
  "{{playerId}}",
  "en",
  { bottom: "20px", right: "20px" },
);

Features

Core Functionality

Widget Management

• startJackpotWidget() - Initialize and display the jackpot widget
• closeJackpotWidget() - Close widget and clean up resources
• Automatic positioning and responsive layout support
• Drag-and-drop widget repositioning
• Mobile-optimized modal display

Real-time Event Handling

• Subscribe to jackpot value updates and win events
• Unsubscribe from all event streams
• Server-sent events for live jackpot value updates
• Instant win notifications with animations

Player Opt-in Management

• Check player's jackpot participation status
• Update player opt-in preferences
• Modal-based opt-in/opt-out interface
• Persistent opt-in status tracking

API Integration

The library includes a comprehensive API service with the following endpoints:

Game Data

• Retrieve jackpot game configuration
• Fetch localized appearance settings

Player Management

• Get player's opt-in status
• Update opt-in preferences

UI Components

Multi-level Jackpot Display

Supports 1-5 jackpot levels with customizable titles and styling:

• Level 1: Mega jackpot (primary display)
• Level 2: Major jackpot
• Level 3: Minor jackpot
• Level 4: Mini jackpot
• Level 5: Rapid jackpot

Navigation System

Three-tab interface:

• Jackpot: Live jackpot values and participation status
• News: Announcements and updates
• Help: User guidance and terms

Visual Effects

• Fireworks animation on jackpot wins
• Winner announcements with customizable messaging
• Responsive animations and transitions
• Mobile-optimized interactions

Configuration Options

Language Support

• Automatic browser language detection
• Custom language specification
• Localized text assets for all UI elements

Positioning

{
  top: '20px',     // Distance from top
  bottom: '20px',  // Distance from bottom
  left: '20px',    // Distance from left
  right: '20px'    // Distance from right
}

Layout Variants

• Desktop: Full-featured widget for desktop screens
• Mobile: Touch-optimized mobile interface
• StickyTop: Fixed top positioning
• StickyLeft: Fixed left sidebar positioning

Device Breakpoints

Configurable responsive breakpoint (default: 480px) for automatic mobile/desktop switching.

API Reference

Methods

startJackpotWidget(orgId, gameId, playerId, language?, startingPosition?, deviceBreakingPoint?)

Initialize and display the jackpot widget.

Parameters:

• orgId (string): Organization identifier
• gameId (string): Game identifier
• playerId (string): Player identifier
• language (string, optional): Language code (e.g., 'en', 'fr-FR')
• startingPosition (Position, optional): Initial widget position
• deviceBreakingPoint (number, optional): Mobile breakpoint in pixels

closeJackpotWidget()

Close the widget and clean up all resources including event listeners and stylesheets.

ListenToJackpotEvents(eventUrl, workspaceId, channel, callback)

Subscribe to real-time jackpot events.

Parameters:

• eventUrl (string): Event server URL
• workspaceId (string): Workspace identifier
• channel (string): Event channel name
• callback (function): Event handler function

StopListeningToJackpotEvents()

Unsubscribe from all active event streams.

Configuration Object

type JackpotGameConfig = {
  organisationId: string;
  playerId: string;
  language: string;
  selectedVariant: "Desktop" | "Mobile";
  defaultPos: Position;
  baseUrl: string;
  eventUrl: string;
  variantBreakingPoint: number;
  optInStatus: OptInStatusEnum;
};

Event Types

Jackpot Events

• jackpot_won: Player wins jackpot (triggers animations)
• jackpot_won_other: Another player wins jackpot
• jackpot_value: Live jackpot value update

Examples

Basic Implementation

// Using default instance (ESM style)
import flowsJackpots from "flowsjackpot";

// Start widget with minimal configuration
flowsJackpots.startJackpotWidget("{{orgId}}", "{{gameId}}", "{{playerId}}");

Advanced Configuration

// Using default instance
import flowsJackpots from "flowsjackpot";

// Custom positioning and language
flowsJackpots.startJackpotWidget(
  "{{orgId}}",
  "{{gameId}}",
  "{{playerId}}",
  "fr-FR",
  { top: "50px", left: "50px" },
  768, // Custom mobile breakpoint
);

// Clean up when done
setTimeout(() => {
  flowsJackpots.closeJackpotWidget();
}, 60000);

Development

This project uses Bun as its package manager. Before starting development:

bun run dev-setup

Use bun for all commands:

bun add package-name
bun run build
bun test

Testing

See example in index.html. Test the widget by running:

bun run build
bun testserver.js

Browser Support

• Modern browsers with ES2015+ support
• Mobile Safari and Chrome for mobile optimization
• Automatic fallbacks for older browsers

License

ISC License

Contributors

• Julian Portelli ([email protected])
• Antoine Duhesme ([email protected])

Version: 2.0.0
Author: Flows LTD