@happyrobot-ai/sdk 0.1.16 → 0.1.17

package/README.md

@@ -789,6 +789,8 @@ const client = new HappyRobotClient({ apiKey: process.env.HAPPYROBOT_API_KEY });
 app.post("/api/chat-token", async (req, res) => {
   const { token, expires_at } = await client.chat.createToken({
     workflow_id: "your-workflow-id",
+    // Optional. Token lifetime in seconds. Default 3600 (1 hour), min 60, max 86400.
+    // ttl_seconds: 1800,
   });
   res.json({ token, expires_at });
 });
@@ -825,8 +827,17 @@ const connection = chat.connect(session_id, {
   onSessionClosed: (event) => {
     // Session ended: event.status, event.reason, event.duration
   },
+  // Auto-refresh: ~30s before the token expires the SDK calls this and
+  // forwards the result over the WebSocket. The connection stays open.
+  getToken: async () => {
+    const { token } = await fetch("/api/chat-token", { method: "POST" }).then(
+      (r) => r.json()
+    );
+    return token;
+  },
   onTokenExpired: () => {
-    // Token expired — fetch a new token from your server and reconnect
+    // Backstop: only fires if no valid refresh arrived in time
+    // (e.g. getToken not provided, network failure). Reconnect from scratch.
   },
 });
 
@@ -890,9 +901,9 @@ await connection.sendMessage({
 
 ### `HappyRobotClient` (server-side)
 
-| Method                                           | Description                                  |
-| ------------------------------------------------ | -------------------------------------------- |
-| `client.chat.createToken({ workflow_id, env? })` | Create a scoped client token (1 hour expiry) |
+| Method                                                         | Description                                                            |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `client.chat.createToken({ workflow_id, env?, ttl_seconds? })` | Create a scoped client token. `ttl_seconds` defaults to 3600 (1 hour). |
 
 ### `HappyRobotChatClient` (browser-side)
 
@@ -918,23 +929,39 @@ await connection.sendMessage({
 
 **Server → Client:**
 
-| Event            | Fields                                                    | Description                                |
-| ---------------- | --------------------------------------------------------- | ------------------------------------------ |
-| `connected`      | `session_id`                                              | Connection established                     |
-| `response-start` | `content`                                                 | AI started generating a response           |
-| `response-chunk` | `content`                                                 | Partial response text                      |
-| `response-end`   | `content`                                                 | Complete response text                     |
-| `session-closed` | `session_id`, `status`, `reason`, `duration`, `timestamp` | Session ended                              |
-| `token-expired`  | —                                                         | JWT expired — reconnect with a fresh token |
-| `message-ack`    | `id`, `message`                                           | Server confirmed the message was sent      |
-| `message-error`  | `id`, `error`                                             | Server failed to send the message          |
-| `heartbeat`      | —                                                         | Keep-alive (every 15s)                     |
+| Event                    | Fields                                                    | Description                                                                  |
+| ------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `connected`              | `session_id`                                              | Connection established                                                       |
+| `response-start`         | `content`                                                 | AI started generating a response                                             |
+| `response-chunk`         | `content`                                                 | Partial response text                                                        |
+| `response-end`           | `content`                                                 | Complete response text                                                       |
+| `session-closed`         | `session_id`, `status`, `reason`, `duration`, `timestamp` | Session ended                                                                |
+| `token-refresh-required` | —                                                         | Sent ~30s before exp. SDK handles automatically when `getToken` is provided  |
+| `token-refresh-ack`      | `expires_at`                                              | Server accepted the refreshed token; connection lifetime extended            |
+| `token-refresh-error`    | `error`                                                   | Refresh token was invalid or scope-mismatched; previous token still in force |
+| `token-expired`          | —                                                         | Backstop: token expired without a valid refresh, connection is closing       |
+| `message-ack`            | `id`, `message`                                           | Server confirmed the message was sent                                        |
+| `message-error`          | `id`, `error`                                             | Server failed to send the message                                            |
+| `heartbeat`              | —                                                         | Keep-alive (every 15s)                                                       |
 
 **Client → Server:**
 
-| Event     | Fields                         | Description                                           |
-| --------- | ------------------------------ | ----------------------------------------------------- |
-| `message` | `content`, `artifacts?`, `id?` | Send a user message. `id` is echoed back in ack/error |
+| Event           | Fields                         | Description                                                                                       |
+| --------------- | ------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `message`       | `content`, `artifacts?`, `id?` | Send a user message. `id` is echoed back in ack/error                                             |
+| `token-refresh` | `token`                        | Provide a fresh token to extend the connection. Sent automatically by the SDK when `getToken` set |
+
+### Token refresh
+
+Tokens have a finite lifetime (default 1 hour, configurable via `ttl_seconds` on `createToken`). To keep long-lived connections alive without forcing the client to reconnect, the SDK supports in-band refresh:
+
+1. ~30s before the active token expires, the server sends `token-refresh-required`.
+2. The SDK calls your `getToken` handler to fetch a fresh token from your backend.
+3. The SDK sends `{ type: "token-refresh", token }` over the WebSocket.
+4. The server verifies the new token (scope must match: same `workflow_id`, `org`, `env`) and replies with `token-refresh-ack`. `onTokenRefreshed(expiresAt)` fires on the client.
+5. If no valid refresh arrives by exp, the server sends `token-expired` and closes the connection — `onTokenExpired` fires as a backstop.
+
+If you don't provide `getToken`, refreshes are skipped and the connection will close at `exp` (legacy behavior). When the same token is shared across multiple concurrent connections, each connection refreshes independently — they diverge to per-connection tokens after the first refresh.
 
 ---
 
@@ -957,6 +984,10 @@ app.post("/api/voice-token", async (req, res) => {
   const result = await client.voice.createToken({
     workflow_id: "your-workflow-id",
     data: { customer_name: "John" }, // optional — passed to the agent
+    // Optional. LiveKit token lifetime in seconds.
+    // Default 21600 (6 hours), min 60, max 86400 (24 hours).
+    // LiveKit does not refresh tokens on an active call.
+    // ttl_seconds: 3600,
   });
   res.json(result); // { url, token, room_name, run_id }
 });
@@ -1008,9 +1039,9 @@ await connection.disconnect();
 
 ### `HappyRobotClient` (server-side)
 
-| Method                                                   | Description                            |
-| -------------------------------------------------------- | -------------------------------------- |
-| `client.voice.createToken({ workflow_id, data?, env? })` | Create a LiveKit token for voice calls |
+| Method                                                                 | Description                                                                                  |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `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). |
 
 ### `HappyRobotVoiceClient` (browser-side)
 

package/chat-client.d.ts

@@ -35,7 +35,25 @@ export interface ChatConnectionHandlers {
     onSessionClosed?: (event: ChatWsSessionClosedEvent) => void;
     /** Connection established. */
     onConnected?: (sessionId: string) => void;
-    /** Token expired — reconnect with a fresh token to continue. */
+    /**
+     * Called when the server requests a fresh token before the current one
+     * expires. Provide an async function that fetches a new token from your
+     * backend; the SDK will send it over the WebSocket automatically and the
+     * connection stays open. If omitted, the connection will be closed at
+     * exp with `onTokenExpired`.
+     *
+     * Note: when one token is shared across multiple concurrent connections,
+     * each connection will refresh independently — they diverge to per-connection
+     * tokens after the first refresh.
+     */
+    getToken?: () => Promise<string>;
+    /** Token was successfully refreshed in-band. */
+    onTokenRefreshed?: (expiresAt: string) => void;
+    /**
+     * Token expired and was not refreshed in time — reconnect with a fresh
+     * token to continue. Acts as a backstop if `getToken` is not provided or
+     * fails to deliver a valid token before expiry.
+     */
     onTokenExpired?: () => void;
     /** WebSocket error. */
     onError?: (error: Event) => void;

package/chat-client.js

@@ -146,6 +146,29 @@ class HappyRobotChatClient {
                     case "session-closed":
                         handlers.onSessionClosed?.(data);
                         break;
+                    case "token-refresh-required": {
+                        const getToken = handlers.getToken;
+                        if (!getToken)
+                            break;
+                        getToken()
+                            .then((newToken) => {
+                            if (ws.readyState === WebSocket.OPEN) {
+                                ws.send(JSON.stringify({ type: "token-refresh", token: newToken }));
+                            }
+                        })
+                            .catch(() => {
+                            // Server's expiry timer is the backstop — onTokenExpired
+                            // will fire if no valid refresh arrives in time.
+                        });
+                        break;
+                    }
+                    case "token-refresh-ack":
+                        handlers.onTokenRefreshed?.(data.expires_at);
+                        break;
+                    case "token-refresh-error":
+                        // Connection stays alive on the previous token until exp; the
+                        // backstop will close it if no valid refresh arrives in time.
+                        break;
                     case "token-expired":
                         handlers.onTokenExpired?.();
                         break;

package/package.json

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

package/types/adversarial-tests.types.d.ts

@@ -2,12 +2,12 @@
  * Adversarial test types extracted from Zod schemas.
  */
 import type { z } from "zod";
+import type { EffectiveScopeApiSchema } from "../../routes/adversarial-tests/effective-scope/get";
 import type { GetAdversarialTestByIdResponseSchema } from "../../routes/adversarial-tests/get";
 import type { PatchAdversarialTestBodySchema, PatchAdversarialTestResponseSchema } from "../../routes/adversarial-tests/patch";
 import type { RunAdversarialTestBodySchema, RunAdversarialTestResponseSchema } from "../../routes/adversarial-tests/run/post";
 import type { AdversarialTestRunMessageSchema, GetAdversarialTestRunMessagesResponseSchema } from "../../routes/adversarial-tests/runs/:run_id/messages/get";
 import type { AuditRemarkApiSchema, AdversarialTestRunApiSchema, GetAdversarialTestRunsResponseSchema } from "../../routes/adversarial-tests/runs/get";
-import type { EffectiveScopeApiSchema } from "../../routes/adversarial-tests/effective-scope/get";
 import type { AdversarialTestApiSchema } from "../../routes/nodes/:node_id/adversarial-tests/get";
 export type AdversarialTest = z.infer<typeof AdversarialTestApiSchema>;
 export type AdversarialTestEffectiveScope = z.infer<typeof EffectiveScopeApiSchema>;

package/types/chat.types.d.ts

@@ -3,6 +3,8 @@ export interface CreateChatTokenBody {
     workflow_id: string;
     data?: Record<string, unknown>;
     env?: "production" | "staging" | "development";
+    /** Token lifetime in seconds. Defaults to 3600 (1 hour). Min 60s, max 24h. */
+    ttl_seconds?: number;
 }
 /** POST /chat/tokens response. */
 export interface CreateChatTokenResponse {
@@ -129,6 +131,17 @@ export interface ChatWsHeartbeatEvent {
 export interface ChatWsTokenExpiredEvent {
     type: "token-expired";
 }
+export interface ChatWsTokenRefreshRequiredEvent {
+    type: "token-refresh-required";
+}
+export interface ChatWsTokenRefreshAckEvent {
+    type: "token-refresh-ack";
+    expires_at: string;
+}
+export interface ChatWsTokenRefreshErrorEvent {
+    type: "token-refresh-error";
+    error: string;
+}
 export interface ChatWsMessageAckEvent {
     type: "message-ack";
     id?: string;
@@ -145,4 +158,4 @@ export interface ChatWsMessageErrorEvent {
     id?: string;
     error: string;
 }
-export type ChatWsEvent = ChatWsConnectedEvent | ChatWsResponseStartEvent | ChatWsResponseChunkEvent | ChatWsResponseEndEvent | ChatWsSessionClosedEvent | ChatWsHeartbeatEvent | ChatWsTokenExpiredEvent | ChatWsMessageAckEvent | ChatWsMessageErrorEvent;
+export type ChatWsEvent = ChatWsConnectedEvent | ChatWsResponseStartEvent | ChatWsResponseChunkEvent | ChatWsResponseEndEvent | ChatWsSessionClosedEvent | ChatWsHeartbeatEvent | ChatWsTokenExpiredEvent | ChatWsTokenRefreshRequiredEvent | ChatWsTokenRefreshAckEvent | ChatWsTokenRefreshErrorEvent | ChatWsMessageAckEvent | ChatWsMessageErrorEvent;

package/types/voice.types.d.ts

@@ -3,6 +3,13 @@ export interface CreateVoiceTokenBody {
     workflow_id: string;
     data?: Record<string, unknown>;
     env?: "production" | "staging" | "development";
+    /**
+     * LiveKit token lifetime in seconds. Defaults to 21600 (6 hours) to match
+     * LiveKit's default. Min 60s, max 86400 (24h). LiveKit does not refresh
+     * tokens on an active call — the browser must reconnect if the call
+     * outlives the TTL.
+     */
+    ttl_seconds?: number;
 }
 /** POST /voice/tokens response. */
 export interface CreateVoiceTokenResponse {