@convertrilo/sdk 0.0.10 → 0.0.11

package/README.md

@@ -41,6 +41,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<{
@@ -73,14 +80,22 @@ export declare class ConvertriloClient {
         encoder?: string | null;
         pct?: number | 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: {
@@ -1648,12 +1671,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,39 @@ 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",
+});
+```
+
 ## 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/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:
@@ -230,6 +248,7 @@ components:
       properties:
         totalJobs: { type: integer }
         totalEstimatedNeu: { type: number }
+        reserved: { type: number }
         jobs:
           type: array
           items:
@@ -237,8 +256,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 +742,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 +1023,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.11",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",