@voxevolv/client 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@voxevolv/client` are recorded here.
+
+## 0.1.0 - 2026-07-18
+
+- Add application-owned audio-track publication and remote-audio access.
+- Add `RealtimeSession.create()`, lifecycle helpers, typed convenience events,
+  credential refresh, and guarded rejoin behavior.
+- Add a self-contained browser ESM bundle with source maps and SHA-384
+  integrity metadata.
+- Add explicit package exports for npm and CDN consumers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoxEvolv contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# `@voxevolv/client`
+
+Browser SDK for connecting to a scoped VoxEvolv realtime session.
+
+## Build and test
+
+```bash
+npm install
+npm test
+```
+
+The build emits ESM JavaScript, declarations, declaration maps, and source maps
+into `dist/`. It also emits a self-contained browser bundle at
+`dist/browser/index.js`; that bundle does not need an import map. Its SHA-384
+integrity value is written to `dist/browser/index.js.sha384` and
+`dist/browser/manifest.json`.
+
+Bundlers should use the package export:
+
+```ts
+import { RealtimeSession } from "@voxevolv/client";
+```
+
+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";
+</script>
+```
+
+## Create through an application backend
+
+`RealtimeSession.create()` calls an application-owned endpoint that creates the
+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",
+  tools: {
+    present_attachment: (arguments_) => presentAttachment(arguments_),
+  },
+});
+
+session.onUserTranscript(({ text, final }) => renderUser(text, final));
+session.onAgentTranscript(({ text, final }) => renderAgent(text, final));
+session.onError((event) => reportVoiceError(event.payload));
+
+await session.connect();
+```
+
+## SDK-owned microphone
+
+Call from a user action so the browser may request microphone permission and
+play remote audio:
+
+```ts
+const session = new RealtimeSession(credentials, {
+  connect: { apiBase: "/api/voxevolv/v1" },
+});
+await session.connect({ microphone: true });
+```
+
+## Application-owned or mixed audio
+
+Applications that already captured a microphone or produced a mixed audio track
+must pass that track instead of opening the microphone twice:
+
+```ts
+const sourceTrack = mixedStream.getAudioTracks()[0];
+
+session.onRemoteAudioTrack((track, stream) => {
+  recordingMixer.addRemoteAudio(stream);
+});
+
+session.onRemoteAudioTrackUnsubscribed((track, stream) => {
+  recordingMixer.removeRemoteAudio(stream);
+});
+
+await session.connect({
+  microphone: false,
+  audioTrack: sourceTrack,
+});
+```
+
+The SDK validates that `audioTrack` is a live audio `MediaStreamTrack`, publishes
+an SDK-owned clone, and publishes a fresh clone when `rejoin()` obtains a new
+room token. It never stops the application-owned source. The application remains
+responsible for stopping that source during its own media teardown.
+
+`microphone: true` and `audioTrack` are mutually exclusive. Use
+`session.setMicrophoneEnabled()` to mute or unmute the published input.
+
+`onRemoteAudioTrack` does not replace automatic agent-audio playback. It exposes
+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
+
+`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.
+
+```ts
+await session.rejoin();
+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:
+
+- `POST /sessions/{id}/room-tokens`
+- `GET /sessions/{id}/events`
+- `DELETE /sessions/{id}`
+
+The proxy must forward the browser's `Authorization: Bearer vsa_...` header. It
+must not replace that credential with an organization API key.
+
+`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.
+The optional `refreshCredentials` constructor callback is used after a `401`
+during rejoin, durable replay, or scoped session ending.