@openvertice/bot-sdk 0.0.0-stage → 0.1.0

package/dist/src/cliente.js

@@ -0,0 +1,381 @@
+// 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 } from "./gateway.js";
+/** Renews the session slightly before it expires, so it never dies mid-event. */
+const RENOVAR_ANTES_MS = 120_000;
+/**
+ * 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 {
+    #http;
+    #intents;
+    #log;
+    #ouvintes = new Map();
+    #comandos = [];
+    #ouvintesDeEstado = new Set();
+    #descoberta = null;
+    #sessao = null;
+    #gateway = null;
+    #ultimoErro = null;
+    /** @param opcoes Token, base URL and the intents this process wants. */
+    constructor(opcoes) {
+        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() {
+        return this.#descoberta?.bot ?? null;
+    }
+    /** Channels granted to the bot, or `null` before {@link start}. */
+    get canais() {
+        return this.#descoberta?.canais ?? null;
+    }
+    /** ICE servers from discovery (the bot's voice uses the same ones). */
+    get iceServers() {
+        return this.#descoberta?.iceServers ?? [];
+    }
+    /** Current gateway state, or `"parado"` before {@link start} and after {@link stop}. */
+    get estado() {
+        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) {
+        this.#ouvintesDeEstado.add(ouvinte);
+        return this;
+    }
+    /** Last connection error, for callers that want to show it in a `/status` command. */
+    get ultimoErro() {
+        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() {
+        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() {
+        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, dados = {}) {
+        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() {
+        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(nome, ouvinte) {
+        if (!this.#ouvintes.has(nome))
+            this.#ouvintes.set(nome, new Set());
+        this.#ouvintes.get(nome).add(ouvinte);
+        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(nome, ouvinte) {
+        this.#ouvintes.get(nome)?.delete(ouvinte);
+        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(nome, dados) {
+        if (nome === "message.created")
+            this.#talvezComando(dados);
+        for (const ouvinte of this.#ouvintes.get(nome) ?? []) {
+            try {
+                const resultado = ouvinte(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, opcoesOuFn, talvezFn) {
+        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() {
+        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() {
+        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) {
+        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 = {
+            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) => 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, texto) {
+        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, audio, opcoes = {}) {
+        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, conteudo, opcoes = {}) {
+        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, antesDe) {
+        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, id) {
+        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() {
+        this.#descoberta = await this.#http.descobrir();
+        return this.#descoberta;
+    }
+}
+export { ErroDaApi };
+//# sourceMappingURL=cliente.js.map

package/dist/src/cliente.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliente.js","sourceRoot":"","sources":["../../src/cliente.ts"],"names":[],"mappings":"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"}

package/dist/src/gateway.d.ts

@@ -0,0 +1,76 @@
+import type { ComandoAnunciado, Eventos, Sessao } from "./tipos.js";
+/**
+ * Connection states the bot can observe.
+ *
+ * - `conectando` — socket being opened and the bot identified.
+ * - `pronto` — `ready` received; events are flowing.
+ * - `reconectando` — waiting out the backoff before trying again.
+ * - `encerrado` — closed on purpose (`stop()`); no reconnect.
+ * - `recusado` — the server refused the bot; no reconnect.
+ */
+export type EstadoDoGateway = "conectando" | "pronto" | "reconectando" | "encerrado" | "recusado";
+/** Everything the gateway needs from the bot, plus its hooks. */
+export interface OpcoesGateway {
+    /** WebSocket URL from the discovery document. */
+    url: string;
+    /** Returns a valid session; called again when the current one expires. */
+    sessao: () => Promise<Sessao>;
+    /** Intents requested on `identify`. */
+    intents: string[];
+    /** Commands for the client's autocomplete; resent on every connection. */
+    comandos?: ComandoAnunciado[];
+    /** Heartbeat interval in milliseconds, as told by the server. */
+    heartbeatMs: number;
+    /** Called for every dispatched event (op 0). */
+    aoEvento: <K extends keyof Eventos>(t: K, d: Eventos[K]) => void;
+    /** Called on every state change, with an optional human-readable detail. */
+    aoEstado?: (estado: EstadoDoGateway, detalhe?: string) => void;
+    /** Diagnostic sink: one line per interesting step. */
+    log?: (mensagem: string) => void;
+}
+/**
+ * WebSocket client for the Vértice gateway.
+ *
+ * It speaks the `{op, t, d, s}` envelope: op 10 `hello`, op 2 `identify` (or
+ * op 6 `resume`), op 1 heartbeat, op 11 heartbeat ack, op 0 dispatch and op 4
+ * action. Heartbeat, session resume and reconnection with exponential backoff
+ * are handled here, so bot authors never have to.
+ *
+ * One instance per bot: `conectar()` resolves only after `ready` arrives.
+ */
+export declare class Gateway {
+    #private;
+    private readonly opcoes;
+    /** @param opcoes Endpoints, credentials and hooks used by the connection. */
+    constructor(opcoes: OpcoesGateway);
+    /** Current connection state. */
+    get estado(): EstadoDoGateway;
+    /** Session in use, or `null` before the first connection attempt. */
+    get sessaoAtual(): Sessao | null;
+    /**
+     * Opens the socket and resolves once the bot is identified (`ready`).
+     *
+     * @returns A promise that settles when the gateway is truly ready.
+     * @throws {Error} When the server refuses the bot or the socket cannot open.
+     */
+    conectar(): Promise<void>;
+    /**
+     * Sends an action (op 4) to the gateway.
+     *
+     * Voice uses this for `voz.entrar`, `voz.sair` and `voice.signal`; the same
+     * route carries `comandos` updates.
+     *
+     * @param tipo Action name understood by the server.
+     * @param dados Action payload, merged into `d`.
+     * @throws {Error} When the gateway is not connected.
+     */
+    agir(tipo: string, dados?: Record<string, unknown>): void;
+    /**
+     * Closes the connection on purpose: it will not reconnect.
+     *
+     * @param codigo WebSocket close code sent to the server.
+     * @param motivo Human-readable reason sent to the server.
+     */
+    fechar(codigo?: number, motivo?: string): void;
+}
+//# sourceMappingURL=gateway.d.ts.map

package/dist/src/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/gateway.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAgBpE;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,YAAY,GACZ,QAAQ,GACR,cAAc,GACd,WAAW,GACX,UAAU,CAAC;AAEf,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,uCAAuC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC9B,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACjE,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D,sDAAsD;IACtD,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAUD;;;;;;;;;GASG;AACH,qBAAa,OAAO;;IAYN,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,6EAA6E;gBAChD,MAAM,EAAE,aAAa;IAElD,gCAAgC;IAChC,IAAI,MAAM,IAAI,eAAe,CAE5B;IAED,qEAAqE;IACrE,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAE/B;IAED;;;;;OAKG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoHzB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAO7D;;;;;OAKG;IACH,MAAM,CAAC,MAAM,SAAO,EAAE,MAAM,SAAkB,GAAG,IAAI;CA6GtD"}