PingMe/PLAN.md

Ping Me Plan

Goal

Build Ping Me, a minimal Discord reaction-role bot that lets server admins create simple role assignment embeds using either:

• reaction emojis, or
• message buttons with optional emojis.

Admins should be guided through setup with an easy step-by-step wizard where each step is shown as an embed page. The same setup message is edited as the admin clicks Back and Next.

Assumptions

• The first version targets Discord only.
• The bot will use slash commands and Discord interactions.
• Only users with an appropriate permission, such as Manage Roles or Administrator, can create/edit reaction-role messages.
• The bot must have Manage Roles, Read Message History, Add Reactions, Send Messages, Embed Links, and interaction permissions.
• Reaction-role messages are configured per guild/server.
• Role assignment should fail gracefully if the selected role is above the bot's highest role.

Core Features

1. Reaction-role creation wizard

Command:

/pingme create

The command starts an interactive wizard visible only to the admin, or optionally in the target channel if Discord limitations require it.

Wizard pages:

1. Intro / Target Channel

   • Explain what will be created.
   • Select the channel where the final reaction-role embed will be posted.

2. Embed Content

   • Set embed title.
   • Set embed description.
   • Optional color.
   • Optional footer.

3. Selection Type

   • Choose Buttons or Reactions.

4. Selection Mode

   • Choose Single role only or Multiple roles allowed.

5. Add Role Options

   • Add one or more entries.
   • Each entry contains:
     • role
     • label/text
     • emoji, optional for buttons and required/practical for reactions
   • For buttons, emoji can be omitted.
   • For reactions, each option needs a unique emoji.

6. Preview

   • Show the final embed.
   • Show configured buttons or reaction list.

7. Publish

   • Confirm and post the final message in the chosen channel.
   • Save the message/configuration to storage.
   • For reaction mode, add the configured reactions to the message.

Each wizard page uses one edited setup message with navigation controls:

• Back
• Next
• Cancel
• page-specific buttons/select menus/modals

2. Button role assignment

When a user clicks a configured button:

• Look up the reaction-role config by guild/channel/message/custom ID.
• Determine the selected role.
• If mode is multiple, toggle that role:
  • if the user has it, remove it;
  • otherwise add it.
• If mode is single, ensure the user only has the selected role from this message:
  • remove other roles configured on the same message;
  • add the selected role.
• Reply ephemerally with a short success/failure message.

3. Reaction role assignment

When a user adds a configured reaction:

• Look up the config by guild/channel/message/emoji.
• Ignore bot reactions.
• If mode is multiple, add the mapped role.
• If mode is single:
  • remove other configured roles from the member;
  • remove the user's other reactions on that message;
  • add the selected role.

When a user removes a configured reaction:

• Remove the mapped role, unless this conflicts with single-select state handling.

4. Management commands

Initial useful commands:

/pingme create
/pingme list
/pingme delete message:<message_id>
/pingme help

Later optional commands:

/pingme edit message:<message_id>
/pingme refresh message:<message_id>

Data Model

Use a small persistent database. SQLite is enough for local/self-hosted use; Postgres can be added later if needed.

reaction_role_messages

• id
• guild_id
• channel_id
• message_id
• created_by_user_id
• type: buttons or reactions
• selection_mode: single or multiple
• embed_title
• embed_description
• embed_color
• embed_footer
• created_at
• updated_at

reaction_role_options

• id
• message_config_id
• role_id
• label
• emoji
• button_custom_id, nullable for reaction mode
• position

wizard_sessions

Can be stored in memory for v1, with timeout cleanup.

Fields:

• guild_id
• admin_user_id
• setup_message_id
• current_page
• draft embed fields
• draft type/mode
• draft options
• created_at
• expires_at

Suggested Technical Stack

• Node.js + TypeScript
• discord.js
• SQLite with either Prisma, Drizzle, or a lightweight query layer
• Environment variables for bot token/client ID/guild dev ID

Important Discord Constraints

• The bot can only assign roles below its highest role.
• Discord messages can have at most 5 action rows and 5 buttons per row, so button mode should support up to 25 options per message.
• Reaction mode should enforce unique emojis per message.
• Custom emojis may require the bot to be in the emoji's source server or otherwise able to use them.
• Removing a user's reaction requires appropriate permissions and access to message history.
• Interactions must be acknowledged quickly; longer work should defer replies.

Implementation Milestones

Milestone 1: Project setup

• Initialize TypeScript project.
• Add Discord client login.
• Register slash commands.
• Add basic logging and environment config.

Milestone 2: Persistence

• Add database setup and migrations.
• Implement repository functions for reaction-role messages and options.

Milestone 3: Creation wizard

• Implement /pingme create.
• Implement paginated embed wizard state.
• Add Back/Next/Cancel controls.
• Add modals/select menus for embed content, roles, emojis, and labels.
• Add preview and publish step.

Milestone 4: Button roles

• Render final button-based reaction-role messages.
• Handle button interactions.
• Implement single-select and multi-select logic.

Milestone 5: Reaction roles

• Render final reaction-based role messages.
• Add configured reactions after publishing.
• Handle reaction add/remove events.
• Implement single-select reaction cleanup.

Milestone 6: Management and polish

• Add /pingme list.
• Add /pingme delete.
• Add permission checks and clear error messages.
• Add validation for role hierarchy, duplicate emojis, and limits.
• Add README setup instructions.

Testing Plan

Manual test cases:

• Create a button-based multi-select role message.
• Create a button-based single-select role message.
• Create a reaction-based multi-select role message.
• Create a reaction-based single-select role message.
• Verify role hierarchy failures show helpful messages.
• Verify non-admins cannot create/delete configs.
• Verify deleting config disables future role assignment.
• Verify bot restart preserves published reaction-role messages.

Future Enhancements

• Edit existing reaction-role messages.
• Role removal policy options, e.g. buttons can be assign-only or toggle.
• Import/export configurations.
• Templates for common role menus.
• Web dashboard.
• Localization.