stealth 1.0.4 → 1.1.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5b41def6c4e13619ace50cff93ef042e41907d847d5bc391342a07b659c12f
-  data.tar.gz: edff40b0be61bb0ce35db7376b85fcbeb287daadb0a936266c0fb3ba2a442b11
+  metadata.gz: 6c918a4ed7d98e6c5e8c60dab8e3e96d1f5a1d6407bb21843fa6a4eb8a46b0fc
+  data.tar.gz: e4fe19747e02ba2b17af1d932e2505153db47173a45bee8558d7ab2cd8c5309b
 SHA512:
-  metadata.gz: d41a57396b557409239312b03ed2009630a0b8d9396f97a5b5582ef6a9d7a68fc76696bf3ea7629a1af9fab3f3ccb9b2dd0b53db8f32cb9376c7b7769b289a75
-  data.tar.gz: 490adbca626688b0af47b89d857cf7bb14a307b49b1a6b92012d49b2eec5d5fc09f5176a5976b493f772af1c6fdc8c91cd8995d7cc08f8843db853135a09dd1c
+  metadata.gz: 0fbe087d4e4a7d5e60bc442524588ae6c63f1d842b35ebb7f73bf5b2a09716e07a08fc0d3867c7392045c781b8fff6fe6d9aa304c73d0c0229118a2f2dcc1bcf
+  data.tar.gz: 710cc3404711a0d18c765846acada15b94d0f1ebd0fb42196fcc85fc8c6254070bfcfee93fadf8db5bf439aa1acd286cd5c52ff5737017afdec65ddd64fd9c41

data/CHANGELOG.md

@@ -1,10 +1,25 @@
-# Changelog for Stealth v1.0.1
+# Changelog for Stealth v1.1.0
+
+## Breaking Changes
+
+* [Sidekiq] Sidekiq queues have been renamed from `webhooks` and `default` to `stealth_webhooks` and `stealth_replies`. Please ensure your `Procfile` is adjusted accordingly.
+* [Flows] `flow_map.current_state.fails_to` now returns a `Stealth::Session` instead of a `Stealth::Flow::State`. This might affect your `catch_alls`.
 
 ## Enhancements
 
-None.
+* [Controllers] `current_session_id` now references the session ID in controllers
+* [Replies] Added support for dynamic delays
+* [Replies] Added support for service-specific variants
+* [Models] ActiveRecord is now part of the generated bot Gemfile and can be removed from bots
+* [Flows] Added support for `redirects_to` during state declaration. If specified, will automatically step a user to the specified state or session.
+* [Flows] `redirects_to` and `fails_to` now support a session string as an argument (`my_flow->some_state`). This allows you to fail and redirect to other flows. A state name specified as a string or symbol is still allowed.
+* [Errors] Backtraces are now more readable in logs
 
 ## Bug Fixes
 
-* [Docs] Fixed link to docs in the README.
-* [Generators] Fixed the generated name of controllers.
+* [Generators] Fixed flow generation
+* [Generators] Fixed sample Facebook services.yml example
+
+## Deprecations
+
+* [Controllers] `current_user_id` has been soft deprecated in favor of `current_session_id`

data/Gemfile

@@ -2,5 +2,5 @@ source 'https://rubygems.org'
 gemspec
 
 platforms :mri do
-  gem 'oj', '~> 3.3'
+  gem 'oj', '~> 3.7'
 end

data/Gemfile.lock

@@ -1,12 +1,10 @@
 PATH
   remote: .
   specs:
-    stealth (1.0.3)
-      activerecord (~> 5.2)
+    stealth (1.1.0.alpha)
       activesupport (~> 5.2)
       multi_json (~> 1.12)
       puma (~> 3.10)
-      railties (~> 5.2)
       sidekiq (~> 5.0)
       sinatra (~> 2.0)
       thor (~> 0.20)
@@ -14,96 +12,53 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.2.0)
-      actionview (= 5.2.0)
-      activesupport (= 5.2.0)
-      rack (~> 2.0)
-      rack-test (>= 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.2.0)
-      activesupport (= 5.2.0)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activemodel (5.2.0)
-      activesupport (= 5.2.0)
-    activerecord (5.2.0)
-      activemodel (= 5.2.0)
-      activesupport (= 5.2.0)
-      arel (>= 9.0)
-    activesupport (5.2.0)
+    activesupport (5.2.1.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    arel (9.0.0)
-    builder (3.2.3)
-    concurrent-ruby (1.0.5)
+    concurrent-ruby (1.1.3)
     connection_pool (2.2.2)
-    crass (1.0.4)
     diff-lcs (1.3)
-    erubi (1.7.1)
-    i18n (1.0.1)
+    i18n (1.1.1)
       concurrent-ruby (~> 1.0)
-    loofah (2.2.2)
-      crass (~> 1.0.2)
-      nokogiri (>= 1.5.9)
-    method_source (0.9.0)
-    mini_portile2 (2.3.0)
     minitest (5.11.3)
-    mock_redis (0.17.3)
+    mock_redis (0.19.0)
     multi_json (1.13.1)
-    mustermann (1.0.2)
-    nokogiri (1.8.4)
-      mini_portile2 (~> 2.3.0)
-    oj (3.5.0)
-    puma (3.11.4)
-    rack (2.0.4)
-    rack-protection (2.0.3)
+    mustermann (1.0.3)
+    oj (3.7.1)
+    puma (3.12.0)
+    rack (2.0.6)
+    rack-protection (2.0.4)
       rack
-    rack-test (0.8.3)
+    rack-test (1.1.0)
       rack (>= 1.0, < 3)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.0.4)
-      loofah (~> 2.2, >= 2.2.2)
-    railties (5.2.0)
-      actionpack (= 5.2.0)
-      activesupport (= 5.2.0)
-      method_source
-      rake (>= 0.8.7)
-      thor (>= 0.18.1, < 2.0)
-    rake (12.3.1)
-    redis (4.0.1)
-    rspec (3.7.0)
-      rspec-core (~> 3.7.0)
-      rspec-expectations (~> 3.7.0)
-      rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.1)
-      rspec-support (~> 3.7.0)
-    rspec-expectations (3.7.0)
+    redis (4.0.3)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-mocks (3.7.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.7.0)
-    rspec-support (3.7.1)
-    rspec_junit_formatter (0.3.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    sidekiq (5.1.3)
-      concurrent-ruby (~> 1.0)
-      connection_pool (~> 2.2, >= 2.2.0)
+    sidekiq (5.2.3)
+      connection_pool (~> 2.2, >= 2.2.2)
       rack-protection (>= 1.5.0)
       redis (>= 3.3.5, < 5)
-    sinatra (2.0.3)
+    sinatra (2.0.4)
       mustermann (~> 1.0)
       rack (~> 2.0)
-      rack-protection (= 2.0.3)
+      rack-protection (= 2.0.4)
       tilt (~> 2.0)
-    thor (0.20.0)
+    thor (0.20.3)
     thread_safe (0.3.6)
     tilt (2.0.8)
     tzinfo (1.2.5)
@@ -114,11 +69,11 @@ PLATFORMS
 
 DEPENDENCIES
   mock_redis (~> 0.17)
-  oj (~> 3.3)
-  rack-test (~> 0.7)
+  oj (~> 3.7)
+  rack-test (~> 1.1)
   rspec (~> 3.6)
   rspec_junit_formatter (~> 0.3)
   stealth!
 
 BUNDLED WITH
-   1.16.1
+   1.16.3

data/README.md

@@ -23,6 +23,7 @@ Currently, there are gems for:
 ### Messaging
 * [Facebook Messenger](https://github.com/hellostealth/stealth-facebook)
 * [Twilio SMS](https://github.com/hellostealth/stealth-twilio)
+* [Smooch](https://github.com/hellostealth/stealth-smooch)
 
 ### Natural Language Processing
 * [AWS Comprehend](https://github.com/hellostealth/stealth-aws-comprehend)

data/VERSION

@@ -1 +1 @@
-1.0.4
+1.1.0.rc1

data/docs/03-basics.md

@@ -75,6 +75,8 @@ class FlowMap
     state :say_hello
     state :ask_name
     state :get_name, fails_to: :ask_name
+    state :say_wow, redirects_to: :say_hello
+    state :say_bye, redirects_to: 'goodbye->say_goodbye'
   end
 
   flow :goodbye do
@@ -89,9 +91,9 @@ class FlowMap
 end
 ```
 
-Here we have defined three flows: `hello`, `goodbye`, and `catch_all`. For the most part, these are default flows that are generated automatically when you create a new bot but we have made a few changes to highlight some functionality.
+Here we have defined three flows: `hello`, `goodbye`, and `catch_all`. These are the default flows that are generated for you when you create a new bot. We have made a few changes above to highlight some functionality.
 
-In the `hello` flow, the second state asks a user for their name. In the third state of `hello`, you see another option: `fails_to`. This is used to tell Stealth to return the user to the specified state if the `get_name` state raises an error or fails in another way. There are more details in the `CatchAll` section below.
+Each flow consists of an arbitrary number of states. These states should each have a corresponding controller action by the same name. States also support two additional options: `fails_to` and `redirects_to` which we explain below.
 
 ## Default Flows
 
@@ -109,6 +111,20 @@ Error handling is one of the most important parts of building great bots. We rec
 
 See the Catch All (#catchalls) section for more information on how Stealth handles `catch_all` flows.
 
+## fails_to
+
+The `fails_to` option allows you to specify a state that a user should be redirected to in case of an error. The `CatchAllsController` will still be responsible for determining how to handle the error, but by specifying a `fails_to` state here, the `CatchAllsController` is able to redirect accordingly.
+
+A freshly generated bot will contain sample `CatchAll` code for redirecting a user to a `fails_to` state.
+
+The `fails_to` option takes a state name (string or symbol) or a session key. See [Redis Backed Sessions](#sessions.redis_backed_sessions) (or in the FlowMap example above) for more info about session keys. By specifying a session key, you can fail to a completely different flow from the one where the error occurred.
+
+## redirects_to
+
+The `redirects_to` option allows you specify a state that a user should be redirected to. This is useful if you have deprecated a state where existing users may still have open sessions pointing to the state. When a user returns to your bot, they will be redirected to the flow and state specified by this option.
+
+Like `fails_to` above, the `redirects_to` option takes a state name (string or symbol) or a session key. See [Redis Backed Sessions](#sessions.redis_backed_sessions) (or in the FlowMap example above) for more info about session keys. By specifying a session key, you can fail to a completely different flow from the one where the error occurred.
+
 ## Say, Ask, Get
 
 Stealth recommends you use the `say`, `ask`, and `get` prefix for your flow state names. It's not required, but it is a convention we have found helpful to keep state names under control. It also helps other developers on your team follow along more easily.

data/docs/04-sessions.md

@@ -15,3 +15,15 @@ User sessions are stored in Redis. Each session is a lightweight key-value pair.
 So if for example a user with ID `100023838288224423` is currently at the `hello` flow and `ask_name` state, the value for the key would be: `hello->ask_name`.
 
 You likely won't be interacting with sessions directly since Stealth manages it automatically for you. We just present it here for clarity into how sessions work.
+
+## Session Expiration
+
+By default, Stealth will not expire your user sessions. If you want your sessions to expire, you can set the `session_ttl` option:
+
+```ruby
+Stealth.config.session_ttl = 2_592_000 # seconds (30 * 24 * 60 * 60)
+```
+
+The above configuration setting will result in stale keys expiring in 30 days. Sessions that have been accessed reset the TTL (time to live). If you set a value of zero (the default), session expiration will be disabled.
+
+If a user returns to your bot after their session has expired, they will start again in the `Hello` flow or whatever you have defined to be your first flow.

data/docs/05-controllers.md

@@ -110,7 +110,7 @@ class ContactsController < BotController
 end
 ```
 
-This would render the reply contained in `replies/contacts/say_contact_us.yml`.
+This would render the reply contained in `replies/contacts/say_contact_us.yml`. See [Reply Variants](#variants) for additional naming options.
 
 ## `step_to_in`
 
@@ -174,6 +174,6 @@ Returns `true` or `false` depending on whether or not the `current_message` cont
 
 Returns `true` or `false` depending on whether or not the `current_message` contains attachments.
 
-### current_user_id
+### current_session_id (previously current_user_id)
 
-A convenience method for accessing the user's ID.
+A convenience method for accessing the session's ID.

data/docs/07-replies.md

@@ -2,7 +2,7 @@
 title: Replies
 ---
 
-Stealth replies can send one or more replies to a user. Reply types are dependent on the specific messaging service you're using. Each service integration will detail it's supported reply types in it's respective docs.
+Stealth replies can send one or more replies to a user. The supported reply types will depend on the specific messaging service you're using. Each service integration will detail it's supported reply types in it's respective docs.
 
 However, here is a generic reply using text, delays, and suggestions.
 
@@ -22,6 +22,22 @@ However, here is a generic reply using text, delays, and suggestions.
     - text: "No"
 ```
 
+## Reply Variants
+
+By default, Stealth will look for your replies in the folder corresponding to your controller name. So, for example, if you have a `MessagesController`, Stealth will look for replies in `bot/replies/messages`.
+
+If you have an action named `say_hello`, it will look for a reply file named `bot/replies/messages/say_hello.yml.erb` first, and then if that is not found, it will look for `bot/replies/messages/say_hello.yml`. If neither of these files are found, Stealth will raise a `Stealth::Errors::ReplyNotFound`.
+
+In addition to these two naming conventions, Stealth 1.1+ supports Reply Variants. By adding the name of the service to your reply filename, Stealth will reply to users from that service using the designated reply file. That's a mouthful. Let's try an example.
+
+For example, if the bot is replying to a message via an action called `hello`:
+
+Facebook users would receive the reply in `hello.yml+facebook.erb`.
+Twilio SMS users would receive the reply in `hello.yml+twilio.erb`.
+Every other service would receive the reply in `hello.yml.erb`.
+
+This allows you to take advantage of things like Facebook Messenger Cards while still maintaining compatibility for users using SMS.
+
 ## Format
 
 Stealth reply templates are written in YAML. Stealth doesn't use advanced YAML features, but we do recommend you familiarize yourself with the syntax. In the above reply example, you should be able to see there are 5 replies included in the reply file.
@@ -58,6 +74,31 @@ Delays are a common pattern of chatbot design. After a block of text, it's recom
 
 Stealth will pause for the duration specified. For service integrations that support it (like Facebook), Stealth will send a typing indicator while it is paused.
 
+### Dynamic Delays
+
+Rather than specifying an explicit delay duration, you can optionally choose to specify a dynamic duration:
+
+```yaml
+- reply_type: delay
+  duration: dynamic
+```
+
+The dynamic delay uses a heuristic to dynamically determine the length of the delay. The previous message sent to the user is examined and depending on it's type and text length (in the case of text replies), an optimal duration is computed.
+
+If you find that the dynamic delays are too fast for your taste, you can slow them down by setting the multiplier value to something between 0 and 1:
+
+```ruby
+Stealth.config.dynamic_delay_muliplier = 0.5
+```
+
+If you find them to be too slow, you can speed them up by setting the multipler to a value greater than 1:
+
+```ruby
+Stealth.config.dynamic_delay_muliplier = 2.5
+```
+
+You can set this option by setting the above value in an intializer file, i.e., `config/dynamic_delay_config.rb`.
+
 ## Naming Conventions
 
 Replies are named after a flow's state (which is also the controller's action). So for a given controller:

data/lib/stealth/base.rb

@@ -37,6 +37,11 @@ module Stealth
     @configuration
   end
 
+  def self.set_config_defaults(config)
+    config.dynamic_delay_muliplier = 1.0
+    config.session_ttl = 0
+  end
+
   # Loads the services.yml configuration unless one has already been loaded
   def self.load_services_config(services_yaml)
     @semaphore ||= Mutex.new
@@ -49,7 +54,10 @@ module Stealth
           raise Stealth::Errors::ConfigurationError, "Could not find services.yml configuration for #{env} environment"
         end
 
-        Stealth::Configuration.new(services_config[env])
+        config = Stealth::Configuration.new(services_config[env])
+        set_config_defaults(config)
+
+        config
       end
     end
   end
@@ -72,10 +80,12 @@ module Stealth
     require File.join(Stealth.root, 'config', 'flow_map')
     require_directory("bot")
 
-    if ENV['DATABASE_URL'].present? && defined?(ActiveRecord)
-      ActiveRecord::Base.establish_connection(ENV['DATABASE_URL'])
-    else
-      ActiveRecord::Base.establish_connection(YAML::load_file("config/database.yml")[Stealth.env])
+    if defined?(ActiveRecord)
+      if ENV['DATABASE_URL'].present?
+        ActiveRecord::Base.establish_connection(ENV['DATABASE_URL'])
+      else
+        ActiveRecord::Base.establish_connection(YAML::load_file("config/database.yml")[Stealth.env])
+      end
     end
   end
 
@@ -107,10 +117,14 @@ require 'stealth/controller/callbacks'
 require 'stealth/controller/replies'
 require 'stealth/controller/catch_all'
 require 'stealth/controller/helpers'
+require 'stealth/controller/dynamic_delay'
 require 'stealth/controller/controller'
 require 'stealth/flow/base'
 require 'stealth/services/base_client'
-require 'stealth/migrations/configurator'
-require 'stealth/migrations/generators'
-require 'stealth/migrations/railtie_config'
-require 'stealth/migrations/tasks'
+
+if defined?(ActiveRecord)
+  require 'stealth/migrations/configurator'
+  require 'stealth/migrations/generators'
+  require 'stealth/migrations/railtie_config'
+  require 'stealth/migrations/tasks'
+end

data/lib/stealth/controller/catch_all.rb

@@ -48,7 +48,7 @@ module Stealth
           end
 
           def error_slug
-            ['error', current_user_id, current_session.flow_string, current_session.state_string].join('-')
+            ['error', current_session_id, current_session.flow_string, current_session.state_string].join('-')
           end
 
           def calculate_catch_all_state(error_level)

data/lib/stealth/controller/controller.rb

@@ -5,17 +5,19 @@ module Stealth
   class Controller
 
     include Stealth::Controller::Callbacks
+    include Stealth::Controller::DynamicDelay
     include Stealth::Controller::Replies
     include Stealth::Controller::CatchAll
     include Stealth::Controller::Helpers
 
     attr_reader :current_message, :current_user_id, :current_flow,
-                :current_service, :flow_controller, :action_name
+                :current_service, :flow_controller, :action_name,
+                :current_session_id
 
     def initialize(service_message:, current_flow: nil)
       @current_message = service_message
       @current_service = service_message.service
-      @current_user_id = service_message.sender_id
+      @current_user_id = @current_session_id = service_message.sender_id
       @current_flow = current_flow
       @progressed = false
     end
@@ -47,17 +49,27 @@ module Stealth
     end
 
     def current_session
-      @current_session ||= Stealth::Session.new(user_id: current_user_id)
+      @current_session ||= Stealth::Session.new(user_id: current_session_id)
     end
 
     def previous_session
-      @previous_session ||= Stealth::Session.new(user_id: current_user_id, previous: true)
+      @previous_session ||= Stealth::Session.new(user_id: current_session_id, previous: true)
     end
 
     def action(action: nil)
       @action_name = action
       @action_name ||= current_session.state_string
 
+      # Check if the user needs to be redirected
+      if current_session.flow.current_state.redirects_to.present?
+        Stealth::Logger.l(
+          topic: "redirect",
+          message: "From #{current_session.session} to #{current_session.flow.current_state.redirects_to.session}"
+        )
+        step_to(session: current_session.flow.current_state.redirects_to)
+        return
+      end
+
       run_callbacks :action do
         begin
           flow_controller.send(@action_name)
@@ -76,8 +88,8 @@ module Stealth
         raise ArgumentError, "Please specify your step_to_in `delay` parameter using ActiveSupport::Duration, e.g. `1.day` or `5.hours`"
       end
 
-      Stealth::ScheduledReplyJob.perform_in(delay, current_service, current_user_id, flow, state)
-      Stealth::Logger.l(topic: "session", message: "User #{current_user_id}: scheduled session step to #{flow}->#{state} in #{delay} seconds")
+      Stealth::ScheduledReplyJob.perform_in(delay, current_service, current_session_id, flow, state)
+      Stealth::Logger.l(topic: "session", message: "User #{current_session_id}: scheduled session step to #{flow}->#{state} in #{delay} seconds")
     end
 
     def step_to_at(timestamp, session: nil, flow: nil, state: nil)
@@ -87,8 +99,8 @@ module Stealth
         raise ArgumentError, "Please specify your step_to_at `timestamp` parameter as a DateTime"
       end
 
-      Stealth::ScheduledReplyJob.perform_at(timestamp, current_service, current_user_id, flow, state)
-      Stealth::Logger.l(topic: "session", message: "User #{current_user_id}: scheduled session step to #{flow}->#{state} at #{timestamp.iso8601}")
+      Stealth::ScheduledReplyJob.perform_at(timestamp, current_service, current_session_id, flow, state)
+      Stealth::Logger.l(topic: "session", message: "User #{current_session_id}: scheduled session step to #{flow}->#{state} at #{timestamp.iso8601}")
     end
 
     def step_to(session: nil, flow: nil, state: nil)
@@ -104,7 +116,7 @@ module Stealth
     private
 
       def update_session(flow:, state:)
-        @current_session = Stealth::Session.new(user_id: current_user_id)
+        @current_session = Stealth::Session.new(user_id: current_session_id)
         @progressed = :updated_session
         @current_session.set(flow: flow, state: state)
       end

data/lib/stealth/controller/dynamic_delay.rb

@@ -0,0 +1,64 @@
+# coding: utf-8
+# frozen_string_literal: true
+
+module Stealth
+  class Controller
+
+    module DynamicDelay
+      extend ActiveSupport::Concern
+
+      SHORT_DELAY = 3.0
+      STANDARD_DELAY = 4.3
+      LONG_DELAY = 7.0
+
+      included do
+        def dynamic_delay(service_replies:, position:)
+          if position <= 0
+            calculate_delay(previous_reply: {})
+          else
+            calculate_delay(previous_reply: service_replies[position - 1])
+          end
+        end
+
+        private
+
+        def calculate_delay(previous_reply:)
+          case previous_reply['reply_type']
+          when 'text'
+            calculate_delay_from_text(previous_reply['text'])
+          when 'image'
+            STANDARD_DELAY
+          when 'audio'
+            STANDARD_DELAY
+          when 'video'
+            STANDARD_DELAY
+          when 'file'
+            STANDARD_DELAY
+          when 'cards'
+            STANDARD_DELAY
+          when 'list'
+            STANDARD_DELAY
+          when nil
+            SHORT_DELAY
+          else
+            SHORT_DELAY
+          end
+        end
+      end
+
+      def calculate_delay_from_text(text)
+        case text.size
+        when 0..55
+          SHORT_DELAY
+        when 56..140
+          STANDARD_DELAY
+        when 141..256
+          STANDARD_DELAY * 1.5
+        else
+          LONG_DELAY
+        end
+      end
+    end
+
+  end
+end