@convertrilo/sdk 0.0.3 → 0.0.5

package/README.md

@@ -37,6 +37,10 @@ The `examples/` directory contains starter scripts for the main integration path
 Local SDK smoke tests use `.env`, but published SDK users should provide credentials through their
 own server environment. Do not put Convertrilo API keys or customer storage tokens in frontend code.
 
+For a complete server-to-server walkthrough covering URL, S3, folder ingest, Google Drive BYO
+OAuth tokens, polling, and webhooks, see
+[`docs/API-INTEGRATION-GUIDE.md`](docs/API-INTEGRATION-GUIDE.md).
+
 ## URL Source To CDN Output
 
 ```ts

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/docs/API-INTEGRATION-GUIDE.md

@@ -0,0 +1,218 @@
+# API Integration Guide
+
+This guide is for server-to-server integrations that want to use Convertrilo as a low-cost video encoding backend.
+
+Do not call Convertrilo directly from browser or mobile apps. Keep Convertrilo API keys, S3 credentials, and Google OAuth tokens on your backend.
+
+## Core Model
+
+1. Your app authenticates your user.
+2. Your backend collects or owns the source video location.
+3. Your backend calls Convertrilo with an API key.
+4. Convertrilo queues one or more encode jobs.
+5. Your backend tracks completion by polling job status or receiving managed webhooks.
+
+API users do not need to connect Google Drive in the Convertrilo dashboard. For Google Drive integrations, your app should run its own Google OAuth flow and pass customer-owned `accessToken` and optional `refreshToken` values to Convertrilo.
+
+## Authentication
+
+Create an API key in the dashboard Developer page and send it with every request:
+
+```bash
+curl https://api.convertrilo.com/tokens/balance \
+  -H "X-API-Key: $CONVERTRILO_API_KEY"
+```
+
+Use API keys with the minimum scopes needed by your integration. Most encode integrations need:
+
+- `jobs:create`
+- `jobs:read`
+- `jobs:cancel` if you expose cancellation
+
+## TypeScript SDK
+
+```bash
+pnpm add @convertrilo/sdk
+```
+
+```ts
+import { ConvertriloClient } from "@convertrilo/sdk";
+
+const client = new ConvertriloClient({
+  baseUrl: "https://api.convertrilo.com",
+  apiKey: process.env.CONVERTRILO_API_KEY,
+});
+```
+
+SDK source and examples: https://github.com/serkandrgn/convertrilo-js
+
+## Flow 1: URL Source To CDN Output
+
+Use this when the source video is already available over HTTP(S), and you want Convertrilo to return a signed CDN download URL.
+
+```ts
+const job = await client.onDemandEncode({
+  sourceUrl: "https://example.com/input.mp4",
+  codec: "h264",
+  resolution: "1080p",
+  quality: "better",
+});
+
+console.log(job.jobId);
+```
+
+Equivalent curl:
+
+```bash
+curl https://api.convertrilo.com/ondemand/encode \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $CONVERTRILO_API_KEY" \
+  -d '{
+    "sourceUrl": "https://example.com/input.mp4",
+    "codec": "h264",
+    "resolution": "1080p",
+    "quality": "better"
+  }'
+```
+
+Poll `/ondemand/status/{jobId}` until the job reaches `success`, then read `downloadUrl`.
+
+## Flow 2: URL Source To S3 Output
+
+Use this when your customer wants the encoded output in their own S3-compatible bucket.
+
+The output credentials need permission to write the final object.
+
+```ts
+const job = await client.onDemandEncode({
+  sourceUrl: "https://example.com/input.mp4",
+  codec: "h264",
+  resolution: "1080p",
+  outputS3: {
+    bucket: "customer-output-bucket",
+    key: "encoded/input-1080p.mp4",
+    region: "us-east-1",
+    endpoint: process.env.CUSTOMER_S3_ENDPOINT,
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+    forcePathStyle: true,
+  },
+});
+```
+
+For AWS S3, `endpoint` is usually unnecessary. For S3-compatible providers such as Cloudflare R2, MinIO, or object storage providers, pass `endpoint` and usually `forcePathStyle: true`.
+
+## Flow 3: S3 Folder To S3 Output
+
+Use this for batch compression. Convertrilo lists a source prefix, filters video files, and queues one encode job per video.
+
+Source credentials need permission to list the prefix and read objects. Output credentials need permission to write encoded objects.
+
+```ts
+const batch = await client.onDemandIngestFolder({
+  sourceS3: {
+    bucket: "customer-source-bucket",
+    prefix: "incoming/",
+    region: "us-east-1",
+    endpoint: process.env.CUSTOMER_S3_ENDPOINT,
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+    forcePathStyle: true,
+  },
+  outputDestination: "s3",
+  outputS3: {
+    bucket: "customer-output-bucket",
+    prefix: "encoded/",
+    region: "us-east-1",
+    endpoint: process.env.CUSTOMER_S3_ENDPOINT,
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+    forcePathStyle: true,
+  },
+  codec: "h264",
+  resolution: "1080p",
+});
+
+for (const job of batch.jobs || []) {
+  console.log(job.jobId, job.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
+
+Use this when your app already owns the customer relationship and can run Google OAuth itself.
+
+Do not send customers to the Convertrilo dashboard OAuth flow for API usage. Your app should request the Google scopes it needs, store tokens on your backend, and pass those tokens to Convertrilo per request.
+
+For output-only jobs:
+
+```ts
+const job = await client.onDemandEncode({
+  sourceUrl: "https://example.com/input.mp4",
+  codec: "h264",
+  resolution: "1080p",
+  outputGoogleDrive: {
+    folderId: "GOOGLE_DRIVE_OUTPUT_FOLDER_ID",
+    fileName: "input-1080p.mp4",
+    accessToken: customerGoogleAccessToken,
+    refreshToken: customerGoogleRefreshToken,
+  },
+});
+```
+
+For folder ingest from Google Drive to Google Drive:
+
+```ts
+const batch = await client.onDemandIngestFolder({
+  sourceGoogleDrive: {
+    folderId: "SOURCE_FOLDER_ID",
+    accessToken: customerGoogleAccessToken,
+    refreshToken: customerGoogleRefreshToken,
+  },
+  outputDestination: "google-drive",
+  outputGoogleDrive: {
+    folderId: "OUTPUT_FOLDER_ID",
+    accessToken: customerGoogleAccessToken,
+    refreshToken: customerGoogleRefreshToken,
+  },
+  codec: "h264",
+  resolution: "1080p",
+});
+```
+
+Include `refreshToken` when jobs may outlive a short-lived access token. Without a valid access token or refresh token, Google Drive folder ingest returns `401`.
+
+## Tracking Completion
+
+For simple integrations, poll status:
+
+```ts
+async function waitForOnDemandJob(jobId: string) {
+  while (true) {
+    const status = await client.onDemandStatus(jobId);
+
+    if (status.status === "success") return status;
+    if (status.status === "failed" || status.status === "canceled") {
+      throw new Error(status.failureMessage || `Job ${status.status}`);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+}
+```
+
+For production workflows, prefer managed webhooks. Managed webhooks are HMAC signed and are better for async pipelines. See [WEBHOOKS.md](WEBHOOKS.md).
+
+## Error Handling
+
+Common responses:
+
+- `400`: invalid request payload
+- `401`: missing API auth or missing/expired Google Drive token
+- `403`: API key does not have the required scope
+- `404`: folder ingest found no video files
+- `410`: Dropbox source or destination was requested; Dropbox is deprecated
+
+Treat encode job failure separately from request failure. A request can return `200` because the job was queued, then the job can later fail during download, encode, upload, or token refresh.

package/docs/WEBHOOKS.md

@@ -0,0 +1,138 @@
+# Webhooks
+
+Convertrilo supports managed webhook subscriptions for job lifecycle events.
+
+Create managed webhooks in the dashboard Developer page or with `POST /webhooks`.
+Managed webhook deliveries are signed with HMAC-SHA256.
+
+## Events
+
+- `job.created`
+- `job.queued`
+- `job.running`
+- `job.completed`
+- `job.failed`
+- `job.canceled`
+- `webhook.test` for manual test deliveries
+
+## Headers
+
+Managed webhook deliveries include:
+
+```txt
+Content-Type: application/json
+X-Webhook-Signature: <hex hmac sha256>
+X-Webhook-Event: job.completed
+X-Webhook-Id: <webhook id>
+```
+
+The signature is:
+
+```txt
+hex(hmac_sha256(raw_request_body, webhook_secret))
+```
+
+Use the raw request body exactly as received. Do not parse and stringify JSON before verifying.
+
+## Payload
+
+```json
+{
+  "event": "job.completed",
+  "timestamp": "2026-06-05T00:00:00.000Z",
+  "data": {
+    "jobId": "550e8400-e29b-41d4-a716-446655440000",
+    "userId": "9c38f5dd-d9d6-4d08-a514-41e166dfbb8b",
+    "status": "success",
+    "encoder": "h264_nvenc",
+    "durationSec": 42,
+    "finalNeu": 2.5
+  }
+}
+```
+
+Failure events include `error` and `failureCode` when available.
+
+## Verify In Node / Express
+
+```ts
+import crypto from "node:crypto";
+import express from "express";
+
+const app = express();
+const webhookSecret = process.env.CONVERTRILO_WEBHOOK_SECRET!;
+
+app.post(
+  "/webhooks/convertrilo",
+  express.raw({ type: "application/json" }),
+  (req, res) => {
+    const signature = req.header("X-Webhook-Signature") || "";
+    const expected = crypto
+      .createHmac("sha256", webhookSecret)
+      .update(req.body)
+      .digest("hex");
+
+    const valid =
+      signature.length === expected.length &&
+      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+
+    if (!valid) {
+      return res.status(401).send("Invalid signature");
+    }
+
+    const payload = JSON.parse(req.body.toString("utf8"));
+    console.log(payload.event, payload.data.jobId);
+
+    return res.sendStatus(204);
+  }
+);
+```
+
+## Verify In Next.js Route Handler
+
+```ts
+import crypto from "node:crypto";
+import { NextRequest, NextResponse } from "next/server";
+
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const signature = req.headers.get("x-webhook-signature") || "";
+  const secret = process.env.CONVERTRILO_WEBHOOK_SECRET!;
+
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(rawBody)
+    .digest("hex");
+
+  const valid =
+    signature.length === expected.length &&
+    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+
+  if (!valid) {
+    return new NextResponse("Invalid signature", { status: 401 });
+  }
+
+  const payload = JSON.parse(rawBody);
+  console.log(payload.event, payload.data.jobId);
+
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+## Delivery Behavior
+
+- Timeout: 15 seconds
+- Success: any `2xx` response
+- Failure: non-`2xx`, network error, or timeout
+- A webhook is automatically disabled after 10 consecutive failures
+- Re-enable it with `PATCH /webhooks/{id}` and `{ "isActive": true }`
+
+Current deliveries are best-effort. There is not yet a durable retry queue or delivery history API.
+
+## One-Off On-Demand Webhook URL
+
+`POST /ondemand/encode` also accepts a `webhook` URL. That URL receives one terminal callback for
+`job.completed`, `job.failed`, or `job.canceled`.
+
+This one-off URL is best-effort and unsigned because it has no stored secret. For production
+workflow integrations, prefer managed webhooks.

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.5",
   "description": "TypeScript client for the Convertrilo video encoding API",
   "private": false,
   "license": "MIT",
@@ -35,6 +35,7 @@
   "files": [
     "dist/src",
     "examples",
+    "docs",
     "openapi.yaml",
     "README.md",
     "LICENSE"