src/telegram: Support API v3 Payments (#335)

References:

   * API v3 Payments: https://core.telegram.org/bots/payments
    * PR: https://github.com/yagop/node-telegram-bot-api/pull/335
    * PR-by: @kamikazechaser 
    * API v3 progress tracker: https://github.com/yagop/node-telegram-bot-api/issues/332

doc/api.md

@@ -62,6 +62,9 @@ TelegramBot
     * [.setGameScore(userId, score, [options])](#TelegramBot+setGameScore) ⇒ <code>Promise</code>
     * [.getGameHighScores(userId, [options])](#TelegramBot+getGameHighScores) ⇒ <code>Promise</code>
     * [.deleteMessage(chatId, messageId, [options])](#TelegramBot+deleteMessage) ⇒ <code>Promise</code>
+    * [.sendInvoice(chatId, title, description, payload, providerToken, startParameter, currency, prices, [options])](#TelegramBot+sendInvoice) ⇒ <code>Promise</code>
+    * [.answerShippingQuery(shippingQueryId, ok, [options])](#TelegramBot+answerShippingQuery) ⇒ <code>Promise</code>
+    * [.answerPreCheckoutQuery(preCheckoutQueryId, ok, [options])](#TelegramBot+answerPreCheckoutQuery) ⇒ <code>Promise</code>
 
 <a name="new_TelegramBot_new"></a>
 
@@ -775,6 +778,57 @@ Use this method to delete a message.
 | messageId | <code>String</code> | Unique identifier of the target message |
 | [options] | <code>Object</code> | Additional Telegram query options |
 
+<a name="TelegramBot+sendInvoice"></a>
+
+### telegramBot.sendInvoice(chatId, title, description, payload, providerToken, startParameter, currency, prices, [options]) ⇒ <code>Promise</code>
+Send invoice.
+Use this method to send an invoice.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#sendinvoice  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
+| title | <code>String</code> | Product name |
+| description | <code>String</code> | product description |
+| payload | <code>String</code> | Bot defined invoice payload |
+| providerToken | <code>String</code> | Payments provider token |
+| startParameter | <code>String</code> | Deep-linking parameter |
+| currency | <code>String</code> | Three-letter ISO 4217 currency code |
+| prices | <code>Array</code> | Breakdown of prices |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
+<a name="TelegramBot+answerShippingQuery"></a>
+
+### telegramBot.answerShippingQuery(shippingQueryId, ok, [options]) ⇒ <code>Promise</code>
+Answer shipping query..
+Use this method to reply to shipping queries.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#answershippingquery  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| shippingQueryId | <code>String</code> | Unique identifier for the query to be answered |
+| ok | <code>Boolean</code> | Specify if delivery of the product is possible |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
+<a name="TelegramBot+answerPreCheckoutQuery"></a>
+
+### telegramBot.answerPreCheckoutQuery(preCheckoutQueryId, ok, [options]) ⇒ <code>Promise</code>
+Answer pre-checkout query.
+Use this method to confirm shipping of a product.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**: https://core.telegram.org/bots/api#answerprecheckoutquery  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| preCheckoutQueryId | <code>String</code> | Unique identifier for the query to be answered |
+| ok | <code>Boolean</code> | Specify if every order details are ok |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
 * * *
 
 

src/telegram.js

@@ -1227,6 +1227,66 @@ class TelegramBot extends EventEmitter {
     form.message_id = messageId;
     return this._request('deleteMessage', { form });
   }
+
+  /**
+   * Send invoice.
+   * Use this method to send an invoice.
+   *
+   * @param  {Number|String} chatId  Unique identifier for the message recipient
+   * @param  {String} title Product name
+   * @param  {String} description product description
+   * @param  {String} payload Bot defined invoice payload
+   * @param  {String} providerToken Payments provider token
+   * @param  {String} startParameter Deep-linking parameter
+   * @param  {String} currency Three-letter ISO 4217 currency code
+   * @param  {Array} prices Breakdown of prices
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#sendinvoice
+   */
+  sendInvoice(chatId, title, description, payload, providerToken, startParameter, currency, prices, form = {}) {
+    form.chat_id = chatId;
+    form.title = title;
+    form.description = description;
+    form.payload = payload;
+    form.provider_token = providerToken;
+    form.start_parameter = startParameter;
+    form.currency = currency;
+    form.prices = JSON.stringify(prices);
+    return this._request('sendInvoice', { form });
+  }
+
+  /**
+   * Answer shipping query..
+   * Use this method to reply to shipping queries.
+   *
+   * @param  {String} shippingQueryId  Unique identifier for the query to be answered
+   * @param  {Boolean} ok Specify if delivery of the product is possible
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#answershippingquery
+   */
+  answerShippingQuery(shippingQueryId, ok, form = {}) {
+    form.shipping_query_id = shippingQueryId;
+    form.ok = ok;
+    return this._request('answerShippingQuery', { form });
+  }
+
+  /**
+   * Answer pre-checkout query.
+   * Use this method to confirm shipping of a product.
+   *
+   * @param  {String} preCheckoutQueryId  Unique identifier for the query to be answered
+   * @param  {Boolean} ok Specify if every order details are ok
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#answerprecheckoutquery
+   */
+  answerPreCheckoutQuery(preCheckoutQueryId, ok, form = {}) {
+    form.pre_checkout_query_id = preCheckoutQueryId;
+    form.ok = ok;
+    return this._request('answerPreCheckoutQuery', { form });
+  }
 }
 
 module.exports = TelegramBot;

test/README.md

@@ -13,6 +13,9 @@ export TEST_GROUP_ID=<GROUP_ID>
 # Game short name which to use in some of the tests, e.g. TelegramBot#sendGame()
 export TEST_GAME_SHORT_NAME=<GAME_SHORT_NAME>
 
+# Payment provider token to be used
+export TEST_PROVIDER_TOKEN=<YOUR_PROVIDER_TOKEN>
+
 # Run ALL tests
 npm run test
 

test/telegram.js

@@ -16,6 +16,11 @@ if (!TOKEN) {
   throw new Error('Bot token not provided');
 }
 
+const PROVIDER_TOKEN = process.env.TEST_PROVIDER_TOKEN;
+if (!PROVIDER_TOKEN) {
+  throw new Error('Provider token not supplied');
+}
+
 // Telegram service if not User Id
 const USERID = process.env.TEST_USER_ID || 777000;
 const GROUPID = process.env.TEST_GROUP_ID || -1001075450562;
@@ -1206,4 +1211,28 @@ describe('TelegramBot', function telegramSuite() {
       return bot.sendPhoto(USERID, stream);
     });
   });
+
+  describe('#sendInvoice', function sendInvoiceSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'sendInvoice', this);
+    });
+    it('should send an invoice', function test() {
+      const title = 'Demo product';
+      const description = 'our test product';
+      const payload = 'sku-p001';
+      const providerToken = PROVIDER_TOKEN;
+      const startParameter = 'pay';
+      const currency = 'KES';
+      const prices = [{ label: 'product', amount: 11000 }, { label: 'tax', amount: 11000 }];
+      return bot.sendInvoice(USERID, title, description, payload, providerToken, startParameter, currency, prices).then(resp => {
+        assert.ok(is.object(resp));
+        assert.ok(is.object(resp.invoice));
+        assert.ok(is.number(resp.invoice.total_amount));
+      });
+    });
+  });
+
+  describe.skip('#answerShippingQuery', function answerShippingQuerySuite() {});
+
+  describe.skip('#answerPreCheckoutQuery', function answerPreCheckoutQuerySuite() {});
 }); // End Telegram