quantum-ai-sdk 0.2.0 → 0.2.1

package/dist/realtime.js

@@ -0,0 +1,259 @@
+/**
+ * Realtime voice sessions via WebSocket.
+ *
+ * Connects to the QAI Realtime API for bidirectional audio streaming
+ * with voice activity detection, transcription, and tool calling.
+ */
+// ── RealtimeSender ─────────────────────────────────────────────────
+/** Write half of a realtime session. */
+export class RealtimeSender {
+    ws;
+    /** @internal */
+    constructor(ws) {
+        this.ws = ws;
+    }
+    /** Send a base64-encoded PCM audio chunk. */
+    sendAudio(base64Pcm) {
+        this.ws.send(JSON.stringify({
+            type: "input_audio_buffer.append",
+            audio: base64Pcm,
+        }));
+    }
+    /** Send a text message and request a response. */
+    sendText(text) {
+        this.ws.send(JSON.stringify({
+            type: "conversation.item.create",
+            item: {
+                type: "message",
+                role: "user",
+                content: [{ type: "input_text", text }],
+            },
+        }));
+        this.ws.send(JSON.stringify({
+            type: "response.create",
+            response: { modalities: ["text", "audio"] },
+        }));
+    }
+    /** Send a function/tool call result back to the model. */
+    sendFunctionResult(callId, output) {
+        this.ws.send(JSON.stringify({
+            type: "conversation.item.create",
+            item: {
+                type: "function_call_output",
+                call_id: callId,
+                output,
+            },
+        }));
+        this.ws.send(JSON.stringify({ type: "response.create" }));
+    }
+    /** Cancel the current response (interrupt). */
+    cancelResponse() {
+        this.ws.send(JSON.stringify({ type: "response.cancel" }));
+    }
+    /** Close the session gracefully. */
+    close() {
+        this.ws.close();
+    }
+}
+// ── RealtimeReceiver ───────────────────────────────────────────────
+/** Read half of a realtime session. */
+export class RealtimeReceiver {
+    queue = [];
+    resolve = null;
+    closed = false;
+    /** @internal */
+    constructor(ws) {
+        ws.addEventListener("message", (ev) => {
+            const event = parseEvent(typeof ev.data === "string" ? ev.data : "");
+            if (this.resolve) {
+                const r = this.resolve;
+                this.resolve = null;
+                r(event);
+            }
+            else {
+                this.queue.push(event);
+            }
+        });
+        ws.addEventListener("close", () => {
+            this.closed = true;
+            if (this.resolve) {
+                const r = this.resolve;
+                this.resolve = null;
+                r(null);
+            }
+        });
+        ws.addEventListener("error", () => {
+            this.closed = true;
+            if (this.resolve) {
+                const r = this.resolve;
+                this.resolve = null;
+                r(null);
+            }
+        });
+    }
+    /** Receive the next event. Returns null when the connection closes. */
+    recv() {
+        if (this.queue.length > 0) {
+            return Promise.resolve(this.queue.shift());
+        }
+        if (this.closed) {
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            this.resolve = resolve;
+        });
+    }
+    /** Async iterator support. */
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const event = await this.recv();
+            if (event === null)
+                break;
+            yield event;
+        }
+    }
+}
+/**
+ * Request an ephemeral token from the QAI proxy for direct voice connection.
+ * Call this before `realtimeConnectDirect` to get a scoped token.
+ *
+ * @param provider - Optional provider ("xai" default, "elevenlabs"). When
+ *   provider is "elevenlabs", the response contains a WebSocket proxy URL
+ *   (signed_url) instead of an ephemeral token.
+ */
+export async function realtimeSession(client, provider) {
+    const body = {};
+    if (provider)
+        body.provider = provider;
+    const { data } = await client._doJSON("POST", "/qai/v1/realtime/session", body);
+    return data;
+}
+/**
+ * End a realtime session and finalize billing.
+ * Call after disconnecting from the direct xAI WebSocket.
+ */
+export async function realtimeEnd(client, sessionId, durationSeconds) {
+    await client._doJSON("POST", "/qai/v1/realtime/end", {
+        session_id: sessionId,
+        duration_seconds: durationSeconds,
+    });
+}
+/**
+ * Refresh an ephemeral token for long sessions (>4 min).
+ * Returns a new ephemeral token string.
+ */
+export async function realtimeRefresh(client, sessionId) {
+    const { data } = await client._doJSON("POST", "/qai/v1/realtime/refresh", { session_id: sessionId });
+    return data.ephemeral_token;
+}
+/**
+ * Connect directly to xAI's realtime API with an ephemeral token.
+ * Much lower latency than the proxy path -- no extra hop.
+ * Use `realtimeSession()` first to get the token.
+ */
+export async function realtimeConnectDirect(ephemeralToken, config, wsUrl = "wss://api.x.ai/v1/realtime") {
+    const ws = new WebSocket(wsUrl, ["realtime", `token-${ephemeralToken}`]);
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error("Direct xAI WebSocket connection timed out (10s)"));
+        }, 10_000);
+        ws.addEventListener("open", () => { clearTimeout(timeout); resolve(); });
+        ws.addEventListener("error", () => { clearTimeout(timeout); reject(new Error("Direct xAI WebSocket connection failed")); });
+    });
+    sendSessionUpdate(ws, config);
+    return [new RealtimeSender(ws), new RealtimeReceiver(ws)];
+}
+// ── Connect (proxy path) ───────────────────────────────────────────
+/**
+ * Open a realtime voice session via the QAI proxy.
+ * Returns [sender, receiver] for bidirectional communication.
+ */
+export async function realtimeConnect(client, config) {
+    const baseUrl = client._baseUrl;
+    const apiKey = client._apiKey;
+    // Convert https:// -> wss://, http:// -> ws://
+    const wsBase = baseUrl
+        .replace(/^https:\/\//, "wss://")
+        .replace(/^http:\/\//, "ws://");
+    const url = `${wsBase}/qai/v1/realtime`;
+    // Browser WebSocket doesn't support custom headers, so pass token as protocol
+    // For Node.js, we'd use the headers option -- but the QAI proxy also accepts
+    // the token as a query parameter for browser compatibility.
+    const wsUrl = `${url}?token=${encodeURIComponent(apiKey)}`;
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error("WebSocket connection timed out (15s)"));
+        }, 15_000);
+        ws.addEventListener("open", () => {
+            clearTimeout(timeout);
+            resolve();
+        });
+        ws.addEventListener("error", () => {
+            clearTimeout(timeout);
+            reject(new Error("WebSocket connection failed"));
+        });
+    });
+    sendSessionUpdate(ws, config);
+    return [new RealtimeSender(ws), new RealtimeReceiver(ws)];
+}
+// ── Session update helper ──────────────────────────────────────────
+function sendSessionUpdate(ws, config) {
+    ws.send(JSON.stringify({
+        type: "session.update",
+        session: {
+            voice: config?.voice ?? "Sal",
+            instructions: config?.instructions ?? "",
+            input_audio_format: "pcm16",
+            output_audio_format: "pcm16",
+            input_audio_transcription: { model: "grok-2-audio" },
+            turn_detection: { type: "server_vad" },
+            tools: config?.tools ?? [],
+        },
+    }));
+}
+// ── Event parsing ──────────────────────────────────────────────────
+function parseEvent(data) {
+    let v;
+    try {
+        v = JSON.parse(data);
+    }
+    catch {
+        return { type: "unknown", raw: data };
+    }
+    const t = v.type;
+    switch (t) {
+        case "session.updated":
+            return { type: "session_ready" };
+        case "response.audio.delta":
+        case "response.output_audio.delta":
+            return { type: "audio_delta", delta: v.delta ?? "" };
+        case "response.audio_transcript.delta":
+        case "response.output_audio_transcript.delta":
+            return { type: "transcript_delta", delta: v.delta ?? "", source: "output" };
+        case "response.audio_transcript.done":
+        case "response.output_audio_transcript.done":
+            return { type: "transcript_done", transcript: v.transcript ?? "", source: "output" };
+        case "conversation.item.input_audio_transcription.completed":
+            return { type: "transcript_done", transcript: v.transcript ?? "", source: "input" };
+        case "input_audio_buffer.speech_started":
+            return { type: "speech_started" };
+        case "input_audio_buffer.speech_stopped":
+            return { type: "speech_stopped" };
+        case "response.function_call_arguments.done":
+            return {
+                type: "function_call",
+                name: v.name ?? "",
+                callId: v.call_id ?? "",
+                arguments: v.arguments ?? "",
+            };
+        case "response.done":
+            return { type: "response_done" };
+        case "error":
+            return { type: "error", message: v.error?.message ?? v.message ?? "unknown error" };
+        default:
+            return { type: "unknown", raw: v };
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,7 @@
+import type { QuantumClient } from "./client.js";
+import type { SessionChatRequest, SessionChatResponse } from "./types.js";
+/**
+ * Send a session-based chat request. The server manages conversation history.
+ * @internal — called by QuantumClient.chatSession()
+ */
+export declare function chatSession(client: QuantumClient, req: SessionChatRequest): Promise<SessionChatResponse>;

package/dist/session.js

@@ -0,0 +1,17 @@
+/**
+ * Send a session-based chat request. The server manages conversation history.
+ * @internal — called by QuantumClient.chatSession()
+ */
+export async function chatSession(client, req) {
+    const body = { ...req, stream: false };
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/chat/session", body);
+    if (data.response) {
+        if (!data.response.cost_ticks) {
+            data.response.cost_ticks = meta.costTicks;
+        }
+        if (!data.response.request_id) {
+            data.response.request_id = meta.requestId;
+        }
+    }
+    return data;
+}