fivelive.js 0.2.0

package/README.md

@@ -0,0 +1,181 @@
+# fivelive.js
+
+SDK oficial para criar bots do **Five Live**. Você recebe as mensagens em tempo real e responde, reage, manda embeds e cria comandos, do mesmo jeito que no discord.js.
+
+```js
+import { Client } from "fivelive.js";
+
+const client = new Client({ token: process.env.FIVELIVE_TOKEN });
+
+client.on("ready", (bot) => console.log(`Online como ${bot.displayName}`));
+
+client.command({
+  name: "ping",
+  run: ({ reply }) => reply("🏓 pong!"),
+});
+
+client.login();
+```
+
+## Começando
+
+1. Crie o bot em **https://live.fivenetwork.dev/developers** e copie o **token** (começa com `b_`). Guarde bem: ele é a senha do bot.
+2. Adicione o bot a um grupo pelo link **"Adicionar a um grupo"** na página dele.
+3. Instale e rode:
+
+```bash
+npm install fivelive.js
+FIVELIVE_TOKEN=b_seu_token node bot.mjs
+```
+
+É preciso o Node 18 ou mais novo. No Node 22 ou mais novo não precisa de mais nada; no 18 e no 20 o pacote `ws` é instalado junto.
+
+## Eventos
+
+```js
+client.on("messageCreate", async (message) => {
+  if (message.content === "oi") await message.reply(`Oi, ${message.author}!`);
+});
+```
+
+| Evento | Recebe |
+|---|---|
+| `ready` | o usuário do bot, depois de conectar e carregar os grupos |
+| `messageCreate` | `Message` nova (as do próprio bot não chegam; as de outros bots só com `ignoreBots: false`) |
+| `messageUpdate` | `Message` editada |
+| `messageDelete` | `{ id, groupId, channelId }` |
+| `reactionUpdate` | `{ messageId, groupId, channelId, reactions }` |
+| `typingStart` | `{ userId, name, groupId, channelId }` |
+| `memberAdd` | `{ user, group, groupId, via }`, quando alguém entra num grupo do bot |
+| `memberRemove` | `{ userId, user, group, groupId, reason, by }` — reason: `left`, `kicked` ou `banned` |
+| `groupJoin` | `Group`, quando adicionam o bot a um grupo |
+| `groupLeave` | `{ id, reason }`, quando o bot sai, é expulso ou o grupo é apagado |
+| `groupUpdate` | `Group`, quando o grupo muda (nome, salas, cargos) |
+| `reconnecting` / `reconnected` / `disconnect` | a conexão caiu e voltou sozinha |
+| `error` | `Error` |
+| `commandError` | `(error, context)`, quando um comando lança um erro |
+
+## Comandos
+
+```js
+const client = new Client({ token, prefix: "!" });
+
+client.command({
+  name: "dado",
+  aliases: ["d"],
+  description: "Rola um dado: !dado 20",
+  run: async ({ args, message, reply }) => {
+    const lados = Number(args[0]) || 6;
+    await message.channel.sendTyping();
+    await reply(`🎲 ${1 + Math.floor(Math.random() * lados)}`);
+  },
+});
+```
+
+## Mensagens
+
+```js
+await message.reply("resposta citando a mensagem");
+await message.channel.send("mensagem normal");
+await message.react("👍");
+await message.unreact("👍");
+
+const minha = await message.channel.send("vou editar");
+await minha.edit("editada");
+await minha.delete();          // só as mensagens do próprio bot
+
+message.content                // o texto como está gravado, com as menções como <@id>
+message.cleanContent           // com as menções trocadas por @nome
+message.author                 // User: id, username, displayName, avatarURL, bot
+message.mentions               // { users: [...ids], roles: [...ids], everyone }
+message.mentionsMe             // se mencionou o bot
+message.group / message.channel
+```
+
+### Menções
+
+```js
+import { userMention } from "fivelive.js";
+
+await channel.send(`Bem-vindo, ${userMention(id)}!`);        // ou `${message.author}`
+await channel.send({ content: "Atenção, mods", roleMentions: [roleId] });
+await channel.send({ content: "Todo mundo!", everyone: true });  // precisa da permissão
+```
+
+A menção avisa a pessoa, igual a uma menção feita por alguém do grupo. As permissões do cargo do bot valem normalmente ("Mencionar membros", "Mencionar @everyone", cargo mencionável).
+
+### Embeds
+
+```js
+import { EmbedBuilder } from "fivelive.js";
+
+const embed = new EmbedBuilder()
+  .setTitle("Placar")
+  .setDescription("Resultado da rodada")
+  .setColor("#3b6cf6")
+  .setAuthor({ name: "Five Bot", iconURL: "https://..." })
+  .addFields(
+    { name: "Time A", value: "3", inline: true },
+    { name: "Time B", value: "1", inline: true },
+  )
+  .setImage("https://...")
+  .setFooter({ text: "Five Live" })
+  .setTimestamp();
+
+await message.channel.send({ content: "Fim de jogo!", embeds: [embed] });
+```
+
+## Grupos, salas e membros
+
+```js
+for (const group of client.groups.values()) {
+  console.log(group.name, [...group.channels.values()].map((c) => c.name));
+}
+
+const geral = client.groups.get(groupId).channel("geral");   // pelo id ou pelo nome
+await geral.send("Bom dia!");
+
+const historico = await geral.fetchMessages({ limit: 20 });
+const membros = await group.fetchMembers();                   // com roleIds, owner e online
+const pessoa = await client.fetchUser(userId);
+```
+
+## Moderação
+
+Tudo respeita as permissões do cargo do bot e a hierarquia: ele só age em quem está abaixo do cargo mais alto dele.
+
+```js
+if (group.can("kickMembers")) await group.kick(userId);
+await group.ban(userId, "flood");          // banMembers
+await group.unban(userId);
+const banidos = await group.fetchBans();
+await group.addRole(userId, roleId);       // manageRoles
+await group.removeRole(userId, roleId);
+await message.pin();                        // manageMessages
+await message.delete();                     // de outras pessoas: manageMessages
+await group.leave();
+```
+
+## Limites
+
+- **60 mensagens por minuto** por bot. Passando disso, o SDK espera o tempo que a API pede e tenta de novo sozinho.
+- Texto de até **2000** caracteres e até **10 embeds** por mensagem.
+- O bot só vê os grupos em que foi adicionado, e só as salas de texto.
+
+## Erros
+
+Uma chamada recusada pela API lança `FiveLiveAPIError`, com `status`, `method` e `path`:
+
+```js
+import { FiveLiveAPIError } from "fivelive.js";
+
+try {
+  await message.delete();
+} catch (err) {
+  if (err instanceof FiveLiveAPIError && err.status === 403) console.log("Não posso apagar essa.");
+}
+```
+
+## Sem o SDK
+
+A API por trás é HTTP + WebSocket e pode ser usada de qualquer linguagem. A documentação está em https://live.fivenetwork.dev/developers.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "fivelive.js",
+  "version": "0.2.0",
+  "description": "SDK oficial para criar bots do Five Live — eventos em tempo real, mensagens, embeds, reações e comandos.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "fivelive",
+    "bot",
+    "sdk",
+    "chat"
+  ],
+  "license": "MIT",
+  "homepage": "https://live.fivenetwork.dev/developers"
+}

package/src/client.js

@@ -0,0 +1,289 @@
+// O Client: conecta no WebSocket do Five Live com o token do bot, mantém a
+// conexão viva (e reconecta sozinho), transforma os avisos da API em eventos
+// e guarda grupos e usuários conhecidos.
+//
+// Eventos:
+//   ready(user)                     conectou e carregou os grupos
+//   messageCreate(message)          mensagem nova num grupo do bot
+//   messageUpdate(message)          mensagem editada
+//   messageDelete({ id, groupId, channelId })
+//   reactionUpdate({ messageId, groupId, channelId, reactions })
+//   typingStart({ userId, name, groupId, channelId })
+//   groupJoin(group) / groupLeave({ id, reason }) / groupUpdate(group)
+//   reconnecting(attempt) / reconnected() / disconnect() / error(err)
+//   commandError(err, context)
+
+import { EventEmitter } from "node:events";
+import { REST } from "./rest.js";
+import { Group, Message, User } from "./structures.js";
+
+const DEFAULT_API = "https://api.fivenetwork.dev";
+const KEEPALIVE_MS = 30_000;
+const MAX_BACKOFF_MS = 30_000;
+
+async function socketClass() {
+  if (typeof globalThis.WebSocket === "function") return globalThis.WebSocket;
+  try {
+    const mod = await import("ws");
+    return mod.default ?? mod.WebSocket;
+  } catch {
+    throw new Error("Este Node não tem WebSocket nativo (é do Node 22+). Rode `npm install ws` ou atualize o Node.");
+  }
+}
+
+export class Client extends EventEmitter {
+  /**
+   * @param {{
+   *   token: string,
+   *   apiUrl?: string,
+   *   gatewayUrl?: string,
+   *   prefix?: string,
+   *   ignoreBots?: boolean,
+   * }} options
+   */
+  constructor(options) {
+    super();
+    if (!options?.token || !String(options.token).startsWith("b_")) {
+      throw new Error("Passe o token do bot (começa com b_). Pegue em https://live.fivenetwork.dev/developers.");
+    }
+    this.token = options.token;
+    this.apiUrl = (options.apiUrl ?? DEFAULT_API).replace(/\/$/, "");
+    this.gatewayUrl = options.gatewayUrl ?? `${this.apiUrl.replace(/^http/, "ws")}/ws`;
+    this.prefix = options.prefix ?? "!";
+    this.ignoreBots = options.ignoreBots ?? true;
+    this.rest = new REST({ token: this.token, apiUrl: this.apiUrl });
+    /** @type {User | null} */
+    this.user = null;
+    /** @type {Map<string, Group>} */
+    this.groups = new Map();
+    /** @type {Map<string, User>} */
+    this.users = new Map();
+    /** @type {Map<string, { name: string, description?: string, aliases?: string[], run: Function }>} */
+    this.commands = new Map();
+    this._ws = null;
+    this._ready = false;
+    this._closing = false;
+    this._attempt = 0;
+    this._keepalive = null;
+  }
+
+  // ─── Comandos com prefixo ─────────────────────────────────────────────────
+
+  /**
+   * Registra um comando: `!nome arg1 arg2`.
+   * @param {{ name: string, description?: string, aliases?: string[], run: (ctx: { message: Message, args: string[], client: Client, reply: (content: any) => Promise<Message> }) => any }} command
+   */
+  command(command) {
+    this.commands.set(command.name.toLowerCase(), command);
+    for (const alias of command.aliases ?? []) this.commands.set(alias.toLowerCase(), command);
+    return this;
+  }
+
+  /** @param {Message} message */
+  async _runCommand(message) {
+    if (!this.commands.size || !message.content.startsWith(this.prefix)) return;
+    const [name, ...args] = message.content.slice(this.prefix.length).trim().split(/\s+/);
+    const command = this.commands.get((name ?? "").toLowerCase());
+    if (!command) return;
+    const context = { message, args, client: this, reply: (content) => message.reply(content) };
+    try {
+      await command.run(context);
+    } catch (err) {
+      if (this.listenerCount("commandError")) this.emit("commandError", err, context);
+      else this.emit("error", err);
+    }
+  }
+
+  // ─── Conexão ──────────────────────────────────────────────────────────────
+
+  /** Conecta. Resolve quando o bot estiver pronto (evento "ready"). */
+  async login() {
+    const me = await this.rest.get("/bot/@me");
+    this.user = this._cacheUser({ ...me.bot, bot: true });
+    await this._loadGroups();
+    this._closing = false;
+    await this._connect();
+    return this.user;
+  }
+
+  /** Desconecta de vez (sem reconectar). */
+  destroy() {
+    this._closing = true;
+    clearInterval(this._keepalive);
+    try {
+      this._ws?.close();
+    } catch {
+      // já fechado
+    }
+  }
+
+  async _loadGroups() {
+    const data = await this.rest.get("/bot/groups");
+    const seen = new Set();
+    for (const raw of data.groups) {
+      seen.add(raw.id);
+      const held = this.groups.get(raw.id);
+      if (held) held._patch(raw);
+      else this.groups.set(raw.id, new Group(this, raw));
+    }
+    for (const id of [...this.groups.keys()]) if (!seen.has(id)) this.groups.delete(id);
+  }
+
+  /** Um grupo, relido da API. @param {string} id */
+  async fetchGroup(id) {
+    const data = await this.rest.get(`/bot/groups/${encodeURIComponent(id)}`);
+    const held = this.groups.get(id);
+    if (held) held._patch(data.group);
+    else this.groups.set(id, new Group(this, data.group));
+    return this.groups.get(id);
+  }
+
+  /** Uma pessoa pelo id. @param {string} id */
+  async fetchUser(id) {
+    const data = await this.rest.get(`/bot/users/${encodeURIComponent(id)}`);
+    return this._cacheUser(data.user);
+  }
+
+  /** @param {Record<string, any>} data */
+  _cacheUser(data) {
+    const user = new User(this, data);
+    this.users.set(user.id, user);
+    return user;
+  }
+
+  async _connect() {
+    const Socket = await socketClass();
+    return new Promise((resolve, reject) => {
+      const ws = new Socket(this.gatewayUrl);
+      this._ws = ws;
+      let settled = false;
+      const send = (payload) => {
+        if (ws.readyState === 1) ws.send(JSON.stringify(payload));
+      };
+      ws.onopen = () => {
+        send({ type: "register", name: this.user.displayName || this.user.username, token: this.token });
+        clearInterval(this._keepalive);
+        // O proxy da hospedagem derruba conexão parada: uma mensagem leve de tempos em tempos.
+        this._keepalive = setInterval(() => send({ type: "time-sync", t0: Date.now() }), KEEPALIVE_MS);
+      };
+      ws.onmessage = (event) => {
+        let msg;
+        try {
+          msg = JSON.parse(typeof event.data === "string" ? event.data : event.data.toString());
+        } catch {
+          return;
+        }
+        if (msg.type === "registered") {
+          const first = !this._ready;
+          this._ready = true;
+          this._attempt = 0;
+          if (!settled) {
+            settled = true;
+            resolve();
+          }
+          if (first) this.emit("ready", this.user);
+          else this.emit("reconnected");
+          return;
+        }
+        if (msg.type === "register-error") {
+          this._closing = true;
+          const err = new Error(msg.message || "O Five Live recusou o token do bot.");
+          if (!settled) {
+            settled = true;
+            reject(err);
+          } else this.emit("error", err);
+          return;
+        }
+        this._dispatch(msg).catch((err) => this.emit("error", err));
+      };
+      ws.onerror = (event) => {
+        if (!settled && this._attempt === 0 && !this._ready) {
+          settled = true;
+          reject(new Error(`Não foi possível conectar em ${this.gatewayUrl}: ${event?.message ?? "erro de rede"}`));
+        }
+      };
+      ws.onclose = () => {
+        clearInterval(this._keepalive);
+        this.emit("disconnect");
+        if (this._closing || !this._ready) return;
+        this._reconnect();
+      };
+    });
+  }
+
+  _reconnect() {
+    this._attempt += 1;
+    const delay = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** Math.min(this._attempt - 1, 5)) + Math.random() * 500;
+    this.emit("reconnecting", this._attempt);
+    setTimeout(async () => {
+      if (this._closing) return;
+      try {
+        // O que mudou enquanto estava fora (grupos que entrou/saiu).
+        await this._loadGroups();
+        await this._connect();
+      } catch {
+        this._reconnect();
+      }
+    }, delay);
+  }
+
+  /** @param {Record<string, any>} msg */
+  async _dispatch(msg) {
+    switch (msg.type) {
+      case "group-message": {
+        if (!msg.message) return;
+        const message = new Message(this, msg.message, msg.author ? { ...msg.author } : undefined);
+        if (message.author.id === this.user?.id) return;
+        if (this.ignoreBots && message.author.bot) return;
+        this.emit("messageCreate", message);
+        await this._runCommand(message);
+        return;
+      }
+      case "group-message-updated":
+        if (msg.message) this.emit("messageUpdate", new Message(this, msg.message));
+        return;
+      case "group-message-deleted":
+        this.emit("messageDelete", { id: msg.messageId, groupId: msg.groupId, channelId: msg.channelId });
+        return;
+      case "group-message-reactions":
+        this.emit("reactionUpdate", { messageId: msg.messageId, groupId: msg.groupId, channelId: msg.channelId, reactions: msg.reactions ?? [] });
+        return;
+      case "group-typing":
+        if (msg.userId !== this.user?.id && msg.typing !== false) {
+          this.emit("typingStart", { userId: msg.userId, name: msg.name, groupId: msg.groupId, channelId: msg.channelId });
+        }
+        return;
+      case "group-joined": {
+        const group = await this.fetchGroup(msg.groupId);
+        this.emit("groupJoin", group);
+        return;
+      }
+      case "group-updated": {
+        if (!this.groups.has(msg.groupId)) return;
+        const group = await this.fetchGroup(msg.groupId).catch(() => null);
+        if (group) this.emit("groupUpdate", group);
+        return;
+      }
+      case "group-member-add": {
+        if (!msg.member) return;
+        const user = this._cacheUser(msg.member);
+        const group = this.groups.get(msg.groupId) ?? (await this.fetchGroup(msg.groupId).catch(() => null));
+        if (group) group.memberCount += 1;
+        this.emit("memberAdd", { user, group, groupId: msg.groupId, via: msg.via ?? null });
+        return;
+      }
+      case "group-member-remove": {
+        const group = this.groups.get(msg.groupId) ?? null;
+        if (group) group.memberCount = Math.max(0, group.memberCount - 1);
+        this.emit("memberRemove", { userId: msg.userId, user: this.users.get(msg.userId) ?? null, group, groupId: msg.groupId, reason: msg.reason ?? null, by: msg.by ?? null });
+        return;
+      }
+      case "group-removed":
+        this.groups.delete(msg.groupId);
+        this.emit("groupLeave", { id: msg.groupId, reason: msg.reason ?? null });
+        return;
+      default:
+        this.emit("raw", msg);
+    }
+  }
+}

package/src/embed.js

@@ -0,0 +1,65 @@
+// Construtor de embeds no mesmo formato do discord.js (e do webhook do Five
+// Live): título, descrição, cor, autor, campos, imagem, miniatura, rodapé.
+
+/** @param {string | number} color */
+function toColor(color) {
+  if (typeof color === "number") return color;
+  const hex = String(color).replace(/^#/, "");
+  return /^[0-9a-f]{6}$/i.test(hex) ? parseInt(hex, 16) : undefined;
+}
+
+export class EmbedBuilder {
+  /** @param {Record<string, unknown>} [data] */
+  constructor(data = {}) {
+    /** @type {Record<string, any>} */
+    this.data = { ...data };
+  }
+  setTitle(title) {
+    this.data.title = title;
+    return this;
+  }
+  setDescription(description) {
+    this.data.description = description;
+    return this;
+  }
+  setURL(url) {
+    this.data.url = url;
+    return this;
+  }
+  /** @param {string | number} color "#3b6cf6" ou 0x3b6cf6 */
+  setColor(color) {
+    this.data.color = toColor(color);
+    return this;
+  }
+  /** @param {{ name: string, url?: string, iconURL?: string }} author */
+  setAuthor(author) {
+    this.data.author = { name: author.name, url: author.url, icon_url: author.iconURL };
+    return this;
+  }
+  /** @param {{ text: string, iconURL?: string }} footer */
+  setFooter(footer) {
+    this.data.footer = { text: footer.text, icon_url: footer.iconURL };
+    return this;
+  }
+  setImage(url) {
+    this.data.image = { url };
+    return this;
+  }
+  setThumbnail(url) {
+    this.data.thumbnail = { url };
+    return this;
+  }
+  /** @param {Date | number | string} [timestamp] */
+  setTimestamp(timestamp = new Date()) {
+    this.data.timestamp = new Date(timestamp).toISOString();
+    return this;
+  }
+  /** @param {...{ name: string, value: string, inline?: boolean }} fields */
+  addFields(...fields) {
+    this.data.fields = [...(this.data.fields ?? []), ...fields.flat()];
+    return this;
+  }
+  toJSON() {
+    return this.data;
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,250 @@
+import { EventEmitter } from "node:events";
+
+export interface ClientOptions {
+  /** O token do bot (começa com b_), do portal do desenvolvedor. */
+  token: string;
+  /** Padrão: https://api.fivenetwork.dev */
+  apiUrl?: string;
+  /** Padrão: o apiUrl com ws(s):// e /ws. */
+  gatewayUrl?: string;
+  /** Prefixo dos comandos registrados com client.command(). Padrão: "!" */
+  prefix?: string;
+  /** Ignorar mensagens de outros bots. Padrão: true */
+  ignoreBots?: boolean;
+}
+
+export interface EmbedData {
+  title?: string;
+  description?: string;
+  url?: string;
+  color?: number;
+  author?: { name: string; url?: string; icon_url?: string };
+  footer?: { text: string; icon_url?: string };
+  image?: { url: string };
+  thumbnail?: { url: string };
+  timestamp?: string;
+  fields?: { name: string; value: string; inline?: boolean }[];
+}
+
+export class EmbedBuilder {
+  constructor(data?: EmbedData);
+  data: EmbedData;
+  setTitle(title: string): this;
+  setDescription(description: string): this;
+  setURL(url: string): this;
+  /** "#3b6cf6" ou 0x3b6cf6 */
+  setColor(color: string | number): this;
+  setAuthor(author: { name: string; url?: string; iconURL?: string }): this;
+  setFooter(footer: { text: string; iconURL?: string }): this;
+  setImage(url: string): this;
+  setThumbnail(url: string): this;
+  setTimestamp(timestamp?: Date | number | string): this;
+  addFields(...fields: ({ name: string; value: string; inline?: boolean } | { name: string; value: string; inline?: boolean }[])[]): this;
+  toJSON(): EmbedData;
+}
+
+export interface MessageOptions {
+  content?: string;
+  embeds?: (EmbedBuilder | EmbedData)[];
+  /** ids de pessoas a mencionar (além dos <@id> no texto). */
+  mentions?: string[];
+  /** ids de cargos a mencionar (o cargo precisa ser mencionável, ou o bot ter "Mencionar @everyone"). */
+  roleMentions?: string[];
+  /** @everyone (precisa da permissão). */
+  everyone?: boolean;
+  /** Responder a uma mensagem (id ou a mensagem). */
+  reply?: string | Message;
+}
+export type MessageContent = string | MessageOptions;
+
+export class User {
+  readonly id: string;
+  readonly username: string | null;
+  readonly displayName: string;
+  readonly avatarURL: string | null;
+  readonly bot: boolean;
+  readonly flags: string[];
+  /** "<@id>" */
+  toString(): string;
+}
+
+export class Channel {
+  readonly id: string;
+  readonly name: string;
+  readonly kind: "text" | "voice";
+  readonly categoryId: string | null;
+  readonly topic: string;
+  readonly group: Group;
+  readonly isText: boolean;
+  send(content: MessageContent): Promise<Message>;
+  sendTyping(): Promise<void>;
+  fetchMessages(options?: { limit?: number; after?: string }): Promise<Message[]>;
+  fetchMessage(id: string): Promise<Message>;
+  toString(): string;
+}
+
+export interface GroupRole {
+  id: string;
+  name: string;
+  color: string | null;
+  position: number;
+  mentionable: boolean;
+}
+
+export interface GroupMember {
+  id: string;
+  username: string;
+  displayName: string;
+  avatarUrl: string | null;
+  bot: boolean;
+  roleIds: string[];
+  owner: boolean;
+  online: boolean;
+  user: User;
+}
+
+export type BotPermission =
+  | "administrator"
+  | "manageGroup"
+  | "manageChannels"
+  | "manageRoles"
+  | "kickMembers"
+  | "banMembers"
+  | "manageMessages"
+  | "manageReactions"
+  | "createInvites"
+  | "manageWebhooks";
+
+export class Group {
+  readonly id: string;
+  readonly name: string;
+  readonly iconURL: string | null;
+  readonly ownerId: string | null;
+  readonly memberCount: number;
+  readonly roles: GroupRole[];
+  readonly channels: Map<string, Channel>;
+  /** O que o bot pode fazer neste grupo. */
+  readonly permissions: Partial<Record<BotPermission, boolean>>;
+  can(permission: BotPermission): boolean;
+  kick(userId: string): Promise<void>;
+  ban(userId: string, reason?: string): Promise<void>;
+  unban(userId: string): Promise<void>;
+  fetchBans(): Promise<{ userId: string; name: string; bannedAt: number; by: string; reason?: string }[]>;
+  addRole(userId: string, roleId: string): Promise<string[]>;
+  removeRole(userId: string, roleId: string): Promise<string[]>;
+  leave(): Promise<void>;
+  /** A sala pelo id ou pelo nome. */
+  channel(idOrName: string): Channel | null;
+  role(idOrName: string): GroupRole | null;
+  fetchMembers(): Promise<GroupMember[]>;
+}
+
+export interface Reaction {
+  emoji: string;
+  users: string[];
+}
+
+export class Message {
+  readonly id: string;
+  readonly groupId: string;
+  readonly channelId: string;
+  /** O texto como está gravado: menções como <@id>. */
+  readonly content: string;
+  /** O texto com <@id> trocado por @nome. */
+  readonly cleanContent: string;
+  readonly embeds: EmbedData[];
+  readonly attachments: { url: string; name: string; size: number; type: string; kind: string }[];
+  readonly images: string[];
+  readonly reactions: Reaction[];
+  readonly replyTo: { id: string; from: string; fromName: string; text: string } | null;
+  readonly createdAt: Date;
+  readonly editedAt: Date | null;
+  readonly pinned: boolean;
+  readonly webhook: boolean;
+  readonly author: User;
+  readonly mentions: { users: string[]; roles: string[]; everyone: boolean; raw: string[] };
+  /** A mensagem menciona o bot (pelo id ou @everyone). */
+  readonly mentionsMe: boolean;
+  readonly group: Group | null;
+  readonly channel: Channel | null;
+  reply(content: MessageContent): Promise<Message>;
+  edit(content: MessageContent): Promise<Message>;
+  delete(): Promise<void>;
+  react(emoji: string): Promise<void>;
+  unreact(emoji: string): Promise<void>;
+  pin(): Promise<void>;
+  unpin(): Promise<void>;
+}
+
+export interface CommandContext {
+  message: Message;
+  args: string[];
+  client: Client;
+  reply(content: MessageContent): Promise<Message>;
+}
+
+export interface Command {
+  name: string;
+  description?: string;
+  aliases?: string[];
+  run(context: CommandContext): unknown;
+}
+
+export interface ClientEvents {
+  ready: [user: User];
+  messageCreate: [message: Message];
+  messageUpdate: [message: Message];
+  messageDelete: [info: { id: string; groupId: string; channelId: string }];
+  reactionUpdate: [info: { messageId: string; groupId: string; channelId: string; reactions: Reaction[] }];
+  typingStart: [info: { userId: string; name: string; groupId: string; channelId: string }];
+  groupJoin: [group: Group];
+  memberAdd: [info: { user: User; group: Group | null; groupId: string; via: "join" | "invite" | "profile" | null }];
+  memberRemove: [info: { userId: string; user: User | null; group: Group | null; groupId: string; reason: "left" | "kicked" | "banned" | null; by: string | null }];
+  groupLeave: [info: { id: string; reason: string | null }];
+  groupUpdate: [group: Group];
+  reconnecting: [attempt: number];
+  reconnected: [];
+  disconnect: [];
+  error: [error: Error];
+  commandError: [error: unknown, context: CommandContext];
+  raw: [payload: Record<string, unknown>];
+}
+
+export class Client extends EventEmitter {
+  constructor(options: ClientOptions);
+  readonly user: User | null;
+  readonly groups: Map<string, Group>;
+  readonly users: Map<string, User>;
+  readonly commands: Map<string, Command>;
+  readonly prefix: string;
+  readonly rest: REST;
+  login(): Promise<User>;
+  destroy(): void;
+  command(command: Command): this;
+  fetchGroup(id: string): Promise<Group>;
+  fetchUser(id: string): Promise<User>;
+  on<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+  once<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+  off<K extends keyof ClientEvents>(event: K, listener: (...args: ClientEvents[K]) => void): this;
+}
+
+export class REST {
+  constructor(options: { token: string; apiUrl: string; retries?: number });
+  request<T = any>(method: string, path: string, body?: unknown): Promise<T>;
+  get<T = any>(path: string): Promise<T>;
+  post<T = any>(path: string, body?: unknown): Promise<T>;
+  patch<T = any>(path: string, body?: unknown): Promise<T>;
+  put<T = any>(path: string, body?: unknown): Promise<T>;
+  delete<T = any>(path: string): Promise<T>;
+}
+
+export class FiveLiveAPIError extends Error {
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+}
+
+/** "<@id>" */
+export function userMention(id: string): string;
+/** "<#id>" */
+export function channelMention(id: string): string;

package/src/index.js

@@ -0,0 +1,7 @@
+// fivelive.js — SDK para bots do Five Live.
+// Documentação: README.md e https://live.fivenetwork.dev/developers
+
+export { Client } from "./client.js";
+export { EmbedBuilder } from "./embed.js";
+export { REST, FiveLiveAPIError } from "./rest.js";
+export { Channel, Group, Message, User, channelMention, userMention } from "./structures.js";

package/src/rest.js

@@ -0,0 +1,75 @@
+// As rotas HTTP da API de bots (api/botApi.mjs), com o token no cabeçalho
+// `Authorization: Bot <token>`. Trata o limite de envio (429) esperando o
+// tempo que a API pede e tentando de novo.
+
+export class FiveLiveAPIError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} status
+   * @param {string} method
+   * @param {string} path
+   */
+  constructor(message, status, method, path) {
+    super(message);
+    this.name = "FiveLiveAPIError";
+    this.status = status;
+    this.method = method;
+    this.path = path;
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class REST {
+  /** @param {{ token: string, apiUrl: string, retries?: number }} options */
+  constructor(options) {
+    this.token = options.token;
+    this.apiUrl = options.apiUrl.replace(/\/$/, "");
+    this.retries = options.retries ?? 3;
+  }
+
+  /**
+   * @param {string} method
+   * @param {string} path
+   * @param {unknown} [body]
+   */
+  async request(method, path, body) {
+    for (let attempt = 0; ; attempt++) {
+      const res = await fetch(this.apiUrl + path, {
+        method,
+        headers: {
+          Authorization: `Bot ${this.token}`,
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+          "User-Agent": "fivelive.js (https://live.fivenetwork.dev/developers, 0.1.0)",
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.status === 429 && attempt < this.retries) {
+        const seconds = Number(data.retryAfter ?? res.headers.get("retry-after") ?? 5);
+        await sleep(Math.max(1, seconds) * 1000);
+        continue;
+      }
+      if (!res.ok) throw new FiveLiveAPIError(data.error ?? `HTTP ${res.status}`, res.status, method, path);
+      return data;
+    }
+  }
+
+  get(path) {
+    return this.request("GET", path);
+  }
+  post(path, body) {
+    return this.request("POST", path, body ?? {});
+  }
+  patch(path, body) {
+    return this.request("PATCH", path, body ?? {});
+  }
+  put(path, body) {
+    return this.request("PUT", path, body ?? {});
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+}
+
+export const enc = encodeURIComponent;

package/src/structures.js

@@ -0,0 +1,257 @@
+// Os objetos que o bot recebe: User, Group, Channel, Message. Cada um sabe
+// agir sobre si mesmo (message.reply, channel.send, …) usando o client.
+
+import { enc } from "./rest.js";
+
+/** `<@id>` — como mencionar alguém no texto. */
+export const userMention = (id) => `<@${id}>`;
+/** `<#id>` — como apontar uma sala no texto. */
+export const channelMention = (id) => `<#${id}>`;
+
+/**
+ * Normaliza o que se manda: um texto, ou { content, embeds, mentions, reply }.
+ * @param {string | Record<string, any>} input
+ */
+export function messagePayload(input) {
+  const options = typeof input === "string" ? { content: input } : input ?? {};
+  const embeds = (options.embeds ?? []).map((embed) => (typeof embed?.toJSON === "function" ? embed.toJSON() : embed));
+  const roles = (options.roleMentions ?? []).map((id) => `@role:${id}`);
+  return {
+    text: options.content ?? "",
+    ...(embeds.length ? { embeds } : {}),
+    ...(options.mentions?.length || roles.length || options.everyone
+      ? { mentions: [...(options.mentions ?? []), ...roles, ...(options.everyone ? ["@everyone"] : [])] }
+      : {}),
+    ...(options.reply ? { replyTo: typeof options.reply === "string" ? options.reply : options.reply.id } : {}),
+  };
+}
+
+export class User {
+  /** @param {import("./client.js").Client} client @param {Record<string, any>} data */
+  constructor(client, data) {
+    this.client = client;
+    this.id = data.id;
+    this.username = data.username ?? null;
+    this.displayName = data.displayName ?? data.name ?? data.username ?? "";
+    this.avatarURL = data.avatarUrl ?? null;
+    this.bot = data.bot === true;
+    this.flags = data.flags ?? [];
+  }
+  /** `<@id>`, para colocar no texto. */
+  toString() {
+    return userMention(this.id);
+  }
+}
+
+export class Channel {
+  /** @param {import("./client.js").Client} client @param {Group} group @param {Record<string, any>} data */
+  constructor(client, group, data) {
+    this.client = client;
+    this.group = group;
+    this.id = data.id;
+    this.name = data.name;
+    /** "text" | "voice" */
+    this.kind = data.kind;
+    this.categoryId = data.categoryId ?? null;
+    this.topic = data.topic ?? "";
+  }
+  get isText() {
+    return this.kind === "text";
+  }
+  get path() {
+    return `/bot/groups/${enc(this.group.id)}/channels/${enc(this.id)}`;
+  }
+  /** Manda uma mensagem. @param {string | Record<string, any>} content */
+  async send(content) {
+    const data = await this.client.rest.post(`${this.path}/messages`, messagePayload(content));
+    return new Message(this.client, data.message, this.client.user);
+  }
+  /** "Digitando…" por alguns segundos. */
+  async sendTyping() {
+    await this.client.rest.post(`${this.path}/typing`, { typing: true });
+  }
+  /**
+   * As últimas mensagens (a mais nova por último).
+   * @param {{ limit?: number, after?: string }} [options]
+   */
+  async fetchMessages(options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit) query.set("limit", String(options.limit));
+    if (options.after) query.set("after", options.after);
+    const data = await this.client.rest.get(`${this.path}/messages?${query}`);
+    return data.messages.map((message) => new Message(this.client, message));
+  }
+  /** Uma mensagem pelo id. */
+  async fetchMessage(id) {
+    const data = await this.client.rest.get(`${this.path}/messages/${enc(id)}`);
+    return new Message(this.client, data.message);
+  }
+  toString() {
+    return `<#${this.id}>`;
+  }
+}
+
+export class Group {
+  /** @param {import("./client.js").Client} client @param {Record<string, any>} data */
+  constructor(client, data) {
+    this.client = client;
+    this._patch(data);
+  }
+  /** @param {Record<string, any>} data */
+  _patch(data) {
+    this.id = data.id;
+    this.name = data.name;
+    this.iconURL = data.iconUrl ?? null;
+    this.ownerId = data.ownerId ?? null;
+    this.memberCount = data.memberCount ?? 0;
+    /** @type {{ id: string, name: string, color: string | null, position: number, mentionable: boolean }[]} */
+    this.roles = data.roles ?? [];
+    /** O que o bot pode fazer aqui (kickMembers, banMembers, manageRoles, manageMessages…). */
+    this.permissions = data.permissions ?? {};
+    /** @type {Map<string, Channel>} */
+    this.channels = new Map((data.channels ?? []).map((channel) => [channel.id, new Channel(this.client, this, channel)]));
+  }
+  /** A sala pelo id ou pelo nome. @param {string} idOrName */
+  channel(idOrName) {
+    return this.channels.get(idOrName) ?? [...this.channels.values()].find((channel) => channel.name === idOrName) ?? null;
+  }
+  /** Os membros, com cargos e quem está online. */
+  async fetchMembers() {
+    const data = await this.client.rest.get(`/bot/groups/${enc(this.id)}/members`);
+    return data.members.map((member) => ({ ...member, user: this.client._cacheUser(member) }));
+  }
+  get path() {
+    return `/bot/groups/${enc(this.id)}`;
+  }
+  /** Se o bot tem a permissão (administrator vale por todas). @param {string} key */
+  can(key) {
+    return this.permissions.administrator === true || this.permissions[key] === true;
+  }
+  /** Expulsa alguém (precisa de kickMembers e de um cargo acima do da pessoa). @param {string} userId */
+  async kick(userId) {
+    await this.client.rest.post(`${this.path}/members/${enc(userId)}/kick`, {});
+  }
+  /** Bane alguém, mesmo que não esteja no grupo (banMembers). @param {string} userId @param {string} [reason] */
+  async ban(userId, reason) {
+    await this.client.rest.put(`${this.path}/bans/${enc(userId)}`, reason ? { reason } : {});
+  }
+  /** Tira o banimento (banMembers). @param {string} userId */
+  async unban(userId) {
+    await this.client.rest.delete(`${this.path}/bans/${enc(userId)}`);
+  }
+  /** Quem está banido (banMembers). */
+  async fetchBans() {
+    const data = await this.client.rest.get(`${this.path}/bans`);
+    return data.bans;
+  }
+  /** Dá um cargo (manageRoles; só cargos abaixo do mais alto do bot). @param {string} userId @param {string} roleId */
+  async addRole(userId, roleId) {
+    const data = await this.client.rest.put(`${this.path}/members/${enc(userId)}/roles/${enc(roleId)}`);
+    return data.roleIds;
+  }
+  /** Tira um cargo (manageRoles). @param {string} userId @param {string} roleId */
+  async removeRole(userId, roleId) {
+    const data = await this.client.rest.delete(`${this.path}/members/${enc(userId)}/roles/${enc(roleId)}`);
+    return data.roleIds;
+  }
+  /** O bot sai do grupo. */
+  async leave() {
+    await this.client.rest.post(`${this.path}/leave`, {});
+  }
+  /** `<@&id>` não existe aqui: para mencionar um cargo, use { roleMentions: [id] } no envio. */
+  role(idOrName) {
+    return this.roles.find((role) => role.id === idOrName || role.name === idOrName) ?? null;
+  }
+}
+
+export class Message {
+  /**
+   * @param {import("./client.js").Client} client
+   * @param {Record<string, any>} data
+   * @param {User | Record<string, any>} [author]
+   */
+  constructor(client, data, author) {
+    this.client = client;
+    this.id = data.id;
+    this.groupId = data.groupId;
+    this.channelId = data.channelId;
+    /** O texto como está gravado — menções como `<@id>`. */
+    this.content = data.text ?? "";
+    this.embeds = data.embeds ?? [];
+    this.attachments = data.attachments ?? [];
+    this.images = data.images ?? [];
+    this.reactions = data.reactions ?? [];
+    this.replyTo = data.replyTo ?? null;
+    this.createdAt = new Date(data.ts ?? Date.now());
+    this.editedAt = data.editedAt ? new Date(data.editedAt) : null;
+    this.pinned = Boolean(data.pinnedAt);
+    this.webhook = Boolean(data.webhook);
+    const mentions = data.mentions ?? [];
+    this.mentions = {
+      /** ids das pessoas mencionadas */
+      users: mentions.filter((entry) => !entry.startsWith("@")),
+      /** ids dos cargos mencionados */
+      roles: mentions.filter((entry) => entry.startsWith("@role:")).map((entry) => entry.slice(6)),
+      everyone: mentions.includes("@everyone"),
+      raw: mentions,
+    };
+    this.author =
+      author instanceof User
+        ? author
+        : author
+          ? client._cacheUser(author)
+          : client.users.get(data.from) ?? new User(client, { id: data.from, name: data.fromName });
+  }
+  get group() {
+    return this.client.groups.get(this.groupId) ?? null;
+  }
+  get channel() {
+    return this.group?.channels.get(this.channelId) ?? null;
+  }
+  /** O texto com `<@id>` trocado por `@nome` (quando o nome é conhecido). */
+  get cleanContent() {
+    return this.content.replace(/<@([A-Za-z0-9:_-]+)>/g, (whole, id) => {
+      const user = this.client.users.get(id);
+      return user ? `@${user.displayName}` : whole;
+    });
+  }
+  /** Se a mensagem menciona o bot (pelo id, cargo não conta). */
+  get mentionsMe() {
+    return this.mentions.users.includes(this.client.user?.id) || this.mentions.everyone;
+  }
+  get path() {
+    return `/bot/groups/${enc(this.groupId)}/channels/${enc(this.channelId)}/messages`;
+  }
+  /** Responde citando esta mensagem. @param {string | Record<string, any>} content */
+  async reply(content) {
+    const payload = messagePayload(content);
+    const data = await this.client.rest.post(this.path, { ...payload, replyTo: this.id });
+    return new Message(this.client, data.message, this.client.user);
+  }
+  /** Edita (só as mensagens do próprio bot). @param {string | Record<string, any>} content */
+  async edit(content) {
+    const payload = messagePayload(content);
+    const data = await this.client.rest.patch(`${this.path}/${enc(this.id)}`, { text: payload.text, ...(payload.embeds ? { embeds: payload.embeds } : {}) });
+    return new Message(this.client, data.message, this.author);
+  }
+  /** Fixa na sala (manageMessages). */
+  async pin() {
+    await this.client.rest.put(`${this.path}/${enc(this.id)}/pin`);
+  }
+  /** Desafixa (manageMessages). */
+  async unpin() {
+    await this.client.rest.delete(`${this.path}/${enc(this.id)}/pin`);
+  }
+  /** Apaga: as do próprio bot sempre; as dos outros, com manageMessages. */
+  async delete() {
+    await this.client.rest.delete(`${this.path}/${enc(this.id)}`);
+  }
+  /** Reage com um emoji. @param {string} emoji */
+  async react(emoji) {
+    await this.client.rest.put(`${this.path}/${enc(this.id)}/reactions/${enc(emoji)}`);
+  }
+  /** Tira a reação do bot. @param {string} emoji */
+  async unreact(emoji) {
+    await this.client.rest.delete(`${this.path}/${enc(this.id)}/reactions/${enc(emoji)}`);
+  }
+}