TypeScript SDK Release Notes

Changelog and migration guides for the Skytells TypeScript SDK.

v1.0.3

What's New

The v1.0.3 release introduces a cleaner API surface with namespaced methods, a new Prediction wrapper object, batch dispatching, and a unified error class. The old methods still work but print deprecation warnings and will be removed in a future release.

This is a non-breaking upgrade. All v1.0.2 methods continue to work but are deprecated.

npm install skytells@latest

New Features

`skytells.run()`

The recommended way to generate content. Sends a prediction, polls until completion, and returns a Prediction object with convenient accessors like .outputs(), .raw(), .cancel(), and .delete().

import Skytells from 'skytells';

const skytells = Skytells('sk-your-api-key');

const prediction = await skytells.run('truefusion', {
  input: { prompt: 'A cat wearing sunglasses' },
});

console.log(prediction.outputs()); // "https://..."

The `Prediction` Object

run() returns a Prediction wrapper with getters and lifecycle methods.

Method / Property	Description
`.id`	Unique prediction ID
`.status`	Current lifecycle status
`.output`	Raw output (matches API JSON)
`.outputs()`	Normalized output — unwraps single-element arrays
`.raw()`	Full raw `PredictionResponse`
`.cancel()`	Cancel the prediction
`.delete()`	Delete prediction and its assets

const prediction = await skytells.run('truefusion', {
  input: { prompt: 'A sunset' },
});

prediction.id;       // "pred_abc123"
prediction.status;   // "succeeded"
prediction.output;   // raw: "https://..." or ["https://...", ...]
prediction.outputs(); // normalized, unwraps single-element arrays

const json = prediction.raw();
console.log(json.metrics?.predict_time);

await prediction.cancel();
await prediction.delete();

Background Predictions

skytells.predictions.create() starts a prediction without waiting. Combine with skytells.wait() to poll until completion with optional progress callbacks.

const bg = await skytells.predictions.create({
  model: 'truefusion',
  input: { prompt: 'A landscape' },
});

const result = await skytells.wait(bg, { interval: 2000 }, (p) => {
  console.log(`Status: ${p.status}`);
});

console.log(result.output);

Queue & Dispatch

Queue multiple predictions locally, then dispatch them all concurrently in a single call.

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' } });

const results = await skytells.dispatch();
const completed = await Promise.all(
  results.map((r) => skytells.wait(r)),
);

Unified Error Handling

All errors are now instances of SkytellsError with structured fields for programmatic handling.

Property	Description
`message`	Human-readable message
`errorId`	Machine-readable error ID
`details`	Detailed description
`httpStatus`	HTTP status code

New error IDs in v1.0.3: VALIDATION_ERROR, REQUEST_TIMEOUT, NETWORK_ERROR, SERVER_ERROR, INVALID_JSON.

import Skytells, { SkytellsError } from 'skytells';

try {
  await skytells.run('bad-model', { input: {} });
} catch (error) {
  if (error instanceof SkytellsError) {
    console.error(error.errorId);    // "MODEL_NOT_FOUND"
    console.error(error.httpStatus); // 404
    console.error(error.details);    // extended info
  }
}

Retry Configuration

Full retry configuration with exponential backoff, configurable status codes, and custom delay.

const skytells = Skytells('sk-your-api-key', {
  retry: {
    retries: 3,
    retryDelay: 1000,
    retryOn: [429, 500, 502, 503, 504],
  },
});

Migration from v1.0.2

Renamed Methods

The following methods have been renamed to use namespaced access patterns. The old method names still work but are deprecated and will log warnings.

Old (deprecated)	New
`createClient(key)`	`Skytells(key)`
`client.listModels()`	`skytells.models.list()`
`client.getModel(slug)`	`skytells.models.get(slug)`
`client.listPredictions()`	`skytells.predictions.list()`
`client.getPrediction(id)`	`skytells.predictions.get(id)`

// Before (v1.0.2)
- import { createClient } from 'skytells';
- const client = createClient('key');
- const models = await client.listModels();
- const model = await client.getModel('truefusion');
- const pred = await client.getPrediction(id);

// After (v1.0.3)
+ import Skytells from 'skytells';
+ const skytells = Skytells('key');
+ const models = await skytells.models.list();
+ const model = await skytells.models.get('truefusion');
+ const pred = await skytells.predictions.get(id);

Import Changes

The SDK now uses a default export instead of a named createClient export:

// v1.0.2 — named import
import { createClient } from 'skytells';
const client = createClient('your-api-key');

// v1.0.3 — default import
import Skytells from 'skytells';
const skytells = Skytells('your-api-key');

Error Handling Changes

Replace individual error class checks with the unified SkytellsError class:

The old pattern of checking for specific error classes (SkytellsAuthError, SkytellsValidationError, etc.) is replaced by checking error.errorId on a single SkytellsError class.

// v1.0.2 — multiple error classes
- catch (error) {
-   if (error instanceof SkytellsAuthError) { ... }
-   if (error instanceof SkytellsValidationError) { ... }
- }

// v1.0.3 — single class, check errorId
+ catch (error) {
+   if (error instanceof SkytellsError) {
+     switch (error.errorId) {
+       case 'UNAUTHORIZED': ...
+       case 'VALIDATION_ERROR': ...
+     }
+   }
+ }

Back to TypeScript SDK View Source on GitHub