alexa-rails 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 313cea798184b82bb7e8ad3a18c2948508dc22f7
-  data.tar.gz: 49d36e905f428bb11a5023512d86888bb8f07701
+SHA256:
+  metadata.gz: 37d49fb2475d98d5c65ab9a9b383e04d59354a2f2301bc80b6e73daa68edb07c
+  data.tar.gz: 0f24851a1b5d60b2801749a2aa710e6abbab29e56473fb8abc91a6340b61419e
 SHA512:
-  metadata.gz: 1d057ed83fa856bde32cbf5411d818330a7060bed6c98bea6604a96e2d20106abd9a5aa5a8c690eb09df80cc49163dc5c5261de8819e0261f80b160f8fcd6917
-  data.tar.gz: ab87cd7060f2fcced5ec2d9ca79023e722e1b8f346817b1b44d2a4b889eb2ddd0e476498b2fc033602927aab040bb14ef67b0fe7692e29e9eb750b2194fc806b
+  metadata.gz: 52e1ca2f604b126d3013d739c9c70b7889cac16d6824aa9f947fc2c17b05550820e2c90e7083918e28be548f7b24f39a4f47f4878fa856028dd792a6a835d532
+  data.tar.gz: df7368c54678c6a1bb731c934b186df3db0a52fbdf6244d3690334e60fd09eaaf3fb385480e1ace1feeb50a8cabc54a06d809d6246a345b825136e80d86ae56d

data/README.md

@@ -1,12 +1,12 @@
-# Alexa
+# Alexa-rails
 `alexa-rails` is a ruby gem which is a mountable rails engine that will add abilities to your Ruby on Rails application to handle Amazon alexa requests and responses.
 
 ## Intallation/Usage
 
-Do the usual by adding the following to your Gemfile:
+Do the usual by adding the following to your `Gemfile`:
 
 ```ruby
-gem install alexa-rails
+gem 'alexa-rails'
 ```
 
 ### Migrations
@@ -33,9 +33,7 @@ Set alexa skill IDs in environment config (ex: config/environments/development.r
     "amzn1.ask.skill.xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"
   ]
 
-  config.x.alexa.default_card_title = [
-    "Alexa rails"
-  ]
+  config.x.alexa.default_card_title = "Alexa rails"
 ```
 
 Mount the engine for routes handling in your routes
@@ -49,15 +47,17 @@ Mount the engine for routes handling in your routes
   end
 ```
 
-### Request handling
+This will make you Rails app accept `POST` requests from Alexa at
+```
+https://<your-domain>/alexa/intent_handlers
+```
+This has to be provided as the HTTPS endpoint URL for the skill.
 
-After the above steps, your application is ready to accept requests from Alexa
-servers at `/alexa/intent_handlers`.
-You will have to provide that in the HTTPS endpoint URL for your skill.
+### Request handling
 
 To handle an intent, you will have to create an intent handler class.
 For example, if your intent is named `PlaceOrder`, you will have to create
-the following file under you `app/lib/intent_handlers` directory.
+the following file under you `app/lib/alexa/intent_handlers` directory.
 
 ```ruby
 module Alexa
@@ -65,6 +65,7 @@ module Alexa
     class PlaceOrder < Alexa::IntentHandlers::Base
       def handle
         ...
+        response # intent handlers should always return the +response+ object 
       end
     end
   end
@@ -73,12 +74,21 @@ end
 
 All intent handlers should contain a `#handle` method that has required logic
 as to how to handle the intent request. For example, adding session variables,
-setting response to elicit slots, etc.
+setting response to elicit slots, delegate etc. 
+
+**Note**: `#handle` method should always return the `response` object.
+`response` object in available in the scope of `#handle`.
 
-Adding session variable:
+See [Handling Amazon's Built-in Intents / Other request types] section to see
+how to handle Amazon's built-in intent and other requests types.
+
+#### Adding session variable:
 
 ```ruby
 session.merge!(my_var: value)
+
+# Accesssing session variable
+session[:my_var]
 ```
 
 #### Slot elicitations
@@ -90,6 +100,20 @@ slot and the respecitve views are used.
 response.elicit_slot!(:SlotName)
 ```
 
+#### Delete response
+
+`#handle` is expected to return an instance of `Alexa::Response` or its subclasses.
+In normal cases, the `response` object is returned. 
+In cases where the slots elicitation is delegated to alexa, an instance of 
+`Alexa::Responses::Delegate` has to be returned. 
+
+```ruby
+  def handle
+    ...
+    return Alexa::Responses::Delegate.new
+  end
+```
+
 ### Views
 
 The content for speech and display cards is not set in the intent handler
@@ -146,6 +170,31 @@ view file for the response as follows:
 
 ```
 
+## Handling Amazon's Built-in Intents / Other request types
+
+Requests for Amazon's built-in intents and other request types
+are also handled with intent handlers. 
+Below is the mapping for every request type and respective 
+intent handler classes.
+These intent handlers are not included in the gem as they are a
+but specific to the application.
+Refer to the table below and implement the intent handlers.
+
+Built-in Intents:
+
+| Intent name | Handler class |
+| ------------- | ------------- |
+| AMAZON.CancelIntent | `Alexa::IntentHandlers::GoodBye` |
+| AMAZON.StopIntent | `Alexa::IntentHandlers::GoodBye` |
+| AMAZON.HelpIntent | `Alexa::IntentHandlers::Help` |
+
+Other request types:
+
+| Request type | Handler class |
+| ------------- | ------------- |
+| Launch request | `Alexa::IntentHandlers::LaunchApp` |
+| Session end request | `Alexa::IntentHandlers::SessionEnd` |
+
 ## Installation
 Add this line to your application's Gemfile:
 

data/lib/alexa/request.rb

@@ -82,16 +82,7 @@ module Alexa
     end
 
     def locale
-      request_locale = params["request"]["locale"]
-      case params["request"]["locale"]
-      when "en-US", "en-GB", "en-IN", 'en-CA'
-        # this is to match pjpp locale codes
-        params["request"]["locale"].gsub("-", "_").downcase
-      when "de-DE"
-        "de"
-      else
-        "en_gb"
-      end
+      params["request"]["locale"]
     end
   end
 end

data/lib/alexa/session.rb

@@ -1,3 +1,17 @@
+# Provides easy access to session data from the request.
+#
+# Extends from +HashWithIndifferentAccess+ and initailised with the
+# session hash from the request
+#
+# <b>Session variables</b>:
+# Session variables can be accessed the same way as accessing hash with keys.
+# ```ruby
+# session[:my_var] # Reads the variable
+# session.merge!(my_var: "Some value") # Write a session variable
+# ```
+#
+# Apart from session handling, class also provides an API to other session
+# related information.
 module Alexa
   class Session < HashWithIndifferentAccess
     def initialize(session={})
@@ -5,14 +19,27 @@ module Alexa
       super(session["attributes"])
     end
 
+    # Get the elicitation count of a slot.
+    #
+    # Elicitation counts are maintained in the session so that they
+    # can be referred to within the intenthandlers or the views
+    #
+    # Options:
+    #   - slot_name: Slot name to return the elicitation count for
     def elicitation_count_for(slot_name)
       self["elicitations"] ||= {}
       if self["elicitations"][slot_name].present?
-        return self["elicitations"][slot_name]["count"]
-      end
+        return self["elicitations"][slot_name]["count"] end
       return 0
     end
 
+    # Increase the elicitation count of a slot.
+    #
+    # Elicitation counts are maintained in the session so that they
+    # can be referred to within the intenthandlers or the views
+    #
+    # Options:
+    #   - slot_name: Slot name to increment the elicitation count for
     def increment_elicitation_count!(slot_name)
       count = elicitation_count_for(slot_name)
       self["elicitations"].merge!(
@@ -20,14 +47,17 @@ module Alexa
       )
     end
 
+    # Whether its a new session.
     def new?
       @variables["new"] == true
     end
 
+    # Get application's ID from session
     def application_id
       @variables["application"]["applicationId"]
     end
 
+    # Get Amazon user's ID from session
     def user_id
       @variables["user"]["userId"]
     end

data/lib/alexa/version.rb

@@ -1,3 +1,3 @@
 module Alexa
-  VERSION = '0.1.2'
+  VERSION = '0.1.3'
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: alexa-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Sri Vishnu Totakura
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-27 00:00:00.000000000 Z
+date: 2018-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.1'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Serve Alexa skills with your rails app as backend