@videxo/sdk 0.0.0-stage → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,217 @@
+import { type Client } from 'openapi-fetch';
+import { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT } from './defaults.ts';
+import type { paths } from './generated/openapi.ts';
+import { type RetryPolicy, type Transport } from './transport.ts';
+import type { AudioRequest, ClientToken, CompileRequest, CompileResult, CompletedUpload, ConcatRequest, CreateClientTokenRequest, CreateUploadRequest, GifRequest, Job, JobList, JobRequest, ListJobsParams, FontList, PresetList, ProbeRequest, ProbeResponse, ScenesRequest, SlideshowRequest, StoryboardRequest, ThumbnailsRequest, TranscodeRequest, Upload, WebhookEvent } from './types.ts';
+import { type UploadData } from './uploads.ts';
+import { type VerifyWebhookOptions, type WebhookHeaders } from './webhooks.ts';
+export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT };
+export type VidexoOptions = {
+    /**
+     * An API key from the dashboard (`vdx_...`). Keep it on a server, never in browser code. Typed to
+     * take an unset environment variable (`process.env.VIDEXO_API_KEY`): the constructor throws then.
+     */
+    apiKey: string | undefined;
+    /** `https://api.videxo.io` by default. */
+    baseUrl?: string;
+    /** The `fetch` to send requests with; the runtime's own by default. */
+    fetch?(input: Request, init?: RequestInit): Promise<Response>;
+    /** Retries of a failed request (429, 502, 503, 504, a timeout, a network error); 2 by default. */
+    maxRetries?: number;
+    /** Per attempt, until the whole answer arrived (a download: its headers); 60 seconds by default. */
+    timeoutMs?: number;
+};
+export type RequestOptions = {
+    signal?: AbortSignal;
+    /** Overrides the client's `timeoutMs` for this call. */
+    timeoutMs?: number;
+};
+export type CreateOptions = RequestOptions & {
+    /**
+     * Makes the creation safe to retry for 24 hours. The SDK sends a new random key when you leave it
+     * out, and reuses it on its own retries; pass your own (an order id) to also cover your retries.
+     */
+    idempotencyKey?: string;
+};
+export type WaitOptions = {
+    /** How long to wait for the job to end; 10 minutes by default. */
+    timeoutMs?: number;
+    /** Between two reads of the job; 2 seconds by default. */
+    intervalMs?: number;
+    signal?: AbortSignal;
+};
+export type UploadOptions = RequestOptions & {
+    /** A plain file name: letters, digits, dots, underscores and hyphens. */
+    filename: string;
+    /** The type a job sees; the blob's own type or `application/octet-stream` by default. */
+    contentType?: string;
+    /** The exact byte length; needed for a stream, read from the data otherwise. */
+    size?: number;
+    /** For sending the bytes; no timeout by default, as a large file may take a while. */
+    uploadTimeoutMs?: number;
+};
+export type ClientTokenForUploadOptions = RequestOptions & {
+    /** Your own opaque id of the end user. */
+    subject: string;
+    /** The largest file the app may upload, in bytes. */
+    maxSizeBytes: number;
+    /** Media types the upload may declare, exact or `type/*`; video, audio and images by default. */
+    contentTypes?: string[];
+    /** Lifetime in seconds, 60 to 21600; 900 by default. */
+    ttlSeconds?: number;
+};
+export type ClientTokenForJobOptions = RequestOptions & {
+    /** Your own opaque id of the end user; a continuation keeps its chain's. */
+    subject?: string;
+    /** The app's token id: the new token continues its chain and adds the job. */
+    continues?: string;
+    /** Lifetime in seconds, 60 to 21600; 900 by default. */
+    ttlSeconds?: number;
+};
+type Result<T> = {
+    data?: T;
+    error?: unknown;
+    response: Response;
+};
+/**
+ * The Videxo API client. One instance per API key; it holds no connection and is cheap to create.
+ *
+ * ```ts
+ * const videxo = new Videxo({ apiKey: process.env.VIDEXO_API_KEY });
+ * const job = await videxo.transcode({ input: 'https://example.com/talk.mp4', preset: 'web-720p' });
+ * const done = await videxo.jobs.wait(job.id);
+ * ```
+ */
+export declare class Videxo {
+    readonly baseUrl: string;
+    readonly jobs: Jobs;
+    readonly presets: Presets;
+    readonly fonts: Fonts;
+    readonly uploads: Uploads;
+    readonly outputs: Outputs;
+    readonly webhooks: Webhooks;
+    readonly clientTokens: ClientTokens;
+    /** @internal */
+    readonly transport: Transport;
+    /** @internal */
+    readonly client: Client<paths>;
+    constructor(options: VidexoOptions);
+    /** @internal The per-request `fetch` that openapi-fetch calls: the transport with this call's policy. */
+    fetchFor(retry: RetryPolicy, options?: RequestOptions): (request: Request) => Promise<Response>;
+    /** @internal The data of a 2xx answer, or the error of any other. */
+    unwrap<T>(pending: Promise<Result<T>>): Promise<T>;
+    /** @internal A job creation at `path`, with an Idempotency-Key that its retries reuse. */
+    createAt<T = Job>(path: CreatePath, body: unknown, options?: CreateOptions): Promise<T>;
+    /** `POST /v1/transcode`: one video output from `input`, from a preset or your own options. */
+    transcode(body: TranscodeRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/thumbnails`: one image at `at`, or one per time in `times`. */
+    thumbnails(body: ThumbnailsRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/storyboard`: frames at a fixed interval in a grid on one image. */
+    storyboard(body: StoryboardRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/gif`: an animated GIF with its own palette. */
+    gif(body: GifRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/audio`: the sound of `input` as an audio file. */
+    audio(body: AudioRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/concat`: the `inputs` one after another, as one file. */
+    concat(body: ConcatRequest, options?: CreateOptions): Promise<Job>;
+    /** `POST /v1/slideshow`: the still `images` as one video, each held for a time, with an optional motion. */
+    slideshow(body: SlideshowRequest, options?: CreateOptions): Promise<Job>;
+    /**
+     * `POST /v1/probe`: the container, duration and streams of `input`, read with ffprobe. The api waits
+     * up to 25 seconds; a job still running then is waited for here (`wait`), and its document read from
+     * its output file. A job that failed is answered, not thrown: `probe` is null and `error` says why.
+     */
+    probe(body: ProbeRequest, options?: CreateOptions & {
+        wait?: Omit<WaitOptions, 'signal'>;
+    }): Promise<ProbeResponse>;
+    /** `POST /v1/scenes`: the scenes of `input`, with their times and scores, as a JSON file. */
+    scenes(body: ScenesRequest, options?: CreateOptions): Promise<Job>;
+}
+type CreatePath = '/v1/jobs' | '/v1/transcode' | '/v1/thumbnails' | '/v1/storyboard' | '/v1/gif' | '/v1/audio' | '/v1/concat' | '/v1/slideshow' | '/v1/probe' | '/v1/scenes';
+export declare class Jobs {
+    #private;
+    constructor(videxo: Videxo);
+    /** `POST /v1/jobs`: a command body (`command`, `input_files`, `output_files`) or an operations body (`inputs`, `outputs`). */
+    create(body: JobRequest, options?: CreateOptions): Promise<Job>;
+    /** `GET /v1/jobs/{id}`. */
+    get(id: string, options?: RequestOptions): Promise<Job>;
+    /** `GET /v1/jobs`: one page, newest first; pass its `next_cursor` as `cursor` for the next. */
+    page(params?: ListJobsParams, options?: RequestOptions): Promise<JobList>;
+    /** Every job, newest first, reading page after page as you iterate (`for await (const job of videxo.jobs.list())`). */
+    list(params?: ListJobsParams, options?: RequestOptions): AsyncGenerator<Job, void, undefined>;
+    /** `POST /v1/jobs/{id}/cancel`: a queued or running job becomes cancelled; an ended one is answered as it is. */
+    cancel(id: string, options?: RequestOptions): Promise<Job>;
+    /** `DELETE /v1/jobs/{id}/files`: deletes an ended job's stored outputs now. */
+    deleteFiles(id: string, options?: RequestOptions): Promise<Job>;
+    /** `POST /v1/jobs/compile`: the spec, command and `ffmpeg_command` a job would get; no job is made. */
+    compile(body: CompileRequest, options?: RequestOptions): Promise<CompileResult>;
+    /**
+     * Reads the job until it is `succeeded`, `failed` or `cancelled` and answers it then (a failed job
+     * is answered, not thrown: see `job.error`). Waits out a 429 by its `Retry-After`. Throws
+     * `wait_timeout` when the job has not ended within `timeoutMs`, `aborted` when `signal` fires.
+     */
+    wait(id: string, options?: WaitOptions): Promise<Job>;
+}
+export declare class Presets {
+    #private;
+    constructor(videxo: Videxo);
+    /** `GET /v1/presets`: every preset with its type, its full options and whether it is deprecated. */
+    list(options?: RequestOptions): Promise<PresetList>;
+}
+export declare class Fonts {
+    #private;
+    constructor(videxo: Videxo);
+    /** `GET /v1/fonts`: the fonts a text layer can name, with their family, weight, scripts and licence. */
+    list(options?: RequestOptions): Promise<FontList>;
+}
+export declare class Uploads {
+    #private;
+    constructor(videxo: Videxo);
+    /**
+     * `POST /v1/uploads`: a one-time upload URL for a private input. The route takes no
+     * Idempotency-Key, so only a 429 is retried.
+     */
+    create(params: CreateUploadRequest, options?: RequestOptions): Promise<Upload>;
+    /**
+     * Creates an upload and sends the bytes to its URL; answers the completed upload, whose
+     * `input_url` (`videxo://uploads/<id>`) a job takes as an input.
+     */
+    upload(data: UploadData, options: UploadOptions): Promise<CompletedUpload>;
+}
+export declare class Outputs {
+    #private;
+    constructor(videxo: Videxo);
+    /**
+     * A fresh signed download URL of one output (`GET /v1/jobs/{id}/outputs/{alias}`). `output` is its
+     * alias (`out_video`), or its name or file name when only one file of the job has it.
+     */
+    url(jobId: string, output: string, options?: RequestOptions): Promise<string>;
+    /**
+     * The output's bytes as a `Response` (stream `response.body`, or read it with `arrayBuffer()`),
+     * fetched from a fresh signed URL. The API key is not sent to the file URL.
+     */
+    download(jobId: string, output: string, options?: RequestOptions): Promise<Response>;
+}
+/**
+ * Client tokens for apps and web pages (ADR 016): short-lived, narrowly scoped, minted here on your
+ * server. Hand the answer's `token` and `id` to the app, which uses `@videxo/sdk/client`. Minting
+ * supersedes nothing, so a lost answer is retried by minting again.
+ */
+export declare class ClientTokens {
+    #private;
+    constructor(videxo: Videxo);
+    /** `POST /v1/client-tokens`: a token with the grant you describe; `continues` refreshes a chain. */
+    create(grant: CreateClientTokenRequest, options?: RequestOptions): Promise<ClientToken>;
+    /** A token for one upload by `subject`: what an app needs before it knows of any job. */
+    forUpload({ subject, maxSizeBytes, contentTypes, ttlSeconds, ...options }: ClientTokenForUploadOptions): Promise<ClientToken>;
+    /** A token that reads one job: a new one, or with `continues` the next of the app's chain, adding the job. */
+    forJob(jobId: string, { subject, continues, ttlSeconds, ...options }?: ClientTokenForJobOptions): Promise<ClientToken>;
+    /** `DELETE /v1/client-tokens/{id}`: ends the token and its whole chain. Revoking again is fine. */
+    revoke(id: string, options?: RequestOptions): Promise<void>;
+    /** `POST /v1/client-tokens/revoke`: ends every chain of the end user; answers how many tokens. */
+    revokeSubject(subject: string, options?: RequestOptions): Promise<number>;
+}
+export declare class Webhooks {
+    /** Checks a delivery's Standard Webhooks signature and answers its event (`verifyWebhook`). */
+    verify(body: string | Uint8Array | ArrayBuffer, headers: WebhookHeaders, secret: string, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
+}

package/dist/client.js

@@ -0,0 +1,403 @@
+import createClient, {} from 'openapi-fetch';
+import { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT } from "./defaults.js";
+import { VidexoError, errorFromResponse, sdkError } from "./errors.js";
+import { abortableSleep, redacted, runtimeFetch, send } from "./transport.js";
+import { sendUpload, sizeOf } from "./uploads.js";
+import { verifyWebhook } from "./webhooks.js";
+export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, DEFAULT_WAIT };
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+const OUTPUT_ALIAS = /^out_[A-Za-z0-9_]{1,48}$/;
+/** What an API key may hold: printable ASCII without spaces (the `Authorization` header carries it as is). */
+const API_KEY_PATTERN = /^[\x21-\x7e]+$/;
+/**
+ * The Videxo API client. One instance per API key; it holds no connection and is cheap to create.
+ *
+ * ```ts
+ * const videxo = new Videxo({ apiKey: process.env.VIDEXO_API_KEY });
+ * const job = await videxo.transcode({ input: 'https://example.com/talk.mp4', preset: 'web-720p' });
+ * const done = await videxo.jobs.wait(job.id);
+ * ```
+ */
+export class Videxo {
+    baseUrl;
+    jobs;
+    presets;
+    fonts;
+    uploads;
+    outputs;
+    webhooks;
+    clientTokens;
+    /** @internal */
+    transport;
+    /** @internal */
+    client;
+    constructor(options) {
+        const apiKey = typeof options?.apiKey === 'string' ? options.apiKey.trim() : '';
+        if (!apiKey)
+            throw new TypeError('new Videxo() needs an apiKey: an API key from the dashboard, kept on your server.');
+        // Checked here so that no runtime refuses the Authorization header later with the key in its message.
+        if (!API_KEY_PATTERN.test(apiKey))
+            throw new TypeError('The apiKey is not valid: an API key has only printable ASCII characters, without spaces or line breaks.');
+        const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        if (!/^https?:\/\//.test(baseUrl))
+            throw new TypeError('baseUrl must be an http or https URL.');
+        const userFetch = options.fetch;
+        this.baseUrl = baseUrl;
+        this.transport = {
+            fetch: userFetch ? (input, init) => userFetch(input, init) : runtimeFetch,
+            maxRetries: Math.max(0, Math.floor(options.maxRetries ?? DEFAULT_MAX_RETRIES)),
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            redact: (text) => text.replaceAll(apiKey, '[api key]'),
+        };
+        this.client = createClient({ baseUrl, headers: { Authorization: `Bearer ${apiKey}` } });
+        this.jobs = new Jobs(this);
+        this.presets = new Presets(this);
+        this.fonts = new Fonts(this);
+        this.uploads = new Uploads(this);
+        this.outputs = new Outputs(this);
+        this.webhooks = new Webhooks();
+        this.clientTokens = new ClientTokens(this);
+    }
+    /** @internal The per-request `fetch` that openapi-fetch calls: the transport with this call's policy. */
+    fetchFor(retry, options = {}) {
+        return (request) => send(this.transport, request, { retry, signal: options.signal, timeoutMs: options.timeoutMs, buffer: true });
+    }
+    /** @internal The data of a 2xx answer, or the error of any other. */
+    async unwrap(pending) {
+        let result;
+        try {
+            result = await pending;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                throw sdkError('invalid_response', 'The API answered with a body that is not JSON.', { cause: error });
+            throw redacted(this.transport, error);
+        }
+        if (!result.response.ok)
+            throw errorFromResponse(result.response, result.error);
+        if (result.data === undefined)
+            throw sdkError('invalid_response', 'The API answered without a body.', { status: result.response.status });
+        return result.data;
+    }
+    /** @internal A job creation at `path`, with an Idempotency-Key that its retries reuse. */
+    createAt(path, body, options = {}) {
+        const key = options.idempotencyKey ?? crypto.randomUUID();
+        return this.unwrap(this.client.POST(path, {
+            body: body,
+            params: { header: { 'idempotency-key': key } },
+            fetch: this.fetchFor('safe', options),
+        }));
+    }
+    /** `POST /v1/transcode`: one video output from `input`, from a preset or your own options. */
+    transcode(body, options) {
+        return this.createAt('/v1/transcode', body, options);
+    }
+    /** `POST /v1/thumbnails`: one image at `at`, or one per time in `times`. */
+    thumbnails(body, options) {
+        return this.createAt('/v1/thumbnails', body, options);
+    }
+    /** `POST /v1/storyboard`: frames at a fixed interval in a grid on one image. */
+    storyboard(body, options) {
+        return this.createAt('/v1/storyboard', body, options);
+    }
+    /** `POST /v1/gif`: an animated GIF with its own palette. */
+    gif(body, options) {
+        return this.createAt('/v1/gif', body, options);
+    }
+    /** `POST /v1/audio`: the sound of `input` as an audio file. */
+    audio(body, options) {
+        return this.createAt('/v1/audio', body, options);
+    }
+    /** `POST /v1/concat`: the `inputs` one after another, as one file. */
+    concat(body, options) {
+        return this.createAt('/v1/concat', body, options);
+    }
+    /** `POST /v1/slideshow`: the still `images` as one video, each held for a time, with an optional motion. */
+    slideshow(body, options) {
+        return this.createAt('/v1/slideshow', body, options);
+    }
+    /**
+     * `POST /v1/probe`: the container, duration and streams of `input`, read with ffprobe. The api waits
+     * up to 25 seconds; a job still running then is waited for here (`wait`), and its document read from
+     * its output file. A job that failed is answered, not thrown: `probe` is null and `error` says why.
+     */
+    async probe(body, options = {}) {
+        const answer = await this.createAt('/v1/probe', body, options);
+        if (TERMINAL.has(answer.state))
+            return answer;
+        const job = await this.jobs.wait(answer.id, { ...options.wait, signal: options.signal });
+        if (job.state !== 'succeeded')
+            return { ...job, probe: null };
+        const file = await this.outputs.download(job.id, 'out_metadata', { signal: options.signal });
+        return { ...job, probe: (await file.json()) };
+    }
+    /** `POST /v1/scenes`: the scenes of `input`, with their times and scores, as a JSON file. */
+    scenes(body, options) {
+        return this.createAt('/v1/scenes', body, options);
+    }
+}
+export class Jobs {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /** `POST /v1/jobs`: a command body (`command`, `input_files`, `output_files`) or an operations body (`inputs`, `outputs`). */
+    create(body, options) {
+        return this.#videxo.createAt('/v1/jobs', body, options);
+    }
+    /** `GET /v1/jobs/{id}`. */
+    get(id, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.GET('/v1/jobs/{id}', { params: { path: { id } }, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /** `GET /v1/jobs`: one page, newest first; pass its `next_cursor` as `cursor` for the next. */
+    page(params = {}, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.GET('/v1/jobs', { params: { query: params }, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /** Every job, newest first, reading page after page as you iterate (`for await (const job of videxo.jobs.list())`). */
+    async *list(params = {}, options = {}) {
+        let cursor = params.cursor;
+        for (;;) {
+            const page = await this.page({ ...params, ...(cursor === undefined ? {} : { cursor }) }, options);
+            yield* page.data;
+            if (!page.next_cursor)
+                return;
+            cursor = page.next_cursor;
+        }
+    }
+    /** `POST /v1/jobs/{id}/cancel`: a queued or running job becomes cancelled; an ended one is answered as it is. */
+    cancel(id, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.POST('/v1/jobs/{id}/cancel', { params: { path: { id } }, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /** `DELETE /v1/jobs/{id}/files`: deletes an ended job's stored outputs now. */
+    deleteFiles(id, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.DELETE('/v1/jobs/{id}/files', { params: { path: { id } }, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /** `POST /v1/jobs/compile`: the spec, command and `ffmpeg_command` a job would get; no job is made. */
+    compile(body, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.POST('/v1/jobs/compile', { body, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /**
+     * Reads the job until it is `succeeded`, `failed` or `cancelled` and answers it then (a failed job
+     * is answered, not thrown: see `job.error`). Waits out a 429 by its `Retry-After`. Throws
+     * `wait_timeout` when the job has not ended within `timeoutMs`, `aborted` when `signal` fires.
+     */
+    async wait(id, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_WAIT.timeoutMs;
+        const intervalMs = options.intervalMs ?? DEFAULT_WAIT.intervalMs;
+        const sleep = this.#videxo.transport.sleep ?? abortableSleep;
+        // The deadline also stops a read in flight and the retry pauses inside it (a 429's Retry-After).
+        const deadline = new AbortController();
+        const onAbort = () => deadline.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            onAbort();
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        const timer = setTimeout(() => deadline.abort(), timeoutMs);
+        let job;
+        const timedOut = () => sdkError('wait_timeout', `Job ${id} did not end within ${timeoutMs} ms.`, { body: job });
+        try {
+            for (;;) {
+                let pause = intervalMs;
+                try {
+                    job = await this.get(id, { signal: deadline.signal });
+                    if (TERMINAL.has(job.state))
+                        return job;
+                }
+                catch (error) {
+                    if (!(error instanceof VidexoError && error.status === 429))
+                        throw error;
+                    pause = Math.max(intervalMs, (error.retryAfter ?? 0) * 1000);
+                }
+                if (deadline.signal.aborted)
+                    throw timedOut();
+                await sleep(pause, deadline.signal);
+            }
+        }
+        catch (error) {
+            if (error instanceof VidexoError && error.code === 'aborted' && !options.signal?.aborted)
+                throw timedOut();
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+export class Presets {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /** `GET /v1/presets`: every preset with its type, its full options and whether it is deprecated. */
+    list(options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.GET('/v1/presets', { fetch: videxo.fetchFor('safe', options) }));
+    }
+}
+export class Fonts {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /** `GET /v1/fonts`: the fonts a text layer can name, with their family, weight, scripts and licence. */
+    list(options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.GET('/v1/fonts', { fetch: videxo.fetchFor('safe', options) }));
+    }
+}
+export class Uploads {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /**
+     * `POST /v1/uploads`: a one-time upload URL for a private input. The route takes no
+     * Idempotency-Key, so only a 429 is retried.
+     */
+    create(params, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.POST('/v1/uploads', { body: params, fetch: videxo.fetchFor('rate_limit', options) }));
+    }
+    /**
+     * Creates an upload and sends the bytes to its URL; answers the completed upload, whose
+     * `input_url` (`videxo://uploads/<id>`) a job takes as an input.
+     */
+    async upload(data, options) {
+        const size = options.size ?? sizeOf(data);
+        if (size === null)
+            throw new TypeError('uploads.upload() needs options.size for a stream.');
+        const blobType = typeof Blob !== 'undefined' && data instanceof Blob ? data.type : '';
+        const contentType = options.contentType ?? (blobType || 'application/octet-stream');
+        const upload = await this.create({ filename: options.filename, size_bytes: size, content_type: contentType }, options);
+        return sendUpload(upload.upload_url, data, {
+            contentType,
+            fetch: this.#videxo.transport.fetch,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.uploadTimeoutMs === undefined ? {} : { timeoutMs: options.uploadTimeoutMs }),
+        });
+    }
+}
+export class Outputs {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /**
+     * A fresh signed download URL of one output (`GET /v1/jobs/{id}/outputs/{alias}`). `output` is its
+     * alias (`out_video`), or its name or file name when only one file of the job has it.
+     */
+    async url(jobId, output, options = {}) {
+        const videxo = this.#videxo;
+        const alias = await this.#alias(jobId, output, options);
+        const pending = videxo.client.GET('/v1/jobs/{id}/outputs/{alias}', {
+            params: { path: { id: jobId, alias } },
+            redirect: 'manual',
+            parseAs: 'text',
+            fetch: videxo.fetchFor('safe', options),
+        });
+        const { response, error } = await pending.catch((failure) => {
+            throw redacted(videxo.transport, failure);
+        });
+        const location = response.headers.get('location');
+        if (response.status >= 300 && response.status < 400 && location)
+            return new URL(location, videxo.baseUrl).href;
+        if (!response.ok && response.type !== 'opaqueredirect')
+            throw errorFromResponse(response, error);
+        throw sdkError('invalid_response', 'The API did not answer with the download URL.', { status: response.status });
+    }
+    /**
+     * The output's bytes as a `Response` (stream `response.body`, or read it with `arrayBuffer()`),
+     * fetched from a fresh signed URL. The API key is not sent to the file URL.
+     */
+    async download(jobId, output, options = {}) {
+        const url = await this.url(jobId, output, options);
+        const response = await send(this.#videxo.transport, new Request(url), {
+            retry: 'safe',
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            buffer: false,
+        });
+        if (response.ok)
+            return response;
+        const text = await response.text();
+        let body = text;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // Not JSON: kept as text.
+        }
+        throw errorFromResponse(response, body);
+    }
+    async #alias(jobId, output, options) {
+        if (OUTPUT_ALIAS.test(output))
+            return output;
+        const job = await this.#videxo.jobs.get(jobId, options);
+        const aliases = [...new Set(job.outputs.filter((file) => file.name === output || file.filename === output).map((file) => file.alias))];
+        if (aliases.length === 1)
+            return aliases[0];
+        if (aliases.length === 0)
+            throw sdkError('output_not_found', `Job ${jobId} has no output named ${output}.`);
+        throw sdkError('output_ambiguous', `Several files of job ${jobId} are named ${output}: ${aliases.join(', ')}.`);
+    }
+}
+/**
+ * Client tokens for apps and web pages (ADR 016): short-lived, narrowly scoped, minted here on your
+ * server. Hand the answer's `token` and `id` to the app, which uses `@videxo/sdk/client`. Minting
+ * supersedes nothing, so a lost answer is retried by minting again.
+ */
+export class ClientTokens {
+    #videxo;
+    constructor(videxo) {
+        this.#videxo = videxo;
+    }
+    /** `POST /v1/client-tokens`: a token with the grant you describe; `continues` refreshes a chain. */
+    create(grant, options = {}) {
+        const videxo = this.#videxo;
+        return videxo.unwrap(videxo.client.POST('/v1/client-tokens', { body: grant, fetch: videxo.fetchFor('safe', options) }));
+    }
+    /** A token for one upload by `subject`: what an app needs before it knows of any job. */
+    forUpload({ subject, maxSizeBytes, contentTypes, ttlSeconds, ...options }) {
+        return this.create({
+            subject,
+            uploads: { max_count: 1, max_size_bytes: maxSizeBytes, ...(contentTypes ? { content_types: contentTypes } : {}) },
+            ...(ttlSeconds === undefined ? {} : { ttl_seconds: ttlSeconds }),
+        }, options);
+    }
+    /** A token that reads one job: a new one, or with `continues` the next of the app's chain, adding the job. */
+    forJob(jobId, { subject, continues, ttlSeconds, ...options } = {}) {
+        return this.create({
+            jobs: { read: [jobId] },
+            ...(subject === undefined ? {} : { subject }),
+            ...(continues === undefined ? {} : { continues }),
+            ...(ttlSeconds === undefined ? {} : { ttl_seconds: ttlSeconds }),
+        }, options);
+    }
+    /** `DELETE /v1/client-tokens/{id}`: ends the token and its whole chain. Revoking again is fine. */
+    async revoke(id, options = {}) {
+        const videxo = this.#videxo;
+        const pending = videxo.client.DELETE('/v1/client-tokens/{id}', { params: { path: { id } }, fetch: videxo.fetchFor('safe', options) });
+        const { response, error } = (await pending.catch((failure) => {
+            throw redacted(videxo.transport, failure);
+        }));
+        if (!response.ok)
+            throw errorFromResponse(response, error);
+    }
+    /** `POST /v1/client-tokens/revoke`: ends every chain of the end user; answers how many tokens. */
+    async revokeSubject(subject, options = {}) {
+        const videxo = this.#videxo;
+        const { revoked } = await videxo.unwrap(videxo.client.POST('/v1/client-tokens/revoke', { body: { subject }, fetch: videxo.fetchFor('safe', options) }));
+        return revoked;
+    }
+}
+export class Webhooks {
+    /** Checks a delivery's Standard Webhooks signature and answers its event (`verifyWebhook`). */
+    verify(body, headers, secret, options) {
+        return verifyWebhook(body, headers, secret, options);
+    }
+}

package/dist/defaults.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_BASE_URL = "https://api.videxo.io";
+export declare const DEFAULT_MAX_RETRIES = 2;
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+export declare const DEFAULT_WAIT: Readonly<{
+    timeoutMs: number;
+    intervalMs: 2000;
+}>;

package/dist/defaults.js

@@ -0,0 +1,6 @@
+// The defaults the keyed client and the app client share, apart from both so that one can be
+// bundled without the other.
+export const DEFAULT_BASE_URL = 'https://api.videxo.io';
+export const DEFAULT_MAX_RETRIES = 2;
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export const DEFAULT_WAIT = Object.freeze({ timeoutMs: 10 * 60_000, intervalMs: 2_000 });