feat: Implement structured lootbox results with image support and display referenced items in shop listings.

bot/modules/inventory/effects/handlers.ts

@@ -86,7 +86,11 @@ export const handleLootbox: EffectHandler = async (userId, effect, txFn) => {
 
     // Process Winner
     if (winner.type === LootType.NOTHING) {
-        return winner.message || "You found nothing inside.";
+        return {
+            type: 'LOOTBOX_RESULT',
+            rewardType: 'NOTHING',
+            message: winner.message || "You found nothing inside."
+        };
     }
 
     if (winner.type === LootType.CURRENCY) {
@@ -96,7 +100,12 @@ export const handleLootbox: EffectHandler = async (userId, effect, txFn) => {
         }
         if (amount > 0) {
             await economyService.modifyUserBalance(userId, BigInt(amount), TransactionType.LOOTBOX, 'Lootbox Reward', null, txFn);
-            return winner.message || `You found ${amount} 🪙!`;
+            return {
+                type: 'LOOTBOX_RESULT',
+                rewardType: 'CURRENCY',
+                amount: amount,
+                message: winner.message || `You found ${amount} 🪙!`
+            };
         }
     }
 
@@ -107,7 +116,12 @@ export const handleLootbox: EffectHandler = async (userId, effect, txFn) => {
         }
         if (amount > 0) {
             await levelingService.addXp(userId, BigInt(amount), txFn);
-            return winner.message || `You gained ${amount} XP!`;
+            return {
+                type: 'LOOTBOX_RESULT',
+                rewardType: 'XP',
+                amount: amount,
+                message: winner.message || `You gained ${amount} XP!`
+            };
         }
     }
 
@@ -123,7 +137,18 @@ export const handleLootbox: EffectHandler = async (userId, effect, txFn) => {
                     where: (items: any, { eq }: any) => eq(items.id, winner.itemId!)
                 });
                 if (item) {
-                    return winner.message || `You found ${quantity > 1 ? quantity + 'x ' : ''}**${item.name}**!`;
+                    return {
+                        type: 'LOOTBOX_RESULT',
+                        rewardType: 'ITEM',
+                        amount: Number(quantity),
+                        item: {
+                            name: item.name,
+                            rarity: item.rarity,
+                            description: item.description,
+                            image: item.imageUrl || item.iconUrl
+                        },
+                        message: winner.message || `You found ${quantity > 1 ? quantity + 'x ' : ''}**${item.name}**!`
+                    };
                 }
             } catch (e) {
                 console.error("Failed to fetch item name for lootbox message", e);

bot/modules/inventory/effects/types.ts

@@ -1,4 +1,4 @@
 
 import type { Transaction } from "@shared/lib/types";
 
-export type EffectHandler = (userId: string, effect: any, txFn: Transaction) => Promise<string>;
+export type EffectHandler = (userId: string, effect: any, txFn: Transaction) => Promise<any>;