@happyrobot-ai/sdk 0.1.45 → 0.1.47

package/README.md

@@ -998,6 +998,13 @@ app.post("/api/voice-token", async (req, res) => {
   });
   res.json(result); // { url, token, room_name, run_id }
 });
+
+app.post("/api/live-session/:sessionId/listen-token", async (req, res) => {
+  const result = await client.voice.createToken({
+    session_id: req.params.sessionId,
+  });
+  res.json(result); // Hidden, subscribe-only observer token
+});
 ```
 
 ### Browser-side: `HappyRobotVoiceClient`
@@ -1044,6 +1051,28 @@ await connection.unmute();
 await connection.disconnect();
 ```
 
+To listen to an existing call without publishing audio or affecting the AI
+agent, create a token with `session_id` and use `listen()` in the browser:
+
+```ts
+const { url, token } = await fetch(
+  `/api/live-session/${sessionId}/listen-token`,
+  { method: "POST" }
+).then((r) => r.json());
+
+const voice = new HappyRobotVoiceClient({ url, token });
+const listener = await voice.listen();
+
+// If the browser later blocks playback, call this from a click handler:
+await listener.startAudio();
+
+// Stop listening without affecting the call:
+await listener.disconnect();
+```
+
+Set `should_takeover: true` when creating a session token to retain the
+existing takeover behavior, which removes the AI agent from the call.
+
 ### `HappyRobotClient` (server-side)
 
 List the voices available to the current workspace in its cluster. Use a
@@ -1059,17 +1088,19 @@ for (const voice of voices) {
 
 `voice.id` is the value used in workflow `agent.voices` configuration.
 
-| Method                                                                 | Description                                                                                                    |
-| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `client.voice.list({ language? })`                                     | List voices available to the current workspace. `language` accepts prefixes like `en` or locales like `en-GB`. |
-| `client.voice.createToken({ workflow_id, data?, env?, ttl_seconds? })` | Create a LiveKit token for voice calls. `ttl_seconds` defaults to 21600 (min 60, max 86400).                   |
+| Method                                                                     | Description                                                                                                    |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `client.voice.list({ language? })`                                         | List voices available to the current workspace. `language` accepts prefixes like `en` or locales like `en-GB`. |
+| `client.voice.createToken({ workflow_id, data?, env?, ttl_seconds? })`     | Create a LiveKit token for a new voice call.                                                                   |
+| `client.voice.createToken({ session_id, should_takeover?, ttl_seconds? })` | Observe a live session, or take it over when `should_takeover` is true.                                        |
 
 ### `HappyRobotVoiceClient` (browser-side)
 
-| Method                                      | Description                                                    |
-| ------------------------------------------- | -------------------------------------------------------------- |
-| `new HappyRobotVoiceClient({ url, token })` | Create client with LiveKit credentials                         |
-| `voice.connect(handlers?)`                  | Connect to room, enable microphone — returns `VoiceConnection` |
+| Method                                      | Description                                                                         |
+| ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `new HappyRobotVoiceClient({ url, token })` | Create client with LiveKit credentials                                              |
+| `voice.connect(handlers?)`                  | Connect and enable the microphone — returns `VoiceConnection`                       |
+| `voice.listen(handlers?)`                   | Connect without microphone access or publishing — returns `VoiceListenerConnection` |
 
 ### `VoiceConnection`
 
@@ -1081,6 +1112,14 @@ for (const voice of voices) {
 | `connection.isMuted()`    | Check mute state                                          |
 | `connection.room`         | Underlying LiveKit `Room` instance for advanced use cases |
 
+### `VoiceListenerConnection`
+
+| Method                  | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `listener.disconnect()` | Stop listening without affecting the call                 |
+| `listener.startAudio()` | Resume audio playback from a browser user gesture         |
+| `listener.room`         | Underlying LiveKit `Room` instance for advanced use cases |
+
 ### Room Events
 
 | Handler               | Description                                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyrobot-ai/sdk",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "TypeScript SDK for the HappyRobot Public API",
   "main": "./index.js",
   "module": "./index.mjs",

package/resources/api-key.d.ts

@@ -12,6 +12,7 @@ export interface ApiKeyInfo {
     prefix: string;
     lastFour: string;
     createdAt: string;
+    expiresAt: string | null;
     lastUsedAt: string | null;
     revokedAt: string | null;
 }

package/resources/voice.d.ts

@@ -21,6 +21,14 @@
  *   should_takeover: true,
  * });
  * ```
+ *
+ * @example Silently listen to an in-progress call
+ * ```ts
+ * const { url, token } = await client.voice.createToken({
+ *   session_id: "the-live-session-id",
+ * });
+ * // In the browser: await new HappyRobotVoiceClient({ url, token }).listen()
+ * ```
  */
 import type { HttpClient } from "../core/http";
 import type { CreateVoiceTokenBody, CreateVoiceTokenResponse, ListVoicesQuery, ListVoicesResponse } from "../types/voice.types";
@@ -35,9 +43,9 @@ export declare class VoiceResource {
      * Call this from your server, then pass the returned `url` and `token`
      * to the browser where they can be used to initialize `HappyRobotVoiceClient`.
      *
-     * Provide `workflow_id` to start a new call, or `session_id` (with the
-     * required `should_takeover: true`) to take over an in-progress call, which
-     * drops the AI agent.
+     * Provide `workflow_id` to start a new call, or `session_id` to silently
+     * observe an in-progress call. Set `should_takeover: true` to take over the
+     * call and drop the AI agent.
      */
     createToken(body: CreateVoiceTokenBody): Promise<CreateVoiceTokenResponse>;
 }

package/resources/voice.js

@@ -22,6 +22,14 @@
  *   should_takeover: true,
  * });
  * ```
+ *
+ * @example Silently listen to an in-progress call
+ * ```ts
+ * const { url, token } = await client.voice.createToken({
+ *   session_id: "the-live-session-id",
+ * });
+ * // In the browser: await new HappyRobotVoiceClient({ url, token }).listen()
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VoiceResource = void 0;
@@ -48,9 +56,9 @@ class VoiceResource {
      * Call this from your server, then pass the returned `url` and `token`
      * to the browser where they can be used to initialize `HappyRobotVoiceClient`.
      *
-     * Provide `workflow_id` to start a new call, or `session_id` (with the
-     * required `should_takeover: true`) to take over an in-progress call, which
-     * drops the AI agent.
+     * Provide `workflow_id` to start a new call, or `session_id` to silently
+     * observe an in-progress call. Set `should_takeover: true` to take over the
+     * call and drop the AI agent.
      */
     async createToken(body) {
         return this.http.request({

package/types/voice.types.d.ts

@@ -30,8 +30,8 @@ type CreateVoiceTokenBase = {
  * POST /voice/tokens request body.
  *
  * Provide exactly one of `workflow_id` (start a new call) or `session_id`
- * (join an in-progress call). `should_takeover` is only available alongside
- * `session_id`.
+ * (observe or take over an in-progress call). `should_takeover` is only
+ * available alongside `session_id`.
  */
 export type CreateVoiceTokenBody = (CreateVoiceTokenBase & {
     /** Workflow UUID or slug to start a new call with. */
@@ -40,17 +40,16 @@ export type CreateVoiceTokenBody = (CreateVoiceTokenBase & {
     should_takeover?: never;
 }) | (CreateVoiceTokenBase & {
     /**
-     * ID of an in-progress session to take over. Generates a token for the
-     * session's existing LiveKit room.
+     * ID of an in-progress session to observe or take over. Generates a token
+     * for the session's existing LiveKit room.
      */
     session_id: string;
     workflow_id?: never;
     /**
-     * Must be `true`. Explicit opt-in confirming the joining participant
-     * takes over the call and the AI agent drops. Joining a live call
-     * without taking over is not supported.
+     * Defaults to false, creating a hidden subscribe-only observer while the
+     * AI agent remains active. Set to true to take over and drop the agent.
      */
-    should_takeover: true;
+    should_takeover?: boolean;
 });
 /** POST /voice/tokens response. */
 export interface CreateVoiceTokenResponse {

package/voice/index.d.ts

@@ -18,5 +18,5 @@
  * ```
  */
 export { HappyRobotVoiceClient } from "../voice-client";
-export type { VoiceConnectionHandlers, VoiceConnection } from "../voice-client";
+export type { VoiceClientConfig, VoiceConnection, VoiceConnectionHandlers, VoiceListenerConnection, } from "../voice-client";
 export type { CreateVoiceTokenBody, CreateVoiceTokenResponse, ListVoicesQuery, ListVoicesResponse, Voice, } from "../types/voice.types";

package/voice-client.d.ts

@@ -67,6 +67,14 @@ export interface VoiceConnection {
     /** The underlying LiveKit Room instance for advanced use cases. */
     readonly room: Room;
 }
+export interface VoiceListenerConnection {
+    /** Stop listening and disconnect from the room. */
+    disconnect(): Promise<void>;
+    /** Resume audio playback after a browser autoplay block. Call from a user gesture. */
+    startAudio(): Promise<void>;
+    /** The underlying LiveKit Room instance for advanced use cases. */
+    readonly room: Room;
+}
 export interface VoiceClientConfig {
     /** LiveKit WebSocket URL from `client.voice.createToken()`. */
     url: string;
@@ -84,4 +92,12 @@ export declare class HappyRobotVoiceClient {
      * Pass event handlers to react to room lifecycle events and remote tracks.
      */
     connect(handlers?: VoiceConnectionHandlers): Promise<VoiceConnection>;
+    /**
+     * Silently listen to a live call without requesting microphone access.
+     *
+     * This must be used with a session observer token returned by
+     * `client.voice.createToken({ session_id })`.
+     */
+    listen(handlers?: VoiceConnectionHandlers): Promise<VoiceListenerConnection>;
+    private connectToRoom;
 }

package/voice-client.js

@@ -47,6 +47,25 @@ class HappyRobotVoiceClient {
      * Pass event handlers to react to room lifecycle events and remote tracks.
      */
     async connect(handlers = {}) {
+        return this.connectToRoom(handlers, true);
+    }
+    /**
+     * Silently listen to a live call without requesting microphone access.
+     *
+     * This must be used with a session observer token returned by
+     * `client.voice.createToken({ session_id })`.
+     */
+    async listen(handlers = {}) {
+        const connection = await this.connectToRoom(handlers, false);
+        return {
+            disconnect: connection.disconnect,
+            startAudio: () => connection.room.startAudio(),
+            get room() {
+                return connection.room;
+            },
+        };
+    }
+    async connectToRoom(handlers, enableMicrophone) {
         // Create Room with HappyRobot defaults (matching platform use-webcall.tsx)
         const room = new livekit_client_1.Room({
             adaptiveStream: true,
@@ -106,9 +125,17 @@ class HappyRobotVoiceClient {
         });
         // ── Connect ──
         try {
+            if (!enableMicrophone) {
+                await room.startAudio().catch(() => undefined);
+            }
             await room.prepareConnection(this.url, this.token);
             await room.connect(this.url, this.token);
-            await room.localParticipant.setMicrophoneEnabled(true);
+            if (enableMicrophone) {
+                await room.localParticipant.setMicrophoneEnabled(true);
+            }
+            else {
+                await room.startAudio().catch(() => undefined);
+            }
         }
         catch (error) {
             // Clean up on connection failure