crisp-api 7.3.0 → 7.4.1

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 Changelog
 =========
 
+## v7.4.1
+
+### Bug Fixes
+
+* Changed type of exported services in JSDoc to `any` so that TypeScript projects can use resource methods without `tsc` throwing errors.
+
+## v7.4.0
+
+### New Features
+
+* Generated up-to-date TypeScript definitions.
+
+### Bug Fixes
+
+* Fixed the automatic generation of TypeScript definitions.
+
 ## v7.3.0
 
 ### New Features

package/lib/crisp.js

@@ -161,48 +161,105 @@ var services = {
  * @classdesc This is the Crisp Library. Handles REST and RTM operations
  */
 function Crisp() {
-  this.auth = {};
+  /**
+   * @public
+   * @type {*}
+  */
+  this.bucket = {};
 
   /**
-   * @private
-   * @type {string}
+   * @public
+   * @type {*}
+  */
+  this.media = {};
+
+  /**
+   * @public
+   * @type {*}
+  */
+  this.plugin = {};
+
+  /**
+   * @public
+   * @type {*}
+  */
+  this.website = {};
+
+  /**
+   * @public
+   * @type {object}
   */
-  this._tier = "user";
+  this.auth = {
+    tier       : "user",
+    identifier : null,
+    key        : null,
+    token      : null
+  };
 
-  /** @private */
+  /**
+   * @private
+   * @type {object}
+  */
   this._rest = {
     host     : Crisp.DEFAULT_REST_HOST,
     basePath : Crisp.DEFAULT_REST_BASE_PATH
   };
 
-  /** @private */
+  /**
+   * @private
+   * @type {object}
+  */
   this._rtm  = {
     host : null,
     mode : Crisp.DEFAULT_RTM_MODE
   };
 
-  /** @private */
+  /**
+   * @private
+   * @type {string}
+  */
   this._useragent       = (Crisp.DEFAULT_USERAGENT_PREFIX + pkg.version);
 
-  /** @private */
+  /**
+   * @private
+   * @type {object}
+  */
   this._emitter         = new EventEmitter();
 
-  /** @private */
+  /**
+   * @private
+   * @type {object|null}
+  */
   this._socket          = null;
 
-  /** @private */
+  /**
+   * @private
+   * @type {object|null}
+  */
   this._loopback        = null;
 
-  /** @private */
+  /**
+   * @private
+   * @type {number|null}
+  */
   this._lastEventRebind = null;
 
-  /** @private */
+  /**
+   * @private
+   * @type {object|null}
+  */
   this._brokerScheduler = null;
 
-  /** @private */
+  /**
+   * @private
+   * @type {Array}
+  */
   this._brokerBindHooks = [];
 
-  /** @private */
+  /**
+   * @private
+   * @type {object}
+  */
   this._boundEvents     = {};
 
   // Prepare
@@ -214,8 +271,10 @@ Crisp.prototype = {
   /**
    * Sets the REST API host
    * @memberof Crisp
+   * @public
    * @method setRestHost
    * @param {string} host - Hostname
+   * @return {undefined}
    */
   setRestHost : function(host) {
     if (typeof host === "string") {
@@ -228,8 +287,10 @@ Crisp.prototype = {
   /**
    * Sets the RTM API host
    * @memberof Crisp
+   * @public
    * @method setRtmHost
    * @param {string} host - Hostname
+   * @return {undefined}
    */
   setRtmHost : function(host) {
     if (typeof host === "string") {
@@ -242,8 +303,10 @@ Crisp.prototype = {
   /**
    * Sets the RTM channel mode (ie. WebSockets or Web Hooks)
    * @memberof Crisp
+   * @public
    * @method setRtmMode
    * @param {string} mode - RTM mode ('websockets' or 'webhooks')
+   * @return {undefined}
    */
   setRtmMode : function(mode) {
     if (Crisp.AVAILABLE_RTM_MODES.indexOf(mode) !== -1) {
@@ -257,38 +320,46 @@ Crisp.prototype = {
   },
 
   /**
-   * Sets the tier
+   * Sets the authentication tier
    * @memberof Crisp
+   * @public
    * @method setTier
    * @param {string} tier
+   * @return {undefined}
    */
   setTier : function(tier) {
-    this._tier = (tier || "user");
+    this.auth.tier = (tier || "user");
   },
 
   /**
    * Authenticates
    * @memberof Crisp
+   * @public
    * @method authenticate
    * @param {string} identifier
    * @param {string} key
+   * @return {undefined}
    */
   authenticate : function(identifier, key) {
     var auth = this.auth;
 
+    // Store credentials
     auth.identifier = identifier;
     auth.key        = key;
 
-    auth.token      = Buffer.from(identifier + ":" + key).toString("base64");
+    // Assign pre-computed authentication token
+    auth.token = Buffer.from(identifier + ":" + key).toString("base64");
   },
 
   /**
    * Authenticates (with tier)
    * @memberof Crisp
+   * @public
    * @method authenticateTier
    * @param {string} tier
    * @param {string} identifier
    * @param {string} key
+   * @return {undefined}
    */
   authenticateTier : function(tier, identifier, key) {
     this.setTier(tier);
@@ -298,10 +369,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to HEAD a resource
    * @memberof Crisp
+   * @public
    * @method head
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   head : function(resource, query, body) {
     var self = this;
@@ -316,10 +389,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to GET a resource
    * @memberof Crisp
+   * @public
    * @method get
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   get : function(resource, query) {
     var self = this;
@@ -334,10 +409,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to POST a resource
    * @memberof Crisp
+   * @public
    * @method post
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   post : function(resource, query, body) {
     var self = this;
@@ -352,10 +429,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to PATCH a resource
    * @memberof Crisp
+   * @public
    * @method patch
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   patch : function(resource, query, body) {
     var self = this;
@@ -370,10 +449,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to PUT a resource
    * @memberof Crisp
+   * @public
    * @method put
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   put : function(resource, query, body) {
     var self = this;
@@ -388,10 +469,12 @@ Crisp.prototype = {
   /**
    * Method wrapper to DELETE a resource
    * @memberof Crisp
+   * @public
    * @method delete
    * @param {string} resource
    * @param {object} query
    * @param {object} body
+   * @return {Promise}
    */
   delete : function(resource, query, body) {
     var self = this;
@@ -406,9 +489,11 @@ Crisp.prototype = {
   /**
    * Binds RTM event
    * @memberof Crisp
+   * @public
    * @method on
    * @param {string} event
    * @param {function} callback
+   * @return {Promise}
    */
   on : function(event, callback) {
     // Ensure all input arguments are set
@@ -472,8 +557,10 @@ Crisp.prototype = {
   /**
    * Receives a raw event and dispatches it to the listener (used for Web Hooks)
    * @memberof Crisp
+   * @public
    * @method receiveHook
    * @param {object} body
+   * @return {undefined}
    */
   receiveHook : function(body) {
     var self = this;
@@ -516,11 +603,13 @@ Crisp.prototype = {
    * Verifies an event string and checks that signatures match (used for Web \
    *   Hooks)
    * @memberof Crisp
+   * @public
    * @method verifyHook
    * @param {string} secret
    * @param {object} body
    * @param {string} timestamp
    * @param {string} signature
+   * @return {boolean}
    */
   verifyHook : function(secret, body, timestamp, signature) {
     if (this._loopback) {
@@ -535,11 +624,13 @@ Crisp.prototype = {
    * Verifies an event string and checks that signatures match (used for \
    *   Widgets)
    * @memberof Crisp
+   * @public
    * @method verifyWidget
    * @param {string} secret
    * @param {object} body
    * @param {string} timestamp
    * @param {string} signature
+   * @return {boolean}
    */
   verifyWidget : function(secret, body, timestamp, signature) {
     return this._verifySignature(secret, body, timestamp, signature);
@@ -548,7 +639,9 @@ Crisp.prototype = {
   /**
    * Rebinds socket events (used for WebSockets)
    * @memberof Crisp
+   * @public
    * @method rebind
+   * @return {Promise}
    */
   rebindSocket : function() {
     if (!this._socket) {
@@ -570,12 +663,15 @@ Crisp.prototype = {
       );
     }
 
-    // Rebind to socket events (eg. newly bound websites)
-    this._lastEventRebind = nowTime;
+    return Promise.resolve()
+      .then(function() {
+        // Rebind to socket events (eg. newly bound websites)
+        this._lastEventRebind = nowTime;
 
-    this._socket.emit("socket:bind", {});
+        this._socket.emit("socket:bind", {});
 
-    return Promise.resolve();
+        return Promise.resolve();
+      });
   },
 
   /**
@@ -584,6 +680,7 @@ Crisp.prototype = {
    * @private
    * @method _prepareRestUrl
    * @param {Array} paths - List of paths ['session', 'login']
+   * @return {string}
    */
   _prepareRestUrl : function(paths) {
     if (Array.isArray(paths) === true) {
@@ -604,12 +701,23 @@ Crisp.prototype = {
    * @memberof Crisp
    * @private
    * @method _prepareServices
+   * @return {undefined}
    */
   _prepareServices : function() {
     // Bind services
     for (var name in services) {
       var serviceInstance = new services[name]();
 
+      // Acquire service map
+      var serviceMap = this[(name[0].toLowerCase() + name.substring(1))];
+
+      // No service map available?
+      if (!serviceMap) {
+        throw new Error(
+          "[Crisp] prepareServices: service '" + name + "' has no map available"
+        );
+      }
+
       // No resources defined in service?
       if (!serviceInstance._resources  ||
             serviceInstance._resources.length === 0) {
@@ -621,10 +729,8 @@ Crisp.prototype = {
 
       // Prepare all resources (for service)
       this._prepareResources(
-        serviceInstance, serviceInstance._resources
+        serviceMap, serviceInstance._resources
       );
-
-      this[(name[0].toLowerCase() + name.substring(1))] = serviceInstance;
     }
   },
 
@@ -633,15 +739,16 @@ Crisp.prototype = {
    * @memberof Crisp
    * @private
    * @method _prepareResources
-   * @param {object} serviceInstance
+   * @param {object} serviceMap
    * @param {Array} resources
+   * @return {undefined}
    */
-  _prepareResources : function(serviceInstance, resources) {
+  _prepareResources : function(serviceMap, resources) {
     for (var i = 0; i < resources.length; i++) {
       var resourceConstructor = require("./resources/" + resources[i]);
 
       // Instanciate resource, which will auto-bind itself to service prototype
-      new resourceConstructor(serviceInstance, this);
+      new resourceConstructor(serviceMap, this);
     }
   },
 
@@ -651,6 +758,7 @@ Crisp.prototype = {
    * @private
    * @method _prepareBroker
    * @param {function} fnBindHook
+   * @return {Promise}
    */
   _prepareBroker : function(fnBindHook) {
     var self = this;
@@ -717,15 +825,19 @@ Crisp.prototype = {
    * @memberof Crisp
    * @private
    * @method _connectLoopback
+   * @return {Promise}
    */
   _connectLoopback : function() {
-    // Assign emitter to loopback
-    this._loopback = this._emitter;
+    return Promise.resolve()
+      .then(function() {
+        // Assign emitter to loopback
+        this._loopback = this._emitter;
 
-    // Unstack broker bind hooks immediately
-    this._unstackBrokerBindHooks(this._loopback);
+        // Unstack broker bind hooks immediately
+        this._unstackBrokerBindHooks(this._loopback);
 
-    return Promise.resolve();
+        return Promise.resolve();
+      });
   },
 
   /**
@@ -734,6 +846,7 @@ Crisp.prototype = {
    * @private
    * @method _connectSocket
    * @param {string} rtmHostOverride
+   * @return {Promise}
    */
   _connectSocket : function(rtmHostOverride) {
     var self = this;
@@ -752,7 +865,7 @@ Crisp.prototype = {
         // Acquire RTM API URL from remote
         var restUrlSegments;
 
-        switch (self._tier) {
+        switch (self.auth.tier) {
           case "plugin": {
             restUrlSegments = ["plugin", "connect", "endpoints"];
 
@@ -823,10 +936,10 @@ Crisp.prototype = {
    * @memberof Crisp
    * @private
    * @method _emitAuthenticateSocket
+   * @return {undefined}
    */
   _emitAuthenticateSocket : function() {
     var auth        = this.auth,
-        tier        = this._tier,
         boundEvents = Object.keys(this._boundEvents);
 
     if (!this._socket) {
@@ -851,7 +964,7 @@ Crisp.prototype = {
     this._socket.emit("authentication", {
       username : auth.identifier,
       password : auth.key,
-      tier     : tier,
+      tier     : auth.tier,
       events   : boundEvents
     });
   },
@@ -862,6 +975,7 @@ Crisp.prototype = {
    * @private
    * @method _unstackBrokerBindHooks
    * @param {object} modeInstance
+   * @return {undefined}
    */
   _unstackBrokerBindHooks : function(modeInstance) {
     // Setup user socket event listeners
@@ -883,6 +997,7 @@ Crisp.prototype = {
    * @param {object} body
    * @param {function} resolve
    * @param {function} reject
+   * @return {undefined}
    */
   _request : function(resource, method, query, body, resolve, reject) {
     var self = this;
@@ -893,7 +1008,7 @@ Crisp.prototype = {
 
       headers         : {
         "User-Agent"   : self._useragent,
-        "X-Crisp-Tier" : self._tier
+        "X-Crisp-Tier" : self.auth.tier
       },
 
       throwHttpErrors : false
@@ -976,6 +1091,7 @@ Crisp.prototype = {
    * @param {string} method
    * @param {number} statusCode
    * @param {object} response
+   * @return {string}
    */
   _readErrorResponseReason : function(method, statusCode, response) {
     // HEAD method? As HEAD requests do not expect any response body, then we \
@@ -1006,6 +1122,7 @@ Crisp.prototype = {
    * @param {object} body
    * @param {string} timestamp
    * @param {string} signature
+   * @return {boolean}
    */
   _verifySignature : function(secret, body, timestamp, signature) {
     // Ensure all provided data is valid

package/lib/resources/BucketURL.js

@@ -18,8 +18,10 @@ function BucketURL(service, crisp) {
   /**
    * Generate Bucket URL
    * @memberof BucketURL
+   * @public
    * @method generateBucketURL
-   * @return Promise
+   * @param {object} data
+   * @return {Promise}
    */
   service.generateBucketURL = function(data) {
     return crisp.post(

package/lib/resources/MediaAnimation.js

@@ -18,8 +18,12 @@ function MediaAnimation(service, crisp) {
   /**
    * List Animation Medias
    * @memberof MediaAnimation
+   * @public
    * @method listAnimationMedias
-   * @return Promise
+   * @param {number} pageNumber
+   * @param {string} listID
+   * @param {object} searchQuery
+   * @return {Promise}
    */
   service.listAnimationMedias = function(pageNumber, listID, searchQuery) {
     return crisp.get(

package/lib/resources/PluginConnect.js

@@ -18,8 +18,9 @@ function PluginConnect(service, crisp) {
   /**
    * Get Connect Account
    * @memberof PluginConnect
+   * @public
    * @method getConnectAccount
-   * @return Promise
+   * @return {Promise}
    */
   service.getConnectAccount = function() {
     return crisp.get(
@@ -30,8 +31,9 @@ function PluginConnect(service, crisp) {
   /**
    * Check Connect Session Validity
    * @memberof PluginConnect
+   * @public
    * @method checkConnectSessionValidity
-   * @return Promise
+   * @return {Promise}
    */
   service.checkConnectSessionValidity = function() {
     return crisp.head(
@@ -42,8 +44,12 @@ function PluginConnect(service, crisp) {
   /**
    * List All Connect Websites
    * @memberof PluginConnect
+   * @public
    * @method listAllConnectWebsites
-   * @return Promise
+   * @param {number} pageNumber
+   * @param {boolean} [filterConfigured]
+   * @param {string} [dateSince]
+   * @return {Promise}
    */
   service.listAllConnectWebsites = function(
     pageNumber, filterConfigured, dateSince
@@ -73,8 +79,9 @@ function PluginConnect(service, crisp) {
   /**
    * Get Connect Endpoints
    * @memberof PluginConnect
+   * @public
    * @method getConnectEndpoints
-   * @return Promise
+   * @return {Promise}
    */
   service.getConnectEndpoints = function() {
     return crisp.get(