@convertrilo/sdk 0.0.8 → 0.0.10

package/README.md

@@ -46,9 +46,16 @@ OAuth tokens, polling, and webhooks, see
 ```ts
 const job = await client.onDemandEncode({
   sourceUrl: "https://example.com/input.mp4",
+  externalId: "customer-video-123",
+  metadata: {
+    customerId: "cus_123",
+    workflow: "daily-compression",
+  },
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 let finalStatus;
@@ -117,6 +124,11 @@ Queue one job per video in an S3 prefix:
 
 ```ts
 const batch = await client.onDemandIngestFolder({
+  externalIdPrefix: "batch-2026-06-09",
+  metadata: {
+    customerId: "cus_123",
+    workflow: "folder-compression",
+  },
   sourceS3: {
     bucket: "customer-source-bucket",
     prefix: "incoming/",
@@ -134,10 +146,12 @@ const batch = await client.onDemandIngestFolder({
   },
   codec: "h264",
   resolution: "1080p",
+}, {
+  idempotencyKey: "folder-batch-2026-06-09",
 });
 
 for (const job of batch.jobs || []) {
-  console.log(job.jobId, job.fileName);
+  console.log(job.jobId, job.externalId, job.fileName);
 }
 ```
 

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,8 +146,12 @@ 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?: {
+            [key: string]: unknown;
+        } | null;
         status: string;
         estimatedDuration?: number;
         pricing?: {
@@ -157,15 +164,20 @@ 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;
+            externalId?: string | null;
             fileName?: string;
         }[];
     }>;
     onDemandStatus(jobId: string): Promise<{
         jobId?: string;
+        externalId?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        } | null;
         status?: string;
         progress?: number | null;
         encoder?: string | null;

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;
             };
@@ -1812,6 +1820,12 @@ export interface components {
         OnDemandEncodeRequest: {
             /** Format: uri */
             sourceUrl: string;
+            /** @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;
+            };
             /**
              * @default h264
              * @enum {string}
@@ -1870,6 +1884,10 @@ export interface components {
         OnDemandEncodeResponse: {
             /** Format: uuid */
             jobId: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status: string;
             estimatedDuration?: number;
             pricing?: {
@@ -1885,6 +1903,10 @@ export interface components {
         OnDemandStatusResponse: {
             /** Format: uuid */
             jobId?: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status?: string;
             progress?: number | null;
             encoder?: string | null;
@@ -1913,6 +1935,12 @@ export interface components {
             failureMessage?: string | null;
         };
         OnDemandFolderIngestRequest: {
+            /** @description Optional prefix used to generate one externalId per queued file as `${externalIdPrefix}:${fileName}`. */
+            externalIdPrefix?: string;
+            /** @description Integration-owned JSON object attached to every queued job and returned in webhooks/status responses. */
+            metadata?: {
+                [key: string]: unknown;
+            };
             /**
              * @default h264
              * @enum {string}
@@ -1988,6 +2016,7 @@ export interface components {
             jobs?: {
                 /** Format: uuid */
                 jobId?: string;
+                externalId?: string | null;
                 fileName?: string;
             }[];
         };
@@ -2004,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

@@ -53,9 +53,16 @@ Use this when the source video is already available over HTTP(S), and you want C
 ```ts
 const job = await client.onDemandEncode({
   sourceUrl: "https://example.com/input.mp4",
+  externalId: "customer-video-123",
+  metadata: {
+    customerId: "cus_123",
+    workflow: "daily-compression",
+  },
   codec: "h264",
   resolution: "1080p",
   quality: "better",
+}, {
+  idempotencyKey: "encode-customer-video-123",
 });
 
 console.log(job.jobId);
@@ -67,8 +74,14 @@ 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",
+    "metadata": {
+      "customerId": "cus_123",
+      "workflow": "daily-compression"
+    },
     "codec": "h264",
     "resolution": "1080p",
     "quality": "better"
@@ -77,6 +90,10 @@ curl https://api.convertrilo.com/ondemand/encode \
 
 Poll `/ondemand/status/{jobId}` until the job reaches `success`, then read `downloadUrl`.
 
+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.
@@ -110,6 +127,11 @@ Source credentials need permission to list the prefix and read objects. Output c
 
 ```ts
 const batch = await client.onDemandIngestFolder({
+  externalIdPrefix: "batch-2026-06-09",
+  metadata: {
+    customerId: "cus_123",
+    workflow: "folder-compression",
+  },
   sourceS3: {
     bucket: "customer-source-bucket",
     prefix: "incoming/",
@@ -131,13 +153,17 @@ const batch = await client.onDemandIngestFolder({
   },
   codec: "h264",
   resolution: "1080p",
+}, {
+  idempotencyKey: "folder-batch-2026-06-09",
 });
 
 for (const job of batch.jobs || []) {
-  console.log(job.jobId, job.fileName);
+  console.log(job.jobId, job.externalId, job.fileName);
 }
 ```
 
+For folder ingest, Convertrilo generates each job `externalId` as `${externalIdPrefix}:${fileName}`.
+
 Only files with video extensions are queued. If no video files are found, the API returns `404`.
 
 ## Flow 4: Google Drive With BYO OAuth Tokens

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
@@ -457,6 +466,14 @@ components:
       required: [sourceUrl]
       properties:
         sourceUrl: { type: string, format: uri }
+        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], default: h264 }
         resolution:
           {
@@ -493,6 +510,11 @@ components:
       required: [jobId, status, statusUrl]
       properties:
         jobId: { type: string, format: uuid }
+        externalId: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
         status: { type: string }
         estimatedDuration: { type: integer }
         pricing:
@@ -509,6 +531,11 @@ components:
       type: object
       properties:
         jobId: { type: string, format: uuid }
+        externalId: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
         status: { type: string }
         progress: { type: number, nullable: true }
         encoder: { type: string, nullable: true }
@@ -537,6 +564,14 @@ components:
     OnDemandFolderIngestRequest:
       type: object
       properties:
+        externalIdPrefix:
+          type: string
+          maxLength: 200
+          description: Optional prefix used to generate one externalId per queued file as `${externalIdPrefix}:${fileName}`.
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Integration-owned JSON object attached to every queued job and returned in webhooks/status responses.
         codec: { type: string, enum: [h264, h265, av1], default: h264 }
         resolution:
           {
@@ -589,6 +624,7 @@ components:
             type: object
             properties:
               jobId: { type: string, format: uuid }
+              externalId: { type: string, nullable: true }
               fileName: { type: string }
 
     # Streaming
@@ -1162,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:
@@ -1173,6 +1212,10 @@ paths:
                 summary: URL source to CDN output
                 value:
                   sourceUrl: https://example.com/video.mp4
+                  externalId: customer-video-123
+                  metadata:
+                    customerId: cus_123
+                    workflow: daily-compression
                   codec: h264
                   resolution: 1080p
                   quality: better
@@ -1244,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:
@@ -1254,6 +1300,10 @@ paths:
               s3FolderToS3:
                 summary: S3 folder source to S3 output
                 value:
+                  externalIdPrefix: batch-2026-06-09
+                  metadata:
+                    customerId: cus_123
+                    workflow: folder-compression
                   sourceS3:
                     bucket: customer-source-bucket
                     prefix: incoming/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convertrilo/sdk",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",
@@ -44,6 +44,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "clean": "rimraf dist",
+    "generate": "openapi-typescript openapi.yaml -o src/types.ts --default-non-nullable false",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "pnpm run clean && pnpm run generate && pnpm run build"
+  },
   "dependencies": {},
   "devDependencies": {
     "@types/node": "^20.11.30",
@@ -52,10 +58,5 @@
     "rimraf": "^5.0.5",
     "tsx": "^4.7.0",
     "typescript": "^5.4.0"
-  },
-  "scripts": {
-    "clean": "rimraf dist",
-    "generate": "openapi-typescript openapi.yaml -o src/types.ts --default-non-nullable false",
-    "build": "tsc -p tsconfig.json"
   }
-}
+}