@sluby/sdk reference

@sluby/sdk is the TypeScript client for the Sluby REST API. It wraps every request in typed methods, uploads files over tus, verifies webhook signatures and opens the browser session that streams video straight from Sia. For a walkthrough, start with Upload videos from your app.

InstallCopy Anchor Link

npm install @sluby/sdk

PackageCopy Anchor Link

The Sia storage SDK is a WebAssembly module. The client imports it the first time client.sia connects (connect(), prepare() or resolveObjectId()), so code that never touches client.sia never loads it.

SlubyConfigCopy Anchor Link

interface SlubyConfig {
  baseUrl: string;
  apiKey?: string;
  credentials?: RequestCredentials;
  deliveryBaseUrl?: string;
  sia?: SiaViewerConfig;
  timeoutMs?: number;
}

The constructor throws an Error when:

SiaViewerConfigCopy Anchor Link

The publishable, low-privilege Sia identity a browser uses to download shared objects. Stream from Sia in the browser shows how to create one.

SlubyClientCopy Anchor Link

import { SlubyClient } from '@sluby/sdk';

const client = new SlubyClient({
  baseUrl: 'https://sluby.example.com',
  apiKey: process.env.SLUBY_API_KEY,
  timeoutMs: 30_000,
});

Request behaviorCopy Anchor Link

• Request bodies go out with the API's snake_case field names. Responses come back mapped to the camelCase types on this page.
• Every method that takes options accepts signal?: AbortSignal. When the signal fires, the call rejects with an AbortError whose cause is the signal's reason.
• The SDK reads the whole response body before it resolves, so signal and timeoutMs cover the body too.
• A response outside 200 to 299 rejects with the error class for its status.
• A network failure rejects with the TypeError that fetch threw, not a SlubyError.
• The SDK does not retry REST requests. Uploads retry on their own (see retryDelays in UploadFileOptions).

The endpoint decides which scope a request needs. Each method below links to its endpoint page.

client.uploadsCopy Anchor Link

class UploadManager {
  upload(file: UploadInput, options: UploadOptions): AssetUploadHandle;
  getStatus(uploadId: string, options?: RequestOptions): Promise<UploadSession>;
  cancel(uploadId: string, options?: RequestOptions): Promise<void>;
}

type UploadInput = Blob | Uint8Array;

upload() takes a File or Blob in the browser, and a Buffer, Uint8Array or Blob (for example from fs.openAsBlob) in Node.js. It does not take Node.js streams. Each call creates one video asset, unless it resumes an unfinished upload (see resume below). The upload runs as a single tus stream.

UploadOptionsCopy Anchor Link

UploadOptions is UploadFileOptions plus the fields of the new video. The SDK sends them as tus metadata.

The SDK also sends filename (the File's name, or video) and filetype (the Blob's type, or an empty string).

UploadFileOptionsCopy Anchor Link

Before it resumes a stored upload, the SDK sends a HEAD to it and resumes only when the server reports Upload-Offset below Upload-Length.

AssetUploadHandleCopy Anchor Link

type AssetUploadHandle = Promise<void> & {
  assetId: Promise<string>;
  uploadId: Promise<string>;
  pause: () => Promise<void>;
  resume: () => void;
  abort: () => Promise<void>;
  readonly isPaused: boolean;
};

The handle, assetId and uploadId reject with the error class for the HTTP status of a failed tus request (the tus error is on cause), or with a SlubyError whose message starts with Upload failed: for any other failure.

client.assetsCopy Anchor Link

class AssetManager {
  list(options?: ListAssetsOptions): Promise<PaginatedResponse<VideoAsset>>;
  get(videoAssetId: string, options?: RequestOptions): Promise<VideoAsset>;
  update(
    videoAssetId: string,
    data: Partial<Pick<VideoAsset, 'title' | 'description' | 'accessTier'>>,
    options?: RequestOptions & { ifMatch?: VideoAsset | string },
  ): Promise<VideoAsset>;
  delete(videoAssetId: string, options?: RequestOptions): Promise<void>;
  processing(videoAssetId: string, options?: RequestOptions): Promise<ProcessingJob>;
  renditions(videoAssetId: string, options?: RequestOptions): Promise<Rendition[]>;
  retry(videoAssetId: string, options?: RequestOptions): Promise<{ stage: RetryStage }>;
  stats(options?: RequestOptions): Promise<AssetStats>;
  usage(options?: RequestOptions & { days?: number }): Promise<UsageReport>;
  waitForReady(
    videoAssetId: string,
    options?: { pollInterval?: number; timeout?: number; signal?: AbortSignal },
  ): Promise<VideoAsset>;
}

function assetEtag(asset: Pick<VideoAsset, 'updatedAt'>): string;

update and If-MatchCopy Anchor Link

Pass ifMatch to apply the edit only if nobody changed the asset since you read it. Pass the asset as you read it, or an ETag string. assetEtag(asset) builds the ETag the server uses: asset.updatedAt in milliseconds since the epoch, in double quotes. It throws a TypeError when updatedAt is not a date.

When the asset changed, update rejects with a ConflictError whose statusCode is 412 and whose current is the asset as the server has it now.

import { ConflictError } from '@sluby/sdk';

try {
  await client.assets.update(asset.id, { title: 'New title' }, { ifMatch: asset });
} catch (err) {
  if (err instanceof ConflictError && err.current) {
    // the asset changed on the server; err.current is the version there now
  }
}

waitForReadyCopy Anchor Link

ListAssetsOptionsCopy Anchor Link

Defaults and limits for page and limit are on the endpoint page.

client.playbackCopy Anchor Link

class PlaybackManager {
  streamUrl(idOrPlaybackId: string): string;
  getUrl(videoAssetId: string, options?: RequestOptions): Promise<PlaybackInfo>;
  getSignedUrl(
    videoAssetId: string,
    options?: { expiresIn?: number; signal?: AbortSignal },
  ): Promise<SignedPlaybackInfo>;
}

getSignedUrl rejects with a RangeError before sending anything when expiresIn is not a whole number above 0. Without expiresIn the server's default lifetime applies; Playback and delivery has the default and the maximum.

client.playbackIdsCopy Anchor Link

class PlaybackIdManager {
  list(videoAssetId: string, options?: RequestOptions): Promise<PlaybackId[]>;
  create(
    videoAssetId: string,
    input?: CreatePlaybackIdInput,
    options?: RequestOptions,
  ): Promise<PlaybackId>;
  delete(playbackId: string, options?: RequestOptions): Promise<void>;
}

interface CreatePlaybackIdInput {
  policy?: 'public' | 'signed'; // default 'public'
  name?: string;
}

PlaybackId has id (the record id), playbackId (the pb_... handle to use in playback URLs), policy, name (empty string when none was given) and createdAt.

client.keysCopy Anchor Link

class KeyManager {
  list(options?: ListApiKeysOptions): Promise<ApiKeyPage>;
  create(input: CreateApiKeyInput, options?: RequestOptions): Promise<CreatedApiKey>;
  update(keyId: string, input: { name: string }, options?: RequestOptions): Promise<ApiKey>;
  rotate(
    keyId: string,
    options?: { gracePeriodSeconds?: number; signal?: AbortSignal },
  ): Promise<RotatedApiKey>;
  revoke(keyId: string, options?: RequestOptions): Promise<void>;
}

interface ListApiKeysOptions extends RequestOptions {
  limit?: number;
  cursor?: string;
}

interface CreateApiKeyInput {
  name: string;
  scopes?: ApiKeyScope[];
  rateLimit?: number; // requests per minute
}

rotate rejects with a ConflictError (409) for a key that was already rotated. Rotate its replacement instead.

ApiKey fields: id, name, scopes ('upload' | 'read' | 'manage', see Scopes), rateLimit (requests per minute), isActive, createdAt, expiresAt (set while a rotated-out key is in its grace period, otherwise null), prefix (the first 12 characters of the key, or null), lastUsedAt and createdBy ({ id, name } of the member who made it, or null).

client.sessionsCopy Anchor Link

class SessionManager {
  list(options?: RequestOptions): Promise<StudioSession[]>;
  revoke(sessionId: string, options?: RequestOptions): Promise<void>;
  revokeAll(options?: RequestOptions): Promise<{ revoked: number }>;
}

These methods work only with a Studio session cookie: create the client without apiKey. A client with an API key gets an AuthenticationError (401). On a server with sign-in turned off (AUTH_DISABLED), they reject with a ConflictError (409).

StudioSession fields: id, userAgent, createdAt, expiresAt, lastSeenAt, current.

client.reconciliationCopy Anchor Link

class ReconciliationManager {
  latest(options?: RequestOptions): Promise<ReconciliationReport>;
  run(options?: RequestOptions): Promise<ReconciliationTrigger>;
}

ReconciliationReport is a union on scope:

• scope: 'deployment' (for an admin): the whole deployment, with dbObjectCount, indexerObjectCount, inSyncCount, orphanCount, orphanedIds and errorMessage.
• scope: 'account' (for a caller that is not an admin): the missing objects of the workspace's videos, without the deployment-wide counts.

Both carry id, startedAt, finishedAt, createdAt, status ('ok' | 'drift' | 'failed'), missingCount, missingIds and missingObjects (each { objectId, videoAssetId, title }). Deletion and reconciliation explains the check.

client.webhookEndpointsCopy Anchor Link

class WebhookEndpointManager {
  list(options?: RequestOptions): Promise<WebhookEndpoint[]>;
  get(endpointId: string, options?: RequestOptions): Promise<WebhookEndpoint>;
  create(
    input: CreateWebhookEndpointInput,
    options?: RequestOptions,
  ): Promise<CreatedWebhookEndpoint>;
  update(
    endpointId: string,
    input: UpdateWebhookEndpointInput,
    options?: RequestOptions,
  ): Promise<WebhookEndpoint>;
  delete(endpointId: string, options?: RequestOptions): Promise<void>;
  rotateSecret(
    endpointId: string,
    options?: RequestOptions,
  ): Promise<{ id: string; secret: string }>;
  test(endpointId: string, options?: RequestOptions): Promise<WebhookTestResult>;
  deliveries(
    endpointId: string,
    options?: { limit?: number; signal?: AbortSignal },
  ): Promise<WebhookDelivery[]>;
  redeliver(
    endpointId: string,
    deliveryId: string,
    options?: RequestOptions,
  ): Promise<{ deliveryId: string }>;
}

interface CreateWebhookEndpointInput {
  url: string;
  events: WebhookEventName[];
}

interface UpdateWebhookEndpointInput {
  url?: string;
  events?: WebhookEventName[]; // replaces the subscribed events
  isActive?: boolean; // false pauses the endpoint, true resumes it
}

WebhookDelivery fields: id, eventId, event, statusCode, delivered, error, attempt (1 for the first try), createdAt, payload (the JSON body that was sent) and manual (true for a resend made with redeliver). Webhook events describes the events, payloads and retries.

client.webhooksCopy Anchor Link

class WebhookManager {
  verifyRequest(
    payload: string,
    headers: WebhookHeaders,
    secret: string,
    options?: VerifyRequestOptions,
  ): boolean;
  verifyRequestAsync(
    payload: string,
    headers: WebhookHeaders,
    secret: string,
    options?: VerifyRequestOptions,
  ): Promise<boolean>;
  verifySignature(payload: string, signature: string, secret: string): boolean;
  verifySignatureAsync(payload: string, signature: string, secret: string): Promise<boolean>;
  parseEvent(payload: string): WebhookEvent;
}

type WebhookHeaders =
  { get(name: string): string | null } | Record<string, string | string[] | undefined>;

interface VerifyRequestOptions {
  toleranceSeconds?: number; // default 300
  now?: number; // current time in Unix seconds, default the clock
}

const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;

WebhookManager needs no credentials. Use it through any client, or construct it on its own with new WebhookManager().

Details:

• Pass the raw request body as payload, exactly as received, before any JSON parsing.
• headers takes a Fetch Headers object or a Node.js req.headers record. Header names match case-insensitively, and for an array the SDK uses the first value.
• The timestamp must be 1 to 12 digits. A missing header, a malformed timestamp or one outside the tolerance returns false.
• verifySignature throws where process.getBuiltinModule is missing (outside Node.js): Synchronous signature verification needs Node.js 20.16+ or 22.3+ (process.getBuiltinModule). Use verifySignatureAsync() in browser or edge environments. verifyRequest throws the same error once the headers pass the timestamp checks.
• parseEvent throws Invalid webhook payload: missing required "event" or "timestamp" field. when either is not a string, and throws the SyntaxError of JSON.parse for a body that is not JSON. It keeps id only when it is a string and sets data to {} when it is missing.

import { WebhookManager } from '@sluby/sdk';

const webhooks = new WebhookManager();

// rawBody: the request body as a string; headers: req.headers
if (webhooks.verifyRequest(rawBody, headers, process.env.SLUBY_WEBHOOK_SECRET!)) {
  const event = webhooks.parseEvent(rawBody);
  console.log(event.id, event.event, event.data.video_asset_id);
}

WebhookEvent is { id?: string; event: WebhookEventName | (string & {}); timestamp: string; data: Record<string, unknown> }. data keeps the snake_case keys of the payload. The headers, signature scheme and every payload are on Webhook events.

client.siaCopy Anchor Link

client.sia is a SiaSession when the client was created with sia, and undefined otherwise. It runs only in a browser. @sluby/player drives it; call it yourself only when you build your own player. Playback and delivery explains direct-from-Sia playback.

class SiaSession {
  static readonly MAX_CACHED_OBJECTS = 64;
  constructor(fetchFn: FetchFn, config: SiaViewerConfig, transport?: SiaSessionTransport);
  connect(): Promise<void>;
  prepare(assetId: string, source?: SiaShareSource): Promise<void>;
  getShareMap(
    assetId: string,
    source?: SiaShareSource,
    options?: { renew?: boolean },
  ): Promise<SiaShareMap>;
  shareMapUrl(assetId: string, src: string): string;
  masterObjectId(assetId: string, source?: SiaShareSource): Promise<string>;
  resolveObjectId(assetId: string, objectId: string, source?: SiaShareSource): Promise<SiaObject>;
  download(object: SiaObject, options?: SiaDownloadOptions): ReadableStream;
  dispose(): void;
}

interface SiaShareSource {
  src?: string;
}

interface SiaDownloadOptions {
  offset?: number;
  length?: number;
}

function publicShareMapUrl(assetId: string, src: string): string;

FetchFn is not exported. Use the session SlubyClient creates rather than constructing one.

Share map sourceCopy Anchor Link

Every method that needs an asset's share map takes an optional source:

MethodsCopy Anchor Link

The session caches each share map per asset and source, and fetches a new one when the cached map is missing, expired, or within 60 seconds of its expiresAt. A map that arrived already inside those 60 seconds stays in use until it expires. A refetch of a map the session already held adds renew=1 to a public request.

publicShareMapUrl(assetId, src) builds the public share map URL for an absolute src. The share id is the {id} in a /v1/stream/{id}/master.m3u8 URL, or assetId for a /v1/objects/{id} URL. It throws when src is neither.

SiaShareMap is { masterObjectId: string; shares: Record<string, string>; expiresAt: string }, where shares maps each object id (hex) to its sia:// share URL.

ErrorsCopy Anchor Link

Every error the SDK creates extends SlubyError, which extends Error. Check classes with instanceof.

The message of an HTTP error is the error string of a JSON body, else its message string. For a body that is not JSON, it is the trimmed body text when that is one line under 200 characters and does not start with <. Otherwise it is the HTTP status text, else Unknown API error. The raw body is on responseBody. Errors in API conventions describes the error body the API sends.

A network failure is not a SlubyError: the SDK rethrows the TypeError from fetch. A statusCode of 0 marks an error raised in the client, not by the server.

import { SlubyError, RateLimitError } from '@sluby/sdk';

try {
  await client.assets.list();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`retry in ${err.retryAfter ?? 60} s`);
  } else if (err instanceof SlubyError) {
    console.log(err.name, err.statusCode, err.message);
  } else {
    throw err; // a network failure from fetch
  }
}

TypesCopy Anchor Link

Every type below is exported from @sluby/sdk as a type.

VideoAssetCopy Anchor Link

ProcessingJobCopy Anchor Link

Other typesCopy Anchor Link

The manager classes (UploadManager, AssetManager, PlaybackManager, PlaybackIdManager, KeyManager, SessionManager, ReconciliationManager, WebhookEndpointManager, WebhookManager, SiaSession) are exported for typing. Except for WebhookManager, reach them through a SlubyClient.