@exotel-npm-dev/exotel-ai-assist 1.1.7 → 1.1.8

package/README.md

@@ -113,7 +113,7 @@ function AgentDashboard() {
 import { useExotelAIAssist } from "@exotel-npm-dev/exotel-ai-assist/react";
 
 function MyCustomUI({ call_sid }: { call_sid: string }) {
-  const { isReady, status, suggestions, transcripts, lastError } = useExotelAIAssist({
+  const { isReady, streamState, suggestions, transcripts, lastError } = useExotelAIAssist({
     authToken: "your-auth-token",
     call_sid,
     accountId: "your-account-id",
@@ -121,9 +121,11 @@ function MyCustomUI({ call_sid }: { call_sid: string }) {
 
   if (!isReady) return <p>Connecting…</p>;
 
+  if (streamState === "throttled") return <p>AI Assist is at capacity — available on your next call.</p>;
+  if (streamState === "disconnected") return <p>AI Assist disconnected.</p>;
+
   return (
     <div>
-      <p>Status: {status}</p>
       {suggestions.map((s) => (
         <p key={s.id}>{s.text}</p>
       ))}
@@ -184,7 +186,10 @@ ctrl.on("onReady", (ready) => {
 
 ctrl.on("suggestion", (s) => console.log("Suggestion:", s));
 ctrl.on("transcript", (t) => console.log("Transcript:", t));
-ctrl.on("statusChange", (status) => console.log("Status:", status));
+ctrl.on("streamState", (state) => {
+  console.log("Stream state:", state);
+  // state: "connected" | "throttled" | "disconnected"
+});
 ctrl.on("error", (err) => console.error("Error:", err));
 
 ctrl.connect();
@@ -240,6 +245,7 @@ Extends `EventEmitter`.
 | `setParams(patch)` | Merge params; reconnects if `call_sid` changes |
 | `destroy()`        | Dispose controller and remove all listeners    |
 | `getStatus()`      | Returns current `ConnectionStatus`             |
+| `getStreamState()` | Returns current `StreamState \| null`          |
 
 #### Events
 
@@ -249,9 +255,10 @@ Extends `EventEmitter`.
 | `suggestion`   | `Suggestion`       | New AI suggestion (capped at last 50)                                                                           |
 | `transcript`   | `TranscriptLine[]` | Live transcript update                                                                                          |
 | `sentiment`    | `Sentiment`        | Sentiment label update                                                                                          |
+| `streamState`  | `StreamState`      | Server stream state change (`connected`, `throttled`, `disconnected`)                                           |
 | `onCallStart`  | —                  | Connection opened                                                                                               |
 | `onCallEnd`    | —                  | Connection closed                                                                                               |
-| `statusChange` | `ConnectionStatus` | Status transition                                                                                               |
+| `statusChange` | `ConnectionStatus` | WebSocket-level status transition (internal)                                                                    |
 | `error`        | `Error`            | Any error (auth, parse, max-reconnect)                                                                          |
 | `raw`          | `unknown`          | Every raw server message                                                                                        |
 
@@ -259,23 +266,25 @@ Extends `EventEmitter`.
 
 ### `useExotelAIAssist(params)` — Hook return values
 
-| Field         | Type               | Description                                                            |
-| ------------- | ------------------ | ---------------------------------------------------------------------- |
-| `isReady`     | `boolean`          | `true` after connected + server ack. Multi-tab safe. `false` on disconnect |
-| `status`      | `ConnectionStatus` | Current connection status                                              |
-| `suggestions` | `Suggestion[]`     | AI suggestions, oldest first, capped at 50                             |
-| `transcripts` | `TranscriptLine[]` | Live transcript lines, ordered by start time                           |
-| `sentiment`   | `Sentiment \| null`| Latest sentiment reading                                               |
-| `lastError`   | `Error \| null`    | Most recent error                                                      |
-| `connect()`   | `() => void`       | Manually open the connection                                           |
-| `disconnect()` | `() => void`      | Manually close the connection                                          |
-| `setParams()` | `(patch) => void`  | Merge params; reconnects if connection params change                   |
+| Field          | Type                    | Description                                                                  |
+| -------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `isReady`      | `boolean`               | `true` after connected + server ack. Multi-tab safe. `false` on disconnect   |
+| `streamState`  | `StreamState \| null`   | Server stream state: `"connected"`, `"throttled"`, or `"disconnected"`. `null` until the first `stream_status` message |
+| `suggestions`  | `Suggestion[]`          | AI suggestions, oldest first, capped at 50                                   |
+| `transcripts`  | `TranscriptLine[]`      | Live transcript lines, ordered by start time                                 |
+| `sentiment`    | `Sentiment \| null`     | Latest sentiment reading                                                     |
+| `lastError`    | `Error \| null`         | Most recent error                                                            |
+| `connect()`    | `() => void`            | Manually open the connection                                                 |
+| `disconnect()` | `() => void`            | Manually close the connection                                                |
+| `setParams()`  | `(patch) => void`       | Merge params; reconnects if connection params change                         |
 
 ---
 
 ### TypeScript Types
 
 ```ts
+type StreamState = "connected" | "throttled" | "disconnected";
+
 type ConnectionStatus = "idle" | "connecting" | "connected" | "disconnected" | "error";
 
 interface Suggestion {
@@ -310,6 +319,27 @@ When `wssBaseUrl` is provided it overrides the host + path portion:
 wss://<wssBaseUrl>?[customParam1=value1&customParam2=value2&...]
 ```
 
+### Message flow
+
+1. Client opens WebSocket, sends `{ "type": "auth", "access_token": "..." }`
+2. Server responds with `{ "type": "ack", "config": {...}, "events": [...] }` — triggers `isReady`
+3. Server sends `stream_status` messages whenever the stream state changes:
+
+```json
+{
+  "type": "stream_status",
+  "config": { /* bot config, populated on connected, null otherwise */ },
+  "events": [ /* accumulated events since last message, usually [] */ ],
+  "stream_state": "connected" | "throttled" | "disconnected"
+}
+```
+
+| `stream_state`  | Meaning                                                   |
+| --------------- | --------------------------------------------------------- |
+| `connected`     | Stream is active — suggestions, transcript, and sentiment flow normally |
+| `throttled`     | Capacity full — AI Assist cannot join this call; available on the next call |
+| `disconnected`  | Stream ended or dropped                                   |
+
 ### Reconnection
 
 - Exponential back-off: `delay = Math.min(baseInterval × 2^attempt, 30 000)`

package/dist/components/EmptyState.d.ts

@@ -2,6 +2,8 @@ import React from "react";
 interface EmptyStateProps {
     title: string;
     subtitle: string;
+    showWarningBanner?: boolean;
+    warningBannerMessage?: string;
 }
 export declare const EmptyState: React.FC<EmptyStateProps>;
 export {};

package/dist/components/key-components/SuggestionTab.d.ts

@@ -1,6 +1,6 @@
 import { Suggestion, BotConfig } from "../../types";
 import "../../styles/index.css";
-export declare function SuggestionsTab({ suggestions, connected, botConfig }: {
+export declare function SuggestionsTab({ suggestions, connected, botConfig, }: {
     suggestions: Suggestion[];
     connected: boolean;
     botConfig: BotConfig | null;

package/dist/components/key-components/TranscriptTab.d.ts

@@ -1,6 +1,6 @@
 import { TranscriptLine, BotConfig } from "../../types";
 import "../../styles/index.css";
-export declare function TranscriptTab({ transcripts, connected, botConfig }: {
+export declare function TranscriptTab({ transcripts, connected, botConfig, }: {
     transcripts: TranscriptLine[];
     connected: boolean;
     botConfig: BotConfig | null;

package/dist/controller/index.d.ts

@@ -1,5 +1,5 @@
 import EventEmitter from "eventemitter3";
-import { ExotelAIAssistParams, ConnectionStatus, ControllerEvents } from "../types";
+import { ExotelAIAssistParams, ConnectionStatus, ControllerEvents, StreamState } from "../types";
 export declare class ExotelAIAssistController extends EventEmitter<ControllerEvents> {
     private params;
     private transport;
@@ -7,6 +7,7 @@ export declare class ExotelAIAssistController extends EventEmitter<ControllerEve
     private destroyed;
     private connectionEstablished;
     private readyFired;
+    private _streamState;
     private reconnectAttempt;
     private reconnectTimer;
     private static readonly MAX_RECONNECT_ATTEMPTS;
@@ -17,11 +18,13 @@ export declare class ExotelAIAssistController extends EventEmitter<ControllerEve
     setParams(patch: Partial<ExotelAIAssistParams>): void;
     destroy(): void;
     getStatus(): ConnectionStatus;
+    getStreamState(): StreamState | null;
     private _ensureTransport;
     private _handleTransportMessage;
     private _scheduleReconnect;
     private _clearReconnectTimer;
     private _fireReady;
     private _handleServerPayload;
+    private _handleStreamStatus;
     private _setStatus;
 }

package/dist/controller/index.js

@@ -1538,7 +1538,7 @@ class Utils {
    * @returns The base WebSocket URL.
    */
   static getWssBaseUrl(accountId) {
-    return `wss://aiassist-uat.in.exotel.com/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
+    return `ws://localhost:3456/ai-assist/ws/v1/accounts/${accountId}/ai-assistants/conversation-events`;
   }
   /**
    * Builds a WebSocket URL from the given parameters.
@@ -1603,6 +1603,7 @@ class ExotelAIAssistController extends EventEmitter {
     //   connectionEstablished === true   → server ended a live connection → destroy
     this.connectionEstablished = false;
     this.readyFired = false;
+    this._streamState = null;
     this.reconnectAttempt = 0;
     this.reconnectTimer = null;
     this.params = Object.assign({}, params);
@@ -1612,6 +1613,7 @@ class ExotelAIAssistController extends EventEmitter {
     this._clearReconnectTimer();
     this.connectionEstablished = false;
     this.readyFired = false;
+    this._streamState = null;
     this.reconnectAttempt = 0;
     this._setStatus("connecting");
     this._ensureTransport();
@@ -1662,6 +1664,9 @@ class ExotelAIAssistController extends EventEmitter {
   getStatus() {
     return this.status;
   }
+  getStreamState() {
+    return this._streamState;
+  }
   _ensureTransport() {
     if (this.transport) return;
     this.transport = createTransport(Utils.hash(this.params));
@@ -1677,7 +1682,6 @@ class ExotelAIAssistController extends EventEmitter {
         this.emit("onCallStart");
         break;
       case "ACKNOWLEDGED":
-        this._fireReady();
         break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
@@ -1732,11 +1736,11 @@ class ExotelAIAssistController extends EventEmitter {
     this.emit("onReady", true);
   }
   _handleServerPayload(raw) {
-    var _a, _b;
+    var _a, _b, _c;
     let parsed;
     try {
       parsed = JSON.parse(raw);
-    } catch (_c) {
+    } catch (_d) {
       this.emit("error", new Error(`Failed to parse server message: ${raw}`));
       return;
     }
@@ -1752,7 +1756,12 @@ class ExotelAIAssistController extends EventEmitter {
     }
     if (msgType === "ack") {
       (_b = this.transport) === null || _b === void 0 ? void 0 : _b.markAcknowledged();
-      this._fireReady();
+      const state = parsed.stream_state;
+      if (state) this._handleStreamStatus(state);
+    }
+    if (msgType === "stream_status") {
+      const state = parsed.stream_state;
+      if (state) this._handleStreamStatus(state);
     }
     if (parsed.config) {
       this.emit("botConfig", parsed.config);
@@ -1763,14 +1772,15 @@ class ExotelAIAssistController extends EventEmitter {
     const now = Date.now();
     for (const event of events) {
       if (!event) continue;
-      if (event.transcript && event.transcript.length > 0) {
-        const lines = event.transcript.map(msg => {
+      if (event.event_type === "transcript" && event.value) {
+        const transcripts = Array.isArray(event === null || event === void 0 ? void 0 : event.value) ? event.value : (_c = event === null || event === void 0 ? void 0 : event.transcript) !== null && _c !== void 0 ? _c : [];
+        const lines = transcripts.map(msg => {
           var _a, _b, _c, _d, _e;
           const first = (_a = msg.transcript_segments) === null || _a === void 0 ? void 0 : _a[0];
           const last = (_b = msg.transcript_segments) === null || _b === void 0 ? void 0 : _b[msg.transcript_segments.length - 1];
           return {
             id: String(msg.sequence),
-            text: (_e = (_d = (_c = msg.transcript_segments) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.text) !== null && _e !== void 0 ? _e : "",
+            value: (_e = (_d = (_c = msg.transcript_segments) === null || _c === void 0 ? void 0 : _c[0]) === null || _d === void 0 ? void 0 : _d.text) !== null && _e !== void 0 ? _e : "",
             startTime: (first === null || first === void 0 ? void 0 : first.start_timestamp) ? Date.parse(first.start_timestamp) : now,
             endTime: (last === null || last === void 0 ? void 0 : last.end_timestamp) ? Date.parse(last.end_timestamp) : now,
             isFinal: msg.transcript_segments.every(s => s.is_final)
@@ -1778,23 +1788,31 @@ class ExotelAIAssistController extends EventEmitter {
         });
         this.emit("transcript", lines);
       }
-      if (event.event_type === "suggestion" && event.text) {
+      if (event.event_type === "suggestion" && event.value) {
         const suggestion = {
           id: Utils.getUniqueId(),
-          text: event.text,
+          value: event.value,
           timestamp: now
         };
         this.emit("suggestion", suggestion);
       }
-      if (event.event_type === "sentiment" && event.text) {
+      if (event.event_type === "sentiment" && event.value) {
         const sentiment = {
-          label: event.text.toLowerCase(),
+          label: event.value.toLowerCase(),
           timestamp: now
         };
         this.emit("sentiment", sentiment);
       }
     }
   }
+  _handleStreamStatus(state) {
+    this._streamState = state;
+    this.emit("streamState", state);
+    // We are firing ready because we need to show the UI immediately when the stream is connected or throttled.
+    if (state === "connected" || state === "throttled") {
+      this._fireReady();
+    }
+  }
   _setStatus(status) {
     if (this.status === status) return;
     this.status = status;

package/dist/hooks/useExotelAIAssist.d.ts

@@ -1,6 +1,5 @@
-import { ExotelAIAssistParams, Suggestion, TranscriptLine, Sentiment, BotConfig, ConnectionStatus } from "../types";
+import { ExotelAIAssistParams, Suggestion, TranscriptLine, Sentiment, BotConfig, StreamState } from "../types";
 export interface UseExotelAIAssistReturn {
-    status: ConnectionStatus;
     /**
      * `true` once the WebSocket connection is established and the server has
      * acknowledged it.  In multi-tab scenarios where this tab joins an
@@ -8,6 +7,14 @@ export interface UseExotelAIAssistReturn {
      * Resets to `false` on disconnect.
      */
     isReady: boolean;
+    /**
+     * Server-reported stream state from `stream_status` messages.
+     * `null` until the first `stream_status` is received.
+     * - `"connected"`    – stream is active and healthy
+     * - `"throttled"`    – capacity full; bot cannot join this call
+     * - `"disconnected"` – stream ended or dropped
+     */
+    streamState: StreamState | null;
     /** AI suggestions, oldest first, capped at 50. */
     suggestions: Suggestion[];
     /** Live transcript lines, ordered by start time. */

package/dist/index.d.ts

@@ -2,4 +2,4 @@ import { ExotelAIAssistParams } from "./types";
 export declare function mountExotelAIAssist(container: HTMLElement, params: ExotelAIAssistParams): void;
 export declare function unmountExotelAIAssist(container: HTMLElement): void;
 export { ExotelAIAssistController } from "./controller";
-export type { ExotelAIAssistParams, Suggestion, TranscriptLine, Sentiment, ConnectionStatus } from "./types";
+export type { ExotelAIAssistParams, Suggestion, TranscriptLine, Sentiment, ConnectionStatus, StreamState } from "./types";