skytells 1.0.3 → 1.0.5

package/README.md

@@ -1,5 +1,12 @@
 # Skytells JavaScript/TypeScript SDK
 
+[![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/skytells-learn-blue?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)
@@ -14,6 +21,28 @@ yarn add skytells
 pnpm add skytells
 ```
 
+## Import
+
+```ts
+// Recommended: factory (default export)
+import Skytells from 'skytells';
+
+// Direct class import
+import { SkytellsClient } from 'skytells';
+
+// Both in one import
+import Skytells, { SkytellsClient } from 'skytells';
+```
+
+Optionally, you may use the named factory:
+
+```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')
+```
+
 ## Quick Start
 
 ```typescript
@@ -29,6 +58,13 @@ const prediction = await skytells.run('truefusion', {
 console.log(prediction.outputs()); // "https://delivery.skytells.cloud/..."
 ```
 
+**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)):
+
+```typescript
+const client = Skytells('sk-…', { orchestratorApiKey: 'wfb_…' });
+await client.orchestrator.webhooks.execute(workflowId, { /* JSON body */ });
+```
+
 ### Obtaining an API Key
 
 1. Log in at [Skytells Portal](https://www.skytells.ai/auth/signin) or [Create an Account](https://www.skytells.ai/auth/signup)
@@ -90,11 +126,33 @@ console.log(response.id, response.status); // "pred_..." "pending"
 // Poll until complete
 const result = await skytells.wait(response);
 console.log(result.output);
+```
+
+### Server-side Await
+
+For image models, pass `await: true` to have the server block and return the final output in one request — no polling required:
+
+```typescript
+// Explicit server-side wait (image models only; video models ignore this)
+const response = await skytells.predictions.create({
+  model: 'flux-pro',
+  input: { prompt: 'A cat' },
+  await: true,
+});
+console.log(response.output); // already populated
+
+// Or let the SDK detect the model type automatically:
+const response = await skytells.predictions.create(
+  { model: 'flux-pro', input: { prompt: 'A cat' } },
+  { compatibilityCheck: true, autoAwait: true }, // sets await:true only for image models
+);
+console.log(response.output);
 
-// Or with a timeout and progress
+// Or with a timeout and progress (first GET is immediate; then every interval)
 const result = await skytells.wait(response, {
-  interval: 2000,   // poll every 2s
-  maxWait: 120000,  // timeout after 2 min
+  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));
 ```
 
@@ -120,18 +178,14 @@ const completed = await Promise.all(results.map(r => skytells.wait(r)));
 ### Prediction Lifecycle
 
 ```typescript
-// Cancel a running prediction
+// Cancel a running prediction (works while status is pending/starting/processing)
 await prediction.cancel();
-// or by ID
-await skytells.cancelPrediction('pred_abc123');
 
-// Delete a prediction and its assets
+// Delete a prediction and all its output assets from storage
 await prediction.delete();
-// or by ID
-await skytells.deletePrediction('pred_abc123');
 
-// Stream endpoint
-const stream = await skytells.streamPrediction('pred_abc123');
+// Fetch stream metadata for a prediction
+const stream = await prediction.stream();
 console.log(stream.urls?.stream);
 ```
 
@@ -175,18 +229,20 @@ import Skytells from 'skytells';
 
 const skytells = Skytells('your-api-key', {
   baseUrl: 'https://your-proxy.example.com/v1', // Custom API URL
-  timeout: 30000,                                // Request timeout in ms (default: 60000)
-  headers: { 'X-Custom-Header': 'value' },       // Extra headers on every request
+  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,                            // Delay between retries in ms (default: 1000)
-    retryOn: [429, 500, 502, 503, 504],          // Status codes to retry (default)
+    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) =>                          // Custom fetch (e.g. Next.js cache workaround)
-    fetch(url, { ...opts, cache: 'no-store' }),
+  fetch: (url, opts) => fetch(url, { ...opts, cache: 'no-store' }),
+  // runtime: 'edge', // Vercel Edge / Workers: shorter default timeout, smaller compat cache, one-time hints
 });
 ```
 
+Inspect resolved settings: **`skytells.config`** (`requestTimeoutMs`, `prefetchMaxSlugs`, `runtime`) and **`skytells.runtime`**.
+
 ## The Prediction Object
 
 When you call `skytells.run()`, you get a `Prediction` object:
@@ -213,15 +269,17 @@ When you call `skytells.run()`, you get a `Prediction` object:
 
 ## Edge Compatibility
 
-This SDK works in any environment with Fetch API support:
+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 18+**
+- **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 methods throw `SkytellsError` on failure:
@@ -254,10 +312,12 @@ try {
 | `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` | Server returned invalid JSON |
+| `INVALID_JSON` | Declared JSON but body failed `JSON.parse` |
 
 ## TypeScript
 
@@ -266,16 +326,57 @@ 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.
+
+Auto server-side await for image models: also pass **`autoAwait: true`** alongside `compatibilityCheck: true` in `predictions.create()`.
+
+## 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
@@ -294,13 +395,26 @@ import type {
 + 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 the latest documentation.
-- [SDK API Reference](docs/SDK.md) — Full method signatures, parameter tables, and examples
-- [Developer Guide](docs/Guide.md) — Step-by-step walkthroughs and patterns
+- 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
 
@@ -308,7 +422,7 @@ The SDK automatically handles cases when the server doesn't respond with valid J
 
 ```typescript
 try {
-  const models = await skytells.listModels();
+  const models = await skytells.models.list();
 } catch (error) {
   if (error instanceof SkytellsError) {
     if (error.errorId === 'SERVER_ERROR') {
@@ -344,9 +458,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);
+}

package/dist/chat.js

@@ -0,0 +1,33 @@
+/**
+ * Chat API — OpenAI-compatible chat completions.
+ * Same API surface as OpenAI: client.chat.completions.create()
+ *
+ * @module chat
+ */
+import { ENDPOINTS } from './endpoints.js';
+import { Responses } from './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);
+    }
+}