Better error handling

Author: ALCC01

docs/index.rst

@@ -61,11 +61,12 @@ Nodeogram is released under the GNU General Public License 3.0.
 
 .. _user-documentation:
 .. toctree::
-      :maxdepth: 3
-      :caption: User Documentation
-      :glob:
+    :maxdepth: 3
+    :caption: User Documentation
+    :glob:
 
-      quickstart
+    style
+    quickstart
 
 .. _objects-documentation:
 .. toctree::

docs/objects/Bot.rst

@@ -14,12 +14,18 @@ This object represents a Telegram bot.
     :returns: A Bot object
 
     Creates a new Bot object and fetches basic information about it (aysncronous call to Telegram's ``getMe`` method).
+
     Valid ``options`` are:
 
     .. code-block:: javascript
 
     {
-        profiles_path: __dirname +'/profiles.json'
+        // File to which profiles should be saved
+        profiles_path: __dirname +'/profiles.json',
+        // Whether or not users should be saved
+        saveUsers: true;
+        // Whether or not chats should be saved
+        saveChats: true
     }
 
 .. _init:

docs/quickstart.rst

@@ -310,3 +310,12 @@ correct id.
     // Inline message
     if (query.message) query.message.editText(`You have chosen ${query.data}!`, true)
 
+===================
+Profiles management
+===================
+
+Nodeogram provides a simple way for you and your bot to keep track of the users and chats that are using your services by
+its profile management interface. If a bot is instantiated with ``profiles_path`` in its options, it will start saving
+basic information about any user and chat he will become aware of.
+
+The ``broadcast()`` function will enable you to easily access that data and interact with your users.

docs/style.rst

@@ -0,0 +1,38 @@
+Design & Best Practices
+=======================
+
+==============
+Library design
+==============
+
+********
+Promises
+********
+
+The whole Nodeogram library is promise-based. This means that it takes advantage of the relatively new
+`ES6 native implementation <https://developer.mozilla.org/it/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ of
+promises made available in NodeJS starting from release ~0.12.14. Most of the functions provided by the library will
+return promises in order to enable you to escape the `callback hell <http://callbackhell.com/>`_.
+
+***************
+Handling errors
+***************
+
+Nodeogram does not introduce intrusive error handling and as a result you should pay attention and always profile a
+``catch`` function.
+
+Nodeogram's functions can fail at any time - querying the API, attempting to send a message to a chat the
+bot was kicked out of, etc - and not handling errors properly might result in unexpected behaviours or worse - getting
+your bot or IP address tempbanned from Telegram's server could really ruin your day.
+
+==============
+Best practices
+==============
+
+***************************
+Don't feed initialized bots
+***************************
+
+Nodeogram's :doc:`objects/Bot` object is intended to be immutable once it's initialized. Making changes to its attributes after
+calling the ``init()`` function may produce unexpected behaviours in other objects that rely on them (most notably,
+pretty much all of the library objects).

lib/Bot.js

@@ -24,6 +24,8 @@ function Bot(token, options) {
     this.messageHandlers = [];
     this.me = {};
     this.emitter = new events.EventEmitter();
+    this.saveUsers = true;
+    this.saveChats = true;
     extend(this, options);
 
     this.handleAPIError = (err) => {
@@ -49,10 +51,12 @@ function Bot(token, options) {
         return this.post(path, args)
             .end()
             .then((res) => {
-                if (!res.body.ok) throw "Telegram API response was not OK";
+                if (!res.body.ok) throw new Error("Telegram API response was not OK");
                 return res;
             }).catch((err) => {
-                this.handleAPIError(err);
+                if (err.response.error.status == 403 || err.response.error.status == 400) {
+                    throw new Error(JSON.parse(err.response.error.text).description);
+                } else this.handleAPIError(err);
             })
     };
 
@@ -68,7 +72,9 @@ function Bot(token, options) {
                 if (!res.body.ok) throw "Telegram API response was not OK";
                 return res;
             }).catch((err) => {
-                this.handleAPIError(err);
+                if (err.response.error.status == 403 || err.response.error.status == 400) {
+                    throw new Error(JSON.parse(err.response.error.text).description);
+                } else throw err;
             })
     };
 
@@ -418,21 +424,21 @@ function Bot(token, options) {
 
     this.handleProfiles = (message) => {
         var edited = false;
-        if (!profiles.users[message.from.id]) {
+        if (!profiles.users[message.from.id] && this.saveUsers) {
             profiles.users[message.from.id] = message.from;
             profiles.users[message.from.id].bot = undefined;
             edited = true;
         }
-        if (!profiles.chats[message.chat.id]) {
+        if (!profiles.chats[message.chat.id] && this.saveChats) {
             profiles.chats[message.chat.id] = message.chat;
             profiles.chats[message.chat.id].bot = undefined;
             edited = true;
         }
-        if (edited) fs.writeFile(this.profiles_path, JSON.stringify(profiles), (err) => {console.log(err)})
+        if (edited) fs.writeFile(this.profiles_path, JSON.stringify(profiles), (err) => {if (err) console.log(err)})
     };
 
     this.broadcast = (filter, callback) => {
-        if (!this.profiles_path) throw "Profiles path is not defined";
+        if (!this.profiles_path) throw new Error("Profiles path is not defined");
         if (profiles.chats) {
             for (var chat in profiles.chats) {
                 if (profiles.chats.hasOwnProperty(chat)) {
@@ -447,7 +453,7 @@ function Bot(token, options) {
     };
 
     this.init = () => {
-        if (!this.token) throw "Invalid token!";
+        if (!this.token) throw new Error("Invalid token!");
         this.messageHandlers = [
             this.handleCommands,
             this.handleMessage
@@ -469,8 +475,7 @@ function Bot(token, options) {
 
     this.call('getMe', {}).then((res) => {
         if (res) this.me = res.body.result;
-        else throw "Unable to retrieve informations about the bot!"
-    }).catch(err => this.handleAPIError(err));
+    }).catch(err => console.log(err));
 
     // For more complex event handling use this.emitter
     this.on = (event, listener) => {