@ipcom/asterisk-ari 0.0.19 → 0.0.21

package/dist/esm/index.js

@@ -626,8 +626,8 @@ var Applications = class {
   }
   /**
    * Lists all applications.
-   *
-   * @returns A promise that resolves to an array of Application objects representing all registered applications.
+   * 
+   * @returns A promise that resolves to an array of Application objects.
    * @throws {Error} If the API response is not an array.
    */
   async list() {
@@ -639,19 +639,27 @@ var Applications = class {
   }
   /**
    * Retrieves details of a specific application.
-   *
-   * @param appName - The unique name of the application.
-   * @returns A promise that resolves to an ApplicationDetails object containing the details of the specified application.
+   * 
+   * @param appName - The name of the application to retrieve details for.
+   * @returns A promise that resolves to an ApplicationDetails object.
+   * @throws {Error} If there's an error fetching the application details.
    */
   async getDetails(appName) {
-    return this.client.get(`/applications/${appName}`);
+    try {
+      return await this.client.get(
+        `/applications/${appName}`
+      );
+    } catch (error) {
+      console.error(`Erro ao obter detalhes do aplicativo ${appName}:`, error);
+      throw error;
+    }
   }
   /**
    * Sends a message to a specific application.
-   *
-   * @param appName - The unique name of the application.
-   * @param body - The message body to send.
-   * @returns A promise that resolves when the message is sent successfully.
+   * 
+   * @param appName - The name of the application to send the message to.
+   * @param body - The message to be sent, containing an event and optional data.
+   * @returns A promise that resolves when the message is successfully sent.
    */
   async sendMessage(appName, body) {
     await this.client.post(`/applications/${appName}/messages`, body);
@@ -1188,13 +1196,17 @@ var WebSocketClient = class {
       throw new Error("WebSocket n\xE3o est\xE1 conectado.");
     }
     if (event === "message") {
-      this.ws.on(event, (data) => {
+      this.ws.on(event, (rawData) => {
         try {
-          const decodedData = JSON.parse(data.toString());
-          callback(decodedData);
+          const decodedData = JSON.parse(rawData.toString());
+          if (decodedData?.type) {
+            const matchedEvent = decodedData;
+            callback(matchedEvent);
+          } else {
+            console.warn("Mensagem sem tipo:", decodedData);
+          }
         } catch (err) {
           console.error("Erro ao decodificar mensagem do WebSocket:", err);
-          callback(data);
         }
       });
     } else {
@@ -1250,7 +1262,7 @@ var AriClient = class {
    * @param app - The application name to connect to.
    * @returns {Promise<void>} Resolves when the WebSocket connects successfully.
    */
-  async connectWebSocket(app) {
+  async connectWebSocket(app, subscribedEvents) {
     if (!app) {
       throw new Error(
         "The 'app' parameter is required to connect to the WebSocket."
@@ -1261,8 +1273,9 @@ var AriClient = class {
       return;
     }
     this.isReconnecting = true;
+    const eventsParam = subscribedEvents && subscribedEvents.length > 0 ? `&event=${subscribedEvents.join(",")}` : "&subscribeAll=true";
     const protocol = this.config.secure ? "wss" : "ws";
-    const wsUrl = `${protocol}://${encodeURIComponent(this.config.username)}:${encodeURIComponent(this.config.password)}@${this.config.host}:${this.config.port}/ari/events?app=${app}`;
+    const wsUrl = `${protocol}://${encodeURIComponent(this.config.username)}:${encodeURIComponent(this.config.password)}@${this.config.host}:${this.config.port}/ari/events?app=${app}${eventsParam}`;
     const backoffOptions = {
       delayFirstAttempt: false,
       startingDelay: 1e3,
@@ -1326,16 +1339,22 @@ var AriClient = class {
     return this.wsClient ? this.wsClient.isConnected() : false;
   }
   /**
-   * Registers a callback for a specific WebSocket event.
+   * Registers a callback function for WebSocket events.
+   * This method allows you to listen for and respond to WebSocket messages
+   * and process specific event types.
    *
-   * @param event - The WebSocket event to listen for.
-   * @param callback - The callback function to execute when the event occurs.
+   * @param callback - The callback function to execute when a WebSocket message is received.
+   *                   The function will receive the parsed event data as its parameter.
+   * @throws {Error} Throws an error if the WebSocket is not connected when trying to register the event.
+   * @returns {void}
    */
-  onWebSocketEvent(event, callback) {
+  onWebSocketEvent(callback) {
     if (!this.wsClient) {
       throw new Error("WebSocket is not connected.");
     }
-    this.wsClient.on(event, callback);
+    this.wsClient.on("message", (data) => {
+      callback(data);
+    });
   }
   /**
    * Closes the WebSocket connection.
@@ -1478,7 +1497,14 @@ var AriClient = class {
     return this.channels.snoopChannelWithId(channelId, snoopId, options);
   }
   /**
-   * Dials a created channel.
+   * Initiates a dial operation on a previously created channel.
+   * This function attempts to connect the specified channel to its configured destination.
+   *
+   * @param channelId - The unique identifier of the channel to dial.
+   * @param caller - Optional. The caller ID to use for the outgoing call. If not provided, the default caller ID for the channel will be used.
+   * @param timeout - Optional. The maximum time in seconds to wait for the dial operation to complete. If not specified, the system's default timeout will be used.
+   * @returns A Promise that resolves when the dial operation has been initiated successfully. Note that this does not guarantee that the call was answered, only that dialing has begun.
+   * @throws Will throw an error if the dial operation fails, e.g., if the channel doesn't exist or is in an invalid state.
    */
   async dialChannel(channelId, caller, timeout) {
     return this.channels.dial(channelId, caller, timeout);
@@ -1514,46 +1540,139 @@ var AriClient = class {
     return this.channels.ringChannel(channelId);
   }
   /**
-   * Stops ringing indication on a channel.
+   * Stops the ringing indication on a specified channel in the Asterisk system.
+   *
+   * This function sends a request to the Asterisk server to cease the ringing
+   * indication on a particular channel. This is typically used when you want to
+   * stop the ringing sound on a channel without answering or hanging up the call.
+   *
+   * @param channelId - The unique identifier of the channel on which to stop the ringing.
+   *                    This should be a string that uniquely identifies the channel in the Asterisk system.
+   *
+   * @returns A Promise that resolves when the ringing has been successfully stopped on the specified channel.
+   *          The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected with an error object.
    */
   async stopRingChannel(channelId) {
     return this.channels.stopRingChannel(channelId);
   }
   /**
-   * Sends DTMF to a channel.
+   * Sends DTMF (Dual-Tone Multi-Frequency) tones to a specified channel.
+   *
+   * This function allows sending DTMF tones to a channel, which can be used for various purposes
+   * such as interacting with IVR systems or sending signals during a call.
+   *
+   * @param channelId - The unique identifier of the channel to send DTMF tones to.
+   * @param dtmf - A string representing the DTMF tones to send (e.g., "123#").
+   * @param options - Optional parameters to control the timing of DTMF tones.
+   * @param options.before - The time (in milliseconds) to wait before sending DTMF.
+   * @param options.between - The time (in milliseconds) to wait between each DTMF tone.
+   * @param options.duration - The duration (in milliseconds) of each DTMF tone.
+   * @param options.after - The time (in milliseconds) to wait after sending all DTMF tones.
+   * @returns A Promise that resolves when the DTMF tones have been successfully sent.
    */
   async sendDTMF(channelId, dtmf, options) {
     return this.channels.sendDTMF(channelId, dtmf, options);
   }
   /**
-   * Mutes a channel.
+   * Mutes a channel in the Asterisk system.
+   *
+   * This function initiates a mute operation on the specified channel, preventing
+   * audio transmission in the specified direction(s).
+   *
+   * @param channelId - The unique identifier of the channel to be muted.
+   *                    This should be a string that uniquely identifies the channel in the Asterisk system.
+   * @param direction - The direction of audio to mute. Can be one of:
+   *                    - "both": Mute both incoming and outgoing audio (default)
+   *                    - "in": Mute only incoming audio
+   *                    - "out": Mute only outgoing audio
+   *
+   * @returns A Promise that resolves when the mute operation has been successfully completed.
+   *          The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected with an error object.
    */
   async muteChannel(channelId, direction = "both") {
     return this.channels.muteChannel(channelId, direction);
   }
   /**
-   * Unmutes a channel.
+   * Unmutes a channel in the Asterisk system.
+   *
+   * This function removes the mute status from a specified channel, allowing audio
+   * transmission to resume in the specified direction(s).
+   *
+   * @param channelId - The unique identifier of the channel to be unmuted.
+   *                    This should be a string that uniquely identifies the channel in the Asterisk system.
+   * @param direction - The direction of audio to unmute. Can be one of:
+   *                    - "both": Unmute both incoming and outgoing audio (default)
+   *                    - "in": Unmute only incoming audio
+   *                    - "out": Unmute only outgoing audio
+   *
+   * @returns A Promise that resolves when the unmute operation has been successfully completed.
+   *          The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected with an error object.
    */
   async unmuteChannel(channelId, direction = "both") {
     return this.channels.unmuteChannel(channelId, direction);
   }
   /**
-   * Puts a channel on hold.
+   * Puts a specified channel on hold.
+   *
+   * This function initiates a hold operation on the specified channel in the Asterisk system.
+   * When a channel is put on hold, typically the audio is muted or replaced with hold music,
+   * depending on the system configuration.
+   *
+   * @param channelId - The unique identifier of the channel to be put on hold.
+   *                    This should be a string that uniquely identifies the channel in the Asterisk system.
+   *
+   * @returns A Promise that resolves when the hold operation has been successfully initiated.
+   *          The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected with an error object.
    */
   async holdChannel(channelId) {
     return this.channels.holdChannel(channelId);
   }
   /**
-   * Removes a channel from hold.
+   * Removes a specified channel from hold.
+   *
+   * This function initiates an unhold operation on the specified channel in the Asterisk system.
+   * When a channel is taken off hold, it typically resumes normal audio transmission,
+   * allowing the parties to continue their conversation.
+   *
+   * @param channelId - The unique identifier of the channel to be taken off hold.
+   *                    This should be a string that uniquely identifies the channel in the Asterisk system.
+   *
+   * @returns A Promise that resolves when the unhold operation has been successfully initiated.
+   *          The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected with an error object.
    */
   async unholdChannel(channelId) {
     return this.channels.unholdChannel(channelId);
   }
   /**
-   * Creates a new channel using the provided originate request data.
+   * Creates a new channel in the Asterisk system using the provided originate request data.
+   * This function initiates a new communication channel based on the specified parameters.
    *
-   * @param data - The originate request data containing channel creation parameters.
-   * @returns A promise that resolves to the created Channel object.
+   * @param data - An object containing the originate request data for channel creation.
+   *               This includes details such as the endpoint to call, the context to use,
+   *               and any variables to set on the new channel.
+   * @param data.endpoint - The endpoint to call (e.g., "SIP/1234").
+   * @param data.extension - The extension to dial after the channel is created.
+   * @param data.context - The dialplan context to use for the new channel.
+   * @param data.priority - The priority to start at in the dialplan.
+   * @param data.app - The application to execute on the channel (alternative to extension/context/priority).
+   * @param data.appArgs - The arguments to pass to the application, if 'app' is specified.
+   * @param data.callerId - The caller ID to set on the new channel.
+   * @param data.timeout - The timeout (in seconds) to wait for the channel to be answered.
+   * @param data.variables - An object containing key-value pairs of channel variables to set.
+   * @param data.channelId - An optional ID to assign to the new channel.
+   * @param data.otherChannelId - The ID of another channel to bridge with after creation.
+   *
+   * @returns A Promise that resolves to the created Channel object.
+   *          The Channel object contains details about the newly created channel,
+   *          such as its unique identifier, state, and other relevant information.
+   *
+   * @throws Will throw an error if the channel creation fails for any reason,
+   *         such as invalid parameters or system issues.
    */
   async createChannel(data) {
     return this.channels.createChannel(data);
@@ -1649,68 +1768,85 @@ var AriClient = class {
     return this.playbacks.getDetails(playbackId);
   }
   /**
-   * Controls a specific playback.
+   * Controls a specific playback in the Asterisk server.
    *
-   * @param playbackId - The unique identifier of the playback.
-   * @param controlRequest - The PlaybackControlRequest containing the control operation.
-   * @returns {Promise<void>} A promise resolving when the control operation is successfully executed.
+   * @param playbackId - The unique identifier of the playback to control.
+   * @param controlRequest - An object containing the control operation details.
+   * @returns A Promise that resolves when the control operation is successfully executed.
    */
   async controlPlayback(playbackId, controlRequest) {
     return this.playbacks.control(playbackId, controlRequest);
   }
   /**
-   * Stops a specific playback.
+   * Stops a specific playback in the Asterisk server.
    *
-   * @param playbackId - The unique identifier of the playback.
-   * @returns {Promise<void>} A promise resolving when the playback is successfully stopped.
+   * @param playbackId - The unique identifier of the playback to stop.
+   * @returns A Promise that resolves when the playback is successfully stopped.
    */
   async stopPlayback(playbackId) {
     return this.playbacks.stop(playbackId);
   }
   /**
-   * Lists all available sounds.
+   * Retrieves a list of all available sounds in the Asterisk server.
    *
    * @param params - Optional parameters to filter the list of sounds.
-   * @returns {Promise<Sound[]>} A promise resolving to the list of sounds.
+   * @returns A Promise that resolves to an array of Sound objects representing the available sounds.
    */
   async listSounds(params) {
     return this.sounds.list(params);
   }
   /**
-   * Retrieves details of a specific sound.
+   * Retrieves detailed information about a specific sound in the Asterisk server.
    *
-   * @param soundId - The unique identifier of the sound.
-   * @returns {Promise<Sound>} A promise resolving to the sound details.
+   * @param soundId - The unique identifier of the sound to retrieve details for.
+   * @returns A Promise that resolves to a Sound object containing the details of the specified sound.
    */
   async getSoundDetails(soundId) {
     return this.sounds.getDetails(soundId);
   }
   /**
-   * Retrieves information about the Asterisk server.
+   * Retrieves general information about the Asterisk server.
+   *
+   * @returns A Promise that resolves to an AsteriskInfo object containing server information.
    */
   async getAsteriskInfo() {
     return this.asterisk.getInfo();
   }
   /**
-   * Lists all loaded modules in the Asterisk server.
+   * Retrieves a list of all loaded modules in the Asterisk server.
+   *
+   * @returns A Promise that resolves to an array of Module objects representing the loaded modules.
    */
   async listModules() {
     return this.asterisk.listModules();
   }
   /**
-   * Manages a specific module in the Asterisk server.
+   * Manages a specific module in the Asterisk server by loading, unloading, or reloading it.
+   *
+   * @param moduleName - The name of the module to manage.
+   * @param action - The action to perform on the module: "load", "unload", or "reload".
+   * @returns A Promise that resolves when the module management action is completed successfully.
    */
   async manageModule(moduleName, action) {
     return this.asterisk.manageModule(moduleName, action);
   }
   /**
-   * Retrieves all configured logging channels.
+   * Retrieves a list of all configured logging channels in the Asterisk server.
+   *
+   * @returns A Promise that resolves to an array of Logging objects representing the configured logging channels.
    */
   async listLoggingChannels() {
     return this.asterisk.listLoggingChannels();
   }
   /**
    * Adds or removes a log channel in the Asterisk server.
+   *
+   * @param logChannelName - The name of the log channel to manage.
+   * @param action - The action to perform: "add" to create a new log channel or "remove" to delete an existing one.
+   * @param configuration - Optional configuration object for adding a log channel. Ignored when removing a channel.
+   * @param configuration.type - The type of the log channel.
+   * @param configuration.configuration - Additional configuration details for the log channel.
+   * @returns A Promise that resolves when the log channel management action is completed successfully.
    */
   async manageLogChannel(logChannelName, action, configuration) {
     return this.asterisk.manageLogChannel(
@@ -1720,13 +1856,30 @@ var AriClient = class {
     );
   }
   /**
-   * Retrieves the value of a global variable.
+   * Retrieves the value of a global variable from the Asterisk server.
+   *
+   * @param variableName - The name of the global variable to retrieve.
+   * @returns A Promise that resolves to a Variable object containing the name and value of the global variable.
    */
   async getGlobalVariable(variableName) {
     return this.asterisk.getGlobalVariable(variableName);
   }
   /**
-   * Sets a global variable.
+   * Sets a global variable in the Asterisk server.
+   *
+   * This function allows you to set or update the value of a global variable
+   * in the Asterisk server. Global variables are accessible throughout the
+   * entire Asterisk system and can be used for various purposes such as
+   * configuration settings or sharing data between different parts of the system.
+   *
+   * @param variableName - The name of the global variable to set or update.
+   *                       This should be a string identifying the variable uniquely.
+   * @param value - The value to assign to the global variable. This can be any
+   *                string value, including empty strings.
+   * @returns A Promise that resolves when the global variable has been successfully
+   *          set. The promise resolves to void, indicating no specific return value.
+   *          If an error occurs during the operation, the promise will be rejected
+   *          with an error object.
    */
   async setGlobalVariable(variableName, value) {
     return this.asterisk.setGlobalVariable(variableName, value);
@@ -1735,6 +1888,7 @@ var AriClient = class {
 export {
   Applications,
   AriClient,
+  Asterisk,
   Channels,
   Endpoints,
   Playbacks,