@absolutejs/voice 0.0.22-beta.653 → 0.0.22-beta.655

package/dist/client/index.js

@@ -109,14 +109,17 @@ var WS_FORBIDDEN = 4403;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 15;
 var DEFAULT_PING_INTERVAL = 30000;
 var DEFAULT_RECONNECT_RESET_AFTER_MS = 30000;
+var DEFAULT_CALL_CONTROL_ACK_TIMEOUT_MS = 5000;
+var MAX_PENDING_CONTROL_MESSAGES = 100;
 var RECONNECT_BASE_DELAY_MS = 500;
 var DEFAULT_RECONNECT_MAX_DELAY_MS = 8000;
 var computeVoiceReconnectDelayMs = (attempt, baseMs, maxDelayMs) => Math.min(maxDelayMs, baseMs * 2 ** (Math.max(1, attempt) - 1));
 var DEFAULT_SCENARIO_QUERY_PARAM = "scenarioId";
 var noop = () => {};
+var noopAsync = () => Promise.resolve();
 var noopUnsubscribe = () => noop;
 var NOOP_CONNECTION = {
-  callControl: noop,
+  callControl: noopAsync,
   close: noop,
   disconnect: noop,
   endTurn: noop,
@@ -154,6 +157,7 @@ var isVoiceServerMessage = (value) => {
     case "audio":
     case "assistant":
     case "call_lifecycle":
+    case "call_control_ack":
     case "complete":
     case "connection":
     case "error":
@@ -184,6 +188,7 @@ var createVoiceConnection = (path, options = {}) => {
     return NOOP_CONNECTION;
   }
   const listeners = new Set;
+  const pendingCallControls = new Map;
   const shouldReconnect = options.reconnect !== false;
   const maxReconnectAttempts = options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
   const reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
@@ -204,6 +209,21 @@ var createVoiceConnection = (path, options = {}) => {
   const emitConnection = (reconnect) => {
     listeners.forEach((listener) => listener(reconnect));
   };
+  const emitTerminalFailure = (message) => {
+    listeners.forEach((listener) => listener({
+      message,
+      recoverable: false,
+      type: "error"
+    }));
+    emitConnection({
+      reconnect: {
+        attempts: state.reconnectAttempts,
+        maxAttempts: maxReconnectAttempts,
+        status: "exhausted"
+      },
+      type: "connection"
+    });
+  };
   const clearTimers = () => {
     if (state.pingInterval) {
       clearInterval(state.pingInterval);
@@ -229,6 +249,13 @@ var createVoiceConnection = (path, options = {}) => {
       }
     }
   };
+  const rejectPendingCallControls = (message) => {
+    for (const pending of pendingCallControls.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(message));
+    }
+    pendingCallControls.clear();
+  };
   const scheduleReconnect = () => {
     state.reconnectAttempts += 1;
     const delayMs = computeReconnectDelayMs(state.reconnectAttempts);
@@ -243,16 +270,24 @@ var createVoiceConnection = (path, options = {}) => {
       },
       type: "connection"
     });
-    state.reconnectTimeout = setTimeout(() => {
+    state.reconnectTimeout = setTimeout(async () => {
       if (state.reconnectAttempts > maxReconnectAttempts) {
-        emitConnection({
-          reconnect: {
-            attempts: state.reconnectAttempts,
-            maxAttempts: maxReconnectAttempts,
-            status: "exhausted"
-          },
-          type: "connection"
+        emitTerminalFailure("Voice connection could not be restored.");
+        return;
+      }
+      try {
+        await options.prepareReconnect?.({
+          attempt: state.reconnectAttempts,
+          path,
+          scenarioId: state.scenarioId,
+          sessionId: state.sessionId
         });
+      } catch {
+        if (state.reconnectAttempts < maxReconnectAttempts) {
+          scheduleReconnect();
+        } else {
+          emitTerminalFailure("Voice authorization could not be renewed for reconnect.");
+        }
         return;
       }
       connect();
@@ -309,6 +344,18 @@ var createVoiceConnection = (path, options = {}) => {
         state.sessionId = parsed.sessionId;
         state.scenarioId = parsed.scenarioId ?? state.scenarioId;
       }
+      if (parsed.type === "call_control_ack") {
+        const pending = pendingCallControls.get(parsed.requestId);
+        if (pending) {
+          clearTimeout(pending.timeout);
+          pendingCallControls.delete(parsed.requestId);
+          if (parsed.ok) {
+            pending.resolve();
+          } else {
+            pending.reject(new Error(parsed.message ?? `${parsed.action} was not applied`));
+          }
+        }
+      }
       listeners.forEach((listener) => listener(parsed));
     };
     ws.onclose = (event) => {
@@ -318,18 +365,30 @@ var createVoiceConnection = (path, options = {}) => {
       state.isConnected = false;
       clearTimers();
       const reconnectable = shouldReconnect && event.code !== WS_NORMAL_CLOSURE && event.code !== WS_UNAUTHORIZED && event.code !== WS_FORBIDDEN && state.reconnectAttempts < maxReconnectAttempts;
+      const authorizationFailure = event.code === WS_UNAUTHORIZED || event.code === WS_FORBIDDEN;
+      if (authorizationFailure) {
+        listeners.forEach((listener) => listener({
+          message: event.code === WS_UNAUTHORIZED ? "Voice authorization expired or was rejected." : "Voice authorization was forbidden.",
+          recoverable: false,
+          type: "error"
+        }));
+      }
       if (reconnectable) {
         scheduleReconnect();
       } else if (shouldReconnect && event.code !== WS_NORMAL_CLOSURE) {
-        emitConnection({
-          reconnect: {
-            attempts: state.reconnectAttempts,
-            lastDisconnectAt: Date.now(),
-            maxAttempts: maxReconnectAttempts,
-            status: "exhausted"
-          },
-          type: "connection"
-        });
+        if (authorizationFailure) {
+          emitConnection({
+            reconnect: {
+              attempts: state.reconnectAttempts,
+              lastDisconnectAt: Date.now(),
+              maxAttempts: maxReconnectAttempts,
+              status: "exhausted"
+            },
+            type: "connection"
+          });
+        } else {
+          emitTerminalFailure("Voice connection could not be restored.");
+        }
       }
     };
     state.ws = ws;
@@ -339,6 +398,12 @@ var createVoiceConnection = (path, options = {}) => {
       state.ws.send(value);
       return;
     }
+    if (typeof value !== "string") {
+      return;
+    }
+    if (state.pendingMessages.length >= MAX_PENDING_CONTROL_MESSAGES) {
+      state.pendingMessages.shift();
+    }
     state.pendingMessages.push(value);
   };
   const send = (message) => {
@@ -364,13 +429,23 @@ var createVoiceConnection = (path, options = {}) => {
     send({ type: "end_turn" });
   };
   const callControl = (message) => {
+    const requestId = crypto.randomUUID();
+    const { promise, reject, resolve } = Promise.withResolvers();
+    const timeout = setTimeout(() => {
+      pendingCallControls.delete(requestId);
+      reject(new Error(`${message.action} acknowledgement timed out`));
+    }, DEFAULT_CALL_CONTROL_ACK_TIMEOUT_MS);
+    pendingCallControls.set(requestId, { reject, resolve, timeout });
     send({
       ...message,
+      requestId,
       type: "call_control"
     });
+    return promise;
   };
   const close = (reason = "client-close") => {
     clearTimers();
+    rejectPendingCallControls("Voice connection closed");
     if (state.ws) {
       const ws = state.ws;
       state.ws = null;
@@ -384,6 +459,7 @@ var createVoiceConnection = (path, options = {}) => {
   };
   const disconnect = () => {
     clearTimers();
+    rejectPendingCallControls("Voice connection disconnected");
     if (state.ws) {
       const ws = state.ws;
       state.ws = null;
@@ -1219,8 +1295,11 @@ var serverMessageToAction = (message) => {
     case "error":
       return {
         message: normalizeErrorMessage(message.message),
+        recoverable: message.recoverable,
         type: "error"
       };
+    case "call_control_ack":
+      return null;
     case "final":
       return {
         transcript: message.transcript,
@@ -1465,7 +1544,8 @@ var createVoiceStreamStore = () => {
       case "error":
         state = {
           ...state,
-          error: action.message
+          error: action.message,
+          ...action.recoverable === false ? { isConnected: false, status: "failed" } : {}
         };
         break;
       case "final":
@@ -1605,7 +1685,7 @@ var createVoiceStream = (path, options = {}) => {
       return store.getSnapshot().call;
     },
     callControl(message) {
-      connection.callControl(message);
+      return connection.callControl(message);
     },
     close(reason) {
       unsubscribeConnection();

package/dist/core/types.d.ts

@@ -1256,11 +1256,19 @@ export type VoiceClientCloseMessage = {
 };
 export type VoiceClientCallControlMessage = {
     type: "call_control";
+    requestId?: string;
     action: "complete" | "escalate" | "no-answer" | "pause" | "resume" | "transfer" | "voicemail";
     metadata?: Record<string, unknown>;
     reason?: string;
     target?: string;
 };
+export type VoiceServerCallControlAckMessage = {
+    type: "call_control_ack";
+    action: VoiceClientCallControlMessage["action"];
+    message?: string;
+    ok: boolean;
+    requestId: string;
+};
 export type VoiceClientPingMessage = {
     type: "ping";
 };
@@ -1333,7 +1341,7 @@ export type VoiceServerConnectionMessage = {
     type: "connection";
     reconnect: VoiceReconnectClientState;
 };
-export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerReplayMessage<TResult> | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerAssistantDeltaMessage | VoiceServerAudioMessage | VoiceServerCallLifecycleMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage | VoiceServerConnectionMessage;
+export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerReplayMessage<TResult> | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerAssistantDeltaMessage | VoiceServerAudioMessage | VoiceServerCallControlAckMessage | VoiceServerCallLifecycleMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage | VoiceServerConnectionMessage;
 export type VoiceConnectionOptions = {
     browserMedia?: false | VoiceBrowserMediaReporterOptions;
     protocols?: string[];
@@ -1351,6 +1359,15 @@ export type VoiceConnectionOptions = {
      *  reset. This prevents a server that accepts and immediately drops sockets
      *  from creating an unbounded reconnect loop. Default 30000. */
     reconnectResetAfterMs?: number;
+    /** Refresh application-owned admission state before each reconnect attempt.
+     *  Throwing keeps the transport disconnected and consumes one bounded retry
+     *  attempt instead of opening a socket with stale credentials. */
+    prepareReconnect?: (input: {
+        attempt: number;
+        path: string;
+        scenarioId: string | null;
+        sessionId: string;
+    }) => Promise<void> | void;
     pingInterval?: number;
     /** Additional query values sent on every initial or reconnecting socket. */
     query?: Record<string, string>;
@@ -1524,7 +1541,7 @@ export type VoiceStreamState<TResult = unknown> = {
 };
 export type VoiceStream<TResult = unknown> = {
     call: VoiceCallLifecycleState | null;
-    callControl: (message: Omit<VoiceClientCallControlMessage, "type">) => void;
+    callControl: (message: Omit<VoiceClientCallControlMessage, "requestId" | "type">) => Promise<void>;
     close: (reason?: string) => void;
     /** Release the transport without terminally completing the server session. */
     disconnect: () => void;
@@ -1621,7 +1638,7 @@ export type VoiceBargeInBinding = {
 export type VoiceController<TResult = unknown> = {
     bindHTMX: (options: VoiceHTMXBindingOptions) => () => void;
     call: VoiceCallLifecycleState | null;
-    callControl: (message: Omit<VoiceClientCallControlMessage, "type">) => void;
+    callControl: (message: Omit<VoiceClientCallControlMessage, "requestId" | "type">) => Promise<void>;
     close: (reason?: string) => void;
     /** Release the transport while leaving the server session resumable. */
     disconnect: () => void;
@@ -1717,6 +1734,7 @@ export type VoiceStoreAction<TResult = unknown> = {
 } | {
     type: "error";
     message: string;
+    recoverable?: boolean;
 } | {
     type: "connected";
 } | {

package/dist/embed/index.js

@@ -220,8 +220,11 @@ var serverMessageToAction = (message) => {
     case "error":
       return {
         message: normalizeErrorMessage(message.message),
+        recoverable: message.recoverable,
         type: "error"
       };
+    case "call_control_ack":
+      return null;
     case "final":
       return {
         transcript: message.transcript,
@@ -498,14 +501,17 @@ var WS_FORBIDDEN = 4403;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 15;
 var DEFAULT_PING_INTERVAL = 30000;
 var DEFAULT_RECONNECT_RESET_AFTER_MS = 30000;
+var DEFAULT_CALL_CONTROL_ACK_TIMEOUT_MS = 5000;
+var MAX_PENDING_CONTROL_MESSAGES = 100;
 var RECONNECT_BASE_DELAY_MS = 500;
 var DEFAULT_RECONNECT_MAX_DELAY_MS = 8000;
 var computeVoiceReconnectDelayMs = (attempt, baseMs, maxDelayMs) => Math.min(maxDelayMs, baseMs * 2 ** (Math.max(1, attempt) - 1));
 var DEFAULT_SCENARIO_QUERY_PARAM = "scenarioId";
 var noop = () => {};
+var noopAsync = () => Promise.resolve();
 var noopUnsubscribe = () => noop;
 var NOOP_CONNECTION = {
-  callControl: noop,
+  callControl: noopAsync,
   close: noop,
   disconnect: noop,
   endTurn: noop,
@@ -543,6 +549,7 @@ var isVoiceServerMessage = (value) => {
     case "audio":
     case "assistant":
     case "call_lifecycle":
+    case "call_control_ack":
     case "complete":
     case "connection":
     case "error":
@@ -573,6 +580,7 @@ var createVoiceConnection = (path, options = {}) => {
     return NOOP_CONNECTION;
   }
   const listeners = new Set;
+  const pendingCallControls = new Map;
   const shouldReconnect = options.reconnect !== false;
   const maxReconnectAttempts = options.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
   const reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? DEFAULT_RECONNECT_MAX_DELAY_MS;
@@ -593,6 +601,21 @@ var createVoiceConnection = (path, options = {}) => {
   const emitConnection = (reconnect) => {
     listeners.forEach((listener) => listener(reconnect));
   };
+  const emitTerminalFailure = (message) => {
+    listeners.forEach((listener) => listener({
+      message,
+      recoverable: false,
+      type: "error"
+    }));
+    emitConnection({
+      reconnect: {
+        attempts: state.reconnectAttempts,
+        maxAttempts: maxReconnectAttempts,
+        status: "exhausted"
+      },
+      type: "connection"
+    });
+  };
   const clearTimers = () => {
     if (state.pingInterval) {
       clearInterval(state.pingInterval);
@@ -618,6 +641,13 @@ var createVoiceConnection = (path, options = {}) => {
       }
     }
   };
+  const rejectPendingCallControls = (message) => {
+    for (const pending of pendingCallControls.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(message));
+    }
+    pendingCallControls.clear();
+  };
   const scheduleReconnect = () => {
     state.reconnectAttempts += 1;
     const delayMs = computeReconnectDelayMs(state.reconnectAttempts);
@@ -632,16 +662,24 @@ var createVoiceConnection = (path, options = {}) => {
       },
       type: "connection"
     });
-    state.reconnectTimeout = setTimeout(() => {
+    state.reconnectTimeout = setTimeout(async () => {
       if (state.reconnectAttempts > maxReconnectAttempts) {
-        emitConnection({
-          reconnect: {
-            attempts: state.reconnectAttempts,
-            maxAttempts: maxReconnectAttempts,
-            status: "exhausted"
-          },
-          type: "connection"
+        emitTerminalFailure("Voice connection could not be restored.");
+        return;
+      }
+      try {
+        await options.prepareReconnect?.({
+          attempt: state.reconnectAttempts,
+          path,
+          scenarioId: state.scenarioId,
+          sessionId: state.sessionId
         });
+      } catch {
+        if (state.reconnectAttempts < maxReconnectAttempts) {
+          scheduleReconnect();
+        } else {
+          emitTerminalFailure("Voice authorization could not be renewed for reconnect.");
+        }
         return;
       }
       connect();
@@ -698,6 +736,18 @@ var createVoiceConnection = (path, options = {}) => {
         state.sessionId = parsed.sessionId;
         state.scenarioId = parsed.scenarioId ?? state.scenarioId;
       }
+      if (parsed.type === "call_control_ack") {
+        const pending = pendingCallControls.get(parsed.requestId);
+        if (pending) {
+          clearTimeout(pending.timeout);
+          pendingCallControls.delete(parsed.requestId);
+          if (parsed.ok) {
+            pending.resolve();
+          } else {
+            pending.reject(new Error(parsed.message ?? `${parsed.action} was not applied`));
+          }
+        }
+      }
       listeners.forEach((listener) => listener(parsed));
     };
     ws.onclose = (event) => {
@@ -707,18 +757,30 @@ var createVoiceConnection = (path, options = {}) => {
       state.isConnected = false;
       clearTimers();
       const reconnectable = shouldReconnect && event.code !== WS_NORMAL_CLOSURE && event.code !== WS_UNAUTHORIZED && event.code !== WS_FORBIDDEN && state.reconnectAttempts < maxReconnectAttempts;
+      const authorizationFailure = event.code === WS_UNAUTHORIZED || event.code === WS_FORBIDDEN;
+      if (authorizationFailure) {
+        listeners.forEach((listener) => listener({
+          message: event.code === WS_UNAUTHORIZED ? "Voice authorization expired or was rejected." : "Voice authorization was forbidden.",
+          recoverable: false,
+          type: "error"
+        }));
+      }
       if (reconnectable) {
         scheduleReconnect();
       } else if (shouldReconnect && event.code !== WS_NORMAL_CLOSURE) {
-        emitConnection({
-          reconnect: {
-            attempts: state.reconnectAttempts,
-            lastDisconnectAt: Date.now(),
-            maxAttempts: maxReconnectAttempts,
-            status: "exhausted"
-          },
-          type: "connection"
-        });
+        if (authorizationFailure) {
+          emitConnection({
+            reconnect: {
+              attempts: state.reconnectAttempts,
+              lastDisconnectAt: Date.now(),
+              maxAttempts: maxReconnectAttempts,
+              status: "exhausted"
+            },
+            type: "connection"
+          });
+        } else {
+          emitTerminalFailure("Voice connection could not be restored.");
+        }
       }
     };
     state.ws = ws;
@@ -728,6 +790,12 @@ var createVoiceConnection = (path, options = {}) => {
       state.ws.send(value);
       return;
     }
+    if (typeof value !== "string") {
+      return;
+    }
+    if (state.pendingMessages.length >= MAX_PENDING_CONTROL_MESSAGES) {
+      state.pendingMessages.shift();
+    }
     state.pendingMessages.push(value);
   };
   const send = (message) => {
@@ -753,13 +821,23 @@ var createVoiceConnection = (path, options = {}) => {
     send({ type: "end_turn" });
   };
   const callControl = (message) => {
+    const requestId = crypto.randomUUID();
+    const { promise, reject, resolve } = Promise.withResolvers();
+    const timeout = setTimeout(() => {
+      pendingCallControls.delete(requestId);
+      reject(new Error(`${message.action} acknowledgement timed out`));
+    }, DEFAULT_CALL_CONTROL_ACK_TIMEOUT_MS);
+    pendingCallControls.set(requestId, { reject, resolve, timeout });
     send({
       ...message,
+      requestId,
       type: "call_control"
     });
+    return promise;
   };
   const close = (reason = "client-close") => {
     clearTimers();
+    rejectPendingCallControls("Voice connection closed");
     if (state.ws) {
       const ws = state.ws;
       state.ws = null;
@@ -773,6 +851,7 @@ var createVoiceConnection = (path, options = {}) => {
   };
   const disconnect = () => {
     clearTimers();
+    rejectPendingCallControls("Voice connection disconnected");
     if (state.ws) {
       const ws = state.ws;
       state.ws = null;
@@ -935,7 +1014,8 @@ var createVoiceStreamStore = () => {
       case "error":
         state = {
           ...state,
-          error: action.message
+          error: action.message,
+          ...action.recoverable === false ? { isConnected: false, status: "failed" } : {}
         };
         break;
       case "final":
@@ -1075,7 +1155,7 @@ var createVoiceStream = (path, options = {}) => {
       return store.getSnapshot().call;
     },
     callControl(message) {
-      connection.callControl(message);
+      return connection.callControl(message);
     },
     close(reason) {
       unsubscribeConnection();