@convertrilo/sdk 0.0.10 → 0.0.12

package/README.md

@@ -33,6 +33,8 @@ The `examples/` directory contains starter scripts for the main integration path
 - `node-url-to-s3.ts` - encode a public URL and upload the result to S3/S3-compatible storage
 - `google-drive-byo-token.ts` - upload output to Google Drive using customer OAuth tokens from your app
 - `folder-ingest-s3.ts` - queue one encode job per video in an S3 prefix
+- `idempotency.ts` - safely retry `createJob` and `createJobsBulk`
+- `webhook-receiver-hmac.ts` - verify managed webhook HMAC signatures from a Node receiver
 
 Local SDK smoke tests use `.env`, but published SDK users should provide credentials through their
 own server environment. Do not put Convertrilo API keys or customer storage tokens in frontend code.
@@ -41,6 +43,38 @@ For a complete server-to-server walkthrough covering URL, S3, folder ingest, Goo
 OAuth tokens, polling, and webhooks, see
 [`docs/API-INTEGRATION-GUIDE.md`](docs/API-INTEGRATION-GUIDE.md).
 
+## Idempotent Job Creation
+
+Use an idempotency key when retrying create calls from your backend. Reusing the same key with the
+same body returns the original response instead of creating duplicate jobs.
+
+```ts
+const job = await client.createJob({
+  externalId: "upload-123",
+  metadata: { customerId: "cus_123" },
+  codec: "h264",
+  resolution: "1080p",
+  fps: 30,
+}, {
+  idempotencyKey: "job-upload-123",
+});
+
+const batch = await client.createJobsBulk({
+  jobs: [
+    {
+      externalId: "batch-42:clip-1",
+      codec: "h264",
+      resolution: "1080p",
+      fps: 30,
+      sourceS3: { bucket: "source", key: "clip-1.mp4" },
+    },
+  ],
+  settings: { confirm: true },
+}, {
+  idempotencyKey: "bulk-batch-42",
+});
+```
+
 ## URL Source To CDN Output
 
 ```ts

package/dist/src/index.d.ts

@@ -35,8 +35,13 @@ export declare class ConvertriloClient {
     reserveTokens(body: paths["/tokens/reserve"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
     releaseTokens(body: paths["/tokens/release"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
     deductTokens(body: paths["/tokens/deduct"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
-    createJob(body: paths["/jobs"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+    createJob(body: paths["/jobs"]["post"]["requestBody"]["content"]["application/json"], options?: RequestOptions): Promise<{
         jobId: string;
+        externalId?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        } | null;
+        status?: string;
         upload: {
             url?: string;
             key?: string;
@@ -47,6 +52,8 @@ export declare class ConvertriloClient {
         };
         estimate?: {
             neu?: number;
+            totalNeu?: number;
+            reserved?: number;
         };
     }>;
     probeDuration(id: string): Promise<{
@@ -68,19 +75,40 @@ export declare class ConvertriloClient {
     cancelJob(id: string): Promise<unknown>;
     jobStatus(id: string): Promise<{
         id?: string;
+        externalId?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        } | null;
         status?: string;
+        ingest?: string | null;
+        output?: {
+            key?: string;
+            publicUrl?: string;
+        } | null;
         downloadUrl?: string | null;
         encoder?: string | null;
         pct?: number | null;
+        createdAt?: string;
+        startedAt?: string | null;
+        finishedAt?: string | null;
+        failureMessage?: string | null;
     }>;
-    createJobsBulk(body: paths["/jobs/bulk"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+    createJobsBulk(body: paths["/jobs/bulk"]["post"]["requestBody"]["content"]["application/json"], options?: RequestOptions): Promise<{
         totalJobs?: number;
         totalEstimatedNeu?: number;
+        reserved?: number;
         jobs?: {
             index?: number;
             jobId?: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status?: string;
             error?: string;
+            estimate?: {
+                neu?: number;
+            };
         }[];
     }>;
     bulkStatus(ids: string[]): Promise<{

package/dist/src/index.js

@@ -68,10 +68,13 @@ export class ConvertriloClient {
         });
     }
     // Jobs
-    async createJob(body) {
+    async createJob(body, options = {}) {
         return this.request(`/jobs`, {
             method: "POST",
             body: JSON.stringify(body),
+            headers: options.idempotencyKey
+                ? { "Idempotency-Key": options.idempotencyKey }
+                : undefined,
         });
     }
     async probeDuration(id) {
@@ -96,10 +99,13 @@ export class ConvertriloClient {
         return this.request(`/jobs/${id}/status`);
     }
     // Bulk Jobs
-    async createJobsBulk(body) {
+    async createJobsBulk(body, options = {}) {
         return this.request(`/jobs/bulk`, {
             method: "POST",
             body: JSON.stringify(body),
+            headers: options.idempotencyKey
+                ? { "Idempotency-Key": options.idempotencyKey }
+                : undefined,
         });
     }
     async bulkStatus(ids) {

package/dist/src/types.d.ts

@@ -204,12 +204,15 @@ export interface paths {
         put?: never;
         /**
          * Create a new encode job
-         * @description Create a job for upload ingest (returns a presigned PUT) or direct URL/S3 ingest.
+         * @description Create a job for upload ingest (returns a presigned PUT) or direct URL/S3 ingest. Send `Idempotency-Key` when retrying from your backend to avoid duplicate jobs.
          */
         post: {
             parameters: {
                 query?: never;
-                header?: never;
+                header?: {
+                    /** @description Optional key for safely retrying job creation requests. Reusing the same key with the same request body replays the original response; reusing it with a different body returns 409. */
+                    "Idempotency-Key"?: components["parameters"]["IdempotencyKey"];
+                };
                 path?: never;
                 cookie?: never;
             };
@@ -773,11 +776,17 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Bulk create jobs */
+        /**
+         * Bulk create jobs
+         * @description Send `Idempotency-Key` when retrying from your backend to avoid duplicate bulk batches, duplicate token reservations, or duplicate queue entries.
+         */
         post: {
             parameters: {
                 query?: never;
-                header?: never;
+                header?: {
+                    /** @description Optional key for safely retrying job creation requests. Reusing the same key with the same request body replays the original response; reusing it with a different body returns 409. */
+                    "Idempotency-Key"?: components["parameters"]["IdempotencyKey"];
+                };
                 path?: never;
                 cookie?: never;
             };
@@ -1505,6 +1514,12 @@ export interface components {
             amount: number;
         };
         JobCreateRequest: {
+            /** @description Your stable job identifier for reconciliation in status responses and webhooks. */
+            externalId?: string;
+            /** @description Integration-owned JSON object returned in status responses and webhooks. */
+            metadata?: {
+                [key: string]: unknown;
+            };
             /** @enum {string} */
             codec: "h264" | "h265" | "av1";
             /** @enum {string} */
@@ -1559,6 +1574,12 @@ export interface components {
         };
         JobCreateResponse: {
             jobId: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
+            /** @description Present when the job is auto-confirmed and queued. */
+            status?: string;
             upload: {
                 url?: string;
                 key?: string;
@@ -1569,6 +1590,8 @@ export interface components {
             };
             estimate?: {
                 neu?: number;
+                totalNeu?: number;
+                reserved?: number;
             };
         };
         ProbeDurationResponse: {
@@ -1619,13 +1642,39 @@ export interface components {
         };
         StatusResponse: {
             id?: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status?: string;
+            ingest?: string | null;
+            output?: {
+                key?: string;
+                publicUrl?: string;
+            } | null;
             downloadUrl?: string | null;
             encoder?: string | null;
             pct?: number | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            startedAt?: string | null;
+            /** Format: date-time */
+            finishedAt?: string | null;
+            failureMessage?: string | null;
         };
         ErrorResponse: {
-            message?: string;
+            /**
+             * @description Stable machine-readable error code. Branch on this instead of parsing `message`.
+             * @enum {string}
+             */
+            code: "invalid_api_key" | "api_key_expired" | "user_not_found" | "account_banned" | "missing_required_scope" | "invalid_request" | "invalid_body" | "invalid_url" | "url_ingest_disabled" | "url_host_blocked" | "signed_url_required" | "host_not_resolvable" | "private_ip_blocked" | "missing_content_length" | "file_too_large" | "unsupported_content_type" | "probe_failed" | "insufficient_tokens" | "idempotency_conflict" | "idempotency_in_progress" | "not_found" | "forbidden" | "deprecated_dropbox" | "google_drive_not_connected" | "dropbox_not_connected" | "no_video_files_found" | "webhook_limit_exceeded" | "webhook_not_found" | "no_updates_provided" | "output_not_available";
+            message: string;
+            /** @description Validation details for `invalid_body`. */
+            issues?: unknown;
+            requiredScope?: string;
+            required?: number;
+            available?: number;
         };
         BulkCreateRequest: {
             jobs: components["schemas"]["JobCreateRequest"][];
@@ -1648,12 +1697,20 @@ export interface components {
         BulkCreateResponse: {
             totalJobs?: number;
             totalEstimatedNeu?: number;
+            reserved?: number;
             jobs?: {
                 index?: number;
                 /** Format: uuid */
                 jobId?: string;
+                externalId?: string | null;
+                metadata?: {
+                    [key: string]: unknown;
+                } | null;
                 status?: string;
                 error?: string;
+                estimate?: {
+                    neu?: number;
+                };
             }[];
         };
         BulkStatusResponse: {

package/docs/API-INTEGRATION-GUIDE.md

@@ -46,6 +46,43 @@ const client = new ConvertriloClient({
 
 SDK source and examples: https://github.com/serkandrgn/convertrilo-js
 
+## Idempotency
+
+When your backend retries `POST /jobs`, `POST /jobs/bulk`, `POST /ondemand/encode`, or
+`POST /ondemand/ingest/folder`, send an idempotency key. The API replays the original response for
+the same key and body, and returns `409` if the key is reused with a different body.
+
+```ts
+const job = await client.createJob({
+  externalId: "upload-123",
+  metadata: { customerId: "cus_123" },
+  codec: "h264",
+  resolution: "1080p",
+  fps: 30,
+}, {
+  idempotencyKey: "job-upload-123",
+});
+
+const batch = await client.createJobsBulk({
+  jobs: [
+    {
+      externalId: "batch-42:clip-1",
+      codec: "h264",
+      resolution: "1080p",
+      fps: 30,
+      sourceS3: { bucket: "source", key: "clip-1.mp4" },
+    },
+  ],
+  settings: { confirm: true },
+}, {
+  idempotencyKey: "bulk-batch-42",
+});
+```
+
+API errors include a stable `code` field plus a human-readable `message`. Branch on
+`code` in your backend, for example `idempotency_conflict`, `insufficient_tokens`,
+or `missing_required_scope`.
+
 ## Flow 1: URL Source To CDN Output
 
 Use this when the source video is already available over HTTP(S), and you want Convertrilo to return a signed CDN download URL.

package/examples/idempotency.ts

@@ -0,0 +1,60 @@
+import { ConvertriloClient } from "@convertrilo/sdk";
+
+const apiKey = process.env.CONVERTRILO_API_KEY;
+if (!apiKey) throw new Error("Set CONVERTRILO_API_KEY");
+
+const client = new ConvertriloClient({
+  baseUrl: process.env.CONVERTRILO_API_URL || "https://api.convertrilo.com",
+  apiKey,
+});
+
+async function main() {
+  const externalId = `example-upload-${Date.now()}`;
+
+  const job = await client.createJob(
+    {
+      externalId,
+      metadata: {
+        customerId: "cus_123",
+        workflow: "sdk-idempotency-example",
+      },
+      codec: "h264",
+      resolution: "1080p",
+      fps: 30,
+    },
+    {
+      idempotencyKey: `job-${externalId}`,
+    },
+  );
+
+  console.log(`Created or replayed job ${job.jobId}`);
+
+  const batch = await client.createJobsBulk(
+    {
+      jobs: [
+        {
+          externalId: `${externalId}:clip-1`,
+          metadata: { customerId: "cus_123" },
+          codec: "h264",
+          resolution: "1080p",
+          fps: 30,
+          sourceS3: {
+            bucket: "customer-source-bucket",
+            key: "incoming/clip-1.mp4",
+          },
+        },
+      ],
+      settings: { dryRun: true },
+    },
+    {
+      idempotencyKey: `bulk-${externalId}`,
+    },
+  );
+
+  console.log(`Created or replayed bulk response with ${batch.totalJobs} job(s)`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/webhook-receiver-hmac.ts

@@ -0,0 +1,54 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+
+const secret = process.env.CONVERTRILO_WEBHOOK_SECRET;
+if (!secret) throw new Error("Set CONVERTRILO_WEBHOOK_SECRET");
+
+function verifySignature(rawBody: Buffer, signature: string) {
+  const expected = createHmac("sha256", secret!).update(rawBody).digest("hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+  const signatureBuffer = Buffer.from(signature, "hex");
+
+  return (
+    expectedBuffer.length === signatureBuffer.length &&
+    timingSafeEqual(expectedBuffer, signatureBuffer)
+  );
+}
+
+const server = http.createServer((request, response) => {
+  if (request.method !== "POST" || request.url !== "/webhooks/convertrilo") {
+    response.writeHead(404);
+    response.end("Not found");
+    return;
+  }
+
+  const chunks: Buffer[] = [];
+
+  request.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+  request.on("end", () => {
+    const rawBody = Buffer.concat(chunks);
+    const signature = String(request.headers["x-webhook-signature"] || "");
+
+    if (!signature || !verifySignature(rawBody, signature)) {
+      response.writeHead(401);
+      response.end("Invalid signature");
+      return;
+    }
+
+    const payload = JSON.parse(rawBody.toString("utf8"));
+    console.log("Verified Convertrilo webhook", {
+      event: payload.event,
+      jobId: payload.data?.jobId,
+      status: payload.data?.status,
+      externalId: payload.data?.externalId,
+    });
+
+    response.writeHead(204);
+    response.end();
+  });
+});
+
+const port = Number(process.env.PORT || 3000);
+server.listen(port, () => {
+  console.log(`Webhook receiver listening on http://localhost:${port}/webhooks/convertrilo`);
+});

package/openapi.yaml

@@ -81,6 +81,14 @@ components:
       type: object
       required: [codec, resolution, fps]
       properties:
+        externalId:
+          type: string
+          maxLength: 255
+          description: Your stable job identifier for reconciliation in status responses and webhooks.
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Integration-owned JSON object returned in status responses and webhooks.
         codec:
           type: string
           enum: [h264, h265, av1]
@@ -136,6 +144,14 @@ components:
       required: [jobId, upload, output]
       properties:
         jobId: { type: string }
+        externalId: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
+        status:
+          type: string
+          description: Present when the job is auto-confirmed and queued.
         upload:
           nullable: true
           type: object
@@ -151,6 +167,8 @@ components:
           type: object
           properties:
             neu: { type: number }
+            totalNeu: { type: number }
+            reserved: { type: number }
     ProbeDurationResponse:
       type: object
       properties:
@@ -196,14 +214,70 @@ components:
       type: object
       properties:
         id: { type: string }
+        externalId: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
         status: { type: string }
+        ingest: { type: string, nullable: true }
+        output:
+          nullable: true
+          type: object
+          properties:
+            key: { type: string }
+            publicUrl: { type: string }
         downloadUrl: { type: string, nullable: true }
         encoder: { type: string, nullable: true }
         pct: { type: number, nullable: true }
+        createdAt: { type: string, format: date-time }
+        startedAt: { type: string, format: date-time, nullable: true }
+        finishedAt: { type: string, format: date-time, nullable: true }
+        failureMessage: { type: string, nullable: true }
     ErrorResponse:
       type: object
+      required: [code, message]
       properties:
+        code:
+          type: string
+          description: Stable machine-readable error code. Branch on this instead of parsing `message`.
+          enum:
+            - invalid_api_key
+            - api_key_expired
+            - user_not_found
+            - account_banned
+            - missing_required_scope
+            - invalid_request
+            - invalid_body
+            - invalid_url
+            - url_ingest_disabled
+            - url_host_blocked
+            - signed_url_required
+            - host_not_resolvable
+            - private_ip_blocked
+            - missing_content_length
+            - file_too_large
+            - unsupported_content_type
+            - probe_failed
+            - insufficient_tokens
+            - idempotency_conflict
+            - idempotency_in_progress
+            - not_found
+            - forbidden
+            - deprecated_dropbox
+            - google_drive_not_connected
+            - dropbox_not_connected
+            - no_video_files_found
+            - webhook_limit_exceeded
+            - webhook_not_found
+            - no_updates_provided
+            - output_not_available
         message: { type: string }
+        issues:
+          description: Validation details for `invalid_body`.
+        requiredScope: { type: string }
+        required: { type: number }
+        available: { type: number }
 
     # Bulk Jobs
     BulkCreateRequest:
@@ -230,6 +304,7 @@ components:
       properties:
         totalJobs: { type: integer }
         totalEstimatedNeu: { type: number }
+        reserved: { type: number }
         jobs:
           type: array
           items:
@@ -237,8 +312,17 @@ components:
             properties:
               index: { type: integer }
               jobId: { type: string, format: uuid }
+              externalId: { type: string, nullable: true }
+              metadata:
+                type: object
+                additionalProperties: true
+                nullable: true
               status: { type: string }
               error: { type: string }
+              estimate:
+                type: object
+                properties:
+                  neu: { type: number }
     BulkStatusResponse:
       type: object
       properties:
@@ -714,7 +798,9 @@ paths:
     post:
       security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Create a new encode job
-      description: Create a job for upload ingest (returns a presigned PUT) or direct URL/S3 ingest.
+      description: Create a job for upload ingest (returns a presigned PUT) or direct URL/S3 ingest. Send `Idempotency-Key` when retrying from your backend to avoid duplicate jobs.
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
       requestBody:
         required: true
         content:
@@ -993,6 +1079,9 @@ paths:
     post:
       security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Bulk create jobs
+      description: Send `Idempotency-Key` when retrying from your backend to avoid duplicate bulk batches, duplicate token reservations, or duplicate queue entries.
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
       requestBody:
         required: true
         content:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convertrilo/sdk",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",