@transcodely/sdk 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the Transcodely JavaScript / TypeScript SDK will be docum
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Breaking changes are allowed on minor bumps until 1.0.0.
 
+## [0.3.8](https://github.com/transcodely/transcodely-js/compare/v0.3.7...v0.3.8) (2026-09-15)
+
+
+### Features
+
+* **proto:** sync content-analysis report (per-title) ([#68](https://github.com/transcodely/transcodely-js/issues/68)) ([e010f10](https://github.com/transcodely/transcodely-js/commit/e010f1010e78ad86cace86a3b67216669198cb39))
+* **proto:** sync IngestRuleService (ingest rules) ([#63](https://github.com/transcodely/transcodely-js/issues/63)) ([af8992a](https://github.com/transcodely/transcodely-js/commit/af8992ade9d01ccaa314869198a20dab54e7af16))
+* **proto:** sync OutputReport (job output facts + verdict) ([#61](https://github.com/transcodely/transcodely-js/issues/61)) ([4bf7f6c](https://github.com/transcodely/transcodely-js/commit/4bf7f6c2c26c462f62b2f269f93c22f5c94fcd2c))
+* **proto:** sync protos to api 5.21.0 — optional app_id, per-title accepted, rule clear flags ([#69](https://github.com/transcodely/transcodely-js/issues/69)) ([1ad04ae](https://github.com/transcodely/transcodely-js/commit/1ad04aefc4ec6851b76e38adcea02ee78ded1043))
+* **uploads:** client.uploads.putFile + the npx transcodely CLI ([#64](https://github.com/transcodely/transcodely-js/issues/64)) ([e3e7d58](https://github.com/transcodely/transcodely-js/commit/e3e7d58756492183c966e2eeb3ece4e4eaf7fc6a))
+
+
+### Bug Fixes
+
+* **types:** export HealthStatus and guard every enum against proto drift ([#67](https://github.com/transcodely/transcodely-js/issues/67)) ([d30da94](https://github.com/transcodely/transcodely-js/commit/d30da9462fbf5a68ac18884c5990de93b3c0d2f2))
+
 ## [0.3.7](https://github.com/transcodely/transcodely-js/compare/v0.3.6...v0.3.7) (2026-08-16)
 
 

package/README.md

@@ -1,6 +1,8 @@
 # @transcodely/sdk
 
-Official TypeScript / Node SDK for the [Transcodely](https://transcodely.com) video transcoding API.
+Official TypeScript / Node SDK for [Transcodely](https://www.transcodely.com) — encode
+video into HLS, DASH and MP4 and write it to your own S3, GCS or R2 bucket, with DRM,
+signed playback and deterministic output paths. Or let Transcodely host and deliver it.
 
 ```bash
 npm install @transcodely/sdk
@@ -41,6 +43,138 @@ for await (const event of client.jobs.watch(job.id)) {
 }
 ```
 
+## Upload a file
+
+`client.uploads.putFile` takes a file from your disk to a hosted, playable
+video in one call. It opens the upload, pushes the bytes straight to object
+storage, and tells the API the bytes landed — the API never proxies the media.
+
+```ts
+const video = await client.uploads.putFile("./talk.mp4", {
+  appId: "app_k1l2m3n4o5",
+  title: "Conference talk",
+  onProgress: (p) => process.stdout.write(`\r${p.percent}%`),
+});
+
+console.log(video.id, video.status); // "vid_a1b2c3d4e5f6g7" "processing"
+```
+
+The transcode starts on its own as soon as the upload completes, so the video
+comes back already `processing`. Follow it with `client.videos.watch(video.id)`
+until it reaches `ready` (or `error`, or `deleted`), or subscribe to the
+`video.ready` webhook.
+
+**The app does not need managed hosting turned on first.** An app that has never
+hosted anything is provisioned by the create call itself — bucket, managed
+origin and CDN pull zone — which is why a first upload takes a few seconds
+longer than the ones after it. Two things can still refuse it, and they are
+worth telling apart:
+
+- `hosting_provisioning_failed` — provisioning did not complete. Nothing was
+  created, so the identical call is safe to retry.
+- a billing or admission code — `billing_past_due`,
+  `outstanding_balance_exceeded`, `limit_exceeded`, `intake_paused`,
+  `app_suspended`. These are about the account, not about hosting, and retrying
+  will not clear them.
+
+**Sources.** A filesystem path, a `Blob`/`File`, or a `ReadableStream`. A path
+and a `File` supply their own name and size; a bare `Blob` needs `filename`,
+and a stream needs both `filename` and `sizeBytes` because the API has to know
+the total before the first byte moves.
+
+```ts
+await client.uploads.putFile(blob, { appId, filename: "talk.mp4" });
+await client.uploads.putFile(stream, { appId, filename: "talk.mp4", sizeBytes: 734003200 });
+```
+
+**How it moves the bytes.** A file that fits in one part goes up as a single
+`PUT`. Anything larger becomes an S3 multipart upload: parts are uploaded
+`concurrency` at a time (default 4), a part that fails on a 5xx, 429, 408 or a
+network error is retried with jittered backoff, and a presigned URL that has
+expired is re-signed and retried. If the upload cannot finish, the multipart
+upload is aborted server-side before the error is thrown — nothing sweeps
+orphaned multipart uploads, so an abandoned one would cost storage forever.
+
+**Knobs.**
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `partSize` | 25 MiB | Raised to the 5 MiB S3 minimum, and further if 10,000 parts would not cover the file. |
+| `concurrency` | 4 | Parts in flight at once. For a stream source this also caps how much is buffered. |
+| `maxRetries` | 4 | Retries per part, after the first attempt. |
+| `signal` | — | Aborts the upload and the multipart upload behind it. |
+| `onProgress` | — | Called once per completed part, not per byte. |
+
+**Limits and errors.** The platform ceiling is 5 GB; an empty file or one over
+the ceiling is refused before the first request. Transfer failures throw
+`UploadError` (`UploadAbortedError` when your `signal` fired); everything the
+API itself refuses keeps its usual error class.
+
+```ts
+import { UploadAbortedError, UploadError } from "@transcodely/sdk";
+```
+
+Need finer control? The individual RPCs are still there on `client.videos`
+(`createUpload`, `createMultipartUpload`, `getUploadPartUrls`,
+`completeMultipartUpload`, `abortMultipartUpload`).
+
+## Command line
+
+The same flows from a shell, with no code:
+
+```bash
+npx transcodely ./talk.mp4
+npx transcodely https://example.com/talk.mp4 --wait
+```
+
+**Not published yet.** The `transcodely` CLI lives in this repository under
+[`packages/cli`](packages/cli/README.md) and ships once this SDK releases the
+version it pins. Until then the commands above do not resolve on npm; build it
+from the repo instead (`pnpm install && pnpm build`, then
+`node packages/cli/dist/index.mjs --help`).
+
+## Read the output report
+
+Every completed output carries a report of what the produced file actually
+turned out to be — measured from the encoded file rather than copied from the
+request — plus the verdict of comparing those measurements against what was
+asked for.
+
+```ts
+import type { OutputReport } from "@transcodely/sdk";
+
+const done = await client.jobs.get(job.id);
+
+for (const output of done.outputs) {
+  const report: OutputReport | undefined = output.report;
+  if (!report) continue; // not measured — never "nothing wrong"
+
+  console.log(
+    output.id,
+    report.video?.codec,
+    `${report.video?.width}x${report.video?.height}`,
+    `${report.durationSeconds}s`,
+  );
+
+  if (report.verdict && !report.verdict.matchesRequest) {
+    for (const m of report.verdict.mismatches) {
+      console.log(`  ${m.field}: asked for ${m.expected}, got ${m.actual}`);
+    }
+  }
+}
+```
+
+Branch on `m.field` — it comes from a fixed vocabulary (`video.codec`,
+`video.resolution`, `duration_seconds`, …) — rather than on the values beside
+it. For an ABR ladder the facts describe the highest-resolution rendition, the
+same one the verdict judges; per-rendition detail stays in `variantResults`.
+
+An output encoded with per-title content-aware analysis also carries
+`report.contentAware`: the VMAF target the search aimed at, the score it reached
+on its samples, and the CRF it chose. It describes the SEARCH, not the delivered
+file — `vmafAchieved` scores short samples taken before the real encode, which is
+never scored itself. It is `undefined` on every ordinary output.
+
 ## AI captions
 
 Add auto-generated captions to any output with a `generate` subtitle track.
@@ -92,9 +226,11 @@ const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });
 
 ```ts
 client.jobs            // create / get / list / cancel / confirm / watch
-client.videos          // upload helpers, multipart, createFromUrl, get / list / update / delete / watch / getStats / listTopVideos
+client.uploads         // putFile — the whole create / PUT / complete upload, for a path, Blob or stream
+client.videos          // upload RPCs, multipart, createFromUrl, get / list / update / delete / watch / getStats / listTopVideos
 client.presets         // create / get / getBySlug / list / update / duplicate / archive
 client.origins         // create / get / list / update / validate / archive
+client.ingestRules     // create / get / list / update / delete / listEvents / test / replayEvent
 client.apps            // create / get / list / update / archive / enableHosting
 client.apiKeys         // create / get / list / revoke
 client.organizations   // create / get / list / update / checkSlug
@@ -103,6 +239,20 @@ client.users           // getMe / get / list / updateMe
 client.health          // check
 ```
 
+Every enum in the API schema is exported by name from the package root, so you
+can branch on one without reaching into the generated code:
+
+```ts
+import { HealthStatus } from "@transcodely/sdk";
+
+const health = await client.health.check();
+for (const component of health.components) {
+  if (component.status !== HealthStatus.HEALTHY) {
+    console.warn(component.name, component.message);
+  }
+}
+```
+
 ## Origins
 
 An origin tells Transcodely where to read source media from and where to write outputs. Every origin belongs to a single provider; pass exactly one provider-config field (`s3`, `gcs`, `http`, or `r2`) on create.
@@ -198,6 +348,74 @@ r2: {
 
 Provide either `accountId` or `endpoint`, never both. `jurisdiction` only applies when `accountId` is set.
 
+## Ingest rules
+
+An ingest rule is a standing instruction on one readable origin: *when an object
+matching these filters lands, create this job for it*. Your storage provider
+posts its object-created events to the rule's endpoint, and no server of yours
+is in the path. Amazon S3 via SNS, Google Cloud Storage via a Pub/Sub push
+subscription, Supabase Storage via a database webhook, and a generic shape for
+anything else are all recognised from the payload.
+
+```ts
+const { rule, secret } = await client.ingestRules.create({
+  originId: "ori_a1b2c3d4e5f6",
+  name: "Watch uploads/",
+  filters: {
+    prefix: "uploads/",
+    suffixes: [".mp4", ".mov"],
+    minBytes: 1024n, // ignore the zero-byte placeholder some clients write first
+  },
+  action: {
+    outputs: [{ preset: "web_1080p_standard" }],
+    managed: true, // host and deliver the result; set outputOriginId for your own bucket
+    priority: JobPriority.STANDARD,
+  },
+});
+
+console.log("point your bucket notifications at", rule!.endpointUrl);
+console.log("secret (shown once):", secret);
+```
+
+`secret` is the **only** time the inbound secret is readable — store it wherever
+the event sender will read it from. A later `get` returns just `secretPrefix`
+and `secretHint`. Lost it? `update` with `rotateSecret: true` issues a new one,
+and the previous one keeps working for 24 hours so the sender can be changed
+without dropping an event.
+
+Every delivery is recorded, whether or not it became a job:
+
+```ts
+for await (const event of client.ingestRules
+  .listEvents({ ruleId: rule!.id })
+  .autoPage()) {
+  console.log(event.id, event.source, event.objectKey, event.status, event.reason);
+}
+```
+
+A `SKIPPED` event names why in `reason` — `filter_prefix`, `filter_suffix`,
+`filter_content_type`, `filter_size`, `bucket_mismatch`, `rule_disabled`, or
+`duplicate`. A `FAILED` one carries the API error code that refused the job,
+such as `limit_exceeded`.
+
+Deduplication is permanent: an object is identified by (rule, bucket, key,
+etag), so re-sending the event or re-uploading the same bytes produces nothing.
+To give an object another pass — one that arrived while the rule was paused, or
+was refused while the account was over its cap — replay it:
+
+```ts
+const replayed = await client.ingestRules.replayEvent("sev_a1b2c3d4e5f6g7");
+console.log(replayed.id, "is back in", StorageEventStatus[replayed.status]);
+```
+
+Only `SKIPPED` and `FAILED` events can be replayed. When an `update` switches a
+paused rule back on, the response reports how large that backlog is in
+`eventsSkippedWhileDisabled`.
+
+Before wiring the provider up, dry-run a key against the rule with
+`client.ingestRules.test(...)`: it reports whether the filters match and, when
+they do, the exact job request the rule would submit. Nothing is stored.
+
 ## Webhooks
 
 Transcodely signs every webhook delivery with HMAC-SHA-256 using your endpoint's `whsec_…` secret. Verify the signature before trusting the body — `client.webhooks.constructEvent` validates the signature, parses the envelope, and returns a typed event: