diff --git a/docs/_reference/BaseAPIClient.md b/docs/_reference/BaseAPIClient.md index a865de3f8..6df824338 100644 --- a/docs/_reference/BaseAPIClient.md +++ b/docs/_reference/BaseAPIClient.md @@ -12,7 +12,7 @@ permalink: /reference/BaseAPIClient * [.transport](#BaseAPIClient+transport) : BaseAPIClient~transportFn * [.retryConfig](#BaseAPIClient+retryConfig) : Object * [._createFacets()](#BaseAPIClient+_createFacets) - * [.registerDataStore(dataStore)](#BaseAPIClient+registerDataStore) + * ~~[.registerDataStore(dataStore)](#BaseAPIClient+registerDataStore)~~ * [._callTransport(task, queueCb)](#BaseAPIClient+_callTransport) @@ -27,10 +27,10 @@ Base client for both the RTM and web APIs. | [opts] | Object | | | | [opts.slackAPIUrl] | string | "https://slack.com/api/" | The Slack API URL. | | [opts.transport] | BaseAPIClient~transportFn | | Function to call to make an HTTP call to the Slack API. | -| [opts.logLevel] | string | | The log level for the logger. | +| [opts.logLevel] | string | "info" | The log level for the logger. | | [opts.logger] | BaseAPIClient~logFn | | Function to use for log calls, takes (logLevel, logString) params. | -| opts.maxRequestConcurrency | number | | The max # of concurrent requests to make to Slack's API's, defaults to 3. | -| opts.retryConfig | Object | | The configuration to use for the retry operation, {@see https://github.com/tim-kos/node-retry} | +| [opts.maxRequestConcurrency] | number | 3 | The max # of concurrent requests to make to Slack's API | +| [opts.retryConfig] | Object | | The configuration to use for the retry operation, see [node-retry](https://github.com/tim-kos/node-retry) for more details. | @@ -62,10 +62,10 @@ Initializes each of the API facets. **Access:** protected -### baseAPIClient.registerDataStore(dataStore) -Attaches a data-store to the client instance. +### ~~baseAPIClient.registerDataStore(dataStore)~~ +***Deprecated*** -NOTE: In next major version, remove from BaseAPIClient. Only used in RTMClient. +Attaches a data-store to the client instance. **Kind**: instance method of [BaseAPIClient](#BaseAPIClient) diff --git a/docs/_reference/RTMClient.md b/docs/_reference/RTMClient.md index 20782fcad..4f618ac1f 100644 --- a/docs/_reference/RTMClient.md +++ b/docs/_reference/RTMClient.md @@ -6,7 +6,7 @@ permalink: /reference/RTMClient **Kind**: global class * [RTMClient](#RTMClient) - * [new RTMClient(token, opts)](#new_RTMClient_new) + * [new RTMClient(token, [opts])](#new_RTMClient_new) * [._socketFn](#RTMClient+_socketFn) : function * [.ws](#RTMClient+ws) : Object * [.connected](#RTMClient+connected) : boolean @@ -38,25 +38,25 @@ permalink: /reference/RTMClient -### new RTMClient(token, opts) +### new RTMClient(token, [opts]) Creates a new instance of RTM client. -| Param | Type | Description | -| --- | --- | --- | -| token | String | The token to use for connecting | -| opts | Object | | -| opts.socketFn | function | A function to call, passing in a websocket URL, that should return a websocket instance connected to that URL | -| opts.dataStore | Object | A store to cache Slack info, e.g. channels, users etc. in. Pass null or false to use no store | -| opts.autoReconnect | Boolean | Whether or not to automatically reconnect when the connection closes. Defaults to true | -| opts.useRtmConnect | Boolean | True to use rtm.connect rather than rtm.start | -| opts.retryConfig | Object | The retry policy to use, defaults to forever with exponential backoff {@see https://github.com/SEAPUNK/node-retry} | -| opts.maxReconnectionAttempts | Number | DEPRECATED: Use retryConfig instead | -| opts.reconnectionBackoff | Number | DEPRECATED: Use retryConfig instead | -| opts.wsPingInterval | Number | The time to wait between pings with the server | -| opts.maxPongInterval | Number | The max time (in ms) to wait for a pong before reconnecting | -| opts.logLevel | String | The log level for the logger | -| opts.logger | function | Function to use for log calls, takes (logLevel, logString) parameters | +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| token | string | | The token to use for connecting | +| [opts] | Object | | | +| [opts.socketFn] | RTMClient~socketFn | | A function to call, passing in a websocket URL, that should return a websocket instance connected to that URL | +| [opts.dataStore] | [SlackDataStore](#SlackDataStore) | null | false | | A store to cache Slack info. Recommended value is `false`. Default value is an instance of [SlackMemoryDataStore](#SlackMemoryDataStore). | +| [opts.autoReconnect] | boolean | true | Whether or not to automatically reconnect when the connection closes | +| [opts.useRtmConnect] | boolean | false | Whether to use rtm.connect rather than rtm.start. Recommended value is `true`. | +| [opts.retryConfig] | Object | | The retry policy to use, defaults to forever with exponential backoff, see [node-retry](https://github.com/SEAPUNK/node-retry) for more details. | +| [opts.maxReconnectionAttempts] | number | | DEPRECATED: Use retryConfig instead | +| [opts.reconnectionBackoff] | number | | DEPRECATED: Use retryConfig instead | +| [opts.wsPingInterval] | number | 5000 | The time (in ms) to wait between pings with the server | +| [opts.maxPongInterval] | number | | The max time (in ms) to wait for a pong before reconnecting | +| [opts.logLevel] | string | "info" | The log level for the logger | +| [opts.logger] | RTMClient~logFn | | Function to use for log calls, takes (logLevel, logString) parameters | diff --git a/docs/_reference/SlackDataStore.md b/docs/_reference/SlackDataStore.md index 16659e70e..ac3bebb6d 100644 --- a/docs/_reference/SlackDataStore.md +++ b/docs/_reference/SlackDataStore.md @@ -3,9 +3,11 @@ layout: page title: SlackDataStore permalink: /reference/SlackDataStore --- +***Deprecated*** + **Kind**: global class -* [SlackDataStore](#SlackDataStore) +* ~~[SlackDataStore](#SlackDataStore)~~ * [new SlackDataStore(opts)](#new_SlackDataStore_new) * [.logger](#SlackDataStore+logger) : function * [.registerMessageHandler(event, handler)](#SlackDataStore+registerMessageHandler) diff --git a/docs/_reference/SlackMemoryDataStore.md b/docs/_reference/SlackMemoryDataStore.md index 83f38306f..c6ff22367 100644 --- a/docs/_reference/SlackMemoryDataStore.md +++ b/docs/_reference/SlackMemoryDataStore.md @@ -3,9 +3,11 @@ layout: page title: SlackMemoryDataStore permalink: /reference/SlackMemoryDataStore --- +***Deprecated*** + **Kind**: global class -* [SlackMemoryDataStore](#SlackMemoryDataStore) +* ~~[SlackMemoryDataStore](#SlackMemoryDataStore)~~ * [.users](#SlackMemoryDataStore+users) : Object * [.channels](#SlackMemoryDataStore+channels) : Object * [.dms](#SlackMemoryDataStore+dms) : Object diff --git a/docs/_reference/WebAPIClient.md b/docs/_reference/WebAPIClient.md index 2ff40f9c6..858e05831 100644 --- a/docs/_reference/WebAPIClient.md +++ b/docs/_reference/WebAPIClient.md @@ -19,7 +19,7 @@ Slack Web API client. | --- | --- | --- | | token | | The Slack API token to use with this client. | | [opts] | Object | | -| opts.retryConfig | Object | The configuration to use for the retry operation, {@see https://github.com/tim-kos/node-retry} | +| [opts.retryConfig] | Object | The configuration to use for the retry operation, see [node-retry](https://github.com/tim-kos/node-retry) for more details. | diff --git a/lib/clients/client.js b/lib/clients/client.js index b89dc6515..aa76c2767 100644 --- a/lib/clients/client.js +++ b/lib/clients/client.js @@ -26,12 +26,12 @@ var retryPolicies = require('./retry-policies'); * @param {string} [opts.slackAPIUrl=https://slack.com/api/] - The Slack API URL. * @param {BaseAPIClient~transportFn} [opts.transport] - Function to call to make an HTTP call to * the Slack API. - * @param {string} [opts.logLevel] The log level for the logger. + * @param {string} [opts.logLevel=info] The log level for the logger. * @param {BaseAPIClient~logFn} [opts.logger] Function to use for log calls, takes (logLevel, logString) params. - * @param {number} opts.maxRequestConcurrency The max # of concurrent requests to make to Slack's - * API's, defaults to 3. - * @param {Object} opts.retryConfig The configuration to use for the retry operation, - * {@see https://github.com/tim-kos/node-retry} + * @param {number} [opts.maxRequestConcurrency=3] The max # of concurrent requests to make to Slack's + * API + * @param {Object} [opts.retryConfig] The configuration to use for the retry operation, + * see {@link https://github.com/tim-kos/node-retry|node-retry} for more details. * @constructor */ function BaseAPIClient(token, opts) { @@ -92,11 +92,14 @@ BaseAPIClient.prototype._createFacets = function _createFacets() { /** * Attaches a data-store to the client instance. * - * NOTE: In next major version, remove from BaseAPIClient. Only used in RTMClient. - * + * @deprecated SlackDataStore interface will be removed in v4.0.0. See + * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide} + * for details. * @param {SlackDataStore} dataStore */ BaseAPIClient.prototype.registerDataStore = function registerDataStore(dataStore) { + this.logger('warn', 'SlackDataStore is deprecated and will be removed in the next major ' + + 'version. See project documentation for a migration guide.'); this.dataStore = dataStore; this.logger('debug', 'BaseAPIClient registerDataStore end'); }; diff --git a/lib/clients/rtm/client.js b/lib/clients/rtm/client.js index e31380517..ea254ee40 100644 --- a/lib/clients/rtm/client.js +++ b/lib/clients/rtm/client.js @@ -40,24 +40,27 @@ var retryPolicyFromOptions = require('../retry-policies').retryPolicyFromOptions /** * Creates a new instance of RTM client. - * @param {String} token The token to use for connecting - * @param {Object} opts - * @param {Function} opts.socketFn A function to call, passing in a websocket URL, that should - * return a websocket instance connected to that URL - * @param {Object} opts.dataStore A store to cache Slack info, e.g. channels, users etc. in. - * Pass null or false to use no store - * @param {Boolean} opts.autoReconnect Whether or not to automatically reconnect when the connection - * closes. Defaults to true - * @param {Boolean} opts.useRtmConnect True to use rtm.connect rather than rtm.start - * @param {Object} opts.retryConfig The retry policy to use, defaults to forever with exponential - * backoff {@see https://github.com/SEAPUNK/node-retry} - * @param {Number} opts.maxReconnectionAttempts DEPRECATED: Use retryConfig instead - * @param {Number} opts.reconnectionBackoff DEPRECATED: Use retryConfig instead - * @param {Number} opts.wsPingInterval The time to wait between pings with the server - * @param {Number} opts.maxPongInterval The max time (in ms) to wait for a pong before reconnecting - * @param {String} opts.logLevel The log level for the logger - * @param {Function} opts.logger Function to use for log calls, takes (logLevel, logString) - * parameters + * @param {string} token - The token to use for connecting + * @param {Object} [opts] + * @param {RTMClient~socketFn} [opts.socketFn] - A function to call, passing in a websocket URL, + * that should return a websocket instance connected to that URL + * @param {SlackDataStore|null|false} [opts.dataStore] - A store to cache Slack info. Recommended + * value is `false`. Default value is an instance of {@link SlackMemoryDataStore}. + * @param {boolean} [opts.autoReconnect=true] - Whether or not to automatically reconnect when the + * connection closes + * @param {boolean} [opts.useRtmConnect=false] - Whether to use rtm.connect rather than rtm.start. + * Recommended value is `true`. + * @param {Object} [opts.retryConfig] - The retry policy to use, defaults to forever with + * exponential backoff, see {@link https://github.com/SEAPUNK/node-retry|node-retry} for more details. + * @param {number} [opts.maxReconnectionAttempts] - DEPRECATED: Use retryConfig instead + * @param {number} [opts.reconnectionBackoff] - DEPRECATED: Use retryConfig instead + * @param {number} [opts.wsPingInterval=5000] - The time (in ms) to wait between pings with the + * server + * @param {number} [opts.maxPongInterval] - The max time (in ms) to wait for a pong before + * reconnecting + * @param {string} [opts.logLevel=info] - The log level for the logger + * @param {RTMClient~logFn} [opts.logger] - Function to use for log calls, takes + * (logLevel, logString) parameters * @constructor */ function RTMClient(token, opts) { @@ -169,7 +172,7 @@ RTMClient.prototype.activeTeamId = undefined; /** - * @type {SlackDataStore} + * @type {?SlackDataStore} */ RTMClient.prototype.dataStore = undefined; diff --git a/lib/clients/web/client.js b/lib/clients/web/client.js index 5bf048eb4..fc7c7be7d 100644 --- a/lib/clients/web/client.js +++ b/lib/clients/web/client.js @@ -13,10 +13,10 @@ var facets = require('./facets/index'); /** * Slack Web API client. * - * @param token The Slack API token to use with this client. - * @param {Object=} opts - * @param {Object} opts.retryConfig The configuration to use for the retry operation, - * {@see https://github.com/tim-kos/node-retry} + * @param token - The Slack API token to use with this client. + * @param {Object} [opts] + * @param {Object} [opts.retryConfig] - The configuration to use for the retry operation, + * see {@link https://github.com/tim-kos/node-retry|node-retry} for more details. * @constructor */ function WebAPIClient(token, opts) { diff --git a/lib/data-store/data-store.js b/lib/data-store/data-store.js index 8a83fb62a..30398a3c2 100644 --- a/lib/data-store/data-store.js +++ b/lib/data-store/data-store.js @@ -17,6 +17,9 @@ var models = require('../models'); /** * + * @deprecated SlackDataStore interface will be removed in v4.0.0. See + * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide} + * for details. * @param {Object} opts * @param {string=} opts.logLevel The log level for the logger. * @param {Function=} opts.logger Function to use for log calls, takes (logLevel, logString) params. @@ -31,6 +34,9 @@ function SlackDataStore(opts) { */ this.logger = dataStoreOpts.logger || getLogger(dataStoreOpts.logLevel); + this.logger('warn', 'SlackDataStore is deprecated and will be removed in the next major ' + + 'version. See project documentation for a migration guide.'); + forEach(messageHandlers, bind(function anonRegisterMessageHandler(handler, event) { this.registerMessageHandler(event, handler); }, this)); diff --git a/lib/data-store/memory-data-store.js b/lib/data-store/memory-data-store.js index d17834748..e8d72244d 100644 --- a/lib/data-store/memory-data-store.js +++ b/lib/data-store/memory-data-store.js @@ -13,6 +13,9 @@ var models = require('../models'); /** * + * @deprecated SlackMemoryDataStore will be removed in v4.0.0. See + * {@link https://github.com/slackapi/node-slack-sdk/wiki/DataStore-v3.x-Migration-Guide|the migration guide} + * for details. * @constructor */ function SlackMemoryDataStore(opts) {