Store API

The Store API provides a powerful interface for managing server-specific stores with customizable items, categories, and reward systems.

✨ Features

• Per-server stores — Each guild has its own store

• Multiple categories — Pets, roles, boosters, titles, items, special

• Reward types — Pets, roles, boosters, titles, items, custom

• Requirements — Level and prestige requirements

• Stock management — Limited or unlimited stock

• Purchase limits — Max purchases per user

• Transaction logging — Full purchase history

---

🚀 Quick Start

const StoreAPI = require('./utils/economy/storeAPI');

// Add a custom item
await StoreAPI.addItem(guildId, {
    name: 'VIP Role',
    category: 'roles',
    price: 50000,
    rewardType: 'role',
    rewardData: { roleId: '123456789', roleDuration: null },
    emoji: '👑'
});

// Get all items in a category
const pets = await StoreAPI.getItems(guildId, 'pets');

// Purchase an item for a user
const result = await StoreAPI.purchaseItem(guildId, userId, itemId, client);
if (result.success) {
    console.log(`Purchased: ${result.item.name}`);
}

---

📦 Methods Reference

addItem(guildId, itemData)

Add a new item to the store.

await StoreAPI.addItem(guildId, {
    name: 'Dragon Pet',
    description: 'A legendary beast',
    category: 'pets',           // pets, roles, boosters, titles, items, special
    price: 50000,
    stock: -1,                  // -1 = unlimited
    maxPerUser: 1,              // -1 = unlimited
    enabled: true,
    rewardType: 'pet',
    rewardData: {
        petType: 'Dragon',
        petMultiplier: 1.15,
        petPassiveIncome: 100
    },
    requirements: {
        level: 10,
        prestige: 0
    },
    emoji: '🐉',
    color: '#FF4500',
    featured: true,
    sortOrder: 1
});

Parameters:

Parameter	Type	Required	Description
name	string	✅	Display name of the item
description	string	❌	Item description
category	string	✅	Category: pets, roles, boosters, titles, items, special
price	number	✅	Cost in coins
stock	number	❌	Available stock (-1 = unlimited)
maxPerUser	number	❌	Max purchases per user (-1 = unlimited)
enabled	boolean	❌	Whether item is available (default: true)
rewardType	string	✅	Type of reward (see Reward Types)
rewardData	object	✅	Reward-specific data
requirements	object	❌	{ level: number, prestige: number }
emoji	string	❌	Display emoji (default: 🛒)
color	string	❌	Hex color (default: #5865F2)
featured	boolean	❌	Show in featured section
sortOrder	number	❌	Sort priority (lower = first)

---

removeItem(guildId, itemId)

Remove an item from the store.

const removed = await StoreAPI.removeItem(guildId, 'item-uuid');
// Returns: true if deleted, false if not found

---

updateItem(guildId, itemId, updates)

Update an existing item.

await StoreAPI.updateItem(guildId, 'item-uuid', {
    price: 75000,
    'metadata.featured': true,
    enabled: false
});

---

getItem(guildId, itemId)

Get a single item by ID.

const item = await StoreAPI.getItem(guildId, 'item-uuid');

---

getItems(guildId, category?)

Get all items, optionally filtered by category.

// All items
const allItems = await StoreAPI.getItems(guildId);

// Only pets
const pets = await StoreAPI.getItems(guildId, 'pets');

// Only boosters
const boosters = await StoreAPI.getItems(guildId, 'boosters');

---

getCategories(guildId)

Get all categories that have items.

const categories = await StoreAPI.getCategories(guildId);
// Returns: ['pets', 'boosters', 'titles']

---

getFeaturedItems(guildId)

Get all featured items.

const featured = await StoreAPI.getFeaturedItems(guildId);

---

purchaseItem(guildId, userId, itemId, client)

Process a purchase. Handles balance deduction, requirements validation, stock management, and reward application.

const result = await StoreAPI.purchaseItem(guildId, userId, itemId, client);

if (result.success) {
    console.log(result.item);     // The purchased item
    console.log(result.purchase); // Purchase record
    console.log(result.reward);   // Reward message string
} else {
    console.log(result.error);    // Error message
}

Possible Errors:

• Item not found

• Item out of stock

• User not found

• Insufficient funds

• Requires level X

• Requires prestige X

• Purchase limit reached

• You already own this pet!

---

getUserPurchases(guildId, userId)

Get a user's purchase history.

const purchases = await StoreAPI.getUserPurchases(guildId, userId);
// Returns array of purchase records sorted by date (newest first)

---

🎁 Reward Types

pet

Adds a pet to the user's collection.

rewardType: 'pet',
rewardData: {
    petType: 'Dragon',        // Pet type name
    petMultiplier: 1.15,      // Earnings multiplier (1.15 = +15%)
    petPassiveIncome: 100     // Coins per hour passive income
}

role

Grants a Discord role to the user.

rewardType: 'role',
rewardData: {
    roleId: '123456789012345678',  // Discord role ID
    roleDuration: 2592000000       // Duration in ms (null = permanent)
}

booster

Activates a temporary multiplier booster.

rewardType: 'booster',
rewardData: {
    boosterType: 'Money',       // 'Money' or 'XP'
    boosterMultiplier: 1.5,     // 1.5 = +50% bonus
    boosterDuration: 86400000   // Duration in ms (24 hours)
}

title

Unlocks a display title for the user.

rewardType: 'title',
rewardData: {
    title: '💰 Rich'   // The title string
}

item

Adds a generic item to user's inventory.

rewardType: 'item',
rewardData: {
    itemType: 'charm',           // Custom item type
    itemData: { luckBonus: 0.05 } // Custom data
}

custom

For addon-handled rewards. The reward isn't automatically applied.

rewardType: 'custom',
rewardData: {
    // Your custom data here
}

---

📁 Categories

Category	Emoji	Typical Use
pets	🐾	Companion pets with earnings bonuses
roles	🎭	Discord role rewards
boosters	🚀	Temporary multipliers
titles	🏷️	Display titles/badges
items	🎒	Inventory items
special	✨	Limited/seasonal items

---

💡 Addon Examples

Adding Custom Shop Items

module.exports = {
    name: 'CustomShopItems',

    async run(client) {
        const StoreAPI = require('./utils/economy/storeAPI');

        for (const guild of client.guilds.cache.values()) {
            // Check if item already exists
            const existing = await StoreAPI.getItem(guild.id, 'vip-membership');
            if (existing) continue;

            await StoreAPI.addItem(guild.id, {
                itemId: 'vip-membership',
                name: 'VIP Membership',
                description: 'Get exclusive VIP role for 30 days',
                category: 'roles',
                price: 100000,
                maxPerUser: 1,
                rewardType: 'role',
                rewardData: {
                    roleId: 'YOUR_VIP_ROLE_ID',
                    roleDuration: 2592000000  // 30 days
                },
                emoji: '💎',
                featured: true
            });

            console.log(`Added VIP item to ${guild.name}`);
        }
    }
};

Seasonal/Limited Items

module.exports = {
    name: 'SeasonalStore',

    async run(client) {
        const StoreAPI = require('./utils/economy/storeAPI');

        const month = new Date().getMonth();

        // December = Christmas items
        if (month === 11) {
            for (const guild of client.guilds.cache.values()) {
                const existing = await StoreAPI.getItem(guild.id, 'santa-hat-2024');
                if (existing) continue;

                await StoreAPI.addItem(guild.id, {
                    itemId: 'santa-hat-2024',
                    name: 'Santa Hat 2024',
                    description: 'Limited edition holiday item!',
                    category: 'special',
                    price: 25000,
                    stock: 100,  // Only 100 available!
                    rewardType: 'title',
                    rewardData: { title: '🎅 Santa 2024' },
                    emoji: '🎄',
                    featured: true
                });
            }
        }
    }
};

Dynamic Pricing

module.exports = {
    name: 'DynamicPricing',

    events: {
        'discord:ready': async (eventData, context) => {
            const StoreAPI = require('./utils/economy/storeAPI');

            // Update prices every hour based on purchases
            setInterval(async () => {
                for (const guild of context.client.guilds.cache.values()) {
                    const items = await StoreAPI.getItems(guild.id, 'pets');

                    for (const item of items) {
                        // Increase price if stock is running low
                        if (item.stock > 0 && item.stock < 10) {
                            await StoreAPI.updateItem(guild.id, item.itemId, {
                                price: Math.floor(item.price * 1.1)
                            });
                        }
                    }
                }
            }, 3600000); // Every hour
        }
    }
};

Purchase Announcements

module.exports = {
    name: 'PurchaseAnnouncer',

    events: {
        // Listen for rare purchases and announce them
        'discord:messageCreate': async (eventData, context) => {
            // Note: For better integration, emit custom events from your
            // store command after successful purchases
        }
    },

    async run(client) {
        // Wrap the purchase method to add announcements
        const StoreAPI = require('./utils/economy/storeAPI');
        const originalPurchase = StoreAPI.purchaseItem.bind(StoreAPI);

        StoreAPI.purchaseItem = async (guildId, userId, itemId, c) => {
            const result = await originalPurchase(guildId, userId, itemId, c);

            if (result.success && result.item.metadata?.featured) {
                const guild = client.guilds.cache.get(guildId);
                const channel = guild?.channels.cache.find(
                    ch => ch.name === 'purchases' || ch.name === 'general'
                );

                if (channel) {
                    const user = await client.users.fetch(userId);
                    await channel.send(
                        `🎉 **${user.username}** just purchased **${result.item.name}**!`
                    );
                }
            }

            return result;
        };
    }
};

---

📊 Item Schema

Full item object structure:

{
    "itemId": "uuid-string",
    "guildId": "guild-id",
    "name": "Item Name",
    "description": "Item description",
    "category": "pets",
    "price": 50000,
    "stock": -1,
    "maxPerUser": -1,
    "enabled": true,
    "rewardType": "pet",
    "rewardData": { /* ... */ },
    "requirements": {
        "level": 0,
        "prestige": 0
    },
    "metadata": {
        "emoji": "🐉",
        "color": "#5865F2",
        "image": null,
        "featured": false,
        "sortOrder": 0
    },
    "createdAt": "Date",
    "updatedAt": "Date"
}

---

📋 Purchase Record Schema

{
    "orderId": "uuid-string",
    "guildId": "guild-id",
    "userId": "user-id",
    "itemId": "item-id",
    "itemName": "Item Name",
    "category": "pets",
    "price": 50000,
    "rewardType": "pet",
    "rewardData": { /* ... */ },
    "status": "completed",
    "purchasedAt": "Date"
}