ralyxa 1.6.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c3c11a61cf16f000310698095d20d5e9874e9979
-  data.tar.gz: 5e2fbf15562e67fd80ef3980a2aac6b0cab4c3ea
+  metadata.gz: e2097ed5c0dd85b2f0f5d04d0f6c524b9cc90b8b
+  data.tar.gz: 004060b9f538e547270050bcab4a584bd243ef02
 SHA512:
-  metadata.gz: 2117b738f0a7a247c0d202d2b733b09f08c37dbf5bac38aba9df69fa2c67266b795c4b326cdafdbe225713bbeffdc1df5b83dd7558c97dbeac32a688b4e0d2ab
-  data.tar.gz: 761d94e0e2b39dca488f10184242bab4e2c672f56a10b9613bc83d295b842140a75e5c6b9728c8f7f194995b22480a9caf1ac82d50f5b5e737eb5082f2b3ca58
+  metadata.gz: ec37369ea357d04fbde3353ae06b12407eb34282b466a3895ace4a0276f9c0a63ee05c4359436141ec02db1aca8b9e40a0dfa8a9030767c851032a5075c48008
+  data.tar.gz: 840cf253a18ff2a3e552ea359a7ed15e9a120f869c0cf93020286394add6b86cee9d98f054f404abf83ee3c84eb73dc29b9685f41854442335d5445fcfa1758d

data/.gitignore

@@ -1,2 +1,3 @@
 .DS_Store
-Gemfile.lock
+Gemfile.lock
+coverage

data/.rubocop.yml

@@ -6,6 +6,9 @@ AllCops:
 Metrics/LineLength:
   Enabled: false
 
+Metrics/ParameterLists:
+  Max: 6
+
 Style/FrozenStringLiteralComment:
   Enabled: false
 

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to Ralyxa
+
+1. Have tests.
+
+## The basic idea
+
+Ralyxa is in two parts: 
+
+1. The user-facing Ruby interface which looks a bit like Sinatra.
+2. The under-the-hood Ruby-to-JSON translator which directly references Alexa structures.
+
+This gives rise to some principles:
+
+1. The user-facing Ruby interface should try to provide thoughtful abstractions to the Alexa structures.
+2. The under-the-hood Ruby-to-JSON translator should contain objects which directly map onto Alexa structures.
+
+Some other principles:
+
+1. Keep the user-facing Ruby interface as simple as possible. Imagine a brand-new Ruby developer using this.

data/README.md

@@ -93,6 +93,55 @@ intent "ReadFromSession" do
 end
 ```
 
+##### Playing audio with the `AudioPlayer` directive
+
+###### Play
+
+You can play an audio stream right away with:
+
+```ruby
+intent "PlayAudio" do
+  audio_player.play(
+    'https://s3.amazonaws.com/my-ssml-samples/Flourish.mp3',
+    'flourish-token',
+    speech: 'Playing Audio'
+  )
+end
+```
+
+###### Play Later (Enqueue)
+
+You can queue a song to play next with:
+
+```ruby
+intent "PlayAudioLater" do
+  audio_player.play_later(
+    'https://s3.amazonaws.com/my-ssml-samples/Flourish.mp3',
+    'flourish-token'
+  )
+end
+```
+
+###### Stop
+
+You can stop playing with:
+
+```ruby
+intent "StopAudio" do
+  audio_player.stop
+end
+```
+
+###### Clear Queued
+
+You can clear enqueued audio with:
+
+```ruby
+intent "ClearQueue" do
+  audio_player.clear_queue
+end
+```
+
 ##### Reading the session user
 
 You can read the session user's `userId` and `accessToken`, and check that the `accessToken` exists:
@@ -148,7 +197,8 @@ end
 
 # Standard card
 intent "SendStandardCard" do
-  standard_card = card("Hello World", "I'm alive!", "https://placehold.it/200")
+  standard_card = card("Hello World", "I'm alive!", "http://placehold.it/720x480", "http://placehold.it/1200x800")
+  
   ask("What do you think of the Standard card I just sent?", card: standard_card)
 end
 ```
@@ -190,6 +240,20 @@ end
 
 > You can't actually respond to a `SessionEndedRequest`, but you might want to do some tidying in this action.
 
+
+### I want to serve card images, audio stream etc. over HTTP not HTTPS
+
+In some special cases, you may be allowed to serve content over HTTP instead of HTTPS. To allow this within Ralyxa, you need to set the `require_secure_urls` configuration option to false.
+
+> **NOTE:** In order to use HTTP sources, you must be given special approval directly from Amazon. If you use HTTP sources without getting advanced approval, your skill will not work correctly.
+
+```ruby
+Ralyxa.configure do |config|
+  config.require_secure_urls = false
+end
+```
+
+
 ## Testing
 Part of Amazon's requirements for Alexa skills is that they have to ensure requests are sent from Amazon. This is done in a number of ways documented [here](https://developer.amazon.com/docs/custom-skills/host-a-custom-skill-as-a-web-service.html). This verification is built into Ralyxa and can cause issues when testing your skills with stubbed data.
 
@@ -219,9 +283,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/sjmog/
 
 The main areas of focus are:
 
-- Audio directives :construction:
 - Reprompts :construction:
+- Dialogue :construction:
 - Generators of built-in Intents e.g. `SessionEndedRequest`
+- Automation with the `AVS` command line tool
 
 ## License
 

data/lib/ralyxa/configuration.rb

@@ -1,13 +1,18 @@
 module Ralyxa
   class Configuration
-    attr_accessor :validate_requests
+    attr_accessor :validate_requests, :require_secure_urls
 
     def initialize
       @validate_requests = true
+      @require_secure_urls = true
     end
 
     def validate_requests?
       validate_requests
     end
+
+    def require_secure_urls?
+      require_secure_urls
+    end
   end
 end

data/lib/ralyxa/errors.rb

@@ -1,2 +1,4 @@
-class UnsecureUrlError < StandardError
+module Ralyxa
+  class UnsecureUrlError < StandardError
+  end
 end

data/lib/ralyxa/handler.rb

@@ -13,7 +13,10 @@ module Ralyxa
     end
 
     def respond(response_text = '', response_details = {}, response_builder = Ralyxa::ResponseBuilder)
-      response_builder.build(response_details.merge(response_text: response_text))
+      options = response_details
+      options[:response_text] = response_text if response_text
+
+      response_builder.build(options)
     end
 
     def tell(response_text = '', response_details = {})
@@ -24,10 +27,18 @@ module Ralyxa
       card_class.as_hash(title, body, image_url)
     end
 
+    def audio_player
+      Ralyxa::ResponseEntities::Directives::AudioPlayer
+    end
+
     def link_account_card(card_class = Ralyxa::ResponseEntities::Card)
       card_class.link_account
     end
 
+    def log(level, message)
+      puts "[#{Time.new}] [#{@request.user_id}] #{level} - #{message}"
+    end
+
     alias ask respond
 
     attr_reader :request

data/lib/ralyxa/request_entities/request.rb

@@ -13,13 +13,15 @@ module Ralyxa
       def_delegator :@user, :access_token, :user_access_token
       def_delegator :@user, :access_token_exists?, :user_access_token_exists?
 
+      attr_reader :request
+
       def initialize(original_request, user_class = Ralyxa::RequestEntities::User)
+        validate_request(original_request) if Ralyxa.configuration.validate_requests?
+
         @request = JSON.parse(original_request.body.read)
         attempt_to_rewind_request_body(original_request)
 
         @user = user_class.build(@request)
-
-        validate_request(original_request) if Ralyxa.configuration.validate_requests?
       end
 
       def intent_name
@@ -35,8 +37,12 @@ module Ralyxa
         @request['session']['new']
       end
 
+      def session_attributes
+        @request['session']['attributes']
+      end
+
       def session_attribute(attribute_name)
-        @request['session']['attributes'][attribute_name]
+        session_attributes[attribute_name]
       end
 
       private

data/lib/ralyxa/request_entities/user.rb

@@ -9,9 +9,11 @@ module Ralyxa
       end
 
       def self.build(request)
+        user_hash = request.dig('session', 'user') || request.dig('context', 'System', 'user') || {}
+
         new(
-          id: request.dig('session', 'user', 'userId'),
-          access_token: request.dig('session', 'user', 'accessToken')
+          id: user_hash['userId'],
+          access_token: user_hash['accessToken']
         )
       end
 

data/lib/ralyxa/response_builder.rb

@@ -14,7 +14,7 @@ module Ralyxa
     end
 
     def build
-      merge_output_speech
+      merge_output_speech if response_text_exists?
       merge_card if card_exists?
 
       @response_class.as_hash(@options).to_json
@@ -34,6 +34,10 @@ module Ralyxa
       @options[:card]
     end
 
+    def response_text_exists?
+      @options[:response_text]
+    end
+
     def output_speech
       output_speech_params = { speech: @options.delete(:response_text) }
       output_speech_params[:ssml] = @options.delete(:ssml) if @options[:ssml]

data/lib/ralyxa/response_entities/card.rb

@@ -11,8 +11,8 @@ module Ralyxa
         @options = options
       end
 
-      def self.as_hash(title, body, image_url = nil)
-        new(title: title, body: body, image_url: image_url).to_h
+      def self.as_hash(title, body, small_image_url = nil, large_image_url = small_image_url)
+        new(title: title, body: body, small_image_url: small_image_url, large_image_url: large_image_url).to_h
       end
 
       def self.link_account
@@ -24,7 +24,7 @@ module Ralyxa
           add_type(card)
           add_title(card) if @options[:title]
           add_body(card)  if @options[:body]
-          add_image(card) if @options[:image_url]
+          add_image(card) if standard?
         end
       end
 
@@ -46,10 +46,14 @@ module Ralyxa
       end
 
       def add_image(card)
-        raise UnsecureUrlError, "Card images must be available at an SSL-enabled (HTTPS) endpoint. Your current image url is: #{@options[:image_url]}" unless secure?
+        raise Ralyxa::UnsecureUrlError, "Card images must be available at an SSL-enabled (HTTPS) endpoint. Your current image urls are: (small: #{@options[:small_image_url]}, large: #{@options[:large_image_url]}" unless secure_images?
         card[:image] = {}
-        card[:image][:smallImageUrl] = @options[:image_url]
-        card[:image][:largeImageUrl] = @options[:image_url]
+
+        small_image = @options[:small_image_url] || @options[:large_image_url]
+        large_image = @options[:large_image_url] || @options[:small_image_url]
+
+        card[:image][:smallImageUrl] = small_image if small_image
+        card[:image][:largeImageUrl] = large_image if large_image
       end
 
       def link_account?
@@ -57,15 +61,28 @@ module Ralyxa
       end
 
       def simple?
-        !@options[:image_url]
+        !@options[:small_image_url] && !@options[:large_image_url]
       end
 
       def standard?
-        !@options[:image_url].nil?
+        @options[:small_image_url] || @options[:large_image_url]
+      end
+
+      def secure_images?
+        small_secure = secure_uri?(@options[:small_image_url])
+        large_secure = secure_uri?(@options[:large_image_url])
+
+        small_secure && large_secure
       end
 
-      def secure?
-        URI.parse(@options[:image_url]).scheme == 'https'
+      # Given a uri string, retutrn true if:
+      #   * the scheme is https
+      #   * or if we are not interested in the uri being secure
+      #   * or if the value that has been passed is nil
+      def secure_uri?(uri_string)
+        return true if uri_string.nil?
+
+        (URI.parse(uri_string).scheme == 'https' || !Ralyxa.require_secure_urls?)
       end
     end
   end

data/lib/ralyxa/response_entities/directives/audio/audio_item.rb

@@ -0,0 +1,23 @@
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      module Audio
+        class AudioItem
+          def initialize(stream)
+            @stream = stream
+          end
+
+          def to_h
+            {}.tap do |audio_item|
+              audio_item['stream'] = @stream.to_h
+            end
+          end
+
+          def self.as_hash(stream)
+            new(stream).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio/stream.rb

@@ -0,0 +1,37 @@
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      module Audio
+        class Stream
+          def initialize(url, token, offset_in_milliseconds = 0, expected_previous_token = nil)
+            raise Ralyxa::UnsecureUrlError, "Audio streams must be served from at an SSL-enabled (HTTPS) endpoint. Your current stream url is: #{url}" unless secure?(url)
+
+            @url                     = url
+            @token                   = token
+            @offset_in_milliseconds  = offset_in_milliseconds
+            @expected_previous_token = expected_previous_token
+          end
+
+          def to_h
+            {}.tap do |stream|
+              stream['url']                   = @url
+              stream['token']                 = @token
+              stream['offsetInMilliseconds']  = @offset_in_milliseconds
+              stream['expectedPreviousToken'] = @expected_previous_token if @expected_previous_token
+            end
+          end
+
+          def self.as_hash(url, token, offset_in_milliseconds = 0, expected_previous_token = nil)
+            new(url, token, offset_in_milliseconds, expected_previous_token).to_h
+          end
+
+          private
+
+          def secure?(url)
+            URI.parse(url).scheme == 'https' || !Ralyxa.require_secure_urls?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio.rb

@@ -0,0 +1,11 @@
+require_relative './audio/audio_item'
+require_relative './audio/stream'
+
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      module Audio
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio_player/clear_queue.rb

@@ -0,0 +1,27 @@
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      class AudioPlayer
+        class ClearQueue
+          CLEAR_ENQUEUED = 'CLEAR_ENQUEUED'.freeze
+          CLEAR_ALL = 'CLEAR_ALL'.freeze
+
+          def initialize(behaviour = Ralyxa::ResponseEntities::Directives::AudioPlayer::ClearQueue::CLEAR_ENQUEUED)
+            @behaviour = behaviour
+          end
+
+          def to_h
+            {}.tap do |audio_player|
+              audio_player['type'] = 'AudioPlayer.ClearQueue'
+              audio_player['clearBehavior'] = @behaviour
+            end
+          end
+
+          def self.as_hash(behaviour = Ralyxa::ResponseEntities::Directives::AudioPlayer::ClearQueue::CLEAR_ENQUEUED)
+            new(behaviour).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio_player/play.rb

@@ -0,0 +1,32 @@
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      class AudioPlayer
+        class Play
+          CLEAR_ENQUEUE    = 'CLEAR_ENQUEUE'.freeze
+          ENQUEUE          = 'ENQUEUE'.freeze
+          REPLACE_ALL      = 'REPLACE_ALL'.freeze
+          REPLACE_ENQUEUED = 'REPLACE_ENQUEUED'.freeze
+
+          def initialize(stream, behaviour = Ralyxa::ResponseEntities::Directives::AudioPlayer::Play::REPLACE_ALL)
+            @stream    = stream
+            @behaviour = behaviour
+          end
+
+          def to_h
+            {}.tap do |audio_player|
+              audio_player['type'] = 'AudioPlayer.Play'
+              audio_player['playBehavior'] = @behaviour
+
+              audio_player['audioItem'] = Ralyxa::ResponseEntities::Directives::Audio::AudioItem.new(@stream).to_h
+            end
+          end
+
+          def self.as_hash(stream, behaviour = nil)
+            new(stream, behaviour).to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio_player/stop.rb

@@ -0,0 +1,19 @@
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      class AudioPlayer
+        class Stop
+          def to_h
+            {}.tap do |audio_player|
+              audio_player['type'] = 'AudioPlayer.Stop'
+            end
+          end
+
+          def self.as_hash
+            new.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives/audio_player.rb

@@ -0,0 +1,46 @@
+require_relative './audio_player/clear_queue'
+require_relative './audio_player/play'
+require_relative './audio_player/stop'
+
+module Ralyxa
+  module ResponseEntities
+    module Directives
+      class AudioPlayer
+        class << self
+          def play(url, token, speech: nil, card: nil, offset_in_milliseconds: 0, expected_previous_token: nil, behaviour: Ralyxa::ResponseEntities::Directives::AudioPlayer::Play::REPLACE_ALL, audio_player_class: Ralyxa::ResponseEntities::Directives::AudioPlayer::Play, response_builder: Ralyxa::ResponseBuilder)
+            directive = audio_player_class.as_hash(Ralyxa::ResponseEntities::Directives::Audio::Stream.new(url, token, offset_in_milliseconds, expected_previous_token), behaviour)
+
+            response_builder.build(build_options(directive, speech, card))
+          end
+
+          def play_later(url, token, speech: nil, card: nil, offset_in_milliseconds: 0, expected_previous_token: nil, behaviour: Ralyxa::ResponseEntities::Directives::AudioPlayer::Play::REPLACE_ENQUEUED, audio_player_class: Ralyxa::ResponseEntities::Directives::AudioPlayer::Play, response_builder: Ralyxa::ResponseBuilder)
+            play(url, token, speech: speech, card: card, offset_in_milliseconds: offset_in_milliseconds, expected_previous_token: expected_previous_token, behaviour: behaviour, audio_player_class: audio_player_class, response_builder: response_builder)
+          end
+
+          def stop(speech: nil, card: nil, audio_player_class: Ralyxa::ResponseEntities::Directives::AudioPlayer::Stop, response_builder: Ralyxa::ResponseBuilder)
+            directive = audio_player_class.as_hash
+
+            response_builder.build(build_options(directive, speech, card))
+          end
+
+          def clear_queue(speech: nil, card: nil, behaviour: Ralyxa::ResponseEntities::Directives::AudioPlayer::ClearQueue::CLEAR_ALL, audio_player_class: Ralyxa::ResponseEntities::Directives::AudioPlayer::ClearQueue, response_builder: Ralyxa::ResponseBuilder)
+            directive = audio_player_class.as_hash(behaviour)
+
+            response_builder.build(build_options(directive, speech, card))
+          end
+
+          private
+
+          def build_options(directive, speech, card)
+            {}.tap do |option|
+              option[:directives] = [directive]
+              option[:end_session] = false
+              option[:response_text] = speech if speech
+              option[:card] = card if card
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralyxa/response_entities/directives.rb

@@ -0,0 +1,9 @@
+require_relative './directives/audio'
+require_relative './directives/audio_player'
+
+module Ralyxa
+  module ResponseEntities
+    module Directives
+    end
+  end
+end

data/lib/ralyxa/response_entities/response.rb

@@ -1,14 +1,16 @@
 require_relative './output_speech'
+require_relative './directives'
 
 module Ralyxa
   module ResponseEntities
     class Response
-      def initialize(output_speech, session_attributes, end_session, start_over, card)
+      def initialize(output_speech, session_attributes, end_session, start_over, card, directives)
         @output_speech      = output_speech
         @session_attributes = session_attributes
         @end_session        = end_session
         @start_over         = start_over
         @card               = card
+        @directives         = directives
       end
 
       def to_h
@@ -19,8 +21,8 @@ module Ralyxa
         end
       end
 
-      def self.as_hash(output_speech: Ralyxa::OutputSpeech.as_hash, session_attributes: {}, end_session: false, start_over: false, card: false)
-        new(output_speech, session_attributes, end_session, start_over, card).to_h
+      def self.as_hash(output_speech: false, session_attributes: {}, end_session: false, start_over: false, card: false, directives: false)
+        new(output_speech, session_attributes, end_session, start_over, card, directives).to_h
       end
 
       private
@@ -37,10 +39,12 @@ module Ralyxa
       end
 
       def add_response(response)
-        response[:response] = {}
-        response[:response][:outputSpeech] = @output_speech
-        response[:response][:card] = @card if @card
-        response[:response][:shouldEndSession] = @end_session
+        response[:response] = {}.tap do |response_object|
+          response_object[:outputSpeech]     = @output_speech if @output_speech
+          response_object[:card]             = @card          if @card
+          response_object[:directives]       = @directives    if @directives
+          response_object[:shouldEndSession] = @end_session
+        end
       end
     end
   end

data/lib/ralyxa/version.rb

@@ -1,3 +1,3 @@
 module Ralyxa
-  VERSION = '1.6.2'.freeze
+  VERSION = '1.7.0'.freeze
 end

data/ralyxa.gemspec

@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'timecop', '~> 0.9'
   spec.add_development_dependency 'vcr',     '~> 3.0'
   spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'simplecov', '~> 0.15'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ralyxa
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.0
 platform: ruby
 authors:
 - Sam Morgan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-10 00:00:00.000000000 Z
+date: 2018-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alexa_verifier
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
 description: A Ruby framework for interacting with Amazon Alexa. Designed to work
   with Sinatra, although can be used with a few other web frameworks.
 email:
@@ -122,6 +136,7 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -137,6 +152,14 @@ files:
 - lib/ralyxa/request_entities/user.rb
 - lib/ralyxa/response_builder.rb
 - lib/ralyxa/response_entities/card.rb
+- lib/ralyxa/response_entities/directives.rb
+- lib/ralyxa/response_entities/directives/audio.rb
+- lib/ralyxa/response_entities/directives/audio/audio_item.rb
+- lib/ralyxa/response_entities/directives/audio/stream.rb
+- lib/ralyxa/response_entities/directives/audio_player.rb
+- lib/ralyxa/response_entities/directives/audio_player/clear_queue.rb
+- lib/ralyxa/response_entities/directives/audio_player/play.rb
+- lib/ralyxa/response_entities/directives/audio_player/stop.rb
 - lib/ralyxa/response_entities/output_speech.rb
 - lib/ralyxa/response_entities/response.rb
 - lib/ralyxa/skill.rb
@@ -163,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: A Ruby framework for interacting with Amazon Alexa.