alexa_ruby 0.2.0 → 1.0.0

data/lib/alexa_ruby/request/launch_request.rb

@@ -1,19 +1,12 @@
 module AlexaRuby
   # LaunchRequest class implements Alexa "LaunchRequest" request type
-  class LaunchRequest < Request
+  class LaunchRequest < BaseRequest
     # Initialize new launch request
     #
-    # @param json [JSON] valid JSON request from Amazon
-    def initialize(json)
+    # @param request [Hash] valid request from Amazon Alexa service
+    def initialize(request)
       @type = :launch
       super
     end
-
-    # Outputs the launch requestID
-    #
-    # @return [String] launch request ID
-    def to_s
-      "LaunchRequest requestID: #{request_id}"
-    end
   end
 end

data/lib/alexa_ruby/request/session_ended_request.rb

@@ -1,23 +1,23 @@
 # Session end request class.
 module AlexaRuby
-  # Class for Amazon "SessionEndedRequest" request type
-  class SessionEndedRequest < Request
-    attr_accessor :reason
-
+  # Amazon "SessionEndedRequest" request type
+  class SessionEndedRequest < BaseRequest
     # Initialize new SessionEndedRequest
     #
-    # @param json [JSON] valid JSON request from Amazon
-    def initialize(json)
+    # @param request [Hash] valid request from Amazon Alexa service
+    def initialize(request)
       @type = :session_ended
-      @reason = json[:request][:reason]
       super
+      finalize_session
     end
 
-    # Ouputs the request_id and the reason of session end
-    #
-    # @return [String] request_id and the reason of session end
-    def to_s
-      "Session Ended for requestID: #{request_id} with reason #{reason}"
+    private
+
+    # Set final session params
+    def finalize_session
+      @session.state = :ended
+      @session.end_reason = @req[:request][:reason]
+      @session.error = @req[:request][:error] unless @req[:request][:error].nil?
     end
   end
 end

data/lib/alexa_ruby/response/audio_player.rb

@@ -1,51 +1,44 @@
-require 'securerandom'
-require 'uri'
-
 module AlexaRuby
   # AudioPlayer class encapsulates all Alexa audio player directives
   class AudioPlayer
-    attr_accessor :directive
-
-    # Initialize new directive object
-    def initialize
-      @directive = {}
-    end
-
     # Build an AudioPlayer.Play directive
     #
-    # @param opts [Hash] optional request parameters:
-    #                     - streaming URL
-    #                     - radio station token
-    #                     - expected previous station token
-    #                     - playback offset
+    # @param params [Hash] optional request parameters:
+    #   url [String] streaming URL
+    #   token [String] streaming service token
+    #   offset [Integer] playback offset
     # @return [Hash] AudioPlayer.Play directive
-    def build_play_directive(opts)
-      raise ArgumentError, 'Invalid streaming URL' unless valid_url?(opts[:url])
-      token = opts[:token] || SecureRandom.uuid
-      offset = opts[:offset] || 0
-      @directive[:type] = 'AudioPlayer.Play'
-      @directive[:playBehavior] = 'REPLACE_ALL'
-      @directive[:audioItem] = { stream: {} }
-      @directive[:audioItem][:stream][:url] = opts[:url]
-      @directive[:audioItem][:stream][:token] = token
-      @directive[:audioItem][:stream][:offsetInMilliseconds] = offset
+    def play_directive(params)
+      url = params[:url]
+      token = params[:token] || SecureRandom.uuid
+      offset = params[:offset] || 0
+      build_directive('AudioPlayer.Play', url, token, offset)
     end
 
     # Build AudioPlayer.Stop directive
     #
     # @return [Hash] AudioPlayer.Stop directive
-    def build_stop_directive
-      @directive[:type] = 'AudioPlayer.Stop'
+    def stop_directive
+      build_directive('AudioPlayer.Stop')
     end
 
     private
 
-    # Is it a valid URL?
+    # Set play directive parameters
     #
-    # @param url [String] streaming URL
-    # @return [Boolean]
-    def valid_url?(url)
-      url =~ /\A#{URI.regexp(['https'])}\z/
+    # @param type [String] directive type, can be Play or Stop
+    # @param url [String] streaming service URL
+    # @param token [String] streaming service token
+    # @param offset [Integer] playback offset
+    def build_directive(type, url = nil, token = nil, offset = nil)
+      directive = { type: type }
+      return directive if type == 'AudioPlayer.Stop'
+      directive[:playBehavior] = 'REPLACE_ALL'
+      directive[:audioItem] = { stream: {} }
+      directive[:audioItem][:stream][:url] = url
+      directive[:audioItem][:stream][:token] = token
+      directive[:audioItem][:stream][:offsetInMilliseconds] = offset
+      directive
     end
   end
 end

data/lib/alexa_ruby/response/card.rb

@@ -1,25 +1,80 @@
 module AlexaRuby
   # Class for Amazon Alexa app cards
   class Card
-    attr_accessor :obj
+    attr_reader :obj
 
     # Initialize new card object
-    def initialize
+    #
+    # @param params [Hash] card parameters:
+    #   type [String] card type, can be "Simple", "Standard" or "LinkAccount"
+    #   title [String] card title
+    #   content [String] card content (line breaks must be already included)
+    #   small_image_url [String] an URL for small card image
+    #   large_image_url [String] an URL for large card image
+    # @return [Hash] ready to use card object
+    # @raise [ArgumentError] if card type is unknown
+    def initialize(params)
       @obj = {}
+      @obj[:type] = params[:type] || 'Simple'
+      raise ArgumentError, 'Unknown card type' unless valid_type?
+      @params = params
+      build
+    end
+
+    private
+
+    # Check if card type is valid
+    #
+    # @return [Boolean]
+    def valid_type?
+      %w[Simple Standard LinkAccount].include? @obj[:type]
     end
 
     # Build card object
     #
-    # @param opts [Hash] card parameters:
-    #                     - type - card type
-    #                     - title - card title
-    #                     - subtitle - card subtitle
-    #                     - content - card body content
-    def build(opts)
-      @obj[:type] = opts[:type]
-      @obj[:title] = opts[:title] unless opts[:title].nil?
-      @obj[:subtitle] = opts[:subtitle] unless opts[:subtitle].nil?
-      @obj[:content] = opts[:content] unless opts[:content].nil?
+    # @return [Hash] ready to use card object
+    def build
+      return if @obj[:type] == 'LinkAccount'
+      add_title
+      add_content unless @params[:content].nil?
+      return unless @obj[:type] == 'Standard'
+      return if @params[:small_image_url].nil? &&
+                @params[:large_image_url].nil?
+      add_images
+    end
+
+    # Add card title to object
+    #
+    # @raise [ArgumentError] if not title found
+    def add_title
+      raise ArgumentError, 'Card need a title' if @params[:title].nil?
+      @obj[:title] = @params[:title]
+    end
+
+    # Add content to card body.
+    # Content must be already prepared and contain needed line breaks.
+    # \r\n or \n can be used for line breaks
+    def add_content
+      type =
+        case @obj[:type]
+        when 'Simple'
+          :content
+        when 'Standard'
+          :text
+        end
+      @obj[type] = @params[:content]
+    end
+
+    # Add images to card
+    def add_images
+      @obj[:image] = {}
+
+      if @params[:small_image_url]
+        @obj[:image][:smallImageUrl] = @params[:small_image_url]
+      end
+
+      return unless @params[:large_image_url]
+      @obj[:image][:largeImageUrl] = @params[:large_image_url]
     end
   end
 end

data/lib/alexa_ruby/response.rb

@@ -1,176 +1,204 @@
-require 'alexa_ruby/response/audio_player'
-require 'alexa_ruby/response/card'
-
 module AlexaRuby
-  # Class implements response for Amazon Alexa API
+  # Response for Amazon Alexa service request
   class Response
-    attr_accessor :version, :session, :response_object, :session_attributes,
-                  :speech, :reprompt, :response, :card
-
-    # Initialize new response and set response version
+    # Initialize new response
     #
-    # @param version [String] response version
-    def initialize(version = '1.0')
-      @session_attributes = {}
-      @version = version
-      @directives = []
+    # @param request_type [Symbol] AlexaRuby::Request type
+    # @param version [String] Amazon Alexa SDK version
+    def initialize(request_type, version = '1.0')
+      @req_type = request_type
+      @resp = {
+        version: version,
+        sessionAttributes: {},
+        response: { shouldEndSession: true }
+      }
     end
 
-    # Adds a key => value pair to the session object
+    # Add one session attribute
     #
-    # @param key [String] attribute key
+    # @param key [String] atrribute key
     # @param value [String] attribute value
-    def add_session_attribute(key, value)
-      @session_attributes[key.to_sym] = value
+    # @raise [ArgumentError] if session key is already added and
+    #   rewrite is set to false
+    def add_session_attribute(key, value, rewrite = false)
+      unless rewrite
+        if @resp[:sessionAttributes].key?(key)
+          raise ArgumentError, 'Duplicate session attributes not allowed'
+        end
+      end
+      @resp[:sessionAttributes][key] = value
     end
 
-    # Add output speech to response object.
-    # Speech can be plain text or SSML text, default type is plain text
+    # Add pack of session attributes and overwrite all existing ones
     #
-    # @param speech_text [String] output speech
-    # @param ssml [Boolean] is it an SSML speech or not
-    def add_speech(speech_text, ssml = false)
-      @speech =
-        if ssml
-          { type: 'SSML', ssml: check_ssml(speech_text) }
-        else
-          { type: 'PlainText', text: speech_text }
-        end
-      @speech
+    # @param attributes [Hash] pack of session attributes
+    # @raise [ArgumentError] if given paramter is not a Hash object
+    def add_session_attributes(attributes)
+      unless attributes.is_a? Hash
+        raise ArgumentError, 'Attributes must be a Hash'
+      end
+      session_attributes(attributes, false)
+    end
+
+    # Add pack of session attributes to existing ones
+    #
+    # @param attributes [Hash] pack of session attributes
+    # @raise [ArgumentError] if given paramter is not a Hash object
+    def merge_session_attributes(attributes)
+      unless attributes.is_a? Hash
+        raise ArgumentError, 'Attributes must be a Hash'
+      end
+      session_attributes(attributes, true)
+    end
+
+    # Add card to response object
+    #
+    # @param params [Hash] card parameters:
+    #   type [String] card type, can be "Simple", "Standard" or "LinkAccount"
+    #   title [String] card title
+    #   content [String] card content (line breaks must be already included)
+    #   small_image_url [String] an URL for small card image
+    #   large_image_url [String] an URL for large card image
+    # @raise [NoMethodError] if card is not allowed
+    def add_card(params = {})
+      card_exception unless %i[launch intent].include? @req_type
+      card = Card.new(params)
+      @resp[:response][:card] = card.obj
     end
 
     # Add AudioPlayer directive
     #
     # @param directive [String] audio player directive type,
     #                           can be :start or :stop
-    # @param opts [Hash] optional request parameters
-    def add_audio_player_directive(directive, opts = {})
+    # @param params [Hash] optional request parameters:
+    #   url [String] streaming URL
+    #   token [String] streaming service token
+    #   offset [Integer] playback offset
+    def add_audio_player_directive(directive, params = {})
       player = AudioPlayer.new
-      @directives = []
-      case directive.to_sym
-      when :start
-        player.build_play_directive(opts)
-      when :stop
-        player.build_stop_directive
-      end
-      @directives << player.directive
+      @resp[:response][:directives] = [
+        case directive.to_sym
+        when :start
+          player.play_directive(params)
+        when :stop
+          player.stop_directive
+        end
+      ]
     end
 
-    # Add reprompt to outputSpeech node
+    # Return JSON version of current response state
     #
-    # @param speech_text [String] output speech
-    # @param ssml [Boolean] is it an SSML speech or not
-    def add_reprompt(speech_text, ssml = false)
-      @reprompt =
-        if ssml
-          { outputSpeech: { type: 'SSML', ssml: check_ssml(speech_text) } }
-        else
-          { outputSpeech: { type: 'PlainText', text: speech_text } }
-        end
-      @reprompt
+    # @return [JSON] response object
+    def json
+      Oj.to_json(@resp)
     end
 
-    # Add card that will be shown in Amazon Alexa app on user smartphone/tablet
+    # Tell something to Alexa user and close conversation.
+    # Method will only add a given speech to response object
     #
-    # @param opts [Hash] hash with card parameters
-    # @return [Hash] card object
-    def add_card(opts = {})
-      opts[:type] = 'Simple' if opts[:type].nil?
-      card = Card.new
-      card.build(opts)
-      @card = card.obj
+    # @param speech [Sring] output speech
+    # @param reprompt_speech [String] output speech if user remains idle
+    # @param ssml [Boolean] is it an SSML speech or not
+    def tell(speech, reprompt_speech = nil, ssml = false)
+      obj = { outputSpeech: build_speech(speech, ssml) }
+      if reprompt_speech
+        obj[:reprompt] = { outputSpeech: build_speech(reprompt_speech, ssml) }
+      end
+      @resp[:response].merge!(obj)
     end
 
-    # Adds a speech to the object, also returns a outputspeech object
+    # Tell something to Alexa user and close conversation.
+    # Method will add given sppech to response object and
+    # immediately return its JSON implementation
     #
-    # @param speech [String] output speech
-    # @param end_session [Boolean] is it a final response, or not
+    # @param speech [Sring] output speech
+    # @param reprompt_speech [String] output speech if user remains idle
     # @param ssml [Boolean] is it an SSML speech or not
-    def say_response(speech, end_session = true, ssml = false)
-      output_speech = add_speech(speech, ssml)
-      { outputSpeech: output_speech, shouldEndSession: end_session }
+    # @return [JSON] ready to use response object
+    def tell!(speech, reprompt_speech = nil, ssml = false)
+      obj = { outputSpeech: build_speech(speech, ssml) }
+      if reprompt_speech
+        obj[:reprompt][:outputSpeech] = build_speech(reprompt_speech, ssml)
+      end
+      @resp[:response].merge!(obj)
+      json
     end
 
-    # Incorporates reprompt in the SDK 2015-05
+    # Ask something from user and wait for further information.
+    # Method will only add given sppech to response object and
+    # set "shouldEndSession" parameter to false
     #
-    # @param speech [String] output speech
-    # @param reprompt_speech [String] output repromt speech
-    # @param end_session [Boolean] is it a final response, or not
-    # @param speech_ssml [Boolean] is it an SSML speech or not
-    # @param reprompt_ssml [Boolean] is it an SSML repromt speech or not
-    def say_response_with_reprompt(speech, reprompt_speech, end_session = true,
-                                   speech_ssml = false, reprompt_ssml = false)
-      output_speech = add_speech(speech, speech_ssml)
-      reprompt_speech = add_reprompt(reprompt_speech, reprompt_ssml)
-      {
-        outputSpeech: output_speech,
-        reprompt: reprompt_speech,
-        shouldEndSession: end_session
-      }
+    # @param speech [Sring] output speech
+    # @param reprompt_speech [String] output speech if user remains idle
+    # @param ssml [Boolean] is it an SSML speech or not
+    def ask(speech, reprompt_speech = nil, ssml = false)
+      @resp[:response][:shouldEndSession] = false
+      tell(speech, reprompt_speech, ssml)
     end
 
-    # Creates a session object. We pretty much only use this in testing.
-    # If it's empty assume user doesn't need session attributes
+    # Ask something from user and wait for further information.
+    # Method will only add given sppech to response object,
+    # set "shouldEndSession" parameter to false and
+    # immediately return response JSON implementation
     #
-    # @return [Hash] user session parameters
-    def build_session
-      @session_attributes = {} if @session_attributes.nil?
-      @session = { sessionAttributes: @session_attributes }
-      @session
+    # @param speech [Sring] output speech
+    # @param reprompt_speech [String] output speech if user remains idle
+    # @param ssml [Boolean] is it an SSML speech or not
+    # @return [JSON] ready to use response object
+    def ask!(speech, reprompt_speech = nil, ssml = false)
+      @resp[:response][:shouldEndSession] = false
+      tell!(speech, reprompt_speech, ssml)
     end
 
-    # The response object (with outputspeech, cards and session end)
-    # Should rename this, but Amazon picked their names.
-    # The only mandatory field is end_session which we default to true.
+    private
+
+    # Add pack of session attributes.
+    # By default all existing session attributes would be overwritten
     #
-    # @param session_end [Boolean] is it a final response, or not
-    # @return [Hash] response parameters
-    def build_response_object(session_end = true)
-      @response = {}
-      @response[:outputSpeech] = @speech unless @speech.nil?
-      @response[:directives] = @directives unless @directives.empty?
-      @response[:card] = @card unless @card.nil?
-      @response[:reprompt] = @reprompt unless session_end && @reprompt.nil?
-      @response[:shouldEndSession] = session_end
-      @response
+    # @param attributes [Hash] pack of session attributes
+    # @param merge [Boolean] merge attributes with existing ones?
+    def session_attributes(attributes, merge)
+      if merge
+        attributes.each { |k, v| add_session_attribute(k, v, true) }
+      else
+        @resp[:sessionAttributes] = {}
+        attributes.each { |k, v| add_session_attribute(k, v, false) }
+      end
     end
 
-    # Builds a response.
-    # Takes the version, response, should_end_session variables
-    # and builds a JSON object
+    # Build speech object
     #
-    # @param session_end [Boolean] is it a final response, or not
-    # @return [JSON] json response for Amazon Alexa
-    def build_response(session_end = true)
-      response_object = build_response_object(session_end)
-      response = {}
-      response[:version] = @version
-      unless @session_attributes.empty?
-        response[:sessionAttributes] = @session_attributes
+    # @param speech [Sring] output speech
+    # @param ssml [Boolean] is it an SSML speech or not
+    # @return [Hash] speech object
+    def build_speech(speech, ssml)
+      obj = {}
+      obj[:type] = ssml ? 'SSML' : 'PlainText'
+      if ssml
+        obj[:ssml] = fix_ssml(speech)
+      else
+        obj[:text] = speech
       end
-      response[:response] = response_object
-      Oj.to_json(response)
+      obj
     end
 
-    # Outputs the version, session object and the response object.
+    # Forced fix of SSML speech - manually check and fix open and close tags
     #
-    # @return [String] version, session object and the response object
-    def to_s
-      "Version => #{@version}, SessionObj => #{@session}, " \
-        "Response => #{@response}"
+    # @param text [String] SSML response speech
+    # @return [String] fixed SSML speech
+    def fix_ssml(text)
+      open_tag = text.strip[0..6]
+      close_tag = text.strip[-8..1]
+      text = open_tag == '<speak>' ? text : "<speak>#{text}"
+      close_tag == '</speak>' ? text : "#{text}</speak>"
     end
 
-    private
-
-    # Check and fix SSML speech
+    # Raise card exception
     #
-    # @param ssml [String] SSML string
-    # @return [String] valid SSML string
-    def check_ssml(ssml)
-      open_tag = ssml.strip[0..6]
-      close_tag = ssml.strip[-8..1]
-      ssml = open_tag == '<speak>' ? ssml : "<speak>#{ssml}"
-      close_tag == '</speak>' ? ssml : "#{ssml}</speak>"
+    # @raise [NoMethodError] if card is not allowed
+    def card_exception
+      raise NoMethodError, 'Card can only be included in response ' \
+                            'to a "LaunchRequest" or "IntentRequest"'
     end
   end
 end

data/lib/alexa_ruby/version.rb

@@ -1,3 +1,3 @@
 module AlexaRuby
-  VERSION = '0.2.0'.freeze
+  VERSION = '1.0.0'.freeze
 end