@rendobar/sdk 4.2.0 → 5.1.0

package/README.md

@@ -253,14 +253,14 @@ const endpoint = await client.webhooks.create({
   subscribedEvents: ["job.completed", "job.failed"],
 });
 
-// Verify signature in your webhook handler
-import { verifyWebhookSignature } from "@rendobar/sdk/webhooks";
-
-const isValid = await verifyWebhookSignature(
-  requestBody,
-  request.headers.get("X-Rendobar-Signature"),
-  signingSecret,
-);
+// 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.
+import { verifyWebhook } from "@rendobar/sdk/webhooks";
+
+const ok = await verifyWebhook(rawBody, request.headers, signingSecret);
+if (!ok) throw new Error("invalid signature");
 ```
 
 ## Realtime Events (WebSocket)

package/dist/index.cjs

@@ -176,7 +176,7 @@ function isAbortError(error) {
 }
 //#endregion
 //#region src/resources/jobs.ts
-const TERMINAL_STATUSES$1 = /* @__PURE__ */ new Set([
+const TERMINAL_JOB_STATUSES$1 = /* @__PURE__ */ new Set([
 	"complete",
 	"failed",
 	"cancelled"
@@ -190,7 +190,7 @@ function createJobsResource(request) {
 			if (signal?.aborted) throw new DOMException("Wait aborted", "AbortError");
 			const job = await request(`/jobs/${id}`, { signal });
 			onProgress?.(job);
-			if (TERMINAL_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
+			if (TERMINAL_JOB_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
 			const remaining = deadline - Date.now();
 			const delay = Math.min(currentInterval, remaining);
 			if (delay <= 0) break;
@@ -199,7 +199,7 @@ function createJobsResource(request) {
 		}
 		const job = await request(`/jobs/${id}`, { signal });
 		onProgress?.(job);
-		if (TERMINAL_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
+		if (TERMINAL_JOB_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
 		throw new WaitTimeoutError(id, job.status, timeout);
 	}
 	async function create(params, options) {
@@ -762,7 +762,7 @@ const WS_OPTIONS = {
 	reconnectionDelayGrowFactor: 1.5,
 	maxRetries: Infinity
 };
-const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+const TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set([
 	"complete",
 	"failed",
 	"cancelled"
@@ -775,8 +775,10 @@ const KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set([
 	"job.progress",
 	"job.step",
 	"job.log",
+	"job.resources",
 	"job.metrics",
 	"job.context",
+	"job.region_failover",
 	"balance.updated",
 	"subscription.updated",
 	"notification",
@@ -859,15 +861,19 @@ function dispatchJobEvent(event, options) {
 		case "job.status": {
 			const statusEvent = event;
 			options.onStatus?.(statusEvent);
-			if (TERMINAL_STATUSES.has(statusEvent.status)) options.onComplete?.(statusEvent);
+			if (TERMINAL_JOB_STATUSES.has(statusEvent.status)) options.onComplete?.(statusEvent);
 			break;
 		}
 		case "job.result":
 			options.onResult?.(event);
 			break;
-		case "job.metrics":
-			options.onMetrics?.(event);
+		case "job.resources":
+		case "job.metrics": {
+			const e = event;
+			options.onResources?.(e);
+			options.onMetrics?.(e);
 			break;
+		}
 		case "job.context":
 			options.onContext?.(event);
 			break;

package/dist/index.d.cts

@@ -2246,6 +2246,11 @@ declare const jobErrorSchema: ZodObject<{
   message: ZodString;
   detail: ZodNullable<ZodString>;
   retryable: ZodBoolean;
+  failedPhase: ZodOptional<ZodEnum<{
+    preparing: "preparing";
+    processing: "processing";
+    finalizing: "finalizing";
+  }>>;
 }, $strip>;
 declare const jobCostSchema: ZodObject<{
   amount: ZodNumber;
@@ -2287,7 +2292,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2295,6 +2301,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"waiting">;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2331,7 +2344,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2339,8 +2353,15 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"dispatched">;
-  progress: ZodOptional<ZodNumber>;
+  progress: ZodOptional<ZodNullable<ZodNumber>>;
   eta: ZodOptional<ZodNullable<ZodNumber>>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2377,7 +2398,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2385,8 +2407,15 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"running">;
-  progress: ZodNumber;
+  progress: ZodNullable<ZodNumber>;
   eta: ZodNullable<ZodNumber>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2423,7 +2452,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2431,6 +2461,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"complete">;
   output: ZodObject<{
     data: ZodUnknown;
@@ -2511,7 +2548,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2519,12 +2557,24 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"failed">;
   error: ZodObject<{
     code: ZodString;
     message: ZodString;
     detail: ZodNullable<ZodString>;
     retryable: ZodBoolean;
+    failedPhase: ZodOptional<ZodEnum<{
+      preparing: "preparing";
+      processing: "processing";
+      finalizing: "finalizing";
+    }>>;
   }, $strip>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2561,7 +2611,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2569,6 +2620,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"cancelled">;
 }, $strip>], "status">;
 declare const jobCreatedResponseSchema: ZodObject<{
@@ -2706,10 +2764,10 @@ declare const webhookDeliverySchema: ZodObject<{
   event: ZodString;
   payload: ZodString;
   status: ZodEnum<{
-    failed: "failed";
-    cancelled: "cancelled";
     pending: "pending";
     delivered: "delivered";
+    failed: "failed";
+    cancelled: "cancelled";
   }>;
   statusCode: ZodNullable<ZodNumber>;
   responseBody: ZodNullable<ZodString>;
@@ -2964,14 +3022,35 @@ declare const orgEventSchema: ZodDiscriminatedUnion<[ZodObject<{
   type: ZodLiteral<"job.progress">;
   jobId: ZodString;
   timestamp: ZodNumber;
-  progress: ZodNumber;
+  progress: ZodNullable<ZodNumber>;
+  phase: ZodOptional<ZodEnum<{
+    preparing: "preparing";
+    processing: "processing";
+    finalizing: "finalizing";
+  }>>;
   step: ZodString;
   stepProgress: ZodOptional<ZodNumber>;
   eta: ZodOptional<ZodNumber>;
   metrics: ZodOptional<ZodRecord<ZodString, ZodUnion<readonly [ZodNumber, ZodString]>>>;
 }, $strip>, ZodObject<{
-  type: ZodLiteral<"job.metrics">;
+  timestamp: ZodNumber;
+  cpuPct: ZodNumber;
+  cpuCores: ZodNumber;
+  allocatedCores: ZodOptional<ZodNumber>;
+  memUsedMB: ZodNumber;
+  memLimitMB: ZodNumber;
+  diskRMBps: ZodOptional<ZodNumber>;
+  diskWMBps: ZodOptional<ZodNumber>;
+  netRxMBps: ZodOptional<ZodNumber>;
+  netTxMBps: ZodOptional<ZodNumber>;
+  gpuPct: ZodOptional<ZodNumber>;
+  gpuMemUsedMB: ZodOptional<ZodNumber>;
+  gpuMemTotalMB: ZodOptional<ZodNumber>;
+  gpuTempC: ZodOptional<ZodNumber>;
+  gpuPowerW: ZodOptional<ZodNumber>;
+  type: ZodLiteral<"job.resources">;
   jobId: ZodString;
+}, $strip>, ZodObject<{
   timestamp: ZodNumber;
   cpuPct: ZodNumber;
   cpuCores: ZodNumber;
@@ -2982,6 +3061,13 @@ declare const orgEventSchema: ZodDiscriminatedUnion<[ZodObject<{
   diskWMBps: ZodOptional<ZodNumber>;
   netRxMBps: ZodOptional<ZodNumber>;
   netTxMBps: ZodOptional<ZodNumber>;
+  gpuPct: ZodOptional<ZodNumber>;
+  gpuMemUsedMB: ZodOptional<ZodNumber>;
+  gpuMemTotalMB: ZodOptional<ZodNumber>;
+  gpuTempC: ZodOptional<ZodNumber>;
+  gpuPowerW: ZodOptional<ZodNumber>;
+  type: ZodLiteral<"job.metrics">;
+  jobId: ZodString;
 }, $strip>, ZodObject<{
   type: ZodLiteral<"job.step">;
   jobId: ZodString;
@@ -3518,9 +3604,19 @@ interface RealtimeConnection {
   disconnect: () => void;
 }
 interface JobSubscribeOptions {
+  /**
+   * Overall progress. Build your UI on `event.phase` (stable: preparing |
+   * processing | finalizing) and `event.progress`. `event.step` is the internal
+   * step id — implementation detail, prefer `phase`.
+   */
   onProgress?: (event: Extract<OrgEvent, {
     type: "job.progress";
   }>) => void;
+  /**
+   * @deprecated Internal step transitions leak pipeline detail and vary by job
+   * type. Use `onProgress` (it carries `phase`, and `step` when you need it).
+   * Kept for the dashboard Trace/debug view; not recommended for app UIs.
+   */
   onStep?: (event: Extract<OrgEvent, {
     type: "job.step";
   }>) => void;
@@ -3536,8 +3632,14 @@ interface JobSubscribeOptions {
   onComplete?: (event: Extract<OrgEvent, {
     type: "job.status";
   }>) => void;
+  /** Container resource utilization (CPU, memory, disk, network, GPU). */
+  onResources?: (event: Extract<OrgEvent, {
+    type: "job.resources";
+  }>) => void;
+  /** @deprecated renamed to onResources. Still fires for both event names.
+   *  Remove at the next SDK major — tracked in docs/DEPRECATIONS.md (Group A). */
   onMetrics?: (event: Extract<OrgEvent, {
-    type: "job.metrics";
+    type: "job.resources";
   }>) => void;
   onContext?: (event: Extract<OrgEvent, {
     type: "job.context";
@@ -3583,6 +3685,31 @@ type CreateJobParams = {
   params?: Record<string, unknown>;
   idempotencyKey?: string;
   forceAsync?: boolean;
+  /**
+   * Per-job completion callback. On a terminal state (complete/failed/cancelled)
+   * Rendobar POSTs the standard job envelope to `url`. HTTPS only. The URL is the
+   * capability — keep it secret, or use the callback as a trigger and re-fetch the
+   * job for authoritative data.
+   *
+   * Optional `headers` (e.g. `{ Authorization: "Bearer …" }`) are sent with the
+   * POST, so the callback can hit an authed target directly — for example
+   * Cloudflare's Workflows events endpoint, with no receiver Worker.
+   *
+   * Set `verify: true` to opt into signing: the POST then carries an
+   * `X-Rendobar-Signature` (same HMAC scheme as webhooks). Fetch your org's
+   * callback signing secret once (`GET /orgs/current/callback-secret`) and verify
+   * with `verifyCallback(rawBody, headers, secret)` from `@rendobar/sdk/webhooks`.
+   *
+   * `events` opts into EXTRA non-terminal events. Terminal events
+   * (complete/failed/cancelled) always fire and can't be filtered out, so a
+   * `waitForEvent` can never hang. Today the only opt-in extra is `job.started`.
+   */
+  callback?: {
+    url: string;
+    headers?: Record<string, string>;
+    verify?: boolean;
+    events?: "job.started"[];
+  };
 };
 type ListJobsParams = {
   status?: string;

package/dist/index.d.mts

@@ -2246,6 +2246,11 @@ declare const jobErrorSchema: ZodObject<{
   message: ZodString;
   detail: ZodNullable<ZodString>;
   retryable: ZodBoolean;
+  failedPhase: ZodOptional<ZodEnum<{
+    preparing: "preparing";
+    processing: "processing";
+    finalizing: "finalizing";
+  }>>;
 }, $strip>;
 declare const jobCostSchema: ZodObject<{
   amount: ZodNumber;
@@ -2287,7 +2292,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2295,6 +2301,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"waiting">;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2331,7 +2344,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2339,8 +2353,15 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"dispatched">;
-  progress: ZodOptional<ZodNumber>;
+  progress: ZodOptional<ZodNullable<ZodNumber>>;
   eta: ZodOptional<ZodNullable<ZodNumber>>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2377,7 +2398,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2385,8 +2407,15 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"running">;
-  progress: ZodNumber;
+  progress: ZodNullable<ZodNumber>;
   eta: ZodNullable<ZodNumber>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2423,7 +2452,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2431,6 +2461,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"complete">;
   output: ZodObject<{
     data: ZodUnknown;
@@ -2511,7 +2548,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2519,12 +2557,24 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"failed">;
   error: ZodObject<{
     code: ZodString;
     message: ZodString;
     detail: ZodNullable<ZodString>;
     retryable: ZodBoolean;
+    failedPhase: ZodOptional<ZodEnum<{
+      preparing: "preparing";
+      processing: "processing";
+      finalizing: "finalizing";
+    }>>;
   }, $strip>;
 }, $strip>, ZodObject<{
   id: ZodString;
@@ -2561,7 +2611,8 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
     error: ZodOptional<ZodString>;
   }, $strip>>;
   logsAvailable: ZodBoolean;
-  metricsAvailable: ZodBoolean;
+  resourcesAvailable: ZodBoolean;
+  metricsAvailable: ZodOptional<ZodBoolean>;
   region: ZodOptional<ZodNullable<ZodString>>;
   createdAt: ZodNumber;
   dispatchedAt: ZodNullable<ZodNumber>;
@@ -2569,6 +2620,13 @@ declare const jobResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
   completedAt: ZodNullable<ZodNumber>;
   settledAt: ZodNullable<ZodNumber>;
   retentionExpiresAt: ZodNullable<ZodNumber>;
+  callback: ZodOptional<ZodNullable<ZodObject<{
+    status: ZodEnum<{
+      pending: "pending";
+      delivered: "delivered";
+      failed: "failed";
+    }>;
+  }, $strip>>>;
   status: ZodLiteral<"cancelled">;
 }, $strip>], "status">;
 declare const jobCreatedResponseSchema: ZodObject<{
@@ -2706,10 +2764,10 @@ declare const webhookDeliverySchema: ZodObject<{
   event: ZodString;
   payload: ZodString;
   status: ZodEnum<{
-    failed: "failed";
-    cancelled: "cancelled";
     pending: "pending";
     delivered: "delivered";
+    failed: "failed";
+    cancelled: "cancelled";
   }>;
   statusCode: ZodNullable<ZodNumber>;
   responseBody: ZodNullable<ZodString>;
@@ -2964,14 +3022,35 @@ declare const orgEventSchema: ZodDiscriminatedUnion<[ZodObject<{
   type: ZodLiteral<"job.progress">;
   jobId: ZodString;
   timestamp: ZodNumber;
-  progress: ZodNumber;
+  progress: ZodNullable<ZodNumber>;
+  phase: ZodOptional<ZodEnum<{
+    preparing: "preparing";
+    processing: "processing";
+    finalizing: "finalizing";
+  }>>;
   step: ZodString;
   stepProgress: ZodOptional<ZodNumber>;
   eta: ZodOptional<ZodNumber>;
   metrics: ZodOptional<ZodRecord<ZodString, ZodUnion<readonly [ZodNumber, ZodString]>>>;
 }, $strip>, ZodObject<{
-  type: ZodLiteral<"job.metrics">;
+  timestamp: ZodNumber;
+  cpuPct: ZodNumber;
+  cpuCores: ZodNumber;
+  allocatedCores: ZodOptional<ZodNumber>;
+  memUsedMB: ZodNumber;
+  memLimitMB: ZodNumber;
+  diskRMBps: ZodOptional<ZodNumber>;
+  diskWMBps: ZodOptional<ZodNumber>;
+  netRxMBps: ZodOptional<ZodNumber>;
+  netTxMBps: ZodOptional<ZodNumber>;
+  gpuPct: ZodOptional<ZodNumber>;
+  gpuMemUsedMB: ZodOptional<ZodNumber>;
+  gpuMemTotalMB: ZodOptional<ZodNumber>;
+  gpuTempC: ZodOptional<ZodNumber>;
+  gpuPowerW: ZodOptional<ZodNumber>;
+  type: ZodLiteral<"job.resources">;
   jobId: ZodString;
+}, $strip>, ZodObject<{
   timestamp: ZodNumber;
   cpuPct: ZodNumber;
   cpuCores: ZodNumber;
@@ -2982,6 +3061,13 @@ declare const orgEventSchema: ZodDiscriminatedUnion<[ZodObject<{
   diskWMBps: ZodOptional<ZodNumber>;
   netRxMBps: ZodOptional<ZodNumber>;
   netTxMBps: ZodOptional<ZodNumber>;
+  gpuPct: ZodOptional<ZodNumber>;
+  gpuMemUsedMB: ZodOptional<ZodNumber>;
+  gpuMemTotalMB: ZodOptional<ZodNumber>;
+  gpuTempC: ZodOptional<ZodNumber>;
+  gpuPowerW: ZodOptional<ZodNumber>;
+  type: ZodLiteral<"job.metrics">;
+  jobId: ZodString;
 }, $strip>, ZodObject<{
   type: ZodLiteral<"job.step">;
   jobId: ZodString;
@@ -3518,9 +3604,19 @@ interface RealtimeConnection {
   disconnect: () => void;
 }
 interface JobSubscribeOptions {
+  /**
+   * Overall progress. Build your UI on `event.phase` (stable: preparing |
+   * processing | finalizing) and `event.progress`. `event.step` is the internal
+   * step id — implementation detail, prefer `phase`.
+   */
   onProgress?: (event: Extract<OrgEvent, {
     type: "job.progress";
   }>) => void;
+  /**
+   * @deprecated Internal step transitions leak pipeline detail and vary by job
+   * type. Use `onProgress` (it carries `phase`, and `step` when you need it).
+   * Kept for the dashboard Trace/debug view; not recommended for app UIs.
+   */
   onStep?: (event: Extract<OrgEvent, {
     type: "job.step";
   }>) => void;
@@ -3536,8 +3632,14 @@ interface JobSubscribeOptions {
   onComplete?: (event: Extract<OrgEvent, {
     type: "job.status";
   }>) => void;
+  /** Container resource utilization (CPU, memory, disk, network, GPU). */
+  onResources?: (event: Extract<OrgEvent, {
+    type: "job.resources";
+  }>) => void;
+  /** @deprecated renamed to onResources. Still fires for both event names.
+   *  Remove at the next SDK major — tracked in docs/DEPRECATIONS.md (Group A). */
   onMetrics?: (event: Extract<OrgEvent, {
-    type: "job.metrics";
+    type: "job.resources";
   }>) => void;
   onContext?: (event: Extract<OrgEvent, {
     type: "job.context";
@@ -3583,6 +3685,31 @@ type CreateJobParams = {
   params?: Record<string, unknown>;
   idempotencyKey?: string;
   forceAsync?: boolean;
+  /**
+   * Per-job completion callback. On a terminal state (complete/failed/cancelled)
+   * Rendobar POSTs the standard job envelope to `url`. HTTPS only. The URL is the
+   * capability — keep it secret, or use the callback as a trigger and re-fetch the
+   * job for authoritative data.
+   *
+   * Optional `headers` (e.g. `{ Authorization: "Bearer …" }`) are sent with the
+   * POST, so the callback can hit an authed target directly — for example
+   * Cloudflare's Workflows events endpoint, with no receiver Worker.
+   *
+   * Set `verify: true` to opt into signing: the POST then carries an
+   * `X-Rendobar-Signature` (same HMAC scheme as webhooks). Fetch your org's
+   * callback signing secret once (`GET /orgs/current/callback-secret`) and verify
+   * with `verifyCallback(rawBody, headers, secret)` from `@rendobar/sdk/webhooks`.
+   *
+   * `events` opts into EXTRA non-terminal events. Terminal events
+   * (complete/failed/cancelled) always fire and can't be filtered out, so a
+   * `waitForEvent` can never hang. Today the only opt-in extra is `job.started`.
+   */
+  callback?: {
+    url: string;
+    headers?: Record<string, string>;
+    verify?: boolean;
+    events?: "job.started"[];
+  };
 };
 type ListJobsParams = {
   status?: string;

package/dist/index.mjs

@@ -175,7 +175,7 @@ function isAbortError(error) {
 }
 //#endregion
 //#region src/resources/jobs.ts
-const TERMINAL_STATUSES$1 = /* @__PURE__ */ new Set([
+const TERMINAL_JOB_STATUSES$1 = /* @__PURE__ */ new Set([
 	"complete",
 	"failed",
 	"cancelled"
@@ -189,7 +189,7 @@ function createJobsResource(request) {
 			if (signal?.aborted) throw new DOMException("Wait aborted", "AbortError");
 			const job = await request(`/jobs/${id}`, { signal });
 			onProgress?.(job);
-			if (TERMINAL_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
+			if (TERMINAL_JOB_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
 			const remaining = deadline - Date.now();
 			const delay = Math.min(currentInterval, remaining);
 			if (delay <= 0) break;
@@ -198,7 +198,7 @@ function createJobsResource(request) {
 		}
 		const job = await request(`/jobs/${id}`, { signal });
 		onProgress?.(job);
-		if (TERMINAL_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
+		if (TERMINAL_JOB_STATUSES$1.has(job.status)) return resolveTerminal(id, job, throwOnFailure);
 		throw new WaitTimeoutError(id, job.status, timeout);
 	}
 	async function create(params, options) {
@@ -761,7 +761,7 @@ const WS_OPTIONS = {
 	reconnectionDelayGrowFactor: 1.5,
 	maxRetries: Infinity
 };
-const TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+const TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set([
 	"complete",
 	"failed",
 	"cancelled"
@@ -774,8 +774,10 @@ const KNOWN_EVENT_TYPES = /* @__PURE__ */ new Set([
 	"job.progress",
 	"job.step",
 	"job.log",
+	"job.resources",
 	"job.metrics",
 	"job.context",
+	"job.region_failover",
 	"balance.updated",
 	"subscription.updated",
 	"notification",
@@ -858,15 +860,19 @@ function dispatchJobEvent(event, options) {
 		case "job.status": {
 			const statusEvent = event;
 			options.onStatus?.(statusEvent);
-			if (TERMINAL_STATUSES.has(statusEvent.status)) options.onComplete?.(statusEvent);
+			if (TERMINAL_JOB_STATUSES.has(statusEvent.status)) options.onComplete?.(statusEvent);
 			break;
 		}
 		case "job.result":
 			options.onResult?.(event);
 			break;
-		case "job.metrics":
-			options.onMetrics?.(event);
+		case "job.resources":
+		case "job.metrics": {
+			const e = event;
+			options.onResources?.(e);
+			options.onMetrics?.(e);
 			break;
+		}
 		case "job.context":
 			options.onContext?.(event);
 			break;

package/dist/webhooks.cjs

@@ -77,5 +77,6 @@ async function verifyWebhookSignature(payload, signature, secret) {
 	return mismatch === 0;
 }
 //#endregion
+exports.verifyCallback = verifyWebhook;
 exports.verifyWebhook = verifyWebhook;
 exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/webhooks.d.cts

@@ -40,4 +40,4 @@ declare function verifyWebhook(body: string, headers: WebhookHeaders, secret: st
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
 //#endregion
-export { type WebhookHeaders, verifyWebhook, verifyWebhookSignature };
+export { type WebhookHeaders, verifyWebhook as verifyCallback, verifyWebhook, verifyWebhookSignature };

package/dist/webhooks.d.mts

@@ -40,4 +40,4 @@ declare function verifyWebhook(body: string, headers: WebhookHeaders, secret: st
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
 //#endregion
-export { type WebhookHeaders, verifyWebhook, verifyWebhookSignature };
+export { type WebhookHeaders, verifyWebhook as verifyCallback, verifyWebhook, verifyWebhookSignature };

package/dist/webhooks.mjs

@@ -76,4 +76,4 @@ async function verifyWebhookSignature(payload, signature, secret) {
 	return mismatch === 0;
 }
 //#endregion
-export { verifyWebhook, verifyWebhookSignature };
+export { verifyWebhook as verifyCallback, verifyWebhook, verifyWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rendobar/sdk",
-  "version": "4.2.0",
+  "version": "5.1.0",
   "type": "module",
   "description": "TypeScript client for the Rendobar media processing API",
   "main": "./dist/index.cjs",
@@ -34,7 +34,8 @@
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:live": "vitest run src/__tests__/live"
   },
   "dependencies": {
     "partysocket": "^1.1.16"