@videxo/sdk 0.1.0 → 0.2.0

package/README.md

@@ -16,8 +16,9 @@ Cloudflare Workers. In a browser, use only `sendUpload()` with a `File`, `Blob`
 ## Keep the API key on a server
 
 The API key gives full access to your account. Use it only in server code (a route handler, a
-worker, a job queue), never in code that runs in a browser or an app. A browser only sends files
-to an upload URL your server created, with `sendUpload()`, which needs no key.
+worker, a job queue), never in code that runs in a browser or an app. An app or a web page uses
+`@videxo/sdk/client` with a [client token](https://videxo.io/docs/client-tokens) your server mints,
+or sends files to an upload URL your server created, with `sendUpload()`, which needs no key.
 
 ## Use it
 
@@ -38,7 +39,7 @@ if (done.state === 'succeeded') {
 |---|---|
 | `new Videxo({ apiKey, baseUrl?, fetch?, maxRetries?, timeoutMs? })` | `baseUrl` is `https://api.videxo.io` by default; throws without a key |
 | `jobs.create(body, { idempotencyKey? })` | `POST /v1/jobs`, a command body or an operations body |
-| `transcode`, `thumbnails`, `storyboard`, `gif`, `audio`, `concat` | `POST /v1/<operation>` |
+| `transcode`, `thumbnails`, `storyboard`, `gif`, `audio`, `concat`, `slideshow`, `scenes` | `POST /v1/<operation>` |
 | `jobs.get(id)`, `jobs.cancel(id)`, `jobs.deleteFiles(id)` | `GET /v1/jobs/{id}`, `POST .../cancel`, `DELETE .../files` |
 | `jobs.list(params)`, `jobs.page(params)` | `GET /v1/jobs`: every job as an async iterator, or one page |
 | `jobs.wait(id, { timeoutMs?, intervalMs?, signal? })` | polls until `succeeded`, `failed` or `cancelled` |
@@ -49,6 +50,14 @@ if (done.state === 'succeeded') {
 | `outputs.url(jobId, output)`, `outputs.download(jobId, output)` | `GET /v1/jobs/{id}/outputs/{alias}`: a fresh signed link, or the file |
 | `webhooks.verify(body, headers, secret)`, `verifyWebhook(...)` | Standard Webhooks signature check; answers the event |
 | `sendUpload(uploadUrl, data, { contentType? })` | the PUT alone, without a key |
+| `clientTokens.create(grant)`, `clientTokens.forUpload(...)`, `clientTokens.forJob(jobId, ...)` | `POST /v1/client-tokens`: answers `id` and `token` for the app |
+| `clientTokens.revoke(id)`, `clientTokens.revokeSubject(subject)` | ends a chain, or every chain of an end user |
+
+`@videxo/sdk/client` is a separate entry point for apps and web pages, without the keyed client:
+`new VidexoClient({ token, tokenId?, baseUrl?, getToken? })` with `uploads.create`,
+`uploads.upload(file, { filename, onProgress })`, `jobs.get`, `jobs.list`, `jobs.wait` and `token()`.
+`getToken({ tokenId })` asks your server for a continuation when the token is about to expire or is
+refused as expired or superseded. The constructor refuses a value shaped like an API key.
 
 The docs page [TypeScript SDK](https://videxo.io/docs/sdk) covers each call with examples.
 

package/dist/app-client.d.ts

@@ -0,0 +1,112 @@
+import { type RetryPolicy, type Transport } from './transport.ts';
+import type { ClientJob, ClientTokenInfo, CompletedUpload, CreateUploadRequest, Upload } from './types.ts';
+import { type UploadData, type UploadProgress } from './uploads.ts';
+export { DEFAULT_BASE_URL } from './defaults.ts';
+export { VidexoError, type VidexoErrorCode } from './errors.ts';
+export { sendUpload, type SendUploadOptions, type UploadData, type UploadProgress } from './uploads.ts';
+export type { ClientJob, ClientJobList, ClientJobOutput, ClientTokenInfo, CompletedUpload, CreateUploadRequest, Upload } from './types.ts';
+/** The token a `getToken` callback answers: the string, or with its id as your backend got it. */
+export type FreshToken = string | {
+    token: string;
+    id?: string;
+};
+export type VidexoClientOptions = {
+    /** A client token your backend minted (`vdx_ct_...`); never an API key. */
+    token: string;
+    /** The token's id. Without it the id is read from `GET /v1/client/token` on first use. */
+    tokenId?: string;
+    /** `https://api.videxo.io` by default. */
+    baseUrl?: string;
+    /**
+     * Asks your backend for a continuation of the token (`continues: tokenId`), when it is about to
+     * expire or is refused as expired or superseded, so long flows keep their uploads and jobs. A
+     * failed refresh is asked again with the same id on the next call.
+     */
+    getToken?(request: {
+        tokenId: string | null;
+    }): Promise<FreshToken>;
+    fetch?(input: Request, init?: RequestInit): Promise<Response>;
+    maxRetries?: number;
+    timeoutMs?: number;
+};
+export type ClientRequestOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type ClientCreateOptions = ClientRequestOptions & {
+    /** Makes the creation safe to retry for 24 hours; the SDK makes one and reuses it on its own retries. */
+    idempotencyKey?: string;
+};
+export type ClientUploadOptions = ClientCreateOptions & {
+    /** A plain file name: letters, digits, dots, underscores and hyphens. */
+    filename: string;
+    /** The declared type; 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;
+    /** Called as the bytes are sent. In a browser this uses `XMLHttpRequest`, as `fetch` reports no upload progress. */
+    onProgress?(progress: UploadProgress): void;
+    /** For sending the bytes; no timeout by default, as a large file may take a while. */
+    uploadTimeoutMs?: number;
+};
+export type ClientWaitOptions = {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignal;
+};
+/**
+ * The client of `/v1/client/*` for an app or a web page.
+ *
+ * ```ts
+ * const videxo = new VidexoClient({ token, tokenId, getToken: ({ tokenId }) => myBackend.refresh(tokenId) });
+ * const upload = await videxo.uploads.upload(file, { filename: 'clip.mp4', onProgress: (p) => show(p.loaded / p.total) });
+ * ```
+ */
+export declare class VidexoClient {
+    #private;
+    readonly baseUrl: string;
+    readonly uploads: ClientUploads;
+    readonly jobs: ClientJobs;
+    /** @internal */
+    readonly transport: Transport;
+    constructor(options: VidexoClientOptions);
+    /** `GET /v1/client/token`: the token's id, chain and expiry, the uploads used and the jobs it may read. */
+    token(options?: ClientRequestOptions): Promise<ClientTokenInfo>;
+    /** The id of the current token, once known. */
+    get tokenId(): string | null;
+    /** @internal One call: a token that is about to end is refreshed first, one refused as ended is refreshed and the call sent again once. */
+    request<T>(method: string, path: string, options: {
+        retry: RetryPolicy;
+        body?: unknown;
+        headers?: Record<string, string>;
+        remember?: boolean;
+    } & ClientRequestOptions): Promise<T>;
+}
+export declare class ClientUploads {
+    #private;
+    constructor(client: VidexoClient);
+    /**
+     * `POST /v1/client/uploads`: a one-time upload URL within the token's grant. It sends an
+     * Idempotency-Key of its own, kept for its retries and a refresh, so a lost answer spends nothing.
+     */
+    create(params: CreateUploadRequest, options?: ClientCreateOptions): Promise<Upload>;
+    /**
+     * Creates an upload and sends the bytes; answers the completed upload. Hand its `input_url` to your
+     * backend, which creates the job with its API key.
+     */
+    upload(data: UploadData, options: ClientUploadOptions): Promise<CompletedUpload>;
+}
+export declare class ClientJobs {
+    #private;
+    constructor(client: VidexoClient);
+    /** `GET /v1/client/jobs/{id}`: a job the token may read. Any other job is `not_found`. */
+    get(id: string, options?: ClientRequestOptions): Promise<ClientJob>;
+    /** `GET /v1/client/jobs`: the jobs the token may read, newest first. */
+    list(options?: ClientRequestOptions): Promise<ClientJob[]>;
+    /**
+     * Reads the job until it is `succeeded`, `failed` or `cancelled`, and answers it (a failed job is
+     * answered, not thrown). 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?: ClientWaitOptions): Promise<ClientJob>;
+}

package/dist/app-client.js

@@ -0,0 +1,311 @@
+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, sendUploadWithProgress, sizeOf } from "./uploads.js";
+// `@videxo/sdk/client`: the client for apps and web pages, which hold a short-lived client token
+// (ADR 016), never an API key. It imports nothing of the keyed client, so a bundle stays small and
+// cannot reach a keyed route by accident.
+export { DEFAULT_BASE_URL } from "./defaults.js";
+export { VidexoError } from "./errors.js";
+export { sendUpload } from "./uploads.js";
+const CLIENT_TOKEN_PREFIX = 'vdx_ct_';
+const API_KEY_SHAPE = /^vdx_[A-Za-z]{64}$/;
+/** Refresh a token this close to its expiry, before the request would be refused. */
+const REFRESH_BEFORE_EXPIRY_MS = 30_000;
+const TERMINAL = new Set(['succeeded', 'failed', 'cancelled']);
+/** The refusals a new token of the chain answers. */
+const REFRESHABLE = new Set(['client_token_expired', 'client_token_superseded']);
+/** A value that must be a client token: an API key in an app is a published key, so it stops here. */
+function checkedToken(value) {
+    const token = typeof value === 'string' ? value.trim() : '';
+    // The messages do not repeat the value: it may be a real key.
+    if (API_KEY_SHAPE.test(token))
+        throw new TypeError('VidexoClient takes a client token, never an API key. Keep the API key on your server and mint client tokens there.');
+    if (!token.startsWith(CLIENT_TOKEN_PREFIX) || !/^[\x21-\x7e]+$/.test(token))
+        throw new TypeError('VidexoClient needs a client token (vdx_ct_...) your server minted with POST /v1/client-tokens.');
+    return token;
+}
+/**
+ * The client of `/v1/client/*` for an app or a web page.
+ *
+ * ```ts
+ * const videxo = new VidexoClient({ token, tokenId, getToken: ({ tokenId }) => myBackend.refresh(tokenId) });
+ * const upload = await videxo.uploads.upload(file, { filename: 'clip.mp4', onProgress: (p) => show(p.loaded / p.total) });
+ * ```
+ */
+export class VidexoClient {
+    baseUrl;
+    uploads;
+    jobs;
+    /** @internal */
+    transport;
+    #token;
+    #tokens = new Set();
+    #tokenId;
+    /** Milliseconds; null until the token has been read. */
+    #expiresAt = null;
+    #read = false;
+    #refreshed = false;
+    #clockAhead = false;
+    #refreshing = null;
+    #getToken;
+    constructor(options) {
+        this.#token = checkedToken(options?.token);
+        this.#tokens.add(this.#token);
+        this.#tokenId = options.tokenId ?? null;
+        this.#getToken = options.getToken;
+        const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        if (!/^https?:\/\//.test(baseUrl))
+            throw new TypeError('baseUrl must be an http or https URL.');
+        this.baseUrl = baseUrl;
+        const userFetch = options.fetch;
+        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,
+            // Every token of this client: a request under way when its token was replaced can still fail with it.
+            redact: (text) => [...this.#tokens].reduce((clean, token) => clean.replaceAll(token, '[client token]'), text),
+        };
+        this.uploads = new ClientUploads(this);
+        this.jobs = new ClientJobs(this);
+    }
+    /** `GET /v1/client/token`: the token's id, chain and expiry, the uploads used and the jobs it may read. */
+    async token(options = {}) {
+        return this.request('GET', '/v1/client/token', { retry: 'safe', remember: true, ...options });
+    }
+    /** The id of the current token, once known. */
+    get tokenId() {
+        return this.#tokenId;
+    }
+    /** What a read of the token `used` answered, unless the token was replaced while it was on its way. */
+    #remember(info, used) {
+        if (used !== this.#token)
+            return;
+        this.#tokenId = info.id;
+        this.#expiresAt = Date.parse(info.expires_at);
+        this.#read = true;
+        // A token just refreshed cannot be about to end, so this device's clock runs ahead. Asking for a new
+        // one before every call would not help: from here on only the API's own refusal starts a refresh.
+        if (this.#refreshed && this.#expiresAt - Date.now() < REFRESH_BEFORE_EXPIRY_MS)
+            this.#clockAhead = true;
+        this.#refreshed = false;
+    }
+    /** The current token is replaced by what `getToken` answers; concurrent calls share one refresh. */
+    #refresh() {
+        if (!this.#refreshing) {
+            this.#refreshing = (async () => {
+                const fresh = await this.#getToken({ tokenId: this.#tokenId });
+                const token = checkedToken(typeof fresh === 'string' ? fresh : fresh?.token);
+                // The old id stays until the new one is known, so a failed refresh asks with the same id.
+                this.#token = token;
+                this.#tokens.add(token);
+                if (typeof fresh !== 'string' && fresh.id)
+                    this.#tokenId = fresh.id;
+                this.#expiresAt = null;
+                this.#read = false;
+                this.#refreshed = true;
+            })().finally(() => {
+                this.#refreshing = null;
+            });
+        }
+        return this.#refreshing;
+    }
+    /**
+     * After `used` was refused as ended: a refresh, unless another call already replaced that token. A
+     * refusal that arrives late must not mint a third token, whose first use would end the second while
+     * a call with it is under way.
+     */
+    async #replace(used, signal) {
+        if (this.#refreshing)
+            await settled(this.#refreshing, signal);
+        if (this.#token === used)
+            await settled(this.#refresh(), signal);
+    }
+    /** Before a request: learns the token's id and expiry while it still works, and refreshes it when it is about to end. */
+    async #prepare(path, options) {
+        if (!this.#getToken)
+            return;
+        if (this.#refreshing)
+            await settled(this.#refreshing, options.signal);
+        if (!this.#read && path !== '/v1/client/token') {
+            // Only the call's signal and timeout: its body and headers are not this request's.
+            const { signal, timeoutMs } = options;
+            const used = this.#token;
+            const response = await this.#send('GET', '/v1/client/token', {
+                retry: 'safe',
+                ...(signal ? { signal } : {}),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            });
+            const body = await readBody(response);
+            if (response.ok)
+                this.#remember(body, used);
+            else if (refreshable(response, body))
+                return this.#replace(used, signal);
+            // Any other refusal is left to the call itself, which answers it.
+        }
+        if (!this.#clockAhead && this.#expiresAt !== null && this.#expiresAt - Date.now() < REFRESH_BEFORE_EXPIRY_MS)
+            await settled(this.#refresh(), options.signal);
+    }
+    #send(method, path, options) {
+        const request = new Request(`${this.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.#token}`,
+                ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                ...options.headers,
+            },
+            ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        });
+        return send(this.transport, request, { retry: options.retry, signal: options.signal, timeoutMs: options.timeoutMs, buffer: true });
+    }
+    /** @internal One call: a token that is about to end is refreshed first, one refused as ended is refreshed and the call sent again once. */
+    async request(method, path, options) {
+        try {
+            await this.#prepare(path, options);
+            let used = this.#token;
+            let response = await this.#send(method, path, options);
+            let body = await readBody(response);
+            if (this.#getToken && refreshable(response, body)) {
+                await this.#replace(used, options.signal);
+                used = this.#token;
+                response = await this.#send(method, path, options);
+                body = await readBody(response);
+            }
+            if (!response.ok)
+                throw errorFromResponse(response, body);
+            if (typeof body !== 'object' || body === null)
+                throw sdkError('invalid_response', 'The API answered without a JSON body.', { status: response.status, body });
+            if (options.remember)
+                this.#remember(body, used);
+            return body;
+        }
+        catch (error) {
+            throw redacted(this.transport, error);
+        }
+    }
+}
+/**
+ * Waits for the shared refresh as long as this call still wants it: its signal ends this call's wait
+ * and nothing else, so the refresh goes on for the calls still waiting.
+ */
+function settled(refresh, signal) {
+    if (!signal)
+        return refresh;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(sdkError('aborted', 'The request was aborted while its token was refreshed.', { cause: signal.reason }));
+        if (signal.aborted)
+            return onAbort();
+        signal.addEventListener('abort', onAbort, { once: true });
+        refresh.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+const refreshable = (response, body) => response.status === 401 && REFRESHABLE.has(body?.reason ?? '');
+async function readBody(response) {
+    const text = await response.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export class ClientUploads {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * `POST /v1/client/uploads`: a one-time upload URL within the token's grant. It sends an
+     * Idempotency-Key of its own, kept for its retries and a refresh, so a lost answer spends nothing.
+     */
+    create(params, options = {}) {
+        return this.#client.request('POST', '/v1/client/uploads', {
+            retry: 'safe',
+            body: params,
+            headers: { 'Idempotency-Key': options.idempotencyKey ?? crypto.randomUUID() },
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+    }
+    /**
+     * Creates an upload and sends the bytes; answers the completed upload. Hand its `input_url` to your
+     * backend, which creates the job with its API key.
+     */
+    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);
+        const sending = {
+            contentType,
+            fetch: this.#client.transport.fetch,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.uploadTimeoutMs === undefined ? {} : { timeoutMs: options.uploadTimeoutMs }),
+        };
+        return options.onProgress
+            ? sendUploadWithProgress(upload.upload_url, data, size, { ...sending, onProgress: options.onProgress })
+            : sendUpload(upload.upload_url, data, sending);
+    }
+}
+export class ClientJobs {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** `GET /v1/client/jobs/{id}`: a job the token may read. Any other job is `not_found`. */
+    get(id, options = {}) {
+        return this.#client.request('GET', `/v1/client/jobs/${encodeURIComponent(id)}`, { retry: 'safe', ...options });
+    }
+    /** `GET /v1/client/jobs`: the jobs the token may read, newest first. */
+    async list(options = {}) {
+        const list = await this.#client.request('GET', '/v1/client/jobs', { retry: 'safe', ...options });
+        return list.data;
+    }
+    /**
+     * Reads the job until it is `succeeded`, `failed` or `cancelled`, and answers it (a failed job is
+     * answered, not thrown). 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.#client.transport.sleep ?? abortableSleep;
+        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);
+        }
+    }
+}

package/dist/client.d.ts

@@ -1,16 +1,11 @@
 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, CompileRequest, CompileResult, CompletedUpload, ConcatRequest, CreateUploadRequest, GifRequest, Job, JobList, JobRequest, ListJobsParams, FontList, PresetList, StoryboardRequest, ThumbnailsRequest, TranscodeRequest, Upload, WebhookEvent } from './types.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 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;
-}>;
+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
@@ -55,6 +50,24 @@ export type UploadOptions = RequestOptions & {
     /** 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;
@@ -77,6 +90,7 @@ export declare class Videxo {
     readonly uploads: Uploads;
     readonly outputs: Outputs;
     readonly webhooks: Webhooks;
+    readonly clientTokens: ClientTokens;
     /** @internal */
     readonly transport: Transport;
     /** @internal */
@@ -87,7 +101,7 @@ export declare class Videxo {
     /** @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(path: CreatePath, body: unknown, options?: CreateOptions): Promise<Job>;
+    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`. */
@@ -100,8 +114,20 @@ export declare class Videxo {
     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';
+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);
@@ -166,8 +192,26 @@ export declare class Outputs {
      */
     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>;
 }
-export {};