@happyrobot-ai/sdk 0.1.24 → 0.1.26

package/package.json

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

package/resources/voice.d.ts

@@ -4,7 +4,7 @@
  * Server-side only. Creates LiveKit tokens that are passed to the
  * browser-side `HappyRobotVoiceClient`.
  *
- * @example
+ * @example Start a new call
  * ```ts
  * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
  * const { url, token } = await client.voice.createToken({
@@ -13,6 +13,14 @@
  * });
  * // Pass `url` and `token` to the browser → new HappyRobotVoiceClient({ url, token })
  * ```
+ *
+ * @example Take over an in-progress call (the AI agent drops)
+ * ```ts
+ * const { url, token } = await client.voice.createToken({
+ *   session_id: "the-live-session-id",
+ *   should_takeover: true,
+ * });
+ * ```
  */
 import type { HttpClient } from "../core/http";
 import type { CreateVoiceTokenBody, CreateVoiceTokenResponse } from "../types/voice.types";
@@ -24,6 +32,10 @@ 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.
      */
     createToken(body: CreateVoiceTokenBody): Promise<CreateVoiceTokenResponse>;
 }

package/resources/voice.js

@@ -5,7 +5,7 @@
  * Server-side only. Creates LiveKit tokens that are passed to the
  * browser-side `HappyRobotVoiceClient`.
  *
- * @example
+ * @example Start a new call
  * ```ts
  * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
  * const { url, token } = await client.voice.createToken({
@@ -14,6 +14,14 @@
  * });
  * // Pass `url` and `token` to the browser → new HappyRobotVoiceClient({ url, token })
  * ```
+ *
+ * @example Take over an in-progress call (the AI agent drops)
+ * ```ts
+ * const { url, token } = await client.voice.createToken({
+ *   session_id: "the-live-session-id",
+ *   should_takeover: true,
+ * });
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VoiceResource = void 0;
@@ -27,6 +35,10 @@ 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.
      */
     async createToken(body) {
         return this.http.request({

package/types/voice.types.d.ts

@@ -1,6 +1,5 @@
-/** POST /voice/tokens request body. */
-export interface CreateVoiceTokenBody {
-    workflow_id: string;
+type CreateVoiceTokenBase = {
+    /** Payload data passed to the voice agent as participant attributes (`workflow_id` only). */
     data?: Record<string, unknown>;
     env?: "production" | "staging" | "development";
     /**
@@ -10,7 +9,33 @@ export interface CreateVoiceTokenBody {
      * outlives the TTL.
      */
     ttl_seconds?: number;
-}
+};
+/**
+ * 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`.
+ */
+export type CreateVoiceTokenBody = (CreateVoiceTokenBase & {
+    /** Workflow UUID or slug to start a new call with. */
+    workflow_id: string;
+    session_id?: never;
+    should_takeover?: never;
+}) | (CreateVoiceTokenBase & {
+    /**
+     * ID of an in-progress session to 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.
+     */
+    should_takeover: true;
+});
 /** POST /voice/tokens response. */
 export interface CreateVoiceTokenResponse {
     url: string;
@@ -18,3 +43,4 @@ export interface CreateVoiceTokenResponse {
     room_name: string;
     run_id: string;
 }
+export {};