telegram-bot 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 968133c5cb3e68b5898700cb9ec18b6d56691658
-  data.tar.gz: 1df3660c88d5faf9da1548a3496f518616cdd83c
+  metadata.gz: a045d870c213b5136f08e93b6f6e243b9276c6bb
+  data.tar.gz: f83f3bfd325fbb5014939ea0c4db049c2d8a228a
 SHA512:
-  metadata.gz: 7c1d1409286e9a0d455d13b46920acd0de1f8f2de4d94313480aca5e9185759265b901802853e3ec520ddb5e056002ef6692321661b77bb24e6d28e5ac718543
-  data.tar.gz: b1f815b8f1e7a0c7aa994f66b398615ac9dc6acbd9355b85c2467bca2a9ba2fb873db41db1ab430808e68a9988828ed33015ce7260417a03e169d94b17125d76
+  metadata.gz: ed51cc7ddcb72060182cc6f22ef8e0ab11c7ac07223a03c6c24b301db7a46bab88800b1a00044558d40d17a87fde09bdfa0b7c310039c97a31b7bb172d9f0e56
+  data.tar.gz: 5617505f1d36c7967777bb27c0b1fd1025f7f0617629c884a67ca8092702642760526295ea21683b7d924b2d9f2e5f8350b847600a3506f289b225511fc73d5f

data/.rubocop.yml

@@ -8,9 +8,11 @@ Style/AlignParameters:
   # EnforcedStyle:
   # - with_first_parameter
   # - with_fixed_indentation
+Style/AndOr: {EnforcedStyle: conditionals}
 Style/ClosingParenthesisIndentation: {Enabled: false}
 Style/Documentation: {Enabled: false}
 Style/DotPosition: {EnforcedStyle: trailing}
+Style/FirstParameterIndentation: {EnforcedStyle: consistent}
 Style/IfUnlessModifier: {Enabled: false}
 Style/ModuleFunction: {Enabled: false}
 Style/MultilineOperationIndentation: {EnforcedStyle: indented}

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 0.5.0
+
+- MessageContext.
+- Running controller action without update.
+- Client.wrap supports symbols.
+- Improved testing utils: ability to process multiple updates on same controller instance,
+  stubbing all clients in application.

data/README.md

@@ -142,7 +142,7 @@ You can enable typecasting of `update` with `telegram-bot-types` by including
 
 ```ruby
 class Telegram::WebhookController < Telegram::Bot::UpdatesController
-  include Telegram::Bot::UpdatesPoller::TypedUpdate
+  include Telegram::Bot::UpdatesController::TypedUpdate
 
   def message(message)
     message.class # => Telegram::Bot::Types::Message
@@ -158,6 +158,9 @@ config.telegram_updates_controller.session_store = :redis_store, {expires_in: 1.
 
 class Telegram::WebhookController < Telegram::Bot::UpdatesController
   include Telegram::Bot::UpdatesController::Session
+  # or just shortcut:
+  use_session!
+
   # You can override global config
   self.session_store = :file_store
 
@@ -166,7 +169,7 @@ class Telegram::WebhookController < Telegram::Bot::UpdatesController
   end
 
   def read
-    session[:text]
+    reply_with :message, text: session[:text]
   end
 
   private
@@ -180,6 +183,59 @@ class Telegram::WebhookController < Telegram::Bot::UpdatesController
 end
 ```
 
+It's usual to support chain of messages like BotFather: after receiving command
+it asks you for additional argument. There is `MessageContext` for this:
+
+```ruby
+class Telegram::WebhookController < Telegram::Bot::UpdatesController
+  include Telegram::Bot::UpdatesController::MessageContext
+
+  def rename(*)
+    # set context for the next message
+    save_context :rename
+    reply_with :message, text: 'What name do you like?'
+  end
+
+  # register context handlers to handle this context
+  context_handler :rename do |message|
+    update_name message[:text]
+    reply_with :message, text: 'Renamed!'
+  end
+
+  # You can do it in other way:
+  def rename(name = nil, *)
+    if name
+      update_name name
+      reply_with :message, text: 'Renamed!'
+    else
+      save_context :rename
+      reply_with :message, text: 'What name do you like?'
+    end
+  end
+
+  # This will call #rename like if it is called with message '/rename %text%'
+  context_handler :rename
+
+  # If you have a lot of such methods you can use
+  context_to_action!
+  # It'll use context value as action name for all contexts which miss handlers.
+end
+```
+
+To process update run:
+
+```ruby
+ControllerClass.dispatch(bot, update)
+```
+
+There is also ability to run action without update:
+
+```ruby
+# Most likely you'll want to pass :from and :chat
+controller = ControllerClass.new(bot, from: telegram_user, chat: telegram_chat)
+controller.process(:help, *args)
+```
+
 ### Routes
 
 Use `telegram_webhooks` helper to add routes. It will create routes for bots
@@ -215,13 +271,36 @@ call `.dispatch(bot, update)` on controller.
 
 ### Development & Debugging
 
-Use `rake telegram:bot:poller BOT=chat` to run poller. It'll automatically load
-changes without restart in development env. This task will not if you don't use
-`telegram_webhooks`.
+Use `rake telegram:bot:poller` to run poller. It'll automatically load
+changes without restart in development env. Optionally specify bot to run poller for
+with `BOT` envvar (`BOT=chat`).
 
+This task will not work if you don't use `telegram_webhooks`.
 You can run poller manually with
 `Telegram::Bot::UpdatesPoller.start(bot, controller_class)`.
 
+### Testing
+
+There is `Telegram::Bot::ClientStub` class to stub client for tests.
+Instead of performing API requests it stores them in `requests` hash.
+
+To stub all possible clients use `Telegram::Bot::ClientStub.stub_all!` before
+initializing clients. Most likely you'll want something like this:
+
+```ruby
+RSpec.configure do |config|
+  # ...
+  Telegram.reset_bots
+  Telegram::Bot::ClientStub.stub_all!
+  config.after { Telegram.bot.reset }
+  # ...
+end
+```
+
+There are also some helpers for controller tests.
+Check out `telegram/bot/updates_controller/rspec_helpers` and
+`telegram/bot/updates_controller/testing`.
+
 ### Deploying
 
 Use `rake telegram:bot:set_webhook` to update webhook url for all configured bots.

data/lib/telegram/bot/client.rb

@@ -19,6 +19,9 @@ module Telegram
           when Hash then
             input = input.stringify_keys
             new input['token'], input['username']
+          when Symbol
+            Telegram.bots[input] or
+              raise "Bot #{input} not configured, check Telegram.bots_config."
           else
             new(input)
           end
@@ -104,7 +107,7 @@ module Telegram
       end
 
       def inspect
-        "#<Telegram::Bot::Client##{object_id}(#{@username})>"
+        "#<#{self.class.name}##{object_id}(#{@username})>"
       end
     end
   end

data/lib/telegram/bot/client_stub.rb

@@ -4,6 +4,35 @@ module Telegram
     class ClientStub < Client
       attr_reader :requests
 
+      module StubbedConstructor
+        def new(*args)
+          if self == ClientStub || !ClientStub.stub_all?
+            super
+          else
+            ClientStub.new(args[1])
+          end
+        end
+      end
+
+      class << self
+        # Makes all
+        def stub_all!(enabled = true)
+          Client.extend(StubbedConstructor) unless Client < StubbedConstructor
+          return @_stub_all = enabled unless block_given?
+          begin
+            old = @_stub_all
+            stub_all!(enabled)
+            yield
+          ensure
+            stub_all!(old)
+          end
+        end
+
+        def stub_all?
+          @_stub_all
+        end
+      end
+
       def initialize(username = nil)
         @username = username
         reset

data/lib/telegram/bot/config_methods.rb

@@ -41,6 +41,13 @@ module Telegram
           config[:default] = default if default
         end
       end
+
+      # Resets all cached bots and their configs.
+      def reset_bots
+        @bots = nil
+        @bot = nil
+        @bots_config = nil
+      end
     end
   end
 end

data/lib/telegram/bot/routes_helper.rb

@@ -42,7 +42,9 @@ module Telegram
       #   # You can override this options or specify others:
       #   telegram_webhooks TelegramController, as: :my_webhook
       #   telegram_webhooks bot => [TelegramChatController, as: :chat_webhook],
-      #                     other_bot => [TelegramAuctionController,
+      #                     other_bot => TelegramAuctionController,
+      #                     admin_chat: TelegramAdminChatController
+      #
       def telegram_webhooks(controllers, bots = nil, **options)
         unless controllers.is_a?(Hash)
           bots = bots ? Array.wrap(bots) : Telegram.bots.values

data/lib/telegram/bot/updates_controller.rb

@@ -4,12 +4,59 @@ require 'active_support/version'
 
 module Telegram
   module Bot
+    # Base class to create update processors. With callbacks, session and helpers.
+    #
+    # Define public methods for each command and they will be called when
+    # update has this command. Message is automatically parsed and
+    # words are passed as method arguments. Be sure to use default values and
+    # splat arguments in every action method to not get errors, when user
+    # sends command without necessary args / with extra args.
+    #
+    #     def start(token = nil, *)
+    #       if token
+    #         # ...
+    #       else
+    #         # ...
+    #       end
+    #     end
+    #
+    #     def help(*)
+    #       reply_with :message, text:
+    #     end
+    #
+    # To process plain text messages (without commands) or other updates just
+    # define public method with name of payload type. They will receive payload
+    # as an argument.
+    #
+    #     def message(message)
+    #       reply_with :message, text: "Echo: #{message['text']}"
+    #     end
+    #
+    #     def inline_query(query)
+    #       answer_inline_query results_for_query(query), is_personal: true
+    #     end
+    #
+    #     # To process conflicting commands (`/message args`) just use `on_` prefix:
+    #     def on_message(*args)
+    #       # ...
+    #     end
+    #
+    # To process update run:
+    #
+    #     ControllerClass.dispatch(bot, update)
+    #
+    # There is also ability to run action without update:
+    #
+    #     ControllerClass.new(bot, from: telegram_user, chat: telegram_chat).
+    #       process(:help, *args)
+    #
     class UpdatesController < AbstractController::Base
       abstract!
 
       require 'telegram/bot/updates_controller/session'
       require 'telegram/bot/updates_controller/log_subscriber'
       require 'telegram/bot/updates_controller/instrumentation'
+      autoload :MessageContext, 'telegram/bot/updates_controller/message_context'
 
       include AbstractController::Callbacks
       # Redefine callbacks with default terminator.
@@ -37,6 +84,7 @@ module Telegram
       CONFLICT_CMD_REGEX = Regexp.new("^(#{PAYLOAD_TYPES.join('|')}|\\d)")
 
       class << self
+        # Initialize controller and process update.
         def dispatch(*args)
           new(*args).dispatch
         end
@@ -59,7 +107,7 @@ module Telegram
           match = text.match CMD_REGEX
           return unless match
           return if match[3] && username != true && match[3] != username
-          [match[1], text.split(' ').drop(1)]
+          [match[1], text.split.drop(1)]
         end
       end
 
@@ -67,18 +115,39 @@ module Telegram
       alias_method :command?, :is_command
       delegate :username, to: :bot, prefix: true, allow_nil: true
 
+      # Second argument can be either update object with hash access & string
+      # keys or Hash with `:from` or `:chat` to override this values and assume
+      # that update is nil.
       def initialize(bot = nil, update = nil)
+        if update.is_a?(Hash) && (update.key?(:from) || update.key?(:chat))
+          options = update
+          update = nil
+        end
         @_update = update
         @_bot = bot
+        @_chat, @_from = options && options.values_at(:chat, :from)
 
+        payload_data = nil
         update && PAYLOAD_TYPES.find do |type|
           item = update[type]
-          next unless item
-          @_payload = item
-          @_payload_type = type
+          payload_data = [item, type] if item
         end
+        @_payload, @_payload_type = payload_data
+      end
+
+      # Accessor to `'chat'` field of payload. Can be overriden with `chat` option
+      # for #initialize.
+      def chat
+        @_chat || payload && payload['chat']
       end
 
+      # Accessor to `'from'` field of payload. Can be overriden with `from` option
+      # for #initialize.
+      def from
+        @_from || payload && payload['from']
+      end
+
+      # Processes current update.
       def dispatch
         @_is_command, action, args = action_for_payload
         process(action, *args)
@@ -102,19 +171,32 @@ module Telegram
       def action_missing(*)
       end
 
-      %w(chat from).each do |field|
-        define_method(field) { payload[field] }
-      end
-
+      # Helper to call bot's `send_#{type}` method with already set `chat_id` and
+      # `reply_to_message_id`:
+      #
+      #     reply_with :message, text: 'Hello!'
+      #     reply_with :message, text: '__Hello!__', parse_mode: :Markdown
+      #     reply_with :photo, photo: File.open(photo_to_send), caption: "It's incredible!"
       def reply_with(type, params)
         method = "send_#{type}"
+        chat = self.chat
+        payload = self.payload
         params = params.merge(
-          chat_id: chat['id'],
-          reply_to_message: payload['message_id'],
+          chat_id: (chat && chat['id'] or raise 'Can not reply_with when chat is not present'),
+          reply_to_message: payload && payload['message_id'],
         )
         bot.public_send(method, params)
       end
 
+      # Same as reply_with, but for inline queries.
+      def answer_inline_query(results, params = {})
+        params = params.merge(
+          inline_query_id: payload['id'],
+          results: results,
+        )
+        bot.answer_inline_query(params)
+      end
+
       ActiveSupport.run_load_hooks('telegram.bot.updates_controller', self)
     end
   end

data/lib/telegram/bot/updates_controller/message_context.rb

@@ -0,0 +1,102 @@
+module Telegram
+  module Bot
+    class UpdatesController
+      # Allows to store context in session and treat next message according to this context.
+      module MessageContext
+        extend ActiveSupport::Concern
+
+        include Session
+
+        included do
+          # As we use before_action context is cleared anyway,
+          # no matter we used it or not.
+          before_action :fetch_context
+          singleton_class.send :attr_reader, :context_handlers, :context_to_action
+          @context_handlers = {}
+        end
+
+        module ClassMethods
+          # Registers handler for context.
+          #
+          #     context_handler :rename do |message|
+          #       resource.update!(name: message['text'])
+          #     end
+          #
+          #     # To run other action with all the callbacks:
+          #     context_handler :rename do |message|
+          #       process(:rename, *m['text'].split)
+          #     end
+          #
+          #     # Or just
+          #     context_handler :rename, :your_action_to_call
+          #     context_handler :rename # to call :rename
+          #
+          #     # For messages without context use this instead of `message` method:
+          #     context_handle do |message|
+          #     end
+          #
+          def context_handler(context = nil, action = nil, &block)
+            context &&= context.to_sym
+            context_handlers[context] = block || action || context
+          end
+
+          # Use it to use context value as action name for all contexts
+          # which miss handlers.
+          # For security reasons it supports only action methods and will
+          # raise AbstractController::ActionNotFound if context is invalid.
+          def context_to_action!
+            @context_to_action = true
+          end
+        end
+
+        # Finds handler for current context and processes message with it.
+        def message(message)
+          handler = handler_for_context
+          return unless handler
+          if handler.respond_to?(:call)
+            instance_exec(message, &handler)
+          else
+            process(handler, *message['text'].split)
+          end
+        end
+
+        # Action to clear context.
+        def cancel
+          # Context is already cleared in before_action
+        end
+
+        private
+
+        # Context is read from the session to treat messages
+        # according to previous request.
+        attr_reader :context
+
+        # Fetches and removes context from session.
+        def fetch_context
+          val = session.delete(:context)
+          @context = val && val.to_sym
+          true # TODO: remove in Rails 5.0
+        end
+
+        # Save context for the next request.
+        def save_context(context)
+          session[:context] = context
+        end
+
+        def handler_for_context
+          self.class.context_handlers[context] || self.class.context_to_action && begin
+            action_name = context.to_s
+            unless action_method?(action_name)
+              raise AbstractController::ActionNotFound,
+                "The action '#{action_name}' could not be set from context " \
+                "for #{self.class.name}. " \
+                'context_to_action! supports only action methods for security reasons. ' \
+                'If you need to call this action use context_handler for it.'
+            end
+            action_name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/telegram/bot/updates_controller/rspec_helpers.rb

@@ -1,23 +1,29 @@
+require 'telegram/bot/updates_controller/testing'
+
 RSpec.shared_context 'telegram/bot/updates_controller' do
   let(:controller_class) { described_class }
-  let(:instance) { controller_class.new(bot, update) }
-  let(:update) { {payload_type => payload} }
-  let(:payload_type) { 'some_type' }
+  let(:controller) do
+    controller_class.new(bot, update).tap do |x|
+      x.extend Telegram::Bot::UpdatesController::Testing
+    end
+  end
+  let(:update) { build_update(payload_type, payload) }
+  let(:payload_type) { :some_type }
   let(:payload) { double(:payload) }
   let(:bot) { Telegram::Bot::ClientStub.new(bot_name) }
   let(:bot_name) { 'bot' }
-  let(:session) do
-    session = Telegram::Bot::UpdatesController::Session::TestSessionHash.new
-    allow_any_instance_of(controller_class).to receive(:session) { session }
-    session
+  let(:session) { controller.send(:session) }
+
+  def dispatch(bot = self.bot, update = self.update)
+    controller.dispatch_again(bot, update)
   end
 
   def dispatch_message(text, options = {})
-    payload = build_payload :message, options.merge(text: text)
-    controller_class.dispatch bot, payload
+    update = build_update :message, options.merge(text: text)
+    dispatch bot, update
   end
 
-  def build_payload(type, content)
+  def build_update(type, content)
     deep_stringify type => content
   end
 

data/lib/telegram/bot/updates_controller/session.rb

@@ -59,24 +59,16 @@ module Telegram
           end
         end
 
-        class TestSessionHash < SessionHash
-          def initialize
-            @data = {}
-            @loaded = true
-            @exists = true
-          end
-
-          alias_method :destroy, :clear
-          alias_method :load!, :id
-          alias_method :commit, :id
-        end
-
         module ConfigMethods
           delegate :session_store, to: :config
 
           def session_store=(store)
             config.session_store = ActiveSupport::Cache.lookup_store(store)
           end
+
+          def use_session!
+            include Session
+          end
         end
       end
     end

data/lib/telegram/bot/updates_controller/testing.rb

@@ -0,0 +1,47 @@
+module Telegram
+  module Bot
+    class UpdatesController
+      module Testing
+        IVARS_TO_KEEP = %i(@_session).freeze
+
+        # Perform multiple dispatches on same instance.
+        def dispatch_again(bot = nil, update = nil)
+          recycle!
+          initialize(bot, update)
+          dispatch
+        end
+
+        # Cleans controller between dispatches.
+        # Seems like there is nothing to clean between requests for now:
+        # everything will be rewriten with #initialize.
+        #
+        # With `full` set to `true` it'll clear all cached instance variables.
+        def recycle!(full = false)
+          return unless full
+          (instance_variables - IVARS_TO_KEEP).each do |ivar|
+            remove_instance_variable(ivar)
+          end
+        end
+
+        protected
+
+        # Stubs session.
+        def session
+          @_session ||= Testing::SessionHash.new
+        end
+
+        class SessionHash < Session::SessionHash
+          def initialize
+            @data = {}
+            @loaded = true
+            @exists = true
+          end
+
+          alias_method :destroy, :clear
+          alias_method :load!, :id
+          alias_method :commit, :id
+        end
+      end
+    end
+  end
+end

data/lib/telegram/bot/updates_controller/typed_update.rb

@@ -4,7 +4,7 @@ module Telegram
       # Include this module to type cast update to Virtus model
       # using `telegram-bot-types` gem (install this gem first).
       module TypedUpdate
-        def initialize(bot, update)
+        def initialize(bot = nil, update = nil)
           update = Types::Update.new(update) if update && !update.is_a?(Types::Update)
           super
         end

data/lib/telegram/bot/version.rb

@@ -1,6 +1,6 @@
 module Telegram
   module Bot
-    VERSION = '0.4.2'.freeze
+    VERSION = '0.5.0'.freeze
 
     def self.gem_version
       Gem::Version.new VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telegram-bot
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Max Melentiev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-29 00:00:00.000000000 Z
+date: 2016-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -91,6 +91,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -111,8 +112,10 @@ files:
 - lib/telegram/bot/updates_controller.rb
 - lib/telegram/bot/updates_controller/instrumentation.rb
 - lib/telegram/bot/updates_controller/log_subscriber.rb
+- lib/telegram/bot/updates_controller/message_context.rb
 - lib/telegram/bot/updates_controller/rspec_helpers.rb
 - lib/telegram/bot/updates_controller/session.rb
+- lib/telegram/bot/updates_controller/testing.rb
 - lib/telegram/bot/updates_controller/typed_update.rb
 - lib/telegram/bot/updates_poller.rb
 - lib/telegram/bot/version.rb