@ipcom/asterisk-ari 0.0.140 → 0.0.142

package/README.md

@@ -58,6 +58,63 @@ client.on('ChannelDtmfReceived', event => {
 client.closeWebSocket();
 ```
 
+## Event Instances
+
+### Channel and Playback Instances in Events
+
+When working with WebSocket events, you get access to both the raw event data and convenient instance objects that allow direct interaction with the channel or playback:
+
+```typescript
+client.on('StasisStart', async event => {
+  // event.channel contains the raw channel data
+  console.log('New channel started:', event.channel.id);
+
+  // event.instanceChannel provides a ready-to-use ChannelInstance
+  const channelInstance = event.instanceChannel;
+  
+  // You can directly interact with the channel through the instance
+  await channelInstance.answer();
+  await channelInstance.play({ media: 'sound:welcome' });
+});
+
+// Similarly for playback events
+client.on('PlaybackStarted', async event => {
+  // event.playback contains the raw playback data
+  console.log('Playback ID:', event.playback.id);
+
+  // event.instancePlayback provides a ready-to-use PlaybackInstance
+  const playbackInstance = event.instancePlayback;
+  
+  // Direct control through the instance
+  await playbackInstance.control('pause');
+});
+```
+
+This approach provides two key benefits:
+1. No need to manually create instances using `client.Channel()` or `client.Playback()`
+2. Direct access to control methods without additional setup
+
+### Comparing Approaches
+
+Traditional approach:
+```typescript
+client.on('StasisStart', async event => {
+  // Need to create channel instance manually
+  const channel = client.Channel(event.channel.id);
+  await channel.answer();
+});
+```
+
+Using instance from event:
+```typescript
+client.on('StasisStart', async event => {
+  // Instance is already available
+  await event.instanceChannel.answer();
+});
+```
+
+This feature is particularly useful when handling multiple events and needing to perform actions on channels or playbacks immediately within event handlers.
+
 ### Channel Handling
 
 ```typescript

package/dist/cjs/index.cjs

@@ -1025,6 +1025,7 @@ var Bridges = class {
 
 // src/ari-client/resources/channels.ts
 var import_events = require("events");
+var import_axios2 = require("axios");
 
 // node_modules/uuid/dist/esm/stringify.js
 var byteToHex = [];
@@ -1079,7 +1080,6 @@ function toQueryParams2(options) {
 }
 
 // src/ari-client/resources/channels.ts
-var import_axios2 = require("axios");
 var getErrorMessage = (error) => {
   if ((0, import_axios2.isAxiosError)(error)) {
     return error.response?.data?.message || error.message || "An axios error occurred";
@@ -1127,7 +1127,9 @@ var ChannelInstance = class {
       }
     };
     this.eventEmitter.once(event, wrappedListener);
-    console.log(`One-time event listener registered for ${event} on channel ${this.id}`);
+    console.log(
+      `One-time event listener registered for ${event} on channel ${this.id}`
+    );
   }
   /**
    * Removes event listener(s) for a specific WebSocket event type.
@@ -1144,7 +1146,9 @@ var ChannelInstance = class {
     }
     if (listener) {
       this.eventEmitter.off(event, listener);
-      console.log(`Specific listener removed for ${event} on channel ${this.id}`);
+      console.log(
+        `Specific listener removed for ${event} on channel ${this.id}`
+      );
     } else {
       this.eventEmitter.removeAllListeners(event);
       console.log(`All listeners removed for ${event} on channel ${this.id}`);
@@ -1198,8 +1202,13 @@ var ChannelInstance = class {
       throw new Error("Channel has already been created");
     }
     try {
-      this.channelData = await this.baseClient.post("/channels", data);
-      console.log(`Channel originated successfully with ID: ${this.channelData.id}`);
+      this.channelData = await this.baseClient.post(
+        "/channels",
+        data
+      );
+      console.log(
+        `Channel originated successfully with ID: ${this.channelData.id}`
+      );
       return this.channelData;
     } catch (error) {
       const message = getErrorMessage(error);
@@ -1243,13 +1252,18 @@ var ChannelInstance = class {
       if (!this.id) {
         throw new Error("No channel ID associated with this instance");
       }
-      const details = await this.baseClient.get(`/channels/${this.id}`);
+      const details = await this.baseClient.get(
+        `/channels/${this.id}`
+      );
       this.channelData = details;
       console.log(`Retrieved channel details for ${this.id}`);
       return details;
     } catch (error) {
       const message = getErrorMessage(error);
-      console.error(`Error retrieving channel details for ${this.id}:`, message);
+      console.error(
+        `Error retrieving channel details for ${this.id}:`,
+        message
+      );
       throw new Error(`Failed to get channel details: ${message}`);
     }
   }
@@ -1458,10 +1472,23 @@ var Channels = class {
   }
   channelInstances = /* @__PURE__ */ new Map();
   /**
-   * Creates or retrieves a ChannelInstance based on the provided id.
+   * Creates or retrieves a ChannelInstance.
+   *
+   * @param {Object} [params] - Optional parameters for getting/creating a channel instance
+   * @param {string} [params.id] - Optional ID of an existing channel
+   * @returns {ChannelInstance} The requested or new channel instance
+   * @throws {Error} If channel creation/retrieval fails
+   *
+   * @example
+   * // Create new channel without ID
+   * const channel1 = client.channels.Channel();
+   *
+   * // Create/retrieve channel with specific ID
+   * const channel2 = client.channels.Channel({ id: 'some-id' });
    */
-  Channel({ id }) {
+  Channel(params) {
     try {
+      const id = params?.id;
       if (!id) {
         const instance = new ChannelInstance(this.client, this.baseClient);
         this.channelInstances.set(instance.id, instance);
@@ -1482,6 +1509,27 @@ var Channels = class {
       throw new Error(`Failed to manage channel instance: ${message}`);
     }
   }
+  /**
+   * Retrieves the details of a specific channel.
+   *
+   * @param {string} id - The unique identifier of the channel to retrieve.
+   * @returns {Promise<Channel>} A promise that resolves to the Channel object containing the channel details.
+   * @throws {Error} If no channel ID is associated with this instance or if there's an error retrieving the channel details.
+   */
+  async get(id) {
+    try {
+      if (id) {
+        throw new Error("No channel ID associated with this instance");
+      }
+      const details = await this.baseClient.get(`/channels/${id}`);
+      console.log(`Retrieved channel details for ${id}`);
+      return details;
+    } catch (error) {
+      const message = getErrorMessage(error);
+      console.error(`Error retrieving channel details for ${id}:`, message);
+      throw new Error(`Failed to get channel details: ${message}`);
+    }
+  }
   /**
    * Removes a channel instance from the collection.
    */
@@ -1510,7 +1558,9 @@ var Channels = class {
       const instance = this.channelInstances.get(event.channel.id);
       if (instance) {
         instance.emitEvent(event);
-        console.log(`Event propagated to channel ${event.channel.id}: ${event.type}`);
+        console.log(
+          `Event propagated to channel ${event.channel.id}: ${event.type}`
+        );
       } else {
         console.warn(`No instance found for channel ${event.channel.id}`);
       }
@@ -2017,7 +2067,9 @@ var PlaybackInstance = class {
       }
     };
     this.eventEmitter.on(event, wrappedListener);
-    console.log(`Event listener registered for ${event} on playback ${this.id}`);
+    console.log(
+      `Event listener registered for ${event} on playback ${this.id}`
+    );
   }
   /**
    * Registers a one-time event listener for a specific WebSocket event type.
@@ -2035,7 +2087,9 @@ var PlaybackInstance = class {
       }
     };
     this.eventEmitter.once(event, wrappedListener);
-    console.log(`One-time event listener registered for ${event} on playback ${this.id}`);
+    console.log(
+      `One-time event listener registered for ${event} on playback ${this.id}`
+    );
   }
   /**
    * Removes event listener(s) for a specific WebSocket event type.
@@ -2049,7 +2103,9 @@ var PlaybackInstance = class {
     }
     if (listener) {
       this.eventEmitter.off(event, listener);
-      console.log(`Specific listener removed for ${event} on playback ${this.id}`);
+      console.log(
+        `Specific listener removed for ${event} on playback ${this.id}`
+      );
     } else {
       this.eventEmitter.removeAllListeners(event);
       console.log(`All listeners removed for ${event} on playback ${this.id}`);
@@ -2106,7 +2162,9 @@ var PlaybackInstance = class {
       await this.baseClient.post(
         `/playbacks/${this.id}/control?operation=${operation}`
       );
-      console.log(`Operation ${operation} executed successfully on playback ${this.id}`);
+      console.log(
+        `Operation ${operation} executed successfully on playback ${this.id}`
+      );
     } catch (error) {
       const message = getErrorMessage2(error);
       console.error(`Error controlling playback ${this.id}:`, message);
@@ -2164,12 +2222,13 @@ var Playbacks = class {
   playbackInstances = /* @__PURE__ */ new Map();
   /**
    * Gets or creates a playback instance
-   * @param {Object} params - Parameters for getting/creating a playback instance
+   * @param {Object} [params] - Optional parameters for getting/creating a playback instance
    * @param {string} [params.id] - Optional ID of an existing playback
    * @returns {PlaybackInstance} The requested or new playback instance
    */
-  Playback({ id }) {
+  Playback(params) {
     try {
+      const id = params?.id;
       if (!id) {
         const instance = new PlaybackInstance(this.client, this.baseClient);
         this.playbackInstances.set(instance.id, instance);
@@ -2221,7 +2280,9 @@ var Playbacks = class {
       const instance = this.playbackInstances.get(event.playback.id);
       if (instance) {
         instance.emitEvent(event);
-        console.log(`Event propagated to playback ${event.playback.id}: ${event.type}`);
+        console.log(
+          `Event propagated to playback ${event.playback.id}: ${event.type}`
+        );
       } else {
         console.warn(`No instance found for playback ${event.playback.id}`);
       }