@openvertice/bot-sdk 0.0.0-stage → 0.1.0

package/dist/src/voz.js

@@ -0,0 +1,311 @@
+/** 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 {
+    #bot;
+    #opcoes;
+    #conexoes = new Map();
+    #log;
+    #eu = null;
+    #canal = null;
+    #track = null;
+    #fonte = null;
+    #pendente = 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, opcoes) {
+        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() {
+        return this.#canal;
+    }
+    /** The published track; created on demand when it was not passed in the options. */
+    get track() {
+        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) {
+        const promessa = new Promise((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() {
+        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) {
+        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) {
+        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, { ofertante }) {
+        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"])
+                conexao.addTransceiver(tipo, { direction: "sendrecv" });
+        conexao.onicecandidate = (evento) => {
+            if (evento.candidate)
+                this.#enviar(peerId, { type: "candidate", candidate: evento.candidate });
+        };
+        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) {
+        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, sinal) {
+        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, sdp) {
+        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, tipo, sdp) {
+        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, signal) {
+        this.#bot.agir("voice.signal", { para: peerId, signal });
+    }
+    /** Closes every peer connection the bot currently has open. */
+    #fecharTodas() {
+        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) => {
+    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) => erro instanceof Error ? erro.message : String(erro);
+//# sourceMappingURL=voz.js.map

package/dist/src/voz.js.map

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

package/dist/src/wav.d.ts

@@ -0,0 +1,29 @@
+/** 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 declare function wavDeTom({ segundos, frequencia, amplitude, sampleRate, }?: OpcoesDoWav): Uint8Array;
+//# sourceMappingURL=wav.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wav.d.ts","sourceRoot":"","sources":["../../src/wav.ts"],"names":[],"mappings":"AAMA,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAY,EACZ,UAAgB,EAChB,SAAe,EACf,UAAmB,GACpB,GAAE,WAAgB,GAAG,UAAU,CA+B/B"}

package/dist/src/wav.js

@@ -0,0 +1,54 @@
+// 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;
+/**
+ * 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, } = {}) {
+    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, valor) => {
+        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;
+}
+//# sourceMappingURL=wav.js.map

package/dist/src/wav.js.map

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

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@openvertice/bot-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "SDK para escrever bots do Vértice: gateway, mensagens e voz (WebRTC), sem dependência de runtime",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/src",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "eco": "node dist/exemplos/eco.js",
+    "radio": "node dist/exemplos/radio.js",
+    "recado": "node dist/exemplos/recado.js"
+  },
+  "dependencies": {},
+  "optionalDependencies": {
+    "@roamhq/wrtc": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vortex-SA/vertice-bot-sdk.git"
+  },
+  "homepage": "https://github.com/Vortex-SA/vertice-bot-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Vortex-SA/vertice-bot-sdk/issues"
+  },
+  "author": "OpenVertice",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "vertice",
+    "openvertice",
+    "bot",
+    "sdk",
+    "gateway",
+    "websocket",
+    "webrtc",
+    "voice"
+  ]
 }

package/src/audio.ts

@@ -0,0 +1,88 @@
+// What the bot plays: a pure tone, with no file and no dependency.
+//
+// The source comes from the transport (`RTCAudioSource` in wrtc): it receives
+// 10 ms blocks — 480 samples at 48 kHz, the only frame size wrtc accepts. This
+// is the shortest possible "real audio" example; reading a file is just feeding
+// the same source from somewhere else.
+import type { FonteDeAudio } from "./voz.js";
+
+/** Audio source that accepts raw PCM blocks (the shape `RTCAudioSource` has). */
+interface FonteComDados extends 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;
+}
+
+/** Everything `tocarTom` needs in order to publish a sine wave. */
+export interface OpcoesDoTom {
+  /** The transport source (`transporte.criarFonteDeAudio()`). */
+  fonte: FonteDeAudio;
+  /** Frequency in Hz. 440 is concert A. */
+  frequencia?: number;
+  /** 0…1. Anything above 0.5 starts to clip and distort. */
+  amplitude?: number;
+  /** 48 kHz: wrtc requires blocks of 480 samples. */
+  sampleRate?: number;
+}
+
+/**
+ * Starts playing the tone on the given source.
+ *
+ * Keep the returned stop function for as long as the bot stays in the room:
+ * stopping mid-flight leaves the peer with silence, not with an error — which
+ * is exactly what a bot that stops speaking should do.
+ *
+ * @param options Tone parameters; every field has a sensible default.
+ * @returns A function that stops the tone and clears its timer.
+ *
+ * @example
+ * ```ts
+ * const fonte = transporte.criarFonteDeAudio();
+ * const parar = tocarTom({ fonte, frequencia: 440, amplitude: 0.15 });
+ * // …later, on shutdown:
+ * parar();
+ * ```
+ */
+export function tocarTom({
+  fonte,
+  frequencia = 440,
+  amplitude = 0.2,
+  sampleRate = 48_000,
+}: OpcoesDoTom): () => void {
+  const comDados = fonte as FonteComDados;
+  // 10 ms per block: it is the frame size of wrtc's RTCAudioSource.
+  const quadros = Math.round(sampleRate / 100);
+  const passo = (2 * Math.PI * frequencia) / sampleRate;
+  const limite = Math.max(0, Math.min(1, amplitude)) * 0x7fff;
+  let fase = 0;
+
+  const timer = setInterval(() => {
+    const amostras = new Int16Array(quadros);
+    for (let i = 0; i < quadros; i += 1) {
+      amostras[i] = Math.round(Math.sin(fase) * limite);
+      fase += passo;
+      if (fase > 2 * Math.PI) fase -= 2 * Math.PI;
+    }
+    comDados.onData({
+      samples: amostras,
+      sampleRate,
+      bitsPerSample: 16,
+      channelCount: 1,
+      numberOfFrames: quadros,
+    });
+  }, 10);
+  // Without `unref` the process would not exit while the tone plays — and the
+  // bot must be able to leave the room and still shut down cleanly.
+  timer.unref?.();
+  return () => clearInterval(timer);
+}