From 84f136f6ca667d67b5d5d751ca9085e71df62b8f Mon Sep 17 00:00:00 2001 From: Nathaniel Camomot Date: Fri, 21 Dec 2018 10:42:44 +0800 Subject: [PATCH] docs --- README.md | 105 +- TODO | 3 - docs/assets/js/search.js | 2 +- docs/classes/firepeer.html | 1582 +++++++++++++++++++------ docs/index.html | 1162 +++++++++++++++--- docs/interfaces/firepeerinstance.html | 1262 ++++++++++++++++---- docs/interfaces/firepeeroptions.html | 1316 ++++++++++++++++---- docs/interfaces/signal.html | 1251 +++++++++++++++---- src/firepeer.ts | 74 +- 9 files changed, 5562 insertions(+), 1195 deletions(-) delete mode 100644 TODO diff --git a/README.md b/README.md index bf4e674..470e923 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,54 @@ # firepeer -secure signalling and authentication for [simple-peer](https://github.com/feross/simple-peer) using [firebase realtime database](https://firebase.google.com/docs/database/). - -## Getting Started - -### setup firebase - -Create a firebase project and setup the JS client SDK. - -- https://firebase.google.com/docs/web/setup -- https://firebase.google.com/docs/database/web/start - -### configure security rules - -Add these security rules in the firebase console to secure the signalling data. - -```json -{ - "rules": { - "peers": { - "$uid": { - "$id": { - ".read": "auth != null && auth.uid == $uid", - ".write": "auth != null && auth.uid == $uid", - "$otherUid": { - "$otherId": { - ".read": "auth != null && auth.uid == $otherUid", - ".write": "auth != null && auth.uid == $otherUid", - ".validate": "newData.hasChildren(['sdp', 'type']) || newData.hasChildren(['type', 'error'])", - "sdp": { - ".validate": "newData.isString() && newData.val().length < 4000" - }, - "error": { - ".validate": "newData.isString() && newData.val().length < 1000" - }, - "type": { - ".validate": "newData.val() == 'offer' || newData.val() == 'answer'" +Secure p2p signalling and authentication for [simple-peer](https://github.com/feross/simple-peer) using [firebase realtime database](https://firebase.google.com/docs/database/). + +## Setup firebase + +1. [Create a firebase project and setup the javascript client SDK](https://firebase.google.com/docs/database/web/start). + +2. Add these security rules in the firebase console to secure the signalling data. + + ```json + { + "rules": { + "peers": { + "$uid": { + "$id": { + ".read": "auth != null && auth.uid == $uid", + ".write": "auth != null && auth.uid == $uid", + "$otherUid": { + "$otherId": { + ".read": "auth != null && auth.uid == $otherUid", + ".write": "auth != null && auth.uid == $otherUid", + ".validate": "newData.hasChildren(['sdp', 'type']) || newData.hasChildren(['type', 'error'])", + "sdp": { + ".validate": "newData.isString() && newData.val().length < 4000" + }, + "error": { + ".validate": "newData.isString() && newData.val().length < 1000" + }, + "type": { + ".validate": "newData.val() == 'offer' || newData.val() == 'answer'" + } + } } } } } } } - } -} -``` - -Signaling data is exchanged in `/peers/$uid/$id/$otherUid/$otherId`. - -Security rules ensure that only the intended users can exchange signalling data and the signals are valid. + ``` -- https://firebase.google.com/docs/database/security + Signaling data is exchanged in `/peers/$uid/$id/$otherUid/$otherId`. Security rules ensure that only the intended users can access signalling data and the signals are valid. -### enable sign-in method + > Shortcut: `https://console.firebase.google.com/project//database/rules` -By default, firebase does not enable any sign-in method. You will have to enable one in the firebase console. Right now, firebase supports Email/Password, Phone, Google, Facebook, Twitter, Github. -Firepeer requires authentication so at the very least you have to select [Anonymous authentication](https://firebase.google.com/docs/auth/web/anonymous-auth). +3. Enable your prefered sign-in method in the firebase console. Firepeer requires authentication so at the very least you have to select [anonymous authentication](https://firebase.google.com/docs/auth/web/anonymous-auth). -- https://firebase.google.com/docs/auth/web/start + > Shortcut: `https://console.firebase.google.com/project//authentication/providers` -### install +### Install ```js npm install --save firepeer ``` @@ -68,7 +56,7 @@ npm install --save firepeer ``` -### use firepeer +### Usage ```javascript //alice side @@ -79,7 +67,7 @@ firebase.initializeApp({ const alice = new FirePeer(firebase); -console.log(alice.id) // client id of alice +console.log(alice.id) // peer id of alice //authenticate with the sign-in method you enabled in the console await firebase.auth().signInWith*() @@ -104,12 +92,12 @@ const bob = new FirePeer({ app: firebase.app() }); -console.log(bob.id) // client id of bob +console.log(bob.id) // id //authenticate await firebase.auth().signInWith*() -console.log(bob.uid) // uid of bob +console.log(bob.uid) // peer id of bob // wait for connection and receive message bob.on('connection', (connection)=>{ @@ -119,13 +107,8 @@ bob.on('connection', (connection)=>{ }) ``` -Connections are just instances of [SimplePeer](https://github.com/feross/simple-peer#api) already connected! - -## API Reference - -https://natzcam.github.io/firepeer +Connections are just instances of [simple-peer](https://github.com/feross/simple-peer#api) already connected! -## Demo +## [Reference](https://natzcam.github.io/firepeer) -- https://firepeer-demo.firebaseapp.com -- https://github.com/natzcam/firepeer-demo +## [Demo](https://firepeer-demo.firebaseapp.com) diff --git a/TODO b/TODO deleted file mode 100644 index a95809e..0000000 --- a/TODO +++ /dev/null @@ -1,3 +0,0 @@ -test cleanup -test non-happy path -validation rules \ No newline at end of file diff --git a/docs/assets/js/search.js b/docs/assets/js/search.js index 4e020f3..960b7e7 100644 --- a/docs/assets/js/search.js +++ b/docs/assets/js/search.js @@ -1,3 +1,3 @@ var typedoc = typedoc || {}; typedoc.search = typedoc.search || {}; - typedoc.search.data = {"kinds":{"128":"Class","256":"Interface","512":"Constructor","1024":"Property","2048":"Method"},"rows":[{"id":0,"kind":256,"name":"FirePeerInstance","url":"interfaces/firepeerinstance.html","classes":"tsd-kind-interface"},{"id":1,"kind":1024,"name":"initiatorUid","url":"interfaces/firepeerinstance.html#initiatoruid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":2,"kind":1024,"name":"initiatorId","url":"interfaces/firepeerinstance.html#initiatorid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":3,"kind":1024,"name":"receiverUid","url":"interfaces/firepeerinstance.html#receiveruid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":4,"kind":1024,"name":"receiverId","url":"interfaces/firepeerinstance.html#receiverid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":5,"kind":256,"name":"Signal","url":"interfaces/signal.html","classes":"tsd-kind-interface"},{"id":6,"kind":1024,"name":"type","url":"interfaces/signal.html#type","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"Signal"},{"id":7,"kind":1024,"name":"error","url":"interfaces/signal.html#error","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"Signal"},{"id":8,"kind":1024,"name":"sdp","url":"interfaces/signal.html#sdp","classes":"tsd-kind-property tsd-parent-kind-interface tsd-is-inherited","parent":"Signal"},{"id":9,"kind":1024,"name":"candidate","url":"interfaces/signal.html#candidate","classes":"tsd-kind-property tsd-parent-kind-interface tsd-is-inherited","parent":"Signal"},{"id":10,"kind":256,"name":"FirePeerOptions","url":"interfaces/firepeeroptions.html","classes":"tsd-kind-interface"},{"id":11,"kind":1024,"name":"id","url":"interfaces/firepeeroptions.html#id","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":12,"kind":1024,"name":"spOpts","url":"interfaces/firepeeroptions.html#spopts","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":13,"kind":1024,"name":"onOffer","url":"interfaces/firepeeroptions.html#onoffer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":14,"kind":1024,"name":"onAnswer","url":"interfaces/firepeeroptions.html#onanswer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":15,"kind":1024,"name":"sendOffer","url":"interfaces/firepeeroptions.html#sendoffer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":16,"kind":1024,"name":"sendAnswer","url":"interfaces/firepeeroptions.html#sendanswer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":17,"kind":128,"name":"FirePeer","url":"classes/firepeer.html","classes":"tsd-kind-class"},{"id":18,"kind":2048,"name":"on","url":"classes/firepeer.html#on","classes":"tsd-kind-method tsd-parent-kind-class tsd-is-overwrite","parent":"FirePeer"},{"id":19,"kind":1024,"name":"id","url":"classes/firepeer.html#id","classes":"tsd-kind-property tsd-parent-kind-class","parent":"FirePeer"},{"id":20,"kind":1024,"name":"uid","url":"classes/firepeer.html#uid","classes":"tsd-kind-property tsd-parent-kind-class","parent":"FirePeer"},{"id":21,"kind":512,"name":"constructor","url":"classes/firepeer.html#constructor","classes":"tsd-kind-constructor tsd-parent-kind-class","parent":"FirePeer"},{"id":22,"kind":2048,"name":"connect","url":"classes/firepeer.html#connect","classes":"tsd-kind-method tsd-parent-kind-class","parent":"FirePeer"}]}; \ No newline at end of file + typedoc.search.data = {"kinds":{"128":"Class","256":"Interface","512":"Constructor","1024":"Property","2048":"Method","65536":"Type literal","4194304":"Type alias"},"rows":[{"id":0,"kind":256,"name":"FirePeerInstance","url":"interfaces/firepeerinstance.html","classes":"tsd-kind-interface"},{"id":1,"kind":1024,"name":"initiatorUid","url":"interfaces/firepeerinstance.html#initiatoruid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":2,"kind":1024,"name":"initiatorId","url":"interfaces/firepeerinstance.html#initiatorid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":3,"kind":1024,"name":"receiverUid","url":"interfaces/firepeerinstance.html#receiveruid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":4,"kind":1024,"name":"receiverId","url":"interfaces/firepeerinstance.html#receiverid","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerInstance"},{"id":5,"kind":256,"name":"Signal","url":"interfaces/signal.html","classes":"tsd-kind-interface"},{"id":6,"kind":1024,"name":"type","url":"interfaces/signal.html#type","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"Signal"},{"id":7,"kind":1024,"name":"error","url":"interfaces/signal.html#error","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"Signal"},{"id":8,"kind":1024,"name":"sdp","url":"interfaces/signal.html#sdp","classes":"tsd-kind-property tsd-parent-kind-interface tsd-is-inherited","parent":"Signal"},{"id":9,"kind":1024,"name":"candidate","url":"interfaces/signal.html#candidate","classes":"tsd-kind-property tsd-parent-kind-interface tsd-is-inherited","parent":"Signal"},{"id":10,"kind":256,"name":"FirePeerOptions","url":"interfaces/firepeeroptions.html","classes":"tsd-kind-interface"},{"id":11,"kind":1024,"name":"id","url":"interfaces/firepeeroptions.html#id","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":12,"kind":1024,"name":"spOpts","url":"interfaces/firepeeroptions.html#spopts","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":13,"kind":1024,"name":"onOffer","url":"interfaces/firepeeroptions.html#onoffer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":14,"kind":1024,"name":"onAnswer","url":"interfaces/firepeeroptions.html#onanswer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":15,"kind":1024,"name":"sendOffer","url":"interfaces/firepeeroptions.html#sendoffer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":16,"kind":1024,"name":"sendAnswer","url":"interfaces/firepeeroptions.html#sendanswer","classes":"tsd-kind-property tsd-parent-kind-interface","parent":"FirePeerOptions"},{"id":17,"kind":128,"name":"FirePeer","url":"classes/firepeer.html","classes":"tsd-kind-class"},{"id":18,"kind":2048,"name":"on","url":"classes/firepeer.html#on","classes":"tsd-kind-method tsd-parent-kind-class tsd-is-overwrite","parent":"FirePeer"},{"id":19,"kind":1024,"name":"id","url":"classes/firepeer.html#id","classes":"tsd-kind-property tsd-parent-kind-class","parent":"FirePeer"},{"id":20,"kind":1024,"name":"uid","url":"classes/firepeer.html#uid","classes":"tsd-kind-property tsd-parent-kind-class","parent":"FirePeer"},{"id":21,"kind":512,"name":"constructor","url":"classes/firepeer.html#constructor","classes":"tsd-kind-constructor tsd-parent-kind-class","parent":"FirePeer"},{"id":22,"kind":2048,"name":"connect","url":"classes/firepeer.html#connect","classes":"tsd-kind-method tsd-parent-kind-class","parent":"FirePeer"},{"id":23,"kind":4194304,"name":"SignalInterceptor","url":"index.html#signalinterceptor","classes":"tsd-kind-type-alias"},{"id":24,"kind":65536,"name":"__type","url":"index.html#signalinterceptor.__type","classes":"tsd-kind-type-literal tsd-parent-kind-type-alias tsd-is-not-exported","parent":"SignalInterceptor"}]}; \ No newline at end of file diff --git a/docs/classes/firepeer.html b/docs/classes/firepeer.html index f395b3f..cc30c60 100644 --- a/docs/classes/firepeer.html +++ b/docs/classes/firepeer.html @@ -1,28 +1,885 @@ - + FirePeer | firepeer - +
-
-
-
-
+
-
-
-
-
+
+
+
+
+

Secure p2p signalling and authentication for simple-peer + using firebase realtime database.

+
+
+
+
+

Hierarchy

+
    +
  • + EventEmitter +
      +
    • + FirePeer +
    • +
    +
  • +
+
+
+

Index

+
+
+
+

Constructors

+ +
+
+

Properties

+ +
+
+

Methods

+ +
-
-

Hierarchy

-
    -
  • - EventEmitter -
      +
+
+

Constructors

+
+ +

constructor

+ +
    +
  • + +
    +
    +

    Parameters

    +
    • - FirePeer +
      fbaseOrApp: App | any
      +
      +
      +

      Configured firebase instance or a specific firebase app if you have configured multiple apps.

      +
      +
      +
    • +
    • +
      Default value options: FirePeerOptions = {}
    +

    Returns FirePeer

-
-

Index

-
-
-
-

Constructors

- -
-
-

Properties

- -
-
-

Methods

- -
+
+
+

Properties

+
+ +

id

+
id: string
+ +
+
+

A unique string identifying this peer from other peers. Used as the id parameter in FirePeer.connect.

-
+
-
-

Constructors

-
- -

constructor

- -
-
-

Properties

-
- -

id

-
id: string
- -
-
- -

Optional uid

-
uid: string | null
- -
+ +
+
+

A unique string assigned by firebase when in authenticated state. This identifies the current user within firebase. + Used as the uid parameter in FirePeer.connect.

+
+
-
-

Methods

-
- -

connect

- - -
-
- -

on

-
    -
  • on(event: "connection", listener: function): this
  • -
  • on(event: "loggedin" | "loggedout", listener: function): this
  • -
  • on(event: "error", listener: function): this
  • -
-
    -
  • - -

    Parameters

    -
      -
    • -
      event: "connection"
      -
    • -
    • -
      listener: function
      - -
    • -
    -

    Returns this

    -
  • -
  • - -

    Parameters

    -
      -
    • -
      event: "loggedin" | "loggedout"
      -
    • -
    • -
      listener: function
      -
        -
      • -
          -
        • (): void
        • -
        -
          -
        • -

          Returns void

          -
        • -
        -
      • -
      -
    • -
    -

    Returns this

    -
  • -
  • - -

    Parameters

    -
      -
    • -
      event: "error"
      -
    • -
    • -
      listener: function
      -
        -
      • -
          -
        • (err: Error): void
        • -
        -
          -
        • -

          Parameters

          -
            -
          • -
            err: Error
            -
          • -
          -

          Returns void

          -
        • -
        -
      • -
      -
    • +
+
+

Methods

+
+ +

connect

+ + -
-
-
- -
-
-
-
-

Legend

-
-
    -
  • Module
  • -
  • Object literal
  • -
  • Variable
  • -
  • Function
  • -
  • Function with type parameter
  • -
  • Index signature
  • -
  • Type alias
  • -
-
    -
  • Enumeration
  • -
  • Enumeration member
  • -
  • Property
  • -
  • Method
  • -
-
    -
  • Interface
  • -
  • Interface with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Index signature
  • -
-
    -
  • Class
  • -
  • Class with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Accessor
  • -
  • Index signature
  • -
-
    -
  • Inherited constructor
  • -
  • Inherited property
  • -
  • Inherited method
  • -
  • Inherited accessor
  • -
-
    -
  • Protected property
  • -
  • Protected method
  • -
  • Protected accessor
  • -
-
    -
  • Private property
  • -
  • Private method
  • -
  • Private accessor
  • -
-
    -
  • Static property
  • -
  • Static method
  • -
+ + +
+
+

Legend

+
+
    +
  • Module
  • +
  • Object literal
  • +
  • Variable
  • +
  • Function
  • +
  • Function with type parameter
  • +
  • Index signature
  • +
  • Type alias
  • +
+
    +
  • Enumeration
  • +
  • Enumeration member
  • +
  • Property
  • +
  • Method
  • +
+
    +
  • Interface
  • +
  • Interface with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Index signature
  • +
+
    +
  • Class
  • +
  • Class with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Accessor
  • +
  • Index signature
  • +
+
    +
  • Inherited constructor
  • +
  • Inherited property
  • +
  • Inherited method
  • +
  • Inherited accessor
  • +
+
    +
  • Protected property
  • +
  • Protected method
  • +
  • Protected accessor
  • +
+
    +
  • Private property
  • +
  • Private method
  • +
  • Private accessor
  • +
+
    +
  • Static property
  • +
  • Static method
  • +
+
+
+
+
+

Generated using TypeDoc

-
-
-

Generated using TypeDoc

-
- - + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 7f38a68..e979c5e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,28 +1,885 @@ - + - firepeer + firepeer | firepeer - +
-
-
-
- -

firepeer

-
-
+
-
-
-
-

Index

-
-
-
-

Classes

-
+ + +
-
- -
-
-
-
-

Legend

-
-
    -
  • Module
  • -
  • Object literal
  • -
  • Variable
  • -
  • Function
  • -
  • Function with type parameter
  • -
  • Index signature
  • -
  • Type alias
  • -
-
    -
  • Enumeration
  • -
  • Enumeration member
  • -
  • Property
  • -
  • Method
  • -
-
    -
  • Interface
  • -
  • Interface with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Index signature
  • -
-
    -
  • Class
  • -
  • Class with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Accessor
  • -
  • Index signature
  • -
-
    -
  • Inherited constructor
  • -
  • Inherited property
  • -
  • Inherited method
  • -
  • Inherited accessor
  • -
-
    -
  • Protected property
  • -
  • Protected method
  • -
  • Protected accessor
  • -
-
    -
  • Private property
  • -
  • Private method
  • -
  • Private accessor
  • -
-
    -
  • Static property
  • -
  • Static method
  • -
+ +
+
+

Legend

+
+
    +
  • Module
  • +
  • Object literal
  • +
  • Variable
  • +
  • Function
  • +
  • Function with type parameter
  • +
  • Index signature
  • +
  • Type alias
  • +
+
    +
  • Enumeration
  • +
  • Enumeration member
  • +
  • Property
  • +
  • Method
  • +
+
    +
  • Interface
  • +
  • Interface with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Index signature
  • +
+
    +
  • Class
  • +
  • Class with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Accessor
  • +
  • Index signature
  • +
+
    +
  • Inherited constructor
  • +
  • Inherited property
  • +
  • Inherited method
  • +
  • Inherited accessor
  • +
+
    +
  • Protected property
  • +
  • Protected method
  • +
  • Protected accessor
  • +
+
    +
  • Private property
  • +
  • Private method
  • +
  • Private accessor
  • +
+
    +
  • Static property
  • +
  • Static method
  • +
+
+
+
+
+

Generated using TypeDoc

-
-
-

Generated using TypeDoc

-
- - + \ No newline at end of file diff --git a/docs/interfaces/firepeerinstance.html b/docs/interfaces/firepeerinstance.html index e955be1..03bb6b9 100644 --- a/docs/interfaces/firepeerinstance.html +++ b/docs/interfaces/firepeerinstance.html @@ -1,28 +1,885 @@ - + FirePeerInstance | firepeer - +
-
-
-
-
+
-
-
-
-
+
+
+
+
+

The firepeer instance, just a simple-peer + instance in connected state.

-
-
-

Hierarchy

-
    -
  • - Instance -
      -
    • - FirePeerInstance -
    • +
+
+
+

Hierarchy

+
    +
  • + Instance +
      +
    • + FirePeerInstance +
    • +
    +
  • +
+
+
+

Implements

+
    +
  • ReadableStream
  • +
  • Writable
  • +
+
+
+

Index

+
+
+
+

Properties

+ - - +
+
-
-

Implements

-
    -
  • ReadableStream
  • -
  • Writable
  • -
+
+
+

Properties

+
+ +

initiatorId

+
initiatorId: string | null
+
-
-

Index

-
-
-
-

Properties

- -
-
-
+
+ +

initiatorUid

+
initiatorUid: string | null
+
-
-

Properties

-
- -

initiatorId

-
initiatorId: string | null
- -
-
- -

initiatorUid

-
initiatorUid: string | null
- -
-
- -

receiverId

-
receiverId: string | null
- -
-
- -

receiverUid

-
receiverUid: string | null
- -
+
+ +

receiverId

+
receiverId: string | null
+
-
- -
-
-
-
-

Legend

-
-
    -
  • Module
  • -
  • Object literal
  • -
  • Variable
  • -
  • Function
  • -
  • Function with type parameter
  • -
  • Index signature
  • -
  • Type alias
  • -
-
    -
  • Enumeration
  • -
  • Enumeration member
  • -
  • Property
  • -
  • Method
  • -
-
    -
  • Interface
  • -
  • Interface with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Index signature
  • -
-
    -
  • Class
  • -
  • Class with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Accessor
  • -
  • Index signature
  • -
-
    -
  • Inherited constructor
  • -
  • Inherited property
  • -
  • Inherited method
  • -
  • Inherited accessor
  • -
-
    -
  • Protected property
  • -
  • Protected method
  • -
  • Protected accessor
  • -
-
    -
  • Private property
  • -
  • Private method
  • -
  • Private accessor
  • -
-
    -
  • Static property
  • -
  • Static method
  • -
+
+ +

receiverUid

+
receiverUid: string | null
+ +
+ +
+
+

Legend

+
+
    +
  • Module
  • +
  • Object literal
  • +
  • Variable
  • +
  • Function
  • +
  • Function with type parameter
  • +
  • Index signature
  • +
  • Type alias
  • +
+
    +
  • Enumeration
  • +
  • Enumeration member
  • +
  • Property
  • +
  • Method
  • +
+
    +
  • Interface
  • +
  • Interface with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Index signature
  • +
+
    +
  • Class
  • +
  • Class with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Accessor
  • +
  • Index signature
  • +
+
    +
  • Inherited constructor
  • +
  • Inherited property
  • +
  • Inherited method
  • +
  • Inherited accessor
  • +
+
    +
  • Protected property
  • +
  • Protected method
  • +
  • Protected accessor
  • +
+
    +
  • Private property
  • +
  • Private method
  • +
  • Private accessor
  • +
+
    +
  • Static property
  • +
  • Static method
  • +
+
+
+
+
+

Generated using TypeDoc

-
-
-

Generated using TypeDoc

-
- - + \ No newline at end of file diff --git a/docs/interfaces/firepeeroptions.html b/docs/interfaces/firepeeroptions.html index ad8faba..c054240 100644 --- a/docs/interfaces/firepeeroptions.html +++ b/docs/interfaces/firepeeroptions.html @@ -1,28 +1,885 @@ - + FirePeerOptions | firepeer - +
-
-
-
-
+
-
-
-
-

Hierarchy

-
    -
  • - FirePeerOptions -
  • -
+
+
+

Hierarchy

+
    +
  • + FirePeerOptions +
  • +
+
+
+

Index

+
+
+
+

Properties

+ +
+
-
-

Index

-
-
-
-

Properties

- -
+
+
+

Properties

+
+ +

Optional id

+
id: undefined | string
+ +
+
+

The peer id to be used. Should be unique. If not specified, then a generated one will be used.

-
+
-
-

Properties

-
- -

Optional id

-
id: undefined | string
- -
-
- -

Optional onAnswer

-
onAnswer: undefined | function
- -
-
- -

Optional onOffer

-
onOffer: undefined | function
- -
-
- -

Optional sendAnswer

-
sendAnswer: undefined | function
- -
-
- -

Optional sendOffer

-
sendOffer: undefined | function
- -
-
- -

Optional spOpts

-
spOpts: SimplePeer.Options
- -
+
+ +

Optional onAnswer

+ + +
+
+

SignalInterceptor called when an answer is received from the receiver.

+
+
-
- -
-
-
-
-

Legend

-
-
    -
  • Module
  • -
  • Object literal
  • -
  • Variable
  • -
  • Function
  • -
  • Function with type parameter
  • -
  • Index signature
  • -
  • Type alias
  • -
-
    -
  • Enumeration
  • -
  • Enumeration member
  • -
  • Property
  • -
  • Method
  • -
-
    -
  • Interface
  • -
  • Interface with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Index signature
  • -
-
    -
  • Class
  • -
  • Class with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Accessor
  • -
  • Index signature
  • -
-
    -
  • Inherited constructor
  • -
  • Inherited property
  • -
  • Inherited method
  • -
  • Inherited accessor
  • -
-
    -
  • Protected property
  • -
  • Protected method
  • -
  • Protected accessor
  • -
-
    -
  • Private property
  • -
  • Private method
  • -
  • Private accessor
  • -
-
    -
  • Static property
  • -
  • Static method
  • -
+
+ +

Optional onOffer

+ + +
+
+

SignalInterceptor called when an offer is received from the initiator.

+
+
+
+
+ +

Optional sendAnswer

+
sendAnswer: SignalInterceptor
+ +
+
+

SignalInterceptor called when an answer is about to be sent by the receiver.

+
+
+
+
+ +

Optional sendOffer

+ + +
+
+

SignalInterceptor called when an offer is about to be sent by the initiator.

+
+
+
+
+ +

Optional spOpts

+
spOpts: SimplePeer.Options
+ +
+
+

Simple-peer constructor options.

+
+
+
+ +
+
+

Legend

+
+
    +
  • Module
  • +
  • Object literal
  • +
  • Variable
  • +
  • Function
  • +
  • Function with type parameter
  • +
  • Index signature
  • +
  • Type alias
  • +
+
    +
  • Enumeration
  • +
  • Enumeration member
  • +
  • Property
  • +
  • Method
  • +
+
    +
  • Interface
  • +
  • Interface with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Index signature
  • +
+
    +
  • Class
  • +
  • Class with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Accessor
  • +
  • Index signature
  • +
+
    +
  • Inherited constructor
  • +
  • Inherited property
  • +
  • Inherited method
  • +
  • Inherited accessor
  • +
+
    +
  • Protected property
  • +
  • Protected method
  • +
  • Protected accessor
  • +
+
    +
  • Private property
  • +
  • Private method
  • +
  • Private accessor
  • +
+
    +
  • Static property
  • +
  • Static method
  • +
+
+
+
+
+

Generated using TypeDoc

-
-
-

Generated using TypeDoc

-
- - + \ No newline at end of file diff --git a/docs/interfaces/signal.html b/docs/interfaces/signal.html index 82f6c20..d458f6d 100644 --- a/docs/interfaces/signal.html +++ b/docs/interfaces/signal.html @@ -1,28 +1,885 @@ - + Signal | firepeer - +
-
-
-
-
+
-
-
-
-

Hierarchy

-
    -
  • - SignalData -
      -
    • - Signal -
    • +
      +
      +
      +
      +

      Represents p2p signalling data. error is specific to firepeer and enables passing error information.

      +
      +
      +
      +
      +

      Hierarchy

      +
        +
      • + SignalData +
          +
        • + Signal +
        • +
        +
      • +
      +
      +
      +

      Index

      +
      +
      +
      +

      Properties

      + - -
    +
+
-
-

Index

-
-
-
-

Properties

- -
-
-
+
+
+

Properties

+
+ +

Optional candidate

+
candidate: any
+
-
-

Properties

-
- -

Optional candidate

-
candidate: any
- -
-
- -

Optional error

-
error: undefined | string
- -
-
- -

Optional sdp

-
sdp: any
- -
-
- -

type

-
type: "offer" | "answer"
- -
+
+ +

Optional error

+
error: undefined | string
+
-
- -
- -
-
-

Legend

-
-
    -
  • Module
  • -
  • Object literal
  • -
  • Variable
  • -
  • Function
  • -
  • Function with type parameter
  • -
  • Index signature
  • -
  • Type alias
  • -
-
    -
  • Enumeration
  • -
  • Enumeration member
  • -
  • Property
  • -
  • Method
  • -
-
    -
  • Interface
  • -
  • Interface with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Index signature
  • -
-
    -
  • Class
  • -
  • Class with type parameter
  • -
  • Constructor
  • -
  • Property
  • -
  • Method
  • -
  • Accessor
  • -
  • Index signature
  • -
-
    -
  • Inherited constructor
  • -
  • Inherited property
  • -
  • Inherited method
  • -
  • Inherited accessor
  • -
-
    -
  • Protected property
  • -
  • Protected method
  • -
  • Protected accessor
  • -
-
    -
  • Private property
  • -
  • Private method
  • -
  • Private accessor
  • -
-
    -
  • Static property
  • -
  • Static method
  • -
+
+ +

Optional sdp

+
sdp: any
+ +
+
+ +

type

+
type: "offer" | "answer"
+ +
+ +
+
+

Legend

+
+
    +
  • Module
  • +
  • Object literal
  • +
  • Variable
  • +
  • Function
  • +
  • Function with type parameter
  • +
  • Index signature
  • +
  • Type alias
  • +
+
    +
  • Enumeration
  • +
  • Enumeration member
  • +
  • Property
  • +
  • Method
  • +
+
    +
  • Interface
  • +
  • Interface with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Index signature
  • +
+
    +
  • Class
  • +
  • Class with type parameter
  • +
  • Constructor
  • +
  • Property
  • +
  • Method
  • +
  • Accessor
  • +
  • Index signature
  • +
+
    +
  • Inherited constructor
  • +
  • Inherited property
  • +
  • Inherited method
  • +
  • Inherited accessor
  • +
+
    +
  • Protected property
  • +
  • Protected method
  • +
  • Protected accessor
  • +
+
    +
  • Private property
  • +
  • Private method
  • +
  • Private accessor
  • +
+
    +
  • Static property
  • +
  • Static method
  • +
+
+
+
+
+

Generated using TypeDoc

-
-
-

Generated using TypeDoc

-
- - + \ No newline at end of file diff --git a/src/firepeer.ts b/src/firepeer.ts index d622185..fd9fb83 100644 --- a/src/firepeer.ts +++ b/src/firepeer.ts @@ -5,6 +5,9 @@ import * as SimplePeer from 'simple-peer'; import debug from './debug'; /** + * The firepeer instance, just a [simple-peer](https://github.com/feross/simple-peer#api) + * instance in connected state. + * * @noInheritDoc */ export interface FirePeerInstance extends SimplePeer.Instance { @@ -13,31 +16,82 @@ export interface FirePeerInstance extends SimplePeer.Instance { receiverUid: string | null; receiverId: string | null; } + +/** + * Represents p2p signalling data. `error` is specific to firepeer and enables passing error information. + */ export interface Signal extends SimplePeer.SignalData { type: 'offer' | 'answer'; error?: string; } +/** + * Intercepts signals to/from firepeer instances. + * For the signalling to proceed, firepeer expects the function to return a + * Promise resolving to a signal or a plain signal. + * Otherwise, return null or a promise rejection. + */ +export type SignalInterceptor = (signal: Signal) => Promise | Signal; + export interface FirePeerOptions { + /** + * The peer id to be used. Should be unique. If not specified, then a generated one will be used. + */ id?: string; + /** + * Simple-peer [constructor options](https://github.com/feross/simple-peer#api). + */ spOpts?: SimplePeer.Options; - onOffer?: (signal: Signal) => Promise | Signal; - onAnswer?: (signal: Signal) => Promise | Signal; - sendOffer?: (signal: Signal) => Promise | Signal; - sendAnswer?: (signal: Signal) => Promise | Signal; + /** + * [[SignalInterceptor]] called when an offer is received from the initiator. + */ + onOffer?: SignalInterceptor; + /** + * [[SignalInterceptor]] called when an answer is received from the receiver. + */ + onAnswer?: SignalInterceptor; + /** + * [[SignalInterceptor]] called when an offer is about to be sent by the initiator. + */ + sendOffer?: SignalInterceptor; + /** + * [[SignalInterceptor]] called when an answer is about to be sent by the receiver. + */ + sendAnswer?: SignalInterceptor; } export declare interface FirePeer { + /** + * Triggered when a new connection is established either initiated by you through [[FirePeer.connect]] + * or initiated by another peer. + */ on(event: 'connection', listener: (peer: FirePeerInstance) => void): this; + /** + * Triggered when firebase auth state has changed. Firepeer only works if firebase is in authenticated state + * ([[FirePeer.uid]] is not null). + */ on(event: 'loggedin' | 'loggedout', listener: () => void): this; + /** + * Triggered when an error happens in the signalling process. + */ on(event: 'error', listener: (err: Error) => void): this; } /** + * Secure p2p signalling and authentication for [simple-peer](https://github.com/feross/simple-peer) + * using [firebase realtime database](https://firebase.google.com/docs/database/). + * * @noInheritDoc */ export class FirePeer extends EventEmitter { + /** + * A unique string identifying this peer from other peers. Used as the `id` parameter in [[FirePeer.connect]]. + */ public id: string; + /** + * A unique string assigned by firebase when in authenticated state. This identifies the current user within firebase. + * Used as the `uid` parameter in [[FirePeer.connect]]. + */ public uid?: string | null; private app: firebase.app.App; private refs: firebase.database.Reference[] = []; @@ -47,7 +101,14 @@ export class FirePeer extends EventEmitter { private sendOffer: (signal: Signal) => Promise | Signal; private sendAnswer: (signal: Signal) => Promise | Signal; - constructor(fbaseOrApp: any, options: FirePeerOptions = {}) { + /** + * + * @param fbaseOrApp Configured firebase instance or a specific firebase app if you have configured multiple apps. + */ + constructor( + fbaseOrApp: firebase.app.App | any, + options: FirePeerOptions = {} + ) { super(); this.app = fbaseOrApp as firebase.app.App; @@ -79,6 +140,9 @@ export class FirePeer extends EventEmitter { }); } + /** + * Connect to a peer identified by a user id and peer id. Returns a promise that resolves to a [[FirePeerInstance]]. + */ public connect(uid: string, id: string): Promise { return new Promise((resolve, reject) => { const connectPeer = () => {