surge_api 0.18.0 → 0.20.0

data/rbi/surge_api/models/phone_number_list_available_numbers_response.rbi

@@ -0,0 +1,139 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class PhoneNumberListAvailableNumbersResponse < SurgeAPI::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse,
+            SurgeAPI::Internal::AnyHash
+          )
+        end
+
+      # ISO country code for the phone number
+      sig do
+        returns(
+          SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::TaggedSymbol
+        )
+      end
+      attr_accessor :country
+
+      # The phone number in E.164 format
+      sig { returns(String) }
+      attr_accessor :number
+
+      # Whether the phone number is local or toll-free
+      sig do
+        returns(
+          SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::TaggedSymbol
+        )
+      end
+      attr_accessor :type
+
+      # A phone number available for purchase from Surge inventory
+      sig do
+        params(
+          country:
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::OrSymbol,
+          number: String,
+          type:
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::OrSymbol
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # ISO country code for the phone number
+        country:,
+        # The phone number in E.164 format
+        number:,
+        # Whether the phone number is local or toll-free
+        type:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            country:
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::TaggedSymbol,
+            number: String,
+            type:
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::TaggedSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # ISO country code for the phone number
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        US =
+          T.let(
+            :US,
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::TaggedSymbol
+          )
+        CA =
+          T.let(
+            :CA,
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Country::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+
+      # Whether the phone number is local or toll-free
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        LOCAL =
+          T.let(
+            :local,
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::TaggedSymbol
+          )
+        TOLL_FREE =
+          T.let(
+            :toll_free,
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::Type::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/surge_api/models/phone_number_purchase_params.rbi

@@ -50,6 +50,14 @@ module SurgeAPI
       sig { params(name: String).void }
       attr_writer :name
 
+      # The exact phone number to purchase in E.164 format. When provided, all other
+      # search parameters are ignored.
+      sig { returns(T.nilable(String)) }
+      attr_reader :phone_number
+
+      sig { params(phone_number: String).void }
+      attr_writer :phone_number
+
       # Whether the phone number is local or toll-free. Can be omitted if area_code or
       # latitude/longitude are provided.
       sig do
@@ -69,6 +77,7 @@ module SurgeAPI
           latitude: Float,
           longitude: Float,
           name: String,
+          phone_number: String,
           type: SurgeAPI::PhoneNumberPurchaseParams::Type::OrSymbol,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
@@ -88,6 +97,9 @@ module SurgeAPI
         # A human-readable name for the phone number. If not provided, defaults to the
         # formatted phone number.
         name: nil,
+        # The exact phone number to purchase in E.164 format. When provided, all other
+        # search parameters are ignored.
+        phone_number: nil,
         # Whether the phone number is local or toll-free. Can be omitted if area_code or
         # latitude/longitude are provided.
         type: nil,
@@ -103,6 +115,7 @@ module SurgeAPI
             latitude: Float,
             longitude: Float,
             name: String,
+            phone_number: String,
             type: SurgeAPI::PhoneNumberPurchaseParams::Type::OrSymbol,
             request_options: SurgeAPI::RequestOptions
           }

data/rbi/surge_api/models/phone_number_retrieve_params.rbi

@@ -0,0 +1,43 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class PhoneNumberRetrieveParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            SurgeAPI::PhoneNumberRetrieveParams,
+            SurgeAPI::Internal::AnyHash
+          )
+        end
+
+      # The ID of the phone number to retrieve.
+      sig { returns(String) }
+      attr_accessor :id
+
+      sig do
+        params(
+          id: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The ID of the phone number to retrieve.
+        id:,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          { id: String, request_options: SurgeAPI::RequestOptions }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/surge_api/models/recording_completed_webhook_event.rbi

@@ -161,6 +161,18 @@ module SurgeAPI
           end
           attr_accessor :status
 
+          # The E.164 phone number of the caller
+          sig { returns(T.nilable(String)) }
+          attr_accessor :from
+
+          # The Surge phone number ID (e.g. pn\_...)
+          sig { returns(T.nilable(String)) }
+          attr_accessor :phone_number_id
+
+          # The E.164 phone number of the callee
+          sig { returns(T.nilable(String)) }
+          attr_accessor :to
+
           # The call that produced this recording
           sig do
             params(
@@ -169,7 +181,10 @@ module SurgeAPI
               duration: Integer,
               initiated_at: Time,
               status:
-                SurgeAPI::RecordingCompletedWebhookEvent::Data::Call::Status::OrSymbol
+                SurgeAPI::RecordingCompletedWebhookEvent::Data::Call::Status::OrSymbol,
+              from: T.nilable(String),
+              phone_number_id: T.nilable(String),
+              to: T.nilable(String)
             ).returns(T.attached_class)
           end
           def self.new(
@@ -182,7 +197,13 @@ module SurgeAPI
             # When the call was initiated
             initiated_at:,
             # The status of the call
-            status:
+            status:,
+            # The E.164 phone number of the caller
+            from: nil,
+            # The Surge phone number ID (e.g. pn\_...)
+            phone_number_id: nil,
+            # The E.164 phone number of the callee
+            to: nil
           )
           end
 
@@ -194,7 +215,10 @@ module SurgeAPI
                 duration: Integer,
                 initiated_at: Time,
                 status:
-                  SurgeAPI::RecordingCompletedWebhookEvent::Data::Call::Status::TaggedSymbol
+                  SurgeAPI::RecordingCompletedWebhookEvent::Data::Call::Status::TaggedSymbol,
+                from: T.nilable(String),
+                phone_number_id: T.nilable(String),
+                to: T.nilable(String)
               }
             )
           end

data/rbi/surge_api/models/voicemail_received_webhook_event.rbi

@@ -167,6 +167,18 @@ module SurgeAPI
           end
           attr_accessor :status
 
+          # The E.164 phone number of the caller
+          sig { returns(T.nilable(String)) }
+          attr_accessor :from
+
+          # The Surge phone number ID (e.g. pn\_...)
+          sig { returns(T.nilable(String)) }
+          attr_accessor :phone_number_id
+
+          # The E.164 phone number of the callee
+          sig { returns(T.nilable(String)) }
+          attr_accessor :to
+
           # The call that resulted in this voicemail
           sig do
             params(
@@ -175,7 +187,10 @@ module SurgeAPI
               duration: Integer,
               initiated_at: Time,
               status:
-                SurgeAPI::VoicemailReceivedWebhookEvent::Data::Call::Status::OrSymbol
+                SurgeAPI::VoicemailReceivedWebhookEvent::Data::Call::Status::OrSymbol,
+              from: T.nilable(String),
+              phone_number_id: T.nilable(String),
+              to: T.nilable(String)
             ).returns(T.attached_class)
           end
           def self.new(
@@ -188,7 +203,13 @@ module SurgeAPI
             # When the call was initiated
             initiated_at:,
             # The status of the call
-            status:
+            status:,
+            # The E.164 phone number of the caller
+            from: nil,
+            # The Surge phone number ID (e.g. pn\_...)
+            phone_number_id: nil,
+            # The E.164 phone number of the callee
+            to: nil
           )
           end
 
@@ -200,7 +221,10 @@ module SurgeAPI
                 duration: Integer,
                 initiated_at: Time,
                 status:
-                  SurgeAPI::VoicemailReceivedWebhookEvent::Data::Call::Status::TaggedSymbol
+                  SurgeAPI::VoicemailReceivedWebhookEvent::Data::Call::Status::TaggedSymbol,
+                from: T.nilable(String),
+                phone_number_id: T.nilable(String),
+                to: T.nilable(String)
               }
             )
           end

data/rbi/surge_api/models.rbi

@@ -89,12 +89,17 @@ module SurgeAPI
   PhoneNumberAttachedToCampaignWebhookEvent =
     SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent
 
+  PhoneNumberListAvailableNumbersParams =
+    SurgeAPI::Models::PhoneNumberListAvailableNumbersParams
+
   PhoneNumberListParams = SurgeAPI::Models::PhoneNumberListParams
 
   PhoneNumberPurchaseParams = SurgeAPI::Models::PhoneNumberPurchaseParams
 
   PhoneNumberReleaseParams = SurgeAPI::Models::PhoneNumberReleaseParams
 
+  PhoneNumberRetrieveParams = SurgeAPI::Models::PhoneNumberRetrieveParams
+
   PhoneNumberUpdateParams = SurgeAPI::Models::PhoneNumberUpdateParams
 
   RecordingCompletedWebhookEvent =

data/rbi/surge_api/resources/phone_numbers.rbi

@@ -3,6 +3,20 @@
 module SurgeAPI
   module Resources
     class PhoneNumbers
+      # Retrieves a PhoneNumber object.
+      sig do
+        params(
+          id: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::PhoneNumber)
+      end
+      def retrieve(
+        # The ID of the phone number to retrieve.
+        id,
+        request_options: {}
+      )
+      end
+
       # Updates a phone number's details.
       sig do
         params(
@@ -44,8 +58,47 @@ module SurgeAPI
       )
       end
 
-      # Purchase a new phone number for the account. You can specify search criteria or
-      # let the system select a random number.
+      # Browse purchasable phone numbers from Surge inventory before buying.
+      #
+      # Pagination cursors are always null for now.
+      sig do
+        params(
+          account_id: String,
+          type: SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::OrSymbol,
+          after: String,
+          area_code: String,
+          before: String,
+          country:
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::OrSymbol,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(
+          SurgeAPI::Internal::Cursor[
+            SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse
+          ]
+        )
+      end
+      def list_available_numbers(
+        # The account ID to list available phone numbers for.
+        account_id,
+        # Whether to search for local or toll-free numbers.
+        type:,
+        # Cursor for forward pagination. Use the next_cursor from a previous response.
+        after: nil,
+        # Filter by 3-digit area code.
+        area_code: nil,
+        # Cursor for backward pagination. Use the previous_cursor from a previous
+        # response.
+        before: nil,
+        # ISO country code to search in.
+        country: nil,
+        request_options: {}
+      )
+      end
+
+      # Purchase a new phone number for the account. You can specify an exact phone
+      # number, search criteria, or let the system select a random number.
+      #
+      # When `phone_number` is provided, all other search parameters are ignored.
       sig do
         params(
           account_id: String,
@@ -53,6 +106,7 @@ module SurgeAPI
           latitude: Float,
           longitude: Float,
           name: String,
+          phone_number: String,
           type: SurgeAPI::PhoneNumberPurchaseParams::Type::OrSymbol,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(SurgeAPI::PhoneNumber)
@@ -72,6 +126,9 @@ module SurgeAPI
         # A human-readable name for the phone number. If not provided, defaults to the
         # formatted phone number.
         name: nil,
+        # The exact phone number to purchase in E.164 format. When provided, all other
+        # search parameters are ignored.
+        phone_number: nil,
         # Whether the phone number is local or toll-free. Can be omitted if area_code or
         # latitude/longitude are provided.
         type: nil,

data/sig/surge_api/models/call_ended_webhook_event.rbs

@@ -37,7 +37,10 @@ module SurgeAPI
           contact: SurgeAPI::Contact,
           duration: Integer,
           initiated_at: Time,
-          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status
+          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status,
+          from: String?,
+          phone_number_id: String?,
+          to: String?
         }
 
       class Data < SurgeAPI::Internal::Type::BaseModel
@@ -51,12 +54,21 @@ module SurgeAPI
 
         attr_accessor status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status
 
+        attr_accessor from: String?
+
+        attr_accessor phone_number_id: String?
+
+        attr_accessor to: String?
+
         def initialize: (
           id: String,
           contact: SurgeAPI::Contact,
           duration: Integer,
           initiated_at: Time,
-          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status
+          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status,
+          ?from: String?,
+          ?phone_number_id: String?,
+          ?to: String?
         ) -> void
 
         def to_hash: -> {
@@ -64,7 +76,10 @@ module SurgeAPI
           contact: SurgeAPI::Contact,
           duration: Integer,
           initiated_at: Time,
-          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status
+          status: SurgeAPI::Models::CallEndedWebhookEvent::Data::status,
+          from: String?,
+          phone_number_id: String?,
+          to: String?
         }
 
         type status =

data/sig/surge_api/models/phone_number.rbs

@@ -3,6 +3,7 @@ module SurgeAPI
     type phone_number =
       {
         id: String,
+        campaign: SurgeAPI::PhoneNumber::Campaign?,
         campaign_id: String?,
         name: String?,
         number: String,
@@ -12,6 +13,8 @@ module SurgeAPI
     class PhoneNumber < SurgeAPI::Internal::Type::BaseModel
       attr_accessor id: String
 
+      attr_accessor campaign: SurgeAPI::PhoneNumber::Campaign?
+
       attr_accessor campaign_id: String?
 
       attr_accessor name: String?
@@ -22,6 +25,7 @@ module SurgeAPI
 
       def initialize: (
         id: String,
+        campaign: SurgeAPI::PhoneNumber::Campaign?,
         campaign_id: String?,
         name: String?,
         number: String,
@@ -30,12 +34,49 @@ module SurgeAPI
 
       def to_hash: -> {
         id: String,
+        campaign: SurgeAPI::PhoneNumber::Campaign?,
         campaign_id: String?,
         name: String?,
         number: String,
         type: SurgeAPI::Models::PhoneNumber::type_
       }
 
+      type campaign =
+        {
+          id: String,
+          attachment_status: SurgeAPI::Models::PhoneNumber::Campaign::attachment_status
+        }
+
+      class Campaign < SurgeAPI::Internal::Type::BaseModel
+        attr_accessor id: String
+
+        attr_accessor attachment_status: SurgeAPI::Models::PhoneNumber::Campaign::attachment_status
+
+        def initialize: (
+          id: String,
+          attachment_status: SurgeAPI::Models::PhoneNumber::Campaign::attachment_status
+        ) -> void
+
+        def to_hash: -> {
+          id: String,
+          attachment_status: SurgeAPI::Models::PhoneNumber::Campaign::attachment_status
+        }
+
+        type attachment_status =
+          :attached | :attachment_pending | :detached | :detachment_pending
+
+        module AttachmentStatus
+          extend SurgeAPI::Internal::Type::Enum
+
+          ATTACHED: :attached
+          ATTACHMENT_PENDING: :attachment_pending
+          DETACHED: :detached
+          DETACHMENT_PENDING: :detachment_pending
+
+          def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumber::Campaign::attachment_status]
+        end
+      end
+
       type type_ = :local | :short_code | :toll_free
 
       module Type

data/sig/surge_api/models/phone_number_attached_to_campaign_webhook_event.rbs

@@ -34,6 +34,7 @@ module SurgeAPI
       type data =
         {
           id: String,
+          campaign: SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign?,
           campaign_id: String,
           name: String?,
           number: String,
@@ -43,6 +44,8 @@ module SurgeAPI
       class Data < SurgeAPI::Internal::Type::BaseModel
         attr_accessor id: String
 
+        attr_accessor campaign: SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign?
+
         attr_accessor campaign_id: String
 
         attr_accessor name: String?
@@ -53,6 +56,7 @@ module SurgeAPI
 
         def initialize: (
           id: String,
+          campaign: SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign?,
           campaign_id: String,
           name: String?,
           number: String,
@@ -61,12 +65,49 @@ module SurgeAPI
 
         def to_hash: -> {
           id: String,
+          campaign: SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign?,
           campaign_id: String,
           name: String?,
           number: String,
           type: SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::type_
         }
 
+        type campaign =
+          {
+            id: String,
+            attachment_status: SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::attachment_status
+          }
+
+        class Campaign < SurgeAPI::Internal::Type::BaseModel
+          attr_accessor id: String
+
+          attr_accessor attachment_status: SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::attachment_status
+
+          def initialize: (
+            id: String,
+            attachment_status: SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::attachment_status
+          ) -> void
+
+          def to_hash: -> {
+            id: String,
+            attachment_status: SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::attachment_status
+          }
+
+          type attachment_status =
+            :attached | :attachment_pending | :detached | :detachment_pending
+
+          module AttachmentStatus
+            extend SurgeAPI::Internal::Type::Enum
+
+            ATTACHED: :attached
+            ATTACHMENT_PENDING: :attachment_pending
+            DETACHED: :detached
+            DETACHMENT_PENDING: :detachment_pending
+
+            def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::attachment_status]
+          end
+        end
+
         type type_ = :local | :short_code | :toll_free
 
         module Type