@rendobar/sdk 5.1.0 → 5.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rendobar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,84 @@
-# @rendobar/sdk
+<p align="center">
+  <a href="https://rendobar.com">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://cdn.rendobar.com/assets/brand/logo-mark.svg">
+      <img alt="Rendobar" src="https://cdn.rendobar.com/assets/brand/logo-mark-black.svg" width="80">
+    </picture>
+  </a>
+</p>
 
-TypeScript client for the Rendobar media processing API.
+<h1 align="center">@rendobar/sdk</h1>
 
-## Install
+<p align="center">
+  <strong>TypeScript client for the Rendobar media processing API.</strong>
+</p>
 
-```bash
-npm install @rendobar/sdk
-```
+<p align="center">
+  <a href="https://rendobar.com/docs/sdk">Docs</a> &nbsp;·&nbsp;
+  <a href="https://rendobar.com/docs/quickstart">Quickstart</a> &nbsp;·&nbsp;
+  <a href="https://www.npmjs.com/package/@rendobar/sdk">npm</a> &nbsp;·&nbsp;
+  <a href="https://discord.gg/kAGqjBzx8N">Discord</a>
+</p>
 
-## Quick Start
+<p align="center">
+  <a href="https://www.npmjs.com/package/@rendobar/sdk"><img src="https://img.shields.io/npm/v/@rendobar/sdk?style=flat-square&color=059669&label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@rendobar/sdk"><img src="https://img.shields.io/npm/dm/@rendobar/sdk?style=flat-square&color=059669" alt="npm downloads"></a>
+  <img src="https://img.shields.io/node/v/@rendobar/sdk?style=flat-square&color=059669" alt="Node version">
+</p>
 
-```typescript
-import { createClient } from "@rendobar/sdk";
+`@rendobar/sdk` is the official TypeScript client for [Rendobar](https://rendobar.com), a serverless media processing API. You submit a job, the SDK polls it to completion, and you get back a hosted URL. It ships ESM and CJS builds with full types, retries 429 and 5xx automatically, auto-paginates, and accepts an `AbortSignal` on every method.
 
-const client = createClient({ apiKey: "rb_..." });
+## Requirements
 
-// Submit a job
-const job = await client.jobs.create({
-  type: "watermark.apply",
-  inputs: { source: "https://example.com/video.mp4" },
-  params: { text: "PREVIEW", position: "center", opacity: 0.3 },
-});
+Node 18 or later. Works in any runtime with `fetch`, including Cloudflare Workers, Deno, and Bun.
 
-// Wait for completion
-import { outputUrl } from "@rendobar/sdk";
+## Install
 
-const result = await client.jobs.wait(job.id);
-console.log(outputUrl(result)); // primary download/playable URL
+```bash
+npm install @rendobar/sdk
 ```
 
-## Authentication
-
-```typescript
-// API key (external users, CLI, scripts)
-const client = createClient({ apiKey: "rb_..." });
-
-// Session cookie (internal dashboard)
-const client = createClient({
-  baseUrl: "https://api.rendobar.com",
-  credentials: "include",
-});
-```
+## Quickstart
 
-## Configuration
+Run an FFmpeg command against a remote file and wait for the result. Put input
+URLs directly in `-i` positions; the SDK stages them before execution.
 
 ```typescript
-const client = createClient({
-  apiKey: "rb_...",
-  baseUrl: "https://api.rendobar.com", // default
-  timeout: 30_000,                      // default: 30s
-  maxRetries: 2,                        // default: 2 (retries 429, 5xx)
-  orgId: "org_abc",                     // X-Org-Id header
-  debug: false,                         // log request metadata
-  fetch: customFetch,                   // custom fetch for testing
-});
-```
+import { createClient, outputUrl } from "@rendobar/sdk";
 
-## Jobs
+const client = createClient({ apiKey: process.env.RENDOBAR_API_KEY });
 
-```typescript
-// Create
 const job = await client.jobs.create({
-  type: "watermark.apply",
-  inputs: { source: "https://example.com/video.mp4" },
-  params: { text: "PREVIEW", position: "center" },
-  idempotencyKey: "unique-key-123",
+  type: "ffmpeg",
+  params: {
+    command:
+      "ffmpeg -i https://cdn.example.com/source.mp4 " +
+      "-vf scale=1280:720 -c:v libx264 -crf 23 output.mp4",
+  },
 });
 
-// Get
-const job = await client.jobs.get("job_abc");
-
-// List (paginated — works with React Query)
-const page = await client.jobs.list({ status: "complete", limit: 20 });
-// page.data: Job[], page.meta: { total, page, limit }
+const done = await client.jobs.wait(job.id);
+console.log(outputUrl(done));
+```
 
-// Auto-paginate all pages
-for await (const job of client.jobs.listAll({ status: "complete" })) {
-  console.log(job.id);
-}
+Prefer named inputs? Pass them in `inputs` and reference the keys in the command:
 
-// Wait for completion (polls until terminal status)
-const result = await client.jobs.wait("job_abc", {
-  timeout: 300_000,
-  interval: 2_000,
-  onProgress: (job) => console.log(job.status),
-  signal: abortController.signal,
+```typescript
+await client.jobs.create({
+  type: "ffmpeg",
+  inputs: { source: "https://cdn.example.com/source.mp4" },
+  params: { command: "ffmpeg -i source -vf scale=1280:720 output.mp4" },
 });
-
-// Cancel
-await client.jobs.cancel("job_abc");
-
-// Download output (returns raw Response)
-const response = await client.jobs.download("job_abc");
-const blob = await response.blob();
-
-// Execution logs
-const logs = await client.jobs.logs("job_abc");
-
-// Available job types
-const types = await client.jobs.types();
 ```
 
-### Job output
+`ffmpeg` is one of several job types. Composition, compression to a size budget,
+subtitle burn-in, animated captions, and media inspection each have their own.
+Browse them at [rendobar.com/docs/jobs](https://rendobar.com/docs/jobs), or call
+`client.jobs.types()` to read the live registry.
+
+## Reading a result
 
-Every job type returns the same output shape. A completed job carries an
-`output` with four fields:
+Every job type returns the same output shape, so you write this handling once.
 
 ```typescript
 type Output = {
@@ -123,219 +97,177 @@ type OutputFile = {
 };
 ```
 
-`output` exists only on a completed job (`status === "complete"`), so narrow on
-status before reading it.
+`output` exists only when `status === "complete"`, so narrow on status before
+reading it.
 
 ```typescript
 import { outputUrl, jobData } from "@rendobar/sdk";
 
 const job = await client.jobs.wait("job_abc");
 
-// Headline URL: the single file, or a stream manifest (.m3u8/.mpd). Returns
-// undefined for data-only jobs and pure file sets (no single headline).
+// Headline URL: the single file, or a stream manifest (.m3u8/.mpd). Undefined
+// for data-only jobs and for pure file sets with no single headline.
 const url = outputUrl(job);
 
-// Or read it yourself after a status check
 if (job.status === "complete") {
-  console.log(job.output.file?.url);
-
-  // Iterate every produced file (frame extraction, HLS segments, sprite sets)
   for (const f of job.output.files) {
     console.log(f.type, f.path, f.size, f.url);
   }
 }
 
-// A failed job carries a structured error instead
 if (job.status === "failed") {
   console.log(job.error.code, job.error.message, job.error.detail);
 }
 ```
 
-For data jobs (`extract.metadata`, `caption.extract`, detections), the answer is
-in `output.data`. It is `unknown` at the contract level because its shape is
-job-type-specific. Use `jobData<T>(job)` to read it with your expected type, or
-read `job.output.data` and narrow it yourself:
+Inspection jobs put their answer in `output.data`, which is `unknown` at the
+contract level because its shape depends on the job type. `jobData<T>(job)`
+reads it as your expected type:
 
 ```typescript
-import { jobData } from "@rendobar/sdk";
-
-type Metadata = { format: string; durationMs: number; width: number; height: number };
-
-const job = await client.jobs.wait("job_abc");
-const meta = jobData<Metadata>(job); // Metadata | null
+type Probe = { format: string; durationMs: number; width: number; height: number };
 
-if (meta) {
-  console.log(meta.format, meta.durationMs);
-}
+const probe = jobData<Probe>(await client.jobs.wait("job_abc")); // Probe | null
 ```
 
-`T` is your claim about the shape for the job type you submitted. If the input is
-untrusted, validate `output.data` yourself (e.g. with Zod) instead of asserting a
-type.
-
-## Raw FFmpeg
-
-Run arbitrary FFmpeg commands in a sandboxed container. Commands are parsed, sanitized (protocol whitelist/blacklist flags blocked), and executed with a clean process environment.
-
-Put input URLs directly in `-i` positions — they're extracted automatically and staged via presigned R2 URLs before execution:
+`T` is your claim about the shape, not a guarantee. If the input is untrusted,
+validate `output.data` with Zod rather than asserting.
 
-```ts
-import { createClient } from "@rendobar/sdk";
+## Errors
 
-const client = createClient({ apiKey: process.env.RENDOBAR_API_KEY });
-
-const job = await client.jobs.create({
-  type: "ffmpeg",
-  params: {
-    command:
-      "ffmpeg -i https://cdn.example.com/source.mp4 " +
-      "-vf scale=1280:720 -c:v libx264 -crf 23 output.mp4",
-  },
-});
+```typescript
+import { isApiError } from "@rendobar/sdk";
 
-const done = await client.jobs.wait(job.id);
-console.log(outputUrl(done));
+try {
+  await client.jobs.create({ type: "ffmpeg", params: { command } });
+} catch (err) {
+  if (isApiError(err)) {
+    console.log(err.code);       // "INSUFFICIENT_CREDITS"
+    console.log(err.statusCode); // 402
+    console.log(err.retryAfter); // seconds, on 429s
+  }
+}
 ```
 
-Prefer named inputs? Pass them in the top-level `inputs` map and reference the keys in the command:
+Codes: `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, `INSUFFICIENT_CREDITS`,
+`RATE_LIMITED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`. Full reference at
+[rendobar.com/docs/support/errors](https://rendobar.com/docs/support/errors).
 
-```ts
-await client.jobs.create({
-  type: "ffmpeg",
-  inputs: { source: "https://cdn.example.com/source.mp4" },
-  params: { command: "ffmpeg -i source -vf scale=1280:720 output.mp4" },
-});
-```
-
-Need a typed params object? Import `FfmpegParams` — optional fields (`timeout`, `compute`) have server-side defaults. The output format comes from the command's output filename.
+429 and 5xx retry automatically with exponential backoff (500ms, then 1s), twice
+by default, respecting `Retry-After`. 400, 401, 403 and 404 throw immediately.
 
-See the [FFmpeg guide](https://rendobar.com/docs/guides/ffmpeg) for the full security model and supported flags.
+## The rest of the API
 
-## Billing
+<details>
+<summary><strong>Jobs</strong></summary>
 
 ```typescript
-const state = await client.billing.state();
-const usage = await client.billing.usage({ start: "2026-01-01", end: "2026-03-29" });
-const txns = await client.billing.transactions({ page: 1, limit: 50 });
-```
+await client.jobs.create({ type, inputs, params, idempotencyKey });
+await client.jobs.get("job_abc");
+await client.jobs.cancel("job_abc");
+await client.jobs.logs("job_abc");
+await client.jobs.getTimings("job_abc");
+await client.jobs.types();                    // live job registry
 
-## Uploads
+const page = await client.jobs.list({ status: "complete", limit: 20 });
+// page.data: Job[], page.meta: { total, page, limit }
 
-```typescript
-// Upload a file, get a URL to use as job input
-const { downloadUrl } = await client.uploads.upload(file, { filename: "input.mp4" });
+for await (const job of client.jobs.listAll({ status: "complete" })) { /* ... */ }
 
-const job = await client.jobs.create({
-  type: "watermark.apply",
-  inputs: { source: downloadUrl },
-  params: { text: "PREVIEW" },
+await client.jobs.wait("job_abc", {
+  timeout: 300_000,
+  interval: 2_000,
+  onProgress: (job) => console.log(job.status),
+  signal: controller.signal,
 });
+
+const response = await client.jobs.download("job_abc"); // raw Response
 ```
+</details>
 
-## Batches
+<details>
+<summary><strong>Uploads, batches, billing</strong></summary>
 
 ```typescript
-const batch = await client.batches.create({
+const { downloadUrl } = await client.uploads.upload(file, { filename: "input.mp4" });
+
+await client.batches.create({
   jobs: [
-    { type: "watermark.apply", inputs: { source: url1 }, params: { text: "1" } },
-    { type: "watermark.apply", inputs: { source: url2 }, params: { text: "2" } },
+    { type: "ffmpeg", inputs: { source: url1 }, params: { command } },
+    { type: "ffmpeg", inputs: { source: url2 }, params: { command } },
   ],
 });
+
+await client.billing.state();
+await client.billing.usage({ start: "2026-01-01", end: "2026-03-29" });
+await client.billing.transactions({ page: 1, limit: 50 });
 ```
+</details>
 
-## Webhooks
+<details>
+<summary><strong>Webhooks</strong></summary>
 
 ```typescript
-// Create endpoint
-const endpoint = await client.webhooks.create({
+await client.webhooks.create({
   name: "My Webhook",
   url: "https://example.com/webhook",
   subscribedEvents: ["job.completed", "job.failed"],
 });
+```
+
+Verify a delivery with the **raw body**, not parsed JSON. `verifyWebhook` reads
+the signature and timestamp headers, rebuilds the signed string, checks the
+HMAC, rejects stale deliveries, and handles secret rotation.
 
-// Verify a delivery in your webhook handler. Pass the raw body (a string, not
-// parsed JSON) and the request headers. verifyWebhook reads the signature and
-// timestamp headers, rebuilds the signed string, checks the HMAC, rejects stale
-// deliveries (replay protection), and handles secret rotation.
+```typescript
 import { verifyWebhook } from "@rendobar/sdk/webhooks";
 
-const ok = await verifyWebhook(rawBody, request.headers, signingSecret);
-if (!ok) throw new Error("invalid signature");
+if (!(await verifyWebhook(rawBody, request.headers, signingSecret))) {
+  throw new Error("invalid signature");
+}
 ```
 
-## Realtime Events (WebSocket)
+See the [webhooks guide](https://rendobar.com/docs/guides/webhooks).
+</details>
+
+<details>
+<summary><strong>Realtime and client configuration</strong></summary>
+
+Realtime needs session cookie auth. On an API key, use `jobs.wait()` instead.
 
 ```typescript
-// Org-wide event stream
 const connection = client.realtime.connect({
-  onEvent: (event) => console.log(event.type, event),
-  onLive: () => console.log("Replay complete, now live"),
-  onResync: () => console.log("Buffer overflow — refresh data"),
+  onEvent: (e) => console.log(e.type, e),
+  onLive: () => console.log("replay complete, now live"),
+  onResync: () => console.log("buffer overflow, refresh data"),
 });
 
-// Per-job subscription
 const sub = client.realtime.subscribeJob("job_abc", {
   onProgress: (e) => console.log(`${e.progress}%`),
-  onStep: (e) => console.log(`Step: ${e.stepName}`),
-  onComplete: (e) => console.log("Done!", e.status),
+  onComplete: (e) => console.log("done", e.status),
 });
 
-// Cleanup
 connection.disconnect();
 sub.unsubscribe();
 ```
 
-> **Note:** Realtime requires session cookie auth. API key users should use `jobs.wait()` for polling.
-
-## Error Handling
-
 ```typescript
-import { createClient, ApiError, isApiError } from "@rendobar/sdk";
-
-try {
-  await client.jobs.create({ type: "watermark.apply", ... });
-} catch (err) {
-  if (isApiError(err)) {
-    console.log(err.code);       // "INSUFFICIENT_CREDITS"
-    console.log(err.statusCode); // 402
-    console.log(err.message);    // "Not enough credits"
-    console.log(err.retryAfter); // seconds (for 429s)
-  }
-}
-```
-
-Error codes: `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, `INSUFFICIENT_CREDITS`, `RATE_LIMITED`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`.
-
-## Retries
-
-The SDK automatically retries:
-- **429** (rate limited) — respects `Retry-After` header
-- **500, 502, 503, 504** — server errors
-
-Retries use exponential backoff (500ms, 1s). Max 2 retries by default. Non-retryable errors (400, 401, 403, 404) throw immediately.
-
-## AbortSignal
-
-Every method accepts an optional `signal` for cancellation:
-
-```typescript
-const controller = new AbortController();
-const job = await client.jobs.get("job_abc", { signal: controller.signal });
+const client = createClient({
+  apiKey: "rb_...",
+  baseUrl: "https://api.rendobar.com", // default
+  timeout: 30_000,                     // default 30s
+  maxRetries: 2,                       // default 2
+  orgId: "org_abc",                    // X-Org-Id header
+  debug: false,                        // log request metadata
+  fetch: customFetch,                  // inject a fetch, for tests
+});
 
-// Cancel the request
-controller.abort();
+// Browser session cookie instead of a key
+createClient({ baseUrl: "https://api.rendobar.com", credentials: "include" });
 ```
+</details>
 
-## Types
-
-All response types are exported:
-
-```typescript
-import type {
-  Job, JobStep, Output, OutputFile, FileType, JobError, Cost, JobType, JobCreatedResponse,
-  BillingState, Transaction, UsageSummary,
-  WebhookEndpoint, WebhookDelivery,
-  Organization, ApiKey, PaginationMeta,
-  BillingInvoice, PaymentMethod, LogEntryData,
-} from "@rendobar/sdk";
-```
+Response types are all exported: `Job`, `JobStep`, `Output`, `OutputFile`,
+`FileType`, `JobError`, `Cost`, `JobType`, `BillingState`, `Transaction`,
+`UsageSummary`, `WebhookEndpoint`, `WebhookDelivery`, `Organization`, `ApiKey`,
+and `PaginationMeta`.

package/dist/index.cjs

@@ -209,6 +209,25 @@ function createJobsResource(request) {
 			signal: options?.signal
 		});
 	}
+	/**
+	* Create a job and wait for it to reach a terminal state, returning the
+	* finished job. A convenience wrapper over `create()` + `wait()` for
+	* callers who just want the result without juggling two calls — works for
+	* any job type, not just a specific product.
+	*
+	* Unlike `wait()` (which defaults `throwOnFailure` to `false` to preserve
+	* its existing behavior), `run()` defaults `throwOnFailure` to `true`: a
+	* job that ends "failed" or "cancelled" throws `JobFailedError` unless the
+	* caller explicitly opts out with `throwOnFailure: false`.
+	*/
+	async function run(params, options = {}) {
+		const { signal, throwOnFailure = true, ...waitOptions } = options;
+		return wait((await create(params, { signal })).id, {
+			...waitOptions,
+			signal,
+			throwOnFailure
+		});
+	}
 	async function get(id, options) {
 		return request(`/jobs/${id}`, { signal: options?.signal });
 	}
@@ -265,6 +284,7 @@ function createJobsResource(request) {
 		list,
 		listAll,
 		wait,
+		run,
 		cancel,
 		download,
 		logs,