fivelive.js 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +145 -140
  3. package/package.json +8 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Five Network
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,201 +1,206 @@
1
- # fivelive.js
1
+ <div align="center">
2
+ <br />
3
+ <p>
4
+ <a href="https://live.fivenetwork.dev/developers"><img src="https://live.fivenetwork.dev/brand/five-mark-blue.png" width="120" alt="Five Live" /></a>
5
+ </p>
6
+ <h1>fivelive.js</h1>
7
+ <p>
8
+ <a href="https://www.npmjs.com/package/fivelive.js"><img src="https://img.shields.io/npm/v/fivelive.js.svg?maxAge=3600&color=3b6cf6" alt="versão no npm" /></a>
9
+ <a href="https://www.npmjs.com/package/fivelive.js"><img src="https://img.shields.io/npm/dt/fivelive.js.svg?maxAge=3600&color=3b6cf6" alt="downloads no npm" /></a>
10
+ <a href="https://www.npmjs.com/package/fivelive.js"><img src="https://img.shields.io/node/v/fivelive.js.svg?color=3b6cf6" alt="versão do Node" /></a>
11
+ <a href="https://www.npmjs.com/package/fivelive.js"><img src="https://img.shields.io/npm/types/fivelive.js.svg?color=3b6cf6" alt="tipos TypeScript" /></a>
12
+ <a href="https://www.npmjs.com/package/fivelive.js"><img src="https://img.shields.io/npm/l/fivelive.js.svg?color=3b6cf6" alt="licença" /></a>
13
+ </p>
14
+ <p>
15
+ <a href="https://live.fivenetwork.dev/developers/docs"><b>Documentação</b></a> ·
16
+ <a href="https://live.fivenetwork.dev/developers/docs/primeiro-bot"><b>Primeiro bot</b></a> ·
17
+ <a href="https://live.fivenetwork.dev/developers"><b>Portal do desenvolvedor</b></a>
18
+ </p>
19
+ </div>
20
+
21
+ ## Sobre
22
+
23
+ **fivelive.js** é o SDK oficial para criar bots do [Five Live](https://live.fivenetwork.dev) em Node.js.
24
+
25
+ - Orientado a objetos: `Message`, `Channel`, `Group` e `User`, cada um com os próprios métodos (`message.reply()`, `channel.send()`, `group.kick()`…)
26
+ - Tempo real: mensagens, reações, “digitando…”, quem entra e quem sai, tudo por eventos
27
+ - **Comandos de barra (`/`)**: quem digita `/` no grupo vê os comandos do seu bot, com descrição e argumentos
28
+ - Reconecta sozinho, respeita os limites da API e tenta de novo quando precisa
29
+ - Tipos TypeScript incluídos, e funciona com `import` e com `require`
30
+ - Se você já fez bot com **discord.js**, vai se sentir em casa ([veja a comparação](#vindo-do-discordjs))
31
+
32
+ ## Instalação
33
+
34
+ **Node.js 18 ou mais novo.**
35
+
36
+ ```sh
37
+ npm install fivelive.js
38
+ yarn add fivelive.js
39
+ pnpm add fivelive.js
40
+ bun add fivelive.js
41
+ ```
42
+
43
+ ### Pacotes opcionais
44
+
45
+ - [ws](https://www.npmjs.com/package/ws): o WebSocket no Node 18 e 20 (o Node 22+ já tem um nativo). É instalado junto automaticamente.
2
46
 
3
- 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.
47
+ ## Exemplo
48
+
49
+ Crie o bot em **[live.fivenetwork.dev/developers](https://live.fivenetwork.dev/developers)**, copie o token (começa com `b_`) e adicione o bot a um grupo pelo link da aba **Instalação**.
4
50
 
5
51
  ```js
6
- import { Client } from "fivelive.js";
52
+ import { Client, EmbedBuilder } from "fivelive.js";
7
53
 
8
- const client = new Client({ token: process.env.FIVELIVE_TOKEN });
54
+ const client = new Client({ token: process.env.FIVELIVE_TOKEN, prefix: "/" });
9
55
 
10
- client.on("ready", (bot) => console.log(`Online como ${bot.displayName}`));
56
+ client.on("ready", (bot) => console.log(`Online como ${bot.displayName}!`));
11
57
 
58
+ // Aparece na lista quando alguém digita "/" no grupo.
12
59
  client.command({
13
60
  name: "ping",
61
+ description: "Responde pong",
14
62
  run: ({ reply }) => reply("🏓 pong!"),
15
63
  });
16
64
 
17
- client.login();
18
- ```
65
+ client.command({
66
+ name: "info",
67
+ description: "Mostra o grupo",
68
+ run: ({ message, reply }) =>
69
+ reply({
70
+ embeds: [
71
+ new EmbedBuilder()
72
+ .setTitle(message.group.name)
73
+ .addFields({ name: "Membros", value: String(message.group.memberCount), inline: true })
74
+ .setColor("#3b6cf6"),
75
+ ],
76
+ }),
77
+ });
19
78
 
20
- ## Começando
79
+ client.on("memberAdd", ({ user, group }) => group?.channel("geral")?.send(`Bem-vindo(a), ${user}!`));
21
80
 
22
- 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.
23
- 2. Adicione o bot a um grupo pelo link **"Adicionar a um grupo"** na página dele.
24
- 3. Instale e rode:
81
+ client.login();
82
+ ```
25
83
 
26
- ```bash
27
- npm install fivelive.js
84
+ ```sh
28
85
  FIVELIVE_TOKEN=b_seu_token node bot.mjs
29
86
  ```
30
87
 
31
- É 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.
88
+ ## Guia rápido
32
89
 
33
- ## Eventos
34
-
35
- ```js
36
- client.on("messageCreate", async (message) => {
37
- if (message.content === "oi") await message.reply(`Oi, ${message.author}!`);
38
- });
39
- ```
90
+ ### Eventos
40
91
 
41
92
  | Evento | Recebe |
42
93
  |---|---|
43
94
  | `ready` | o usuário do bot, depois de conectar e carregar os grupos |
44
95
  | `messageCreate` | `Message` nova (as do próprio bot não chegam; as de outros bots só com `ignoreBots: false`) |
45
- | `messageUpdate` | `Message` editada |
46
- | `messageDelete` | `{ id, groupId, channelId }` |
96
+ | `messageUpdate` / `messageDelete` | `Message` editada / `{ id, groupId, channelId }` |
47
97
  | `reactionUpdate` | `{ messageId, groupId, channelId, reactions }` |
48
98
  | `typingStart` | `{ userId, name, groupId, channelId }` |
49
- | `memberAdd` | `{ user, group, groupId, via }`, quando alguém entra num grupo do bot |
50
- | `memberRemove` | `{ userId, user, group, groupId, reason, by }` — reason: `left`, `kicked` ou `banned` |
51
- | `groupJoin` | `Group`, quando adicionam o bot a um grupo |
52
- | `groupLeave` | `{ id, reason }`, quando o bot sai, é expulso ou o grupo é apagado |
53
- | `groupUpdate` | `Group`, quando o grupo muda (nome, salas, cargos) |
99
+ | `memberAdd` | `{ user, group, groupId, via }` — alguém entrou num grupo do bot |
100
+ | `memberRemove` | `{ userId, user, group, groupId, reason, by }` — `left`, `kicked` ou `banned` |
101
+ | `groupJoin` / `groupLeave` / `groupUpdate` | o bot entrou, saiu ou o grupo mudou |
54
102
  | `reconnecting` / `reconnected` / `disconnect` | a conexão caiu e voltou sozinha |
55
- | `error` | `Error` |
56
- | `commandError` | `(error, context)`, quando um comando lança um erro |
103
+ | `error` / `commandError` | erros (o segundo recebe o contexto do comando) |
57
104
 
58
- ## Comandos
105
+ ### Comandos de barra (/)
59
106
 
60
- ```js
61
- const client = new Client({ token, prefix: "!" });
107
+ Todo `client.command` com `description` aparece na lista do `/`. O `login()` manda a lista sozinho.
62
108
 
109
+ ```js
63
110
  client.command({
64
- name: "dado",
65
- aliases: ["d"],
66
- description: "Rola um dado: !dado 20",
67
- run: async ({ args, message, reply }) => {
68
- const lados = Number(args[0]) || 6;
69
- await message.channel.sendTyping();
70
- await reply(`🎲 ${1 + Math.floor(Math.random() * lados)}`);
111
+ name: "ban",
112
+ description: "Bane alguém do grupo",
113
+ options: [
114
+ { name: "usuario", description: "Quem banir", required: true, type: "user" },
115
+ { name: "motivo", description: "Por quê" },
116
+ ],
117
+ run: async ({ message, args, reply }) => {
118
+ const alvo = message.mentions.users[0];
119
+ if (!alvo) return reply("Use: /ban @pessoa motivo");
120
+ await message.group.ban(alvo, args.slice(1).join(" ") || "sem motivo");
121
+ await reply(`<@${alvo}> foi banido(a).`);
71
122
  },
72
123
  });
73
124
  ```
74
125
 
75
- ## Mensagens
126
+ Até 25 comandos por bot. Sem `description`, o comando funciona pelo prefixo mas fica fora da lista. Registrou mais comandos depois do `login()`? Chame `client.syncCommands()`.
127
+
128
+ ### Mensagens, menções e embeds
76
129
 
77
130
  ```js
78
- await message.reply("resposta citando a mensagem");
79
- await message.channel.send("mensagem normal");
131
+ await message.reply("citando a mensagem");
132
+ await message.channel.send({ content: `Oi, ${message.author}!`, roleMentions: [roleId] });
80
133
  await message.react("👍");
81
- await message.unreact("👍");
134
+ await message.pin();
82
135
 
83
136
  const minha = await message.channel.send("vou editar");
84
137
  await minha.edit("editada");
85
- await minha.delete(); // só as mensagens do próprio bot
86
-
87
- message.content // o texto como está gravado, com as menções como <@id>
88
- message.cleanContent // com as menções trocadas por @nome
89
- message.author // User: id, username, displayName, avatarURL, bot
90
- message.mentions // { users: [...ids], roles: [...ids], everyone }
91
- message.mentionsMe // se mencionou o bot
92
- message.group / message.channel
93
- ```
94
-
95
- ### Menções
96
-
97
- ```js
98
- import { userMention } from "fivelive.js";
99
-
100
- await channel.send(`Bem-vindo, ${userMention(id)}!`); // ou `${message.author}`
101
- await channel.send({ content: "Atenção, mods", roleMentions: [roleId] });
102
- await channel.send({ content: "Todo mundo!", everyone: true }); // precisa da permissão
103
- ```
104
-
105
- 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).
106
-
107
- ### Embeds
108
-
109
- ```js
110
- import { EmbedBuilder } from "fivelive.js";
111
-
112
- const embed = new EmbedBuilder()
113
- .setTitle("Placar")
114
- .setDescription("Resultado da rodada")
115
- .setColor("#3b6cf6")
116
- .setAuthor({ name: "Five Bot", iconURL: "https://..." })
117
- .addFields(
118
- { name: "Time A", value: "3", inline: true },
119
- { name: "Time B", value: "1", inline: true },
120
- )
121
- .setImage("https://...")
122
- .setFooter({ text: "Five Live" })
123
- .setTimestamp();
124
-
125
- await message.channel.send({ content: "Fim de jogo!", embeds: [embed] });
126
- ```
127
-
128
- ## Grupos, salas e membros
129
-
130
- ```js
131
- for (const group of client.groups.values()) {
132
- console.log(group.name, [...group.channels.values()].map((c) => c.name));
133
- }
138
+ await minha.delete();
134
139
 
135
- const geral = client.groups.get(groupId).channel("geral"); // pelo id ou pelo nome
136
- await geral.send("Bom dia!");
137
-
138
- const historico = await geral.fetchMessages({ limit: 20 });
139
- const membros = await group.fetchMembers(); // com roleIds, owner e online
140
- const pessoa = await client.fetchUser(userId);
140
+ message.cleanContent; // texto com <@id> trocado por @nome
141
+ message.mentionsMe; // se mencionou o bot
141
142
  ```
142
143
 
143
- ## Moderação
144
+ ### Grupos e moderação
144
145
 
145
146
  Tudo respeita as permissões do cargo do bot e a hierarquia: ele só age em quem está abaixo do cargo mais alto dele.
146
147
 
147
148
  ```js
149
+ const group = client.groups.get(groupId);
150
+ await group.channel("geral").send("Bom dia!"); // sala pelo id ou pelo nome
151
+ const membros = await group.fetchMembers(); // com roleIds, owner e online
152
+
148
153
  if (group.can("kickMembers")) await group.kick(userId);
149
- await group.ban(userId, "flood"); // banMembers
150
- await group.unban(userId);
151
- const banidos = await group.fetchBans();
152
- await group.addRole(userId, roleId); // manageRoles
153
- await group.removeRole(userId, roleId);
154
- await message.pin(); // manageMessages
155
- await message.delete(); // de outras pessoas: manageMessages
156
- await group.leave();
154
+ await group.ban(userId, "flood");
155
+ await group.addRole(userId, roleId);
157
156
  ```
158
157
 
159
- ## Limites
158
+ ### Erros e limites
160
159
 
161
- - **60 mensagens por minuto** por bot. Passando disso, o SDK espera o tempo que a API pede e tenta de novo sozinho.
162
- - Texto de até **2000** caracteres e até **10 embeds** por mensagem.
163
- - O bot só vê os grupos em que foi adicionado, e só as salas de texto.
164
-
165
- ## Erros
166
-
167
- Uma chamada recusada pela API lança `FiveLiveAPIError`, com `status`, `method` e `path`:
160
+ - 60 mensagens por minuto por bot; ao passar disso, o SDK espera o tempo que a API pede e tenta de novo.
161
+ - Até 2000 caracteres e 10 embeds por mensagem.
162
+ - Uma chamada recusada lança `FiveLiveAPIError`, com `status`, `method` e `path`.
168
163
 
169
164
  ```js
170
165
  import { FiveLiveAPIError } from "fivelive.js";
171
166
 
172
167
  try {
173
- await message.delete();
168
+ await group.kick(userId);
174
169
  } catch (err) {
175
- if (err instanceof FiveLiveAPIError && err.status === 403) console.log("Não posso apagar essa.");
170
+ if (err instanceof FiveLiveAPIError && err.status === 403) console.log("Sem permissão.");
176
171
  }
177
172
  ```
178
173
 
179
- ## Comandos de barra (/)
174
+ ## Vindo do discord.js
180
175
 
181
- Todo `client.command` com `description` vira um comando de barra: quem digitar `/` numa sala em que o bot está vê o comando na lista, com a descrição e os argumentos — do jeito do Discord. O `login()` manda a lista sozinho.
182
-
183
- ```js
184
- const client = new Client({ token: process.env.FIVELIVE_TOKEN, prefix: "/" });
185
-
186
- client.command({
187
- name: "ban",
188
- description: "Bane alguém do grupo",
189
- options: [
190
- { name: "usuario", description: "Quem banir", required: true, type: "user" },
191
- { name: "motivo", description: "Por quê" },
192
- ],
193
- run: async ({ message, args, reply }) => { /* ... */ },
194
- });
195
- ```
196
-
197
- Até 25 comandos por bot. Registrou mais depois do `login()`? Chame `client.syncCommands()`.
198
-
199
- ## Documentação
200
-
201
- Tudo em https://live.fivenetwork.dev/developers/docs — gateway, permissões, moderação, OAuth2, webhooks e exemplos.
176
+ | discord.js | fivelive.js |
177
+ |---|---|
178
+ | `new Client({ intents: [...] })` | `new Client({ token })` — sem intents: o bot recebe tudo dos grupos em que está |
179
+ | `client.login(token)` | `client.login()` (o token vai no `Client`) |
180
+ | `Guild` / `message.guild` | `Group` / `message.group` |
181
+ | `TextChannel` / `channel.send()` | `Channel` / `channel.send()` |
182
+ | `SlashCommandBuilder` + `interactionCreate` | `client.command({ name, description, options, run })` |
183
+ | `interaction.reply()` | `reply()` no contexto do comando |
184
+ | `guildMemberAdd` / `guildMemberRemove` | `memberAdd` / `memberRemove` |
185
+ | `messageReactionAdd` / `Remove` | `reactionUpdate` (a lista inteira, atualizada) |
186
+ | `EmbedBuilder` | `EmbedBuilder` (os mesmos métodos) |
187
+ | `member.kick()` / `guild.members.ban()` | `group.kick(userId)` / `group.ban(userId, motivo)` |
188
+ | `member.roles.add()` | `group.addRole(userId, roleId)` |
189
+ | `<@id>` | `<@id>` (igual) |
190
+
191
+ ## Links
192
+
193
+ - [Documentação](https://live.fivenetwork.dev/developers/docs) — gateway, permissões, moderação, OAuth2, webhooks
194
+ - [Primeiro bot](https://live.fivenetwork.dev/developers/docs/primeiro-bot) — do zero ao bot funcionando
195
+ - [Comandos de barra](https://live.fivenetwork.dev/developers/docs/comandos-de-barra)
196
+ - [Exemplos prontos](https://live.fivenetwork.dev/developers/docs/exemplos) — boas-vindas, moderação, cargos por reação
197
+ - [Portal do desenvolvedor](https://live.fivenetwork.dev/developers) — criar bots, token, OAuth2 e instalação
198
+ - [Five Live](https://live.fivenetwork.dev)
199
+
200
+ ## Ajuda
201
+
202
+ Travou em algo? Comece pela [documentação](https://live.fivenetwork.dev/developers/docs). Se o problema continuar, fale com a equipe pelo [Five Live](https://live.fivenetwork.dev).
203
+
204
+ ## Licença
205
+
206
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "fivelive.js",
3
- "version": "0.3.0",
4
- "description": "SDK oficial para criar bots do Five Live — eventos em tempo real, mensagens, embeds, reações e comandos.",
3
+ "version": "0.3.1",
4
+ "description": "SDK oficial para criar bots do Five Live — eventos em tempo real, comandos de barra (/), embeds, reações e moderação. Parecido com o discord.js.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
7
7
  "module": "./dist/index.mjs",
@@ -38,9 +38,14 @@
38
38
  },
39
39
  "keywords": [
40
40
  "fivelive",
41
+ "five-live",
41
42
  "bot",
42
43
  "sdk",
43
- "chat"
44
+ "chat",
45
+ "slash-commands",
46
+ "embeds",
47
+ "moderation",
48
+ "discord.js-like"
44
49
  ],
45
50
  "license": "MIT",
46
51
  "homepage": "https://live.fivenetwork.dev/developers"