signalwire-sdk 2.0.0

data/lib/signalwire/rest/namespaces/fabric.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Standard fabric resource with CRUD + addresses.
+      class FabricResource < CrudResource
+        def list_addresses(resource_id, **params)
+          @http.get(_path(resource_id, 'addresses'), params.empty? ? nil : params)
+        end
+      end
+
+      # Fabric resource that uses PUT for updates.
+      class FabricResourcePUT < FabricResource
+        self.update_method = 'PUT'
+      end
+
+      # Fabric webhook resource that's normally auto-created by
+      # +phone_numbers.set_*_webhook+. Exposed for backwards compatibility.
+      #
+      # The binding model for these resources is on the phone number (see
+      # +phone_numbers.set_swml_webhook+ / +set_cxml_webhook+) -- setting
+      # +call_handler+ on a phone number auto-materializes the webhook
+      # Fabric resource. Calling +create+ directly here produces an orphan
+      # resource that isn't bound to any phone number.
+      class AutoMaterializedWebhook < FabricResource
+        # Subclasses override to advertise the correct helper in the warning.
+        AUTO_HELPER_NAME = 'phone_numbers.set_*_webhook'
+
+        # @deprecated Creating a webhook Fabric resource directly produces an
+        #   orphan that isn't bound to any phone number. Use the matching
+        #   +phone_numbers.set_*_webhook+ helper instead; it updates the
+        #   phone number and the server auto-materializes the resource.
+        #   See porting-sdk's +phone-binding.md+.
+        def create(**kwargs)
+          Kernel.warn(
+            "DEPRECATION: creating a webhook Fabric resource directly produces " \
+            "an orphan not bound to any phone number. Use " \
+            "#{self.class::AUTO_HELPER_NAME} instead; it updates the phone " \
+            "number and the server auto-materializes the resource. " \
+            "See porting-sdk's phone-binding.md.",
+            uplevel: 1
+          )
+          super
+        end
+      end
+
+      # SWML webhooks -- auto-materialized by +phone_numbers.set_swml_webhook+.
+      class SwmlWebhooksResource < AutoMaterializedWebhook
+        AUTO_HELPER_NAME = 'phone_numbers.set_swml_webhook(sid, url: ...)'
+      end
+
+      # cXML webhooks -- auto-materialized by +phone_numbers.set_cxml_webhook+.
+      class CxmlWebhooksResource < AutoMaterializedWebhook
+        AUTO_HELPER_NAME = 'phone_numbers.set_cxml_webhook(sid, url: ...)'
+      end
+
+      # Call flows with version management.
+      class CallFlowsResource < FabricResourcePUT
+        def list_addresses(resource_id, **params)
+          path = @base_path.sub('/call_flows', '/call_flow')
+          @http.get("#{path}/#{resource_id}/addresses", params.empty? ? nil : params)
+        end
+
+        def list_versions(resource_id, **params)
+          path = @base_path.sub('/call_flows', '/call_flow')
+          @http.get("#{path}/#{resource_id}/versions", params.empty? ? nil : params)
+        end
+
+        def deploy_version(resource_id, **kwargs)
+          path = @base_path.sub('/call_flows', '/call_flow')
+          @http.post("#{path}/#{resource_id}/versions", kwargs)
+        end
+      end
+
+      # Conference rooms -- uses singular 'conference_room' for sub-resource paths.
+      class ConferenceRoomsResource < FabricResourcePUT
+        def list_addresses(resource_id, **params)
+          path = @base_path.sub('/conference_rooms', '/conference_room')
+          @http.get("#{path}/#{resource_id}/addresses", params.empty? ? nil : params)
+        end
+      end
+
+      # Subscribers with SIP endpoint management.
+      class SubscribersResource < FabricResourcePUT
+        def list_sip_endpoints(subscriber_id, **params)
+          @http.get(_path(subscriber_id, 'sip_endpoints'), params.empty? ? nil : params)
+        end
+
+        def create_sip_endpoint(subscriber_id, **kwargs)
+          @http.post(_path(subscriber_id, 'sip_endpoints'), kwargs)
+        end
+
+        def get_sip_endpoint(subscriber_id, endpoint_id)
+          @http.get(_path(subscriber_id, 'sip_endpoints', endpoint_id))
+        end
+
+        def update_sip_endpoint(subscriber_id, endpoint_id, **kwargs)
+          @http.patch(_path(subscriber_id, 'sip_endpoints', endpoint_id), kwargs)
+        end
+
+        def delete_sip_endpoint(subscriber_id, endpoint_id)
+          @http.delete(_path(subscriber_id, 'sip_endpoints', endpoint_id))
+        end
+      end
+
+      # cXML applications -- no create method.
+      class CxmlApplicationsResource < FabricResourcePUT
+        def create(**_kwargs)
+          raise NotImplementedError, 'cXML applications cannot be created via this API'
+        end
+      end
+
+      # Generic resource operations across all fabric resource types.
+      class GenericResources < BaseResource
+        def list(**params)
+          @http.get(@base_path, params.empty? ? nil : params)
+        end
+
+        def get(resource_id)
+          @http.get(_path(resource_id))
+        end
+
+        def delete(resource_id)
+          @http.delete(_path(resource_id))
+        end
+
+        def list_addresses(resource_id, **params)
+          @http.get(_path(resource_id, 'addresses'), params.empty? ? nil : params)
+        end
+
+        # @deprecated For the common binding cases use +phone_numbers.set_*+ helpers.
+        #
+        # This endpoint (+POST /api/fabric/resources/{id}/phone_routes+) accepts
+        # only a narrow set of legacy resource types as the attach target. It
+        # *does not work* for +swml_webhook+ / +cxml_webhook+ / +ai_agent+
+        # bindings -- those are configured on the phone number and the Fabric
+        # resource is auto-materialized (see +phone_numbers.set_swml_webhook+
+        # etc.). The authoritative list of accepting resource types lives in
+        # the OpenAPI spec; routing here for those types returns 404 or 422.
+        def assign_phone_route(resource_id, **kwargs)
+          Kernel.warn(
+            "DEPRECATION: assign_phone_route does not bind phone numbers to " \
+            "swml_webhook/cxml_webhook/ai_agent resources -- those are " \
+            "configured via phone_numbers.set_swml_webhook / set_cxml_webhook " \
+            "/ set_ai_agent. This method applies only to a narrow set of " \
+            "legacy resource types. See porting-sdk's phone-binding.md.",
+            uplevel: 1
+          )
+          @http.post(_path(resource_id, 'phone_routes'), kwargs)
+        end
+
+        def assign_domain_application(resource_id, **kwargs)
+          @http.post(_path(resource_id, 'domain_applications'), kwargs)
+        end
+      end
+
+      # Read-only fabric addresses.
+      class FabricAddresses < BaseResource
+        def list(**params)
+          @http.get(@base_path, params.empty? ? nil : params)
+        end
+
+        def get(address_id)
+          @http.get(_path(address_id))
+        end
+      end
+
+      # Subscriber, guest, invite, and embed token creation.
+      class FabricTokens < BaseResource
+        def initialize(http)
+          super(http, '/api/fabric')
+        end
+
+        def create_subscriber_token(**kwargs)
+          @http.post(_path('subscribers', 'tokens'), kwargs)
+        end
+
+        def refresh_subscriber_token(**kwargs)
+          @http.post(_path('subscribers', 'tokens', 'refresh'), kwargs)
+        end
+
+        def create_invite_token(**kwargs)
+          @http.post(_path('subscriber', 'invites'), kwargs)
+        end
+
+        def create_guest_token(**kwargs)
+          @http.post(_path('guests', 'tokens'), kwargs)
+        end
+
+        def create_embed_token(**kwargs)
+          @http.post(_path('embeds', 'tokens'), kwargs)
+        end
+      end
+
+      # Fabric API namespace grouping all resource types.
+      class FabricNamespace
+        attr_reader :swml_scripts, :relay_applications, :call_flows,
+                    :conference_rooms, :freeswitch_connectors, :subscribers,
+                    :sip_endpoints, :cxml_scripts, :cxml_applications,
+                    :swml_webhooks, :ai_agents, :sip_gateways, :cxml_webhooks,
+                    :resources, :addresses, :tokens
+
+        def initialize(http)
+          base = '/api/fabric/resources'
+
+          # PUT-update resources
+          @swml_scripts           = FabricResourcePUT.new(http, "#{base}/swml_scripts")
+          @relay_applications     = FabricResourcePUT.new(http, "#{base}/relay_applications")
+          @call_flows             = CallFlowsResource.new(http, "#{base}/call_flows")
+          @conference_rooms       = ConferenceRoomsResource.new(http, "#{base}/conference_rooms")
+          @freeswitch_connectors  = FabricResourcePUT.new(http, "#{base}/freeswitch_connectors")
+          @subscribers            = SubscribersResource.new(http, "#{base}/subscribers")
+          @sip_endpoints          = FabricResourcePUT.new(http, "#{base}/sip_endpoints")
+          @cxml_scripts           = FabricResourcePUT.new(http, "#{base}/cxml_scripts")
+          @cxml_applications      = CxmlApplicationsResource.new(http, "#{base}/cxml_applications")
+
+          # PATCH-update resources
+          # swml_webhooks and cxml_webhooks are normally auto-materialized by
+          # phone_numbers.set_swml_webhook / set_cxml_webhook. Direct create
+          # still works for backcompat but emits a deprecation warning.
+          @swml_webhooks = SwmlWebhooksResource.new(http, "#{base}/swml_webhooks")
+          @ai_agents     = FabricResource.new(http, "#{base}/ai_agents")
+          @sip_gateways  = FabricResource.new(http, "#{base}/sip_gateways")
+          @cxml_webhooks = CxmlWebhooksResource.new(http, "#{base}/cxml_webhooks")
+
+          # Special resources
+          @resources = GenericResources.new(http, base)
+          @addresses = FabricAddresses.new(http, '/api/fabric/addresses')
+          @tokens    = FabricTokens.new(http)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/imported_numbers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Import externally-hosted phone numbers.
+      class ImportedNumbersResource < BaseResource
+        def initialize(http)
+          super(http, '/api/relay/rest/imported_phone_numbers')
+        end
+
+        def create(**kwargs)
+          @http.post(@base_path, kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/logs.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Message log queries.
+      class MessageLogs < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def get(log_id)    = @http.get(_path(log_id))
+      end
+
+      # Voice log queries.
+      class VoiceLogs < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def get(log_id)    = @http.get(_path(log_id))
+
+        def list_events(log_id, **params)
+          @http.get(_path(log_id, 'events'), params.empty? ? nil : params)
+        end
+      end
+
+      # Fax log queries.
+      class FaxLogs < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+        def get(log_id)    = @http.get(_path(log_id))
+      end
+
+      # Conference log queries.
+      class ConferenceLogs < BaseResource
+        def list(**params) = @http.get(@base_path, params.empty? ? nil : params)
+      end
+
+      # Logs API namespace.
+      class LogsNamespace
+        attr_reader :messages, :voice, :fax, :conferences
+
+        def initialize(http)
+          @messages    = MessageLogs.new(http, '/api/messaging/logs')
+          @voice       = VoiceLogs.new(http, '/api/voice/logs')
+          @fax         = FaxLogs.new(http, '/api/fax/logs')
+          @conferences = ConferenceLogs.new(http, '/api/logs/conferences')
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/lookup.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Phone number lookup (carrier, CNAM).
+      class LookupResource < BaseResource
+        def initialize(http)
+          super(http, '/api/relay/rest/lookup')
+        end
+
+        def phone_number(e164, **params)
+          @http.get(_path('phone_number', e164), params.empty? ? nil : params)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/mfa.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Multi-factor authentication via SMS or phone call.
+      class MfaResource < BaseResource
+        def initialize(http)
+          super(http, '/api/relay/rest/mfa')
+        end
+
+        def sms(**kwargs)
+          @http.post(_path('sms'), kwargs)
+        end
+
+        def call(**kwargs)
+          @http.post(_path('call'), kwargs)
+        end
+
+        def verify(request_id, **kwargs)
+          @http.post(_path(request_id, 'verify'), kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/number_groups.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Number group management with membership operations.
+      class NumberGroupsResource < CrudResource
+        self.update_method = 'PUT'
+
+        def initialize(http)
+          super(http, '/api/relay/rest/number_groups')
+        end
+
+        def list_memberships(group_id, **params)
+          @http.get(_path(group_id, 'number_group_memberships'), params.empty? ? nil : params)
+        end
+
+        def add_membership(group_id, **kwargs)
+          @http.post(_path(group_id, 'number_group_memberships'), kwargs)
+        end
+
+        def get_membership(membership_id)
+          @http.get("/api/relay/rest/number_group_memberships/#{membership_id}")
+        end
+
+        def delete_membership(membership_id)
+          @http.delete("/api/relay/rest/number_group_memberships/#{membership_id}")
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/phone_numbers.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative '../phone_call_handler'
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Phone number management.
+      #
+      # Supports the standard CRUD surface plus typed helpers for binding an
+      # inbound call to a handler (SWML webhook, cXML webhook, AI agent, call
+      # flow, RELAY application/topic). The binding model is: set
+      # +call_handler+ and the handler-specific companion field on the phone
+      # number; the server auto-materializes the matching Fabric resource.
+      # See +SignalWire::REST::PhoneCallHandler+ for the enum, and the
+      # porting-sdk's +phone-binding.md+ for the full model.
+      class PhoneNumbersResource < CrudResource
+        self.update_method = 'PUT'
+
+        def initialize(http)
+          super(http, '/api/relay/rest/phone_numbers')
+        end
+
+        def search(**params)
+          @http.get(_path('search'), params.empty? ? nil : params)
+        end
+
+        # -- Typed binding helpers -----------------------------------------
+        #
+        # Each helper is a one-line wrapper over +update+ with the right
+        # +call_handler+ value and companion field already set. Pass extra
+        # kwargs through for cases the helper doesn't name explicitly (e.g.
+        # +call_fallback_url+ on cXML webhooks).
+
+        # Route inbound calls to an SWML webhook URL.
+        #
+        # Your backend returns an SWML document per call. The server
+        # auto-creates a +swml_webhook+ Fabric resource keyed off this URL.
+        #
+        # @param sid [String] the phone number SID (e.g. +pn-...+)
+        # @param url [String] the SWML webhook URL
+        # @param extra [Hash] additional fields passed to +update+
+        # @return [Hash] the updated phone number representation
+        def set_swml_webhook(sid, url:, **extra)
+          update(
+            sid,
+            call_handler: PhoneCallHandler::RELAY_SCRIPT,
+            call_relay_script_url: url,
+            **extra
+          )
+        end
+
+        # Route inbound calls to a cXML (Twilio-compat / LAML) webhook.
+        #
+        # Despite the wire value +laml_webhooks+ being plural, this creates a
+        # single +cxml_webhook+ Fabric resource. +fallback_url+ is used when
+        # the primary URL fails; +status_callback_url+ receives call status
+        # updates.
+        def set_cxml_webhook(sid, url:, fallback_url: nil, status_callback_url: nil, **extra)
+          body = {
+            call_handler: PhoneCallHandler::LAML_WEBHOOKS,
+            call_request_url: url
+          }
+          body[:call_fallback_url]        = fallback_url        unless fallback_url.nil?
+          body[:call_status_callback_url] = status_callback_url unless status_callback_url.nil?
+          update(sid, **body, **extra)
+        end
+
+        # Route inbound calls to an existing cXML application by ID.
+        def set_cxml_application(sid, application_id:, **extra)
+          update(
+            sid,
+            call_handler: PhoneCallHandler::LAML_APPLICATION,
+            call_laml_application_id: application_id,
+            **extra
+          )
+        end
+
+        # Route inbound calls to an AI Agent Fabric resource by ID.
+        def set_ai_agent(sid, agent_id:, **extra)
+          update(
+            sid,
+            call_handler: PhoneCallHandler::AI_AGENT,
+            call_ai_agent_id: agent_id,
+            **extra
+          )
+        end
+
+        # Route inbound calls to a Call Flow by ID.
+        #
+        # +version+ accepts +"working_copy"+ or +"current_deployed"+ (server
+        # default when omitted).
+        def set_call_flow(sid, flow_id:, version: nil, **extra)
+          body = {
+            call_handler: PhoneCallHandler::CALL_FLOW,
+            call_flow_id: flow_id
+          }
+          body[:call_flow_version] = version unless version.nil?
+          update(sid, **body, **extra)
+        end
+
+        # Route inbound calls to a named RELAY application.
+        def set_relay_application(sid, name:, **extra)
+          update(
+            sid,
+            call_handler: PhoneCallHandler::RELAY_APPLICATION,
+            call_relay_application: name,
+            **extra
+          )
+        end
+
+        # Route inbound calls to a RELAY topic (client subscription).
+        def set_relay_topic(sid, topic:, status_callback_url: nil, **extra)
+          body = {
+            call_handler: PhoneCallHandler::RELAY_TOPIC,
+            call_relay_topic: topic
+          }
+          body[:call_relay_topic_status_callback_url] = status_callback_url unless status_callback_url.nil?
+          update(sid, **body, **extra)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/project.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Project API token management.
+      class ProjectTokens < BaseResource
+        def initialize(http)
+          super(http, '/api/project/tokens')
+        end
+
+        def create(**kwargs) = @http.post(@base_path, kwargs)
+
+        def update(token_id, **kwargs)
+          @http.patch(_path(token_id), kwargs)
+        end
+
+        def delete(token_id)
+          @http.delete(_path(token_id))
+        end
+      end
+
+      # Project API namespace.
+      class ProjectNamespace
+        attr_reader :tokens
+
+        def initialize(http)
+          @tokens = ProjectTokens.new(http)
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/pubsub.rb

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

data/lib/signalwire/rest/namespaces/queues.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Queue management with member operations.
+      class QueuesResource < CrudResource
+        self.update_method = 'PUT'
+
+        def initialize(http)
+          super(http, '/api/relay/rest/queues')
+        end
+
+        def list_members(queue_id, **params)
+          @http.get(_path(queue_id, 'members'), params.empty? ? nil : params)
+        end
+
+        def get_next_member(queue_id)
+          @http.get(_path(queue_id, 'members', 'next'))
+        end
+
+        def get_member(queue_id, member_id)
+          @http.get(_path(queue_id, 'members', member_id))
+        end
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/recordings.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # Recording management (read-only + delete).
+      class RecordingsResource < BaseResource
+        def initialize(http)
+          super(http, '/api/relay/rest/recordings')
+        end
+
+        def list(**params)       = @http.get(@base_path, params.empty? ? nil : params)
+        def get(recording_id)    = @http.get(_path(recording_id))
+        def delete(recording_id) = @http.delete(_path(recording_id))
+      end
+    end
+  end
+end

data/lib/signalwire/rest/namespaces/registry.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SignalWire
+  module REST
+    module Namespaces
+      # 10DLC brand management.
+      class RegistryBrands < BaseResource
+        def list(**params)  = @http.get(@base_path, params.empty? ? nil : params)
+        def create(**kwargs) = @http.post(@base_path, kwargs)
+        def get(brand_id)   = @http.get(_path(brand_id))
+
+        def list_campaigns(brand_id, **params)
+          @http.get(_path(brand_id, 'campaigns'), params.empty? ? nil : params)
+        end
+
+        def create_campaign(brand_id, **kwargs)
+          @http.post(_path(brand_id, 'campaigns'), kwargs)
+        end
+      end
+
+      # 10DLC campaign management.
+      class RegistryCampaigns < BaseResource
+        def get(campaign_id)             = @http.get(_path(campaign_id))
+        def update(campaign_id, **kwargs) = @http.put(_path(campaign_id), kwargs)
+
+        def list_numbers(campaign_id, **params)
+          @http.get(_path(campaign_id, 'numbers'), params.empty? ? nil : params)
+        end
+
+        def list_orders(campaign_id, **params)
+          @http.get(_path(campaign_id, 'orders'), params.empty? ? nil : params)
+        end
+
+        def create_order(campaign_id, **kwargs)
+          @http.post(_path(campaign_id, 'orders'), kwargs)
+        end
+      end
+
+      # 10DLC assignment order management.
+      class RegistryOrders < BaseResource
+        def get(order_id)
+          @http.get(_path(order_id))
+        end
+      end
+
+      # 10DLC number assignment management.
+      class RegistryNumbers < BaseResource
+        def delete(number_id)
+          @http.delete(_path(number_id))
+        end
+      end
+
+      # 10DLC Campaign Registry namespace.
+      class RegistryNamespace
+        attr_reader :brands, :campaigns, :orders, :numbers
+
+        def initialize(http)
+          base = '/api/relay/rest/registry/beta'
+          @brands    = RegistryBrands.new(http, "#{base}/brands")
+          @campaigns = RegistryCampaigns.new(http, "#{base}/campaigns")
+          @orders    = RegistryOrders.new(http, "#{base}/orders")
+          @numbers   = RegistryNumbers.new(http, "#{base}/numbers")
+        end
+      end
+    end
+  end
+end