@rendobar/sdk 5.0.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.d.cts

@@ -2301,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;
@@ -2346,6 +2353,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<"dispatched">;
   progress: ZodOptional<ZodNullable<ZodNumber>>;
   eta: ZodOptional<ZodNullable<ZodNumber>>;
@@ -2393,6 +2407,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<"running">;
   progress: ZodNullable<ZodNumber>;
   eta: ZodNullable<ZodNumber>;
@@ -2440,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;
@@ -2529,6 +2557,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<"failed">;
   error: ZodObject<{
     code: ZodString;
@@ -2585,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<{
@@ -2722,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>;
@@ -3643,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

@@ -2301,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;
@@ -2346,6 +2353,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<"dispatched">;
   progress: ZodOptional<ZodNullable<ZodNumber>>;
   eta: ZodOptional<ZodNullable<ZodNumber>>;
@@ -2393,6 +2407,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<"running">;
   progress: ZodNullable<ZodNumber>;
   eta: ZodNullable<ZodNumber>;
@@ -2440,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;
@@ -2529,6 +2557,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<"failed">;
   error: ZodObject<{
     code: ZodString;
@@ -2585,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<{
@@ -2722,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>;
@@ -3643,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/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": "5.0.0",
+  "version": "5.1.0",
   "type": "module",
   "description": "TypeScript client for the Rendobar media processing API",
   "main": "./dist/index.cjs",