🎄 Adventcord

Discord webhook notifications for Advent of Code leaderboards and new puzzle announcements.

✨ Features

• Leaderboard Updates — Get your private leaderboard standings sent to Discord at scheduled hours
• New Puzzle Notifications — Be notified when a new puzzle drops (configurable dates)
• Role Mentions — Optionally ping a Discord role with updates
• No Session Token Required — Uses AoC's public read-only leaderboard links
• Smart Caching — Respects AoC's API guidelines with intelligent caching

🚀 Quick Start

Using the Hosted Version

1. Get your leaderboard's read-only link from AoC Leaderboards
2. Create a Discord webhook in your server (Server Settings → Integrations → Webhooks)
3. Visit adventcord.liam.so and fill out the form
4. Done! You'll receive updates at your scheduled times

Self-Hosting

Prerequisites

• Bun runtime
• Turso database (or any libSQL-compatible database)

Setup

# Clone the repository
git clone https://github.com/Lermatroid/adventcord.git
cd adventcord

# Install dependencies
bun install

# Create env file
touch .env
# Edit .env with your Turso credentials

# Push database schema
bun run db:push

# Start development server
bun run dev

Environment Variables

# Database (required)
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-auth-token

# AoC Season Configuration (optional - defaults shown)
NEXT_PUBLIC_AOC_START_DAY=1   # First day of puzzles
NEXT_PUBLIC_AOC_END_DAY=12    # Last day of puzzles
NEXT_PUBLIC_AOC_MONTH=12      # Month (12 = December)

Note: Leaderboard updates continue for 24 hours after the last puzzle day to capture final standings.

🏗️ Architecture

Component	Platform	Description
Web App	Vercel	Next.js 16 frontend for managing subscriptions
Cron Job	Railway	Hourly job that sends webhook notifications
Database	Turso	SQLite database for storing subscriptions

📦 Tech Stack

• Framework: Next.js 16
• Runtime: Bun
• Database: Turso (libSQL) + Drizzle ORM
• Styling: Tailwind CSS v4
• HTTP Client: @better-fetch/fetch

🛠️ Development

# Run development server
bun run dev

# Run database studio
bun run db:studio

# Generate database migrations
bun run db:generate

# Run cron job manually
bun run cron --help

Cron Debug Commands

# Test with a specific webhook (from DB)
bun run cron --webhook-url "https://discord.com/api/webhooks/..."

# Dry run (no webhooks sent)
bun run cron --dry-run --force-aoc --day 1

# Test directly without DB
bun run cron --test-url "https://discord.com/api/webhooks/..." --test-leaderboard "https://adventofcode.com/..."

🚢 Deployment

Vercel (Web App)

1. Connect your GitHub repository to Vercel
2. Add environment variables (TURSO_DATABASE_URL, TURSO_AUTH_TOKEN)
3. Deploy

Railway (Cron Job)

1. Create a new project and connect your repository
2. Add environment variables
3. Set up a cron job: 0 * * * * (every hour on the hour)
4. Command: bun run cron

📄 License

MIT

🙏 Acknowledgments

• Advent of Code by Eric Wastl
• Inspired by the AoC terminal aesthetic

---

_{Not affiliated with Advent of Code. Please support AoC by purchasing AoC++!}