@speechrouter/sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,17 +1,20 @@
-# @speechrouter/sdk
+# speechrouter
 
-One API for every speech model — [speechrouter.ai](https://speechrouter.ai).
+One API for every speech model — [speechrouter.ai](https://speechrouter.ai)
 
-Streaming speech-to-text over WebSocket with mid-stream provider failover,
-plus batch transcription. Works in browsers, Node ≥ 18, and React Native.
-Zero runtime dependencies.
+Streaming speech-to-text over WebSocket with **mid-stream provider failover**,
+plus batch transcription. One key, one schema, 30+ models across 12 providers —
+switch vendors by editing a string.
+
+- **Works everywhere** — browsers, Node ≥ 18, React Native, edge runtimes
+- **Zero runtime dependencies**
+- **Fully typed** — every wire event and error code ships as a TypeScript type
 
 ```sh
-npm install speechrouter        # canonical
-npm install @speechrouter/sdk   # same client, scoped
+npm install speechrouter
 ```
 
-## Streaming
+## Quickstart — live transcription
 
 ```ts
 import { SpeechRouter } from "speechrouter";
@@ -20,76 +23,238 @@ const sr = new SpeechRouter({ apiKey: "sk_sr_..." });
 
 const stream = sr.listen({
   model: "deepgram/nova-3",
-  fallbacks: ["soniox/stt-rt-v5"],   // dies mid-stream? we switch, you keep captioning
+  fallbacks: ["soniox/stt-rt-v5"], // primary dies mid-stream? we switch, you keep captioning
 });
 
+stream.on("open", (s) => console.log("session", s.session_id));
 stream.on("transcript", (t) => {
-  if (t.is_final) console.log(t.text);
+  if (t.is_final) console.log("✔", t.text);
+  else console.log("…", t.text);
 });
-stream.on("provider_switched", (s) => console.log(`failover: ${s.from} → ${s.to}`));
+stream.on("provider_switched", (s) =>
+  console.log(`failover: ${s.from} → ${s.to}, resumed at ${s.resumed_at}s`),
+);
+stream.on("error", (e) => console.error(e.code, e.message));
+
+stream.sendAudio(pcmChunk); // 16-bit linear PCM, 16 kHz mono by default
 
-stream.sendAudio(pcmChunk);            // 16-bit linear PCM, 16 kHz mono by default
-const { usage } = await stream.stop(); // finalize → transcript tail → usage
+const done = await stream.stop(); // finalize → transcript tail → usage
+console.log(done.usage); // { audio_seconds: 12.4, model: "deepgram/nova-3" }
 ```
 
-Or consume the session as an async stream:
+Prefer async iteration? Every session is an `AsyncIterable` of wire events:
 
 ```ts
 for await (const event of stream) {
   if (event.type === "transcript" && event.is_final) console.log(event.text);
+  if (event.type === "provider_switched") console.log("failover!");
 }
 ```
 
 ## Microphone (browser)
 
+`speechrouter/mic` captures the default mic, resamples whatever rate the
+browser gives you (96 kHz interfaces included) down to 16 kHz PCM, and pumps
+it into the stream:
+
 ```ts
+import { SpeechRouter } from "speechrouter";
 import { openMicrophone } from "speechrouter/mic";
 
-const mic = await openMicrophone(stream, { onLevel: (rms) => meter.style.width = `${rms * 300}px` });
-// later: mic.stop(); await stream.stop();
+const stream = new SpeechRouter({ apiKey }).listen({ model: "deepgram/flux-general-en" });
+const mic = await openMicrophone(stream, {
+  onLevel: (rms) => (meter.style.width = `${rms * 300}px`),
+});
+
+// later:
+mic.stop();
+const { usage } = await stream.stop();
+```
+
+It's a separate entry point so React Native and server bundles never touch
+browser APIs.
+
+## React
+
+```tsx
+function Captions({ apiKey }: { apiKey: string }) {
+  const [text, setText] = useState("");
+  const [interim, setInterim] = useState("");
+
+  useEffect(() => {
+    const stream = new SpeechRouter({ apiKey }).listen({ model: "deepgram/nova-3" });
+    const offT = stream.on("transcript", (t) =>
+      t.is_final ? (setText((p) => p + " " + t.text), setInterim("")) : setInterim(t.text),
+    );
+    let mic: { stop(): void } | undefined;
+    void import("speechrouter/mic").then(async (m) => (mic = await m.openMicrophone(stream)));
+    return () => {
+      offT();
+      mic?.stop();
+      stream.close();
+    };
+  }, [apiKey]);
+
+  return <p>{text} <i>{interim}</i></p>;
+}
+```
+
+## React Native
+
+The core client is RN-safe (global WebSocket, no Node or DOM APIs). Capture
+PCM with a native module and feed the stream:
+
+```ts
+import LiveAudioStream from "react-native-live-audio-stream";
+import { Buffer } from "buffer";
+
+LiveAudioStream.init({ sampleRate: 16000, channels: 1, bitsPerSample: 16, bufferSize: 4096 });
+const stream = sr.listen({ model: "deepgram/nova-3" });
+LiveAudioStream.on("data", (b64) => stream.sendAudio(Buffer.from(b64, "base64")));
+LiveAudioStream.start();
 ```
 
-Captures the default mic, resamples whatever rate the browser gives you
-(96 kHz interfaces included) down to 16 kHz PCM, and pumps it into the stream.
+For batch uploads, pass an RN file descriptor: `{ uri, name, type }`.
+
+## Node
+
+```ts
+import { createReadStream } from "node:fs";
+
+// stream a file as if it were live audio
+const stream = sr.listen({ model: "soniox/stt-rt-v5" });
+for await (const chunk of createReadStream("call.raw", { highWaterMark: 8000 })) {
+  stream.sendAudio(chunk);
+  await new Promise((r) => setTimeout(r, 40)); // pace ~real-time when required
+}
+const { usage } = await stream.stop();
+```
 
-In React Native, capture PCM with a native module (e.g.
-`react-native-live-audio-stream`) and call `stream.sendAudio(chunk)` — the
-core client is RN-safe and never imports browser APIs.
+Node 22+ uses the built-in WebSocket. Node 18–21: `npm install ws`
+(optional peer dependency, picked up automatically).
 
-## Batch
+## Batch transcription
 
 ```ts
+// simplest: { text }
 const { text } = await sr.transcribe({ model: "cartesia/ink-whisper", file });
 
-// subtitles straight out:
-const srt = await sr.transcribe({ model: "deepgram/nova-3", file, responseFormat: "srt" });
+// word timings, language, duration
+const verbose = await sr.transcribe({ model: "deepgram/nova-3", file, responseFormat: "verbose_json" });
+
+// subtitles straight out
+const srt = await sr.transcribe({ model: "groq/whisper-large-v3", file, responseFormat: "srt" });
+
+// let the gateway fetch the audio itself
+await sr.transcribe({ model: "deepgram/nova-3", url: "https://example.com/call.mp3" });
 ```
 
-`file` accepts a browser `File`/`Blob`, raw bytes (`Uint8Array`/`ArrayBuffer`),
-or a React Native descriptor `{ uri, name, type }`. Pass `url` instead to have
-the gateway fetch the audio itself.
+| `responseFormat` | returns |
+| --- | --- |
+| `json` (default) | `{ text }` |
+| `verbose_json` | text + words with timings + language + duration |
+| `srt` / `vtt` | subtitle file as a string — synthesized from word timings even when the vendor won't |
+| `text` | plain string |
+
+`file` accepts a `File`/`Blob`, `Uint8Array`/`ArrayBuffer`, or a React Native
+descriptor `{ uri, name, type }`. Files up to 250 MB.
 
 ## Models
 
 ```ts
-const models = await sr.listModels(); // slugs, capabilities, live pricing
+const models = await sr.listModels();
+// [{ slug: "deepgram/nova-3", modes: ["streaming","batch"], pricing: {...}, capabilities: {...} }, ...]
 ```
 
+Live catalog with pricing: [speechrouter.ai/models](https://speechrouter.ai/models)
+
+## `listen()` options
+
+| option | default | |
+| --- | --- | --- |
+| `model` | — | model slug, e.g. `"deepgram/nova-3"` |
+| `fallbacks` | `[]` | ordered failover lane; audio is replayed into the takeover so no words are lost |
+| `encoding` | `"linear16"` | PCM encoding of the audio you send |
+| `sampleRate` | `16000` | sample rate of the audio you send |
+| `channels` | `1` | channel count |
+| `language` | auto | BCP-47 hint |
+| `interimResults` | `true` | emit non-final hypotheses |
+| `diarization` | `false` | speaker labels on words |
+| `keyterms` | `[]` | bias recognition toward these terms |
+| `includeRaw` | `false` | attach the untouched provider payload to every transcript |
+| `providerParams` | `{}` | escape hatch: raw params forwarded to the provider |
+| `connectTimeoutMs` | `10000` | dial timeout |
+| `keepAlive` | `true` (8s) | keep the session alive through silences; `false` to disable — an open session bills wall-clock time on session-billed providers |
+
+## Events
+
+| event | payload | when |
+| --- | --- | --- |
+| `open` | `session_id`, `model` | gateway accepted the session |
+| `transcript` | `is_final`, `text`, `words[]` (`w`,`start`,`end`,`conf`,`speaker`), `provider_raw?` | hypothesis or final |
+| `provider_switched` | `from`, `to`, `resumed_at`, `speaker_mapping_preserved` | mid-stream failover happened |
+| `done` | `usage.audio_seconds`, `usage.model` | session complete — also resolves `stream.done()` |
+| `error` | `SpeechRouterError` | anything went wrong |
+| `close` | `code?`, `reason?` | socket closed (always last) |
+| `event` | any wire event | firehose — includes `speech_started`, `utterance_end`, `text.delta`, … |
+
+**`ListenStream` methods:** `sendAudio(chunk)` (queued if the socket isn't open
+yet) · `finalize()` · `stop()` → usage · `close()` · `done()` · `bufferedAmount`
+· `state` · `session`.
+
 ## Errors
 
-Everything throws or emits `SpeechRouterError` with a machine-readable
-`code` (`insufficient_credits`, `concurrency_exceeded`, `provider_error`,
-…), the upstream `provider` when known, and a `recoverable` hint.
+Everything throws or emits `SpeechRouterError`:
+
+```ts
+try {
+  await sr.transcribe({ model: "deepgram/nova-3", file });
+} catch (e) {
+  if (e instanceof SpeechRouterError && e.code === "insufficient_credits") topUp();
+}
+```
+
+| `code` | meaning |
+| --- | --- |
+| `auth_failed` / `key_revoked` | bad or revoked API key |
+| `insufficient_credits` | balance empty — top up |
+| `concurrency_exceeded` | too many simultaneous streams for your org |
+| `model_not_found` / `unsupported_capability` / `unsupported_encoding` | request can't be routed as asked |
+| `invalid_request` / `payload_too_large` | malformed input / file over 250 MB |
+| `provider_error` / `provider_timeout` | upstream vendor failed (`e.provider` says which); with fallbacks these become a `provider_switched` instead |
+| `all_providers_failed` | primary and every fallback failed |
+| `audio_timeout` | no audio or keepalive long enough that the gateway hung up |
+| `connection_failed` / `connection_closed` / `timeout` | client-side network conditions |
+
+`e.recoverable` hints whether retrying the same request may succeed.
 
 ## Self-hosting
 
-Point the client at your own gateway:
+The gateway is Apache-2.0 and runs anywhere Docker runs. Point the SDK at yours:
 
 ```ts
 new SpeechRouter({ apiKey, baseUrl: "http://localhost:8080" });
 ```
 
-Note for browsers: an API key shipped to a page is public. Mint short-lived
-keys from your backend, or proxy the socket.
+## Browsers & mobile: short-lived tokens
+
+An API key shipped to a page is public — never do it. Instead, your backend
+mints a short-lived token and hands it to the client:
+
+```ts
+// backend (key stays here)
+const { token } = await sr.createToken({ ttlSeconds: 60 });
+
+// client (browser / React Native)
+const client = new SpeechRouter({ apiKey: token });
+const stream = client.listen({ model: "deepgram/nova-3" });
+```
+
+The TTL only limits how long the token can *open* connections — a stream
+that's already running continues past expiry. Default 60s, max 300s.
+
+---
+
+Apache-2.0 · [gateway & protocol spec](https://github.com/speech-router/speechrouter) · [console](https://speechrouter.ai) · [live models & pricing](https://speechrouter.ai/models)
 
-Apache-2.0 · [protocol spec](https://github.com/speech-router/speechrouter/tree/main/packages/spec) · [gateway](https://github.com/speech-router/speechrouter)
+> `@speechrouter/sdk` is a hard re-export of [`speechrouter`](https://www.npmjs.com/package/speechrouter) — same code, same class identities. Docs use the canonical name.

package/index.cjs

@@ -0,0 +1 @@
+module.exports = require('speechrouter')

package/index.d.ts

@@ -0,0 +1 @@
+export * from 'speechrouter'

package/index.js

@@ -0,0 +1 @@
+export * from 'speechrouter'

package/mic.cjs

@@ -0,0 +1 @@
+module.exports = require('speechrouter/mic')

package/mic.d.ts

@@ -0,0 +1 @@
+export * from 'speechrouter/mic'

package/mic.js

@@ -0,0 +1 @@
+export * from 'speechrouter/mic'

package/package.json

@@ -1,64 +1,20 @@
 {
   "name": "@speechrouter/sdk",
-  "version": "0.1.1",
-  "description": "One API for every speech model \u2014 official TypeScript SDK for speechrouter.ai. Streaming STT with mid-stream failover, batch transcription. Browser, Node, React Native.",
+  "version": "0.3.0",
+  "description": "One API for every speech model — official TypeScript SDK for speechrouter.ai. Streaming STT with mid-stream failover, batch transcription. Browser, Node, React Native.",
   "license": "Apache-2.0",
   "homepage": "https://speechrouter.ai",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/speech-router/speechrouter.git",
-    "directory": "packages/sdk-js"
-  },
-  "keywords": [
-    "speech-to-text",
-    "stt",
-    "transcription",
-    "streaming",
-    "websocket",
-    "deepgram",
-    "whisper",
-    "react-native"
-  ],
+  "repository": { "type": "git", "url": "git+https://github.com/speech-router/speechrouter.git", "directory": "packages/sdk-ts" },
+  "keywords": ["speech-to-text", "stt", "transcription", "streaming", "websocket", "deepgram", "whisper", "react-native"],
   "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./mic": {
-      "import": {
-        "types": "./dist/mic.d.ts",
-        "default": "./dist/mic.js"
-      },
-      "require": {
-        "types": "./dist/mic.d.cts",
-        "default": "./dist/mic.cjs"
-      }
-    }
+    ".": { "types": "./index.d.ts", "import": "./index.js", "require": "./index.cjs" },
+    "./mic": { "types": "./mic.d.ts", "import": "./mic.js", "require": "./mic.cjs" }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
+  "files": ["index.js", "index.cjs", "index.d.ts", "mic.js", "mic.cjs", "mic.d.ts", "README.md"],
   "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "peerDependencies": {
-    "ws": ">=8"
-  },
-  "peerDependenciesMeta": {
-    "ws": {
-      "optional": true
-    }
-  }
-}
+  "dependencies": { "speechrouter": "^0.3.0" }
+}