aurorabot/shared/modules/trivia/CLAUDE.md

Trivia Module

• Trivia is an economic sink: the entry fee is deducted immediately when starting, before the question is fetched. If the API call fails after payment, the user loses the fee. This is by design (prevents free retries).
• Questions come from the OpenTDB API with base64 encoding to avoid HTML entity issues. The service decodes all fields from base64 before returning.
• Sessions are in-memory (Map keyed by userId_timestamp). Lost on restart. Expired sessions are cleaned up every 30 seconds.
• The cooldown is set at session start, not on answer submission. This means a user is on cooldown even if they never answer.
• Answer correctness (isCorrect) is determined by the caller (interaction handler), not the service. The submitAnswer method trusts the isCorrect boolean. The session stores correctIndex for the UI layer to compare.
• Reward calculation: potentialReward = entryFee * rewardMultiplier. The multiplier comes from config. Wrong answers get 0 (the entry fee is already gone).
• Unlike most services, TriviaService is a class instance (not a plain object). This is because it needs constructor logic for the cleanup interval. The singleton is exported as triviaService.
• The reward payment in submitAnswer reads the current balance and sets it directly (not using sql addition). This is a potential race condition under extreme concurrency but acceptable given the per-user cooldown.
• Session is deleted before processing the reward to prevent double-submit, even if the reward transaction fails.