Documentation for the gaming platform and the debug logging

ALCC01 · ALCC01 · commit a736e91a8df1 · 2016-10-03T22:24:47.000+02:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -76,14 +76,17 @@ Nodeogram is released under the GNU General Public License 3.0.
     :caption: Objects
     :glob:
 
+    objects/Animation
     objects/Bot
-    objects/Chat
-    objects/User
-    objects/Message
-    objects/Keyboard
     objects/CallbackQuery
-    objects/ChosenInlineResult
+    objects/Chat
     objects/ChatMember
+    objects/ChosenInlineResult
     objects/File
+    objects/Game
+    objects/GameHighScore
     objects/InlineQuery
+    objects/Keyboard
+    objects/Message
+    objects/User
     objects/UserProfilePhotos
diff --git a/docs/objects/Animation.rst b/docs/objects/Animation.rst
@@ -0,0 +1,20 @@
+Animation
+=========
+
+This object represents an animation for a Telegram game.
+
+.. note::
+
+    This object inherits some properties from the corresponding `Telegram object <https://core.telegram.org/bots/api#animation>`_.
+
+.. js:class:: Animation(object, bot)
+
+.. warning::
+
+    This constructor should be for internal use only.
+
+Creates a new Animation object.
+
+.. js:attribute:: Message.photo
+
+    Array of :doc:`PhotoSize` objects.
diff --git a/docs/objects/Bot.rst b/docs/objects/Bot.rst
@@ -34,7 +34,8 @@ This object represents a Telegram bot.
             webhookPort: 8080,
             webhookFunction: (req, res) => {...},
             // Should the bot automatically fetch/listen for updates?
-            autoFetch: true
+            autoFetch: true,
+            debug: false
         }
 
 .. _init:
@@ -117,9 +118,16 @@ This object represents a Telegram bot.
     :param object options: *Optional*
     :returns: A promise that resolves to a :doc:`Message` object representing what has been sent.
 
-
     Sends a contact object to the specified chat.
 
+.. js:function:: sendGame(chat_id, game_short_name[, options])
+
+    :param string chat_id: Can also be a :doc:`Chat` or a :doc:`User` object
+    :param string game_short_name: The Telegram identifier for the game
+    :returns: A promise that resolves to a :doc:`Message` object representing what has been sent.
+
+    Sends a game to the specified chat.
+
 .. js:function:: forwardMessage(chat_id, from_chat_id, message_id[, options])
 
     :param string chat_id: Can also be a :doc:`Chat` or a :doc:`User` object
@@ -130,11 +138,10 @@ This object represents a Telegram bot.
 
     Forwards a message to the specified chat,
 
-.. js:function:: answerCallbackQuery(id, text, alert)
+.. js:function:: answerCallbackQuery(id, options)
 
     :param string id:
-    :param string text:
-    :param boolean alert: Whether the user should be shown an alert
+    :param object options: **Not optional**
     :returns: A promise that resolves to the response (according to Telegram, true on success).
 
     Answers a callback query.
@@ -207,6 +214,28 @@ This object represents a Telegram bot.
 
     Updates the specified message markup in the specified chat.
 
+.. js:function:: setGameScore(id, user_id, score, inline, options, chat_id)
+
+    :param string id: The message id
+    :param string user_id: Can also be a :doc:`User` object
+    :param number score:
+    :param boolean inline: Is the message an inline one?
+    :param object options:
+    :param string chat_id: Can also be a :doc:`Chat` or a :doc:`User` object
+    :returns: A promise that resolves to a :doc:`Message` object representing the updated message. True is returned by the promise if the message is an inline one or if the request did not instruct Telegram to edit the original message.
+
+    Sets a user's score for a game.
+
+.. js:function:: getGameHighScores(id, user_id, inline, chat_id)
+
+    :param string id: The message id
+    :param string user_id: Can also be a :doc:`User` object
+    :param boolean inline: Is the message an inline one?
+    :param string chat_id: Can also be a :doc:`Chat` or a :doc:`User` object
+    :returns: A promise that resolves to an array of :doc:`GameHighScore` objects.
+
+    Returns information about the user's rank and score for a game.
+
 .. js:function:: getChatAdministrators (chat_id)
 
     :param string chat_id: Can also be a :doc:`Chat` object
diff --git a/docs/objects/CallbackQuery.rst b/docs/objects/CallbackQuery.rst
@@ -15,10 +15,9 @@ This object represents a Telegram callback query.
 
 Creates a new CallbackQuery object.
 
-.. js:function:: answer(text, alert)
+.. js:function:: answer(options)
 
-    :param string text:
-    :param boolean alert: Whether the user should be shown an alert
+    :param object options: **Not optional**
     :returns: A promise that resolves to the response (according to Telegram, true on success).
 
     Answers the query.
diff --git a/docs/objects/Chat.rst b/docs/objects/Chat.rst
@@ -58,6 +58,14 @@ Creates a new Chat object.
 
     Sends a contact object to the chat.
 
+.. js:function:: sendGame (game_short_name[, options])
+
+    :param string game_short_name: The Telegram game identifier.
+    :param object options: *Optional*
+    :returns: A promise that resolves to a :doc:`Message` object representing what has been sent.
+
+    Sends a Telegram game to the chat.
+
 .. js:function:: forwardMessage(from_chat_id, message_id[, options])
 
     :param string from_chat_id:
diff --git a/docs/objects/Game.rst b/docs/objects/Game.rst
@@ -0,0 +1,53 @@
+Game
+====
+
+This object represents a Telegram game.
+
+.. note::
+
+    This object inherits some properties from the corresponding `Telegram object <https://core.telegram.org/bots/api#game>`_.
+
+.. js:class:: Game(object, bot)
+
+.. warning::
+
+    This constructor should be for internal use only.
+
+Creates a new Game object.
+
+.. js:attribute:: Game.commands
+
+    Array of objects, each one representing a command in the game description.
+
+.. code-block:: javascript
+
+    // Recipient is undefined if it's a direct command
+    {command: '/echo', recipient: 'yourbot', args: ['Many', 'things']}
+
+.. js:attribute:: Game.mentions
+
+    Array of strings, each one representing a mention (e.g. @nickname) in the game description.
+
+.. js:attribute:: Game.hashtags
+
+    Array of strings, each one representing an hashtag (e.g. #things) in the game description.
+
+.. js:attribute:: Game.links
+
+    Array of objects, each one representing a link (both URL and parsed text links) in the game description.
+
+.. code-block:: javascript
+
+    // URL
+    {type: 'url', url: 'http://google.com', text: 'http://google.it'}
+
+    // Text link
+    {type: 'link', url: 'http://google.com', text: 'Google'}
+
+.. js:attribute:: Game.text_mentions
+
+    Array of objects, each one representing a text mention (i.e. mentions of users without a nickname) in the game description.
+
+.. code-block:: javascript
+
+    {text: 'User', user: <User>}
diff --git a/docs/objects/GameHighScore.rst b/docs/objects/GameHighScore.rst
@@ -0,0 +1,16 @@
+GameHighScore
+=============
+
+This object represents an high score for a user on the Telegram gaming platform.
+
+.. note::
+
+    This object inherits some properties from the corresponding `Telegram object <https://core.telegram.org/bots/api#gamehighscore>`_.
+
+.. js:class:: GameHighScore(object, bot)
+
+.. warning::
+
+    This constructor should be for internal use only.
+
+Creates a new GameHighScore object.
diff --git a/docs/objects/InlineQueryResult.rst b/docs/objects/InlineQueryResult.rst
@@ -90,4 +90,10 @@ the objects' properties are directly inherited from the upstream Telegram API.
     :param string id:
     :param string voice_url:
     :param string title:
+    :param object options: *Optional*.
+
+.. js:class:: InlineQueryResultGame(id, game_short_name[, options])
+
+    :param string id:
+    :param string game_short_name:
     :param object options: *Optional*.
diff --git a/docs/objects/Message.rst b/docs/objects/Message.rst
@@ -57,6 +57,24 @@ Creates a new Message object.
 
     Updates the specified message markup.
 
+.. js:function:: setGameScore(user_id, score, inline[, options])
+
+    :param string user_id: Can also be a :doc:`User` object
+    :param number score:
+    :param boolean inline: Is the message an inline one?
+    :param object options:
+    :returns: A promise that resolves to a :doc:`Message` object representing the updated message. True is returned by the promise if the message is an inline one or if the request did not instruct Telegram to edit the original message.
+
+    Sets a user's score for a game.
+
+.. js:function:: getGameHighScores(user_id, inline)
+
+    :param string user_id: Can also be a :doc:`User` object
+    :param boolean inline: Is the message an inline one?
+    :returns: A promise that resolves to an array of :doc:`GameHighScore` objects.
+
+    Returns information about the user's rank and score for a game.
+
 .. js:attribute:: Message.commands
 
     Array of objects, each one representing a command in the message.
diff --git a/docs/objects/User.rst b/docs/objects/User.rst
@@ -77,6 +77,14 @@ Creates a new User object.
     :param string action: <String> Must be one of the following: ``typing``, ``upload_photo``, ``record_video``, ``upload_video``, ``record_audio``, ``upload_audio``, ``upload_document``, ``find_location``
     :returns: A promise that resolves to the response (true on success).
 
+.. js:function:: sendGame (game_short_name[, options])
+
+    :param string game_short_name: The Telegram game identifier.
+    :param object options: *Optional*
+    :returns: A promise that resolves to a :doc:`Message` object representing what has been sent.
+
+    Sends a Telegram game to the user.
+
 .. js:function:: getProfilePhotos(options)
 
     :param object options: *Optional*
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -402,4 +402,11 @@ if they match a regular expression (regex).
         }
     }, (result) => {
         message.from.sendMessage(`Your name is ${result.name} ${result.surname}`)
-    })
+    })
+
+=========
+Debugging
+=========
+
+Your bot is not behaving like it should be? Some extra information about the inner processes of the library may help! Try
+starting your bot by setting the environment variable ``NODEOGRAM_DEBUG`` to true or set ``debug`` to true in the bot options.
diff --git a/lib/Animation.js b/lib/Animation.js
@@ -2,6 +2,7 @@
 const extend = require('util')._extend;
 
 function Animation(object, bot) {
+    if (object == undefined) return;
     this.bot = bot;
     extend(this, object);
 
diff --git a/lib/Bot.js b/lib/Bot.js
@@ -293,6 +293,8 @@ function Bot(token, options) {
     this.answerCallbackQuery = (id, options, alert) => {
         // TODO Drop support for the old method signature
         if (typeof options === 'string') {
+            console.log('WARNING! The old answerCallbackQuery method signature is deprecated and will likely be removed in the next releases.');
+            console.trace();
             options = {
                 text: options,
                 alert: alert
diff --git a/lib/CallbackQuery.js b/lib/CallbackQuery.js
@@ -15,12 +15,14 @@ function CallbackQuery(object, bot) {
     this.answer = (options, alert) => {
         // TODO Drop support for the old method signature
         if (typeof options === 'string') {
+            console.log('WARNING! The old answerCallbackQuery method signature is deprecated and will likely be removed in the next releases.');
+            console.trace();
             options = {
                 text: options,
                 alert: alert
             }
         }
-        this.bot.answerCallbackQuery(this.id, options || options)
+        this.bot.answerCallbackQuery(this.id, options)
     }
 }
 
diff --git a/lib/GameHighScore.js b/lib/GameHighScore.js
@@ -3,6 +3,7 @@ const User = require('./User.js'),
     extend = require('util')._extend;
 
 function GameHighScore(object, bot) {
+    if (object == undefined) return;
     extend(this, object);
     this.bot = bot;
 
