punchblock 0.4.0

data/lib/punchblock/component/tropo/ask.rb

@@ -0,0 +1,197 @@
+module Punchblock
+  module Component
+    module Tropo
+      class Ask < ComponentNode
+        register :ask, :ask
+
+        ##
+        # Create an ask message
+        #
+        # @param [Hash] options for asking/prompting a specific call
+        # @option options [Choices, Hash] :choices to allow the user to input
+        # @option options [Prompt, Hash, Optional] :prompt to play/read to the caller as the question
+        # @option options [Symbol, Optional] :mode by which to accept input. Can be :speech, :dtmf or :any
+        # @option options [Integer, Optional] :timeout to wait for user input
+        # @option options [Boolean, Optional] :bargein wether or not to allow the caller to begin their response before the prompt finishes
+        # @option options [String, Optional] :recognizer to use for speech recognition
+        # @option options [String, Optional] :terminator by which to signal the end of input
+        # @option options [Float, Optional] :min_confidence with which to consider a response acceptable
+        #
+        # @return [Command::Ask] a formatted Rayo ask command
+        #
+        # @example
+        #    ask :prompt      => {:text => 'Please enter your postal code.', :voice => 'simon'},
+        #        :choices     => {:value => '[5 DIGITS]'},
+        #        :timeout     => 30,
+        #        :recognizer  => 'es-es'
+        #
+        #    returns:
+        #      <ask xmlns="urn:xmpp:tropo:ask:1" timeout="30" recognizer="es-es">
+        #        <prompt voice='simon'>Please enter your postal code.</prompt>
+        #        <choices content-type="application/grammar+voxeo">[5 DIGITS]</choices>
+        #      </ask>
+        #
+        def self.new(options = {})
+          super().tap do |new_node|
+            options.each_pair { |k,v| new_node.send :"#{k}=", v }
+          end
+        end
+
+        ##
+        # @return [Boolean] wether or not to allow the caller to begin their response before the prompt finishes
+        #
+        def bargein
+          read_attr(:bargein) == "true"
+        end
+
+        ##
+        # @param [Boolean] bargein wether or not to allow the caller to begin their response before the prompt finishes
+        #
+        def bargein=(bargein)
+          write_attr :bargein, bargein.to_s
+        end
+
+        ##
+        # @return [Float] Confidence with which to consider a response acceptable
+        #
+        def min_confidence
+          read_attr 'min-confidence', :to_f
+        end
+
+        ##
+        # @param [Float] min_confidence with which to consider a response acceptable
+        #
+        def min_confidence=(min_confidence)
+          write_attr 'min-confidence', min_confidence
+        end
+
+        ##
+        # @return [Symbol] mode by which to accept input. Can be :speech, :dtmf or :any
+        #
+        def mode
+          read_attr :mode, :to_sym
+        end
+
+        ##
+        # @param [Symbol] mode by which to accept input. Can be :speech, :dtmf or :any
+        #
+        def mode=(mode)
+          write_attr :mode, mode
+        end
+
+        ##
+        # @return [String] recognizer to use for speech recognition
+        #
+        def recognizer
+          read_attr :recognizer
+        end
+
+        ##
+        # @param [String] recognizer to use for speech recognition
+        #
+        def recognizer=(recognizer)
+          write_attr :recognizer, recognizer
+        end
+
+        ##
+        # @return [String] terminator by which to signal the end of input
+        #
+        def terminator
+          read_attr :terminator
+        end
+
+        ##
+        # @param [String] terminator by which to signal the end of input
+        #
+        def terminator=(terminator)
+          write_attr :terminator, terminator
+        end
+
+        ##
+        # @return [Integer] timeout to wait for user input
+        #
+        def timeout
+          read_attr :timeout, :to_i
+        end
+
+        ##
+        # @param [Integer] timeout to wait for user input
+        #
+        def timeout=(timeout)
+          write_attr :timeout, timeout
+        end
+
+        ##
+        # @return [Prompt] the prompt by which to introduce the question
+        #
+        def prompt
+          Prompt.new find_first('//ns:prompt', :ns => self.registered_ns)
+        end
+
+        ##
+        # @param [Hash] p
+        # @option p [String] :text to read the caller via TTS as the question
+        # @option p [String] :voice to use for speech synthesis
+        #
+        def prompt=(p)
+          remove_children :prompt
+          p = Prompt.new(p) unless p.is_a?(Prompt)
+          self << p
+        end
+
+        class Prompt < MediaNode
+          register :prompt, :ask
+        end
+
+        ##
+        # @return [Choices] the choices available
+        #
+        def choices
+          Choices.new find_first('ns:choices', :ns => self.class.registered_ns)
+        end
+
+        ##
+        # @param [Hash] choices
+        # @option choices [String] :content_type
+        # @option choices [String] :value the choices available
+        #
+        def choices=(choices)
+          remove_children :choices
+          choices = Choices.new(choices) unless choices.is_a?(Choices)
+          self << choices
+        end
+
+        def inspect_attributes # :nodoc:
+          [:bargein, :min_confidence, :mode, :recognizer, :terminator, :timeout, :prompt, :choices] + super
+        end
+
+        class Choices < Input::Grammar
+          ##
+          # @param [Hash] options
+          # @option options [String] :content_type
+          # @option options [String] :value the choices available
+          #
+          def self.new(options = {})
+            super(options).tap do |new_node|
+              new_node.name = 'choices'
+            end
+          end
+        end # Choices
+
+        class Complete
+          class Success < Input::Complete::Success
+            register :success, :ask_complete
+          end
+
+          class NoMatch < Input::Complete::NoMatch
+            register :nomatch, :ask_complete
+          end
+
+          class NoInput < Input::Complete::NoInput
+            register :noinput, :ask_complete
+          end
+        end # Complete
+      end # Ask
+    end # Tropo
+  end # Command
+end # Punchblock

data/lib/punchblock/component/tropo/conference.rb

@@ -0,0 +1,328 @@
+module Punchblock
+  module Component
+    module Tropo
+      class Conference < ComponentNode
+        register :conference, :conference
+
+        ##
+        # Creates an Rayo conference command
+        #
+        # @param [Hash] options
+        # @option options [String] :name room id to with which to create or join the conference
+        # @option options [Announcement, Hash, Optional] :announcement to play on entry
+        # @option options [Music, Hash, Optional] :music to play to the participant when no moderator is present
+        # @option options [Boolean, Optional] :mute If set to true, the user will be muted in the conference
+        # @option options [Boolean, Optional] :moderator Whether or not the conference should be moderated
+        # @option options [Boolean, Optional] :tone_passthrough Identifies whether or not conference members can hear the tone generated when a a key on the phone is pressed.
+        # @option options [String, Optional] :terminator This is the touch-tone key (also known as "DTMF digit") used to exit the conference.
+        #
+        # @return [Command::Conference] a formatted Rayo conference command
+        #
+        # @example
+        #    conference :name => 'the_one_true_conference', :terminator => '#'
+        #
+        #    returns:
+        #      <conference xmlns="urn:xmpp:tropo:conference:1" name="the_one_true_conference" terminator="#"/>
+        def self.new(options = {})
+          super().tap do |new_node|
+            options.each_pair do |k,v|
+              new_node.send :"#{k}=", v
+            end
+          end
+        end
+
+        ##
+        # @return [String] the name of the conference
+        #
+        def name
+          read_attr :name
+        end
+
+        ##
+        # @param [String] name of the conference
+        #
+        def name=(name)
+          write_attr :name, name
+        end
+
+        ##
+        # @return [Boolean] If set to true, the user will be muted in the conference.
+        #
+        def mute
+          read_attr(:mute) == 'true'
+        end
+
+        ##
+        # @param [Boolean] mute If set to true, the user will be muted in the conference
+        #
+        def mute=(mute)
+          write_attr :mute, mute.to_s
+        end
+
+        ##
+        # @return [String] This is the touch-tone key (also known as "DTMF digit") used to exit the conference.
+        #
+        def terminator
+          read_attr :terminator
+        end
+
+        ##
+        # @param [String] terminator This is the touch-tone key (also known as "DTMF digit") used to exit the conference.
+        #
+        def terminator=(terminator)
+          write_attr :terminator, terminator
+        end
+
+        ##
+        # @return [Boolean] Identifies whether or not conference members can hear the tone generated when a a key on the phone is pressed.
+        #
+        def tone_passthrough
+          read_attr('tone-passthrough') == 'true'
+        end
+
+        ##
+        # @param [Boolean] tone_passthrough Identifies whether or not conference members can hear the tone generated when a a key on the phone is pressed.
+        #
+        def tone_passthrough=(tone_passthrough)
+          write_attr 'tone-passthrough', tone_passthrough.to_s
+        end
+
+        ##
+        # @return [Boolean] Whether or not the conference should be moderated
+        #
+        def moderator
+          read_attr(:moderator) == 'true'
+        end
+
+        ##
+        # @param [Boolean] moderator Whether or not the conference should be moderated
+        #
+        def moderator=(moderator)
+          write_attr :moderator, moderator.to_s
+        end
+
+        ##
+        # @return [Announcement] the announcement to play to the participant on entry
+        #
+        def announcement
+          node = find_first '//ns:announcement', :ns => self.registered_ns
+          Announcement.new node if node
+        end
+
+        ##
+        # @param [Announcement, Hash] ann
+        # @option ann [String] :text Text to speak to the caller as an announcement
+        # @option ann [String] :url URL to play to the caller as an announcement
+        #
+        def announcement=(ann)
+          ann = Announcement.new(ann) unless ann.is_a? Announcement
+          self << ann
+        end
+
+        ##
+        # @return [Music] the music to play to the participant on entry if there's no moderator present
+        #
+        def music
+          node = find_first '//ns:music', :ns => self.registered_ns
+          Music.new node if node
+        end
+
+        ##
+        # @param [Music, Hash] m
+        # @option m [String] :text Text to speak to the caller
+        # @option m [String] :url URL to play to the caller
+        #
+        def music=(m)
+          m = Music.new(m) unless m.is_a? Announcement
+          self << m
+        end
+
+        class Announcement < MediaNode
+          register :announcement, :conference
+        end
+
+        class Music < MediaNode
+          register :music, :conference
+        end
+
+        def inspect_attributes # :nodoc:
+          [:name, :mute, :terminator, :tone_passthrough, :moderator, :announcement, :music] + super
+        end
+
+        def transition_state!(event)
+          super
+          case event
+          when OnHold
+            onhold!
+          when OffHold
+            offhold!
+          end
+        end
+
+        state_machine :state do
+          after_transition :new => :requested do |command, transition|
+            command.mute ? command.muted! : command.unmuted!
+          end
+        end
+
+        state_machine :mute_status, :initial => :unknown_mute do
+          event :muted do
+            transition [:unmuted, :unknown_mute] => :muted
+          end
+
+          event :unmuted do
+            transition [:muted, :unknown_mute] => :unmuted
+          end
+        end
+
+        state_machine :hold_status, :initial => :unknown_hold do
+          event :onhold do
+            transition [:offhold, :unknown_hold] => :onhold
+          end
+
+          event :offhold do
+            transition [:onhold, :unknown_hold] => :offhold
+          end
+        end
+
+        class OnHold < Event
+          register :'on-hold', :conference
+        end
+
+        class OffHold < Event
+          register :'off-hold', :conference
+        end
+
+        module ActiveSpeaker
+          def speaking_call_id
+            read_attr :'call-id'
+          end
+        end
+
+        class Speaking < Event
+          register :speaking, :conference
+          include ActiveSpeaker
+        end
+
+        class FinishedSpeaking < Event
+          register :'finished-speaking', :conference
+          include ActiveSpeaker
+        end
+
+        class Complete
+          class Kick < Event::Complete::Reason
+            register :kick, :conference_complete
+
+            alias :details :text
+
+            def inspect_attributes # :nodoc:
+              [:details] + super
+            end
+          end
+
+          class Terminator < Event::Complete::Reason
+            register :terminator, :conference_complete
+          end
+        end
+
+        ##
+        # Create an Rayo mute message for the current conference
+        #
+        # @return [Command::Conference::Mute] an Rayo mute message
+        #
+        # @example
+        #    conf_obj.mute_action.to_xml
+        #
+        #    returns:
+        #      <mute xmlns="urn:xmpp:tropo:conference:1"/>
+        #
+        def mute_action
+          Command::Mute.new :component_id => component_id, :call_id => call_id
+        end
+
+        ##
+        # Sends an Rayo mute message for the current Conference
+        #
+        def mute!
+          raise InvalidActionError, "Cannot mute a Conference that is already muted" if muted?
+          mute_action.tap do |action|
+            result = write_action action
+            muted! if result
+          end
+        end
+
+        ##
+        # Create an Rayo unmute message for the current conference
+        #
+        # @return [Command::Conference::Unmute] an Rayo unmute message
+        #
+        # @example
+        #    conf_obj.unmute_action.to_xml
+        #
+        #    returns:
+        #      <unmute xmlns="urn:xmpp:tropo:conference:1"/>
+        #
+        def unmute_action
+          Command::Unmute.new :component_id => component_id, :call_id => call_id
+        end
+
+        ##
+        # Sends an Rayo unmute message for the current Conference
+        #
+        def unmute!
+          raise InvalidActionError, "Cannot unmute a Conference that is not muted" unless muted?
+          unmute_action.tap do |action|
+            result = write_action action
+            unmuted! if result
+          end
+        end
+
+        ##
+        # Create an Rayo conference kick message
+        #
+        # @param [Hash] options
+        # @option options [String] :message to explain the reason for kicking
+        #
+        # @return [Command::Conference::Kick] an Rayo conference kick message
+        #
+        # @example
+        #    conf_obj.kick_action(:message => 'bye!').to_xml
+        #
+        #    returns:
+        #      <kick xmlns="urn:xmpp:tropo:conference:1">bye!</kick>
+        #
+        def kick_action(options = {})
+          Kick.new options.merge(:component_id => component_id, :call_id => call_id)
+        end
+
+        ##
+        # Sends an Rayo kick message for the current Conference
+        #
+        # @param [Hash] options
+        # @option options [String] :message to explain the reason for kicking
+        #
+        def kick!(options = {})
+          raise InvalidActionError, "Cannot kick a Conference that is not executing" unless executing?
+          kick_action.tap do |action|
+            write_action action
+          end
+        end
+
+        class Kick < CommandNode # :nodoc:
+          register :kick, :conference
+
+          def self.new(options = {})
+            super.tap do |new_node|
+              new_node.message = options[:message]
+            end
+          end
+
+          def message=(m)
+            self << m if m
+          end
+        end
+
+      end # Conference
+    end # Tropo
+  end # Command
+end # Punchblock

data/lib/punchblock/component/tropo/say.rb

@@ -0,0 +1,113 @@
+module Punchblock
+  module Component
+    module Tropo
+      class Say < ComponentNode
+        register :say, :say
+
+        include MediaContainer
+
+        ##
+        # Creates an Rayo Say command
+        #
+        # @param [Hash] options
+        # @option options [String, Optional] :text to speak back
+        # @option options [String, Optional] :voice with which to render TTS
+        # @option options [String, Optional] :ssml document to render TTS
+        #
+        # @return [Command::Say] an Rayo "say" command
+        #
+        # @example
+        #   say :text => 'Hello brown cow.'
+        #
+        #   returns:
+        #     <say xmlns="urn:xmpp:tropo:say:1">Hello brown cow.</say>
+        #
+        def self.new(options = {})
+          super().tap do |new_node|
+            case options
+            when Hash
+              new_node.voice = options.delete(:voice) if options[:voice]
+              new_node.ssml = options.delete(:ssml) if options[:ssml]
+              new_node << options.delete(:text) if options[:text]
+            when Nokogiri::XML::Element
+              new_node.inherit options
+            end
+          end
+        end
+
+        state_machine :state do
+          event :paused do
+            transition :executing => :paused
+          end
+
+          event :resumed do
+            transition :paused => :executing
+          end
+        end
+
+        # Pauses a running Say
+        #
+        # @return [Command::Say::Pause] an Rayo pause message for the current Say
+        #
+        # @example
+        #    say_obj.pause_action.to_xml
+        #
+        #    returns:
+        #      <pause xmlns="urn:xmpp:tropo:say:1"/>
+        def pause_action
+          Pause.new :component_id => component_id, :call_id => call_id
+        end
+
+        ##
+        # Sends an Rayo pause message for the current Say
+        #
+        def pause!
+          raise InvalidActionError, "Cannot pause a Say that is not executing" unless executing?
+          pause_action.tap do |action|
+            result = write_action action
+            paused! if result
+          end
+        end
+
+        ##
+        # Create an Rayo resume message for the current Say
+        #
+        # @return [Command::Say::Resume] an Rayo resume message
+        #
+        # @example
+        #    say_obj.resume_action.to_xml
+        #
+        #    returns:
+        #      <resume xmlns="urn:xmpp:tropo:say:1"/>
+        def resume_action
+          Resume.new :component_id => component_id, :call_id => call_id
+        end
+
+        ##
+        # Sends an Rayo resume message for the current Say
+        #
+        def resume!
+          raise InvalidActionError, "Cannot resume a Say that is not paused." unless paused?
+          resume_action.tap do |action|
+            result = write_action action
+            resumed! if result
+          end
+        end
+
+        class Pause < CommandNode # :nodoc:
+          register :pause, :say
+        end
+
+        class Resume < CommandNode # :nodoc:
+          register :resume, :say
+        end
+
+        class Complete
+          class Success < Event::Complete::Reason
+            register :success, :say_complete
+          end
+        end
+      end # Say
+    end # Tropo
+  end # Command
+end # Punchblock