@convertrilo/sdk 0.0.8 → 0.0.9

package/README.md

@@ -46,6 +46,11 @@ 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",
@@ -117,6 +122,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/",
@@ -137,7 +147,7 @@ const batch = await client.onDemandIngestFolder({
 });
 
 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

@@ -145,6 +145,10 @@ export declare class ConvertriloClient {
     abortStream(id: string): Promise<unknown>;
     onDemandEncode(body: paths["/ondemand/encode"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
         jobId: string;
+        externalId?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        } | null;
         status: string;
         estimatedDuration?: number;
         pricing?: {
@@ -161,11 +165,16 @@ export declare class ConvertriloClient {
         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/types.d.ts

@@ -1812,6 +1812,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 +1876,10 @@ export interface components {
         OnDemandEncodeResponse: {
             /** Format: uuid */
             jobId: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status: string;
             estimatedDuration?: number;
             pricing?: {
@@ -1885,6 +1895,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 +1927,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 +2008,7 @@ export interface components {
             jobs?: {
                 /** Format: uuid */
                 jobId?: string;
+                externalId?: string | null;
                 fileName?: string;
             }[];
         };

package/docs/API-INTEGRATION-GUIDE.md

@@ -53,6 +53,11 @@ 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",
@@ -69,6 +74,11 @@ curl https://api.convertrilo.com/ondemand/encode \
   -H "X-API-Key: $CONVERTRILO_API_KEY" \
   -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 +87,8 @@ 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.
+
 ## Flow 2: URL Source To S3 Output
 
 Use this when your customer wants the encoded output in their own S3-compatible bucket.
@@ -110,6 +122,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/",
@@ -134,10 +151,12 @@ const batch = await client.onDemandIngestFolder({
 });
 
 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

@@ -457,6 +457,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 +501,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 +522,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 +555,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 +615,7 @@ components:
             type: object
             properties:
               jobId: { type: string, format: uuid }
+              externalId: { type: string, nullable: true }
               fileName: { type: string }
 
     # Streaming
@@ -1173,6 +1200,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
@@ -1254,6 +1285,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.9",
   "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"
   }
-}
+}