surge_api 0.18.0 → 0.20.0

data/lib/surge_api/resources/phone_numbers.rb

@@ -3,6 +3,26 @@
 module SurgeAPI
   module Resources
     class PhoneNumbers
+      # Retrieves a PhoneNumber object.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] The ID of the phone number to retrieve.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::PhoneNumber]
+      #
+      # @see SurgeAPI::Models::PhoneNumberRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["phone_numbers/%1$s", id],
+          model: SurgeAPI::PhoneNumber,
+          options: params[:request_options]
+        )
+      end
+
       # Updates a phone number's details.
       #
       # @overload update(id, campaign_id: nil, name: nil, request_options: {})
@@ -60,13 +80,54 @@ module SurgeAPI
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::PhoneNumberListAvailableNumbersParams} for more details.
+      #
+      # Browse purchasable phone numbers from Surge inventory before buying.
+      #
+      # Pagination cursors are always null for now.
+      #
+      # @overload list_available_numbers(account_id, type:, after: nil, area_code: nil, before: nil, country: nil, request_options: {})
+      #
+      # @param account_id [String] The account ID to list available phone numbers for.
+      #
+      # @param type [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Type] Whether to search for local or toll-free numbers.
+      #
+      # @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      # @param area_code [String] Filter by 3-digit area code.
+      #
+      # @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      # @param country [Symbol, SurgeAPI::Models::PhoneNumberListAvailableNumbersParams::Country] ISO country code to search in.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Internal::Cursor<SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse>]
+      #
+      # @see SurgeAPI::Models::PhoneNumberListAvailableNumbersParams
+      def list_available_numbers(account_id, params)
+        parsed, options = SurgeAPI::PhoneNumberListAvailableNumbersParams.dump_request(params)
+        query = SurgeAPI::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["accounts/%1$s/available_phone_numbers", account_id],
+          query: query,
+          page: SurgeAPI::Internal::Cursor,
+          model: SurgeAPI::Models::PhoneNumberListAvailableNumbersResponse,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {SurgeAPI::Models::PhoneNumberPurchaseParams} for more details.
       #
-      # Purchase a new phone number for the account. You can specify search criteria or
-      # let the system select a random number.
+      # 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.
       #
-      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, name: nil, type: nil, request_options: {})
+      # When `phone_number` is provided, all other search parameters are ignored.
+      #
+      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, name: nil, phone_number: nil, type: nil, request_options: {})
       #
       # @param account_id [String] The account for which the phone number should be created.
       #
@@ -78,6 +139,8 @@ module SurgeAPI
       #
       # @param name [String] A human-readable name for the phone number. If not provided, defaults to the for
       #
+      # @param phone_number [String] The exact phone number to purchase in E.164 format. When provided, all other sea
+      #
       # @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]

data/lib/surge_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SurgeAPI
-  VERSION = "0.18.0"
+  VERSION = "0.20.0"
 end

data/lib/surge_api.rb

@@ -99,9 +99,12 @@ require_relative "surge_api/models/message_sent_webhook_event"
 require_relative "surge_api/models/organization"
 require_relative "surge_api/models/phone_number"
 require_relative "surge_api/models/phone_number_attached_to_campaign_webhook_event"
+require_relative "surge_api/models/phone_number_list_available_numbers_params"
+require_relative "surge_api/models/phone_number_list_available_numbers_response"
 require_relative "surge_api/models/phone_number_list_params"
 require_relative "surge_api/models/phone_number_purchase_params"
 require_relative "surge_api/models/phone_number_release_params"
+require_relative "surge_api/models/phone_number_retrieve_params"
 require_relative "surge_api/models/phone_number_update_params"
 require_relative "surge_api/models/recording_completed_webhook_event"
 require_relative "surge_api/models/recording_delete_params"

data/rbi/surge_api/models/call_ended_webhook_event.rbi

@@ -94,6 +94,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 data associated with the event
         sig do
           params(
@@ -101,7 +113,10 @@ module SurgeAPI
             contact: SurgeAPI::Contact::OrHash,
             duration: Integer,
             initiated_at: Time,
-            status: SurgeAPI::CallEndedWebhookEvent::Data::Status::OrSymbol
+            status: SurgeAPI::CallEndedWebhookEvent::Data::Status::OrSymbol,
+            from: T.nilable(String),
+            phone_number_id: T.nilable(String),
+            to: T.nilable(String)
           ).returns(T.attached_class)
         end
         def self.new(
@@ -114,7 +129,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
 
@@ -126,7 +147,10 @@ module SurgeAPI
               duration: Integer,
               initiated_at: Time,
               status:
-                SurgeAPI::CallEndedWebhookEvent::Data::Status::TaggedSymbol
+                SurgeAPI::CallEndedWebhookEvent::Data::Status::TaggedSymbol,
+              from: T.nilable(String),
+              phone_number_id: T.nilable(String),
+              to: T.nilable(String)
             }
           )
         end

data/rbi/surge_api/models/phone_number.rbi

@@ -12,7 +12,19 @@ module SurgeAPI
       sig { returns(String) }
       attr_accessor :id
 
-      # The unique identifier of the campaign this phone number is attached to, if any
+      # Campaign attachment details for a domestic local phone number
+      sig { returns(T.nilable(SurgeAPI::PhoneNumber::Campaign)) }
+      attr_reader :campaign
+
+      sig do
+        params(
+          campaign: T.nilable(SurgeAPI::PhoneNumber::Campaign::OrHash)
+        ).void
+      end
+      attr_writer :campaign
+
+      # Deprecated. The unique identifier of the campaign this phone number is attached
+      # to, if any
       sig { returns(T.nilable(String)) }
       attr_accessor :campaign_id
 
@@ -32,6 +44,7 @@ module SurgeAPI
       sig do
         params(
           id: String,
+          campaign: T.nilable(SurgeAPI::PhoneNumber::Campaign::OrHash),
           campaign_id: T.nilable(String),
           name: T.nilable(String),
           number: String,
@@ -41,7 +54,10 @@ module SurgeAPI
       def self.new(
         # Unique identifier for the phone number
         id:,
-        # The unique identifier of the campaign this phone number is attached to, if any
+        # Campaign attachment details for a domestic local phone number
+        campaign:,
+        # Deprecated. The unique identifier of the campaign this phone number is attached
+        # to, if any
         campaign_id:,
         # A human-readable name for the phone number
         name:,
@@ -56,6 +72,7 @@ module SurgeAPI
         override.returns(
           {
             id: String,
+            campaign: T.nilable(SurgeAPI::PhoneNumber::Campaign),
             campaign_id: T.nilable(String),
             name: T.nilable(String),
             number: String,
@@ -66,6 +83,95 @@ module SurgeAPI
       def to_hash
       end
 
+      class Campaign < SurgeAPI::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(SurgeAPI::PhoneNumber::Campaign, SurgeAPI::Internal::AnyHash)
+          end
+
+        # The unique identifier of the campaign this phone number is attached to
+        sig { returns(String) }
+        attr_accessor :id
+
+        # The current campaign attachment status for this phone number.
+        sig do
+          returns(
+            SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+          )
+        end
+        attr_accessor :attachment_status
+
+        # Campaign attachment details for a domestic local phone number
+        sig do
+          params(
+            id: String,
+            attachment_status:
+              SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::OrSymbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The unique identifier of the campaign this phone number is attached to
+          id:,
+          # The current campaign attachment status for this phone number.
+          attachment_status:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              id: String,
+              attachment_status:
+                SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The current campaign attachment status for this phone number.
+        module AttachmentStatus
+          extend SurgeAPI::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, SurgeAPI::PhoneNumber::Campaign::AttachmentStatus)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          ATTACHED =
+            T.let(
+              :attached,
+              SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+            )
+          ATTACHMENT_PENDING =
+            T.let(
+              :attachment_pending,
+              SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+            )
+          DETACHED =
+            T.let(
+              :detached,
+              SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+            )
+          DETACHMENT_PENDING =
+            T.let(
+              :detachment_pending,
+              SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                SurgeAPI::PhoneNumber::Campaign::AttachmentStatus::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+
       # Whether the phone number is local, toll-free, or short code
       module Type
         extend SurgeAPI::Internal::Type::Enum

data/rbi/surge_api/models/phone_number_attached_to_campaign_webhook_event.rbi

@@ -84,7 +84,28 @@ module SurgeAPI
         sig { returns(String) }
         attr_accessor :id
 
-        # The unique identifier of the campaign this phone number is attached to
+        # Campaign attachment details for a domestic local phone number
+        sig do
+          returns(
+            T.nilable(
+              SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign
+            )
+          )
+        end
+        attr_reader :campaign
+
+        sig do
+          params(
+            campaign:
+              T.nilable(
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::OrHash
+              )
+          ).void
+        end
+        attr_writer :campaign
+
+        # Deprecated. The unique identifier of the campaign this phone number is attached
+        # to
         sig { returns(String) }
         attr_accessor :campaign_id
 
@@ -108,6 +129,10 @@ module SurgeAPI
         sig do
           params(
             id: String,
+            campaign:
+              T.nilable(
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::OrHash
+              ),
             campaign_id: String,
             name: T.nilable(String),
             number: String,
@@ -118,7 +143,10 @@ module SurgeAPI
         def self.new(
           # The unique identifier for the phone number
           id:,
-          # The unique identifier of the campaign this phone number is attached to
+          # Campaign attachment details for a domestic local phone number
+          campaign:,
+          # Deprecated. The unique identifier of the campaign this phone number is attached
+          # to
           campaign_id:,
           # A human-readable name for the phone number
           name:,
@@ -133,6 +161,10 @@ module SurgeAPI
           override.returns(
             {
               id: String,
+              campaign:
+                T.nilable(
+                  SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign
+                ),
               campaign_id: String,
               name: T.nilable(String),
               number: String,
@@ -144,6 +176,101 @@ module SurgeAPI
         def to_hash
         end
 
+        class Campaign < SurgeAPI::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign,
+                SurgeAPI::Internal::AnyHash
+              )
+            end
+
+          # The unique identifier of the campaign this phone number is attached to
+          sig { returns(String) }
+          attr_accessor :id
+
+          # The current campaign attachment status for this phone number.
+          sig do
+            returns(
+              SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+            )
+          end
+          attr_accessor :attachment_status
+
+          # Campaign attachment details for a domestic local phone number
+          sig do
+            params(
+              id: String,
+              attachment_status:
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::OrSymbol
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # The unique identifier of the campaign this phone number is attached to
+            id:,
+            # The current campaign attachment status for this phone number.
+            attachment_status:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                id: String,
+                attachment_status:
+                  SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # The current campaign attachment status for this phone number.
+          module AttachmentStatus
+            extend SurgeAPI::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            ATTACHED =
+              T.let(
+                :attached,
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+              )
+            ATTACHMENT_PENDING =
+              T.let(
+                :attachment_pending,
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+              )
+            DETACHED =
+              T.let(
+                :detached,
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+              )
+            DETACHMENT_PENDING =
+              T.let(
+                :detachment_pending,
+                SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  SurgeAPI::PhoneNumberAttachedToCampaignWebhookEvent::Data::Campaign::AttachmentStatus::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+
         # Whether the phone number is local, toll-free, or short code
         module Type
           extend SurgeAPI::Internal::Type::Enum

data/rbi/surge_api/models/phone_number_list_available_numbers_params.rbi

@@ -0,0 +1,183 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class PhoneNumberListAvailableNumbersParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            SurgeAPI::PhoneNumberListAvailableNumbersParams,
+            SurgeAPI::Internal::AnyHash
+          )
+        end
+
+      # The account ID to list available phone numbers for.
+      sig { returns(String) }
+      attr_accessor :account_id
+
+      # Whether to search for local or toll-free numbers.
+      sig do
+        returns(SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::OrSymbol)
+      end
+      attr_accessor :type
+
+      # Cursor for forward pagination. Use the next_cursor from a previous response.
+      sig { returns(T.nilable(String)) }
+      attr_reader :after
+
+      sig { params(after: String).void }
+      attr_writer :after
+
+      # Filter by 3-digit area code.
+      sig { returns(T.nilable(String)) }
+      attr_reader :area_code
+
+      sig { params(area_code: String).void }
+      attr_writer :area_code
+
+      # Cursor for backward pagination. Use the previous_cursor from a previous
+      # response.
+      sig { returns(T.nilable(String)) }
+      attr_reader :before
+
+      sig { params(before: String).void }
+      attr_writer :before
+
+      # ISO country code to search in.
+      sig do
+        returns(
+          T.nilable(
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::OrSymbol
+          )
+        )
+      end
+      attr_reader :country
+
+      sig do
+        params(
+          country:
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::OrSymbol
+        ).void
+      end
+      attr_writer :country
+
+      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(T.attached_class)
+      end
+      def self.new(
+        # 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
+
+      sig do
+        override.returns(
+          {
+            account_id: String,
+            type:
+              SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::OrSymbol,
+            after: String,
+            area_code: String,
+            before: String,
+            country:
+              SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::OrSymbol,
+            request_options: SurgeAPI::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Whether to search for local or toll-free numbers.
+      module Type
+        extend SurgeAPI::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, SurgeAPI::PhoneNumberListAvailableNumbersParams::Type)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        LOCAL =
+          T.let(
+            :local,
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::TaggedSymbol
+          )
+        TOLL_FREE =
+          T.let(
+            :toll_free,
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              SurgeAPI::PhoneNumberListAvailableNumbersParams::Type::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+
+      # ISO country code to search in.
+      module Country
+        extend SurgeAPI::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(
+              Symbol,
+              SurgeAPI::PhoneNumberListAvailableNumbersParams::Country
+            )
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        US =
+          T.let(
+            :US,
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::TaggedSymbol
+          )
+        CA =
+          T.let(
+            :CA,
+            SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[
+              SurgeAPI::PhoneNumberListAvailableNumbersParams::Country::TaggedSymbol
+            ]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end