surge_api 0.19.0 → 0.20.0

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/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

data/sig/surge_api/models/phone_number_list_available_numbers_params.rbs

@@ -0,0 +1,83 @@
+module SurgeAPI
+  module Models
+    type phone_number_list_available_numbers_params =
+      {
+        account_id: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_,
+        after: String,
+        area_code: String,
+        before: String,
+        country: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country
+      }
+      & SurgeAPI::Internal::Type::request_parameters
+
+    class PhoneNumberListAvailableNumbersParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      attr_accessor account_id: String
+
+      attr_accessor type: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_
+
+      attr_reader after: String?
+
+      def after=: (String) -> String
+
+      attr_reader area_code: String?
+
+      def area_code=: (String) -> String
+
+      attr_reader before: String?
+
+      def before=: (String) -> String
+
+      attr_reader country: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country?
+
+      def country=: (
+        SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country
+      ) -> SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country
+
+      def initialize: (
+        account_id: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_,
+        ?after: String,
+        ?area_code: String,
+        ?before: String,
+        ?country: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country,
+        ?request_options: SurgeAPI::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        account_id: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_,
+        after: String,
+        area_code: String,
+        before: String,
+        country: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country,
+        request_options: SurgeAPI::RequestOptions
+      }
+
+      type type_ = :local | :toll_free
+
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        LOCAL: :local
+        TOLL_FREE: :toll_free
+
+        def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_]
+      end
+
+      type country = :US | :CA
+
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        US: :US
+        CA: :CA
+
+        def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country]
+      end
+    end
+  end
+end

data/sig/surge_api/models/phone_number_list_available_numbers_response.rbs

@@ -0,0 +1,52 @@
+module SurgeAPI
+  module Models
+    type phone_number_list_available_numbers_response =
+      {
+        country: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::country,
+        number: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::type_
+      }
+
+    class PhoneNumberListAvailableNumbersResponse < SurgeAPI::Internal::Type::BaseModel
+      attr_accessor country: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::country
+
+      attr_accessor number: String
+
+      attr_accessor type: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::type_
+
+      def initialize: (
+        country: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::country,
+        number: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::type_
+      ) -> void
+
+      def to_hash: -> {
+        country: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::country,
+        number: String,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::type_
+      }
+
+      type country = :US | :CA
+
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        US: :US
+        CA: :CA
+
+        def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::country]
+      end
+
+      type type_ = :local | :toll_free
+
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        LOCAL: :local
+        TOLL_FREE: :toll_free
+
+        def self?.values: -> ::Array[SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse::type_]
+      end
+    end
+  end
+end

data/sig/surge_api/models/phone_number_purchase_params.rbs

@@ -7,6 +7,7 @@ module SurgeAPI
         latitude: Float,
         longitude: Float,
         name: String,
+        phone_number: String,
         type: SurgeAPI::Models::PhoneNumberPurchaseParams::type_
       }
       & SurgeAPI::Internal::Type::request_parameters
@@ -33,6 +34,10 @@ module SurgeAPI
 
       def name=: (String) -> String
 
+      attr_reader phone_number: String?
+
+      def phone_number=: (String) -> String
+
       attr_reader type: SurgeAPI::Models::PhoneNumberPurchaseParams::type_?
 
       def type=: (
@@ -45,6 +50,7 @@ module SurgeAPI
         ?latitude: Float,
         ?longitude: Float,
         ?name: String,
+        ?phone_number: String,
         ?type: SurgeAPI::Models::PhoneNumberPurchaseParams::type_,
         ?request_options: SurgeAPI::request_opts
       ) -> void
@@ -55,6 +61,7 @@ module SurgeAPI
         latitude: Float,
         longitude: Float,
         name: String,
+        phone_number: String,
         type: SurgeAPI::Models::PhoneNumberPurchaseParams::type_,
         request_options: SurgeAPI::RequestOptions
       }

data/sig/surge_api/models/phone_number_retrieve_params.rbs

@@ -0,0 +1,20 @@
+module SurgeAPI
+  module Models
+    type phone_number_retrieve_params =
+      { id: String } & SurgeAPI::Internal::Type::request_parameters
+
+    class PhoneNumberRetrieveParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      attr_accessor id: String
+
+      def initialize: (
+        id: String,
+        ?request_options: SurgeAPI::request_opts
+      ) -> void
+
+      def to_hash: -> { id: String, request_options: SurgeAPI::RequestOptions }
+    end
+  end
+end

data/sig/surge_api/models.rbs

@@ -85,12 +85,16 @@ module SurgeAPI
 
   class PhoneNumberAttachedToCampaignWebhookEvent = SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent
 
+  class PhoneNumberListAvailableNumbersParams = SurgeAPI::Models::PhoneNumberListAvailableNumbersParams
+
   class PhoneNumberListParams = SurgeAPI::Models::PhoneNumberListParams
 
   class PhoneNumberPurchaseParams = SurgeAPI::Models::PhoneNumberPurchaseParams
 
   class PhoneNumberReleaseParams = SurgeAPI::Models::PhoneNumberReleaseParams
 
+  class PhoneNumberRetrieveParams = SurgeAPI::Models::PhoneNumberRetrieveParams
+
   class PhoneNumberUpdateParams = SurgeAPI::Models::PhoneNumberUpdateParams
 
   class RecordingCompletedWebhookEvent = SurgeAPI::Models::RecordingCompletedWebhookEvent

data/sig/surge_api/resources/phone_numbers.rbs

@@ -1,6 +1,11 @@
 module SurgeAPI
   module Resources
     class PhoneNumbers
+      def retrieve: (
+        String id,
+        ?request_options: SurgeAPI::request_opts
+      ) -> SurgeAPI::PhoneNumber
+
       def update: (
         String id,
         ?campaign_id: String,
@@ -15,12 +20,23 @@ module SurgeAPI
         ?request_options: SurgeAPI::request_opts
       ) -> SurgeAPI::Internal::Cursor[SurgeAPI::PhoneNumber]
 
+      def list_available_numbers: (
+        String account_id,
+        type: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::type_,
+        ?after: String,
+        ?area_code: String,
+        ?before: String,
+        ?country: SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::country,
+        ?request_options: SurgeAPI::request_opts
+      ) -> SurgeAPI::Internal::Cursor[SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse]
+
       def purchase: (
         String account_id,
         ?area_code: String,
         ?latitude: Float,
         ?longitude: Float,
         ?name: String,
+        ?phone_number: String,
         ?type: SurgeAPI::Models::PhoneNumberPurchaseParams::type_,
         ?request_options: SurgeAPI::request_opts
       ) -> SurgeAPI::PhoneNumber

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: surge_api
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Surge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -129,9 +129,12 @@ files:
 - lib/surge_api/models/organization.rb
 - lib/surge_api/models/phone_number.rb
 - lib/surge_api/models/phone_number_attached_to_campaign_webhook_event.rb
+- lib/surge_api/models/phone_number_list_available_numbers_params.rb
+- lib/surge_api/models/phone_number_list_available_numbers_response.rb
 - lib/surge_api/models/phone_number_list_params.rb
 - lib/surge_api/models/phone_number_purchase_params.rb
 - lib/surge_api/models/phone_number_release_params.rb
+- lib/surge_api/models/phone_number_retrieve_params.rb
 - lib/surge_api/models/phone_number_update_params.rb
 - lib/surge_api/models/recording_completed_webhook_event.rb
 - lib/surge_api/models/recording_delete_params.rb
@@ -237,9 +240,12 @@ files:
 - rbi/surge_api/models/organization.rbi
 - rbi/surge_api/models/phone_number.rbi
 - rbi/surge_api/models/phone_number_attached_to_campaign_webhook_event.rbi
+- rbi/surge_api/models/phone_number_list_available_numbers_params.rbi
+- rbi/surge_api/models/phone_number_list_available_numbers_response.rbi
 - rbi/surge_api/models/phone_number_list_params.rbi
 - rbi/surge_api/models/phone_number_purchase_params.rbi
 - rbi/surge_api/models/phone_number_release_params.rbi
+- rbi/surge_api/models/phone_number_retrieve_params.rbi
 - rbi/surge_api/models/phone_number_update_params.rbi
 - rbi/surge_api/models/recording_completed_webhook_event.rbi
 - rbi/surge_api/models/recording_delete_params.rbi
@@ -344,9 +350,12 @@ files:
 - sig/surge_api/models/organization.rbs
 - sig/surge_api/models/phone_number.rbs
 - sig/surge_api/models/phone_number_attached_to_campaign_webhook_event.rbs
+- sig/surge_api/models/phone_number_list_available_numbers_params.rbs
+- sig/surge_api/models/phone_number_list_available_numbers_response.rbs
 - sig/surge_api/models/phone_number_list_params.rbs
 - sig/surge_api/models/phone_number_purchase_params.rbs
 - sig/surge_api/models/phone_number_release_params.rbs
+- sig/surge_api/models/phone_number_retrieve_params.rbs
 - sig/surge_api/models/phone_number_update_params.rbs
 - sig/surge_api/models/recording_completed_webhook_event.rbs
 - sig/surge_api/models/recording_delete_params.rbs