quantum-ai-sdk 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,174 @@
+# @quantum-encoding/quantum-sdk
+
+TypeScript client SDK for the [Quantum AI API](https://api.quantumencoding.ai).
+
+```bash
+npm install @quantum-encoding/quantum-sdk
+```
+
+## Quick Start
+
+```typescript
+import { QuantumClient } from "@quantum-encoding/quantum-sdk";
+
+const client = new QuantumClient("qai_k_your_key_here");
+const response = await client.chat("gemini-2.5-flash", "Hello! What is quantum computing?");
+console.log(response.text);
+```
+
+## Features
+
+- 110+ endpoints across 10 AI providers and 45+ models
+- TypeScript-first with full type definitions
+- ESM + CommonJS dual package
+- Streaming via async iterators
+- Agent orchestration with SSE event streams
+- GPU/CPU compute rental
+- Batch processing (50% discount)
+- Tree-shakeable exports
+
+## Examples
+
+### Chat Completion
+
+```typescript
+import { QuantumClient } from "@quantum-encoding/quantum-sdk";
+
+const client = new QuantumClient("qai_k_your_key_here");
+
+const response = await client.chat({
+  model: "claude-sonnet-4-6",
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Explain closures in JavaScript" },
+  ],
+  temperature: 0.7,
+  maxTokens: 1000,
+});
+
+console.log(response.text);
+```
+
+### Streaming
+
+```typescript
+const stream = client.chatStream({
+  model: "claude-sonnet-4-6",
+  messages: [{ role: "user", content: "Write a haiku about TypeScript" }],
+});
+
+for await (const event of stream) {
+  if (event.deltaText) {
+    process.stdout.write(event.deltaText);
+  }
+}
+```
+
+### Image Generation
+
+```typescript
+const images = await client.generateImage("grok-imagine-image", "A cosmic duck in space");
+for (const image of images.images) {
+  console.log(image.url ?? "base64");
+}
+```
+
+### Text-to-Speech
+
+```typescript
+const audio = await client.speak("Welcome to Quantum AI!", "alloy", "mp3");
+console.log(audio.audioUrl);
+```
+
+### Web Search
+
+```typescript
+const results = await client.webSearch("latest TypeScript releases 2026");
+for (const result of results.results) {
+  console.log(`${result.title}: ${result.url}`);
+}
+```
+
+### Agent Orchestration
+
+```typescript
+const stream = client.agentRun("Research quantum computing breakthroughs");
+for await (const event of stream) {
+  switch (event.type) {
+    case "content_delta":
+      process.stdout.write(event.content ?? "");
+      break;
+    case "done":
+      console.log("\n--- Done ---");
+      break;
+  }
+}
+```
+
+## All Endpoints
+
+| Category | Endpoints | Description |
+|----------|-----------|-------------|
+| Chat | 2 | Text generation + session chat |
+| Agent | 2 | Multi-step orchestration + missions |
+| Images | 2 | Generation + editing |
+| Video | 7 | Generation, studio, translation, avatars |
+| Audio | 13 | TTS, STT, music, dialogue, dubbing, voice design |
+| Voices | 5 | Clone, list, delete, library, design |
+| Embeddings | 1 | Text embeddings |
+| RAG | 4 | Vertex AI + SurrealDB search |
+| Documents | 3 | Extract, chunk, process |
+| Search | 3 | Web search, context, answers |
+| Scanner | 11 | Code scanning, type queries, diffs |
+| Scraper | 2 | Doc scraping + screenshots |
+| Jobs | 3 | Async job management |
+| Compute | 7 | GPU/CPU rental |
+| Keys | 3 | API key management |
+| Account | 3 | Balance, usage, summary |
+| Credits | 6 | Packs, tiers, lifetime, purchase |
+| Batch | 4 | 50% discount batch processing |
+| Realtime | 3 | Voice sessions |
+| Models | 2 | Model list + pricing |
+
+## Authentication
+
+Pass your API key when creating the client:
+
+```typescript
+const client = new QuantumClient("qai_k_your_key_here");
+```
+
+The SDK sends it as the `X-API-Key` header. Both `qai_...` (primary) and `qai_k_...` (scoped) keys are supported. You can also use `Authorization: Bearer <key>`.
+
+Get your API key at [cosmicduck.dev](https://cosmicduck.dev).
+
+## Pricing
+
+See [api.quantumencoding.ai/pricing](https://api.quantumencoding.ai/pricing) for current rates.
+
+The **Lifetime tier** offers 0% margin at-cost pricing via a one-time payment.
+
+## Other SDKs
+
+All SDKs are at v0.4.0 with type parity verified by scanner.
+
+| Language | Package | Install |
+|----------|---------|---------|
+| Rust | quantum-sdk | `cargo add quantum-sdk` |
+| Go | quantum-sdk | `go get github.com/quantum-encoding/quantum-sdk` |
+| **TypeScript** | @quantum-encoding/quantum-sdk | `npm i @quantum-encoding/quantum-sdk` |
+| Python | quantum-sdk | `pip install quantum-sdk` |
+| Swift | QuantumSDK | Swift Package Manager |
+| Kotlin | quantum-sdk | Gradle dependency |
+
+MCP server: `npx @quantum-encoding/ai-conductor-mcp`
+
+## API Reference
+
+- Interactive docs: [api.quantumencoding.ai/docs](https://api.quantumencoding.ai/docs)
+- OpenAPI spec: [api.quantumencoding.ai/openapi.yaml](https://api.quantumencoding.ai/openapi.yaml)
+- LLM context: [api.quantumencoding.ai/llms.txt](https://api.quantumencoding.ai/llms.txt)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { realtimeConnect, realtimeConnectDirect, realtimeSession, realtimeEnd, r
 export type { RealtimeConfig, RealtimeEvent, RealtimeSession } from "./realtime.js";
 export { contact } from "./contact.js";
 export type { BillingRequest, BillingEntry, BillingResponse } from "./compute-billing.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, JobStreamEvent, 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, WebSearchRequest, WebSearchResponse, WebSearchResult, NewsResult, VideoSearchResult, LLMContextRequest, LLMContextResponse, ContentChunk, ContextSource, SearchAnswerRequest, SearchAnswerResponse, SearchAnswerChoice, SearchCitation, StatusResponse, Citation, CollectionsListResponse, CollectionDocumentsResponse, CollectionSearchResponse, CreateCollectionRequest, DeleteCollectionResponse, ModelsResponse, RagCorporaResponse, Infobox, Discussion, TextToSpeechRequest, TextToSpeechResponse, SpeechToTextRequest, SpeechToTextResponse, ContactResponse, ContextChunk, ContextOptions, HeyGenAvatarsResponse, JobAcceptedResponse, JobListEntry, PostProcess, RealtimeSessionResponse, SearchMessage, SearchOptions, } from "./types.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, JobStreamEvent, 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, WebSearchRequest, WebSearchResponse, WebSearchResult, NewsResult, VideoSearchResult, LLMContextRequest, LLMContextResponse, ContentChunk, ContextSource, SearchAnswerRequest, SearchAnswerResponse, SearchAnswerChoice, SearchCitation, StatusResponse, Citation, CollectionsListResponse, CollectionDocumentsResponse, CollectionSearchResponse, CreateCollectionRequest, DeleteCollectionResponse, ModelsResponse, RagCorporaResponse, Infobox, Discussion, TextToSpeechRequest, TextToSpeechResponse, SpeechToTextRequest, SpeechToTextResponse, ContactResponse, ContextChunk, ContextOptions, HeyGenAvatarsResponse, JobAcceptedResponse, JobListEntry, PostProcess, RealtimeSessionResponse, SearchMessage, SearchOptions, ScrapeTarget, ScrapeRequest, ScrapeResponse, ScreenshotURL, ScreenshotRequest, ScreenshotResult, ScreenshotResponse, } from "./types.js";
 export { DEFAULT_BASE_URL, TICKS_PER_USD } from "./types.js";
 import type { ChatMessage } from "./types.js";
 /** Create a user message. */

package/dist/types.d.ts

@@ -2208,3 +2208,53 @@ export interface SearchOptions {
     freshness?: string;
     safe_search?: string;
 }
+/** A single scrape target. */
+export interface ScrapeTarget {
+    name: string;
+    url: string;
+    type?: string;
+    selector?: string;
+    content?: string;
+    notebook?: string;
+    recursive?: boolean;
+    max_pages?: number;
+    delay_ms?: number;
+    ingest?: string;
+}
+/** Request body for submitting a scrape job. */
+export interface ScrapeRequest {
+    targets: ScrapeTarget[];
+}
+/** Response from submitting a scrape job. */
+export interface ScrapeResponse {
+    job_id: string;
+    status: string;
+    targets: number;
+    request_id: string;
+}
+/** A single URL to screenshot. */
+export interface ScreenshotURL {
+    url: string;
+    width?: number;
+    height?: number;
+    full_page?: boolean;
+    delay_ms?: number;
+}
+/** Request body for taking screenshots. */
+export interface ScreenshotRequest {
+    urls: ScreenshotURL[];
+}
+/** A single screenshot result. */
+export interface ScreenshotResult {
+    url: string;
+    base64: string;
+    format: string;
+    width: number;
+    height: number;
+    error?: string;
+}
+/** Response from the screenshot endpoint. */
+export interface ScreenshotResponse {
+    screenshots: ScreenshotResult[];
+    count: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantum-ai-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cosmic Duck SDK — 100+ AI endpoints across 10 providers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",