crisp-api 6.4.0 → 7.0.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 Changelog
 =========
 
+## v7.0.0
+
+### Breaking Changes
+
+* ⚠️ Renamed the `CrispClient.rebind` method into `CrispClient.rebindSocket` (update your code if you use it).
+
+### New Features
+
+* Added support for receiving Web Hooks through the RTM events pipeline (via `CrispClient.setRtmMode(Crisp.RTM_MODES.WebHooks)`).
+
+## v6.4.1
+
+### Bug Fixes
+
+* Return more informative error reasons for non `2xx / 3xx` response codes on `HEAD` requests.
+
 ## v6.4.0
 
 ### New Features
@@ -18,7 +34,7 @@ Changelog
 
 ### Breaking Changes
 
-* Support for NodeJS 8 has been removed. The minimum version is now NodeJS 10.
+* ⚠️ Support for NodeJS 8 has been removed. The minimum version is now NodeJS 10.
 
 ### Changes
 
@@ -48,8 +64,8 @@ Changelog
 
 ### Breaking Changes
 
-* Support for NodeJS 6 has been removed. The minimum version is now NodeJS 8.
-* The `CrispClient.on` method now returns a `Promise`. Please update your code accordingly. We do recommend that you add error catchers.
+* ⚠️ Support for NodeJS 6 has been removed. The minimum version is now NodeJS 8.
+* ⚠️ The `CrispClient.on` method now returns a `Promise`. Please update your code accordingly. We do recommend that you add error catchers.
 
 ### New Features
 
@@ -105,7 +121,7 @@ Changelog
 
 ### Breaking Changes
 
-* The package has been renamed from `node-crisp-api` to `crisp-api`. Since it is typical of NPM packages to skip the `node-` prefix in their name, we chose to normalize the package name to this community standard. The programmatic API did not change, so you can simply update the package name to the new name in your `package.json` and all imports.
+* ⚠️ The package has been renamed from `node-crisp-api` to `crisp-api`. Since it is typical of NPM packages to skip the `node-` prefix in their name, we chose to normalize the package name to this community standard. The programmatic API did not change, so you can simply update the package name to the new name in your `package.json` and all imports.
 
 ## v4.2.0
 
@@ -141,14 +157,14 @@ Changelog
 
 ### Breaking Changes
 
-**⚠️ Major changes follow, that will likely require that you update your integration code. If you want to wait to apply those changes, we recommend that you pin `node-crisp-api` to `3.0.0` or lower in your `package.json`.**
+**🆘 Major changes follow, that will likely require that you update your integration code. If you want to wait to apply those changes, we recommend that you pin `node-crisp-api` to `3.0.0` or lower in your `package.json`.**
 
-* All resource methods have been nested into their parent category, eg. `website`. So all calls to eg. `CrispClient.websiteConversation` or `CrispClient.websitePeople` become `CrispClient.website`. This makes API calls more readable throughout your code.
+* ⚠️ All resource methods have been nested into their parent category, eg. `website`. So all calls to eg. `CrispClient.websiteConversation` or `CrispClient.websitePeople` become `CrispClient.website`. This makes API calls more readable throughout your code.
 
 ## v3.0.0
 
 ### Breaking Changes
 
-**⚠️ Major changes follow, that will likely require that you update your integration code. If you want to wait to apply those changes, we recommend that you pin `node-crisp-api` to `2.0.0` or lower in your `package.json`.**
+**🆘 Major changes follow, that will likely require that you update your integration code. If you want to wait to apply those changes, we recommend that you pin `node-crisp-api` to `2.0.0` or lower in your `package.json`.**
 
-* The programmatic interface to `node-crisp-api` has been completely revamped, so that all REST API methods specified in [REST API Reference (V1)](https://docs.crisp.chat/references/rest-api/v1/) are also available in this wrapper. Most method names have been changed as to match their name in the reference. Please check the [README](./README.md) for a full list of available methods.
+* ⚠️ The programmatic interface to `node-crisp-api` has been completely revamped, so that all REST API methods specified in [REST API Reference (V1)](https://docs.crisp.chat/references/rest-api/v1/) are also available in this wrapper. Most method names have been changed as to match their name in the reference. Please check the [README](./README.md) for a full list of available methods.

package/README.md

@@ -142,7 +142,7 @@ All methods that you will most likely need when building a Crisp integration are
 </details>
 <details>
   <summary>
-  <a href="#plugin">RTM Events</a>
+  <a href="#realtime-events">RTM Events</a>
   </summary>
   <ul>
     <li><a href="#session--reference">Session Events</a></li>
@@ -2399,10 +2399,42 @@ _👉 Notice: The `peopleID` argument can be an email or the `peopleID`._
 
 You can bind to realtime events from Crisp, in order to get notified of incoming messages and updates in websites.
 
-Before you start with RTM events, please consider the following:
+You won't receive any event if you don't explicitly subscribe to realtime events, as the library doesn't connect to the realtime backend automatically.
+
+**There are two ways to receive realtime events:**
+
+1. Using Web Hooks (**⭐ recommended**)
+2. Using WebSockets with the RTM API
+
+**Before you start with RTM events, please consider the following:**
 
 * You won't receive any event if you don't explicitly subscribe to realtime events using `CrispClient.on()`, as the library doesn't connect to the realtime backend automatically. This method returns a `Promise` object.
-* Whenever the list of websites that your authentication token is entitled to receive events for changes, you will need to call `CrispClient.rebind()`. This method also returns a `Promise` object.
+* Whenever the list of websites that your authentication token is entitled to receive events for changes, you will need to call `CrispClient.rebindSocket()`. This method also returns a `Promise` object. _This only applies to WebSockets with the RTM API_.
+
+### Receive realtime events
+
+#### Receive events over Web Hooks
+
+To start listening for events and bind a handler, check out the [events over Web Hooks example](https://github.com/crisp-im/node-crisp-api/blob/master/examples/events_webhooks.js).
+
+You will need to adjust your code so that:
+
+1. The RTM events mode is set to Web Hooks: `CrispClient.setRtmMode(Crisp.RTM_MODES.WebHooks)`
+2. Your HTTP endpoint mounts a route listening for POST requests, and upon receiving requests:
+    1. It verifies the requests with: `CrispClient.verifyHook(secret, body, timestamp, signature)`
+    2. It receives the Web Hook with: `CrispClient.receiveHook(body)`
+
+Plugin Web Hooks will need to be configured first for this to work. Check out our [Web Hooks Quickstart guide](https://docs.crisp.chat/guides/web-hooks/quickstart/) and our [Web Hooks Reference](https://docs.crisp.chat/references/web-hooks/v1/) to get started.
+
+#### Receive events over WebSockets (RTM API)
+
+To start listening for events and bind a handler, check out the [events over WebSockets example](https://github.com/crisp-im/node-crisp-api/blob/master/examples/events_websockets.js).
+
+You will need to adjust your code so that:
+
+1. The RTM events mode is set to WebSockets: `CrispClient.setRtmMode(Crisp.RTM_MODES.WebSockets)`
+
+### Available realtime events
 
 Available events are listed below:
 

package/lib/crisp.js

@@ -14,26 +14,41 @@ var pkg           = require("../package.json");
 var got           = require("got");
 
 var URL           = require("url").URL;
+var Crypto        = require("crypto");
 var EventEmitter  = require("fbemitter").EventEmitter;
 
 
+// RTM modes available
+Crisp.RTM_MODES           = {
+  WebSockets : "websockets",
+  WebHooks   : "webhooks"
+};
+
+Crisp.AVAILABLE_RTM_MODES = [
+  Crisp.RTM_MODES.WebSockets,
+  Crisp.RTM_MODES.WebHooks
+];
+
+
 // Base configuration
 Crisp.DEFAULT_REQUEST_TIMEOUT            = 10000;
 Crisp.DEFAULT_SOCKET_TIMEOUT             = 10000;
 Crisp.DEFAULT_SOCKET_RECONNECT_DELAY     = 5000;
 Crisp.DEFAULT_SOCKET_RECONNECT_DELAY_MAX = 10000;
 Crisp.DEFAULT_SOCKET_RECONNECT_FACTOR    = 0.75;
-Crisp.DEFAULT_SOCKET_SCHEDULE            = 500;
+Crisp.DEFAULT_BROKER_SCHEDULE            = 500;
 Crisp.DEFAULT_EVENT_REBIND_INTERVAL_MIN  = 2500;
 Crisp.DEFAULT_USERAGENT_PREFIX           = "node-crisp-api/";
 
 
 // REST API defaults
-Crisp.DEFAULT_REST_HOST        = "https://api.crisp.chat";
-Crisp.DEFAULT_REST_BASE_PATH   = "/v1/";
+Crisp.DEFAULT_REST_HOST      = "https://api.crisp.chat";
+Crisp.DEFAULT_REST_BASE_PATH = "/v1/";
 
 
 // RTM API defaults
+Crisp.DEFAULT_RTM_MODE   = Crisp.RTM_MODES.WebSockets;
+
 Crisp.DEFAULT_RTM_EVENTS = [
   // Session Events
   "session:update_availability",
@@ -162,7 +177,8 @@ function Crisp() {
 
   /** @private */
   this._rtm  = {
-    host : null
+    host : null,
+    mode : Crisp.DEFAULT_RTM_MODE
   };
 
   /** @private */
@@ -175,16 +191,19 @@ function Crisp() {
   this._socket          = null;
 
   /** @private */
-  this._socketScheduler = null;
+  this._loopback        = null;
 
   /** @private */
   this._lastEventRebind = null;
 
   /** @private */
-  this._socketBindHooks = [];
+  this._brokerScheduler = null;
+
+  /** @private */
+  this._brokerBindHooks = [];
 
   /** @private */
-  this._boundEvents     = [];
+  this._boundEvents     = {};
 
   // Prepare
   this._prepareServices();
@@ -193,7 +212,7 @@ function Crisp() {
 
 Crisp.prototype = {
   /**
-   * Set the REST API host
+   * Sets the REST API host
    * @memberof Crisp
    * @method setRestHost
    * @param {string} host - Hostname
@@ -207,7 +226,7 @@ Crisp.prototype = {
   },
 
   /**
-   * Set the RTM API host
+   * Sets the RTM API host
    * @memberof Crisp
    * @method setRtmHost
    * @param {string} host - Hostname
@@ -220,6 +239,23 @@ Crisp.prototype = {
     }
   },
 
+  /**
+   * Sets the RTM channel mode (ie. WebSockets or Web Hooks)
+   * @memberof Crisp
+   * @method setRtmMode
+   * @param {string} mode - RTM mode ('websockets' or 'webhooks')
+   */
+  setRtmMode : function(mode) {
+    if (Crisp.AVAILABLE_RTM_MODES.indexOf(mode) !== -1) {
+      this._rtm.mode = mode;
+    } else {
+      throw new Error(
+        "[Crisp] setRtmMode: parameter mode value should be one of: "  +
+          Crisp.AVAILABLE_RTM_MODES.join(", ")
+      );
+    }
+  },
+
   /**
    * Sets the tier
    * @memberof Crisp
@@ -231,7 +267,7 @@ Crisp.prototype = {
   },
 
   /**
-   * Authenticate
+   * Authenticates
    * @memberof Crisp
    * @method authenticate
    * @param {string} identifier
@@ -247,7 +283,7 @@ Crisp.prototype = {
   },
 
   /**
-   * Authenticate (with tier)
+   * Authenticates (with tier)
    * @memberof Crisp
    * @method authenticateTier
    * @param {string} tier
@@ -368,7 +404,7 @@ Crisp.prototype = {
   },
 
   /**
-   * Bind socket event
+   * Binds RTM event
    * @memberof Crisp
    * @method on
    * @param {string} event
@@ -391,30 +427,41 @@ Crisp.prototype = {
     }
 
     // Important: we do not allow .on() to be called once socket is connected, \
-    //   as we consider event listeners must be bound once all together. This \
-    //   prevents bogous integrations from sending flood of 'socket:bind'` to \
-    //   the RTM API.
-    if (this._socket) {
+    //   or loopback is bound as we consider event listeners must be bound \
+    //   once all together. This prevents bogous integrations from sending \
+    //   flood of 'socket:bind'` to the RTM API, if using WebSockets. Web \
+    //   Hooks follows the same scheme for consistency's sake.
+    if (this._socket || this._loopback) {
       throw new Error(
-        "[Crisp] on: socket is already bound, please bind event earlier on: "  +
-          "'" + event + "'"
+        "[Crisp] on: connector is already bound, please listen to event "  +
+          "earlier on: '" + event + "'"
       );
     }
 
     // Add listener to emitter
     this._emitter.addListener(event, callback);
 
-    // Subscribe event on the socket
-    if (this._boundEvents.indexOf(event) === -1) {
-      this._boundEvents.push(event);
-
-      // Socket not connected? Connect now.
-      return this._prepareSocket(
-        function(socket, emitter) {
-          // Listen for event (once socket is bound)
-          socket.on(event, function(data) {
-            emitter.emit(event, data);
-          });
+    // Subscribe event on the broker
+    if (this._boundEvents[event] !== true) {
+      var rtmMode = this._rtm.mode;
+
+      // Mark event as bound
+      this._boundEvents[event] = true;
+
+      // Broker not connected? Connect now.
+      return this._prepareBroker(
+        function(instance, emitter) {
+          // Listen for event? (once instance is bound)
+          switch (rtmMode) {
+            case Crisp.RTM_MODES.WebSockets: {
+              // Listen on socket event
+              instance.on(event, function(data) {
+                emitter.emit(event, data);
+              });
+
+              break;
+            }
+          }
         }
       );
     }
@@ -423,14 +470,96 @@ Crisp.prototype = {
   },
 
   /**
-   * Rebind socket events
+   * Receives a raw event and dispatches it to the listener (used for Web Hooks)
+   * @memberof Crisp
+   * @method receiveHook
+   * @param {object} body
+   */
+  receiveHook : function(body) {
+    var self = this;
+
+    if (self._loopback) {
+      // Ensure payload is readable
+      if (!body || typeof body !== "object") {
+        return new Error("[Crisp] receiveHook: empty hook payload");
+      }
+
+      // Ensure payload is properly formatted
+      if (!body.event || !body.data  ||
+            typeof body.event !== "string" || typeof body.data !== "object") {
+        return new Error("[Crisp] receiveHook: malformatted hook payload");
+      }
+
+      // Check if event is subscribed to? (in routing table)
+      // Notice: if not in routing table, then silently discard the event w/o \
+      //   any error, as we do not want an HTTP failure status to be sent in \
+      //   response by the implementor.
+      if (self._boundEvents[body.event] !== true) {
+        return null;
+      }
+
+      // Dispatch event to event bus
+      // Notice: go asynchronous, so that the event is processed ASAP and \
+      //   dispatched on the event bus later, as the hook might be received \
+      //   synchronously over HTTP.
+      process.nextTick(function() {
+        self._loopback.emit(body.event, body.data);
+      });
+
+      return null;
+    }
+
+    return new Error("[Crisp] receiveHook: hook loopback not bound");
+  },
+
+  /**
+   * Verifies an event string and checks that signatures match (used for Web \
+   *   Hooks)
+   * @memberof Crisp
+   * @method verifyHook
+   * @param {string} secret
+   * @param {object} body
+   * @param {string} timestamp
+   * @param {string} signature
+   */
+  verifyHook : function(secret, body, timestamp, signature) {
+    if (this._loopback) {
+      // Ensure all provided data is valid
+      if (!secret || !signature || !body || typeof body !== "object"  ||
+            !timestamp || isNaN(timestamp) === true) {
+        return false;
+      }
+
+      // Compute local trace
+      var localTrace = ("[" + timestamp + ";" + JSON.stringify(body) + "]");
+
+      // Create local HMAC
+      var localMac = Crypto.createHmac("sha256", secret);
+
+      localMac.update(localTrace);
+
+      // Compute local signature, and compare
+      var localSignature = localMac.digest("hex");
+
+      return (
+        (signature === localSignature) ? true : false
+      );
+    }
+
+    // Default: not verified (signatures do not match or loopback not /yet?/ \
+    //   bound)
+    return false;
+  },
+
+  /**
+   * Rebinds socket events (used for WebSockets)
    * @memberof Crisp
    * @method rebind
    */
-  rebind : function() {
+  rebindSocket : function() {
     if (!this._socket) {
       throw new Error(
-        "[Crisp] rebind: cannot rebind a socket that is not yet bound"
+        "[Crisp] rebindSocket: cannot rebind a socket that is not yet bound"
       );
     }
 
@@ -442,7 +571,8 @@ Crisp.prototype = {
           ((nowTime - this._lastEventRebind)  <
               Crisp.DEFAULT_EVENT_REBIND_INTERVAL_MIN)) {
       throw new Error(
-        "[Crisp] rebind: cannot rebind, last rebind was requested too recently"
+        "[Crisp] rebindSocket: cannot rebind, last rebind was requested too "  +
+          "recently"
       );
     }
 
@@ -455,14 +585,14 @@ Crisp.prototype = {
   },
 
   /**
-   * Prepare a URI based from path segments
+   * Prepares a URI based from path segments
    * @memberof Crisp
    * @private
    * @method _prepareRestUrl
    * @param {Array} paths - List of paths ['session', 'login']
    */
   _prepareRestUrl : function(paths) {
-    if (Array.isArray(paths)) {
+    if (Array.isArray(paths) === true) {
       var output = this._rest.host + this._rest.basePath;
 
       output += paths.join("/");
@@ -522,38 +652,65 @@ Crisp.prototype = {
   },
 
   /**
-   * Binds socket to the main object
+   * Binds broker to the main object
    * @memberof Crisp
    * @private
-   * @method _prepareSocket
+   * @method _prepareBroker
    * @param {function} fnBindHook
    */
-  _prepareSocket : function(fnBindHook) {
+  _prepareBroker : function(fnBindHook) {
     var self = this;
 
     return new Promise(function(resolve, reject) {
-      var rtmHostOverride = self._rtm.host;
+      var rtmMode         = self._rtm.mode,
+          rtmHostOverride = self._rtm.host;
 
       // Append bind hook to pending stack
-      self._socketBindHooks.push(fnBindHook);
+      self._brokerBindHooks.push(fnBindHook);
 
-      // Make sure to prepare socket once? (defer socket binding, waiting that \
+      // Make sure to prepare broker once? (defer broker binding, waiting that \
       //   all listeners have been bound, that way we submit the list of \
       //   filtered events to the RTM API once, and never again in the future)
-      if (self._socketScheduler === null) {
-        // Socket is already set? We should not even have entered there.
-        if (self._socket) {
+      if (self._brokerScheduler === null) {
+        // Socket or loopback already set? We should not even have entered \
+        //   there.
+        if (self._socket || self._loopback) {
           throw new Error(
-            "[Crisp] prepareSocket: illegal call to prepare socket (tie break)"
+            "[Crisp] prepareBroker: illegal call to prepare broker (tie break)"
           );
         }
 
-        self._socketScheduler = setTimeout(function() {
-          // Connect to socket now
-          self._connectSocket(rtmHostOverride)
-            .then(resolve)
-            .catch(reject);
-        }, Crisp.DEFAULT_SOCKET_SCHEDULE);
+        self._brokerScheduler = setTimeout(function() {
+          switch (rtmMode) {
+            case Crisp.RTM_MODES.WebSockets: {
+              // Connect to socket now
+              // Notice: will unstack broker bind hooks once ready
+              self._connectSocket(rtmHostOverride)
+                .then(resolve)
+                .catch(reject);
+
+              break;
+            }
+
+            case Crisp.RTM_MODES.WebHooks: {
+              // Connect to loopback now
+              self._connectLoopback()
+                .then(resolve)
+                .catch(reject);
+
+              break;
+            }
+
+            default: {
+              var unsupportedError = new Error(
+                "[Crisp] prepareBroker: mode of RTM broker unsupported "  +
+                  "('" + rtmMode + "')"
+              );
+
+              reject(unsupportedError);
+            }
+          }
+        }, Crisp.DEFAULT_BROKER_SCHEDULE);
       } else {
         // Pass-through
         resolve();
@@ -562,7 +719,23 @@ Crisp.prototype = {
   },
 
   /**
-   * Connects socket, using preferred RTM API host
+   * Connects loopback (used for Web Hooks)
+   * @memberof Crisp
+   * @private
+   * @method _connectLoopback
+   */
+  _connectLoopback : function() {
+    // Assign emitter to loopback
+    this._loopback = this._emitter;
+
+    // Unstack broker bind hooks immediately
+    this._unstackBrokerBindHooks(this._loopback);
+
+    return Promise.resolve();
+  },
+
+  /**
+   * Connects socket, using preferred RTM API host (used for WebSockets)
    * @memberof Crisp
    * @private
    * @method _connectSocket
@@ -630,11 +803,11 @@ Crisp.prototype = {
           randomizationFactor  : Crisp.DEFAULT_SOCKET_RECONNECT_FACTOR
         });
 
-        self._emitAuthenticate();
+        self._emitAuthenticateSocket();
 
         // Setup base socket event listeners
         self._socket.io.on("reconnect", function() {
-          self._emitAuthenticate();
+          self._emitAuthenticateSocket();
         });
 
         self._socket.on("unauthorized", function() {
@@ -645,16 +818,68 @@ Crisp.prototype = {
         });
 
         // Setup user socket event listeners
-        while (self._socketBindHooks.length > 0) {
-          self._socketBindHooks.shift()(
-            self._socket, self._emitter
-          );
-        }
+        self._unstackBrokerBindHooks(self._socket);
+
+        return Promise.resolve();
       });
   },
 
   /**
-   * Perform a request
+   * Authenticates client (used for WebSockets)
+   * @memberof Crisp
+   * @private
+   * @method _emitAuthenticateSocket
+   */
+  _emitAuthenticateSocket : function() {
+    var auth        = this.auth,
+        tier        = this._tier,
+        boundEvents = Object.keys(this._boundEvents);
+
+    if (!this._socket) {
+      throw new Error(
+        "[Crisp] emitAuthenticateSocket: cannot listen for events as socket "  +
+          "is not yet bound"
+      );
+    }
+    if (!auth.identifier || !auth.key) {
+      throw new Error(
+        "[Crisp] emitAuthenticateSocket: cannot listen for events as you "  +
+          "did not authenticate"
+      );
+    }
+    if (boundEvents.length === 0) {
+      throw new Error(
+        "[Crisp] emitAuthenticateSocket: cannot listen for events as no "  +
+          "event is being listened to"
+      );
+    }
+
+    this._socket.emit("authentication", {
+      username : auth.identifier,
+      password : auth.key,
+      tier     : tier,
+      events   : boundEvents
+    });
+  },
+
+  /**
+   * Unstacks pending broker bind hooks
+   * @memberof Crisp
+   * @private
+   * @method _unstackBrokerBindHooks
+   * @param {object} modeInstance
+   */
+  _unstackBrokerBindHooks : function(modeInstance) {
+    // Setup user socket event listeners
+    while (this._brokerBindHooks.length > 0) {
+      this._brokerBindHooks.shift()(
+        modeInstance, this._emitter
+      );
+    }
+  },
+
+  /**
+   * Performs a request to REST API
    * @memberof Crisp
    * @private
    * @method _request
@@ -666,21 +891,23 @@ Crisp.prototype = {
    * @param {function} reject
    */
   _request : function(resource, method, query, body, resolve, reject) {
+    var self = this;
+
     var requestParameters = {
       responseType    : "json",
       timeout         : Crisp.DEFAULT_REQUEST_TIMEOUT,
 
       headers         : {
-        "User-Agent"   : this._useragent,
-        "X-Crisp-Tier" : this._tier
+        "User-Agent"   : self._useragent,
+        "X-Crisp-Tier" : self._tier
       },
 
       throwHttpErrors : false
     };
 
     // Add authorization?
-    if (this.auth.token) {
-      requestParameters.headers.Authorization = ("Basic " + this.auth.token);
+    if (self.auth.token) {
+      requestParameters.headers.Authorization = ("Basic " + self.auth.token);
     }
 
     // Add body?
@@ -720,7 +947,9 @@ Crisp.prototype = {
 
         // Response error?
         if (response.statusCode >= 400) {
-          var reason_message = ((response.body || {}).reason || "http_error");
+          var reason_message = self._readErrorResponseReason(
+            method, response.statusCode, response
+          );
           var data_message   = ((response.body || {}).data || {}).message;
 
           return reject({
@@ -746,40 +975,32 @@ Crisp.prototype = {
   },
 
   /**
-   * Authenticate client
+   * Reads reason for error response
    * @memberof Crisp
    * @private
-   * @method _emitAuthenticate
+   * @method _readErrorResponseReason
+   * @param {string} method
+   * @param {number} statusCode
+   * @param {object} response
    */
-  _emitAuthenticate : function() {
-    var auth = this.auth;
-    var tier = this._tier;
+  _readErrorResponseReason : function(method, statusCode, response) {
+    // HEAD method? As HEAD requests do not expect any response body, then we \
+    //   cannot map a reason from the response.
+    if (method === "head") {
+      // 5xx errors?
+      if (statusCode >= 500) {
+        return "server_error";
+      }
 
-    if (!this._socket) {
-      throw new Error(
-        "[Crisp] emitAuthenticate: cannot listen for events as socket is "  +
-          "not yet bound"
-      );
-    }
-    if (!auth.identifier || !auth.key) {
-      throw new Error(
-        "[Crisp] emitAuthenticate: cannot listen for events as you did not "  +
-          "authenticate"
-      );
-    }
-    if (this._boundEvents.length === 0) {
-      throw new Error(
-        "[Crisp] emitAuthenticate: cannot listen for events as no event is "  +
-          "being listened to"
-      );
+      // 4xx errors?
+      if (statusCode >= 400) {
+        return "route_error";
+      }
     }
 
-    this._socket.emit("authentication", {
-      username : auth.identifier,
-      password : auth.key,
-      tier     : tier,
-      events   : this._boundEvents
-    });
+    // Other methods must hold a response body, therefore we can fallback on \
+    //   an HTTP error if we fail to acquire any reason at all.
+    return ((response.body || {}).reason || "http_error");
   }
 };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "crisp-api",
   "description": "Crisp API wrapper for Node - official, maintained by Crisp",
-  "version": "6.4.0",
+  "version": "7.0.0",
   "homepage": "https://github.com/crisp-im/node-crisp-api",
   "license": "MIT",
   "author": {
@@ -9,6 +9,18 @@
     "email": "baptiste@crisp.chat",
     "url": "https://jamin.me/"
   },
+  "contributors": [
+    {
+      "name": "Valerian Saliou",
+      "email": "valerian@valeriansaliou.name",
+      "url": "https://valeriansaliou.name/"
+    },
+    {
+      "name": "Eliott Vincent",
+      "email": "eliott@crisp.chat",
+      "url": "https://www.eliottvincent.com/"
+    }
+  ],
   "repository": {
     "type": "git",
     "url": "git://github.com/crisp-im/node-crisp-api.git"

package/types/crisp.d.ts

@@ -32,6 +32,7 @@ declare class Crisp {
     private _boundEvents;
     setRestHost: (host: string) => void;
     setRtmHost: (host: string) => void;
+    setRtmMode: (mode: string) => void;
     setTier: (tier: string) => void;
     authenticate: (identifier: string, key: string) => void;
     authenticateTier: (tier: string, identifier: string, key: string) => void;
@@ -41,18 +42,23 @@ declare class Crisp {
     patch: (resource: string, query: object, body: object) => any;
     put: (resource: string, query: object, body: object) => any;
     delete: (resource: string, query: object, body: object) => any;
-    on: (event: string, callback: Function) => void;
-    rebind: () => void;
+    on: (event: string, callback: Function) => any;
+    rebindSocket: () => any;
     _prepareRestUrl: (paths: any[]) => string;
     _prepareServices: () => void;
     _prepareResources: (serviceInstance: object, resources: any[]) => void;
-    _prepareSocket: (fnBindHook: Function) => void;
+    _prepareBroker: (fnBindHook: Function) => any;
+    _connectLoopback: () => any;
+    _connectSocket: (rtmHostOverride: string) => any;
+    _emitAuthenticateSocket: () => void;
+    _unstackBrokerBindHooks: (modeInstance: object) => void;
     _request: (resource: string, method: string, query: object, body: object, resolve: Function, reject: Function) => void;
-    _emitAuthenticate: () => void;
 }
 declare namespace Crisp {
-    export { DEFAULT_REQUEST_TIMEOUT, DEFAULT_SOCKET_TIMEOUT, DEFAULT_SOCKET_RECONNECT_DELAY, DEFAULT_SOCKET_RECONNECT_DELAY_MAX, DEFAULT_SOCKET_RECONNECT_FACTOR, DEFAULT_SOCKET_SCHEDULE, DEFAULT_EVENT_REBIND_INTERVAL_MIN, DEFAULT_USERAGENT_PREFIX, DEFAULT_REST_HOST, DEFAULT_REST_BASE_PATH, DEFAULT_RTM_EVENTS, Crisp };
+    export { RTM_MODES, AVAILABLE_RTM_MODES, DEFAULT_REQUEST_TIMEOUT, DEFAULT_SOCKET_TIMEOUT, DEFAULT_SOCKET_RECONNECT_DELAY, DEFAULT_SOCKET_RECONNECT_DELAY_MAX, DEFAULT_SOCKET_RECONNECT_FACTOR, DEFAULT_SOCKET_SCHEDULE, DEFAULT_EVENT_REBIND_INTERVAL_MIN, DEFAULT_USERAGENT_PREFIX, DEFAULT_REST_HOST, DEFAULT_REST_BASE_PATH, DEFAULT_RTM_MODE, DEFAULT_RTM_EVENTS, Crisp };
 }
+declare var RTM_MODES: object;
+declare var AVAILABLE_RTM_MODES: string[];
 declare var DEFAULT_REQUEST_TIMEOUT: number;
 declare var DEFAULT_SOCKET_TIMEOUT: number;
 declare var DEFAULT_SOCKET_RECONNECT_DELAY: number;
@@ -63,4 +69,5 @@ declare var DEFAULT_EVENT_REBIND_INTERVAL_MIN: number;
 declare var DEFAULT_USERAGENT_PREFIX: string;
 declare var DEFAULT_REST_HOST: string;
 declare var DEFAULT_REST_BASE_PATH: string;
+declare var DEFAULT_RTM_MODE: string;
 declare var DEFAULT_RTM_EVENTS: string[];