@convertrilo/sdk 0.0.7 → 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

@@ -564,7 +564,7 @@ export interface paths {
         };
         /**
          * List webhooks
-         * @description List managed webhook subscriptions for the authenticated user. Managed webhook deliveries include HMAC-SHA256 signatures.
+         * @description List managed webhook subscriptions for the authenticated user. API keys need the `webhooks:manage` scope. Managed webhook deliveries include HMAC-SHA256 signatures.
          */
         get: {
             parameters: {
@@ -591,6 +591,7 @@ export interface paths {
          * Create a webhook
          * @description Create a managed webhook subscription. The response includes `secret` exactly once.
          *     Store it securely and use it to verify `X-Webhook-Signature`.
+         *     API keys need the `webhooks:manage` scope.
          */
         post: {
             parameters: {
@@ -633,7 +634,7 @@ export interface paths {
         put?: never;
         /**
          * Test a webhook
-         * @description Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries.
+         * @description Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries. API keys need the `webhooks:manage` scope.
          */
         post: {
             parameters: {
@@ -655,7 +656,10 @@ export interface paths {
                 };
             };
         };
-        /** Delete a webhook */
+        /**
+         * Delete a webhook
+         * @description API keys need the `webhooks:manage` scope.
+         */
         delete: {
             parameters: {
                 query?: never;
@@ -678,7 +682,10 @@ export interface paths {
         };
         options?: never;
         head?: never;
-        /** Update a webhook */
+        /**
+         * Update a webhook
+         * @description API keys need the `webhooks:manage` scope.
+         */
         patch: {
             parameters: {
                 query?: never;
@@ -716,7 +723,7 @@ export interface paths {
         };
         /**
          * List webhook delivery attempts
-         * @description Returns the 50 most recent managed or test delivery attempts for this webhook.
+         * @description Returns the 50 most recent managed or test delivery attempts for this webhook. API keys need the `webhooks:manage` scope.
          */
         get: {
             parameters: {
@@ -1805,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}
@@ -1863,6 +1876,10 @@ export interface components {
         OnDemandEncodeResponse: {
             /** Format: uuid */
             jobId: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status: string;
             estimatedDuration?: number;
             pricing?: {
@@ -1878,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;
@@ -1906,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}
@@ -1981,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
@@ -839,9 +866,9 @@ paths:
 
   /webhooks:
     get:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: List webhooks
-      description: List managed webhook subscriptions for the authenticated user. Managed webhook deliveries include HMAC-SHA256 signatures.
+      description: List managed webhook subscriptions for the authenticated user. API keys need the `webhooks:manage` scope. Managed webhook deliveries include HMAC-SHA256 signatures.
       responses:
         "200":
           description: List of webhooks
@@ -850,11 +877,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/WebhookListResponse"
     post:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Create a webhook
       description: |
         Create a managed webhook subscription. The response includes `secret` exactly once.
         Store it securely and use it to verify `X-Webhook-Signature`.
+        API keys need the `webhooks:manage` scope.
       requestBody:
         required: true
         content:
@@ -876,8 +904,9 @@ paths:
                 $ref: "#/components/schemas/WebhookResponse"
   /webhooks/{id}:
     patch:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Update a webhook
+      description: API keys need the `webhooks:manage` scope.
       parameters:
         - in: path
           name: id
@@ -906,8 +935,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/WebhookResponse"
     delete:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Delete a webhook
+      description: API keys need the `webhooks:manage` scope.
       parameters:
         - in: path
           name: id
@@ -916,9 +946,9 @@ paths:
       responses:
         "204": { description: Deleted }
     post:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: Test a webhook
-      description: Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries.
+      description: Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries. API keys need the `webhooks:manage` scope.
       parameters:
         - in: path
           name: id
@@ -928,9 +958,9 @@ paths:
         "200": { description: Test event sent }
   /webhooks/{id}/deliveries:
     get:
-      security: [{ BearerAuth: [] }]
+      security: [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
       summary: List webhook delivery attempts
-      description: Returns the 50 most recent managed or test delivery attempts for this webhook.
+      description: Returns the 50 most recent managed or test delivery attempts for this webhook. API keys need the `webhooks:manage` scope.
       parameters:
         - in: path
           name: id
@@ -1170,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
@@ -1251,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.7",
+  "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"
   }
-}
+}