Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/resynceddesign/giveawaybot/llms.txt

Use this file to discover all available pages before exploring further.

GiveawayBot’s SQLite database contains two tables: giveaways, which stores every giveaway and its live entry list, and guilds, which stores per-server configuration. Both tables are created with CREATE TABLE IF NOT EXISTS on startup so the bot never errors if the file is fresh.

​
giveaways table

CREATE TABLE IF NOT EXISTS giveaways (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    channelId TEXT NOT NULL,
    duration INTEGER NOT NULL,
    winners INTEGER NOT NULL,
    prize TEXT NOT NULL,
    entries TEXT NOT NULL,
    createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
    messageId TEXT,
    hostId TEXT NOT NULL,
    guildId TEXT NOT NULL,
    status BOOLEAN DEFAULT 1
)
​
id
INTEGER
Auto-increment primary key. Used internally to identify a giveaway row and as the argument to endGiveaway() and addEntry().
​
channelId
TEXT
required
Discord channel snowflake (string) where the giveaway embed was posted. Used by processGiveaways() to fetch the channel and send winner announcements.
​
duration
INTEGER
required
Giveaway duration in seconds. Combined with createdAt to calculate the end time: endTime = createdAt + duration * 1000.
​
winners
INTEGER
required
Number of winners to pick when the giveaway ends. pickWinners() iterates up to this count when sampling from entries.
​
prize
TEXT
required
Prize description string provided by the host via /gcreate. Used as the embed title and in winner announcement messages.
​
entries
TEXT
required
JSON array of Discord user ID strings representing everyone who clicked the entry button. Example: ["123456789", "987654321"]. Stored as text and parsed with JSON.parse() at runtime. Starts as [] on creation.
​
createdAt
DATETIME
default:"CURRENT_TIMESTAMP"
UTC timestamp set automatically by SQLite when the row is inserted. checkEnding() parses this value with new Date() to determine whether the giveaway has expired.
​
messageId
TEXT
Discord message snowflake of the giveaway embed. Set after the embed is posted. Used by processGiveaways() to fetch and edit the message when the giveaway ends, and by fetchGiveaway() as an alternative lookup key.
​
hostId
TEXT
required
Discord user snowflake of the member who ran /gcreate. Displayed in the embed footer and winner announcement messages.
​
guildId
TEXT
required
Discord guild snowflake. Used to look up the guild’s configured color, emoji, and ping preference from the guilds table when rendering embeds.
​
status
BOOLEAN
default:"1"
Active flag. 1 = giveaway is running and accepting entries. 0 = giveaway has ended. fetchActive() filters to status = 1; endGiveaway() sets this to 0.

​
guilds table

CREATE TABLE IF NOT EXISTS guilds (
    guildId BIGINT PRIMARY KEY,
    color TEXT DEFAULT '#ff8e4d',
    everyonePing BOOLEAN DEFAULT 0,
    emoji TEXT DEFAULT '🎊'
)
​
guildId
BIGINT
Discord guild snowflake. Primary key. A row is inserted when the bot joins a server and used as the lookup key for all config reads during giveaway rendering.
​
color
TEXT
default:"#ff8e4d"
Hex colour string applied to the giveaway embed via EmbedBuilder.setColor(). Configurable with /gconfig color. Falls back to #ff8e4d if the row is missing.
​
everyonePing
BOOLEAN
default:"0"
Whether to include a spoiler-wrapped @everyone mention in the giveaway-ended message. 0 = disabled, 1 = enabled. Toggled with /gconfig ping.
​
emoji
TEXT
default:"🎊"
Emoji shown on the entry button label and in the giveaway header/footer text. Configurable with /gconfig emoji. Falls back to 🎊 if the row is missing.

​
GiveawayManager methods

​
createGiveaway(giveaway: Giveaway)
void
Inserts a new row into the giveaways table. entries defaults to [] if not provided. status defaults to 1 via the column default.
​
endGiveaway(giveawayId: string)
void
Sets status = 0 on the row with the given id. Called by processGiveaways() immediately after winners are picked.
​
fetchActive()
Giveaway[]
Returns all rows where status = 1. Called every second by checkEnding() to determine which giveaways need to be checked for expiry.
​
fetchGiveaway(gId: string)
Giveaway
Looks up a giveaway by its integer id first. If no row is found, falls back to a lookup by messageId. This makes the method work with either the database row ID or the Discord message snowflake.
​
checkEnding()
string[]
Calls fetchActive() and compares each giveaway’s createdAt + duration * 1000 against Date.now(). Returns an array of id strings for every giveaway whose end time has passed.
​
pickWinners(giveaway: Giveaway)
string[]
Parses giveaway.entries as a JSON array, then randomly samples up to giveaway.winners unique user IDs by splicing from the array. Returns an empty array if there are no entries. Duplicate winners are not possible because each selected entry is removed from the pool before the next pick.
​
addEntry(giveawayId: number, userId: string)
boolean
Reads the current entries array for the given giveawayId. Returns false without writing if the giveaway does not exist or if userId is already present in the array. Otherwise appends userId, serialises the array back to JSON, and updates the row. Returns true on a successful entry.

​
GuildManager methods

​
createGuild(guildId: string, color?: string)
void
Inserts a new row for the guild using INSERT OR IGNORE, so calling it multiple times for the same guild is safe. color defaults to #ff8e4d when omitted.
​
updateColor(guildId: string, newColor: string)
void
Updates the color column for the given guild. Called by /gconfig color.
​
updateEmoji(guildId: string, newEmoji: string)
void
Updates the emoji column for the given guild. Called by /gconfig emoji.
​
updatePing(guildId: string, newPing: boolean)
void
Updates everyonePing to 1 or 0 based on the boolean argument. Called by /gconfig ping.
​
fetchColor(guildId: string)
ColorResolvable
Returns the guild’s configured embed colour, or #ff8e4d if no row exists.
​
fetchEmoji(guildId: string)
string
Returns the guild’s configured emoji, or 🎊 if no row exists.
​
fetchEveryonePing(guildId: string)
boolean
Returns true if everyonePing = 1 for the guild, false otherwise (including when no row exists).

​
Giveaway TypeScript interface

The Giveaway interface is defined in gwManager.ts and used as the argument and return type for all GiveawayManager methods: 
export interface Giveaway {
    id?: number;
    channelId: string;
    duration: number;
    winners: number;
    prize: string;
    entries: string;
    createdAt?: string;
    messageId: string;
    hostId: string;
    guildId: string;
    status?: number; // 1 = active, 0 = ended
}
id, createdAt, and status are optional because they are supplied by SQLite (auto-increment, default timestamp, and default 1 respectively) rather than by the caller when creating a new giveaway.
entries is typed as string rather than string[] because it is stored as a serialised JSON string in SQLite. Always use JSON.parse(giveaway.entries) before working with the array, and JSON.stringify(entries) before writing it back.

Build docs developers (and LLMs) love

Get started for freeTalk to us