aurorabot/shared/modules/inventory/AGENTS.md

Inventory Module

• Inventory has two hard limits from config: max slots (distinct item types) and max stack size (quantity per item). Both are enforced in addItem and will throw UserError if exceeded.
• When quantity reaches 0, the inventory row is deleted (not kept with quantity 0). This means slot count = row count.
• buyItem delegates balance deduction to economyService.modifyUserBalance within the same transaction to ensure atomicity. Never deduct balance directly when purchasing.
• Item usage is driven by a JSON usageData field on the item record. Items without usageData.effects cannot be used. The consume flag in usageData controls whether the item is removed after use.
• Effect system: effects are validated at runtime via Zod (EffectPayloadSchema) before execution. The registry maps effect type strings to handler functions. Adding a new effect type requires: (1) add to EffectType enum in constants, (2) add Zod schema variant in effect.types.ts, (3) add handler in effect.handlers.ts, (4) register in effect.registry.ts.
• XP_BOOST and TEMP_ROLE effects use userTimers with upsert -- activating while already active replaces the timer (does not stack or extend).
• TEMP_ROLE only records the timer in DB; actual Discord role assignment must happen in the bot command layer.
• LOOTBOX effect uses weighted random selection. Weights are relative, not percentages. A NOTHING loot type is valid and intentional.
• The getAutocompleteItems method filters to only show items that have usable effects, so non-usable items won't appear in the /use autocomplete.