@videxo/sdk 0.0.0-stage → 0.1.0

package/dist/generated/openapi.js

@@ -0,0 +1,2 @@
+// Generated by `bun run sdk:generate` (packages/sdk scripts/generate.ts) from the api's OpenAPI document. Do not edit.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT, Fonts, Jobs, Outputs, Presets, Uploads, Videxo, Webhooks, type CreateOptions, type RequestOptions, type UploadOptions, type VidexoOptions, type WaitOptions, } from './client.ts';
+export { SDK_ERROR_CODES, VidexoError, VidexoWebhookError, type ApiErrorCode, type SdkErrorCode, type VidexoErrorCode, type VidexoWebhookErrorCode, } from './errors.ts';
+export { MAX_RETRY_AFTER_SECONDS, type RetryPolicy } from './transport.ts';
+export { sendUpload, type SendUploadOptions, type UploadData } from './uploads.ts';
+export { WEBHOOK_TOLERANCE_SECONDS, verifyWebhook, type VerifyWebhookOptions, type WebhookHeaders } from './webhooks.ts';
+export type * from './types.ts';
+export type { components, paths } from './generated/openapi.ts';

package/dist/index.js

@@ -0,0 +1,7 @@
+// @videxo/sdk: the TypeScript client of the Videxo API (README.md). Runs on Node 20+, Bun, Deno and
+// Workers, and `sendUpload()` in browsers: it uses only fetch, Web Streams and WebCrypto.
+export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT, Fonts, Jobs, Outputs, Presets, Uploads, Videxo, Webhooks, } from "./client.js";
+export { SDK_ERROR_CODES, VidexoError, VidexoWebhookError, } from "./errors.js";
+export { MAX_RETRY_AFTER_SECONDS } from "./transport.js";
+export { sendUpload } from "./uploads.js";
+export { WEBHOOK_TOLERANCE_SECONDS, verifyWebhook } from "./webhooks.js";

package/dist/transport.d.ts

@@ -0,0 +1,45 @@
+/**
+ * - `safe`: may run twice (reads, cancel, compile, deleting files, and creations with an
+ *   Idempotency-Key): every retryable failure is retried.
+ * - `rate_limit`: not safe to repeat (`POST /v1/uploads` has no Idempotency-Key): retried only after
+ *   a 429, which the API answers before it does anything.
+ * - `never`: sent once (the one-time upload URL).
+ */
+export type RetryPolicy = 'safe' | 'rate_limit' | 'never';
+/** The `fetch` the SDK sends with: the runtime's own, or one you pass. */
+export type Fetch = (input: Request, init?: RequestInit) => Promise<Response>;
+/**
+ * The runtime's `fetch`, called unbound (some runtimes refuse it called as a method of another
+ * object). The cast is for projects with both Bun's and Node's types, which disagree about `Request`.
+ */
+export declare const runtimeFetch: Fetch;
+export type Transport = {
+    fetch: Fetch;
+    maxRetries: number;
+    /** Per attempt, until the answer's headers (and its body when `buffer` is set) arrive; null for none. */
+    timeoutMs: number | null;
+    /** Removes the API key from a text that might hold it (an error message of a custom fetch). */
+    redact?: (text: string) => string;
+    /** Injected in tests. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    random?: () => number;
+};
+export type SendOptions = {
+    retry: RetryPolicy;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | null | undefined;
+    /** Read the whole body inside the attempt (JSON answers); false hands the stream on (downloads). */
+    buffer: boolean;
+};
+/** A Retry-After longer than this is not waited for: the answer is returned as it is. */
+export declare const MAX_RETRY_AFTER_SECONDS = 60;
+/** The wait before retry `attempt` (0-based) without a Retry-After: 0.5 s doubling to 8 s, with jitter. */
+export declare function backoffMs(attempt: number, random?: () => number): number;
+export declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * `error` with the API key removed from its message: itself when the message does not hold the key,
+ * otherwise a new error of the same name with the redacted message and no cause (a thrown string is
+ * redacted as it is).
+ */
+export declare function redacted(transport: Pick<Transport, 'redact'>, error: unknown): unknown;
+export declare function send(transport: Transport, request: Request, options: SendOptions): Promise<Response>;

package/dist/transport.js

@@ -0,0 +1,148 @@
+import { VidexoError, retryAfterSeconds, sdkError } from "./errors.js";
+/**
+ * The runtime's `fetch`, called unbound (some runtimes refuse it called as a method of another
+ * object). The cast is for projects with both Bun's and Node's types, which disagree about `Request`.
+ */
+export const runtimeFetch = (input, init) => fetch(input, init);
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+/** A Retry-After longer than this is not waited for: the answer is returned as it is. */
+export const MAX_RETRY_AFTER_SECONDS = 60;
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+/** The wait before retry `attempt` (0-based) without a Retry-After: 0.5 s doubling to 8 s, with jitter. */
+export function backoffMs(attempt, random = Math.random) {
+    return Math.min(8_000, 500 * 2 ** attempt) * (0.5 + random() / 2);
+}
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(sdkError('aborted', 'The request was aborted.', { cause: signal.reason }));
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(sdkError('aborted', 'The request was aborted.', { cause: signal?.reason }));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * `error` with the API key removed from its message: itself when the message does not hold the key,
+ * otherwise a new error of the same name with the redacted message and no cause (a thrown string is
+ * redacted as it is).
+ */
+export function redacted(transport, error) {
+    if (!transport.redact || error instanceof VidexoError)
+        return error;
+    if (typeof error === 'string')
+        return transport.redact(error);
+    if (!(error instanceof Error))
+        return error;
+    const message = transport.redact(error.message);
+    const stack = transport.redact(String(error.stack));
+    if (message === error.message && stack === String(error.stack))
+        return error;
+    const copy = new Error(message);
+    copy.name = error.name;
+    copy.stack = stack;
+    return copy;
+}
+/**
+ * `response` with a body that calls `release` once it is read to the end, fails or is cancelled, so
+ * the caller's abort signal keeps reaching the fetch while a download streams.
+ */
+function linkedBody(response, release) {
+    if (!response.body) {
+        release();
+        return response;
+    }
+    const reader = response.body.getReader();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const { done, value } = await reader.read();
+                if (done) {
+                    release();
+                    controller.close();
+                }
+                else
+                    controller.enqueue(value);
+            }
+            catch (error) {
+                release();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            release();
+            await reader.cancel(reason);
+        },
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+const describe = (request) => `${request.method} ${new URL(request.url).pathname}`;
+export async function send(transport, request, options) {
+    const sleep = transport.sleep ?? abortableSleep;
+    const random = transport.random ?? Math.random;
+    const timeoutMs = options.timeoutMs === undefined ? transport.timeoutMs : options.timeoutMs;
+    const maxRetries = options.retry === 'never' ? 0 : transport.maxRetries;
+    for (let attempt = 0;; attempt++) {
+        const last = attempt >= maxRetries;
+        if (options.signal?.aborted)
+            throw sdkError('aborted', `${describe(request)} was aborted.`, { cause: options.signal.reason });
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = timeoutMs === null
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeoutMs);
+        const onAbort = () => controller.abort(options.signal?.reason);
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        const done = () => {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+        };
+        let failure;
+        try {
+            // `as Request`: with both Bun's and Node's types, `clone()` is typed as the other `Request`.
+            const response = await transport.fetch(last ? request : request.clone(), { signal: controller.signal });
+            const retryable = RETRY_STATUSES.has(response.status) && (options.retry === 'safe' || response.status === 429);
+            const retryAfter = retryAfterSeconds(response.headers.get('retry-after'));
+            if (!last && retryable && (retryAfter === null || retryAfter <= MAX_RETRY_AFTER_SECONDS)) {
+                done();
+                await response.body?.cancel().catch(() => undefined);
+                await sleep(retryAfter === null ? backoffMs(attempt, random) : retryAfter * 1000, options.signal);
+                continue;
+            }
+            if (!options.buffer) {
+                // The timeout covers the headers only; the caller's signal stays linked until the body is read.
+                clearTimeout(timer);
+                return linkedBody(response, () => options.signal?.removeEventListener('abort', onAbort));
+            }
+            const text = await response.text();
+            done();
+            return new Response(NULL_BODY_STATUSES.has(response.status) ? null : text, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers,
+            });
+        }
+        catch (error) {
+            done();
+            if (error instanceof VidexoError)
+                throw error;
+            if (options.signal?.aborted)
+                throw sdkError('aborted', `${describe(request)} was aborted.`, { cause: options.signal.reason });
+            const cause = redacted(transport, error);
+            failure = timedOut
+                ? sdkError('timeout', `${describe(request)} got no answer within ${timeoutMs} ms.`, { cause })
+                : sdkError('network_error', `${describe(request)} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+        if (last || options.retry !== 'safe')
+            throw failure;
+        await sleep(backoffMs(attempt, random), options.signal);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { components, paths } from './generated/openapi.ts';
+type Schemas = components['schemas'];
+type JsonBody<T> = T extends {
+    requestBody: {
+        content: {
+            'application/json': infer B;
+        };
+    };
+} ? B : never;
+export type Job = Schemas['Job'];
+export type JobState = Schemas['JobState'];
+export type JobOutput = Schemas['JobOutput'];
+export type JobList = Schemas['JobList'];
+/** `POST /v1/jobs`: a command body or an operations body. */
+export type JobRequest = JsonBody<paths['/v1/jobs']['post']>;
+/** The command body: `command`, `input_files`, `output_files`. */
+export type CommandJobRequest = Schemas['CreateJobRequest'];
+/** The operations body: `inputs`, `outputs`. */
+export type OperationsJobRequest = Schemas['OperationsJobRequest'];
+export type JobSpec = Schemas['JobSpec'];
+export type Output = Schemas['Output'];
+export type ListJobsParams = NonNullable<paths['/v1/jobs']['get']['parameters']['query']>;
+export type CompileRequest = JsonBody<paths['/v1/jobs/compile']['post']>;
+export type CompileResult = Schemas['CompileResult'];
+export type TranscodeRequest = JsonBody<paths['/v1/transcode']['post']>;
+export type ThumbnailsRequest = JsonBody<paths['/v1/thumbnails']['post']>;
+export type StoryboardRequest = JsonBody<paths['/v1/storyboard']['post']>;
+export type GifRequest = JsonBody<paths['/v1/gif']['post']>;
+export type AudioRequest = JsonBody<paths['/v1/audio']['post']>;
+export type ConcatRequest = JsonBody<paths['/v1/concat']['post']>;
+export type Font = Schemas['Font'];
+export type FontList = Schemas['FontList'];
+export type Preset = Schemas['Preset'];
+export type PresetList = Schemas['PresetList'];
+export type Upload = Schemas['Upload'];
+export type CreateUploadRequest = JsonBody<paths['/v1/uploads']['post']>;
+/** The answer of the upload URL once every byte arrived; use `input_url` as a job input. */
+export type CompletedUpload = {
+    id: string;
+    input_url: string;
+    size_bytes: number;
+    sha256: string;
+    content_type: string;
+    expires_at: string;
+};
+export type Problem = Schemas['Problem'];
+export type FieldError = Schemas['FieldError'];
+export type CommandProblem = Schemas['CommandProblem'];
+export type WebhookEventType = Schemas['WebhookEventType'];
+/** The body of every webhook delivery: the event, when the job ended, and the job. */
+export type WebhookEvent = {
+    type: WebhookEventType;
+    timestamp: string;
+    data: Job;
+};
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/uploads.d.ts

@@ -0,0 +1,19 @@
+import type { CompletedUpload } from './types.ts';
+/** What `uploads.upload()` and `sendUpload()` take: a file, a blob, bytes or a stream of bytes. */
+export type UploadData = Blob | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>;
+export type SendUploadOptions = {
+    /** The content type the upload was created with; `application/octet-stream` by default. */
+    contentType?: string;
+    fetch?(input: Request, init?: RequestInit): Promise<Response>;
+    signal?: AbortSignal;
+    /** No timeout by default: a large file may take a while. */
+    timeoutMs?: number | null;
+};
+/** The byte length of `data`, when it can be known without reading it. */
+export declare function sizeOf(data: UploadData): number | null;
+/**
+ * Sends the bytes to an upload's one-time `upload_url` and answers the completed upload. It needs no
+ * API key, so it also runs in a browser with an upload URL your server created. The URL is used up
+ * once the bytes start to flow, so this request is never retried.
+ */
+export declare function sendUpload(uploadUrl: string, data: UploadData, options?: SendUploadOptions): Promise<CompletedUpload>;

package/dist/uploads.js

@@ -0,0 +1,42 @@
+import { errorFromResponse, sdkError } from "./errors.js";
+import { runtimeFetch, send } from "./transport.js";
+/** The byte length of `data`, when it can be known without reading it. */
+export function sizeOf(data) {
+    if (typeof Blob !== 'undefined' && data instanceof Blob)
+        return data.size;
+    if (data instanceof ArrayBuffer || ArrayBuffer.isView(data))
+        return data.byteLength;
+    return null;
+}
+/**
+ * Sends the bytes to an upload's one-time `upload_url` and answers the completed upload. It needs no
+ * API key, so it also runs in a browser with an upload URL your server created. The URL is used up
+ * once the bytes start to flow, so this request is never retried.
+ */
+export async function sendUpload(uploadUrl, data, options = {}) {
+    const stream = typeof ReadableStream !== 'undefined' && data instanceof ReadableStream;
+    // `duplex` is required for a stream body (Node, Deno, Chrome); the DOM types do not have it yet.
+    const init = {
+        method: 'PUT',
+        headers: { 'Content-Type': options.contentType ?? 'application/octet-stream' },
+        body: data,
+        ...(stream ? { duplex: 'half' } : {}),
+    };
+    const request = new Request(uploadUrl, init);
+    const userFetch = options.fetch;
+    const response = await send({ fetch: userFetch ? (input, init) => userFetch(input, init) : runtimeFetch, maxRetries: 0, timeoutMs: options.timeoutMs ?? null }, request, { retry: 'never', signal: options.signal, buffer: true });
+    const text = await response.text();
+    let body = text;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        // Not JSON: kept as text for the error.
+    }
+    if (!response.ok)
+        throw errorFromResponse(response, body);
+    const value = body;
+    if (typeof value !== 'object' || value === null || typeof value.input_url !== 'string')
+        throw sdkError('invalid_response', 'The upload URL answered without the completed upload.', { status: response.status, body });
+    return value;
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,18 @@
+import type { WebhookEvent } from './types.ts';
+/** How far a delivery's `webhook-timestamp` may be from now, either way. */
+export declare const WEBHOOK_TOLERANCE_SECONDS: number;
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined | null>;
+export type VerifyWebhookOptions = {
+    /** Seconds the timestamp may differ from now; 300 by default. */
+    toleranceSeconds?: number;
+    /** The current time in milliseconds, for tests. */
+    now?: number;
+};
+/**
+ * Checks a webhook delivery and answers its event. `body` is the raw request body, exactly as it
+ * arrived (read it as text before any JSON parser touches it); `headers` the request's headers;
+ * `secret` the account's `whsec_` signing secret. Throws a `VidexoWebhookError` when the headers are
+ * missing, the timestamp is more than five minutes away, no `v1` signature matches or the body is not
+ * an event.
+ */
+export declare function verifyWebhook(body: string | Uint8Array | ArrayBuffer, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<WebhookEvent>;

package/dist/webhooks.js

@@ -0,0 +1,85 @@
+import { VidexoWebhookError } from "./errors.js";
+// Standard Webhooks verification with WebCrypto, so it runs in every runtime the SDK does. A
+// delivery is signed `v1,` and base64 HMAC-SHA-256 of `webhook-id.webhook-timestamp.body` with the
+// key after `whsec_`; after a secret rotation it carries a second signature, space separated.
+/** How far a delivery's `webhook-timestamp` may be from now, either way. */
+export const WEBHOOK_TOLERANCE_SECONDS = 5 * 60;
+const encoder = new TextEncoder();
+function header(headers, name) {
+    if (typeof Headers !== 'undefined' && headers instanceof Headers)
+        return headers.get(name);
+    const record = headers;
+    const key = Object.keys(record).find((candidate) => candidate.toLowerCase() === name);
+    const value = key === undefined ? undefined : record[key];
+    if (Array.isArray(value))
+        return value.join(' ');
+    return value ?? null;
+}
+function fromBase64(text) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(text) || text.length % 4 !== 0)
+        return null;
+    try {
+        return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Checks a webhook delivery and answers its event. `body` is the raw request body, exactly as it
+ * arrived (read it as text before any JSON parser touches it); `headers` the request's headers;
+ * `secret` the account's `whsec_` signing secret. Throws a `VidexoWebhookError` when the headers are
+ * missing, the timestamp is more than five minutes away, no `v1` signature matches or the body is not
+ * an event.
+ */
+export async function verifyWebhook(body, headers, secret, options = {}) {
+    const id = header(headers, 'webhook-id');
+    const timestamp = header(headers, 'webhook-timestamp');
+    const signatures = header(headers, 'webhook-signature');
+    if (!id || !timestamp || !signatures)
+        throw new VidexoWebhookError('missing_headers', 'The webhook-id, webhook-timestamp and webhook-signature headers are required.');
+    const key = fromBase64(secret.startsWith('whsec_') ? secret.slice('whsec_'.length) : secret);
+    if (!key || key.length === 0)
+        throw new VidexoWebhookError('invalid_secret', 'The secret is not a whsec_ signing secret.');
+    if (!/^\d{1,15}$/.test(timestamp))
+        throw new VidexoWebhookError('invalid_timestamp', 'The webhook-timestamp header is not a number.');
+    const tolerance = options.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    const now = Math.floor((options.now ?? Date.now()) / 1000);
+    if (Math.abs(now - Number(timestamp)) > tolerance)
+        throw new VidexoWebhookError('invalid_timestamp', 'The webhook-timestamp is too far from the current time.');
+    // The signature covers the body's bytes exactly as they arrived; they are decoded only once it matched.
+    const bytes = typeof body === 'string' ? encoder.encode(body) : body instanceof ArrayBuffer ? new Uint8Array(body) : body;
+    const prefix = encoder.encode(`${id}.${timestamp}.`);
+    const signed = new Uint8Array(prefix.length + bytes.length);
+    signed.set(prefix);
+    signed.set(bytes, prefix.length);
+    const hmac = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    let matched = false;
+    for (const entry of signatures.split(' ')) {
+        const [version, signature] = entry.split(',', 2);
+        if (version !== 'v1' || !signature)
+            continue;
+        const mac = fromBase64(signature);
+        // crypto.subtle.verify compares in constant time.
+        if (mac && (await crypto.subtle.verify('HMAC', hmac, mac, signed)))
+            matched = true;
+    }
+    if (!matched)
+        throw new VidexoWebhookError('invalid_signature', 'No v1 signature matches the body.');
+    let event;
+    try {
+        const text = typeof body === 'string' ? body : new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+        event = JSON.parse(text);
+    }
+    catch {
+        throw new VidexoWebhookError('invalid_payload', 'The body is not JSON in UTF-8.');
+    }
+    const value = event;
+    if (typeof value !== 'object' ||
+        value === null ||
+        typeof value.type !== 'string' ||
+        typeof value.data !== 'object' ||
+        value.data === null)
+        throw new VidexoWebhookError('invalid_payload', 'The body is not a webhook event.');
+    return event;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@videxo/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The TypeScript client of the Videxo API: hosted ffmpeg jobs over HTTP.",
+  "license": "MIT",
+  "author": "Videxo",
+  "homepage": "https://videxo.io/docs/sdk",
+  "keywords": [
+    "videxo",
+    "ffmpeg",
+    "video",
+    "transcode",
+    "api",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json && tsc -p tsconfig.test.json && bun run build && bun scripts/pack-check.ts",
+    "build": "bun scripts/build.ts",
+    "generate": "bun scripts/generate.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.13.0",
+    "typescript": "~6.0.3",
+    "vitest": "^5.1.0"
+  }
+}