Ensure consistency of methods signatures (#245)

Bug:

  The library assumes signatures of methods to be, somewhat:

    methodName(requiredParam1, requiredParam2, form = {})

  where 'requiredParam1' ('requiredParam2', ..., 'requiredParamN')
  are parameters that MUST be provided, and
  'form' is an optional object allowing supplying any additional,
  optional parameters that the Bot API allows.

  This allows any new parameters added by Telegram to be
  readily-supported by our library.

  Also, the following have been included:

  * Corresponding tests
  * Documentation on the old, deprecated signatures
  * Console-logging the deprecation notices

README.hbs

@@ -68,3 +68,7 @@ Once they are generated, the `crt.pem` can be provided to `telegramBot.setWebHoo
 {{>members~}}
 {{/class}}
 * * *
+
+[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert
+[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates
+[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos

README.md

@@ -78,12 +78,12 @@ TelegramBot
     * [.closeWebHook()](#TelegramBot+closeWebHook) ⇒ <code>Promise</code>
     * [.hasOpenWebHook()](#TelegramBot+hasOpenWebHook) ⇒ <code>Boolean</code>
     * [.getMe()](#TelegramBot+getMe) ⇒ <code>Promise</code>
-    * [.setWebHook(url, [cert])](#TelegramBot+setWebHook)
+    * [.setWebHook(url, [options])](#TelegramBot+setWebHook)
-    * [.getUpdates([timeout], [limit], [offset])](#TelegramBot+getUpdates) ⇒ <code>Promise</code>
+    * [.getUpdates([options])](#TelegramBot+getUpdates) ⇒ <code>Promise</code>
     * [.processUpdate(update)](#TelegramBot+processUpdate)
     * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ <code>Promise</code>
     * [.answerInlineQuery(inlineQueryId, results, [options])](#TelegramBot+answerInlineQuery) ⇒ <code>Promise</code>
-    * [.forwardMessage(chatId, fromChatId, messageId)](#TelegramBot+forwardMessage) ⇒ <code>Promise</code>
+    * [.forwardMessage(chatId, fromChatId, messageId, [options])](#TelegramBot+forwardMessage) ⇒ <code>Promise</code>
     * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ <code>Promise</code>
     * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ <code>Promise</code>
     * [.sendDocument(chatId, doc, [options], [fileOpts])](#TelegramBot+sendDocument) ⇒ <code>Promise</code>
@@ -97,7 +97,7 @@ TelegramBot
     * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ <code>Promise</code>
     * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ <code>Promise</code>
     * [.editMessageReplyMarkup(replyMarkup, [options])](#TelegramBot+editMessageReplyMarkup) ⇒ <code>Promise</code>
-    * [.getUserProfilePhotos(userId, [offset], [limit])](#TelegramBot+getUserProfilePhotos) ⇒ <code>Promise</code>
+    * [.getUserProfilePhotos(userId, [options])](#TelegramBot+getUserProfilePhotos) ⇒ <code>Promise</code>
     * [.sendLocation(chatId, latitude, longitude, [options])](#TelegramBot+sendLocation) ⇒ <code>Promise</code>
     * [.sendVenue(chatId, latitude, longitude, title, address, [options])](#TelegramBot+sendVenue) ⇒ <code>Promise</code>
     * [.sendContact(chatId, phoneNumber, firstName, [options])](#TelegramBot+sendContact) ⇒ <code>Promise</code>
@@ -188,8 +188,10 @@ Returns basic information about the bot in form of a `User` object.
 **See**: https://core.telegram.org/bots/api#getme  
 <a name="TelegramBot+setWebHook"></a>
 
-### telegramBot.setWebHook(url, [cert])
+### telegramBot.setWebHook(url, [options])
 Specify an url to receive incoming updates via an outgoing webHook.
+This method has an [older, compatible signature][setWebHook-v0.25.0]
+that is being deprecated.
 
 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
 **See**: https://core.telegram.org/bots/api#setwebhook  
@@ -197,22 +199,22 @@ Specify an url to receive incoming updates via an outgoing webHook.
 | Param | Type | Description |
 | --- | --- | --- |
 | url | <code>String</code> | URL where Telegram will make HTTP Post. Leave empty to delete webHook. |
-| [cert] | <code>String</code> &#124; <code>stream.Stream</code> | PEM certificate key (public). |
+| [options] | <code>Object</code> | Additional Telegram query options |
+| [options.certificate] | <code>String</code> &#124; <code>stream.Stream</code> | PEM certificate key (public). |
 
 <a name="TelegramBot+getUpdates"></a>
 
-### telegramBot.getUpdates([timeout], [limit], [offset]) ⇒ <code>Promise</code>
+### telegramBot.getUpdates([options]) ⇒ <code>Promise</code>
-Use this method to receive incoming updates using long polling
+Use this method to receive incoming updates using long polling.
+This method has an [older, compatible signature][getUpdates-v0.25.0]
+that is being deprecated.
 
 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**Returns**: <code>Promise</code> - Updates  
 **See**: https://core.telegram.org/bots/api#getupdates  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [timeout] | <code>Number</code> &#124; <code>String</code> | Timeout in seconds for long polling. |
+| [options] | <code>Object</code> | Additional Telegram query options |
-| [limit] | <code>Number</code> &#124; <code>String</code> | Limits the number of updates to be retrieved. |
-| [offset] | <code>Number</code> &#124; <code>String</code> | Identifier of the first update to be returned. |
 
 <a name="TelegramBot+processUpdate"></a>
 
@@ -258,7 +260,7 @@ Send answers to an inline query.
 
 <a name="TelegramBot+forwardMessage"></a>
 
-### telegramBot.forwardMessage(chatId, fromChatId, messageId) ⇒ <code>Promise</code>
+### telegramBot.forwardMessage(chatId, fromChatId, messageId, [options]) ⇒ <code>Promise</code>
 Forward messages of any kind.
 
 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
@@ -268,6 +270,7 @@ Forward messages of any kind.
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | fromChatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the chat where the original message was sent |
 | messageId | <code>Number</code> &#124; <code>String</code> | Unique message identifier |
+| [options] | <code>Object</code> | Additional Telegram query options |
 
 <a name="TelegramBot+sendPhoto"></a>
 
@@ -478,9 +481,11 @@ inline_message_id in your request.
 
 <a name="TelegramBot+getUserProfilePhotos"></a>
 
-### telegramBot.getUserProfilePhotos(userId, [offset], [limit]) ⇒ <code>Promise</code>
+### telegramBot.getUserProfilePhotos(userId, [options]) ⇒ <code>Promise</code>
 Use this method to get a list of profile pictures for a user.
 Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos) object.
+This method has an [older, compatible signature][getUserProfilePhotos-v0.25.0]
+that is being deprecated.
 
 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
 **See**: https://core.telegram.org/bots/api#getuserprofilephotos  
@@ -488,8 +493,7 @@ Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephot
 | Param | Type | Description |
 | --- | --- | --- |
 | userId | <code>Number</code> &#124; <code>String</code> | Unique identifier of the target user |
-| [offset] | <code>Number</code> | Sequential number of the first photo to be returned. By default, all photos are returned. |
+| [options] | <code>Object</code> | Additional Telegram query options |
-| [limit] | <code>Number</code> | Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. |
 
 <a name="TelegramBot+sendLocation"></a>
 
@@ -717,3 +721,7 @@ Use this method to get data for high score table.
 | [options] | <code>Object</code> | Additional Telegram query options |
 
 * * *
+
+[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert
+[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates
+[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos

package.json

@@ -28,6 +28,7 @@
     "bl": "^1.1.2",
     "bluebird": "^3.3.4",
     "debug": "^2.2.0",
+    "depd": "^1.1.0",
     "eventemitter3": "^1.2.0",
     "file-type": "^3.8.0",
     "mime": "^1.3.4",

src/telegram.js

@@ -13,6 +13,7 @@ const path = require('path');
 const URL = require('url');
 const fs = require('fs');
 const pump = require('pump');
+const deprecate = require('depd')('node-telegram-bot-api');
 
 const _messageTypes = [
   'text', 'audio', 'document', 'photo', 'sticker', 'video', 'voice', 'contact',
@@ -290,14 +291,33 @@ class TelegramBot extends EventEmitter {
 
   /**
    * Specify an url to receive incoming updates via an outgoing webHook.
-   * @param {String} url URL where Telegram will make HTTP Post. Leave empty to
+   * This method has an [older, compatible signature][setWebHook-v0.25.0]
+   * that is being deprecated.
+   *
+   * @param  {String} url URL where Telegram will make HTTP Post. Leave empty to
    * delete webHook.
-   * @param {String|stream.Stream} [cert] PEM certificate key (public).
+   * @param  {Object} [options] Additional Telegram query options
+   * @param  {String|stream.Stream} [options.certificate] PEM certificate key (public).
    * @see https://core.telegram.org/bots/api#setwebhook
    */
-  setWebHook(url, cert) {
+  setWebHook(url, options = {}) {
-    const _path = 'setWebHook';
+    /* The older method signature was setWebHook(url, cert).
-    const opts = { qs: { url } };
+     * We need to ensure backwards-compatibility while maintaining
+     * consistency of the method signatures throughout the library */
+    let cert;
+    // Note: 'options' could be an object, if a stream was provided (in place of 'cert')
+    if (typeof options !== 'object' || options instanceof stream.Stream) {
+      deprecate('The method signature setWebHook(url, cert) has been deprecated since v0.25.0');
+      cert = options;
+      options = {}; // eslint-disable-line no-param-reassign
+    } else {
+      cert = options.certificate;
+    }
+
+    const opts = {
+      qs: options,
+    };
+    opts.qs.url = url;
 
     if (cert) {
       const [formData, certificate] = this._formatSendData('certificate', cert);
@@ -305,7 +325,7 @@ class TelegramBot extends EventEmitter {
       opts.qs.certificate = certificate;
     }
 
-    return this._request(_path, opts)
+    return this._request('setWebHook', opts)
       .then(resp => {
         if (!resp) {
           throw new Error(resp);
@@ -316,19 +336,28 @@ class TelegramBot extends EventEmitter {
   }
 
   /**
-   * Use this method to receive incoming updates using long polling
+   * Use this method to receive incoming updates using long polling.
-   * @param  {Number|String} [timeout] Timeout in seconds for long polling.
+   * This method has an [older, compatible signature][getUpdates-v0.25.0]
-   * @param  {Number|String} [limit] Limits the number of updates to be retrieved.
+   * that is being deprecated.
-   * @param  {Number|String} [offset] Identifier of the first update to be returned.
+   *
-   * @return {Promise} Updates
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
    * @see https://core.telegram.org/bots/api#getupdates
    */
-  getUpdates(timeout, limit, offset) {
+  getUpdates(form = {}) {
-    const form = {
+    /* The older method signature was getUpdates(timeout, limit, offset).
-      offset,
+     * We need to ensure backwards-compatibility while maintaining
-      limit,
+     * consistency of the method signatures throughout the library */
-      timeout,
+    if (typeof form !== 'object') {
-    };
+      /* eslint-disable no-param-reassign, prefer-rest-params */
+      deprecate('The method signature getUpdates(timeout, limit, offset) has been deprecated since v0.25.0');
+      form = {
+        timeout: arguments[0],
+        limit: arguments[1],
+        offset: arguments[2],
+      };
+      /* eslint-enable no-param-reassign, prefer-rest-params */
+    }
 
     return this._request('getUpdates', { form });
   }
@@ -454,15 +483,13 @@ class TelegramBot extends EventEmitter {
    * @param  {Number|String} fromChatId Unique identifier for the chat where the
    * original message was sent
    * @param  {Number|String} messageId  Unique message identifier
+   * @param  {Object} [options] Additional Telegram query options
    * @return {Promise}
    */
-  forwardMessage(chatId, fromChatId, messageId) {
+  forwardMessage(chatId, fromChatId, messageId, form = {}) {
-    const form = {
+    form.chat_id = chatId;
-      chat_id: chatId,
+    form.from_chat_id = fromChatId;
-      from_chat_id: fromChatId,
+    form.message_id = messageId;
-      message_id: messageId
-    };
-
     return this._request('forwardMessage', { form });
   }
 
@@ -727,19 +754,28 @@ class TelegramBot extends EventEmitter {
   /**
    * Use this method to get a list of profile pictures for a user.
    * Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos) object.
+   * This method has an [older, compatible signature][getUserProfilePhotos-v0.25.0]
+   * that is being deprecated.
    *
    * @param  {Number|String} userId  Unique identifier of the target user
-   * @param  {Number} [offset] Sequential number of the first photo to be returned. By default, all photos are returned.
+   * @param  {Object} [options] Additional Telegram query options
-   * @param  {Number} [limit] Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100.
    * @return {Promise}
    * @see https://core.telegram.org/bots/api#getuserprofilephotos
    */
-  getUserProfilePhotos(userId, offset, limit) {
+  getUserProfilePhotos(userId, form = {}) {
-    const form = {
+    /* The older method signature was getUserProfilePhotos(userId, offset, limit).
-      user_id: userId,
+     * We need to ensure backwards-compatibility while maintaining
-      offset,
+     * consistency of the method signatures throughout the library */
-      limit
+    if (typeof form !== 'object') {
-    };
+      /* eslint-disable no-param-reassign, prefer-rest-params */
+      deprecate('The method signature getUserProfilePhotos(userId, offset, limit) has been deprecated since v0.25.0');
+      form = {
+        offset: arguments[1],
+        limit: arguments[2],
+      };
+      /* eslint-enable no-param-reassign, prefer-rest-params */
+    }
+    form.user_id = userId;
     return this._request('getUserProfilePhotos', { form });
   }
 

test/telegram.js

@@ -215,6 +215,7 @@ describe('Telegram', function telegramSuite() {
 
   describe('#setWebHook', function setWebHookSuite() {
     const ip = '216.58.210.174';
+    const cert = `${__dirname}/../examples/crt.pem`;
     before(function before() {
       utils.handleRatelimit(bot, 'setWebHook', this);
     });
@@ -227,7 +228,13 @@ describe('Telegram', function telegramSuite() {
         });
     });
     it('should set a webHook with certificate', function test() {
-      const cert = `${__dirname}/../examples/crt.pem`;
+      return bot
+        .setWebHook(ip, { certificate: cert })
+        .then(resp => {
+          assert.equal(resp, true);
+        });
+    });
+    it('(v0.25.0 and lower) should set a webHook with certificate', function test() {
       return bot
         .setWebHook(ip, cert)
         .then(resp => {
@@ -244,11 +251,22 @@ describe('Telegram', function telegramSuite() {
   });
 
   describe('#getUpdates', function getUpdatesSuite() {
+    const opts = {
+      timeout: 0,
+      limit: 10,
+    };
     before(function before() {
+      utils.handleRatelimit(bot, 'setWebHook', this);
       utils.handleRatelimit(bot, 'getUpdates', this);
+      return bot.setWebHook('');
     });
     it('should return an Array', function test() {
-      return bot.getUpdates().then(resp => {
+      return bot.getUpdates(opts).then(resp => {
+        assert.equal(Array.isArray(resp), true);
+      });
+    });
+    it('(v0.25.0 and lower) should return an Array', function test() {
+      return bot.getUpdates(opts.timeout, opts.limit).then(resp => {
         assert.equal(Array.isArray(resp), true);
       });
     });
@@ -637,11 +655,22 @@ describe('Telegram', function telegramSuite() {
   });
 
   describe('#getUserProfilePhotos', function getUserProfilePhotosSuite() {
+    const opts = {
+      offset: 0,
+      limit: 1,
+    };
     before(function before() {
       utils.handleRatelimit(bot, 'getUserProfilePhotos', this);
     });
     it('should get user profile photos', function test() {
-      return bot.getUserProfilePhotos(USERID).then(resp => {
+      return bot.getUserProfilePhotos(USERID, opts).then(resp => {
+        assert.ok(is.object(resp));
+        assert.ok(is.number(resp.total_count));
+        assert.ok(is.array(resp.photos));
+      });
+    });
+    it('(v0.25.0 and lower) should get user profile photos', function test() {
+      return bot.getUserProfilePhotos(USERID, opts.offset, opts.limit).then(resp => {
         assert.ok(is.object(resp));
         assert.ok(is.number(resp.total_count));
         assert.ok(is.array(resp.photos));