quantum-ai-sdk 0.2.0 → 0.2.1

package/dist/client.d.ts

@@ -0,0 +1,251 @@
+import { RealtimeSender, RealtimeReceiver } from "./realtime.js";
+import type { RealtimeConfig, RealtimeSession } from "./realtime.js";
+import type { AccountPricingResponse, AgentEvent, AgentRequest, AlignRequest, AlignResponse, AsyncJobResponse, AuthAppleRequest, AuthResponse, AvatarsResponse, BalanceResponse, BatchJobInfo, BatchJobsResponse, BatchJsonlResponse, BatchSubmitRequest, BatchSubmitResponse, ChatRequest, ChatResponse, ChunkDocumentRequest, ChunkDocumentResponse, ClientOptions, CloneVoiceRequest, CloneVoiceResponse, CreateKeyRequest, CreateKeyResponse, CreditBalanceResponse, CreditPacksResponse, CreditPurchaseRequest, CreditPurchaseResponse, CreditTiersResponse, DeleteResponse, DevProgramApplyRequest, DevProgramApplyResponse, DialogueRequest, DialogueResponse, DigitalTwinRequest, DocumentRequest, DocumentResponse, DubRequest, DubResponse, EmbedRequest, EmbedResponse, HeyGenTemplatesResponse, HeyGenVoicesResponse, ImageEditRequest, ImageEditResponse, ImageRequest, ImageResponse, InstanceResponse, InstancesResponse, IsolateVoiceRequest, IsolateVoiceResponse, JobCreateRequest, JobCreateResponse, JobListResponse, JobStatusResponse, ListKeysResponse, MissionEvent, MissionRequest, ModelInfo, MusicRequest, MusicResponse, PhotoAvatarRequest, PricingInfo, ProcessDocumentRequest, ProcessDocumentResponse, ProvisionRequest, ProvisionResponse, RAGCorpus, RAGSearchRequest, RAGSearchResponse, RemixVoiceRequest, RemixVoiceResponse, ResponseMeta, SessionChatRequest, SessionChatResponse, SoundEffectRequest, SoundEffectResponse, SpeechToSpeechRequest, SpeechToSpeechResponse, SSHKeyRequest, StarfishTTSRequest, StarfishTTSResponse, StatusResponse, STTRequest, STTResponse, StreamEvent, SurrealRAGProvidersResponse, SurrealRAGSearchRequest, SurrealRAGSearchResponse, TemplatesResponse, TTSRequest, TTSResponse, UsageQuery, UsageResponse, UsageSummaryResponse, VideoRequest, VideoResponse, VideoStudioRequest, VideoTranslateRequest, VoiceDesignRequest, VoiceDesignResponse, VoicesResponse } from "./types.js";
+/**
+ * QuantumClient is the Quantum AI API client.
+ *
+ * @example
+ * ```ts
+ * const client = new QuantumClient("qai_key_xxx");
+ *
+ * const resp = await client.chat({
+ *   model: "claude-sonnet-4-6",
+ *   messages: [{ role: "user", content: "Hello!" }],
+ * });
+ * ```
+ */
+export declare class QuantumClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly _fetch;
+    constructor(apiKey: string, options?: ClientOptions);
+    /** @internal — used by realtime module to build WebSocket URL. */
+    get _baseUrl(): string;
+    /** @internal — used by realtime module for auth. */
+    get _apiKey(): string;
+    /** Send a non-streaming chat request. */
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Send a streaming chat request. Returns an AsyncIterableIterator of StreamEvents.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.chatStream({
+     *   model: "gpt-5-mini",
+     *   messages: [{ role: "user", content: "Write a haiku" }],
+     * })) {
+     *   process.stdout.write(event.delta?.text ?? "");
+     * }
+     * ```
+     */
+    chatStream(req: ChatRequest, signal?: AbortSignal): AsyncIterableIterator<StreamEvent>;
+    /**
+     * Send a session-based chat request. The server manages conversation history.
+     *
+     * @example
+     * ```ts
+     * // Start a new session
+     * const resp = await client.chatSession({
+     *   message: "Hello!",
+     *   model: "claude-sonnet-4-6",
+     * });
+     *
+     * // Continue the conversation
+     * const resp2 = await client.chatSession({
+     *   session_id: resp.session_id,
+     *   message: "Tell me more",
+     * });
+     * ```
+     */
+    chatSession(req: SessionChatRequest): Promise<SessionChatResponse>;
+    /**
+     * Run a server-side agent orchestration. Streams SSE events as the
+     * conductor delegates work to workers.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.agentRun({
+     *   task: "Research the latest AI papers and summarize them",
+     * })) {
+     *   console.log(event.type, event);
+     * }
+     * ```
+     */
+    agentRun(req: AgentRequest, signal?: AbortSignal): AsyncIterableIterator<AgentEvent>;
+    /**
+     * Run a full mission orchestration. Streams SSE events as the conductor
+     * plans, delegates, and workers execute.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.missionRun({
+     *   goal: "Build a REST API server in Go",
+     * })) {
+     *   console.log(event.type, event);
+     * }
+     * ```
+     */
+    missionRun(req: MissionRequest, signal?: AbortSignal): AsyncIterableIterator<MissionEvent>;
+    /** Generate images from a text prompt. */
+    generateImage(req: ImageRequest): Promise<ImageResponse>;
+    /** Edit images using an AI model. */
+    editImage(req: ImageEditRequest): Promise<ImageEditResponse>;
+    /** Generate speech from text. */
+    speak(req: TTSRequest): Promise<TTSResponse>;
+    /** Convert speech to text. */
+    transcribe(req: STTRequest): Promise<STTResponse>;
+    /** Generate sound effects from a text prompt (ElevenLabs). */
+    soundEffects(req: SoundEffectRequest): Promise<SoundEffectResponse>;
+    /** Generate music from a text prompt. */
+    generateMusic(req: MusicRequest): Promise<MusicResponse>;
+    /** Generate multi-speaker dialogue audio (ElevenLabs). */
+    dialogue(req: DialogueRequest): Promise<DialogueResponse>;
+    /** Convert speech audio to a different voice (ElevenLabs). */
+    speechToSpeech(req: SpeechToSpeechRequest): Promise<SpeechToSpeechResponse>;
+    /** Remove background noise and isolate speech (ElevenLabs). */
+    isolateVoice(req: IsolateVoiceRequest): Promise<IsolateVoiceResponse>;
+    /** Transform a voice by modifying attributes (ElevenLabs). */
+    remixVoice(req: RemixVoiceRequest): Promise<RemixVoiceResponse>;
+    /** Dub audio/video into a target language (ElevenLabs). */
+    dub(req: DubRequest): Promise<DubResponse>;
+    /** Get word-level timestamps for audio+text alignment (ElevenLabs). */
+    align(req: AlignRequest): Promise<AlignResponse>;
+    /** Generate voice previews from a text description (ElevenLabs). */
+    voiceDesign(req: VoiceDesignRequest): Promise<VoiceDesignResponse>;
+    /** Generate speech using HeyGen's Starfish TTS model. */
+    starfishTTS(req: StarfishTTSRequest): Promise<StarfishTTSResponse>;
+    /**
+     * Generate a video from a text prompt.
+     *
+     * Video generation is slow (30s-5min). For production use, consider
+     * submitting via the Jobs API instead.
+     */
+    generateVideo(req: VideoRequest): Promise<VideoResponse>;
+    /** Create a talking-head video via HeyGen Studio. Returns an async job. */
+    videoStudio(req: VideoStudioRequest): Promise<AsyncJobResponse>;
+    /** Submit a video translation job via HeyGen. Returns an async job. */
+    videoTranslate(req: VideoTranslateRequest): Promise<AsyncJobResponse>;
+    /** Create a photo avatar via HeyGen. Returns an async job. */
+    videoPhotoAvatar(req: PhotoAvatarRequest): Promise<AsyncJobResponse>;
+    /** Create a digital twin via HeyGen. Returns an async job. */
+    videoDigitalTwin(req: DigitalTwinRequest): Promise<AsyncJobResponse>;
+    /** List available HeyGen avatars. */
+    videoAvatars(): Promise<AvatarsResponse>;
+    /** List available HeyGen templates. */
+    videoTemplates(): Promise<HeyGenTemplatesResponse>;
+    /** List available HeyGen voices. */
+    videoHeygenVoices(): Promise<HeyGenVoicesResponse>;
+    /** Generate text embeddings for the given inputs. */
+    embed(req: EmbedRequest): Promise<EmbedResponse>;
+    /** Extract text content from a document (PDF, image, etc.). */
+    extractDocument(req: DocumentRequest): Promise<DocumentResponse>;
+    /** Chunk a document into smaller pieces for embedding or processing. */
+    chunkDocument(req: ChunkDocumentRequest): Promise<ChunkDocumentResponse>;
+    /** Process a document with extraction + optional instructions. */
+    processDocument(req: ProcessDocumentRequest): Promise<ProcessDocumentResponse>;
+    /** Search Vertex AI RAG corpora for relevant documentation. */
+    ragSearch(req: RAGSearchRequest): Promise<RAGSearchResponse>;
+    /** List available Vertex AI RAG corpora. */
+    ragCorpora(): Promise<RAGCorpus[]>;
+    /** Search provider API documentation via SurrealDB vector search. */
+    surrealRagSearch(req: SurrealRAGSearchRequest): Promise<SurrealRAGSearchResponse>;
+    /** List available documentation providers in SurrealDB RAG. */
+    surrealRagProviders(): Promise<SurrealRAGProvidersResponse>;
+    /** List all available models with provider and pricing information. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Get the complete pricing table for all models. */
+    getPricing(): Promise<PricingInfo[]>;
+    /** Get the account credit balance. */
+    accountBalance(): Promise<BalanceResponse>;
+    /** Get paginated usage history. */
+    accountUsage(query?: UsageQuery): Promise<UsageResponse>;
+    /** Get monthly usage summary. */
+    accountUsageSummary(months?: number): Promise<UsageSummaryResponse>;
+    /** Get the full pricing table (model ID -> pricing entry map). */
+    accountPricing(): Promise<AccountPricingResponse>;
+    /** Create an async job. Returns the job ID for polling. */
+    createJob(req: JobCreateRequest): Promise<JobCreateResponse>;
+    /** Check the status of an async job. */
+    getJob(jobId: string): Promise<JobStatusResponse>;
+    /**
+     * Poll a job until completion or timeout.
+     *
+     * @param jobId - Job ID to poll.
+     * @param intervalMs - Polling interval in milliseconds (default 2000).
+     * @param maxAttempts - Maximum poll attempts before timeout (default 150).
+     */
+    pollJob(jobId: string, intervalMs?: number, maxAttempts?: number): Promise<JobStatusResponse>;
+    /** List all jobs for the authenticated user. */
+    listJobs(): Promise<JobListResponse>;
+    /** Create a scoped API key. */
+    createKey(req: CreateKeyRequest): Promise<CreateKeyResponse>;
+    /** List all API keys for the authenticated user. */
+    listKeys(): Promise<ListKeysResponse>;
+    /** Revoke an API key. */
+    revokeKey(id: string): Promise<StatusResponse>;
+    /** Get available compute templates with pricing. */
+    computeTemplates(): Promise<TemplatesResponse>;
+    /** Provision a new GPU compute instance. */
+    computeProvision(req: ProvisionRequest): Promise<ProvisionResponse>;
+    /** List all compute instances for the authenticated user. */
+    computeInstances(): Promise<InstancesResponse>;
+    /** Get full status of a single compute instance. */
+    computeInstance(id: string): Promise<InstanceResponse>;
+    /** Tear down a compute instance and finalize billing. */
+    computeDelete(id: string): Promise<DeleteResponse>;
+    /** Inject an SSH public key into a running instance. */
+    computeSSHKey(id: string, req: SSHKeyRequest): Promise<StatusResponse>;
+    /** Reset the inactivity timer on a compute instance. */
+    computeKeepalive(id: string): Promise<StatusResponse>;
+    /** List all available voices (ElevenLabs). */
+    listVoices(): Promise<VoicesResponse>;
+    /** Create an instant voice clone from audio samples (ElevenLabs). */
+    cloneVoice(req: CloneVoiceRequest): Promise<CloneVoiceResponse>;
+    /** Delete a cloned voice (ElevenLabs). */
+    deleteVoice(id: string): Promise<StatusResponse>;
+    /**
+     * Open a realtime voice session via WebSocket (proxy path).
+     * Returns [sender, receiver] for bidirectional audio communication.
+     */
+    realtimeConnect(config?: RealtimeConfig): Promise<[RealtimeSender, RealtimeReceiver]>;
+    /** Request an ephemeral token for direct xAI voice connection (lower latency). */
+    realtimeSession(): Promise<RealtimeSession>;
+    /** End a realtime session and finalize billing. */
+    realtimeEnd(sessionId: string, durationSeconds: number): Promise<void>;
+    /** Refresh an ephemeral token for long sessions (>4 min). */
+    realtimeRefresh(sessionId: string): Promise<string>;
+    /** Submit a batch of jobs for processing. */
+    batchSubmit(req: BatchSubmitRequest): Promise<BatchSubmitResponse>;
+    /** Submit a batch of jobs using JSONL format. */
+    batchSubmitJsonl(jsonl: string): Promise<BatchJsonlResponse>;
+    /** List all batch jobs for the account. */
+    batchJobs(): Promise<BatchJobsResponse>;
+    /** Get the status and result of a single batch job. */
+    batchJob(id: string): Promise<BatchJobInfo>;
+    /** List available credit packs (no auth required). */
+    creditPacks(): Promise<CreditPacksResponse>;
+    /** Purchase a credit pack. Returns a checkout URL for payment. */
+    creditPurchase(req: CreditPurchaseRequest): Promise<CreditPurchaseResponse>;
+    /** Get the current credit balance. */
+    creditBalance(): Promise<CreditBalanceResponse>;
+    /** List available credit tiers (no auth required). */
+    creditTiers(): Promise<CreditTiersResponse>;
+    /** Apply for the developer program. */
+    devProgramApply(req: DevProgramApplyRequest): Promise<DevProgramApplyResponse>;
+    /** Authenticate with Apple Sign-In. */
+    authApple(req: AuthAppleRequest): Promise<AuthResponse>;
+    /**
+     * Send a JSON request and decode the JSON response.
+     * @internal
+     */
+    _doJSON<T>(method: string, path: string, body: unknown): Promise<{
+        data: T;
+        meta: ResponseMeta;
+    }>;
+    /**
+     * Send a JSON request expecting an SSE (text/event-stream) response.
+     * Returns the raw Response for the caller to read SSE events from.
+     * @internal
+     */
+    _doStreamRaw(path: string, body: unknown, signal?: AbortSignal): Promise<Response>;
+}