@skippr/live-agent-sdk 0.33.0 → 0.35.0

package/README.md

@@ -2,13 +2,14 @@
 
 [![Website](https://img.shields.io/badge/Website-skippr.ai-blue)](https://skippr.ai) [![NPM Version](https://img.shields.io/npm/v/%40skippr%2Flive-agent-sdk?color=red)](https://www.npmjs.com/package/@skippr/live-agent-sdk)
 
-Embed an autonomous product specialist that sees, speaks, and acts in real time — handling demos, onboarding, training, and support inside your app with a single React component or script tag.
+Embed product specialists that see, speak, and act in real time. Configure **modules** — for onboarding, demos, training, support, and anything else — and let your users pick which one to talk to from a single embed.
 
 ## Key Features
 
+- **Multi-module picker** — the widget fetches your active modules and lets the user pick which one to start (onboarding, demo, support, etc.), so a single embed covers every use case
 - **Real-time voice** — two-way audio with live transcription
 - **Capture modes** — `screenshare` (user shares screen) or `auto` (DOM capture)
-- **Agent controls** — opt-in capabilities like element highlighting (auto mode only)
+- **Agent controls** — opt-in capabilities like element highlighting, configured per module (auto mode only)
 - **Chat + transcript** — text messaging with voice transcripts merged into one thread
 - **Session agenda** — structured phases with progress tracking
 - **Flexible auth** — email OTP (direct auth) or backend-signed JWT (secret mode)
@@ -17,11 +18,13 @@ Embed an autonomous product specialist that sees, speaks, and acts in real time
 
 ## Prerequisites
 
-You need an `agentId` and `appKey` from the [Skippr Platform](https://specialist.skippr.ai/).
+You need an `appKey` from the [Skippr Platform](https://specialist.skippr.ai/).
 
 1. **Sign up** at [specialist.skippr.ai](https://specialist.skippr.ai/)
-2. **Create an agent** and copy the `agentId` from the agent details page
-3. **Create an App Key** in Settings and copy the `appKey` — one App Key works for all your agents
+2. **Create your modules** in the dashboard — for example an `onboarding` agent to walk new users through setup and a `support` module for help. Every active module shows up in the widget's picker automatically.
+3. **Create an App Key** in Settings and copy the `appKey` — one App Key works for all your modules
+
+Optionally, you can pin the widget to a single module by passing its id as `agentId` (see [Pinning](#pinning-to-a-specific-module) below). Without it, the user picks from all active modules at runtime.
 
 ## Installation
 
@@ -39,7 +42,6 @@ No install needed. Add this to any webpage:
 <script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
 <script>
   Skippr.initialize({
-    agentId: 'your_agent_id',
     appKey: 'pk_live_your_key',
   });
 </script>
@@ -47,6 +49,8 @@ No install needed. Add this to any webpage:
 
 ## Quick Start
 
+The widget opens with a picker of your active modules — the user chooses which one to start a session with.
+
 ### React
 
 ```tsx
@@ -54,12 +58,7 @@ import { LiveAgent } from '@skippr/live-agent-sdk';
 import '@skippr/live-agent-sdk/styles';
 
 function App() {
-  return (
-    <LiveAgent
-      agentId="your_agent_id"
-      appKey="pk_live_your_key"
-    />
-  );
+  return <LiveAgent appKey="pk_live_your_key" />;
 }
 ```
 
@@ -69,12 +68,19 @@ function App() {
 <script src="https://unpkg.com/@skippr/live-agent-sdk/dist/skippr-sdk.js"></script>
 <script>
   Skippr.initialize({
-    agentId: 'your_agent_id',
     appKey: 'pk_live_your_key',
   });
 </script>
 ```
 
+### Pinning to a specific module
+
+If you want to skip the picker and always open straight into one module, pass its id as `agentId`:
+
+```tsx
+<LiveAgent appKey="pk_live_your_key" agentId="your_module_id" />
+```
+
 ## Authentication
 
 The SDK supports two identity modes, configured per App Key in the Skippr dashboard.
@@ -86,14 +92,13 @@ Users log in via email OTP inside the widget. No backend integration needed. The
 **React:**
 
 ```tsx
-<LiveAgent agentId="your_agent_id" appKey="pk_live_your_key" />
+<LiveAgent appKey="pk_live_your_key" />
 ```
 
 **Script tag:**
 
 ```js
 Skippr.initialize({
-  agentId: 'your_agent_id',
   appKey: 'pk_live_your_key',
 });
 ```
@@ -135,7 +140,6 @@ const userToken = jwt.sign(
 
 ```tsx
 <LiveAgent
-  agentId="your_agent_id"
   appKey="pk_live_your_key"
   userToken={userToken}
 />
@@ -145,7 +149,6 @@ const userToken = jwt.sign(
 
 ```js
 Skippr.initialize({
-  agentId: 'your_agent_id',
   appKey: 'pk_live_your_key',
   userToken: 'eyJhbGciOiJIUzI1NiIs...',
 });
@@ -167,7 +170,7 @@ function ConnectionStatus() {
 
 function App() {
   return (
-    <LiveAgent agentId="your_agent_id" appKey="pk_live_your_key">
+    <LiveAgent appKey="pk_live_your_key">
       <ConnectionStatus />
     </LiveAgent>
   );
@@ -184,18 +187,18 @@ Self-contained widget component. Renders a floating button that opens a sidebar
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `agentId` | `string` | *required* | Agent ID from the Skippr dashboard |
 | `appKey` | `string` | *required* | Publishable App Key from the Skippr dashboard |
+| `agentId` | `string` | — | Pin the widget to a specific module (pass that module's id). Omit to let the user pick from all your active modules at runtime. |
 | `userToken` | `string` | — | Signed JWT for secret mode identity verification |
 | `position` | `'left' \| 'right'` | `'right'` | Side of the screen for the widget |
 | `variant` | `'floating' \| 'sidebar'` | `'floating'` | Widget display mode |
 | `minimizable` | `boolean` | `true` | Whether the widget can be minimized |
 | `defaultOpen` | `boolean` | `false` | Whether the panel starts open |
 | `welcomeMessage` | `string` | — | Message shown on the minimized bubble |
-| `startSessionLabel` | `string` | `'Talk to Skippr'` | Label for the start-session button |
+| `startSessionLabel` | `string` | `'Talk to Skippr'` | Label for the start-session button (only shown when `agentId` is pinned) |
 | `autoFocusChat` | `boolean` | `true` | Whether the chat input auto-focuses when opened |
-| `captureMode` | `'screenshare' \| 'auto'` | `'screenshare'` | How the agent sees the page - `'screenshare'` prompts the user to share, `'auto'` uses DOM capture (no permission prompt) |
-| `agentControls` | `{ highlight?: boolean }` | — | Opt-in agent capabilities (e.g. element highlighting). **Requires `captureMode: 'auto'`.** |
+| `captureMode` | `'screenshare' \| 'auto'` | `'screenshare'` | How the agent sees the page — `'screenshare'` prompts the user to share, `'auto'` uses DOM capture (no permission prompt) |
+| `agentControls` | `{ highlight?: boolean }` | — | Opt-in agent capabilities (e.g. element highlighting). **Requires `captureMode: 'auto'`** and only applies when `agentId` is pinned. In picker mode, controls are configured per module in the dashboard. |
 
 ### `useLiveAgent()`
 
@@ -206,19 +209,42 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
 | Field | Type | Description |
 |-------|------|-------------|
 | `isConnected` | `boolean` | Whether the agent is connected |
-| `isStarting` | `boolean` | Whether a session is being created |
+| `isStarting` | `boolean` | Whether a session is being created or resumed |
+| `isDisconnecting` | `boolean` | Whether the session is being torn down |
+| `isPausing` | `boolean` | Whether a pause request is in flight (before `isPaused` commits) |
+| `isPaused` | `boolean` | Whether the current session is paused |
+| `resumableSession` | `{ id: string } \| null` | The pinned agent's most recent paused session, or `null` |
+| `resumableSessions` | `{ id: string; agentId: string }[]` | All of the user's paused sessions (one per agent), for module pickers |
 | `isPanelOpen` | `boolean` | Whether the panel is currently open |
 | `isMinimized` | `boolean` | Whether the widget is minimized |
 | `isAuthenticated` | `boolean` | Whether the user is authenticated |
 | `variant` | `'floating' \| 'sidebar'` | Current widget display mode |
 | `position` | `'left' \| 'right'` | Current widget position |
 | `error` | `string` | Error message, if any |
+| `hasModuleSelector` | `boolean` | Whether the widget is in picker mode |
+| `availableModules` | `Module[]` | Modules fetched for the picker |
+| `activeModule` | `Module \| null` | The module the current session was started with |
+| `isLoadingModules` | `boolean` | Whether the picker list is being fetched |
+| `modulesError` | `string \| null` | Error from fetching the picker list, if any |
+
+```ts
+interface Module {
+  id: string;
+  name: string;
+  description: string | null;
+  type: string;
+  priority: number;
+  controls: { highlight?: boolean };
+}
+```
 
 #### Methods
 
 | Method | Type | Description |
 |--------|------|-------------|
-| `startSession` | `() => Promise<void>` | Start a new agent session |
+| `startSession` | `(opts: { agentId: string; agentControls?: { highlight?: boolean } }) => Promise<void>` | Start a new agent session |
+| `pauseSession` | `() => Promise<void>` | Pause the active session and disconnect from LiveKit; resumable later |
+| `resumeSession` | `() => Promise<void>` | Resume the pinned agent's paused session, reconnecting to continue |
 | `disconnect` | `() => Promise<void>` | End the current session |
 | `openPanel` | `() => void` | Open the panel |
 | `closePanel` | `() => void` | Close the panel |
@@ -226,6 +252,8 @@ Hook for accessing session state and panel controls. Must be called within `<Liv
 | `expandPanel` | `() => void` | Expand from minimized state |
 | `minimizePanel` | `() => void` | Minimize the widget |
 | `setPosition` | `(position: 'left' \| 'right') => void` | Change widget position |
+| `selectModule` | `(id: string) => void` | Start a session with the module of the given id |
+| `refetchModules` | `() => Promise<void>` | Refetch the picker list |
 
 ### Additional Hooks
 
@@ -250,7 +278,7 @@ Available on `window.Skippr` when using the script tag bundle.
 
 | Method | Description |
 |--------|-------------|
-| `Skippr.initialize(config)` | Mount the widget. Accepts `agentId`, `appKey`, `userToken`, `position`, `variant`, `minimizable`, `captureMode`, `agentControls`. |
+| `Skippr.initialize(config)` | Mount the widget. Accepts `appKey` (required), `agentId` (optional — omit for picker), `userToken`, `position`, `variant`, `minimizable`, `captureMode`, `agentControls`. |
 | `Skippr.logout()` | Clear stored auth token and show the login form (direct auth mode) |
 | `Skippr.destroy()` | Remove the widget from the page and clear auth tokens |