@openvertice/bot-sdk 0.0.0-stage → 0.1.0

package/src/cliente.ts

@@ -0,0 +1,472 @@
+// The bot as its author sees it: `start`, `on`, `command`, `enviar`. Everything
+// else (token, session, heartbeat, reconnection) stays underneath.
+import { ErroDaApi, Http } from "./http.js";
+import { Gateway, type EstadoDoGateway } from "./gateway.js";
+import type {
+  CanalDeTexto,
+  ComandoAnunciado,
+  Descoberta,
+  ServidorIce,
+  Eventos,
+  Intencao,
+  Mensagem,
+  Sessao,
+} from "./tipos.js";
+
+/** Renews the session slightly before it expires, so it never dies mid-event. */
+const RENOVAR_ANTES_MS = 120_000;
+
+/** Everything needed to build a {@link Bot}. */
+export interface OpcoesDoBot {
+  /** Bot token (`vtb_…`), copied from the admin panel (Bots tab). */
+  token: string;
+  /** Server base URL. Default: `http://localhost:8080`. */
+  baseUrl?: string;
+  /** Intents this process wants; the server refuses whatever the panel did not grant. */
+  intents?: Intencao[];
+  /** Diagnostics: one line per state change. */
+  log?: (mensagem: string) => void;
+}
+
+/** What a command handler receives on every invocation. */
+export interface ContextoDoComando {
+  /** The message that triggered the command. */
+  mensagem: Mensagem;
+  /** The channel where the command was typed, with its settings. */
+  canal: CanalDeTexto;
+  /** `!tocar a.mp3` → `["a.mp3"]` (already split on whitespace). */
+  args: string[];
+  /** Everything typed after the command name, as-is. */
+  resto: string;
+  /** Replies in the same channel. */
+  responder(texto: string): Promise<Mensagem>;
+  /** Deletes the triggering message — only works when the bot wrote it. */
+  apagar(): Promise<void>;
+}
+
+/** A registered command, as kept inside the bot. */
+interface Comando {
+  /** Command name, lowercase and without the prefix. */
+  nome: string;
+  /** Optional summary announced to the client's autocomplete. */
+  descricao?: string;
+  /** Channels where it applies; empty = every channel the bot can speak in. */
+  canais: string[];
+  /** Handler invoked when the command matches. */
+  executar: (contexto: ContextoDoComando) => void | Promise<void>;
+}
+
+/** Handler signature for one gateway event. */
+type Ouvinte<K extends keyof Eventos> = (dados: Eventos[K]) => void | Promise<void>;
+
+/**
+ * A Vértice bot.
+ *
+ * Create one, register listeners with {@link on} and commands with
+ * {@link command}, then call {@link start}. Sessions, heartbeats, `resume` and
+ * reconnection are handled internally, so the author only has to react to
+ * events.
+ *
+ * @example
+ * ```ts
+ * const bot = new Bot({ token: process.env.VERTICE_BOT_TOKEN! });
+ *
+ * bot.command("ping", { descricao: "responde pong" }, async ({ responder }) => {
+ *   await responder("pong");
+ * });
+ *
+ * await bot.start();
+ * ```
+ */
+export class Bot {
+  readonly #http: Http;
+  readonly #intents: Intencao[];
+  readonly #log: (mensagem: string) => void;
+  readonly #ouvintes = new Map<string, Set<(dados: never) => void>>();
+  readonly #comandos: Comando[] = [];
+  readonly #ouvintesDeEstado = new Set<(estado: EstadoDoGateway) => void>();
+  #descoberta: Descoberta | null = null;
+  #sessao: Sessao | null = null;
+  #gateway: Gateway | null = null;
+  #ultimoErro: Error | null = null;
+
+  /** @param opcoes Token, base URL and the intents this process wants. */
+  constructor(opcoes: OpcoesDoBot) {
+    this.#http = new Http({ baseUrl: opcoes.baseUrl, token: opcoes.token });
+    this.#intents = opcoes.intents ?? ["MESSAGES"];
+    this.#log = opcoes.log ?? (() => {});
+  }
+
+  /** Identity the server assigned, or `null` before {@link start}. */
+  get bot(): Descoberta["bot"] | null {
+    return this.#descoberta?.bot ?? null;
+  }
+
+  /** Channels granted to the bot, or `null` before {@link start}. */
+  get canais(): Descoberta["canais"] | null {
+    return this.#descoberta?.canais ?? null;
+  }
+
+  /** ICE servers from discovery (the bot's voice uses the same ones). */
+  get iceServers(): ServidorIce[] {
+    return this.#descoberta?.iceServers ?? [];
+  }
+
+  /** Current gateway state, or `"parado"` before {@link start} and after {@link stop}. */
+  get estado(): EstadoDoGateway | "parado" {
+    return this.#gateway?.estado ?? "parado";
+  }
+
+  /**
+   * Registers a listener for every gateway state change.
+   *
+   * Voice uses it to leave the room when the connection drops: `resume` brings
+   * the events back, but not the seat in the voice room.
+   *
+   * @param ouvinte Called with the new state.
+   * @returns This bot, for chaining.
+   */
+  aoMudarEstado(ouvinte: (estado: EstadoDoGateway) => void): this {
+    this.#ouvintesDeEstado.add(ouvinte);
+    return this;
+  }
+
+  /** Last connection error, for callers that want to show it in a `/status` command. */
+  get ultimoErro(): Error | null {
+    return this.#ultimoErro;
+  }
+
+  /**
+   * Discovers what the bot may do, opens a session and connects the gateway.
+   *
+   * @returns This bot, once the gateway reports `ready`.
+   * @throws {ErroDaApi} When discovery or session creation fails.
+   * @throws {Error} When the server refuses the bot.
+   */
+  async start(): Promise<this> {
+    this.#descoberta = await this.#http.descobrir();
+    this.#log(
+      `conectando como @${this.#descoberta.bot.usuario} (${this.#descoberta.canais.texto.length} canal(is) de texto)`,
+    );
+    this.#sessao = await this.#http.abrirSessao();
+    this.#gateway = new Gateway({
+      url: this.#descoberta.gateway.url,
+      heartbeatMs: this.#descoberta.gateway.heartbeatMs,
+      intents: this.#intents,
+      comandos: this.#anunciarComandos(),
+      sessao: () => this.#sessaoValida(),
+      aoEvento: (t, d) => this.#despachar(t, d),
+      aoEstado: (estado, detalhe) => {
+        if (estado === "recusado") this.#ultimoErro = new Error(detalhe ?? estado);
+        this.#log(`gateway: ${estado}${detalhe ? ` (${detalhe})` : ""}`);
+        for (const ouvinte of this.#ouvintesDeEstado) {
+          try {
+            ouvinte(estado);
+          } catch (erro) {
+            this.#log(`ouvinte de estado falhou: ${erro}`);
+          }
+        }
+      },
+      log: this.#log,
+    });
+    await this.#gateway.conectar();
+    return this;
+  }
+
+  /**
+   * Returns a session that will not expire while the bot is connected.
+   *
+   * On reconnect it asks for a new one when the current session is about to
+   * expire. Rotating the token or disabling the bot kills the connection for
+   * good (4009) — in that case `start` fails on purpose, instead of retrying
+   * forever with a dead credential.
+   *
+   * @returns A session valid for at least {@link RENOVAR_ANTES_MS} more.
+   */
+  async #sessaoValida(): Promise<Sessao> {
+    const atual = this.#sessao;
+    if (atual && atual.expiraEm - RENOVAR_ANTES_MS > Date.now()) return atual;
+    this.#sessao = await this.#http.abrirSessao();
+    return this.#sessao;
+  }
+
+  /**
+   * Sends a raw gateway action (voice uses it to join, leave and signal).
+   *
+   * @param tipo Action name understood by the server.
+   * @param dados Action payload.
+   * @throws {Error} When `start()` has not been called yet.
+   */
+  agir(tipo: string, dados: Record<string, unknown> = {}): void {
+    if (!this.#gateway) throw new Error("Chame `start()` antes de agir no gateway.");
+    this.#gateway.agir(tipo, dados);
+  }
+
+  /** Closes the gateway for good and forgets the session. */
+  async stop(): Promise<void> {
+    this.#gateway?.fechar();
+    this.#gateway = null;
+    this.#sessao = null;
+  }
+
+  /**
+   * Subscribes to a gateway event (`message.created`, `voice.joined`, …).
+   *
+   * @param nome Event name.
+   * @param ouvinte Handler; it may be async. Failures are logged, never thrown.
+   * @returns This bot, for chaining.
+   */
+  on<K extends keyof Eventos>(nome: K, ouvinte: Ouvinte<K>): this {
+    if (!this.#ouvintes.has(nome)) this.#ouvintes.set(nome, new Set());
+    this.#ouvintes.get(nome)!.add(ouvinte as (dados: never) => void);
+    return this;
+  }
+
+  /**
+   * Removes a listener previously registered with {@link on}.
+   *
+   * @param nome Event name.
+   * @param ouvinte The exact handler reference that was registered.
+   * @returns This bot, for chaining.
+   */
+  off<K extends keyof Eventos>(nome: K, ouvinte: Ouvinte<K>): this {
+    this.#ouvintes.get(nome)?.delete(ouvinte as (dados: never) => void);
+    return this;
+  }
+
+  /**
+   * Fans an event out to its listeners.
+   *
+   * Listener failures (a sync throw or a rejected promise) are logged and
+   * swallowed, so one broken handler cannot stop the others.
+   *
+   * @param nome Event name.
+   * @param dados Event payload.
+   */
+  #despachar<K extends keyof Eventos>(nome: K, dados: Eventos[K]): void {
+    if (nome === "message.created") this.#talvezComando(dados as Eventos["message.created"]);
+    for (const ouvinte of this.#ouvintes.get(nome) ?? []) {
+      try {
+        const resultado = (ouvinte as (d: Eventos[K]) => unknown)(dados);
+        if (resultado instanceof Promise) resultado.catch((erro) => this.#log(`ouvinte falhou: ${erro}`));
+      } catch (erro) {
+        this.#log(`ouvinte falhou: ${erro}`);
+      }
+    }
+  }
+
+  // ---- commands (the everyday `!tocar`)
+
+  /**
+   * Registers a command.
+   *
+   * The channel prefix (`!`) belongs to the server: here the name is just
+   * `tocar`. Without `canais`, the command works in every channel where the bot
+   * may speak. Every registered command is announced to the client's
+   * autocomplete, including ones registered after `start()`.
+   *
+   * @param nome Command name; a leading `!` or `/` is stripped.
+   * @param opcoesOuFn Either the options object or the handler itself.
+   * @param talvezFn Handler, when the second argument carries the options.
+   * @returns This bot, for chaining.
+   * @throws {Error} When no handler is provided.
+   *
+   * @example
+   * ```ts
+   * bot.command("ping", async ({ responder }) => {
+   *   await responder("pong");
+   * });
+   *
+   * bot.command("eco", { descricao: "repete o texto" }, async ({ resto, responder }) => {
+   *   await responder(resto);
+   * });
+   * ```
+   */
+  command(
+    nome: string,
+    opcoesOuFn:
+      | { descricao?: string; canais?: string[] }
+      | ((contexto: ContextoDoComando) => void | Promise<void>),
+    talvezFn?: (contexto: ContextoDoComando) => void | Promise<void>,
+  ): this {
+    const opcoes = typeof opcoesOuFn === "function" ? {} : opcoesOuFn;
+    const executar = typeof opcoesOuFn === "function" ? opcoesOuFn : talvezFn;
+    if (!executar) throw new Error(`O comando ${nome} não tem o que executar.`);
+    this.#comandos.push({
+      nome: nome.replace(/^[!\/]/, "").toLowerCase(),
+      ...(opcoes.descricao ? { descricao: opcoes.descricao } : {}),
+      canais: (opcoes.canais ?? []).map((c) => c.toUpperCase()),
+      executar,
+    });
+    // Announced here and not only in `start()`: a command registered after
+    // connecting must reach the autocomplete too.
+    this.#anunciarComandos();
+    return this;
+  }
+
+  /**
+   * Builds the list announced on `identify`: names and descriptions only, no handlers.
+   *
+   * It also pushes the list to a live gateway, so a command registered after
+   * `start()` appears in the client's autocomplete without reconnecting.
+   *
+   * @returns The list of commands to announce.
+   */
+  #anunciarComandos(): ComandoAnunciado[] {
+    const anunciados = this.#comandos.map(({ nome, descricao }) =>
+      descricao ? { nome, descricao } : { nome },
+    );
+    // Already connected: send the new list without reconnecting (the client's
+    // autocomplete updates immediately).
+    if (this.#gateway?.estado === "pronto")
+      this.#gateway.agir("comandos", { comandos: anunciados });
+    return anunciados;
+  }
+
+  /** Registered commands, in registration order (handy in a `!help` command). */
+  get comandos(): { nome: string; descricao?: string }[] {
+    return this.#comandos.map(({ nome, descricao }) =>
+      descricao ? { nome, descricao } : { nome },
+    );
+  }
+
+  /**
+   * Tries to run a command for a message that just arrived.
+   *
+   * Prefix handling, channel filtering and "the bot never runs its own
+   * commands" all live here.
+   *
+   * @param mensagem The `message.created` payload that just arrived.
+   */
+  #talvezComando(mensagem: Eventos["message.created"]): void {
+    if (!mensagem.texto || !mensagem.sala) return;
+    // The bot does not run its own commands: otherwise `!eco !eco …` would loop.
+    if (mensagem.autorBot && mensagem.autorId === this.#descoberta?.bot.id) return;
+    const canal = this.#descoberta?.canais.texto.find((c) => c.code === mensagem.sala);
+    if (!canal) return;
+    const texto = mensagem.texto.trim();
+    const prefixo = canal.prefixo;
+    // Without a channel prefix, the command is simply the first token ("tocar x").
+    const semPrefixo = prefixo && texto.startsWith(prefixo) ? texto.slice(prefixo.length) : texto;
+    if (prefixo && !texto.startsWith(prefixo)) return;
+    const [bruto = "", ...args] = semPrefixo.split(/\s+/);
+    const nome = bruto.toLowerCase();
+    const comando = this.#comandos.find(
+      (c) => c.nome === nome && (c.canais.length === 0 || c.canais.includes(canal.code)),
+    );
+    if (!comando) return;
+    const contexto: ContextoDoComando = {
+      mensagem,
+      canal,
+      args,
+      resto: semPrefixo.slice(bruto.length).trim(),
+      responder: (resposta) => this.enviar(canal.code, resposta),
+      apagar: () => this.#http.apagar(canal.code, mensagem.id, this.#sessao?.sessao),
+    };
+    Promise.resolve(comando.executar(contexto)).catch((erro: Error) =>
+      this.#log(`comando ${comando.nome} falhou: ${erro.message}`),
+    );
+  }
+
+  // ---- messages
+
+  /**
+   * Sends a text message.
+   *
+   * It goes over HTTP on purpose: the response carries the created item (id,
+   * timestamp), and the gateway delivers `message.created` to everyone anyway.
+   *
+   * @param canal Channel code (case-insensitive; uppercased before sending).
+   * @param texto Message content.
+   * @returns The message the server created.
+   * @throws {ErroDaApi} When the bot cannot post in the channel.
+   */
+  enviar(canal: string, texto: string): Promise<Mensagem> {
+    return this.#http.enviar(canal.toUpperCase(), texto, this.#sessao?.sessao);
+  }
+
+  /**
+   * Sends audio as a **voice message** — the item the client renders as a
+   * "voice message" and plays inline.
+   *
+   * @param canal Channel code.
+   * @param audio The audio bytes (WAV by default; see `wavDeTom`).
+   * @param opcoes File name and MIME type; defaults to `recado.wav` / `audio/wav`.
+   * @returns The message the server created.
+   * @throws {ErroDaApi} When the upload fails.
+   */
+  enviarVoz(
+    canal: string,
+    audio: Uint8Array,
+    opcoes: { nome?: string; mime?: string } = {},
+  ): Promise<Mensagem> {
+    return this.#http.enviarArquivo(canal.toUpperCase(), audio, {
+      nome: opcoes.nome ?? "recado.wav",
+      mime: opcoes.mime ?? "audio/wav",
+      tipo: "voz",
+      sessao: this.#sessao?.sessao,
+    });
+  }
+
+  /**
+   * Sends any other file (image, PDF, audio as a regular attachment).
+   *
+   * @param canal Channel code.
+   * @param conteudo File bytes.
+   * @param opcoes File name and MIME type; defaults to `arquivo` /
+   * `application/octet-stream`.
+   * @returns The message the server created.
+   * @throws {ErroDaApi} When the upload fails.
+   */
+  enviarArquivo(
+    canal: string,
+    conteudo: Uint8Array,
+    opcoes: { nome?: string; mime?: string } = {},
+  ): Promise<Mensagem> {
+    return this.#http.enviarArquivo(canal.toUpperCase(), conteudo, {
+      nome: opcoes.nome ?? "arquivo",
+      mime: opcoes.mime ?? "application/octet-stream",
+      tipo: "arquivo",
+      sessao: this.#sessao?.sessao,
+    });
+  }
+
+  /**
+   * Reads a page of history (100 items; `antesDe` pages backwards).
+   *
+   * @param canal Channel code.
+   * @param antesDe Timestamp cursor: returns messages older than this one.
+   * @returns The page, plus `temMais` telling whether another page exists.
+   * @throws {ErroDaApi} When the bot cannot read the channel.
+   */
+  historico(canal: string, antesDe?: number) {
+    return this.#http.historico(canal.toUpperCase(), {
+      ...(antesDe ? { antesDe } : {}),
+      sessao: this.#sessao?.sessao,
+    });
+  }
+
+  /**
+   * Deletes a message the bot wrote.
+   *
+   * @param canal Channel code.
+   * @param id Message id.
+   * @throws {ErroDaApi} When the message is not the bot's or is already gone.
+   */
+  apagar(canal: string, id: string): Promise<void> {
+    return this.#http.apagar(canal.toUpperCase(), id, this.#sessao?.sessao);
+  }
+
+  /**
+   * Re-runs only the discovery step (e.g. after changing channels in the panel).
+   *
+   * @returns The fresh discovery document.
+   * @throws {ErroDaApi} When the token is rejected.
+   */
+  async recarregar(): Promise<Descoberta> {
+    this.#descoberta = await this.#http.descobrir();
+    return this.#descoberta;
+  }
+}
+
+export { ErroDaApi };