@babelbeez/sdk 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `@babelbeez/sdk` are documented here.
 
+## [0.3.3] - 2026-03-15
+
+### Fixed
+- Added an explicit `hardDisconnect()` path for UI end-call actions and stabilized disconnect handling so explicit stop clicks no longer rely on promise chaining from `session.interrupt()`.
+- Restored the intended AI end-call flow so the `end_conversation` tool triggers the configured localized goodbye turn from the SDK, instead of requiring the model to say goodbye before calling the tool.
+- Added a `finalizing` button state to better represent in-progress disconnects for host UIs.
+
+
 ## [0.3.2] - 2026-01-30
 
 ### Fixed

package/README.md

@@ -47,11 +47,18 @@ const client = new BabelbeezClient({
   publicChatbotId: 'YOUR_PUBLIC_CHATBOT_ID',
 });
 
-let currentState: 'idle' | 'loading' | 'active' | 'speaking' | 'error' | 'rag-retrieval' = 'idle';
+let currentState:
+  | 'idle'
+  | 'loading'
+  | 'active'
+  | 'speaking'
+  | 'finalizing'
+  | 'error'
+  | 'rag-retrieval' = 'idle';
 
 // 2. Listen for state changes to drive your UI
 client.on('buttonState', (state) => {
-  // state: 'idle' | 'loading' | 'active' | 'speaking' | 'error' | 'rag-retrieval'
+  // state: 'idle' | 'loading' | 'active' | 'speaking' | 'finalizing' | 'error' | 'rag-retrieval'
   console.log('Agent state:', state);
   currentState = state;
   updateMyButton(state); // implement this in your own UI
@@ -69,8 +76,8 @@ 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');
+    // Immediate explicit stop for UI end-call actions
+    await client.hardDisconnect('user_button_click');
   } else if (currentState === 'idle' || currentState === 'error') {
     try {
       await client.connect(); // Browser will request microphone access
@@ -215,7 +222,7 @@ await client.connect();
 
 #### `disconnect(reason?: string): Promise<void>`
 
-Gracefully ends the current session and sends a final usage + transcript summary to Babelbeez.
+Ends the current session and sends a final usage + transcript summary to Babelbeez. This method remains available as a compatibility wrapper.
 
 ```ts
 await client.disconnect();
@@ -224,7 +231,31 @@ await client.disconnect('user_button_click');
 ```
 
 - `reason` **(optional)** – String reason used for analytics and backend handling.
-  - Passing `'user_button_click'` triggers the configured **goodbye message** before disconnecting.
+  - For explicit UI end-call actions, prefer `hardDisconnect('user_button_click')`.
+
+---
+
+#### `hardDisconnect(reason?: string): Promise<void>`
+
+Immediately ends the current session without waiting for assistant audio to finish.
+
+```ts
+await client.hardDisconnect('user_button_click');
+```
+
+Use this for explicit end-call buttons where the user expects an immediate stop.
+
+---
+
+#### `gracefulDisconnect(reason?: string): Promise<void>`
+
+Triggers the configured AI goodbye turn and then ends the session after that goodbye audio finishes.
+
+```ts
+await client.gracefulDisconnect('ai_end_conversation_tool');
+```
+
+This is primarily intended for SDK-managed end-of-call flows.
 
 ---
 
@@ -303,6 +334,7 @@ export type BabelbeezButtonState =
   | 'loading'
   | 'active'
   | 'speaking'
+  | 'finalizing'
   | 'error'
   | 'rag-retrieval';
 ```

package/dist/babelbeez-sdk.d.ts

@@ -3,6 +3,7 @@ export type BabelbeezButtonState =
   | 'loading'
   | 'active'
   | 'speaking'
+  | 'finalizing'
   | 'error'
   | 'rag-retrieval';
 
@@ -119,11 +120,26 @@ export class BabelbeezClient {
   connect(): Promise<void>;
 
   /**
-   * Gracefully end the session and send /end-chat to the backend.
-   * The optional reason is included in the payload.
+   * End the current session.
+   *
+   * For common UI stop actions, prefer `hardDisconnect('user_button_click')`
+   * for an immediate stop. This legacy wrapper remains available for
+   * compatibility and routes certain known reasons to the appropriate path.
    */
   disconnect(reason?: string): Promise<void>;
 
+  /**
+   * Immediately end the session without waiting for any active assistant
+   * audio to finish.
+   */
+  hardDisconnect(reason?: string): Promise<void>;
+
+  /**
+   * Trigger the configured AI goodbye turn and end the session after that
+   * goodbye audio finishes.
+   */
+  gracefulDisconnect(reason?: string): Promise<void>;
+
   /**
    * Optional helper to unlock the AudioContext (e.g. in response to a
    * user gesture) when running in a browser environment.