Idle Champions Code Redeemer Bot

A Discord bot that automatically scans for and redeems Idle Champions promo codes. Replaces the browser extension with a 24/7 cloud-ready bot that runs on your Discord server.

Features

🤖 Slash Commands - /setup, /redeem, /catchup, /autoredeem, /inventory, /open, /blacksmith, /codes, /makepublic, /notifications, /stats, /logs, /backfill, /deleteaccount, /help
🔄 Auto Code Detection - Scans Discord messages for codes automatically
🤖 Auto-Redeem Toggle - Enable or disable automatic code redemption per user (/autoredeem)
🔔 DM Notifications - Configurable per-user DM alerts for new codes, successes, and failures (/notifications)
📊 Server Stats - Aggregate loot totals and redemption statistics (/stats)
⏮️ Message History Backfill - Recover missed codes from message history (protected with rate limiting)
🎁 Code Redemption - Submit codes and get rewards
📦 Chest Management - Open chests and view loot
⚒️ Blacksmith - Upgrade heroes with contracts
📋 Inventory - View gold, rubies, equipment, and progress
🔐 Encrypted Credentials - AES-256-GCM encryption for stored user credentials
💾 Secure Storage - SQLite database keeps credentials safe and local
🗑️ Account Deletion - GDPR-friendly self-service removal of all stored data (/deleteaccount)
👥 Multi-User - Each user manages their own account
⚡ Fast - Built on Bun for 3-4x performance vs Node.js

Quick Start

Prerequisites

Mise 2024+ (or Bun 1.3.14+ if you prefer to manage tools manually)
Discord bot token

Setup (5 minutes)

# 1. Clone and enter directory
git clone <repo> && cd idle-code-redeemer

# 2. Install dependencies (Mise manages Bun automatically)
mise run install

# 3. Configure environment
cp .env.example .env
# Edit .env and add:
# - DISCORD_TOKEN (from Discord Developer Portal)
# - DISCORD_GUILD_ID (your server ID)
# - DISCORD_CHANNEL_ID (where bot scans for codes)
# - DISCORD_CODE_AUTHOR_ID (ID of the bot that posts codes, e.g. Idle Champions #combinations)
# - ENCRYPTION_KEY — generate once with: openssl rand -hex 32
#   ⚠️  Store this value safely and never regenerate it for an existing database;
#       changing the key makes previously saved credentials unreadable.

# 4. Start the bot
mise run dev

Don't have Mise? Install it first

# macOS/Linux
curl https://mise.jdx.dev/install.sh | sh

# Or with Homebrew
brew install mise

Commands

Command	Description
`/setup user_id:<id> user_hash:<hash>`	Save your Idle Champions credentials
`/redeem code:<code>`	Manually redeem a code
`/catchup`	Redeem all known valid codes you haven't claimed yet
`/autoredeem enabled:<on\|off>`	Toggle automatic redemption of new codes for your account
`/inventory`	View your account (gold, rubies, equipment, progress)
`/open chest_type:<type> count:<count>`	Open chests (Gold, Sapphire, etc.)
`/blacksmith contract_type:<type> hero_id:<id> count:<count>`	Upgrade heroes
`/codes`	Show your redeemed codes history (paginated, 5 per page)
`/makepublic code:<code>`	Share one of your redeemed codes with other users
`/notifications`	View/update DM notification preferences
`/stats`	Server-wide statistics and aggregate loot totals
`/logs [lines:<1-100>]`	Show last N lines of combined.log (admin only)
`/backfill [channel:<channel>]`	Recover missed codes from message history (admin only)
`/deleteaccount`	Permanently delete all your stored data (GDPR)
`/help`	Show all commands

Setup & Authentication

`/setup user_id:<id> user_hash:<hash>`

Initialize your account with the bot. You need your Idle Champions user ID and user hash to authenticate.

Required parameters:
- user_id - Your Idle Champions user ID (found in game settings)
- user_hash - Your user hash token (also in game settings)
Security: Credentials are encrypted and stored locally in SQLite
Example: /setup user_id:12345 user_hash:abc123def456

Code Redemption

`/redeem code:<code>`

Manually redeem a single code and immediately receive rewards.

Required parameters:
- code - The promo code to redeem (e.g., IDLE2024)
Response: Shows rewards obtained (gold, rubies, chests, etc.)
Example: /redeem code:IDLE2024

`/catchup`

Redeem all known valid codes that you have not yet claimed. Useful when you first join the server or the bot was offline when new codes were posted.

No parameters required
Behaviour:
- Fetches every code the bot knows about (redeemed by any user + pending codes)
- Skips codes you have already redeemed
- Skips codes that have already expired
- Refreshes your instance_id every 10 API calls to prevent staleness
- Adds a 150 ms delay between API calls to avoid rate limiting
Response: Reports how many codes were newly redeemed, already had, expired, or failed
Available to: All users (no special permissions required)
Example: /catchup

Inventory & Progress

`/inventory`

View your complete account status including:

Gold - Current gold balance
Rubies - Gem currency for special items
Equipment - Gear inventory with rarity levels
Progress - Objectives completed, champions, areas unlocked
Example: /inventory

`/open chest_type:<type> count:<count>`

Open chests to receive random loot. Different chest types contain different rewards.

Required parameters:
- chest_type - Type of chest (e.g., Gold, Sapphire, Legendary)
- count - Number of chests to open (1+)
Common chest types: Gold, Sapphire, Ruby, Epic, Legendary
Response: Lists all items obtained from opened chests
Example: /open chest_type:Sapphire count:5

`/blacksmith contract_type:<type> hero_id:<id> count:<count>`

Upgrade heroes using blacksmith contracts. Different contract types upgrade different hero abilities.

Required parameters:
- contract_type - Type of contract (e.g., Damage, HP, Ability)
- hero_id - ID of the hero to upgrade
- count - Number of contracts to use (1+)
Effect: Permanently increases hero stats
Example: /blacksmith contract_type:Damage hero_id:42 count:10

Code Management

`/codes [count:<count>]`

View your personal code redemption history.

Optional parameters:
- count - Number of codes to show (1-20, default: 10)
Shows: Code, redemption date, rewards received
Example: /codes or /codes count:20

`/makepublic code:<code>`

Share one of your previously redeemed codes with other users. Other users can redeem the same code via /redeem and the rewards will be shared.

Required parameters:
- code - One of your redeemed codes (must be in your history)
Requirement: You must have already redeemed this code
Note: Codes automatically become public when a second user successfully redeems them
Example: /makepublic code:SHARED123

`/backfill [channel:<channel>]`

Recover missed codes from Discord message history. Scans the entire message history of a channel and redeems any codes that weren't previously found.

Optional parameters:
- channel - Target channel to scan (defaults to current channel)
Requirements:
- You must have "Manage Messages" permission (admin-only)
- Only works on text channels
Protection:
- Only one backfill can run at a time (global lock)
- Per-user rate limit: 1 hour between initiations
- Automatically runs on startup if last run was >6 hours ago
Response: Shows stats (codes found, redeemed, pending, any errors)
Example: /backfill or /backfill channel:#code-drops

Automatic Startup Backfill:

Runs automatically when the bot starts if DISCORD_CHANNEL_ID is configured
Only runs if the last backfill was more than 6 hours ago
Helps catch codes that appeared while the bot was offline
No manual action needed

Auto-Redeem Settings

`/autoredeem enabled:<on|off>`

Toggle whether the bot automatically redeems new codes when they are detected in the monitored channel.

Required parameters:
- enabled - on to enable, off to disable automatic redemption
Default: Auto-redeem is enabled for all users after /setup
Behaviour when enabled: Any code detected by the scanner is immediately submitted to the Idle Champions API on your behalf
Behaviour when disabled: Codes are still detected and stored, but you must use /redeem or /catchup to claim them manually
Example: /autoredeem enabled:off

Account Management

`/deleteaccount`

Permanently and irreversibly delete all data the bot holds about you. Requires an explicit confirmation step to prevent accidents.

No parameters required
What is deleted:
- Your Idle Champions credentials (user ID + hash)
- Your full code redemption history
- Your audit log entries
- Your backfill operation history
Confirmation: A Yes / Cancel button prompt appears with a 30-second timeout — no action is taken unless you click Yes, delete everything
After deletion: You will need to run /setup again to use the bot
Example: /deleteaccount

Notification Preferences

`/notifications`

View and update your DM notification preferences.

No parameters required (shows current settings)
Optional parameters:
- dm_on_code – DM when a new code is detected in the channel (default: false)
- dm_on_success – DM when auto-redeem succeeds (default: true)
- dm_on_failure – DM when auto-redeem fails (default: false)
Example: /notifications or /notifications dm_on_code:true dm_on_failure:true

Server Statistics

`/stats`

Show server-wide code redemption statistics and aggregate loot totals.

No parameters required
Shows: Total unique codes seen, total redemption events, registered user count, server-wide aggregate loot
Available to: All users — no special permissions required
Example: /stats

Admin Tools

`/logs [lines:<1-100>]`

Show the last N lines of the bot's combined log file.

Optional parameters:
- lines – Number of log lines (1–100, default: 20)
Permissions: Requires Discord Manage Messages permission
Returns: Ephemeral embed with log content
Example: /logs or /logs lines:50

Help

`/help`

Display all available commands with brief descriptions.

Use when: You need a quick reference of all bot commands
Example: /help

Architecture

src/bot/
├── bot.ts                     # Main Discord client & event handlers
├── api/
│   ├── idleChampionsApi.ts    # Game server API client
│   └── types/                 # Type definitions from game API
├── commands/              # Slash command handlers (15 commands)
├── database/              # Database layer (Drizzle ORM)
│   ├── db.ts              # Drizzle connection & migrate() on startup
│   ├── userManager.ts     # User credentials (AES-256-GCM encrypted)
│   ├── codeManager.ts     # Code tracking, history & loot totals
│   ├── auditManager.ts    # Audit log
│   ├── backfillManager.ts # Backfill locking & tracking
│   ├── schema/            # Drizzle table definitions (one file per table)
│   │   ├── users.ts
│   │   ├── redeemed_codes.ts
│   │   ├── pending_codes.ts
│   │   ├── audit_log.ts
│   │   ├── backfill_operations.ts
│   │   └── loot_totals.ts
│   └── migrations/        # Auto-generated SQL migrations
├── handlers/              # Message scanning for codes
│   ├── codeScanner.ts
│   ├── autoRedeemer.ts
│   └── backfillHandler.ts
└── utils/                 # Helpers (logging, crypto, debug, API logging)
    ├── logger.ts
    ├── crypto.ts
    ├── apiRequestLogger.ts
    └── debugLogger.ts

src/test/
└── setup.ts               # Bun test preload (DB_PATH=:memory:)

Configuration

`.env` Example

DISCORD_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=1214259114725605436
DISCORD_CHANNEL_ID=1502624358055809104
DISCORD_CODE_AUTHOR_ID=1502625533236744222
# Required: 64-char hex key for AES-256-GCM credential encryption
# Generate with: openssl rand -hex 32
ENCRYPTION_KEY=your_64_char_hex_key_here
DB_PATH=./data/idle.db
NODE_ENV=development

Development

Use Mise for all development tasks. The environment is automatically configured:

mise run install  # Setup all tools & dependencies
mise run dev      # Start bot with auto-rebuild
mise run build    # Compile TypeScript
mise run watch    # Watch for changes and rebuild
mise run lint     # Check code quality
mise run lint:fix # Auto-fix linting issues
mise tasks        # View all available tasks

Database

SQLite database managed with Drizzle ORM (bun:sqlite + drizzle-orm). Migrations are applied automatically at startup.

users - Discord user credentials (AES-256-GCM encrypted user_id/hash), notification prefs, autoRedeem flag
redeemed_codes - Code history (status: Success or Code Expired; includes is_public and expires_at)
pending_codes - Codes waiting to be redeemed
audit_log - All bot actions
backfill_operations - Backfill run history & global lock
loot_totals - Aggregate loot cache (per-user and server-wide, used by /stats)

bun run db:generate   # Regenerate migrations from schema changes
bun run db:studio     # Open Drizzle Studio (visual DB browser)

Troubleshooting

"CERT_HAS_EXPIRED" errors?

This is handled automatically by Mise (no manual setup needed)
The environment variable NODE_TLS_REJECT_UNAUTHORIZED=0 is set by .mise.toml

Bot not responding?

Check DISCORD_TOKEN in .env
Ensure bot is invited to your server with correct permissions

Codes not detecting?

Verify DISCORD_CHANNEL_ID points to the right channel
Bot must have message read permissions
Run mise run lint to check for code issues

Documentation

Development Guide - Development setup, structure & debugging
Project Structure - Complete directory layout & key files
Mise Setup Guide - Tool management & available tasks

Original Extension

This was originally a Chrome/Edge extension. The Discord bot version is vastly superior:

Feature	Extension	Bot
Uptime	Browser only	24/7
Setup	Popup UI	Discord commands
Multi-user	No	Yes
Automatic	Browser dependent	Always on
Deployment	Install extension	Docker

License

See LICENSE file

FilesExpand file tree

full-documentation.md

Latest commit

History