Update documentation

- generate new docs
- add migration guide for upcoming 0.21 release
- update static docs as needed to reflect SessionManager

RELEASE.md

@@ -28,7 +28,7 @@ All the demos must work.
 
 ## Documentation
 
-Make sure the documentation is up to date and review any changes to the API. Commit any new documentation and consider the version number bump based on the changes to the API.
+Make sure the documentation is up to date and review any changes to the API. Commit any new documentation and consider the version number bump based on the changes to the API. If you commit any changes, go back to the Clean, Build and Test step.
 
 * `npm run build-docs`
 
@@ -53,8 +53,7 @@ This approach will leverage the `npm pack` command to package up and zip your np
 1. From within your npm package directory, run `npm pack` in your terminal. Note the .tgz file it produces and the location of it.
 2. Change directories to the project directory where you want to use the npm package. Example: `cd /path/to/project`
 3. From within the client project directory, run `npm install /path/to/package.tgz` but replace it with the proper path to the location of the .tgz file from step 1.
-4. Then you can start using the package in that client project to test things out
-This will give you the closest to production experience for using your npm package.
+4. Then you can start using the package in that client project to test things out. This will give you the closest to production experience for using your npm package.
 5. Delete the .tgz file created in step 1.
 
 ## Tag, Push and Publish

docs/MIGRATION.md

@@ -2,6 +2,10 @@
 
 * From [Simple to SimpleUser](./migration-simple.md) is relatively simple.
 
+* From [0.20 to 0.21](./migration-0.20-0.21.md)
+  * 0.21 has two minor breaking changes with 0.20
+  * ECMAScript module support and SessionManager introduction
+
 * From 0.19 to 0.20
   * 0.20 is backwards compatible with 0.19
 

docs/README.md

@@ -18,12 +18,15 @@ Bundle? Download UMD [here](https://sipjs.com/download).
 
 ## What is here?
 
-Herein lies software enabling Session Initiation Protocol (SIP) internet endpoints (called user agents) to carry various forms of real-time multimedia session data such as voice, video, or text messages. Said software is organized into three (3) divisions - each of which provides a different integration point for development...
+Herein lies software enabling Session Initiation Protocol (SIP) internet endpoints (called user agents) to carry various forms of real-time multimedia session data such as voice, video, or text messages. Said software is organized into four (4) divisions - each of which provides a different integration point for development...
 
 * SimpleUser class
   * [Demo](../demo/README.md)
   * [Overview](./simple-user.md)
   * [Reference](./simple-user/sip.js.md)
+* SessionManager class
+  * [Overview](./session-manager.md)
+  * [Reference](./session-manager/sip.js.md)
 * API framework
   * [Overview](./api.md)
   * [Reference](./api/sip.js.md)
@@ -42,11 +45,15 @@ Additional supporting implementations of classes for use with web browser enviro
 
 ### SimpleUser class
 
-The [SimpleUser](./simple-user.md) class provides a representation of a simple internet endpoint (a simple user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. There are working [Demonstrations](../demo/README.md) provided to help get started. It is the recommended interface for many applications. It has its limitations. The [SimpleUser](./simple-user.md) class is implemented utilizing the [API](./api.md) framework and as such provides a working example of how one might utilize the [API](./api.md) framework.
+The [SimpleUser](./simple-user.md) class provides a representation of a simple internet endpoint (a simple user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. There are working [Demonstrations](../demo/README.md) provided to help get started. It is the recommended interface for many applications. It has its limitations. The [SimpleUser](./simple-user.md) class is implemented utilizing the [SessionManager](./session-manager.md) class and as such provides a working example of how one might utilize the [SessionManager](./session-manager.md) class.
+
+### SessionManager class
+
+The [SessionManager](./session-manager.md) class provides a representation of a simple internet endpoint which can handle multiple concurrent calls (a user agent). It requires an understanding of what a phone call is, but minimal knowledge of SIP. It is the recommended interface for many applications which require managing multiple concurrent calls. It has its limitations. The [SessionManager](./session-manager.md) class is implemented utilizing the [API](./api.md) framework and as such provides a working example of how one might utilize the [API](./api.md) framework.
 
 ### API framework
 
-The [API](./api.md) framework is intended to provide a complete and suitable framework on which to build most end user applications - business phones, video conferencing endpoints, smart doorbells. A working knowledge of the SIP protocol is a prerequisite for using it. The framework provides infrastructure to connect with a SIP server as well as establish and maintain SIP registrations, sessions and subscriptions. There are no user interface components in it. The source code of the [SimpleUser](./simple-user.md) class is well documented and provides a good example of how to get started using the [API](./api.md) framework. The framework is implemented on top of the [Core](./core.md) library and as such provides a working example of how one might utilize the [Core](./core.md) library.
+The [API](./api.md) framework is intended to provide a complete and suitable framework on which to build most end user applications - business phones, video conferencing endpoints, smart doorbells. A working knowledge of the SIP protocol is a prerequisite for using it. The framework provides infrastructure to connect with a SIP server as well as establish and maintain SIP registrations, sessions and subscriptions. There are no user interface components in it. The source code of the [SessionManager](./session-manager.md) class is well documented and provides a good example of how to get started using the [API](./api.md) framework. The framework is implemented on top of the [Core](./core.md) library and as such provides a working example of how one might utilize the [Core](./core.md) library.
 
 ### Core library
 

docs/api/sip.js.cancel.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [Cancel](./sip.js.cancel.md)
+
+## Cancel class
+
+A request to reject an [Invitation](./sip.js.invitation.md) (incoming CANCEL).
+
+<b>Signature:</b>
+
+```typescript
+export declare class Cancel 
+```
+
+## Remarks
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Cancel` class.
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [request](./sip.js.cancel.request.md) |  | IncomingRequestMessage | Incoming CANCEL request message. |
+

docs/api/sip.js.cancel.request.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [Cancel](./sip.js.cancel.md) &gt; [request](./sip.js.cancel.request.md)
+
+## Cancel.request property
+
+Incoming CANCEL request message.
+
+<b>Signature:</b>
+
+```typescript
+get request(): IncomingRequestMessage;
+```

docs/api/sip.js.md

@@ -12,6 +12,7 @@ A simple yet powerful API which takes care of SIP signaling and WebRTC media ses
 |  --- | --- |
 |  [Ack](./sip.js.ack.md) | A request to confirm a [Session](./sip.js.session.md) (incoming ACK). |
 |  [Bye](./sip.js.bye.md) | A request to end a [Session](./sip.js.session.md) (incoming BYE). |
+|  [Cancel](./sip.js.cancel.md) | A request to reject an [Invitation](./sip.js.invitation.md) (incoming CANCEL). |
 |  [ContentTypeUnsupportedError](./sip.js.contenttypeunsupportederror.md) | An exception indicating an unsupported content type prevented execution. |
 |  [Info](./sip.js.info.md) | An exchange of information (incoming INFO). |
 |  [Invitation](./sip.js.invitation.md) | An invitation is an offer to establish a [Session](./sip.js.session.md) (incoming INVITE). |

docs/api/sip.js.registereroptions.instanceid.md

@@ -4,6 +4,11 @@
 
 ## RegistererOptions.instanceId property
 
+> Warning: This API is now obsolete.
+> 
+> Use UserAgentOptions.instanceId
+> 
+
 UUID to provide with "+sip.instance" Contact parameter.
 
 <b>Signature:</b>

docs/api/sip.js.sessiondelegate.md

@@ -18,6 +18,7 @@ export interface SessionDelegate
 |  --- | --- |
 |  [onAck(ack)](./sip.js.sessiondelegate.onack.md) | Called upon receiving an incoming in dialog ACK request. |
 |  [onBye(bye)](./sip.js.sessiondelegate.onbye.md) | Called upon receiving an incoming in dialog BYE request. |
+|  [onCancel(cancel)](./sip.js.sessiondelegate.oncancel.md) | Called upon receiving an incoming CANCEL request. |
 |  [onInfo(info)](./sip.js.sessiondelegate.oninfo.md) | Called upon receiving an incoming in dialog INFO request. |
 |  [onInvite(request, response, statusCode)](./sip.js.sessiondelegate.oninvite.md) | Called upon receiving an incoming in dialog INVITE request. |
 |  [onMessage(message)](./sip.js.sessiondelegate.onmessage.md) | Called upon receiving an incoming in dialog MESSAGE request. |

docs/api/sip.js.sessiondelegate.onack.md

@@ -22,3 +22,7 @@ onAck?(ack: Ack): void;
 
 void
 
+## Remarks
+
+Includes the ACK confirming an accepted initial Invite as well as ACKs associated with in dialog INVITE requests.
+

docs/api/sip.js.sessiondelegate.oncancel.md

@@ -0,0 +1,28 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [SessionDelegate](./sip.js.sessiondelegate.md) &gt; [onCancel](./sip.js.sessiondelegate.oncancel.md)
+
+## SessionDelegate.onCancel() method
+
+Called upon receiving an incoming CANCEL request.
+
+<b>Signature:</b>
+
+```typescript
+onCancel?(cancel: Cancel): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  cancel | [Cancel](./sip.js.cancel.md) | The cancel. |
+
+<b>Returns:</b>
+
+void
+
+## Remarks
+
+Relevant to an Invitation only. CANCEL reqeusts are being handled as a special case and there is currently no way to externally impact the response to the a CANCEL request. See core implementation for details.
+

docs/api/sip.js.subscriber.md

@@ -29,6 +29,8 @@ const subscriber = new Subscriber(userAgent, targetURI, eventType);
 // Add delegate to handle event notifications.
 subscriber.delegate = {
   onNotify: (notification: Notification) => {
+    // send a response
+    notification.accept();
     // handle notification here
   }
 };

docs/api/sip.js.useragent.instanceid.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [UserAgent](./sip.js.useragent.md) &gt; [instanceId](./sip.js.useragent.instanceid.md)
+
+## UserAgent.instanceId property
+
+User agent instance id.
+
+<b>Signature:</b>
+
+```typescript
+get instanceId(): string;
+```

docs/api/sip.js.useragent.makeuri.md

@@ -22,6 +22,10 @@ static makeURI(uri: string): URI | undefined;
 
 URI \| undefined
 
+## Remarks
+
+Returns undefined if the syntax of the URI is invalid. The syntax must conform to a SIP URI as defined in the RFC. 25 Augmented BNF for the SIP Protocol https://tools.ietf.org/html/rfc3261\#section-25
+
 ## Example
 
 

docs/api/sip.js.useragent.md

@@ -30,6 +30,7 @@ A user agent (UA) is associated with a user via the user's SIP address of record
 |  [contact](./sip.js.useragent.contact.md) |  | Contact | User agent contact. |
 |  [data](./sip.js.useragent.data.md) |  | unknown | Property reserved for use by instance owner. |
 |  [delegate](./sip.js.useragent.delegate.md) |  | [UserAgentDelegate](./sip.js.useragentdelegate.md) \| undefined | Delegate. |
+|  [instanceId](./sip.js.useragent.instanceid.md) |  | string | User agent instance id. |
 |  [state](./sip.js.useragent.state.md) |  | [UserAgentState](./sip.js.useragentstate.md) | User agent state. |
 |  [stateChange](./sip.js.useragent.statechange.md) |  | [Emitter](./sip.js.emitter.md)<!-- -->&lt;[UserAgentState](./sip.js.useragentstate.md)<!-- -->&gt; | User agent state change emitter. |
 |  [transport](./sip.js.useragent.transport.md) |  | [Transport](./sip.js.transport.md) | User agent transport. |

docs/api/sip.js.useragent.start.md

@@ -17,7 +17,7 @@ Promise<void>
 
 ## Remarks
 
-Resolves if transport connects, otherwise rejects.
+Resolves if transport connects, otherwise rejects. Calling `start()` after calling `stop()` will fail if `stop()` has yet to resolve.
 
 ## Example
 

docs/api/sip.js.useragent.stop.md

@@ -27,6 +27,8 @@ Resolves when the user agent has completed a graceful shutdown.
 5) Transport disconnects.
 6) User Agent Core resets.
 ```
+The user agent state transistions to stopped once these steps have been completed. Calling `start()` after calling `stop()` will fail if `stop()` has yet to resolve.
+
 NOTE: While this is a "graceful shutdown", it can also be very slow one if you are waiting for the returned Promise to resolve. The disposal of the clients and dialogs is done serially - waiting on one to finish before moving on to the next. This can be slow if there are lot of subscriptions to unsubscribe for example.
 
 THE SLOW PACE IS INTENTIONAL! While one could spin them all down in parallel, this could slam the remote server. It is bad practice to denial of service attack (DoS attack) servers!!! Moreover, production servers will automatically blacklist clients which send too many requests in too short a period of time - dropping any additional requests.

docs/api/sip.js.useragentoptions.gracefulshutdown.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [UserAgentOptions](./sip.js.useragentoptions.md) &gt; [gracefulShutdown](./sip.js.useragentoptions.gracefulshutdown.md)
+
+## UserAgentOptions.gracefulShutdown property
+
+If `true`<!-- -->, the `stop()` method will attempt to gracefully end all dialogs and registrations before disconnecting. Otherwise `stop()` will transition immediately abandoning all dialogs and registrations.
+
+<b>Signature:</b>
+
+```typescript
+gracefulShutdown?: boolean;
+```

docs/api/sip.js.useragentoptions.instanceid.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [UserAgentOptions](./sip.js.useragentoptions.md) &gt; [instanceId](./sip.js.useragentoptions.instanceid.md)
+
+## UserAgentOptions.instanceId property
+
+UUID to provide with "+sip.instance" Contact header parameter.
+
+<b>Signature:</b>
+
+```typescript
+instanceId?: string;
+```

docs/api/sip.js.useragentoptions.instanceidalwaysadded.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sip.js](./sip.js.md) &gt; [UserAgentOptions](./sip.js.useragentoptions.md) &gt; [instanceIdAlwaysAdded](./sip.js.useragentoptions.instanceidalwaysadded.md)
+
+## UserAgentOptions.instanceIdAlwaysAdded property
+
+Add "+sip.instance" Contact header parameter to all requests.
+
+<b>Signature:</b>
+
+```typescript
+instanceIdAlwaysAdded?: boolean;
+```

docs/api/sip.js.useragentoptions.md

@@ -20,16 +20,17 @@ export interface UserAgentOptions
 |  [authorizationHa1](./sip.js.useragentoptions.authorizationha1.md) |  | string | Authorization ha1. |
 |  [authorizationPassword](./sip.js.useragentoptions.authorizationpassword.md) |  | string | Authorization password. |
 |  [authorizationUsername](./sip.js.useragentoptions.authorizationusername.md) |  | string | Authorization username. |
-|  [autoStart](./sip.js.useragentoptions.autostart.md) |  | boolean |  |
-|  [autoStop](./sip.js.useragentoptions.autostop.md) |  | boolean | If <code>true</code>, the user agent calls the <code>stop()</code> method on unload (if running in browser window). |
 |  [contactName](./sip.js.useragentoptions.contactname.md) |  | string | The user portion of user agent's contact URI. |
 |  [contactParams](./sip.js.useragentoptions.contactparams.md) |  | { \[name: string\]: string; } | The URI parameters of the user agent's contact URI. |
 |  [delegate](./sip.js.useragentoptions.delegate.md) |  | [UserAgentDelegate](./sip.js.useragentdelegate.md) | Delegate for [UserAgent](./sip.js.useragent.md)<!-- -->. |
 |  [displayName](./sip.js.useragentoptions.displayname.md) |  | string | The display name associated with the user agent. |
 |  [forceRport](./sip.js.useragentoptions.forcerport.md) |  | boolean | Force adding rport to Via header. |
+|  [gracefulShutdown](./sip.js.useragentoptions.gracefulshutdown.md) |  | boolean | If <code>true</code>, the <code>stop()</code> method will attempt to gracefully end all dialogs and registrations before disconnecting. Otherwise <code>stop()</code> will transition immediately abandoning all dialogs and registrations. |
 |  [hackAllowUnregisteredOptionTags](./sip.js.useragentoptions.hackallowunregisteredoptiontags.md) |  | boolean | Hack |
 |  [hackIpInContact](./sip.js.useragentoptions.hackipincontact.md) |  | boolean \| string | Hack |
 |  [hackViaTcp](./sip.js.useragentoptions.hackviatcp.md) |  | boolean | Hack |
+|  [instanceId](./sip.js.useragentoptions.instanceid.md) |  | string | UUID to provide with "+sip.instance" Contact header parameter. |
+|  [instanceIdAlwaysAdded](./sip.js.useragentoptions.instanceidalwaysadded.md) |  | boolean | Add "+sip.instance" Contact header parameter to all requests. |
 |  [logBuiltinEnabled](./sip.js.useragentoptions.logbuiltinenabled.md) |  | boolean | Indicates whether log messages should be written to the browser console. |
 |  [logConfiguration](./sip.js.useragentoptions.logconfiguration.md) |  | boolean | If true, constructor logs the user agent configuration. |
 |  [logConnector](./sip.js.useragentoptions.logconnector.md) |  | [LogConnector](./sip.js.logconnector.md) | A function which will be called every time a log is generated. |