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

package/LICENSE

@@ -1,21 +1,21 @@
-VocalStack Proprietary License
-
-Copyright (C) 2024 VocalStack
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use the Software solely in connection with the VocalStack service, subject to the following conditions:
-
-## Usage Limitations
-
-1. **Compliance with Terms of Service**: The Software must be used in a manner that does not violate the VocalStack terms of service ([https://www.vocalstack.com/terms-of-service](https://www.vocalstack.com/terms-of-service)).
-
-2. **Commercial Use Allowed**: The Licensed Work may be used for commercial purposes, provided the user has a valid API key and an active subscription to the VocalStack service. Unauthorized use is strictly prohibited.
-
-3. **Modification and Contributions**: You may view and modify the Licensed Work for internal use only. Contributions to the Licensed Work may be made through pull requests. By submitting a contribution, you agree to assign the rights of the contribution to VocalStack.
-
-4. **Redistribution Allowed**: Redistribution of the Software, in whole or in part, whether modified or unmodified, is permitted, provided that it does not violate the company's terms of service.
-
-5. **Termination**: VocalStack reserves the right to terminate your access to and use of the Software at any time if you fail to comply with these terms.
-
-## Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT License
+
+Copyright (c) 2026 VocalStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,89 +1,132 @@
-[![](/logo.svg 'VocalStack')](https://vocalstack.com)
+# @vocalstack/js-sdk
 
-> VocalStack is a platform that can be used for building voice applications. See more at [https://vocalstack.com](vocalstack.com).
+The VocalStack speech API for Node (20 or newer) and browsers: one client,
+`VocalStack`, with one group per resource, typed from the API's one OpenAPI
+document (`/v1/openapi.json`, generated into `@vocalstack/contract`).
 
-This repository contains the official VocalStack SDK for JavaScript. It provides a simple way
-to interact with the [VocalStack API](https://vocalstack.com/api).
-Most notably, it helps implement asynchronous bidirectional communication
-such as live stream transcriptions in just a few lines of code.
-This SDK will work in both Node.js and the browser.
+```ts
+import { VocalStack } from '@vocalstack/js-sdk';
 
+const vs = new VocalStack({ apiKey: process.env.VOCALSTACK_API_KEY }); // baseUrl defaults to https://api.vocalstack.com
 
-# Installation
+// A stored transcription of a link (or `file:` a path, Blob or bytes).
+const tx = await vs.transcriptions.create({ url: 'https://example.com/talk.mp3' });
+const job = await vs.jobs.wait(tx.job!.recordingId); // done | failed | cropping
+const { sentences } = await vs.recordings.transcript(job.recordingId);
 
-Before you start, install the VocalStack JavaScript SDK using your preferred Node package manager, such as npm:
-
-```bash
-npm install @vocalstack/js-sdk
+const srt = await (await vs.recordings.export(job.recordingId, 'srt')).text();
 ```
 
-Also make sure to have a [VocalStack account](https://vocalstack.com) and an API key, which you can generate
-at https://vocalstack.com/dashboard/api-keys.
-There is a free tier available, so you can start experimenting right away.
-
-
-# Quick Example
-
-Here is a quick example of how to use the SDK to transcribe a file from a URL:
-```javascript
-import { UrlTranscription } from '@vocalstack/js-sdk';
-
-const sdk = new UrlTranscription({ apiKey: 'YOUR-API-KEY' });
-const transcription = await sdk.connect({
-  url: 'http://example.com/files/meaningless.mp3',
+<!-- sdk-docs: generated from the VocalStack API guides; edits here are overwritten -->
+
+## Install
+
+Not on npm yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+
+## Guides
+
+- [Quickstart](https://github.com/vocalstack/js-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
+- [Transcribe a file](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
+- [Transcribe a link](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a batch of files](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-batch.md): Send many files or links as one batch, start it once, and read every transcript when it is done. Cheaper than one transcription per file.
+- [Stream a microphone](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
+- [Stream a file at full speed](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
+- [Go live](https://github.com/vocalstack/js-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.
+- [Listen](https://github.com/vocalstack/js-sdk/blob/main/docs/listen.md): Follow a recording as it happens, in any language: subscribe, catch up from a snapshot, then apply live frames in order.
+- [Live translation and spoken translations](https://github.com/vocalstack/js-sdk/blob/main/docs/translation-and-voices.md): Translate a stream as it is spoken, and have each translated sentence spoken back in a voice. Text frames and audio clips, over the same socket.
+- [Connect an app with one click](https://github.com/vocalstack/js-sdk/blob/main/docs/connect-an-app.md): Let the people who use your app connect their VocalStack account with one Authenticate click — OAuth 2.0 authorization code with PKCE, where the access token is an API key — instead of pasting a key.
+- [Errors, retries and limits](https://github.com/vocalstack/js-sdk/blob/main/docs/errors-and-limits.md): One error envelope everywhere; what to retry (429, 503 unavailable) and how to make a retry safe (Idempotency-Key); credit, plan limits and the 402s.
+
+<!-- /sdk-docs -->
+
+## What is what
+
+| Name | What it is | Group |
+|---|---|---|
+| realtime session | a signed token plus one socket; nothing stored | `vs.realtime` |
+| broadcast | the link listeners open | `vs.broadcasts` |
+| transcription | a file, link, microphone or stream, transcribed and stored (`live: true` for a microphone or stream) | `vs.transcriptions` |
+| recording | one take inside a broadcast or a transcription | `vs.recordings` |
+| job | a file or link recording's transcription work | `vs.jobs` |
+| batch | many files transcribed together, for less than one transcription each | `vs.batches` |
+
+The other groups: `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+`vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
+Method names follow the document's `operationId`s (`broadcasts.startRecording`
+is `POST /v1/broadcasts/{id}/recordings`); lists return arrays.
+
+## Options
+
+```ts
+new VocalStack({
+  baseUrl,          // default https://api.vocalstack.com
+  apiKey,           // an API key (vs_key_…), for a server
+  token,            // or, in a browser: an access token / browser token, or a getter (read per request)
+  actingPrincipal,  // act for an organization (X-Acting-Principal)
+  deviceId,         // correlation only (X-Device-Id)
+  fetch,            // any fetch
+  maxRetries: 2,    // 429s, and 503 unavailable on safe calls, retried after Retry-After (at most 60 s each)
+  readyDeadlineMs,  // how long a realtime socket may take to report ready
 });
-
-transcription.start();
-
-// This will print the transcription data as it comes in
-transcription.onData(console.log);
-
-/*
-{
-  status: 'processing',
-  data: {
-    id: 'd1e7b3b0-7b3b-4b3b-8b3b-0b3b7b3b3b3b',
-    operation: 'transcription-prerecorded',
-    progress: 0.1,
-    timeline: [
-      {
-        start: 0,
-        end: 7.52,
-        text: 'Meaningless, meaningless, says the teacher, utterly meaningless, everything is meaningless.',
-        language: 'en',
-        translations: { ... },
-      },
-      ...
-    ]
-  }
-}
-*/
 ```
 
+Every call that creates something takes `{ idempotencyKey }` last.
 
-# Documentation Index
+## Realtime sessions
 
-- [Transcribe Audio from URL](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcribe-audio-from-url-to-text.md): 
-Transcribe speech from pre-recorded audio in a URL to plain text. Major file formats are supported, including MP3, WAV, FLAC, and OGG.
+```ts
+const session = await vs.realtime.connect({ spokenLanguage: 'en' });
+session.sendAudio(pcmChunk); // raw PCM, f32le, 16 kHz, mono, as binary frames
+for await (const event of session) {
+  if (event.type === 'transcript.committed') render(event.segment);
+}
+session.eof(); // at end of source: final commits, then session.done
 
-- [Transcribe from a Microphone or LiveStream](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcribe-from-a-microphone-or-live-stream.md): 
-Transcribe live speech from a microphone or live stream. Integrate with Polyglot to create a public shareable link for the transcription which users can read in any language. 
+// A whole file through one socket, nothing stored:
+const { text, segments } = await vs.realtime.transcribeFile('meeting.mp3', { spokenLanguage: 'en' });
+```
 
-- [Transcribe and Present a Polyglot Session](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcribe-and-present-a-polyglot-session.md): 
-Create a session that can be used to broadcast a live transcription via a public shareable link. Users can read live transcriptions in their preferred language, and even past transcriptions when your session is inactive.
+- `transcript.draft` frames **fully replace** the live tail; never append them.
+- `transcript.committed` segments are immutable, gapless by `segment.seq`,
+  and carry word timings.
+- A dropped connection ends the session (no resume): start a new one.
+
+## Live recordings and listeners
+
+```ts
+const b = await vs.broadcasts.create({ name: 'Release standup' }); // b.code is the link
+const grant = await vs.broadcasts.startRecording(b.id);           // 409 conflict + details.takeover
+                                                                  // when another device records
+const stream = await vs.recordings.publish(grant);                // the publisher socket
+await vs.recordings.pause(grant.recording.id);
+await vs.recordings.resume(grant.recording.id);
+await vs.recordings.stop(grant.recording.id);                     // only from paused
+
+// A listener (no account), holding a share link's code:
+const link = await vs.broadcasts.createShareLink(b.id, { label: 'Audience' });
+const anon = new VocalStack({ baseUrl, deviceId });
+const sub = await anon.recordings.subscribe(grant.recording.id, { lang: 'es', shareCode: link.code, asOwner: false });
+for await (const ev of sub) {
+  if (ev.type === 'snapshot') render(ev.snapshot); // backfill, initial or after a gap
+  if (ev.type === 'frame') apply(ev.frame);        // transcript.*, recording.state, ...
+}
+```
 
-- [Translate a Transcription](https://github.com/vocalstack/js-sdk/blob/main/documentation/translate-transcription-to-another-language.md): 
-Translate transcribed text to another language. This can be done for any transcription, including prerecorded transcriptions, live transcriptions or Polyglot session transcriptions.
+Browser microphone capture ships as `@vocalstack/js-sdk/mic`
+(`streamMicrophone(session, { onStall, onRecover })`).
 
-- [Get Transcription Data](https://github.com/vocalstack/js-sdk/blob/main/documentation/get-transcription-data.md): 
-Get data from pending or completed transcriptions. This includes the transcription timeline, key words, summary, and paragraph segments.
+## Errors
 
-- [Client Side Authentication Tokens](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcribe-on-the-front-end-with-auth-tokens.md): 
-Create a temporary authentication token for client side requests. Safely implement API requests in web browsers without exposing your API keys.
+`VocalStackError` carries `code` (the contract's closed enum), `message`,
+`status`, `retryable`, `details` (quota numbers, code suggestions,
+`{ recordingId, takeover }`), `headers` and `retryAfter`.
 
-- [Transcription Sessions](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcription-sessions.md): 
-Monitor and manage transcription state with sessions. Using sessions you can reconnect to a previously created asynchronous connection.
+## Binary answers
 
-- [Transcription Request and Response](https://github.com/vocalstack/js-sdk/blob/main/documentation/transcription-request-and-response.md): 
-Common request options and responses for all transcription operations. Use options to configure the transcription settings.
+`recordings.export`, `recordings.clip`, `recordings.voiceClip`, `jobs.preview`,
+`voices.preview`, `voices.clonePreview` and `voices.sample` return the
+`Response` itself: `.text()`, `.arrayBuffer()` or stream it.
+`recordings.audioUrl` returns the signed media URL.
 
+Verified against a language-agnostic conformance suite shared by every
+VocalStack SDK and against a running API. For agents: `SKILL.md`.

package/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/errors.d.ts

@@ -0,0 +1,40 @@
+import type { ErrorCode } from '@vocalstack/contract';
+/** The OAuth errors `vs.connect.token()` raises (RFC 6749 §5.2): the token
+ * endpoint answers `400 { error, error_description }`, not the envelope. */
+export type ConnectTokenErrorCode = 'invalid_request' | 'invalid_grant' | 'unsupported_grant_type';
+export interface VocalStackErrorOptions {
+    retryable?: boolean;
+    status?: number;
+    details?: unknown;
+    headers?: Headers;
+    requestId?: string;
+}
+/** Every failure this SDK surfaces: an HTTP error envelope, a socket
+ * `error` frame, or one the transport synthesizes (`capacity_exceeded`). */
+export declare class VocalStackError extends Error {
+    /** The envelope's code; on `vs.connect.token()`, the OAuth `error`. */
+    readonly code: ErrorCode | ConnectTokenErrorCode;
+    readonly retryable: boolean;
+    /** HTTP status, when the error came from an HTTP response. */
+    readonly status?: number;
+    /** The envelope's `data.details`: for example `{ balance, required,
+     * plan, topUpUrl }` on `insufficient_credit`, code suggestions on a
+     * link conflict, `{ recordingId, takeover: true }` when another device
+     * is recording. */
+    readonly details?: unknown;
+    /** The response headers (`Retry-After`, `RateLimit-*`,
+     * `WWW-Authenticate`), when the error came from an HTTP response. */
+    readonly headers?: Headers;
+    /** The request's id (the envelope's `requestId`, else the `X-Request-Id`
+     * header): quote it when reporting a failure. */
+    readonly requestId?: string;
+    constructor(code: ErrorCode | ConnectTokenErrorCode, message: string, opts?: VocalStackErrorOptions);
+    /** Seconds the server asked the caller to wait (`Retry-After`), if it said. */
+    get retryAfter(): number | undefined;
+}
+export declare function capacityExceeded(message: string): VocalStackError;
+export declare function fromEnvelope(body: unknown, status?: number, headers?: Headers): VocalStackError;
+/** A token endpoint's `400 { error, error_description }` (RFC 6749 §5.2) as
+ * a `VocalStackError` whose `code` is the `error`; any other answer goes
+ * through the envelope. */
+export declare function fromOAuth(body: unknown, status?: number, headers?: Headers): VocalStackError;

package/dist/errors.js

@@ -0,0 +1,74 @@
+/** Every failure this SDK surfaces: an HTTP error envelope, a socket
+ * `error` frame, or one the transport synthesizes (`capacity_exceeded`). */
+export class VocalStackError extends Error {
+    /** The envelope's code; on `vs.connect.token()`, the OAuth `error`. */
+    code;
+    retryable;
+    /** HTTP status, when the error came from an HTTP response. */
+    status;
+    /** The envelope's `data.details`: for example `{ balance, required,
+     * plan, topUpUrl }` on `insufficient_credit`, code suggestions on a
+     * link conflict, `{ recordingId, takeover: true }` when another device
+     * is recording. */
+    details;
+    /** The response headers (`Retry-After`, `RateLimit-*`,
+     * `WWW-Authenticate`), when the error came from an HTTP response. */
+    headers;
+    /** The request's id (the envelope's `requestId`, else the `X-Request-Id`
+     * header): quote it when reporting a failure. */
+    requestId;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = 'VocalStackError';
+        this.code = code;
+        this.retryable = opts.retryable ?? false;
+        this.status = opts.status;
+        this.details = opts.details;
+        this.headers = opts.headers;
+        this.requestId = opts.requestId;
+    }
+    /** Seconds the server asked the caller to wait (`Retry-After`), if it said. */
+    get retryAfter() {
+        const v = this.headers?.get('retry-after');
+        if (v == null || v === '')
+            return undefined;
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+        const at = Date.parse(v);
+        return Number.isNaN(at) ? undefined : Math.max(0, (at - Date.now()) / 1000);
+    }
+}
+export function capacityExceeded(message) {
+    return new VocalStackError('capacity_exceeded', message, { retryable: true });
+}
+export function fromEnvelope(body, status, headers) {
+    const b = body;
+    // The envelope names the request; a header the page cannot read across
+    // origins (when it is not exposed) is the fallback.
+    const requestId = (b && typeof b.requestId === 'string' ? b.requestId : undefined) ?? headers?.get('x-request-id') ?? undefined;
+    if (b && typeof b.code === 'string') {
+        return new VocalStackError(b.code, b.message ?? b.code, {
+            retryable: b.data?.retryable ?? false,
+            status,
+            details: b.data?.details,
+            headers,
+            requestId,
+        });
+    }
+    return new VocalStackError('internal', `unexpected error (status ${status})`, { status, headers, requestId });
+}
+/** A token endpoint's `400 { error, error_description }` (RFC 6749 §5.2) as
+ * a `VocalStackError` whose `code` is the `error`; any other answer goes
+ * through the envelope. */
+export function fromOAuth(body, status, headers) {
+    const b = body;
+    if (status === 400 && b && typeof b.error === 'string') {
+        return new VocalStackError(b.error, b.error_description ?? b.error, {
+            status,
+            headers,
+            requestId: headers?.get('x-request-id') ?? undefined,
+        });
+    }
+    return fromEnvelope(body, status, headers);
+}

package/dist/file.d.ts

@@ -0,0 +1,2 @@
+export type FileInput = string | Uint8Array | ArrayBuffer | Blob | AsyncIterable<Uint8Array>;
+export declare function fileChunks(input: FileInput): AsyncIterable<Uint8Array>;