@convertrilo/sdk 0.0.9 → 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
@@ -54,6 +86,8 @@ const job = await client.onDemandEncode({
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 let finalStatus;
@@ -144,6 +178,8 @@ const batch = await client.onDemandIngestFolder({
   },
   codec: "h264",
   resolution: "1080p",
+}, {
+  idempotencyKey: "folder-batch-2026-06-09",
 });
 
 for (const job of batch.jobs || []) {

package/dist/src/index.d.ts

@@ -15,6 +15,9 @@ export type ClientConfig = {
     apiKey?: string;
     fetchImpl?: typeof fetch;
 };
+export type RequestOptions = {
+    idempotencyKey?: string;
+};
 export declare class ConvertriloClient {
     private baseUrl;
     private getToken?;
@@ -32,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;
@@ -44,6 +52,8 @@ export declare class ConvertriloClient {
         };
         estimate?: {
             neu?: number;
+            totalNeu?: number;
+            reserved?: number;
         };
     }>;
     probeDuration(id: string): Promise<{
@@ -70,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<{
@@ -143,7 +161,7 @@ export declare class ConvertriloClient {
         };
     } ? B : any): Promise<unknown>;
     abortStream(id: string): Promise<unknown>;
-    onDemandEncode(body: paths["/ondemand/encode"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+    onDemandEncode(body: paths["/ondemand/encode"]["post"]["requestBody"]["content"]["application/json"], options?: RequestOptions): Promise<{
         jobId: string;
         externalId?: string | null;
         metadata?: {
@@ -161,7 +179,7 @@ export declare class ConvertriloClient {
         statusUrl: string;
         webhook?: string | null;
     }>;
-    onDemandIngestFolder(body: paths["/ondemand/ingest/folder"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+    onDemandIngestFolder(body: paths["/ondemand/ingest/folder"]["post"]["requestBody"]["content"]["application/json"], options?: RequestOptions): Promise<{
         message?: string;
         jobs?: {
             jobId?: string;

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) {
@@ -170,16 +176,22 @@ export class ConvertriloClient {
         return this.request(`/jobs/${id}/stream/abort`, { method: "POST" });
     }
     // On-Demand Encoding
-    async onDemandEncode(body) {
+    async onDemandEncode(body, options = {}) {
         return this.request(`/ondemand/encode`, {
             method: "POST",
             body: JSON.stringify(body),
+            headers: options.idempotencyKey
+                ? { "Idempotency-Key": options.idempotencyKey }
+                : undefined,
         });
     }
-    async onDemandIngestFolder(body) {
+    async onDemandIngestFolder(body, options = {}) {
         return this.request(`/ondemand/ingest/folder`, {
             method: "POST",
             body: JSON.stringify(body),
+            headers: options.idempotencyKey
+                ? { "Idempotency-Key": options.idempotencyKey }
+                : undefined,
         });
     }
     async onDemandStatus(jobId) {

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;
             };
@@ -1224,11 +1233,15 @@ export interface paths {
          * Submit video for immediate on-demand encoding
          * @description Simplified API for immediate video encoding. Automatically probes, reserves tokens,
          *     and starts encoding. Premium pricing (1.5x-2x) for on-demand convenience.
+         *     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;
             };
@@ -1311,11 +1324,15 @@ export interface paths {
          *     - Include `refreshToken` when jobs may outlive a short access token.
          *
          *     Your users do not need to connect Google Drive inside the Convertrilo dashboard for API usage.
+         *     Send `Idempotency-Key` when retrying from your backend to avoid duplicate folder batches.
          */
         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;
             };
@@ -1497,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} */
@@ -1551,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;
@@ -1561,6 +1590,8 @@ export interface components {
             };
             estimate?: {
                 neu?: number;
+                totalNeu?: number;
+                reserved?: number;
             };
         };
         ProbeDurationResponse: {
@@ -1640,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: {
@@ -2025,7 +2064,10 @@ export interface components {
         };
     };
     responses: never;
-    parameters: never;
+    parameters: {
+        /** @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. */
+        IdempotencyKey: string;
+    };
     requestBodies: never;
     headers: never;
     pathItems: never;

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.
@@ -61,6 +94,8 @@ const job = await client.onDemandEncode({
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 console.log(job.jobId);
@@ -72,6 +107,7 @@ Equivalent curl:
 curl https://api.convertrilo.com/ondemand/encode \
   -H "Content-Type: application/json" \
   -H "X-API-Key: $CONVERTRILO_API_KEY" \
+  -H "Idempotency-Key: encode-customer-video-123" \
   -d '{
     "sourceUrl": "https://example.com/input.mp4",
     "externalId": "customer-video-123",
@@ -89,6 +125,8 @@ Poll `/ondemand/status/{jobId}` until the job reaches `success`, then read `down
 
 Use `externalId` and `metadata` to reconcile Convertrilo jobs with your own database. They are returned by status responses and managed webhook payloads.
 
+Use `Idempotency-Key` on creation requests that your backend may retry. If the same key and request body are received again, Convertrilo returns the original response instead of queuing another job. If the same key is reused with a different body, the API returns `409`.
+
 ## Flow 2: URL Source To S3 Output
 
 Use this when your customer wants the encoded output in their own S3-compatible bucket.
@@ -148,6 +186,8 @@ const batch = await client.onDemandIngestFolder({
   },
   codec: "h264",
   resolution: "1080p",
+}, {
+  idempotencyKey: "folder-batch-2026-06-09",
 });
 
 for (const job of batch.jobs || []) {

package/openapi.yaml

@@ -37,6 +37,15 @@ components:
       type: apiKey
       in: header
       name: X-API-Key
+  parameters:
+    IdempotencyKey:
+      in: header
+      name: Idempotency-Key
+      required: false
+      schema:
+        type: string
+        maxLength: 255
+      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.
   schemas:
     AuthLoginRequest:
       type: object
@@ -72,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]
@@ -127,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
@@ -142,6 +167,8 @@ components:
           type: object
           properties:
             neu: { type: number }
+            totalNeu: { type: number }
+            reserved: { type: number }
     ProbeDurationResponse:
       type: object
       properties:
@@ -221,6 +248,7 @@ components:
       properties:
         totalJobs: { type: integer }
         totalEstimatedNeu: { type: number }
+        reserved: { type: number }
         jobs:
           type: array
           items:
@@ -228,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:
@@ -705,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:
@@ -984,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:
@@ -1189,6 +1231,9 @@ paths:
       description: |
         Simplified API for immediate video encoding. Automatically probes, reserves tokens, 
         and starts encoding. Premium pricing (1.5x-2x) for on-demand convenience.
+        Send `Idempotency-Key` when retrying from your backend to avoid duplicate jobs.
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
       requestBody:
         required: true
         content:
@@ -1275,6 +1320,9 @@ paths:
         - Include `refreshToken` when jobs may outlive a short access token.
 
         Your users do not need to connect Google Drive inside the Convertrilo dashboard for API usage.
+        Send `Idempotency-Key` when retrying from your backend to avoid duplicate folder batches.
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
       requestBody:
         required: true
         content:

package/package.json

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