signalwire_agents 1.1.0

data/lib/signalwire_agents/rest/http_client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'base64'
+
+module SignalWireAgents
+  module REST
+    # Raised when the SignalWire REST API returns a non-2xx response.
+    class SignalWireRestError < StandardError
+      attr_reader :status_code, :body, :url, :method_name
+
+      def initialize(status_code, body, url, method_name = 'GET')
+        @status_code = status_code
+        @body        = body
+        @url         = url
+        @method_name = method_name
+        super("#{method_name} #{url} returned #{status_code}: #{body}")
+      end
+    end
+
+    # Thin wrapper around Net::HTTP with Basic Auth and JSON handling.
+    class HttpClient
+      attr_reader :base_url
+
+      def initialize(project_id, token, space)
+        host = space.include?('.') ? space : "#{space}.signalwire.com"
+        @base_url    = "https://#{host}"
+        @project_id  = project_id
+        @token       = token
+        @auth_header = 'Basic ' + Base64.strict_encode64("#{project_id}:#{token}")
+      end
+
+      def get(path, params = nil)
+        _request('GET', path, params: params)
+      end
+
+      def post(path, body = nil, params: nil)
+        _request('POST', path, body: body, params: params)
+      end
+
+      def put(path, body = nil)
+        _request('PUT', path, body: body)
+      end
+
+      def patch(path, body = nil)
+        _request('PATCH', path, body: body)
+      end
+
+      def delete(path)
+        _request('DELETE', path)
+      end
+
+      private
+
+      def _request(method, path, body: nil, params: nil)
+        uri = URI("#{@base_url}#{path}")
+        if params && !params.empty?
+          uri.query = URI.encode_www_form(params)
+        end
+
+        req = case method
+              when 'GET'    then Net::HTTP::Get.new(uri)
+              when 'POST'   then Net::HTTP::Post.new(uri)
+              when 'PUT'    then Net::HTTP::Put.new(uri)
+              when 'PATCH'  then Net::HTTP::Patch.new(uri)
+              when 'DELETE' then Net::HTTP::Delete.new(uri)
+              else raise ArgumentError, "Unknown HTTP method: #{method}"
+              end
+
+        req['Authorization'] = @auth_header
+        req['Content-Type']  = 'application/json'
+        req['Accept']        = 'application/json'
+        req['User-Agent']    = 'signalwire-agents-ruby-rest/1.0'
+
+        if body && %w[POST PUT PATCH].include?(method)
+          req.body = JSON.generate(body)
+        end
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        response = http.request(req)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          err_body = begin
+                       JSON.parse(response.body)
+                     rescue
+                       response.body
+                     end
+          raise SignalWireRestError.new(response.code.to_i, err_body, path, method)
+        end
+
+        return {} if response.code.to_i == 204 || response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      end
+    end
+
+    # Base for all namespace/resource classes.
+    class BaseResource
+      def initialize(http, base_path)
+        @http      = http
+        @base_path = base_path
+      end
+
+      private
+
+      def _path(*parts)
+        ([@base_path] + parts.map(&:to_s)).join('/')
+      end
+    end
+
+    # Standard CRUD resource with list/create/get/update/delete.
+    class CrudResource < BaseResource
+      def self.update_method
+        @update_method || 'PATCH'
+      end
+
+      def self.update_method=(m)
+        @update_method = m
+      end
+
+      def list(**params)
+        @http.get(@base_path, params.empty? ? nil : params)
+      end
+
+      def create(**kwargs)
+        @http.post(@base_path, kwargs)
+      end
+
+      def get(resource_id)
+        @http.get(_path(resource_id))
+      end
+
+      def update(resource_id, **kwargs)
+        m = self.class.update_method.downcase
+        @http.send(m, _path(resource_id), kwargs)
+      end
+
+      def delete(resource_id)
+        @http.delete(_path(resource_id))
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/namespaces/addresses.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # Address management (no update endpoint).
+      class AddressesResource < BaseResource
+        def initialize(http)
+          super(http, '/api/relay/rest/addresses')
+        end
+
+        def list(**params)  = @http.get(@base_path, params.empty? ? nil : params)
+        def create(**kwargs) = @http.post(@base_path, kwargs)
+        def get(address_id) = @http.get(_path(address_id))
+        def delete(address_id) = @http.delete(_path(address_id))
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/namespaces/calling.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # REST call control -- all 37 commands dispatched via single POST endpoint.
+      class CallingNamespace < BaseResource
+        def initialize(http)
+          super(http, '/api/calling/calls')
+        end
+
+        # Call lifecycle
+        def dial(**params)       = _execute('dial', **params)
+        def update(**params)     = _execute('update', **params)
+
+        def end_call(call_id, **params)
+          _execute('calling.end', call_id: call_id, **params)
+        end
+
+        def transfer(call_id, **params)
+          _execute('calling.transfer', call_id: call_id, **params)
+        end
+
+        def disconnect(call_id, **params)
+          _execute('calling.disconnect', call_id: call_id, **params)
+        end
+
+        # Play
+        def play(call_id, **params)
+          _execute('calling.play', call_id: call_id, **params)
+        end
+
+        def play_pause(call_id, **params)
+          _execute('calling.play.pause', call_id: call_id, **params)
+        end
+
+        def play_resume(call_id, **params)
+          _execute('calling.play.resume', call_id: call_id, **params)
+        end
+
+        def play_stop(call_id, **params)
+          _execute('calling.play.stop', call_id: call_id, **params)
+        end
+
+        def play_volume(call_id, **params)
+          _execute('calling.play.volume', call_id: call_id, **params)
+        end
+
+        # Record
+        def record(call_id, **params)
+          _execute('calling.record', call_id: call_id, **params)
+        end
+
+        def record_pause(call_id, **params)
+          _execute('calling.record.pause', call_id: call_id, **params)
+        end
+
+        def record_resume(call_id, **params)
+          _execute('calling.record.resume', call_id: call_id, **params)
+        end
+
+        def record_stop(call_id, **params)
+          _execute('calling.record.stop', call_id: call_id, **params)
+        end
+
+        # Collect
+        def collect(call_id, **params)
+          _execute('calling.collect', call_id: call_id, **params)
+        end
+
+        def collect_stop(call_id, **params)
+          _execute('calling.collect.stop', call_id: call_id, **params)
+        end
+
+        def collect_start_input_timers(call_id, **params)
+          _execute('calling.collect.start_input_timers', call_id: call_id, **params)
+        end
+
+        # Detect
+        def detect(call_id, **params)
+          _execute('calling.detect', call_id: call_id, **params)
+        end
+
+        def detect_stop(call_id, **params)
+          _execute('calling.detect.stop', call_id: call_id, **params)
+        end
+
+        # Tap
+        def tap(call_id, **params)
+          _execute('calling.tap', call_id: call_id, **params)
+        end
+
+        def tap_stop(call_id, **params)
+          _execute('calling.tap.stop', call_id: call_id, **params)
+        end
+
+        # Stream
+        def stream(call_id, **params)
+          _execute('calling.stream', call_id: call_id, **params)
+        end
+
+        def stream_stop(call_id, **params)
+          _execute('calling.stream.stop', call_id: call_id, **params)
+        end
+
+        # Denoise
+        def denoise(call_id, **params)
+          _execute('calling.denoise', call_id: call_id, **params)
+        end
+
+        def denoise_stop(call_id, **params)
+          _execute('calling.denoise.stop', call_id: call_id, **params)
+        end
+
+        # Transcribe
+        def transcribe(call_id, **params)
+          _execute('calling.transcribe', call_id: call_id, **params)
+        end
+
+        def transcribe_stop(call_id, **params)
+          _execute('calling.transcribe.stop', call_id: call_id, **params)
+        end
+
+        # AI
+        def ai_message(call_id, **params)
+          _execute('calling.ai_message', call_id: call_id, **params)
+        end
+
+        def ai_hold(call_id, **params)
+          _execute('calling.ai_hold', call_id: call_id, **params)
+        end
+
+        def ai_unhold(call_id, **params)
+          _execute('calling.ai_unhold', call_id: call_id, **params)
+        end
+
+        def ai_stop(call_id, **params)
+          _execute('calling.ai.stop', call_id: call_id, **params)
+        end
+
+        # Live transcribe / translate
+        def live_transcribe(call_id, **params)
+          _execute('calling.live_transcribe', call_id: call_id, **params)
+        end
+
+        def live_translate(call_id, **params)
+          _execute('calling.live_translate', call_id: call_id, **params)
+        end
+
+        # Fax
+        def send_fax_stop(call_id, **params)
+          _execute('calling.send_fax.stop', call_id: call_id, **params)
+        end
+
+        def receive_fax_stop(call_id, **params)
+          _execute('calling.receive_fax.stop', call_id: call_id, **params)
+        end
+
+        # SIP
+        def refer(call_id, **params)
+          _execute('calling.refer', call_id: call_id, **params)
+        end
+
+        # Custom events
+        def user_event(call_id, **params)
+          _execute('calling.user_event', call_id: call_id, **params)
+        end
+
+        private
+
+        def _execute(command, call_id: nil, **params)
+          body = { 'command' => command, 'params' => params.transform_keys(&:to_s) }
+          body['id'] = call_id if call_id
+          @http.post(@base_path, body)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/namespaces/chat.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # Chat token generation.
+      class ChatResource < BaseResource
+        def initialize(http)
+          super(http, '/api/chat/tokens')
+        end
+
+        def create_token(**kwargs)
+          @http.post(@base_path, kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/namespaces/compat.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # Compat account/subproject management.
+      class CompatAccounts < BaseResource
+        def initialize(http)
+          super(http, '/api/laml/2010-04-01/Accounts')
+        end
+
+        def list(**params)  = @http.get(@base_path, params.empty? ? nil : params)
+        def create(**kwargs) = @http.post(@base_path, kwargs)
+        def get(sid)         = @http.get(_path(sid))
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+      end
+
+      # Compat call management with recording and stream sub-resources.
+      class CompatCalls < CrudResource
+        def update(sid, **kwargs)
+          @http.post(_path(sid), kwargs)
+        end
+
+        def start_recording(call_sid, **kwargs)
+          @http.post(_path(call_sid, 'Recordings'), kwargs)
+        end
+
+        def update_recording(call_sid, recording_sid, **kwargs)
+          @http.post(_path(call_sid, 'Recordings', recording_sid), kwargs)
+        end
+
+        def start_stream(call_sid, **kwargs)
+          @http.post(_path(call_sid, 'Streams'), kwargs)
+        end
+
+        def stop_stream(call_sid, stream_sid, **kwargs)
+          @http.post(_path(call_sid, 'Streams', stream_sid), kwargs)
+        end
+      end
+
+      # Compat message management with media sub-resources.
+      class CompatMessages < CrudResource
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+
+        def list_media(message_sid, **params)
+          @http.get(_path(message_sid, 'Media'), params.empty? ? nil : params)
+        end
+
+        def get_media(message_sid, media_sid)
+          @http.get(_path(message_sid, 'Media', media_sid))
+        end
+
+        def delete_media(message_sid, media_sid)
+          @http.delete(_path(message_sid, 'Media', media_sid))
+        end
+      end
+
+      # Compat fax management with media sub-resources.
+      class CompatFaxes < CrudResource
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+
+        def list_media(fax_sid, **params)
+          @http.get(_path(fax_sid, 'Media'), params.empty? ? nil : params)
+        end
+
+        def get_media(fax_sid, media_sid)
+          @http.get(_path(fax_sid, 'Media', media_sid))
+        end
+
+        def delete_media(fax_sid, media_sid)
+          @http.delete(_path(fax_sid, 'Media', media_sid))
+        end
+      end
+
+      # Compat conference management.
+      class CompatConferences < BaseResource
+        def list(**params)     = @http.get(@base_path, params.empty? ? nil : params)
+        def get(sid)           = @http.get(_path(sid))
+        def update(sid, **kw)  = @http.post(_path(sid), kw)
+
+        # Participants
+        def list_participants(conference_sid, **params)
+          @http.get(_path(conference_sid, 'Participants'), params.empty? ? nil : params)
+        end
+
+        def get_participant(conference_sid, call_sid)
+          @http.get(_path(conference_sid, 'Participants', call_sid))
+        end
+
+        def update_participant(conference_sid, call_sid, **kwargs)
+          @http.post(_path(conference_sid, 'Participants', call_sid), kwargs)
+        end
+
+        def remove_participant(conference_sid, call_sid)
+          @http.delete(_path(conference_sid, 'Participants', call_sid))
+        end
+
+        # Conference recordings
+        def list_recordings(conference_sid, **params)
+          @http.get(_path(conference_sid, 'Recordings'), params.empty? ? nil : params)
+        end
+
+        def get_recording(conference_sid, recording_sid)
+          @http.get(_path(conference_sid, 'Recordings', recording_sid))
+        end
+
+        def update_recording(conference_sid, recording_sid, **kwargs)
+          @http.post(_path(conference_sid, 'Recordings', recording_sid), kwargs)
+        end
+
+        def delete_recording(conference_sid, recording_sid)
+          @http.delete(_path(conference_sid, 'Recordings', recording_sid))
+        end
+
+        # Conference streams
+        def start_stream(conference_sid, **kwargs)
+          @http.post(_path(conference_sid, 'Streams'), kwargs)
+        end
+
+        def stop_stream(conference_sid, stream_sid, **kwargs)
+          @http.post(_path(conference_sid, 'Streams', stream_sid), kwargs)
+        end
+      end
+
+      # Compat phone number management.
+      class CompatPhoneNumbers < BaseResource
+        def initialize(http, base)
+          super(http, base)
+          @available_base = base.sub('/IncomingPhoneNumbers', '/AvailablePhoneNumbers')
+        end
+
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def purchase(**kwargs) = @http.post(@base_path, kwargs)
+        def get(sid) = @http.get(_path(sid))
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+        def delete(sid) = @http.delete(_path(sid))
+
+        def import_number(**kwargs)
+          path = @base_path.sub('/IncomingPhoneNumbers', '/ImportedPhoneNumbers')
+          @http.post(path, kwargs)
+        end
+
+        def list_available_countries(**params)
+          @http.get(@available_base, params.empty? ? nil : params)
+        end
+
+        def search_local(country, **params)
+          @http.get("#{@available_base}/#{country}/Local", params.empty? ? nil : params)
+        end
+
+        def search_toll_free(country, **params)
+          @http.get("#{@available_base}/#{country}/TollFree", params.empty? ? nil : params)
+        end
+      end
+
+      # Compat application management.
+      class CompatApplications < CrudResource
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+      end
+
+      # Compat cXML/LaML script management.
+      class CompatLamlBins < CrudResource
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+      end
+
+      # Compat queue management with members.
+      class CompatQueues < CrudResource
+        def update(sid, **kwargs) = @http.post(_path(sid), kwargs)
+
+        def list_members(queue_sid, **params)
+          @http.get(_path(queue_sid, 'Members'), params.empty? ? nil : params)
+        end
+
+        def get_member(queue_sid, call_sid)
+          @http.get(_path(queue_sid, 'Members', call_sid))
+        end
+
+        def dequeue_member(queue_sid, call_sid, **kwargs)
+          @http.post(_path(queue_sid, 'Members', call_sid), kwargs)
+        end
+      end
+
+      # Compat recording management.
+      class CompatRecordings < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def get(sid)       = @http.get(_path(sid))
+        def delete(sid)    = @http.delete(_path(sid))
+      end
+
+      # Compat transcription management.
+      class CompatTranscriptions < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def get(sid)       = @http.get(_path(sid))
+        def delete(sid)    = @http.delete(_path(sid))
+      end
+
+      # Compat API token management.
+      class CompatTokens < BaseResource
+        def create(**kwargs) = @http.post(@base_path, kwargs)
+        def update(token_id, **kwargs) = @http.patch(_path(token_id), kwargs)
+        def delete(token_id) = @http.delete(_path(token_id))
+      end
+
+      # Twilio-compatible LAML API namespace.
+      class CompatNamespace
+        attr_reader :accounts, :calls, :messages, :faxes, :conferences,
+                    :phone_numbers, :applications, :laml_bins, :queues,
+                    :recordings, :transcriptions, :tokens
+
+        def initialize(http, account_sid)
+          base = "/api/laml/2010-04-01/Accounts/#{account_sid}"
+
+          @accounts       = CompatAccounts.new(http)
+          @calls          = CompatCalls.new(http, "#{base}/Calls")
+          @messages       = CompatMessages.new(http, "#{base}/Messages")
+          @faxes          = CompatFaxes.new(http, "#{base}/Faxes")
+          @conferences    = CompatConferences.new(http, "#{base}/Conferences")
+          @phone_numbers  = CompatPhoneNumbers.new(http, "#{base}/IncomingPhoneNumbers")
+          @applications   = CompatApplications.new(http, "#{base}/Applications")
+          @laml_bins      = CompatLamlBins.new(http, "#{base}/LamlBins")
+          @queues         = CompatQueues.new(http, "#{base}/Queues")
+          @recordings     = CompatRecordings.new(http, "#{base}/Recordings")
+          @transcriptions = CompatTranscriptions.new(http, "#{base}/Transcriptions")
+          @tokens         = CompatTokens.new(http, "#{base}/tokens")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire_agents/rest/namespaces/datasphere.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SignalWireAgents
+  module REST
+    module Namespaces
+      # Document management with search and chunk operations.
+      class DatasphereDocuments < CrudResource
+        def initialize(http)
+          super(http, '/api/datasphere/documents')
+        end
+
+        def search(**kwargs)
+          @http.post(_path('search'), kwargs)
+        end
+
+        def list_chunks(document_id, **params)
+          @http.get(_path(document_id, 'chunks'), params.empty? ? nil : params)
+        end
+
+        def get_chunk(document_id, chunk_id)
+          @http.get(_path(document_id, 'chunks', chunk_id))
+        end
+
+        def delete_chunk(document_id, chunk_id)
+          @http.delete(_path(document_id, 'chunks', chunk_id))
+        end
+      end
+
+      # Datasphere API namespace.
+      class DatasphereNamespace
+        attr_reader :documents
+
+        def initialize(http)
+          @documents = DatasphereDocuments.new(http)
+        end
+      end
+    end
+  end
+end