@convertrilo/sdk 0.0.11 → 0.0.12

package/README.md

@@ -33,6 +33,8 @@ The `examples/` directory contains starter scripts for the main integration path
 - `node-url-to-s3.ts` - encode a public URL and upload the result to S3/S3-compatible storage
 - `google-drive-byo-token.ts` - upload output to Google Drive using customer OAuth tokens from your app
 - `folder-ingest-s3.ts` - queue one encode job per video in an S3 prefix
+- `idempotency.ts` - safely retry `createJob` and `createJobsBulk`
+- `webhook-receiver-hmac.ts` - verify managed webhook HMAC signatures from a Node receiver
 
 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.

package/dist/src/index.d.ts

@@ -75,10 +75,23 @@ export declare class ConvertriloClient {
     cancelJob(id: string): Promise<unknown>;
     jobStatus(id: string): Promise<{
         id?: string;
+        externalId?: string | null;
+        metadata?: {
+            [key: string]: unknown;
+        } | null;
         status?: string;
+        ingest?: string | null;
+        output?: {
+            key?: string;
+            publicUrl?: string;
+        } | null;
         downloadUrl?: string | null;
         encoder?: string | null;
         pct?: number | null;
+        createdAt?: string;
+        startedAt?: string | null;
+        finishedAt?: string | null;
+        failureMessage?: string | null;
     }>;
     createJobsBulk(body: paths["/jobs/bulk"]["post"]["requestBody"]["content"]["application/json"], options?: RequestOptions): Promise<{
         totalJobs?: number;

package/dist/src/types.d.ts

@@ -1642,13 +1642,39 @@ export interface components {
         };
         StatusResponse: {
             id?: string;
+            externalId?: string | null;
+            metadata?: {
+                [key: string]: unknown;
+            } | null;
             status?: string;
+            ingest?: string | null;
+            output?: {
+                key?: string;
+                publicUrl?: string;
+            } | null;
             downloadUrl?: string | null;
             encoder?: string | null;
             pct?: number | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            startedAt?: string | null;
+            /** Format: date-time */
+            finishedAt?: string | null;
+            failureMessage?: string | null;
         };
         ErrorResponse: {
-            message?: string;
+            /**
+             * @description Stable machine-readable error code. Branch on this instead of parsing `message`.
+             * @enum {string}
+             */
+            code: "invalid_api_key" | "api_key_expired" | "user_not_found" | "account_banned" | "missing_required_scope" | "invalid_request" | "invalid_body" | "invalid_url" | "url_ingest_disabled" | "url_host_blocked" | "signed_url_required" | "host_not_resolvable" | "private_ip_blocked" | "missing_content_length" | "file_too_large" | "unsupported_content_type" | "probe_failed" | "insufficient_tokens" | "idempotency_conflict" | "idempotency_in_progress" | "not_found" | "forbidden" | "deprecated_dropbox" | "google_drive_not_connected" | "dropbox_not_connected" | "no_video_files_found" | "webhook_limit_exceeded" | "webhook_not_found" | "no_updates_provided" | "output_not_available";
+            message: string;
+            /** @description Validation details for `invalid_body`. */
+            issues?: unknown;
+            requiredScope?: string;
+            required?: number;
+            available?: number;
         };
         BulkCreateRequest: {
             jobs: components["schemas"]["JobCreateRequest"][];

package/docs/API-INTEGRATION-GUIDE.md

@@ -79,6 +79,10 @@ const batch = await client.createJobsBulk({
 });
 ```
 
+API errors include a stable `code` field plus a human-readable `message`. Branch on
+`code` in your backend, for example `idempotency_conflict`, `insufficient_tokens`,
+or `missing_required_scope`.
+
 ## 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.

package/examples/idempotency.ts

@@ -0,0 +1,60 @@
+import { ConvertriloClient } from "@convertrilo/sdk";
+
+const apiKey = process.env.CONVERTRILO_API_KEY;
+if (!apiKey) throw new Error("Set CONVERTRILO_API_KEY");
+
+const client = new ConvertriloClient({
+  baseUrl: process.env.CONVERTRILO_API_URL || "https://api.convertrilo.com",
+  apiKey,
+});
+
+async function main() {
+  const externalId = `example-upload-${Date.now()}`;
+
+  const job = await client.createJob(
+    {
+      externalId,
+      metadata: {
+        customerId: "cus_123",
+        workflow: "sdk-idempotency-example",
+      },
+      codec: "h264",
+      resolution: "1080p",
+      fps: 30,
+    },
+    {
+      idempotencyKey: `job-${externalId}`,
+    },
+  );
+
+  console.log(`Created or replayed job ${job.jobId}`);
+
+  const batch = await client.createJobsBulk(
+    {
+      jobs: [
+        {
+          externalId: `${externalId}:clip-1`,
+          metadata: { customerId: "cus_123" },
+          codec: "h264",
+          resolution: "1080p",
+          fps: 30,
+          sourceS3: {
+            bucket: "customer-source-bucket",
+            key: "incoming/clip-1.mp4",
+          },
+        },
+      ],
+      settings: { dryRun: true },
+    },
+    {
+      idempotencyKey: `bulk-${externalId}`,
+    },
+  );
+
+  console.log(`Created or replayed bulk response with ${batch.totalJobs} job(s)`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/webhook-receiver-hmac.ts

@@ -0,0 +1,54 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import http from "node:http";
+
+const secret = process.env.CONVERTRILO_WEBHOOK_SECRET;
+if (!secret) throw new Error("Set CONVERTRILO_WEBHOOK_SECRET");
+
+function verifySignature(rawBody: Buffer, signature: string) {
+  const expected = createHmac("sha256", secret!).update(rawBody).digest("hex");
+  const expectedBuffer = Buffer.from(expected, "hex");
+  const signatureBuffer = Buffer.from(signature, "hex");
+
+  return (
+    expectedBuffer.length === signatureBuffer.length &&
+    timingSafeEqual(expectedBuffer, signatureBuffer)
+  );
+}
+
+const server = http.createServer((request, response) => {
+  if (request.method !== "POST" || request.url !== "/webhooks/convertrilo") {
+    response.writeHead(404);
+    response.end("Not found");
+    return;
+  }
+
+  const chunks: Buffer[] = [];
+
+  request.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+  request.on("end", () => {
+    const rawBody = Buffer.concat(chunks);
+    const signature = String(request.headers["x-webhook-signature"] || "");
+
+    if (!signature || !verifySignature(rawBody, signature)) {
+      response.writeHead(401);
+      response.end("Invalid signature");
+      return;
+    }
+
+    const payload = JSON.parse(rawBody.toString("utf8"));
+    console.log("Verified Convertrilo webhook", {
+      event: payload.event,
+      jobId: payload.data?.jobId,
+      status: payload.data?.status,
+      externalId: payload.data?.externalId,
+    });
+
+    response.writeHead(204);
+    response.end();
+  });
+});
+
+const port = Number(process.env.PORT || 3000);
+server.listen(port, () => {
+  console.log(`Webhook receiver listening on http://localhost:${port}/webhooks/convertrilo`);
+});

package/openapi.yaml

@@ -214,14 +214,70 @@ components:
       type: object
       properties:
         id: { type: string }
+        externalId: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
         status: { type: string }
+        ingest: { type: string, nullable: true }
+        output:
+          nullable: true
+          type: object
+          properties:
+            key: { type: string }
+            publicUrl: { type: string }
         downloadUrl: { type: string, nullable: true }
         encoder: { type: string, nullable: true }
         pct: { type: number, nullable: true }
+        createdAt: { type: string, format: date-time }
+        startedAt: { type: string, format: date-time, nullable: true }
+        finishedAt: { type: string, format: date-time, nullable: true }
+        failureMessage: { type: string, nullable: true }
     ErrorResponse:
       type: object
+      required: [code, message]
       properties:
+        code:
+          type: string
+          description: Stable machine-readable error code. Branch on this instead of parsing `message`.
+          enum:
+            - invalid_api_key
+            - api_key_expired
+            - user_not_found
+            - account_banned
+            - missing_required_scope
+            - invalid_request
+            - invalid_body
+            - invalid_url
+            - url_ingest_disabled
+            - url_host_blocked
+            - signed_url_required
+            - host_not_resolvable
+            - private_ip_blocked
+            - missing_content_length
+            - file_too_large
+            - unsupported_content_type
+            - probe_failed
+            - insufficient_tokens
+            - idempotency_conflict
+            - idempotency_in_progress
+            - not_found
+            - forbidden
+            - deprecated_dropbox
+            - google_drive_not_connected
+            - dropbox_not_connected
+            - no_video_files_found
+            - webhook_limit_exceeded
+            - webhook_not_found
+            - no_updates_provided
+            - output_not_available
         message: { type: string }
+        issues:
+          description: Validation details for `invalid_body`.
+        requiredScope: { type: string }
+        required: { type: number }
+        available: { type: number }
 
     # Bulk Jobs
     BulkCreateRequest:

package/package.json

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