@convertrilo/sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Convertrilo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# Convertrilo TypeScript SDK
+
+Type-safe client for the Convertrilo API.
+
+## Install
+
+```bash
+pnpm add @convertrilo/sdk
+```
+
+The package currently targets modern Node.js runtimes with global `fetch`. If your runtime does
+not provide `fetch`, pass `fetchImpl` to the client.
+
+## Create A Client
+
+```ts
+import { ConvertriloClient } from "@convertrilo/sdk";
+
+const client = new ConvertriloClient({
+  baseUrl: "https://api.convertrilo.com",
+  apiKey: process.env.CONVERTRILO_API_KEY,
+});
+```
+
+Use an API key for server-to-server integrations. Browser apps should call your own backend,
+then your backend calls Convertrilo.
+
+## Examples
+
+The `examples/` directory contains starter scripts for the main integration paths:
+
+- `node-url-to-cdn.ts` - encode a public URL and receive a signed CDN download URL
+- `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
+
+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.
+
+## URL Source To CDN Output
+
+```ts
+const job = await client.onDemandEncode({
+  sourceUrl: "https://example.com/input.mp4",
+  codec: "h264",
+  resolution: "1080p",
+  quality: "better",
+});
+
+let finalStatus;
+while (true) {
+  finalStatus = await client.onDemandStatus(job.jobId);
+
+  if (finalStatus.status === "success") break;
+  if (finalStatus.status === "failed") {
+    throw new Error(finalStatus.failureMessage || "Encoding failed");
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+}
+
+console.log(finalStatus.downloadUrl);
+```
+
+## URL Source To S3 Output
+
+```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",
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+  },
+});
+
+console.log(job.jobId);
+```
+
+For S3-compatible services, pass `endpoint` and usually `forcePathStyle: true`.
+
+## URL Source To Google Drive Output
+
+For API integrations, the customer should authorize Google Drive inside your application.
+Then your backend passes the resulting Google token to Convertrilo.
+
+```ts
+const job = await client.onDemandEncode({
+  sourceUrl: "https://example.com/input.mp4",
+  codec: "h264",
+  resolution: "1080p",
+  outputGoogleDrive: {
+    folderId: "GOOGLE_DRIVE_FOLDER_ID",
+    fileName: "input-1080p.mp4",
+    accessToken: customerGoogleAccessToken,
+    refreshToken: customerGoogleRefreshToken,
+  },
+});
+
+console.log(job.jobId);
+```
+
+Dashboard Google OAuth is for dashboard workflows. API integrations should use this
+bring-your-own-token pattern.
+
+## Folder Ingest
+
+Queue one job per video in an S3 prefix:
+
+```ts
+const batch = await client.onDemandIngestFolder({
+  sourceS3: {
+    bucket: "customer-source-bucket",
+    prefix: "incoming/",
+    region: "us-east-1",
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+  },
+  outputDestination: "s3",
+  outputS3: {
+    bucket: "customer-output-bucket",
+    prefix: "encoded/",
+    region: "us-east-1",
+    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,
+  },
+  codec: "h264",
+  resolution: "1080p",
+});
+
+for (const job of batch.jobs || []) {
+  console.log(job.jobId, job.fileName);
+}
+```
+
+Queue one job per video in a Google Drive folder:
+
+```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",
+});
+
+for (const job of batch.jobs || []) {
+  console.log(job.jobId, job.fileName);
+}
+```
+
+Poll each returned `jobId` with `client.onDemandStatus(jobId)`.
+
+## Regenerate Types
+
+The SDK types are generated from `openapi.yaml`.
+
+```bash
+pnpm run generate
+pnpm run build
+```
+
+The generate script uses `--default-non-nullable false` so OpenAPI defaults remain optional
+in TypeScript request bodies.

package/dist/src/index.d.ts

@@ -0,0 +1,194 @@
+import type { paths } from "./types";
+type ApproveBody = paths["/jobs/{id}/approve-unified"]["post"]["requestBody"] extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : undefined;
+type ConfirmBody = paths["/jobs/{id}/confirm"]["post"]["requestBody"] extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : undefined;
+export type ClientConfig = {
+    baseUrl: string;
+    getToken?: () => Promise<string> | string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+};
+export declare class ConvertriloClient {
+    private baseUrl;
+    private getToken?;
+    private apiKey?;
+    private fetchImpl;
+    constructor(config: ClientConfig);
+    private request;
+    login(body: paths["/auth/login"]["post"]["requestBody"]["content"]["application/json"]): Promise<paths["/auth/login"]["post"]["responses"]["200"]["content"]["application/json"]>;
+    getBalance(): Promise<{
+        available?: number;
+        reserved?: number;
+        trialGrantRemaining?: number;
+        trialExpiresAt?: string | null;
+    }>;
+    reserveTokens(body: paths["/tokens/reserve"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
+    releaseTokens(body: paths["/tokens/release"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
+    deductTokens(body: paths["/tokens/deduct"]["post"]["requestBody"]["content"]["application/json"]): Promise<unknown>;
+    createJob(body: paths["/jobs"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        jobId: string;
+        upload: {
+            url?: string;
+            key?: string;
+        } | null;
+        output: {
+            key?: string;
+            publicUrl?: string;
+        };
+        estimate?: {
+            neu?: number;
+        };
+    }>;
+    probeDuration(id: string): Promise<{
+        durationSec?: number;
+        durationMinutes?: number;
+    }>;
+    approveUnified(id: string, body?: ApproveBody): Promise<{
+        ok?: boolean;
+        estimate?: {
+            perMinuteNeu?: number;
+            durationSec?: number;
+            totalNeu?: number;
+            reserved?: number;
+        };
+    }>;
+    confirmJob(id: string, body?: ConfirmBody): Promise<{
+        ok?: boolean;
+    }>;
+    cancelJob(id: string): Promise<unknown>;
+    jobStatus(id: string): Promise<{
+        id?: string;
+        status?: string;
+        downloadUrl?: string | null;
+        encoder?: string | null;
+        pct?: number | null;
+    }>;
+    createJobsBulk(body: paths["/jobs/bulk"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        totalJobs?: number;
+        totalEstimatedNeu?: number;
+        jobs?: {
+            index?: number;
+            jobId?: string;
+            status?: string;
+            error?: string;
+        }[];
+    }>;
+    bulkStatus(ids: string[]): Promise<{
+        jobs?: import("./types").components["schemas"]["StatusResponse"][];
+        missing?: string[];
+    }>;
+    bulkConfirm(body: paths["/jobs/bulk/confirm"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        queued?: number;
+        jobs?: Record<string, never>[];
+    }>;
+    getApiKeys(): Promise<{
+        keys?: import("./types").components["schemas"]["ApiKeyResponse"][];
+    }>;
+    createApiKey(body: paths["/api-keys"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        id?: string;
+        name?: string;
+        key?: string;
+        prefix?: string;
+        scopes?: string[];
+        expiresAt?: string | null;
+        createdAt?: string;
+    }>;
+    revokeApiKey(id: string): Promise<unknown>;
+    getWebhooks(): Promise<{
+        webhooks?: import("./types").components["schemas"]["WebhookResponse"][];
+    }>;
+    createWebhook(body: paths["/webhooks"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        id?: string;
+        url?: string;
+        events?: string[];
+        secret?: string;
+        isActive?: boolean;
+        createdAt?: string;
+    }>;
+    deleteWebhook(id: string): Promise<unknown>;
+    testWebhook(id: string): Promise<unknown>;
+    initStream(id: string): Promise<{
+        ok?: boolean;
+        uploadId?: string;
+        inputKey?: string;
+    }>;
+    uploadChunk(id: string, index: number, data: Buffer | Blob | ArrayBuffer): Promise<unknown>;
+    finalizeStream(id: string, body?: paths["/jobs/{id}/stream/finalize"]["post"]["requestBody"] extends {
+        content: {
+            "application/json": infer B;
+        };
+    } ? B : any): Promise<unknown>;
+    abortStream(id: string): Promise<unknown>;
+    onDemandEncode(body: paths["/ondemand/encode"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        jobId: string;
+        status: string;
+        estimatedDuration?: number;
+        pricing?: {
+            basePerMinute?: number;
+            onDemandPerMinute?: number;
+            multiplier?: number;
+            totalNeu?: number;
+            reserved?: number;
+        };
+        statusUrl: string;
+        webhook?: string | null;
+    }>;
+    onDemandIngestFolder(body: paths["/ondemand/ingest/folder"]["post"]["requestBody"]["content"]["application/json"]): Promise<{
+        message?: string;
+        jobs?: {
+            jobId?: string;
+            fileName?: string;
+        }[];
+    }>;
+    onDemandStatus(jobId: string): Promise<{
+        jobId?: string;
+        status?: string;
+        progress?: number | null;
+        encoder?: string | null;
+        downloadUrl?: string | null;
+        expiresIn?: number | null;
+        destination?: ({
+            type?: "cdn";
+        } | {
+            type?: "s3";
+            bucket?: string;
+            key?: string;
+        } | {
+            type?: "google-drive";
+            folderId?: string;
+            fileName?: string | null;
+        }) | null;
+        createdAt?: string;
+        startedAt?: string | null;
+        finishedAt?: string | null;
+        failureMessage?: string | null;
+    }>;
+    onDemandCancel(jobId: string): Promise<{
+        ok: boolean;
+        released: number;
+    }>;
+    /**
+     * Helper method to encode a video and wait for completion
+     * @param sourceUrl - URL to the video file
+     * @param options - Encoding options
+     * @param pollInterval - Polling interval in milliseconds (default: 5000)
+     * @param maxAttempts - Maximum polling attempts (default: 120)
+     * @returns Download URL when encoding is complete
+     */
+    onDemandEncodeAndWait(sourceUrl: string, options?: {
+        codec?: "h264" | "h265" | "av1";
+        resolution?: "480p" | "720p" | "1080p" | "1440p" | "2160p";
+        fps?: number;
+        quality?: "good" | "better" | "best";
+        priority?: "normal" | "high";
+        outputExpiry?: number;
+    }, pollInterval?: number, maxAttempts?: number): Promise<string>;
+}
+export {};

package/dist/src/index.js

@@ -0,0 +1,215 @@
+export class ConvertriloClient {
+    baseUrl;
+    getToken;
+    apiKey;
+    fetchImpl;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.getToken = config.getToken;
+        this.apiKey = config.apiKey;
+        this.fetchImpl = config.fetchImpl || fetch;
+    }
+    async request(path, init = {}) {
+        const headers = {
+            ...init.headers,
+        };
+        if (this.apiKey) {
+            headers["X-API-Key"] = this.apiKey;
+        }
+        else if (this.getToken) {
+            const token = await this.getToken();
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+        }
+        const hasBody = init.body !== undefined;
+        if (hasBody && !headers["Content-Type"]) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`HTTP ${res.status} ${res.statusText}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    // Auth
+    async login(body) {
+        return this.request(`/auth/login`, {
+            method: "POST",
+            body: JSON.stringify(body),
+            headers: { Authorization: "" }, // no auth
+        });
+    }
+    // Tokens
+    async getBalance() {
+        return this.request(`/tokens/balance`);
+    }
+    async reserveTokens(body) {
+        return this.request(`/tokens/reserve`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async releaseTokens(body) {
+        return this.request(`/tokens/release`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async deductTokens(body) {
+        return this.request(`/tokens/deduct`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    // Jobs
+    async createJob(body) {
+        return this.request(`/jobs`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async probeDuration(id) {
+        return this.request(`/jobs/${id}/probe-duration`);
+    }
+    async approveUnified(id, body) {
+        return this.request(`/jobs/${id}/approve-unified`, {
+            method: "POST",
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async confirmJob(id, body) {
+        return this.request(`/jobs/${id}/confirm`, {
+            method: "POST",
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async cancelJob(id) {
+        return this.request(`/jobs/${id}/cancel`, { method: "POST" });
+    }
+    async jobStatus(id) {
+        return this.request(`/jobs/${id}/status`);
+    }
+    // Bulk Jobs
+    async createJobsBulk(body) {
+        return this.request(`/jobs/bulk`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async bulkStatus(ids) {
+        return this.request(`/jobs/bulk/status?ids=${ids.join(",")}`);
+    }
+    async bulkConfirm(body) {
+        return this.request(`/jobs/bulk/confirm`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    // API Keys
+    async getApiKeys() {
+        return this.request(`/api-keys`);
+    }
+    async createApiKey(body) {
+        return this.request(`/api-keys`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async revokeApiKey(id) {
+        return this.request(`/api-keys/${id}`, { method: "DELETE" });
+    }
+    // Webhooks
+    async getWebhooks() {
+        return this.request(`/webhooks`);
+    }
+    async createWebhook(body) {
+        return this.request(`/webhooks`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async deleteWebhook(id) {
+        return this.request(`/webhooks/${id}`, { method: "DELETE" });
+    }
+    async testWebhook(id) {
+        return this.request(`/webhooks/${id}/test`, { method: "POST" });
+    }
+    // Streaming
+    async initStream(id) {
+        return this.request(`/jobs/${id}/stream/init`, { method: "POST" });
+    }
+    async uploadChunk(id, index, data) {
+        return this.request(`/jobs/${id}/stream/chunk/${index}`, {
+            method: "PUT",
+            body: data,
+            headers: { "Content-Type": "application/octet-stream" },
+        });
+    }
+    async finalizeStream(id, body) {
+        return this.request(`/jobs/${id}/stream/finalize`, {
+            method: "POST",
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    async abortStream(id) {
+        return this.request(`/jobs/${id}/stream/abort`, { method: "POST" });
+    }
+    // On-Demand Encoding
+    async onDemandEncode(body) {
+        return this.request(`/ondemand/encode`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async onDemandIngestFolder(body) {
+        return this.request(`/ondemand/ingest/folder`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async onDemandStatus(jobId) {
+        return this.request(`/ondemand/status/${jobId}`);
+    }
+    async onDemandCancel(jobId) {
+        return this.request(`/ondemand/${jobId}`, { method: "DELETE" });
+    }
+    /**
+     * Helper method to encode a video and wait for completion
+     * @param sourceUrl - URL to the video file
+     * @param options - Encoding options
+     * @param pollInterval - Polling interval in milliseconds (default: 5000)
+     * @param maxAttempts - Maximum polling attempts (default: 120)
+     * @returns Download URL when encoding is complete
+     */
+    async onDemandEncodeAndWait(sourceUrl, options = {}, pollInterval = 5000, maxAttempts = 120) {
+        // Submit for encoding
+        const job = await this.onDemandEncode({
+            sourceUrl,
+            ...options,
+        });
+        // Poll for completion
+        let attempts = 0;
+        while (attempts < maxAttempts) {
+            const status = await this.onDemandStatus(job.jobId);
+            if (status.status === "success" && status.downloadUrl) {
+                return status.downloadUrl;
+            }
+            if (status.status === "failed") {
+                throw new Error(status.failureMessage || "Encoding failed");
+            }
+            if (status.status === "canceled") {
+                throw new Error("Job was canceled");
+            }
+            // Wait before next poll
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            attempts++;
+        }
+        throw new Error("Polling timeout: job did not complete in time");
+    }
+}