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

package/dist/subscription.d.ts

@@ -0,0 +1,55 @@
+import type { ServerFrame, SubscriberFrame, TranscriptSnapshot } from '@vocalstack/contract';
+export interface SubscribeOptions {
+    /** Read (and hear) the recording in this language. */
+    lang?: string;
+    /** Which voice speaks `lang` for this listener: a voice id from
+     * `vs.voices.available(lang)`.  Omitted means the recording's
+     * `settings.voiceByLang` pin, then the engine's pick. */
+    voice?: string;
+    /** A private broadcast's listener token (the one VocalStack's listener page holds). */
+    listenerToken?: string;
+    /** Read a transcription through its share link. */
+    shareCode?: string;
+    /** With a token the socket is an owner subscriber (full frames, audience
+     * counts); `false` listens as a plain listener. */
+    asOwner?: boolean;
+    /** Live original audio (binary Opus frames) from the start. */
+    audio?: boolean;
+}
+export type SubscriptionEvent = {
+    type: 'snapshot';
+    snapshot: TranscriptSnapshot;
+    reason: 'initial' | 'gap';
+} | {
+    type: 'frame';
+    frame: ServerFrame | SubscriberFrame;
+    seq?: number;
+} | {
+    type: 'audio';
+    bytes: ArrayBuffer;
+} | {
+    type: 'closed';
+    reason?: string;
+};
+type Snapshotter = (after: number | undefined) => Promise<TranscriptSnapshot>;
+/** A recording's live fan-out (`vs.recordings.subscribe`).  It resolves
+ * once the backfill snapshot is in place; live frames follow through the
+ * async iterator, with gaps detected on the cursor and healed by
+ * re-snapshotting. */
+export declare class Subscription implements AsyncIterable<SubscriptionEvent> {
+    #private;
+    readonly recordingId: string;
+    /** Highest durable cursor applied (snapshot or frame). */
+    cursor: number;
+    snapshot: TranscriptSnapshot | null;
+    private constructor();
+    /** @internal */
+    static open(recordingId: string, url: string, bearer: string | undefined, opts: SubscribeOptions, snap: Snapshotter): Promise<Subscription>;
+    /** Switch the target language (`null` = as spoken). */
+    setLanguage(lang: string | null): void;
+    /** Opt in or out of live original audio. */
+    setAudio(enabled: boolean): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SubscriptionEvent>;
+}
+export {};

package/dist/subscription.js

@@ -0,0 +1,164 @@
+import { VocalStackError } from './errors.js';
+import { openWebSocket, WS_OPEN } from './ws.js';
+/** A recording's live fan-out (`vs.recordings.subscribe`).  It resolves
+ * once the backfill snapshot is in place; live frames follow through the
+ * async iterator, with gaps detected on the cursor and healed by
+ * re-snapshotting. */
+export class Subscription {
+    recordingId;
+    /** Highest durable cursor applied (snapshot or frame). */
+    cursor = -1;
+    snapshot = null;
+    #snap;
+    #opts;
+    #ws;
+    #queue = [];
+    #wake = null;
+    #closed = false;
+    #healing = false;
+    #buffering = [];
+    constructor(recordingId, ws, opts, snap) {
+        this.recordingId = recordingId;
+        this.#ws = ws;
+        this.#opts = opts;
+        this.#snap = snap;
+    }
+    /** @internal */
+    static async open(recordingId, url, bearer, opts, snap) {
+        const ws = await openWebSocket(url, bearer);
+        ws.binaryType = 'arraybuffer';
+        const sub = new Subscription(recordingId, ws, opts, snap);
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new VocalStackError('engine_unavailable', 'no subscribe.ready', { retryable: true })), 15_000);
+            ws.addEventListener('message', (ev) => {
+                if (typeof ev.data !== 'string') {
+                    sub.#push({ type: 'audio', bytes: ev.data });
+                    return;
+                }
+                let frame;
+                try {
+                    frame = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                if (frame.type === 'subscribe.ready') {
+                    clearTimeout(timer);
+                    resolve();
+                    return;
+                }
+                sub.#onFrame(frame);
+            });
+            ws.addEventListener('close', (ev) => {
+                clearTimeout(timer);
+                sub.#push({ type: 'closed', reason: ev?.reason });
+                sub.#closed = true;
+                sub.#wake?.();
+                reject(new VocalStackError('engine_unavailable', 'socket closed before subscribe.ready', { retryable: true }));
+            });
+            ws.addEventListener('error', () => {
+                clearTimeout(timer);
+                reject(new VocalStackError('engine_unavailable', 'subscriber socket error', { retryable: true }));
+            });
+        });
+        if (opts.audio)
+            sub.setAudio(true);
+        await sub.#resnapshot('initial');
+        return sub;
+    }
+    async #resnapshot(reason) {
+        const snap = await this.#snap(reason === 'gap' ? this.cursor : undefined);
+        this.snapshot = reason === 'initial' || !this.snapshot ? snap : mergeSnapshot(this.snapshot, snap);
+        this.cursor = Math.max(this.cursor, snap.lastSeq);
+        this.#push({ type: 'snapshot', snapshot: snap, reason });
+        const buffered = this.#buffering ?? [];
+        this.#buffering = null;
+        for (const b of buffered)
+            this.#onFrame(b.frame);
+    }
+    #onFrame(frame) {
+        // The relay cursor is `cursor`; segment-scoped frames use `seq` for the segment.
+        const seq = typeof frame.cursor === 'number' ? frame.cursor : typeof frame.seq === 'number' ? frame.seq : undefined;
+        if (this.#buffering) {
+            this.#buffering.push({ seq, frame });
+            return;
+        }
+        if (seq !== undefined) {
+            if (seq <= this.cursor)
+                return; // already in the snapshot
+            if (seq > this.cursor + 1 && !this.#healing) {
+                this.#healing = true;
+                this.#buffering = [{ seq, frame }];
+                this.#resnapshot('gap')
+                    .catch(() => { })
+                    .finally(() => {
+                    this.#healing = false;
+                });
+                return;
+            }
+            this.cursor = seq;
+            if (frame.type === 'noop')
+                return;
+        }
+        this.#push({ type: 'frame', frame, seq });
+    }
+    #push(ev) {
+        this.#queue.push(ev);
+        this.#wake?.();
+    }
+    /** Switch the target language (`null` = as spoken). */
+    setLanguage(lang) {
+        // A gap heal re-reads the snapshot in the language being read now.
+        this.#opts.lang = lang ?? undefined;
+        this.#send({ type: 'subscribe.update', lang: lang ?? 'none' });
+    }
+    /** Opt in or out of live original audio. */
+    setAudio(enabled) {
+        this.#send({ type: 'subscribe.update', audio: enabled });
+    }
+    #send(frame) {
+        if (this.#ws.readyState === WS_OPEN)
+            this.#ws.send(JSON.stringify(frame));
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        try {
+            this.#ws.close();
+        }
+        catch {
+            // already closed
+        }
+        this.#wake?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            if (this.#queue.length) {
+                yield this.#queue.shift();
+                continue;
+            }
+            if (this.#closed)
+                return;
+            await new Promise((r) => {
+                this.#wake = r;
+            });
+            this.#wake = null;
+        }
+    }
+}
+function mergeSnapshot(base, delta) {
+    const segs = new Map(base.segments.map((s) => [s.seq, s]));
+    for (const s of delta.segments)
+        segs.set(s.seq, s);
+    const sents = new Map(base.sentences.map((s) => [s.sentenceId, s]));
+    for (const s of delta.sentences)
+        sents.set(s.sentenceId, s);
+    return {
+        ...delta,
+        segments: [...segs.values()].sort((a, b) => a.seq - b.seq),
+        sentences: [...sents.values()].sort((a, b) => a.sentenceId - b.sentenceId),
+        speakers: delta.speakers.length ? delta.speakers : base.speakers,
+        spans: delta.spans.length ? delta.spans : base.spans,
+    };
+}

package/dist/ws.d.ts

@@ -0,0 +1,12 @@
+export interface WsLike {
+    binaryType: string;
+    readyState: number;
+    send(data: string | ArrayBufferLike | Uint8Array): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: string, listener: (ev: any) => void): void;
+}
+export declare const WS_OPEN = 1;
+/** Open a socket.  `bearer` is the caller's credential: Node sends it as
+ * an `Authorization` header (an API key is refused in a URL); a browser
+ * cannot set socket headers, so it rides in `access_token` instead. */
+export declare function openWebSocket(url: string, bearer?: string): Promise<WsLike>;

package/dist/ws.js

@@ -0,0 +1,15 @@
+export const WS_OPEN = 1;
+const isNode = () => typeof globalThis.process?.versions?.node === 'string' &&
+    !globalThis.Deno &&
+    !globalThis.Bun;
+/** Open a socket.  `bearer` is the caller's credential: Node sends it as
+ * an `Authorization` header (an API key is refused in a URL); a browser
+ * cannot set socket headers, so it rides in `access_token` instead. */
+export async function openWebSocket(url, bearer) {
+    if (!isNode() && typeof globalThis.WebSocket === 'function') {
+        const u = bearer ? `${url}${url.includes('?') ? '&' : '?'}access_token=${encodeURIComponent(bearer)}` : url;
+        return new globalThis.WebSocket(u);
+    }
+    const { WebSocket: NodeWebSocket } = await import('ws');
+    return new NodeWebSocket(url, bearer ? { headers: { authorization: `Bearer ${bearer}` } } : undefined);
+}

package/package.json

@@ -1,48 +1,44 @@
 {
   "name": "@vocalstack/js-sdk",
-  "version": "1.1.0",
-  "description": "A JavaScript API Client and SDK for VocalStack",
-  "author": "VocalStack",
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/vocalstack/js-sdk.git"
-  },
+  "version": "2.0.0-alpha.0",
+  "description": "VocalStack speech API SDK for Node and browsers: one client (VocalStack) grouped by resource, typed from the generated contract, with realtime WebSocket streaming.",
+  "license": "MIT",
+  "type": "module",
   "engines": {
-    "node": ">=16.20.2",
-    "npm": ">=8.19.4"
+    "node": ">=20"
   },
   "main": "./dist/index.js",
-  "typings": "./dist/index.d.ts",
-  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mic": {
+      "types": "./dist/mic.d.ts",
+      "default": "./dist/mic.js"
+    }
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "skills"
+  ],
   "scripts": {
-    "lint": "eslint",
-    "build": "rm -rf ./dist && npm i && tsc && tsc -p tsconfig.esm.json",
-    "docs": "rm -rf ./documentation && npm run --prefix ./../website script:docs -- $(node -e \"console.log(process.cwd())\")",
-    "prepublish": "npm run docs",
-    "prepare": "tsc -p tsconfig.esm.json"
+    "build": "npm run build --prefix contract && tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "ws": "^8.18.0",
-    "zod": "^3.23.8"
+    "@vocalstack/contract": "1.0.0-alpha.0",
+    "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@types/node": "^22.9.0",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "typescript": "^5.3.3"
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.6.0"
   },
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "keywords": [
-    "vocalstack",
-    "api",
-    "sdk",
-    "transcription",
-    "livestream",
-    "ASR",
-    "speech-to-text",
-    "speech-to-speech"
-  ]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vocalstack/js-sdk.git"
+  }
 }

package/skills/vocalstack/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: vocalstack
+description: Use when writing Node or TypeScript code that calls the VocalStack speech API with @vocalstack/js-sdk, for example to transcribe an audio or video URL or a local file, stream live audio for realtime transcription, fetch or export a transcript (JSON, SRT, XLSX, PDF), or search transcripts. Covers installing, API keys, base URLs, five copy-paste programs and error handling (401, 402, 403, 429).
+---
+
+# VocalStack TypeScript SDK
+
+The VocalStack API transcribes speech (files, links, live audio), with speaker
+labels and translation. `@vocalstack/js-sdk` has one client, `VocalStack`, with
+one group per resource: `vs.transcriptions`, `vs.jobs`, `vs.recordings`,
+`vs.broadcasts`, `vs.search`, `vs.realtime` and a few more (listed at the end).
+
+## What is what
+
+- A **transcription** is a file, a link, a microphone or a stream, transcribed
+  and stored. Create one with `vs.transcriptions.create(...)`.
+- A **recording** is one take inside it. Its id (`recordingId`) is what you
+  read the transcript and exports with: `vs.recordings.transcript(recordingId)`.
+- A **job** is a file or link recording's transcription work:
+  `vs.jobs.wait(recordingId)` polls it until it is `done` or `failed`
+  (`{ onProgress: (job) => … }` sees each read: `job.state`, `job.progress.pct`).
+- A **batch** is many files transcribed together for less than one
+  transcription each: `vs.batches.create()`, `addFile`/`addUrl` per file,
+  `start`, then `wait` (section 6).
+- A **broadcast** is a link listeners open to follow a live recording.
+- A **realtime session** (`vs.realtime`) is a socket you stream audio into and
+  read the transcript from. Nothing is stored. "Session" means only this.
+
+## Install
+
+```sh
+npm init -y && npm pkg set type=module   # in a new folder: the programs below are ESM
+npm i @vocalstack/js-sdk                    # Node 20 or newer
+```
+
+Before the package is published, any account installs
+the private build its environment serves: the API reference's Install section
+(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
+give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
+Or install it from a clone of https://github.com/vocalstack/js-sdk. Build it
+first (`npm run build` also builds the bundled `contract/` package):
+
+```sh
+git clone https://github.com/vocalstack/js-sdk && (cd js-sdk && npm install && npm run build)
+npm i ./js-sdk
+```
+
+Use ESM (`"type": "module"` in package.json, or `.mjs` files).
+
+Speaker numbers start at 0. A speaker of `-1` means speaker labels were off
+for that transcription, so print the text without a speaker.
+
+## Auth and base URL
+
+- Read the key from `VOCALSTACK_API_KEY` and pass it as `apiKey`. It goes out
+  as `Authorization: Bearer <key>`, also on sockets.
+- An API key starts with `vs_key_`. There is one kind of key: every call is
+  real usage on the account's tier and quotas.
+- Keys are for servers. Never put a key in browser code or in a URL. The API
+  refuses a key sent from a web page (`Origin` header) or in a query string.
+- Scopes: `read` (read transcripts, search, export), `write` and
+  `recordings:publish` (create transcriptions, stream live audio), or `*`.
+- Base URL: `https://api.vocalstack.com` (the default). Override it with
+  `VOCALSTACK_BASE_URL` (for example, a local or staging server).
+
+Every program below starts like this:
+
+```js
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({
+  baseUrl: process.env.VOCALSTACK_BASE_URL, // absent: https://api.vocalstack.com
+  apiKey: process.env.VOCALSTACK_API_KEY,
+});
+```
+
+## 1. Transcribe a URL and wait for the result
+
+The server fetches the link itself, so it must be a public http(s) address.
+Private, loopback and cloud-metadata addresses are refused.
+
+```js
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+const tx = await vs.transcriptions.create({
+  url: 'https://raw.githubusercontent.com/openai/whisper/main/tests/jfk.flac',
+  name: 'JFK sample',
+});
+const recordingId = tx.job.recordingId;
+
+// queued -> fetching -> transcribing -> done | failed
+const job = await vs.jobs.wait(recordingId);
+if (job.state !== 'done') throw new Error(`transcription ${job.state}: ${job.error}`);
+
+const { sentences } = await vs.recordings.transcript(recordingId);
+for (const s of sentences) console.log(s.speaker >= 0 ? `[speaker ${s.speaker}] ${s.text}` : s.text);
+console.log('recordingId', recordingId);
+```
+
+## 2. Transcribe a local file
+
+```js
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+const tx = await vs.transcriptions.create({
+  file: process.argv[2], // a path (mp3, wav, flac, ogg, m4a, mp4 ...), a Blob or bytes
+  settings: { spokenLanguage: 'en', speakerLabels: 'on' }, // both optional; speakerLabels: 'off' (default) | 'auto' | 'on'
+  // Off unless asked for: settings.summary, settings.title, settings.summaryTranslations,
+  // settings.voice (spoken translations), and shareLink: true (a public share link).
+});
+const job = await vs.jobs.wait(tx.job.recordingId);
+if (job.state !== 'done') throw new Error(`transcription ${job.state}: ${job.error}`);
+
+const { sentences } = await vs.recordings.transcript(job.recordingId);
+console.log(sentences.map((s) => s.text).join(' '));
+```
+
+## 3. Fetch a transcript or an export file
+
+`recordings.transcript` returns segments (with word timings), sentences and
+speakers. `recordings.export` returns the file as a `Response`: formats `json`,
+`srt`, `xlsx`, `pdf`; add `{ lang: '<code>' }` for a translated file.
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+const recordingId = process.argv[2];
+
+const snap = await vs.recordings.transcript(recordingId);
+console.log(`${snap.segments.length} segments, ${snap.sentences.length} sentences, state ${snap.state}`);
+
+const res = await vs.recordings.export(recordingId, 'srt');
+await writeFile('transcript.srt', Buffer.from(await res.arrayBuffer()));
+```
+
+## 4. Live transcription from a microphone or a file
+
+A live transcription takes raw PCM: 32-bit float little-endian, 16 kHz, mono.
+Create it, start a recording, and open the publisher socket the grant names.
+Here ffmpeg decodes a file at realtime speed (`-re`). For a microphone, swap
+the input: `-f avfoundation -i :0` on macOS, `-f pulse -i default` on Linux.
+(`@vocalstack/js-sdk/mic` is for browsers, and browsers must not hold API keys.)
+
+```js
+import { spawn } from 'node:child_process';
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+const tx = await vs.transcriptions.createLive({ name: 'Live demo', settings: { spokenLanguage: 'en' } });
+const grant = await vs.transcriptions.startRecording(tx.id);
+const stream = await vs.recordings.publish(grant, { readyDeadlineMs: 180_000 }); // a cold engine can take a while
+
+const ff = spawn('ffmpeg', ['-loglevel', 'error', '-re', '-i', process.argv[2],
+  '-f', 'f32le', '-ac', '1', '-ar', '16000', '-']);
+ff.stdout.on('data', (chunk) => stream.sendAudio(new Uint8Array(chunk)));
+ff.on('close', () => stream.eof()); // eof() ends the recording
+
+for await (const ev of stream) {
+  if (ev.type === 'transcript.committed') console.log(`[speaker ${ev.segment.speaker}] ${ev.segment.text}`);
+  // also: 'transcript.draft' (replaces the live tail), 'transcript.sentence', 'transcript.translated'
+}
+
+// To end a recording without eof(): vs.recordings.pause(id), then vs.recordings.stop(id).
+const { sentences } = await vs.recordings.transcript(grant.recording.id);
+console.log('final:', sentences.map((s) => s.text).join(' '));
+```
+
+To transcribe without storing anything, use a realtime session instead:
+`await vs.realtime.transcribeFile('talk.mp3')` returns `{ text, segments }`.
+
+## 5. Search transcripts
+
+```js
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+const { hits } = await vs.search.query(process.argv[2] ?? 'country', { limit: 5 }); // q: 2+ characters
+for (const h of hits) {
+  console.log(`${h.linkName} @ ${h.mediaStart.toFixed(1)}s [speaker ${h.speaker}]: ${h.text} (recording ${h.recordingId})`);
+}
+```
+
+## 6. A batch of files
+
+Many files at once cost less as a batch: one create, one minimum charge for
+the whole batch. Its files get transcripts, exports and speaker labels (when
+`settings.speakerLabels` asks), never a summary, title, share link or voices.
+
+```js
+import { VocalStack } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+const batch = await vs.batches.create({ name: 'Interviews', settings: { spokenLanguage: 'en' } });
+for (const path of process.argv.slice(2)) await vs.batches.addFile(batch.id, { file: path }); // or addUrl(batch.id, url)
+await vs.batches.start(batch.id);
+const done = await vs.batches.wait(batch.id); // done (or stopped); check done.counts.failed
+for (const tx of done.files ?? []) {
+  if (tx.job?.state !== 'done') continue;
+  const { sentences } = await vs.recordings.transcript(tx.job.recordingId);
+  console.log(tx.name, sentences.map((s) => s.text).join(' '));
+}
+// vs.batches.export(batch.id, 'srt') is every finished transcript in one zip.
+```
+
+## Errors
+
+A failed call throws `VocalStackError` with `code`, `message`, `status`,
+`retryable`, `details` (the body's `data.details`), `headers` and
+`retryAfter` (seconds, from `Retry-After`). A `429`, and a `503 unavailable`
+on a call that is safe to repeat, is retried for you after its `Retry-After`,
+twice by default (`maxRetries` on the client).
+
+| Status | `code` | What to do |
+|---|---|---|
+| 401 | `invalid_token`, `key_expired`, `key_revoked` | Check `VOCALSTACK_API_KEY`. Use the replacement key, or create a new one. |
+| 403 | `forbidden` | Usually a missing scope: the message names it, and `err.headers.get('www-authenticate')` lists the scopes the route needs. A suspended key or account gets `suspended`. |
+| 403 | `terms_acceptance_required` | The account has not accepted the current Terms of Service and Privacy Policy: someone signs in to the Dashboard and accepts them (an organisation's keys work once an owner or admin has). Not retryable until then. |
+| 402 | `insufficient_credit` | The account's credit is out, or does not cover the transcription: every transcription is billed at least the plan's minimum (`rates.minimumSeconds`, 5 minutes). `details`: `balance`, `plan`, `topUpUrl`, and `required` when the cost was known up front. Add credit; `vs.billing.get()` shows the balance. |
+| 409 | `payment_method_required` | Auto top-up (`vs.billing.setAutoTopUp`) and the portal (`vs.billing.portal()`) need a payment first (`vs.billing.createCheckout({ kind: 'topup', amount, acceptTerms: true })` opens one; a signed-in person's token, never an API key). |
+| 402 | `quota_exceeded` | The plan's transcriptions-at-once limit is reached. `details`: `metric` (`concurrent_transcriptions`), `limit`, `used`, `plan`, `topUpUrl`. |
+| 429 | `rate_limited` | Retried automatically; if it still fails, wait `err.retryAfter` seconds. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. |
+| 503 | `unavailable` | The service is waking (its database was asleep). Retried automatically after `Retry-After` (2 s) on calls that are safe to repeat: GET, HEAD, DELETE, or any call with `{ idempotencyKey }`. A create without a key is not retried: retry it yourself, with an `idempotencyKey` so it cannot run twice. A realtime socket refused this way throws `unavailable`; a bare 503 there is `capacity_exceeded`. |
+
+```js
+import { VocalStack, VocalStackError } from '@vocalstack/js-sdk';
+const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
+
+try {
+  await vs.search.query('country');
+} catch (err) {
+  if (!(err instanceof VocalStackError)) throw err;
+  if (err.code === 'insufficient_credit' || err.code === 'quota_exceeded') console.error(err.message, err.details);
+  else console.error(err.status, err.code, err.message);
+}
+```
+
+## More
+
+- The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
+  `restore`, `purge`, `listShareLinks`, `createShareLink`), `vs.recordings`
+  (`get`, `summarize`, `summary`, `translation`, `audioUrl`, `subscribe` for a
+  live transcript feed), `vs.batches` (`create`, `addFile`, `addUrl`, `start`,
+  `wait`, `get`, `list`, `export`, `stop`, `delete`), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+  `vs.broadcasts`, `vs.me` (`get`, `usage`), `vs.languages`,
+  `vs.rtmp`, `vs.events`, `vs.meta`. Each method is named after its operation
+  in the OpenAPI document (`transcriptions.create` is `POST /v1/transcriptions`).
+- `<base>/llms.txt` lists every operation in a form written for agents.
+  `<base>/llms-full.txt` adds parameters, auth mode, tier and scopes.
+- `<base>/docs` is the interactive reference. `<base>/v1/openapi.json` is
+  the OpenAPI document; the SDK's types are generated from it.

package/dist/ApiVersion.d.ts

@@ -1,2 +0,0 @@
-export declare const EXPECTED_VOCALSTACK_API_VERSION = "1.1.0";
-export declare const verifyApiVersion: (actualVersion: string | null, discontinued?: boolean) => void;

package/dist/ApiVersion.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyApiVersion = exports.EXPECTED_VOCALSTACK_API_VERSION = void 0;
-exports.EXPECTED_VOCALSTACK_API_VERSION = '1.1.0';
-const verifyApiVersion = (actualVersion, discontinued = false) => {
-    if (!actualVersion) {
-        throw new Error('VocalStack API version is missing.');
-    }
-    if (discontinued) {
-        throw Error(`The VocalStack API has undergone a new release (v.${actualVersion}) and no longer supports this SDK. Please update the SDK to the latest version by running 'npm update @vocalstack/js-sdk'.`);
-    }
-    const [major, minor, patch] = parseVersion(actualVersion);
-    const [expectedMajor, expectedMinor, expectedPatch] = exports.EXPECTED_VOCALSTACK_API_VERSION.split('.').map((v) => parseInt(v, 10));
-    if (major < expectedMajor ||
-        (major === expectedMajor && minor < expectedMinor) ||
-        (major === expectedMajor && minor === expectedMinor && patch < expectedPatch)) {
-        throw new Error(`VocalStack API version ${actualVersion} is lower than that expected by this SDK. Expected version >= ${exports.EXPECTED_VOCALSTACK_API_VERSION}`);
-    }
-    if (major > expectedMajor || (major === expectedMajor && minor > expectedMinor)) {
-        const type = major > expectedMajor ? 'major' : 'minor';
-        console[type === 'major' ? 'error' : 'warn'](`The VocalStack API has undergone a new ${type} release (v.${actualVersion}). Your SDK version may not support all new API features. Consider updating by running 'npm update @vocalstack/js-sdk'.`);
-    }
-};
-exports.verifyApiVersion = verifyApiVersion;
-function parseVersion(version) {
-    const regex = /^\d+\.\d+\.\d+$/;
-    if (!regex.test(version)) {
-        throw new Error(`Invalid version format: ${version}. Expected format "major.minor.patch" with numeric segments.`);
-    }
-    const segments = version.split('.').map((v) => parseInt(v, 10));
-    return [segments[0], segments[1], segments[2]];
-}

package/dist/RestApi.d.ts

@@ -1,21 +0,0 @@
-export type ApiResponse<T> = {
-    status: 'waiting' | 'processing' | 'done' | 'error';
-    data?: null | T;
-    success: boolean;
-    error?: string;
-};
-export type RequestOptions = RequestInit & {
-    json?: Record<string, unknown>;
-};
-export declare class RestApi {
-    private apiServer;
-    private headers;
-    constructor(apiServer: string, headers: Record<string, string>);
-    get<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
-    post<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
-    put<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
-    patch<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
-    delete<T>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
-    private apiCall;
-    private respond;
-}