@openvertice/bot-sdk 0.1.1 → 0.2.0

package/src/voz.ts

@@ -0,0 +1,407 @@
+// The bot's voice: it is one more peer in the mesh, not a privileged listener.
+//
+// The layout contract is the same the clients use
+// (client/src/lib/webrtc/pares.ts):
+//   audio[0] = microphone · audio[1] = broadcast sound · video[0] = screen
+// The offerer creates all three transceivers; the answerer reuses the ones from
+// the received SDP and forces `sendrecv`. In a crossed offer, the larger id
+// ignores the smaller one's offer.
+import type { Bot } from "./cliente.js";
+import type { ServidorIce, SinalDeVoz } from "./tipos.js";
+
+/**
+ * The minimum voice needs from WebRTC — swappable in tests.
+ *
+ * `criarTransporteWrtc()` provides the Node implementation.
+ */
+export interface TransporteDeVoz {
+  /** Opens one peer connection, configured with the given ICE servers. */
+  criarConexao(opcoes: { iceServers: ServidorIce[] }): ConexaoDeVoz;
+  /** Creates the PCM source that feeds the published track. */
+  criarFonteDeAudio(): FonteDeAudio;
+  /** Closes every connection this transport opened. */
+  fechar(): void;
+}
+
+/** The slice of `RTCPeerConnection` the mesh actually uses. */
+export interface ConexaoDeVoz {
+  /** Standard `signalingState` (`stable`, `have-local-offer`, …). */
+  signalingState: string;
+  /** Local session description, once one has been set. */
+  localDescription: { type: string; sdp?: string } | null;
+  /** Adds an `audio` or `video` m-line and returns the transceiver. */
+  addTransceiver(tipo: "audio" | "video", opcoes?: { direction?: string }): unknown;
+  /** Current transceivers, in SDP order. */
+  getTransceivers(): {
+    direction: string;
+    sender: { track: unknown; replaceTrack(track: unknown): Promise<void> };
+  }[];
+  /** Builds an offer from the current transceivers. */
+  createOffer(): Promise<{ type: "offer"; sdp: string }>;
+  /** Builds an answer to the current remote offer. */
+  createAnswer(): Promise<{ type: "answer"; sdp: string }>;
+  /** Applies a local session description. */
+  setLocalDescription(descricao: { type: string; sdp?: string }): Promise<void>;
+  /** Applies the remote session description. */
+  setRemoteDescription(descricao: { type: string; sdp?: string }): Promise<void>;
+  /** Adds a remote ICE candidate. */
+  addIceCandidate(candidato: unknown): Promise<void>;
+  /** Closes the connection and releases its resources. */
+  close(): void;
+  /** Emits local ICE candidates as they are gathered. */
+  onicecandidate: ((evento: { candidate: unknown }) => void) | null;
+  /** Emits remote tracks as they arrive. */
+  ontrack: ((evento: { track: unknown }) => void) | null;
+}
+
+/** Audio source: where the track the bot publishes comes from. */
+export interface FonteDeAudio {
+  /** Creates the track fed by this source. */
+  createTrack(): unknown;
+}
+
+/** What {@link Voz} needs to run. */
+export interface OpcoesDeVoz {
+  /** Runtime that creates peer connections and audio sources. */
+  transporte: TransporteDeVoz;
+  /**
+   * The track the bot publishes. Without it, voice creates one from
+   * `transporte.criarFonteDeAudio()` — and you feed that source (see audio.ts).
+   */
+  track?: unknown;
+  /** What to do with the audio that arrives from the other peers. */
+  aoReceberTrack?: (peerId: string, track: unknown) => void;
+  /** Diagnostic sink. */
+  log?: (mensagem: string) => void;
+}
+
+/** Result of a successful {@link Voz.entrar}. */
+export interface EntradaNaVoz {
+  /** Channel code the bot joined. */
+  code: string;
+  /** Channel name. */
+  nome: string;
+  /** The bot's id in the room (it settles the crossed offer). */
+  eu: string;
+  /** Peers that were already in the room. */
+  peers: { id: string; nome: string; bot?: boolean }[];
+}
+
+/** How long {@link Voz.entrar} waits for the server's `voice.joined`. */
+const ESPERA_DA_ENTRADA_MS = 15_000;
+
+/**
+ * Voice client for a {@link Bot}.
+ *
+ * The bot is one more peer in the mesh: it offers to peers that are already in
+ * the room, answers offers, exchanges ICE candidates and publishes one audio
+ * track. Create it once, before `bot.start()`, so the listeners are in place
+ * when `voice.joined` arrives.
+ *
+ * @example
+ * ```ts
+ * const transporte = await criarTransporteWrtc();
+ * const voz = new Voz(bot, { transporte });
+ * await bot.start();
+ * await voz.entrar("PATIO");
+ * ```
+ */
+export class Voz {
+  readonly #bot: Bot;
+  readonly #opcoes: OpcoesDeVoz;
+  readonly #conexoes = new Map<string, ConexaoDeVoz>();
+  readonly #log: (mensagem: string) => void;
+  #eu: string | null = null;
+  #canal: string | null = null;
+  #track: unknown = null;
+  #fonte: FonteDeAudio | null = null;
+  #pendente: {
+    resolver: (entrada: EntradaNaVoz) => void;
+    rejeitar: (erro: Error) => void;
+    prazo: ReturnType<typeof setTimeout>;
+  } | null = null;
+
+  /**
+   * Wires the voice client to a bot.
+   *
+   * It subscribes to the voice events right away, so the instance must exist
+   * before the bot starts.
+   *
+   * @param bot Bot whose gateway carries the signaling.
+   * @param opcoes Transport, optional track and logging.
+   */
+  constructor(bot: Bot, opcoes: OpcoesDeVoz) {
+    this.#bot = bot;
+    this.#opcoes = opcoes;
+    this.#log = opcoes.log ?? (() => {});
+    this.#track = opcoes.track ?? null;
+
+    bot.on("voice.joined", (entrada) => {
+      this.#eu = entrada.eu;
+      this.#canal = entrada.code;
+      this.#log(`voz: em ${entrada.code} com ${entrada.peers.length} par(es)`);
+      this.#concluirEntrada(entrada);
+      for (const peer of entrada.peers) void this.#oferecer(peer.id);
+    });
+    bot.on("voice.left", ({ code, motivo }) => {
+      this.#log(`voz: saiu de ${code} (${motivo})`);
+      this.#canal = null;
+      this.#fecharTodas();
+    });
+    bot.on("voice.peer.joined", ({ id, nome }) => {
+      this.#log(`voz: ${nome} entrou`);
+      void this.#oferecer(id);
+    });
+    bot.on("voice.peer.left", ({ id }) => {
+      this.#conexoes.get(id)?.close();
+      this.#conexoes.delete(id);
+    });
+    bot.on("voice.signal", ({ de, signal }) => {
+      void this.#aoSinal(de, signal);
+    });
+    bot.on("error", ({ codigo, mensagem }) => {
+      if (codigo === "canal" || codigo === "voz") this.#falharEntrada(mensagem);
+    });
+    // Reconnecting takes a new seat on the server: the previous room is released
+    // in the gateway's `aoFechar` and `voice.left` never arrives (the socket
+    // died). Without releasing the room here, the bot would believe it is
+    // somewhere it is not, and `entrar` would answer "already in …" forever.
+    bot.aoMudarEstado((estado) => {
+      if (estado !== "reconectando" && estado !== "encerrado" && estado !== "recusado")
+        return;
+      this.#canal = null;
+      this.#fecharTodas();
+      this.#falharEntrada("A conexão com o gateway caiu: a voz foi encerrada.");
+    });
+  }
+
+  /** Channel the bot is in (`null` = not in voice). */
+  get canal(): string | null {
+    return this.#canal;
+  }
+
+  /** The published track; created on demand when it was not passed in the options. */
+  get track(): unknown {
+    if (!this.#track) {
+      this.#fonte ??= this.#opcoes.transporte.criarFonteDeAudio();
+      this.#track = this.#fonte.createTrack();
+    }
+    return this.#track;
+  }
+
+  /**
+   * Joins a voice channel and offers to everyone already there.
+   *
+   * @param code Channel code (case-insensitive).
+   * @returns The room information, once the server confirms the join.
+   * @throws {Error} When the server rejects the join or does not confirm it
+   * within {@link ESPERA_DA_ENTRADA_MS}.
+   */
+  async entrar(code: string): Promise<EntradaNaVoz> {
+    const promessa = new Promise<EntradaNaVoz>((resolver, rejeitar) => {
+      const prazo = setTimeout(() => {
+        this.#pendente = null;
+        rejeitar(new Error("O servidor não confirmou a entrada na voz."));
+      }, ESPERA_DA_ENTRADA_MS);
+      prazo.unref?.();
+      this.#pendente = { resolver, rejeitar, prazo };
+    });
+    try {
+      this.#bot.agir("voz.entrar", { code: code.toUpperCase() });
+    } catch (erro) {
+      // With no gateway connected there is nothing to wait for: fail now
+      // instead of leaving the caller hanging until the timeout.
+      this.#falharEntrada(erro instanceof Error ? erro.message : String(erro));
+    }
+    return promessa;
+  }
+
+  /** Leaves the voice room, if the bot is in one. */
+  sair(): void {
+    if (this.#canal) this.#bot.agir("voz.sair");
+  }
+
+  /**
+   * Resolves a pending {@link entrar} call with the room information.
+   *
+   * @param entrada Data from the `voice.joined` event.
+   */
+  #concluirEntrada(entrada: EntradaNaVoz): void {
+    const pendente = this.#pendente;
+    if (!pendente) return;
+    this.#pendente = null;
+    clearTimeout(pendente.prazo);
+    pendente.resolver(entrada);
+  }
+
+  /**
+   * Rejects a pending {@link entrar} call (server refusal, timeout, dropped gateway).
+   *
+   * @param mensagem Reason shown to the caller.
+   */
+  #falharEntrada(mensagem: string): void {
+    const pendente = this.#pendente;
+    if (!pendente) return;
+    this.#pendente = null;
+    clearTimeout(pendente.prazo);
+    pendente.rejeitar(new Error(mensagem));
+  }
+
+  /**
+   * Returns the peer connection for `peerId`, creating it on first use.
+   *
+   * The offerer adds the three m-lines up front; the answerer reuses the ones
+   * from the received SDP. ICE candidates and remote tracks are wired here.
+   *
+   * @param peerId Peer id inside the room.
+   * @param options Whether this side is the offerer.
+   * @returns The existing or newly created connection.
+   */
+  #conexao(peerId: string, { ofertante }: { ofertante: boolean }): ConexaoDeVoz {
+    const existente = this.#conexoes.get(peerId);
+    if (existente) return existente;
+    const conexao = this.#opcoes.transporte.criarConexao({
+      iceServers: this.#bot.iceServers,
+    });
+    // The offerer creates the three m-lines; the answerer reuses the ones from the SDP.
+    if (ofertante)
+      for (const tipo of ["audio", "audio", "video"] as const)
+        conexao.addTransceiver(tipo, { direction: "sendrecv" });
+    conexao.onicecandidate = (evento) => {
+      if (evento.candidate)
+        this.#enviar(peerId, { type: "candidate", candidate: evento.candidate } as SinalDeVoz);
+    };
+    conexao.ontrack = (evento) => this.#opcoes.aoReceberTrack?.(peerId, evento.track);
+    this.#conexoes.set(peerId, conexao);
+    return conexao;
+  }
+
+  /**
+   * Sends an offer to one peer, publishing the bot's track on the first m-line.
+   *
+   * @param peerId Peer to negotiate with.
+   */
+  async #oferecer(peerId: string): Promise<void> {
+    try {
+      const conexao = this.#conexao(peerId, { ofertante: true });
+      const primeiro = conexao.getTransceivers()[0];
+      if (primeiro && !primeiro.sender.track)
+        await primeiro.sender.replaceTrack(this.track);
+      const oferta = await conexao.createOffer();
+      await conexao.setLocalDescription(oferta);
+      this.#enviarSdp(peerId, "offer", oferta.sdp);
+    } catch (erro) {
+      this.#log(`voz: oferta para ${peerId} falhou: ${mensagemDe(erro)}`);
+    }
+  }
+
+  /**
+   * Applies an incoming signal: offer, answer or ICE candidate.
+   *
+   * @param peerId Peer that sent the signal.
+   * @param sinal Raw WebRTC signal.
+   */
+  async #aoSinal(peerId: string, sinal: SinalDeVoz): Promise<void> {
+    try {
+      if (sinal.type === "offer") return await this.#responder(peerId, sdpDe(sinal));
+      if (sinal.type === "answer") {
+        const sdp = sdpDe(sinal);
+        if (!sdp) return this.#log(`voz: resposta de ${peerId} veio sem SDP`);
+        const conexao = this.#conexao(peerId, { ofertante: false });
+        await conexao.setRemoteDescription({ type: "answer", sdp });
+        return;
+      }
+      if (sinal.type === "candidate" && sinal.candidate) {
+        const conexao = this.#conexao(peerId, { ofertante: false });
+        await conexao.addIceCandidate(sinal.candidate);
+      }
+    } catch (erro) {
+      this.#log(`voz: sinal de ${peerId} falhou: ${mensagemDe(erro)}`);
+    }
+  }
+
+  /**
+   * Answers an offer.
+   *
+   * In a glare (both sides offered), the larger id ignores the other one's
+   * offer — the rule holds on both sides, so nobody ends up with two open
+   * negotiations.
+   *
+   * @param peerId Peer that sent the offer.
+   * @param sdp The offer's session description.
+   */
+  async #responder(peerId: string, sdp: string): Promise<void> {
+    if (!sdp) return this.#log(`voz: oferta de ${peerId} veio sem SDP`);
+    const conexao = this.#conexao(peerId, { ofertante: false });
+    const emDisputa =
+      conexao.signalingState === "have-local-offer" &&
+      conexao.localDescription?.type === "offer";
+    if (emDisputa) {
+      if (this.#eu && this.#eu > peerId) return;
+      await conexao.setLocalDescription({ type: "rollback" });
+    }
+    await conexao.setRemoteDescription({ type: "offer", sdp });
+    // The SDP carries the three m-lines; forcing `sendrecv` is what lets the bot
+    // speak even when the offer arrived as `recvonly`.
+    for (const transceiver of conexao.getTransceivers()) transceiver.direction = "sendrecv";
+    const primeiro = conexao.getTransceivers()[0];
+    if (primeiro && !primeiro.sender.track)
+      await primeiro.sender.replaceTrack(this.track);
+    const resposta = await conexao.createAnswer();
+    await conexao.setLocalDescription(resposta);
+    this.#enviarSdp(peerId, "answer", resposta.sdp);
+  }
+
+  /**
+   * Sends an offer/answer with the SDP under **both** names the protocol knows:
+   * `sdp` (the bot contract's) and `description` (what the browser client
+   * reads). Sending only one left the mesh mute on one side — the symptom was a
+   * `setRemoteDescription(undefined)` swallowed by the client, with no error on
+   * the bot.
+   *
+   * @param peerId Destination peer.
+   * @param tipo `"offer"` or `"answer"`.
+   * @param sdp Session description to send.
+   */
+  #enviarSdp(peerId: string, tipo: "offer" | "answer", sdp: string): void {
+    this.#enviar(peerId, { type: tipo, sdp, description: { type: tipo, sdp } });
+  }
+
+  /**
+   * Sends a raw signal to a peer through the gateway.
+   *
+   * @param peerId Destination peer.
+   * @param signal Signal payload.
+   */
+  #enviar(peerId: string, signal: SinalDeVoz): void {
+    this.#bot.agir("voice.signal", { para: peerId, signal });
+  }
+
+  /** Closes every peer connection the bot currently has open. */
+  #fecharTodas(): void {
+    for (const conexao of this.#conexoes.values()) conexao.close();
+    this.#conexoes.clear();
+  }
+}
+
+/**
+ * Extracts the SDP from a signal, accepting both the bot's name and the browser
+ * client's.
+ *
+ * @param sinal Incoming signal.
+ * @returns The SDP, or `""` when the signal carries none.
+ */
+const sdpDe = (sinal: SinalDeVoz): string => {
+  if (typeof sinal.sdp === "string" && sinal.sdp) return sinal.sdp;
+  const descricao = sinal.description;
+  return typeof descricao?.sdp === "string" ? descricao.sdp : "";
+};
+
+/**
+ * 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: unknown): string =>
+  erro instanceof Error ? erro.message : String(erro);

package/src/wav.ts

@@ -0,0 +1,71 @@
+// WAV of a pure tone — no sample file in the repository and no dependency.
+//
+// It serves two purposes: sending a voice "note" to the chat and exercising the
+// upload path without needing a recorded audio file.
+const CABECALHO = 44;
+
+/** Shape of the generated WAV. Every field is optional. */
+export interface OpcoesDoWav {
+  /** Duration in seconds (clamped to a 0.05 s minimum). */
+  segundos?: number;
+  /** Frequency in Hz. 440 is concert A. */
+  frequencia?: number;
+  /** 0…1. */
+  amplitude?: number;
+  /** Sample rate in Hz; 48 kHz matches the voice transport. */
+  sampleRate?: number;
+}
+
+/**
+ * Builds an in-memory WAV file containing a sine wave.
+ *
+ * Output is 16-bit PCM, mono, little-endian — what any player and the client's
+ * `<audio>` element can play without conversion. Useful to post a quick voice
+ * message (`bot.enviarVoz`) or to test the upload path end to end.
+ *
+ * @param options Tone and container parameters; defaults to one second at 440 Hz.
+ * @returns The complete `.wav` file as bytes, header included.
+ *
+ * @example
+ * ```ts
+ * const wav = wavDeTom({ segundos: 2, frequencia: 330, amplitude: 0.2 });
+ * await bot.enviarVoz("MURAL", wav, { nome: "recado.wav" });
+ * ```
+ */
+export function wavDeTom({
+  segundos = 1,
+  frequencia = 440,
+  amplitude = 0.2,
+  sampleRate = 48_000,
+}: OpcoesDoWav = {}): Uint8Array {
+  const quadros = Math.max(1, Math.round(sampleRate * Math.max(0.05, segundos)));
+  const bytes = new Uint8Array(CABECALHO + quadros * 2);
+  const visao = new DataView(bytes.buffer);
+  const texto = (posicao: number, valor: string) => {
+    for (let i = 0; i < valor.length; i += 1) visao.setUint8(posicao + i, valor.charCodeAt(i));
+  };
+
+  texto(0, "RIFF");
+  visao.setUint32(4, 36 + quadros * 2, true);
+  texto(8, "WAVE");
+  texto(12, "fmt ");
+  visao.setUint32(16, 16, true); // tamanho do bloco fmt
+  visao.setUint16(20, 1, true); // PCM
+  visao.setUint16(22, 1, true); // mono
+  visao.setUint32(24, sampleRate, true);
+  visao.setUint32(28, sampleRate * 2, true); // bytes por segundo
+  visao.setUint16(32, 2, true); // alinhamento do bloco
+  visao.setUint16(34, 16, true); // bits por amostra
+  texto(36, "data");
+  visao.setUint32(40, quadros * 2, true);
+
+  const limite = Math.max(0, Math.min(1, amplitude)) * 0x7fff;
+  const passo = (2 * Math.PI * frequencia) / sampleRate;
+  let fase = 0;
+  for (let i = 0; i < quadros; i += 1) {
+    visao.setInt16(CABECALHO + i * 2, Math.round(Math.sin(fase) * limite), true);
+    fase += passo;
+    if (fase > 2 * Math.PI) fase -= 2 * Math.PI;
+  }
+  return bytes;
+}

package/src/wrtc.d.ts

@@ -0,0 +1,4 @@
+// `@roamhq/wrtc` ships no types of its own: the subset this SDK uses is
+// described in voz.ts (`ConexaoDeVoz`, `FonteDeAudio`) and voz-wrtc.ts adapts
+// it on arrival.
+declare module "@roamhq/wrtc";