@voice-session/web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,83 @@
+# Realtime voice session SDK
+
+Browser SDK for starting a realtime voice session with an AI assistant.
+
+The package talks to **your API host**. Pass `baseUrl` yourself. There is no default host.
+
+## Install
+
+```bash
+npm i @voice-session/web
+```
+
+## Server
+
+Your backend mints a short-lived `client_token` with your API key, then the browser SDK exchanges it. Never put the API key in frontend code.
+
+```bash
+curl -X POST "$API_HOST/api/user/realtime/session" \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"assistant_id":"ASSISTANT_UUID"}'
+```
+
+Response:
+
+```json
+{
+  "id": "session-uuid",
+  "client_token": "opaque-token"
+}
+```
+
+Tokens expire in 15 minutes. Pass `baseUrl` as the same API host (scheme + host, no trailing path).
+
+## Browser
+
+```ts
+import { RealtimeSession } from "@voice-session/web";
+
+const session = new RealtimeSession({
+  baseUrl: "https://api.example.com",
+  clientToken,
+});
+
+session.on("agent_state", (state) => {
+  console.log(state);
+});
+
+session.on("transcript", ({ role, text, final }) => {
+  if (final) {
+    console.log(role, text);
+  }
+});
+
+session.on("error", (error) => {
+  console.error(error.message);
+});
+
+await session.start({ microphone: true });
+await session.end();
+```
+
+### Events
+
+| Event | Payload |
+| --- | --- |
+| `transcript` | `{ role: "user" \| "assistant", text: string, final: boolean }` |
+| `agent_state` | `"connecting" \| "listening" \| "thinking" \| "speaking" \| "ended"` |
+| `level` | `number` (0 to 1, remote audio level) |
+| `ended` | none |
+| `error` | `Error` |
+
+### Direct credentials
+
+If your backend already exchanged the session and you have `{ url, token }`, you can skip the client-token hop:
+
+```ts
+const session = new RealtimeSession({ url, token });
+```
+
+## License
+
+MIT. See `licenses/` for notices covering bundled third-party code.