Skip to main content

Seasonal Events

Status: ✅ Core Features Complete
Last Updated: 2026-01-19

Overview​

Complete seasonal events system with limited-time shop items, event challenges, event scheduling, event-specific achievements, event announcements, and ARC-loop integration (daily event quests and weekly event bosses).

Implementation Details​

Backend​

  • ✅ SeasonalService with getActiveEvents, getAllEvents, getEvent, createEvent, createRecurringEvent, ensureRecurringEvents methods
  • ✅ Event shop items (link/unlink shop items to events, automatic disable/enable logic for expired/active event items)
  • ✅ Event challenges (link/unlink challenges to events)
  • ✅ Event scheduling (createRecurringEvent for specific years, ensureRecurringEvents automatically creates upcoming events within 30 days)
  • ✅ Event-specific achievements (linkAchievementToEvent method, UserAchievements automatically linked to events when unlocked during active events)
  • ✅ Event announcements (sendEventAnnouncement, checkAndAnnounceNewEvents methods, system messages sent when events start)
  • ✅ Comprehensive test coverage (12 service tests, 6 route tests for basic service; 24 service tests, 13 route tests for shop items; 33 service tests, 21 route tests for scheduling; 36 service tests, 26 route tests for announcements; 46 service tests, 29 route tests for daily quests)

Frontend​

  • ✅ Event announcements (system messages in messaging center)
  • ✅ Event shop section (SeasonalEventsTab shows expandable event details with shop items, full item details, purchase functionality)
  • ✅ Event progress tracking (SeasonalEventsTab shows challenge progress with progress bars, challenge completion status, rewards display)
  • ✅ Enhanced UI with expandable event cards, item cards, purchase buttons, progress bars

ARC-Loop Integration​

  • ✅ Daily event quest tied to reporting completion (ensureDailyEventQuest creates daily challenges for active events, updateDailyEventQuestProgress auto-completes quests when daily report is done)
  • ✅ Integration with ChecklistService and PerimeterService to trigger on report completion
  • ✅ Weekly event boss tied to domain focus (createEventWeeklyBoss creates event-specific weekly bosses, ensureEventWeeklyBosses creates bosses for all active events)
  • ✅ Bosses tied to stat domains (strength/recovery/wisdom/balance)
  • ✅ Note: Only one boss per week due to unique constraint on weekStart

API Endpoints​

  • GET /api/events - List all events
  • GET /api/events/active - Get active events
  • GET /api/events/:key - Get event by key
  • GET /api/events/:key/details - Get detailed event information
  • POST /api/events - Create event
  • POST /api/events/recurring - Create recurring event for specific year
  • POST /api/events/ensure-recurring - Ensure recurring events are created (within 30 days)
  • POST /api/events/:key/items - Link shop item to event
  • DELETE /api/events/:key/items/:itemId - Unlink shop item from event
  • POST /api/events/:key/challenges - Link challenge to event
  • DELETE /api/events/:key/challenges/:challengeId - Unlink challenge from event
  • POST /api/events/:key/achievements - Link achievement to event
  • POST /api/events/:key/announce - Send event announcement
  • POST /api/events/check-and-announce - Check and announce new events
  • POST /api/events/ensure-daily-quests - Ensure daily event quests are created
  • POST /api/events/:key/weekly-boss - Create event-specific weekly boss
  • POST /api/events/ensure-weekly-bosses - Ensure event weekly bosses are created

Frontend Pages​

  • Character Page → Seasonal Tab (/gamification/character with tab=seasonal)