@openvertice/bot-sdk 0.0.0-stage → 0.1.0

package/src/tipos.ts

@@ -0,0 +1,220 @@
+// Types of the Vértice contract (server/bots/README.md, version 2026-10).
+// They are the boundary: if the server changes a field, it changes here too.
+
+/** Contract version this SDK implements. */
+export const CONTRATO = "2026-10";
+
+/** Gateway event families a bot may subscribe to. */
+export type Intencao = "MESSAGES" | "MEMBERS" | "ROOMS" | "PRESENCE";
+
+/** A text channel as the server grants it to this bot. */
+export interface CanalDeTexto {
+  /** Stable channel code used in every API call (for example `"MURAL"`). */
+  code: string;
+  /** Name people see ("Música"); falls back to `code` if the room is gone. */
+  nome: string;
+  /** Whether the bot may read what is posted here. */
+  escutar: boolean;
+  /** Whether the bot may post here. */
+  falar: boolean;
+  /** Command prefix of the channel; `null` = the bot receives everything it can hear. */
+  prefixo: string | null;
+}
+
+/** A voice channel the bot is allowed to join. */
+export interface CanalDeVoz {
+  code: string;
+  nome: string;
+}
+
+/** STUN/TURN server handed to the WebRTC peer connection. */
+export interface ServidorIce {
+  /** One URL or a list of them (`stun:`, `turn:`). */
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+/** Rate limits the server enforces for this bot. */
+export interface Limites {
+  /** Messages per minute. */
+  mensagensPorMinuto: number;
+  /** `identify` attempts per minute. */
+  identifyPorMinuto: number;
+  /** Session lifetime in seconds. */
+  sessaoSegundos: number;
+}
+
+/** Response of `GET /api/bots/gateway`: everything this bot is allowed to do. */
+export interface Descoberta {
+  /** Contract version the server speaks; compare it with `CONTRATO`. */
+  contrato: string;
+  /** The identity the server assigned to the bot. */
+  bot: { id: string; usuario: string; exibicao: string };
+  /** Where to connect and how often to send heartbeats. */
+  gateway: { versao: number; url: string; heartbeatMs: number };
+  /** Channels the panel granted, split by kind. */
+  canais: { texto: CanalDeTexto[]; voz: CanalDeVoz[] };
+  /** Event families the panel granted. */
+  intents: Intencao[];
+  /** ICE servers to use for voice. */
+  iceServers: ServidorIce[];
+  /** Effective rate limits. */
+  limites: Limites;
+}
+
+/** Response of `POST /api/bots/session`: a short-lived gateway credential. */
+export interface Sessao {
+  /** The session token, sent on `identify` and on message requests. */
+  sessao: string;
+  /** Expiry as a Unix timestamp in milliseconds. */
+  expiraEm: number;
+  /** Gateway endpoint and cadence to use with this session. */
+  gateway: { versao: number; url: string; heartbeatMs: number };
+}
+
+/** A file attached to a message. */
+export interface AnexoDaMensagem {
+  /** Original file name, as uploaded. */
+  nome: string;
+  /** MIME type. */
+  mime: string;
+  /** Size in bytes. */
+  tamanho: number;
+  /** Absolute URL to download the file. */
+  url: string;
+}
+
+/** Link preview the server resolved for a message. */
+export interface PreviaDeLink {
+  /** URL the preview was built from. */
+  url: string;
+  /** Page title, when the server could read one. */
+  titulo: string | null;
+  /** Page description, when available. */
+  descricao: string | null;
+  /** Preview image URL, when available. */
+  imagem: string | null;
+  /** Site name (host) shown next to the preview. */
+  site: string;
+}
+
+/** A message, as delivered by `message.created` and returned by the send routes. */
+export interface Mensagem {
+  /** Message id, unique inside the channel. */
+  id: string;
+  /** Code of the channel the message belongs to. */
+  sala?: string;
+  /** Display name of the author. */
+  autor: string;
+  /** Author id, used to tell the bot's own messages apart. */
+  autorId?: string | null;
+  /** `true` when the author is a bot — this one included. */
+  autorBot: boolean;
+  /** Kind of payload the message carries. */
+  tipo?: "texto" | "arquivo" | "voz";
+  /** Text content; `null` for attachments without a caption. */
+  texto: string | null;
+  /** Creation time as a Unix timestamp in milliseconds. */
+  criadaEm: number;
+  /** When the message was pinned, if it was. */
+  fixadaEm?: number | null;
+  /** Who pinned the message. */
+  fixadaPor?: string | null;
+  /** Attachment, when `tipo` is `arquivo` or `voz`. */
+  arquivo?: AnexoDaMensagem | null;
+  /** Resolved link preview, when the message contains a link. */
+  previa?: PreviaDeLink | null;
+}
+
+/**
+ * The payload of `voice.signal` — the raw WebRTC `signal`, untranslated.
+ *
+ * The SDP travels under two names because both sides of the protocol already
+ * existed: `sdp` is the bot contract's name (server/bots/README.md) and
+ * `description.sdp` is what the browser client reads
+ * (`client/src/types/signaling.ts`). Senders fill in both; receivers accept
+ * either one.
+ */
+export interface SinalDeVoz {
+  /** `"offer"`, `"answer"` or `"candidate"`. */
+  type?: string;
+  /** Session description, in the bot contract's name. */
+  sdp?: string;
+  /** Session description, in the browser client's shape. */
+  description?: { type?: string; sdp?: string };
+  /** ICE candidate, when `type` is `"candidate"`. */
+  candidate?: unknown;
+  [chave: string]: unknown;
+}
+
+/** A command announced on `identify`, used by the client's autocomplete. */
+export interface ComandoAnunciado {
+  /** Command name, without the channel prefix (e.g. `"tocar"`). */
+  nome: string;
+  /** Short, human-readable summary shown next to the suggestion. */
+  descricao?: string;
+}
+
+/** Someone else in the voice room. */
+export interface PeerDaVoz {
+  /** Peer id inside the room. */
+  id: string;
+  /** Display name. */
+  nome: string;
+  /** `true` when the peer is a bot. */
+  bot?: boolean;
+}
+
+/** Events dispatched by the gateway (op 0), keyed by event name, with the shape of their `d`. */
+export interface Eventos {
+  /** Sent once per connection, right after `identify` (or `resume`) succeeds. */
+  ready: {
+    /** The bot's identity on the server. */
+    bot: { id: string; usuario: string; exibicao: string };
+    /** Text channels with full settings; voice channels as bare codes. */
+    canais: { texto: CanalDeTexto[]; voz: string[] };
+    /** Event families the server accepted. */
+    intents: Intencao[];
+    /** Channels where the read subscription took effect (they exist and grant access). */
+    ouvindo: string[];
+    /** Commands this process announced, for the client's autocomplete. */
+    comandos: ComandoAnunciado[];
+    /** ICE servers to use for voice. */
+    iceServers: ServidorIce[];
+    /** Id of the session this connection is using. */
+    sessao: string;
+  };
+  /** A message was posted in a channel the bot listens to. */
+  "message.created": Mensagem;
+  /**
+   * Someone called the bot with `@login`/`@display`.
+   *
+   * Arrives even in channels with a prefix (where `message.created` would not)
+   * and, in channels without a prefix, alongside it.
+   */
+  mention: Mensagem;
+  /** A message was deleted; `sala` is the channel code it belonged to. */
+  "message.deleted": { id: string; sala: string };
+  /** An operation failed; `codigo` tells channel errors from voice errors. */
+  error: { codigo: string; mensagem: string };
+  /** The bot is now in the voice room. */
+  "voice.joined": {
+    /** Channel code. */
+    code: string;
+    /** Channel name. */
+    nome: string;
+    /** The bot's id in the room: it settles the crossed offer (glare). */
+    eu: string;
+    /** Peers already in the room. */
+    peers: PeerDaVoz[];
+  };
+  /** Another peer joined the voice room. */
+  "voice.peer.joined": PeerDaVoz;
+  /** Another peer left the voice room. */
+  "voice.peer.left": { id: string };
+  /** The bot left (or was removed from) the voice room. */
+  "voice.left": { code: string; motivo: string };
+  /** WebRTC signaling addressed to this bot by peer `de`. */
+  "voice.signal": { de: string; signal: SinalDeVoz };
+}

package/src/voz-wrtc.ts

@@ -0,0 +1,100 @@
+// Voice transport for Node: `@roamhq/wrtc` (an optional dependency).
+//
+// It is loaded only when someone actually uses voice — a text-only bot never
+// downloads a native binary. The Node 24 spike (ABI 137) is documented in the
+// README.
+import type { ConexaoDeVoz, FonteDeAudio, TransporteDeVoz } from "./voz.js";
+import type { ServidorIce } from "./tipos.js";
+
+/** The pieces of `@roamhq/wrtc` this SDK touches. */
+interface ModuloWrtc {
+  RTCPeerConnection: new (config: unknown) => ConexaoDeVoz;
+  nonstandard: { RTCAudioSource: new () => FonteDeAudio & {
+    /** Pushes one PCM block into the source. */
+    onData(dados: {
+      /** Interleaved signed 16-bit samples. */
+      samples: Int16Array;
+      /** Sample rate in Hz (48 kHz for wrtc). */
+      sampleRate: number;
+      /** Bits per sample (16). */
+      bitsPerSample: number;
+      /** Number of channels (1 = mono). */
+      channelCount: number;
+      /** Frames in this block (480 at 48 kHz, i.e. 10 ms). */
+      numberOfFrames: number;
+    }): void;
+  } };
+}
+
+/** Module cache: the native addon is imported at most once per process. */
+let carregado: ModuloWrtc | null = null;
+
+/**
+ * Imports `@roamhq/wrtc` on first use.
+ *
+ * The import is dynamic on purpose: a bot that only handles text must not pay
+ * for (or fail because of) a native dependency it never uses.
+ *
+ * @returns The wrtc module, memoised after the first call.
+ * @throws {Error} With install instructions when the optional dependency is missing.
+ */
+async function carregarWrtc(): Promise<ModuloWrtc> {
+  if (carregado) return carregado;
+  try {
+    const modulo = (await import("@roamhq/wrtc")) as unknown as
+      | ModuloWrtc
+      | { default: ModuloWrtc };
+    carregado = "RTCPeerConnection" in modulo ? modulo : modulo.default;
+    return carregado;
+  } catch (erro) {
+    throw new Error(
+      "A voz do bot precisa de `@roamhq/wrtc`. Instale com `npm i @roamhq/wrtc` " +
+        `no projeto do bot (o texto funciona sem ele). Detalhe: ${
+          erro instanceof Error ? erro.message : String(erro)
+        }`,
+    );
+  }
+}
+
+/**
+ * Creates the Node voice transport backed by `@roamhq/wrtc`.
+ *
+ * The returned transport mirrors the browser's `RTCPeerConnection` API, so the
+ * mesh code in voz.ts does not need to know which runtime it is running on.
+ * Every connection it opens is tracked, and `fechar()` closes them all.
+ *
+ * @returns A transport that creates peer connections and audio sources.
+ * @throws {Error} When `@roamhq/wrtc` is not installed.
+ *
+ * @example
+ * ```ts
+ * const transporte = await criarTransporteWrtc();
+ * const voz = new Voz(bot, { transporte });
+ * await voz.entrar("PATIO");
+ * ```
+ */
+export async function criarTransporteWrtc(): Promise<TransporteDeVoz> {
+  const wrtc = await carregarWrtc();
+  const abertas = new Set<ConexaoDeVoz>();
+  return {
+    /** Opens a peer connection configured with the server-provided ICE servers. */
+    criarConexao({ iceServers }: { iceServers: ServidorIce[] }) {
+      const conexao = new wrtc.RTCPeerConnection({
+        iceServers: iceServers.map((servidor) => ({
+          urls: servidor.urls,
+          ...(servidor.username ? { username: servidor.username } : {}),
+          ...(servidor.credential ? { credential: servidor.credential } : {}),
+        })),
+      });
+      abertas.add(conexao);
+      return conexao;
+    },
+    /** Creates the PCM source that feeds the published audio track. */
+    criarFonteDeAudio: () => new wrtc.nonstandard.RTCAudioSource(),
+    /** Closes every connection this transport opened. */
+    fechar() {
+      for (const conexao of abertas) conexao.close();
+      abertas.clear();
+    },
+  };
+}