alexa_ruby 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81b1c1d716759449c12046344b3cd8fc75a39063
-  data.tar.gz: ad89af2cee60262bdb2f00c2283113fd575a1a20
+  metadata.gz: 614cfabdfe8ff5b456181b71845955ef4f42cc70
+  data.tar.gz: 272c62255de2f0ffe5ad774fa3cb87a331e6253d
 SHA512:
-  metadata.gz: 9282ec9d6a7fe0a36e0121da659d3dbfe17eaff4f4a9f961d2b05190c1eb92cab63e73f886ce613ec2596d935caf334c55f50f5bfd696ca27b2d9159c073e6fc
-  data.tar.gz: 5b508751a1daafd887f0f29b33b9915b3aa3372386b82e11c699667fc1384737c38748d5b60980d777819ef1259e1a12d03db4e887ca954ad9a5515e69e59223
+  metadata.gz: ca93f9950a01cb3dcbf3337ba4e669d8b7de7aa9af49cc3d9800ef3205286a04fd6a459838026ada39b1e2dc6be877df869061018863824f2aca5bd730d8f035
+  data.tar.gz: 16a2a33ca5ec93c3af3a0c7cd519dd4d3ec89871ef2afa907a4b659055ee05cb54db0825a87ee165dd24e31c334b397c459bae2596e113077faa069485508629

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    alexa_ruby (1.0.3)
+    alexa_ruby (1.0.4)
       bundler (>= 1.6.9)
       oj (~> 3.0)
       rake

data/README.md

@@ -31,6 +31,7 @@ $ gem install alexa_ruby
 
 |Resource|URL|
 |---|---|
+|Amazon Alexa Skill Kit docs|[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interface-reference](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/alexa-skills-kit-interface-reference)|
 |Rubydoc|[http://www.rubydoc.info/gems/alexa_ruby](http://www.rubydoc.info/gems/alexa_ruby)|
 |Source|[https://github.com/mulev/alexa-ruby](https://github.com/mulev/alexa-ruby)|
 |Bugs|[https://github.com/mulev/alexa-ruby/issues](https://github.com/mulev/alexa-ruby/issues)|
@@ -38,33 +39,183 @@ $ gem install alexa_ruby
 ## Usage
 
 Gem provides a possibility to easily handle requests from Amazon Alexa service and build responses to given requests.
-Usage is as easy as:
+
+### Getting started
+
+AlexaRuby usage is quite simple, to start you need to require gem in your ruby
+file and pass it JSON request from Amazon Alexa service.  
+Here and below all examples will be based on Roda routing tree framework, but
+you can use any other -- AlexaRuby is a framework independent gem.
 
 ```ruby
+require 'roda'
 require 'alexa_ruby'
 
-alexa = AlexaRuby.new(request) # request is a HTTP request body
-alexa.response.tell!('Ruby is awesome!')
+class App < Roda
+  route do |r|
+    r.post do
+      r.on 'alexa' do
+        alexa = AlexaRuby.new(r.body.read)
+      end
+    end
+  end
+end
+```
+
+After initializing new AlexaRuby instance you will have a possibility to access
+all parameters of the received request.
+
+#### General request parameters
+
+|Access path|Description|
+|---|---|
+|alexa.request.json|given JSON request|
+|alexa.request.version|request version, typically "1.0"|
+|alexa.request.type|request type, can be :launch, :intent, :session_ended or :audio_player|
+|alexa.request.id|request ID|
+|alexa.request.timestamp|request timestamp|
+|alexa.request.locale|request locale|
+
+#### Session parameters
+
+Notice that user data exists in two scopes -- session and context.
+
+|Access path|Description|
+|---|---|
+|alexa.request.session.id|session ID|
+|alexa.request.session.attributes|array with all session attributes|
+|alexa.request.session.end_reason|session end reason, can be :user_quit, :processing_error or :user_idle|
+|alexa.request.session.error|hash with session error info|
+|alexa.request.session.state|current session state, can be :new, :old or :ended|
+|alexa.request.session.user.id|skill user ID|
+|alexa.request.session.user.access_token|user access token if account linking is enabled and user is authenticated|
+|alexa.request.session.user.permissions_token|user permissions token|
+
+#### Context parameters
+
+Notice that user data exists in two scopes -- session and context.
+
+|Access path|Description|
+|---|---|
+|alexa.request.context.app_id|Alexa application ID|
+|alexa.request.context.api_endpoint|Alexa API endpoint|
+|alexa.request.context.user.id|skill user ID|
+|alexa.request.context.user.access_token|user access token if account linking is enabled and user is authenticated|
+|alexa.request.context.user.permissions_token|user permissions token|
+|alexa.request.context.device.id|user device ID|
+|alexa.request.context.device.interfaces|interfaces, supported by user device|
+
+#### Intent request parameters
+
+|Access path|Description|
+|---|---|
+|alexa.request.intent_name|given intent name|
+|alexa.request.dialog_state|state of dialog with user, can be :started, :in_progress or :completed|
+|alexa.request.confirmation_status|user confirmation status, can be :unknown, :confirmed or :denied|
+|alexa.request.slots|array with all slots from intent|
+
+#### Audio player request parameters
+
+|Access path|Description|
+|---|---|
+|alexa.request.playback_state|current playback state|
+|alexa.request.playback_offset|current playback offset in milliseconds|
+|alexa.request.error_type|playback error type|
+|alexa.request.error_message|playback error message explaining error|
+|alexa.request.error_playback_token|audio player token of failed playback|
+|alexa.request.error_player_activity|audio player activity in moment of failure|
+
+### Building response
+
+To build a response take your freshly initialized `alexa` and start using `alexa.response` methods.
+
+#### Add session attributes
+
+It is possible to add one attribute to session scope:
+
+```ruby
+alexa.response.add_session_attribute('key', 'value')
+```
+
+Exception will be raised if attribute already exists in the session scope.  
+If you want to overwrite it, call:
+
+```ruby
+alexa.response.add_session_attribute('key', 'value_2', true)
+```
+
+You can also add a pack of attributes. To overwrite all existing ones call:
+
+```ruby
+alexa.response.add_session_attributes(key: 'value', key_2: 'value_2')
 ```
 
-This simple example will return a valid JSON with response to Amazon Alexa service request:
-
-```json
-{
-  "version": "1.0",
-  "sessionAttributes": {},
-  "response": {
-    "shouldEndSession": true,
-    "outputSpeech": {
-      "type": "PlainText",
-      "text": "Ruby is awesome!"
-    }
-  }
+To add new attributes and save existing ones call:
+
+```ruby
+alexa.response.merge_session_attributes(key: 'value', key_2: 'value_2')
+```
+
+#### Add card
+
+Supported card types are: Simple, Standard and LinkAccount.
+
+```ruby
+card = {
+  type: 'Standard', title: 'Test', content: 'test',
+  small_image_url: 'https://test.ru/example_small.jpg',
+  large_image_url: 'https://test.ru/example_large.jpg'
 }
+alexa.response.add_card(card)
+```
+
+#### Add audio player directive
+
+Supported directives - AudioPlayer.Play and AudioPlayer.Stop.  
+To start playback call:
+
+```ruby
+params = { url: 'https://my-site.com/my-stream', token: 'test', offset: 0 }
+alexa.response.add_audio_player_directive(:start, params)
+```
 
+To stop playback call:
+
+```ruby
+alexa.response.add_audio_player_directive(:stop)
 ```
 
-Gem can be used with any framework - Rails, Sinatra, Cuba, Roda, or any other that can handle HTTP requests and responses.
+#### Get current state of response encoded in JSON
+
+```ruby
+alexa.response.json
+```
+
+#### Add output speech to response
+
+Ask user a question and wait for response (session will remain open):
+
+```ruby
+question = 'What can I do for you?'
+
+alexa.response.ask(question)                  # will add outputSpeech node
+alexa.response.ask(question, question)        # outputSpeech node and reprompt node
+alexa.response.ask(question, question, true)  # outputSpeech node, reprompt node and both will be converted into SSML
+
+alexa.response.ask!(question)                 # will add outputSpeech node and return JSON encoded response object
+```
+
+Tell something to user and end conversation (session will be closed):
+
+```ruby
+speech = 'You are awesome!'
+
+alexa.response.tell(speech)               # will add outputSpeech node
+alexa.response.tell(speech, speech)       # outputSpeech node and reprompt node
+alexa.response.tell(speech, speech, true) # outputSpeech node, reprompt node and both will be converted into SSML
+
+alexa.response.tell!(speech)              # will add outputSpeech node and return JSON encoded response object
+```
 
 ## Testing
 
@@ -89,4 +240,4 @@ All development is made only in develop branch before being merged to master.
 
 ## License
 
-AlexaRuby is released under [MIT license](https://github.com/mulev/alexa-ruby/blob/master/LICENSE).
+AlexaRuby is released under the [MIT license](https://github.com/mulev/alexa-ruby/blob/master/LICENSE).

data/lib/alexa_ruby/request/base_request/session.rb

@@ -1,7 +1,7 @@
 module AlexaRuby
   # Amazon Alexa user session
   class Session
-    attr_reader :id, :attributes, :end_reason, :error
+    attr_reader :id, :attributes, :user, :end_reason, :error
     attr_accessor :state
 
     # Initialize new Session
@@ -15,6 +15,7 @@ module AlexaRuby
       @state = @session[:new] ? :new : :old
       @id = @session[:sessionId]
       @attributes = @session[:attributes] || {}
+      @user = load_user unless @session[:user].nil?
     end
 
     # Set session end reason
@@ -56,5 +57,12 @@ module AlexaRuby
     def invalid_session?
       @session.nil?
     end
+
+    # Initialize user parameters
+    #
+    # @return [Object] new User object instance
+    def load_user
+      User.new(@session[:user])
+    end
   end
 end

data/lib/alexa_ruby/response/response.rb

@@ -18,6 +18,7 @@ module AlexaRuby
     #
     # @param key [String] atrribute key
     # @param value [String] attribute value
+    # @param rewrite [Boolean] rewrite if key already exists?
     # @raise [ArgumentError] if session key is already added and
     #   rewrite is set to false
     def add_session_attribute(key, value, rewrite = false)

data/lib/alexa_ruby/version.rb

@@ -1,3 +1,3 @@
 module AlexaRuby
-  VERSION = '1.0.4'.freeze
+  VERSION = '1.1.0'.freeze
 end

data/lib/alexa_ruby.rb

@@ -7,8 +7,8 @@ require 'alexa_ruby/alexa'
 require 'alexa_ruby/request/base_request'
 require 'alexa_ruby/request/base_request/context'
 require 'alexa_ruby/request/base_request/context/device'
-require 'alexa_ruby/request/base_request/context/user'
 require 'alexa_ruby/request/base_request/session'
+require 'alexa_ruby/request/base_request/user'
 require 'alexa_ruby/request/audio_player_request'
 require 'alexa_ruby/request/launch_request'
 require 'alexa_ruby/request/intent_request'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alexa_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Mulev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-01 00:00:00.000000000 Z
+date: 2017-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -110,8 +110,8 @@ files:
 - lib/alexa_ruby/request/base_request.rb
 - lib/alexa_ruby/request/base_request/context.rb
 - lib/alexa_ruby/request/base_request/context/device.rb
-- lib/alexa_ruby/request/base_request/context/user.rb
 - lib/alexa_ruby/request/base_request/session.rb
+- lib/alexa_ruby/request/base_request/user.rb
 - lib/alexa_ruby/request/intent_request.rb
 - lib/alexa_ruby/request/intent_request/slot.rb
 - lib/alexa_ruby/request/launch_request.rb