Temp Roles — Timed Role Assignments

GrumpyTempRoles grants a role for a fixed duration — once it expires, it's automatically removed again. Independent of the Tempban system (/mod tempban), meant for anything that should be time-limited: event access, probation roles, temporary boosts, penalties short of a full timeout.

---

Example Scenario (Step by Step)

Sven is running a weekend event and wants every participant to get a special @Event-Guest role for the duration — one that disappears on its own afterward, without him having to remember to remove it manually on Monday.

1. Create the @Event-Guest role on the server (normal Discord server settings, not a bot step).
2. For each participant:

   /temprole add user:@Jonas role:@Event-Guest duration:2d
   

   → Jonas gets the role immediately, and the bot remembers: "remove again in 2 days".
3. Check in between who currently has the role and how much time is left:

   /temprole list
   

   → shows e.g. @Jonas — @Event-Guest · 1d 4h left
4. Event ends earlier than planned? Remove the role immediately instead of waiting for it to expire:

   /temprole remove user:@Jonas role:@Event-Guest
   

5. Otherwise: do nothing else. After 2 days the bot removes the role automatically — within a minute of expiry at the latest, even if the bot was restarted in between.

---

Activation

In configs/config.yml:

addons:
  temproles: true

There's no dedicated temproles.yml — the module has no settings, just the on/off toggle.

---

Commands

/temprole add <user> <role> <duration> [reason]

Grants a role temporarily. If the member already has the role, it isn't granted again — only the expiry is set.

Option	Description
user	Target member
role	Role to grant
duration	Duration, e.g. 2h, 1d, 30m, 1h30m (same format as /mod tempban, /xp boost)
reason	Optional reason (max 300 characters)

/temprole add user:@Jonas role:@Event-Guest duration:1d
/temprole add user:@Jonas role:@Probation duration:7d reason:"New team member"

Extending: Running /temprole add again for the same user+role combination extends the existing assignment (the new expiry and reason overwrite the old ones) — no duplicate entry is created.

Permission: Manage Roles

---

/temprole list [user]

Shows all active temporary role assignments, optionally filtered to one member.

/temprole list
/temprole list user:@Jonas

Each line shows the member, the role, and the remaining time (e.g. 3h 12m left).

Permission: Manage Roles

---

/temprole remove <user> <role>

Removes a temporary role immediately, instead of waiting for it to expire.

/temprole remove user:@Jonas role:@Event-Guest

Permission: Manage Roles

---

How Automatic Removal Works

A runner checks every minute which temp roles have expired (expiresAt in the past) — including an immediate check right at bot startup, so roles that expired during downtime aren't noticed up to a full minute late.

Minute tick
  ├─ Find expired entries
  ├─ Claim each entry individually (prevents double-processing from two
  │    overlapping ticks — e.g. if one tick takes longer than a minute
  │    due to many expired roles)
  ├─ Member still in the server? → Remove the role
  │    ├─ Success → done
  │    └─ Failure (rate-limit, missing permission) → revert the claim,
  │         next tick retries
  └─ Member gone / role already removed manually → nothing to do

This pattern is identical to the existing Tempban auto-unban (/mod tempban) — proven, robust against overlapping ticks and transient Discord API errors.

---

Deliberate Limits

• No role hierarchy bypass: the bot can only grant roles that sit below its own highest role, and never roles managed by Discord/integrations (e.g. the boost role, other bots' own roles).
• No @everyone role — doesn't make sense and is rejected.
• No dedicated log — unlike the Tempban system, automatic removal doesn't (yet) post to a log channel, only an internal console log line. /temprole list is the source of truth for currently active assignments.

---

Permissions

Command	Permission
/temprole add	Manage Roles
/temprole list	Manage Roles
/temprole remove	Manage Roles

Discord-side default via setDefaultMemberPermissions — server admins can override this per role/channel in the server's Integrations settings. All commands are guild-only (no DM context).