@transcodely/sdk 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.1](https://github.com/transcodely/transcodely-js/compare/v0.3.0...v0.3.1) (2026-07-29)
+
+
+### Features
+
+* expose daily usage buckets and webhook endpoint health + event object-id filtering ([#26](https://github.com/transcodely/transcodely-js/issues/26)) ([28d3c77](https://github.com/transcodely/transcodely-js/commit/28d3c775c04dea4d3f8ff5c35b232072e40144f2))
+* post-launch feature program integration (transcodely-js) ([#38](https://github.com/transcodely/transcodely-js/issues/38)) ([c8705ca](https://github.com/transcodely/transcodely-js/commit/c8705ca411d6ad0a0a221fb4d61461b9f963f49a))
+* sync protos with api 3.10 — billing, captions text tracks, app suspension ([#39](https://github.com/transcodely/transcodely-js/issues/39)) ([a0e158c](https://github.com/transcodely/transcodely-js/commit/a0e158ce19f40c0f983ee9bc018f53073b6bdba4))
+
+
+### Bug Fixes
+
+* add working eslint setup, correct create-job example shape ([#24](https://github.com/transcodely/transcodely-js/issues/24)) ([d2e40bd](https://github.com/transcodely/transcodely-js/commit/d2e40bd922cd1b453eba903e63e67cacb512c25b))
+* **webhooks:** restore WebhookEvent narrowing via type guards ([#40](https://github.com/transcodely/transcodely-js/issues/40)) ([c5913a3](https://github.com/transcodely/transcodely-js/commit/c5913a311a6efde2d9a29fb53a9ef0f76d5f904a))
+
+
+### Documentation
+
+* note content-aware encoding is rejected at create ([#30](https://github.com/transcodely/transcodely-js/issues/30)) ([a7da4ec](https://github.com/transcodely/transcodely-js/commit/a7da4ec9474e9754aa30269e5cdeb1dd40af8815))
+* set managed on the README quick start create-job ([#32](https://github.com/transcodely/transcodely-js/issues/32)) ([5cef326](https://github.com/transcodely/transcodely-js/commit/5cef326f2788262204fb1d986eb284f38870dffc))
+
 ## [0.3.0](https://github.com/transcodely/transcodely-js/compare/v0.2.0...v0.3.0) (2026-07-15)
 
 

package/README.md

@@ -16,6 +16,9 @@ const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });
 // Create a job
 const job = await client.jobs.create({
   inputUrl: "https://example.com/source.mp4",
+  // Write outputs to Transcodely-managed storage. Drop `managed` and set
+  // `outputOriginId: "ori_..."` to write to your own configured origin.
+  managed: true,
   outputs: [{
     type: OutputFormat.HLS,
     video: [
@@ -23,6 +26,10 @@ const job = await client.jobs.create({
       { codec: VideoCodec.H264, resolution: Resolution.RESOLUTION_720P },
     ],
   }],
+  // Optional: encode only a sub-range of the input. Applies job-wide and
+  // reduces cost (billing keys off the produced output duration). Omit
+  // `endSeconds` (or leave 0) to encode through to the end of the input.
+  clip: { startSeconds: 2, endSeconds: 7 },
 });
 
 console.log(job.id); // "job_a1b2c3d4e5f6"
@@ -34,6 +41,45 @@ for await (const event of client.jobs.watch(job.id)) {
 }
 ```
 
+## AI captions
+
+Add auto-generated captions to any output with a `generate` subtitle track.
+Leave `language` empty (or set `"auto"`) to auto-detect the spoken language, or
+pass an ISO 639-2 code to force one. A per-job fee is metered by source minute
+and surfaced on `job.fees`; the produced captions show up on `job.subtitleResults`
+with `autoGenerated: true`.
+
+```ts
+import { Transcodely, OutputFormat, VideoCodec, Resolution, SubtitleOperation } from "@transcodely/sdk";
+
+const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });
+
+// Generate captions while transcoding a new source.
+await client.jobs.create({
+  inputUrl: "https://example.com/source.mp4",
+  managed: true,
+  outputs: [{
+    type: OutputFormat.HLS,
+    video: [{ codec: VideoCodec.H264, resolution: Resolution.RESOLUTION_1080P }],
+    subtitleTracks: [{ operation: SubtitleOperation.GENERATE, language: "auto" }],
+  }],
+});
+
+// Retro-caption a video you've already hosted: reference it by inputVideoId and
+// request a single captions-only output (no video encode).
+const job = await client.jobs.create({
+  inputVideoId: "vid_a1b2c3d4e5f6g7",
+  outputs: [{ subtitleTracks: [{ operation: SubtitleOperation.GENERATE }] }],
+});
+
+for (const result of job.subtitleResults) {
+  console.log(result.language, result.autoGenerated, result.url);
+}
+for (const fee of job.fees) {
+  console.log(fee.feeType, fee.amount, fee.currency); // "captions" 0.51 "eur"
+}
+```
+
 ## Authentication
 
 Pass your API key in the constructor:
@@ -46,7 +92,7 @@ const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });
 
 ```ts
 client.jobs            // create / get / list / cancel / confirm / watch
-client.videos          // upload helpers, multipart, get / list / update / delete / watch
+client.videos          // upload helpers, 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.apps            // create / get / list / update / archive / enableHosting
@@ -174,17 +220,22 @@ app.post(
         process.env.WEBHOOK_SECRET!,
       );
 
-      switch (event.type) {
-        case "job.succeeded":
-          // event.data is a fully-typed Job
-          console.log("Job done:", event.data.id);
-          break;
-        case "video.uploaded":
-          console.log("Video uploaded:", event.data.id);
-          break;
-        default:
-          // Forward-compat: unknown types still parse.
-          console.log("Unhandled:", event.type);
+      // `isKnownEvent` narrows `event` to the events this SDK types precisely,
+      // so inside the switch `event.data` is the exact resource — no casts.
+      if (client.webhooks.isKnownEvent(event)) {
+        switch (event.type) {
+          case "job.succeeded":
+            console.log("Job done:", event.data.id); // event.data is a fully-typed Job
+            break;
+          case "video.uploaded":
+            console.log("Video uploaded:", event.data.id); // event.data is a Video
+            break;
+          // ...handle the other known types you care about
+        }
+      } else {
+        // Forward-compat: an event type added to the API after this SDK
+        // release still verifies and parses; `event.data` is raw `unknown`.
+        console.log("Unhandled future type:", event.type);
       }
       res.sendStatus(200);
     } catch (err) {
@@ -200,6 +251,21 @@ app.post(
 
 The signed payload is the **raw HTTP body** — use `express.raw()` (or the equivalent in your framework) to receive a `Buffer`, never `express.json()`.
 
+#### Narrowing the event
+
+`constructEvent` (and `client.events.retrieve` / `.list`) return a `WebhookEvent`: the closed, precisely-typed `KnownWebhookEvent` union **plus** an open `UnknownWebhookEvent` arm (`type: string; data: unknown`) so a payload for an event type added after this SDK release still verifies and parses instead of being dropped. That open arm means a bare `switch (event.type)` can't narrow `event.data` on its own — funnel through one of two guards first:
+
+- **`isKnownEvent(event)`** narrows to `KnownWebhookEvent`, re-enabling a `switch (event.type)` where every `case` narrows `event.data` to the right resource (and TypeScript flags a `case` you left out if you keep the switch exhaustive). The `else` branch is your forward-compat handler.
+- **`isEventType(event, "job.succeeded")`** narrows to a single event type — ideal for a receiver that only cares about one or two:
+
+```ts
+if (client.webhooks.isEventType(event, "output.ready")) {
+  console.log(event.data.outputUrl); // event.data is a fully-typed JobOutput
+}
+```
+
+Both are also exported standalone (`import { isKnownEvent, isEventType } from "@transcodely/sdk"`) for code that doesn't hold a client. `WebhookEvent`, `KnownWebhookEvent`, and `UnknownWebhookEvent` are all exported for annotating your own handler signatures.
+
 Every event carries a `request` object. Events emitted **inside** an API request scope (e.g. `job.created`, from your `jobs.create` call) set `request.id` to the originating `req_*` ID. Events emitted **outside** a request scope — every worker-driven `job.*` / `output.*` event (`job.succeeded`, `job.failed`, `job.canceled`, `job.progress`, `output.ready`, …) — set `request.id` to `null`. `request.idempotencyKey` is `null` whenever the originating request didn't supply one.
 
 `constructEvent` accepts `request.id: null` from **v0.1.3** onward. v0.1.2 and earlier rejected such deliveries with a `WebhookPayloadError` — upgrade if you validate worker-driven events.