Roster Watcher 🏀

A Discord bot that monitors Swedish basketball league rosters (SBL Herr / SBL Dam) and notifies you when key players are missing from game rosters.

Features

• Live Roster Monitoring: Fetches game rosters from FIBA LiveStats/GeniusSports
• Season Stats Integration: Pulls player statistics from Eurobasket.com
• Key Player Detection: Identifies key players based on MPG threshold (default: 15.0 MPG)
• Smart Name Matching: Fuzzy matching between different data sources with confidence scoring
• Out Streak Tracking: Tracks consecutive missed games for players
• Discord Notifications: Rich embeds with player stats and streak information
• Deduplication: Avoids sending duplicate alerts for the same game/team

Prerequisites

• Node.js 20+
• npm or yarn
• A Discord webhook URL

Installation

1. Clone and install dependencies:

   cd DiscordBot
   npm install

2. Configure environment:

   cp .env.example .env

   Edit .env and set your Discord webhook URL:

   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN
   

3. Initialize the database:

   npm run db:init

4. Sync player data from Eurobasket:

   npm run sync-eurobasket

5. Test Discord integration:

   npm run test-discord

Usage

Start Watching

npm run watch

This will:

• Poll for upcoming games every 5 minutes (configurable)
• Fetch rosters when they become available (typically 15-30 min before tip-off)
• Compare against Eurobasket season stats
• Send Discord alerts for missing key players

Check a Specific Game

npm run check-game <gameId>
# Example: npm run check-game 123456

Other Commands

# List teams in database
npm start -- list-teams

# List unmatched players (for manual mapping)
npm start -- list-unmatched

# Show current configuration
npm start -- show-config

# Sync Eurobasket data for specific league
npm start -- sync-eurobasket --league SBL_HERR

Configuration

All configuration is done via environment variables (see .env.example):

Variable	Default	Description
DISCORD_WEBHOOK_URL	(required)	Discord webhook URL for notifications
DATABASE_PATH	./data/roster.db	SQLite database file path
LOG_LEVEL	info	Logging level: debug, info, warn, error
KEY_PLAYER_MIN_MPG	15.0	Minimum MPG to be considered a key player
FUZZY_MATCH_THRESHOLD	75	Minimum confidence % for name matching
ROSTER_POLL_INTERVAL_MINUTES	5	How often to poll for new rosters
PRE_GAME_POLL_START_MINUTES	90	When to start polling before tip-off
DAYS_AHEAD	1	Days ahead to look for games
EUROBASKET_CACHE_MINUTES	60	Cache duration for Eurobasket data
TEST_MODE	false	If true, logs Discord messages instead of sending

Discord Message Format

🏀 SBL Herr: Team A vs Team B
HOME team missing key players

❌ Player Name
📊 25.5 MPG / 18.2 PPG / 5.1 RPG / 3.4 APG
⏮️ Played previous: No
🔢 3 consecutive games missed

📅 Game Info
Date: 2026-02-06
Time: 18:00

League Schedule Configuration

The bot needs to discover game schedules. The URLs are configured in src/config.ts:

Current Configuration

leagues: {
  SBL_HERR: {
    fibaScheduleUrl: 'https://fibalivestats.dcd.shared.geniussports.com/data/competition/schedule.json',
    eurobasketUrl: 'https://basketball.eurobasket.com/Sweden/basketball-league-Swedish-Basketligan',
  },
  SBL_DAM: {
    fibaScheduleUrl: 'https://fibalivestats.dcd.shared.geniussports.com/data/competition/schedule.json',
    eurobasketUrl: 'https://basketball.eurobasket.com/Sweden/basketball-league-Swedish-Basketligan-Women',
  },
}

How to Update Schedule URLs

1. Find the correct FIBA LiveStats URL:

   • Go to the Swedish Basketball Federation site or FIBA website
   • Find a live game and inspect the network requests
   • Look for URLs containing fibalivestats or livestats.dcd.shared.geniussports.com
   • The schedule endpoint typically follows patterns like:
     • https://fibalivestats.dcd.shared.geniussports.com/data/{competitionId}/schedule.json
     • https://livestats.dcd.shared.geniussports.com/u/SBBF/

2. Update src/config.ts:

   fibaScheduleUrl: 'YOUR_NEW_URL_HERE',

3. Add alternative sources in alternativeScheduleSources:

   alternativeScheduleSources: {
     SBL_HERR: [
       'https://www.basket.se/tavling/serier-och-matcher/?serie=sbl-herr',
       // Add more URLs here
     ],
   }

Game ID Discovery

If you can't find an automatic schedule URL, you can manually check games:

1. Find the game page URL (e.g., https://fibalivestats.dcd.shared.geniussports.com/u/SBBF/2345678/)
2. Extract the game ID (2345678)
3. Run: npm run check-game 2345678

Database Schema

The SQLite database stores:

• teams: Team information and mappings
• players: Player stats from Eurobasket
• name_mappings: Fuzzy match mappings between FIBA and Eurobasket names
• games: Game schedule and status
• player_game_participation: Who played in which games
• alerts_sent: Deduplication tracking
• cache: Temporary cache for API responses
• unmatched_players: Players that couldn't be matched (for review)

Handling Name Mismatches

When the fuzzy matcher can't confidently match a FIBA name to an Eurobasket player:

1. Run npm start -- list-unmatched to see unmatched names

2. The output shows the best match and confidence score

3. If names are clearly the same person, you can add a manual mapping:

   -- In SQLite
   INSERT INTO manual_name_overrides (fiba_name, eurobasket_name, team_id)
   VALUES ('J. Smith', 'John Smith', 1);

Architecture

src/
├── index.ts           # CLI entry point
├── config.ts          # Configuration management
├── sources/
│   ├── fiba.ts       # FIBA LiveStats parser
│   └── eurobasket.ts # Eurobasket.com parser
├── matching/
│   ├── normalize.ts  # Name normalization (diacritics, etc.)
│   └── match.ts      # Fuzzy matching logic
├── db/
│   ├── schema.sql    # Database schema
│   ├── db.ts         # Database connection
│   └── repo.ts       # Data access layer
├── logic/
│   ├── compare.ts    # Roster comparison
│   └── streaks.ts    # Missed game streak tracking
├── notify/
│   └── discord.ts    # Discord webhook integration
└── utils/
    └── logger.ts     # Logging configuration

Troubleshooting

"Roster not available"

• Rosters are typically published 15-30 minutes before tip-off
• Try again closer to game time

"Teams not found in database"

• Run npm run sync-eurobasket to populate team data

"Could not match FIBA player"

• Check npm start -- list-unmatched
• Add manual mapping if needed
• Lower FUZZY_MATCH_THRESHOLD if too strict

Discord messages not sending

• Verify webhook URL in .env
• Run npm run test-discord to test
• Check logs/error.log for details

Development

# Run with debug logging
LOG_LEVEL=debug npm run watch

# Test mode (logs instead of sending)
TEST_MODE=true npm run check-game 123456

# Type checking
npm run typecheck

License

MIT