VBLOCKS-2175 | Fix events docs (twilio#195)

* VBLOCKS-2175 | Fix events documentation

* Adding changelog

* Update call.ts

* Update device.ts

CHANGELOG.md

@@ -1,5 +1,17 @@
 :warning: **Important**: If you are upgrading to version 2.3.0 or later and have firewall rules or network configuration that blocks any unknown traffic by default, you need to update your configuration to allow connections to the new DNS names and IP addresses. Please refer to this [changelog](#230-january-23-2023) for more details.
 
+2.7.2 (In Progress)
+===================
+
+Changes
+-------
+
+- Added missing documentation for the following events:
+  - `call.on('ringing', handler)`
+  - `call.on('warning', handler)`
+  - `call.on('warning-cleared', handler)`
+  - `device.on('destroyed', handler)`
+
 2.7.1 (August 3, 2023)
 ======================
 

lib/twilio/call.ts

@@ -1595,6 +1595,29 @@ namespace Call {
    */
   declare function rejectEvent(): void;
 
+  /**
+   * Emitted when the {@link Call} has entered the `ringing` state.
+   * When using the Dial verb with `answerOnBridge=true`, the ringing state will begin when
+   * the callee has been notified of the call and will transition into open after the callee accepts the call,
+   * or closed if the call is rejected or cancelled.
+   * @param hasEarlyMedia - Denotes whether there is early media available from the callee.
+   * If `true`, the Client SDK will automatically play the early media. Sometimes this is ringing,
+   * other times it may be an important message about the call. If `false`, there is no remote media to play,
+   * so the application may want to play its own outgoing ringtone sound.
+   * @example `call.on('ringing', hasEarlyMedia => { })`
+   * @event
+   */
+  declare function ringingEvent(hasEarlyMedia: boolean): void;
+
+  /**
+   * Emitted when the {@link Call} gets a webrtc sample object.
+   * This event is published every second.
+   * @param sample
+   * @example `call.on('sample', sample => { })`
+   * @event
+   */
+  declare function sampleEvent(sample: RTCSample): void;
+
   /**
    * Emitted every 50ms with the current input and output volumes, as a percentage of maximum
    * volume, between -100dB and -30dB. Represented by a floating point number.
@@ -1606,13 +1629,32 @@ namespace Call {
   declare function volumeEvent(inputVolume: number, outputVolume: number): void;
 
   /**
-   * Emitted when the {@link Call} gets a webrtc sample object.
-   * This event is published every second.
-   * @param sample
-   * @example `call.on('sample', sample => { })`
+   * Emitted when the SDK detects a drop in call quality or other conditions that may indicate
+   * the user is having trouble with the call. You can implement callbacks on these events to
+   * alert the user of an issue.
+   *
+   * To alert the user that an issue has been resolved, you can listen for the `warning-cleared` event,
+   * which indicates that a call quality metric has returned to normal.
+   *
+   * For a full list of conditions that will raise a warning event, check the
+   * [Voice Insights SDK Events Reference](https://www.twilio.com/docs/voice/voice-insights/api/call/details-sdk-call-quality-events) page.
+   *
+   * @param name - The name of the warning
+   * @param data - An object containing data on the warning
+   * @example `call.on('warning', (name, data) => { })`
    * @event
    */
-  declare function sampleEvent(sample: RTCSample): void;
+  declare function warningEvent(name: string, data: any): void;
+
+  /**
+   * Emitted when a call quality metric has returned to normal.
+   * You can listen for this event to update the user when a call quality issue has been resolved.
+   *
+   * @param name - The name of the warning
+   * @example `call.on('warning-cleared', name => { })`
+   * @event
+   */
+  declare function warningClearedEvent(name: string): void;
 
   /**
    * Possible states of the {@link Call}.

lib/twilio/device.ts

@@ -1535,6 +1535,13 @@ class Device extends EventEmitter {
 }
 
 namespace Device {
+  /**
+   * Emitted when the {@link Device} has been destroyed.
+   * @example `device.on('destroyed', () => { })`
+   * @event
+   */
+  declare function destroyedEvent(): void;
+
   /**
    * Emitted when the {@link Device} receives an error.
    * @param error
@@ -1553,32 +1560,30 @@ namespace Device {
 
   /**
    * Emitted when the {@link Device} is unregistered.
-   * @param device
-   * @example `device.on('unregistered', device => { })`
+   * @example `device.on('unregistered', () => { })`
    * @event
    */
-  declare function unregisteredEvent(device: Device): void;
+  declare function unregisteredEvent(): void;
 
   /**
    * Emitted when the {@link Device} is registering.
-   * @param device
-   * @example `device.on('registering', device => { })`
+   * @example `device.on('registering', () => { })`
    * @event
    */
-  declare function registeringEvent(device: Device): void;
+  declare function registeringEvent(): void;
 
   /**
    * Emitted when the {@link Device} is registered.
-   * @param device
-   * @example `device.on('registered', device => { })`
+   * @example `device.on('registered', () => { })`
    * @event
    */
-  declare function registeredEvent(device: Device): void;
+  declare function registeredEvent(): void;
 
   /**
    * Emitted when the {@link Device}'s token is about to expire. Use DeviceOptions.refreshTokenMs
    * to set a custom warning time. Default is 10000 (10 seconds) prior to the token expiring.
-   * @example `device.on('tokenWillExpire', () => {
+   * @param device
+   * @example `device.on('tokenWillExpire', device => {
    *   const token = getNewTokenViaAjax();
    *   device.updateToken(token);
    * })`