skytells 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,15 @@
 # Skytells JavaScript/TypeScript SDK
 
-The official JavaScript/TypeScript SDK for interacting with the [Skytells](https://skytells.ai) API. Edge-compatible with Cloudflare Pages, Vercel Edge Functions, and more.
+[![npm version](https://img.shields.io/npm/v/skytells.svg?style=flat-square)](https://www.npmjs.com/package/skytells)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![Docs](https://img.shields.io/badge/docs-skytells.ai-blueviolet?style=flat-square)](https://docs.skytells.ai/sdks/ts/)
+[![Skytells Learn | Docs](https://img.shields.io/badge/docs-skytells-learn-blueviolet?style=flat-square)](https://learn.skytells.ai/sdks/ts/)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square)](docs/Architecture.md)
+
+The official JavaScript/TypeScript SDK for interacting with the [Skytells](https://skytells.ai) API. Edge-compatible with Cloudflare Workers, Vercel Edge Functions, Netlify Edge Functions, and more.
+
+Generate text, photos, videos, avatars, audio, music, and more using Skytells' own models and partner models — all through a single API. [Explore models →](https://skytells.ai/explore/models)
 
 ## Installation
 
@@ -12,192 +21,377 @@ yarn add skytells
 pnpm add skytells
 ```
 
-## Quick Start
+## Import
 
+```ts
+// Recommended: factory (default export)
+import Skytells from 'skytells';
 
-### Obtaining an API Key
+// Direct class import
+import { SkytellsClient } from 'skytells';
+
+// Both in one import
+import Skytells, { SkytellsClient } from 'skytells';
+```
 
-To obtain an API key, follow these steps:
+Optionally, you may use the named factory:
 
-1. Log in to your Skytells account at [https://www.skytells.ai/auth/signin](https://www.skytells.ai/auth/signin)
-2. Navigate to your dashboard and go to the API Keys section at [https://www.skytells.ai/dashboard/api-keys](https://www.skytells.ai/dashboard/api-keys)
-3. Click on "Generate New API Key"
-4. Give your API key a descriptive name (e.g., "Production API Key", "Development API Key")
-5. Copy the generated API key immediately - you won't be able to see it again!
+```ts
+import { createClient } from 'skytells';
+
+const client = createClient('sk-your-api-key');
+// equivalent to: Skytells('sk-your-api-key') and new SkytellsClient('sk-your-api-key')
+```
 
-## Making Predictions
+## Quick Start
 
 ```typescript
-import { createClient } from 'skytells';
+import Skytells from 'skytells';
 
-// Initialize the client with your API key
-const skytells = createClient('your-api-key-here');
-
-// Make a prediction
-async function makePrediction() {
-  try {
-    const prediction = await skytells.predict({
-      model: 'model-name',
-      input: {
-        prompt: 'Your prompt here'
-      }
-    });
-    
-    console.log('Prediction ID:', prediction.id);
-    console.log('Status:', prediction.status);
-    console.log('Output:', prediction.output);
-  } catch (error) {
-    console.error('Error making prediction:', error);
-  }
-}
+const skytells = Skytells('your-api-key');
 
-// List available models
-async function listModels() {
-  try {
-    const models = await skytells.listModels();
-    console.log('Available models:', models);
-  } catch (error) {
-    console.error('Error listing models:', error);
-  }
-}
+// Run a model and get the result
+const prediction = await skytells.run('truefusion', {
+  input: { prompt: 'A cat wearing sunglasses' },
+});
 
-// Get a prediction by ID
-async function getPrediction(id) {
-  try {
-    const prediction = await skytells.getPrediction(id);
-    console.log('Prediction:', prediction);
-  } catch (error) {
-    console.error('Error getting prediction:', error);
-  }
-}
+console.log(prediction.outputs()); // "https://delivery.skytells.cloud/..."
 ```
 
-## Edge Compatibility
+**Orchestrator** (workflows / webhook triggers) uses a separate `wfb_…` key. Optional **`orchestratorApiKey`** on the same client keeps both products in one place — the SDK applies the right auth per API ([Orchestrator.md](docs/Orchestrator.md)):
 
-This SDK is fully compatible with edge environments including:
+```typescript
+const client = Skytells('sk-…', { orchestratorApiKey: 'wfb_…' });
+await client.orchestrator.webhooks.execute(workflowId, { /* JSON body */ });
+```
 
-- Cloudflare Workers and Pages
-- Vercel Edge Functions
-- Netlify Edge Functions
-- Deno Deploy
-- Any environment with Fetch API support
+### Obtaining an API Key
 
-To use a custom API endpoint or proxy:
+1. Log in at [Skytells Portal](https://www.skytells.ai/auth/signin) or [Create an Account](https://www.skytells.ai/auth/signup)
+2. Go to [Dashboard → API Keys](https://www.skytells.ai/dashboard/api-keys)
+3. Click **Generate New API Key** and copy it immediately
+
+## Usage
+
+### Running a Prediction
+
+`skytells.run()` sends a prediction, waits for completion, and returns a `Prediction` object:
 
 ```typescript
-import { createClient } from 'skytells';
+import Skytells from 'skytells';
+
+const skytells = Skytells('your-api-key');
 
-// Use a custom API endpoint or proxy
-const client = createClient('your-api-key', {
-  baseUrl: 'https://your-proxy.example.com/v1'
+const prediction = await skytells.run('truefusion', {
+  input: { prompt: 'A sunset over mountains' },
 });
+
+// Access output
+console.log(prediction.id);        // "pred_abc123"
+console.log(prediction.status);    // "succeeded"
+console.log(prediction.output);    // Raw: ["https://..."] or "https://..."
+console.log(prediction.outputs()); // Normalized: "https://..." (unwraps single-element arrays)
+
+// Full raw response
+const raw = prediction.raw();
+console.log(raw.metrics);          // { predict_time: 3.86, total_time: 3.86, ... }
+console.log(raw.metadata);         // { billing: { credits_used: 0 }, storage: { ... } }
 ```
 
-## API Reference
+### Progress Tracking
 
-### Creating a Client
+Pass an `onProgress` callback to track prediction status during polling:
 
 ```typescript
-import { createClient } from 'skytells';
+const prediction = await skytells.run('beatfusion-2.0', {
+  input: { prompt: 'rap, romantic', lyrics: 'Let me introduce the voice you hear, Beatfusion by Skytells making it clear..' },
+}, (p) => {
+  console.log(`Status: ${p.status}, Progress: ${p.metrics?.progress ?? 'n/a'}`);
+});
+// [... song url ]
+```
 
-// With API key (authenticated)
-const client = createClient('your-api-key');
+### Background Predictions
 
-// Without API key (unauthenticated, limited functionality)
-const unauthenticatedClient = createClient();
+Create a prediction without waiting for it to finish:
 
-// With options
-const clientWithOptions = createClient('your-api-key', {
-  baseUrl: 'https://api.skytells.ai/v1', // Custom API URL
-  timeout: 30000 // Custom timeout in ms
+```typescript
+// Create in background (returns immediately)
+const response = await skytells.predictions.create({
+  model: 'truefusion',
+  input: { prompt: 'A cat' },
 });
+console.log(response.id, response.status); // "pred_..." "pending"
+
+// Poll until complete
+const result = await skytells.wait(response);
+console.log(result.output);
+
+// Or with a timeout and progress (first GET is immediate; then every interval)
+const result = await skytells.wait(response, {
+  interval: 2000,   // delay between polls after the first refresh
+  maxWait: 120000,  // wall-clock limit → WAIT_TIMEOUT
+  // signal: ac.signal, // optional AbortSignal → ABORTED
+}, (p) => console.log(p.status));
 ```
 
-### Predictions
+### Queue & Dispatch
 
-#### Make a Prediction
+Batch multiple predictions and dispatch them concurrently:
 
 ```typescript
-const prediction = await client.predict({
-  model: 'model-name',
-  input: {
-    // Model-specific inputs
-    prompt: 'Your prompt here',
-    // Other parameters...
-  }
-});
+skytells.queue({ model: 'truefusion-pro', input: { prompt: 'Cat' } });
+skytells.queue({ model: 'truefusion-x', input: { prompt: 'Dog' } });
+skytells.queue({ model: 'FLUX-2.0', input: { prompt: 'Bird' } });
+skytells.queue({ model: 'sora-2', input: { prompt: 'A stunning video....' } });
+skytells.queue({ model: 'beatfusion-2.0', input: { lyrics:' Wherever you are I go In every beat every sound Your love is all around....', prompt: 'Romantic, Love' } });
+
+
+const results = await skytells.dispatch();
+// results: PredictionResponse[] — one per queued item
+
+// Wait for all to complete
+const completed = await Promise.all(results.map(r => skytells.wait(r)));
 ```
 
-#### Get a Prediction by ID
+### Prediction Lifecycle
 
 ```typescript
-const prediction = await client.getPrediction('prediction-id');
+// Cancel a running prediction (works while status is pending/starting/processing)
+await prediction.cancel();
+
+// Delete a prediction and all its output assets from storage
+await prediction.delete();
+
+// Fetch stream metadata for a prediction
+const stream = await prediction.stream();
+console.log(stream.urls?.stream);
 ```
 
-#### Stream a Prediction
+### Models
 
 ```typescript
-const prediction = await client.streamPrediction('prediction-id');
+// List all models
+const models = await skytells.models.list();
+for (const m of models) {
+  console.log(m.name, m.type, m.pricing?.amount);
+}
+
+// Get a specific model
+const model = await skytells.models.get('truefusion');
+
+// Include schemas
+const detailed = await skytells.models.get('truefusion', {
+  fields: ['input_schema', 'output_schema'],
+});
 ```
 
-#### Cancel a Prediction
+### Predictions API
 
 ```typescript
-const prediction = await client.cancelPrediction('prediction-id');
+// List predictions with filters
+const { data, pagination } = await skytells.predictions.list({
+  model: 'truefusion',
+  since: '2026-01-01',
+  until: '2026-03-15',
+  page: 2,
+});
+
+// Get a prediction by ID
+const prediction = await skytells.predictions.get('pred_abc123');
 ```
 
-#### Delete a Prediction
+## Client Options
 
 ```typescript
-const prediction = await client.deletePrediction('prediction-id');
+import Skytells from 'skytells';
+
+const skytells = Skytells('your-api-key', {
+  baseUrl: 'https://your-proxy.example.com/v1', // Custom API URL
+  timeout: 30000, // Omit for defaults: 60000 normally, 25000 when runtime: 'edge'
+  headers: { 'X-Custom-Header': 'value' }, // Extra headers on every request
+  retry: {
+    retries: 3, // Retry failed requests (default: 0)
+    retryDelay: 1000, // Base delay; actual wait is retryDelay * (attempt + 1) per retry
+    retryOn: [429, 500, 502, 503, 504],
+  },
+  fetch: (url, opts) => fetch(url, { ...opts, cache: 'no-store' }),
+  // runtime: 'edge', // Vercel Edge / Workers: shorter default timeout, smaller compat cache, one-time hints
+});
 ```
 
-### Models
+Inspect resolved settings: **`skytells.config`** (`requestTimeoutMs`, `prefetchMaxSlugs`, `runtime`) and **`skytells.runtime`**.
 
-#### List All Models
+## The Prediction Object
 
-```typescript
-const models = await client.listModels();
-```
+When you call `skytells.run()`, you get a `Prediction` object:
+
+| Property / Method | Returns | Description |
+|---|---|---|
+| `.id` | `string` | Unique prediction ID |
+| `.status` | `PredictionStatus` | `pending`, `starting`, `started`, `processing`, `succeeded`, `failed`, `cancelled` |
+| `.output` | `string \| string[] \| undefined` | Raw output from the API |
+| `.response` | `PredictionResponse` | Full response object |
+| `.outputs()` | `string \| string[] \| undefined` | Normalized output — unwraps single-element arrays |
+| `.raw()` | `PredictionResponse` | Full raw response |
+| `.cancel()` | `Promise<PredictionResponse>` | Cancel the prediction |
+| `.delete()` | `Promise<PredictionResponse>` | Delete the prediction and its assets |
 
-## TypeScript Support
+### `outputs()` Behavior
+
+| API returns | `outputs()` returns |
+|---|---|
+| `undefined` | `undefined` |
+| `"https://..."` | `"https://..."` |
+| `["https://..."]` | `"https://..."` (unwrapped) |
+| `["a", "b"]` | `["a", "b"]` (kept as array) |
+
+## Edge Compatibility
 
-This SDK is built with TypeScript and provides full type definitions for all methods and responses.
+This SDK works in any environment with **Fetch** and (for **webhook HMAC verification**) **`crypto.subtle`** (Web Crypto):
+
+- **Cloudflare Workers & Pages**
+- **Vercel Edge Functions**
+- **Netlify Edge Functions**
+- **Deno Deploy**
+- **Node.js** — use **19+** for global `crypto.subtle`, or verify webhooks in an environment that provides it
+- **Browsers**
+
+Pass **`{ runtime: 'edge' }`** when constructing the client on edge/serverless so the SDK uses a **25s default request timeout** (if you don’t set `timeout`) and a **smaller** inference-compat model cache; see **`EDGE_DEFAULT_REQUEST_TIMEOUT_MS`** / **`EDGE_PREFETCH_MAX_SLUGS`** in the package exports.
 
 ## Error Handling
 
-All API methods return promises that may reject with a `SkytellsError`. The SDK parses API error responses into this structured format:
+All methods throw `SkytellsError` on failure:
 
 ```typescript
-import { createClient, SkytellsError } from 'skytells';
+import Skytells, { SkytellsError } from 'skytells';
 
 try {
-  const prediction = await client.predict({
-    model: 'model-name',
-    input: { prompt: 'Your prompt' }
+  const prediction = await skytells.run('truefusion', {
+    input: { prompt: 'A cat' },
   });
 } catch (error) {
   if (error instanceof SkytellsError) {
-    console.error('Error message:', error.message);
-    console.error('Error ID:', error.errorId);      // Example: "VALIDATION_ERROR"
-    console.error('Error details:', error.details);  // Detailed error information
-    console.error('HTTP status:', error.httpStatus); // HTTP status code (e.g., 422)
-  } else {
-    console.error('Unknown error:', error);
+    console.error(error.message);    // Human-readable message
+    console.error(error.errorId);    // e.g. "VALIDATION_ERROR"
+    console.error(error.details);    // Detailed info
+    console.error(error.httpStatus); // e.g. 422
   }
 }
 ```
 
-### Common Error IDs
+### Error IDs
+
+| Error ID | Description |
+|---|---|
+| `UNAUTHORIZED` | Invalid or missing API key |
+| `VALIDATION_ERROR` | Request parameters failed validation |
+| `MODEL_NOT_FOUND` | Model slug not found |
+| `INSUFFICIENT_CREDITS` | Not enough credits |
+| `RATE_LIMIT_EXCEEDED` | Too many requests |
+| `PREDICTION_FAILED` | Prediction completed with failure |
+| `WAIT_TIMEOUT` | Polling exceeded `maxWait` |
+| `ABORTED` | `wait()` / `run` polling stopped via `AbortSignal` |
+| `SDK_ERROR` | Client guard (OpenAI-compat model + `compatibilityCheck`, missing `prediction.id`, webhook crypto unavailable, …) |
+| `REQUEST_TIMEOUT` | HTTP request timed out |
+| `NETWORK_ERROR` | Connection issue |
+| `SERVER_ERROR` | Non-JSON response from server |
+| `INVALID_JSON` | Declared JSON but body failed `JSON.parse` |
 
-- `VALIDATION_ERROR` - Request parameters failed validation
-- `AUTHENTICATION_ERROR` - Invalid or missing API key
-- `RATE_LIMIT_EXCEEDED` - Too many requests
-- `RESOURCE_NOT_FOUND` - The requested resource doesn't exist
-- `NETWORK_ERROR` - Connection issue with the API
-- `REQUEST_TIMEOUT` - Request took too long to complete
-- `SERVER_ERROR` - The server responded with a non-JSON response (e.g., HTML error page)
-- `INVALID_JSON` - The server returned invalid JSON content
+## TypeScript
+
+Full type definitions are included. Key types:
+
+```typescript
+import type {
+  PredictionRequest,
+  PredictionSdkOptions,
+  PredictionResponse,
+  PredictionStatus,
+  RunOptions,
+  WaitOptions,
+  Model,
+  ClientOptions,
+  SkytellsRuntime,
+  PaginatedResponse,
+} from 'skytells';
+```
+
+Inference guard: pass **`{ compatibilityCheck: true }`** as the **second** argument to **`predict`** / **`predictions.create`**, **fourth** to **`run`** (use `undefined` for `onProgress` if unused), or **second** to **`queue`** — never inside the JSON body.
+
+## Safety
+
+Proactive content moderation and response parsing via `client.safety`:
+
+```typescript
+import Skytells, { SafetyTemplates } from 'skytells';
+
+const client = Skytells(process.env.SKYTELLS_API_KEY);
+
+// Check user input before sending to a model
+const check = await client.safety.checkText(userInput, {
+  template: SafetyTemplates.MODERATE,
+});
+if (!check.passed) {
+  throw new Error(`Blocked: ${check.failedCategories.join(', ')}`);
+}
+
+// Evaluate generated prediction output (image URLs are auto-detected)
+const prediction = await client.run('flux-pro', { input: { prompt: userInput } });
+const eval = await client.safety.evaluate(prediction.output, SafetyTemplates.STRICT);
+if (!eval.passed) {
+  await prediction.delete();
+  throw new Error(`Output blocked: ${eval.failedCategories.join(', ')}`);
+}
+
+// Parse content_filter_results from an existing chat completion (no extra API call)
+const completion = await client.chat.completions.create({ ... });
+if (client.safety.wasFiltered(completion)) {
+  const categories = client.safety.getFilteredCategories(completion);
+  console.warn('Filtered:', categories);
+}
+```
+
+See [Safety.md](docs/Safety.md) for templates, all input types, and integration patterns.
+
+## Migration from v1.0.2
+
+```diff
+- import { createClient } from 'skytells';
+- const client = createClient('key');
++ import Skytells from 'skytells';
++ const skytells = Skytells('key');
+
+- const models = await client.listModels();
++ const models = await skytells.models.list();
+
+- const model = await client.getModel('truefusion');
++ const model = await skytells.models.get('truefusion');
+
+- const pred = await client.getPrediction(id);
++ const pred = await skytells.predictions.get(id);
+```
+
+`createClient` is still exported for compatibility; the first call logs a console hint to prefer `import Skytells from 'skytells'`.
+
+> The old method names still work but log deprecation warnings and will be removed in a future version.
+
+## Documentation
+
+- See [Official Docs](https://docs.skytells.ai/sdks/ts/) for hosted documentation.
+- **[Client.md](docs/Client.md)** — `SkytellsClient` in full: options, every method, sub-APIs
+- **[SDKReference.md](docs/SDKReference.md)** — Low-level reference: every class, method, type, constant
+- [Guide.md](docs/Guide.md) — Getting started walkthroughs
+- [Architecture.md](docs/Architecture.md) — Request pipeline, retries, streams, model cache
+- [Reliability.md](docs/Reliability.md) — Timeouts, retries, AbortSignal, edge/serverless patterns
+- [Errors.md](docs/Errors.md) — `SkytellsError` catalog
+- [Prediction.md](docs/Prediction.md) — Predictions: run, wait, queue, cancel, delete
+- [Chat.md](docs/Chat.md) — Chat completions (streaming + tools)
+- [Responses.md](docs/Responses.md) — Responses API (SSE events, multi-turn)
+- [Embeddings.md](docs/Embeddings.md) — Embeddings, semantic search, RAG
+- [Safety.md](docs/Safety.md) — Content moderation, templates, prediction evaluation
+- [Webhooks.md](docs/Webhooks.md) — Inbound webhooks, framework integrations, HMAC
+- [Orchestrator.md](docs/Orchestrator.md) — Orchestrator workflows (`wfb_…` key)
 
 ### Non-JSON Response Handling
 
@@ -205,7 +399,7 @@ The SDK automatically handles cases when the server doesn't respond with valid J
 
 ```typescript
 try {
-  const models = await client.listModels();
+  const models = await skytells.models.list();
 } catch (error) {
   if (error instanceof SkytellsError) {
     if (error.errorId === 'SERVER_ERROR') {
@@ -241,9 +435,26 @@ npm run lint
 
 See [CHANGELOG.md](CHANGELOG.md) for the latest changes.
 
-## SDK Docs
-
-See [SDK Docs](https://docs.skytells.ai/sdks/ts/) for the latest documentation.
+## Documentation in this repo
+
+| File | Description |
+|------|-------------|
+| [docs/Client.md](docs/Client.md) | `SkytellsClient`: options, methods, sub-APIs, best practices |
+| [docs/SDKReference.md](docs/SDKReference.md) | Low-level reference: every export, class, type, and constant |
+| [docs/Guide.md](docs/Guide.md) | Getting started — first prediction, chat, embeddings |
+| [docs/Architecture.md](docs/Architecture.md) | Request pipeline, retries, streaming, model cache |
+| [docs/Reliability.md](docs/Reliability.md) | Timeouts, retries, AbortSignal, edge/serverless |
+| [docs/Errors.md](docs/Errors.md) | `SkytellsError` fields and all `errorId` values |
+| [docs/Prediction.md](docs/Prediction.md) | Predictions: run, wait, queue, dispatch, cancel, webhooks |
+| [docs/Chat.md](docs/Chat.md) | Chat completions, streaming, tools, vision |
+| [docs/Responses.md](docs/Responses.md) | Responses API, SSE events, multi-turn |
+| [docs/Embeddings.md](docs/Embeddings.md) | Embeddings, semantic search, RAG |
+| [docs/Safety.md](docs/Safety.md) | Safety checks, templates, prediction output evaluation |
+| [docs/Webhooks.md](docs/Webhooks.md) | Inbound webhooks, HMAC verification, framework integrations |
+| [docs/Orchestrator.md](docs/Orchestrator.md) | Orchestrator: workflows, executions, integrations |
+| [docs/.env.example](docs/.env.example) | All environment variables for local dev and CI |
+
+Hosted: [Skytells TS SDK docs](https://docs.skytells.ai/sdks/ts/).
 
 ## License
 

package/dist/chat.cjs

@@ -0,0 +1,33 @@
+/**
+ * Chat API — OpenAI-compatible chat completions.
+ * Same API surface as OpenAI: client.chat.completions.create()
+ *
+ * @module chat
+ */
+const { ENDPOINTS } = require("./endpoints.js");
+const { Responses } = require("./responses.js");
+/**
+ * Completions sub-resource. Exposes create() for chat completions.
+ * Mirrors OpenAI's client.chat.completions API.
+ */
+export class Completions {
+    constructor(http) {
+        this.http = http;
+    }
+    create(params) {
+        if (params.stream === true) {
+            return this.http.requestStream(ENDPOINTS.CHAT_COMPLETIONS, params);
+        }
+        return this.http.request('POST', ENDPOINTS.CHAT_COMPLETIONS, params);
+    }
+}
+/**
+ * Chat resource. Exposes completions and responses sub-APIs.
+ * Mirrors OpenAI's client.chat structure.
+ */
+export class Chat {
+    constructor(http) {
+        this.completions = new Completions(http);
+        this.responses = new Responses(http);
+    }
+}

package/dist/chat.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Chat API — OpenAI-compatible chat completions.
+ * Same API surface as OpenAI: client.chat.completions.create()
+ *
+ * @module chat
+ */
+import type { HTTP } from './http.js';
+import { Responses } from './responses.js';
+import type { ChatCompletion, ChatCompletionChunk, ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from './types/inference.types.js';
+/**
+ * Completions sub-resource. Exposes create() for chat completions.
+ * Mirrors OpenAI's client.chat.completions API.
+ */
+export declare class Completions {
+    private readonly http;
+    constructor(http: HTTP);
+    /**
+     * Creates a chat completion. Same as OpenAI's `client.chat.completions.create()`.
+     *
+     * When `stream` is `false` or omitted: returns `Promise<ChatCompletion>`.
+     * When `stream` is `true`: returns an `AsyncIterable<ChatCompletionChunk>` directly;
+     * consume with `for await…of` — no extra `await` needed.
+     *
+     * @param params - model, messages, and optional stream, tools, max_tokens, temperature, etc.
+     * @returns `Promise<ChatCompletion>` or `AsyncIterable<ChatCompletionChunk>`.
+     *
+     * @example Non-streaming:
+     * ```ts
+     * const completion = await client.chat.completions.create({
+     *   model: 'deepbrain-router',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     * });
+     * console.log(completion.choices[0].message.content);
+     * ```
+     *
+     * @example Streaming:
+     * ```ts
+     * for await (const chunk of client.chat.completions.create({
+     *   model: 'deepbrain-router',
+     *   messages: [{ role: 'user', content: 'Hello' }],
+     *   stream: true,
+     * })) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+     * }
+     * ```
+     *
+     * @example Tool calling:
+     * ```ts
+     * const result = await client.chat.completions.create({
+     *   model: 'deepbrain-router',
+     *   messages: [{ role: 'user', content: 'What is the weather in London?' }],
+     *   tools: [{
+     *     type: 'function',
+     *     function: {
+     *       name: 'get_weather',
+     *       description: 'Get current weather for a location.',
+     *       parameters: {
+     *         type: 'object',
+     *         properties: { location: { type: 'string' } },
+     *         required: ['location'],
+     *       },
+     *     },
+     *   }],
+     *   tool_choice: 'auto',
+     * });
+     * const toolCall = result.choices[0].message.tool_calls?.[0];
+     * ```
+     */
+    create(params: ChatCompletionCreateParamsStreaming): AsyncIterable<ChatCompletionChunk>;
+    create(params: ChatCompletionCreateParamsNonStreaming): Promise<ChatCompletion>;
+}
+/**
+ * Chat resource. Exposes completions and responses sub-APIs.
+ * Mirrors OpenAI's client.chat structure.
+ */
+export declare class Chat {
+    /** Chat completions. Same as OpenAI's `client.chat.completions` */
+    readonly completions: Completions;
+    /** Responses API (`POST /v1/responses`). Same surface as OpenAI-style `client.responses`. */
+    readonly responses: Responses;
+    constructor(http: HTTP);
+}