From 8d0911ac23835568b2f3f2fcfd13f6396d7f3bcd Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 15:15:23 -0800
Subject: [PATCH 1/8] simplify and standardize readme

---
 README.md             |  2 +-
 packages/js/README.md | 32 ++++++++++++++++----------------
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 3fe256af..65e50bd6 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Enable [Telnyx real-time communication](https://developers.telnyx.com/docs/v2/we
 
 | Project          | Description                  | README                                         | CHANGELOG                                            |                                     Version                                     |
 | ---------------- | ---------------------------- | ---------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
-| **@telnyx/webrtc**   | Telnyx in the browser        | [`README`](packages/js#telnyx-webrtc-sdk)           | [`CHANGELOG`](packages/js/CHANGELOG.md)           |    ![NPM](https://img.shields.io/npm/v/@telnyx/webrtc.svg?color=brightgreen)    |
+| **@telnyx/webrtc**   | Telnyx in the browser        | [`README`](packages/js#telnyxwebrtc)           | [`CHANGELOG`](packages/js/CHANGELOG.md)           |    ![NPM](https://img.shields.io/npm/v/@telnyx/webrtc.svg?color=brightgreen)    |
 | **@telnyx/react-client**   | React wrapper for TelnyxRTC        | [`README`](packages/react-client#telnyxreact-client)           | [`CHANGELOG`](packages/react-client/CHANGELOG.md)           |    ![NPM](https://img.shields.io/npm/v/@telnyx/react-client.svg?color=brightgreen)    |
 | **@telnyx/react-native** | React Native wrapper for TelnyxRTC| [`README`](packages/react-native#telnyx-react-native) | [`CHANGELOG`](packages/react-native/CHANGELOG.md) | ![NPM](https://img.shields.io/npm/v/@telnyx/react-native.svg?color=brightgreen) |
 
diff --git a/packages/js/README.md b/packages/js/README.md
index 401e0203..b00a19e4 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -1,25 +1,14 @@
-# Telnyx WebRTC SDK
+# @telnyx/webrtc
 
 ![npm (scoped)](https://img.shields.io/npm/v/@telnyx/webrtc) <!-- GEN:chromium-version-badge-if-release -->[![Chromium version](https://img.shields.io/badge/chromium-82.0.4057.0-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge-if-release -->[![Firefox version](https://img.shields.io/badge/firefox-72-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> [![WebKit version](https://img.shields.io/badge/webkit-13.0.4-blue.svg?logo=safari)](https://webkit.org/) [![Join Slack](https://img.shields.io/badge/join-slack-infomational)](https://joinslack.telnyx.com/)
 
-The Telnyx WebRTC SDK provides all the functionality you need to start making voice calls from a browser to phone numbers or other browsers.
-
-[v2 CHANGELOG](CHANGELOG.md)
-
-To access v1, click [here](https://github.com/team-telnyx/webrtc/tree/v1.0.9)
+The Telnyx WebRTC Client provides all the functionality you need to start making voice & video calls from a browser.
 
 ---
 
-## Our packages
-
-- `@telnyx/webrtc`
-- `@telnyx/react-native` - [React Native](https://www.npmjs.com/package/@telnyx/react-native)
-
 ## Requirements
 
-You'll need node v11.15.0 or later.
-
-You'll also need a Telnyx account in order to authenticate your application. Follow our [WebRTC quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to setup your account.
+You'll need a Telnyx account in order to authenticate your application. Follow our [WebRTC quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to setup your account.
 
 ## Installation
 
@@ -207,7 +196,7 @@ call.hangup();
 
 ### Vanilla Javascript
 
-We've included a few [examples in Javascript(ES6)](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples/vanilla) to help you get started.
+We've included a few [examples in Javascript (ES6)](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples/vanilla) to help you get started.
 
 ```
 cd examples/vanilla
@@ -223,6 +212,11 @@ Screenshot:
 
 We've included a few [examples in React](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples) to help you get started. This library is not limited to React and can be used with any JavaScript framework of your choosing.
 
+> _Looking for an easier way to get started with React or React Native? Check out our other packages:_
+>
+> - [@telnyx/react-client](../react-client)
+> - [@telnyx/react-native](../react-client)
+
 #### Audio call
 
 ```
@@ -249,7 +243,9 @@ npm start
 Screenshot:
 ![Web Dialer](https://raw.githubusercontent.com/team-telnyx/webrtc/master/packages/js/examples/react-video/react-video-screenshot.png)
 
-### Development
+---
+
+## Development
 
 This library is written in [TypeScript](https://www.typescriptlang.org/) to define a clear API with optional typechecking benefits.
 
@@ -273,6 +269,10 @@ To generate TypeScript documentation:
 npm run docs
 ```
 
+### Requirements
+
+You'll need node v11.15.0 or later.
+
 ---
 
 ## Contributing

From 264ebb9c13ae5c591d6cb2580b3baf67a23ba348 Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:09:12 -0800
Subject: [PATCH 2/8] cross link readme to docs

---
 packages/js/README.md        | 190 ++++++++++++-----------------------
 packages/js/src/TelnyxRTC.ts |   9 +-
 2 files changed, 70 insertions(+), 129 deletions(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index b00a19e4..92aa3844 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -26,169 +26,107 @@ import { TelnyxRTC } from '@telnyx/webrtc';
 
 ## Usage
 
-To initialize the WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our [quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to learn how to use our APIs to create **JWTs** (JSON Web Tokens) to authenticate. You can also [create a Credential Connection](https://developers.telnyx.com/docs/v2/sip-trunking/quickstarts/portal-setup) and authenticate with its `username` and `password`.
-
-To use the `ringbackFile`, make sure the "Generate Ringback Tone" option is **disabled** in your [Telnyx Portal connection](https://portaldev.telnyx.com/#/app/connections) configuration (Inbound tab.)
+To initialize the WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our [quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to create **JWTs** (JSON Web Tokens) to authenticate. You can also authenticate directly with the SIP Connection `username` and `password`.
 
 ```js
 // Initialize the client
 const client = new TelnyxRTC({
-  /*
-    Use a JWT to authenticate (recommended)
-   */
+  /* Use a JWT to authenticate (recommended) */
   login_token: login_token,
-  /*
-    or use your Connection credentials
-   */
-  login: username,
-  password: password,
-  /* 
-    ringtoneFile - This file can be a wav/mp3 in your local public folder or you can host it in a CDN and pass just the URL, such as https://cdn.company.com/sounds/call.mp3
-   */
-  ringtoneFile: './sounds/incoming_call.mp3',
-  /*
-    ringbackFile - Used when you disable Generate Ringback Tone to provide your own ringback sound.
-  */
-  ringbackFile: './sounds/ringback_tone.mp3',
+  /* or use your Connection credentials */
+  // login: username,
+  // password: password,
 });
 
+// Connect and login
+client.connect();
+
+// You can disconnect when you're done
+//  client.disconnect();
+```
+
+> See [TelnyxRTC#constructor](./docs/ts/classes/telnyxrtc.md#constructors) for all options.
+
+Important: You should treat Connection credentials as sensitive data and should not hardcode credentials into your frontend web application. Check out the [examples](https://github.com/team-telnyx/webrtc/tree/main/examples/react) for sample React code that handles username and password by prompting the user.
+
+To hear/view calls in the browser, you'll need to specify an HTML media element:
+
+```js
+client.remoteElement = 'remoteMedia';
+```
+
+The corresponding HTML:
+
+```html
+<audio id="remoteMedia" autoplay="true" />
+<!-- or for video: -->
+<!-- <video id="remoteMedia" autoplay="true" playsinline="true" /> -->
+```
+
+### Events
+
+```js
 // Create a variable to track the current call
 let activeCall;
 
 // Attach event listeners
 client
-  .on('telnyx.socket.open', () => console.log('socket open'))
-  .on('telnyx.socket.close', () => {
-    console.log('socket closed');
-    client.disconnect();
-  })
-  .on('telnyx.socket.error', (error) => {
-    console.log('telnyx.socket.error', error);
-    client.disconnect();
-  })
   .on('telnyx.ready', () => console.log('ready to call'))
   .on('telnyx.error', () => console.log('error'))
-  // Event fired on call updates, e.g. when there's an incoming call
+  // Events are fired on both session and call updates
+  // ex: when the session has been established
+  // ex: when there's an incoming call
   .on('telnyx.notification', (notification) => {
-    activeCall = notification.call;
-
-    switch (notification.type) {
-      case 'callUpdate':
-        // Call is over and can be removed
-        if (
-          notification.call.state === 'hangup' ||
-          notification.call.state === 'destroy'
-        ) {
-          activeCall = null;
-        }
-        // An established and active call
-        if (notification.call.state === 'active') {
-          return;
-        }
-        // New calls that haven't started connecting yet
-        if (notification.call.state === 'new') {
-          return;
-        }
-        // Receiving an inbound call
-        if (notification.call.state === 'ringing') {
-          return;
-        }
-        // Call is active but on hold
-        if (notification.call.state === 'held') {
-          return;
-        }
-        break;
+    if (notification.type === 'callUpdate') {
+      activeCall = notification.call;
     }
   });
-
-// Connect and login
-client.connect();
-
-// You can disconnect when you're done
-// client.disconnect();
 ```
 
-Important: You should treat Connection credentials as sensitive data and should not hardcode credentials into your frontend web application. Check out the [examples](https://github.com/team-telnyx/webrtc/tree/main/examples/react) for sample React code that handles username and password by prompting the user.
+> See [TelnyxRTC.on](./docs/ts/classes/telnyxrtc.md#on) for all events.
 
 ### Calls
 
-To initiate a call from your application:
-
 ```js
-// You can save this call or wait for `callUpdate` and use the returned `activeCall`
+// Dial a number
 const call = client.newCall({
   // Destination is required and can be a phone number or SIP URI
   destinationNumber: '18004377950',
-  callerName: 'Caller ID Name',
-  // Caller ID number is optional.
-  // You can only specify a phone number that you own and have assigned
-  // to your Connection in the Telnyx Portal
-  callerNumber: '‬',
-  audio: true,
-  video: false, //Used to enable/disable video
+  callerNumber: '‬155531234567',
 });
 ```
 
-A [Call](./docs/ts/interfaces/icall.md) has methods that can be hooked up to your UI:
+Set `video` to `true` to enable audio & video:
 
 ```js
-// End a call
-call.hangup();
+const videoCall = client.newCall({
+  destinationNumber: 'sip:example@sip.example.com',
+  video: true,
+});
 
-// Call states that can be toggled
-call.hold();
-call.unhold();
-call.muteAudio();
-call.unmuteAudio();
+// And in your HTML:
+//  <video id="remoteMedia" autoplay="true" playsinline="true" />
+```
 
-// Send digits and keypresses
-call.dtmf('1234');
+> See [TelnyxRTC.newCall](./docs/ts/classes/telnyxrtc.md#newCall) for all options.
+
+A `Call` instance has methods that can be hooked up to your UI:
 
-// Answer an incoming call
+```js
+// Answer an incoming call in the `'telnyx.notification'` event
 call.answer();
-// Hangup (reject) an incoming call
+// Hangup or reject an incoming call
 call.hangup();
-```
-
----
 
-#### Using WebRTC with React to make an audio call
-
-```Js
-    // Used to set remote stream
-    if (mediaRef.current && call && call.remoteStream) {
-        mediaRef.current.srcObject = call.remoteStream;
-    }
+// Send digits and keypresses
+call.dtmf('1234');
 
-    <audio
-      ref={mediaRef}
-      id='audioCall'
-      autoPlay='autoplay'
-      controls={false}
-    />
+// Call states that can be toggled
+call.hold();
+call.muteAudio();
 ```
 
----
-
-#### Using WebRTC with Vanilla Javascript to make video call
-
-```Js
-    // Used to set local and remote stream
-    client.remoteElement = 'remoteVideo';
-    client.localElement = 'localVideo';
-
-    <video
-      id="localVideo"
-      autoplay="true"
-      playsinline="true"
-    />
-     <video
-      id="remoteVideo"
-      autoplay="true"
-      playsinline="true"
-    />
-
-```
+> See [Call#methods](./docs/ts/classes/call.md#methods) for all methods.
 
 ---
 
@@ -263,11 +201,7 @@ To run all tests:
 npm test
 ```
 
-To generate TypeScript documentation:
-
-```
-npm run docs
-```
+TypeScript documentation is automatically generated from TSDoc-style comments on merge to `main`.
 
 ### Requirements
 
diff --git a/packages/js/src/TelnyxRTC.ts b/packages/js/src/TelnyxRTC.ts
index 802df40d..3f12b478 100644
--- a/packages/js/src/TelnyxRTC.ts
+++ b/packages/js/src/TelnyxRTC.ts
@@ -34,7 +34,14 @@ export default class TelnyxRTC extends TelnyxRTCClient {
    * });
    * ```
    *
-   * Setting `ringtoneFile` and `ringbackFile`:
+   * ### Custom ringtone and ringback
+   *
+   * Custom ringback and ringtone files can be a wav/mp3 in your local public folder
+   * or a file hosted on a CDN, ex: https://cdn.company.com/sounds/call.mp3.
+   *
+   * To use the `ringbackFile`, make sure the "Generate Ringback Tone" option is **disabled**
+   * in your [Telnyx Portal connection](https://portaldev.telnyx.com/#/app/connections)
+   * configuration (Inbound tab.)
    *
    * ```js
    * const client = new TelnyxRTC({

From c181f5b257bd81c81a3ca02d22125b1163e4ed26 Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:21:59 -0800
Subject: [PATCH 3/8] add toc

---
 packages/js/README.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index 92aa3844..4b0518cf 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -4,11 +4,14 @@
 
 The Telnyx WebRTC Client provides all the functionality you need to start making voice & video calls from a browser.
 
----
-
-## Requirements
+- [Installation](#Installation)
+- [Usage](#Usage)
+- [Examples](#Examples)
+  - [Vanilla JavaScript](#vanilla-javascript)
+  - [React.js](#reactjs)
+- [Development](#Development)
 
-You'll need a Telnyx account in order to authenticate your application. Follow our [WebRTC quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to setup your account.
+---
 
 ## Installation
 

From c886ed2ec3ffc87226a107ebf8eb819d63846cea Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:26:01 -0800
Subject: [PATCH 4/8] specify example requirements

---
 packages/js/README.md | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index 4b0518cf..0bf11569 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -139,18 +139,18 @@ call.muteAudio();
 
 We've included a few [examples in Javascript (ES6)](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples/vanilla) to help you get started.
 
-```
-cd examples/vanilla
-open index.html
+```sh
+$ cd examples/vanilla
+$ open index.html
 ```
 
 Screenshot:
 ![Video call](https://raw.githubusercontent.com/team-telnyx/webrtc/master/packages/js/examples/vanilla/vanilla-screeshot.png)
 
----
-
 ### ReactJS
 
+_**Requirement** Node v11.15.0 or later_
+
 We've included a few [examples in React](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples) to help you get started. This library is not limited to React and can be used with any JavaScript framework of your choosing.
 
 > _Looking for an easier way to get started with React or React Native? Check out our other packages:_
@@ -160,11 +160,11 @@ We've included a few [examples in React](https://github.com/team-telnyx/webrtc/t
 
 #### Audio call
 
-```
-cd examples/react-audio
-npm run setup
-npm install
-npm run storybook
+```sh
+$ cd examples/react-audio
+$ npm run setup
+$ npm install
+$ npm run storybook
 ```
 
 Configuration options for your Telnyx account are available under the [Storybook **Knobs**](https://github.com/storybookjs/storybook/tree/master/addons/knobs).
@@ -174,11 +174,11 @@ Screenshot:
 
 #### Video call
 
-```
-cd examples/react-video
-npm run setup
-npm install
-npm start
+```sh
+$ cd examples/react-video
+$ npm run setup
+$ npm install
+$ npm start
 ```
 
 Screenshot:
@@ -188,6 +188,8 @@ Screenshot:
 
 ## Development
 
+_**Requirement** Node v11.15.0 or later_
+
 This library is written in [TypeScript](https://www.typescriptlang.org/) to define a clear API with optional typechecking benefits.
 
 To contribute, clone this repo and install locally:
@@ -206,10 +208,6 @@ npm test
 
 TypeScript documentation is automatically generated from TSDoc-style comments on merge to `main`.
 
-### Requirements
-
-You'll need node v11.15.0 or later.
-
 ---
 
 ## Contributing

From 0cdaa2161509d4db1a89f7aeebaa824d1986260e Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:30:46 -0800
Subject: [PATCH 5/8] add client header

---
 packages/js/README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/js/README.md b/packages/js/README.md
index 0bf11569..f70a5cb3 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -31,6 +31,8 @@ import { TelnyxRTC } from '@telnyx/webrtc';
 
 To initialize the WebRTC client, you'll need to authenticate using a Telnyx SIP Connection. Follow our [quickstart guide](https://developers.telnyx.com/docs/v2/webrtc/quickstart) to create **JWTs** (JSON Web Tokens) to authenticate. You can also authenticate directly with the SIP Connection `username` and `password`.
 
+### Client
+
 ```js
 // Initialize the client
 const client = new TelnyxRTC({

From 9a94d35afee7795e6c9ccf33f517210a20df5178 Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:32:26 -0800
Subject: [PATCH 6/8] fix broken example link

---
 packages/js/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index f70a5cb3..46510c30 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -52,7 +52,7 @@ client.connect();
 
 > See [TelnyxRTC#constructor](./docs/ts/classes/telnyxrtc.md#constructors) for all options.
 
-Important: You should treat Connection credentials as sensitive data and should not hardcode credentials into your frontend web application. Check out the [examples](https://github.com/team-telnyx/webrtc/tree/main/examples/react) for sample React code that handles username and password by prompting the user.
+Important: You should treat Connection credentials as sensitive data and should not hardcode credentials into your frontend web application. Check out the [examples](./examples) for sample React code that handles username and password by prompting the user.
 
 To hear/view calls in the browser, you'll need to specify an HTML media element:
 

From 63d942e4eae3dac622520a8da2bb07b487c768c3 Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Fri, 11 Dec 2020 16:38:36 -0800
Subject: [PATCH 7/8] add answer example

---
 packages/js/README.md | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index 46510c30..ab200f69 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -92,8 +92,9 @@ client
 
 ### Calls
 
+To initiate an outgoing call:
+
 ```js
-// Dial a number
 const call = client.newCall({
   // Destination is required and can be a phone number or SIP URI
   destinationNumber: '18004377950',
@@ -101,7 +102,7 @@ const call = client.newCall({
 });
 ```
 
-Set `video` to `true` to enable audio & video:
+To enable video when calling:
 
 ```js
 const videoCall = client.newCall({
@@ -109,17 +110,27 @@ const videoCall = client.newCall({
   video: true,
 });
 
-// And in your HTML:
+// And in your HTML, replace the audio element with video.
 //  <video id="remoteMedia" autoplay="true" playsinline="true" />
 ```
 
 > See [TelnyxRTC.newCall](./docs/ts/classes/telnyxrtc.md#newCall) for all options.
 
-A `Call` instance has methods that can be hooked up to your UI:
+To answer an incoming call:
+
+```js
+client.on('telnyx.notification', (notification) => {
+  const call = notification.call;
+
+  if (notification.type === 'callUpdate' && call.state === 'ringing') {
+    call.answer();
+  }
+});
+```
+
+Both the outgoing and incoming `Call` instance has methods that can be hooked up to your UI:
 
 ```js
-// Answer an incoming call in the `'telnyx.notification'` event
-call.answer();
 // Hangup or reject an incoming call
 call.hangup();
 

From 565a85460228dc79a0a703d1ec5e1f0ac3cfec4f Mon Sep 17 00:00:00 2001
From: Sua Yoo <sua@telnyx.com>
Date: Tue, 15 Dec 2020 15:57:59 -0800
Subject: [PATCH 8/8] Apply suggestions from code review

Co-authored-by: Hugo Bessa <eu@hugobessa.com.br>
---
 packages/js/README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/packages/js/README.md b/packages/js/README.md
index ab200f69..04ae431a 100644
--- a/packages/js/README.md
+++ b/packages/js/README.md
@@ -153,8 +153,8 @@ call.muteAudio();
 We've included a few [examples in Javascript (ES6)](https://github.com/team-telnyx/webrtc/tree/main/packages/js/examples/vanilla) to help you get started.
 
 ```sh
-$ cd examples/vanilla
-$ open index.html
+cd examples/vanilla
+open index.html
 ```
 
 Screenshot:
@@ -174,10 +174,10 @@ We've included a few [examples in React](https://github.com/team-telnyx/webrtc/t
 #### Audio call
 
 ```sh
-$ cd examples/react-audio
-$ npm run setup
-$ npm install
-$ npm run storybook
+cd examples/react-audio
+npm run setup
+npm install
+npm run storybook
 ```
 
 Configuration options for your Telnyx account are available under the [Storybook **Knobs**](https://github.com/storybookjs/storybook/tree/master/addons/knobs).
@@ -188,10 +188,10 @@ Screenshot:
 #### Video call
 
 ```sh
-$ cd examples/react-video
-$ npm run setup
-$ npm install
-$ npm start
+cd examples/react-video
+npm run setup
+npm install
+npm start
 ```
 
 Screenshot: