call_center 0.0.9 → 0.1.0

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - ree

data/README.md

@@ -12,62 +12,66 @@ Call Center streamlines the process of defining multi-party call workflows in yo
 Usage
 -----
 
-    class Call
-      include CallCenter
+```ruby
+class Call
+  include CallCenter
 
-      call_flow :state, :intial => :incoming do
-        actor :customer do |call, event|
-          "/voice/calls/flow?event=#{event}&actor=customer&call_id=#{call.id}"
-        end
-
-        state :incoming do
-          response do |x|
-            x.Gather :numDigits => '1', :action => customer(:wants_voicemail) do
-              x.Say "Hello World"
-              x.Play some_nice_music, :loop => 100
-            end
-            # <?xml version="1.0" encoding="UTF-8" ?>
-            # <Response>
-            #   <Gather numDigits="1" action="/voice/calls/flow?event=wants_voicemail&actor=customer&call_id=5000">
-            #     <Say>Hello World</Say>
-            #     <Play loop="100">http://some.nice.music.com/1.mp3</Play>
-            #   </Gather>
-            # </Response>
-          end
-
-          event :called, :to => :routing, :if => :agents_available?
-          event :called, :to => :voicemail
-          event :wants_voicemail, :to => :voicemail
-          event :customer_hangs_up, :to => :cancelled
-        end
+  call_flow :state, :intial => :incoming do
+    actor :customer do |call, event|
+      "/voice/calls/flow?event=#{event}&actor=customer&call_id=#{call.id}"
+    end
 
-        state :voicemail do
-          response do |x|
-            x.Say "Please leave a message"
-            x.Record(:action => customer(:voicemail_complete))
-            # <?xml version="1.0" encoding="UTF-8" ?>
-            # <Response>
-            #   <Say>Please leave a message</Say>
-            #   <Record action="/voice/calls/flow?event=voicemail_complete&actor=customer&call_id=5000"/>
-            # </Response>
-          end
-
-          event :voicemail_complete, :to => :voicemail_completed
-          event :customer_hangs_up, :to => :cancelled
+    state :incoming do
+      response do |x|
+        x.Gather :numDigits => '1', :action => customer(:wants_voicemail) do
+          x.Say "Hello World"
+          x.Play some_nice_music, :loop => 100
         end
+        # <?xml version="1.0" encoding="UTF-8" ?>
+        # <Response>
+        #   <Gather numDigits="1" action="/voice/calls/flow?event=wants_voicemail&actor=customer&call_id=5000">
+        #     <Say>Hello World</Say>
+        #     <Play loop="100">http://some.nice.music.com/1.mp3</Play>
+        #   </Gather>
+        # </Response>
+      end
 
-        state :routing do
+      event :called, :to => :routing, :if => :agents_available?
+      event :called, :to => :voicemail
+      event :wants_voicemail, :to => :voicemail
+      event :customer_hangs_up, :to => :cancelled
+    end
 
-        end
+    state :voicemail do
+      response do |x|
+        x.Say "Please leave a message"
+        x.Record(:action => customer(:voicemail_complete))
+        # <?xml version="1.0" encoding="UTF-8" ?>
+        # <Response>
+        #   <Say>Please leave a message</Say>
+        #   <Record action="/voice/calls/flow?event=voicemail_complete&actor=customer&call_id=5000"/>
+        # </Response>
       end
+
+      event :voicemail_complete, :to => :voicemail_completed
+      event :customer_hangs_up, :to => :cancelled
     end
 
+    state :routing do
+
+    end
+  end
+end
+```
+
 Benefits of **CallCenter** is that it's backed by [state_machine](https://github.com/pluginaweek/state_machine). Which means you can interact with events the same you do in `state_machine`.
 
-    @call.called!
-    @call.wants_voicemail!
-    @call.routing?
-    @call.render # See Rendering
+```ruby
+@call.called!
+@call.wants_voicemail!
+@call.routing?
+@call.render # See Rendering
+```
 
 Flow
 ----
@@ -91,9 +95,11 @@ In order to DRY up the callbacks, it is best to have use standardized callback U
 
 By handling this in your controller, you can immediately retrieve the **Call** from persistence, run an event on the call, and return the rendered TwiML. Here's an example:
 
-    def flow
-      render :xml => @call.run(params[:event])
-    end
+```ruby
+def flow
+  render :xml => @call.run(params[:event])
+end
+```
 
 For an in-depth example, take a look at [call_roulette](https://github.com/zendesk/call_roulette).
 
@@ -102,48 +108,56 @@ Rendering
 
 Rendering is your way of interacting with Twilio. Thus, it provides two facilities: access to an XML builder and access to your call.
 
-    state :sales do
-      response do |xml_builder, the_call|
-        xml_builder.Say "This is #{the_call.agent.name}!" # Or agent.name, you can access he call implicitly
-      end
-    end
+```ruby
+state :sales do
+  response do |xml_builder, the_call|
+    xml_builder.Say "This is #{the_call.agent.name}!" # Or agent.name, you can access he call implicitly
+  end
+end
+```
 
 Renders with `@call.render` if the current state is :sales:
 
-    <?xml version="1.0" encoding="UTF-8"?>
-    <Response>
-      <Say>This is Henry!</Say>
-    </Response>
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say>This is Henry!</Say>
+</Response>
+```
 
 Callbacks
 ---------
 
 You have control over what you want to happen before/after state transitions:
 
-    state :voicemail do
-      before(:always) { # Invokes before any transition }
-      before(:always, :uniq => true) { # Invokes before transitions to a different state }
+```ruby
+state :voicemail do
+  before(:always) { # Invokes before any transition }
+  before(:always, :uniq => true) { # Invokes before transitions to a different state }
 
-      after(:always) { # Invokes after any transition }
-      after(:success) { # Invokes after any successful transition }
-      after(:failure) { # Invokes after any failed transition (those not covered in your call flow) }
+  after(:always) { # Invokes after any transition }
+  after(:success) { # Invokes after any successful transition }
+  after(:failure) { # Invokes after any failed transition (those not covered in your call flow) }
 
-      after(:always, :uniq => true) { # Invokes after any transition to a different state }
-      after(:success, :uniq => true) { # Successful unique transitions }
-      after(:failure, :uniq => true) { # Failed unique transitions }
-    end
+  after(:always, :uniq => true) { # Invokes after any transition to a different state }
+  after(:success, :uniq => true) { # Successful unique transitions }
+  after(:failure, :uniq => true) { # Failed unique transitions }
+end
+```
 
 For example,
 
-    state :voicemail do
-      before(:always) { log_start_event }
+```ruby
+state :voicemail do
+  before(:always) { log_start_event }
 
-      after(:always) { log_end_event }
-      after(:failure) { notify_airbrake }
+  after(:always) { log_end_event }
+  after(:failure) { notify_airbrake }
 
-      after(:success, :uniq => true) { notify_browser }
-      after(:failure, :uniq => true) { notify_cleanup_browser }
-    end
+  after(:success, :uniq => true) { notify_browser }
+  after(:failure, :uniq => true) { notify_cleanup_browser }
+end
+```
 
 Motivation
 ----------
@@ -173,9 +187,11 @@ Tools
 
 Should you be interested in what your call center workflow looks like, you can draw.
 
-    Call.state_machines[:status].draw(:font => 'Helvetica Neue')
-    # OR
-    @call.draw_call_flow(:font => 'Helvetica Neue')
+```ruby
+Call.state_machines[:status].draw(:font => 'Helvetica Neue')
+# OR
+@call.draw_call_flow(:font => 'Helvetica Neue')
+```
 
 Future
 ------

data/VERSION

@@ -1 +1 @@
-0.0.9
+0.1.0

data/call_center.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{call_center}
-  s.version = "0.0.9"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Henry Hsu"]
-  s.date = %q{2011-11-09}
+  s.date = %q{2012-06-04}
   s.description = %q{Support for describing call center workflows}
   s.email = %q{hhsu@zendesk.com}
   s.extra_rdoc_files = [
@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
     ".rvmrc",
+    ".travis.yml",
     "Gemfile",
     "Gemfile.lock",
     "Guardfile",
@@ -30,6 +31,7 @@ Gem::Specification.new do |s|
     "call_center.gemspec",
     "init.rb",
     "lib/call_center.rb",
+    "lib/call_center/conditional_stack.rb",
     "lib/call_center/core_ext/object_instance_exec.rb",
     "lib/call_center/deferred_callbacks.rb",
     "lib/call_center/flow_callback.rb",
@@ -42,6 +44,7 @@ Gem::Specification.new do |s|
     "test/call_center_test.rb",
     "test/core_ext_test.rb",
     "test/examples/call.rb",
+    "test/examples/dynamic_transition_call.rb",
     "test/examples/legacy_call.rb",
     "test/examples/multiple_flow_call.rb",
     "test/examples/non_standard_call.rb",

data/lib/call_center.rb

@@ -3,6 +3,7 @@ require 'state_machine'
 require 'call_center/state_machine_ext'
 require 'call_center/flow_callback'
 require 'call_center/deferred_callbacks'
+require 'call_center/conditional_stack'
 
 module CallCenter
   def self.included(base)

data/lib/call_center/conditional_stack.rb

@@ -0,0 +1,51 @@
+module CallCenter
+  class ConditionalStack
+    def initialize
+      @stack = []
+    end
+
+    def <<(obj)
+      @stack << obj
+    end
+
+    def pop
+      @stack.pop
+    end
+
+    def any?
+      @stack.any?
+    end
+
+    def inject(options)
+      current_stack = @stack.dup
+      options.merge(:if => lambda { |model|
+        current_stack.map { |conditional| conditional.evaluate(model) }.all?
+      })
+    end
+
+    class Conditional
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def evaluate(model)
+        result = model.send(@name)
+        if? ? result : !result
+      end
+    end
+
+    class IfConditional < Conditional
+      def if?
+        true
+      end
+    end
+
+    class UnlessConditional < Conditional
+      def if?
+        false
+      end
+    end
+  end
+end

data/lib/call_center/state_machine_ext.rb

@@ -65,6 +65,8 @@ end
 
 # Extension for StateMachine::AlternateMachine to provide render blocks inside a state definition
 class StateMachine::AlternateMachine
+  attr_accessor :flow_stacks
+
   def response(state_name = nil, &blk)
     if @from_state
       @queued_sends << [[:response, @from_state], blk]
@@ -92,4 +94,37 @@ class StateMachine::AlternateMachine
     end
     @queued_sends << [[:flow_actors, name], blk]
   end
+
+  def event_with_blocks(*args, &blk)
+    options = args.extract_options!
+
+    if flow_stacks && flow_stacks.any?
+      options = flow_stacks.inject(options)
+    end
+
+    event_without_blocks(*args.push(options), &blk)
+  end
+
+  alias_method :event_without_blocks, :event
+  alias_method :event, :event_with_blocks
+
+  def flow_if(conditional, &blk)
+    self.flow_stacks ||= CallCenter::ConditionalStack.new
+    begin
+      self.flow_stacks << CallCenter::ConditionalStack::IfConditional.new(conditional)
+      yield if block_given?
+    ensure
+      self.flow_stacks.pop
+    end
+  end
+
+  def flow_unless(conditional, &blk)
+    self.flow_stacks ||= CallCenter::ConditionalStack.new
+    begin
+      self.flow_stacks << CallCenter::ConditionalStack::UnlessConditional.new(conditional)
+      yield if block_given?
+    ensure
+      self.flow_stacks.pop
+    end
+  end
 end

data/test/call_center_test.rb

@@ -6,10 +6,92 @@ require 'test/examples/legacy_call'
 require 'test/examples/call'
 require 'test/examples/non_standard_call'
 require 'test/examples/multiple_flow_call'
+require 'test/examples/dynamic_transition_call'
 
 class CallCenterTest < Test::Unit::TestCase
   include CallCenter::Test::DSL
 
+  context "dynamic transition workflow" do
+    setup do
+      @call = DynamicTransitionCall.new
+      @call.stubs(:notify)
+    end
+
+    context "agents available on phone" do
+      setup do
+        @call.stubs(:agents_available?).returns(true)
+        @call.stubs(:via_phone?).returns(true)
+      end
+
+      should "transition to routing on phone" do
+        @call.incoming_call!
+        assert_equal 'routing_on_phone', @call.state
+      end
+    end
+
+    context "agents available on client" do
+      setup do
+        @call.stubs(:agents_available?).returns(true)
+        @call.stubs(:via_phone?).returns(false)
+      end
+
+      should "transition to routing on client" do
+        @call.incoming_call!
+        assert_equal 'routing_on_client', @call.state
+      end
+    end
+
+    context "no agents available" do
+      setup do
+        @call.stubs(:agents_available?).returns(false)
+        @call.stubs(:via_phone?).returns(true)
+        @call.stubs(:voicemail_full?).returns(false)
+      end
+
+      should "transition to voicemail" do
+        @call.incoming_call!
+        assert_equal 'voicemail', @call.state
+      end
+    end
+
+    context "no agents available when voicemail is full" do
+      setup do
+        @call.stubs(:agents_available?).returns(false)
+        @call.stubs(:via_phone?).returns(false) # Doesn't matter
+        @call.stubs(:voicemail_full?).returns(true)
+      end
+
+      should "transition to voicemail" do
+        @call.incoming_call!
+        assert_equal 'cancelled', @call.state
+      end
+    end
+
+    context "out of area" do
+      setup do
+        @call.state = 'routing_on_client'
+        @call.stubs(:out_of_area?).returns(true)
+      end
+
+      should "transition to cancelled" do
+        @call.picks_up!
+        assert_equal 'cancelled', @call.state
+      end
+    end
+
+    context "not out of area" do
+      setup do
+        @call.state = 'routing_on_client'
+        @call.stubs(:out_of_area?).returns(false)
+      end
+
+      should "transition to in_conference" do
+        @call.picks_up!
+        assert_equal 'in_conference', @call.state
+      end
+    end
+  end
+
   [:call, :legacy_call].each do |call_type|
     context "#{call_type.to_s.gsub('_', ' ')} workflow" do
       setup do

data/test/examples/dynamic_transition_call.rb

@@ -0,0 +1,41 @@
+class DynamicTransitionCall
+  include CallCenter
+  include CommonCallMethods
+
+  call_flow :state, :initial => :initial do
+    state :initial do
+      response do |x|
+        x.Say "Hello World"
+      end
+
+      flow_if :agents_available? do
+        flow_if :via_phone? do
+          event :incoming_call, :to => :routing_on_phone
+        end
+
+        flow_unless :via_phone? do
+          event :incoming_call, :to => :routing_on_client
+        end
+      end
+
+      flow_unless :agents_available? do
+        flow_unless :voicemail_full? do
+          event :incoming_call, :to => :voicemail
+        end
+
+        flow_if :voicemail_full? do
+          event :incoming_call, :to => :cancelled
+        end
+      end
+    end
+
+    state :routing_on_client do
+      flow_if :out_of_area? do
+        event :picks_up, :to => :cancelled
+      end
+      flow_unless :out_of_area? do
+        event :picks_up, :to => :in_conference
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: call_center
 version: !ruby/object:Gem::Version 
-  hash: 13
+  hash: 27
   prerelease: 
   segments: 
   - 0
+  - 1
   - 0
-  - 9
-  version: 0.0.9
+  version: 0.1.0
 platform: ruby
 authors: 
 - Henry Hsu
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-11-09 00:00:00 -08:00
+date: 2012-06-04 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -264,6 +264,7 @@ extra_rdoc_files:
 files: 
 - .document
 - .rvmrc
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - Guardfile
@@ -275,6 +276,7 @@ files:
 - call_center.gemspec
 - init.rb
 - lib/call_center.rb
+- lib/call_center/conditional_stack.rb
 - lib/call_center/core_ext/object_instance_exec.rb
 - lib/call_center/deferred_callbacks.rb
 - lib/call_center/flow_callback.rb
@@ -287,6 +289,7 @@ files:
 - test/call_center_test.rb
 - test/core_ext_test.rb
 - test/examples/call.rb
+- test/examples/dynamic_transition_call.rb
 - test/examples/legacy_call.rb
 - test/examples/multiple_flow_call.rb
 - test/examples/non_standard_call.rb