# 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.