@convertrilo/sdk 0.0.3 → 0.0.4

package/dist/src/index.d.ts

@@ -110,6 +110,9 @@ export declare class ConvertriloClient {
         events?: string[];
         secret?: string;
         isActive?: boolean;
+        failureCount?: number;
+        lastTriggeredAt?: string | null;
+        lastFailedAt?: string | null;
         createdAt?: string;
     }>;
     deleteWebhook(id: string): Promise<unknown>;

package/dist/src/types.d.ts

@@ -562,7 +562,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List webhooks */
+        /**
+         * List webhooks
+         * @description List managed webhook subscriptions for the authenticated user. Managed webhook deliveries include HMAC-SHA256 signatures.
+         */
         get: {
             parameters: {
                 query?: never;
@@ -584,7 +587,11 @@ export interface paths {
             };
         };
         put?: never;
-        /** Create a webhook */
+        /**
+         * 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`.
+         */
         post: {
             parameters: {
                 query?: never;
@@ -624,7 +631,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Test a webhook */
+        /**
+         * Test a webhook
+         * @description Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries.
+         */
         post: {
             parameters: {
                 query?: never;
@@ -668,7 +678,33 @@ export interface paths {
         };
         options?: never;
         head?: never;
-        patch?: never;
+        /** Update a webhook */
+        patch: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["WebhookUpdateRequest"];
+                };
+            };
+            responses: {
+                /** @description Updated */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WebhookResponse"];
+                    };
+                };
+            };
+        };
         trace?: never;
     };
     "/jobs/bulk": {
@@ -1212,8 +1248,12 @@ export interface paths {
          * @description Crawls an S3 prefix or Google Drive folder, queues one encode job per video file,
          *     and optionally delivers outputs to CDN, S3, or Google Drive.
          *
-         *     For API integrations, Google Drive can be used without dashboard OAuth by passing
-         *     `accessToken` in `sourceGoogleDrive` and/or `outputGoogleDrive`.
+         *     For API integrations, use bring-your-own credentials:
+         *     - S3-compatible storage: pass `sourceS3` and/or `outputS3` credentials from your backend.
+         *     - Google Drive: pass customer OAuth `accessToken` values in `sourceGoogleDrive` and/or `outputGoogleDrive`.
+         *     - 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.
          */
         post: {
             parameters: {
@@ -1590,6 +1630,12 @@ export interface components {
             url: string;
             events: ("job.created" | "job.queued" | "job.running" | "job.completed" | "job.failed" | "job.canceled")[];
         };
+        WebhookUpdateRequest: {
+            /** Format: uri */
+            url?: string;
+            events?: ("job.created" | "job.queued" | "job.running" | "job.completed" | "job.failed" | "job.canceled")[];
+            isActive?: boolean;
+        };
         WebhookResponse: {
             /** Format: uuid */
             id?: string;
@@ -1598,6 +1644,11 @@ export interface components {
             /** @description HMAC secret, only returned on creation */
             secret?: string;
             isActive?: boolean;
+            failureCount?: number;
+            /** Format: date-time */
+            lastTriggeredAt?: string | null;
+            /** Format: date-time */
+            lastFailedAt?: string | null;
             /** Format: date-time */
             createdAt?: string;
         };
@@ -1615,45 +1666,63 @@ export interface components {
             secretAccessKey?: string;
             forcePathStyle?: boolean;
         };
+        /** @description Customer-owned S3-compatible folder source. Credentials should allow listing the prefix and reading objects. */
         S3FolderSource: {
             bucket: string;
-            /** @default  */
+            /**
+             * @description Prefix to crawl. Only files with video extensions are queued.
+             * @default
+             */
             prefix?: string;
-            /** Format: uri */
+            /**
+             * Format: uri
+             * @description Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
+             */
             endpoint?: string;
             region?: string;
+            /** @description Optional source access key. Omit only when your backend/runtime provides credentials another way. */
             accessKeyId?: string;
             /** Format: password */
             secretAccessKey?: string;
             /** @default true */
             forcePathStyle?: boolean;
         };
+        /** @description Customer-owned S3-compatible output destination. Credentials should allow writing encoded objects. */
         S3FolderOutput: {
             bucket: string;
-            /** @default outputs/ */
+            /**
+             * @description Output key prefix. The source file name is appended to this prefix.
+             * @default outputs/
+             */
             prefix?: string;
-            /** Format: uri */
+            /**
+             * Format: uri
+             * @description Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
+             */
             endpoint?: string;
             region?: string;
+            /** @description Optional output access key. Omit only when your backend/runtime provides credentials another way. */
             accessKeyId?: string;
             /** Format: password */
             secretAccessKey?: string;
             /** @default true */
             forcePathStyle?: boolean;
         };
+        /** @description Google Drive folder source for API integrations. Pass a customer-owned OAuth token instead of sending the user through the Convertrilo dashboard. */
         GoogleDriveFolderSource: {
             folderId: string;
-            /** @description Short-lived Google OAuth access token supplied by the API caller. */
+            /** @description Short-lived Google OAuth access token supplied by the API caller. Must allow reading/listing files in the folder. */
             accessToken?: string;
-            /** @description Optional Google refresh token supplied by the API caller for long-running jobs. */
+            /** @description Optional Google refresh token supplied by the API caller. Recommended for long-running folder jobs so workers can refresh expired access tokens. */
             refreshToken?: string;
         };
+        /** @description Google Drive output destination for API integrations. Pass a customer-owned OAuth token with upload access to the destination folder. */
         GoogleDriveOutput: {
             folderId: string;
             fileName?: string;
-            /** @description Short-lived Google OAuth access token supplied by the API caller. */
+            /** @description Short-lived Google OAuth access token supplied by the API caller. Must allow uploading to the destination folder. */
             accessToken?: string;
-            /** @description Optional Google refresh token supplied by the API caller for long-running jobs. */
+            /** @description Optional Google refresh token supplied by the API caller. Recommended for long-running jobs so workers can refresh expired access tokens. */
             refreshToken?: string;
         };
         OnDemandEncodeRequest: {
@@ -1698,7 +1767,10 @@ export interface components {
             priority?: "normal" | "high";
             /** @default 86400 */
             outputExpiry?: number;
-            /** Format: uri */
+            /**
+             * Format: uri
+             * @description Optional one-off terminal callback URL for this job. Best-effort and unsigned. Use managed webhooks for signed HMAC delivery.
+             */
             webhook?: string;
             outputS3?: components["schemas"]["S3Output"];
             outputGoogleDrive?: components["schemas"]["GoogleDriveOutput"];

package/openapi.yaml

@@ -5,6 +5,16 @@ info:
   description: |
     JWT-protected API for creating and managing encode jobs. Supports browser-upload, direct URL ingest, or S3 source.
     Public endpoints are limited and rate-limited.
+
+    Swagger auth:
+    1. Create an API key in Dashboard -> Developer.
+    2. Click Authorize in these docs.
+    3. Paste the raw API key into ApiKeyAuth.
+    4. Protected endpoints can then be executed from Swagger.
+
+    API integrations should keep Convertrilo API keys and customer storage/OAuth tokens on the server.
+    For storage integrations, pass customer-owned S3 credentials or Google OAuth access/refresh tokens directly in the API request.
+    Convertrilo does not require your API users to visit the dashboard OAuth flow.
     
     Official TypeScript SDK: https://www.npmjs.com/package/@convertrilo/sdk
     SDK source and examples: https://github.com/serkandrgn/convertrilo-js
@@ -292,6 +302,24 @@ components:
                 job.failed,
                 job.canceled,
               ]
+    WebhookUpdateRequest:
+      type: object
+      properties:
+        url: { type: string, format: uri }
+        events:
+          type: array
+          items:
+            type: string
+            enum:
+              [
+                job.created,
+                job.queued,
+                job.running,
+                job.completed,
+                job.failed,
+                job.canceled,
+              ]
+        isActive: { type: boolean }
     WebhookResponse:
       type: object
       properties:
@@ -306,6 +334,9 @@ components:
             description: "HMAC secret, only returned on creation",
           }
         isActive: { type: boolean }
+        failureCount: { type: integer }
+        lastTriggeredAt: { type: string, format: date-time, nullable: true }
+        lastFailedAt: { type: string, format: date-time, nullable: true }
         createdAt: { type: string, format: date-time }
     WebhookListResponse:
       type: object
@@ -329,49 +360,69 @@ components:
         forcePathStyle: { type: boolean }
     S3FolderSource:
       type: object
+      description: Customer-owned S3-compatible folder source. Credentials should allow listing the prefix and reading objects.
       required: [bucket]
       properties:
         bucket: { type: string }
-        prefix: { type: string, default: "" }
-        endpoint: { type: string, format: uri }
+        prefix:
+          type: string
+          default: ""
+          description: Prefix to crawl. Only files with video extensions are queued.
+        endpoint:
+          type: string
+          format: uri
+          description: Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
         region: { type: string }
-        accessKeyId: { type: string }
+        accessKeyId:
+          type: string
+          description: Optional source access key. Omit only when your backend/runtime provides credentials another way.
         secretAccessKey: { type: string, format: password }
         forcePathStyle: { type: boolean, default: true }
     S3FolderOutput:
       type: object
+      description: Customer-owned S3-compatible output destination. Credentials should allow writing encoded objects.
       required: [bucket]
       properties:
         bucket: { type: string }
-        prefix: { type: string, default: outputs/ }
-        endpoint: { type: string, format: uri }
+        prefix:
+          type: string
+          default: outputs/
+          description: Output key prefix. The source file name is appended to this prefix.
+        endpoint:
+          type: string
+          format: uri
+          description: Optional S3-compatible endpoint, for example Cloudflare R2, MinIO, or object storage providers.
         region: { type: string }
-        accessKeyId: { type: string }
+        accessKeyId:
+          type: string
+          description: Optional output access key. Omit only when your backend/runtime provides credentials another way.
         secretAccessKey: { type: string, format: password }
         forcePathStyle: { type: boolean, default: true }
     GoogleDriveFolderSource:
       type: object
+      description: Google Drive folder source for API integrations. Pass a customer-owned OAuth token instead of sending the user through the Convertrilo dashboard.
       required: [folderId]
       properties:
         folderId: { type: string }
         accessToken:
           type: string
-          description: Short-lived Google OAuth access token supplied by the API caller.
+          description: Short-lived Google OAuth access token supplied by the API caller. Must allow reading/listing files in the folder.
         refreshToken:
           type: string
-          description: Optional Google refresh token supplied by the API caller for long-running jobs.
+          description: Optional Google refresh token supplied by the API caller. Recommended for long-running folder jobs so workers can refresh expired access tokens.
     GoogleDriveOutput:
       type: object
+      description: Google Drive output destination for API integrations. Pass a customer-owned OAuth token with upload access to the destination folder.
       required: [folderId]
       properties:
         folderId: { type: string }
         fileName: { type: string }
         accessToken:
           type: string
-          description: Short-lived Google OAuth access token supplied by the API caller.
+          description: Short-lived Google OAuth access token supplied by the API caller. Must allow uploading to the destination folder.
         refreshToken:
           type: string
-          description: Optional Google refresh token supplied by the API caller for long-running jobs.
+          description: Optional Google refresh token supplied by the API caller. Recommended for long-running jobs so workers can refresh expired access tokens.
     OnDemandEncodeRequest:
       type: object
       required: [sourceUrl]
@@ -393,7 +444,10 @@ components:
         priority: { type: string, enum: [normal, high], default: normal }
         outputExpiry:
           { type: integer, minimum: 3600, maximum: 604800, default: 86400 }
-        webhook: { type: string, format: uri }
+        webhook:
+          type: string
+          format: uri
+          description: Optional one-off terminal callback URL for this job. Best-effort and unsigned. Use managed webhooks for signed HMAC delivery.
         outputS3:
           $ref: "#/components/schemas/S3Output"
         outputGoogleDrive:
@@ -758,6 +812,7 @@ paths:
     get:
       security: [{ BearerAuth: [] }]
       summary: List webhooks
+      description: List managed webhook subscriptions for the authenticated user. Managed webhook deliveries include HMAC-SHA256 signatures.
       responses:
         "200":
           description: List of webhooks
@@ -768,12 +823,21 @@ paths:
     post:
       security: [{ BearerAuth: [] }]
       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`.
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/WebhookCreateRequest"
+            examples:
+              jobCompletionWebhook:
+                summary: Completion and failure notifications
+                value:
+                  url: https://your-app.com/webhooks/convertrilo
+                  events: [job.completed, job.failed, job.canceled]
       responses:
         "200":
           description: Created
@@ -782,6 +846,36 @@ paths:
               schema:
                 $ref: "#/components/schemas/WebhookResponse"
   /webhooks/{id}:
+    patch:
+      security: [{ BearerAuth: [] }]
+      summary: Update a webhook
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/WebhookUpdateRequest"
+            examples:
+              reEnableWebhook:
+                summary: Re-enable a disabled webhook
+                value:
+                  isActive: true
+              changeEvents:
+                summary: Receive only terminal job events
+                value:
+                  events: [job.completed, job.failed, job.canceled]
+      responses:
+        "200":
+          description: Updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WebhookResponse"
     delete:
       security: [{ BearerAuth: [] }]
       summary: Delete a webhook
@@ -795,6 +889,7 @@ paths:
     post:
       security: [{ BearerAuth: [] }]
       summary: Test a webhook
+      description: Sends a `webhook.test` event to the configured URL using the same HMAC signature header as managed deliveries.
       parameters:
         - in: path
           name: id
@@ -1018,6 +1113,37 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/OnDemandEncodeRequest"
+            examples:
+              urlToCdn:
+                summary: URL source to CDN output
+                value:
+                  sourceUrl: https://example.com/video.mp4
+                  codec: h264
+                  resolution: 1080p
+                  quality: better
+              urlToS3:
+                summary: URL source to S3 output
+                value:
+                  sourceUrl: https://example.com/video.mp4
+                  codec: h264
+                  resolution: 1080p
+                  outputS3:
+                    bucket: customer-output-bucket
+                    key: encoded/video-1080p.mp4
+                    region: us-east-1
+                    accessKeyId: AKIA...
+                    secretAccessKey: replace-with-secret
+              urlToGoogleDrive:
+                summary: URL source to Google Drive output with BYO token
+                value:
+                  sourceUrl: https://example.com/video.mp4
+                  codec: h264
+                  resolution: 1080p
+                  outputGoogleDrive:
+                    folderId: GOOGLE_DRIVE_FOLDER_ID
+                    fileName: video-1080p.mp4
+                    accessToken: ya29...
+                    refreshToken: optional-refresh-token
       responses:
         "200":
           description: Job created and queued
@@ -1057,14 +1183,51 @@ paths:
         Crawls an S3 prefix or Google Drive folder, queues one encode job per video file,
         and optionally delivers outputs to CDN, S3, or Google Drive.
 
-        For API integrations, Google Drive can be used without dashboard OAuth by passing
-        `accessToken` in `sourceGoogleDrive` and/or `outputGoogleDrive`.
+        For API integrations, use bring-your-own credentials:
+        - S3-compatible storage: pass `sourceS3` and/or `outputS3` credentials from your backend.
+        - Google Drive: pass customer OAuth `accessToken` values in `sourceGoogleDrive` and/or `outputGoogleDrive`.
+        - 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.
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/OnDemandFolderIngestRequest"
+            examples:
+              s3FolderToS3:
+                summary: S3 folder source to S3 output
+                value:
+                  sourceS3:
+                    bucket: customer-source-bucket
+                    prefix: incoming/
+                    region: us-east-1
+                    accessKeyId: AKIA...
+                    secretAccessKey: replace-with-secret
+                  outputDestination: s3
+                  outputS3:
+                    bucket: customer-output-bucket
+                    prefix: encoded/
+                    region: us-east-1
+                    accessKeyId: AKIA...
+                    secretAccessKey: replace-with-secret
+                  codec: h264
+                  resolution: 1080p
+              googleDriveFolderToGoogleDrive:
+                summary: Google Drive folder source to Google Drive output
+                value:
+                  sourceGoogleDrive:
+                    folderId: SOURCE_FOLDER_ID
+                    accessToken: ya29...
+                    refreshToken: optional-refresh-token
+                  outputDestination: google-drive
+                  outputGoogleDrive:
+                    folderId: OUTPUT_FOLDER_ID
+                    accessToken: ya29...
+                    refreshToken: optional-refresh-token
+                  codec: h264
+                  resolution: 1080p
       responses:
         "200":
           description: Folder jobs queued

package/package.json

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