telegram_workflow 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c96cb2e0a64ca84710249746fba7e205101fa03d3708f154e7b9532133c550f6
-  data.tar.gz: edf5c725fb5100eea709c375657026cc80d3e16075de537422f55604dea150b7
+  metadata.gz: 9f33398c3b33397236392a5b645e39b58827df8e453727fd06496ce0b4479e11
+  data.tar.gz: 9155e202748c8242adc4f4789623b8c42156658616e545d1aafd2aa4f2f776f7
 SHA512:
-  metadata.gz: fb13268c4f33b5add25b82ccc628199aaec2571e57e8731f88b417c5727bb9c9d7639d860a7f6ef9af09110ba12a39db5c4d2ebbd777ea40e2f54c39d0d893ae
-  data.tar.gz: 5cdeb13d1098f17784dfdca787e2f73a0c8d8ee6cd704d42c5894b3de4b714b2cf1118ffbcd2f3391aa0e977b8a1c7806b3b3f606cf51e85e3df6074b6a61204
+  metadata.gz: 4f85e7ab9b297deab054185d03863c8183bf7fbd6a7f1325ec612fa0042ee0999a700e80d91cb5cbed3b945605595904ec1716192b341d39f2402df805ea69f1
+  data.tar.gz: 67bf8b6d8abc59f26c2e302f989aaa17777303bc3efdfb29844686d35f62994a2257557e7838188292e2fbbecc7eb7d1ad872c3f123eb9eb1b61b686b046a5ba

data/.gitignore

@@ -7,6 +7,7 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+*.db
 
 # rspec failure tracking
 .rspec_status

data/README.md

@@ -140,6 +140,19 @@ client.send_location latitude: 40.748, longitude: -73.985, live_period: 120
 
 `chat_id` parameter should be omitted.
 
+Use `TelegramWorkflow::InputFile` to upload a file:
+
+```ruby
+client.send_photo photo: TelegramWorkflow::InputFile.new("/Users/telegram/images/image1.jpg")
+```
+
+`filename` and `content_type` fields can be customized:
+
+```ruby
+file = StringIO.new("hello!")
+client.send_document document: TelegramWorkflow::InputFile.new(file, filename: "hello.txt")
+```
+
 ### session
 
 This is a persistent store to save the data associated with a user, e.g. current user's id, some settings or anything you would store in a session in a regular web application.
@@ -381,6 +394,10 @@ end
 
 As you can see, testing utility starts the flow automatically, calling `initial` step on `described_class`.
 
+## Example
+
+Check out an example of a bot under [example](example) folder.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/example/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gem "telegram_workflow"

data/example/README.md

@@ -0,0 +1,79 @@
+## Description
+
+This is a fully working example of a bot which allows you to book an appointment with a doctor.
+
+The following diagram will help you understand the bot's flow:
+<p>
+  <img src="https://github.com/rsamoilov/telegram_workflow/blob/master/example/flow.jpg" width="400">
+</p>
+
+## Running the bot
+
+First, open [main.rb](main.rb) and configure the bot with your API token:
+
+```diff
+TelegramWorkflow.configure do |config|
+- config.api_token = <YOUR_TOKEN>
++ config.api_token = "123456780:ABCDE_my-token"
+end
+```
+
+Next, run the bot:
+
+```
+bundle
+ruby main.rb
+```
+
+## Configuration
+
+Every Bot workflow begins with **`on_message`** callback in a `start_action`.
+There's no need to store current user data in session in this example, so we simply redirect to the `ListActions` action, which will be our "main" action.
+
+```ruby
+class Actions::Start < TelegramWorkflow::Action
+  def initial
+    on_message do
+      redirect_to Actions::ListActions
+    end
+  end
+end
+```
+
+Next, the Telegram client can be customized. We want to use Telegram's [InlineKeyboard](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating) to provide a user with a list of available actions.
+
+Let's encapsulate this inside our custom client class:
+
+```ruby
+class Client < TelegramWorkflow::Client
+  def send_actions(message, actions)
+    send_message text: message, reply_markup: { inline_keyboard: actions }
+  end
+end
+```
+
+Now, let's configure the gem:
+
+```ruby
+TelegramWorkflow.configure do |config|
+  config.start_action = Actions::Start
+  config.client = Client
+  config.session_store = TelegramWorkflow::Stores::File.new
+end
+```
+
+The last configuration parameter here is `session_store`. We are using `TelegramWorkflow::Stores::File` - a built-in implementation of persistent file store.
+
+[getUpdates](https://core.telegram.org/bots/api#getupdates) method is used in this example to receive the updates:
+
+```ruby
+TelegramWorkflow.updates.each do |params|
+  TelegramWorkflow.process(params)
+end
+```
+
+After a user has sent a message, `TelegramWorkflow.process` will initialize the last processed action and step and then call `on_message` callback on it.
+
+## Actions
+
+Check out the bot's code under [actions](actions) folder.

data/example/actions/create_appointment.rb

@@ -0,0 +1,56 @@
+#
+# this is an action to create an appointment;
+# each method represents one of the steps for appointment creation;
+# for the sake of simplicity, all created appointments are stored in the session
+#
+class Actions::CreateAppointment < TelegramWorkflow::Action
+  def initial
+    on_redirect do
+      client.send_message text: "Enter patient's name:"
+    end
+
+    on_message do
+      flash[:name] = params.message_text
+      redirect_to :reason
+    end
+  end
+
+  def reason
+    on_redirect do
+      client.send_message text: "What is the reason for visit?"
+    end
+
+    on_message do
+      flash[:reason] = params.message_text
+      redirect_to :date
+    end
+  end
+
+  def date
+    on_redirect do
+      client.send_message text: "What date works best for you?"
+    end
+
+    on_message do
+      date = Date.parse(params.message_text) rescue nil
+
+      # there's no redirect in case the date is invalid;
+      # this means that next time a user sends a message, the current action will be executed again
+      if date
+        flash[:date] = date
+        redirect_to :done
+      else
+        client.send_message text: "Invalid date format. Please try again."
+      end
+    end
+  end
+
+  # `specialty` parameter is added to flash in previous `Actions::SelectDoctor` action
+  def done
+    on_redirect do
+      (session[:appointments] ||= []) << flash.slice(:name, :reason, :date, :specialty)
+      client.send_message text: "Your appointment has been created!"
+      redirect_to Actions::ListActions
+    end
+  end
+end

data/example/actions/list_actions.rb

@@ -0,0 +1,28 @@
+class Actions::ListActions < TelegramWorkflow::Action
+  def initial
+    on_redirect do
+      available_actions = [
+        [{ text: "Make an appointment", callback_data: "create" }]
+      ]
+
+      if session[:appointments]&.any?
+        available_actions.unshift [{ text: "List my appointments", callback_data: "list" }]
+      end
+
+      # this is the customized client object
+      client.send_actions "Select an action:", available_actions
+    end
+
+    # `params.callback_data` here will be one of the identifiers defined as `callback_data` in `available_actions` array
+    # refer to https://core.telegram.org/bots/api#inlinekeyboardbutton
+    on_message do
+      next_action = if params.callback_data == "create"
+        Actions::SelectDoctor
+      elsif params.callback_data == "list"
+        Actions::ListAppointments
+      end
+
+      redirect_to next_action
+    end
+  end
+end

data/example/actions/list_appointments.rb

@@ -0,0 +1,13 @@
+class Actions::ListAppointments < TelegramWorkflow::Action
+  def initial
+    on_redirect do
+      appointments = session[:appointments].map do |app|
+        "<b>#{app[:name]}</b> on #{app[:date].to_s}"
+      end
+
+      # refer to https://core.telegram.org/bots/api#sendmessage for the list of available parameters
+      client.send_message text: appointments.join("\n"), parse_mode: "HTML"
+      redirect_to Actions::ListActions
+    end
+  end
+end

data/example/actions/select_doctor.rb

@@ -0,0 +1,19 @@
+class Actions::SelectDoctor < TelegramWorkflow::Action
+  def initial
+    on_redirect do
+      available_doctors = [
+        [{ text: "Family Medicine", callback_data: "family" }],
+        [{ text: "Emergency Medicine", callback_data: "emergency" }],
+        [{ text: "Pediatrics", callback_data: "pediatrics" }]
+      ]
+
+      client.send_actions "Select a doctor:", available_doctors
+    end
+
+    on_message do
+      # pass `specialty` parameter to the next action
+      # https://github.com/rsamoilov/telegram_workflow#redirect_toaction_or_class-flash_params--
+      redirect_to Actions::CreateAppointment, specialty: params.callback_data
+    end
+  end
+end

data/example/actions/start.rb

@@ -0,0 +1,9 @@
+class Actions::Start < TelegramWorkflow::Action
+  def initial
+    # we don't need to store current user id in session or make any other setup,
+    # so just redirect to the `ListActions` action
+    on_message do
+      redirect_to Actions::ListActions
+    end
+  end
+end

data/example/client.rb

@@ -0,0 +1,5 @@
+class Client < TelegramWorkflow::Client
+  def send_actions(message, actions)
+    send_message text: message, reply_markup: { inline_keyboard: actions }
+  end
+end

data/example/environment.rb

@@ -0,0 +1,13 @@
+require "telegram_workflow"
+require "date"
+
+module Actions
+end
+
+dependencies = %w(
+  ./actions/*.rb
+  ./client.rb
+)
+dependencies.each do |path|
+  Dir[path].each { |path| require_relative path }
+end

data/example/main.rb

@@ -0,0 +1,17 @@
+require_relative "environment"
+
+TelegramWorkflow.configure do |config|
+  config.start_action = Actions::Start
+  config.client = Client
+  config.session_store = TelegramWorkflow::Stores::File.new
+  config.api_token = <YOUR_TOKEN>
+end
+
+trap "SIGINT" do
+  puts "Exiting..."
+  TelegramWorkflow.stop_updates
+end
+
+TelegramWorkflow.updates(timeout: 5).each do |params|
+  TelegramWorkflow.process(params)
+end

data/lib/telegram_workflow.rb

@@ -33,6 +33,7 @@ require "telegram_workflow/session"
 require "telegram_workflow/version"
 require "telegram_workflow/updates"
 require "telegram_workflow/workflow"
+require "telegram_workflow/input_file"
 require "telegram_workflow/stores/in_memory"
 require "telegram_workflow/stores/file"
 

data/lib/telegram_workflow/client.rb

@@ -1,5 +1,5 @@
 class TelegramWorkflow::Client
-  API_VERSION = "4.8"
+  API_VERSION = "4.9"
   WebhookFilePath = Pathname.new("tmp/telegram_workflow/webhook_url.txt")
 
   AVAILABLE_ACTIONS = %i(
@@ -129,8 +129,11 @@ class TelegramWorkflow::Client
   end
 
   def make_request(action, params)
+    has_file_params = params.any? { |_, param| param.is_a?(TelegramWorkflow::InputFile) }
+    request_type = has_file_params ? :form : :json
+
     response = ::Retryable.retryable(tries: 3, on: HTTP::ConnectionError) do
-      ::HTTP.post("#{@api_url}/#{action}", json: { chat_id: @chat_id, **params })
+      ::HTTP.post("#{@api_url}/#{action}", request_type => { chat_id: @chat_id, **params })
     end
 
     if response.code != 200

data/lib/telegram_workflow/errors.rb

@@ -11,6 +11,12 @@ module TelegramWorkflow::Errors
     end
   end
 
+  class StartRedirect < StandardError
+    def initialize(msg = "You cannot redirect to a start action.")
+      super
+    end
+  end
+
   class NoSession < StandardError
     def initialize(msg = "Session could not be fetched for this update.")
       super

data/lib/telegram_workflow/input_file.rb

@@ -0,0 +1,2 @@
+class TelegramWorkflow::InputFile < HTTP::FormData::File
+end

data/lib/telegram_workflow/version.rb

@@ -1,3 +1,3 @@
 module TelegramWorkflow
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/telegram_workflow/workflow.rb

@@ -36,6 +36,7 @@ class TelegramWorkflow::Workflow
   def redirect_to(action_or_step, session_params = nil)
     raise TelegramWorkflow::Errors::DoubleRedirect if @redirect_to
     raise TelegramWorkflow::Errors::SharedRedirect if action_or_step == :shared
+    raise TelegramWorkflow::Errors::StartRedirect  if action_or_step == TelegramWorkflow.config.start_action
 
     @redirect_to = action_or_step
     @session_params = session_params

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telegram_workflow
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Roman Samoilov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-21 00:00:00.000000000 Z
+date: 2020-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -82,11 +82,23 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- example/Gemfile
+- example/README.md
+- example/actions/create_appointment.rb
+- example/actions/list_actions.rb
+- example/actions/list_appointments.rb
+- example/actions/select_doctor.rb
+- example/actions/start.rb
+- example/client.rb
+- example/environment.rb
+- example/flow.jpg
+- example/main.rb
 - lib/telegram_workflow.rb
 - lib/telegram_workflow/action.rb
 - lib/telegram_workflow/client.rb
 - lib/telegram_workflow/config.rb
 - lib/telegram_workflow/errors.rb
+- lib/telegram_workflow/input_file.rb
 - lib/telegram_workflow/params.rb
 - lib/telegram_workflow/rspec.rb
 - lib/telegram_workflow/session.rb