@convertrilo/sdk 0.0.9 → 0.0.10

package/README.md

@@ -54,6 +54,8 @@ const job = await client.onDemandEncode({
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 let finalStatus;
@@ -144,6 +146,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?;
@@ -143,7 +146,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 +164,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

@@ -170,16 +170,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

@@ -1224,11 +1224,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 +1315,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;
             };
@@ -2025,7 +2033,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

@@ -61,6 +61,8 @@ const job = await client.onDemandEncode({
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 console.log(job.jobId);
@@ -72,6 +74,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 +92,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 +153,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
@@ -1189,6 +1198,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 +1287,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.10",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",