Initial commit

2026-06-27 11:32:25 -05:00
commit 865ab2007b
18 changed files with 2926 additions and 0 deletions
@@ -0,0 +1,237 @@
+# 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:
+
+```text
+/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:
+
+```text
+/pingme create
+/pingme list
+/pingme delete message:<message_id>
+/pingme help
+```
+
+Later optional commands:
+
+```text
+/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.