@rimelabs/sdk 0.1.0-alpha.1 → 0.1.0-alpha.12

package/dist/realtime/async.d.ts

@@ -0,0 +1,23 @@
+export { scope } from "../cancellation.js";
+export declare class Deferred<T> {
+    readonly promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (error: unknown) => void;
+    constructor();
+}
+export declare class Flag {
+    private waiters;
+    isSet: boolean;
+    set(): void;
+    clear(): void;
+    wait(signal: AbortSignal): Promise<void>;
+}
+export declare class Mutex {
+    private locked;
+    private waiters;
+    acquire(signal: AbortSignal): Promise<() => void>;
+}
+export declare function cancellation(signal?: AbortSignal): {
+    signal: AbortSignal;
+    dispose: () => void | undefined;
+};

package/dist/realtime/async.js

@@ -0,0 +1,87 @@
+export { scope } from "../cancellation.js";
+import { abortable } from "../cancellation.js";
+import { RimeCancelledError } from "../errors.js";
+export class Deferred {
+    promise;
+    resolve;
+    reject;
+    constructor() {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        // Session failures can arrive before a caller starts waiting.
+        this.promise.catch(() => { });
+    }
+}
+export class Flag {
+    waiters = new Set();
+    isSet = false;
+    set() {
+        this.isSet = true;
+        for (const wake of this.waiters)
+            wake();
+    }
+    clear() {
+        this.isSet = false;
+    }
+    wait(signal) {
+        if (signal.aborted)
+            return Promise.reject(signal.reason);
+        if (this.isSet)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.waiters.delete(wake);
+                signal.removeEventListener("abort", abort);
+            };
+            const wake = () => {
+                cleanup();
+                resolve();
+            };
+            const abort = () => {
+                cleanup();
+                reject(signal.reason);
+            };
+            this.waiters.add(wake);
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+}
+export class Mutex {
+    locked = false;
+    waiters = new Set();
+    async acquire(signal) {
+        signal.throwIfAborted();
+        while (this.locked) {
+            const wake = new Deferred();
+            const notify = () => wake.resolve();
+            this.waiters.add(notify);
+            try {
+                await abortable(wake.promise, signal);
+            }
+            finally {
+                this.waiters.delete(notify);
+            }
+            signal.throwIfAborted();
+        }
+        this.locked = true;
+        return () => {
+            this.locked = false;
+            for (const wake of this.waiters)
+                wake();
+        };
+    }
+}
+export function cancellation(signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(new RimeCancelledError("Realtime operation cancelled"));
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => signal?.removeEventListener("abort", abort),
+    };
+}

package/dist/realtime/audio.d.ts

@@ -0,0 +1,2 @@
+import type { AudioChunk, PCMFormat } from "./types.js";
+export declare function formatOf(chunk: AudioChunk): Required<PCMFormat>;

package/dist/realtime/audio.js

@@ -0,0 +1,11 @@
+import { RimeAudioFormatError } from "../errors.js";
+import { resolvePCMFormat } from "../pcm.js";
+export function formatOf(chunk) {
+    const format = resolvePCMFormat(chunk.format);
+    if (!(chunk.data instanceof Uint8Array) ||
+        chunk.data.length % (2 * format.channels))
+        throw new RimeAudioFormatError("Audio must contain complete PCM16 frames as Uint8Array");
+    if (chunk.data.length > 192000)
+        throw new RimeAudioFormatError("Send audio in chunks of at most 192000 bytes");
+    return format;
+}

package/dist/realtime/client.d.ts

@@ -0,0 +1,12 @@
+import { Credentials } from "../auth.js";
+import { RealtimeSession } from "./session.js";
+import type { RealtimeConnectOptions } from "./types.js";
+export declare class Realtime {
+    private readonly credentials;
+    private readonly checkOpen;
+    private readonly sessions;
+    private readonly opening;
+    constructor(credentials: Credentials, checkOpen: () => void);
+    connect(options: RealtimeConnectOptions): Promise<RealtimeSession>;
+    close(): Promise<void>;
+}

package/dist/realtime/client.js

@@ -0,0 +1,156 @@
+import { abortable } from "../cancellation.js";
+import { RimeCancelledError, RimeInputError, RimeUnavailableError, } from "../errors.js";
+import { cancellation, scope } from "./async.js";
+import { RealtimeSession } from "./session.js";
+import { RealtimeConnection } from "./transport.js";
+function endpoint(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new RimeInputError("endpoint must be a full ws:// or wss:// URL ending in /v1/realtime");
+    }
+    if (!["ws:", "wss:"].includes(url.protocol) ||
+        !url.hostname ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        url.pathname.replace(/\/+$/, "") !== "/v1/realtime")
+        throw new RimeInputError("endpoint must be a full ws:// or wss:// URL ending in /v1/realtime");
+    if (url.protocol === "ws:" &&
+        !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+        throw new RimeInputError("Use wss:// outside localhost to protect credentials");
+    return url.href;
+}
+function timeouts(options = {}) {
+    const result = {
+        connectS: options.connectS ?? 10,
+        readyS: options.readyS ?? 30,
+        requestS: options.requestS ?? 10,
+    };
+    if (Object.values(result).some((value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0))
+        throw new RimeInputError("Timeouts must be finite and positive");
+    return result;
+}
+/** Reject values that JSON.stringify would silently drop or change. */
+function copyJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return Array.from(value, copyJson);
+    if (value &&
+        typeof value === "object" &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyJson(item)]));
+    throw new RimeInputError("Tool schemas must contain finite JSON values");
+}
+export class Realtime {
+    credentials;
+    checkOpen;
+    sessions = new Set();
+    opening = new Map();
+    constructor(credentials, checkOpen) {
+        this.credentials = credentials;
+        this.checkOpen = checkOpen;
+    }
+    async connect(options) {
+        this.checkOpen();
+        const address = endpoint(options.endpoint);
+        const limits = timeouts(options.timeouts);
+        if ((options.model ?? "prism") !== "prism")
+            throw new RimeInputError("The realtime model must be prism");
+        if (options.interruptOnSpeech !== undefined &&
+            typeof options.interruptOnSpeech !== "boolean")
+            throw new RimeInputError("interruptOnSpeech must be a boolean");
+        const names = new Set();
+        const settings = {
+            modalities: ["text", "audio"],
+            input_audio_format: "pcm16",
+            turn_detection: { interrupt_response: options.interruptOnSpeech ?? true },
+            tools: (options.tools ?? []).map((tool) => {
+                if (typeof tool.name !== "string" ||
+                    !tool.name.trim() ||
+                    names.has(tool.name))
+                    throw new RimeInputError("Tool names must be nonblank and unique");
+                names.add(tool.name);
+                if (!tool.parameters ||
+                    Array.isArray(tool.parameters) ||
+                    typeof tool.parameters !== "object" ||
+                    (tool.description !== undefined &&
+                        typeof tool.description !== "string"))
+                    throw new RimeInputError("Tool parameters must be a JSON object and description must be a string");
+                let parameters;
+                try {
+                    parameters = copyJson(tool.parameters);
+                }
+                catch {
+                    throw new RimeInputError("Tool schemas must contain finite JSON values");
+                }
+                if (parameters === null ||
+                    typeof parameters !== "object" ||
+                    Array.isArray(parameters))
+                    throw new RimeInputError("Tool parameters must be an object");
+                return {
+                    type: "function",
+                    function: {
+                        name: tool.name,
+                        description: tool.description ?? "",
+                        parameters,
+                    },
+                };
+            }),
+        };
+        for (const name of ["voice", "instructions"]) {
+            const value = options[name];
+            if (value !== undefined && value !== null) {
+                if (typeof value !== "string" || !value.trim())
+                    throw new RimeInputError(`${name} must be nonblank`);
+                settings[name] = value;
+            }
+        }
+        const owner = new AbortController();
+        const caller = cancellation(options.signal);
+        const openingScope = scope([caller.signal, owner.signal]);
+        const task = (async () => {
+            let session;
+            try {
+                openingScope.signal.throwIfAborted();
+                let socket;
+                try {
+                    socket = new RealtimeConnection(address, this.credentials.realtimeAuthorization());
+                }
+                catch {
+                    throw new RimeUnavailableError("Realtime handshake failed");
+                }
+                session = new RealtimeSession(socket, limits, () => this.sessions.delete(session));
+                this.sessions.add(session);
+                await abortable(session.initialize(settings, openingScope.signal), openingScope.signal);
+                openingScope.signal.throwIfAborted();
+                this.checkOpen();
+                return session;
+            }
+            catch (error) {
+                await session?.close();
+                throw error;
+            }
+        })();
+        this.opening.set(owner, task);
+        try {
+            return await task;
+        }
+        finally {
+            this.opening.delete(owner);
+            openingScope.dispose();
+            caller.dispose();
+        }
+    }
+    async close() {
+        for (const controller of this.opening.keys())
+            controller.abort(new RimeCancelledError("Client closed"));
+        await Promise.allSettled(this.opening.values());
+        await Promise.all([...this.sessions].map((session) => session.close()));
+    }
+}

package/dist/realtime/protocol.d.ts

@@ -0,0 +1,80 @@
+import * as t from "./types.js";
+export interface SessionSettings {
+    modalities: ("text" | "audio")[];
+    input_audio_format: "pcm16";
+    turn_detection: {
+        interrupt_response: boolean;
+    };
+    tools: {
+        type: "function";
+        function: {
+            name: string;
+            description: string;
+            parameters: t.JsonObject;
+        };
+    }[];
+    voice?: string;
+    instructions?: string;
+}
+export interface SessionView {
+    id: string;
+    voice: string;
+    interruptOnSpeech: boolean | null;
+    toolResultTimeoutS: number | null;
+    toolContinuationTimeoutS: number | null;
+}
+export interface SessionCreated {
+    kind: "session.created";
+    session: SessionView;
+}
+export interface SessionUpdated {
+    kind: "session.updated";
+    session: SessionView;
+}
+export interface ItemCreated {
+    kind: "item.created";
+    itemId: string;
+}
+export interface ToolResultCreated {
+    kind: "tool.result.created";
+    callId: string;
+}
+export interface AudioCleared {
+    kind: "audio.cleared";
+}
+export interface ItemTruncated {
+    kind: "item.truncated";
+    itemId: string;
+    contentIndex: number;
+}
+export interface ResponseEnded extends t.ResponseEnded {
+    drainToken: string | null;
+}
+export type Acknowledgment = SessionUpdated | ItemCreated | ToolResultCreated | AudioCleared | ItemTruncated | t.ResponseStarted | ResponseEnded;
+export type ServerPayload = SessionCreated | Acknowledgment | t.InputEvent | t.MessageStarted | t.TextDelta | t.TextDone | t.AudioDelta | t.AudioDone | t.ToolCall | t.FaultEvent;
+export interface ServerEvent {
+    eventId: string;
+    requestId: string | null;
+    payload: ServerPayload;
+}
+export type RequestKind = "session.update" | "conversation.item.create" | "response.create" | "response.cancel" | "input_audio_buffer.clear" | "conversation.item.truncate";
+/** A request carries its result type and checks it before exposing the result. */
+export declare class Request<T extends Acknowledgment> {
+    readonly kind: RequestKind;
+    private readonly accepts;
+    readonly allowsItemCreated: boolean;
+    constructor(kind: RequestKind, accepts: (event: Acknowledgment) => event is T, allowsItemCreated?: boolean);
+    result(event: Acknowledgment): T;
+    check(event: Acknowledgment): void;
+}
+export declare const requests: {
+    update: Request<SessionUpdated>;
+    item: Request<ItemCreated>;
+    toolResult: Request<ToolResultCreated>;
+    create: Request<t.ResponseStarted>;
+    text: Request<t.ResponseStarted>;
+    cancel: Request<ResponseEnded>;
+    clear: Request<AudioCleared>;
+    truncate: Request<ItemTruncated>;
+};
+export declare function decode(raw: string, sessionId: string | null): ServerEvent | null;