telegram_bot_middleware 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d39fe2bef0e2ca483f3a3c6d31aac1a4c4d8e14b
-  data.tar.gz: 2a3d02a2962ea2910f93ede19af24b18f5ee2201
+  metadata.gz: 19dee6688c9ccd4a5f152303e79a438a3ada2355
+  data.tar.gz: ccd54a63a55513074a270f07fbcd0018a6a2deca
 SHA512:
-  metadata.gz: 733cbb9bd5f14245bfd6bee885bc7aa86a195db64d7c9657dbcb272267005a6440581ebe33a69063f5d62c923c4f4d40ab8b05aa9217e7d3dd77d94fc86c1b74
-  data.tar.gz: c26f854c127f75e85020acb6c46150632e6664cc2e19ea48ff5093bbe6ead1064ed33743c1ed5227d5eed62d5707ea7f54c5204274d425b41d6307682b33b9fc
+  metadata.gz: 6ff282369b82fd2ca2f8ee923530f0b7a6d1c1b7ab0ce5dc3a675efef887bf8e1b59d008368aadce034593d69376b89bb3f8b0d6cfcc9779d6c40f025019935e
+  data.tar.gz: 8fcdba4d61f4d1c499aa250f10ce4ef4e3af4ad250f3ea3409353bd0dd0d561a75917d98d39ea87d3ef4afbccef395d59b75ea1f060cce575dcbd93964816460

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    telegram_bot_middleware (0.1.0)
+    telegram_bot_middleware (0.2.0)
       httmultiparty
       http
       persistent_httparty
@@ -42,19 +42,19 @@ GEM
       httparty (~> 0.9)
       persistent_http (< 2)
     rake (10.4.2)
-    rspec (3.3.0)
-      rspec-core (~> 3.3.0)
-      rspec-expectations (~> 3.3.0)
-      rspec-mocks (~> 3.3.0)
-    rspec-core (3.3.2)
-      rspec-support (~> 3.3.0)
-    rspec-expectations (3.3.1)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-mocks (3.3.2)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.3.0)
-    rspec-support (3.3.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.0)
     thread_safe (0.3.5)
     unf (0.1.4)
       unf_ext

data/README.md

@@ -1,4 +1,4 @@
-# TelegramBotMiddleware
+# Telegram Bot Middleware
 
 Rack middleware to communicate with a telegram bot.
 
@@ -18,7 +18,7 @@ Or install it yourself as:
 
     $ gem install telegram_bot_middleware
     
-Add the middleware in config.ru or in other files base on the framework you are using:
+Add the middleware in config.ru or in other files based on the framework you are using:
 
 ```ruby
 require 'telegram_bot_middleware'
@@ -36,7 +36,127 @@ end
 
 ## Usage
 
-TODO: Write usage instructions here
+After the middleware is added to your preferred framework and configured as specified in installation instructions, you are ready to receive and send message to your telegram bot.
+Every message from the chat where the bot is added is received from your application as a GET request.
+
+### Text messages
+
+In case of a text message, the text will be escaped as URI and the first work will be the command, let's see how every message is parsed (message -> result):
+* '/test' -> '/test'
+* 'test' -> '/test'
+* 'test test2' -> '/test/test2'
+* 'test test2 test3' -> '/test/test2%20test3'
+
+You can use your preferred framework router to handle the GET requests, for example:
+```ruby
+get %r{/greets/(.*)}i do |name| 
+  "Hello #{name}!"
+end
+```
+If the chat input is for example 'greets Mike' the bot output will be 'Hello Mike!'
+
+Every message received from the chat contains parameters as specified in [bot api](https://core.telegram.org/bots/api#message) in the form of query string parameters, let's see an example:
+```ruby    
+get %r{/hello$}i do 
+  "Hello #{params['from']['first_name']} #{params['from']['last_name']}!"
+end
+```
+
+### Other types of messages
+The middleware supports also every other kind of message from bot, here is the list:
+* audio 
+* document 
+* photo 
+* sticker 
+* video 
+* voice 
+* contact 
+* location 
+* new_chat_participant 
+* left_chat_participant 
+* new_chat_title 
+* new_chat_photo 
+* delete_chat_photo 
+* group_chat_created
+
+Every message of this kind is routed as a GET request, the command is the message itself and the message parameters are in querystring, for example:
+```ruby
+get '/location' do
+  "Your coordinates are: #{params['location']['latitude']} #{params['location']['longitude']}"
+end
+```
+
+### Return types
+Depending on the return types of your functions differents telegram methods are used to send bot messages to chat.
+
+#### Plain text
+When the function return a string is sent as-is using the [sendMessage Telegram function](https://core.telegram.org/bots/api#sendmessage).
+
+#### JSON return types
+When the function return a json a different telegram function is called depending the json content, for example:
+```ruby
+{ text: 'Hello', reply_markup: {keyboard: [%w(A B), %w(C D)]} }
+```
+In this case the [sendMessage Telegram function](https://core.telegram.org/bots/api#sendmessage) is called but with additional parameter as specified (reply_markup in this case). You can use every telegram functions parameter.
+
+To return a location the json has to contains latitude and longitude, obviously is possible to use every optional parameters as specified in [sendLocation Telegram function](https://core.telegram.org/bots/api#sendlocation)
+```ruby
+{ latitude: 38.115036, longitude: 13.366640 }
+```
+
+To return a photo with a caption it's necessary to specify the picture path:
+```ruby
+{ photo: 'tmp/test.png', caption: 'Awesome picture!' }
+```
+The same to return other types according to [Telegram documentation](https://core.telegram.org/bots/api#available-methods)
+
+#### Documents, audio, video, images...
+If the function returns a file, as showing in the following sinatra snippet:
+```ruby
+send_file 'tmp/test.png'
+```
+According to the file MIME type the appropriate telegram function is called, [sendPhoto](https://core.telegram.org/bots/api#sendphoto) in this example.
+
+#### Multiple return messages
+Sometimes can be useful to return more than one message, do this is very simple, it's enough to return an array of single messages json encapsulated with the multiple keyword, example:
+```ruby
+{
+  multiple: 
+  [
+    {
+      photo: 'tmp/test.png',
+      caption: 'image caption'
+    },
+    {
+      text: 'Hello'
+    },
+    {
+      latitude: 38.115036, 
+      longitude: 13.366640
+    }
+  ]
+}
+```
+In this case the bot will send an image, a message and a location.
+
+## Examples
+
+To run an example call:
+```shell
+    $ rackup
+```
+In the desired example folder
+
+### Basic examples in various frameworks
+There are various ready to go basic examples in the following frameworks:
+* [Sinatra](https://github.com/MirkoMignini/telegram_bot_middleware/tree/master/examples/sinatra)
+* [Cuba](https://github.com/MirkoMignini/telegram_bot_middleware/tree/master/examples/cuba)
+* [Roda](https://github.com/MirkoMignini/telegram_bot_middleware/tree/master/examples/roda)
+* [Rack](https://github.com/MirkoMignini/telegram_bot_middleware/tree/master/examples/rack)
+
+### Little bot examples:
+* [Calculator (sinatra)](https://github.com/MirkoMignini/telegram_bot_middleware/blob/master/examples/sinatra/calc.rb)
+* [Random joke from Chuck Norris database (sinatra)](https://github.com/MirkoMignini/telegram_bot_middleware/blob/master/examples/sinatra/chuck_norris.rb)
 
 ## Development
 
@@ -48,7 +168,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/MirkoMignini/telegram_bot_middleware. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](contributor-covenant.org) code of conduct.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/examples/sinatra/example.rb

@@ -7,7 +7,7 @@ get %r{/hello$}i do
   }
 end
 
-get %r{/hello/(.*)}i do |name|
+get %r{/greets/(.*)}i do |name|
   "Hello #{name}!"
 end
 

data/examples/sinatra/example_init.rb

@@ -1,6 +1,10 @@
 require 'sinatra'
 require_relative '../../lib/telegram_bot_middleware'
 
+configure :development do
+  set :logging, Logger::DEBUG
+end
+
 use TelegramBotMiddleware do |config|
   config.token = '138381425:AAEXjzZx5U5wZmiKvFmHjdNMkXJqnkHnum4'
   #config.host = 'https://telegram-bot-middleware.herokuapp.com'

data/lib/telegram_bot_middleware/version.rb

@@ -1,3 +1,3 @@
 class TelegramBotMiddleware
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/telegram_bot_middleware.rb

@@ -9,17 +9,19 @@ require_relative 'telegram_bot_middleware/version'
 class TelegramBotMiddleware
   include HTTMultiParty
   base_uri 'https://api.telegram.org'
-  persistent_connection_adapter pool_size: 1,
-                                keep_alive: 30,
-                                force_retry: true
   
-  def initialize(app, &block)
+  def initialize(app, &block)    
     # save the app var
     @app = app
+    @env = nil
     
     # create the config and populate passing do the block function
     @config = OpenStruct.new
     yield(@config) if block_given?
+    
+    self.class.persistent_connection_adapter  pool_size: (@config.connection_pool_size || 2),
+                                              keep_alive: (@config.connection_keep_alive || 30),
+                                              force_retry: (@config.connection_force_retry || true)
 
     # setup webhook
     if @config.webhook.nil?
@@ -78,8 +80,10 @@ class TelegramBotMiddleware
   end
   
   def _call(env)
+    @env = env
+    
     # retrieve the request object
-    req = Rack::Request.new(env)
+    req = Rack::Request.new(@env)
     
     # if the request is a post to bot webhhok
     if req.post? and req.path == "/#{@config.token}"
@@ -88,6 +92,8 @@ class TelegramBotMiddleware
       req.body.rewind
       # build an openstruct based on post params
       params = OpenStruct.from_json(req.body.read)
+      
+      log_debug("Message from chat: #{params}")
 
       path = nil
       unless params.message['text'].nil?
@@ -112,14 +118,14 @@ class TelegramBotMiddleware
       query_string = Rack::Utils.build_nested_query(params.message.to_h_nested)
       
       # transform the POST in GET
-      env['PATH_INFO'] = path
-      env['QUERY_STRING'] = query_string
-      env['REQUEST_METHOD'] = 'GET'
-      env['REQUEST_URI'] = "https://#{req.host}#{path}"
+      @env['PATH_INFO'] = path
+      @env['QUERY_STRING'] = query_string
+      @env['REQUEST_METHOD'] = 'GET'
+      @env['REQUEST_URI'] = "https://#{req.host}#{path}"
       # TODO use update(hash) { |name, old_value, new_value| }
       
       # call the rack stack
-      status, headers, body = @app.call(env)
+      status, headers, body = @app.call(@env)
       
       if status == 200 or status == '200'
         
@@ -193,8 +199,31 @@ class TelegramBotMiddleware
     end  
   end
   
+  def log_error(exception)
+    message = "Error: #{exception.message}\n#{exception.backtrace.join("\n")}\n"
+    log(:error, message)
+  end
+
+  def log_info(message)
+    log(:info, message)
+  end
+
+  def log_debug(message)
+    log(:debug, message)
+  end
+  
+  def log(level, message)
+    return if @env.nil?
+    if @env['rack.logger']
+      @env['rack.logger'].send(level, message)
+    else
+      @env['rack.errors'].write(message)
+    end
+  end
+  
   def send_to_bot(path, query)
+    log_debug("Sending to chat: #{path} - #{query}")
     response = self.class.post("/bot#{@config.token}/#{path}", query: query)
-    # TODO check respobse error
+    # TODO check response error and return response
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telegram_bot_middleware
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Mirko Mignini
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-11-10 00:00:00.000000000 Z
+date: 2015-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake