Serveurs, rôles & membres

Cette page couvre Guild (serveur), Category, Member et Role.

Guild

Représente un serveur BloumeChat. Instancié pour chaque serveur où le bot est présent, préchargé automatiquement dans client.guilds.cache lors du ready.

Propriétés

Propriété	Type	Description
id	string	publicId (Snowflake) du serveur.
name	string	Nom du serveur.
icon	string | null	URL de l'icône, null si absente.
ownerId	string	publicId du propriétaire. Résolu depuis la liste des membres (members.find(m => m.isOwner)) si l'API ne fournit pas de champ ownerId direct.
memberCount	number	Nombre approximatif de membres, 0 si non fourni par l'API.
roles	RoleManager	Manager de rôles scopé à ce serveur — voir RoleManager.
invites	InviteManager	(1.5.0+) Manager d'invitations scopé à ce serveur — voir InviteManager.
emojis	EmojiManager	(1.5.0+) Manager d'émojis scopé à ce serveur — voir EmojiManager.
members	MemberManager (getter)	Raccourci vers client.members (le manager de membres est global, pas scopé par serveur).
channels	Collection<string, Channel> (getter)	Filtre à la volée client.channels.cache sur c.serverId === this.id — reflète toujours l'état courant du cache global, pas un snapshot figé.

guild.channels est calculé, pas stocké

Chaque accès à guild.channels refiltre le cache global des salons. Si vous n'avez encore rien chargé via guild.fetchChannels() (ou client.channels.fetchForGuild()), cette Collection sera vide même si le serveur a des salons.

Gestion du serveur

setName(name: string): Promise<void>
edit(data: { name?: string; imageUrl?: string | null }): Promise<Guild>
leave(): Promise<void>
delete(): Promise<void>

setName() est un raccourci vers edit({ name }). edit() ne modifie que les champs fournis et met à jour l'instance locale (this.name/this.icon) avant de retourner this. leave() fait quitter le bot du serveur. delete() supprime définitivement le serveur — le bot doit en être le propriétaire, sinon la requête rejette en 403.

delete() est irréversible et réservé au propriétaire

Contrairement à leave() qui retire simplement le bot, delete() supprime le serveur pour tous ses membres. N'exposez jamais cette méthode derrière une simple commande texte sans confirmation forte.

TypeScript

await guild.setName("Mon Serveur 2.0");
await guild.edit({ imageUrl: "https://example.com/new-icon.png" });

JavaScript

await guild.setName("Mon Serveur 2.0");
await guild.edit({ imageUrl: "https://example.com/new-icon.png" });

Salons & catégories

fetchChannels(): Promise<Channel[]>
createChannel(options: {
  name: string; type: "TEXT" | "VOICE";
  categoryId?: string; isPrivate?: boolean;
  permissionOverwrites?: { id: string; type: "ROLE" | "MEMBER"; allow: bigint | string; deny: bigint | string }[];
}): Promise<Channel>

fetchCategories(): Promise<Category[]>
createCategory(name: string): Promise<Category>

fetchChannels() reconstruit la liste depuis /servers/:id/categories (il n'existe pas d'endpoint GET plat pour les salons — le SDK aplatit les catégories et les salons non catégorisés en interne). createChannel() accepte optionnellement un tableau permissionOverwrites appliqué séquentiellement après la création via channel.editPermissions().

TypeScript

import { PermissionFlags } from "bloumechat";

const channel = await guild.createChannel({
  name: "annonces",
  type: "TEXT",
  isPrivate: true,
  permissionOverwrites: [
    { id: guild.id, type: "ROLE", allow: 0n, deny: PermissionFlags.SEND_MESSAGES }, // @everyone en lecture seule
  ],
});

JavaScript

const { PermissionFlags } = require("bloumechat");

const channel = await guild.createChannel({
  name: "annonces",
  type: "TEXT",
  isPrivate: true,
  permissionOverwrites: [
    { id: guild.id, type: "ROLE", allow: 0n, deny: PermissionFlags.SEND_MESSAGES }, // @everyone en lecture seule
  ],
});

Membres

searchMembers(query: string): Promise<MemberSearchResultDTO[]>
fetchOwner(): Promise<Member>

searchMembers() fait une recherche par correspondance partielle sur le nom d'utilisateur (tableau vide si aucun résultat). fetchOwner() (4.2.0+) récupère l'objet Member du propriétaire du serveur — raccourci pour client.members.fetch(guild.id, guild.ownerId).

Bans

fetchBans(): Promise<BanDTO[]>
unbanMember(userId: string): Promise<void>

unbanMember() passe par le socket (server:unban) — lève BloumeChatAuthError si le socket n'est pas établi, et BloumeChatGatewayError si le serveur refuse (depuis 4.2.0 ; avant cela l'échec était silencieusement ignoré). Voir aussi Member.ban() pour bannir.

Rôles

fetchRoles(): Promise<Role[]>
createRole(options: { name: string; color?: string; permissions?: bigint | string; hoist?: boolean }): Promise<Role>
editRole(roleId: string, options: { name?: string; color?: string | null; permissions?: bigint | string; hoist?: boolean }): Promise<Role>
deleteRole(roleId: string): Promise<void>

Ces quatre méthodes existent à la fois sur Guild et sur guild.roles (RoleManager) — voir RoleManager pour la version manager, qui gère aussi la résolution (resolve()). fetchRoles() remplace intégralement le cache guild.roles.cache (le vide puis le repeuple) ; les trois autres méthodes le maintiennent à jour de façon incrémentale.

TypeScript

import { PermissionFlags } from "bloumechat";

const role = await guild.createRole({
  name: "Modérateur",
  color: "#e74c3c",
  hoist: true,
  permissions: PermissionFlags.KICK_MEMBERS | PermissionFlags.MANAGE_MESSAGES,
});

JavaScript

const { PermissionFlags } = require("bloumechat");

const role = await guild.createRole({
  name: "Modérateur",
  color: "#e74c3c",
  hoist: true,
  permissions: PermissionFlags.KICK_MEMBERS | PermissionFlags.MANAGE_MESSAGES,
});

Invitations

Depuis la 1.5.0 : guild.invites

Ces raccourcis délèguent maintenant à InviteManager (guild.invites), qui expose aussi cache et delete(code).

fetchInvites(): Promise<GuildInviteDTO[]>
createInvite(channelId: string, options?: { maxAge?: number; maxUses?: number }): Promise<GuildInviteDTO>

fetchInvites() récupère la liste complète des invitations actives du serveur (?all=true en interne). createInvite() requiert un channelId explicite (contrairement à channel.createInvite() qui l'infère de lui-même). Voir Invite.

Emojis

Depuis la 1.5.0 : guild.emojis

Ces raccourcis délèguent maintenant à EmojiManager (guild.emojis), qui expose aussi create() pour uploader un nouvel émoji.

fetchEmojis(): Promise<Emoji[]>
deleteEmoji(emojiId: string): Promise<void>

Voir Emoji.

Boosts, vanity URL, notifications, audit logs

boost(): Promise<void>
fetchVanityURL(): Promise<string | null>
markAsRead(): Promise<void>
setNotifications(settings: { muted?: boolean; muteUntil?: string | null; mentionsOnly?: boolean }): Promise<void>
fetchAuditLogs(options?: { limit?: number; action?: string }): Promise<AuditLogEntryDTO[]>

Méthode	Description
boost()	Applique un boost disponible du bot à ce serveur. Requiert que le bot dispose d'un crédit de boost — sinon la requête rejette.
fetchVanityURL()	Retourne le code d'URL personnalisée du serveur (fonctionnalité liée aux boosts), null si aucune n'est configurée.
markAsRead()	Marque tout le serveur comme lu pour le compte connecté.
setNotifications(settings)	Met à jour les préférences de notification (mute, mute jusqu'à une date, mentions uniquement).
fetchAuditLogs(options)	options.limit (défaut serveur si omis) et options.action (filtre par type d'action) sont tous deux optionnels.

TypeScript

const logs = await guild.fetchAuditLogs({ limit: 20, action: "MEMBER_BAN" });
for (const entry of logs) console.log(entry);

JavaScript

const logs = await guild.fetchAuditLogs({ limit: 20, action: "MEMBER_BAN" });
for (const entry of logs) console.log(entry);

Category

Regroupe des salons sous un même en-tête, avec ses propres overrides de permission hérités par les salons enfants (voir channel.syncPermissions()).

Propriétés

Propriété	Type	Description
id	string	publicId de la catégorie.
name	string	Nom de la catégorie.
position	number	Position d'affichage.
serverId	string	ID du serveur parent.
isPrivate	boolean	Visibilité restreinte ou non.
channels	Channel[]	Salons nichés dans cette catégorie, tels que reçus à la construction.

Méthodes

setName(name: string): Promise<void>
edit(data: { name?: string; isPrivate?: boolean }): Promise<void>
delete(): Promise<void>
syncPermissions(): Promise<void>
fetchPermissionOverrides(): Promise<PermissionOverrideDTO[]>

delete() ne supprime que la catégorie — les salons qu'elle contenait deviennent non catégorisés (ils ne sont pas supprimés). syncPermissions() propage les overrides de la catégorie vers tous ses salons enfants en une opération (à ne pas confondre avec channel.syncPermissions(), qui ne synchronise qu'un salon individuel).

TypeScript

const categories = await guild.fetchCategories();
const general = categories.find(c => c.name === "Général");
await general?.edit({ isPrivate: true });
await general?.syncPermissions(); // applique le nouvel override à tous les salons enfants

JavaScript

const categories = await guild.fetchCategories();
const general = categories.find(c => c.name === "Général");
if (general) {
  await general.edit({ isPrivate: true });
  await general.syncPermissions(); // applique le nouvel override à tous les salons enfants
}

Member

Un membre représente un utilisateur au sein d'un serveur donné — rôles, date d'arrivée, pseudo. Ne confondez pas member.id (identifiant de la membership, propre à ce couple utilisateur/serveur) avec member.user.id (identifiant de l'utilisateur, global).

Propriétés

Propriété	Type	Description
id	string	publicId de la membership (distinct de user.id).
user	User	Utilisateur sous-jacent.
serverId	string	ID du serveur.
roles	Array<MemberRoleRef | string>	Rôles attachés à ce membre — objets { id?, publicId?, permissions? }, ou parfois une simple chaîne d'ID (accepté par addRole/removeRole).
joinedAt	Date	Date d'arrivée sur le serveur.
permissions	bigint (getter)	Union des permissions de tous les rôles du membre (voir ci-dessous).

Le propriétaire a toutes les permissions

member.permissions retourne ALL_PERMISSIONS sans même regarder les rôles si guild.ownerId === member.user.id — cohérent avec le comportement serveur. Si le serveur correspondant n'est pas en cache (client.guilds.cache), le getter renvoie 0n par sécurité plutôt que de lever une erreur.

Le calcul agrège aussi le bypass ADMINISTRATOR : si l'union des rôles contient ce flag, permissions retourne directement ALL_PERMISSIONS — inutile de tester ADMINISTRATOR séparément après coup.

hasPermission(permission: bigint): boolean

Teste un flag unique ou une combinaison (FLAG_A | FLAG_B) contre this.permissions. Ne tient pas compte des overrides de salon/catégorie — pour une vérification exhaustive dans un salon donné, combinez avec applyChannelOverrides côté serveur ou consultez channel.fetchPermissionOverrides().

TypeScript

import { PermissionFlags } from "bloumechat";

if (member.hasPermission(PermissionFlags.KICK_MEMBERS)) {
  // autorisé à expulser
}

JavaScript

const { PermissionFlags } = require("bloumechat");

if (member.hasPermission(PermissionFlags.KICK_MEMBERS)) {
  // autorisé à expulser
}

Modération

kick(reason?: string): Promise<void>
ban(options?: { reason?: string; deleteHistory?: "none" | "1d" | "7d" | "14d" | "30d" }): Promise<void>

kick() retire le membre du serveur (il peut revenir avec une nouvelle invitation). ban() l'expulse et l'empêche de revenir tant que le ban n'est pas levé (guild.unbanMember()) ; deleteHistory supprime rétroactivement ses messages récents. Les deux passent par Socket.IO (server:kick/server:ban, aucune route REST) — voir l'encart d'avertissement sur la page Member pour le détail des erreurs.

TypeScript

await target.kick("Comportement inapproprié");
await target.ban({ reason: "Spam répété", deleteHistory: "7d" });

JavaScript

await target.kick("Comportement inapproprié");
await target.ban({ reason: "Spam répété", deleteHistory: "7d" });

Édition — rôles & pseudo

edit(data: { roles?: string[]; nickname?: string | null }): Promise<void>
setNickname(nickname: string | null): Promise<void>
addRole(roleId: string): Promise<void>
removeRole(roleId: string): Promise<void>

edit({ roles }) remplace la liste complète des rôles — utilisez addRole/removeRole pour une modification incrémentale sans risquer d'écraser les rôles existants. addRole/removeRole sont no-op (résolvent immédiatement sans appel réseau) si le rôle est déjà présent/absent respectivement.

TypeScript

await member.setNickname("Le Boss");
await member.addRole(moderatorRoleId);
await member.removeRole(newbieRoleId);

JavaScript

await member.setNickname("Le Boss");
await member.addRole(moderatorRoleId);
await member.removeRole(newbieRoleId);

Role

Propriétés

Propriété	Type	Description
id	string	publicId du rôle.
name	string	Nom du rôle.
color	string | null	Couleur hex, null si aucune.
hoist	boolean	Affiché séparément dans la liste des membres.
serverId	string	ID du serveur.
permissions	bigint	Bitmask de permissions accordées par ce rôle.
position	number	Position hiérarchique (plus haut = priorité plus élevée dans les conflits d'overrides).

Méthodes

hasPermission(permission: bigint): boolean
edit(data: { name?: string; color?: string | null; hoist?: boolean; permissions?: bigint | string }): Promise<void>
delete(): Promise<void>

hasPermission() applique le même bypass ADMINISTRATOR que Member.hasPermission() : si le rôle a ADMINISTRATOR, toute vérification retourne true sans inspecter le flag demandé. edit() ne modifie que les champs fournis et met à jour l'instance locale, y compris la reconversion de permissions en BigInt.

TypeScript

import { PermissionFlags } from "bloumechat";

const role = guild.roles.cache.find(r => r.name === "Modérateur");
await role?.edit({ permissions: role.permissions | PermissionFlags.MANAGE_MESSAGES });

JavaScript

const { PermissionFlags } = require("bloumechat");

const role = guild.roles.cache.find(r => r.name === "Modérateur");
if (role) {
  await role.edit({ permissions: role.permissions | PermissionFlags.MANAGE_MESSAGES });
}

Exemple : bot de modération minimal

TypeScript

client.on("messageCreate", async (message) => {
  if (!message.content.startsWith("!kick ") || !message.serverId) return;

  const modMember = message.member;
  if (!modMember?.hasPermission(PermissionFlags.KICK_MEMBERS)) {
    return message.reply("Permission refusée.");
  }

  const targetId = message.content.split(" ")[1];
  const target = await client.members.fetch(message.serverId, targetId);
  await target.kick("Expulsé via commande bot");
  await message.reply(`${target.user.username} a été expulsé.`);
});

JavaScript

client.on("messageCreate", async (message) => {
  if (!message.content.startsWith("!kick ") || !message.serverId) return;

  const modMember = message.member;
  if (!modMember || !modMember.hasPermission(PermissionFlags.KICK_MEMBERS)) {
    return message.reply("Permission refusée.");
  }

  const targetId = message.content.split(" ")[1];
  const target = await client.members.fetch(message.serverId, targetId);
  await target.kick("Expulsé via commande bot");
  await message.reply(`${target.user.username} a été expulsé.`);
});

Voir aussi

• Permissions (bitmask) — table complète des PermissionFlags et bonnes pratiques bitwise.
• RoleManager / MemberManager / GuildManager — caches et méthodes fetch.
• InviteManager / EmojiManager — guild.invites / guild.emojis (1.5.0+).
• Gestion des erreurs — BloumeChatAuthError, BloumeChatAPIError, etc.
• Messages & salons — Channel, overrides de permission par salon.
• Exemple : bot de modération — !kick/!ban/!warn avec journalisation.