Mythic+ Keystone Tracker with subscription & auto-fetch

[karaktaka]

Background

The feature_wow_mplus branch contains an incomplete prototype for a Mythic+ keystone tracker. This issue documents what was built, the original intent, and what's needed to bring it to completion on the current codebase — including new subscription, key giver, and auto-fetch features.

Depends on #182 — this feature will be developed as slash commands only (no prefix/hybrid support).

---

What Was Done (on the branch)

Database Model — WoW (keystone storage)

A WoW table storing per-character keystones per Discord guild:

Column	Type	Purpose
Id	Integer (PK)	Auto-increment
GuildId	BigInteger	Discord guild ID
KeystoneName	String	Dungeon short name (e.g. NW, SOA)
KeystoneLevel	SmallInteger	Key level
Character	String	WoW character name
CreateDate	DateTime	When the key was added
ModifiedDate	DateTime	(unused — never populated)
Author	String	Discord user who added it

Unique constraint on (Character, GuildId).

Command Group — !wow mplus

Command	Description
!wow mplus keystones	List all keystones for the guild (embed with affixes)
!wow mplus keystones get level <N>	Filter by key level
!wow mplus keystones get dungeon <name>	Filter by dungeon (EN/DE names)
!wow mplus keystones get character <name>	Filter by character name
!wow mplus keystones add <dungeon> <level> <character>	Register a keystone
!wow mplus keystones remove <character>	Delete a character's keystone
!wow mplus dungeons list	Show all recognized dungeon names

Helper Functions

• Raider.io integration for weekly affix display in the keystone embed
• Dungeon name dictionaries (English + German) for input normalization
• Existing helpers refactored to module-level functions

---

New Feature Requirements

1. Seasonal Dungeon Data (auto-fetched & cached in DB)

Dungeon rotations are seasonal (lasting several months). The branch hardcodes Shadowlands Season 1 dungeons — this needs to be dynamic.

• Fetch the current M+ dungeon pool from the Blizzard API (e.g. Mythic Keystone Dungeon Index / Season endpoint)
• Store dungeon data in a DB table (id, short name, full name, season) — only refresh when the season changes
• Autocomplete dungeon names in slash commands from the cached DB data

2. Key Subscription System (DM Notifications)

Users subscribe to specific keystones they need. When a matching key is added (manually or auto-fetched), subscribed users receive a DM.

Commands:

• /wow mplus subscribe <dungeon> [min_level] — "I need this key" (multiple subscriptions per user)
• /wow mplus unsubscribe <dungeon> / unsubscribe all — Remove subscriptions
• /wow mplus subscriptions — List active subscriptions

Matching logic:

• Match if dungeon matches AND key level ≥ subscriber's min_level (if set)
• DM includes: dungeon name, key level, character name, who added it
• Only notify users in the same Discord guild

3. Key Giver Registration

Users register as "key givers" — always available to run keys for others, with automatic keystone fetching.

Commands:

• /wow mplus giver register <character> <realm> <region> — Link Discord user to WoW character
• /wow mplus giver unregister — Remove registration
• /wow mplus giver list — Show all registered givers in the guild

Behavior:

• Givers can still manually add keys (triggers subscriber DMs as normal)
• Their keystones are auto-fetched on schedule (see below)

4. Automatic Key Fetch & Scheduled Announcements

The system fetches keystones for registered givers at two key moments each week:

Pre-Reset — "Vault Push" Window

• When: Monday evening (configurable; before the weekly reset)
• Purpose: Help people find groups to fill their Great Vault slots before the week ends
• Actions:
  1. Fetch each giver's current keystone via the Raider.io API
  2. DM subscribers whose subscriptions match
  3. Optionally post a guild channel summary ("These keys are available for vault runs!")

Post-Reset — "Fresh Keys" Window

• When: After weekly reset (Tuesday NA / Wednesday EU — region-aware)
• Purpose: Announce freshly assigned keystones so groups can form early
• Actions:
  1. Auto-clear the previous week's keystones
  2. Fetch each giver's new keystone via the Raider.io API
  3. Store the fetched key
  4. DM subscribers whose subscriptions match
  5. Optionally post a guild channel summary ("Fresh keys this week!")

---

Implementation Checklist

Architecture (Required)

• Slash commands only (depends on Migrate fully to slash commands, drop prefix command support #182) — use GroupCog + app_commands
• Replace wowapi (WowApi) with blizzapi (RetailClient)
• Use async def setup(bot)
• Use send_hidden_message / ephemeral responses where appropriate

New Models (Required)

The WoW model on main is a guild-level placeholder alongside WowGuildNewsConfig / WowCharacterMounts. New tables needed:

• WowMplusDungeon — Cached seasonal dungeon data (id, short name, full name, season id). Auto-fetched from Blizzard API.
• WowKeystone — Current keystones per character per guild (replaces the branch's WoW table)
• WowKeystoneSubscription — Per-user dungeon subscriptions with optional min level, per guild
• WowKeystoneGiver — Per-user WoW character link (character, realm, region) for auto-fetch
• Follow conventions: Unicode columns for utf8mb4, datetime.now(UTC), proper indexes

Scheduling (Required)

• Season refresh — Check Blizzard API periodically (e.g. daily) for season changes; update dungeon cache
• Pre-reset fetch (Monday) — Fetch givers' keys, DM subscribers for vault push groups
• Post-reset — Clear old keystones, fetch new keys, DM subscribers
• Region-aware reset timing (Tuesday NA / Wednesday EU)
• Use discord.ext.tasks loops

Code Quality Fixes (from branch)

• Remove bare except: clause in keystone add command
• Remove ctx.guild.region usage (removed in discord.py v2)
• Replace datetime.utcnow() with datetime.now(UTC)
• Drop unused ModifiedDate column or use it properly

Enhancements (Nice to Have)

• Autocomplete for character names
• Sorted output — sort keystone embeds by level or dungeon
• Update command — overwrite a keystone without delete+add
• Summary channel config — configurable per guild for scheduled announcement posts
• Documentation in docs/wow.md

---

Branch Reference

Branch: feature_wow_mplus
Commits: 8b30866 ("müffiks") + merge commits
Files changed: NerdyPy/models/wow.py, NerdyPy/modules/wow.py, NerdyPy/models/__init__.py