diff --git a/README.hbs b/README.hbs index ce5aa50..6b814e7 100644 --- a/README.hbs +++ b/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 diff --git a/README.md b/README.md index 1ea1f16..f32cc47 100644 --- a/README.md +++ b/README.md @@ -78,12 +78,12 @@ TelegramBot * [.closeWebHook()](#TelegramBot+closeWebHook) ⇒ Promise * [.hasOpenWebHook()](#TelegramBot+hasOpenWebHook) ⇒ Boolean * [.getMe()](#TelegramBot+getMe) ⇒ Promise - * [.setWebHook(url, [cert])](#TelegramBot+setWebHook) - * [.getUpdates([timeout], [limit], [offset])](#TelegramBot+getUpdates) ⇒ Promise + * [.setWebHook(url, [options])](#TelegramBot+setWebHook) + * [.getUpdates([options])](#TelegramBot+getUpdates) ⇒ Promise * [.processUpdate(update)](#TelegramBot+processUpdate) * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ Promise * [.answerInlineQuery(inlineQueryId, results, [options])](#TelegramBot+answerInlineQuery) ⇒ Promise - * [.forwardMessage(chatId, fromChatId, messageId)](#TelegramBot+forwardMessage) ⇒ Promise + * [.forwardMessage(chatId, fromChatId, messageId, [options])](#TelegramBot+forwardMessage) ⇒ Promise * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ Promise * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ Promise * [.sendDocument(chatId, doc, [options], [fileOpts])](#TelegramBot+sendDocument) ⇒ Promise @@ -97,7 +97,7 @@ TelegramBot * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ Promise * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ Promise * [.editMessageReplyMarkup(replyMarkup, [options])](#TelegramBot+editMessageReplyMarkup) ⇒ Promise - * [.getUserProfilePhotos(userId, [offset], [limit])](#TelegramBot+getUserProfilePhotos) ⇒ Promise + * [.getUserProfilePhotos(userId, [options])](#TelegramBot+getUserProfilePhotos) ⇒ Promise * [.sendLocation(chatId, latitude, longitude, [options])](#TelegramBot+sendLocation) ⇒ Promise * [.sendVenue(chatId, latitude, longitude, title, address, [options])](#TelegramBot+sendVenue) ⇒ Promise * [.sendContact(chatId, phoneNumber, firstName, [options])](#TelegramBot+sendContact) ⇒ Promise @@ -188,8 +188,10 @@ Returns basic information about the bot in form of a `User` object. **See**: https://core.telegram.org/bots/api#getme -### 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 [TelegramBot](#TelegramBot) **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 | String | URL where Telegram will make HTTP Post. Leave empty to delete webHook. | -| [cert] | String | stream.Stream | PEM certificate key (public). | +| [options] | Object | Additional Telegram query options | +| [options.certificate] | String | stream.Stream | PEM certificate key (public). | -### telegramBot.getUpdates([timeout], [limit], [offset]) ⇒ Promise -Use this method to receive incoming updates using long polling +### telegramBot.getUpdates([options]) ⇒ Promise +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 [TelegramBot](#TelegramBot) -**Returns**: Promise - Updates **See**: https://core.telegram.org/bots/api#getupdates | Param | Type | Description | | --- | --- | --- | -| [timeout] | Number | String | Timeout in seconds for long polling. | -| [limit] | Number | String | Limits the number of updates to be retrieved. | -| [offset] | Number | String | Identifier of the first update to be returned. | +| [options] | Object | Additional Telegram query options | @@ -258,7 +260,7 @@ Send answers to an inline query. -### telegramBot.forwardMessage(chatId, fromChatId, messageId) ⇒ Promise +### telegramBot.forwardMessage(chatId, fromChatId, messageId, [options]) ⇒ Promise Forward messages of any kind. **Kind**: instance method of [TelegramBot](#TelegramBot) @@ -268,6 +270,7 @@ Forward messages of any kind. | chatId | Number | String | Unique identifier for the message recipient | | fromChatId | Number | String | Unique identifier for the chat where the original message was sent | | messageId | Number | String | Unique message identifier | +| [options] | Object | Additional Telegram query options | @@ -478,9 +481,11 @@ inline_message_id in your request. -### telegramBot.getUserProfilePhotos(userId, [offset], [limit]) ⇒ Promise +### telegramBot.getUserProfilePhotos(userId, [options]) ⇒ Promise 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 [TelegramBot](#TelegramBot) **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 | Number | String | Unique identifier of the target user | -| [offset] | Number | Sequential number of the first photo to be returned. By default, all photos are returned. | -| [limit] | Number | Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. | +| [options] | Object | Additional Telegram query options | @@ -717,3 +721,7 @@ Use this method to get data for high score table. | [options] | Object | 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 diff --git a/package.json b/package.json index 8a10d0a..f178c57 100644 --- a/package.json +++ b/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", diff --git a/src/telegram.js b/src/telegram.js index 8d9be09..f76d441 100644 --- a/src/telegram.js +++ b/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) { - const _path = 'setWebHook'; - const opts = { qs: { url } }; + setWebHook(url, options = {}) { + /* The older method signature was setWebHook(url, cert). + * 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 - * @param {Number|String} [timeout] Timeout in seconds for long polling. - * @param {Number|String} [limit] Limits the number of updates to be retrieved. - * @param {Number|String} [offset] Identifier of the first update to be returned. - * @return {Promise} Updates + * 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. + * + * @param {Object} [options] Additional Telegram query options + * @return {Promise} * @see https://core.telegram.org/bots/api#getupdates */ - getUpdates(timeout, limit, offset) { - const form = { - offset, - limit, - timeout, - }; + getUpdates(form = {}) { + /* The older method signature was getUpdates(timeout, limit, offset). + * We need to ensure backwards-compatibility while maintaining + * consistency of the method signatures throughout the library */ + 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) { - const form = { - chat_id: chatId, - from_chat_id: fromChatId, - message_id: messageId - }; - + forwardMessage(chatId, fromChatId, messageId, form = {}) { + form.chat_id = chatId; + form.from_chat_id = fromChatId; + form.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 {Number} [limit] Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. + * @param {Object} [options] Additional Telegram query options * @return {Promise} * @see https://core.telegram.org/bots/api#getuserprofilephotos */ - getUserProfilePhotos(userId, offset, limit) { - const form = { - user_id: userId, - offset, - limit - }; + getUserProfilePhotos(userId, form = {}) { + /* The older method signature was getUserProfilePhotos(userId, offset, limit). + * We need to ensure backwards-compatibility while maintaining + * consistency of the method signatures throughout the library */ + 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 }); } diff --git a/test/telegram.js b/test/telegram.js index 4f0628a..80ee7cb 100644 --- a/test/telegram.js +++ b/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));