@transcodely/sdk 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.2.0](https://github.com/transcodely/transcodely-js/compare/v0.1.4...v0.2.0) (2026-07-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* The APIKeyEnvironment enum and its API-key `environment` field are removed, and webhook events no longer expose `livemode`. Code that read `event.livemode` or referenced `APIKeyEnvironment` must be updated.
+
+### Features
+
+* proto resync (rotation + measured output metrics), null request.id vector, wire-type docs ([#15](https://github.com/transcodely/transcodely-js/issues/15)) ([b50fac9](https://github.com/transcodely/transcodely-js/commit/b50fac9a5778642ab5887347bd117fed32ac5a2d))
+* remove API-key environment and webhook livemode ([#18](https://github.com/transcodely/transcodely-js/issues/18)) ([80d05ab](https://github.com/transcodely/transcodely-js/commit/80d05ab5a45a592e8b42487c420074d23f2228e1))
+
+
+### Documentation
+
+* commit CLAUDE.md (was untracked — the routine fleet reads it via the GitHub API) ([3a494f3](https://github.com/transcodely/transcodely-js/commit/3a494f36d7f2416984097ec9cec72a58efb6ea37))
+
 ## [0.1.4](https://github.com/transcodely/transcodely-js/compare/v0.1.3...v0.1.4) (2026-07-07)
 
 

package/README.md

@@ -42,8 +42,6 @@ Pass your API key in the constructor:
 const client = new Transcodely({ apiKey: process.env.TRANSCODELY_API_KEY! });
 ```
 
-Test-mode keys (`ak_test_*`) and live-mode keys (`ak_live_*`) hit the same base URL — the environment is encoded in the key prefix.
-
 ## Resources
 
 ```ts
@@ -202,6 +200,10 @@ 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()`.
 
+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.
+
 ### Multi-secret rotation
 
 Pass an array to verify against both your previous and current secrets during a rotation window:
@@ -354,6 +356,18 @@ catch (err) {
 
 The SDK uses Connect-RPC over HTTP+JSON with snake_case field names and lowercase simplified enum values (e.g. `"pending"` instead of `"JOB_STATUS_PENDING"`). A custom codec handles the transformation transparently — the surface you write against is fully typed.
 
+A few in-memory vs. on-the-wire representations are worth knowing:
+
+- **64-bit integers** (byte sizes, millisecond durations — e.g. `sizeBytes`) are `bigint` in memory and serialize as decimal **strings** on the wire.
+- **Enums** are numeric in memory but serialize to their lowercase string names via `toJSON()` (`JobStatus.COMPLETED` ⇄ `"completed"`).
+- **`output_url` and thumbnail URL values are storage URLs** (e.g. `s3://bucket/key`, `gs://bucket/key`), not HTTP URLs — resolve them through your origin or CDN to fetch bytes.
+
+### Measured output & input metadata
+
+When an output completes, its `JobOutput` reports the real encoded geometry measured from the produced media — `width`, `height`, and `averageBitrateKbps`. For multi-variant outputs (ABR ladders) those aggregate the ladder, and `variantResults` (an `OutputVariantResult[]`, indexed like `variantPricing`) carries per-variant `width` / `height` / `averageBitrateKbps` / `sizeBytes`. Thumbnail results (`ThumbnailResult`) likewise carry their real rendered `width` / `height`.
+
+On the input side, `VideoStreamInfo.rotation` exposes container rotation in degrees clockwise (`0` / `90` / `180` / `270`, absent when the stream has no rotation metadata), and `width` / `height` / `displayAspectRatio` are **display-oriented** — rotation is already applied, so they match what a player shows.
+
 ## Versioning
 
 The SDK is versioned independently with semver, starting at `0.1.0`. Breaking changes are allowed on minor bumps until `1.0.0`. Each release pins a specific calendar-versioned API (`Transcodely.API_VERSION`) and sends `Transcodely-Version` on every request.

package/dist/index.cjs

@@ -357,17 +357,6 @@ var FieldViolation = class _FieldViolation extends protobuf.Message {
 };
 
 // src/gen/transcodely/v1/api_key_pb.ts
-var APIKeyEnvironment = /* @__PURE__ */ ((APIKeyEnvironment2) => {
-  APIKeyEnvironment2[APIKeyEnvironment2["API_KEY_ENVIRONMENT_UNSPECIFIED"] = 0] = "API_KEY_ENVIRONMENT_UNSPECIFIED";
-  APIKeyEnvironment2[APIKeyEnvironment2["API_KEY_ENVIRONMENT_LIVE"] = 1] = "API_KEY_ENVIRONMENT_LIVE";
-  APIKeyEnvironment2[APIKeyEnvironment2["API_KEY_ENVIRONMENT_TEST"] = 2] = "API_KEY_ENVIRONMENT_TEST";
-  return APIKeyEnvironment2;
-})(APIKeyEnvironment || {});
-protobuf.proto3.util.setEnumType(APIKeyEnvironment, "transcodely.v1.APIKeyEnvironment", [
-  { no: 0, name: "API_KEY_ENVIRONMENT_UNSPECIFIED" },
-  { no: 1, name: "API_KEY_ENVIRONMENT_LIVE" },
-  { no: 2, name: "API_KEY_ENVIRONMENT_TEST" }
-]);
 var APIKey = class _APIKey extends protobuf.Message {
   /**
    * Unique API key identifier (e.g., "ak_a1b2c3d4...").
@@ -388,7 +377,7 @@ var APIKey = class _APIKey extends protobuf.Message {
    */
   description = "";
   /**
-   * Key prefix for identification (e.g., "ak_live_" or "ak_test_").
+   * Key prefix for identification (e.g., "ak_...").
    * Safe to display in logs and dashboards.
    *
    * @generated from field: string key_prefix = 4;
@@ -401,12 +390,6 @@ var APIKey = class _APIKey extends protobuf.Message {
    * @generated from field: string key_hint = 5;
    */
   keyHint = "";
-  /**
-   * Environment the key is valid for.
-   *
-   * @generated from field: transcodely.v1.APIKeyEnvironment environment = 6;
-   */
-  environment = 0 /* API_KEY_ENVIRONMENT_UNSPECIFIED */;
   /**
    * Permission scopes (empty means full access).
    * Future: granular permissions like "jobs:read", "jobs:write".
@@ -486,7 +469,6 @@ var APIKey = class _APIKey extends protobuf.Message {
       T: 9
       /* ScalarType.STRING */
     },
-    { no: 6, name: "environment", kind: "enum", T: protobuf.proto3.getEnumType(APIKeyEnvironment) },
     { no: 7, name: "scopes", kind: "scalar", T: 9, repeated: true },
     { no: 8, name: "last_used_at", kind: "message", T: protobuf.Timestamp, opt: true },
     { no: 9, name: "expires_at", kind: "message", T: protobuf.Timestamp, opt: true },
@@ -526,12 +508,6 @@ var CreateAPIKeyRequest = class _CreateAPIKeyRequest extends protobuf.Message {
    * @generated from field: string description = 2;
    */
   description = "";
-  /**
-   * Environment for the key.
-   *
-   * @generated from field: transcodely.v1.APIKeyEnvironment environment = 3;
-   */
-  environment = 0 /* API_KEY_ENVIRONMENT_UNSPECIFIED */;
   /**
    * Optional expiration time. Null means the key never expires.
    *
@@ -566,7 +542,6 @@ var CreateAPIKeyRequest = class _CreateAPIKeyRequest extends protobuf.Message {
       T: 9
       /* ScalarType.STRING */
     },
-    { no: 3, name: "environment", kind: "enum", T: protobuf.proto3.getEnumType(APIKeyEnvironment) },
     { no: 4, name: "expires_at", kind: "message", T: protobuf.Timestamp, opt: true },
     {
       no: 5,
@@ -698,12 +673,6 @@ var GetAPIKeyResponse = class _GetAPIKeyResponse extends protobuf.Message {
   }
 };
 var ListAPIKeysRequest = class _ListAPIKeysRequest extends protobuf.Message {
-  /**
-   * Optional filter by environment.
-   *
-   * @generated from field: optional transcodely.v1.APIKeyEnvironment environment = 1;
-   */
-  environment;
   /**
    * If true, include revoked keys in the response.
    *
@@ -723,7 +692,6 @@ var ListAPIKeysRequest = class _ListAPIKeysRequest extends protobuf.Message {
   static runtime = protobuf.proto3;
   static typeName = "transcodely.v1.ListAPIKeysRequest";
   static fields = protobuf.proto3.util.newFieldList(() => [
-    { no: 1, name: "environment", kind: "enum", T: protobuf.proto3.getEnumType(APIKeyEnvironment), opt: true },
     {
       no: 2,
       name: "include_revoked",
@@ -2379,13 +2347,6 @@ var Event = class _Event extends protobuf.Message {
    * @generated from field: string api_version = 8;
    */
   apiVersion = "";
-  /**
-   * True when the event was emitted from production (live mode) traffic.
-   * Reserved for a future test-mode concept; always `true` today.
-   *
-   * @generated from field: bool livemode = 9;
-   */
-  livemode = false;
   /**
    * Resource type discriminator. Always "event" for this message.
    * Mirrored into the webhook envelope as the top-level `object`.
@@ -2444,13 +2405,6 @@ var Event = class _Event extends protobuf.Message {
       T: 9
       /* ScalarType.STRING */
     },
-    {
-      no: 9,
-      name: "livemode",
-      kind: "scalar",
-      T: 8
-      /* ScalarType.BOOL */
-    },
     {
       no: 10,
       name: "object",
@@ -2492,8 +2446,11 @@ var WebhookDelivery = class _WebhookDelivery extends protobuf.Message {
    */
   eventId = "";
   /**
-   * Delivery status: "pending", "succeeded", or "failed".
-   * Wire value is lowercase per project convention.
+   * Delivery status: "pending", "succeeded", "failed", or "exhausted".
+   * "exhausted" means the retry curve ran out (attempt 15) without a success;
+   * "failed" is a single failed attempt (a retry may still be scheduled) or an
+   * early stop on a non-retryable 4xx. Wire value is lowercase per project
+   * convention.
    *
    * @generated from field: string status = 4;
    */
@@ -2546,7 +2503,8 @@ var WebhookDelivery = class _WebhookDelivery extends protobuf.Message {
   latencyMs;
   /**
    * Reason a response was not received. Absent when response_status is set.
-   * One of: "timeout", "connection_refused", "dns_failure",
+   * One of: "timeout", "connection_refused", "connection_reset",
+   * "connection_closed", "host_unreachable", "dns_failure",
    * "tls_handshake_failed", "ssrf_blocked", "unknown".
    * Wire value is lowercase per project convention.
    *
@@ -2565,6 +2523,15 @@ var WebhookDelivery = class _WebhookDelivery extends protobuf.Message {
    * @generated from field: optional string response_headers = 13;
    */
   responseHeaders;
+  /**
+   * Human-readable detail for the failure: the transport error text when
+   * transport_error is set, or "non-2xx response: <status>" for a completed
+   * request that the endpoint rejected. Absent for pending or succeeded
+   * deliveries.
+   *
+   * @generated from field: optional string error_message = 14;
+   */
+  errorMessage;
   constructor(data) {
     super();
     protobuf.proto3.util.initPartial(data, this);
@@ -2614,7 +2581,8 @@ var WebhookDelivery = class _WebhookDelivery extends protobuf.Message {
     { no: 10, name: "updated_at", kind: "message", T: protobuf.Timestamp },
     { no: 11, name: "latency_ms", kind: "scalar", T: 5, opt: true },
     { no: 12, name: "transport_error", kind: "scalar", T: 9, opt: true },
-    { no: 13, name: "response_headers", kind: "scalar", T: 9, opt: true }
+    { no: 13, name: "response_headers", kind: "scalar", T: 9, opt: true },
+    { no: 14, name: "error_message", kind: "scalar", T: 9, opt: true }
   ]);
   static fromBinary(bytes, options) {
     return new _WebhookDelivery().fromBinary(bytes, options);
@@ -3438,7 +3406,7 @@ var ListWebhookDeliveriesRequest = class _ListWebhookDeliveriesRequest extends p
    */
   eventId;
   /**
-   * Filter by status: "pending", "succeeded", or "failed".
+   * Filter by status: "pending", "succeeded", "failed", or "exhausted".
    *
    * @generated from field: optional string status = 3;
    */
@@ -6975,13 +6943,16 @@ var VideoStreamInfo = class _VideoStreamInfo extends protobuf.Message {
    */
   codec = "";
   /**
-   * Frame width in pixels.
+   * Frame width in pixels, as displayed (container rotation applied).
+   * For a portrait phone recording stored as 1920x1440 with a 90° rotation
+   * side-matrix this is 1440 — matching the media players render and the
+   * outputs Transcodely produces. See `rotation` for the stored orientation.
    *
    * @generated from field: int32 width = 2;
    */
   width = 0;
   /**
-   * Frame height in pixels.
+   * Frame height in pixels, as displayed (container rotation applied).
    *
    * @generated from field: int32 height = 3;
    */
@@ -7053,7 +7024,9 @@ var VideoStreamInfo = class _VideoStreamInfo extends protobuf.Message {
    */
   frameCount;
   /**
-   * Display aspect ratio as string (e.g., "16:9", "2.35:1").
+   * Display aspect ratio as string (e.g., "16:9", "2.35:1"), rotation-aware:
+   * for a 90°/270° rotated stream the ratio describes the displayed frame
+   * (consistent with width/height above), not the coded one.
    *
    * @generated from field: optional string display_aspect_ratio = 15;
    */
@@ -7064,6 +7037,16 @@ var VideoStreamInfo = class _VideoStreamInfo extends protobuf.Message {
    * @generated from field: optional string sample_aspect_ratio = 16;
    */
   sampleAspectRatio;
+  /**
+   * Container-level rotation metadata in degrees clockwise: 0, 90, 180 or
+   * 270. Parsed from the display-matrix side data (or legacy rotate tag).
+   * width/height/display_aspect_ratio already have this rotation applied;
+   * the field is informational so callers can recover the coded orientation.
+   * Absent when the stream carries no rotation metadata.
+   *
+   * @generated from field: optional int32 rotation = 17;
+   */
+  rotation;
   constructor(data) {
     super();
     protobuf.proto3.util.initPartial(data, this);
@@ -7128,7 +7111,8 @@ var VideoStreamInfo = class _VideoStreamInfo extends protobuf.Message {
     { no: 13, name: "interlaced", kind: "scalar", T: 8, opt: true },
     { no: 14, name: "frame_count", kind: "scalar", T: 3, opt: true },
     { no: 15, name: "display_aspect_ratio", kind: "scalar", T: 9, opt: true },
-    { no: 16, name: "sample_aspect_ratio", kind: "scalar", T: 9, opt: true }
+    { no: 16, name: "sample_aspect_ratio", kind: "scalar", T: 9, opt: true },
+    { no: 17, name: "rotation", kind: "scalar", T: 5, opt: true }
   ]);
   static fromBinary(bytes, options) {
     return new _VideoStreamInfo().fromBinary(bytes, options);
@@ -8606,6 +8590,38 @@ var JobOutput = class _JobOutput extends protobuf.Message {
    * @generated from field: string object = 21;
    */
   object = "";
+  /**
+   * Actual encoded frame width in pixels, measured from the produced media
+   * (rotation applied, so it matches what players display). For multi-variant
+   * outputs (ABR ladders) this is the highest-resolution variant's width;
+   * per-variant dimensions are in variant_results. Set when completed.
+   *
+   * @generated from field: optional int32 width = 22;
+   */
+  width;
+  /**
+   * Actual encoded frame height in pixels (see width for semantics).
+   *
+   * @generated from field: optional int32 height = 23;
+   */
+  height;
+  /**
+   * Measured average bitrate of the encoded output in kbps
+   * (total bytes × 8 / encoded duration). For multi-variant outputs this
+   * aggregates all variants; per-variant bitrates are in variant_results.
+   * Set when completed.
+   *
+   * @generated from field: optional int32 average_bitrate_kbps = 24;
+   */
+  averageBitrateKbps;
+  /**
+   * Per-variant encode results for multi-variant outputs (ABR ladders),
+   * indexed like variant_pricing. Empty for single-variant outputs (use
+   * width/height/average_bitrate_kbps instead). Set when completed.
+   *
+   * @generated from field: repeated transcodely.v1.OutputVariantResult variant_results = 25;
+   */
+  variantResults = [];
   constructor(data) {
     super();
     protobuf.proto3.util.initPartial(data, this);
@@ -8649,7 +8665,11 @@ var JobOutput = class _JobOutput extends protobuf.Message {
       kind: "scalar",
       T: 9
       /* ScalarType.STRING */
-    }
+    },
+    { no: 22, name: "width", kind: "scalar", T: 5, opt: true },
+    { no: 23, name: "height", kind: "scalar", T: 5, opt: true },
+    { no: 24, name: "average_bitrate_kbps", kind: "scalar", T: 5, opt: true },
+    { no: 25, name: "variant_results", kind: "message", T: OutputVariantResult, repeated: true }
   ]);
   static fromBinary(bytes, options) {
     return new _JobOutput().fromBinary(bytes, options);
@@ -8664,6 +8684,81 @@ var JobOutput = class _JobOutput extends protobuf.Message {
     return protobuf.proto3.util.equals(_JobOutput, a, b);
   }
 };
+var OutputVariantResult = class _OutputVariantResult extends protobuf.Message {
+  /**
+   * Variant index within the output (0-based).
+   *
+   * @generated from field: int32 index = 1;
+   */
+  index = 0;
+  /**
+   * Actual encoded frame width in pixels.
+   *
+   * @generated from field: int32 width = 2;
+   */
+  width = 0;
+  /**
+   * Actual encoded frame height in pixels.
+   *
+   * @generated from field: int32 height = 3;
+   */
+  height = 0;
+  /**
+   * Measured average bitrate for this variant in kbps.
+   *
+   * @generated from field: optional int32 average_bitrate_kbps = 4;
+   */
+  averageBitrateKbps;
+  /**
+   * Total encoded size of this variant in bytes.
+   *
+   * @generated from field: optional int64 size_bytes = 5;
+   */
+  sizeBytes;
+  constructor(data) {
+    super();
+    protobuf.proto3.util.initPartial(data, this);
+  }
+  static runtime = protobuf.proto3;
+  static typeName = "transcodely.v1.OutputVariantResult";
+  static fields = protobuf.proto3.util.newFieldList(() => [
+    {
+      no: 1,
+      name: "index",
+      kind: "scalar",
+      T: 5
+      /* ScalarType.INT32 */
+    },
+    {
+      no: 2,
+      name: "width",
+      kind: "scalar",
+      T: 5
+      /* ScalarType.INT32 */
+    },
+    {
+      no: 3,
+      name: "height",
+      kind: "scalar",
+      T: 5
+      /* ScalarType.INT32 */
+    },
+    { no: 4, name: "average_bitrate_kbps", kind: "scalar", T: 5, opt: true },
+    { no: 5, name: "size_bytes", kind: "scalar", T: 3, opt: true }
+  ]);
+  static fromBinary(bytes, options) {
+    return new _OutputVariantResult().fromBinary(bytes, options);
+  }
+  static fromJson(jsonValue, options) {
+    return new _OutputVariantResult().fromJson(jsonValue, options);
+  }
+  static fromJsonString(jsonString, options) {
+    return new _OutputVariantResult().fromJsonString(jsonString, options);
+  }
+  static equals(a, b) {
+    return protobuf.proto3.util.equals(_OutputVariantResult, a, b);
+  }
+};
 var ExecutionTiming = class _ExecutionTiming extends protobuf.Message {
   /**
    * Worker instance details
@@ -11505,7 +11600,6 @@ function protoEventToSdk(proto) {
     created: proto.createdAt ? proto.createdAt.toDate().toISOString() : "",
     type: proto.type,
     data,
-    livemode: proto.livemode,
     pendingWebhooks: proto.pendingWebhooks,
     // proto Event carries only `request_id`; `idempotency_key` is always
     // null until JobService.Create propagates it (out-of-scope feature).
@@ -11857,7 +11951,7 @@ function backoff(attempt) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.0";
 var API_VERSION = "2026-05-03";
 var DEFAULT_BASE_URL = "https://api.transcodely.com";
 
@@ -16230,13 +16324,6 @@ function requireString(obj, key) {
   }
   return v;
 }
-function requireBoolean(obj, key) {
-  const v = obj[key];
-  if (typeof v !== "boolean") {
-    throw new WebhookPayloadError(`Webhook envelope field \`${key}\` must be a boolean`);
-  }
-  return v;
-}
 function requireNumber(obj, key) {
   const v = obj[key];
   if (typeof v !== "number" || !Number.isFinite(v)) {
@@ -16255,7 +16342,6 @@ function buildEvent(parsed) {
   const apiVersion = requireString(parsed, "api_version");
   const created = requireString(parsed, "created");
   const type = requireString(parsed, "type");
-  const livemode = requireBoolean(parsed, "livemode");
   const pendingWebhooks = requireNumber(parsed, "pending_webhooks");
   const dataRaw = parsed["data"];
   if (!isPlainObject(dataRaw)) {
@@ -16286,7 +16372,6 @@ function buildEvent(parsed) {
     created,
     type,
     data,
-    livemode,
     pendingWebhooks,
     request: { id: requestIdRaw, idempotencyKey: idempotencyKeyRaw }
   };
@@ -16376,7 +16461,6 @@ Transcodely.SDK_VERSION = SDK_VERSION;
 
 exports.APIConnectionError = APIConnectionError;
 exports.APIError = APIError;
-exports.APIKeyEnvironment = APIKeyEnvironment;
 exports.API_VERSION = API_VERSION;
 exports.AppStatus = AppStatus;
 exports.AudioCodec = AudioCodec;