signalwire_agents 1.1.0

data/lib/signalwire_agents/relay/constants.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module Relay
+    # Protocol version sent during signalwire.connect
+    PROTOCOL_VERSION = { 'major' => 2, 'minor' => 0, 'revision' => 0 }.freeze
+    AGENT_STRING = 'signalwire-agents-ruby/1.0'
+
+    # JSON-RPC methods
+    METHOD_SIGNALWIRE_CONNECT    = 'signalwire.connect'
+    METHOD_SIGNALWIRE_EVENT      = 'signalwire.event'
+    METHOD_SIGNALWIRE_PING       = 'signalwire.ping'
+    METHOD_SIGNALWIRE_DISCONNECT = 'signalwire.disconnect'
+    METHOD_SIGNALWIRE_RECEIVE    = 'signalwire.receive'
+    METHOD_SIGNALWIRE_UNRECEIVE  = 'signalwire.unreceive'
+
+    # Authorization state event
+    EVENT_AUTHORIZATION_STATE = 'signalwire.authorization.state'
+
+    # Call states
+    CALL_STATE_CREATED  = 'created'
+    CALL_STATE_RINGING  = 'ringing'
+    CALL_STATE_ANSWERED = 'answered'
+    CALL_STATE_ENDING   = 'ending'
+    CALL_STATE_ENDED    = 'ended'
+
+    CALL_STATES = [
+      CALL_STATE_CREATED,
+      CALL_STATE_RINGING,
+      CALL_STATE_ANSWERED,
+      CALL_STATE_ENDING,
+      CALL_STATE_ENDED
+    ].freeze
+
+    # End reasons
+    END_REASON_HANGUP       = 'hangup'
+    END_REASON_CANCEL       = 'cancel'
+    END_REASON_BUSY         = 'busy'
+    END_REASON_NO_ANSWER    = 'noAnswer'
+    END_REASON_DECLINE      = 'decline'
+    END_REASON_ERROR        = 'error'
+    END_REASON_ABANDONED    = 'abandoned'
+    END_REASON_MAX_DURATION = 'max_duration'
+    END_REASON_NOT_FOUND    = 'not_found'
+
+    # Connect states
+    CONNECT_STATE_CONNECTING   = 'connecting'
+    CONNECT_STATE_CONNECTED    = 'connected'
+    CONNECT_STATE_DISCONNECTED = 'disconnected'
+    CONNECT_STATE_FAILED       = 'failed'
+
+    # Event types — calling
+    EVENT_CALL_STATE      = 'calling.call.state'
+    EVENT_CALL_RECEIVE    = 'calling.call.receive'
+    EVENT_CALL_CONNECT    = 'calling.call.connect'
+    EVENT_CALL_PLAY       = 'calling.call.play'
+    EVENT_CALL_COLLECT    = 'calling.call.collect'
+    EVENT_CALL_RECORD     = 'calling.call.record'
+    EVENT_CALL_DETECT     = 'calling.call.detect'
+    EVENT_CALL_FAX        = 'calling.call.fax'
+    EVENT_CALL_TAP        = 'calling.call.tap'
+    EVENT_CALL_SEND_DIGITS = 'calling.call.send_digits'
+    EVENT_CALL_DIAL       = 'calling.call.dial'
+    EVENT_CALL_REFER      = 'calling.call.refer'
+    EVENT_CALL_DENOISE    = 'calling.call.denoise'
+    EVENT_CALL_PAY        = 'calling.call.pay'
+    EVENT_CALL_QUEUE      = 'calling.call.queue'
+    EVENT_CALL_STREAM     = 'calling.call.stream'
+    EVENT_CALL_ECHO       = 'calling.call.echo'
+    EVENT_CALL_TRANSCRIBE = 'calling.call.transcribe'
+    EVENT_CONFERENCE      = 'calling.conference'
+    EVENT_CALLING_ERROR   = 'calling.error'
+
+    # Messaging event types
+    EVENT_MESSAGING_RECEIVE = 'messaging.receive'
+    EVENT_MESSAGING_STATE   = 'messaging.state'
+
+    # Message states
+    MESSAGE_STATE_QUEUED       = 'queued'
+    MESSAGE_STATE_INITIATED    = 'initiated'
+    MESSAGE_STATE_SENT         = 'sent'
+    MESSAGE_STATE_DELIVERED    = 'delivered'
+    MESSAGE_STATE_UNDELIVERED  = 'undelivered'
+    MESSAGE_STATE_FAILED       = 'failed'
+    MESSAGE_STATE_RECEIVED     = 'received'
+
+    MESSAGE_TERMINAL_STATES = [
+      MESSAGE_STATE_DELIVERED,
+      MESSAGE_STATE_UNDELIVERED,
+      MESSAGE_STATE_FAILED
+    ].freeze
+
+    # Play states
+    PLAY_STATE_PLAYING  = 'playing'
+    PLAY_STATE_PAUSED   = 'paused'
+    PLAY_STATE_FINISHED = 'finished'
+    PLAY_STATE_ERROR    = 'error'
+
+    # Record states
+    RECORD_STATE_RECORDING = 'recording'
+    RECORD_STATE_PAUSED    = 'paused'
+    RECORD_STATE_FINISHED  = 'finished'
+    RECORD_STATE_NO_INPUT  = 'no_input'
+
+    # Detect types
+    DETECT_TYPE_MACHINE = 'machine'
+    DETECT_TYPE_FAX     = 'fax'
+    DETECT_TYPE_DIGIT   = 'digit'
+
+    # Join room states
+    ROOM_STATE_JOINING = 'joining'
+    ROOM_STATE_JOIN    = 'join'
+    ROOM_STATE_LEAVING = 'leaving'
+    ROOM_STATE_LEAVE   = 'leave'
+
+    # Reconnect settings
+    RECONNECT_MIN_DELAY      = 1.0
+    RECONNECT_MAX_DELAY      = 30.0
+    RECONNECT_BACKOFF_FACTOR = 2.0
+
+    # Default host
+    DEFAULT_RELAY_HOST = 'relay.signalwire.com'
+  end
+end

data/lib/signalwire_agents/relay/message.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module Relay
+    # Represents a single SMS/MMS message.
+    #
+    # For outbound messages, use message.wait to block until a terminal state
+    # (delivered, undelivered, failed) is reached.
+    class Message
+      attr_reader :message_id, :context, :direction, :from_number, :to_number,
+                  :body, :media, :segments, :tags, :reason
+      attr_accessor :state
+
+      def initialize(message_id: '', context: '', direction: '', from_number: '',
+                     to_number: '', body: '', media: nil, segments: 0,
+                     state: '', reason: '', tags: nil)
+        @message_id  = message_id
+        @context     = context
+        @direction   = direction
+        @from_number = from_number
+        @to_number   = to_number
+        @body        = body
+        @media       = media || []
+        @segments    = segments
+        @state       = state
+        @reason      = reason
+        @tags        = tags || []
+
+        # Completion tracking
+        @mutex        = Mutex.new
+        @condition    = ConditionVariable.new
+        @done         = false
+        @result       = nil
+        @on_completed = nil
+        @listeners    = []
+      end
+
+      # Set the on_completed callback.
+      def on_completed(&block)
+        @on_completed = block
+      end
+
+      # Set the on_completed callback from options.
+      def _set_on_completed(callback)
+        @on_completed = callback
+      end
+
+      # Register an event listener for state changes.
+      def on_event(&handler)
+        @listeners << handler
+      end
+
+      def done?
+        @done
+      end
+
+      alias_method :is_done?, :done?
+
+      def result
+        @result
+      end
+
+      # Wait for the message to reach a terminal state.
+      # Raises ActionTimeoutError if timeout exceeded.
+      def wait(timeout: nil)
+        @mutex.synchronize do
+          return @result if @done
+
+          if timeout
+            deadline = Time.now + timeout
+            while !@done
+              remaining = deadline - Time.now
+              if remaining <= 0
+                raise ActionTimeoutError, "Message #{@message_id} timed out after #{timeout}s"
+              end
+              @condition.wait(@mutex, remaining)
+            end
+          else
+            @condition.wait(@mutex) until @done
+          end
+          @result
+        end
+      end
+
+      # Handle a messaging.state event for this message.
+      def _dispatch_event(payload)
+        event_params = payload['params'] || {}
+        new_state = event_params['message_state'] || ''
+
+        @state  = new_state unless new_state.empty?
+        @reason = event_params['reason'] if event_params.key?('reason')
+
+        event = Relay.parse_event(payload)
+
+        # Notify listeners
+        @listeners.each do |handler|
+          begin
+            handler.call(event)
+          rescue => e
+            $stderr.puts "[RELAY] Error in message event handler for #{@message_id}: #{e.message}"
+          end
+        end
+
+        # Check terminal state
+        _resolve(event) if MESSAGE_TERMINAL_STATES.include?(new_state)
+      end
+
+      def to_s
+        "Message(id=#{@message_id}, direction=#{@direction}, " \
+          "state=#{@state}, from=#{@from_number}, to=#{@to_number})"
+      end
+
+      def inspect
+        to_s
+      end
+
+      private
+
+      def _resolve(event)
+        @mutex.synchronize do
+          return if @done
+
+          @result = event
+          @done   = true
+          @condition.broadcast
+        end
+        if @on_completed
+          begin
+            @on_completed.call(event)
+          rescue => e
+            $stderr.puts "[RELAY] Error in on_completed callback for message #{@message_id}: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end