@openvertice/bot-sdk 0.0.0-stage → 0.1.1

package/dist/src/gateway.js

@@ -0,0 +1,431 @@
+/** `WebSocket.readyState` for an open socket. */
+const ABERTO = 1;
+/** How long without any server frame before the connection is assumed dead. */
+const SEM_SINAL_MS = 90_000;
+/** Deadline for a new socket to answer `hello`/`ready` before the attempt is abandoned. */
+const SEM_RESPOSTA_MS = 15_000;
+/** Codes where retrying is pointless: the server refused the bot. */
+const DEFINITIVOS = new Set([4001, 4003, 4005]);
+/** Another connection took over this bot: reconnecting would fight over it. */
+const OUTRA_CONEXAO = 4000;
+/** Session closed (rotated token, disabled bot): it does not come back on its own. */
+const SESSAO_ENCERRADA = 4009;
+/** Expired session: renew the token and come back. */
+const SESSAO_EXPIRADA = 4002;
+/**
+ * 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 class Gateway {
+    opcoes;
+    #ws = null;
+    #sessao = null;
+    #seq = 0;
+    #batida = null;
+    #vigia = null;
+    /** Deadline of the attempt in progress (waiting for `hello`/`ready`). */
+    #prazo = null;
+    /** Backoff timer between attempts. */
+    #recuo = null;
+    /** Wakes the backoff early, so `fechar()` can settle a sleeping `conectar()`. */
+    #acordar = null;
+    /** Connection cycle in progress; one at a time, no matter who asks. */
+    #corrida = null;
+    #tentativa = 0;
+    #encerrado = false;
+    #estado = "conectando";
+    /** @param opcoes Endpoints, credentials and hooks used by the connection. */
+    constructor(opcoes) {
+        this.opcoes = opcoes;
+    }
+    /** Current connection state. */
+    get estado() {
+        return this.#estado;
+    }
+    /** Session in use, or `null` before the first connection attempt. */
+    get sessaoAtual() {
+        return this.#sessao;
+    }
+    /**
+     * Opens the socket and resolves once the bot is identified (`ready`).
+     *
+     * Transient failures — network drops, an unreachable server, a session that
+     * could not be renewed, a gateway that never answers — are retried with
+     * exponential backoff until the bot is ready. Only a definitive refusal (or
+     * {@link fechar}) stops the loop.
+     *
+     * @returns A promise that settles when the gateway is truly ready.
+     * @throws {Error} When the server refuses the bot or the gateway was closed.
+     */
+    conectar() {
+        this.#encerrado = false;
+        // Already identified: nothing to open, and a healthy socket is not replaced.
+        if (this.#estado === "pronto")
+            return Promise.resolve();
+        if (this.#corrida)
+            return this.#corrida;
+        // A manual start begins with the short backoff again.
+        this.#tentativa = 0;
+        return this.#iniciarCiclo();
+    }
+    /**
+     * Starts a connection cycle, or joins the one already running.
+     *
+     * @returns The cycle promise; it settles on `ready`, on a definitive refusal
+     * or when {@link fechar} is called.
+     */
+    #iniciarCiclo() {
+        if (this.#corrida)
+            return this.#corrida;
+        const corrida = this.#manterConectado().finally(() => {
+            if (this.#corrida === corrida)
+                this.#corrida = null;
+        });
+        this.#corrida = corrida;
+        return corrida;
+    }
+    /**
+     * Attempts the connection and retries until `ready` or a definitive refusal.
+     *
+     * Every failure comes back through here — including the ones that happen
+     * before a socket exists, such as a session that could not be renewed. It is
+     * a loop on purpose: a single retry used to end the reconnection, leaving the
+     * bot offline for good.
+     */
+    async #manterConectado() {
+        for (;;) {
+            // `fechar()` may have run while we were sleeping in the backoff.
+            if (this.#encerrado)
+                throw new Error("gateway encerrado");
+            try {
+                await this.#abrir();
+                return;
+            }
+            catch (erro) {
+                if (this.#encerrado)
+                    throw erro;
+                await this.#esperarRecuo(erro);
+            }
+        }
+    }
+    /**
+     * Waits out the backoff before the next attempt.
+     *
+     * The wait is interruptible: {@link fechar} wakes it, so a `conectar()` call
+     * sleeping here settles instead of hanging until the timer fires.
+     *
+     * @param erro Failure that triggered the wait; it goes into the state detail.
+     */
+    async #esperarRecuo(erro) {
+        this.#tentativa += 1;
+        const espera = Math.min(30_000, 500 * 2 ** Math.min(this.#tentativa, 6));
+        this.#mudar("reconectando", `${mensagemDe(erro)}: volta em ${espera} ms (tentativa ${this.#tentativa})`);
+        await new Promise((resolver) => {
+            this.#acordar = () => {
+                this.#acordar = null;
+                if (this.#recuo)
+                    clearTimeout(this.#recuo);
+                this.#recuo = null;
+                resolver();
+            };
+            this.#recuo = setTimeout(() => this.#acordar?.(), espera);
+            this.#recuo.unref?.();
+        });
+    }
+    /**
+     * Opens one socket attempt.
+     *
+     * Resolves on `ready` and rejects on any failure before it (socket error,
+     * close, no answer within {@link SEM_RESPOSTA_MS}, session error), which is
+     * what lets {@link #manterConectado} decide when to try again.
+     */
+    async #abrir() {
+        this.#mudar("conectando");
+        const sessao = await this.opcoes.sessao();
+        // `fechar()` may have run while the session was being fetched: do not open
+        // a socket that nobody is waiting for.
+        if (this.#encerrado)
+            throw new Error("gateway encerrado");
+        this.#sessao = sessao;
+        return new Promise((resolver, rejeitar) => {
+            let concluido = false;
+            const concluir = (erro) => {
+                if (concluido)
+                    return;
+                concluido = true;
+                if (this.#prazo)
+                    clearTimeout(this.#prazo);
+                this.#prazo = null;
+                if (erro)
+                    rejeitar(erro);
+                else
+                    resolver();
+            };
+            let ws;
+            try {
+                ws = new WebSocket(this.opcoes.url);
+            }
+            catch (erro) {
+                concluir(erro instanceof Error ? erro : new Error(String(erro)));
+                return;
+            }
+            this.#ws = ws;
+            // A socket that opens but never answers would hang this attempt (and the
+            // retry loop) forever; the deadline settles it as a failure.
+            this.#prazo = setTimeout(() => {
+                this.#prazo = null;
+                if (this.#ws !== ws)
+                    return;
+                try {
+                    ws.close(4000, "sem resposta");
+                }
+                catch {
+                    /* it had already dropped */
+                }
+                concluir(new Error("o gateway não respondeu ao `identify`"));
+            }, SEM_RESPOSTA_MS);
+            this.#prazo.unref?.();
+            ws.addEventListener("error", () => {
+                if (this.#ws !== ws)
+                    return;
+                concluir(new Error("não consegui abrir o gateway"));
+            });
+            ws.addEventListener("message", (evento) => {
+                if (this.#ws !== ws)
+                    return;
+                const envelope = this.#ler(evento);
+                if (!envelope)
+                    return;
+                this.#armarVigia();
+                // hello: now it is safe to identify (or to resume, if a seq exists).
+                if (envelope.op === 10) {
+                    this.#identificar(ws, sessao);
+                    return;
+                }
+                this.#receber(envelope, () => concluir());
+            });
+            ws.addEventListener("close", (evento) => {
+                // A close from a socket that is no longer the current one is residue
+                // from a previous attempt: it must not touch the live connection.
+                if (this.#ws !== ws)
+                    return;
+                const estavaPronto = this.#estado === "pronto";
+                const definitivo = this.#aoFechar(evento.code, evento.reason);
+                concluir(new Error(this.#estado === "encerrado"
+                    ? "gateway encerrado"
+                    : `gateway ${definitivo ? "recusado" : "caiu"} (${evento.code})`));
+                // After `ready` there is no attempt left to fail — the loop already
+                // returned — so a drop has to start a new cycle.
+                if (!definitivo && estavaPronto) {
+                    this.#corrida = null;
+                    void this.#iniciarCiclo().catch(() => { });
+                }
+            });
+        });
+    }
+    /**
+     * Sends `identify` (op 2) on a fresh connection, or `resume` (op 6) when a
+     * sequence number from a previous connection is available.
+     *
+     * @param ws Socket already past `hello`.
+     * @param sessao Session to present to the server.
+     */
+    #identificar(ws, sessao) {
+        const comandos = this.opcoes.comandos ?? [];
+        const envelope = this.#seq > 0
+            ? { op: 6, d: { sessao: sessao.sessao, seq: this.#seq, comandos } }
+            : {
+                op: 2,
+                d: { sessao: sessao.sessao, intents: this.opcoes.intents, comandos },
+            };
+        ws.send(JSON.stringify(envelope));
+    }
+    /**
+     * Parses one socket frame, discarding anything that is not a valid envelope.
+     *
+     * @param evento Raw `message` event from the socket.
+     * @returns The envelope, or `null` when the payload is not JSON or has no `op`.
+     */
+    #ler(evento) {
+        try {
+            const bruto = typeof evento.data === "string" ? evento.data : String(evento.data);
+            const envelope = JSON.parse(bruto);
+            return typeof envelope?.op === "number" ? envelope : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Handles one gateway frame.
+     *
+     * op 0 is a dispatch, op 11 is the heartbeat ack and everything else is
+     * ignored here.
+     *
+     * @param envelope Frame received from the socket.
+     * @param aoPronto Called once, as soon as `ready` marks the bot as connected.
+     */
+    #receber(envelope, aoPronto) {
+        if (envelope.op === 11)
+            return;
+        if (envelope.op !== 0 || !envelope.t)
+            return;
+        if (typeof envelope.s === "number")
+            this.#seq = envelope.s;
+        if (envelope.t === "ready") {
+            this.#tentativa = 0;
+            this.#mudar("pronto");
+            this.#bater();
+            aoPronto();
+        }
+        this.opcoes.aoEvento(envelope.t, envelope.d);
+    }
+    /**
+     * 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, dados = {}) {
+        const ws = this.#ws;
+        if (!ws || ws.readyState !== ABERTO)
+            throw new Error("O gateway não está conectado.");
+        ws.send(JSON.stringify({ op: 4, d: { tipo, ...dados } }));
+    }
+    /**
+     * 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 = 1000, motivo = "pedido do bot") {
+        this.#encerrado = true;
+        this.#limpar();
+        // Nothing else to wait for: wake a `conectar()` that is sleeping in backoff.
+        this.#acordar?.();
+        try {
+            this.#ws?.close(codigo, motivo);
+        }
+        catch {
+            /* it was already closing */
+        }
+        // `#ws` is cleared by the close handler: it has to settle the attempt in
+        // progress, otherwise a `conectar()` waiting on it would never return.
+        this.#mudar("encerrado");
+    }
+    /**
+     * Stores the new state, notifies the bot and logs the detail, when there is one.
+     *
+     * @param estado New connection state.
+     * @param detalhe Optional human-readable explanation for logs and errors.
+     */
+    #mudar(estado, detalhe) {
+        this.#estado = estado;
+        this.opcoes.aoEstado?.(estado, detalhe);
+        if (detalhe)
+            this.opcoes.log?.(`[${estado}] ${detalhe}`);
+    }
+    /**
+     * (Re)starts the heartbeat timer, sending op 1 with the last sequence number.
+     *
+     * The interval is left `unref`'d so it never keeps the process alive.
+     */
+    #bater() {
+        if (this.#batida)
+            clearInterval(this.#batida);
+        this.#batida = setInterval(() => {
+            const ws = this.#ws;
+            if (!ws || ws.readyState !== ABERTO)
+                return;
+            ws.send(JSON.stringify({ op: 1, d: this.#seq }));
+        }, this.opcoes.heartbeatMs);
+        this.#batida.unref?.();
+    }
+    /**
+     * With nothing from the server for more than 90 s, the connection died
+     * silently (proxy, NAT). Drops it so the reconnect logic kicks in: it is the
+     * same deadline the server uses.
+     */
+    #armarVigia() {
+        if (this.#vigia)
+            clearTimeout(this.#vigia);
+        this.#vigia = setTimeout(() => {
+            if (this.#estado === "encerrado")
+                return;
+            this.opcoes.log?.("sem sinal do servidor; reconectando");
+            try {
+                this.#ws?.close(4000, "sem sinal");
+            }
+            catch {
+                /* it had already dropped */
+            }
+        }, SEM_SINAL_MS);
+        this.#vigia.unref?.();
+    }
+    /**
+     * Applies the close policy: stop for good or let the caller reconnect.
+     *
+     * @param codigo WebSocket close code.
+     * @param motivo Close reason, used in the log and in the state detail.
+     * @returns `true` when the bot must stop; `false` when a retry makes sense.
+     */
+    #aoFechar(codigo, motivo) {
+        this.#limpar();
+        this.#ws = null;
+        if (this.#encerrado)
+            return true;
+        if (DEFINITIVOS.has(codigo)) {
+            this.#mudar("recusado", `${codigo}: ${motivo}`);
+            this.#encerrado = true;
+            return true;
+        }
+        if (codigo === OUTRA_CONEXAO) {
+            this.#mudar("recusado", "outra conexão assumiu este bot");
+            this.#encerrado = true;
+            return true;
+        }
+        if (codigo === SESSAO_ENCERRADA) {
+            this.#mudar("recusado", "a sessão foi encerrada (token girado ou bot desativado)");
+            this.#encerrado = true;
+            return true;
+        }
+        // 4002 (expired session) and network drops: renew the session and come back.
+        return false;
+    }
+    /**
+     * Clears the timers of a live connection (heartbeat, silence watch, attempt
+     * deadline), so a closed gateway leaves no handles behind.
+     *
+     * The backoff timer is not touched here: it belongs to {@link #esperarRecuo},
+     * which is woken by {@link fechar}.
+     */
+    #limpar() {
+        if (this.#batida)
+            clearInterval(this.#batida);
+        if (this.#vigia)
+            clearTimeout(this.#vigia);
+        if (this.#prazo)
+            clearTimeout(this.#prazo);
+        this.#batida = null;
+        this.#vigia = null;
+        this.#prazo = null;
+    }
+}
+/**
+ * Turns any thrown value into a printable message.
+ *
+ * @param erro Value thrown or rejected.
+ * @returns `erro.message` for `Error`s, `String(erro)` otherwise.
+ */
+const mensagemDe = (erro) => erro instanceof Error ? erro.message : String(erro);
+//# sourceMappingURL=gateway.js.map

package/dist/src/gateway.js.map

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

package/dist/src/http.d.ts

@@ -0,0 +1,119 @@
+import type { Descoberta, Intencao, Mensagem, Sessao } from "./tipos.js";
+/**
+ * Error thrown for every non-2xx response from the bot API.
+ *
+ * It carries the HTTP status and, when the server sends one, the machine-readable
+ * `codigo` (e.g. `"canal"`, `"voz"`), so callers can react to the cause instead
+ * of parsing the message.
+ */
+export declare class ErroDaApi extends Error {
+    readonly status: number;
+    readonly codigo: string | null;
+    /**
+     * @param mensagem Human-readable message taken from the server payload.
+     * @param status HTTP status code of the failed response.
+     * @param codigo Server error code, when the payload provided one.
+     */
+    constructor(mensagem: string, status: number, codigo?: string | null);
+}
+/** Credentials and transport used by every {@link Http} call. */
+export interface OpcoesHttp {
+    /** Server base URL, e.g. `https://vertice.example` (default: `http://localhost:8080`). */
+    baseUrl?: string;
+    /** Bot token (`vtb_…`), copied from the admin panel. */
+    token: string;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * Minimal HTTP client for the `/api/bots/*` routes.
+ *
+ * Requests authenticate as `Bot <token>` until a session exists, then as
+ * `Bearer <sessao>` — the form the server expects on message routes. There is
+ * no runtime dependency: it uses the global `fetch` from Node 22+.
+ */
+export declare class Http {
+    #private;
+    /**
+     * @param options Base URL, bot token and an optional `fetch` implementation.
+     * @throws {Error} When the token is missing or empty.
+     */
+    constructor({ baseUrl, token, fetch: buscar }: OpcoesHttp);
+    /**
+     * Fetches the discovery document: what this bot may do, as configured in the panel.
+     *
+     * @returns Channels, intents, ICE servers and rate limits granted to the bot.
+     * @throws {ErroDaApi} When the token is rejected.
+     */
+    descobrir(): Promise<Descoberta>;
+    /**
+     * Exchanges the bot token for a short-lived session (15 minutes).
+     *
+     * The SDK renews it on its own shortly before it expires.
+     *
+     * @returns The new session and its expiry.
+     * @throws {ErroDaApi} When the token is invalid or the bot is disabled.
+     */
+    abrirSessao(): Promise<Sessao>;
+    /**
+     * Posts a text message over HTTP (the gateway can do the same over WebSocket).
+     *
+     * @param code Channel code.
+     * @param texto Message content.
+     * @param sessao Session token; when absent, the bot token is used.
+     * @returns The message the server created (id, timestamp, …).
+     * @throws {ErroDaApi} When the channel does not exist or the bot cannot post.
+     */
+    enviar(code: string, texto: string, sessao?: string): Promise<Mensagem>;
+    /**
+     * Reads one page of channel history (up to 100 messages).
+     *
+     * @param code Channel code.
+     * @param options `antesDe` to page backwards; `sessao` to authenticate with a session.
+     * @returns The page, plus `temMais` telling whether another page exists.
+     * @throws {ErroDaApi} When the bot cannot read the channel.
+     */
+    historico(code: string, { antesDe, sessao }?: {
+        antesDe?: number;
+        sessao?: string;
+    }): Promise<{
+        sala: string;
+        mensagens: Mensagem[];
+        temMais: boolean;
+    }>;
+    /**
+     * Uploads a file (or a voice message) to a channel.
+     *
+     * The body goes raw, with the type in the headers — the same path the chat
+     * upload uses, without multipart.
+     *
+     * @param code Channel code.
+     * @param corpo File bytes.
+     * @param options File name, MIME type, whether it is a voice message, and session.
+     * @returns The message the server created.
+     * @throws {ErroDaApi} When the upload fails or the response carries no message.
+     */
+    enviarArquivo(code: string, corpo: Uint8Array, { nome, mime, tipo, sessao, }?: {
+        nome?: string;
+        mime?: string;
+        tipo?: "arquivo" | "voz";
+        sessao?: string;
+    }): Promise<Mensagem>;
+    /**
+     * Deletes one of the bot's own messages (the server refuses anyone else's).
+     *
+     * @param code Channel code the message belongs to.
+     * @param id Message id.
+     * @param sessao Session token; when absent, the bot token is used.
+     * @throws {ErroDaApi} When the message is not the bot's or is already gone.
+     */
+    apagar(code: string, id: string, sessao?: string): Promise<void>;
+    /**
+     * Lists the intents the server granted, for callers that want to check before connecting.
+     *
+     * @returns The intent names granted to this bot.
+     * @throws {ErroDaApi} When discovery fails.
+     */
+    intents(): Promise<Intencao[]>;
+}
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/http.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAQhC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IARhC;;;;OAIG;gBAED,QAAQ,EAAE,MAAM,EACP,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAM,GAAG,IAAW;CAKxC;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAKD;;;;;;GAMG;AACH,qBAAa,IAAI;;IAKf;;;OAGG;gBACS,EAAE,OAAiC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU;IAyDnF;;;;;OAKG;IACH,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAIhC;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAI9B;;;;;;;;OAQG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQ7E;;;;;;;OAOG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9D,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAQrE;;;;;;;;;;;OAWG;IACG,aAAa,CACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,EACjB,EACE,IAAgB,EAChB,IAAiC,EACjC,IAAgB,EAChB,MAAM,GACP,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAClF,OAAO,CAAC,QAAQ,CAAC;IAgCpB;;;;;;;OAOG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtE;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;CAGrC"}