Invite Tracking System
Relevant source files
The following files were used as context for generating this wiki page:The Invite Tracking System is a comprehensive feature within Amina designed to monitor server invitations, attribute new members to their inviters, and manage a system of rewards based on invite counts. It provides both user-facing commands to check invite statistics and administrative tools to manage tracking, rewards, and user data. The system relies on caching guild invites and comparing them upon a new member's arrival to accurately identify the source of the join. This data is then persisted in the database and used for features like invite ranks, leaderboards, and customized welcome messages.
The system requires the ManageGuild permission for core tracking functionality and the GuildInvites gateway intent to receive invite-related events from Discord.
Sources: src/commands/social/invites.ts:20, src/handlers/invite.ts:47, src/structures/BotClient.ts:60
Core Architecture
The system is primarily composed of an event-driven tracking handler, an in-memory cache, database models for persistence, and a set of slash commands for interaction.
Components
| Component | Description | File |
|---|---|---|
| Invite Handler | Contains the core business logic for caching invites, tracking joins/leaves, and managing rewards. | src/handlers/invite.ts |
/invite Command | The main user and admin interface for interacting with the invite system. | src/commands/social/invites.ts |
| Event Listeners | Triggers tracking logic on guildMemberAdd and guildMemberRemove events. | src/handlers/invite.ts |
| Invite Cache | An in-memory Collection that stores a snapshot of a guild's invites to detect changes. | src/handlers/invite.ts:21 |
| Database Schema | The invite_data object within the Member schema stores persistent invite statistics for each user. | src/commands/social/invites.ts:303 |
Data Model: invite_data
Invite statistics are stored within the Member document in the database. The structure is as follows:
| Field | Type | Description |
|---|---|---|
inviter | String | The user ID of the person who invited this member. Can be 'VANITY'. |
code | String | The specific invite code used by the member to join. |
tracked | Number | The number of members who joined using this user's invites. |
added | Number | The number of invites manually added by an admin. |
fake | Number | The number of "fake" invites (not explicitly defined in the code, but present in the data structure). |
left | Number | The number of members invited by this user who have since left the server. |
Sources: src/commands/social/invites.ts:303-310, src/handlers/invite.ts:15-20, src/handlers/invite.ts:178-180
The effective number of invites for a user is calculated using the formula: tracked + added - fake - left.
Sources: src/handlers/invite.ts:27-30
Invite Tracking Flow
The system's primary function is to identify which invite was used when a new member joins. This is achieved through a process of caching and comparison.
Invite Caching
To detect which invite's usage count has increased, the bot maintains an in-memory cache of all invites for a guild.
- The
cacheGuildInvitesfunction fetches all current invites from the guild, including the vanity URL if one exists. - It formats them into a
CachedInviteobject and stores them in aCollectionkeyed by the guild's ID. - This cache is populated when invite tracking is enabled and is updated each time a new member joins to get the latest state.
Sources: src/handlers/invite.ts:21, src/handlers/invite.ts:45-64
This diagram illustrates the process of caching guild invites.
Sources: src/handlers/invite.ts:45-64
Member Join Logic (trackJoinedMember)
When a new user joins a guild (guildMemberAdd event), the trackJoinedMember function is executed to determine the inviter.
This sequence diagram shows the interactions when a new member joins.
Sources: src/handlers/invite.ts:114-153
The logic identifies the used invite by finding an invite whose uses count in the new fetch is greater than its uses count in the cached version. A special case handles invites that are deleted immediately after use.
Sources: src/handlers/invite.ts:124-128, src/handlers/invite.ts:132-143
Member Leave Logic (trackLeftMember)
When a member leaves, the trackLeftMember function is called. It retrieves the departed member's invite_data from the database to find their original inviter. It then increments the left counter for that inviter and re-evaluates their invite rewards, potentially removing a rank role.
Sources: src/handlers/invite.ts:158-176
Commands and Management
The /invite command serves as the central hub for all invite-related actions.
Sources: src/commands/social/invites.ts:15-21
User Commands
| Subcommand | Description |
|---|---|
view [user] | Checks the invite count (total, fake, left) for a specified user or the command author. |
codes [user] | Lists all active invite codes created by a user and their usage counts. |
inviter [user] | Shows who invited a specific user to the server, along with the invite code used. |
ranks | Displays the configured invite rank rewards for the server. |
Sources: src/commands/social/invites.ts:26-66
Admin Commands
These commands require the Manage Guild permission.
| Subcommand | Description |
|---|---|
tracking <status> | Enables or disables the invite tracking system for the server. |
reset <user> | Clears the added invites for a specified user. |
import [user] | Syncs existing guild invites to the tracking system. Can be run for all members or a specific user. |
rank add <role> <invites> | Creates a new invite rank, granting a specific role at a required number of invites. |
rank remove <role> | Deletes an existing invite rank reward. |
Sources: src/commands/social/invites.ts:68-166, src/commands/social/invites.ts:192-198
An additional admin command, /add invites, allows for manually adding a number of invites to a user's added count.
Sources: src/commands/utility/add/sub/invites.ts
Invite Rewards (Ranks)
The system includes a feature to automatically grant roles to members when they reach a certain number of effective invites.
Configuration
Admins use the /invite rank add and /invite rank remove commands to configure these rewards. The configuration is stored in the guild's settings document.
Sources: src/commands/social/invites.ts:466-522
Reward Logic (checkInviteRewards)
The checkInviteRewards function is the core of the reward system. It is triggered after a member's invite count changes (e.g., after a new member joins, a member leaves, or an admin uses /add invites or /invite reset).
This flowchart shows how the system decides whether to add or remove a rank role.
Sources: src/handlers/invite.ts:69-93
Integrations
The data from the Invite Tracking System is utilized by other features within Amina.
Welcome Messages
The Greeting handler can use placeholders like {inviter:name} and {invites} in welcome messages to announce who invited the new member and how many invites they now have.
Sources: src/handlers/greeting.ts:40-41, src/handlers/greeting.ts:55-59
Leaderboard
The /leaderboard invite command queries the database to generate a top-10 list of members with the most effective invites, fostering a friendly sense of competition.