voice-react-native-sdk 1.6.2-fork.4

package/src/Call.tsx

@@ -0,0 +1,1343 @@
+/**
+ * Copyright © 2022 Twilio, Inc. All rights reserved. Licensed under the Twilio
+ * license.
+ *
+ * See LICENSE in the project root for license information.
+ */
+
+import { EventEmitter } from 'eventemitter3';
+import type { RTCStats } from './';
+import { NativeModule, NativeEventEmitter } from './common';
+import { Constants } from './constants';
+import type {
+  NativeCallEvent,
+  NativeCallEventType,
+  NativeCallInfo,
+  NativeCallFeedbackIssue,
+  NativeCallFeedbackScore,
+} from './type/Call';
+import type { CustomParameters, Uuid } from './type/common';
+import type { TwilioError } from './error/TwilioError';
+import { InvalidArgumentError } from './error/InvalidArgumentError';
+import { constructTwilioError } from './error/utility';
+import { CallMessage, validateCallMessage } from './CallMessage/CallMessage';
+import { IncomingCallMessage } from './CallMessage/IncomingCallMessage';
+import { OutgoingCallMessage } from './CallMessage/OutgoingCallMessage';
+
+/**
+ * Defines strict typings for all events emitted by {@link (Call:class)
+ * | Call objects}.
+ *
+ * @remarks
+ * Note that the `on` function is an alias for the `addListener` function.
+ * They share identical functionality and either may be used interchangeably.
+ *
+ * - See also the {@link (Call:class) | Call class}.
+ * - See also the {@link (Call:namespace) | Call namespace}.
+ *
+ * @public
+ */
+export declare interface Call {
+  /**
+   * ------------
+   * Emit Typings
+   * ------------
+   */
+
+  /** @internal */
+  emit(connectedEvent: Call.Event.Connected): boolean;
+
+  /** @internal */
+  emit(
+    connectFailureEvent: Call.Event.ConnectFailure,
+    error: TwilioError
+  ): boolean;
+
+  /** @internal */
+  emit(reconnectingEvent: Call.Event.Reconnecting, error: TwilioError): boolean;
+
+  /** @internal */
+  emit(reconnectedEvent: Call.Event.Reconnected): boolean;
+
+  /** @internal */
+  emit(
+    disconnectedEvent: Call.Event.Disconnected,
+    error?: TwilioError
+  ): boolean;
+
+  /** @internal */
+  emit(ringingEvent: Call.Event.Ringing): boolean;
+
+  /** @internal */
+  emit(
+    qualityWarningsChangedEvent: Call.Event.QualityWarningsChanged,
+    currentQualityWarnings: Call.QualityWarning[],
+    previousQualityWarnings: Call.QualityWarning[]
+  ): boolean;
+
+  /** @internal */
+  emit(
+    messageReceivedEvent: Call.Event.MessageReceived,
+    incomingCallMessage: IncomingCallMessage
+  ): boolean;
+
+  /**
+   * ----------------
+   * Listener Typings
+   * ----------------
+   */
+
+  /**
+   * Connected event. Raised when the call has successfully connected.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.Connected, () => {
+   *   // call has been connected
+   * });
+   * ```
+   *
+   * @param connectedEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    connectedEvent: Call.Event.Connected,
+    listener: Call.Listener.Connected
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:1)}
+   */
+  on(
+    connectedEvent: Call.Event.Connected,
+    listener: Call.Listener.Connected
+  ): this;
+
+  /**
+   * Connect failure event. Raised when the call has failed to connect.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.ConnectFailure, (error) => {
+   *   // call was unable to connect, handle error
+   * });
+   * ```
+   *
+   * @param connectFailureEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    connectFailureEvent: Call.Event.ConnectFailure,
+    listener: Call.Listener.ConnectFailure
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:2)}
+   */
+  on(
+    connectFailureEvent: Call.Event.ConnectFailure,
+    listener: Call.Listener.ConnectFailure
+  ): this;
+
+  /**
+   * Reconnecting event. Raised when the call is reconnecting.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.Reconnecting, (error) => {
+   *   // call is attempting to reconnect, handle error
+   * });
+   * ```
+   *
+   * @param reconnectingEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    reconnectingEvent: Call.Event.Reconnecting,
+    listener: Call.Listener.Reconnecting
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:3)}
+   */
+  on(
+    reconnectingEvent: Call.Event.Reconnecting,
+    listener: Call.Listener.Reconnecting
+  ): this;
+
+  /**
+   * Reconnected event. Raised when the call has recovered and reconnected.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.Reconnected, () => {
+   *   // call has reconnected
+   * });
+   * ```
+   *
+   * @param reconnectedEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    reconnectedEvent: Call.Event.Reconnected,
+    listener: Call.Listener.Reconnected
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:4)}
+   */
+  on(
+    reconnectedEvent: Call.Event.Reconnected,
+    listener: Call.Listener.Reconnected
+  ): this;
+
+  /**
+   * Disconnected event. Raised when the call has disconnected.
+   *
+   * @remarks
+   * This event can occur in "naturally" disconnected calls and calls
+   * disconnected from issues such as network problems. If the SDK has detected
+   * an issue that has caused the call to disconnect, then the error parameter
+   * will be defined, otherwise it will be undefined.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.Disconnected, (error) => {
+   *   // call has disconnected
+   *   // if a natural disconnect occurred, then error is `undefined`
+   *   // if an unnatural disconnect occurred, then error is defined
+   * });
+   * ```
+   *
+   * @param disconnectedEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    disconnectedEvent: Call.Event.Disconnected,
+    listener: Call.Listener.Disconnected
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:5)}
+   */
+  on(
+    disconnectedEvent: Call.Event.Disconnected,
+    listener: Call.Listener.Disconnected
+  ): this;
+
+  /**
+   * Ringing event. Raised when the call has begun to ring.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.Ringing, () => {
+   *   // call is ringing
+   * });
+   * ```
+   *
+   * @param ringingEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    ringingEvent: Call.Event.Ringing,
+    listener: Call.Listener.Ringing
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:6)}
+   */
+  on(ringingEvent: Call.Event.Ringing, listener: Call.Listener.Ringing): this;
+
+  /**
+   * Quality warnings changed event. Raised when a call quality warning is set
+   * or unset. All "ongoing" call quality warnings are passed to the invoked
+   * listener function.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(
+   *   Call.Event.QualityWarningsChanged,
+   *   (
+   *      currentWarnings: Call.QualityWarning[],
+   *      previousWarnings: Call.QualityWarning[]
+   *   ) => {
+   *     // call quality warnings have changed
+   *   }
+   * );
+   * ```
+   *
+   * @param qualityWarningsChangedEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(
+    qualityWarningsChangedEvent: Call.Event.QualityWarningsChanged,
+    listener: Call.Listener.QualityWarningsChanged
+  ): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:7)}
+   */
+  on(
+    qualityWarningsChangedEvent: Call.Event.QualityWarningsChanged,
+    listener: Call.Listener.QualityWarningsChanged
+  ): this;
+
+  /**
+   * MessageReceived event. Raised when a {@link IncomingCallMessage} is
+   * received.
+   *
+   * @example
+   * ```typescript
+   * call.addListener(Call.Event.MessageReceived, (message) => {
+   *    // callMessage received
+   * })
+   * ```
+   *
+   * @param messageReceivedEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The callMessage object
+   */
+  addListener(
+    messageReceivedEvent: Call.Event.MessageReceived,
+    listener: Call.Listener.MessageReceived
+  ): this;
+  /** {@inheritDoc (Call:interface).(addListener:8)} */
+  on(
+    callMessageEvent: Call.Event.MessageReceived,
+    listener: Call.Listener.MessageReceived
+  ): this;
+
+  /**
+   * Generic event listener typings.
+   * @param callEvent - The raised event string.
+   * @param listener - A listener function that will be invoked when the event
+   * is raised.
+   * @returns - The call object.
+   */
+  addListener(callEvent: Call.Event, listener: Call.Listener.Generic): this;
+  /**
+   * {@inheritDoc (Call:interface).(addListener:9)}
+   */
+  on(callEvent: Call.Event, listener: Call.Listener.Generic): this;
+}
+
+/**
+ * Provides access to information about a call, including the call parameters,
+ * and exposes functionality for a call such as disconnecting, muting, and
+ * holding.
+ *
+ * @remarks
+ * Note that the call information is fetched as soon as possible from the native
+ * layer, but there is no guarantee that all information is immediately
+ * available. Methods such as `Call.getFrom()` or `Call.getTo()` may return
+ * `undefined`.
+ *
+ * As call events are received from the native layer, call information will
+ * propagate from the native layer to the JS layer and become available.
+ * Therefore, it is good practice to read information from the call after an
+ * event occurs, or as events occur.
+ *
+ *  - See the {@link (Call:namespace).Event} enum for events emitted by `Call`
+ *    objects.
+ *  - See the {@link (Call:interface) | Call interface} for overloaded event
+ *    listening methods.
+ *  - See the {@link (Call:namespace) | Call namespace} for types and
+ *    enumerations used by this class.
+ *
+ * @public
+ */
+export class Call extends EventEmitter {
+  /**
+   * The `Uuid` of this call. Used to identify calls between the JS and native
+   * layer so we can associate events and native functionality between the
+   * layers.
+   */
+  private _uuid: Uuid;
+  /**
+   * Call custom parameters.
+   */
+  private _customParameters: CustomParameters;
+  /**
+   * Call `from` parameter.
+   */
+  private _from?: string;
+  /**
+   * Initial `connected` timestamp. Milliseconds since epoch.
+   */
+  private _initialConnectedTimestamp?: Date;
+  /**
+   * A boolean representing if the call is currently muted.
+   */
+  private _isMuted?: boolean;
+  /**
+   * A boolean representing if the call is currently on hold.
+   */
+  private _isOnHold?: boolean;
+  /**
+   * A string representing the SID of this call.
+   */
+  private _sid?: string;
+  /**
+   * The current state of the call.
+   *
+   * @remarks
+   * See {@link (Call:namespace).State}.
+   */
+  private _state: Call.State;
+  /**
+   * Call `to` parameter.
+   */
+  private _to?: string;
+
+  /**
+   * Handlers for native call events. Set upon construction so we can
+   * dynamically bind events to handlers.
+   *
+   * @privateRemarks
+   * This is done by the constructor so this mapping isn't made every time the
+   * {@link (Call:class)._handleNativeEvent} function is invoked.
+   */
+  private _nativeEventHandler: Record<
+    NativeCallEventType,
+    (callEvent: NativeCallEvent) => void
+  >;
+
+  /**
+   * Constructor for the {@link (Call:class) | Call class}. This should not be
+   * invoked by third-party code. All instances of the
+   * {@link (Call:class) | Call class} should be made by the SDK and emitted by
+   * {@link (Voice:class) | Voice objects}.
+   *
+   * @param nativeCallInfo - An object containing all of the data from the
+   * native layer necessary to fully describe a call, as well as invoke native
+   * functionality for the call.
+   *
+   * @internal
+   */
+  constructor({
+    uuid,
+    customParameters,
+    from,
+    sid,
+    state,
+    to,
+    isMuted,
+    isOnHold,
+    initialConnectedTimestamp,
+  }: NativeCallInfo) {
+    super();
+
+    this._uuid = uuid;
+    this._customParameters = { ...customParameters };
+    this._from = from;
+    this._sid = sid;
+    this._state = typeof state === 'string' ? state : Call.State.Connecting;
+    this._to = to;
+    this._isMuted = isMuted;
+    this._isOnHold = isOnHold;
+    this._initialConnectedTimestamp = initialConnectedTimestamp
+      ? new Date(initialConnectedTimestamp)
+      : undefined;
+
+    this._nativeEventHandler = {
+      /**
+       * Call State
+       */
+      [Constants.CallEventConnected]: this._handleConnectedEvent,
+      [Constants.CallEventConnectFailure]: this._handleConnectFailureEvent,
+      [Constants.CallEventDisconnected]: this._handleDisconnectedEvent,
+      [Constants.CallEventReconnected]: this._handleReconnectedEvent,
+      [Constants.CallEventReconnecting]: this._handleReconnectingEvent,
+      [Constants.CallEventRinging]: this._handleRingingEvent,
+
+      /**
+       * Call Quality
+       */
+      [Constants.CallEventQualityWarningsChanged]:
+        this._handleQualityWarningsChangedEvent,
+
+      /**
+       * Call Message
+       */
+      [Constants.CallEventMessageReceived]: this._handleMessageReceivedEvent,
+    };
+
+    NativeEventEmitter.addListener(
+      Constants.ScopeCall,
+      this._handleNativeEvent
+    );
+  }
+
+  /**
+   * This intermediate native call event handler acts as a "gate", only
+   * executing the actual call event handler (such as `Connected`) if this call
+   * object matches the `Uuid` of the call that had an event raised.
+   * @param nativeCallEvent - A call event directly from the native layer.
+   */
+  private _handleNativeEvent = (nativeCallEvent: NativeCallEvent) => {
+    const { type, call: callInfo } = nativeCallEvent;
+
+    const handler = this._nativeEventHandler[type];
+    if (typeof handler === 'undefined') {
+      throw new Error(
+        `Unknown call event type received from the native layer: "${type}".`
+      );
+    }
+
+    if (callInfo.uuid === this._uuid) {
+      handler(nativeCallEvent);
+    }
+  };
+
+  /**
+   * Helper function to update the state of the call when a call event occurs
+   * that necessitates an update, i.e. upon a
+   * {@link (Call:namespace).Event.Connected | Connected event} we want to
+   * update the state of the call to also reflect the
+   * {@link (Call:namespace).State.Connected | Connected state}.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _update({
+    type,
+    call: { from, initialConnectedTimestamp, sid, to },
+  }: NativeCallEvent) {
+    const newState = eventTypeStateMap[type];
+    if (typeof newState === 'string') {
+      this._state = newState;
+    }
+    this._from = from;
+    this._initialConnectedTimestamp = initialConnectedTimestamp
+      ? new Date(initialConnectedTimestamp)
+      : undefined;
+    this._sid = sid;
+    this._to = to;
+  }
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.Connected} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleConnectedEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventConnected) {
+      throw new Error(
+        'Incorrect "call#connected" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    this.emit(Call.Event.Connected);
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.ConnectFailure} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleConnectFailureEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventConnectFailure) {
+      throw new Error(
+        'Incorrect "call#connectFailure" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    const { message, code } = nativeCallEvent.error;
+    const error = constructTwilioError(message, code);
+    this.emit(Call.Event.ConnectFailure, error);
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.Disconnected} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleDisconnectedEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventDisconnected) {
+      throw new Error(
+        'Incorrect "call#disconnected" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    if (nativeCallEvent.error) {
+      const { message, code } = nativeCallEvent.error;
+      const error = constructTwilioError(message, code);
+      this.emit(Call.Event.Disconnected, error);
+    } else {
+      this.emit(Call.Event.Disconnected);
+    }
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.Reconnecting} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleReconnectingEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventReconnecting) {
+      throw new Error(
+        'Incorrect "call#reconnecting" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    const { message, code } = nativeCallEvent.error;
+    const error = constructTwilioError(message, code);
+    this.emit(Call.Event.Reconnecting, error);
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.Reconnected} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleReconnectedEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventReconnected) {
+      throw new Error(
+        'Incorrect "call#reconnected" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    this.emit(Call.Event.Reconnected);
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.Ringing} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleRingingEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventRinging) {
+      throw new Error(
+        'Incorrect "call#ringing" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    this.emit(Call.Event.Ringing);
+  };
+
+  /**
+   * Handler for the the {@link (Call:namespace).Event.QualityWarningsChanged}
+   * event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleQualityWarningsChangedEvent = (
+    nativeCallEvent: NativeCallEvent
+  ) => {
+    if (nativeCallEvent.type !== Constants.CallEventQualityWarningsChanged) {
+      throw new Error(
+        'Incorrect "call#qualityWarnings" handler called for type ' +
+          `"${nativeCallEvent.type}".`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    const currentWarnings = nativeCallEvent[Constants.CallEventCurrentWarnings];
+    const previousWarnings =
+      nativeCallEvent[Constants.CallEventPreviousWarnings];
+
+    this.emit(
+      Call.Event.QualityWarningsChanged,
+      currentWarnings as Call.QualityWarning[],
+      previousWarnings as Call.QualityWarning[]
+    );
+  };
+
+  /**
+   * Handler for the {@link (Call:namespace).Event.MessageReceived} event.
+   * @param nativeCallEvent - The native call event.
+   */
+  private _handleMessageReceivedEvent = (nativeCallEvent: NativeCallEvent) => {
+    if (nativeCallEvent.type !== Constants.CallEventMessageReceived) {
+      throw new Error(
+        'Incorrect "call#Received" handler called for type' +
+          `"${nativeCallEvent.type}`
+      );
+    }
+
+    this._update(nativeCallEvent);
+
+    const { callMessage: callMessageInfo } = nativeCallEvent;
+
+    const incomingCallMessage = new IncomingCallMessage(callMessageInfo);
+
+    this.emit(Call.Event.MessageReceived, incomingCallMessage);
+  };
+
+  /**
+   * Disconnect this side of the call.
+   * @returns
+   *  A `Promise` that
+   *    - Resolves when the call has disconnected.
+   *    - Rejects if the native layer cannot disconnect the call.
+   */
+  disconnect(): Promise<void> {
+    return NativeModule.call_disconnect(this._uuid);
+  }
+
+  /**
+   * Get the mute status of this side of the call.
+   * @returns
+   *  - A boolean representing the muted status of the call.
+   *  - `undefined` if the call state has not yet been received from the native
+   *    layer.
+   */
+  isMuted(): boolean | undefined {
+    return this._isMuted;
+  }
+
+  /**
+   * Get the hold status of this side of the call.
+   * @returns
+   *  - A boolean representing the hold status of the call.
+   *  - `undefined` if the call state has not yet been received from the native
+   *    layer.
+   */
+  isOnHold(): boolean | undefined {
+    return this._isOnHold;
+  }
+
+  /**
+   * Return a `Record` of custom parameters given to this call.
+   * @returns
+   *   - A `Record` of custom parameters.
+   */
+  getCustomParameters(): CustomParameters {
+    return this._customParameters;
+  }
+
+  /**
+   * Get the value of the `from` parameter given to this call.
+   * @returns
+   *  - A `String` representing the `from` parameter.
+   *  - `undefined` if the call information has not yet been received from the
+   *    native layer.
+   */
+  getFrom(): string | undefined {
+    return this._from;
+  }
+
+  /**
+   * Get the timestamp (milliseconds since epoch) of the call connected event.
+   * @returns
+   *  - A `number` representing the timestamp.
+   *  - `undefined` if the call has not yet connected.
+   */
+  getInitialConnectedTimestamp(): Date | undefined {
+    return this._initialConnectedTimestamp;
+  }
+
+  /**
+   * Get the call `SID`.
+   * @returns
+   *  - A `String` representing the `SID` of the call.
+   *  - `undefined` if the call information has not yet been received from the
+   *    native layer.
+   */
+  getSid(): string | undefined {
+    return this._sid;
+  }
+
+  /**
+   * Get the state of the call object, such as {@link (Call:namespace).State.Connected} or
+   * {@link (Call:namespace).State.Disconnected}.
+   * @returns
+   *  - A {@link (Call:namespace).State}.
+   */
+  getState(): Call.State {
+    return this._state;
+  }
+
+  /**
+   * Gets the `PeerConnection` `WebRTC` stats for the ongoing call.
+   * @returns
+   *  A `Promise` that
+   *    - Resolves with a {@link RTCStats.StatsReport} object representing the
+   *      `WebRTC` `PeerConnection` stats of a call.
+   *    - Rejects when a {@link RTCStats.StatsReport} cannot be generated for a
+   *      call.
+   */
+  getStats(): Promise<RTCStats.StatsReport> {
+    return NativeModule.call_getStats(this._uuid);
+  }
+
+  /**
+   * Get the value of the `to` parameter given to this call.
+   * @returns
+   *  - A `String` representing the `to` parameter.
+   *  - `undefined` if the call information has not yet been received from the
+   *    native layer.
+   */
+  getTo(): string | undefined {
+    return this._to;
+  }
+
+  /**
+   * Put this end of the call on hold or not on hold.
+   *
+   * @example
+   * To put a call on hold
+   * ```typescript
+   * call.hold(true);
+   * ```
+   * @example
+   * To take a call off hold
+   * ```typescript
+   * call.hold(false);
+   * ```
+   *
+   * @param hold - A `boolean` representing whether or not to put this end of
+   *  the call on hold.
+   *
+   * @returns
+   *  A `Promise` that
+   *    - Resolves with the hold status when the call is put on hold or not on
+   *      hold.
+   *    - Rejects when the call is not able to be put on hold or not on hold.
+   */
+  async hold(hold: boolean): Promise<boolean> {
+    this._isOnHold = await NativeModule.call_hold(this._uuid, hold);
+    return this._isOnHold;
+  }
+
+  /**
+   * Mute or unmute this end of the call.
+   *
+   * @example
+   * To mute a call
+   * ```typescript
+   * call.mute(true);
+   * ```
+   *
+   * @example
+   * To unmute a call
+   * ```typescript
+   * call.mute(false);
+   * ```
+   *
+   * @param mute - A `boolean` representing whether or not to mute this end of
+   *  the call.
+   *
+   * @returns
+   *  A `Promise` that
+   *    - Resolves with the muted status of the call when the call is muted or
+   *      unmuted.
+   *    - Rejects when the call is not able to be muted or unmuted.
+   */
+  async mute(mute: boolean): Promise<boolean> {
+    this._isMuted = await NativeModule.call_mute(this._uuid, mute);
+    return this._isMuted;
+  }
+
+  /**
+   * Send DTMF digits.
+   *
+   * @example
+   * To send the `0` dialtone:
+   * ```typescript
+   * call.sendDigits('0');
+   * ```
+   *
+   * @example
+   * To send the `0` and then `1` dialtone:
+   * ```typescript
+   * call.sendDigits('01');
+   * ```
+   *
+   * @param digits - A sequence of DTMF digits in a string.
+   *
+   * @returns
+   *  A `Promise` that
+   *    - Resolves when the DTMF digits have been sent.
+   *    - Rejects when DTMF tones are not able to be sent.
+   */
+  sendDigits(digits: string): Promise<void> {
+    return NativeModule.call_sendDigits(this._uuid, digits);
+  }
+
+  /**
+   * Send a CallMessage.
+   *
+   * @example
+   * To send a user-defined-message
+   * ```typescript
+   * const outgoingCallMessage: OutgoingCallMessage = await call.sendMessage({
+   *   content: { key1: 'This is a messsage from the parent call' },
+   *   contentType: 'application/json',
+   *   messageType: 'user-defined-message'
+   * });
+   *
+   * outgoingCallMessage.addListener(OutgoingCallMessage.Event.Failure, (error) => {
+   *   // outgoingCallMessage failed, handle error
+   * });
+   *
+   * outgoingCallMessage.addListener(OutgoingCallMessage.Event.Sent, () => {
+   *   // outgoingCallMessage sent
+   * });
+   * ```
+   *
+   * @param message - The call message to send.
+   *
+   * @returns
+   *  A `Promise` that
+   *    - Resolves with the OutgoingCallMessage object.
+   *    - Rejects when the message is unable to be sent.
+   */
+  async sendMessage(message: CallMessage): Promise<OutgoingCallMessage> {
+    const { content, contentType, messageType } = validateCallMessage(message);
+
+    const voiceEventSid = await NativeModule.call_sendMessage(
+      this._uuid,
+      content,
+      contentType,
+      messageType
+    );
+
+    const outgoingCallMessage = new OutgoingCallMessage({
+      content,
+      contentType,
+      messageType,
+      voiceEventSid,
+    });
+
+    return outgoingCallMessage;
+  }
+
+  /**
+   * Post feedback about a call.
+   *
+   * @example
+   * To report that a call had very significant audio latency:
+   * ```typescript
+   * call.postFeedback(Call.Score.Five, Call.Issue.AudioLatency);
+   * ```
+   *
+   * @param score - A score representing the serverity of the issue being
+   * reported.
+   * @param issue - The issue being reported.
+   * @returns
+   *  A `Promise` that
+   *    - Resolves when the feedback has been posted.
+   *    - Rejects when the feedback is unable to be sent.
+   */
+  async postFeedback(score: Call.Score, issue: Call.Issue): Promise<void> {
+    if (!validScores.includes(score)) {
+      throw new InvalidArgumentError(
+        '"score" parameter invalid. Must be a member of the `Call.Score` enum.'
+      );
+    }
+
+    if (!Object.values(Call.Issue).includes(issue)) {
+      throw new InvalidArgumentError(
+        '"issue" parameter invalid. Must be a member of the `Call.Issue` enum.'
+      );
+    }
+
+    const nativeScore = scoreMap[score];
+    const nativeIssue = issueMap[issue];
+
+    return NativeModule.call_postFeedback(this._uuid, nativeScore, nativeIssue);
+  }
+}
+
+/**
+ * Namespace for enumerations and types used by
+ * {@link (Call:class) | Call objects}.
+ *
+ * @remarks
+ *  - See also the {@link (Call:class) | Call class}.
+ *  - See also the {@link (Call:interface) | Call interface}.
+ *
+ * @public
+ */
+export namespace Call {
+  /**
+   * Enumeration of all event strings emitted by {@link (Call:class)} objects.
+   */
+  export enum Event {
+    /**
+     * Event string for the `Connected` event.
+     * See {@link (Call:interface).(addListener:1)}.
+     */
+    'Connected' = 'connected',
+
+    /**
+     * Event string for the `ConnectedFailure` event.
+     * See {@link (Call:interface).(addListener:2)}.
+     */
+    'ConnectFailure' = 'connectFailure',
+
+    /**
+     * Event string for the `Reconnecting` event.
+     * See {@link (Call:interface).(addListener:3)}.
+     */
+    'Reconnecting' = 'reconnecting',
+
+    /**
+     * Event string for the `Reconnected` event.
+     * See {@link (Call:interface).(addListener:4)}.
+     */
+    'Reconnected' = 'reconnected',
+
+    /**
+     * Event string for the `Disconnected` event.
+     * See {@link (Call:interface).(addListener:5)}.
+     */
+    'Disconnected' = 'disconnected',
+
+    /**
+     * Event string for the `Ringing` event.
+     * See {@link (Call:interface).(addListener:6)}.
+     */
+    'Ringing' = 'ringing',
+
+    /**
+     * Event string for the `QualityWarningsChanged` event.
+     * See {@link (Call:interface).(addListener:7)}.
+     */
+    'QualityWarningsChanged' = 'qualityWarningsChanged',
+
+    /**
+     * Event string for the `MessageReceived` event.
+     * See {@link (Call:interface).(addListener:8)}
+     */
+    'MessageReceived' = 'messageReceived',
+  }
+
+  /**
+   * An enumeration of all possible {@link (Call:class) | Call object} states.
+   */
+  export enum State {
+    /**
+     * Call `Connected` state.
+     *
+     * Occurs when the `Connected` and `Reconnected` event is raised.
+     *
+     * @remarks
+     *
+     * See {@link (Call:interface).(addListener:1)}.
+     *
+     * See {@link (Call:interface).(addListener:4)}.
+     */
+    'Connected' = Constants.CallStateConnected,
+
+    /**
+     * Call `Connecting` state.
+     *
+     * The default state of an outgoing call.
+     */
+    'Connecting' = Constants.CallStateConnecting,
+
+    /**
+     * Call `Disconnected` state.
+     *
+     * Occurs when the `Disconnected` or `ConnectFailure` event is raised.
+     *
+     * @remarks
+     *
+     * See {@link (Call:interface).(addListener:5)}.
+     *
+     * See {@link (Call:interface).(addListener:2)}.
+     */
+    'Disconnected' = Constants.CallStateDisconnected,
+
+    /**
+     * Call `Reconnecting` state.
+     *
+     * Occurs when the `Reconnecting` event is raised.
+     *
+     * @remarks
+     *
+     * See {@link (Call:interface).(addListener:3)}.
+     */
+    'Reconnecting' = Constants.CallStateReconnecting,
+
+    /**
+     * Call `Ringing` state. Occurs when the `Ringing` event is raised.
+     *
+     * @remarks
+     *
+     * See {@link (Call:interface).(addListener:6)}.
+     */
+    'Ringing' = Constants.CallStateRinging,
+  }
+
+  /**
+   * An enumeration of all call quality-warning types.
+   */
+  export enum QualityWarning {
+    /**
+     * Raised when the call detects constant audio input, such as silence.
+     */
+    'ConstantAudioInputLevel' = 'constant-audio-input-level',
+    /**
+     * Raised when the network encounters high jitter.
+     */
+    'HighJitter' = 'high-jitter',
+    /**
+     * Raised when the network encounters high packet loss.
+     */
+    'HighPacketLoss' = 'high-packet-loss',
+    /**
+     * Raised when the network encounters high packet round-trip-time.
+     */
+    'HighRtt' = 'high-rtt',
+    /**
+     * Raised when the call detects a low mean-opinion-score or MOS.
+     */
+    'LowMos' = 'low-mos',
+  }
+
+  /**
+   * An enumeration of all scores that could be used to rate the experience of
+   * a call or issues encountered during the call.
+   */
+  export enum Score {
+    /**
+     * An issue was not encountered or there is no desire to report said issue.
+     */
+    'NotReported' = 0,
+    /**
+     * An issue had severity approximately 1/5.
+     */
+    'One' = 1,
+    /**
+     * An issue had severity approximately 2/5.
+     */
+    'Two' = 2,
+    /**
+     * An issue had severity approximately 3/5.
+     */
+    'Three' = 3,
+    /**
+     * An issue had severity approximately 4/5.
+     */
+    'Four' = 4,
+    /**
+     * An issue had severity approximately 5/5.
+     */
+    'Five' = 5,
+  }
+
+  /**
+   * An enumeration of call issues that can be reported.
+   */
+  export enum Issue {
+    /**
+     * No issue is reported.
+     */
+    'NotReported' = 'not-reported',
+    /**
+     * The call was dropped unexpectedly.
+     */
+    'DroppedCall' = 'dropped-call',
+    /**
+     * The call encountered significant audio latency.
+     */
+    'AudioLatency' = 'audio-latency',
+    /**
+     * One party of the call could not hear the other callee.
+     */
+    'OneWayAudio' = 'one-way-audio',
+    /**
+     * Call audio was choppy.
+     */
+    'ChoppyAudio' = 'choppy-audio',
+    /**
+     * Call audio had significant noise.
+     */
+    'NoisyCall' = 'noisy-call',
+    /**
+     * Call audio had significant echo.
+     */
+    'Echo' = 'echo',
+  }
+
+  /**
+   * Listener types for all events emitted by a
+   * {@link (Call:class) | Call object.}
+   */
+  export namespace Listener {
+    /**
+     * Connected event listener. This should be the function signature of any
+     * event listener bound to the {@link (Call:namespace).Event.Connected}
+     * event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:1)}.
+     */
+    export type Connected = () => void;
+
+    /**
+     * Connect failure event listener. This should be the function signature of
+     * any event listener bound to the
+     * {@link (Call:namespace).Event.ConnectFailure} event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:2)}.
+     *
+     * See {@link TwilioErrors} for all error classes.
+     */
+    export type ConnectFailure = (error: TwilioError) => void;
+
+    /**
+     * Reconnecting event listener. This should be the function signature of any
+     * event listener bound to the {@link (Call:namespace).Event.Reconnecting}
+     * event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:3)}.
+     *
+     * See {@link TwilioErrors} for all error classes.
+     */
+    export type Reconnecting = (error: TwilioError) => void;
+
+    /**
+     * Reconnected event listener. This should be the function signature of any
+     * event listener bound to the {@link (Call:namespace).Event.Reconnected}
+     * event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:4)}.
+     */
+    export type Reconnected = () => void;
+
+    /**
+     * Disconnected event listener. This should be the function signature of any
+     * event listener bound to the {@link (Call:namespace).Event.Disconnected}
+     * event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:5)}.
+     *
+     * See {@link TwilioErrors} for all error classes.
+     */
+    export type Disconnected = (error?: TwilioError) => void;
+
+    /**
+     * Ringing event listener. This should be the function signature of any
+     * event listener bound to the {@link (Call:namespace).Event.Ringing} event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:6)}.
+     */
+    export type Ringing = () => void;
+
+    /**
+     * Quality warnings changed event listener. This should be the function
+     * signature of any event listener bound to the
+     * {@link (Call:namespace).Event.QualityWarningsChanged} event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:7)}.
+     */
+    export type QualityWarningsChanged = (
+      currentQualityWarnings: Call.QualityWarning[],
+      previousQualityWarnings: Call.QualityWarning[]
+    ) => void;
+
+    /**
+     * CallMessage received event listener. This should be the function signature of
+     * any event listener bound to the {@link (Call:namespace).Event.MessageReceived} event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:8)}.
+     */
+    export type MessageReceived = (
+      incomingCallMessage: IncomingCallMessage
+    ) => void;
+
+    /**
+     * Generic event listener. This should be the function signature of any
+     * event listener bound to any call event.
+     *
+     * @remarks
+     * See {@link (Call:interface).(addListener:9)}.
+     */
+    export type Generic = (...args: any[]) => void;
+  }
+}
+
+/**
+ * Mapping of {@link (Call:namespace).Event | Call events} to
+ * {@link (Call:namespace).State | Call states}.
+ *
+ * @remarks
+ * Note that this mapping is not a 1:1 bijection. Not every event coming from
+ * the native layer has a relevant state, and some events share a state.
+ * Therefore, this `Record` needs to be marked as `Partial` and
+ * undefined-checking logic is needed when using this mapping.
+ *
+ * @internal
+ */
+const eventTypeStateMap: Partial<Record<NativeCallEventType, Call.State>> = {
+  [Constants.CallEventConnected]: Call.State.Connected,
+  [Constants.CallEventConnectFailure]: Call.State.Disconnected,
+  [Constants.CallEventDisconnected]: Call.State.Disconnected,
+  [Constants.CallEventReconnecting]: Call.State.Reconnecting,
+  [Constants.CallEventReconnected]: Call.State.Connected,
+  [Constants.CallEventRinging]: Call.State.Ringing,
+};
+
+/**
+ * Array of valid call scores.
+ *
+ * @internal
+ */
+const validScores = [
+  Call.Score.NotReported,
+  Call.Score.One,
+  Call.Score.Two,
+  Call.Score.Three,
+  Call.Score.Four,
+  Call.Score.Five,
+];
+
+/**
+ * Mapping of the {@link (Call:namespace).Score | Call score} enum to
+ * cross-platform common constants.
+ *
+ * @internal
+ */
+const scoreMap: Record<Call.Score, NativeCallFeedbackScore> = {
+  [Call.Score.NotReported]: Constants.CallFeedbackScoreNotReported,
+  [Call.Score.One]: Constants.CallFeedbackScoreOne,
+  [Call.Score.Two]: Constants.CallFeedbackScoreTwo,
+  [Call.Score.Three]: Constants.CallFeedbackScoreThree,
+  [Call.Score.Four]: Constants.CallFeedbackScoreFour,
+  [Call.Score.Five]: Constants.CallFeedbackScoreFive,
+};
+
+/**
+ * Mapping of the {@link (Call:namespace).Issue | Call issue} enum to
+ * cross-platform common constants.
+ *
+ * @internal
+ */
+const issueMap: Record<Call.Issue, NativeCallFeedbackIssue> = {
+  [Call.Issue.AudioLatency]: Constants.CallFeedbackIssueAudioLatency,
+  [Call.Issue.ChoppyAudio]: Constants.CallFeedbackIssueChoppyAudio,
+  [Call.Issue.DroppedCall]: Constants.CallFeedbackIssueDroppedCall,
+  [Call.Issue.Echo]: Constants.CallFeedbackIssueEcho,
+  [Call.Issue.NoisyCall]: Constants.CallFeedbackIssueNoisyCall,
+  [Call.Issue.NotReported]: Constants.CallFeedbackIssueNotReported,
+  [Call.Issue.OneWayAudio]: Constants.CallFeedbackIssueOneWayAudio,
+};