diff --git a/shared/docs/COMMANDS.md b/shared/docs/COMMANDS.md deleted file mode 100644 index 11eaae9..0000000 --- a/shared/docs/COMMANDS.md +++ /dev/null @@ -1,63 +0,0 @@ -# Command Reference - -This document lists all available slash commands in Aurora, categorized by their function. - -## Economy - -| Command | Description | Options | Permissions | -|---|---|---|---| -| `/balance` | View your or another user's balance. | `user` (Optional): The user to check. | Everyone | -| `/daily` | Claim your daily currency reward and streak bonus. | None | Everyone | -| `/pay` | Transfer currency to another user. | `user` (Required): Recipient.
`amount` (Required): Amount to send. | Everyone | -| `/trade` | Start a trade session with another user. | `user` (Required): The user to trade with. | Everyone | -| `/exam` | Take your weekly exam to earn rewards based on XP gain. | None | Everyone | - -## Inventory & Items - -| Command | Description | Options | Permissions | -|---|---|---|---| -| `/inventory` | View your or another user's inventory. | `user` (Optional): The user to check. | Everyone | -| `/use` | Use an item from your inventory. | `item` (Required): The item to use (Autocomplete). | Everyone | - -## User & Social - -| Command | Description | Options | Permissions | -|---|---|---|---| -| `/profile` | View your or another user's Student ID card. | `user` (Optional): The user to view. | Everyone | -| `/leaderboard` | View top players. | `type` (Required): 'Level / XP' or 'Balance'. | Everyone | -| `/feedback` | Submit feedback, bug reports, or suggestions. | None | Everyone | -| `/quests` | View your active quests. | None | Everyone | - -## Admin - -> [!IMPORTANT] -> These commands require Administrator permissions or specific roles as configured. - -### General Management -| Command | Description | Options | -|---|---|---| -| `/config` | Manage bot configuration. | `group` (Req): Section.
`key` (Req): Setting.
`value` (Req): New value. | -| `/refresh` | Refresh commands or configuration cache. | `type`: 'Commands' or 'Config'. | -| `/update` | Update the bot from the repository. | None | -| `/features` | Enable/Disable system features. | `feature` (Req): Feature name.
`enabled` (Req): True/False. | -| `/webhook` | Send a message via webhook. | `payload` (Req): JSON payload. | - -### Moderation -| Command | Description | Options | -|---|---|---| -| `/warn` | Warn a user. | `user` (Req): Target.
`reason` (Req): Reason. | -| `/warnings` | View active warnings for a user. | `user` (Req): Target. | -| `/clearwarning`| Clear a specific warning. | `case_id` (Req): Case ID. | -| `/case` | View details of a specific moderation case. | `case_id` (Req): Case ID. | -| `/cases` | View moderation history for a user. | `user` (Req): Target. | -| `/note` | Add a note to a user. | `user` (Req): Target.
`note` (Req): Content. | -| `/notes` | View notes for a user. | `user` (Req): Target. | -| `/prune` | Bulk delete messages. | `amount` (Req): Number (1-100). | - -### Game Admin -| Command | Description | Options | -|---|---|---| -| `/create_item` | Create a new item in the database. | (Modal based interaction) | -| `/create_color`| Create a new color role. | `name` (Req): Role name.
`hex` (Req): Hex color code. | -| `/listing` | Manage shop listings (Admin view). | None (Context sensitive?) | -| `/terminal` | Control the terminal display channel. | `action`: 'setup', 'update', 'clear'. | diff --git a/shared/docs/CONFIGURATION.md b/shared/docs/CONFIGURATION.md deleted file mode 100644 index 418a3bc..0000000 --- a/shared/docs/CONFIGURATION.md +++ /dev/null @@ -1,160 +0,0 @@ -# Configuration Guide - -This document outlines the structure and available options for the `config/config.json` file. The configuration is validated using Zod schemas at runtime (see `src/lib/config.ts`). - -## Core Structure - -### Leveling -Configuration for the XP and leveling system. - -| Field | Type | Description | -|-------|------|-------------| -| `base` | `number` | The base XP required for the first level. | -| `exponent` | `number` | The exponent used to calculate XP curves. | -| `chat.cooldownMs` | `number` | Time in milliseconds between XP gains from chat. | -| `chat.minXp` | `number` | Minimum XP awarded per message. | -| `chat.maxXp` | `number` | Maximum XP awarded per message. | - -### Economy -Settings for currency, rewards, and transfers. - -#### Daily -| Field | Type | Description | -|-------|------|-------------| -| `amount` | `integer` | Base amount granted by `/daily`. | -| `streakBonus` | `integer` | Bonus amount per streak day. | -| `weeklyBonus` | `integer` | Bonus amount for a 7-day streak. | -| `cooldownMs` | `number` | Cooldown period for the command (usually 24h). | - -#### Transfers -| Field | Type | Description | -|-------|------|-------------| -| `allowSelfTransfer` | `boolean` | Whether users can transfer money to themselves. | -| `minAmount` | `integer` | Minimum amount required for a transfer. | - -#### Exam -| Field | Type | Description | -|-------|------|-------------| -| `multMin` | `number` | Minimum multiplier for exam rewards. | -| `multMax` | `number` | Maximum multiplier for exam rewards. | - -### Inventory -| Field | Type | Description | -|-------|------|-------------| -| `maxStackSize` | `integer` | Maximum count of a single item in one slot. | -| `maxSlots` | `number` | Total number of inventory slots available. | - -### Lootdrop -Settings for the random chat loot drop events. - -| Field | Type | Description | -|-------|------|-------------| -| `activityWindowMs` | `number` | Time window to track activity for spawning drops. | -| `minMessages` | `number` | Minimum messages required in window to trigger drop. | -| `spawnChance` | `number` | Probability (0-1) of a drop spawning when conditions met. | -| `cooldownMs` | `number` | Minimum time between loot drops. | -| `reward.min` | `number` | Minimum currency reward. | -| `reward.max` | `number` | Maximum currency reward. | -| `reward.currency` | `string` | The currency ID/Symbol used for rewards. | - -### Roles -| Field | Type | Description | -|-------|------|-------------| -| `studentRole` | `string` | Discord Role ID for students. | -| `visitorRole` | `string` | Discord Role ID for visitors. | -| `colorRoles` | `string[]` | List of Discord Role IDs available as color roles. | - -### Moderation -Automated moderation settings. - -#### Prune -| Field | Type | Description | -|-------|------|-------------| -| `maxAmount` | `number` | Maximum messages to delete in one go. | -| `confirmThreshold` | `number` | Amount above which confirmation is required. | -| `batchSize` | `number` | Size of delete batches. | -| `batchDelayMs` | `number` | Delay between batches. | - -#### Cases -| Field | Type | Description | -|-------|------|-------------| -| `dmOnWarn` | `boolean` | Whether to DM users when they are warned. | -| `logChannelId` | `string` | (Optional) Channel ID for moderation logs. | -| `autoTimeoutThreshold` | `number` | (Optional) Warn count to trigger auto-timeout. | - -### System & Misc -| Field | Type | Description | -|-------|------|-------------| -| `commands` | `Object` | Map of command names (keys) to boolean (values) to enable/disable them. | -| `welcomeChannelId` | `string` | (Optional) Channel ID for welcome messages. | -| `welcomeMessage` | `string` | (Optional) Custom welcome message text. | -| `feedbackChannelId` | `string` | (Optional) Channel ID where feedback is posted. | -| `terminal.channelId` | `string` | (Optional) Channel ID for terminal display. | -| `terminal.messageId` | `string` | (Optional) Message ID for terminal display. | - -## Example Config - -```json -{ - "leveling": { - "base": 100, - "exponent": 1.5, - "chat": { - "cooldownMs": 60000, - "minXp": 15, - "maxXp": 25 - } - }, - "economy": { - "daily": { - "amount": "100", - "streakBonus": "10", - "weeklyBonus": "500", - "cooldownMs": 86400000 - }, - "transfers": { - "allowSelfTransfer": false, - "minAmount": "10" - }, - "exam": { - "multMin": 1.0, - "multMax": 2.0 - } - }, - "inventory": { - "maxStackSize": "99", - "maxSlots": 20 - }, - "lootdrop": { - "activityWindowMs": 300000, - "minMessages": 10, - "spawnChance": 0.05, - "cooldownMs": 3600000, - "reward": { - "min": 50, - "max": 150, - "currency": "CREDITS" - } - }, - "commands": { - "example": true - }, - "studentRole": "123456789012345678", - "visitorRole": "123456789012345678", - "colorRoles": [], - "moderation": { - "prune": { - "maxAmount": 100, - "confirmThreshold": 50, - "batchSize": 100, - "batchDelayMs": 1000 - }, - "cases": { - "dmOnWarn": true - } - } -} -``` - -> [!NOTE] -> Fields marked as `integer` or `bigint` in the types can often be provided as strings in the JSON to ensure precision, but the system handles parsing them. diff --git a/shared/docs/DATABASE.md b/shared/docs/DATABASE.md deleted file mode 100644 index f3ed4b6..0000000 --- a/shared/docs/DATABASE.md +++ /dev/null @@ -1,149 +0,0 @@ -# Database Schema - -This document outlines the database schema for the Aurora project. The database is PostgreSQL, managed via Drizzle ORM. - -## Tables - -### Users (`users`) -Stores user data, economy, and progression. - -| Column | Type | Description | -|---|---|---| -| `id` | `bigint` | Primary Key. Discord User ID. | -| `class_id` | `bigint` | Foreign Key -> `classes.id`. | -| `username` | `varchar(255)` | User's Discord username. | -| `is_active` | `boolean` | Whether the user is active (default: true). | -| `balance` | `bigint` | User's currency balance. | -| `xp` | `bigint` | User's experience points. | -| `level` | `integer` | User's level. | -| `daily_streak` | `integer` | Current streak of daily command usage. | -| `settings` | `jsonb` | User-specific settings. | -| `created_at` | `timestamp` | Record creation time. | -| `updated_at` | `timestamp` | Last update time. | - -### Classes (`classes`) -Available character classes. - -| Column | Type | Description | -|---|---|---| -| `id` | `bigint` | Primary Key. Custom ID. | -| `name` | `varchar(255)` | Class name (Unique). | -| `balance` | `bigint` | Class bank balance (shared/flavor). | -| `role_id` | `varchar(255)` | Discord Role ID associated with the class. | - -### Items (`items`) -Definitions of items available in the game. - -| Column | Type | Description | -|---|---|---| -| `id` | `serial` | Primary Key. Auto-incrementing ID. | -| `name` | `varchar(255)` | Item name (Unique). | -| `description` | `text` | Item description. | -| `rarity` | `varchar(20)` | Common, Rare, etc. Default: 'Common'. | -| `type` | `varchar(50)` | MATERIAL, CONSUMABLE, EQUIPMENT, etc. | -| `usage_data` | `jsonb` | Effect data for consumables/usables. | -| `price` | `bigint` | Base value of the item. | -| `icon_url` | `text` | URL for the item's icon. | -| `image_url` | `text` | URL for the item's large image. | - -### Inventory (`inventory`) -Items held by users. - -| Column | Type | Description | -|---|---|---| -| `user_id` | `bigint` | PK/FK -> `users.id`. | -| `item_id` | `integer` | PK/FK -> `items.id`. | -| `quantity` | `bigint` | Amount held. Must be > 0. | - -### Transactions (`transactions`) -Currency transaction history. - -| Column | Type | Description | -|---|---|---| -| `id` | `bigserial` | Primary Key. | -| `user_id` | `bigint` | FK -> `users.id`. The user affecting the balance. | -| `related_user_id` | `bigint` | FK -> `users.id`. The other party (if any). | -| `amount` | `bigint` | Amount transferred. | -| `type` | `varchar(50)` | Transaction type identifier. | -| `description` | `text` | Human-readable description. | -| `created_at` | `timestamp` | Time of transaction. | - -### Item Transactions (`item_transactions`) -Item flow history. - -| Column | Type | Description | -|---|---|---| -| `id` | `bigserial` | Primary Key. | -| `user_id` | `bigint` | FK -> `users.id`. | -| `related_user_id` | `bigint` | FK -> `users.id`. | -| `item_id` | `integer` | FK -> `items.id`. | -| `quantity` | `bigint` | Amount gained (+) or lost (-). | -| `type` | `varchar(50)` | TRADE, SHOP_BUY, DROP, etc. | -| `description` | `text` | Description. | -| `created_at` | `timestamp` | Time of transaction. | - -### Quests (`quests`) -Quest definitions. - -| Column | Type | Description | -|---|---|---| -| `id` | `serial` | Primary Key. | -| `name` | `varchar(255)` | Quest title. | -| `description` | `text` | Quest text. | -| `trigger_event` | `varchar(50)` | Event that triggers progress checks. | -| `requirements` | `jsonb` | Completion criteria. | -| `rewards` | `jsonb` | Rewards for completion. | - -### User Quests (`user_quests`) -User progress on quests. - -| Column | Type | Description | -|---|---|---| -| `user_id` | `bigint` | PK/FK -> `users.id`. | -| `quest_id` | `integer` | PK/FK -> `quests.id`. | -| `progress` | `integer` | Current progress value. | -| `completed_at` | `timestamp` | Completion time (null if active). | - -### User Timers (`user_timers`) -Generic timers for cooldowns, temporary effects, etc. - -| Column | Type | Description | -|---|---|---| -| `user_id` | `bigint` | PK/FK -> `users.id`. | -| `type` | `varchar(50)` | PK. Timer type (COOLDOWN, EFFECT, ACCESS). | -| `key` | `varchar(100)` | PK. specific ID (e.g. 'daily'). | -| `expires_at` | `timestamp` | When the timer expires. | -| `metadata` | `jsonb` | Extra data. | - -### Lootdrops (`lootdrops`) -Active chat loot drop events. - -| Column | Type | Description | -|---|---|---| -| `message_id` | `varchar(255)` | Primary Key. Discord Message ID. | -| `channel_id` | `varchar(255)` | Discord Channel ID. | -| `reward_amount` | `integer` | Currency amount. | -| `currency` | `varchar(50)` | Currency type constant. | -| `claimed_by` | `bigint` | FK -> `users.id`. Null if unclaimed. | -| `created_at` | `timestamp` | Spawn time. | -| `expires_at` | `timestamp` | Despawn time. | - -### Moderation Cases (`moderation_cases`) -History of moderation actions. - -| Column | Type | Description | -|---|---|---| -| `id` | `bigserial` | Primary Key. | -| `case_id` | `varchar(50)` | Unique friendly ID. | -| `type` | `varchar(20)` | warn, timeout, kick, ban, etc. | -| `user_id` | `bigint` | Target user ID. | -| `username` | `varchar(255)` | Target username snapshot. | -| `moderator_id` | `bigint` | Acting moderator ID. | -| `moderator_name` | `varchar(255)` | Moderator username snapshot. | -| `reason` | `text` | Reason for action. | -| `metadata` | `jsonb` | Extra data. | -| `active` | `boolean` | Is this case active? | -| `created_at` | `timestamp` | Creation time. | -| `resolved_at` | `timestamp` | Resolution/Expiration time. | -| `resolved_by` | `bigint` | User ID who resolved it. | -| `resolved_reason` | `text` | Reason for resolution. | diff --git a/shared/docs/LOOTBOX_GUIDE.md b/shared/docs/LOOTBOX_GUIDE.md deleted file mode 100644 index fd986c4..0000000 --- a/shared/docs/LOOTBOX_GUIDE.md +++ /dev/null @@ -1,127 +0,0 @@ -# Lootbox Creation Guide - -Currently, the Item Wizard does not support creating **Lootbox** items directly. Instead, they must be inserted manually into the database. This guide details the required JSON structure for the `LOOTBOX` effect. - -## Item Structure - -To create a lootbox, you need to insert a row into the `items` table. The critical part is the `usageData` JSON column. - -```json -{ - "consume": true, - "effects": [ - { - "type": "LOOTBOX", - "pool": [ ... ] - } - ] -} -``` - -## Loot Table Structure - -The `pool` property is an array of `LootTableItem` objects. A random item is selected based on the total `weight` of all items in the pool. - -| Field | Type | Description | -|-------|------|-------------| -| `type` | `string` | One of: `CURRENCY`, `ITEM`, `XP`, `NOTHING`. | -| `weight` | `number` | The relative probability weight of this outcome. | -| `message` | `string` | (Optional) Custom message to display when this outcome is selected. | - -### Outcome Types - -#### 1. Currency -Gives the user coins. - -```json -{ - "type": "CURRENCY", - "weight": 50, - "amount": 100, // Fixed amount OR - "minAmount": 50, // Minimum random amount - "maxAmount": 150 // Maximum random amount -} -``` - -#### 2. XP -Gives the user Experience Points. - -```json -{ - "type": "XP", - "weight": 30, - "amount": 500 // Fixed amount OR range (minAmount/maxAmount) -} -``` - -#### 3. Item -Gives the user another item (by ID). - -```json -{ - "type": "ITEM", - "weight": 10, - "itemId": 42, // The ID of the item to give - "amount": 1 // (Optional) Quantity to give, default 1 -} -``` - -#### 4. Nothing -An empty roll. - -```json -{ - "type": "NOTHING", - "weight": 10, - "message": "The box was empty! Better luck next time." -} -``` - -## Complete Example - -Here is a full SQL insert example (using a hypothetical SQL client or Drizzle studio) for a "Basic Lootbox": - -**Name**: Basic Lootbox -**Type**: CONSUMABLE -**Effect**: -- 50% chance for 100-200 Coins -- 30% chance for 500 XP -- 10% chance for Item ID 5 (e.g. Rare Gem) -- 10% chance for Nothing - -**JSON for `usageData`**: -```json -{ - "consume": true, - "effects": [ - { - "type": "LOOTBOX", - "pool": [ - { - "type": "CURRENCY", - "weight": 50, - "minAmount": 100, - "maxAmount": 200 - }, - { - "type": "XP", - "weight": 30, - "amount": 500 - }, - { - "type": "ITEM", - "weight": 10, - "itemId": 5, - "amount": 1, - "message": "Startstruck! You found a Rare Gem!" - }, - { - "type": "NOTHING", - "weight": 10, - "message": "It's empty..." - } - ] - } - ] -} -``` diff --git a/shared/docs/MODULE_STRUCTURE.md b/shared/docs/MODULE_STRUCTURE.md deleted file mode 100644 index 6ed32ea..0000000 --- a/shared/docs/MODULE_STRUCTURE.md +++ /dev/null @@ -1,72 +0,0 @@ -# Aurora Module Structure Guide - -This guide documents the standard module organization patterns used in the Aurora codebase. Following these patterns ensures consistency, maintainability, and clear separation of concerns. - -## Module Anatomy - -A typical module in `@modules/` is organized into several files, each with a specific responsibility. - -Example: `trade` module -- `trade.service.ts`: Business logic and data access. -- `trade.view.ts`: Discord UI components (embeds, modals, select menus). -- `trade.interaction.ts`: Handler for interaction events (buttons, modals, etc.). -- `trade.types.ts`: TypeScript interfaces and types. -- `trade.service.test.ts`: Unit tests for the service logic. - -## File Responsibilities - -### 1. Service (`*.service.ts`) -The core of the module. It contains the business logic, database interactions (using Drizzle), and state management. -- **Rules**: - - Export a singleton instance: `export const tradeService = new TradeService();` - - Should not contain Discord-specific rendering logic (return data, not embeds). - - Throw `UserError` for validation issues that should be shown to the user. - -### 2. View (`*.view.ts`) -Handles the creation of Discord-specific UI elements like `EmbedBuilder`, `ActionRowBuilder`, and `ModalBuilder`. -- **Rules**: - - Focus on formatting and presentation. - - Takes raw data (from services) and returns Discord components. - -### 3. Interaction Handler (`*.interaction.ts`) -The entry point for Discord component interactions (buttons, select menus, modals). -- **Rules**: - - Export a single handler function: `export async function handleTradeInteraction(interaction: Interaction) { ... }` - - Routes internal `customId` patterns to specific logic. - - Relies on `ComponentInteractionHandler` for centralized error handling. - - **No local try-catch** for standard validation errors; let them bubble up as `UserError`. - -### 4. Types (`*.types.ts`) -Central location for module-specific TypeScript types and constants. -- **Rules**: - - Define interfaces for complex data structures. - - Use enums or literal types for states and custom IDs. - -## Interaction Routing - -All interaction handlers must be registered in `src/lib/interaction.routes.ts`. - -```typescript -{ - predicate: (i) => i.customId.startsWith("module_"), - handler: () => import("@/modules/module/module.interaction"), - method: 'handleModuleInteraction' -} -``` - -## Error Handling Standards - -Aurora uses a centralized error handling pattern in `ComponentInteractionHandler`. - -1. **UserError**: Use this for validation errors or issues the user can fix (e.g., "Insufficient funds"). - - `throw new UserError("You need more coins!");` -2. **SystemError / Generic Error**: Use this for unexpected system failures. - - These are logged to the console/logger and show a generic "Unexpected error" message to the user. - -## Naming Conventions - -- **Directory Name**: Lowercase, singular (e.g., `trade`, `inventory`). -- **File Names**: `moduleName.type.ts` (e.g., `trade.service.ts`). -- **Class Names**: PascalCase (e.g., `TradeService`). -- **Service Instances**: camelCase (e.g., `tradeService`). -- **Interaction Method**: `handle[ModuleName]Interaction`.