@ipcom/asterisk-ari 0.0.145 → 0.0.146

package/dist/cjs/index.cjs

@@ -2340,12 +2340,17 @@ var DEFAULT_STARTING_DELAY = 500;
 var DEFAULT_MAX_DELAY = 1e4;
 var WebSocketClient = class extends import_events3.EventEmitter {
   /**
-   * Creates a new WebSocket client instance.
+   * Creates a new WebSocketClient instance.
    *
-   * @param {BaseClient} baseClient - The base client containing connection details
-   * @param {string[]} apps - List of applications to connect to
-   * @param {WebSocketEventType[]} [subscribedEvents] - Optional list of events to subscribe to
-   * @param {AriClient} [ariClient] - Optional ARI client for handling channel and playback events
+   * This constructor initializes a WebSocketClient with the necessary dependencies and configuration.
+   * It ensures that at least one application name is provided.
+   *
+   * @param baseClient - The BaseClient instance used for basic ARI operations and authentication.
+   * @param apps - An array of application names to connect to via the WebSocket.
+   * @param subscribedEvents - Optional. An array of WebSocketEventTypes to subscribe to. If not provided, all events will be subscribed.
+   * @param ariClient - Optional. The AriClient instance, used for creating Channel and Playback instances when processing events.
+   *
+   * @throws {Error} Throws an error if the apps array is empty.
    */
   constructor(baseClient, apps, subscribedEvents, ariClient) {
     super();
@@ -2360,6 +2365,8 @@ var WebSocketClient = class extends import_events3.EventEmitter {
   ws;
   isReconnecting = false;
   maxReconnectAttempts = DEFAULT_MAX_RECONNECT_ATTEMPTS;
+  reconnectionAttempts = 0;
+  lastWsUrl = "";
   backOffOptions = {
     numOfAttempts: DEFAULT_MAX_RECONNECT_ATTEMPTS,
     startingDelay: DEFAULT_STARTING_DELAY,
@@ -2376,10 +2383,14 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     }
   };
   /**
-   * Establishes a WebSocket connection.
+   * Establishes a WebSocket connection to the Asterisk server.
    *
-   * @returns {Promise<void>} Resolves when connection is established
-   * @throws {Error} If connection fails
+   * This method constructs the WebSocket URL using the base URL, credentials,
+   * application names, and subscribed events. It then initiates the connection
+   * using the constructed URL.
+   *
+   * @returns A Promise that resolves when the WebSocket connection is successfully established.
+   * @throws Will throw an error if the connection cannot be established.
    */
   async connect() {
     const { baseUrl, username, password } = this.baseClient.getCredentials();
@@ -2394,15 +2405,24 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     } else {
       queryParams.append("subscribeAll", "true");
     }
-    const wsUrl = `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${normalizedHost}/ari/events?${queryParams.toString()}`;
+    this.lastWsUrl = `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${normalizedHost}/ari/events?${queryParams.toString()}`;
     console.log("Connecting to WebSocket...");
-    return this.initializeWebSocket(wsUrl);
+    return this.initializeWebSocket(this.lastWsUrl);
   }
   /**
-   * Initializes WebSocket connection with reconnection logic.
+   * Initializes a WebSocket connection with exponential backoff retry mechanism.
    *
-   * @param {string} wsUrl - The WebSocket URL to connect to
-   * @returns {Promise<void>} Resolves when connection is established
+   * This method attempts to establish a WebSocket connection to the specified URL.
+   * It sets up event listeners for the WebSocket's 'open', 'message', 'close', and 'error' events.
+   * If the connection is successful, it emits a 'connected' event. If it's a reconnection,
+   * it also emits a 'reconnected' event with the current apps and subscribed events.
+   * In case of connection failure, it uses an exponential backoff strategy to retry.
+   *
+   * @param wsUrl - The WebSocket URL to connect to.
+   * @returns A Promise that resolves when the connection is successfully established,
+   *          or rejects if an error occurs during the connection process.
+   * @throws Will throw an error if the WebSocket connection cannot be established
+   *         after the maximum number of retry attempts.
    */
   async initializeWebSocket(wsUrl) {
     return (0, import_exponential_backoff.backOff)(async () => {
@@ -2411,7 +2431,14 @@ var WebSocketClient = class extends import_events3.EventEmitter {
           this.ws = new import_ws.default(wsUrl);
           this.ws.on("open", () => {
             console.log("WebSocket connection established successfully");
+            if (this.isReconnecting) {
+              this.emit("reconnected", {
+                apps: this.apps,
+                subscribedEvents: this.subscribedEvents
+              });
+            }
             this.isReconnecting = false;
+            this.reconnectionAttempts = 0;
             this.emit("connected");
             resolve();
           });
@@ -2421,13 +2448,13 @@ var WebSocketClient = class extends import_events3.EventEmitter {
               `WebSocket disconnected with code ${code}. Attempting to reconnect...`
             );
             if (!this.isReconnecting) {
-              this.reconnect(wsUrl);
+              this.reconnect(this.lastWsUrl);
             }
           });
           this.ws.on("error", (err) => {
             console.error("WebSocket error:", err.message);
             if (!this.isReconnecting) {
-              this.reconnect(wsUrl);
+              this.reconnect(this.lastWsUrl);
             }
             reject(err);
           });
@@ -2438,9 +2465,16 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     }, this.backOffOptions);
   }
   /**
-   * Processes incoming WebSocket messages.
+   * Handles incoming WebSocket messages by parsing and processing events.
+   *
+   * This method parses the raw message into a WebSocketEvent, filters it based on
+   * subscribed events (if any), processes channel and playback events, and emits
+   * the event to listeners. It also handles any errors that occur during processing.
    *
-   * @param {string} rawMessage - The raw message received from WebSocket
+   * @param rawMessage - The raw message string received from the WebSocket connection.
+   * @returns void This method doesn't return a value but emits events.
+   *
+   * @throws Will emit an 'error' event if the message cannot be parsed or processed.
    */
   handleMessage(rawMessage) {
     try {
@@ -2468,18 +2502,27 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     }
   }
   /**
-   * Attempts to reconnect to the WebSocket.
+   * Attempts to reconnect to the WebSocket server using an exponential backoff strategy.
+   *
+   * This method is called when the WebSocket connection is closed unexpectedly.
+   * It increments the reconnection attempt counter, logs the attempt, and uses
+   * the backOff utility to retry the connection with exponential delays between attempts.
    *
-   * @param {string} wsUrl - The WebSocket URL to reconnect to
+   * @param wsUrl - The WebSocket URL to reconnect to.
+   * @returns void - This method doesn't return a value.
+   *
+   * @emits reconnectFailed - Emitted if all reconnection attempts fail.
    */
   reconnect(wsUrl) {
     this.isReconnecting = true;
-    console.log("Initiating reconnection attempt...");
-    this.removeAllListeners();
+    this.reconnectionAttempts++;
+    console.log(
+      `Initiating reconnection attempt #${this.reconnectionAttempts}...`
+    );
     (0, import_exponential_backoff.backOff)(() => this.initializeWebSocket(wsUrl), this.backOffOptions).catch(
       (error) => {
         console.error(
-          "Failed to reconnect after multiple attempts:",
+          `Failed to reconnect after ${this.reconnectionAttempts} attempts:`,
           error instanceof Error ? error.message : "Unknown error"
         );
         this.emit("reconnectFailed", error);
@@ -2487,7 +2530,13 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     );
   }
   /**
-   * Manually closes the WebSocket connection.
+   * Closes the WebSocket connection if it exists.
+   *
+   * This method attempts to gracefully close the WebSocket connection
+   * and sets the WebSocket instance to undefined. If an error occurs
+   * during the closing process, it will be caught and logged.
+   *
+   * @throws {Error} Logs an error message if closing the WebSocket fails.
    */
   close() {
     try {
@@ -2504,17 +2553,30 @@ var WebSocketClient = class extends import_events3.EventEmitter {
     }
   }
   /**
-   * Checks if the WebSocket is currently connected.
+   * Checks if the WebSocket connection is currently open and active.
    *
-   * @returns {boolean} True if connected, false otherwise
+   * This method examines the readyState of the WebSocket instance to determine
+   * if the connection is established and ready for communication.
+   *
+   * @returns {boolean} True if the WebSocket connection is open and ready,
+   *                    false otherwise.
    */
   isConnected() {
     return this.ws?.readyState === import_ws.default.OPEN;
   }
   /**
-   * Gets the current connection state.
+   * Retrieves the current state of the WebSocket connection.
+   *
+   * This method returns the readyState of the WebSocket instance, which
+   * indicates the current state of the connection. If no WebSocket instance
+   * exists, it returns the CLOSED state.
    *
-   * @returns {number} The WebSocket ready state
+   * @returns {number} The current state of the WebSocket connection.
+   *                   Possible values are:
+   *                   - WebSocket.CONNECTING (0): The connection is not yet open.
+   *                   - WebSocket.OPEN (1): The connection is open and ready to communicate.
+   *                   - WebSocket.CLOSING (2): The connection is in the process of closing.
+   *                   - WebSocket.CLOSED (3): The connection is closed or couldn't be opened.
    */
   getState() {
     return this.ws?.readyState ?? import_ws.default.CLOSED;