Introduction

Le BloumeChat SDK (package npm bloumechat, actuellement en version 4.2.0) est la bibliothèque officielle pour créer des bots et des applications tierces sur BloumeChat. Il est développé et maintenu par l'équipe BloumeChat, et publié avec ses propres types TypeScript — aucun package @types/ séparé n'est nécessaire.

Il utilise une architecture moderne basée sur des événements (EventEmitter), un cache local par ressource et des structures de données orientées objet qui exposent directement les actions possibles (message.reply(), guild.createChannel(), member.kick()…), à la manière de bibliothèques comme discord.js.

Pourquoi ce SDK ?

• Entièrement typé. Chaque événement, chaque payload, chaque méthode a un type précis grâce à l'interface ClientEvents — votre éditeur vous guide, pas de data: any à deviner sur les events les plus courants (messageCreate, roleCreate…).
• Temps réel géré pour vous. La connexion Socket.IO, la reconnexion automatique (backoff progressif jusqu'à 30s, tentatives illimitées) et le mapping des événements internes bas niveau (message:new, server:member_update…) vers une API stable et documentée sont pris en charge par le client — vous n'avez jamais besoin de toucher au socket brut.
• Sécurisé par défaut. Le token de bot est stocké dans une propriété non énumérable : il n'apparaît jamais dans un console.log(client) ou un JSON.stringify(client) accidentel. Les appels API ont un timeout par défaut (15s), des retries automatiques avec backoff exponentiel sur erreur réseau ou statut 429/502/503/504, et une file d'attente limite la concurrence à 5 requêtes simultanées pour éviter de se faire rate-limiter ou bannir côté serveur.
• Complet. Salons et catégories, rôles avec permissions en bitmask BigInt, membres (kick/ban/rôles/pseudo), invitations, webhooks, emojis personnalisés, réactions, embeds riches, présence/activité (Rich Presence), messages directs — la quasi-totalité de l'API BloumeChat est couverte par des méthodes typées.

Architecture en un coup d'œil

BloumeChat (client)
├── user       — User | null (le bot lui-même, peuplé après `ready`)
├── users      — UserManager      → cache de User
├── guilds     — GuildManager     → cache de Guild
│                  └── roles      — RoleManager (par serveur, sur chaque Guild)
├── channels   — ChannelManager   → cache de Channel / DMChannel
└── members    — MemberManager    → cache de Member

Chaque manager (UserManager, GuildManager, ChannelManager, MemberManager, RoleManager) expose des méthodes fetch() / fetchAll() qui interrogent l'API REST et peuplent un cache — une Collection, une Map enrichie de méthodes utilitaires (find, filter, map, sorted…). Chaque structure (User, Message, Guild, Channel, Member, Role…) porte directement ses propres méthodes d'action, pour éviter d'avoir à repasser par un manager pour la moindre opération.

Un seul client, plusieurs caches

Vous n'instanciez qu'un seul BloumeChat. Tous les managers (client.users, client.guilds, client.channels, client.members) partagent la même instance et se synchronisent automatiquement via les événements WebSocket — vous n'avez normalement jamais besoin de rafraîchir un cache manuellement en cours de fonctionnement.

Où trouver quoi

• Installation — installer le package et créer un bot.
• Démarrage rapide — un premier bot qui répond aux messages, en TypeScript et en JavaScript.
• Utiliser le SDK en JavaScript — CommonJS vs ESM, autocomplétion sans TypeScript.
• Événements — la liste complète des events et leurs payloads typés.
• Permissions — le système de bitmask BigInt pour les rôles.
• Référence API — la documentation exhaustive de chaque classe (client, managers, structures, utilitaires).

Ce que le SDK n'est pas

• Ce n'est pas un client utilisateur. Le SDK est conçu pour des comptes de type bot (isBot: true, authentifiés par token). Il ne remplace pas l'interface web/mobile BloumeChat pour un compte personnel.
• Un bot ne peut pas rejoindre un serveur seul. Il n'y a pas de méthode guild.join() — voir l'encadré ci-dessous.

Un bot ne peut pas rejoindre un serveur seul

Un bot n'a pas de bouton « join » : il doit être ajouté par un utilisateur disposant de la permission nécessaire sur le serveur (via le portail développeurs BloumeChat). Le SDK permet en revanche d'inspecter une invitation en lecture seule (client.fetchInvite(code)) et de la révoquer si le bot a la permission MANAGE_INVITES sur le serveur concerné. Écoutez l'événement guildCreate pour réagir dès que le bot est ajouté.

• Un bot n'a pas accès aux notifications personnelles du compte. Il n'existe pas de méthode pour lire les mentions, demandes d'ami ou invitations en attente d'un utilisateur — cette information est personnelle, pas une ressource de bot. Pour réagir à une mention, écoutez messageCreate et inspectez message.mentions directement.

Prochaine étape

Passez à la page Installation pour ajouter le package à votre projet et obtenir un token de bot.