@voxevolv/client 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to `@voxevolv/client` are recorded here.
 
+## Unreleased
+
+## 0.3.0 - 2026-07-24
+
+- Add opt-in SDK-owned recovery with `autoRejoin`, bounded backoff, terminal
+  disconnect-reason handling, and the `resuming` connection state.
+- Surface signal-only LiveKit reconnects instead of skipping directly from
+  `connected` to readiness restoration.
+- Add `hasConnectedBefore`, `onRecovery()`, `onConnectionQuality()`, and
+  `waitForState()`.
+- Make rejoin disconnect based on the underlying LiveKit room state so a
+  failed post-reconnect hello cannot leave a connected room in the way.
+- Add configurable lifecycle fetch credentials with a `same-origin` default,
+  preserving cookie-authenticated same-origin proxies while omitting cookies
+  on direct cross-origin calls.
+- End an in-flight recovery cleanly when the server emits `session.ended`
+  instead of leaving the wrapper state at `resuming`.
+- Preserve the outer `rejoin` recovery when late LiveKit reconnect events
+  arrive during that attempt, preventing them from moving the wrapper back to
+  `reconnecting` and blocking the replacement connection.
+- Preserve the user's microphone mute state across manual and automatic full
+  rejoin so recovery never returns with a previously muted microphone enabled.
+- Keep commands pending when the first post-reconnect data publish is rejected,
+  allowing the existing retry loop to deliver them once the data channel is
+  writable.
+
+## 0.2.0 - 2026-07-20
+
+- Add `session.outputStream`: a stable `MediaStream` that always holds the
+  agent's current remote audio tracks across track arrival, reconnects, and
+  rejoin.
+- `connect()` now also waits for the first remote agent audio track (within
+  the same `readyTimeoutMs` budget) before resolving, so media is flowing when
+  connect resolves. Pass `waitForRemoteAudio: false` to restore the previous
+  signaling-only readiness.
+
 ## 0.1.0 - 2026-07-18
 
 - Add application-owned audio-track publication and remote-audio access.

package/README.md

@@ -26,7 +26,7 @@ Browsers without a build step can use the versioned bundle after publication:
 ```html
 <script type="module">
   import { RealtimeSession } from
-    "https://cdn.jsdelivr.net/npm/@voxevolv/client@0.1.0/dist/browser/index.js";
+    "https://cdn.jsdelivr.net/npm/@voxevolv/client@0.3.0/dist/browser/index.js";
 </script>
 ```
 
@@ -38,9 +38,10 @@ VoxEvolv session without exposing an organization API key:
 ```ts
 const session = await RealtimeSession.create({
   endpoint: "/api/voice-session",
-  // Recommended: expose the scoped lifecycle routes through your backend.
-  // An allowlisted absolute VoxEvolv API URL is also supported.
-  apiBase: "/api/voxevolv/v1",
+  // Use the hosted API directly when its lifecycle CORS policy is public.
+  // A same-origin lifecycle proxy remains supported.
+  apiBase: "https://YOUR_VOXEVOLV_HOST/v1",
+  autoRejoin: true,
   tools: {
     present_attachment: (arguments_) => presentAttachment(arguments_),
   },
@@ -60,7 +61,8 @@ play remote audio:
 
 ```ts
 const session = new RealtimeSession(credentials, {
-  connect: { apiBase: "/api/voxevolv/v1" },
+  connect: { apiBase: "https://YOUR_VOXEVOLV_HOST/v1" },
+  autoRejoin: true,
 });
 await session.connect({ microphone: true });
 ```
@@ -100,11 +102,59 @@ a native `MediaStreamTrack` and single-track `MediaStream` for recording,
 metering, or another application-owned audio graph. Both listener registration
 methods return an unsubscribe function.
 
-## Rejoin and end
+## Agent audio readiness
 
-`rejoin()` can be called from a connected or disconnected state. It obtains a
-fresh room token, disconnects an existing room connection when necessary, and
-reconnects with the original microphone or application-owned track choice.
+By default `connect()` resolves only after the agent reported readiness *and*
+the first remote agent audio track arrived, both within the same
+`readyTimeoutMs` budget (15 s by default). Agent media is therefore already
+flowing when `connect()` resolves, so recording or metering set up right after
+`connect()` does not race track arrival.
+
+`session.outputStream` is a stable `MediaStream` available from session
+creation. The stream object never changes; remote agent audio tracks are added
+when they arrive and removed when they end, including across `rejoin()` and
+reconnects. Note that Web Audio's `createMediaStreamSource()` requires the
+stream to already contain an audio track, so audio-graph consumers should
+still attach inside `onRemoteAudioTrack`.
+
+Applications that intentionally run without agent audio can opt out:
+
+```ts
+await session.connect({ waitForRemoteAudio: false });
+```
+
+## Recovery, rejoin, and connection quality
+
+Set `autoRejoin: true` to let the SDK own recovery after LiveKit exhausts its
+transport-level reconnect. Automatic recovery runs only after the session has
+connected successfully, never after an explicit `disconnect()`, `end()`, or
+terminal LiveKit removal. It waits for browser connectivity, obtains a fresh
+room token, and retries with bounded backoff.
+
+```ts
+session.onStateChange((state) => {
+  // reconnecting: LiveKit is restoring transport
+  // resuming: VoxEvolv is restoring readiness with a fresh connection
+  renderConnectionState(state);
+});
+
+session.onRecovery(({ status, strategy, attempt, error }) => {
+  recordRecovery({ status, strategy, attempt, error });
+});
+
+session.onConnectionQuality((quality) => {
+  renderCallQuality(quality);
+});
+```
+
+`session.hasConnectedBefore` distinguishes recovery from initial setup.
+`waitForState(states, timeoutMs, { signal })` is available for advanced flows
+that need to await a bounded set of lifecycle states.
+
+Manual `rejoin()` remains available. It obtains a fresh room token, disconnects
+any underlying room connection, and reconnects with the original microphone or
+application-owned track choice. A managed microphone that the user muted with
+`setMicrophoneEnabled(false)` remains muted after rejoin.
 
 ```ts
 await session.rejoin();
@@ -113,8 +163,8 @@ await session.end();
 
 `RealtimeSession.create()` requires `apiBase` because rejoin, durable replay,
 and scoped ending happen after the application-owned creation request. Set it
-to either an explicit absolute VoxEvolv `/v1` base whose deployment allowlists
-the application origin, or a same-origin proxy base that forwards only:
+to either an explicit absolute VoxEvolv `/v1` base (browser lifecycle access is
+enabled by default), or a same-origin proxy base that forwards only:
 
 - `POST /sessions/{id}/room-tokens`
 - `GET /sessions/{id}/events`
@@ -123,6 +173,12 @@ the application origin, or a same-origin proxy base that forwards only:
 The proxy must forward the browser's `Authorization: Bearer vsa_...` header. It
 must not replace that credential with an organization API key.
 
+Lifecycle fetches default to `credentials: "same-origin"`. This sends cookies
+to a same-origin proxy but not to an absolute cross-origin VoxEvolv API. Set
+`lifecycleCredentials` only when a custom proxy has a different credential
+policy; cross-origin `include` requires an exact-origin credentialed CORS
+configuration and is incompatible with wildcard CORS.
+
 `end()` uses the browser-safe `vsa_...` credential to end only that session and
 then leaves the LiveKit room. Pass `endEndpoint` to the constructor or
 `end({ endpoint })` when application policy requires a backend completion route.