@byokit/realtime 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+import type { RealtimeClientFrame, RealtimeHostFrame, RealtimeAppAction } from './frames.ts';
+export type RealtimeProviderId = 'chatgpt' | 'openai' | 'gemini' | 'xai';
+export type RealtimeTool = {
+    name: string;
+    description: string;
+    parameters: object;
+};
+export type RealtimeUsage = {
+    seconds: number;
+    basis: 'tokens' | 'minutes' | 'subscription';
+    inputTokens?: number;
+    outputTokens?: number;
+    audioInTokens?: number;
+    audioOutTokens?: number;
+    cachedTokens?: number;
+};
+export type RealtimeAuth = {
+    kind: 'key';
+    key: string;
+} | {
+    kind: 'plan';
+    access(signal?: AbortSignal): Promise<{
+        access: string;
+        accountId: string;
+    }>;
+};
+export type RealtimeConfig = {
+    instructions?: string;
+    model?: string;
+    voice?: string;
+    tools?: RealtimeTool[];
+};
+export type RealtimeErrorCode = 'signed-out' | 'resting' | 'not-included' | 'rate-limited' | 'network' | 'bad-key' | 'expired' | 'protocol' | 'mic-blocked' | 'mic-busy' | 'unsupported';
+export declare class RealtimeError extends Error {
+    readonly name = "RealtimeError";
+    readonly code: RealtimeErrorCode;
+    readonly detail?: Record<string, unknown>;
+    readonly until?: number;
+    constructor(code: RealtimeErrorCode, options?: {
+        cause?: unknown;
+        detail?: Record<string, unknown>;
+        until?: number;
+    });
+}
+export type RealtimeToolCall = {
+    callId: string;
+    name: string;
+    args: unknown;
+    delegated?: boolean;
+};
+export type AudioPorts = {
+    microphone: {
+        acquire(): Promise<void>;
+        release(): void;
+    };
+    capture(rate: number, onData: (base64: string) => void): Promise<{
+        pending: string[];
+        release(): Promise<void>;
+    }>;
+    player: {
+        ensure(rate: number): void;
+        bind(sink: PlaybackSink): void;
+        unbind(sink: PlaybackSink): void;
+        admit(base64: string): 'ok' | 'malformed' | 'overflow';
+        clear(): void;
+        finish(onDrained?: () => void): boolean;
+        afterDrain(kind: 'connected' | 'speech', run: () => void): boolean;
+        stop(): void;
+        release(): void;
+    };
+    route(): Promise<void>;
+    unroute(): Promise<void>;
+};
+export type PlaybackSink = {
+    send(frame: RealtimeClientFrame): boolean;
+};
+export type RealtimeStream = PlaybackSink & {
+    onFrame(fn: (frame: RealtimeHostFrame) => void): void;
+    onClose(fn: (reason?: string) => void): void;
+    start(): void;
+    close(): void;
+};
+export type RealtimeClientOptions = {
+    open(): Promise<RealtimeStream>;
+    audio: AudioPorts;
+    /** Transport closures retry by default. Return false for intentional or terminal closures. */
+    retryableClose?(reason?: string): boolean;
+    webrtc?: (options: import('./webrtc.ts').WebRtcOptions) => Promise<import('./webrtc.ts').WebRtcHandle>;
+    onStatus(status: 'connecting' | 'connected' | 'thinking' | 'speaking' | 'disconnected', reason?: string): void;
+    onTurn(role: 'user' | 'agent', text: string): void;
+    onActivity?(): void;
+    onLevel?(direction: 'input' | 'output', base64: string): void;
+    onStats?(stats: {
+        micCaptured: number;
+        micSent: number;
+        micQueued: number;
+        micDropped: number;
+        transportReconnects: number;
+        providerReconnects: number;
+    }): void;
+    onUsage?(usage: RealtimeUsage): void;
+    onAppRequest?(action: RealtimeAppAction, target?: string): Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+};

package/dist/types.js

@@ -0,0 +1,12 @@
+export class RealtimeError extends Error {
+    name = 'RealtimeError';
+    code;
+    detail;
+    until;
+    constructor(code, options = {}) {
+        super(code, { cause: options.cause });
+        this.code = code;
+        this.detail = options.detail;
+        this.until = options.until;
+    }
+}

package/dist/webrtc.d.ts

@@ -0,0 +1,24 @@
+import type { AudioPorts } from './types.ts';
+export type WebRtcHandle = {
+    acceptAnswer(sdp: string): Promise<void>;
+    sendData(data: string): boolean;
+    setMuted(muted: boolean): void;
+    stop(): void;
+};
+export type WebRtcOptions = {
+    label: string;
+    audio: Pick<AudioPorts, 'microphone' | 'route' | 'unroute'>;
+    signal?: AbortSignal;
+    platform?: {
+        createPeer(): RTCPeerConnection;
+        getUserMedia(): Promise<MediaStream>;
+    };
+    onOffer(sdp: string): void;
+    onData(data: string): void;
+    onRemoteAudio(active: boolean): void;
+    onConnectionState(state: 'connecting' | 'connected' | 'disconnected'): void;
+    onInterruption(active: boolean): void;
+    onError(error: Error): void;
+};
+/** One peer per handle. Microphone permission/service readiness precedes media capture. */
+export declare function webRtcPeer(options: WebRtcOptions): Promise<WebRtcHandle>;

package/dist/webrtc.js

@@ -0,0 +1,133 @@
+import { MAX_REALTIME_SDP_BYTES, MAX_REALTIME_WEBRTC_DATA_BYTES } from "./frames.js";
+function sdp(value) {
+    if (typeof value !== 'string' || !value.startsWith('v=0') || value.includes('\0') || new TextEncoder().encode(value).length > MAX_REALTIME_SDP_BYTES)
+        throw new Error('Invalid voice connection answer.');
+    return value;
+}
+/** One peer per handle. Microphone permission/service readiness precedes media capture. */
+export async function webRtcPeer(options) {
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(options.label))
+        throw new Error('Invalid voice channel.');
+    const platform = options.platform ?? { createPeer: () => new RTCPeerConnection({ bundlePolicy: 'max-bundle', rtcpMuxPolicy: 'require' }), getUserMedia: () => navigator.mediaDevices.getUserMedia({ audio: true, video: false }) };
+    let acquired = false, stopped = false, stream, peer, channel;
+    const queue = [];
+    let queuedBytes = 0;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        stream?.getTracks().forEach(track => track.stop());
+        channel?.close();
+        peer?.close();
+        queue.length = 0;
+        void options.audio.unroute().catch(() => { });
+        if (acquired) {
+            options.audio.microphone.release();
+            acquired = false;
+        }
+        options.signal?.removeEventListener('abort', stop);
+        options.onRemoteAudio(false);
+        options.onConnectionState('disconnected');
+    };
+    options.signal?.addEventListener('abort', stop, { once: true });
+    const fail = (error) => { if (!stopped) {
+        options.onError(error);
+        stop();
+    } };
+    try {
+        options.onConnectionState('connecting');
+        options.signal?.throwIfAborted();
+        await options.audio.microphone.acquire();
+        acquired = true;
+        if (stopped) {
+            options.audio.microphone.release();
+            acquired = false;
+            throw new Error('Voice is closed.');
+        }
+        await options.audio.route();
+        if (stopped) {
+            await options.audio.unroute();
+            throw new Error('Voice is closed.');
+        }
+        stream = await platform.getUserMedia();
+        if (stopped) {
+            stream.getTracks().forEach(track => track.stop());
+            throw new Error('Voice is closed.');
+        }
+        peer = platform.createPeer();
+        channel = peer.createDataChannel(options.label);
+        const current = peer, dataChannel = channel;
+        const flush = () => { while (!stopped && queue.length && dataChannel.readyState === 'open' && dataChannel.bufferedAmount <= 256 * 1024) {
+            const data = queue.shift();
+            queuedBytes -= new TextEncoder().encode(data).length;
+            dataChannel.send(data);
+        } };
+        dataChannel.bufferedAmountLowThreshold = 128 * 1024;
+        dataChannel.onopen = flush;
+        dataChannel.onbufferedamountlow = flush;
+        dataChannel.onmessage = event => { if (typeof event.data === 'string' && !event.data.includes('\0') && new TextEncoder().encode(event.data).length <= MAX_REALTIME_WEBRTC_DATA_BYTES && !stopped)
+            options.onData(event.data); };
+        dataChannel.onerror = () => fail(new Error('Voice channel failed.'));
+        dataChannel.onclose = () => fail(new Error('Voice channel closed.'));
+        current.onconnectionstatechange = () => { if (stopped)
+            return; if (current.connectionState === 'connected')
+            options.onConnectionState('connected');
+        else if (['failed', 'closed'].includes(current.connectionState))
+            fail(new Error('Voice connection ended.'));
+        else
+            options.onConnectionState('connecting'); };
+        current.ontrack = event => { const track = event.track; if (track.kind !== 'audio' || stopped)
+            return; options.onRemoteAudio(!track.muted); track.onmute = () => options.onRemoteAudio(false); track.onunmute = () => options.onRemoteAudio(true); track.onended = () => options.onRemoteAudio(false); };
+        const input = stream.getAudioTracks()[0];
+        if (!input)
+            throw new Error('Microphone is unavailable.');
+        input.onmute = () => options.onInterruption(true);
+        input.onunmute = () => options.onInterruption(false);
+        input.onended = () => fail(new Error('Microphone ended.'));
+        current.addTrack(input, stream);
+        await current.setLocalDescription(await current.createOffer());
+        if (current.iceGatheringState !== 'complete')
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { current.onicegatheringstatechange = null; reject(new Error('Voice connection timed out.')); }, 5000);
+                current.onicegatheringstatechange = () => { if (current.iceGatheringState === 'complete') {
+                    clearTimeout(timer);
+                    current.onicegatheringstatechange = null;
+                    resolve();
+                } };
+                if (current.iceGatheringState === 'complete') {
+                    clearTimeout(timer);
+                    current.onicegatheringstatechange = null;
+                    resolve();
+                }
+            });
+        if (stopped)
+            throw new Error('Voice is closed.');
+        options.onOffer(sdp(current.localDescription?.sdp));
+        return {
+            async acceptAnswer(answer) { if (stopped)
+                throw new Error('Voice is closed.'); await current.setRemoteDescription({ type: 'answer', sdp: sdp(answer) }); },
+            sendData(data) {
+                const bytes = new TextEncoder().encode(data).length;
+                if (stopped || !bytes || bytes > MAX_REALTIME_WEBRTC_DATA_BYTES || data.includes('\0'))
+                    return false;
+                if (dataChannel.readyState === 'open' && queue.length === 0) {
+                    if (dataChannel.bufferedAmount > 256 * 1024)
+                        return false;
+                    dataChannel.send(data);
+                    return true;
+                }
+                if (!['open', 'connecting'].includes(dataChannel.readyState) || queuedBytes + bytes > 64 * 1024)
+                    return false;
+                queue.push(data);
+                queuedBytes += bytes;
+                flush();
+                return true;
+            },
+            setMuted(muted) { stream?.getAudioTracks().forEach(track => { track.enabled = !muted; }); }, stop,
+        };
+    }
+    catch (error) {
+        stop();
+        throw error;
+    }
+}

package/dist/words.d.ts

@@ -0,0 +1,8 @@
+import WORDS from './words.json' with { type: 'json' };
+export { WORDS };
+export type WordKey = keyof typeof WORDS;
+export declare function words(key: WordKey): string;
+export declare function stateWords(state: {
+    phase: 'connecting' | 'connected' | 'thinking' | 'speaking' | 'closed';
+}): string;
+export declare function errorWords(_error: unknown): string;

package/dist/words.js

@@ -0,0 +1,5 @@
+import WORDS from './words.json' with { type: 'json' };
+export { WORDS };
+export function words(key) { return WORDS[key]; }
+export function stateWords(state) { return words(`realtime.${state.phase}`); }
+export function errorWords(_error) { return words('realtime.error'); }

package/dist/words.json

@@ -0,0 +1,8 @@
+{
+    "realtime.connecting": "Connecting voice…",
+    "realtime.connected": "Listening",
+    "realtime.thinking": "Thinking…",
+    "realtime.speaking": "Speaking",
+    "realtime.closed": "Voice ended",
+    "realtime.error": "Voice could not connect. Please try again."
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@byokit/realtime",
+  "version": "0.1.0",
+  "description": "Realtime voice sessions with host-held credentials and injected audio.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umeranjum17/byokit.git",
+    "directory": "packages/realtime"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./webrtc": {
+      "react-native": {
+        "types": "./dist/rn-webrtc.d.ts",
+        "default": "./dist/rn-webrtc.js"
+      },
+      "types": "./dist/webrtc.d.ts",
+      "default": "./dist/webrtc.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "8.21.3"
+  },
+  "peerDependencies": {
+    "react-native-webrtc": "124.0.8"
+  },
+  "peerDependenciesMeta": {
+    "react-native-webrtc": {
+      "optional": true
+    }
+  }
+}