@babelbeez/sdk 0.1.1 → 0.1.2

package/README.md

@@ -1,17 +1,19 @@
 # Babelbeez Headless SDK (`@babelbeez/sdk`)
 
-The **Babelbeez Headless SDK** provides raw, programmatic access to the Babelbeez Voice Agent protocol.
+> Build your own UI for the Babelbeez AI voice agent – custom buttons, call controls, and chat views – while we handle realtime audio, OpenAI Realtime, and connection lifecycle.
 
-It’s ideal if you want to:
+The **Babelbeez Headless SDK** gives you low‑level, event‑driven control of a Babelbeez Voice Agent from the browser.
 
-- Integrate Babelbeez voice agents into an existing app (web, dashboards, custom UIs)
-- Build completely custom button/widget designs instead of using the standard embed
-- Create hybrid **text + voice** interfaces while Babelbeez handles:
-  - Low-latency audio processing
-  - WebRTC connections
-  - AI orchestration and session management
+> **Note:** Using this SDK requires a **Babelbeez account** and a configured Voice Agent. Sign up at https://www.babelbeez.com.
 
-> If you just want a drop-in widget for your website, you probably want the standard Babelbeez embed instead of this SDK.
+Use this SDK when you want to:
+
+- Replace the default widget with your **own button or call UI**
+- Show **live transcripts** in your app
+- Combine **voice + text** input in a single experience
+- Orchestrate **human handoffs** (email / WhatsApp) from your own components
+
+If you just want a drop‑in chat button, use the standard Babelbeez embed instead. This SDK is for developers who want full control over the UX.
 
 ---
 
@@ -21,188 +23,387 @@ It’s ideal if you want to:
 npm install @babelbeez/sdk
 ```
 
-The SDK is designed for modern browsers that support WebRTC and access to the microphone.
+**Requirements**
+
+- A **Babelbeez account** and at least one configured Voice Agent
+- Modern browser with **WebRTC** and microphone support
+- Page served over **HTTPS** (or `localhost`) so the browser will allow mic access
 
 ---
 
-## Quick Start
+## Getting your `publicChatbotId`
 
-To use the SDK, you will need the **Public Chatbot ID** of your configured Voice Agent. You can find this in the Babelbeez Dashboard under **Voice Agent Settings**.
+In the Babelbeez Dashboard, open your Voice Agent and go to **Settings → Embed**. Copy the **Public Chatbot ID** – you’ll pass this into the SDK.
+
+---
+
+## Quick Start: custom start/stop button
 
 ```ts
 import { BabelbeezClient } from '@babelbeez/sdk';
 
-// 1. Initialize the client
+// 1. Create the client
 const client = new BabelbeezClient({
-  publicChatbotId: 'YOUR_UUID_HERE',
+  publicChatbotId: 'YOUR_PUBLIC_CHATBOT_ID',
 });
 
-// 2. Listen for state changes (e.g., loading, listening, speaking)
+let currentState: 'idle' | 'loading' | 'active' | 'speaking' | 'error' | 'rag-retrieval' = 'idle';
+
+// 2. Listen for state changes to drive your UI
 client.on('buttonState', (state) => {
-  console.log('Agent State:', state); // 'loading' | 'active' | 'speaking' | 'idle'
+  // state: 'idle' | 'loading' | 'active' | 'speaking' | 'error' | 'rag-retrieval'
+  console.log('Agent state:', state);
+  currentState = state;
+  updateMyButton(state); // implement this in your own UI
+});
+
+// 3. Listen for live transcripts (user + agent)
+client.on('transcript', ({ role, text, isFinal }) => {
+  // role: 'user' | 'agent'
+  console.log(`${role}:`, text, isFinal ? '(final)' : '(partial)');
+  appendMessageToChat(role, text, isFinal); // your own renderer
+});
+
+// 4. Wire up your button to connect / disconnect
+const startStopButton = document.getElementById('voice-button')!;
+
+startStopButton.addEventListener('click', async () => {
+  if (currentState === 'active' || currentState === 'speaking' || currentState === 'rag-retrieval') {
+    // Play nice goodbye UX (triggers configured farewell in Babelbeez)
+    await client.disconnect('user_button_click');
+  } else if (currentState === 'idle' || currentState === 'error') {
+    try {
+      await client.connect(); // Browser will request microphone access
+    } catch (err) {
+      console.error('Failed to connect:', err);
+    }
+  }
 });
+```
+
+You’re responsible for implementing `updateMyButton` and `appendMessageToChat` in your own DOM or framework components.
+
+---
+
+## Example: building a transcript view
+
+The SDK emits **streaming transcripts** for both the user and the agent, including partial and final messages. You can use this to build a chat‑like view.
+
+```ts
+const transcriptContainer = document.getElementById('messages');
+let currentLine: HTMLDivElement | null = null;
 
-// 3. Listen for live transcripts
 client.on('transcript', ({ role, text, isFinal }) => {
-  console.log(`${role}: ${text}`);
+  // role is 'user' or 'agent'
+
+  const roleAttr = role;
+
+  // 1. Start a new line when role changes or previous line was final
+  if (!currentLine || currentLine.dataset.role !== roleAttr || currentLine.dataset.final === 'true') {
+    currentLine = document.createElement('div');
+    currentLine.dataset.role = roleAttr;
+    currentLine.className = role === 'user' ? 'message-user' : 'message-agent';
+    transcriptContainer!.appendChild(currentLine);
+  }
+
+  // 2. Update the text content with the latest transcript
+  currentLine.textContent = text;
+
+  // 3. Mark final utterances
+  currentLine.dataset.final = String(isFinal);
+
+  // 4. Auto-scroll
+  transcriptContainer!.scrollTop = transcriptContainer!.scrollHeight;
 });
+```
+
+Style `.message-user` and `.message-agent` in CSS to match your design system.
+
+---
+
+## Example: hybrid text + voice
+
+You can send text input into the same live voice session. The agent will respond via audio, and you’ll still get `transcript` events.
 
-// 4. Connect (browser will request microphone permissions)
-document.getElementById('start-btn')!.addEventListener('click', async () => {
+```ts
+// e.g. on form submit
+async function handleTextSubmit(message: string) {
   try {
-    await client.connect();
+    await client.sendUserText(message);
   } catch (err) {
-    console.error('Failed to connect:', err);
+    console.error('Failed to send text message:', err);
   }
+}
+```
+
+> Note: The voice session must be active (after `connect()`) for `sendUserText` to take effect.
+
+---
+
+## Example: handling human handoff
+
+If your agent is configured for **human handoff**, the SDK will emit events so you can present your own email/WhatsApp UI.
+
+```ts
+client.on('handoff:show', ({ summaryText, waLink }) => {
+  // summaryText: short description of the conversation / request
+  // waLink: WhatsApp deeplink if configured, otherwise null
+  openHandoffModal({ summaryText, waLink });
 });
+
+client.on('handoff:hide', ({ outcome }) => {
+  // outcome: 'email_submitted' | 'whatsapp_submitted' | 'cancelled'
+  closeHandoffModal(outcome);
+});
+
+// When the user submits your handoff form
+async function submitHandoff(email: string, consent: boolean) {
+  await client.handleHandoffSubmit({ email, consent });
+}
+
+// When the user cancels or chooses WhatsApp instead
+async function cancelHandoff(viaWhatsapp: boolean) {
+  await client.handleHandoffCancel({ viaWhatsapp });
+}
 ```
 
+The agent behavior, wording, and when handoff is triggered are all configured in the Babelbeez Dashboard.
+
 ---
 
 ## API Reference
 
 ### `new BabelbeezClient(config)`
 
-Creates a new instance of the Babelbeez client.
-
-**Config object**
-
-- `publicChatbotId` **(string, required)** – The unique UUID of your Voice Agent.
+Create a new client instance.
 
 ```ts
+import { BabelbeezClient } from '@babelbeez/sdk';
+
 const client = new BabelbeezClient({
-  publicChatbotId: 'YOUR_UUID_HERE',
+  publicChatbotId: 'YOUR_PUBLIC_CHATBOT_ID',
 });
 ```
 
+**Config**
+
+```ts
+interface BabelbeezClientConfig {
+  publicChatbotId: string;
+}
+```
+
+- `publicChatbotId` **(string, required)** – The public ID of the Voice Agent from the Babelbeez Dashboard.
+
 ---
 
 ### Methods
 
-#### `connect()`
+#### `connect(): Promise<void>`
 
-Initializes the session, requests microphone access from the user, and establishes a realtime WebRTC connection with the Babelbeez infrastructure.
+Initializes the session via Babelbeez, requests microphone access from the user, and opens a realtime connection to the OpenAI Realtime API.
+
+- Emits `buttonState: 'loading'` while connecting.
+- On success, emits `buttonState: 'active'` and `session:start`.
+- On failure (e.g. mic denied), emits an `error` event and `buttonState: 'error'`.
 
 ```ts
 await client.connect();
 ```
 
-If the user denies microphone permissions, or the connection fails, an `error` event will be emitted and the promise will reject.
-
 ---
 
-#### `disconnect(reason?)`
+#### `disconnect(reason?: string): Promise<void>`
 
-Gracefully terminates the voice session.
+Gracefully ends the current session and sends a final usage + transcript summary to Babelbeez.
 
 ```ts
-client.disconnect('user_button_click');
+await client.disconnect();
+// or
+await client.disconnect('user_button_click');
 ```
 
-**Parameters**
+- `reason` **(optional)** – String reason used for analytics and backend handling.
+  - Passing `'user_button_click'` triggers the configured **goodbye message** before disconnecting.
 
-- `reason` **(string, optional)** – A descriptive reason for the disconnection. Defaults to `'client_disconnect'`.
+---
 
-Special handling:
+#### `initializeAudio(): void`
 
-- Passing `'user_button_click'` specifically triggers the agent to play its configured **“Goodbye”** message **before** disconnecting.
-- Other reasons generally terminate the session immediately.
+Optional helper to unlock the browser `AudioContext` in response to a user gesture (click/tap), which can help avoid autoplay restrictions in some environments.
+
+```ts
+// e.g. on a user click before connecting
+client.initializeAudio();
+```
 
 ---
 
-#### `sendUserText(text)`
+#### `sendUserText(text: string): Promise<void>`
 
-Sends a text message to the agent. This enables hybrid interfaces where a user can **speak or type** to the same agent within the same session.
+Sends a user text message into the active voice session – useful for hybrid **chat + voice** interfaces.
 
 ```ts
-client.sendUserText('Hello, I would like to book an appointment.');
+await client.sendUserText('Hello, do you have pricing for teams?');
 ```
 
-**Parameters**
-
-- `text` **(string)** – The message to send.
+- If the agent is currently speaking, the SDK will attempt to **interrupt** the response before sending the new message.
 
 ---
 
-#### `handleHandoffSubmit({ email, consent })`
+#### `handleHandoffSubmit(payload): Promise<void>`
 
-Submits user contact details in response to a **“Request Human Handoff”** event.
+Notify Babelbeez when the user submits your human handoff form.
 
 ```ts
-client.handleHandoffSubmit({
+await client.handleHandoffSubmit({
   email: 'user@example.com',
   consent: true,
 });
 ```
 
-**Parameters**
-
 - `email` **(string)** – The user’s email address.
 - `consent` **(boolean)** – Whether the user consented to be contacted.
 
 ---
 
-#### `handleHandoffCancel({ viaWhatsapp })`
+#### `handleHandoffCancel(options?): Promise<void>`
 
-Cancels a pending handoff request.
+Notify Babelbeez when the user cancels the handoff form or switches to WhatsApp.
 
 ```ts
-client.handleHandoffCancel({
-  viaWhatsapp: true,
-});
+await client.handleHandoffCancel({ viaWhatsapp: true });
 ```
 
-**Parameters**
-
-- `viaWhatsapp` **(boolean, optional)** – Set to `true` if the cancellation occurred because the user chose to continue the conversation on WhatsApp via a deep link.
+- `viaWhatsapp` **(boolean, optional)** – Pass `true` if the user opted to continue via WhatsApp (using the provided `waLink`). In that case, the SDK will end the voice session after a goodbye.
 
 ---
 
-## Events
+### Events
+
+The client extends a simple `EventEmitter` interface. Subscribe with `client.on(event, listener)` and unsubscribe with `client.off(event, listener)`.
 
-The client extends an `EventEmitter`. You can subscribe to events using `client.on(event, callback)`.
+#### Core events
 
 ```ts
-client.on('event-name', (payload) => {
-  // handle event
-});
+client.on('buttonState', (state) => { /* ... */ });
+client.on('transcript', (event) => { /* ... */ });
+client.on('error', (event) => { /* ... */ });
+client.on('session:start', (event) => { /* ... */ });
+client.on('session:end', (event) => { /* ... */ });
+client.on('handoff:show', (event) => { /* ... */ });
+client.on('handoff:hide', (event) => { /* ... */ });
 ```
 
-### Core Events
+#### `buttonState`
 
-| Event           | Payload                    | Description |
-|-----------------|----------------------------|-------------|
-| `buttonState`   | `string`                   | Current status of the agent. One of: `'idle'`, `'loading'`, `'active'` (listening), `'speaking'`, `'rag-retrieval'`, `'error'`. |
-| `transcript`    | `{ role, text, isFinal }`  | Realtime transcript updates. `role` is `'user'` or `'agent'`. `isFinal` indicates that the utterance/response is complete. |
-| `session:start` | `{ chatbotId, config }`    | Fired when the WebRTC connection is fully established and the session is active. |
-| `session:end`   | `{ reason }`               | Fired when the session terminates (user disconnect, timeout, error, etc.). |
-| `handoff:show`  | `{ summaryText, waLink }`  | Fired when the AI determines a human is needed. Render a UI form to collect user details. `waLink` contains a WhatsApp deep link if configured. |
-| `handoff:hide`  | `{ outcome }`              | Fired when the handoff flow is completed or cancelled. |
-| `error`         | `{ code, message, fatal }` | Emitted when an error occurs. If `fatal` is `true`, the session has been terminated. |
+```ts
+export type BabelbeezButtonState =
+  | 'idle'
+  | 'loading'
+  | 'active'
+  | 'speaking'
+  | 'error'
+  | 'rag-retrieval';
+```
+
+Use this to drive your call control UI (start/stop button, spinners, etc.).
 
-Example:
+#### `transcript`
 
 ```ts
-client.on('error', ({ code, message, fatal }) => {
-  console.error(`[Babelbeez] Error (${code}): ${message}`);
+export interface BabelbeezTranscriptEvent {
+  role: 'user' | 'agent';
+  text: string;
+  isFinal: boolean;
+}
+```
 
-  if (fatal) {
-    // e.g. update UI, disable button, prompt user to refresh
-  }
-});
+- Multiple events are emitted per utterance.
+- `isFinal: true` marks the end of a user or agent turn.
+
+#### `session:start`
+
+```ts
+export interface BabelbeezSessionStartEvent {
+  chatbotId: string;
+  config: unknown; // snapshot of chatbot configuration
+}
+```
+
+Fired when the WebRTC session is fully established and active.
+
+#### `session:end`
+
+```ts
+export interface BabelbeezSessionEndEvent {
+  reason: string;
+}
+```
+
+Fired when the session terminates (user disconnect, timeout, error, agent‑initiated close, etc.).
+
+#### `error`
+
+```ts
+export type BabelbeezErrorSeverity = 'info' | 'warning' | 'error';
+
+export interface BabelbeezErrorEvent {
+  code: string;
+  message: string;
+  severity: BabelbeezErrorSeverity;
+  fatal?: boolean;
+}
+```
+
+- When `fatal === true`, the session has been terminated.
+- Use `severity` to decide how aggressively to update your UI or prompt the user.
+
+#### `handoff:show`
+
+```ts
+export interface BabelbeezHandoffShowEvent {
+  summaryText: string;
+  waLink: string | null; // WhatsApp deeplink if configured
+}
 ```
 
+Fired when the AI decides a human is needed. Use this to show your own form/modal.
+
+#### `handoff:hide`
+
+```ts
+export type BabelbeezHandoffHideOutcome =
+  | 'email_submitted'
+  | 'whatsapp_submitted'
+  | 'cancelled';
+
+export interface BabelbeezHandoffHideEvent {
+  outcome: BabelbeezHandoffHideOutcome;
+}
+```
+
+Fired when the handoff flow is completed or cancelled.
+
 ---
 
-## Usage Notes
+## Usage notes
 
-- The SDK is **browser-first** and assumes access to `navigator.mediaDevices` for microphone input.
-- Make sure your site is served over **HTTPS**, or from `localhost`, otherwise the browser may block microphone access.
-- You should always provide clear UI affordances (e.g. a “Start call” / “End call” button) that map to `connect()` and `disconnect()` calls.
+- The SDK is **browser‑first** and assumes access to `navigator.mediaDevices` for microphone input.
+- Always provide clear UX affordances (e.g. "Start call" / "End call") that map to `connect()` and `disconnect()`.
+- For best results, prompt the user before accessing the microphone and explain what the agent will do.
 
 ---
 
-## License
+## Further reading
+
+For a full walkthrough of building a custom button and UI, see the guide:
+
+**Headless embed: use your own chat button**  
+https://www.babelbeez.com/resources/help/for-developers/headless-embed-custom-button.html
 
-ISC
+---
+
+## License
 
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babelbeez/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,5 +18,29 @@
   "files": [
     "dist"
   ],
-  "license": "ISC"
+  "keywords": [
+    "babelbeez",
+    "headless voice ai",
+    "headless voice sdk",
+    "headless chatbot",
+    "speech to speech ai",
+    "speech to speech",
+    "website voice assistant",
+    "website voice agent",
+    "website voice chatbot",
+    "voice chat widget",
+    "web voice widget",
+    "voice ai for websites",
+    "embedded voice assistant",
+    "embedded voice ai",
+    "white label voice ai",
+    "web agency",
+    "client website voice",
+    "openai realtime voice",
+    "openai voice agent",
+    "webrtc voice",
+    "browser voice sdk",
+    "javascript voice sdk"
+  ],
+  "license": "MIT"
 }