stealth 2.0.0.beta5 → 2.0.0.beta6

data/docs/controllers/catch-alls.md

@@ -0,0 +1,135 @@
+# Catch-Alls
+
+Stealth Catch-Alls are designed to handle the error cases within bots. Either the bot doesn't understand what a user typed or an error occurred. If this were a webpage, we'd see the dreaded HTTP 500 error page. 
+
+Catch-Alls are designed to move beyond simple "I don't understand" messages and help users get back on track. The better your CatchAlls, the better your bot.
+
+### Triggering
+
+The `catch_all` flow is automatically triggered when either of two things happens within a controller action:
+
+1. The action [fails to progress a user](controller-overview.md#failing-to-progress-a-user).
+2. An Exception is raised.
+
+{% hint style="info" %}
+If an action within `CatchAllsController` raises an exception, it won't fire another Catch-All to prevent loops.
+{% endhint %}
+
+### Multi-Level
+
+Stealth keeps track of how many times a Catch-All is triggered for a given session. This allows you to build experiences in which the user is provided different responses for subsequent failures.
+
+So for example, if in the `hello` flow and `say_hello` state an exception is raised, then Catch-All _Level 1_ will be called. If the user is return to that same flow and state and another exception is raised, Catch-All _Level 2_ will be called. This continues until you either run out of Catch-All states or if the Catch-All counter resets.
+
+{% hint style="info" %}
+The Catch-All counter currently resets after 15 minutes. This is per flow and state. So a user may encounter a Catch-All elsewhere in your bot and it will utilize a separate Catch-All counter.
+{% endhint %}
+
+### Retrying
+
+By default, a Stealth bot comes with Catch-All Level 1 already defined. Here is the default `CatchAllsController` and associated reply:
+
+```ruby
+class CatchAllsController < BotController
+
+  def level1
+    send_replies
+
+    if fail_session.present?
+      step_to session: fail_session
+    else
+      step_to session: previous_session - 2.states
+    end
+  end
+
+private
+
+   def fail_session
+     previous_session.flow.current_state.fails_to
+   end
+
+end
+```
+
+```yaml
+- reply_type: text
+  text: Oops. It looks like something went wrong. Let's try that again
+```
+
+In the controller action, we check if the `previous_session` (the one that failed) specified a `fails_to` state. If so, we send the user there. Otherwise, we send the user back 2 states.
+
+Sending a user back two states is a pretty good generic action. Going back 1 state takes us back to the action that failed. Since the actions most likely to fail are `get` actions, or actions that deal with user responses, going back 2 states usually takes us back to the original "question".
+
+{% hint style="info" %}
+Where possible, it's better to specify a `fails_to` state so Stealth doesn't incorrectly guess where to send your user back.
+{% endhint %}
+
+### Adding More Levels
+
+If you would like to extend the experience, add a `level2` controller action and associated reply (and update the `FlowMap`). You can go as far as you want. CatchAlls have no limit, just make sure you increment using the standardized method names of `level1`, `level2`, `level3`, `level4`, etc.
+
+If a user has encountered the maximum number of CatchAll levels that have been defined, it won't attempt to call any more levels.
+
+{% hint style="warning" %}
+For the last Catch-All state, you'll probably want to prompt the user to contact support or send them to a special menu to choose from.
+{% endhint %}
+
+### Catch-All Reasons
+
+As mentioned in the [Triggering](catch-alls.md#triggering) section above, there are two reasons a Catch-All triggers. Stealth will provide the `CatchAllsController` with that reason so you can customize your messages and take the appropriate action.
+
+So if for example your bot just didn't recognize the message sent by the user, you may ask the user to repeat. If however, your database is down, you might other action.
+
+Here is an example usage:
+
+```ruby
+class CatchAllsController < BotController
+  
+  before_action :set_catch_all_reason
+
+  def level1
+    send_catch_all_replies('level1')
+
+    if fail_session.present?
+      step_to session: fail_session, pos: -1
+    else
+      step_to session: previous_session - 2.states, pos: -1
+    end
+  end
+
+  def level2
+    send_catch_all_replies('level2')
+  end
+
+  def level3
+    send_catch_all_replies('level3')
+  end
+
+  private
+
+  def fail_session
+    previous_session.flow.current_state.fails_to
+  end
+
+  def send_catch_all_replies(level)
+    if @reason == :unrecognized_message
+      send_replies(custom_reply: "catch_alls/#{level}_unrecognized")
+    else
+      send_replies(custom_reply: "catch_alls/#{level}")
+    end
+  end
+
+  def set_catch_all_reason
+    @reason = case current_message.catch_all_reason[:err].to_s
+    when 'Stealth::Errors::UnrecognizedMessage'
+      :unrecognized_message
+    else
+      :system_error
+    end
+  end
+
+end
+
+```
+
+In `CatchAllsController` we have two sets of Catch-All replies. One for when the message was unrecognized and another for when we've encountered a system error. We dynamically send the appropriate reply based on the `@reason` instance variable that we set with the `before_action` in the controller.

data/docs/controllers/controller-overview.md

@@ -0,0 +1,130 @@
+# Controller Overview
+
+Controllers are responsible for handling incoming requests and getting a response back to the user via replies. They also perform all state transitions.
+
+## Naming Conventions
+
+The controller's methods, also referred to as actions, must be named after the flow's states. So for example, given the flow:
+
+```ruby
+flow :onboard do
+  state :say_welcome
+  state :ask_for_phone
+  state :get_phone, fails_to: :ask_for_phone
+end
+```
+
+The corresponding controller would be:
+
+```ruby
+class OnboardsController < BotController
+  def say_welcome
+
+  end
+
+  def ask_for_phone
+  
+  end
+
+  def get_phone
+
+  end
+end
+```
+
+## BotController
+
+Every Stealth bot comes with a default `bot_controller.rb`. You don't have to know what each method does yet, we'll cover each in their respective doc sections.
+
+```ruby
+# frozen_string_literal: true
+
+class BotController < Stealth::Controller
+
+  helper :all
+
+  def route
+    if current_message.payload.present?
+      handle_payloads
+      # Clear out the payload to prevent duplicate handling
+      current_message.payload = nil
+      return
+    end
+
+    # Allow devs to jump around flows and states by typing:
+    #   /flow_name/state_name or
+    #   /flow_name (jumps to first state) or
+    #   //state_name (jumps to state in current flow)
+    # (only works for bots in development)
+    return if dev_jump_detected?
+
+    if current_session.present?
+      step_to session: current_session
+    else
+      step_to flow: 'hello', state: 'say_hello'
+    end
+  end
+
+private
+
+  # Handle payloads globally since payload buttons remain in the chat
+  # and we cannot guess in which states they will be tapped.
+  def handle_payloads
+    case current_message.payload
+    when 'developer_restart', 'new_user'
+      step_to flow: 'hello', state: 'say_hello'
+    when 'goodbye'
+      step_to flow: 'goodbye'
+    end
+  end
+
+  # Automatically called when clients receive an opt-out error from
+  # the platform. You can write your own steps for handling.
+  def handle_opt_out
+    do_nothing
+  end
+
+  # Automatically called when clients receive an invalid session_id error from
+  # the platform. For example, attempting to text a landline.
+  # You can write your own steps for handling.
+  def handle_invalid_session_id
+    do_nothing
+  end
+
+end
+
+```
+
+All of your controllers will inherit from this `BotController`:
+
+```ruby
+class QuotesController < BotController
+
+end
+```
+
+## Failing to Progress a User
+
+One of the primary responsibilities of a controller is to update a user's session. The other responsibility is sending replies to a user. If you fail to do either of these things, essentially the user at the other end won't have any feedback.
+
+If a controller action fails to update the state or send any replies, Stealth will automatically fire a [CatchAll](catch-alls.md). This is designed to catch errors during development. If you are certain you don't want to send any feedback to the user for a specific action you can call [do\_nothing](sessions/do\_nothing.md) to override Stealth's default behavior. &#x20;
+
+## Before/After/Around Filters
+
+Like Ruby on Rails controllers, Stealth controllers support `before_action`, `after_action`, and `around_action` filters.
+
+Given a `BotController` that loads a user:
+
+```ruby
+class BotController < Stealth::Controller
+
+  before_action :current_user
+  
+  private def current_user
+    @current_user ||= User.find_by_session_id(current_session_id)
+  end
+  
+end
+```
+
+The `current_user` method will be run on all controllers that inherit from `BotController`. Similarly, if you add a `before_action` to a child controller, only that controller's actions will run that filter.

data/docs/controllers/dev-jumps.md

@@ -0,0 +1,47 @@
+# Dev Jumps
+
+Dev Jumps are a feature of Stealth that makes you and your team more productive during development. It enables you to jump between flows and states while interacting with your bot. As you develop your bot, you can avoid having to restart the conversation each time.
+
+{% hint style="warning" %}
+Dev Jumps will only work while your bot is in the `development` environment. Dev jumps in other environments will be ignored.
+{% endhint %}
+
+## Usage
+
+You can specify Dev Jumps in one of three ways:
+
+1. Flow and state.
+2. Just a flow name.
+3. Just a state name.
+
+{% hint style="info" %}
+You can text these at any time to your bot.
+{% endhint %}
+
+### Flow and State
+
+```
+/flow_name/state_name
+```
+
+This will immediately step to the `flow_name` and `state_name` that you specified.
+
+### Flow Name
+
+```
+/flow_name
+```
+
+This will jump the the first state declared in the [FlowMap](../flows/flowmap.md) for the flow.
+
+### State Name
+
+```
+//state_name
+```
+
+This will jump to specified `state_name` within the current flow.
+
+{% hint style="info" %}
+Note the double forward slash `//`. This is essentially because the `flow_name` has been explicitly omitted.
+{% endhint %}

data/docs/controllers/get_match/README.md

@@ -0,0 +1,2 @@
+# get\_match
+

data/docs/controllers/get_match/alpha-ordinals.md

@@ -0,0 +1,2 @@
+# Alpha Ordinals
+

data/docs/controllers/get_match/entity-match.md

@@ -0,0 +1,2 @@
+# Entity Match
+

data/docs/controllers/get_match/exact-match.md

@@ -0,0 +1,2 @@
+# Exact Match
+

data/docs/controllers/handle_message/README.md

@@ -0,0 +1,54 @@
+# handle\_message
+
+The `handle_message` method is one of the most fundamental controller methods in Stealth. It enables you to succinctly handle messages without needing long `if/else` or `case` statements.
+
+## Example
+
+Here's an example of what it looks like:
+
+```ruby
+def get_call_response
+  handle_message(
+    :yes             => proc { step_to state: :say_yes },
+    'Not available'  => proc { step_to state: :say_no_problem },
+    :no              => proc { step_to state: :say_no_problem },
+    :call            => proc { step_to state: :say_call_later }
+  )
+end
+```
+
+In this example, the `handle_message` method has four different "match arms". Each arm is just `key => value` pair since it's all  just a hash. The keys are the `match expressions`. The values are `procs` that serve as the action to take if the match expression is matched.
+
+Stealth accepts match expressions in five different ways:
+
+1. [A string](string-mather.md) (like Line 4)
+2. An [alpha ordinal](alpha-ordinal-matcher.md)
+3. A [symbol](nlp-matcher.md) (like Lines 3, 5, and 6)
+4. A [regex](regex-matcher.md)
+5. [nil](nil-matcher.md)
+
+{% hint style="info" %}
+The `procs` can be multi-line and thus perform more than one action. In the docs for the match expressions we'll include some of those examples.
+{% endhint %}
+
+## Proc Scope
+
+If you are new to Ruby, you might be wondering about `procs`. You can think of them as anonymous functions from Javascript or closures. 
+
+The code inside of the `proc` is executed if the match expression is matched. That code has access to the same variables as the containing method's scope. So for example:
+
+```ruby
+def get_response
+  x = 15
+  handle_message(
+    'Buy' => proc { 
+      x += 1 
+    },
+    'Refinance' => proc { 
+      x += 2 
+    }
+  )
+end
+```
+
+In this example if a user sends the message "Buy", the value of `x` will be `16`. Similarly, if the user sends the message "Refinance", the value of `x` will be `17`.

data/docs/controllers/handle_message/alpha-ordinal-matcher.md

@@ -0,0 +1,40 @@
+# Alpha Ordinal Matcher
+
+Alpha ordinals are a way of providing "quick replies" for messaging services that do not support them natively, such as SMS and Whatsapp. With `handle_message`, they are supported directly.
+
+## Example
+
+Imagine you send a user this reply:
+
+```
+What's your favorite color?
+
+Reply with:
+"A" for Red
+"B" for Blue
+"C" for Green
+"D" for Yellow
+```
+
+{% hint style="info" %}
+Stealth's Twilio component can automatically generate these for you. This is covered in depth in the [YAML Replies docs](../../replies/yaml-replies.md).
+{% endhint %}
+
+The corresponding `handle_message` method would look like this:
+
+```ruby
+def get_response
+  handle_message(
+    'Red' => proc { current_user.update_attributes!(favorite_color: 'red') },
+    'Blue' => proc { current_user.update_attributes!(favorite_color: 'blue') },
+    'Green' => proc { current_user.update_attributes!(favorite_color: 'green') },
+    'Yellow' => proc { current_user.update_attributes!(favorite_color: 'yellow') }
+  )
+end
+```
+
+With alpha ordinals, if a user types "C", then the `Green` match arm is automatically selected since it is the 3rd match expression (Line 5) specified in `handle_message`. Similarly, the user could still reply with "green" directly and that will also match the 3rd match expression (Line 5).
+
+{% hint style="warning" %}
+If a user were to type, "E", then Stealth will still raise a `Stealth::Errors::UnrecognizedMessage` exception.
+{% endhint %}

data/docs/controllers/handle_message/homophone-detection.md

@@ -0,0 +1,36 @@
+# Homophone Detection
+
+One of the problems that arises with [alpha ordinals](alpha-ordinal-matcher.md) is that some English letters sound like other words. So for example, pronouncing "C" sounds like "see" or "sea". The letter "B" sounds like "bee" or "be". These are called homophones.
+
+If your user is using a voice assistant to dictate their responses to your bot, it's likely the voice assistant will substitute one of these homophones for the actual letter and your bot would fail to match the user's message.
+
+This is where homophone detection helps.
+
+{% hint style="info" %}
+Homophone detection is currently only supported for the English language.
+{% endhint %}
+
+## Example
+
+Given this code snippet from the [Alpha Ordinal Matcher docs](alpha-ordinal-matcher.md):
+
+```ruby
+def get_response
+  handle_message(
+    'Red' => proc { current_user.update_attributes!(favorite_color: 'red') },
+    'Blue' => proc { current_user.update_attributes!(favorite_color: 'blue') },
+    'Green' => proc { current_user.update_attributes!(favorite_color: 'green') },
+    'Yellow' => proc { current_user.update_attributes!(favorite_color: 'yellow') }
+  )
+end
+```
+
+If a user enters the letter "b", then the "Blue" match arm will automatically be selected as expected. However, Stealth will also natively accept the input "be" and "bee" from the user and the "Blue" match arm will still be selected. Similarly, "see" and "sea" will select the "Green" match arm.
+
+{% hint style="info" %}
+For a full list of homophones Stealth detects, you can inspect the array constant `Stealth::Controller::Messages::HOMOPHONES`
+{% endhint %}
+
+{% hint style="danger" %}
+If you attempt to use a homophone as your match expression, Stealth will raise a `Stealth::Errors::ReservedHomophoneUsed` exception.
+{% endhint %}

data/docs/controllers/handle_message/nil-matcher.md

@@ -0,0 +1,44 @@
+# Nil Matcher
+
+When none of the match expressions are matched in a `handle_message` method call, by default Stealth will raise a `Stealth::Errors::UnrecognizedMessage` exception. This is typically the desired behavior because it allows the [UnrecognizedMessagesController](../unrecognized-messages.md) to run.
+
+In the event that you don't want to raise an error, like in the case where you want to just save what the user typed in and move on, you can use the nil matcher.
+
+## Example
+
+Given this reply to a user:
+
+```
+How much is your property worth?
+
+Reply with:
+"A" for $1 - $100
+"B" for $101 - $999
+"C" for $1000 - $9999
+```
+
+```ruby
+def get_response
+  handle_message(
+    '$1 - $100' => proc { 
+      current_user.update_attributes!(property_value: '$1 - $100') 
+    },
+    '$101 - $999' => proc { 
+      current_user.update_attributes!(property_value: '$101 - $999') 
+    },
+    '$1000 - $9999' => proc { 
+      current_user.update_attributes!(property_value: '$1000 - $9999') 
+    },
+    nil => proc {
+      amount = current_user.message
+      current_user.update_attributes!(property_value: amount)
+    }
+  )
+end
+```
+
+In the above example, if a user enters a specific amount instead of choosing one of the ranges provided, we just store that amount and don't raise an error.
+
+{% hint style="warning" %}
+You may likely still want to verify the input they entered is a Numeric. There are also better ways to handle an example like this using [get\_match](../get\_match/).
+{% endhint %}

data/docs/controllers/handle_message/nlp-matcher.md

@@ -0,0 +1,51 @@
+# NLP Matcher
+
+NLP is a very important part of creating powerful bots. Stealth seamlessly integrates with NLP services to provide NLP matching from within the same `handle_message` method.
+
+{% hint style="info" %}
+Check out the [NLP section](../../nlp-nlu/overview.md) for more information on how to configure your NLP service to work with Stealth's `handle_message`.
+{% endhint %}
+
+## Example
+
+Let's pretend you've trained your NLP service with some examples of "Yes" and some examples of "No". These are two common intents that you'll likely want to train for your bot. Let's also assume that we've named the "Yes" intent as `yes` and the "No" intent as `no`
+
+{% hint style="warning" %}
+Make sure you name your intents using Ruby's `snake_casing` so they easily be used in `handle_message`.
+{% endhint %}
+
+Given this reply to the user:
+
+```
+Are you interested in learning more about Stealth?
+
+Reply with:
+"A" for Yes
+"B" for Remind me later
+"C" for No longer interested
+```
+
+Here is what our controller action that handles this message can look like with NLP matchers:
+
+```ruby
+def get_response
+  handle_message(
+    :yes => proc {
+      step_to state: :say_proceed
+    },
+    'Remind me later' => proc { step_to state: :say_no_problem },
+    :no => proc { step_to state: :say_goodbye },
+    :call => proc {
+      step_to state: :ask_when_to_call
+    }
+  )
+end
+```
+
+Here, we are using NLP matchers on Lines 3, 7, and 8. NLP matchers have specify match expression as a Ruby symbol.
+
+When Stealth encounters an NLP matcher as a match expression, it will perform NLP using your configured NLP service. The result is automatically cached so that subsequent NLP matchers don't trigger another NLP lookup. The raw result of the NLP query will be stored in `current_message.nlp_result`, but `handle_message` will automatically make use of that without you having to parse it yourself.
+
+If the resulting NLP intent is `yes` then the `:yes` match arm will be matched. The same for `:no` and `:call`. So for example, if a user type "Nah, not interested" it's likely or `:no` match arm will be called. Similarly, if a user writes "Sure!!" the `:yes` match arm will be called.
+
+Another interesting thing to note about this example is that we have a 4th option (`:call`) that isn't explicitly mentioned in the reply to the user. With NLP matchers, it's sometimes useful to do this when your data shows that a lot users are manually typing in a custom response for a specific question. So in this case, we've asked the user if they are interested in learning more about Stealth, but some users will ask to jump on a phone call. So we've trained an NLP intent for "calls" and it will match the cases where a user requests a call for this question.

data/docs/controllers/handle_message/regex-matcher.md

@@ -0,0 +1,41 @@
+# Regex Matcher
+
+When using the [string matcher](string-mather.md), you might have a scenario where the option you present to user for selection is longer or contains more detail than the answer they type. In these cases, it's useful to be able to use a regex to match a just a part of a message.
+
+{% hint style="info" %}
+The regex matcher is not limited to this use case. You can use the full power of Ruby regexes.
+{% endhint %}
+
+## Example
+
+Given this reply to a user:
+
+```
+What would you like to do?
+
+Reply with:
+"A" for I'd like to restart
+"B" for Just stop
+"C" for Repeat
+```
+
+We can take advantage of the regex matcher for options "A" and "B" since it's unlikely a user would type that entire string with the formatting we expect.
+
+```ruby
+def get_response
+  handle_message(
+    /restart/  => proc { step_to flow: :hello },
+    /stop/  => proc { 
+      current_user.opt_out!
+      step_to flow: :opt_out 
+    },
+    'Repeat' => proc { step_to session: previous_session }
+  )
+end
+```
+
+Now if a user types "restart" or "restart plz" it will still match the first match arm. Similarly, if they type "stop" it will match the second match arm. But just as before, typing "just stop" and "B" will also match the second match arm.
+
+{% hint style="info" %}
+Notice how we are able to mix matchers in the same `handle_message` method.
+{% endhint %}

data/docs/controllers/handle_message/string-mather.md

@@ -0,0 +1,23 @@
+# String Matcher
+
+The string matcher matches exact string responses. It will however automatically ignore case and also ignore blank padding preceding and trailing a string. These blank spaces occur frequently with texting apps and autocomplete.
+
+## Example
+
+```ruby
+def get_response
+  handle_message(
+    'Sure'  => proc {
+      current_user.update_attributes!(interested: true)
+      step_to state: :say_yes 
+    },
+    'Nope'  => proc { step_to state: :say_no_problem }
+  )
+end
+```
+
+In this example, if a user types in `SURE` or `SuRE` or `sure`, it will match the first match arm and the corresponding proc will be executed.
+
+{% hint style="warning" %}
+If none of the match expressions are matched, Stealth will raise a `Stealth::Errors::UnrecognizedMessage` exception unless the [nil matcher](nil-matcher.md) is included.
+{% endhint %}

data/docs/controllers/interrupt-detection.md

@@ -0,0 +1,2 @@
+# Interrupt Detection
+

data/docs/controllers/platform-errors.md

@@ -0,0 +1,2 @@
+# Platform Errors
+