pr/362: Support Bot API v3.1 (#362, #369)

References:

  * FR: https://github.com/yagop/node-telegram-bot-api/issues/361
  * PR: https://github.com/yagop/node-telegram-bot-api/pull/362
  * PR-by: @Lord-Protector
  * PR/2: https://github.com/yagop/node-telegram-bot-api/pull/369
  * PR/2-by: @kamikazechaser

README.md

@@ -1,6 +1,6 @@
 # Node.js Telegram Bot API
 
-[![Bot API](http://img.shields.io/badge/Bot%20API-v3.0.0-00aced.svg)](https://core.telegram.org/bots/api)
+[![Bot API](https://img.shields.io/badge/Bot%20API-v.3.1.0-00aced.svg)](https://core.telegram.org/bots/api)
 [![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api)
 [![Build status](https://ci.appveyor.com/api/projects/status/ujko6bsum3g5msjh/branch/master?svg=true)](https://ci.appveyor.com/project/yagop/node-telegram-bot-api/branch/master)
 [![Coverage Status](https://coveralls.io/repos/yagop/node-telegram-bot-api/badge.svg?branch=master)](https://coveralls.io/r/yagop/node-telegram-bot-api?branch=master)

doc/api.md

@@ -38,6 +38,15 @@ TelegramBot
     * [.sendChatAction(chatId, action)](#TelegramBot+sendChatAction) ⇒ <code>Promise</code>
     * [.kickChatMember(chatId, userId)](#TelegramBot+kickChatMember) ⇒ <code>Promise</code>
     * [.unbanChatMember(chatId, userId)](#TelegramBot+unbanChatMember) ⇒ <code>Promise</code>
+    * [.restrictChatMember(chatId, userId, [options])](#TelegramBot+restrictChatMember) ⇒ <code>Promise</code>
+    * [.promoteChatMember(chatId, userId, [options])](#TelegramBot+promoteChatMember) ⇒ <code>Promise</code>
+    * [.exportChatInviteLink(chatId)](#TelegramBot+exportChatInviteLink) ⇒ <code>Promise</code>
+    * [.setChatPhoto(chatId, photo)](#TelegramBot+setChatPhoto) ⇒ <code>Promise</code>
+    * [.deleteChatPhoto(chatId)](#TelegramBot+deleteChatPhoto) ⇒ <code>Promise</code>
+    * [.setChatTitle(chatId, title)](#TelegramBot+setChatTitle) ⇒ <code>Promise</code>
+    * [.setChatDescription(chatId, description)](#TelegramBot+setChatDescription) ⇒ <code>Promise</code>
+    * [.pinChatMessage(chatId, messageId)](#TelegramBot+pinChatMessage) ⇒ <code>Promise</code>
+    * [.unpinChatMessage(chatId)](#TelegramBot+unpinChatMessage) ⇒ <code>Promise</code>
     * [.answerCallbackQuery(callbackQueryId, text, showAlert, [options])](#TelegramBot+answerCallbackQuery) ⇒ <code>Promise</code>
     * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ <code>Promise</code>
     * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ <code>Promise</code>
@@ -422,6 +431,142 @@ the group for this to work. Returns True on success.
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the target group or username of the target supergroup |
 | userId | <code>String</code> | Unique identifier of the target user |
 
+<a name="TelegramBot+restrictChatMember"></a>
+
+### telegramBot.restrictChatMember(chatId, userId, [options]) ⇒ <code>Promise</code>
+Use this method to restrict a user in a supergroup.
+The bot must be an administrator in the supergroup for this to work
+and must have the appropriate admin rights. Pass True for all boolean parameters
+to lift restrictions from a user. Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#restrictchatmember  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the target chat or username of the target supergroup |
+| userId | <code>String</code> | Unique identifier of the target user |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
+<a name="TelegramBot+promoteChatMember"></a>
+
+### telegramBot.promoteChatMember(chatId, userId, [options]) ⇒ <code>Promise</code>
+Use this method to promote or demote a user in a supergroup or a channel.
+The bot must be an administrator in the chat for this to work
+and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#promotechatmember  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the target chat or username of the target supergroup |
+| userId | <code>String</code> |  |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
+<a name="TelegramBot+exportChatInviteLink"></a>
+
+### telegramBot.exportChatInviteLink(chatId) ⇒ <code>Promise</code>
+Use this method to export an invite link to a supergroup or a channel.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns exported invite link as String on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#exportchatinvitelink  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the target chat or username of the target supergroup |
+
+<a name="TelegramBot+setChatPhoto"></a>
+
+### telegramBot.setChatPhoto(chatId, photo) ⇒ <code>Promise</code>
+Use this method to set a new profile photo for the chat. Photos can't be changed for private chats.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#setchatphoto  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+| photo | <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or a Stream. |
+
+<a name="TelegramBot+deleteChatPhoto"></a>
+
+### telegramBot.deleteChatPhoto(chatId) ⇒ <code>Promise</code>
+Use this method to delete a chat photo. Photos can't be changed for private chats.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#deletechatphoto  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+
+<a name="TelegramBot+setChatTitle"></a>
+
+### telegramBot.setChatTitle(chatId, title) ⇒ <code>Promise</code>
+Use this method to change the title of a chat. Titles can't be changed for private chats.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#setchattitle  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+| title | <code>String</code> | New chat title, 1-255 characters |
+
+<a name="TelegramBot+setChatDescription"></a>
+
+### telegramBot.setChatDescription(chatId, description) ⇒ <code>Promise</code>
+Use this method to change the description of a supergroup or a channel.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#setchatdescription  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+| description | <code>String</code> | New chat title, 1-255 characters |
+
+<a name="TelegramBot+pinChatMessage"></a>
+
+### telegramBot.pinChatMessage(chatId, messageId) ⇒ <code>Promise</code>
+Use this method to pin a message in a supergroup.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#pinchatmessage  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+| messageId | <code>String</code> | Identifier of a message to pin |
+
+<a name="TelegramBot+unpinChatMessage"></a>
+
+### telegramBot.unpinChatMessage(chatId) ⇒ <code>Promise</code>
+Use this method to unpin a message in a supergroup chat.
+The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+Returns True on success.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#unpinchatmessage  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+
 <a name="TelegramBot+answerCallbackQuery"></a>
 
 ### telegramBot.answerCallbackQuery(callbackQueryId, text, showAlert, [options]) ⇒ <code>Promise</code>

src/telegram.js

@@ -844,6 +844,157 @@ class TelegramBot extends EventEmitter {
     return this._request('unbanChatMember', { form });
   }
 
+  /**
+   * Use this method to restrict a user in a supergroup.
+   * The bot must be an administrator in the supergroup for this to work
+   * and must have the appropriate admin rights. Pass True for all boolean parameters
+   * to lift restrictions from a user. Returns True on success.
+   *
+   * @param  {Number|String} chatId Unique identifier for the target chat or username of the target supergroup
+   * @param  {String} userId Unique identifier of the target user
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#restrictchatmember
+   */
+  restrictChatMember(chatId, userId, form = {}) {
+    form.chat_id = chatId;
+    form.user_id = userId;
+    return this._request('restrictChatMember', { form });
+  }
+
+  /**
+   * Use this method to promote or demote a user in a supergroup or a channel.
+   * The bot must be an administrator in the chat for this to work
+   * and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId Unique identifier for the target chat or username of the target supergroup
+   * @param  {String} userId
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#promotechatmember
+   */
+  promoteChatMember(chatId, userId, form = {}) {
+    form.chat_id = chatId;
+    form.user_id = userId;
+    return this._request('promoteChatMember', { form });
+  }
+
+  /**
+   * Use this method to export an invite link to a supergroup or a channel.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns exported invite link as String on success.
+   *
+   * @param  {Number|String} chatId Unique identifier for the target chat or username of the target supergroup
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#exportchatinvitelink
+   */
+  exportChatInviteLink(chatId, form = {}) {
+    form.chat_id = chatId;
+    return this._request('exportChatInviteLink', { form });
+  }
+
+  /**
+   * Use this method to set a new profile photo for the chat. Photos can't be changed for private chats.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @param  {stream.Stream|Buffer} photo A file path or a Stream.
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#setchatphoto
+   */
+  setChatPhoto(chatId, photo, options = {}) {
+    const opts = {
+      qs: options,
+    };
+    opts.qs.chat_id = chatId;
+    try {
+      const sendData = this._formatSendData('photo', photo);
+      opts.formData = sendData[0];
+      opts.qs.photo = sendData[1];
+    } catch (ex) {
+      return Promise.reject(ex);
+    }
+    return this._request('setChatPhoto', opts);
+  }
+
+  /**
+   * Use this method to delete a chat photo. Photos can't be changed for private chats.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#deletechatphoto
+   */
+  deleteChatPhoto(chatId, form = {}) {
+    form.chat_id = chatId;
+    return this._request('deleteChatPhoto', { form });
+  }
+
+  /**
+   * Use this method to change the title of a chat. Titles can't be changed for private chats.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @param  {String} title New chat title, 1-255 characters
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#setchattitle
+   */
+  setChatTitle(chatId, title, form = {}) {
+    form.chat_id = chatId;
+    form.title = title;
+    return this._request('setChatTitle', { form })
+  }
+
+  /**
+   * Use this method to change the description of a supergroup or a channel.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @param  {String} description New chat title, 1-255 characters
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#setchatdescription
+   */
+  setChatDescription(chatId, description, form = {}) {
+    form.chat_id = chatId;
+    form.description = description;
+    return this._request('setChatDescription', { form })
+  }
+
+  /**
+   * Use this method to pin a message in a supergroup.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @param  {String} messageId Identifier of a message to pin
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#pinchatmessage
+   */
+  pinChatMessage(chatId, messageId, form = {}) {
+    form.chat_id = chatId;
+    form.message_id = messageId;
+    return this._request('pinChatMessage', { form });
+  }
+
+  /**
+   * Use this method to unpin a message in a supergroup chat.
+   * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
+   * Returns True on success.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#unpinchatmessage
+   */
+  unpinChatMessage(chatId, form = {}) {
+    form.chat_id = chatId;
+    return this._request('unpinChatMessage', { form });
+  }
+
   /**
    * Use this method to send answers to callback queries sent from
    * inline keyboards. The answer will be displayed to the user as

test/README.md

@@ -23,3 +23,4 @@ npm run test
 npm run eslint              # static-analysis
 npm run mocha               # mocha tests
 ```
+Note: The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.

test/telegram.js

@@ -812,8 +812,115 @@ describe('TelegramBot', function telegramSuite() {
 
   describe.skip('#unbanChatMember', function unbanChatMemberSuite() {});
 
+  describe.skip('#restrictChatMember', function restrictChatMemberSuite() {});
+
+  describe.skip('#promoteChatMember', function promoteChatMemberSuite() {});
+
   describe.skip('#answerCallbackQuery', function answerCallbackQuerySuite() {});
 
+  describe('#exportChatInviteLink', function exportChatInviteLinkSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'exportChatInviteLink', this);
+    });
+    it('should export the group invite link', function test() {
+      return bot.exportChatInviteLink(GROUPID).then(resp => {
+        assert(resp.match(/^https:\/\/t\.me\/joinchat\/.+$/i), 'is a telegram invite link');
+      });
+    });
+  });
+
+  describe('#setChatPhoto', function setChatPhotoSuite() {
+    this.timeout(timeout);
+    before(function before() {
+      utils.handleRatelimit(bot, 'setChatPhoto', this);
+    });
+    it('should set a chat photo from file', function test() {
+      const photo = `${__dirname}/data/chat_photo.png`;
+      return bot.setChatPhoto(GROUPID, photo).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+    it('should set a chat photo from fs.readStream', function test() {
+      const photo = fs.createReadStream(`${__dirname}/data/chat_photo.png`);
+      return bot.setChatPhoto(GROUPID, photo).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+    it('should set a chat photo from request Stream', function test() {
+      const photo = request(`${staticUrl}/chat_photo.png`);
+      return bot.setChatPhoto(GROUPID, photo).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+    it('should set a chat photo from a Buffer', function test() {
+      const photo = fs.readFileSync(`${__dirname}/data/chat_photo.png`);
+      return bot.setChatPhoto(GROUPID, photo).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
+  describe('#deleteChatPhoto', function deleteChatPhotoSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'deleteChatPhoto', this);
+    });
+    it('should delete the chat photo', function test() {
+      return bot.deleteChatPhoto(GROUPID).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
+  describe('#setChatTitle', function setChatTitleSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'setChatTitle', this);
+    });
+    it('should set the chat title', function test() {
+      return bot.setChatTitle(GROUPID, 'ntba test group').then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
+  describe('#setChatDescription', function setChatDescriptionSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'setChatDescription', this);
+    });
+    it('should set the chat description', function test() {
+      const random = Math.floor(Math.random() * 1000);
+      const description = `node-telegram-bot-api test group (random: ${random})`;
+      return bot.setChatDescription(GROUPID, description).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
+  describe('#pinChatMessage', function pinChatMessageSuite() {
+    let messageId;
+    before(function before() {
+      utils.handleRatelimit(bot, 'pinChatMessage', this);
+      return bot.sendMessage(GROUPID, 'To be pinned').then(resp => {
+        messageId = resp.message_id;
+      });
+    });
+    it('should pin chat message', function test() {
+      return bot.pinChatMessage(GROUPID, messageId).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
+  describe('#unpinChatMessage', function unpinChatMessageSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'unpinChatMessage', this);
+    });
+    it('should unpin chat message', function test() {
+      return bot.unpinChatMessage(GROUPID).then(resp => {
+        assert.equal(resp, true);
+      });
+    });
+  });
+
   describe('#editMessageText', function editMessageTextSuite() {
     before(function before() {
       utils.handleRatelimit(bot, 'sendMessage', this);