@voxevolv/client 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `@voxevolv/client` are recorded here.
 
+## 0.3.5 - 2026-09-23
+
+- Preserve global client command order across concurrent context keys and prevent
+  timer updates from being overtaken by screen updates at the LiveKit publish boundary.
+- Add opt-in SDK-owned initial connection recovery with three default attempts,
+  increasing 15/20/25-second readiness budgets, bounded delays, and a 65-second
+  overall startup deadline.
+- Renew the same session's room token between startup attempts while keeping
+  intermediate failures nonterminal.
+- Add `onStartupAttempt()` progress events for connecting and retrying UI.
+- Stop startup retry on terminal HTTP, session, microphone, and audio errors;
+  preserve one configured credential refresh after `401` and honor explicitly
+  retryable `session.error` events.
+- Preserve caller options across startup attempts, retry transient network
+  failures, and enforce the startup deadline during token renewal.
+- Keep explicit startup cancellation disconnected and deliver command timeouts
+  even when an earlier command is still waiting to publish.
+
 ## 0.3.4 - 2026-09-22
 
 - Add a typed `trigger` and safe command correlation fields to every recovery event.

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.3.4/dist/browser/index.js";
+    "https://cdn.jsdelivr.net/npm/@voxevolv/client@0.3.5/dist/browser/index.js";
 </script>
 ```
 
@@ -41,6 +41,7 @@ const session = await RealtimeSession.create({
   // 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",
+  startupRetry: true,
   autoRejoin: true,
   tools: {
     present_attachment: (arguments_) => presentAttachment(arguments_),
@@ -64,6 +65,7 @@ play remote audio:
 ```ts
 const session = new RealtimeSession(credentials, {
   connect: { apiBase: "https://YOUR_VOXEVOLV_HOST/v1" },
+  startupRetry: true,
   autoRejoin: true,
 });
 await session.connect({ microphone: true });
@@ -125,6 +127,61 @@ Applications that intentionally run without agent audio can opt out:
 await session.connect({ waitForRemoteAudio: false });
 ```
 
+## Initial connection retries
+
+Set `startupRetry: true` to let the SDK retry a session that has not connected
+successfully yet. The default policy makes three total attempts with 15, 20,
+and 25-second readiness budgets, waits one second before attempt two and three
+seconds before attempt three, and enforces a 65-second overall deadline. The
+overall deadline also includes room connection, token renewal, microphone
+publication, the client hello, and remote-audio readiness.
+
+Attempt one uses the room token returned at session creation. Later attempts
+obtain a fresh room token for the same VoxEvolv session ID. Intermediate
+failures remain nonterminal; `connect()` rejects and the session enters
+`failed` only when the attempts are exhausted, the overall deadline expires,
+or a terminal error occurs.
+
+```ts
+const session = await RealtimeSession.create({
+  endpoint: "/api/voice-session",
+  apiBase: "https://YOUR_VOXEVOLV_HOST/v1",
+  startupRetry: true,
+  autoRejoin: true,
+});
+
+session.onStartupAttempt(({ status, attempt, maxAttempts, error }) => {
+  if (status === "started" && attempt > 1) {
+    renderConnectionStatus(`Retrying connection (${attempt}/${maxAttempts})…`);
+  }
+  if (status === "failed") recordStartupFailure(attempt, error);
+});
+
+await session.connect();
+```
+
+Custom policies use explicit attempts. `delayBeforeMs` is the wait before that
+attempt. When startup retry is enabled, each attempt's `readyTimeoutMs` replaces
+the single timeout supplied through `connect()` or the constructor defaults.
+
+```ts
+startupRetry: {
+  attempts: [
+    { readyTimeoutMs: 15_000 },
+    { delayBeforeMs: 1_000, readyTimeoutMs: 20_000 },
+    { delayBeforeMs: 3_000, readyTimeoutMs: 25_000 },
+  ],
+  timeoutMs: 65_000,
+}
+```
+
+The SDK does not retry invalid audio configuration, microphone permission or
+device errors, non-retryable `session.error` events, or non-transient HTTP 4xx
+responses such as `401`, `403`, and `409 Session has ended`. A configured
+`refreshCredentials` callback still gets one opportunity to replace expired
+credentials after a `401`. A `session.error` explicitly marked
+`retryable: true` may advance to the next startup attempt.
+
 ## Recovery, rejoin, and connection quality
 
 With `@voxevolv/client@0.3.2` or newer, set `autoRejoin: true` to let the SDK recover
@@ -158,9 +215,9 @@ or replayed during recovery because repeating them could duplicate input. Update
 already in flight may have reached the server even if their acknowledgment was lost.
 
 Keep the existing `RealtimeSession` instance during recovery, register tools on
-that instance, and use `onStateChange` / `onRecovery` for UI. Avoid application
-retry loops that create new sessions. Older clients remain API-compatible but
-need the SDK upgrade to gain agent-loss detection and context restoration.
+that instance, and use `onStateChange`, `onStartupAttempt`, and `onRecovery` for
+UI. Avoid application retry loops that create new sessions. Older clients remain
+API-compatible but need the SDK upgrade to gain these recovery behaviors.
 
 ```ts
 session.onStateChange((state) => {