signalwire-sdk 2.0.0

data/lib/signalwire/prefabs/info_gatherer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWire
+  module Prefabs
+    # Prefab agent for collecting answers to a series of questions.
+    #
+    #   agent = InfoGatherer.new(
+    #     questions: [
+    #       { 'key_name' => 'full_name', 'question_text' => 'What is your full name?' },
+    #       { 'key_name' => 'email',     'question_text' => 'Email?', 'confirm' => true }
+    #     ]
+    #   )
+    #
+    class InfoGatherer
+      attr_reader :questions, :name, :route
+
+      def initialize(questions:, name: 'info_gatherer', route: '/info_gatherer', **_opts)
+        raise ArgumentError, 'questions must be a non-empty Array' unless questions.is_a?(Array) && !questions.empty?
+        questions.each_with_index do |q, i|
+          raise ArgumentError, "Question #{i} missing key_name" unless q['key_name'] || q[:key_name]
+          raise ArgumentError, "Question #{i} missing question_text" unless q['question_text'] || q[:question_text]
+        end
+
+        @questions = questions.map { |q| q.transform_keys(&:to_s) }
+        @name  = name
+        @route = route
+      end
+
+      # Tool definitions this prefab provides.
+      def tools
+        %w[start_questions submit_answer]
+      end
+
+      # Build the prompt sections.
+      def prompt_sections
+        [
+          {
+            'title' => 'Info Gatherer',
+            'body' => 'You need to gather answers to a series of questions. ' \
+                      'Call start_questions to get the first question, then submit_answer after each response.'
+          }
+        ]
+      end
+
+      # Global data for initial state.
+      def global_data
+        {
+          'info_gatherer' => {
+            'questions' => @questions,
+            'question_index' => 0,
+            'answers' => []
+          }
+        }
+      end
+
+      # Tool handler: start_questions
+      def handle_start(_args, _raw_data)
+        q = @questions.first
+        Swaig::FunctionResult.new(
+          "[Question 1 of #{@questions.size}]: \"#{q['question_text']}\""
+        )
+      end
+
+      # Tool handler: submit_answer
+      def handle_submit(args, _raw_data)
+        answer = args['answer'] || ''
+        # In a real implementation, state would be tracked via global_data.
+        Swaig::FunctionResult.new("Answer recorded: #{answer}")
+      end
+    end
+  end
+end

data/lib/signalwire/prefabs/receptionist.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWire
+  module Prefabs
+    # Prefab agent for greeting callers and transferring them to departments.
+    #
+    #   agent = Receptionist.new(
+    #     departments: [
+    #       { 'name' => 'sales',   'description' => 'Product inquiries', 'number' => '+15551235555' },
+    #       { 'name' => 'support', 'description' => 'Technical help',    'number' => '+15551236666' }
+    #     ]
+    #   )
+    #
+    class Receptionist
+      attr_reader :departments, :name, :route, :greeting
+
+      def initialize(departments:, name: 'receptionist', route: '/receptionist',
+                     greeting: 'Thank you for calling. How can I help you today?', **_opts)
+        raise ArgumentError, 'departments must be a non-empty Array' unless departments.is_a?(Array) && !departments.empty?
+        departments.each_with_index do |d, i|
+          d = d.transform_keys(&:to_s)
+          raise ArgumentError, "Department #{i} missing 'name'" unless d['name']
+          raise ArgumentError, "Department #{i} missing 'number'" unless d['number']
+        end
+
+        @departments = departments.map { |d| d.transform_keys(&:to_s) }
+        @greeting    = greeting
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[transfer_to_department collect_caller_info]
+      end
+
+      def prompt_sections
+        bullets = @departments.map { |d| "#{d['name']}: #{d['description'] || d['name']} (#{d['number']})" }
+        [
+          {
+            'title' => 'Receptionist',
+            'body' => @greeting,
+            'bullets' => bullets
+          }
+        ]
+      end
+
+      def global_data
+        {
+          'departments' => @departments,
+          'caller_info' => {}
+        }
+      end
+
+      def handle_transfer(args, _raw_data)
+        dept_name = args['department']
+        dept = @departments.find { |d| d['name'] == dept_name }
+        if dept
+          result = Swaig::FunctionResult.new("Transferring you to #{dept_name} now.")
+          result.connect(dept['number'])
+          result
+        else
+          Swaig::FunctionResult.new("I couldn't find that department. Available departments: #{@departments.map { |d| d['name'] }.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/prefabs/survey.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 SignalWire
+#
+# Licensed under the MIT License.
+# See LICENSE file in the project root for full license information.
+
+require_relative '../swaig/function_result'
+
+module SignalWire
+  module Prefabs
+    # Prefab agent for conducting automated surveys.
+    #
+    #   agent = Survey.new(
+    #     survey_name: 'Customer Satisfaction',
+    #     questions: [
+    #       { 'id' => 'satisfaction', 'text' => 'How satisfied were you?', 'type' => 'rating', 'scale' => 5 }
+    #     ]
+    #   )
+    #
+    class Survey
+      attr_reader :survey_name, :questions, :name, :route
+
+      def initialize(survey_name:, questions:, introduction: nil, conclusion: nil,
+                     name: 'survey', route: '/survey', **_opts)
+        raise ArgumentError, 'questions must be a non-empty Array' unless questions.is_a?(Array) && !questions.empty?
+
+        @survey_name  = survey_name
+        @questions    = questions.map { |q| q.transform_keys(&:to_s) }
+        @introduction = introduction || "Welcome to the #{survey_name}. Let's get started."
+        @conclusion   = conclusion   || 'Thank you for completing the survey!'
+        @name  = name
+        @route = route
+      end
+
+      def tools
+        %w[start_survey submit_survey_answer get_survey_summary]
+      end
+
+      def prompt_sections
+        [
+          {
+            'title' => "Survey: #{@survey_name}",
+            'body' => @introduction,
+            'bullets' => @questions.map { |q| "#{q['id']}: #{q['text']} (#{q['type'] || 'open_ended'})" }
+          }
+        ]
+      end
+
+      def global_data
+        {
+          'survey' => {
+            'name'      => @survey_name,
+            'questions' => @questions,
+            'current'   => 0,
+            'responses' => {}
+          }
+        }
+      end
+
+      def handle_start(_args, _raw_data)
+        q = @questions.first
+        Swaig::FunctionResult.new("#{@introduction}\n\n[Question 1 of #{@questions.size}]: #{q['text']}")
+      end
+
+      def handle_submit(args, _raw_data)
+        Swaig::FunctionResult.new("Response recorded: #{args['answer']}")
+      end
+
+      def handle_summary(_args, _raw_data)
+        Swaig::FunctionResult.new(@conclusion)
+      end
+    end
+  end
+end

data/lib/signalwire/relay/action.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module SignalWire
+  module Relay
+    # Raised when an action times out waiting for completion.
+    class ActionTimeoutError < StandardError; end
+
+    # Base class for async action handles (play, record, detect, etc.).
+    #
+    # Holds a control_id and back-reference to the Call. Resolves when the
+    # server sends a terminal event for this control_id.
+    #
+    # Uses Ruby's Queue for blocking wait semantics.
+    class Action
+      attr_reader :control_id, :call, :result, :completed
+
+      def initialize(call, control_id, terminal_event, terminal_states)
+        @call             = call
+        @control_id       = control_id
+        @terminal_event   = terminal_event
+        @terminal_states  = terminal_states
+        @result           = nil
+        @completed        = false
+        @mutex            = Mutex.new
+        @condition        = ConditionVariable.new
+        @on_completed     = nil
+      end
+
+      # Set the on_completed callback.
+      def on_completed(&block)
+        @on_completed = block
+      end
+
+      # Called internally to set the on_completed callback from options.
+      def _set_on_completed(callback)
+        @on_completed = callback
+      end
+
+      # Called by Call when an event matches our control_id.
+      def _check_event(event)
+        state = event.params['state'] || ''
+        if @terminal_states.include?(state) && !@completed
+          _resolve(event)
+        end
+      end
+
+      # Mark the action as completed and fire the on_completed callback.
+      def _resolve(event)
+        @mutex.synchronize do
+          return if @completed
+
+          @result    = event
+          @completed = true
+          @condition.broadcast
+        end
+        if @on_completed
+          begin
+            @on_completed.call(event)
+          rescue => e
+            $stderr.puts "[RELAY] Error in on_completed callback for #{@control_id}: #{e.message}"
+          end
+        end
+      end
+
+      # Wait for the action to complete. Returns the terminal event.
+      # Raises ActionTimeoutError if timeout is specified and exceeded.
+      def wait(timeout: nil)
+        @mutex.synchronize do
+          return @result if @completed
+
+          if timeout
+            deadline = Time.now + timeout
+            while !@completed
+              remaining = deadline - Time.now
+              if remaining <= 0
+                raise ActionTimeoutError, "Action #{@control_id} timed out after #{timeout}s"
+              end
+              @condition.wait(@mutex, remaining)
+            end
+          else
+            @condition.wait(@mutex) until @completed
+          end
+          @result
+        end
+      end
+
+      def done?
+        @completed
+      end
+
+      alias_method :is_done?, :done?
+    end
+
+    # Handle for an active play operation.
+    class PlayAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_PLAY,
+              [PLAY_STATE_FINISHED, PLAY_STATE_ERROR])
+      end
+
+      def stop
+        @call._execute('play.stop', { 'control_id' => @control_id })
+      end
+
+      def pause
+        @call._execute('play.pause', { 'control_id' => @control_id })
+      end
+
+      def resume
+        @call._execute('play.resume', { 'control_id' => @control_id })
+      end
+
+      def volume(vol)
+        @call._execute('play.volume', { 'control_id' => @control_id, 'volume' => vol })
+      end
+    end
+
+    # Handle for an active record operation.
+    class RecordAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_RECORD,
+              [RECORD_STATE_FINISHED, RECORD_STATE_NO_INPUT])
+      end
+
+      def stop
+        @call._execute('record.stop', { 'control_id' => @control_id })
+      end
+
+      def pause(behavior: nil)
+        params = { 'control_id' => @control_id }
+        params['behavior'] = behavior if behavior
+        @call._execute('record.pause', params)
+      end
+
+      def resume
+        @call._execute('record.resume', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active detect operation.
+    class DetectAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_DETECT, %w[finished error])
+      end
+
+      # Detect delivers results continuously. Resolve on first result or
+      # when finished/error.
+      def _check_event(event)
+        detect = event.params['detect'] || {}
+        state  = event.params['state'] || ''
+        if (!detect.empty? || @terminal_states.include?(state)) && !@completed
+          _resolve(event)
+        end
+      end
+
+      def stop
+        @call._execute('detect.stop', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for play_and_collect or standalone collect.
+    class CollectAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_COLLECT,
+              %w[finished error no_input no_match])
+      end
+
+      # play_and_collect shares a control_id across play and collect
+      # phases. Only resolve on collect events, not play events.
+      def _check_event(event)
+        return unless event.event_type == EVENT_CALL_COLLECT
+
+        result_data = event.params['result'] || {}
+        if !result_data.empty? && !@completed
+          _resolve(event)
+        else
+          super(event)
+        end
+      end
+
+      def stop
+        @call._execute('play_and_collect.stop', { 'control_id' => @control_id })
+      end
+
+      def volume(vol)
+        @call._execute('play_and_collect.volume', {
+          'control_id' => @control_id, 'volume' => vol
+        })
+      end
+
+      def start_input_timers
+        @call._execute('collect.start_input_timers', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for standalone calling.collect (without play).
+    class StandaloneCollectAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_COLLECT,
+              %w[finished error no_input no_match])
+      end
+
+      def _check_event(event)
+        return unless event.event_type == EVENT_CALL_COLLECT
+
+        result_data = event.params['result'] || {}
+        state       = event.params['state'] || ''
+        if (!result_data.empty? || @terminal_states.include?(state)) && !@completed
+          _resolve(event)
+        end
+      end
+
+      def stop
+        @call._execute('collect.stop', { 'control_id' => @control_id })
+      end
+
+      def start_input_timers
+        @call._execute('collect.start_input_timers', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for send_fax or receive_fax.
+    class FaxAction < Action
+      def initialize(call, control_id, method_prefix)
+        super(call, control_id, EVENT_CALL_FAX, %w[finished error])
+        @method_prefix = method_prefix
+      end
+
+      def stop
+        @call._execute("#{@method_prefix}.stop", { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active tap operation.
+    class TapAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_TAP, %w[finished])
+      end
+
+      def stop
+        @call._execute('tap.stop', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active stream operation.
+    class StreamAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_STREAM, %w[finished])
+      end
+
+      def stop
+        @call._execute('stream.stop', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active pay operation.
+    class PayAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_PAY, %w[finished error])
+      end
+
+      def stop
+        @call._execute('pay.stop', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active transcribe operation.
+    class TranscribeAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, EVENT_CALL_TRANSCRIBE, %w[finished])
+      end
+
+      def stop
+        @call._execute('transcribe.stop', { 'control_id' => @control_id })
+      end
+    end
+
+    # Handle for an active AI agent session.
+    class AIAction < Action
+      def initialize(call, control_id)
+        super(call, control_id, 'calling.call.ai', %w[finished error])
+      end
+
+      def stop
+        @call._execute('ai.stop', { 'control_id' => @control_id })
+      end
+    end
+  end
+end