@openvertice/bot-sdk 0.0.0-stage → 0.1.0

package/src/gateway.ts

@@ -0,0 +1,354 @@
+// The gateway: one WebSocket, the `{op, t, d, s}` envelope and nothing else. It
+// owns the heartbeat, the resume and the reconnection with growing backoff.
+//
+// It uses Node's global WebSocket (22+), so the SDK has no runtime dependency.
+// The interface is deliberately the browser's.
+import type { ComandoAnunciado, Eventos, Sessao } from "./tipos.js";
+
+/** `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;
+
+/** 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;
+
+/**
+ * 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;
+}
+
+/** Gateway frame: `op` is mandatory, every other field depends on the op code. */
+interface Envelope {
+  op: number;
+  t?: string;
+  d?: unknown;
+  s?: number;
+}
+
+/**
+ * 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 {
+  #ws: WebSocket | null = null;
+  #sessao: Sessao | null = null;
+  #seq = 0;
+  #batida: ReturnType<typeof setInterval> | null = null;
+  #vigia: ReturnType<typeof setTimeout> | null = null;
+  #recuo: ReturnType<typeof setTimeout> | null = null;
+  #tentativa = 0;
+  #encerrado = false;
+  #estado: EstadoDoGateway = "conectando";
+
+  /** @param opcoes Endpoints, credentials and hooks used by the connection. */
+  constructor(private readonly opcoes: OpcoesGateway) {}
+
+  /** Current connection state. */
+  get estado(): EstadoDoGateway {
+    return this.#estado;
+  }
+
+  /** Session in use, or `null` before the first connection attempt. */
+  get sessaoAtual(): Sessao | null {
+    return this.#sessao;
+  }
+
+  /**
+   * 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> {
+    this.#encerrado = false;
+    return this.#abrir();
+  }
+
+  /**
+   * Opens one socket attempt.
+   *
+   * Resolves on the first dispatched event — in practice `ready` — and rejects
+   * if the socket fails before that.
+   */
+  async #abrir(): Promise<void> {
+    this.#mudar("conectando");
+    const sessao = await this.opcoes.sessao();
+    this.#sessao = sessao;
+    return new Promise<void>((resolver, rejeitar) => {
+      let concluido = false;
+      const falhar = (erro: Error) => {
+        if (concluido) return;
+        concluido = true;
+        rejeitar(erro);
+      };
+      let ws: WebSocket;
+      try {
+        ws = new WebSocket(this.opcoes.url);
+      } catch (erro) {
+        falhar(erro instanceof Error ? erro : new Error(String(erro)));
+        return;
+      }
+      this.#ws = ws;
+
+      ws.addEventListener("error", () =>
+        falhar(new Error("não consegui abrir o gateway")),
+      );
+      ws.addEventListener("message", (evento) => {
+        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, () => {
+          if (concluido) return;
+          concluido = true;
+          resolver();
+        });
+      });
+      ws.addEventListener("close", (evento) => {
+        this.#aoFechar(evento.code, evento.reason);
+        if (this.#encerrado) falhar(new Error("gateway encerrado"));
+      });
+    });
+  }
+
+  /**
+   * 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: WebSocket, sessao: Sessao): void {
+    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: MessageEvent): Envelope | null {
+    try {
+      const bruto = typeof evento.data === "string" ? evento.data : String(evento.data);
+      const envelope = JSON.parse(bruto) as Envelope;
+      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: Envelope, aoPronto: () => void): void {
+    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 as keyof Eventos,
+      envelope.d as Eventos[keyof Eventos],
+    );
+  }
+
+  /**
+   * 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 {
+    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"): void {
+    this.#encerrado = true;
+    this.#limpar();
+    try {
+      this.#ws?.close(codigo, motivo);
+    } catch {
+      /* it was already closing */
+    }
+    this.#ws = null;
+    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: EstadoDoGateway, detalhe?: string): void {
+    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(): void {
+    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(): void {
+    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?.();
+  }
+
+  /**
+   * Decides what to do when the socket closes: come back or stop for good.
+   *
+   * @param codigo WebSocket close code.
+   * @param motivo Close reason, used in the log and in the state detail.
+   */
+  #aoFechar(codigo: number, motivo: string): void {
+    this.#limpar();
+    this.#ws = null;
+    if (this.#encerrado) return;
+    if (DEFINITIVOS.has(codigo)) {
+      this.#mudar("recusado", `${codigo}: ${motivo}`);
+      this.#encerrado = true;
+      return;
+    }
+    if (codigo === OUTRA_CONEXAO) {
+      this.#mudar("recusado", "outra conexão assumiu este bot");
+      this.#encerrado = true;
+      return;
+    }
+    if (codigo === SESSAO_ENCERRADA) {
+      this.#mudar("recusado", "a sessão foi encerrada (token girado ou bot desativado)");
+      this.#encerrado = true;
+      return;
+    }
+    // 4002 (expired session) and network drops: renew the session and come back.
+    this.#tentativa += 1;
+    const espera = Math.min(30_000, 500 * 2 ** Math.min(this.#tentativa, 6));
+    this.#mudar(
+      "reconectando",
+      `${codigo || "sem código"}: volta em ${espera} ms (tentativa ${this.#tentativa})`,
+    );
+    this.#recuo = setTimeout(() => {
+      if (this.#encerrado) return;
+      // On an expired session, the client's `sessao()` already asks for another one.
+      this.#abrir().catch((erro: Error) =>
+        this.#mudar("reconectando", `falhou: ${erro.message}`),
+      );
+    }, espera);
+    this.#recuo.unref?.();
+  }
+
+  /** Clears every timer, so a closed gateway leaves no handles behind. */
+  #limpar(): void {
+    if (this.#batida) clearInterval(this.#batida);
+    if (this.#vigia) clearTimeout(this.#vigia);
+    if (this.#recuo) clearTimeout(this.#recuo);
+    this.#batida = null;
+    this.#vigia = null;
+    this.#recuo = null;
+  }
+}

package/src/http.ts

@@ -0,0 +1,249 @@
+// Bot HTTP layer: discovery, session and the message routes. Dependency-free:
+// `fetch` is global on Node 22+.
+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 class ErroDaApi extends Error {
+  /**
+   * @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,
+    readonly status: number,
+    readonly codigo: string | null = null,
+  ) {
+    super(mensagem);
+    this.name = "ErroDaApi";
+  }
+}
+
+/** 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;
+}
+
+/** Trailing slashes, removed so every path can safely start with `/`. */
+const SEM_BARRA = /\/+$/;
+
+/**
+ * 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 class Http {
+  readonly #base: string;
+  readonly #token: string;
+  readonly #fetch: typeof fetch;
+
+  /**
+   * @param options Base URL, bot token and an optional `fetch` implementation.
+   * @throws {Error} When the token is missing or empty.
+   */
+  constructor({ baseUrl = "http://localhost:8080", token, fetch: buscar }: OpcoesHttp) {
+    if (!token) throw new Error("Falta o token do bot (o `vtb_…` do painel).");
+    this.#base = baseUrl.replace(SEM_BARRA, "");
+    this.#token = token;
+    this.#fetch = buscar ?? globalThis.fetch;
+  }
+
+  /**
+   * Performs a JSON request and unwraps the response.
+   *
+   * @typeParam T Expected shape of the response body.
+   * @param caminho Path relative to the base URL (e.g. `/api/bots/gateway`).
+   * @param options HTTP method, session token and JSON body.
+   * @returns The parsed body, or `null` when the server sent no content.
+   * @throws {ErroDaApi} When the response status is not 2xx.
+   */
+  async #pedir<T>(
+    caminho: string,
+    {
+      metodo = "GET",
+      sessao,
+      corpo,
+    }: { metodo?: string; sessao?: string; corpo?: unknown } = {},
+  ): Promise<T> {
+    const cabecalhos: Record<string, string> = {
+      Accept: "application/json",
+      // The bot token always works; the session only once one is in hand.
+      Authorization: sessao ? `Bearer ${sessao}` : `Bot ${this.#token}`,
+    };
+    let envio: string | undefined;
+    if (corpo !== undefined) {
+      cabecalhos["Content-Type"] = "application/json";
+      envio = JSON.stringify(corpo);
+    }
+    const resposta = await this.#fetch(this.#base + caminho, {
+      method: metodo,
+      headers: cabecalhos,
+      body: envio,
+    });
+    const texto = await resposta.text();
+    let dados: unknown = null;
+    try {
+      dados = texto ? JSON.parse(texto) : null;
+    } catch {
+      dados = null;
+    }
+    if (!resposta.ok) {
+      const erro = (dados ?? {}) as { erro?: string; codigo?: string };
+      throw new ErroDaApi(
+        erro.erro ?? `O servidor respondeu ${resposta.status}.`,
+        resposta.status,
+        erro.codigo ?? null,
+      );
+    }
+    return dados as T;
+  }
+
+  /**
+   * 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> {
+    return this.#pedir<Descoberta>("/api/bots/gateway");
+  }
+
+  /**
+   * 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> {
+    return this.#pedir<Sessao>("/api/bots/session", { metodo: "POST" });
+  }
+
+  /**
+   * 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.
+   */
+  async enviar(code: string, texto: string, sessao?: string): Promise<Mensagem> {
+    const resposta = await this.#pedir<{ mensagem: Mensagem }>(
+      `/api/bots/channels/${encodeURIComponent(code)}/messages`,
+      { metodo: "POST", sessao, corpo: { content: texto } },
+    );
+    return resposta.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 }> {
+    const consulta = antesDe ? `?antesDe=${antesDe}` : "";
+    return this.#pedir(
+      `/api/bots/channels/${encodeURIComponent(code)}/messages${consulta}`,
+      { sessao },
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async enviarArquivo(
+    code: string,
+    corpo: Uint8Array,
+    {
+      nome = "arquivo",
+      mime = "application/octet-stream",
+      tipo = "arquivo",
+      sessao,
+    }: { nome?: string; mime?: string; tipo?: "arquivo" | "voz"; sessao?: string } = {},
+  ): Promise<Mensagem> {
+    const resposta = await this.#fetch(
+      `${this.#base}/api/bots/channels/${encodeURIComponent(code)}/messages`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: sessao ? `Bearer ${sessao}` : `Bot ${this.#token}`,
+          "Content-Type": mime,
+          // The server undoes the percent-encoding, so accented names survive intact.
+          "X-Vertice-Nome": encodeURIComponent(nome),
+          "X-Vertice-Tipo": tipo,
+        },
+        body: corpo as unknown as BodyInit,
+      },
+    );
+    const texto = await resposta.text();
+    const dados = (() => {
+      try {
+        return JSON.parse(texto) as { mensagem?: Mensagem; erro?: string; codigo?: string };
+      } catch {
+        return {} as { mensagem?: Mensagem; erro?: string; codigo?: string };
+      }
+    })();
+    if (!resposta.ok || !dados.mensagem)
+      throw new ErroDaApi(
+        dados.erro ?? `O servidor respondeu ${resposta.status}.`,
+        resposta.status,
+        dados.codigo ?? null,
+      );
+    return dados.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.
+   */
+  async apagar(code: string, id: string, sessao?: string): Promise<void> {
+    await this.#pedir<null>(
+      `/api/bots/messages/${encodeURIComponent(id)}?canal=${encodeURIComponent(code)}`,
+      { metodo: "DELETE", sessao },
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async intents(): Promise<Intencao[]> {
+    return (await this.descobrir()).intents;
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+// Vértice bot SDK entry point (`@openvertice/bot-sdk`). The contract belongs to
+// the server (server/bots/README.md); this module exports only what a bot needs
+// in order to exist.
+/**
+ * Public surface of `@openvertice/bot-sdk`.
+ *
+ * Everything a bot needs lives behind this module: the {@link Bot} client, the
+ * {@link Voz} mesh client, the contract types and the audio helpers.
+ */
+export { Bot, ErroDaApi } from "./cliente.js";
+export type { ContextoDoComando, OpcoesDoBot } from "./cliente.js";
+export type { EstadoDoGateway, OpcoesGateway } from "./gateway.js";
+export type {
+  AnexoDaMensagem,
+  CanalDeTexto,
+  CanalDeVoz,
+  Descoberta,
+  Eventos,
+  Intencao,
+  Limites,
+  Mensagem,
+  PeerDaVoz,
+  PreviaDeLink,
+  ServidorIce,
+  Sessao,
+  SinalDeVoz,
+} from "./tipos.js";
+export { CONTRATO } from "./tipos.js";
+export { Voz } from "./voz.js";
+export type {
+  ConexaoDeVoz,
+  EntradaNaVoz,
+  FonteDeAudio,
+  OpcoesDeVoz,
+  TransporteDeVoz,
+} from "./voz.js";
+export { criarTransporteWrtc } from "./voz-wrtc.js";
+export { tocarTom } from "./audio.js";
+export type { OpcoesDoTom } from "./audio.js";
+export { wavDeTom } from "./wav.js";
+export type { OpcoesDoWav } from "./wav.js";