quantum-ai-sdk 0.2.0 → 0.2.1

package/dist/documents.d.ts

@@ -0,0 +1,17 @@
+import type { QuantumClient } from "./client.js";
+import type { ChunkDocumentRequest, ChunkDocumentResponse, DocumentRequest, DocumentResponse, ProcessDocumentRequest, ProcessDocumentResponse } from "./types.js";
+/**
+ * Extract text content from a document (PDF, image, etc.).
+ * @internal — called by QuantumClient.extractDocument()
+ */
+export declare function extractDocument(client: QuantumClient, req: DocumentRequest): Promise<DocumentResponse>;
+/**
+ * Chunk a document into smaller pieces for embedding or processing.
+ * @internal — called by QuantumClient.chunkDocument()
+ */
+export declare function chunkDocument(client: QuantumClient, req: ChunkDocumentRequest): Promise<ChunkDocumentResponse>;
+/**
+ * Process a document with extraction + optional instructions.
+ * @internal — called by QuantumClient.processDocument()
+ */
+export declare function processDocument(client: QuantumClient, req: ProcessDocumentRequest): Promise<ProcessDocumentResponse>;

package/dist/documents.js

@@ -0,0 +1,42 @@
+/**
+ * Extract text content from a document (PDF, image, etc.).
+ * @internal — called by QuantumClient.extractDocument()
+ */
+export async function extractDocument(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/documents/extract", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}
+/**
+ * Chunk a document into smaller pieces for embedding or processing.
+ * @internal — called by QuantumClient.chunkDocument()
+ */
+export async function chunkDocument(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/documents/chunk", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}
+/**
+ * Process a document with extraction + optional instructions.
+ * @internal — called by QuantumClient.processDocument()
+ */
+export async function processDocument(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/documents/process", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,7 @@
+import type { QuantumClient } from "./client.js";
+import type { EmbedRequest, EmbedResponse } from "./types.js";
+/**
+ * Generate text embeddings for the given inputs.
+ * @internal — called by QuantumClient.embed()
+ */
+export declare function embed(client: QuantumClient, req: EmbedRequest): Promise<EmbedResponse>;

package/dist/embeddings.js

@@ -0,0 +1,14 @@
+/**
+ * Generate text embeddings for the given inputs.
+ * @internal — called by QuantumClient.embed()
+ */
+export async function embed(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/embeddings", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * APIError is thrown when the API responds with a non-2xx status code.
+ */
+export declare class APIError extends Error {
+    /** HTTP status code from the response. */
+    readonly statusCode: number;
+    /** Error type from the API (e.g. "invalid_request", "rate_limit"). */
+    readonly code: string;
+    /** Unique request identifier from the X-QAI-Request-Id header. */
+    readonly requestId: string | undefined;
+    constructor(statusCode: number, code: string, message: string, requestId?: string);
+    /** True if the error is a 429 rate limit response. */
+    isRateLimit(): boolean;
+    /** True if the error is a 401 or 403 authentication/authorization failure. */
+    isAuth(): boolean;
+    /** True if the error is a 404 not found response. */
+    isNotFound(): boolean;
+}
+/** Check whether an error is a rate limit APIError. */
+export declare function isRateLimitError(err: unknown): err is APIError;
+/** Check whether an error is an authentication APIError. */
+export declare function isAuthError(err: unknown): err is APIError;
+/** Check whether an error is a not found APIError. */
+export declare function isNotFoundError(err: unknown): err is APIError;
+/**
+ * Parse an API error response into an APIError.
+ * @internal
+ */
+export declare function parseAPIError(response: Response, requestId: string): Promise<APIError>;

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * APIError is thrown when the API responds with a non-2xx status code.
+ */
+export class APIError extends Error {
+    /** HTTP status code from the response. */
+    statusCode;
+    /** Error type from the API (e.g. "invalid_request", "rate_limit"). */
+    code;
+    /** Unique request identifier from the X-QAI-Request-Id header. */
+    requestId;
+    constructor(statusCode, code, message, requestId) {
+        const msg = requestId
+            ? `qai: ${statusCode} ${code}: ${message} (request_id=${requestId})`
+            : `qai: ${statusCode} ${code}: ${message}`;
+        super(msg);
+        this.name = "APIError";
+        this.statusCode = statusCode;
+        this.code = code;
+        this.requestId = requestId;
+    }
+    /** True if the error is a 429 rate limit response. */
+    isRateLimit() {
+        return this.statusCode === 429;
+    }
+    /** True if the error is a 401 or 403 authentication/authorization failure. */
+    isAuth() {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+    /** True if the error is a 404 not found response. */
+    isNotFound() {
+        return this.statusCode === 404;
+    }
+}
+/** Check whether an error is a rate limit APIError. */
+export function isRateLimitError(err) {
+    return err instanceof APIError && err.isRateLimit();
+}
+/** Check whether an error is an authentication APIError. */
+export function isAuthError(err) {
+    return err instanceof APIError && err.isAuth();
+}
+/** Check whether an error is a not found APIError. */
+export function isNotFoundError(err) {
+    return err instanceof APIError && err.isNotFound();
+}
+/**
+ * Parse an API error response into an APIError.
+ * @internal
+ */
+export async function parseAPIError(response, requestId) {
+    const bodyText = await response.text();
+    let code = response.statusText || "Unknown";
+    let message = bodyText;
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (parsed.error?.message) {
+            message = parsed.error.message;
+            if (parsed.error.code) {
+                code = parsed.error.code;
+            }
+            else if (parsed.error.type) {
+                code = parsed.error.type;
+            }
+        }
+    }
+    catch {
+        // Body is not JSON — use raw text as message.
+    }
+    return new APIError(response.status, code, message, requestId || undefined);
+}

package/dist/image.d.ts

@@ -0,0 +1,12 @@
+import type { QuantumClient } from "./client.js";
+import type { ImageEditRequest, ImageEditResponse, ImageRequest, ImageResponse } from "./types.js";
+/**
+ * Generate images from a text prompt.
+ * @internal — called by QuantumClient.generateImage()
+ */
+export declare function generateImage(client: QuantumClient, req: ImageRequest): Promise<ImageResponse>;
+/**
+ * Edit images using an AI model.
+ * @internal — called by QuantumClient.editImage()
+ */
+export declare function editImage(client: QuantumClient, req: ImageEditRequest): Promise<ImageEditResponse>;

package/dist/image.js

@@ -0,0 +1,28 @@
+/**
+ * Generate images from a text prompt.
+ * @internal — called by QuantumClient.generateImage()
+ */
+export async function generateImage(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/images/generate", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}
+/**
+ * Edit images using an AI model.
+ * @internal — called by QuantumClient.editImage()
+ */
+export async function editImage(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/images/edit", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { QuantumClient } from "./client.js";
+export { APIError, isRateLimitError, isAuthError, isNotFoundError, } from "./errors.js";
+export { responseText, responseThinking, responseToolCalls } from "./chat.js";
+export { realtimeConnect, realtimeConnectDirect, realtimeSession, realtimeEnd, realtimeRefresh, RealtimeSender, RealtimeReceiver } from "./realtime.js";
+export type { RealtimeConfig, RealtimeEvent, RealtimeSession } from "./realtime.js";
+export { contact } from "./contact.js";
+export type { ClientOptions, ResponseMeta, ChatRequest, ChatMessage, ChatTool, ContentBlock, ChatUsage, ChatResponse, StreamEvent, StreamDelta, StreamToolUse, SessionChatRequest, SessionChatResponse, SessionToolResult, ContextConfig, ContextMetadata, AgentRequest, AgentWorkerConfig, AgentEvent, MissionRequest, MissionWorkerConfig, MissionEvent, ImageRequest, ImageResponse, GeneratedImage, ImageEditRequest, ImageEditResponse, TTSRequest, TTSResponse, STTRequest, STTResponse, MusicRequest, MusicClip, MusicResponse, SoundEffectRequest, SoundEffectResponse, DialogueRequest, DialogueResponse, DialogueVoice, SpeechToSpeechRequest, SpeechToSpeechResponse, IsolateVoiceRequest, IsolateVoiceResponse, RemixVoiceRequest, RemixVoiceResponse, DubRequest, DubResponse, AlignRequest, AlignResponse, AlignedWord, VoiceDesignRequest, VoiceDesignResponse, VoicePreview, StarfishTTSRequest, StarfishTTSResponse, VideoRequest, VideoResponse, GeneratedVideo, VideoStudioRequest, VideoTranslateRequest, PhotoAvatarRequest, DigitalTwinRequest, AsyncJobResponse, AvatarsResponse, HeyGenAvatar, HeyGenTemplatesResponse, HeyGenTemplate, HeyGenVoicesResponse, HeyGenVoice, EmbedRequest, EmbedResponse, DocumentRequest, DocumentResponse, ChunkDocumentRequest, ChunkDocumentResponse, DocumentChunk, ProcessDocumentRequest, ProcessDocumentResponse, RAGSearchRequest, RAGSearchResponse, RAGResult, RAGCorpus, SurrealRAGSearchRequest, SurrealRAGSearchResponse, SurrealRAGResult, SurrealRAGProvidersResponse, SurrealRAGProviderInfo, ModelInfo, PricingInfo, BalanceResponse, UsageEntry, UsageResponse, UsageQuery, UsageSummaryMonth, UsageSummaryResponse, PricingEntry, AccountPricingResponse, JobCreateRequest, JobCreateResponse, JobStatusResponse, JobListResponse, JobListItem, CreateKeyRequest, CreateKeyResponse, KeyDetails, ListKeysResponse, ComputeTemplate, TemplatesResponse, ProvisionRequest, ProvisionResponse, ComputeInstanceInfo, InstancesResponse, InstanceDetailInfo, InstanceResponse, SSHKeyRequest, DeleteResponse, VoiceInfo, VoicesResponse, CloneVoiceRequest, CloneVoiceResponse, ContactRequest, BatchJobInput, BatchSubmitRequest, BatchSubmitResponse, BatchJsonlResponse, BatchJobInfo, BatchJobsResponse, CreditPack, CreditPacksResponse, CreditPurchaseRequest, CreditPurchaseResponse, CreditBalanceResponse, CreditTier, CreditTiersResponse, DevProgramApplyRequest, DevProgramApplyResponse, AuthUser, AuthResponse, AuthAppleRequest, StatusResponse, } from "./types.js";
+export { DEFAULT_BASE_URL, TICKS_PER_USD } from "./types.js";
+import type { ChatMessage } from "./types.js";
+/** Create a user message. */
+export declare function userMessage(content: string): ChatMessage;
+/** Create an assistant message. */
+export declare function assistantMessage(content: string): ChatMessage;
+/** Create a system message. */
+export declare function systemMessage(content: string): ChatMessage;
+/** Create a tool result message. */
+export declare function toolMessage(toolCallId: string, content: string, isError?: boolean): ChatMessage;

package/dist/index.js

@@ -0,0 +1,33 @@
+// ── Client ──────────────────────────────────────────────────────────
+export { QuantumClient } from "./client.js";
+// ── Errors ──────────────────────────────────────────────────────────
+export { APIError, isRateLimitError, isAuthError, isNotFoundError, } from "./errors.js";
+// ── Chat helpers ────────────────────────────────────────────────────
+export { responseText, responseThinking, responseToolCalls } from "./chat.js";
+// ── Realtime Voice ──────────────────────────────────────────────────
+export { realtimeConnect, realtimeConnectDirect, realtimeSession, realtimeEnd, realtimeRefresh, RealtimeSender, RealtimeReceiver } from "./realtime.js";
+// ── Contact (standalone, no auth required) ──────────────────────────
+export { contact } from "./contact.js";
+// ── Constants ───────────────────────────────────────────────────────
+export { DEFAULT_BASE_URL, TICKS_PER_USD } from "./types.js";
+/** Create a user message. */
+export function userMessage(content) {
+    return { role: "user", content };
+}
+/** Create an assistant message. */
+export function assistantMessage(content) {
+    return { role: "assistant", content };
+}
+/** Create a system message. */
+export function systemMessage(content) {
+    return { role: "system", content };
+}
+/** Create a tool result message. */
+export function toolMessage(toolCallId, content, isError) {
+    return {
+        role: "tool",
+        tool_call_id: toolCallId,
+        content,
+        is_error: isError,
+    };
+}

package/dist/jobs.d.ts

@@ -0,0 +1,28 @@
+import type { QuantumClient } from "./client.js";
+import type { JobCreateRequest, JobCreateResponse, JobListResponse, JobStatusResponse } from "./types.js";
+/**
+ * Create an async job. Returns the job ID for polling.
+ * @internal
+ */
+export declare function createJob(client: QuantumClient, req: JobCreateRequest): Promise<JobCreateResponse>;
+/**
+ * Check the status of an async job.
+ * @internal
+ */
+export declare function getJob(client: QuantumClient, jobId: string): Promise<JobStatusResponse>;
+/**
+ * Poll a job until completion or timeout.
+ * @internal
+ */
+export declare function pollJob(client: QuantumClient, jobId: string, intervalMs?: number, maxAttempts?: number): Promise<JobStatusResponse>;
+/**
+ * List all jobs for the authenticated user.
+ * @internal
+ */
+export declare function listJobs(client: QuantumClient): Promise<JobListResponse>;
+/**
+ * Convenience method for 3D model generation via the async jobs system.
+ * Submits a job with type "3d/generate" and the given parameters.
+ * @internal
+ */
+export declare function generate3D(client: QuantumClient, model: string, prompt?: string, imageUrl?: string): Promise<JobCreateResponse>;

package/dist/jobs.js

@@ -0,0 +1,56 @@
+/**
+ * Create an async job. Returns the job ID for polling.
+ * @internal
+ */
+export async function createJob(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/jobs", req);
+    return data;
+}
+/**
+ * Check the status of an async job.
+ * @internal
+ */
+export async function getJob(client, jobId) {
+    const { data } = await client._doJSON("GET", `/qai/v1/jobs/${jobId}`, undefined);
+    return data;
+}
+/**
+ * Poll a job until completion or timeout.
+ * @internal
+ */
+export async function pollJob(client, jobId, intervalMs = 2000, maxAttempts = 150) {
+    for (let i = 0; i < maxAttempts; i++) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        const status = await getJob(client, jobId);
+        if (status.status === "completed" || status.status === "failed") {
+            return status;
+        }
+    }
+    return {
+        job_id: jobId,
+        status: "timeout",
+        error: `Job polling timed out after ${maxAttempts} attempts`,
+        cost_ticks: 0,
+    };
+}
+/**
+ * List all jobs for the authenticated user.
+ * @internal
+ */
+export async function listJobs(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/jobs", undefined);
+    return data;
+}
+/**
+ * Convenience method for 3D model generation via the async jobs system.
+ * Submits a job with type "3d/generate" and the given parameters.
+ * @internal
+ */
+export async function generate3D(client, model, prompt, imageUrl) {
+    const params = { model };
+    if (prompt)
+        params.prompt = prompt;
+    if (imageUrl)
+        params.image_url = imageUrl;
+    return createJob(client, { type: "3d/generate", params });
+}

package/dist/keys.d.ts

@@ -0,0 +1,17 @@
+import type { QuantumClient } from "./client.js";
+import type { CreateKeyRequest, CreateKeyResponse, ListKeysResponse, StatusResponse } from "./types.js";
+/**
+ * Create a scoped API key.
+ * @internal — called by QuantumClient.createKey()
+ */
+export declare function createKey(client: QuantumClient, req: CreateKeyRequest): Promise<CreateKeyResponse>;
+/**
+ * List all API keys for the authenticated user.
+ * @internal — called by QuantumClient.listKeys()
+ */
+export declare function listKeys(client: QuantumClient): Promise<ListKeysResponse>;
+/**
+ * Revoke an API key.
+ * @internal — called by QuantumClient.revokeKey()
+ */
+export declare function revokeKey(client: QuantumClient, id: string): Promise<StatusResponse>;

package/dist/keys.js

@@ -0,0 +1,24 @@
+/**
+ * Create a scoped API key.
+ * @internal — called by QuantumClient.createKey()
+ */
+export async function createKey(client, req) {
+    const { data } = await client._doJSON("POST", "/qai/v1/keys", req);
+    return data;
+}
+/**
+ * List all API keys for the authenticated user.
+ * @internal — called by QuantumClient.listKeys()
+ */
+export async function listKeys(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/keys", undefined);
+    return data;
+}
+/**
+ * Revoke an API key.
+ * @internal — called by QuantumClient.revokeKey()
+ */
+export async function revokeKey(client, id) {
+    const { data } = await client._doJSON("DELETE", `/qai/v1/keys/${id}`, undefined);
+    return data;
+}

package/dist/models.d.ts

@@ -0,0 +1,12 @@
+import type { QuantumClient } from "./client.js";
+import type { ModelInfo, PricingInfo } from "./types.js";
+/**
+ * List all available models with provider and pricing information.
+ * @internal — called by QuantumClient.listModels()
+ */
+export declare function listModels(client: QuantumClient): Promise<ModelInfo[]>;
+/**
+ * Get the complete pricing table for all models.
+ * @internal — called by QuantumClient.getPricing()
+ */
+export declare function getPricing(client: QuantumClient): Promise<PricingInfo[]>;

package/dist/models.js

@@ -0,0 +1,16 @@
+/**
+ * List all available models with provider and pricing information.
+ * @internal — called by QuantumClient.listModels()
+ */
+export async function listModels(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/models", undefined);
+    return data.models;
+}
+/**
+ * Get the complete pricing table for all models.
+ * @internal — called by QuantumClient.getPricing()
+ */
+export async function getPricing(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/pricing", undefined);
+    return data.pricing;
+}

package/dist/rag.d.ts

@@ -0,0 +1,22 @@
+import type { QuantumClient } from "./client.js";
+import type { RAGCorpus, RAGSearchRequest, RAGSearchResponse, SurrealRAGProvidersResponse, SurrealRAGSearchRequest, SurrealRAGSearchResponse } from "./types.js";
+/**
+ * Search Vertex AI RAG corpora for relevant documentation.
+ * @internal — called by QuantumClient.ragSearch()
+ */
+export declare function ragSearch(client: QuantumClient, req: RAGSearchRequest): Promise<RAGSearchResponse>;
+/**
+ * List available Vertex AI RAG corpora.
+ * @internal — called by QuantumClient.ragCorpora()
+ */
+export declare function ragCorpora(client: QuantumClient): Promise<RAGCorpus[]>;
+/**
+ * Search provider API documentation via SurrealDB vector search.
+ * @internal — called by QuantumClient.surrealRagSearch()
+ */
+export declare function surrealRagSearch(client: QuantumClient, req: SurrealRAGSearchRequest): Promise<SurrealRAGSearchResponse>;
+/**
+ * List available documentation providers in SurrealDB RAG.
+ * @internal — called by QuantumClient.surrealRagProviders()
+ */
+export declare function surrealRagProviders(client: QuantumClient): Promise<SurrealRAGProvidersResponse>;

package/dist/rag.js

@@ -0,0 +1,44 @@
+/**
+ * Search Vertex AI RAG corpora for relevant documentation.
+ * @internal — called by QuantumClient.ragSearch()
+ */
+export async function ragSearch(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/rag/search", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}
+/**
+ * List available Vertex AI RAG corpora.
+ * @internal — called by QuantumClient.ragCorpora()
+ */
+export async function ragCorpora(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/rag/corpora", undefined);
+    return data.corpora;
+}
+/**
+ * Search provider API documentation via SurrealDB vector search.
+ * @internal — called by QuantumClient.surrealRagSearch()
+ */
+export async function surrealRagSearch(client, req) {
+    const { data, meta } = await client._doJSON("POST", "/qai/v1/rag/surreal/search", req);
+    if (!data.cost_ticks) {
+        data.cost_ticks = meta.costTicks;
+    }
+    if (!data.request_id) {
+        data.request_id = meta.requestId;
+    }
+    return data;
+}
+/**
+ * List available documentation providers in SurrealDB RAG.
+ * @internal — called by QuantumClient.surrealRagProviders()
+ */
+export async function surrealRagProviders(client) {
+    const { data } = await client._doJSON("GET", "/qai/v1/rag/surreal/providers", undefined);
+    return data;
+}

package/dist/realtime.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Realtime voice sessions via WebSocket.
+ *
+ * Connects to the QAI Realtime API for bidirectional audio streaming
+ * with voice activity detection, transcription, and tool calling.
+ */
+import type { QuantumClient } from "./client.js";
+/** Configuration for a realtime voice session. */
+export interface RealtimeConfig {
+    /** Voice to use (e.g. "Sal", "Eve", "Vesper"). Default: "Sal". */
+    voice?: string;
+    /** System instructions for the AI. */
+    instructions?: string;
+    /** PCM sample rate in Hz. Default: 24000. */
+    sampleRate?: number;
+    /** Tool definitions (xAI Realtime API format). */
+    tools?: Record<string, unknown>[];
+}
+/** Parsed incoming event from the realtime API. */
+export type RealtimeEvent = {
+    type: "session_ready";
+} | {
+    type: "audio_delta";
+    delta: string;
+} | {
+    type: "transcript_delta";
+    delta: string;
+    source: "input" | "output";
+} | {
+    type: "transcript_done";
+    transcript: string;
+    source: "input" | "output";
+} | {
+    type: "speech_started";
+} | {
+    type: "speech_stopped";
+} | {
+    type: "function_call";
+    name: string;
+    callId: string;
+    arguments: string;
+} | {
+    type: "response_done";
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "unknown";
+    raw: unknown;
+};
+/** Write half of a realtime session. */
+export declare class RealtimeSender {
+    private ws;
+    /** @internal */
+    constructor(ws: WebSocket);
+    /** Send a base64-encoded PCM audio chunk. */
+    sendAudio(base64Pcm: string): void;
+    /** Send a text message and request a response. */
+    sendText(text: string): void;
+    /** Send a function/tool call result back to the model. */
+    sendFunctionResult(callId: string, output: string): void;
+    /** Cancel the current response (interrupt). */
+    cancelResponse(): void;
+    /** Close the session gracefully. */
+    close(): void;
+}
+/** Read half of a realtime session. */
+export declare class RealtimeReceiver {
+    private queue;
+    private resolve;
+    private closed;
+    /** @internal */
+    constructor(ws: WebSocket);
+    /** Receive the next event. Returns null when the connection closes. */
+    recv(): Promise<RealtimeEvent | null>;
+    /** Async iterator support. */
+    [Symbol.asyncIterator](): AsyncIterableIterator<RealtimeEvent>;
+}
+/** Response from POST /qai/v1/realtime/session. */
+export interface RealtimeSession {
+    /** Ephemeral token for direct WebSocket connection (xAI/OpenAI). */
+    ephemeral_token: string;
+    /** WebSocket URL to connect to. */
+    url: string;
+    /** Signed WebSocket URL (ElevenLabs returns this field). */
+    signed_url?: string;
+    /** Session ID for billing (pass to realtimeEnd on disconnect). */
+    session_id: string;
+    /** Provider name (e.g. "xai", "elevenlabs"). */
+    provider?: string;
+}
+/**
+ * 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 declare function realtimeSession(client: QuantumClient, provider?: string): Promise<RealtimeSession>;
+/**
+ * End a realtime session and finalize billing.
+ * Call after disconnecting from the direct xAI WebSocket.
+ */
+export declare function realtimeEnd(client: QuantumClient, sessionId: string, durationSeconds: number): Promise<void>;
+/**
+ * Refresh an ephemeral token for long sessions (>4 min).
+ * Returns a new ephemeral token string.
+ */
+export declare function realtimeRefresh(client: QuantumClient, sessionId: string): Promise<string>;
+/**
+ * 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 declare function realtimeConnectDirect(ephemeralToken: string, config?: RealtimeConfig, wsUrl?: string): Promise<[RealtimeSender, RealtimeReceiver]>;
+/**
+ * Open a realtime voice session via the QAI proxy.
+ * Returns [sender, receiver] for bidirectional communication.
+ */
+export declare function realtimeConnect(client: QuantumClient, config?: RealtimeConfig): Promise<[RealtimeSender, RealtimeReceiver]>;