@origonai/web-sdk 0.1.0

package/docs/voice.md

@@ -0,0 +1,165 @@
+# Voice (WebTransport + WASM Opus)
+
+## Wire summary
+
+| Layer        | Tech                                                                 |
+|--------------|----------------------------------------------------------------------|
+| Transport    | WebTransport (`https://<media-server>/web`), one bidi control sub-stream + datagrams |
+| Control      | B2BUA verbs (Connect/ConnectOk/Mute/Resume/PeerAttached/…), `msg_type (vi) \| payload_len (vi) \| payload` |
+| Audio        | Opus 48 kHz mono, 20 ms frames (50 per wall-second), `ObjectDatagram` per frame |
+| Group / object IDs | `group_id = floor(Date.now()/1000) - server_epoch_unix`, `object_id ∈ [0..49]`, `end_of_group` on object 49 |
+| Reconnect    | Tier-3 `Resume { call_token, last_event_seq }` only — browsers expose no QUIC migration / 0-RTT |
+| Audio engine | WASM, prebuilt + committed at `src/voice/audio/wasm-gen/` (vendored libopus; see "The WASM audio engine is prebuilt") |
+
+See [`backend-integration.md`](backend-integration.md) (canonical spec) for the full wire definitions.
+
+## Required browser features (the SDK-wide floor)
+
+| Feature                | Needed by                                        |
+|------------------------|--------------------------------------------------|
+| WebTransport           | **Chat AND voice** — chat is orpc-over-WebTransport only (no SSE fallback), voice rides connection + datagrams |
+| AudioWorklet           | Voice only — the real-time audio thread          |
+
+**WebTransport is the floor for the whole SDK**: chat has no non-WT
+transport (owner decision 2026-08-06), so browsers without WebTransport
+(Safari, Firefox today) are unsupported for chat and voice alike.
+
+Datagrams cross the main ↔ worklet boundary as port messages with
+transferred buffers — no `SharedArrayBuffer`, so the page needs **no
+COOP/COEP / cross-origin-isolation headers**. Voice works on any page that
+has WebTransport (including the embed widget on a third-party host page).
+
+## The WASM audio engine is prebuilt
+
+The WASM audio engine ships **prebuilt and committed** at
+`src/voice/audio/wasm-gen/` (`origon_web_audio.js` + `origon_web_audio_bg.wasm`
++ type declarations). Building or publishing this repo needs **no Rust, no
+wasm toolchain** — `pnpm i && pnpm build` is the whole story.
+
+The engine's Rust source lives in the Origon monorepo (`apps/sdk/web`, the
+`web-audio` crate) and is regenerated there with
+`apps/sdk/web/scripts/build-wasm.sh`, which rebuilds the artifact into this
+repo's `wasm-gen/` and stamps the `PROVENANCE` file beside it (source git SHA,
+crate + toolchain versions, artifact byte size). Treat `wasm-gen/` as
+generated output: never edit it by hand, and take updates only through the
+ship script so `PROVENANCE` stays truthful.
+
+### The wasm-bindgen glue inside the AudioWorklet
+
+The AudioWorklet thread has no ES-module loader, so `src/voice/audio/audio-processor.ts` imports the generated `wasm-gen/origon_web_audio.js` directly and `pnpm build:worklet` (Vite, IIFE) bundles the two into a single self-contained `audio-processor.js` (an intermediate `.worklet-build/` output that the main build then ships as the `audio/audio-processor.js` asset). After a reshipped `wasm-gen/`, just re-run `pnpm build` — no hand-editing of glue entries.
+
+## Voice assets: emitted by YOUR bundler
+
+The voice path needs two files at runtime — the AudioWorklet bundle
+(`audio/audio-processor.js`) and the Opus pipeline wasm
+(`audio/wasm-gen/origon_web_audio_bg.wasm`). The shipped SDK bundle
+references them as relative, unresolved
+`new URL('./audio/…?no-inline', import.meta.url)` literals, so **your
+bundler emits and relocates them automatically** when you build — there
+is nothing to configure and nothing to host by hand.
+
+Requirements:
+
+- **Vite ≥ 6.3.3** (or another bundler that supports the
+  `new URL(..., import.meta.url)` asset pattern and strips the
+  `?no-inline` query from the emitted URL). Below 6.3.3 the query leaks
+  into the emitted asset URL and the fetch 404s — and an SPA-fallback
+  server can mask that 404 as a 200 `text/html` response that only
+  fails later, inside `audioWorklet.addModule()`
+  (`AbortError: Unable to load a worklet's module`). **After any
+  bundler upgrade, re-verify both asset fetches return
+  `text/javascript` / `application/wasm`, never `text/html`.**
+- **CSP**: the pipeline compiles its wasm from fetched bytes
+  (`WebAssembly.compile`), so a page with a Content-Security-Policy
+  needs `'wasm-unsafe-eval'` in `script-src`. No COOP/COEP is needed
+  (see above).
+
+### `assetBaseUrl` — the copy-step escape hatch
+
+If your pipeline cannot relocate the literals (e.g. esbuild-only),
+copy the two files to a served location **preserving the `audio/…`
+layout**, and point the SDK at it:
+
+```ts
+client.initialize({
+  endpoint: 'https://your-control-plane',
+  assetBaseUrl: 'https://cdn.example.com/web-sdk/',
+  // voice then fetches <base>/audio/audio-processor.js
+  //             and    <base>/audio/wasm-gen/origon_web_audio_bg.wasm
+})
+```
+
+Cost note: the bundler-relocation branch is emitted at build time
+regardless, so a bundling consumer that sets `assetBaseUrl` still emits
+(and deploys) ~490 KB of wasm it never fetches. The override changes
+which URLs are fetched at call time; it does not remove the emitted
+copies.
+
+## Public voice API
+
+```ts
+import { getSessionManager } from '@origonai/web-sdk'
+
+const client = getSessionManager()
+client.initialize({
+  endpoint: 'https://your-control-plane',
+  token: '<bearer>',
+  userId: '<your-user>',
+  // assetBaseUrl: '…' — only for non-relocating pipelines, see above
+})
+client.setCallbacks({
+  onConnected:    (sessionId) => console.log('voice connected:', sessionId),
+  onReconnecting: (id, ch, { attempt, reason }) => console.log('reconnecting', attempt, reason),
+  onReconnected:  (sessionId) => console.log('back online'),
+  onPeerAttached: (id, ch, peer) => console.log('peer joined:', peer),
+  onPeerDetached: (id, ch, peer) => console.log('peer left:', peer),
+  onDisconnected: (id, ch, { reason }) => console.log('disconnected:', reason),
+  onCallError:    (id, ch, msg) => console.warn('call error:', msg),
+})
+
+// Supplied out of band by the application's control plane.
+const listenOffer = { sessionId: '<id>', url: '<media-url>', token: '<call-token>' }
+const { sessionId } = await client.joinSession({
+  channel: 'voice',
+  sessionId: listenOffer.sessionId,
+  url: listenOffer.url,
+  token: listenOffer.token,
+  voice: { receiveOnly: true },
+})
+
+await client.setMute(sessionId, 'uplink')   // 'uplink' | 'downlink' | 'both' | 'none'
+
+// For a provisioned receive-only join, enter and leave microphone capture
+// without exposing an unmuted permission/acquisition window.
+await client.enableCapture(sessionId)
+await client.releaseCapture(sessionId)
+
+const unsubscribe = client.subscribeAudioStats(sessionId, (stats) => {
+  // stats.outboundLevel  — local mic RMS (0..1)
+  // stats.inboundLevel   — playback RMS (0..1)
+  // stats.pipeline       — { tracks: [{ alias, jitter_ms, plc_count, … }] }
+})
+
+// Later
+unsubscribe()
+await client.endSession(sessionId)
+```
+
+## Reconnect behaviour
+
+When `wt.closed` fires unexpectedly (no `EndpointHangup` or terminal `MoqError` arrived first), the SDK runs:
+
+```
+1. wait 100ms
+2. open new WebTransport
+3. send Resume { call_token, last_event_seq }
+4. on ResumeOk → restore peer aliases + mute scope from EndpointSnapshot
+5. fire onReconnected
+```
+
+Backoff schedule: `[100, 250, 500, 1000]` ms. Fires `onReconnecting({attempt, reason})` before each attempt. After the four retries, fires `onDisconnected({reason: 'networkLoss'})`.
+
+Terminal close paths that skip the retry loop:
+- We called `endSession()` (`reason: 'localClose'`)
+- Received `EndpointHangup` (`reason: 'remoteHangup'` for `origin: 'peer'`)
+- Received `MoqError` with a terminal code (`tokenInvalid`, `tokenExpired`, `tokenReplayed`, `sessionEnded`, `replayLost`, `endpointNotProvisioned`, `endpointAlreadyConnected`)

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@origonai/web-sdk",
+  "version": "0.1.0",
+  "description": "Origon Web SDK - chat and voice session client",
+  "type": "module",
+  "packageManager": "pnpm@11.5.1",
+  "main": "./dist/origon-web-sdk.js",
+  "module": "./dist/origon-web-sdk.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/origon-web-sdk.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/origon/web-sdk.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "check:wasm": "test -f src/voice/audio/wasm-gen/origon_web_audio.js && test -f src/voice/audio/wasm-gen/origon_web_audio_bg.wasm || { echo '✗ wasm-gen incomplete — it ships prebuilt and committed; restore it from git (regenerated only from the Origon monorepo: apps/sdk/web/scripts/build-wasm.sh)' >&2; exit 1; }",
+    "check:orpc": "test -f src/orpc-gen/index.ts && test -f src/orpc-gen/chat_pb.ts && test -f src/orpc-gen/PROVENANCE || { echo '✗ orpc-gen incomplete — it ships vendored and committed; restore it from git (regenerated only from the Origon monorepo: web/kit/scripts/ship-orpc.sh)' >&2; exit 1; }",
+    "build": "pnpm check:wasm && pnpm check:orpc && pnpm build:worklet && pnpm build:main",
+    "build:main": "vite build --mode production",
+    "build:worklet": "BUILD_TARGET=worklet vite build --mode production",
+    "dev": "pnpm build && pnpm build:main --watch --mode development",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "deploy": "pnpm build && npm publish --access public"
+  },
+  "keywords": [
+    "chat",
+    "voice",
+    "sdk",
+    "origon",
+    "moq",
+    "webtransport"
+  ],
+  "author": "Origon",
+  "license": "MIT",
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "magic-string": "^0.30.21",
+    "typescript": "^5.4.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}