Data Retention & Purging

Relevant source files

The following files were used as context for generating this wiki page:

• src/util/dataRetention.ts
• src/commands/util/purge.ts
• config.example.json
• src/util/logging/logAction.ts
• src/util/logging/utils.ts
• src/db/db.ts
• src/util/helpers.ts

The Data Retention and Purging systems in the Poixpixel Discord Bot are designed to manage the lifecycle of stored data and facilitate the bulk removal of message content. Data retention specifically focuses on the automated cleanup of user-related metrics (such as levels and achievements) for members who have left the server, ensuring compliance with privacy standards and maintaining database efficiency. Purging, on the other hand, provides moderators with tools to manually delete large volumes of recent message history within specific channels.

These systems interact closely with the bot's configuration, database layer, and logging modules to ensure that all deletion actions are governed by defined rules and are transparently recorded for audit purposes.

Automated Data Retention

The automated data retention system runs as a scheduled background task that periodically scans the database for users who are no longer present in the guild. It determines eligibility for data deletion based on configurable time thresholds and the user's current moderation status (e.g., active bans).

Retention Logic and Thresholds

The system utilizes two primary configuration values to govern cleanup: deleteAfterDays and postBanGraceDays. The cleanup process identifies "candidates" from the memberTable where currentlyInServer is false.

The following flowchart illustrates the decision logic for deleting user data:

The logic ensures that temporary bans are respected by waiting for the ban to expire and an additional grace period to pass before wiping data. Permanent bans do not block deletion once the standard retention period has passed.
Sources: src/util/dataRetention.ts:13-98, config.example.json:118-124

Data Deletion Implementation

When a user is confirmed eligible, the system invokes specialized database functions to remove their footprint.

• deleteUserLevel(discordId): Removes the user's experience points and level data.
• removeAllUserAchievements(discordId): Clears all earned achievements for the user.

Citations: src/util/dataRetention.ts:117-118

Manual Message Purging

The purge command allows administrators and moderators with the ManageMessages permission to bulk-delete up to 100 messages at once. This system is subject to Discord API limitations, specifically the inability to bulk-delete messages older than 14 days.

Purge Execution Flow

The purging process involves validating the user's request, fetching recent channel history, filtering for age and user-specific constraints, and finally executing the bulkDelete API call.

Purge Configurations & Limits

Parameter	Type	Default	Description
amount	Integer	Required	Number of messages to delete (Min: 1, Max: 100).
age_limit	String	14d	Duration string (e.g., 7d). Maxed at 14d due to API limits.
user	User	Optional	If provided, only messages from this specific user are purged.
reason	String	"No reason"	Audit log reason for the purge action.

Sources: src/commands/util/purge.ts:15-38

Audit Logging and Persistence

Every purging action and automated data retention event is logged to maintain a transparent record of data destruction.

Purge Logs and File Attachments

Because a single purge action can involve many messages, the bot generates a temporary text file containing the full metadata (Author, Timestamp, Content, Attachments) of every deleted message. This file is sent to the log channel along with a summary embed.

• Storage: Purge logs are stored in a temporary OS directory (os.tmpdir()/poixpixel-discord-bot/purge-logs).
• Cleanup: The cleanupOldPurgeLogs function runs in the background to delete these temporary files if they are older than 7 days.

Sources: src/util/logging/logAction.ts:121-164, src/util/logging/utils.ts:223-248

Logging Components

The logAction function constructs detailed embeds for various deletion events:

• Purge Embed: Includes the channel, moderator, message count, and target user.
• Data Retention Logs: Uses the logger.info transport to record when levels and achievements are wiped, often redacting full IDs for privacy (e.g., "ID suffix of: 1234").

Sources: src/util/logging/logAction.ts:167-185, src/util/dataRetention.ts:119-122

Configuration Schema

Data retention and purging behavior is defined in the config.json file.

{
  "dataRetention": {
    "deleteAfterDays": 30,
    "postBanGraceDays": 7
  },
  "channels": {
    "logs": "LOG_CHANNEL_ID"
  }
}

• deleteAfterDays: The number of days a user must be absent before their level/achievement data is purged. Setting this to 0 disables automated retention.
• postBanGraceDays: An additional buffer period after a temporary ban expires before data becomes eligible for deletion.

Sources: config.example.json:118-124, src/util/dataRetention.ts:15-18

Summary

The Data Retention & Purging module ensures the bot remains performant and respects user data lifecycles. By combining automated daily cleanup of inactive user stats with robust manual message purging tools, the system provides both maintenance and moderation capabilities. All actions are backed by an asynchronous logging system that preserves the context of deleted data through summary embeds and detailed file attachments.