@rendobar/sdk 2.1.2 → 3.0.0

package/README.md

@@ -23,8 +23,10 @@ const job = await client.jobs.create({
 });
 
 // Wait for completion
+import { outputUrl } from "@rendobar/sdk";
+
 const result = await client.jobs.wait(job.id);
-console.log(result.outputUrl);
+console.log(outputUrl(result)); // primary download/playable URL
 ```
 
 ## Authentication
@@ -99,6 +101,78 @@ const logs = await client.jobs.logs("job_abc");
 const types = await client.jobs.types();
 ```
 
+### Job output
+
+Every job type returns the same output shape. A completed job carries an
+`output` with four fields:
+
+```typescript
+type Output = {
+  data: unknown;            // structured result (probe, detections, transcript), or null
+  file: OutputFile | null;  // the headline file or stream manifest, or null
+  files: OutputFile[];      // every produced file (empty for data-only jobs)
+  expiresAt: number | null; // Unix ms URL expiry, set when files is non-empty
+};
+
+type OutputFile = {
+  url: string;   // ready-to-fetch, time-limited URL
+  path: string;  // path within the job output
+  type: "video" | "image" | "audio" | "captions" | "playlist" | "data" | "other";
+  size: number;  // bytes
+  meta?: { format?: string; width?: number; height?: number; durationMs?: number };
+};
+```
+
+`output` exists only on a completed job (`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).
+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:
+
+```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
+
+if (meta) {
+  console.log(meta.format, meta.durationMs);
+}
+```
+
+`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.
@@ -120,7 +194,7 @@ const job = await client.jobs.create({
 });
 
 const done = await client.jobs.wait(job.id);
-console.log(done.outputUrl);
+console.log(outputUrl(done));
 ```
 
 Prefer named inputs? Pass them in the top-level `inputs` map and reference the keys in the command:
@@ -258,7 +332,7 @@ All response types are exported:
 
 ```typescript
 import type {
-  Job, JobStep, JobType, JobCreatedResponse,
+  Job, JobStep, Output, OutputFile, FileType, JobError, Cost, JobType, JobCreatedResponse,
   BillingState, Transaction, UsageSummary,
   WebhookEndpoint, WebhookDelivery,
   Organization, ApiKey, PaginationMeta,

package/dist/index.cjs

@@ -303,13 +303,130 @@ function createBillingResource(request) {
 }
 //#endregion
 //#region src/resources/uploads.ts
+function toBlob(file) {
+	return file instanceof Blob ? file : new Blob([file]);
+}
+/**
+* PUT a body to a presigned R2 url with bounded retry.
+*
+* Returns the ETag string when the bucket exposes it, or `null` when the
+* response header is absent (e.g. bucket CORS not exposing ETag). Only
+* network/HTTP failures trigger retries; a missing ETag is not retried because
+* it is a deterministic misconfiguration, not a transient error.
+*/
+async function putWithRetry(url, body, signal, attempts = 3) {
+	let lastErr;
+	for (let i = 0; i < attempts; i++) {
+		if (signal?.aborted) throw new Error("Upload aborted");
+		try {
+			const res = await fetch(url, {
+				method: "PUT",
+				body,
+				signal
+			});
+			if (!res.ok) throw new Error(`Upload PUT failed: ${res.status}`);
+			return res.headers.get("etag");
+		} catch (e) {
+			lastErr = e;
+			if (signal?.aborted) throw e;
+			if (i < attempts - 1) await new Promise((r) => setTimeout(r, 200 * 2 ** i));
+		}
+	}
+	throw lastErr;
+}
+/**
+* Run `fn` over `items` with at most `limit` in flight; preserves order.
+* Workers stop pulling new items once `signal` is aborted, enabling fast
+* cancellation when one part fails.
+*/
+async function mapLimit(items, limit, fn, signal) {
+	const out = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			if (signal?.aborted) break;
+			const i = next++;
+			out[i] = await fn(items[i]);
+		}
+	};
+	const workers = Math.min(Math.max(1, limit), items.length);
+	await Promise.all(Array.from({ length: workers }, worker));
+	return out;
+}
 function createUploadsResource(request) {
-	return { async upload(file, options) {
-		return request("/uploads", {
+	return { async create(file, options) {
+		const blob = toBlob(file);
+		const size = options.size ?? blob.size;
+		if (options.signal?.aborted) throw new Error("Upload aborted");
+		const init = await (await request("/assets", {
 			method: "POST",
-			bodyRaw: file,
-			query: options?.filename ? { filename: options.filename } : void 0,
-			signal: options?.signal
+			body: {
+				filename: options.filename,
+				size,
+				contentType: options.contentType,
+				checksum: options.checksum,
+				lifecycle: options.persist ? "persisted" : "ephemeral"
+			},
+			raw: true,
+			signal: options.signal
+		})).json();
+		if (init.status === "deduplicated") {
+			options.onProgress?.({
+				loaded: size,
+				total: size
+			});
+			return init.data;
+		}
+		if (init.status === "presigned") {
+			await putWithRetry(init.upload.url, blob, options.signal);
+			options.onProgress?.({
+				loaded: size,
+				total: size
+			});
+			return request(`/assets/${init.data.id}/complete`, {
+				method: "POST",
+				body: {},
+				signal: options.signal
+			});
+		}
+		const internal = new AbortController();
+		const combinedSignal = options.signal ? AbortSignal.any([options.signal, internal.signal]) : internal.signal;
+		const { partSize, parts } = init.upload;
+		let loaded = 0;
+		let partError = null;
+		const completed = await mapLimit(parts, options.concurrency ?? 5, async (p) => {
+			const start = (p.partNumber - 1) * partSize;
+			const chunk = blob.slice(start, Math.min(start + partSize, size));
+			let etag;
+			try {
+				etag = await putWithRetry(p.url, chunk, combinedSignal);
+			} catch (e) {
+				internal.abort();
+				partError = e instanceof Error ? e : new Error(String(e));
+				throw partError;
+			}
+			if (etag === null) {
+				internal.abort();
+				const corsErr = /* @__PURE__ */ new Error("Multipart upload requires the ETag response header. Configure the R2 bucket CORS to expose 'ETag'.");
+				partError = corsErr;
+				throw corsErr;
+			}
+			loaded += chunk.size;
+			options.onProgress?.({
+				loaded,
+				total: size
+			});
+			return {
+				partNumber: p.partNumber,
+				etag
+			};
+		}, combinedSignal);
+		if (partError) throw partError;
+		completed.sort((a, b) => a.partNumber - b.partNumber);
+		return request(`/assets/${init.data.id}/complete`, {
+			method: "POST",
+			body: { parts: completed },
+			signal: options.signal
 		});
 	} };
 }
@@ -449,12 +566,32 @@ function createBatchesResource(request) {
 //#endregion
 //#region src/resources/assets.ts
 function createAssetsResource(request) {
-	return { async templates(params, options) {
-		return request("/assets/templates", {
-			query: params ? { ...params } : void 0,
-			signal: options?.signal
-		});
-	} };
+	return {
+		async list(params, options) {
+			return request("/assets", {
+				query: params,
+				signal: options?.signal
+			});
+		},
+		async get(id, options) {
+			return request(`/assets/${id}`, { signal: options?.signal });
+		},
+		async delete(id, options) {
+			return request(`/assets/${id}`, {
+				method: "DELETE",
+				signal: options?.signal
+			});
+		},
+		async download(id, options) {
+			return request(`/assets/${id}/download`, { signal: options?.signal });
+		},
+		async templates(params, options) {
+			return request("/assets/templates", {
+				query: params,
+				signal: options?.signal
+			});
+		}
+	};
 }
 //#endregion
 //#region src/resources/team.ts
@@ -646,6 +783,44 @@ function createClient(config = {}) {
 	};
 }
 //#endregion
+//#region src/types.ts
+/**
+* Primary playable/download URL for a completed job, or `undefined`.
+*
+* Returns `output.file.url` — the single download for a file job or the playlist
+* URL for a stream. A pure set (multiple files, no headline) or a data-only job
+* has no single primary URL: inspect `job.output.files` / `job.output.data`.
+*/
+function outputUrl(job) {
+	if (job.status !== "complete") return void 0;
+	return job.output.file?.url;
+}
+/**
+* Typed accessor for a completed job's structured `data`, or `null`.
+*
+* `output.data` is job-type-specific (probe result, detections, transcript) and
+* is `unknown` at the contract level — its shape is documented per job type, not
+* by the API schema. This helper applies the caller-supplied type `T` so you can
+* read `data` without sprinkling assertions at each call site. `T` is your claim
+* about the shape for the job type you submitted; validate it yourself (e.g. with
+* Zod) if the input is untrusted.
+*
+* Returns `null` for non-complete jobs and for jobs with no structured data
+* (pure file transforms).
+*
+* @example
+* type Metadata = { format: string; durationMs: number };
+* const meta = jobData<Metadata>(await client.jobs.wait(id));
+* if (meta) console.log(meta.durationMs);
+*/
+function jobData(job) {
+	if (job.status !== "complete") return null;
+	if (job.output.data == null) return null;
+	return job.output.data;
+}
+//#endregion
 exports.ApiError = ApiError;
 exports.createClient = createClient;
 exports.isApiError = isApiError;
+exports.jobData = jobData;
+exports.outputUrl = outputUrl;