skytells 1.0.4 → 1.0.5

package/README.md

@@ -4,7 +4,7 @@
 [![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/)
+[![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.
@@ -126,6 +126,27 @@ 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 (first GET is immediate; then every interval)
 const result = await skytells.wait(response, {
@@ -319,6 +340,8 @@ import type {
 
 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`:

package/dist/client.cjs

@@ -24,7 +24,7 @@ const { Chat } = require("./chat.js");
 const { Responses } = require("./responses.js");
 const { Embeddings } = require("./embeddings.js");
 const { Safety } = require("./safety.js");
-const { PredictionStatus } = require("./types/index.js");
+const { PredictionStatus, ModelType } = require("./types/index.js");
 const { Webhook, createWebhookListener } = require("./webhooks.js");
 const { SkytellsError } = require("./types/shared.types.js");
 const DEFAULT_POLL_INTERVAL = 5000;
@@ -287,28 +287,41 @@ export class PredictionsAPI {
      * @param payload.input - Key-value input parameters for the model.
      * @param payload.webhook - Optional webhook to receive events.
      * @param payload.stream - Enable streaming (default: `false`).
+     * @param payload.await - When `true`, the server blocks until the prediction completes and returns
+     *   the final result in one response. Ignored by the server for video predictions (returns
+     *   immediately regardless). Defaults to `false`.
      * @param sdk - SDK-only options (not sent in JSON). When `sdk.compatibilityCheck === true`, runs inference compatibility guard before POST.
-     * @returns The initial prediction response with `status: 'pending'` or `'starting'`.
+     * @returns The prediction response — with final `output` when `payload.await` is `true`,
+     *   or `status: 'pending'` / `'starting'` when `false`.
      * @throws {SkytellsError} On API errors (invalid input, model not found, insufficient credits).
      *
      * @example
      * ```ts
+     * // Fire and poll manually
      * const prediction = await client.predictions.create({
      *   model: "flux-pro",
      *   input: { prompt: "An astronaut riding a unicorn" },
      * });
-     * console.log(prediction.id, prediction.status); // "pending"
-     *
-     * // Wait for it to finish
      * const result = await client.wait(prediction);
      * console.log(result.output);
+     *
+     * // Server-side wait — returns final output immediately (not supported for video models)
+     * const prediction = await client.predictions.create({
+     *   model: "flux-pro",
+     *   input: { prompt: "An astronaut riding a unicorn" },
+     *   await: true,
+     * });
+     * console.log(prediction.output);
      * ```
      */
     async create(payload, sdk) {
+        let shouldAutoAwait = false;
         if (this.onBeforePredict) {
-            await this.onBeforePredict(payload, sdk);
+            ({ shouldAutoAwait } = await this.onBeforePredict(payload, sdk));
         }
-        return this.http.request('POST', ENDPOINTS.PREDICT, predictionBodyForHttp(payload, { await: false }));
+        // payload.await takes explicit priority; autoAwait only applies when await is not set by the caller
+        const awaitValue = payload.await !== undefined ? payload.await : shouldAutoAwait || false;
+        return this.http.request('POST', ENDPOINTS.PREDICT, predictionBodyForHttp(payload, { await: awaitValue }));
     }
     /**
      * Fetches a prediction by its ID.
@@ -493,7 +506,7 @@ export class SkytellsClient {
      */
     get predictions() {
         if (!this._predictions) {
-            this._predictions = new PredictionsAPI(this.http, (p, sdk) => this._maybeCompatibilityGuard(p.model, sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck));
+            this._predictions = new PredictionsAPI(this.http, (p, sdk) => this._resolveBeforePredict(p, sdk));
         }
         return this._predictions;
     }
@@ -806,6 +819,24 @@ export class SkytellsClient {
         }
         return model;
     }
+    /**
+     * @internal Runs compatibility guard and resolves autoAwait from model type.
+     * Returns `{ shouldAutoAwait }` for use by `PredictionsAPI.create`.
+     */
+    async _resolveBeforePredict(payload, sdk) {
+        await this._maybeCompatibilityGuard(payload.model, sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck);
+        if ((sdk === null || sdk === void 0 ? void 0 : sdk.autoAwait) !== true || (sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck) !== true) {
+            return { shouldAutoAwait: false };
+        }
+        try {
+            const modelData = await this._getModelForCompatibilityCheck(payload.model);
+            const isImage = modelData.type === ModelType.IMAGE;
+            return { shouldAutoAwait: isImage };
+        }
+        catch (_a) {
+            return { shouldAutoAwait: false };
+        }
+    }
     /**
      * @internal When `compatibilityCheck === true`, throws SDK_ERROR if the model is chat-only here.
      */

package/dist/client.d.ts

@@ -191,7 +191,9 @@ export declare class PredictionsAPI {
     private http;
     private onBeforePredict?;
     /** @internal */
-    constructor(http: HTTP, onBeforePredict?: (payload: PredictionRequest, sdk?: PredictionSdkOptions) => Promise<void>);
+    constructor(http: HTTP, onBeforePredict?: (payload: PredictionRequest, sdk?: PredictionSdkOptions) => Promise<{
+        shouldAutoAwait: boolean;
+    }>);
     /**
      * Creates a prediction in the background (does not wait for completion).
      *
@@ -203,21 +205,31 @@ export declare class PredictionsAPI {
      * @param payload.input - Key-value input parameters for the model.
      * @param payload.webhook - Optional webhook to receive events.
      * @param payload.stream - Enable streaming (default: `false`).
+     * @param payload.await - When `true`, the server blocks until the prediction completes and returns
+     *   the final result in one response. Ignored by the server for video predictions (returns
+     *   immediately regardless). Defaults to `false`.
      * @param sdk - SDK-only options (not sent in JSON). When `sdk.compatibilityCheck === true`, runs inference compatibility guard before POST.
-     * @returns The initial prediction response with `status: 'pending'` or `'starting'`.
+     * @returns The prediction response — with final `output` when `payload.await` is `true`,
+     *   or `status: 'pending'` / `'starting'` when `false`.
      * @throws {SkytellsError} On API errors (invalid input, model not found, insufficient credits).
      *
      * @example
      * ```ts
+     * // Fire and poll manually
      * const prediction = await client.predictions.create({
      *   model: "flux-pro",
      *   input: { prompt: "An astronaut riding a unicorn" },
      * });
-     * console.log(prediction.id, prediction.status); // "pending"
-     *
-     * // Wait for it to finish
      * const result = await client.wait(prediction);
      * console.log(result.output);
+     *
+     * // Server-side wait — returns final output immediately (not supported for video models)
+     * const prediction = await client.predictions.create({
+     *   model: "flux-pro",
+     *   input: { prompt: "An astronaut riding a unicorn" },
+     *   await: true,
+     * });
+     * console.log(prediction.output);
      * ```
      */
     create(payload: PredictionRequest, sdk?: PredictionSdkOptions): Promise<PredictionResponse>;
@@ -565,6 +577,11 @@ export declare class SkytellsClient {
      * Returns model metadata for the inference compatibility check, using {@link _prefetchedModelCache} when fresh.
      */
     private _getModelForCompatibilityCheck;
+    /**
+     * @internal Runs compatibility guard and resolves autoAwait from model type.
+     * Returns `{ shouldAutoAwait }` for use by `PredictionsAPI.create`.
+     */
+    private _resolveBeforePredict;
     /**
      * @internal When `compatibilityCheck === true`, throws SDK_ERROR if the model is chat-only here.
      */

package/dist/client.js

@@ -24,7 +24,7 @@ import { Chat } from './chat.js';
 import { Responses } from './responses.js';
 import { Embeddings } from './embeddings.js';
 import { Safety } from './safety.js';
-import { PredictionStatus } from './types/index.js';
+import { PredictionStatus, ModelType } from './types/index.js';
 import { Webhook, createWebhookListener } from './webhooks.js';
 import { SkytellsError } from './types/shared.types.js';
 const DEFAULT_POLL_INTERVAL = 5000;
@@ -287,28 +287,41 @@ export class PredictionsAPI {
      * @param payload.input - Key-value input parameters for the model.
      * @param payload.webhook - Optional webhook to receive events.
      * @param payload.stream - Enable streaming (default: `false`).
+     * @param payload.await - When `true`, the server blocks until the prediction completes and returns
+     *   the final result in one response. Ignored by the server for video predictions (returns
+     *   immediately regardless). Defaults to `false`.
      * @param sdk - SDK-only options (not sent in JSON). When `sdk.compatibilityCheck === true`, runs inference compatibility guard before POST.
-     * @returns The initial prediction response with `status: 'pending'` or `'starting'`.
+     * @returns The prediction response — with final `output` when `payload.await` is `true`,
+     *   or `status: 'pending'` / `'starting'` when `false`.
      * @throws {SkytellsError} On API errors (invalid input, model not found, insufficient credits).
      *
      * @example
      * ```ts
+     * // Fire and poll manually
      * const prediction = await client.predictions.create({
      *   model: "flux-pro",
      *   input: { prompt: "An astronaut riding a unicorn" },
      * });
-     * console.log(prediction.id, prediction.status); // "pending"
-     *
-     * // Wait for it to finish
      * const result = await client.wait(prediction);
      * console.log(result.output);
+     *
+     * // Server-side wait — returns final output immediately (not supported for video models)
+     * const prediction = await client.predictions.create({
+     *   model: "flux-pro",
+     *   input: { prompt: "An astronaut riding a unicorn" },
+     *   await: true,
+     * });
+     * console.log(prediction.output);
      * ```
      */
     async create(payload, sdk) {
+        let shouldAutoAwait = false;
         if (this.onBeforePredict) {
-            await this.onBeforePredict(payload, sdk);
+            ({ shouldAutoAwait } = await this.onBeforePredict(payload, sdk));
         }
-        return this.http.request('POST', ENDPOINTS.PREDICT, predictionBodyForHttp(payload, { await: false }));
+        // payload.await takes explicit priority; autoAwait only applies when await is not set by the caller
+        const awaitValue = payload.await !== undefined ? payload.await : shouldAutoAwait || false;
+        return this.http.request('POST', ENDPOINTS.PREDICT, predictionBodyForHttp(payload, { await: awaitValue }));
     }
     /**
      * Fetches a prediction by its ID.
@@ -493,7 +506,7 @@ export class SkytellsClient {
      */
     get predictions() {
         if (!this._predictions) {
-            this._predictions = new PredictionsAPI(this.http, (p, sdk) => this._maybeCompatibilityGuard(p.model, sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck));
+            this._predictions = new PredictionsAPI(this.http, (p, sdk) => this._resolveBeforePredict(p, sdk));
         }
         return this._predictions;
     }
@@ -806,6 +819,24 @@ export class SkytellsClient {
         }
         return model;
     }
+    /**
+     * @internal Runs compatibility guard and resolves autoAwait from model type.
+     * Returns `{ shouldAutoAwait }` for use by `PredictionsAPI.create`.
+     */
+    async _resolveBeforePredict(payload, sdk) {
+        await this._maybeCompatibilityGuard(payload.model, sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck);
+        if ((sdk === null || sdk === void 0 ? void 0 : sdk.autoAwait) !== true || (sdk === null || sdk === void 0 ? void 0 : sdk.compatibilityCheck) !== true) {
+            return { shouldAutoAwait: false };
+        }
+        try {
+            const modelData = await this._getModelForCompatibilityCheck(payload.model);
+            const isImage = modelData.type === ModelType.IMAGE;
+            return { shouldAutoAwait: isImage };
+        }
+        catch (_a) {
+            return { shouldAutoAwait: false };
+        }
+    }
     /**
      * @internal When `compatibilityCheck === true`, throws SDK_ERROR if the model is chat-only here.
      */

package/dist/types/predict.types.d.ts

@@ -53,6 +53,28 @@ export interface PredictionSdkOptions {
      * (smaller when `runtime: "edge"`).
      */
     compatibilityCheck?: boolean;
+    /**
+     * When `true`, automatically sets `await: true` on the request if the model type is `image`
+     * (or `image_megapixel`), causing the server to block and return the final output in one response.
+     *
+     * **Requires `compatibilityCheck: true`** — the model type is read from the same cached `GET /model/{slug}`
+     * call made by the compatibility guard. Silently falls back to `await: false` if the model fetch fails
+     * or the type is not an image type (e.g. video models ignore server-side await).
+     *
+     * `payload.await` always takes priority: if you explicitly set `await: true` or `await: false` on the
+     * request, `autoAwait` is ignored.
+     *
+     * @example
+     * ```ts
+     * const prediction = await client.predictions.create(
+     *   { model: 'flux-pro', input: { prompt: '...' } },
+     *   { compatibilityCheck: true, autoAwait: true },
+     * );
+     * // For image models: prediction.output is already populated
+     * // For video/audio models: prediction.status is 'pending', poll with client.wait()
+     * ```
+     */
+    autoAwait?: boolean;
 }
 /**
  * Options for {@link SkytellsClient.run}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skytells",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Official Skytells JavaScript/TypeScript SDK - Edge compatible",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",