V2 - Big update

lib/.eslintrc

@@ -1,5 +1,59 @@
 {
+  "env": {
+    "es6": true,
+    "browser": true
+  },
+  "ecmaFeatures": {
+    "modules": true
+  },
+  "globals": {
+    "exports": true,
+    "require": true,
+    "ViewHelpers": true,
+    "is": true,
+    "Components": true,
+    "XPCOMUtils": true,
+    "EventEmitter": true,
+    "add_task": true,
+    "info": true,
+    "createHost": true,
+    "promiseTab": true,
+    "ok": true,
+    "TEST_URI_ROOT": true,
+    "TargetFactory": true,
+    "gBrowser": true,
+    "gDevTools": true
+  },
   "rules": {
+    "comma-dangle": [2, "never"],
+    "no-underscore-dangle": 0,
+    "no-cond-assign": 0,
+    "no-undef": 0,
+    "no-console": 0,
+    "no-reserved-keys": 2,
+    "valid-jsdoc": [2, {
+      "requireReturn": false,
+      "requireParamDescription": false,
+      "requireReturnDescription": false
+    }],
+    "max-len": [1, 80],
+    "no-use-before-define": 0,
+    "no-self-compare": 1,
+    "no-sequences": 0,
+    "radix": 2,
+    "wrap-iife": 2,
+    "indent": [2, 2],
+    "brace-style": [2, "1tbs"],
+    "comma-style": [2, "last"],
+    "no-lonely-if": 2,
+    "no-multiple-empty-lines": [2, {"max": 2}],
+    "quotes": 0,
+    "space-after-keywords": [2, "always"],
+    "space-before-blocks": [2, "always"],
+    "space-infix-ops": [2, { "int32Hint": false }],
+    "strict": 0,
+    "global-strict": 0,
+    "no-new": 0,
     "camelcase": 0
   }
 }

lib/api.js

@@ -1,8 +1,22 @@
 // API methods
 import fetch from './fetch';
 
-export default function API(token) {
-  this.token = token;
+/**
+ * API class, has a function for each method of the Telegram API which take
+ * an object argument, and send request to the API server
+ *
+ * Methods: getMe, sendMessage, forwardMessage, sendPhoto, sendAudio,
+ * sendDocument, sendSticker, sendVideo, sendLocation, sendChatAction,
+ * getUserProfilePhotos, getUpdates
+ */
+export default class API {
+  /**
+   * Create a new api object with the given token
+   * @param  {string} token
+   */
+  constructor(token) {
+    this.token = token;
+  }
 }
 
 API.prototype.request = function request(method, data) {

lib/classes/Keyboard.js

@@ -1,61 +0,0 @@
-export default class Keyboard {
-  constructor(message, options = {}) {
-    this.message = message;
-    this.replyMarkup = options;
-  }
-
-  keys(keys) {
-    this.setProperties({
-      keyboard: keys,
-      hide_keyboard: false
-    });
-    return this;
-  }
-
-  force(enable = true) {
-    this.setProperties({
-      force_keyboard: enable
-    });
-    return this;
-  }
-
-  resize(enable = true) {
-    this.setProperties({
-      resize: enable
-    });
-    return this;
-  }
-
-  oneTime(enable = true) {
-    this.setProperties({
-      one_time_keyboard: enable
-    });
-    return this;
-  }
-
-  selective(enable = true) {
-    this.setProperties({
-      selective: enable
-    });
-    return this;
-  }
-
-  hide() {
-    this.replyMarkup = {
-      hide_keyboard: true
-    };
-
-    return this;
-  }
-
-  get replyMarkup() {
-    return JSON.parse(this.message.params.reply_markup);
-  }
-  set replyMarkup(json) {
-    this.message.params.reply_markup = JSON.stringify(json);
-  }
-
-  setProperties(object) {
-    this.replyMarkup = Object.assign(this.replyMarkup, object);
-  }
-}

lib/classes/Message.js

@@ -1,77 +0,0 @@
-import {EventEmitter} from 'events';
-import Keyboard from './Keyboard';
-
-export default class Message extends EventEmitter {
-  constructor(options = {}) {
-    super();
-
-    this.params = options;
-  }
-
-  to(chat) {
-    this.params.chat_id = chat;
-    return this;
-  }
-
-  text(text) {
-    this.params.text = text;
-    return this;
-  }
-
-  reply(chat) {
-    this.params.reply_to_message_id = chat;
-    return this;
-  }
-
-  keyboard(options) {
-    let params;
-
-    if (this._keyboard && !options) {
-      return this._keyboard;
-    }
-
-    if (this._keyboard) {
-      params = Object.assign(this._keyboard.replyMarkup, options);
-    } else {
-      params = options;
-    }
-
-    this._keyboard = new Keyboard(this, params);
-    return this._keyboard;
-  }
-
-  send(bot) {
-    let messageId;
-
-    return new Promise(resolve => {
-      bot.api.sendMessage(this.params).then(response => {
-        messageId = response.result.message_id;
-        this.emit('message:sent', response);
-      });
-
-      if (this.keyboard().replyMarkup.one_time_keyboard) {
-        this.keyboard().replyMarkup = '';
-      }
-
-      const chat = this.params.chat_id;
-      bot.on('update', function listener(result) {
-        const update = result.find(({message}) => {
-          // if in a group, there will be a reply to this message
-          if (chat < 0) {
-            return message.chat.id === chat &&
-                   message.reply_to_message.message_id === messageId;
-          } else {
-            return message.chat.id === chat;
-          }
-        });
-
-        if (update) {
-          resolve(update);
-          this.emit('message:answer', update);
-
-          bot.removeListener('update', listener);
-        }
-      });
-    });
-  }
-}

lib/classes/Question.js

@@ -1,43 +0,0 @@
-import Message from './Message';
-
-export default class Question extends Message {
-  constructor(options = {}) {
-    super(options);
-
-    this.keyboard().force().oneTime().selective();
-  }
-
-  answers(answers) {
-    this.answers = answers;
-    this.keyboard().keys(answers);
-    return this;
-  }
-
-  send(bot) {
-    const answers = this.answers;
-
-    return new Promise((resolve, reject) => {
-      super.send(bot).then(update => {
-        const message = update.message;
-        let answer;
-
-        answers.forEach(function find(a) {
-          if (Array.isArray(a)) {
-            a.forEach(find);
-          }
-          if (a === message.text) {
-            answer = a;
-          }
-        });
-
-        if (answer) {
-          resolve(answer, update);
-          this.emit('question:answer', answer, update);
-        } else {
-          reject(update);
-          this.emit('question:invalid', update);
-        }
-      });
-    });
-  }
-}

lib/fetch.js

@@ -1,7 +1,7 @@
 import https from 'https';
 import qs from 'qs';
 
-export default function(path, data) {
+export default function fetch(path, data) {
   const post = qs.stringify(data);
 
   return new Promise((resolve, reject) => {

lib/index.js

@@ -1,3 +1,4 @@
+import 'babel/polyfill';
 import API from './api';
 import {EventEmitter} from 'events';
 
@@ -9,11 +10,23 @@ const DEFAULTS = {
   }
 };
 
-export default class Bot {
+/**
+ * Bot class used to connect to a new bot
+ * Bots have an api property which gives access to all Telegram API methods,
+ * see API class
+ */
+export default class Bot extends EventEmitter {
+  /**
+   * Create and connect to a new bot
+   * @param  {object} options Bot properties.
+   */
   constructor(options = {update: {}}) {
+    super();
+
     if (!options.token) {
       throw new Error('Token cannot be empty');
     }
+
     this.token = options.token;
     this.update = Object.assign(options.update || {}, DEFAULTS.update);
 
@@ -26,6 +39,13 @@ export default class Bot {
     this._userEvents = [];
   }
 
+  /**
+   * Gets information about the bot and then starts polling updates from API
+   * Emits an `update` event after polling with the response from server
+   * Returns a promise which is resolved after the bot information is received
+   * and set to it's `info` property i.e. bot.info
+   * @return {promise} A promise which is resolved with the response of getMe
+   */
   start() {
     let poll = function() {
       this.api.getUpdates(this.update).then(response => {
@@ -47,13 +67,13 @@ export default class Bot {
         this.emit('update', response.result);
         result.forEach(res => {
           let text = res.message.text;
-          if (text.indexOf('/') === 0) {
-            // Commands are sent in format /command@botusername format
+          if (text.startsWith('/')) {
+            // Commands are sent in /command@botusername format in groups
             const regex = new RegExp(`@${this.info.username}$`);
             text = text.replace(regex, '');
           }
 
-          let ev = this._userEvents.find(({message}) => message.test(text));
+          let ev = this._userEvents.find(({pattern}) => pattern.test(text));
           ev.listener(res);
         });
       });
@@ -65,26 +85,50 @@ export default class Bot {
     });
   }
 
-  get(message, listener) {
-    if (typeof message === 'string') {
-      message = new RegExp(`^${message}`);
+  /**
+   * Listens on specific message matching the pattern which can be an string
+   * or a regexp.
+   * @param  {string/regex} pattern
+   * @param  {function} listener function to call when a message matching the
+   *                             pattern is found, gets the Update
+   *                             In case of string, the message should start
+   *                             with the string i.e. /^yourString/
+   * @return {object} returns the bot object
+   */
+  get(pattern, listener) {
+    if (typeof pattern === 'string') {
+      pattern = new RegExp(`^${pattern}`);
     }
 
     this._userEvents.push({
-      message, listener
+      pattern, listener
     });
+
+    return this;
   }
 
+  /**
+   * Listens on a command
+   * @param  {string} cmd the command string, should not include slash (/)
+   * @param  {function} listener function to call when the command is received,
+   *                           gets the update
+   * @return {object} returns the bot object
+   */
   command(cmd, listener) {
     this._userEvents.push({
-      message: new RegExp(`/${cmd}`),
+      pattern: new RegExp(`/${cmd}`),
       listener
     });
+
+    return this;
   }
 
+  /**
+   * Sends the message provided
+   * @param  {object} message The message to send. Gets it's send method called
+   * @return {unknown} returns the result of calling message's send method
+   */
   send(message) {
     return message.send(this);
   }
 }
-
-Bot.prototype = Object.assign(Bot.prototype, EventEmitter.prototype);

lib/types/Base.js

@@ -0,0 +1,35 @@
+import {EventEmitter} from 'events';
+
+/**
+ * Base class of all classes
+ */
+export default class Base extends EventEmitter {
+  constructor() {
+    super();
+    this.properties = {};
+  }
+
+  /**
+   * Returns properties of the object
+   * @return {object} properties of object
+   */
+  getProperties() {
+    return this.properties;
+  }
+
+  /**
+   * Set properties of the object
+   * @param {object} object properties to set
+   * @param {boolean} extend A boolean indicating if the properties should be
+   *                         extended by the object provided (Object.assign)
+   *                         or properties should be replaced by the object
+   *                         defaults to true
+   * @return {object} returns the properties (same as getProperties)
+   */
+  setProperties(object, extend = true) {
+    this.properties = extend ? Object.assign(this.properties, object)
+                             : object;
+
+    return this.getProperties();
+  }
+}

lib/types/Keyboard.js

@@ -0,0 +1,85 @@
+import Base from './Base';
+
+/**
+ * Keyboard class, used to configure keyboards for messages.
+ * You should pass your instance of this class to message.keyboard() method
+ */
+export default class Keyboard extends Base {
+  /**
+   * Create a new keyboard
+   * @param  {object} properties Keyboard properties, as defined by Telegram API
+   *                             See ReplyKeyboardMarkup, ReplyKeyboardHide,
+   *                                 ForceReply
+   */
+  constructor(properties = {}) {
+    super();
+
+    this.properties = properties;
+  }
+
+  /**
+   * Set the keyboard property of reply_markup
+   * @param  {array} keys An array of arrays, with the format of
+   *                            Column         Column
+   *                      Row [['TopLeft',   'TopRight'],
+   *                      Row ['BottomLeft', 'BottomRight']]
+   * @return {object} returns the keyboard object
+   */
+  keys(keys) {
+    this.properties.keyboard = keys;
+    this.properties.hide_keyboard = false;
+    return this;
+  }
+
+  /**
+   * Set force_keyboard property of reply_markup
+   * @param  {boolean} enable value of force_keyboard, defaults to true
+   * @return {object} returns the keyboard object
+   */
+  force(enable = true) {
+    this.properties.force_keyboard = enable;
+    return this;
+  }
+
+  /**
+   * Set resize_keyboard property of reply_markup
+   * @param  {boolean} enable value of resize_keyboard, defaults to true
+   * @return {object} returns the keyboard object
+   */
+  resize(enable = true) {
+    this.properties.resize_keyboard = enable;
+    return this;
+  }
+
+  /**
+   * Set force_keyboard property of reply_markup
+   * @param  {boolean} enable value of force_keyboard, defaults to true
+   * @return {object} returns the keyboard object
+   */
+  oneTime(enable = true) {
+    this.properties.one_time_keyboard = enable;
+    return this;
+  }
+
+  /**
+   * Set selective property of reply_markup
+   * @param  {boolean} enable value of force_keyboard, defaults to true
+   * @return {object} returns the keyboard object
+   */
+  selective(enable = true) {
+    this.properties.selective = enable;
+    return this;
+  }
+
+  /**
+   * Set hide_keyboard property of reply_markup to true
+   * @return {object} returns the keyboard object
+   */
+  hide() {
+    this.properties = {
+      hide_keyboard: true
+    };
+
+    return this;
+  }
+}

lib/types/Message.js

@@ -0,0 +1,110 @@
+import Base from './Base';
+
+/**
+ * Message class, used to send message to a chat
+ */
+export default class Message extends Base {
+  /**
+   * Create a new message
+   * @param  {object} properties Message properties, as defined by Telegram API
+   */
+  constructor(properties = {}) {
+    super();
+
+    this.properties = properties;
+    this._keyboard = new Base();
+  }
+
+  /**
+   * Set chat_id of the message
+   * @param  {number} chat
+   * @return {object} returns the message object
+   */
+  to(chat) {
+    this.properties.chat_id = chat;
+    return this;
+  }
+
+  /**
+   * Set text of the message
+   * @param  {string} text Message's content
+   * @return {object} returns the message object
+   */
+  text(text) {
+    this.properties.text = text;
+    return this;
+  }
+
+  /**
+   * Set reply_to_message_id of the message
+   * @param  {number} id message_id of the message to reply to
+   * @return {object} returns the message object
+   */
+  reply(id) {
+    this.properties.reply_to_message_id = id;
+    return this;
+  }
+
+  /**
+   * Sets keyboard of the message
+   * The value of reply_markup is set to the sanitized keyboard properties
+   * i.e. reply_markup = JSON.stringify(kb.getProperties())
+   * @param  {object} kb A Keyboard instance
+   * @return {object} returns the message object
+   */
+  keyboard(kb) {
+    this._keyboard = kb;
+    return this;
+  }
+
+  /**
+   * Sends the message, you should only use this method yourself if
+   * you are extending this class. Normally you should call bot.send(message)
+   *
+   * Events: message:sent => Emitted after sending the message to API, gets the
+   * 												  API's response
+   *
+   *			message:answer => Emitted when your message gets an answer from
+   *				                 the contact (reply in case of groups)
+   *				                 gets the Update object containing message
+   *
+   * @param  {object} bot
+   * @return {promise} returns a promise, resolved with message:answer
+   */
+  send(bot) {
+    let messageId;
+    const reply_markup = JSON.stringify(this._keyboard.getProperties());
+    this.properties.reply_markup = reply_markup;
+
+    return new Promise(resolve => {
+      bot.api.sendMessage(this.properties).then(response => {
+        messageId = response.result.message_id;
+        this.emit('message:sent', response);
+      });
+
+      if (this._keyboard.one_time_keyboard) {
+        this._keyboard.replyMarkup = '';
+      }
+
+      const chat = this.properties.chat_id;
+      bot.on('update', function listener(result) {
+        const update = result.find(({message}) => {
+          // if in a group, there will be a reply to this message
+          if (chat < 0) {
+            return message.chat.id === chat &&
+                   message.reply_to_message.message_id === messageId;
+          } else {
+            return message.chat.id === chat;
+          }
+        });
+
+        if (update) {
+          resolve(update);
+          this.emit('message:answer', update);
+
+          bot.removeListener('update', listener);
+        }
+      });
+    });
+  }
+}

lib/types/Question.js

@@ -0,0 +1,71 @@
+import Message from './Message';
+import Keyboard from './Keyboard';
+
+/**
+ * Question class, extends Message
+ * Sends a message, shows a keyboard with the answers provided, and validates
+ * the answer
+ */
+export default class Question extends Message {
+  /**
+   * Create a new question
+   * @param  {object} options Options, same as Message, plus `answers` which
+   *                          is a keyboard layout, see Keyboard#keys
+   */
+  constructor(options = {}) {
+    super(options);
+
+    let kb = new Keyboard().force().oneTime().selective()
+                           .keys(this.properties.answers);
+    this.keyboard(kb);
+  }
+
+  /**
+   * Sets answers of the question. This is passed to Keyboard#keys, and then
+   * used to validate the answer given
+   * @param  {array} answers Array of arrays of strings, same as Keyboard#keys
+   * @return {object} returns the question object
+   */
+  answers(answers) {
+    this.answers = answers;
+    this._keyboard.keys(answers);
+    return this;
+  }
+
+  /**
+   * Sends the question (same as Message#send), and validates the answer given
+   * if the answer is one of the defined answers, resolves, else rejects
+   * You should not manually use this method unless you're extending this class
+   * You should instead use bot.send(question);
+   * @param  {object} bot
+   * @return {promise} A promise which is resolved in case of valid answer, and
+   *                     rejected in case of invalid answer
+   */
+  send(bot) {
+    const answers = this.answers;
+
+    return new Promise((resolve, reject) => {
+      super.send(bot).then(update => {
+        const message = update.message;
+        let answer;
+
+        answers.forEach(function find(a) {
+          if (Array.isArray(a)) {
+            a.forEach(find);
+          }
+          if (a === message.text) {
+            answer = a;
+          }
+        });
+
+        if (answer) {
+          resolve(answer, update);
+          this.emit('question:answer', answer, update);
+        } else {
+          reject(update);
+          this.emit('question:invalid', update);
+        }
+      });
+    });
+  }
+}