@vocalstack/js-sdk 1.1.0 → 2.0.0-alpha.0

package/dist/resources.js

@@ -0,0 +1,787 @@
+import { VocalStackError } from './errors.js';
+import { listenerQuery, seg } from './http.js';
+import { RealtimeSession } from './realtime.js';
+import { Subscription } from './subscription.js';
+import { openWebSocket } from './ws.js';
+async function toBlob(file) {
+    if (typeof file === 'string') {
+        const fsSpecifier = 'node:' + 'fs';
+        const { openAsBlob } = (await import(/* @vite-ignore */ fsSpecifier));
+        return { blob: await openAsBlob(file), name: file.split(/[\\/]/).pop() };
+    }
+    if (typeof Blob !== 'undefined' && file instanceof Blob) {
+        return { blob: file, name: file.name || undefined };
+    }
+    return { blob: new Blob([file]) };
+}
+/** Every item of a paged list: each page asked for with the previous
+ * page's `nextCursor` until one comes back without it. */
+async function allPages(page) {
+    const out = [];
+    let cursor;
+    for (;;) {
+        const r = await page(cursor);
+        out.push(...(r.items ?? []));
+        if (!r.nextCursor)
+            return out;
+        cursor = r.nextCursor;
+    }
+}
+/** What broadcasts and transcriptions have in common: both hold
+ * recordings and share links. */
+class ParentResource {
+    t;
+    constructor(t) {
+        this.t = t;
+    }
+    p(id, rest = '') {
+        return `${this.base}/${seg(id)}${rest}`;
+    }
+    /** Every one, newest first: a paged list is read to its last page
+     * (`transcriptions.listPage` reads one). */
+    list(lifecycle = 'active') {
+        return allPages(async (cursor) => {
+            const r = await this.t.json('GET', this.base, { query: { lifecycle, cursor } });
+            return { items: r[this.key], nextCursor: r.nextCursor };
+        });
+    }
+    get(id) {
+        return this.t.json('GET', this.p(id));
+    }
+    /** Rename, change the default capture settings (a broadcast: also its access, password or link). */
+    update(id, req) {
+        return this.t.json('PATCH', this.p(id), { body: req });
+    }
+    /** Hidden, its links dead, its data kept until `restore` or `purge`. */
+    archive(id) {
+        return this.t.json('POST', this.p(id, '/archive'));
+    }
+    restore(id) {
+        return this.t.json('POST', this.p(id, '/restore'));
+    }
+    /** Delete an archived one and everything in it, for good. */
+    async purge(id) {
+        await this.t.json('POST', this.p(id, '/purge'));
+    }
+    /** Every recording, newest first (every page of `listRecordingsPage`). */
+    listRecordings(id, lifecycle = 'active') {
+        return allPages(async (cursor) => {
+            const r = await this.listRecordingsPage(id, { lifecycle, cursor });
+            return { items: r.recordings, nextCursor: r.nextCursor };
+        });
+    }
+    /** One page of recordings, newest first: pass its `nextCursor` as `cursor` for the next. */
+    listRecordingsPage(id, opts = {}) {
+        return this.t.json('GET', this.p(id, '/recordings'), { query: { lifecycle: opts.lifecycle, cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** Start a live recording.  The grant's `streamUrl` is the publisher
+     * socket (`vs.recordings.publish(grant)`).  A 409 `conflict` with
+     * `details.takeover` means another device is recording: retry with
+     * `{ takeover: true }` to record here instead. */
+    startRecording(id, req = {}, call = {}) {
+        return this.t.json('POST', this.p(id, '/recordings'), { body: req, ...call });
+    }
+    async listShareLinks(id) {
+        const r = await this.t.json('GET', this.p(id, '/share-links'));
+        return r.links ?? [];
+    }
+    createShareLink(id, req) {
+        return this.t.json('POST', this.p(id, '/share-links'), { body: req });
+    }
+    /** The events socket a waiting screen needs: `recording.started` (it is
+     * live), `recording.ended`, `job.progress`, `stream.ingest`.
+     * Each names the transcription the recording is made in (`transcriptionId`). */
+    async events(id, as = {}) {
+        const token = as.asOwner === false ? undefined : await this.t.bearer();
+        return openWebSocket(this.t.wsUrl(this.p(id, '/events'), listenerQuery(as)), token);
+    }
+}
+/** `vs.broadcasts`: the links listeners open (design 77). */
+export class Broadcasts extends ParentResource {
+    base = '/v1/broadcasts';
+    key = 'broadcasts';
+    create(req, call = {}) {
+        return this.t.json('POST', this.base, { body: req, ...call });
+    }
+    /** Give a broadcast a stream it can record from (a YouTube live, an
+     * internet radio address).  Returns the broadcast. */
+    addAudioSource(id, req) {
+        return this.t.json('POST', this.p(id, '/audio-sources'), { body: req });
+    }
+    removeAudioSource(id, sourceId) {
+        return this.t.json('DELETE', this.p(id, `/audio-sources/${seg(sourceId)}`));
+    }
+    /** Whether that source can be recorded right now; `fresh` skips the short cache. */
+    checkAudioSource(id, sourceId, opts = {}) {
+        return this.t.json('GET', this.p(id, `/audio-sources/${seg(sourceId)}/check`), { query: { fresh: opts.fresh || undefined } });
+    }
+}
+/** `vs.transcriptions`: a file, a link, a microphone or a stream, transcribed and stored. */
+export class Transcriptions extends ParentResource {
+    base = '/v1/transcriptions';
+    key = 'transcriptions';
+    /** One page of transcriptions, newest first: pass its `nextCursor` as
+     * `cursor` for the next; the last page has none. */
+    listPage(opts = {}) {
+        return this.t.json('GET', this.base, { query: { lifecycle: opts.lifecycle, cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** A file or link recording in this transcription: no live phase, transcribed at full speed.
+     * It has no job: open the grant's socket with `vs.recordings.publish(grant)` (with `url`
+     * the server fetches the link) and read it until the session is done. */
+    uploadRecording(id, req = {}, call = {}) {
+        return this.t.json('POST', this.p(id, '/recordings/upload'), { body: req, ...call });
+    }
+    /** From a file (`file`) or a public link (`url`).  The answer's
+     * `job.recordingId` is the job: `vs.jobs.wait(recordingId)`,
+     * then `vs.recordings.transcript(recordingId)`. */
+    async create(req, call = {}) {
+        const { file, fileName, ...options } = req;
+        if (file === undefined)
+            return this.t.json('POST', this.base, { body: options, ...call });
+        const { blob, name } = await toBlob(file);
+        const fd = new FormData();
+        fd.append('options', JSON.stringify(options));
+        fd.append('file', blob, fileName ?? name ?? 'upload');
+        return this.t.json('POST', this.base, { body: fd, ...call });
+    }
+    /** `create({ url, ...opts })`. */
+    createFromUrl(url, opts = {}, call = {}) {
+        return this.create({ ...opts, url }, call);
+    }
+    /** A transcription captured as it is spoken: a microphone, or a stream
+     * the server pulls.  Created idle: `startRecording(id)` starts it. */
+    createLive(req, call = {}) {
+        return this.t.json('POST', `${this.base}/live`, { body: req, ...call });
+    }
+    /** Whether a link is live (a live transcription) or a file. */
+    probe(url) {
+        return this.t.json('GET', `${this.base}/probe`, { query: { url } });
+    }
+    /** Feed a broadcast from a live transcription.  Returns the transcription. */
+    attachBroadcast(id, broadcastId) {
+        return this.t.json('PUT', this.p(id, `/broadcasts/${seg(broadcastId)}`));
+    }
+    detachBroadcast(id, broadcastId) {
+        return this.t.json('DELETE', this.p(id, `/broadcasts/${seg(broadcastId)}`));
+    }
+}
+/** `vs.batches`: several files transcribed together, for less than a
+ * transcription each (one create, one minimum charge).  Create a batch, add
+ * each file or link with `addFile`, then `start` it; `get` shows its files
+ * (each a transcription with its job) and their counts.  A batch's files get
+ * no summary, title, share link or spoken translations. */
+export class Batches {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    #p(id, rest = '') {
+        return `/v1/batches/${seg(id)}${rest}`;
+    }
+    /** An open batch, ready for files (`name` defaults to "Batch of <date>"). */
+    create(req = {}, call = {}) {
+        return this.#t.json('POST', '/v1/batches', { body: req, ...call });
+    }
+    /** Every batch, newest first (every page of `listPage`); each with its counts, not its files. */
+    list() {
+        return allPages(async (cursor) => {
+            const r = await this.listPage({ cursor });
+            return { items: r.batches, nextCursor: r.nextCursor };
+        });
+    }
+    /** One page of batches, newest first: pass its `nextCursor` as `cursor` for the next. */
+    listPage(opts = {}) {
+        return this.#t.json('GET', '/v1/batches', { query: { cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** A batch with its files (`files`, each a transcription with its job), in the order they were added. */
+    get(id) {
+        return this.#t.json('GET', this.#p(id));
+    }
+    /** Discard a batch that was never started, with its files (nothing was charged). */
+    async delete(id) {
+        await this.#t.json('DELETE', this.#p(id));
+    }
+    /** Add one file (`file`) or link (`url`) to an open batch: a transcription
+     * of its own (`batchId`), waiting for the batch's `start`. */
+    async addFile(id, req, call = {}) {
+        const { file, fileName, ...options } = req;
+        if (file === undefined)
+            return this.#t.json('POST', this.#p(id, '/files'), { body: options, ...call });
+        const { blob, name } = await toBlob(file);
+        const fd = new FormData();
+        fd.append('options', JSON.stringify(options));
+        fd.append('file', blob, fileName ?? name ?? 'upload');
+        return this.#t.json('POST', this.#p(id, '/files'), { body: fd, ...call });
+    }
+    /** `addFile(id, { url, ...opts })`. */
+    addUrl(id, url, opts = {}, call = {}) {
+        return this.addFile(id, { ...opts, url }, call);
+    }
+    /** Seal the batch and queue its files, longest first; `wait` follows it to the end. */
+    start(id, call = {}) {
+        return this.#t.json('POST', this.#p(id, '/start'), call);
+    }
+    /** Every finished file's transcript in one `format` (as `recordings.export`
+     * makes one), in one zip, as a `Response`: `.arrayBuffer()` it.  Files
+     * still running or failed are left out. */
+    export(id, format) {
+        return this.#t.raw('GET', this.#p(id, '/export'), { headers: { accept: '*/*' }, query: { format } });
+    }
+    /** Stop every file not finished yet: queued files never start, a running
+     * one is cancelled and billed for what it transcribed. */
+    stop(id) {
+        return this.#t.json('POST', this.#p(id, '/stop'));
+    }
+    /** Poll a started batch until it is `done` (every file finished or
+     * failed) or `stopped`, and return it with its files.  It does not throw
+     * on a failed file: check `counts.failed` and each file's `job.state`.
+     * `onProgress` sees every read, the last one included. */
+    async wait(id, opts = {}) {
+        const interval = opts.intervalMs ?? 5000;
+        const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : Infinity;
+        for (;;) {
+            const batch = await this.get(id);
+            opts.onProgress?.(batch);
+            // Closed: every file over (a stopped batch's running file too).
+            if ((batch.state === 'done' || batch.state === 'stopped') && batch.finishedAt)
+                return batch;
+            if (batch.state === 'open')
+                throw new VocalStackError('invalid_state', 'the batch is open: start it before waiting for it');
+            if (Date.now() + interval > deadline)
+                throw new VocalStackError('timeout', `batch still ${batch.state} after ${opts.timeoutMs} ms`, { retryable: true });
+            if (opts.signal?.aborted)
+                throw opts.signal.reason ?? new Error('aborted');
+            await new Promise((r) => setTimeout(r, interval));
+        }
+    }
+}
+/** `vs.recordings`: one take, live or uploaded. */
+export class Recordings {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    #p(id, rest = '') {
+        return `/v1/recordings/${seg(id)}${rest}`;
+    }
+    get(id, as) {
+        return this.#t.json('GET', this.#p(id), { query: listenerQuery(as) });
+    }
+    pause(id) {
+        return this.#t.json('POST', this.#p(id, '/pause'));
+    }
+    resume(id) {
+        return this.#t.json('POST', this.#p(id, '/resume'));
+    }
+    /** Only from paused. */
+    stop(id, reason) {
+        return this.#t.json('POST', this.#p(id, '/stop'), { body: { reason } });
+    }
+    settings(id, patch) {
+        return this.#t.json('PATCH', this.#p(id, '/settings'), { body: patch });
+    }
+    /** A new publisher grant for a recording that is already live. */
+    publishToken(id, opts = {}) {
+        return this.#t.json('POST', this.#p(id, '/publish-token'), { body: { takeover: opts.takeover ?? false } });
+    }
+    /** Open the publisher socket a grant names and wait until it is ready:
+     * send raw PCM (f32le, 16 kHz, mono) with `sendAudio`, end with `eof()`. */
+    publish(grant, opts = {}) {
+        if (!grant.streamUrl)
+            throw new VocalStackError('invalid_state', 'this grant has no streamUrl (an upload recording has no publisher socket)');
+        return RealtimeSession.connect({
+            sessionId: grant.sessionId ?? grant.recording.id,
+            streamUrl: grant.streamUrl,
+            readyDeadlineMs: opts.readyDeadlineMs ?? this.#t.opts.readyDeadlineMs,
+            onLoading: opts.onLoading,
+            onFrame: opts.onFrame,
+        });
+    }
+    archive(id) {
+        return this.#t.json('POST', this.#p(id, '/archive'));
+    }
+    restore(id) {
+        return this.#t.json('POST', this.#p(id, '/restore'));
+    }
+    async purge(id) {
+        await this.#t.json('POST', this.#p(id, '/purge'));
+    }
+    /** The transcript: segments (with word timings), sentences and speakers,
+     * up to `lastSeq`; `after` continues from a cursor, `lang` reads it translated. */
+    transcript(id, opts = {}) {
+        return this.#t.json('GET', this.#p(id, '/transcript'), {
+            query: { ...listenerQuery(opts), after: opts.after, lang: opts.lang, role: opts.asListener ? 'listener' : undefined },
+        });
+    }
+    /** Translate the given sentences (at most 40 ids per call); the answer
+     * carries only what this call translated. */
+    translation(id, lang, sentences = [], as) {
+        return this.#t.json('GET', this.#p(id, '/translation'), {
+            query: { ...listenerQuery(as), lang, sentences: sentences.length ? sentences.join(',') : undefined },
+        });
+    }
+    /** Queue the AI title and summary of a finished recording. */
+    summarize(id, call = {}) {
+        return this.#t.json('POST', this.#p(id, '/summarize'), call);
+    }
+    /** The title and summary as they stand, in `lang` when given. */
+    summary(id, opts = {}) {
+        return this.#t.json('GET', this.#p(id, '/summary'), { query: { ...listenerQuery(opts), lang: opts.lang } });
+    }
+    /** An export file (JSON, SRT, XLSX, PDF) as a `Response`: `.text()` or
+     * `.arrayBuffer()` it.  `lang` makes it read in that language. */
+    export(id, format, opts = {}) {
+        return this.#t.raw('GET', this.#p(id, '/export'), { headers: { accept: '*/*' }, query: { ...listenerQuery(opts), format, lang: opts.lang } });
+    }
+    /** The export as a plain link, for a browser download with a browser
+     * access token (it rides in the query).  Never use it with an API key:
+     * the API refuses a key in a URL. */
+    async exportUrl(id, format, opts = {}) {
+        const token = opts.shareCode || opts.listenerToken ? undefined : await this.#t.bearer();
+        return this.#t.url(this.#p(id, '/export'), { format, lang: opts.lang, shareCode: opts.shareCode, listenerToken: opts.listenerToken, access_token: token });
+    }
+    /** The signed media URL the server redirects to.  `kind`: `delivery`
+     * (default), `master`, or `source` (a transcription's original upload). */
+    async audioUrl(id, opts = {}) {
+        const res = await this.#t.raw('GET', this.#p(id, '/audio'), {
+            query: { ...listenerQuery(opts), kind: opts.kind, lang: opts.lang, format: opts.format },
+        });
+        const location = res.headers.get('location');
+        if (!location)
+            throw new VocalStackError('not_found', 'no signed URL in the redirect');
+        return location;
+    }
+    /** A stretch of the recording's audio, `startS` to `endS` seconds (at most 120 s). */
+    clip(id, startS, endS, as) {
+        return this.#t.raw('GET', this.#p(id, '/audio/clip'), { headers: { accept: '*/*' }, query: { ...listenerQuery(as), startS, endS } });
+    }
+    /** The synthesized voice tracks of a recording (per language). */
+    voice(id, lang, as) {
+        return this.#t.json('GET', this.#p(id, '/voice'), { query: { ...listenerQuery(as), lang } });
+    }
+    /** Synthesize the voice track in these languages. */
+    renderVoice(id, langs, call = {}) {
+        return this.#t.json('POST', this.#p(id, '/voice'), { body: { langs }, ...call });
+    }
+    /** One sentence spoken in `lang`. */
+    voiceClip(id, sentence, lang, opts = {}) {
+        return this.#t.raw('GET', this.#p(id, `/voice/${seg(sentence)}`), { headers: { accept: '*/*' }, query: { ...listenerQuery(opts), lang, format: opts.format } });
+    }
+    /** A short-lived token for the recording's media URLs. */
+    mediaToken(id) {
+        return this.#t.json('GET', this.#p(id, '/media-token'));
+    }
+    /** Name a speaker (the diarizer's index); `null` clears the name. */
+    async nameSpeaker(id, speaker, name) {
+        await this.#t.json('PUT', this.#p(id, `/speakers/${seg(speaker)}`), { body: { name } });
+    }
+    /** The durable event log with wall times (owner only): every event
+     * after `after` (a `seq`; the whole log without it), read `limit` a page. */
+    events(id, opts = {}) {
+        return allPages(async (cursor) => {
+            const r = await this.eventsPage(id, cursor ? { cursor, limit: opts.limit } : { after: opts.after, limit: opts.limit });
+            return { items: r.events, nextCursor: r.nextCursor };
+        });
+    }
+    /** One page of the event log (500 by default, 1000 at most): from `after`
+     * a `seq`, or the previous page's `nextCursor` as `cursor`. */
+    eventsPage(id, opts = {}) {
+        return this.#t.json('GET', this.#p(id, '/events'), { query: { cursor: opts.cursor, after: opts.after, limit: opts.limit } });
+    }
+    /** Attach to the live fan-out; resolves once the backfill snapshot is in place. */
+    async subscribe(id, opts = {}) {
+        const token = opts.asOwner === false ? undefined : await this.#t.bearer();
+        const url = this.#t.wsUrl(this.#p(id, '/subscribe'), {
+            lang: opts.lang,
+            voice: opts.voice,
+            ...listenerQuery(opts),
+            role: opts.asOwner === false ? 'listener' : undefined,
+            device: this.#t.opts.deviceId,
+        });
+        return Subscription.open(id, url, token, opts, (after) => this.transcript(id, {
+            after,
+            lang: opts.lang,
+            listenerToken: opts.listenerToken,
+            shareCode: opts.shareCode,
+            asListener: opts.asOwner === false,
+        }));
+    }
+}
+const TERMINAL = new Set(['done', 'failed', 'stopped', 'cropping']);
+/** `vs.jobs`: the transcription job of a file or link recording
+ * (`/v1/recordings/{id}/job`).  States: queued, fetching, transcribing,
+ * done, failed, and cropping (waiting for `start`). */
+export class Jobs {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    get(recordingId) {
+        return this.#t.json('GET', `/v1/recordings/${seg(recordingId)}/job`);
+    }
+    /** Release a job waiting in `cropping`: the window to transcribe, in seconds. */
+    start(recordingId, window = {}) {
+        return this.#t.json('POST', `/v1/recordings/${seg(recordingId)}/job/start`, { body: window });
+    }
+    /** Re-queue a failed job from its stored source. */
+    retry(recordingId) {
+        return this.#t.json('POST', `/v1/recordings/${seg(recordingId)}/job/retry`);
+    }
+    /** The file the server fetched for a link job waiting in `cropping`. */
+    preview(recordingId) {
+        return this.#t.raw('GET', `/v1/recordings/${seg(recordingId)}/job/preview`, { headers: { accept: '*/*' } });
+    }
+    /** Poll until the job is `done`, `failed` or `cropping`, and return it.
+     * It does not throw on `failed`: check `job.state` (and `job.error`).
+     * `onProgress` sees every job read, the last one included: its `state`
+     * and `progress` (`pct`, `processedS`, the fetch phase). */
+    async wait(recordingId, opts = {}) {
+        const interval = opts.intervalMs ?? 2000;
+        const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : Infinity;
+        for (;;) {
+            const job = await this.get(recordingId);
+            opts.onProgress?.(job);
+            if (TERMINAL.has(job.state))
+                return job;
+            if (Date.now() + interval > deadline)
+                throw new VocalStackError('timeout', `job still ${job.state} after ${opts.timeoutMs} ms`, { retryable: true });
+            if (opts.signal?.aborted)
+                throw opts.signal.reason ?? new Error('aborted');
+            await new Promise((r) => setTimeout(r, interval));
+        }
+    }
+}
+/** `vs.corrections`: edits to a finished transcript, each revertible. */
+export class Corrections {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** Every correction, newest first (every page of `listPage`). */
+    list(recordingId) {
+        return allPages(async (cursor) => {
+            const r = await this.listPage(recordingId, { cursor });
+            return { items: r.corrections, nextCursor: r.nextCursor };
+        });
+    }
+    /** One page of corrections, newest first: pass its `nextCursor` as `cursor` for the next. */
+    listPage(recordingId, opts = {}) {
+        return this.#t.json('GET', `/v1/recordings/${seg(recordingId)}/corrections`, { query: { cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** Apply a staged batch atomically; every target must be settled. */
+    async apply(recordingId, batch) {
+        const r = await this.#t.json('POST', `/v1/recordings/${seg(recordingId)}/corrections`, { body: batch });
+        return r.corrections ?? [];
+    }
+    /** Read lines again with the language forced; lands as `line` corrections. */
+    async retranscribe(recordingId, req) {
+        const r = await this.#t.json('POST', `/v1/recordings/${seg(recordingId)}/retranscribe`, { body: req });
+        return r.corrections ?? [];
+    }
+    revert(correctionId) {
+        return this.#t.json('POST', `/v1/corrections/${seg(correctionId)}/revert`);
+    }
+}
+/** `vs.shareLinks`: named public links to a transcription or broadcast
+ * (create and list them on their owner). */
+export class ShareLinks {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    update(id, req) {
+        return this.#t.json('PATCH', `/v1/share-links/${seg(id)}`, { body: req });
+    }
+    revoke(id) {
+        return this.#t.json('DELETE', `/v1/share-links/${seg(id)}`);
+    }
+}
+/** `vs.voices`: the account's cloned voices, and the catalogue a language offers. */
+export class Voices {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    async list() {
+        const r = await this.#t.json('GET', '/v1/voices');
+        return r.voices ?? [];
+    }
+    get(id) {
+        return this.#t.json('GET', `/v1/voices/${seg(id)}`);
+    }
+    /** Build a voice from a sample (`sample`) or audio the server fetches
+     * (`sampleUrl`).  Calling it asserts you have the speaker's permission,
+     * unless `draft` (a draft is named and consented to later with `update`). */
+    async create(req, call = {}) {
+        const { sample, fileName, ...meta } = req;
+        const form = new FormData();
+        form.append('meta', JSON.stringify({ consent: !meta.draft, ...meta }));
+        if (sample !== undefined) {
+            const { blob, name } = await toBlob(sample);
+            form.append('sample', blob, fileName ?? name ?? 'sample.webm');
+        }
+        return this.#t.json('POST', '/v1/voices', { body: form, ...call });
+    }
+    /** Build a voice from one speaker of a recording (asserts permission). */
+    createFromSpeaker(req, call = {}) {
+        return this.#t.json('POST', '/v1/voices/from-speaker', { body: { consent: true, ...req }, ...call });
+    }
+    /** Rename, recolour, switch off; `{ name, consent: true, draft: false }` finishes a draft. */
+    update(id, patch) {
+        return this.#t.json('PATCH', `/v1/voices/${seg(id)}`, { body: patch });
+    }
+    async delete(id) {
+        await this.#t.json('DELETE', `/v1/voices/${seg(id)}`);
+    }
+    /** The voices that can speak `lang`, best first (with a token, also the
+     * account's ready clones).  `recording` also offers the cloned voices that
+     * recording uses, to whoever may read it: its owner, or a listener with
+     * `listenerToken` or `shareCode`. */
+    available(lang, opts = {}) {
+        return this.#t.json('GET', '/v1/voices/available', {
+            query: { ...listenerQuery(opts), lang, recording: opts.recording },
+            anonymous: opts.asOwner === false,
+        });
+    }
+    /** A catalogue voice speaking `lang` (Ogg/Opus; `caf` for Apple). 202 while it is prepared. */
+    preview(voice, lang, opts = {}) {
+        return this.#t.raw('GET', '/v1/voices/preview', { headers: { accept: '*/*' }, query: { voice, lang, format: opts.format } });
+    }
+    /** A cloned voice speaking `lang`; 409 while it is not ready.  With
+     * `recording`, as it speaks in that recording, for whoever may read it
+     * (its owner, or a listener with `listenerToken` or `shareCode`). */
+    clonePreview(id, opts = {}) {
+        return this.#t.raw('GET', `/v1/voices/${seg(id)}/preview`, {
+            headers: { accept: '*/*' },
+            query: { ...listenerQuery(opts), lang: opts.lang, format: opts.format, recording: opts.recording },
+            anonymous: opts.asOwner === false,
+        });
+    }
+    /** The audio a voice was made from. */
+    sample(id) {
+        return this.#t.raw('GET', `/v1/voices/${seg(id)}/sample`, { headers: { accept: '*/*' } });
+    }
+}
+/** `vs.search`: full-text search over the caller's transcripts. */
+export class Search {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** `q` is 2 or more characters. */
+    query(q, opts = {}) {
+        const query = {
+            q,
+            broadcasts: opts.broadcasts?.join(','),
+            listenerTokens: opts.listenerTokens?.join(','),
+            recording: opts.recording,
+            lang: opts.lang,
+            limit: opts.limit,
+        };
+        return this.#t.json('GET', '/v1/search', { query });
+    }
+}
+/** `vs.me`: who the credential is. */
+export class MeApi {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    get() {
+        return this.#t.json('GET', '/v1/me');
+    }
+}
+/** `vs.connect`: one-click Connect, on the app's server. */
+export class Connect {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** Redeem the `code` the dashboard sent to the app's `redirect_uri` for
+     * an API key (OAuth 2.0 authorization code + PKCE).  No credential is
+     * sent, even when the client has one, and the call is never retried:
+     * the code works once.  A refusal is a `VocalStackError` whose `code` is
+     * OAuth's `error` (`invalid_grant`: unknown, spent or expired code, or a
+     * verifier or `redirect_uri` that does not match). */
+    token(input, opts = {}) {
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code: input.code,
+            code_verifier: input.codeVerifier,
+            redirect_uri: input.redirectUri,
+        });
+        return this.#t.json('POST', '/v1/connect/token', { body, anonymous: true, noRetry: true, oauthErrors: true, signal: opts.signal });
+    }
+}
+/** `vs.billing`: the account's plan, credit balance and limits, the price
+ *  list, the ledger, the per-recording charges, the usage report, the
+ *  payments history, payment methods, invoice details and promo codes. */
+export class Billing {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** The account: plan, rates, balance, limits, subscription, top-up URL. */
+    get() {
+        return this.#t.json('GET', '/v1/billing');
+    }
+    /** The visible plans with their current rates and limits (no credential needed). */
+    plans() {
+        return this.#t.json('GET', '/v1/billing/plans');
+    }
+    /** The ledger, newest first. */
+    ledger(opts = {}) {
+        return this.#t.json('GET', '/v1/billing/ledger', { query: { cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** The per-recording charges, newest first. */
+    charges(opts = {}) {
+        return this.#t.json('GET', '/v1/billing/charges', { query: { cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** Open a checkout at the payment provider (a top-up or a subscription); send the customer to `url`.
+     *  A signed-in person only, never an API key. */
+    createCheckout(req, opts = {}) {
+        return this.#t.json('POST', '/v1/billing/checkouts', { body: req, ...opts });
+    }
+    /** A checkout's status (by its id or the provider's). */
+    getCheckout(id) {
+        return this.#t.json('GET', `/v1/billing/checkouts/${seg(id)}`);
+    }
+    /** Cancel the subscription at the end of its period. */
+    cancelSubscription() {
+        return this.#t.json('POST', '/v1/billing/subscription/cancel');
+    }
+    /** Take back a scheduled cancellation. */
+    uncancelSubscription() {
+        return this.#t.json('POST', '/v1/billing/subscription/uncancel');
+    }
+    /** Turn auto top-up on (threshold and amount from `plans().autoTopUp`) or off. */
+    setAutoTopUp(req) {
+        return this.#t.json('PUT', '/v1/billing/auto-top-up', { body: req });
+    }
+    /** A link to the provider's customer portal (payment methods, invoices, receipts). */
+    portal() {
+        return this.#t.json('GET', '/v1/billing/portal');
+    }
+    /** Charge the configured auto top-up amount now (under the day's cap). */
+    retryAutoTopUp() {
+        return this.#t.json('POST', '/v1/billing/auto-top-up/retry');
+    }
+    /** Turn the low-balance email on or off and set its line. */
+    setLowBalanceAlert(req) {
+        return this.#t.json('PUT', '/v1/billing/low-balance-alert', { body: req });
+    }
+    /** Renew `month`ly or `year`ly from the next period, at `subscription.switchPrices` (needs `acceptTerms` and `noNewWithdrawalPeriodShown`). */
+    setInterval(req) {
+        return this.#t.json('POST', '/v1/billing/subscription/interval', { body: req });
+    }
+    /** Keep the subscription by switching to yearly when monthly billing is withdrawn (`subscription.yearlyOptIn`). */
+    optInYearly(req) {
+        return this.#t.json('POST', '/v1/billing/subscription/yearly-opt-in', { body: req });
+    }
+    /** Take back a scheduled interval switch. */
+    unsetInterval() {
+        return this.#t.json('DELETE', '/v1/billing/subscription/interval');
+    }
+    /** What the account spent per day, source (API key or Dashboard) and kind. */
+    usage(opts = {}) {
+        return this.#t.json('GET', '/v1/billing/usage', { query: { startDate: opts.startDate, endDate: opts.endDate, tz: opts.tz } });
+    }
+    /** The usage report's charges one by one, newest first, with how many match and their total. */
+    usageCharges(opts = {}) {
+        const query = { startDate: opts.startDate, endDate: opts.endDate, tz: opts.tz, kind: opts.kind, source: opts.source, cursor: opts.cursor, limit: opts.limit };
+        return this.#t.json('GET', '/v1/billing/usage/charges', { query });
+    }
+    /** The payments history, newest first. */
+    payments(opts = {}) {
+        return this.#t.json('GET', '/v1/billing/payments', { query: { cursor: opts.cursor, limit: opts.limit } });
+    }
+    /** A payment's invoice or receipt: `{url}`, or `{pending: true}` while the provider makes it. */
+    paymentDocument(id) {
+        return this.#t.json('GET', `/v1/billing/payments/${seg(id)}/document`);
+    }
+    /** The saved payment methods. */
+    paymentMethods() {
+        return this.#t.json('GET', '/v1/billing/payment-methods');
+    }
+    /** Remove a saved payment method. */
+    async deletePaymentMethod(id) {
+        await this.#t.json('DELETE', `/v1/billing/payment-methods/${seg(id)}`);
+    }
+    /** A link to the provider's portal to add a card or choose the default. */
+    managePaymentMethods() {
+        return this.#t.json('POST', '/v1/billing/payment-methods/manage');
+    }
+    /** The invoice details. */
+    details() {
+        return this.#t.json('GET', '/v1/billing/details');
+    }
+    /** Save the invoice details. */
+    setDetails(req) {
+        return this.#t.json('PUT', '/v1/billing/details', { body: req });
+    }
+    /** What a promo code gives for a top-up or a subscription. */
+    checkPromoCode(req) {
+        return this.#t.json('POST', '/v1/billing/promo-codes/check', { body: req });
+    }
+}
+/** `vs.languages`. */
+export class Languages {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** Spoken and translation languages. */
+    list() {
+        return this.#t.json('GET', '/v1/languages');
+    }
+}
+/** `vs.rtmp`. */
+export class Rtmp {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** The account's RTMP ingest: server URL (RTMPS where available), the stream key (in full only in the answer that made it, `maskedStreamKey` after), and whether an encoder is sending. */
+    status() {
+        return this.#t.json('GET', '/v1/rtmp');
+    }
+    /** A stream key of the app's own, beside the account's: `streamKey` is in full in this answer only. It works while the API key that made it does. */
+    createKey(req) {
+        return this.#t.json('POST', '/v1/rtmp/keys', { body: req });
+    }
+    /** The account's app stream keys, oldest first: masked, each with whether an encoder is sending on it (`live`, `audio`). */
+    async listKeys() {
+        const r = await this.#t.json('GET', '/v1/rtmp/keys');
+        return r.keys ?? [];
+    }
+    /** Delete an app stream key: an encoder publishing on it is dropped within seconds. */
+    async deleteKey(id) {
+        await this.#t.json('DELETE', `/v1/rtmp/keys/${seg(id)}`);
+    }
+}
+/** `vs.events`: the account socket. */
+export class Events {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    /** `events.ready`, then `lists.changed` whenever one of the owner's
+     * lists of broadcasts or transcriptions is out of date: re-read them. */
+    async account() {
+        return openWebSocket(this.#t.wsUrl('/v1/events'), await this.#t.bearer());
+    }
+}
+/** `vs.meta`. */
+export class Meta {
+    #t;
+    constructor(t) {
+        this.#t = t;
+    }
+    health() {
+        return this.#t.json('GET', '/v1/health');
+    }
+    /** The OpenAPI document this SDK is generated from. */
+    openapi() {
+        return this.#t.json('GET', '/v1/openapi.json');
+    }
+}