TypeScript SDK

@orilla-video/sdk 0.1.31 is Orilla’s own ESM TypeScript client for Node.js 22 or later. It uses environment credentials to create and retrieve assets, manage playback, and integrate analytics and webhooks.

For a complete first integration, follow Play your first video, including processing checks and a working iframe. Fundamentals explains assets, playback IDs, and authorization.

Install from npm

npm install @orilla-video/sdk

The package includes TypeScript declarations and supports ESM on Node.js 22 or later.

Build from source

From the Orilla repository root:

pnpm build:sdk
pnpm check:sdk

From your application:

pnpm add /path/to/repository/packages/sdk

Configure the client in your backend

Store your environment’s URL and token in server environment variables. The names in this example belong to your application; configure them with your installation’s values.

Use the platform origin, such as https://video.example.com, as ORILLA_API_URL. Do not append /video/v1, /v1, or /api: the client adds the API and media route paths.

import { Orilla } from "@orilla-video/sdk";

const orilla = new Orilla({
  baseURL: process.env.ORILLA_API_URL!,
  tokenId: process.env.ORILLA_TOKEN_ID!,
  tokenSecret: process.env.ORILLA_TOKEN_SECRET!,
});

Import a video

sourceUrl must point to a media file or finite HLS VOD accessible to the server. Import is asynchronous: creating an asset does not mean it is ready for playback.

const sourceUrl = "https://your-media.example/video.mp4";

const asset = await orilla.assets.create({
  inputs: [{ url: sourceUrl }],
  playback_policies: ["signed"],
});

console.log(asset.id, asset.status);

Poll the status or process the ready event through a webhook. A signed policy requires your backend to generate playback tokens; it does not automatically provide a public link.

Retrieve your content

const { data: assets } = await orilla.assets.list({ limit: 25 });

for (const asset of assets) {
  console.log(asset.id, asset.status);
}

The SDK provides pagination and additional resources. The API reference describes the routes; docs/sdk-reference.md in the repository documents the extended client contract.

Credentials belong on the server

Do not include tokenSecret, private keys, or administrative tokens in the browser bundle. Your backend controls authorization and gives the client only the information needed for playback.

Choose the next integration

Task	Resource or guide
Video from the browser	uploads.create and uploadFile
Resumable text/audio attachments	trackUploads.uploadText and uploadAudio
Image overlays and test mode	VOD options
HLS and iframe for a window	Clip modifiers
Thirteen metrics and groups	data.metrics.comparison and insights
Operational series	data.monitoring
Email, Slack, and PagerDuty	data.notificationChannels
Bytes and ingest; CSV export	usage.retrieve and exportCSV

Pagination and failures

Lists preserve their envelope and are paginated explicitly with page/limit; they do not automatically traverse all pages. Individual queries and mutations return the resource; deletions resolve without a value.

HTTP errors are OrillaAPIError, with status, type, and messages. The default timeout is 30 seconds per request; you can pass { signal, timeoutMs }. The SDK does not automatically retry mutations and rejects redirects. Preserve idempotency UUIDs and durable upload IDs to recover lost responses without duplicating resources.

A local package version does not certify publication or remote availability of each workflow. See implementation status.