# Broccolini Bot – Commands Analysis

Analysis of slash commands and context menus: who can see/use them today, and how to restrict usage to the support role (@broccolini / `ROLE_ID_TO_PING`) only so customers cannot use them.

---

## Current permission model

Commands use **Discord permission bits** via `setDefaultMemberPermissions(...)`. Only users who have that permission (or Administrator) see the command in the slash menu. There is **no role-ID check** at registration time (Discord API does not support “visible only to role X”).

| Command | Registration permission | Handler: staff only? | Who can use today |
|--------|-------------------------|----------------------|--------------------|
| **Slash commands** | | | |
| `/escalate` | ManageMessages | Yes | Broccolini (staff role) only |
| `/deescalate` | ManageMessages | Yes | Broccolini only |
| `/add` | ManageMessages | Yes | Broccolini only |
| `/remove` | ManageMessages | Yes | Broccolini only |
| `/transfer` | ManageMessages | Yes (caller + target staff) | Broccolini only |
| `/move` | ManageChannels | Yes | Broccolini only |
| `/force-close` | ManageChannels | Yes | Broccolini only |
| `/topic` | ManageMessages | Yes | Broccolini only |
| `/tag` | ManageMessages | Yes | Broccolini only |
| `/response` | ManageMessages | Yes | Broccolini only |
| `/help` | **None** | **No** | **Everyone** |
| `/setup` | ManageChannels | Yes | Broccolini only |
| `/panel` | ManageChannels | Yes | Broccolini only |
| `/email-routing` | ManageGuild | Yes | Broccolini only |
| `/backup` | Administrator | Yes | Broccolini only |
| `/export` | Administrator | Yes | Broccolini only |
| `/priority` | ManageMessages | Yes | Broccolini only |
| `/search` | ManageMessages | Yes | Broccolini only |
| `/stats` | Administrator | Yes | Broccolini only |
| `/accountinfo` | ManageMessages | Yes | Broccolini only |
| **Context menus** | | | |
| Create Ticket From Message | ManageMessages | Yes | Broccolini only |
| View User Tickets | ManageMessages | Yes | Broccolini only |

---

## Role used for pinging

- **`ROLE_ID_TO_PING`** (env: `ROLE_ID_TO_PING`) – The “@broccolini” role ID used to ping support on new tickets, escalations, etc. Same as `ROLE_TO_PING_ID` in config (alias).
- **`ADDITIONAL_STAFF_ROLES`** – Optional comma-separated role IDs; members with any of these roles can also use staff-only commands (same as having `ROLE_ID_TO_PING`). `/transfer` also validates that the *target* user has the main staff role.

---

## Goal: “Support @broccolini @role to ping id only – I don’t want customers using them”

You want **all** bot commands to be usable **only** by users who have the support role (the one you ping, i.e. `ROLE_ID_TO_PING`), so customers cannot use them.

- **Ping role** = same role as today: `ROLE_ID_TO_PING` (e.g. @broccolini). No change to who gets pinged.
- **Who can run commands** = only members who have that role (and optionally `ADDITIONAL_STAFF_ROLES`). No permission-bit-only access.

Discord does **not** let you restrict slash commands by role ID in the registration. So the way to get “only this role can use” is:

1. **In the handler**: For every guild interaction, before running any command logic, check that the member has `ROLE_ID_TO_PING` (or one of `ADDITIONAL_STAFF_ROLES`). If not, reply ephemeral e.g. “This command is only available to the support team.” and do not run the command.
2. **Registration**: Leave as-is (or tighten for consistency). The role check in the handler is the real gate; permission bits only control who *sees* the command. If you want only staff to see commands, you’d give the support role a permission (e.g. Manage Messages) and set that on commands; the handler check still ensures only that role (and optional additional staff roles) can actually run them.

---

## Who can use what (current behavior)

- **Only `/help`** – Usable by everyone (no staff role required). Visible in guild and in DMs; in DMs there is no role check.
- **All other commands** (including `/topic` and `/priority`) – Broccolini-only. The handler requires the support role (`ROLE_ID_TO_PING` or `ADDITIONAL_STAFF_ROLES`) in guild; customers get an ephemeral “This command is only available to the support team.” and the command does not run.

Note: `/topic` and `/priority` use `ManageMessages` in registration, so they appear in the slash menu only for users with that permission (typically staff). The handler also enforces the staff role. Only `/help` has no default permission and is visible to everyone.

---

## Implementation (done)

- **`handlers/commands.js`**
  - **`hasStaffRole(member)`** – Returns true if the member has `ROLE_ID_TO_PING` or any `ADDITIONAL_STAFF_ROLES`.
  - **`requireStaffRole(interaction)`** – If the interaction is in a guild and the user is not staff, replies ephemeral with “This command is only available to the support team (@role).” and returns `true` (so the handler returns without running the command). If not in a guild (e.g. `/help` in DMs), or if no staff roles are configured, no block is applied.
  - **`handleCommand`** – Calls `requireStaffRole(interaction)` at the top **except for `/help`**; if it returns true, the handler returns immediately.
  - **`handleContextMenu`** – Same check at the top for “Create Ticket From Message” and “View User Tickets”.

- **Behavior**
  - **`/help`** – Can be used by everyone (no staff role required).
  - **All other slash commands** – In a guild, only users with the staff role (ROLE_ID_TO_PING or ADDITIONAL_STAFF_ROLES) can use them; others get an ephemeral message and the command does not run.
  - **Context menus** – Staff role required in guild.
  - In **DM** (e.g. `/help` in BotDM): No role check, so help and any other DM commands still work.
  - If **`ROLE_ID_TO_PING`** and **`ADDITIONAL_STAFF_ROLES`** are both unset, the check is skipped (backward compatible).