Giveaway Management
Relevant source files
The following files were used as context for generating this wiki page:
The Giveaway Management system in Amina provides a comprehensive suite of tools for creating, managing, and concluding giveaways within a Discord server. It is built upon the discord-giveaways third-party library, extending its functionality with custom database integration using Mongoose for data persistence.
The system is primarily accessed through the /giveaway slash command, which offers a range of subcommands for full lifecycle management, from starting a new giveaway with a detailed modal-based setup to ending, rerolling, and listing active giveaways. This feature is designed to be robust and user-friendly, with centralized configuration and response strings.
Architecture Overview
The giveaway system's architecture is composed of several key components that work together: the user-facing command, the core giveaway manager, the database schema for persistence, and configuration files.
The diagram below illustrates the interaction between these components.
This diagram shows the flow from a user's command through the command router to the specific subcommand handler. The handler then utilizes the MongooseGiveaways manager, which acts as an abstraction layer over the discord-giveaways library and communicates with the MongoDB database via the Giveaways schema.
Sources: src/commands/giveaways/giveaway.ts, src/handlers/giveaway.ts, src/database/schemas/Giveaways.ts, package.json:35
Database Schema
All giveaway data is persisted in a MongoDB collection defined by the Giveaways.ts schema. This schema is designed to be compatible with the discord-giveaways library.
Sources: src/database/schemas/Giveaways.ts
ER Diagram
The following diagram represents the entity relationship for the Giveaways schema.
Schema Fields
| Field | Type | Description |
|---|---|---|
messageId | String | The Discord message ID of the giveaway embed. Serves as the primary key. |
channelId | String | The ID of the channel where the giveaway is running. |
guildId | String | The ID of the server where the giveaway is running. |
startAt | Number | Timestamp (ms) of when the giveaway started. |
endAt | Number | Timestamp (ms) of when the giveaway is scheduled to end. |
ended | Boolean | true if the giveaway has ended, otherwise false. |
winnerCount | Number | The number of winners to be chosen. |
prize | String | A description of the prize. |
messages | String | A JSON string containing custom messages for various giveaway events. |
thumbnail | String | URL for the thumbnail image in the giveaway embed. |
hostedBy | String | The user tag of the person hosting the giveaway. |
exemptPermissions | String | A JSON array of permissions that exempt users from requirements. |
bonusEntries | String | A JSON string defining roles that grant bonus entries. |
embedColor | Mixed | The color of the giveaway embed. |
embedColorEnd | Mixed | The color of the embed after the giveaway has ended. |
reaction | Mixed | The emoji used for entering the giveaway. |
winnerIds | [String] | An array of user IDs for the winners. |
extraData | Mixed | An object for storing extra data, such as allowedRoles. |
pauseOptions | Object | Contains options related to pausing, like isPaused. |
Sources: src/database/schemas/Giveawaysts:4-65
Core Logic: MongooseGiveaways Manager
The MongooseGiveaways class in src/handlers/giveaway.ts is the heart of the system's persistence layer. It extends the GiveawaysManager from the discord-giveaways library and overrides its data handling methods to use Mongoose, enabling giveaways to be stored in MongoDB.
Sources: src/handlers/giveaway.ts:5-39
Key Methods
constructor(client): Initializes the manager with default settings, such as embed colors and the entry reaction emoji, which are pulled from the application's configuration.getAllGiveaways(): Retrieves all giveaway documents from the MongoDB collection. This is used by thediscord-giveawaysmanager on startup to load all active giveaways.saveGiveaway(messageId, giveawayData): Creates a new giveaway document in the database.editGiveaway(messageId, giveawayData): Updates an existing giveaway document in the database, identified by itsmessageId.deleteGiveaway(messageId): Removes a giveaway document from the database.
Sources: src/handlers/giveaway.ts:7-38
Command Structure
All giveaway functionality is exposed through the /giveaway slash command. This command acts as a router, delegating tasks to various subcommands.
Sources: src/commands/giveaways/giveaway.ts:20-132
| Subcommand | Description |
|---|---|
start | Begins a new giveaway in a specified channel using a modal for setup. |
pause | Temporarily pauses an active giveaway. |
resume | Resumes a paused giveaway. |
end | Immediately ends a giveaway and picks winners. |
reroll | Picks new winners for a finished giveaway. |
list | Shows all active giveaways in the current server. |
edit | Modifies an ongoing giveaway (duration, prize, winner count). |
Sources: src/commands/giveaways/giveaway.ts:23-131
The system also integrates with the /settings status command, which lists active giveaways as part of the overall server settings overview.
Sources: src/commands/admin/settings/status.ts:114-145
Giveaway Creation Flow
Creating a giveaway is an interactive process initiated by the /giveaway start command. It uses a button and a modal to gather all necessary details from the user.
The sequence diagram below outlines the entire creation flow.
The modal prompts for the following information:
- Duration (e.g.,
1h,1d) - Prize
- Number of winners
- Role IDs required to enter (optional)
- User ID of the host (optional)
Sources: src/commands/giveaways/giveaway.ts:246-299, src/data/respSocial.json:89-107
Configuration
The giveaway system has a few configuration options defined in types/config.d.ts and applied in src/handlers/giveaway.ts.
| Key | File | Description |
|---|---|---|
GIVEAWAYS.ENABLED | types/config.d.ts | A boolean to enable or disable the entire giveaway feature. |
GIVEAWAYS.REACTION | types/config.d.ts | The default emoji used for giveaway entries. |
default.botsCanWin | src/handlers/giveaway.ts | If false, bots cannot win giveaways. Default is false. |
default.embedColor | src/handlers/giveaway.ts | The default hex color for active giveaway embeds. |
default.embedColorEnd | src/handlers/giveawayts | The default hex color for ended giveaway embeds. |
Sources: types/config.d.ts:77-80, src/handlers/giveaway.ts:10-15
User-Facing Text
All responses, prompts, and error messages for the giveaway feature are centralized in src/data/respSocial.json under the giveaway key. This allows for easy modification of text without changing the application code.
| Key Path | Example Text |
|---|---|
giveaway.success.started | "giveaway started." |
giveaway.error.notFound | "giveaway not found." |
giveaway.winner | "congrats {winners}. you won {prize}." |
giveaway.noWinner | "no valid participants." |
giveaway.setup.modal.title | "giveaway setup" |
giveaway.setup.modal.duration.label | "what is the duration?" |
Sources: src/data/respSocial.json:30-109
Summary
The Giveaway Management system is a well-structured and feature-rich module within Amina. By extending the discord-giveaways library with a custom Mongoose-based persistence layer, it ensures that giveaways are durable and can survive bot restarts. The use of a modal-driven setup for giveaway creation provides a superior user experience, while the comprehensive set of subcommands allows for fine-grained control over the entire giveaway lifecycle. Centralized configuration and response strings make the system maintainable and easy to customize.