@connekz/connekz-agent 2.3.2 → 2.4.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [2.4.0] - 2026-07-19 (Minor Release)
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Security
+
+## [Unreleased]
+
+### Added
+
+- **Transport ladder (websocket-first)**: the socket now connects over a direct websocket by default (no cookies or load-balancer sticky sessions required), falling back to polling+upgrade and polling-only when websockets are blocked. Fixes the mobile Safari / cross-site embed failure where blocked third-party cookies caused endless `400 "Session ID unknown"` loops behind the ALB. The last working transport is remembered per browser for fast reconnects.
+- **Capability detection layer** (`Layer 0`): WebSocket/fetch, secure context, mic API, Web Audio, AudioWorklet and storage are detected up front. Impossible features fail fast with precise messages; degraded modes are chosen automatically.
+- **Inline audio worklet**: the worklet processor is bundled and loaded from a Blob URL — no same-origin file or CDN required (previous `404 connekz-worklet-processor.js` noise is gone). Same-origin file and CDN remain as CSP fallbacks, and capture falls back to ScriptProcessor on browsers without AudioWorklet.
+- **Structured server error handling**: the client now consumes the server's `connection_error` event (`INVALID_CREDENTIALS`, `TOKEN_EXPIRED`, `UNAUTHORIZED_DOMAIN`, `QUOTA_EXCEEDED`) and maps it to precise error codes instead of generic "unable to connect".
+- New error codes: `CNKZ_ERR_1006` (offline), `CNKZ_ERR_1007` (token expired), `CNKZ_ERR_1008` (unauthorized domain), `CNKZ_ERR_1009` (browser unsupported), `CNKZ_ERR_1010` (voice unsupported — text chat continues to work).
+- `connekzSocket.getDiagnostics()` — connection internals snapshot (transport, attempts, last error, capabilities) for support/debugging.
+- iOS audio robustness: WebKit `interrupted` state handling with resume-on-gesture for both capture and playback contexts.
+
+### Changed
+
+- Reconnection now uses exponential backoff with instant retry on `online`/tab-visible/bfcache-restore events; offline is surfaced as its own state instead of a server error.
+- `"Session ID unknown"` is classified as a retryable transport problem (load-balancer session affinity loss), no longer misreported as an authentication failure.
+- Mic initialization no longer retries permission-denied / no-microphone / unsupported-environment errors (fails fast with the right message; transient errors still retry).
+- Voice capture sample rate now follows the audio context rate (fixes potential pitch-shifted audio on iOS audio routes where track and context rates disagree).
+- `userIdentity` persistence and transport memory use safe storage wrappers — Safari private mode and sandboxed iframes can no longer crash init.
+- Connection error screen shows a "Retrying automatically" hint for retryable errors.
+
+### Fixed
+
+### Security
+
 ## [2.3.2] - 2026-07-14 (Patch Release)
 
 ### Added

package/README.md

@@ -157,8 +157,53 @@ Socket is automatically managed with agent start/stop. The following methods ava
 connekzSocket.connect(); // Force optional
 connekzSocket.disconnect();
 connekzSocket.cleanup(); // Remove listeners
+connekzSocket.getDiagnostics(); // Connection internals snapshot (see Reliability below)
 ````
 
+## Reliability & Browser Support
+
+The agent is engineered to connect from any modern browser on any host page — including mobile Safari/Chrome and cross-site embeds — without any special setup on your side.
+
+### Transport ladder
+
+Instead of relying on Socket.IO defaults, the agent walks a transport ladder until one connects:
+
+1. **websocket** (default) — a direct websocket connection. Needs no cookies or sticky sessions, which makes it reliable behind load balancers and on browsers that block third-party cookies (Safari/iOS on cross-site embeds).
+2. **polling + websocket upgrade** — HTTP long-polling with credentials, for networks/proxies that block raw websockets.
+3. **polling only** — last resort for middleboxes that break the websocket upgrade.
+
+The last strategy that worked is remembered (localStorage, best effort), so repeat visits connect fast. Retries use exponential backoff and resume instantly when the tab becomes visible again or the browser comes back online (including iOS back/forward-cache restores).
+
+### Voice pipeline
+
+- The audio worklet processor ships **inside the bundle** (loaded from a Blob URL) — no extra file to host, no CDN dependency. If your site's CSP forbids `blob:` workers (`worker-src`), serve `worklet-processor.js` at `/connekz-worklet-processor.js` on your origin, or allow `https://storage.connekz.com`.
+- Browsers without AudioWorklet automatically fall back to ScriptProcessor-based capture.
+- iOS audio interruptions (phone calls, Siri, route changes) are detected and playback/capture resume automatically, retrying on the next tap if the browser requires a user gesture.
+- If the environment can never support voice (http page, no microphone API — e.g. some in-app browsers), the agent shows a clear message and **text chat keeps working**.
+
+### Error codes
+
+Subscribe with `connekzAgent.subscribe.onError((err) => ...)`. Codes:
+
+| Code | Meaning | Retried automatically? |
+|------|---------|------------------------|
+| `CNKZ_ERR_1001` | Server unreachable (network, proxy, server down) | Yes — transport ladder + backoff |
+| `CNKZ_ERR_1002` | Invalid clientId / clientSecret | No — fix credentials in the developer portal |
+| `CNKZ_ERR_1003` | Quota / token limit exceeded | No — manage your plan in the developer portal |
+| `CNKZ_ERR_1004` | Network too weak for voice | n/a — suggests text chat |
+| `CNKZ_ERR_1005` | Agent runtime error | n/a |
+| `CNKZ_ERR_1006` | Browser is offline | Yes — reconnects when connectivity returns |
+| `CNKZ_ERR_1007` | Session/ephemeral token expired | No — mint a fresh token and re-init |
+| `CNKZ_ERR_1008` | Page origin not in the instance's Authorized Domains | No — add the exact origin in the portal |
+| `CNKZ_ERR_1009` | Browser unsupported (no realtime transport) | No |
+| `CNKZ_ERR_1010` | Voice unsupported here (text chat still works) | No |
+
+### Troubleshooting
+
+- Call `connekzSocket.getDiagnostics()` in the browser console and include the output in support requests — it reports the transport in use, attempt counts, the last classified error, and the browser's capability snapshot.
+- `400 "Session ID unknown"` loops in the network tab mean long-polling lost its load-balancer session (typically third-party cookies blocked). The current package avoids this entirely by connecting websocket-first; if you see it, update to the latest version.
+- Voice on iOS requires the page to be served over **https** and the user to tap to start (browser autoplay policy).
+
 ## Integration Tips
 - Frontend Embedding: Mount built-in UI or use headless APIs to integrate into existing apps.
 - Backend/Automations: Use headless APIs for server-side task running or integrations.