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

``bash
npm install flowsjackpot


or with bun


bun add flowsjackpot
`

Quick Start

$3

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

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

Features

$3

#### 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

$3

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

$3

#### 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

$3

#### Language Support

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

#### Positioning

`javascript
{
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

$3

#### 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.

$3

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

$3

#### Jackpot Events

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

Examples

$3

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

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

$3

`javascript
// 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:

`bash
bun run dev-setup
`

Use bun for all commands:

`bash
bun add package-name
bun run build
bun test
`

$3

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

`bash
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 (julian@flows.world)
- Antoine Duhesme (antoine@flows.world)

---

Version: 2.0.0
Author: Flows LTD