@exotel-npm-dev/exotel-ai-assist 1.3.7 → 1.5.0

package/README.md

@@ -121,6 +121,8 @@ function MyCustomUI({ call_sid }: { call_sid: string }) {
 
   if (!isReady) return <p>Connecting…</p>;
 
+  if (streamState === "quota_exhausted") return <p>Your organisation's AI Assist quota is exhausted.</p>;
+  if (streamState === "agent_quota_exhausted") return <p>Your personal AI Assist call limit is reached.</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>;
   if (streamState === "connection_timeout") return <p>Connection timed out.</p>;
@@ -189,7 +191,7 @@ ctrl.on("suggestion", (s) => console.log("Suggestion:", s));
 ctrl.on("transcript", (t) => console.log("Transcript:", t));
 ctrl.on("streamState", (state) => {
   console.log("Stream state:", state);
-  // state: "connected" | "throttled" | "pending" | "disconnected" | "connection_timeout"
+  // Quota blocks are reported as "quota_exhausted" or "agent_quota_exhausted".
 });
 ctrl.on("error", (err) => console.error("Error:", err));
 
@@ -256,7 +258,7 @@ 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`, `pending`, `disconnected`, `connection_timeout`)          |
+| `streamState`  | `StreamState`      | Server stream state change, including tenant and per-agent quota exhaustion                                     |
 | `onCallStart`  | —                  | Connection opened                                                                                               |
 | `onCallEnd`    | —                  | Connection closed                                                                                               |
 | `statusChange` | `ConnectionStatus` | WebSocket-level status transition (internal)                                                                    |
@@ -270,7 +272,7 @@ Extends `EventEmitter`.
 | Field                      | Type                    | Description                                                                  |
 | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
 | `isReady`                  | `boolean`               | `true` after connected + server ack. Multi-tab safe. `false` on disconnect   |
-| `streamState`              | `StreamState \| null`   | Server stream state: `"connected"`, `"throttled"`, `"pending"`, `"disconnected"`, or `"connection_timeout"`. `null` until the first `stream_status` message |
+| `streamState`              | `StreamState \| null`   | Server stream state, including `"quota_exhausted"` and `"agent_quota_exhausted"`. `null` until the first stream-state 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                                                     |
@@ -284,7 +286,14 @@ Extends `EventEmitter`.
 ### TypeScript Types
 
 ```ts
-type StreamState = "connected" | "throttled" | "pending" | "disconnected" | "connection_timeout";
+type StreamState =
+  | "connected"
+  | "throttled"
+  | "quota_exhausted"
+  | "agent_quota_exhausted"
+  | "pending"
+  | "disconnected"
+  | "connection_timeout";
 
 type ConnectionStatus = "idle" | "connecting" | "connected" | "disconnected" | "error";
 
@@ -331,7 +340,7 @@ wss://<wssBaseUrl>?[customParam1=value1&customParam2=value2&...]
   "type": "stream_status",
   "config": { /* bot config, populated on connected, null otherwise */ },
   "events": [ /* accumulated events since last message, usually [] */ ],
-  "stream_state": "connected" | "throttled" | "pending" | "disconnected" | "connection_timeout"
+  "stream_state": "connected" | "throttled" | "quota_exhausted" | "agent_quota_exhausted" | "pending" | "disconnected" | "connection_timeout"
 }
 ```
 
@@ -339,6 +348,8 @@ wss://<wssBaseUrl>?[customParam1=value1&customParam2=value2&...]
 | -------------------- | --------------------------------------------------------- |
 | `connected`          | Stream is active — suggestions, transcript, and sentiment flow normally |
 | `throttled`          | Capacity full — AI Assist cannot join this call; available on the next call |
+| `quota_exhausted`    | The organisation's AI Assist plan quota is exhausted |
+| `agent_quota_exhausted` | The current agent's AI Assist call allowance is exhausted |
 | `pending`            | Stream is pending — waiting for a definitive state |
 | `disconnected`       | Stream ended or dropped                                   |
 | `connection_timeout` | Connection timeout occurred                               |

package/dist/controller/index.js

@@ -1604,6 +1604,10 @@ class Utils {
 }
 Utils.MAX_EXTRA_QUERY_PARAMS = 3;
 
+const UNAVAILABLE_STREAM_STATES = new Set(["throttled", "quota_exhausted", "agent_quota_exhausted"]);
+function isUnavailableStreamState(state) {
+  return state !== null && UNAVAILABLE_STREAM_STATES.has(state);
+}
 class ExotelAIAssistController extends EventEmitter {
   constructor(params) {
     super();
@@ -1637,7 +1641,7 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
-    if (this.readyFired && this._streamState !== "throttled") {
+    if (this.readyFired && !isUnavailableStreamState(this._streamState)) {
       this.readyFired = false;
       this.emit("onReady", false);
     }
@@ -1719,8 +1723,8 @@ class ExotelAIAssistController extends EventEmitter {
         break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          const wasThrottled = this._streamState === "throttled";
-          if (this.readyFired && !wasThrottled) {
+          const wasUnavailable = isUnavailableStreamState(this._streamState);
+          if (this.readyFired && !wasUnavailable) {
             this.emit("onReady", false);
           }
           this.connectionEstablished = false;
@@ -1872,7 +1876,7 @@ class ExotelAIAssistController extends EventEmitter {
   _handleStreamStatus(state) {
     this._streamState = state;
     this.emit("streamState", state);
-    if (state === "connected" || state === "throttled") {
+    if (state === "connected" || isUnavailableStreamState(state)) {
       this._fireReady();
     } else if (this.readyFired) {
       this.readyFired = false;

package/dist/hooks/useExotelAIAssist.d.ts

@@ -10,9 +10,11 @@ export interface UseExotelAIAssistReturn {
     /**
      * 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
+     * - `"connected"`             – stream is active and healthy
+     * - `"throttled"`             – capacity full; bot cannot join this call
+     * - `"quota_exhausted"`       – tenant plan quota is exhausted
+     * - `"agent_quota_exhausted"` – current agent's call quota is exhausted
+     * - `"disconnected"`          – stream ended or dropped
      */
     streamState: StreamState | null;
     /** AI suggestions, oldest first, capped at 50. */

package/dist/index.js

@@ -22105,6 +22105,10 @@ class Utils {
 }
 Utils.MAX_EXTRA_QUERY_PARAMS = 3;
 
+const UNAVAILABLE_STREAM_STATES$1 = new Set(["throttled", "quota_exhausted", "agent_quota_exhausted"]);
+function isUnavailableStreamState(state) {
+  return state !== null && UNAVAILABLE_STREAM_STATES$1.has(state);
+}
 class ExotelAIAssistController extends EventEmitter {
   constructor(params) {
     super();
@@ -22138,7 +22142,7 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
-    if (this.readyFired && this._streamState !== "throttled") {
+    if (this.readyFired && !isUnavailableStreamState(this._streamState)) {
       this.readyFired = false;
       this.emit("onReady", false);
     }
@@ -22220,8 +22224,8 @@ class ExotelAIAssistController extends EventEmitter {
         break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          const wasThrottled = this._streamState === "throttled";
-          if (this.readyFired && !wasThrottled) {
+          const wasUnavailable = isUnavailableStreamState(this._streamState);
+          if (this.readyFired && !wasUnavailable) {
             this.emit("onReady", false);
           }
           this.connectionEstablished = false;
@@ -22373,7 +22377,7 @@ class ExotelAIAssistController extends EventEmitter {
   _handleStreamStatus(state) {
     this._streamState = state;
     this.emit("streamState", state);
-    if (state === "connected" || state === "throttled") {
+    if (state === "connected" || isUnavailableStreamState(state)) {
       this._fireReady();
     } else if (this.readyFired) {
       this.readyFired = false;
@@ -23236,6 +23240,7 @@ function TransferSummaryCard({
   });
 }
 
+const UNAVAILABLE_STREAM_STATES = new Set(["throttled", "quota_exhausted", "agent_quota_exhausted"]);
 function ExotelAIAssist(_a) {
   var {
       className,
@@ -23260,6 +23265,22 @@ function ExotelAIAssist(_a) {
   }, [isReady]);
   const connected = streamState === "connected";
   function renderProperEmptyContent() {
+    if (streamState === "quota_exhausted") {
+      return jsxRuntimeExports.jsx(EmptyState, {
+        title: "AI Assist Unavailable",
+        subtitle: "Contact your administrator to restore AI Assist.",
+        showWarningBanner: true,
+        warningBannerMessage: "Your organisation's AI Assist quota is exhausted. Ask your admin to renew the plan."
+      });
+    }
+    if (streamState === "agent_quota_exhausted") {
+      return jsxRuntimeExports.jsx(EmptyState, {
+        title: "Your AI Assist limit is reached",
+        subtitle: "Contact your administrator to raise your call allowance.",
+        showWarningBanner: true,
+        warningBannerMessage: "You've reached your personal AI Assist call limit."
+      });
+    }
     if (streamState === "throttled") {
       return jsxRuntimeExports.jsx(EmptyState, {
         title: "AI Assist Unavailable",
@@ -23296,7 +23317,7 @@ function ExotelAIAssist(_a) {
               botConfig: botConfig
             }), transferSummary ? jsxRuntimeExports.jsx(TransferSummaryCard, {
               data: transferSummary
-            }) : null, streamState !== "throttled" ? jsxRuntimeExports.jsxs(Root2$1, {
+            }) : null, !streamState || !UNAVAILABLE_STREAM_STATES.has(streamState) ? jsxRuntimeExports.jsxs(Root2$1, {
               defaultValue: "suggestions",
               className: "oa-tabs",
               style: {

package/dist/react/index.js

@@ -7391,6 +7391,10 @@ class Utils {
 }
 Utils.MAX_EXTRA_QUERY_PARAMS = 3;
 
+const UNAVAILABLE_STREAM_STATES$1 = new Set(["throttled", "quota_exhausted", "agent_quota_exhausted"]);
+function isUnavailableStreamState(state) {
+  return state !== null && UNAVAILABLE_STREAM_STATES$1.has(state);
+}
 class ExotelAIAssistController extends EventEmitter {
   constructor(params) {
     super();
@@ -7424,7 +7428,7 @@ class ExotelAIAssistController extends EventEmitter {
     var _a;
     this._clearReconnectTimer();
     (_a = this.transport) === null || _a === void 0 ? void 0 : _a.disconnect();
-    if (this.readyFired && this._streamState !== "throttled") {
+    if (this.readyFired && !isUnavailableStreamState(this._streamState)) {
       this.readyFired = false;
       this.emit("onReady", false);
     }
@@ -7506,8 +7510,8 @@ class ExotelAIAssistController extends EventEmitter {
         break;
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          const wasThrottled = this._streamState === "throttled";
-          if (this.readyFired && !wasThrottled) {
+          const wasUnavailable = isUnavailableStreamState(this._streamState);
+          if (this.readyFired && !wasUnavailable) {
             this.emit("onReady", false);
           }
           this.connectionEstablished = false;
@@ -7659,7 +7663,7 @@ class ExotelAIAssistController extends EventEmitter {
   _handleStreamStatus(state) {
     this._streamState = state;
     this.emit("streamState", state);
-    if (state === "connected" || state === "throttled") {
+    if (state === "connected" || isUnavailableStreamState(state)) {
       this._fireReady();
     } else if (this.readyFired) {
       this.readyFired = false;
@@ -8522,6 +8526,7 @@ function TransferSummaryCard({
   });
 }
 
+const UNAVAILABLE_STREAM_STATES = new Set(["throttled", "quota_exhausted", "agent_quota_exhausted"]);
 function ExotelAIAssist(_a) {
   var {
       className,
@@ -8546,6 +8551,22 @@ function ExotelAIAssist(_a) {
   }, [isReady]);
   const connected = streamState === "connected";
   function renderProperEmptyContent() {
+    if (streamState === "quota_exhausted") {
+      return jsxRuntime.jsx(EmptyState, {
+        title: "AI Assist Unavailable",
+        subtitle: "Contact your administrator to restore AI Assist.",
+        showWarningBanner: true,
+        warningBannerMessage: "Your organisation's AI Assist quota is exhausted. Ask your admin to renew the plan."
+      });
+    }
+    if (streamState === "agent_quota_exhausted") {
+      return jsxRuntime.jsx(EmptyState, {
+        title: "Your AI Assist limit is reached",
+        subtitle: "Contact your administrator to raise your call allowance.",
+        showWarningBanner: true,
+        warningBannerMessage: "You've reached your personal AI Assist call limit."
+      });
+    }
     if (streamState === "throttled") {
       return jsxRuntime.jsx(EmptyState, {
         title: "AI Assist Unavailable",
@@ -8582,7 +8603,7 @@ function ExotelAIAssist(_a) {
               botConfig: botConfig
             }), transferSummary ? jsxRuntime.jsx(TransferSummaryCard, {
               data: transferSummary
-            }) : null, streamState !== "throttled" ? jsxRuntime.jsxs(Root2$1, {
+            }) : null, !streamState || !UNAVAILABLE_STREAM_STATES.has(streamState) ? jsxRuntime.jsxs(Root2$1, {
               defaultValue: "suggestions",
               className: "oa-tabs",
               style: {

package/dist/types/index.d.ts

@@ -37,11 +37,13 @@ export interface Sentiment {
 export type ConnectionStatus = "idle" | "connecting" | "connected" | "disconnected" | "error";
 /**
  * Server-side stream state, received via `stream_status` messages.
- * - `connected`    – stream is active and healthy
- * - `throttled`    – capacity full; the bot cannot join this call
- * - `pending` – stream is pending
+ * - `connected`              – stream is active and healthy
+ * - `throttled`              – capacity full; the bot cannot join this call
+ * - `quota_exhausted`        – the tenant's plan quota is exhausted
+ * - `agent_quota_exhausted`  – the current agent's call quota is exhausted
+ * - `pending`                – stream is pending
  */
-export type StreamState = "connected" | "throttled" | "pending" | "disconnected" | "connection_timeout";
+export type StreamState = "connected" | "throttled" | "quota_exhausted" | "agent_quota_exhausted" | "pending" | "disconnected" | "connection_timeout";
 /** Feature-flag config received from the AI Assist backend. */
 export interface BotConfig {
     sentiment: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exotel-npm-dev/exotel-ai-assist",
-  "version": "1.3.7",
+  "version": "1.5.0",
   "description": "AI-powered real-time suggestions, transcript, and sentiment for agent calls",
   "license": "Apache-2.0",
   "main": "dist/index.js",

package/src/components/ExotelAIAssistApp.tsx

@@ -19,6 +19,12 @@ export interface ExotelAIAssistProps extends ExotelAIAssistParams {
   onReady?: (ready: boolean) => void;
 }
 
+const UNAVAILABLE_STREAM_STATES = new Set([
+  "throttled",
+  "quota_exhausted",
+  "agent_quota_exhausted",
+]);
+
 export function ExotelAIAssist({ className, onReady, ...params }: ExotelAIAssistProps): JSX.Element {
   const {
     streamState,
@@ -41,6 +47,26 @@ export function ExotelAIAssist({ className, onReady, ...params }: ExotelAIAssist
   const connected = streamState === "connected";
 
   function renderProperEmptyContent(): JSX.Element | null {
+    if (streamState === "quota_exhausted") {
+      return (
+        <EmptyState
+          title="AI Assist Unavailable"
+          subtitle="Contact your administrator to restore AI Assist."
+          showWarningBanner={true}
+          warningBannerMessage="Your organisation's AI Assist quota is exhausted. Ask your admin to renew the plan."
+        />
+      );
+    }
+    if (streamState === "agent_quota_exhausted") {
+      return (
+        <EmptyState
+          title="Your AI Assist limit is reached"
+          subtitle="Contact your administrator to raise your call allowance."
+          showWarningBanner={true}
+          warningBannerMessage="You've reached your personal AI Assist call limit."
+        />
+      );
+    }
     if (streamState === "throttled") {
       return (
         <EmptyState
@@ -66,7 +92,7 @@ export function ExotelAIAssist({ className, onReady, ...params }: ExotelAIAssist
               <Header sentiment={sentiment} botConfig={botConfig} />
               {transferSummary ? <TransferSummaryCard data={transferSummary} /> : null}
 
-              {streamState !== "throttled" ? (
+              {!streamState || !UNAVAILABLE_STREAM_STATES.has(streamState) ? (
                 <Tabs.Root defaultValue="suggestions" className="oa-tabs" style={{ flex: 1, display: "flex", flexDirection: "column", minHeight: 0 }}>
                   <Tabs.List className="oa-tabs-list">
                     <Tabs.Trigger value="suggestions" className="oa-tabs-trigger">

package/src/controller/index.ts

@@ -17,6 +17,16 @@ import {
 import { ITransport, createTransport } from "../transport";
 import { Utils } from "../utils";
 
+const UNAVAILABLE_STREAM_STATES: ReadonlySet<StreamState> = new Set([
+  "throttled",
+  "quota_exhausted",
+  "agent_quota_exhausted",
+]);
+
+function isUnavailableStreamState(state: StreamState | null): boolean {
+  return state !== null && UNAVAILABLE_STREAM_STATES.has(state);
+}
+
 export class ExotelAIAssistController extends EventEmitter<ControllerEvents> {
   private params: ExotelAIAssistParams;
   private transport: ITransport | null = null;
@@ -57,7 +67,7 @@ export class ExotelAIAssistController extends EventEmitter<ControllerEvents> {
   disconnect(): void {
     this._clearReconnectTimer();
     this.transport?.disconnect();
-    if (this.readyFired && this._streamState !== "throttled") {
+    if (this.readyFired && !isUnavailableStreamState(this._streamState)) {
       this.readyFired = false;
       this.emit("onReady", false);
     }
@@ -145,8 +155,8 @@ export class ExotelAIAssistController extends EventEmitter<ControllerEvents> {
 
       case "DISCONNECTED":
         if (this.connectionEstablished) {
-          const wasThrottled = this._streamState === "throttled";
-          if (this.readyFired && !wasThrottled) {
+          const wasUnavailable = isUnavailableStreamState(this._streamState);
+          if (this.readyFired && !wasUnavailable) {
             this.emit("onReady", false);
           }
           this.connectionEstablished = false;
@@ -323,7 +333,7 @@ export class ExotelAIAssistController extends EventEmitter<ControllerEvents> {
   private _handleStreamStatus(state: StreamState): void {
     this._streamState = state;
     this.emit("streamState", state);
-    if (state === "connected" || state === "throttled") {
+    if (state === "connected" || isUnavailableStreamState(state)) {
       this._fireReady();
     } else if (this.readyFired) {
       this.readyFired = false;

package/src/hooks/useExotelAIAssist.ts

@@ -24,9 +24,11 @@ export interface UseExotelAIAssistReturn {
   /**
    * 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
+   * - `"connected"`             – stream is active and healthy
+   * - `"throttled"`             – capacity full; bot cannot join this call
+   * - `"quota_exhausted"`       – tenant plan quota is exhausted
+   * - `"agent_quota_exhausted"` – current agent's call quota is exhausted
+   * - `"disconnected"`          – stream ended or dropped
    */
   streamState: StreamState | null;
   /** AI suggestions, oldest first, capped at 50. */

package/src/types/index.ts

@@ -42,11 +42,20 @@ export type ConnectionStatus = "idle" | "connecting" | "connected" | "disconnect
 
 /**
  * Server-side stream state, received via `stream_status` messages.
- * - `connected`    – stream is active and healthy
- * - `throttled`    – capacity full; the bot cannot join this call
- * - `pending` – stream is pending
+ * - `connected`              – stream is active and healthy
+ * - `throttled`              – capacity full; the bot cannot join this call
+ * - `quota_exhausted`        – the tenant's plan quota is exhausted
+ * - `agent_quota_exhausted`  – the current agent's call quota is exhausted
+ * - `pending`                – stream is pending
  */
-export type StreamState = "connected" | "throttled" | "pending" | "disconnected" | "connection_timeout";
+export type StreamState =
+  | "connected"
+  | "throttled"
+  | "quota_exhausted"
+  | "agent_quota_exhausted"
+  | "pending"
+  | "disconnected"
+  | "connection_timeout";
 
 // ---------------------------------------------------------------------------
 // Internal-only backend response types