@babelbeez/sdk 0.1.1

package/README.md

@@ -0,0 +1,208 @@
+# Babelbeez Headless SDK (`@babelbeez/sdk`)
+
+The **Babelbeez Headless SDK** provides raw, programmatic access to the Babelbeez Voice Agent protocol.
+
+It’s ideal if you want to:
+
+- 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
+
+> If you just want a drop-in widget for your website, you probably want the standard Babelbeez embed instead of this SDK.
+
+---
+
+## Installation
+
+```bash
+npm install @babelbeez/sdk
+```
+
+The SDK is designed for modern browsers that support WebRTC and access to the microphone.
+
+---
+
+## Quick Start
+
+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**.
+
+```ts
+import { BabelbeezClient } from '@babelbeez/sdk';
+
+// 1. Initialize the client
+const client = new BabelbeezClient({
+  publicChatbotId: 'YOUR_UUID_HERE',
+});
+
+// 2. Listen for state changes (e.g., loading, listening, speaking)
+client.on('buttonState', (state) => {
+  console.log('Agent State:', state); // 'loading' | 'active' | 'speaking' | 'idle'
+});
+
+// 3. Listen for live transcripts
+client.on('transcript', ({ role, text, isFinal }) => {
+  console.log(`${role}: ${text}`);
+});
+
+// 4. Connect (browser will request microphone permissions)
+document.getElementById('start-btn')!.addEventListener('click', async () => {
+  try {
+    await client.connect();
+  } catch (err) {
+    console.error('Failed to connect:', err);
+  }
+});
+```
+
+---
+
+## 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.
+
+```ts
+const client = new BabelbeezClient({
+  publicChatbotId: 'YOUR_UUID_HERE',
+});
+```
+
+---
+
+### Methods
+
+#### `connect()`
+
+Initializes the session, requests microphone access from the user, and establishes a realtime WebRTC connection with the Babelbeez infrastructure.
+
+```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?)`
+
+Gracefully terminates the voice session.
+
+```ts
+client.disconnect('user_button_click');
+```
+
+**Parameters**
+
+- `reason` **(string, optional)** – A descriptive reason for the disconnection. Defaults to `'client_disconnect'`.
+
+Special handling:
+
+- Passing `'user_button_click'` specifically triggers the agent to play its configured **“Goodbye”** message **before** disconnecting.
+- Other reasons generally terminate the session immediately.
+
+---
+
+#### `sendUserText(text)`
+
+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.
+
+```ts
+client.sendUserText('Hello, I would like to book an appointment.');
+```
+
+**Parameters**
+
+- `text` **(string)** – The message to send.
+
+---
+
+#### `handleHandoffSubmit({ email, consent })`
+
+Submits user contact details in response to a **“Request Human Handoff”** event.
+
+```ts
+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 })`
+
+Cancels a pending handoff request.
+
+```ts
+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.
+
+---
+
+## Events
+
+The client extends an `EventEmitter`. You can subscribe to events using `client.on(event, callback)`.
+
+```ts
+client.on('event-name', (payload) => {
+  // handle event
+});
+```
+
+### Core Events
+
+| 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. |
+
+Example:
+
+```ts
+client.on('error', ({ code, message, fatal }) => {
+  console.error(`[Babelbeez] Error (${code}): ${message}`);
+
+  if (fatal) {
+    // e.g. update UI, disable button, prompt user to refresh
+  }
+});
+```
+
+---
+
+## 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.
+
+---
+
+## License
+
+ISC
+

package/dist/babelbeez-sdk.d.ts

@@ -0,0 +1,167 @@
+export type BabelbeezButtonState =
+  | 'idle'
+  | 'loading'
+  | 'active'
+  | 'speaking'
+  | 'error'
+  | 'rag-retrieval';
+
+export interface BabelbeezTranscriptEvent {
+  role: 'user' | 'agent';
+  text: string;
+  isFinal: boolean;
+}
+
+export interface BabelbeezSessionStartEvent {
+  chatbotId: string;
+  // Chatbot configuration snapshot returned from /initialize-chat.
+  // The exact shape is backend-defined, so we leave it open.
+  config: unknown;
+}
+
+export interface BabelbeezSessionEndEvent {
+  reason: string;
+}
+
+export type BabelbeezErrorSeverity = 'info' | 'warning' | 'error';
+
+export interface BabelbeezErrorEvent {
+  code: string;
+  message: string;
+  severity: BabelbeezErrorSeverity;
+  fatal?: boolean;
+}
+
+export interface BabelbeezHandoffShowEvent {
+  summaryText: string;
+  /** WhatsApp deep-link if configured, otherwise null. */
+  waLink: string | null;
+}
+
+export type BabelbeezHandoffHideOutcome =
+  | 'email_submitted'
+  | 'whatsapp_submitted'
+  | 'cancelled';
+
+export interface BabelbeezHandoffHideEvent {
+  outcome: BabelbeezHandoffHideOutcome;
+}
+
+export interface BabelbeezClientEventMap {
+  /**
+   * Voice button / widget state changes.
+   */
+  buttonState: BabelbeezButtonState;
+
+  /**
+   * Fired once a Realtime session has successfully started.
+   */
+  'session:start': BabelbeezSessionStartEvent;
+
+  /**
+   * Fired when the session has fully ended and resources are cleaned up.
+   */
+  'session:end': BabelbeezSessionEndEvent;
+
+  /**
+   * Non-fatal and fatal errors surfaced to the host UI.
+   */
+  error: BabelbeezErrorEvent;
+
+  /**
+   * Streaming user/agent transcripts suitable for rendering a chat-like UI.
+   *
+   * - For role "user": multiple events per utterance; the last has
+   *   isFinal = true once speech transcription completes.
+   * - For role "agent": multiple events per spoken response; a final event
+   *   with isFinal = true is emitted when the assistant has finished
+   *   speaking for that turn.
+   */
+  transcript: BabelbeezTranscriptEvent;
+
+  /**
+   * Request to show the human handoff form.
+   */
+  'handoff:show': BabelbeezHandoffShowEvent;
+
+  /**
+   * Notification that the handoff form has been closed.
+   */
+  'handoff:hide': BabelbeezHandoffHideEvent;
+}
+
+export interface BabelbeezHandoffSubmitPayload {
+  email: string;
+  consent: boolean;
+}
+
+export interface BabelbeezHandoffCancelOptions {
+  viaWhatsapp?: boolean;
+}
+
+export interface BabelbeezClientConfig {
+  publicChatbotId: string;
+}
+
+/**
+ * Headless Babelbeez voice client.
+ *
+ * Manages the OpenAI Realtime session lifecycle and exposes a small
+ * event-driven API for building custom UIs.
+ */
+export class BabelbeezClient {
+  constructor(config: BabelbeezClientConfig);
+
+  /**
+   * Initialize the session via /initialize-chat and connect to the
+   * OpenAI Realtime API. Safe to call once per session.
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Gracefully end the session and send /end-chat to the backend.
+   * The optional reason is included in the payload.
+   */
+  disconnect(reason?: string): Promise<void>;
+
+  /**
+   * Optional helper to unlock the AudioContext (e.g. in response to a
+   * user gesture) when running in a browser environment.
+   */
+  initializeAudio(): void;
+
+  /**
+   * Send a text message from the user to the agent. Useful for hybrid
+   * text/voice interfaces.
+   */
+  sendUserText(text: string): Promise<void>;
+
+  /**
+   * Called when the user submits the handoff form in your UI.
+   */
+  handleHandoffSubmit(payload: BabelbeezHandoffSubmitPayload): Promise<void>;
+
+  /**
+   * Called when the user cancels the handoff form or chooses WhatsApp.
+   */
+  handleHandoffCancel(options?: BabelbeezHandoffCancelOptions): Promise<void>;
+
+  /**
+   * Subscribe to SDK events. Unknown event names are allowed but will be
+   * typed as `any` payloads.
+   */
+  on<E extends keyof BabelbeezClientEventMap>(
+    event: E,
+    listener: (payload: BabelbeezClientEventMap[E]) => void,
+  ): this;
+  on(event: string, listener: (...args: any[]) => void): this;
+
+  /**
+   * Unsubscribe an event listener.
+   */
+  off<E extends keyof BabelbeezClientEventMap>(
+    event: E,
+    listener: (payload: BabelbeezClientEventMap[E]) => void,
+  ): this;
+  off(event: string, listener: (...args: any[]) => void): this;
+}