aws-lex-conversation 5.1.1 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46556f575fd08ac0ded8d8fc50692be70388fbf1e3d96ff8d236c82a5e8eb860
-  data.tar.gz: c5456ec5961936b210d80491bb9edaebf503c71daba5acf755257b36ae211875
+  metadata.gz: 3a4ab092d321df0c71e5f16cf1021e87358b1b39ab025eaf5555e3e3da7894c1
+  data.tar.gz: a0332c4f2f73b35972c83a0740e1adfa4d724fe5d9861087d348e905e3e15633
 SHA512:
-  metadata.gz: dfcf7591d2c9667d17f3863dde180724c4dc5ec5b2f623173be6c11b6cbf9548d99b39ae1ad809e25adb6069fea9239dc58c3a8776bc85340ec07c9752a3c976
-  data.tar.gz: 6cd97d779b1e482c19300db5cb63e9d36f01278be04c896dc603138b0a293d0baf8fa8cfadfd95d27896b4a467d81211607bb0cb551e960f72d3efd740a5a9cf
+  metadata.gz: 734b1ec8921c8982a3e123520b08b0d0b9e655159c781f7df18d106b8de635815bc026862fd6a4ec7a3d2665d47393bb8d977cf530a1331e2f3c2bea543b4a94
+  data.tar.gz: 2c4c43bafd522791d6f5f39596c7b594d3788098876b51fc8294cf2304a23c42a06fd6635e15e791410bc824273599f9afab3935fd853981f81b732672d03d96

data/.rubocop.yml

@@ -20,12 +20,17 @@ Metrics/AbcSize:
   Max: 20
 Metrics/ClassLength:
   Max: 150
+  Exclude:
+    - lib/aws/lex/conversation/simulator.rb
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
     - '*.gemspec'
 Metrics/MethodLength:
   Max: 25
+Metrics/ModuleLength:
+  Exclude:
+    - lib/aws/lex/conversation/spec/matchers.rb
 Naming/FileName:
   Enabled: true
   Exclude:

data/CHANGELOG.md

@@ -1,3 +1,107 @@
+# 6.2.0 - Sept 28, 2021
+
+* Add a `Aws::Lex::Conversation#restore_from!` method that accepts a checkpoint parameter. This method modifies the underlying conversation state to match the data from the saved checkpoint.
+* Make the `dialog_action_type` parameter on `Aws::Lex::Conversation#checkpoint!` default to `Delegate` if not specified as a developer convenience.
+* Allow developers to pass an optional `intent` override parameter on `Aws::Lex::Conversation#checkpoint!` for convenience.
+* Update the README with advanced examples for the conversation stash and checkpoints.
+
+# 6.1.1 - Sept 22, 2021
+
+* renamed `maximum_elicitations` to `max_retries` and made it backwards compatible to make the param name clear, by default this value is zero, allowing each slot to elicit only once
+
+# 6.1.0 - Sept 7, 2021
+
+Added helper methods for clearing active contexts
+
+```ruby
+conversation.clear_context!(name: 'test') # clears this specific active context
+conversation.clear_all_contexts! # clears all current active contexts
+```
+
+# 6.0.0 - Sept 7, 2021
+
+* **breaking change** - Modify `Aws::Lex::Conversation::Type::Base#computed_property` to accept a block instead of a callable argument. This is an internal class and should not require any application-level changes.
+* **breaking change** - Add a required `alias_name` attribute on `Aws::Lex::Conversation::Type::Bot` instances. Please note that the Version 2 of AWS Lex correctly returns this value as input to lambda functions. Therefore no application-level changes are necessary.
+* Implement a new set of test helpers to make it easier to modify state and match test expectations. You can use the test helpers as follows:
+
+```ruby
+# we must explicitly require the test helpers
+require 'aws/lex/conversation/spec'
+
+# optional: include the custom matchers if you're using RSpec
+RSpec.configure do |config|
+  config.include(Aws::Lex::Conversation::Spec)
+end
+
+# we can now simulate state in a test somewhere
+it 'simulates a conversation' do
+  conversation                      # given we have an instance of Aws::Lex::Conversation
+    .simulate!                      # simulation modifies the underlying instance
+    .transcript('My age is 21')     # optionally set an input transcript
+    .intent(name: 'MyCoolIntent')   # route to the intent named "MyCoolIntent"
+    .slot(name: 'Age', value: '21') # add a slot named "Age" with a corresponding value
+
+  expect(conversation).to have_transcript('My age is 21')
+  expect(conversation).to route_to_intent('MyCoolIntent')
+  expect(conversation).to have_slot(name: 'Age', value: '21')
+end
+
+# if you'd rather create your own event from scratch
+it 'creates an event' do
+  simulator = Aws::Lex::Conversation::Simulator.new
+  simulator
+    .transcript('I am 21 years old.')
+    .input_mode('Speech')
+    .context(name: 'WelcomeGreetingCompleted')
+    .invocation_source('FulfillmentCodeHook')
+    .session(username: 'jane.doe')
+    .intent(
+      name: 'GuessZodiacSign',
+      state: 'ReadyForFulfillment',
+      slots: {
+        age: {
+          value: '21'
+        }
+      }
+    )
+  event = simulator.event
+
+  expect(event).to have_transcript('I am 21 years old.')
+  expect(event).to have_input_mode('Speech')
+  expect(event).to have_active_context(name: 'WelcomeGreetingCompleted')
+  expect(event).to have_invocation_source('FulfillmentCodeHook')
+  expect(event).to route_to_intent('GuessZodiacSign')
+  expect(event).to have_slot(name: 'age', value: '21')
+  expect(event).to include_session_values(username: 'jane.doe')
+end
+```
+
+* Add a few convenience methods to `Aws::Lex::Conversation` instances for dealing with active contexts:
+  - `#active_context(name:)`:
+
+     Returns the active context instance that matches the name parameter.
+
+  - `#active_context?(name:)`:
+
+     Returns true/false depending on if an active context matching
+     the name parameter is found.
+
+  - `#active_context!(name:, turns:, seconds:, attributes:)`:
+
+     Creates or updates an existing active context instance for
+     the conversation.
+
+# 5.1.0 - Sept 2, 2021
+
+* Allow the intent to be specified when returning a response such as `elicit_slot`.
+
+# 5.0.0 - August 30, 2021
+
+* **breaking change** - `Aws::Lex::Conversation::Support::Mixins::SlotElicitation`
+  - Rename the `message` attribute to `messages`. This attribute must be a callable that returns and array of `Aws::Lex::Conversation::Type::Message` instances.
+  - rename the `follow_up_message` attribute to `follow_up_messages`. This must also be a callable that returns an array of message instances.
+* Allow the `fallback` callable in `SlotElicitation` to be nilable. The slot value will not be elicited if the value is nil and maximum attempts have been exceeded.
+
 # 4.3.0 - August 25, 2021
 
 * Slot elicitor can now be passed an Aws::Lex::Conversation::Type::Message as part of the DSL/callback and properly formats the response as such

data/README.md

@@ -191,6 +191,170 @@ conversation.handlers = [
 conversation.respond # => { dialogAction: { type: 'Delegate' } }
 ```
 
+## Advanced Concepts
+
+This library provides a few constructs to help manage complex interactions:
+
+### Data Stash
+
+`Aws::Lex::Conversation` instances implement a `stash` method that can be used to store temporary data within a single invocation.
+
+A conversation's stashed data will not be persisted between multiple invocations of your lambda function.
+
+The conversation stash is a great spot to store deserialized data from the session, or invocation-specific state that needs to be shared between handler classes.
+
+This example illustrates how the stash can be used to store deserialized data from the session:
+
+```ruby
+# given we have JSON-serialized data in as a persisted session value
+conversation.session[:user_data] = '{"name":"Jane","id":1234,"email":"test@example.com"}'
+# we can deserialize the data into a Hash that we store in the conversation stash
+conversation.stash[:user] = JSON.parse(conversation.session[:user_data])
+# later on we can reference our stashed data (within the same invocation)
+conversation.stash[:user] # => {"name"=>"Jane", "id"=>1234, "email"=>"test@example.com"}
+```
+
+### Checkpoints
+
+A conversation may transition between many different topics as the interaction progresses. This type of state transition can be easily handled with checkpoints.
+
+When a checkpoint is created, all intent and slot data is encoded and stored into a `checkpoints` session value. This data persists between invocations, and is not removed until the checkpoint is restored.
+
+You can create a checkpoint as follows:
+
+```ruby
+# we're ready to fulfill the OrderFlowers intent, but we want to elicit another intent first
+conversation.checkpoint!(
+  label: 'order_flowers',
+  dialog_action_type: 'Close' # defaults to 'Delegate' if not specified
+)
+conversation.elicit_intent(
+  messages: [
+    {
+      content: 'Thanks! Before I place your order, is there anything else I can help with?',
+      contentType: 'PlainText'
+    }
+  ]
+)
+```
+
+You can restore the checkpoint in one of two ways:
+
+```ruby
+# in a future invocation, we can fetch an instance of the checkpoint and easily
+# restore the conversation to the previous state
+checkpoint = conversation.checkpoint(label: 'order_flowers')
+checkpoint.restore!(
+  fulfillment_state: 'Fulfilled',
+  messages: [
+    {
+      content: 'Okay, your flowers have been ordered! Thanks!',
+      contentType: 'PlainText'
+    }
+  ]
+) # => our response object to Lex is returned
+```
+
+It's also possible to restore state from a checkpoint and utilize the conversation's handler chain:
+
+```ruby
+class AnotherIntent < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == 'AnotherIntent' &&
+    conversation.checkpoint?(label: 'order_flowers')
+  end
+
+  def response(conversation)
+    checkpoint = conversation.checkpoint(label: 'order_flowers')
+    # replace the conversation's current resolved intent/slot data with the saved checkpoint data
+    conversation.restore_from!(checkpoint)
+    # call the next handler in the chain to produce a response
+    successor.handle(conversation)
+  end
+end
+
+class OrderFlowers < Aws::Lex::Conversation::Handler::Base
+  def will_respond?(conversation)
+    conversation.intent_name == 'OrderFlowers'
+  end
+
+  def response(conversation)
+    conversation.close(
+      fulfillment_state: 'Fulfilled',
+      messages: [
+        {
+          content: 'Okay, your flowers have been ordered! Thanks!',
+          contentType: 'PlainText'
+        }
+      ]
+    )
+  end
+end
+
+conversation = Aws::Lex::Conversation.new(event: event, context: context)
+conversation.handlers = [
+  { handler: AnotherIntent },
+  { handler: OrderFlowers }
+]
+conversation.respond # => returns a Lex response object
+```
+
+## Test Helpers
+
+This library provides convenience methods to make testing easy! You can use the test helpers as follows:
+
+```ruby
+# we must explicitly require the test helpers
+require 'aws/lex/conversation/spec'
+
+# optional: include the custom matchers if you're using RSpec
+RSpec.configure do |config|
+  config.include(Aws::Lex::Conversation::Spec)
+end
+
+# we can now simulate state in a test somewhere
+it 'simulates a conversation' do
+  conversation                      # given we have an instance of Aws::Lex::Conversation
+    .simulate!                      # simulation modifies the underlying instance
+    .transcript('My age is 21')     # optionally set an input transcript
+    .intent(name: 'MyCoolIntent')   # route to the intent named "MyCoolIntent"
+    .slot(name: 'Age', value: '21') # add a slot named "Age" with a corresponding value
+
+  expect(conversation).to have_transcript('My age is 21')
+  expect(conversation).to route_to_intent('MyCoolIntent')
+  expect(conversation).to have_slot(name: 'Age', value: '21')
+end
+
+# if you'd rather create your own event from scratch
+it 'creates an event' do
+  simulator = Aws::Lex::Conversation::Simulator.new
+  simulator
+    .transcript('I am 21 years old.')
+    .input_mode('Speech')
+    .context(name: 'WelcomeGreetingCompleted')
+    .invocation_source('FulfillmentCodeHook')
+    .session(username: 'jane.doe')
+    .intent(
+      name: 'GuessZodiacSign',
+      state: 'ReadyForFulfillment',
+      slots: {
+        age: {
+          value: '21'
+        }
+      }
+    )
+  event = simulator.event
+
+  expect(event).to have_transcript('I am 21 years old.')
+  expect(event).to have_input_mode('Speech')
+  expect(event).to have_active_context(name: 'WelcomeGreetingCompleted')
+  expect(event).to have_invocation_source('FulfillmentCodeHook')
+  expect(event).to route_to_intent('GuessZodiacSign')
+  expect(event).to have_slot(name: 'age', value: '21')
+  expect(event).to include_session_values(username: 'jane.doe')
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/aws/lex/conversation/simulator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      class Simulator
+        attr_accessor :lex
+
+        def initialize(opts = {})
+          self.lex = opts.fetch(:lex) do
+            Type::Event.shrink_wrap(
+              bot: default_bot,
+              inputMode: 'Text',
+              inputTranscript: '',
+              interpretations: [],
+              invocationSource: 'DialogCodeHook',
+              messageVersion: '1.0',
+              requestAttributes: {},
+              responseContentType: 'text/plain; charset=utf-8',
+              sessionId: '1234567890000',
+              sessionState: default_session_state
+            )
+          end
+          interpretation(name: 'SIMULATION')
+        end
+
+        def event
+          lex.to_lex
+        end
+
+        def bot(opts = {})
+          changes = {
+            aliasName: opts[:alias_name],
+            aliasId: opts[:alias_id],
+            name: opts[:name],
+            version: opts[:version],
+            localeId: opts[:locale_id],
+            id: opts[:id]
+          }.compact
+          lex.bot = Type::Bot.shrink_wrap(lex.bot.to_lex.merge(changes))
+          self
+        end
+
+        def transcript(message)
+          lex.input_transcript = message
+          self
+        end
+
+        def intent(opts = {})
+          data = default_intent(opts)
+          intent = Type::Intent.shrink_wrap(data)
+          lex.session_state.intent = intent
+          interpretation(data)
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def interpretation(opts = {})
+          name = opts.fetch(:name)
+          slots = opts.fetch(:slots) { {} }
+          sentiment_score = opts.dig(:sentiment_response, :sentiment_score)
+          sentiment = opts.dig(:sentiment_response, :sentiment)
+          sentiment_response = opts[:sentiment_response] && {
+            sentiment: sentiment,
+            sentimentScore: sentiment_score
+          }
+          data = {
+            intent: default_intent(opts),
+            sentimentResponse: sentiment_response,
+            nluConfidence: opts[:nlu_confidence]
+          }.compact
+          lex.interpretations.delete_if { |i| i.intent.name == name }
+          lex.interpretations << Type::Interpretation.shrink_wrap(data)
+          slots.each do |key, value|
+            slot_data = { name: key }.merge(value)
+            slot(slot_data)
+          end
+          reset_computed_properties!
+          self
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def context(opts = {})
+          data = {
+            name: opts.fetch(:name),
+            contextAttributes: opts.fetch(:context_attributes) { {} },
+            timeToLive: {
+              timeToLiveInSeconds: opts.fetch(:seconds) { 600 },
+              turnsToLive: opts.fetch(:turns) { 100 }
+            }
+          }
+          context = Type::Context.shrink_wrap(data)
+          lex.session_state.active_contexts.delete_if { |c| c.name == context.name }
+          lex.session_state.active_contexts << context
+          self
+        end
+
+        def slot(opts = {})
+          name = opts.fetch(:name).to_sym
+          raw_slots = {
+            shape: opts.fetch(:shape) { 'Scalar' },
+            value: {
+              originalValue: opts.fetch(:original_value) { opts.fetch(:value) },
+              resolvedValues: opts.fetch(:resolved_values) { [opts.fetch(:value)] },
+              interpretedValue: opts.fetch(:interpreted_value) { opts.fetch(:value) }
+            }
+          }
+          lex.session_state.intent.raw_slots[name] = raw_slots
+          current_interpretation.intent.raw_slots[name] = raw_slots
+          reset_computed_properties!
+          self
+        end
+
+        def invocation_source(source)
+          lex.invocation_source = Type::InvocationSource.new(source)
+          self
+        end
+
+        def input_mode(mode)
+          lex.input_mode = Type::InputMode.new(mode)
+          self
+        end
+
+        def session(data)
+          lex.session_state.session_attributes.merge!(Type::SessionAttributes[data])
+          self
+        end
+
+        private
+
+        def current_interpretation
+          lex.interpretations.find { |i| i.intent.name == lex.session_state.intent.name }
+        end
+
+        # computed properties are memoized using instance variables, so we must
+        # uncache the values when things change
+        def reset_computed_properties!
+          %w[
+            @alternate_intents
+            @current_intent
+            @intents
+          ].each do |variable|
+            lex.instance_variable_set(variable, nil)
+          end
+
+          lex.session_state.intent.instance_variable_set('@slots', nil)
+          current_interpretation.intent.instance_variable_set('@slots', nil)
+        end
+
+        def default_bot
+          {
+            aliasId: 'TSTALIASID',
+            aliasName: 'TestBotAlias',
+            id: 'BOT_ID',
+            localeId: 'en_US',
+            name: 'SIMULATOR',
+            version: 'DRAFT'
+          }
+        end
+
+        def default_session_state
+          {
+            activeContexts: [],
+            sessionAttributes: {},
+            intent: {
+              confirmationState: 'None',
+              name: 'SIMULATION',
+              slots: {},
+              state: 'InProgress',
+              originatingRequestId: SecureRandom.uuid
+            }
+          }
+        end
+
+        def default_intent(opts = {})
+          {
+            confirmationState: opts.fetch(:confirmation_state) { 'None' },
+            kendraResponse: opts[:kendra_response],
+            name: opts.fetch(:name),
+            nluConfidence: opts[:nlu_confidence],
+            originatingRequestId: opts.fetch(:originating_request_id) { SecureRandom.uuid },
+            slots: opts.fetch(:slots) { {} },
+            state: opts.fetch(:state) { 'InProgress' }
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/slot/elicitation.rb

@@ -6,7 +6,7 @@ module Aws
       module Slot
         class Elicitation
           attr_accessor :name, :elicit, :messages, :follow_up_messages,
-                        :fallback, :maximum_elicitations, :conversation
+                        :fallback, :max_retries, :conversation
 
           def initialize(opts = {})
             self.name = opts.fetch(:name)
@@ -14,7 +14,7 @@ module Aws
             self.messages = opts.fetch(:messages)
             self.follow_up_messages = opts.fetch(:follow_up_messages) { opts.fetch(:messages) }
             self.fallback = opts[:fallback]
-            self.maximum_elicitations = opts.fetch(:maximum_elicitations) { 0 }
+            self.max_retries = opts[:max_retries] || opts[:maximum_elicitations] || 0
           end
 
           def elicit!
@@ -53,9 +53,7 @@ module Aws
           end
 
           def maximum_elicitations?
-            return false if maximum_elicitations.zero?
-
-            elicitation_attempts > maximum_elicitations
+            elicitation_attempts > max_retries
           end
 
           def first_elicitation?

data/lib/aws/lex/conversation/spec/matchers.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Aws
+  module Lex
+    class Conversation
+      module Spec
+        module Matchers
+          extend RSpec::Matchers::DSL
+
+          # :nocov:
+          def build_event(input)
+            case input
+            when Aws::Lex::Conversation
+              input.lex.to_lex
+            when Hash
+              input
+            else
+              raise ArgumentError, \
+                    'expected instance of Aws::Lex::Conversation ' \
+                    "or Hash, got: #{input.inspect}"
+            end
+          end
+          # :nocov:
+
+          matcher(:have_transcript) do |expected|
+            match do |actual|
+              build_event(actual).fetch(:inputTranscript) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              "expected a transcript of '#{expected}', got '#{response.fetch(:inputTranscript)}'"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              "expected transcript to not equal '#{expected}', got '#{response.fetch(:inputTranscript)}'"
+            end
+            # :nocov:
+          end
+
+          matcher(:route_to_intent) do |expected|
+            match do |actual|
+              build_event(actual).dig(:sessionState, :intent, :name) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              "expected intent to be '#{expected}', got '#{response.dig(:sessionState, :intent, :name)}'"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              "expected intent to not be '#{expected}', got '#{response.dig(:sessionState, :intent, :name)}'"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_active_context) do |expected|
+            match do |actual|
+              build_event(actual).dig(:sessionState, :activeContexts).any? { |c| c[:name] == expected }
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              names = response.dig(:sessionState, :activeContexts).map { |c| c[:name] }.inspect
+              "expected active context of `#{expected}` in #{names}"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              names = response.dig(:sessionState, :activeContexts).map { |c| c[:name] }.inspect
+              "expected active contexts to not include `#{expected}`, got:  #{names}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_invocation_source) do |expected|
+            match do |actual|
+              build_event(actual).fetch(:invocationSource) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              "expected invocationSource of `#{expected}`, got: #{response[:invocationSource]}"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              "expected invocationSource to not be `#{expected}`, got:  #{response[:invocationSource]}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_input_mode) do |expected|
+            match do |actual|
+              build_event(actual).fetch(:inputMode) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              "expected inputMode of `#{expected}`, got: #{response[:inputMode]}"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              "expected inputMode to not be `#{expected}`, got:  #{response[:inputMode]}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_interpretation) do |expected|
+            match do |actual|
+              build_event(actual).fetch(:interpretations).any? { |i| i.dig(:intent, :name) == expected }
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              response = build_event(actual)
+              names = response[:interpretations].map { |i| i.dig(:intent, :name) }.inspect
+              "expected interpretation of `#{expected}` in #{names}"
+            end
+
+            failure_message_when_negated do |actual|
+              response = build_event(actual)
+              names = response[:interpretations].map { |_i| c.dig(:intent, :name) }.inspect
+              "expected interpretations to not include `#{expected}`, got:  #{names}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_slot) do |opts|
+            name = opts.fetch(:name)
+            value = opts[:value]
+            values = value && [value]
+            expected_slot = {
+              shape: opts.fetch(:shape) { 'Scalar' },
+              value: {
+                originalValue: opts.fetch(:original_value, value),
+                interpretedValue: opts.fetch(:interpreted_value, value),
+                resolvedValues: opts.fetch(:resolved_values, values)
+              }.compact
+            }
+
+            match do |actual|
+              slot = build_event(actual).dig(:sessionState, :intent, :slots, name.to_sym)
+              slot[:shape] == expected_slot[:shape] &&
+                slot[:value].slice(*expected_slot[:value].keys) == expected_slot[:value]
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              slot = build_event(actual).dig(:sessionState, :intent, :slots, name.to_sym)
+              "expected #{expected_slot.inspect} to equal #{slot.inspect}"
+            end
+
+            failure_message_when_negated do |actual|
+              slot = build_event(actual).dig(:sessionState, :intent, :slots, name.to_sym)
+              "expected #{expected_slot.inspect} to not equal #{slot.inspect}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_action) do |expected|
+            match do |actual|
+              build_event(actual).dig(:sessionState, :dialogAction, :type) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              "expected #{build_event(actual).dig(:sessionState, :dialogAction, :type)} to equal #{expected}"
+            end
+
+            failure_message_when_negated do |actual|
+              "expected #{build_event(actual).dig(:sessionState, :dialogAction, :type)} to not equal #{expected}"
+            end
+            # :nocov:
+          end
+
+          matcher(:have_intent_state) do |expected|
+            match do |actual|
+              build_event(actual).dig(:sessionState, :intent, :state) == expected
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              "expected #{build_event(actual).dig(:sessionState, :intent, :state)} to equal #{expected}"
+            end
+
+            failure_message_when_negated do |actual|
+              "expected #{build_event(actual).dig(:sessionState, :intent, :state)} to not equal #{expected}"
+            end
+            # :nocov:
+          end
+
+          matcher(:elicit_slot) do |expected|
+            match do |actual|
+              response = build_event(actual)
+
+              response.dig(:sessionState, :dialogAction, :type) == 'ElicitSlot' &&
+                response.dig(:sessionState, :dialogAction, :slotToElicit) == expected
+            end
+          end
+
+          matcher(:include_session_values) do |expected|
+            match do |actual|
+              response = build_event(actual)
+              response.dig(:sessionState, :sessionAttributes).slice(*expected.keys) == expected
+            end
+          end
+
+          matcher(:have_message) do |expected|
+            match do |actual|
+              build_event(actual)[:messages].any? { |m| m.slice(*expected.keys) == expected }
+            end
+
+            # :nocov:
+            failure_message do |actual|
+              "expected matching message of #{expected.inspect} in #{build_event(actual)[:messages].inspect}"
+            end
+
+            failure_message_when_negated do |actual|
+              "found matching message of #{expected.inspect} in #{build_event(actual)[:messages].inspect}"
+            end
+            # :nocov:
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/spec.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+require_relative 'simulator'
+require_relative 'spec/matchers'
+
+module Aws
+  module Lex
+    class Conversation
+      module Spec
+        def self.included(base)
+          base.include(Matchers)
+        end
+      end
+
+      def simulate!
+        @simulate ||= Simulator.new(lex: lex)
+      end
+    end
+  end
+end

data/lib/aws/lex/conversation/type/base.rb

@@ -71,14 +71,19 @@ module Aws
               ->(v) { v.transform_keys(&:to_sym) }
             end
 
-            def computed_property(attribute, callable)
-              mapping[attribute] = attribute
+            def computed_property(attribute, opts = {}, &block)
               attr_writer(attribute)
 
+              if opts.fetch(:virtual) { false }
+                virtual_attributes << attribute
+              else
+                mapping[attribute] = attribute
+              end
+
               # dynamically memoize the result
               define_method(attribute) do
                 instance_variable_get("@#{attribute}") ||
-                  instance_variable_set("@#{attribute}", callable.call(self))
+                  instance_variable_set("@#{attribute}", block.call(self))
               end
             end
 

data/lib/aws/lex/conversation/type/bot.rb

@@ -8,6 +8,7 @@ module Aws
           include Base
 
           required :alias_id
+          required :alias_name
           required :id
           required :locale_id
           required :name

data/lib/aws/lex/conversation/type/checkpoint.rb

@@ -20,6 +20,34 @@ module Aws
             fulfillment_state: FulfillmentState
           )
 
+          class << self
+            def build(opts = {})
+              new(normalize_parameters(opts))
+            end
+
+            private
+
+            def normalize_parameters(opts)
+              params = opts.dup # we don't want to mutate our arguments
+
+              if params[:dialog_action_type].is_a?(String)
+                params[:dialog_action_type] = DialogActionType.new(params[:dialog_action_type])
+              end
+
+              if params[:fulfillment_state].is_a?(String)
+                params[:fulfillment_state] = FulfillmentState.new(params[:fulfillment_state])
+              end
+
+              params
+            end
+          end
+
+          # restore the checkpoint AND remove it from session
+          def restore!(conversation, opts = {})
+            conversation.checkpoints.delete_if { |c| c.label == label }
+            restore(conversation, opts)
+          end
+
           # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           def restore(conversation, opts = {})
             case dialog_action_type.raw

data/lib/aws/lex/conversation/type/context.rb

@@ -7,9 +7,9 @@ module Aws
         class Context
           include Base
 
-          required :context_attributes
           required :name
           required :time_to_live
+          required :context_attributes, default: -> { {} }
 
           coerce(
             context_attributes: symbolize_hash!,

data/lib/aws/lex/conversation/type/event.rb

@@ -18,21 +18,21 @@ module Aws
           required :session_id
           required :session_state
 
-          computed_property :current_intent, ->(instance) do
+          computed_property(:current_intent, virtual: true) do |instance|
             instance.session_state.intent.tap do |intent|
-              intent.nlu_confidence = instance.interpretations.find { |i| i.intent.name == intent.name }.nlu_confidence
+              intent.nlu_confidence = instance.interpretations.find { |i| i.intent.name == intent.name }&.nlu_confidence
             end
           end
 
-          computed_property :intents, ->(instance) do
+          computed_property(:intents, virutal: true) do |instance|
             instance.interpretations.map(&:intent).tap do |intents|
               intents.map do |intent|
-                intent.nlu_confidence = instance.interpretations.find { |i| i.intent.name == intent.name }.nlu_confidence
+                intent.nlu_confidence = instance.interpretations.find { |i| i.intent.name == intent.name }&.nlu_confidence
               end
             end
           end
 
-          computed_property :alternate_intents, ->(instance) do
+          computed_property(:alternate_intents, virtual: true) do |instance|
             instance.intents.reject { |intent| intent.name == instance.current_intent.name }
           end
 

data/lib/aws/lex/conversation/type/intent.rb

@@ -15,7 +15,7 @@ module Aws
           optional :originating_request_id
           optional :nlu_confidence
 
-          computed_property :slots, ->(instance) do
+          computed_property(:slots) do |instance|
             # any keys indexed without a value will return an empty Slot instance
             default_hash = Hash.new do |_hash, key|
               Slot.shrink_wrap(active: false, name: key.to_sym, value: nil, shape: 'Scalar')

data/lib/aws/lex/conversation/type/slot.rb

@@ -20,10 +20,7 @@ module Aws
           )
 
           def to_lex
-            super.merge(
-              value: transform_to_lex(lex_value),
-              values: transform_to_lex(lex_values)
-            )
+            super.merge(extra_response_attributes)
           end
 
           def value=(val)
@@ -35,7 +32,7 @@ module Aws
           def value
             raise TypeError, 'use values for List-type slots' if shape.list?
 
-            lex_value.interpreted_value
+            lex_value&.interpreted_value
           end
 
           # takes an array of slot values
@@ -87,6 +84,20 @@ module Aws
           def requestable?
             active? && blank?
           end
+
+          private
+
+          def extra_response_attributes
+            if shape.list?
+              {
+                values: transform_to_lex(lex_values)
+              }
+            else
+              {
+                value: transform_to_lex(lex_value)
+              }
+            end
+          end
         end
       end
     end

data/lib/aws/lex/conversation/version.rb

@@ -3,7 +3,7 @@
 module Aws
   module Lex
     class Conversation
-      VERSION = '5.1.1'
+      VERSION = '6.2.0'
     end
   end
 end

data/lib/aws/lex/conversation.rb

@@ -62,9 +62,9 @@ module Aws
         label = opts.fetch(:label)
         params = {
           label: label,
-          dialog_action_type: opts.fetch(:dialog_action_type),
+          dialog_action_type: opts.fetch(:dialog_action_type) { 'Delegate' },
           fulfillment_state: opts[:fulfillment_state],
-          intent: lex.current_intent,
+          intent: opts.fetch(:intent) { lex.current_intent },
           slot_to_elicit: opts[:slot_to_elicit]
         }.compact
 
@@ -72,9 +72,8 @@ module Aws
           # update the existing checkpoint
           checkpoint(label: label).assign_attributes!(params)
         else
-          # push a new checkpoint to the recent_intent_summary_view
           checkpoints.unshift(
-            Type::Checkpoint.new(params)
+            Type::Checkpoint.build(params)
           )
         end
       end
@@ -91,6 +90,58 @@ module Aws
         lex.session_state.session_attributes.checkpoints
       end
 
+      def restore_from!(checkpoint)
+        # we're done with the stored checkpoint once it's been restored
+        checkpoints.delete_if { |c| c.label == checkpoint.label }
+        # remove any memoized intent data
+        lex.current_intent = nil
+        # replace the intent with data from the checkpoint
+        lex.session_state.intent = checkpoint.intent
+        dialog_action = Type::DialogAction.new(
+          type: checkpoint.dialog_action_type,
+          slot_to_elicit: checkpoint.slot_to_elicit
+        )
+        lex.session_state.dialog_action = dialog_action
+        self
+      end
+
+      def active_context?(name:)
+        !active_context(name: name).nil?
+      end
+
+      def active_context(name:)
+        lex.session_state.active_contexts.find { |c| c.name == name }
+      end
+
+      def active_context!(name:, turns: 10, seconds: 300, attributes: {})
+        # look for an existing active context if present
+        instance = active_context(name: name)
+
+        if instance
+          clear_context!(name: name)
+        else
+          instance = Type::Context.new
+        end
+
+        # update attributes as requested
+        instance.name = name
+        instance.context_attributes = attributes
+        instance.time_to_live = Type::TimeToLive.new(
+          turns_to_live: turns,
+          time_to_live_in_seconds: seconds
+        )
+        lex.session_state.active_contexts << instance
+        instance
+      end
+
+      def clear_context!(name:)
+        lex.session_state.active_contexts.delete_if { |c| c.name == name }
+      end
+
+      def clear_all_contexts!
+        lex.session_state.active_contexts = []
+      end
+
       def stash
         @stash ||= {}
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aws-lex-conversation
 version: !ruby/object:Gem::Version
-  version: 5.1.1
+  version: 6.2.0
 platform: ruby
 authors:
 - Jesse Doyle
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-03 00:00:00.000000000 Z
+date: 2021-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shrink_wrap
@@ -67,8 +67,11 @@ files:
 - lib/aws/lex/conversation/response/delegate.rb
 - lib/aws/lex/conversation/response/elicit_intent.rb
 - lib/aws/lex/conversation/response/elicit_slot.rb
+- lib/aws/lex/conversation/simulator.rb
 - lib/aws/lex/conversation/slot/elicitation.rb
 - lib/aws/lex/conversation/slot/elicitor.rb
+- lib/aws/lex/conversation/spec.rb
+- lib/aws/lex/conversation/spec/matchers.rb
 - lib/aws/lex/conversation/support/inflector.rb
 - lib/aws/lex/conversation/support/mixins/responses.rb
 - lib/aws/lex/conversation/support/mixins/slot_elicitation.rb