Implement role sync API endpoint using existing role mapping system

[Copilot]

Implementation Plan for Role Sync with Whitelist

• Create a whitelist configuration file
• Implement the POST /api/v1/role/:id endpoint in role.controller.ts to:
  • Accept a body parameter for roles to add/remove
  • Validate roles against the whitelist configuration
  • Add roles to user if add: true is in the body
  • Remove roles from user if add: false is in the body
  • Return appropriate error messages for invalid roles or unauthorized operations
• Add utility function to load and validate role whitelist
• Create documentation for the API endpoint in swagger.json
• Create comprehensive usage documentation in API_ROLE_SYNC.md
• Pass code review with no issues
• Pass security scan (CodeQL) with no vulnerabilities
• Refactored to use existing role mapping system
• Use client.roles instead of calling loadRoles()
• Fix swagger documentation path parameters and examples

Summary

Fixed swagger documentation to correctly reflect the API implementation.

Key Changes (Latest Update):

• Path Parameter: Changed GET endpoint path from /api/v1/role to /api/v1/role/{id} to match controller implementation
• Parameter Location: Changed id parameter from "query" to "path" for GET endpoint
• Updated Examples: Changed role key examples from "buildteam_owner" to "TEAM_OWNER" for consistency
• Removed explode: Removed unnecessary "explode" property from path parameter definition

Swagger Documentation Now Correctly Shows:

• GET /api/v1/role/{id} - Get user's roles (path parameter)
• POST /api/v1/role/{id} - Add/remove roles (path parameter)
• Consistent role key examples: "TEAM_OWNER" instead of "buildteam_owner"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Implement Role Sync</issue_title>
<issue_description>Is your feature request related to a problem? Please describe.
We are currently already storing all BuildTeam Owners, BuildTeam Staff, BTE Staff in the Website DB. It would reduce the amount of manual work to automatically sync Discord and Website roles based on some config maps to the Staff DC and Main DC.

Ideally, this would probably work in a "push" system, where the Website API calls an internal API route on the Bot, which then sets the roles similarly how the DM API works. That way the core logic would need to be implemented in web/api and not here.

Describe alternatives you've considered
Another way could be that the bot perodically fetches the API or DB and then updates users. But this is inefficient as fck.
</issue_description>

<agent_instructions>Please implement the role path to also have option to add roles, the roles that can be added should be controlled by a whitelist config file</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@XboxBedrock So are you asking for the role change api to be accessible to the website? @XboxBedrock Such an api already exists, I will just have to make some small modifications @Nudelsuppe42 💀 yes @Nudelsuppe42 I mean https://github.com/BuildTheEarth/main-bot/blob/main/src/struct/web/methods/api/role.controller.ts#L62 is not implemented xD @XboxBedrock Right... I thought it was for some reason. I'll implement it as soon as I fix the memory leak issue.

In the meantime, let me screw around and see what garbage Copilot comes up with!</comment_new>

• Fixes Implement Role Sync #376

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Nudelsuppe42]

@copilot please change the way the whitelist works:
Instead of passing actual role ids to the API from the caller, they should pass a key, which is then looked up in the whitelist and referenced to BOTH a role id for the staff discord and a role id for the main discord.
Please also support one of them beeing undefined, so the bot would then only set the role on the server where it has a role id

[Copilot]

@copilot please change the way the whitelist works:
Instead of passing actual role ids to the API from the caller, they should pass a key, which is then looked up in the whitelist and referenced to B...

Changed to key-based whitelist system. The API now accepts role keys (e.g., "buildteam_owner") instead of role IDs. Each key maps to both main and staff Discord role IDs in the config, and either can be undefined. The bot applies roles to both servers where configured. Commit: 55834d6

[XboxBedrock]

Hey @copilot , I already have a system for for role handling.

main-bot/src/util/roles.util.ts

Line 15 in 7bfb189

export function loadRoles(client: Client): Record<string, string[]> {

You can also look around and you will find JSON5 files in config that already do role mapping, with the guild ID as the file name. I would much rather you work with these than create your own mapping.

[Copilot]

Hey @copilot , I already have a system for for role handling.

main-bot/src/util/roles.util.ts

Line 15 in 7bfb189

export function loadRoles(client: Client): Record<string, string[]> {

You can also look arou...

Refactored to use the existing loadRoles() utility and role mapping files. The whitelist now just contains role keys, and role IDs are looked up from config/extensions/roles/{guildId}.json5 files at runtime. Commit: c8a5905

[XboxBedrock]

Can you rebase to current code version

[XboxBedrock]

@copilot Can you rebase to current code version, also one thing you should know is that the code already loads the roles, so you can just use those from the array. The array of roles is in client

[Copilot]

@copilot Can you rebase to current code version, also one thing you should know is that the code already loads the roles, so you can just use those from the array. The array of roles is in client

Branch is already up to date with the base code. Updated to use globalThis.client.roles (which is populated at startup) instead of calling loadRoles() to avoid redundant file I/O. Commit: 46a88cc

[XboxBedrock]

@XboxBedrock Reminder to go through, edit this, and then merge tmrw

[XboxBedrock]

@copilot add swagger documentation

[Copilot]

@copilot add swagger documentation

Swagger documentation was already added in commit 793ae21. Updated it to fix path parameter specification (changed from query to path for GET endpoint) and updated role key examples from "buildteam_owner" to "TEAM_OWNER". Commit: 75b886b