chore: add docs for customHeaders and preferred_codecs (#387)

* chore: add docs for customHeaders and preferred_codecs * chore: deprecate video methods
team-telnyx · Oct 16, 2024 · e0299f9 · e0299f9
1 parent fd87e08
commit e0299f9
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 1 deletion.
diff --git a/packages/js/docs/ts/classes/TelnyxRTC.md b/packages/js/docs/ts/classes/TelnyxRTC.md
@@ -903,6 +903,36 @@ const call = client.newCall().catch(console.error);
 // => `destinationNumber is required`
 ```
 
+### Setting Custom Headers
+
+```js
+
+client.newCall({
+ destinationNumber: '18004377950',
+
+ callerNumber: '155531234567',
+
+ customHeaders: [ {name: "X-Header", value: "value" } ] 
+});
+```
+
+### Setting Preferred Codec
+
+You can pass `preferred_codecs` to the `newCall` method to set codec preference during the call.
+
+`preferred_codecs` is a sub-array of the codecs returned by [RTCRtpReceiver.getCapabilities('audio')](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpReceiver/getCapabilities_static#codecs)
+
+```js
+const allCodecs = RTCRtpReceiver.getCapabilities('audio').codecs;
+
+const PCMACodec = allCodecs.find((c) => c.mimeType.toLowerCase().includes('pcma'));
+
+client.newCall({
+ destinationNumber: '123',
+ preferred_codecs: [PCMACodec],
+});
+```
+
 #### Overrides
 
 TelnyxRTCClient.newCall

diff --git a/packages/js/src/Modules/Verto/BaseSession.ts b/packages/js/src/Modules/Verto/BaseSession.ts
@@ -247,6 +247,7 @@ export default abstract class BaseSession {
   /**
    * Callback when the ws connection is going to close or get an error
    * @return void
+   * @private
    */
   public onNetworkClose(): void {
     if (this.relayProtocol) {

diff --git a/packages/js/src/Modules/Verto/BrowserSession.ts b/packages/js/src/Modules/Verto/BrowserSession.ts
@@ -247,6 +247,7 @@ export default abstract class BrowserSession extends BaseSession {
    * ```
    *
    * @returns Promise with an array of MediaDeviceInfo
+   * @deprecated
    */
   getVideoDevices(): Promise<MediaDeviceInfo[]> {
     return getDevices(DeviceType.Video).catch((error) => {
@@ -391,6 +392,7 @@ export default abstract class BrowserSession extends BaseSession {
    *   console.log(result);
    * });
    * ```
+   * @deprecated
    */
   async getDeviceResolutions(deviceId: string) {
     try {
@@ -545,6 +547,7 @@ export default abstract class BrowserSession extends BaseSession {
    *  height: 720
    * })
    * ```
+   * @deprecated
    */
   async setVideoSettings(settings: IVideoSettings) {
     if (!settings) {
@@ -586,6 +589,7 @@ export default abstract class BrowserSession extends BaseSession {
    *
    * client.disableWebcam();
    * ```
+   * @deprecated
    */
   disableWebcam() {
     this._videoConstraints = false;
@@ -604,6 +608,7 @@ export default abstract class BrowserSession extends BaseSession {
    *
    * client.enableWebcam();
    * ```
+   * @deprecated
    */
   enableWebcam() {
     this._videoConstraints = true;

diff --git a/packages/js/src/Modules/Verto/webrtc/BaseCall.ts b/packages/js/src/Modules/Verto/webrtc/BaseCall.ts
@@ -590,6 +590,7 @@ export default abstract class BaseCall implements IWebRTCCall {
    * ```js
    * call.muteVideo();
    * ```
+   * @deprecated
    */
   muteVideo() {
     disableVideoTracks(this.options.localStream);
@@ -604,6 +605,7 @@ export default abstract class BaseCall implements IWebRTCCall {
    * ```js
    * call.unmuteVideo();
    * ```
+   * @deprecated
    */
   unmuteVideo() {
     enableVideoTracks(this.options.localStream);
@@ -617,6 +619,7 @@ export default abstract class BaseCall implements IWebRTCCall {
    * ```js
    * call.toggleVideoMute();
    * ```
+   * @deprecated
    */
   toggleVideoMute() {
     toggleVideoTracks(this.options.localStream);
@@ -653,6 +656,7 @@ export default abstract class BaseCall implements IWebRTCCall {
    *
    * @param deviceId the target video device ID
    * @returns Promise that resolves if the video device has been updated
+   * @deprecated
    */
   async setVideoDevice(deviceId: string): Promise<void> {
     const { instance } = this.peer;

diff --git a/packages/js/src/Modules/Verto/webrtc/Call.ts b/packages/js/src/Modules/Verto/webrtc/Call.ts
@@ -53,7 +53,6 @@ import { IVertoCallOptions } from './interfaces';
 export class Call extends BaseCall {
   public screenShare: Call;
 
-
   private _statsInterval: any = null;
 
   hangup(params: any = {}, execute: boolean = true) {
@@ -63,6 +62,10 @@ export class Call extends BaseCall {
     super.hangup(params, execute);
   }
 
+  /**
+   * @deprecated
+   * @private
+   */
   async startScreenShare(opts?: IVertoCallOptions) {
     const displayStream: MediaStream = await getDisplayMedia({ video: true });
     displayStream.getTracks().forEach((t) => {
@@ -89,6 +92,10 @@ export class Call extends BaseCall {
     return this.screenShare;
   }
 
+  /**
+   * @deprecated
+   * @private
+   */
   stopScreenShare() {
     if (this.screenShare instanceof Call) {
       this.screenShare.hangup();

diff --git a/packages/js/src/Modules/Verto/webrtc/interfaces.ts b/packages/js/src/Modules/Verto/webrtc/interfaces.ts
@@ -56,7 +56,41 @@ export interface IStatsBinding {
 }
 
 export interface AnswerParams {
+  /**
+   *  *
+   * ### Setting Custom Headers
+   *
+   * ```js
+   *
+   * client.newCall({
+   *  destinationNumber: '18004377950',
+   *
+   *  callerNumber: '155531234567',
+   *
+   *  customHeaders: [ {name: "X-Header", value: "value" } ]
+   * });
+   * ```
+   */
   customHeaders?: Array<{ name: string; value: string }>;
+
+  /**
+   *
+   * ### Setting Preferred Codec
+   *
+   * You can pass `preferred_codecs` to the `newCall` method to set codec preference during the call.
+   *
+   * `preferred_codecs` is a sub-array of the codecs returned by [RTCRtpReceiver.getCapabilities('audio')](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpReceiver/getCapabilities_static#codecs)
+   *
+   * ```js
+   * const allCodecs = RTCRtpReceiver.getCapabilities('audio').codecs;
+   *
+   * const PCMACodec = allCodecs.find((c) => c.mimeType.toLowerCase().includes('pcma'));
+   *
+   * client.newCall({
+   * destinationNumber: '123',
+   * preferred_codecs: [PCMACodec],
+   * });
+   */
   preferred_codecs?: Array<RTCRtpCodecCapability>;
 }
 

diff --git a/packages/js/src/TelnyxRTC.ts b/packages/js/src/TelnyxRTC.ts
@@ -152,6 +152,36 @@ export class TelnyxRTC extends TelnyxRTCClient {
    * const call = client.newCall().catch(console.error);
    * // => `destinationNumber is required`
    * ```
+   * 
+   * ### Setting Custom Headers
+   * 
+   * ```js
+   * 
+   * client.newCall({
+   *  destinationNumber: '18004377950',
+   * 
+   *  callerNumber: '155531234567',
+   * 
+   *  customHeaders: [ {name: "X-Header", value: "value" } ] 
+   * });
+   * ```
+
+   * ### Setting Preferred Codec
+   *
+   * You can pass `preferred_codecs` to the `newCall` method to set codec preference during the call.
+   *
+   * `preferred_codecs` is a sub-array of the codecs returned by [RTCRtpReceiver.getCapabilities('audio')](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpReceiver/getCapabilities_static#codecs)
+   *
+   * ```js
+   * const allCodecs = RTCRtpReceiver.getCapabilities('audio').codecs;
+   *
+   * const PCMACodec = allCodecs.find((c) => c.mimeType.toLowerCase().includes('pcma'));
+   *
+   * client.newCall({
+   *  destinationNumber: '123',
+   *  preferred_codecs: [PCMACodec],
+   * });
+   * ```
    */
   newCall(options: ICallOptions) {
     return super.newCall(options);