ceejay.roles

Every function takes the same last argument, options: signal, timeoutMs and maxRetries, for that one call. A write also takes idempotencyKey there. Every function can also raise the errors any request can raise, such as a bad key or the rate limit. See Errors and retries.

Which roles can be changed

Only an ordinary role of your own server. CEEJAY refuses, with the code role_not_allowed:

• the @everyone role;
• a role that Discord or another app manages, such as a bot's own role;
• a role that can moderate or manage the server;
• a role that can mention everyone, in a server whose @everyone role cannot. Where @everyone can, every member already has that permission, the role adds nothing, and it is not refused;
• a bot master role: a role your community added under Settings → General → Team Management, whose members have full access to the CEEJAY dashboard, whatever its Discord permissions are.

ceejay.roles.list shows for every role whether it can be changed, and the reason if it cannot.

The CEEJAY bot needs Manage Roles, and its own role must sit above the role you change in Server Settings → Roles.

All three requests go through Discord, which has its own rate limit. Do not retry them in a tight loop.

ceejay.roles.list

Lists your server's roles, highest first, without @everyone, and shows for each one whether ceejay.roles.grant and ceejay.roles.revoke accept it.

GET /v1/roles · requires roles:manage · API reference: List roles

Retried by the SDK: Yes. It is a read

Parameters: options only.

Returns the full response, typed as Schemas['ListRolesResponse']. The roles are in data, and the pagination details are in page.

Each role, typed as Schemas['Role']:

notGrantableReason is one of five values:

above_bot is reported when CEEJAY could read the bot's own role. When it could not, the role reads as grantable and Discord may still refuse it. A role that moderates only through the settings of single channels cannot be seen from the list either.

CEEJAY reads the list from Discord and caches it for up to a minute. The response never includes a role's permissions or which members have it.

Errors

A list that could not be read is an error, never an empty list.

Example

const roles = await ceejay.roles.list()

for (const role of roles.data) {
  console.log(role.roleId, role.name, role.grantable ? 'can be given' : `not given: ${role.notGrantableReason}`)
}

ceejay.roles.grant

Assigns a Discord role to a member. A member who already has it is not an error.

POST /v1/roles/grant · requires roles:manage · API reference: Grant a role

Retried by the SDK: Only with idempotencyKey

Parameters: one object, then options.

Options

Returns Schemas['GrantRoleResult'].

Errors

Any other status that Discord returns is passed on with the code discord_error. The message is then Discord API error: followed by that status, and error.body includes Discord's own response in details. Idempotency errors are covered in Errors and retries.

Example

import { CeejayError } from '@communitystudios/ceejay'

try {
  const result = await ceejay.roles.grant({
    discordId: '409876543210987654',
    roleId: '718230049827100399',
  })
  console.log(result.action)
} catch (error) {
  if (error instanceof CeejayError && error.code === 'role_not_allowed') {
    console.log('The API never gives this role. Choose another one.')
  } else {
    throw error
  }
}

ceejay.roles.revoke

Revokes a Discord role from a member. A member who does not have it is not an error.

POST /v1/roles/revoke · requires roles:manage · API reference: Revoke a role

Retried by the SDK: Only with idempotencyKey

Parameters: one object, then options.

Options

Returns Schemas['RevokeRoleResult'].

Errors

Any other status that Discord returns is passed on with the code discord_error, as for ceejay.roles.grant.

Example

const result = await ceejay.roles.revoke({
  discordId: '409876543210987654',
  roleId: '718230049827100399',
})

console.log(result.action)