@babelforce/babelconnect-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@babelforce/babelconnect-sdk` — the TypeScript SDK for babelconnect.
+ *
+ * - {@link BabelconnectClient}: a server-authoritative "dumb renderer" client over
+ *   gRPC-web (state mirror + typed intents) with a pluggable WebRTC media leg.
+ * - {@link passwordGrant}: OAuth helper (via the server's `/oauth/token` endpoint).
+ * - {@link BrowserWebrtcMedia}: the default browser audio backend.
+ *
+ * For embedding the prebuilt agent app into a host page, import the `/embed` entry
+ * point: `@babelforce/babelconnect-sdk/embed`.
+ */
+export { BabelconnectClient, type ConnectOptions } from "./client.js";
+export { StateCache } from "./state-cache.js";
+export { passwordGrant } from "./auth.js";
+export { BrowserWebrtcMedia, browserMediaFactory, type Media, type MediaFactory } from "./media.js";
+export * from "./gen/babelconnect/v1/babelconnect_pb.js";
+export { Agent } from "./gen/babelconnect/v1/babelconnect_connect.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@babelforce/babelconnect-sdk` — the TypeScript SDK for babelconnect.
+ *
+ * - {@link BabelconnectClient}: a server-authoritative "dumb renderer" client over
+ *   gRPC-web (state mirror + typed intents) with a pluggable WebRTC media leg.
+ * - {@link passwordGrant}: OAuth helper (via the server's `/oauth/token` endpoint).
+ * - {@link BrowserWebrtcMedia}: the default browser audio backend.
+ *
+ * For embedding the prebuilt agent app into a host page, import the `/embed` entry
+ * point: `@babelforce/babelconnect-sdk/embed`.
+ */
+export { BabelconnectClient } from "./client.js";
+export { StateCache } from "./state-cache.js";
+export { passwordGrant } from "./auth.js";
+export { BrowserWebrtcMedia, browserMediaFactory } from "./media.js";
+// The generated babelconnect.v1 messages + enums (AgentView, CallState, Command, …)
+// and the Agent service descriptor.
+export * from "./gen/babelconnect/v1/babelconnect_pb.js";
+export { Agent } from "./gen/babelconnect/v1/babelconnect_connect.js";

package/dist/media.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The pluggable media seam: one WebRTC leg per call. The SDK drives control over
+ * gRPC-web and hands the server's SDP offer to a `Media` to answer (audio flows
+ * between the browser and babelconnect-server). Mute/hold are server-side intents
+ * (`mute`/`hold`), so they are not part of this seam.
+ */
+export interface Media {
+    /**
+     * Consume the server's SDP offer and return the client's SDP answer, starting
+     * audio. Called once per call.
+     *
+     * @param iceServers STUN/TURN servers the server advertised on the call
+     *   (`CallState.ice_servers`) — for off-host NAT traversal; empty in the
+     *   in-cluster/LAN case.
+     */
+    answer(offer: string, iceServers?: RTCIceServer[]): Promise<string>;
+    /** Tear down the peer (idempotent). */
+    close(): Promise<void>;
+}
+/** Builds the {@link Media} for a given call id. */
+export type MediaFactory = (callId: string) => Media;
+/**
+ * The default browser WebRTC backend: capture the mic, answer the server's offer
+ * (non-trickle ICE), and play the remote audio through a hidden `<audio>` element.
+ * A-law (PCMA) passthrough is negotiated by the server's offer.
+ */
+export declare class BrowserWebrtcMedia implements Media {
+    private readonly iceServers;
+    private pc?;
+    private local?;
+    private audioEl?;
+    private closed;
+    /** @param iceServers fallback ICE servers; the per-call `answer(offer, iceServers)`
+     *  argument (from `CallState.ice_servers`) takes precedence when provided. */
+    constructor(iceServers?: RTCIceServer[]);
+    answer(offer: string, iceServers?: RTCIceServer[]): Promise<string>;
+    close(): Promise<void>;
+}
+/** The default factory: a {@link BrowserWebrtcMedia} per call. */
+export declare const browserMediaFactory: MediaFactory;
+/** A server-advertised ICE server (shape of `CallState.ice_servers[]`). */
+export interface IceServerLike {
+    urls: string[];
+    username: string;
+    credential: string;
+}
+/**
+ * Map the server-advertised `CallState.ice_servers` to the browser's
+ * {@link RTCIceServer} shape for `answer(offer, iceServers)`. Returns `undefined`
+ * when none are advertised (in-cluster/LAN) so the Media's own fallback applies.
+ */
+export declare function toRTCIceServers(servers: readonly IceServerLike[]): RTCIceServer[] | undefined;

package/dist/media.js

@@ -0,0 +1,97 @@
+/**
+ * The default browser WebRTC backend: capture the mic, answer the server's offer
+ * (non-trickle ICE), and play the remote audio through a hidden `<audio>` element.
+ * A-law (PCMA) passthrough is negotiated by the server's offer.
+ */
+export class BrowserWebrtcMedia {
+    iceServers;
+    pc;
+    local;
+    audioEl;
+    closed = false;
+    /** @param iceServers fallback ICE servers; the per-call `answer(offer, iceServers)`
+     *  argument (from `CallState.ice_servers`) takes precedence when provided. */
+    constructor(iceServers = []) {
+        this.iceServers = iceServers;
+    }
+    async answer(offer, iceServers) {
+        // Prefer the per-call ICE servers the server advertised; fall back to any set
+        // at construction (kept for backward compatibility).
+        const pc = new RTCPeerConnection({ iceServers: iceServers ?? this.iceServers });
+        this.pc = pc;
+        // Remote audio: attach the inbound stream to a hidden, autoplaying <audio>.
+        pc.ontrack = (ev) => {
+            const stream = ev.streams[0];
+            if (!stream)
+                return;
+            let el = this.audioEl;
+            if (!el) {
+                el = document.createElement("audio");
+                el.autoplay = true;
+                el.style.display = "none";
+                document.body.appendChild(el);
+                this.audioEl = el;
+            }
+            el.srcObject = stream;
+            void el.play().catch(() => { });
+        };
+        // Capture the microphone and add it to the peer.
+        const local = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
+        this.local = local;
+        for (const track of local.getAudioTracks())
+            pc.addTrack(track, local);
+        await pc.setRemoteDescription({ type: "offer", sdp: offer });
+        const ans = await pc.createAnswer();
+        await pc.setLocalDescription(ans);
+        await waitIceGatheringComplete(pc);
+        const sdp = pc.localDescription?.sdp;
+        if (!sdp)
+            throw new Error("webrtc: empty local SDP after answer");
+        return sdp;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const t of this.local?.getTracks() ?? [])
+            t.stop();
+        this.local = undefined;
+        this.pc?.close();
+        this.pc = undefined;
+        if (this.audioEl) {
+            this.audioEl.srcObject = null;
+            this.audioEl.remove();
+            this.audioEl = undefined;
+        }
+    }
+}
+/** The default factory: a {@link BrowserWebrtcMedia} per call. */
+export const browserMediaFactory = () => new BrowserWebrtcMedia();
+/**
+ * Map the server-advertised `CallState.ice_servers` to the browser's
+ * {@link RTCIceServer} shape for `answer(offer, iceServers)`. Returns `undefined`
+ * when none are advertised (in-cluster/LAN) so the Media's own fallback applies.
+ */
+export function toRTCIceServers(servers) {
+    if (servers.length === 0)
+        return undefined;
+    return servers.map((s) => ({ urls: s.urls, username: s.username, credential: s.credential }));
+}
+/** Resolve once ICE gathering completes (non-trickle), or after `timeoutMs`. */
+function waitIceGatheringComplete(pc, timeoutMs = 5000) {
+    if (pc.iceGatheringState === "complete")
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            pc.removeEventListener("icegatheringstatechange", check);
+            resolve();
+        };
+        const check = () => {
+            if (pc.iceGatheringState === "complete")
+                done();
+        };
+        const timer = setTimeout(done, timeoutMs);
+        pc.addEventListener("icegatheringstatechange", check);
+    });
+}

package/dist/state-cache.d.ts

@@ -0,0 +1,30 @@
+import { AgentView, type StateUpdate } from "./gen/babelconnect/v1/babelconnect_pb.js";
+/**
+ * The client-side mirror of the server-authoritative {@link AgentView}.
+ *
+ * It applies `StateUpdate` snapshots and entity-level patches **mechanically** —
+ * there is no domain logic here, by design: the server reduces, the client
+ * renders. This is the TypeScript twin of the Go (`bcclient.StateCache`) and Dart
+ * (`StateCache`) reducers and is meant to be identical (and trivial) across the
+ * SDKs so they cannot drift.
+ */
+export declare class StateCache {
+    private view;
+    private seq;
+    private seenSeq;
+    private readonly listeners;
+    /** The current view (a deep copy, safe to hold/read). */
+    get current(): AgentView;
+    /**
+     * Fold one snapshot or patch into the view and notify listeners. Returns `true`
+     * if a seq gap was detected (a patch whose seq is not exactly the previous
+     * seq + 1) — the caller should resubscribe for a fresh snapshot. Error updates
+     * are handled by the client, not here.
+     */
+    apply(u: StateUpdate): boolean;
+    /** Register a render callback, invoked immediately and on every update. Returns an unsubscribe fn. */
+    subscribe(fn: (v: AgentView) => void): () => void;
+    private reduce;
+    private putById;
+    private putByPeer;
+}

package/dist/state-cache.js

@@ -0,0 +1,106 @@
+import { AgentView } from "./gen/babelconnect/v1/babelconnect_pb.js";
+/**
+ * The client-side mirror of the server-authoritative {@link AgentView}.
+ *
+ * It applies `StateUpdate` snapshots and entity-level patches **mechanically** —
+ * there is no domain logic here, by design: the server reduces, the client
+ * renders. This is the TypeScript twin of the Go (`bcclient.StateCache`) and Dart
+ * (`StateCache`) reducers and is meant to be identical (and trivial) across the
+ * SDKs so they cannot drift.
+ */
+export class StateCache {
+    view = new AgentView();
+    seq = 0n;
+    seenSeq = false;
+    listeners = new Set();
+    /** The current view (a deep copy, safe to hold/read). */
+    get current() {
+        return this.view.clone();
+    }
+    /**
+     * Fold one snapshot or patch into the view and notify listeners. Returns `true`
+     * if a seq gap was detected (a patch whose seq is not exactly the previous
+     * seq + 1) — the caller should resubscribe for a fresh snapshot. Error updates
+     * are handled by the client, not here.
+     */
+    apply(u) {
+        let gap = false;
+        switch (u.update.case) {
+            case "snapshot":
+                this.view = u.update.value;
+                this.seq = u.seq;
+                this.seenSeq = true;
+                break;
+            case "patch":
+                if (this.seenSeq && u.seq !== this.seq + 1n)
+                    gap = true;
+                this.seq = u.seq;
+                this.seenSeq = true;
+                this.reduce(u.update.value);
+                break;
+            default:
+                return false;
+        }
+        const snapshot = this.view.clone();
+        for (const fn of this.listeners)
+            fn(snapshot);
+        return gap;
+    }
+    /** Register a render callback, invoked immediately and on every update. Returns an unsubscribe fn. */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        fn(this.view.clone());
+        return () => this.listeners.delete(fn);
+    }
+    reduce(p) {
+        switch (p.change.case) {
+            case "agent":
+                this.view.agent = p.change.value;
+                break;
+            case "callUpsert":
+                this.putById(this.view.activeCalls, p.change.value);
+                break;
+            case "callRemove":
+                this.view.activeCalls = this.view.activeCalls.filter((c) => c.id !== p.change.value);
+                break;
+            case "wrapUp":
+                this.view.wrapUp = p.change.value;
+                break;
+            case "smsUpsert":
+                // SMS conversations are keyed by PEER (the stable thread identity), not the
+                // backend conversation id — mirror the server reducer + sdk-go/sdk-dart caches.
+                this.putByPeer(this.view.sms, p.change.value);
+                break;
+            case "smsRemove":
+                // The sms_remove patch value is the peer.
+                this.view.sms = this.view.sms.filter((c) => c.peer !== p.change.value);
+                break;
+            case "conferenceUpsert":
+                this.putById(this.view.conferences, p.change.value);
+                break;
+            case "conferenceRemove":
+                this.view.conferences = this.view.conferences.filter((c) => c.id !== p.change.value);
+                break;
+            case "config":
+                this.view.config = p.change.value;
+                break;
+            // `notification` is transient (handled by the client as an event), not stored.
+            default:
+                break;
+        }
+    }
+    putById(list, item) {
+        const i = list.findIndex((x) => x.id === item.id);
+        if (i >= 0)
+            list[i] = item;
+        else
+            list.push(item);
+    }
+    putByPeer(list, item) {
+        const i = list.findIndex((x) => x.peer === item.peer);
+        if (i >= 0)
+            list[i] = item;
+        else
+            list.push(item);
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@babelforce/babelconnect-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for babelconnect — server-authoritative agent state over gRPC-web, native WebRTC audio, and an embeddable widget (iframe + postMessage) for the Flutter web app.",
+  "license": "Apache-2.0",
+  "homepage": "https://babelforce.github.io/babelconnect-sdk-docs/",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./embed": {
+      "types": "./dist/embed/index.d.ts",
+      "import": "./dist/embed/index.js"
+    }
+  },
+  "scripts": {
+    "generate": "echo 'run `task gen` at the repo root (buf generate emits src/gen)'",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "docs": "typedoc",
+    "docs:md": "typedoc --options typedoc.docusaurus.json",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^1.10.1",
+    "@connectrpc/connect": "^1.6.1",
+    "@connectrpc/connect-web": "^1.6.1"
+  },
+  "devDependencies": {
+    "@bufbuild/protoc-gen-es": "^1.10.1",
+    "@connectrpc/protoc-gen-connect-es": "^1.6.1",
+    "typedoc": "^0.27.0",
+    "typedoc-plugin-markdown": "^4.4.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}