@openvertice/bot-sdk 0.0.0-stage → 0.1.1

package/dist/src/http.js

@@ -0,0 +1,189 @@
+/**
+ * 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 {
+    status;
+    codigo;
+    /**
+     * @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, status, codigo = null) {
+        super(mensagem);
+        this.status = status;
+        this.codigo = codigo;
+        this.name = "ErroDaApi";
+    }
+}
+/** 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 {
+    #base;
+    #token;
+    #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 }) {
+        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(caminho, { metodo = "GET", sessao, corpo, } = {}) {
+        const cabecalhos = {
+            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;
+        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 = null;
+        try {
+            dados = texto ? JSON.parse(texto) : null;
+        }
+        catch {
+            dados = null;
+        }
+        if (!resposta.ok) {
+            const erro = (dados ?? {});
+            throw new ErroDaApi(erro.erro ?? `O servidor respondeu ${resposta.status}.`, resposta.status, erro.codigo ?? null);
+        }
+        return dados;
+    }
+    /**
+     * 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() {
+        return this.#pedir("/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() {
+        return this.#pedir("/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, texto, sessao) {
+        const resposta = await this.#pedir(`/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, { antesDe, sessao } = {}) {
+        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, corpo, { nome = "arquivo", mime = "application/octet-stream", tipo = "arquivo", sessao, } = {}) {
+        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,
+        });
+        const texto = await resposta.text();
+        const dados = (() => {
+            try {
+                return JSON.parse(texto);
+            }
+            catch {
+                return {};
+            }
+        })();
+        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, id, sessao) {
+        await this.#pedir(`/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() {
+        return (await this.descobrir()).intents;
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/http.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACnE,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,WAAW,EACX,MAAM,EACN,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,16 @@
+// 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 { CONTRATO } from "./tipos.js";
+export { Voz } from "./voz.js";
+export { criarTransporteWrtc } from "./voz-wrtc.js";
+export { tocarTom } from "./audio.js";
+export { wavDeTom } from "./wav.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gFAAgF;AAChF,qBAAqB;AACrB;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAkB9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAQ/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/src/tipos.d.ts

@@ -0,0 +1,243 @@
+/** Contract version this SDK implements. */
+export declare 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;
+    };
+}
+//# sourceMappingURL=tipos.d.ts.map

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

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

package/dist/src/tipos.js

@@ -0,0 +1,5 @@
+// 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";
+//# sourceMappingURL=tipos.js.map

package/dist/src/tipos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tipos.js","sourceRoot":"","sources":["../../src/tipos.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAE7E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,CAAC"}

package/dist/src/voz-wrtc.d.ts

@@ -0,0 +1,20 @@
+import type { TransporteDeVoz } from "./voz.js";
+/**
+ * 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 declare function criarTransporteWrtc(): Promise<TransporteDeVoz>;
+//# sourceMappingURL=voz-wrtc.d.ts.map

package/dist/src/voz-wrtc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voz-wrtc.d.ts","sourceRoot":"","sources":["../../src/voz-wrtc.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAA8B,eAAe,EAAE,MAAM,UAAU,CAAC;AAqD5E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAwBpE"}

package/dist/src/voz-wrtc.js

@@ -0,0 +1,68 @@
+/** Module cache: the native addon is imported at most once per process. */
+let carregado = 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() {
+    if (carregado)
+        return carregado;
+    try {
+        const modulo = (await import("@roamhq/wrtc"));
+        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() {
+    const wrtc = await carregarWrtc();
+    const abertas = new Set();
+    return {
+        /** Opens a peer connection configured with the server-provided ICE servers. */
+        criarConexao({ iceServers }) {
+            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();
+        },
+    };
+}
+//# sourceMappingURL=voz-wrtc.js.map

package/dist/src/voz-wrtc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voz-wrtc.js","sourceRoot":"","sources":["../../src/voz-wrtc.ts"],"names":[],"mappings":"AA4BA,2EAA2E;AAC3E,IAAI,SAAS,GAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,KAAK,UAAU,YAAY;IACzB,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,cAAc,CAAC,CAEjB,CAAC;QAC5B,SAAS,GAAG,mBAAmB,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAAC,OAAO,IAAI,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,2EAA2E;YACzE,0DACE,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CACpD,EAAE,CACL,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,IAAI,GAAG,MAAM,YAAY,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgB,CAAC;IACxC,OAAO;QACL,+EAA+E;QAC/E,YAAY,CAAC,EAAE,UAAU,EAAiC;YACxD,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,iBAAiB,CAAC;gBACzC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;oBACxC,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC7D,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpE,CAAC,CAAC;aACJ,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,mEAAmE;QACnE,iBAAiB,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE;QAC9D,qDAAqD;QACrD,MAAM;YACJ,KAAK,MAAM,OAAO,IAAI,OAAO;gBAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC/C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}