@convertrilo/sdk 0.0.4 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convertrilo/sdk",
-  "version": "0.0.4",
+  "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"