abeya-tg-api 0.0.1-security → 1.0.0

package/doc/experimental.md

@@ -0,0 +1,28 @@
+# Experimental
+
+Experimental features are things we are trying out. We are **not** sure
+if they'll become stable and move into the `master` branch.
+Try them out and give feedback to support stabilizing them.
+
+* [Features](#features)
+* [API Reference][api-experimental]
+* [Installation](#installation)
+
+
+<a name="features"></a>
+## features:
+
+* Support API method `deleteMessage`
+
+Open issues tagged `experimental`: [link](https://github.com/yagop/node-telegram-bot-api/issues?q=is%3Apr+is%3Aopen+label%3Aexperimental)
+
+
+<a name="installation"></a>
+## installation:
+
+```bash
+$ npm install yagop/node-telegram-bot-api#experimental
+```
+
+
+[api-experimental]:https://github.com/yagop/node-telegram-bot-api/tree/experimental/doc/api.md

package/doc/help.md

@@ -0,0 +1,151 @@
+# Help Information
+
+* [Common Pitfalls](#pitfalls)
+* [FAQs](#faqs)
+
+<a name="pitfalls"></a>
+## Common Pitfalls
+
+<a name="reply-to-message"></a>
+### Failing to receive reply with `ReplyToMessage`
+
+The user has to **manually reply** to your message, by tapping on the bot's message and select *Reply*.
+
+Sources:
+
+* Issue [#113](https://github.com/yagop/node-telegram-bot-api/issues/113)
+
+<a name="faqs"></a>
+## Frequently Asked Questions
+
+> Check out [all questions ever asked][questions] on our Github Issues.
+
+1. [How do I send GIFs?](#gifs)
+1. [Why and When do I need a certificate when using WebHooks?](#webhook-cert)
+1. [How do I know when a user leaves a chat?](#leave-chat)
+1. [What does this error mean?](#error-meanings)
+1. [How do I know the selected option in reply keyboard?](#reply-keyboard)
+1. [How do I send multiple message in correct sequence?](#ordered-sending)
+1. [How do I run my bot behind a proxy?](#proxy)
+1. [Can you add feature X to the library?](#new-feature)
+1. [Is this scalable?](#scalable)
+1. [How do I listen for messages in a chat group?](#messages-in-chat)
+1. [How do I know when a user blocks the bot?](#blocked-bot)
+
+<a name="gifs"></a>
+### How do I send GIFs?
+
+You might be trying to send your animated GIFs using *TelegramBot#sendPhoto()*.
+The method mostly supports static images. As noted by the community,
+it seems you need to send them as documents, using *TelegramBot#sendDocument()*.
+
+```js
+bot.sendDocument(chatId, 'cat.gif');
+```
+
+Sources:
+
+* Issue [#11](https://github.com/yagop/node-telegram-bot-api/issues/11)
+
+<a name="webhook-cert"></a>
+### Why and When do I need a certificate when using WebHooks?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#63](https://github.com/yagop/node-telegram-bot-api/issues/63)
+* Issue [#125](https://github.com/yagop/node-telegram-bot-api/issues/125)
+
+<a name="leave-chat"></a>
+### How do I know when a user leaves a chat?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#248](https://github.com/yagop/node-telegram-bot-api/issues/248)
+
+<a name="error-meanings"></a>
+### What does this error mean?
+
+* [502 Bad Gateway](https://github.com/yagop/node-telegram-bot-api/issues/377)
+
+*Not complete. PRs welcome!*
+
+Sources:
+
+* Issue [#73](https://github.com/yagop/node-telegram-bot-api/issues/73)
+* Issue [#99](https://github.com/yagop/node-telegram-bot-api/issues/99)
+* Issue [#101](https://github.com/yagop/node-telegram-bot-api/issues/101)
+* Issue [#107](https://github.com/yagop/node-telegram-bot-api/issues/107)
+* Issue [#156](https://github.com/yagop/node-telegram-bot-api/issues/156)
+* Issue [#170](https://github.com/yagop/node-telegram-bot-api/issues/170)
+* Issue [#244](https://github.com/yagop/node-telegram-bot-api/issues/244)
+
+<a name="reply-keyboard"></a>
+### How do I know the selected option in reply keyboard?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#108](https://github.com/yagop/node-telegram-bot-api/issues/108)
+
+<a name="ordered-sending"></a>
+### How do I send multiple message in correct sequence?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#240](https://github.com/yagop/node-telegram-bot-api/issues/240)
+
+<a name="proxy"></a>
+### How do I run my bot behind a proxy?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#122](https://github.com/yagop/node-telegram-bot-api/issues/122)
+* Issue [#253](https://github.com/yagop/node-telegram-bot-api/issues/253)
+* Issue [#766](https://github.com/yagop/node-telegram-bot-api/issues/766)
+
+<a name="new-feature"></a>
+### Can you add feature X to the library?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#238](https://github.com/yagop/node-telegram-bot-api/issues/238)
+
+<a name="scalable"></a>
+### Is this scalable?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#219](https://github.com/yagop/node-telegram-bot-api/issues/219)
+
+<a name="messages-in-chat"></a>
+### How do I listen for messages in a chat group?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#304](https://github.com/yagop/node-telegram-bot-api/issues/304)
+
+<a name="blocked-bot"></a>
+### How do I know when a user blocks the bot?
+
+*Not done. PRs welcome!*
+
+Sources:
+
+* Issue [#273](https://github.com/yagop/node-telegram-bot-api/issues/273)
+
+[questions]:https://github.com/yagop/node-telegram-bot-api/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20

package/doc/tutorials.md

@@ -0,0 +1,12 @@
+# Tutorials
+
+* [node-telegram-bot-api-tutorial by @hosein2398](https://github.com/hosein2398/node-telegram-bot-api-tutorial)
+* [node-telegram-bot-api-persian-language by @saeedhei](https://github.com/saeedhei/node-telegram-bot-api-persian-language)
+* [Node.JS: Делаем своего Telegram бота [RUS]](https://archakov.im/post/telegram-bot-on-nodejs)
+* [YouTube: Пишем Telegram бота на NodeJS [RUS]](https://www.youtube.com/watch?v=RS1nmDMf69U&list=PL6AOr-PZtK-mM2QC1ixyfa5CtJZGK61aN)
+* [Node.jsでTelegramのチャットボットを作る - Qiita](https://qiita.com/neetshin/items/0e2f6fa3ade41adb77bc)
+* [Guía: Creación de bots de Telegram en Nodejs [ES]](https://tecnonucleous.com/creacion-de-bots-de-telegram-en-nodejs/)
+* [node-telegram-bot-api-tutorial:a telegram bot helper to send templates by sms](https://github.com/vito2005/chatManagerTelegramBot)
+* [Telegram bot using blockchain services](https://ilanolkies.com/post/Telegram-bot-using-blockchain-services)
+* [How to set webhooks using express local server and NGROK](https://github.com/leobloise/node-telegram-bot-api-wb-tutorial)
+> Send a PR with useful links **not** listed above

package/doc/usage.md

@@ -0,0 +1,269 @@
+# Usage
+
+- [Usage](#usage)
+  - [Events](#events)
+  - [WebHooks](#webhooks)
+  - [Sending files](#sending-files)
+    - [File Options (metadata)](#file-options-metadata)
+    - [Performance Issue](#performance-issue)
+  - [Error handling](#error-handling)
+  - [Polling errors](#polling-errors)
+  - [WebHook errors](#webhook-errors)
+
+<a name="events"></a>
+## Events
+
+*TelegramBot* is an [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
+that emits the following events:
+
+1. `message`: Received a new incoming [Message][message] of any kind
+  1. Depending on the properties of the [Message][message], one of these
+     events may **ALSO** be emitted: `text`, `audio`, `document`, `photo`,
+     `sticker`, `video`, `voice`, `contact`, `location`,
+     `new_chat_members`, `left_chat_member`, `new_chat_title`,
+     `new_chat_photo`, `delete_chat_photo`, `group_chat_created`,
+     `game`, `pinned_message`, `poll`, `dice`, `migrate_from_chat_id`, `migrate_to_chat_id`,
+     `channel_chat_created`, `supergroup_chat_created`,
+     `successful_payment`, `invoice`, `video_note`
+  1. **Arguments**: `message` ([Message][message]), `metadata` (`{ type?:string }`)
+  1. `new_chat_participant`, `left_chat_participant` are **deprecated**
+1. `callback_query`: Received a new incoming [Callback Query][callback-query]
+1. `inline_query`: Received a new incoming [Inline Query][inline-query]
+1. `chosen_inline_result`: Received result of an inline query i.e. [ChosenInlineResult][chosen-inline-result]
+1. `channel_post`: Received a new incoming channel post of any kind
+1. `edited_message`: Received a new version of a message that is known to the bot and was edited
+  1. `edited_message_text`
+  1. `edited_message_caption`
+1. `edited_channel_post`: Received a new version of a channel post that is known to the bot and was edited
+  1. `edited_channel_post_text`
+  1. `edited_channel_post_caption`
+1. `shipping_query`: Received a new incoming shipping query
+1. `pre_checkout_query`: Received a new  incoming pre-checkout query
+1. `poll`: Received a new  incoming poll
+2. `poll_answer`: A user has changed their answer in a non-anonymous poll (Only polls sent by the bot)
+3. `chat_member`: A chat member's status was updated in a chat
+4. `my_chat_member`: The bot's chat member status was updated in a chat
+5. `chat_join_request`: A request to join the chat has been sent (The bot must have the can_invite_users administrator right)
+5. `polling_error`: Error occurred during polling. See [polling errors](#polling-errors).
+6. `webhook_error`: Error occurred handling a webhook request. See [webhook errors](#webhook-errors).
+7. `error`: Unexpected error occurred, usually fatal!
+
+**Tip:** Its much better to listen a specific event rather than on
+`message` in order to stay safe from the content.
+
+**Tip:** Bot must be enabled on [inline mode][inline-mode] for receive some
+messages.
+
+<a name="webhooks"></a>
+## WebHooks
+
+Telegram only supports HTTPS connections to WebHooks.
+Therefore, in order to set a WebHook, you will need a SSL certificate.
+Since August 29, 2015 Telegram supports self-signed ones, thus, you can
+generate them:
+
+```bash
+# Our private cert will be key.pem, keep this file private
+$ openssl genrsa -out key.pem 2048
+
+# Our public certificate will be crt.pem
+$ openssl req -new -sha256 -key key.pem -out crt.pem
+```
+
+Once they are generated, the `crt.pem` should be uploaded, when setting up
+your webhook. For example,
+
+```js
+bot.setWebHook('public-url.com', {
+  certificate: 'path/to/crt.pem', // Path to your crt.pem
+});
+```
+
+**Note:** If you encounter an error, like
+`Error: error:0906D06C:PEM routines:PEM_read_bio:no start line`,
+you may want to proceed to [this issue][issue-63] for more information.
+
+<a name="sending-files"></a>
+## Sending files
+
+The library makes it easy to get started sending files. *By default*, you
+may provide a **file-path** and the library will handle reading it for you.
+For example,
+
+```js
+bot.sendAudio(chatId, 'path/to/audio.mp3');
+```
+
+You may also pass in a **Readable Stream** from which data will be piped.
+For example,
+
+```js
+const stream = fs.createReadStream('path/to/audio.mp3');
+bot.sendAudio(chatId, stream);
+```
+
+You may also pass in a **Buffer** containing the contents of your file.
+For example,
+
+```js
+const buffer = fs.readFileSync('path/to/audio.mp3'); // sync! that's sad! :-( Just making a point!
+bot.sendAudio(chatId, buffer);
+```
+
+If you already have a **File ID**, you earlier retrieved from Telegram,
+you may pass it in, for example:
+
+```js
+const fileId = getFileIdSomehow();
+bot.sendAudio(chatId, fileId);
+```
+
+Some API methods, such as *SendPhoto*, allow passing a **HTTP URL**, that
+the Telegram servers will use to download the file. For example,
+
+```js
+const url = 'https://telegram.org/img/t_logo.png';
+bot.sendPhoto(chatId, url);
+```
+
+If you wish to explicitly specify the filename or
+[MIME type](http://en.wikipedia.org/wiki/Internet_media_type),
+you may pass an additional argument as file options, like so:
+
+```js
+const fileOptions = {
+  // Explicitly specify the file name.
+  filename: 'customfilename',
+  // Explicitly specify the MIME type.
+  contentType: 'audio/mpeg',
+};
+bot.sendAudio(chatId, data, {}, fileOptions);
+```
+
+**NOTE:** You **MUST** provide an empty object (`{}`) in place of
+*Additional Telegram query options*, if you have **no** query options
+to specify. For example,
+
+```js
+// WRONG!
+// 'fileOptions' will be taken as additional Telegram query options!!!
+bot.sendAudio(chatId, data, fileOptions);
+
+// RIGHT!
+bot.sendAudio(chatId, data, {}, fileOptions);
+```
+
+
+<a name="sending-files-options"></a>
+### File Options (metadata)
+
+When sending files, the library automatically resolves
+the `filename` and `contentType` properties.
+**For now, this has to be manually activated using environment
+variable `NTBA_FIX_350`.**
+
+In order of highest-to-lowest precedence in searching for
+a value, when resolving the `filename`:
+
+*(`fileOptions` is the Object argument passed to the method.
+The "file" argument passed to the method can be a `Stream`,
+`Buffer` or `filepath`.)*
+
+1. Is `fileOptions.filename` explictly defined?
+1. Does `Stream#path` exist?
+1. Is `filepath` provided?
+1. Default to `"filename"`
+
+And the `contentType`:
+
+1. Is `fileOptions.contentType` explictly-defined?
+1. Does `Stream#path` exist?
+1. Try detecting file-type from the `Buffer`
+1. Is `filepath` provided?
+1. Is `fileOptions.filename` explicitly defined?
+1. Default to `"application/octet-stream"`
+
+<a name="sending-files-performance"></a>
+### Performance Issue
+
+To support providing file-paths to methods that send files involves
+performing a file operation, i.e. *fs.existsSync()*, that checks for
+the existence of the file at the provided path. While the cost of
+this operation *might* be negligible in most use cases, if you want
+to squeeze the best performance out of this library, you may wish to
+disable this behavior.
+
+This will mean that you will **NOT** be able to pass in file-paths.
+You will have to use Streams or Buffers to provide the file contents.
+
+Disabling this behavior:
+
+```js
+const bot = new TelegramBot(token, {
+  filepath: false,
+});
+```
+
+<a name="error-handling"></a>
+## Error handling
+
+Every `Error` object we pass back has the properties:
+
+* `code` (String):
+  * value is `EFATAL` if error was fatal e.g. network error
+  * value is `EPARSE` if response body could **not** be parsed
+  * value is `ETELEGRAM` if error was returned from Telegram servers
+* `response` ([http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)):
+  * available if `error.code` is **not** `EFATAL`
+* `response.body` (String|Object): Error response from Telegram
+  * type is `String` if `error.code` is `EPARSE`
+  * type is `Object` if `error.code` is `ETELEGRAM`
+
+For example, sending message to a non-existent user:
+
+```js
+bot.sendMessage(nonExistentUserId, 'text').catch((error) => {
+  console.log(error.code);  // => 'ETELEGRAM'
+  console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' }
+});
+```
+
+<a name="polling-errors"></a>
+## Polling errors
+
+An error may occur during polling. It is up to you to handle it
+as you see fit. You may decide to crash your bot after a maximum number
+of polling errors occurring. **It is all up to you.**
+
+By default, the polling error is just logged to stderr, if you do
+**not** handle this event yourself.
+
+Listen on the `'polling_error'` event. For example,
+
+```js
+bot.on('polling_error', (error) => {
+  console.log(error.code);  // => 'EFATAL'
+});
+```
+
+<a name="webhook-errors"></a>
+## WebHook errors
+
+Just like with [polling errors](#polling-errors), you decide on how to
+handle it. By default, the error is logged to stderr.
+
+Listen on the `'webhook_error'` event. For example,
+
+```js
+bot.on('webhook_error', (error) => {
+  console.log(error.code);  // => 'EPARSE'
+});
+```
+
+[update]:https://core.telegram.org/bots/api#update
+[message]:https://core.telegram.org/bots/api#message
+[callback-query]:https://core.telegram.org/bots/api#callbackquery
+[inline-query]:https://core.telegram.org/bots/api#inlinequery
+[chosen-inline-result]:https://core.telegram.org/bots/api#choseninlineresult
+[inline-mode]:https://core.telegram.org/bots/api#inline-mode
+[issue-63]:https://github.com/yagop/node-telegram-bot-api/issues/63

package/index.js

@@ -0,0 +1,13 @@
+/**
+ * If running on Nodejs 5.x and below, we load the transpiled code.
+ * Otherwise, we use the ES6 code.
+ * We are deprecating support for Node.js v5.x and below.
+ */
+const majorVersion = parseInt(process.versions.node.split('.')[0], 10);
+if (majorVersion <= 5) {
+  const deprecate = require('./src/utils').deprecate;
+  deprecate('Node.js v5.x and below will no longer be supported in the future');
+  module.exports = require('./lib/telegram');
+} else {
+  module.exports = require('./src/telegram');
+}

package/lib/errors.js

@@ -0,0 +1,112 @@
+'use strict';
+
+var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }();
+
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+
+function _possibleConstructorReturn(self, call) { if (!self) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return call && (typeof call === "object" || typeof call === "function") ? call : self; }
+
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; }
+
+exports.BaseError = function (_Error) {
+  _inherits(BaseError, _Error);
+
+  /**
+   * @class BaseError
+   * @constructor
+   * @private
+   * @param  {String} code Error code
+   * @param  {String} message Error message
+   */
+  function BaseError(code, message) {
+    _classCallCheck(this, BaseError);
+
+    var _this = _possibleConstructorReturn(this, (BaseError.__proto__ || Object.getPrototypeOf(BaseError)).call(this, code + ': ' + message));
+
+    _this.code = code;
+    return _this;
+  }
+
+  _createClass(BaseError, [{
+    key: 'toJSON',
+    value: function toJSON() {
+      return {
+        code: this.code,
+        message: this.message
+      };
+    }
+  }]);
+
+  return BaseError;
+}(Error);
+
+exports.FatalError = function (_exports$BaseError) {
+  _inherits(FatalError, _exports$BaseError);
+
+  /**
+   * Fatal Error. Error code is `"EFATAL"`.
+   * @class FatalError
+   * @constructor
+   * @param  {String|Error} data Error object or message
+   */
+  function FatalError(data) {
+    _classCallCheck(this, FatalError);
+
+    var error = typeof data === 'string' ? null : data;
+    var message = error ? error.message : data;
+
+    var _this2 = _possibleConstructorReturn(this, (FatalError.__proto__ || Object.getPrototypeOf(FatalError)).call(this, 'EFATAL', message));
+
+    if (error) {
+      _this2.stack = error.stack;
+      _this2.cause = error;
+    }
+    return _this2;
+  }
+
+  return FatalError;
+}(exports.BaseError);
+
+exports.ParseError = function (_exports$BaseError2) {
+  _inherits(ParseError, _exports$BaseError2);
+
+  /**
+   * Error during parsing. Error code is `"EPARSE"`.
+   * @class ParseError
+   * @constructor
+   * @param  {String} message Error message
+   * @param  {http.IncomingMessage} response Server response
+   */
+  function ParseError(message, response) {
+    _classCallCheck(this, ParseError);
+
+    var _this3 = _possibleConstructorReturn(this, (ParseError.__proto__ || Object.getPrototypeOf(ParseError)).call(this, 'EPARSE', message));
+
+    _this3.response = response;
+    return _this3;
+  }
+
+  return ParseError;
+}(exports.BaseError);
+
+exports.TelegramError = function (_exports$BaseError3) {
+  _inherits(TelegramError, _exports$BaseError3);
+
+  /**
+   * Error returned from Telegram. Error code is `"ETELEGRAM"`.
+   * @class TelegramError
+   * @constructor
+   * @param  {String} message Error message
+   * @param  {http.IncomingMessage} response Server response
+   */
+  function TelegramError(message, response) {
+    _classCallCheck(this, TelegramError);
+
+    var _this4 = _possibleConstructorReturn(this, (TelegramError.__proto__ || Object.getPrototypeOf(TelegramError)).call(this, 'ETELEGRAM', message));
+
+    _this4.response = response;
+    return _this4;
+  }
+
+  return TelegramError;
+}(exports.BaseError);