surge_api 0.17.0 → 0.18.0

data/lib/surge_api/models/verification_check_params.rb

@@ -7,13 +7,21 @@ module SurgeAPI
       extend SurgeAPI::Internal::Type::RequestParameters::Converter
       include SurgeAPI::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   The ID of the verification to check against.
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute code
       #   The Verification code that was received.
       #
       #   @return [String]
       required :code, String
 
-      # @!method initialize(code:, request_options: {})
+      # @!method initialize(id:, code:, request_options: {})
+      #   @param id [String] The ID of the verification to check against.
+      #
       #   @param code [String] The Verification code that was received.
       #
       #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]

data/lib/surge_api/models/verification_create_params.rb

@@ -7,13 +7,21 @@ module SurgeAPI
       extend SurgeAPI::Internal::Type::RequestParameters::Converter
       include SurgeAPI::Internal::Type::RequestParameters
 
+      # @!attribute account_id
+      #   The account to associate with the verification.
+      #
+      #   @return [String]
+      required :account_id, String
+
       # @!attribute phone_number
       #   The phone number to be verified. In E.164 format.
       #
       #   @return [String]
       required :phone_number, String
 
-      # @!method initialize(phone_number:, request_options: {})
+      # @!method initialize(account_id:, phone_number:, request_options: {})
+      #   @param account_id [String] The account to associate with the verification.
+      #
       #   @param phone_number [String] The phone number to be verified. In E.164 format.
       #
       #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]

data/lib/surge_api/models.rb

@@ -129,6 +129,10 @@ module SurgeAPI
 
   PhoneNumberPurchaseParams = SurgeAPI::Models::PhoneNumberPurchaseParams
 
+  PhoneNumberReleaseParams = SurgeAPI::Models::PhoneNumberReleaseParams
+
+  PhoneNumberUpdateParams = SurgeAPI::Models::PhoneNumberUpdateParams
+
   RecordingCompletedWebhookEvent = SurgeAPI::Models::RecordingCompletedWebhookEvent
 
   RecordingDeleteParams = SurgeAPI::Models::RecordingDeleteParams

data/lib/surge_api/resources/campaigns.rb

@@ -12,7 +12,7 @@ module SurgeAPI
       #
       # @param account_id [String] The account for which the campaign should be created.
       #
-      # @param campaign_params [SurgeAPI::CampaignParams] Parameters for creating a new campaign. Either provide full campaign details or
+      # @param campaign_params [SurgeAPI::Models::CampaignParams::StandardCampaignParams, SurgeAPI::Models::CampaignParams::ExternalCampaignParams] Parameters for creating a new campaign. Either provide full campaign details or
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -21,15 +21,10 @@ module SurgeAPI
       # @see SurgeAPI::Models::CampaignCreateParams
       def create(account_id, params)
         parsed, options = SurgeAPI::CampaignCreateParams.dump_request(params)
-        case parsed
-        in {campaign_params: Hash => union, **rest}
-          parsed = {**rest, **union}
-        else
-        end
         @client.request(
           method: :post,
           path: ["accounts/%1$s/campaigns", account_id],
-          body: parsed,
+          body: parsed[:campaign_params],
           model: SurgeAPI::Campaign,
           options: options
         )
@@ -67,7 +62,7 @@ module SurgeAPI
       #
       # @param id [String] The ID of the campaign to update.
       #
-      # @param campaign_params [SurgeAPI::CampaignParams] Parameters for creating a new campaign. Either provide full campaign details or
+      # @param campaign_params [SurgeAPI::Models::CampaignParams::StandardCampaignParams, SurgeAPI::Models::CampaignParams::ExternalCampaignParams] Parameters for creating a new campaign. Either provide full campaign details or
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -76,15 +71,10 @@ module SurgeAPI
       # @see SurgeAPI::Models::CampaignUpdateParams
       def update(id, params)
         parsed, options = SurgeAPI::CampaignUpdateParams.dump_request(params)
-        case parsed
-        in {campaign_params: Hash => union, **rest}
-          parsed = {**rest, **union}
-        else
-        end
         @client.request(
           method: :patch,
           path: ["campaigns/%1$s", id],
-          body: parsed,
+          body: parsed[:campaign_params],
           model: SurgeAPI::Campaign,
           options: options
         )

data/lib/surge_api/resources/messages.rb

@@ -32,11 +32,15 @@ module SurgeAPI
       # `conversation` field, and `conversation.phone_number` should be specified
       # instead.
       #
+      # Optionally, you can pass a `settings` object to override account-level settings
+      # for this message. Currently the only supported setting is `link_shortening`,
+      # which accepts `"enabled"` or `"disabled"`.
+      #
       # @overload create(account_id, message_params:, request_options: {})
       #
       # @param account_id [String] The account from which the message should be sent.
       #
-      # @param message_params [SurgeAPI::MessageParams] Payload for creating a message. Either an attachment or the body must be given.
+      # @param message_params [SurgeAPI::Models::MessageParams::MessageParamsWithConversation, SurgeAPI::Models::MessageParams::SimpleMessageParams] Payload for creating a message. Either an attachment or the body must be given.
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -45,15 +49,10 @@ module SurgeAPI
       # @see SurgeAPI::Models::MessageCreateParams
       def create(account_id, params)
         parsed, options = SurgeAPI::MessageCreateParams.dump_request(params)
-        case parsed
-        in {message_params: Hash => union, **rest}
-          parsed = {**rest, **union}
-        else
-        end
         @client.request(
           method: :post,
           path: ["accounts/%1$s/messages", account_id],
-          body: parsed,
+          body: parsed[:message_params],
           model: SurgeAPI::Message,
           options: options
         )

data/lib/surge_api/resources/phone_numbers.rb

@@ -3,6 +3,32 @@
 module SurgeAPI
   module Resources
     class PhoneNumbers
+      # Updates a phone number's details.
+      #
+      # @overload update(id, campaign_id: nil, name: nil, request_options: {})
+      #
+      # @param id [String] The ID of the phone number to update.
+      #
+      # @param campaign_id [String] Campaign ID to attach this number to (`cpn_...`).
+      #
+      # @param name [String] A human-readable name for the phone number.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::PhoneNumber]
+      #
+      # @see SurgeAPI::Models::PhoneNumberUpdateParams
+      def update(id, params = {})
+        parsed, options = SurgeAPI::PhoneNumberUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["phone_numbers/%1$s", id],
+          body: parsed,
+          model: SurgeAPI::PhoneNumber,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {SurgeAPI::Models::PhoneNumberListParams} for more details.
       #
@@ -70,6 +96,26 @@ module SurgeAPI
         )
       end
 
+      # Releases a phone number from the account.
+      #
+      # @overload release(id, request_options: {})
+      #
+      # @param id [String] The ID of the phone number to release.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::PhoneNumber]
+      #
+      # @see SurgeAPI::Models::PhoneNumberReleaseParams
+      def release(id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["phone_numbers/%1$s", id],
+          model: SurgeAPI::PhoneNumber,
+          options: params[:request_options]
+        )
+      end
+
       # @api private
       #
       # @param client [SurgeAPI::Client]

data/lib/surge_api/resources/verifications.rb

@@ -3,9 +3,12 @@
 module SurgeAPI
   module Resources
     class Verifications
-      # Creates a new Verification and sends the code to the given phone number.
+      # Creates a new Verification for an account and sends the code to the given phone
+      # number.
       #
-      # @overload create(phone_number:, request_options: {})
+      # @overload create(account_id, phone_number:, request_options: {})
+      #
+      # @param account_id [String] The account to associate with the verification.
       #
       # @param phone_number [String] The phone number to be verified. In E.164 format.
       #
@@ -14,11 +17,11 @@ module SurgeAPI
       # @return [SurgeAPI::Models::Verification]
       #
       # @see SurgeAPI::Models::VerificationCreateParams
-      def create(params)
+      def create(account_id, params)
         parsed, options = SurgeAPI::VerificationCreateParams.dump_request(params)
         @client.request(
           method: :post,
-          path: "verifications",
+          path: ["accounts/%1$s/verifications", account_id],
           body: parsed,
           model: SurgeAPI::Verification,
           options: options

data/lib/surge_api/resources/webhooks.rb

@@ -5,8 +5,18 @@ module SurgeAPI
     class Webhooks
       # @param payload [String] The raw webhook payload as a string
       #
+      # @param headers [Hash{String=>String}] The raw HTTP headers that came with the payload
+      #
+      # @param key [String, nil] The webhook signing key
+      #
       # @return [SurgeAPI::Models::CallEndedWebhookEvent, SurgeAPI::Models::CampaignApprovedWebhookEvent, SurgeAPI::Models::ContactOptedInWebhookEvent, SurgeAPI::Models::ContactOptedOutWebhookEvent, SurgeAPI::Models::ConversationCreatedWebhookEvent, SurgeAPI::Models::LinkFollowedWebhookEvent, SurgeAPI::Models::MessageDeliveredWebhookEvent, SurgeAPI::Models::MessageFailedWebhookEvent, SurgeAPI::Models::MessageReceivedWebhookEvent, SurgeAPI::Models::MessageSentWebhookEvent, SurgeAPI::Models::PhoneNumberAttachedToCampaignWebhookEvent, SurgeAPI::Models::RecordingCompletedWebhookEvent, SurgeAPI::Models::VoicemailReceivedWebhookEvent]
-      def unwrap(payload)
+      def unwrap(payload, headers:, key: @client.webhook_signing_secret)
+        if key.nil?
+          raise ArgumentError.new("Cannot verify a webhook without a key on either the client's webhook_signing_secret or passed in as an argument")
+        end
+
+        ::StandardWebhooks::Webhook.new(key).verify(payload, headers)
+
         parsed = JSON.parse(payload, symbolize_names: true)
         SurgeAPI::Internal::Type::Converter.coerce(SurgeAPI::Models::UnwrapWebhookEvent, parsed)
       end

data/lib/surge_api/version.rb

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

data/lib/surge_api.rb

@@ -30,6 +30,7 @@ end
 
 # Gems.
 require "connection_pool"
+require "standardwebhooks"
 
 # Package files.
 require_relative "surge_api/version"
@@ -100,6 +101,8 @@ 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_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_update_params"
 require_relative "surge_api/models/recording_completed_webhook_event"
 require_relative "surge_api/models/recording_delete_params"
 require_relative "surge_api/models/recording_delete_response"

data/rbi/surge_api/client.rbi

@@ -13,6 +13,9 @@ module SurgeAPI
     sig { returns(String) }
     attr_reader :api_key
 
+    sig { returns(T.nilable(String)) }
+    attr_reader :webhook_signing_secret
+
     sig { returns(SurgeAPI::Resources::Accounts) }
     attr_reader :accounts
 
@@ -58,6 +61,7 @@ module SurgeAPI
     sig do
       params(
         api_key: T.nilable(String),
+        webhook_signing_secret: T.nilable(String),
         base_url: T.nilable(String),
         max_retries: Integer,
         timeout: Float,
@@ -68,6 +72,8 @@ module SurgeAPI
     def self.new(
       # Defaults to `ENV["SURGE_API_KEY"]`
       api_key: ENV["SURGE_API_KEY"],
+      # Defaults to `ENV["SURGE_WEBHOOK_SIGNING_SECRET"]`
+      webhook_signing_secret: ENV["SURGE_WEBHOOK_SIGNING_SECRET"],
       # Override the default base URL for the API, e.g.,
       # `"https://api.example.com/v2/"`. Defaults to `ENV["SURGE_BASE_URL"]`
       base_url: ENV["SURGE_BASE_URL"],

data/rbi/surge_api/internal/util.rbi

@@ -148,12 +148,20 @@ module SurgeAPI
         end
       end
 
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = T.let(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/, Regexp)
+
       class << self
         # @api private
         sig { params(uri: URI::Generic).returns(String) }
         def uri_origin(uri)
         end
 
+        # @api private
+        sig { params(path: T.any(String, Integer)).returns(String) }
+        def encode_path(path)
+        end
+
         # @api private
         sig { params(path: T.any(String, T::Array[String])).returns(String) }
         def interpolate_path(path)

data/rbi/surge_api/models/account_archive_params.rbi

@@ -11,15 +11,28 @@ module SurgeAPI
           T.any(SurgeAPI::AccountArchiveParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The ID of the account to archive.
+      sig { returns(String) }
+      attr_accessor :id
+
       sig do
-        params(request_options: SurgeAPI::RequestOptions::OrHash).returns(
-          T.attached_class
-        )
+        params(
+          id: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(T.attached_class)
       end
-      def self.new(request_options: {})
+      def self.new(
+        # The ID of the account to archive.
+        id:,
+        request_options: {}
+      )
       end
 
-      sig { override.returns({ request_options: SurgeAPI::RequestOptions }) }
+      sig do
+        override.returns(
+          { id: String, request_options: SurgeAPI::RequestOptions }
+        )
+      end
       def to_hash
       end
     end

data/rbi/surge_api/models/account_retrieve_status_params.rbi

@@ -14,6 +14,10 @@ module SurgeAPI
           )
         end
 
+      # ID of the account to check
+      sig { returns(String) }
+      attr_accessor :account_id
+
       # capabilities about which to check the status
       sig do
         returns(
@@ -38,6 +42,7 @@ module SurgeAPI
 
       sig do
         params(
+          account_id: String,
           capabilities:
             T::Array[
               SurgeAPI::AccountRetrieveStatusParams::Capability::OrSymbol
@@ -46,6 +51,8 @@ module SurgeAPI
         ).returns(T.attached_class)
       end
       def self.new(
+        # ID of the account to check
+        account_id:,
         # capabilities about which to check the status
         capabilities: nil,
         request_options: {}
@@ -55,6 +62,7 @@ module SurgeAPI
       sig do
         override.returns(
           {
+            account_id: String,
             capabilities:
               T::Array[
                 SurgeAPI::AccountRetrieveStatusParams::Capability::OrSymbol

data/rbi/surge_api/models/account_update_params.rbi

@@ -11,6 +11,10 @@ module SurgeAPI
           T.any(SurgeAPI::AccountUpdateParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The ID for the account to update.
+      sig { returns(String) }
+      attr_accessor :id
+
       # The name by which the people this account communicates with know it. If not
       # provided, this will match the name field.
       sig { returns(T.nilable(String)) }
@@ -48,6 +52,7 @@ module SurgeAPI
 
       sig do
         params(
+          id: String,
           brand_name: String,
           name: String,
           organization: SurgeAPI::AccountUpdateParams::Organization::OrHash,
@@ -56,6 +61,8 @@ module SurgeAPI
         ).returns(T.attached_class)
       end
       def self.new(
+        # The ID for the account to update.
+        id:,
         # The name by which the people this account communicates with know it. If not
         # provided, this will match the name field.
         brand_name: nil,
@@ -77,6 +84,7 @@ module SurgeAPI
       sig do
         override.returns(
           {
+            id: String,
             brand_name: String,
             name: String,
             organization: SurgeAPI::AccountUpdateParams::Organization,

data/rbi/surge_api/models/attachment_get_file_params.rbi

@@ -11,15 +11,28 @@ module SurgeAPI
           T.any(SurgeAPI::AttachmentGetFileParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The ID of the attachment.
+      sig { returns(String) }
+      attr_accessor :attachment_id
+
       sig do
-        params(request_options: SurgeAPI::RequestOptions::OrHash).returns(
-          T.attached_class
-        )
+        params(
+          attachment_id: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(T.attached_class)
       end
-      def self.new(request_options: {})
+      def self.new(
+        # The ID of the attachment.
+        attachment_id:,
+        request_options: {}
+      )
       end
 
-      sig { override.returns({ request_options: SurgeAPI::RequestOptions }) }
+      sig do
+        override.returns(
+          { attachment_id: String, request_options: SurgeAPI::RequestOptions }
+        )
+      end
       def to_hash
       end
     end

data/rbi/surge_api/models/audience_add_contact_params.rbi

@@ -11,6 +11,10 @@ module SurgeAPI
           T.any(SurgeAPI::AudienceAddContactParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The audience ID to add the contact to.
+      sig { returns(String) }
+      attr_accessor :audience_id
+
       # The ID of the contact to add. The contact must belong to the same account as the
       # audience.
       sig { returns(String) }
@@ -18,11 +22,14 @@ module SurgeAPI
 
       sig do
         params(
+          audience_id: String,
           id: String,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # The audience ID to add the contact to.
+        audience_id:,
         # The ID of the contact to add. The contact must belong to the same account as the
         # audience.
         id:,
@@ -32,7 +39,11 @@ module SurgeAPI
 
       sig do
         override.returns(
-          { id: String, request_options: SurgeAPI::RequestOptions }
+          {
+            audience_id: String,
+            id: String,
+            request_options: SurgeAPI::RequestOptions
+          }
         )
       end
       def to_hash

data/rbi/surge_api/models/audience_create_params.rbi

@@ -11,17 +11,24 @@ module SurgeAPI
           T.any(SurgeAPI::AudienceCreateParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The account for which the audience should be created.
+      sig { returns(String) }
+      attr_accessor :account_id
+
       # The audience name.
       sig { returns(String) }
       attr_accessor :name
 
       sig do
         params(
+          account_id: String,
           name: String,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # The account for which the audience should be created.
+        account_id:,
         # The audience name.
         name:,
         request_options: {}
@@ -30,7 +37,11 @@ module SurgeAPI
 
       sig do
         override.returns(
-          { name: String, request_options: SurgeAPI::RequestOptions }
+          {
+            account_id: String,
+            name: String,
+            request_options: SurgeAPI::RequestOptions
+          }
         )
       end
       def to_hash

data/rbi/surge_api/models/audience_list_contacts_params.rbi

@@ -14,6 +14,10 @@ module SurgeAPI
           )
         end
 
+      # The audience ID to list contacts for.
+      sig { returns(String) }
+      attr_accessor :audience_id
+
       # Cursor for forward pagination. Use the next_cursor from a previous response.
       sig { returns(T.nilable(String)) }
       attr_reader :after
@@ -31,12 +35,15 @@ module SurgeAPI
 
       sig do
         params(
+          audience_id: String,
           after: String,
           before: String,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
+        # The audience ID to list contacts for.
+        audience_id:,
         # Cursor for forward pagination. Use the next_cursor from a previous response.
         after: nil,
         # Cursor for backward pagination. Use the previous_cursor from a previous
@@ -49,6 +56,7 @@ module SurgeAPI
       sig do
         override.returns(
           {
+            audience_id: String,
             after: String,
             before: String,
             request_options: SurgeAPI::RequestOptions

data/rbi/surge_api/models/blast_create_params.rbi

@@ -11,6 +11,10 @@ module SurgeAPI
           T.any(SurgeAPI::BlastCreateParams, SurgeAPI::Internal::AnyHash)
         end
 
+      # The account for which the blast should be sent.
+      sig { returns(String) }
+      attr_accessor :account_id
+
       sig do
         returns(T.nilable(T::Array[SurgeAPI::BlastCreateParams::Attachment]))
       end
@@ -74,6 +78,7 @@ module SurgeAPI
 
       sig do
         params(
+          account_id: String,
           attachments:
             T::Array[SurgeAPI::BlastCreateParams::Attachment::OrHash],
           body: T.nilable(String),
@@ -87,6 +92,8 @@ module SurgeAPI
         ).returns(T.attached_class)
       end
       def self.new(
+        # The account for which the blast should be sent.
+        account_id:,
         attachments: nil,
         # The message body.
         body: nil,
@@ -112,6 +119,7 @@ module SurgeAPI
       sig do
         override.returns(
           {
+            account_id: String,
             attachments: T::Array[SurgeAPI::BlastCreateParams::Attachment],
             body: T.nilable(String),
             contacts: T::Array[String],

data/rbi/surge_api/models/campaign_create_params.rbi

@@ -11,46 +11,26 @@ module SurgeAPI
           T.any(SurgeAPI::CampaignCreateParams, SurgeAPI::Internal::AnyHash)
         end
 
-      # Parameters for creating a new campaign. Either provide full campaign details or
-      # import using a TCR ID.
-      sig do
-        returns(
-          T.any(
-            SurgeAPI::CampaignParams::StandardCampaignParams,
-            SurgeAPI::CampaignParams::ExternalCampaignParams
-          )
-        )
-      end
-      attr_accessor :campaign_params
+      # The account for which the campaign should be created.
+      sig { returns(String) }
+      attr_accessor :account_id
 
       sig do
         params(
-          campaign_params:
-            T.any(
-              SurgeAPI::CampaignParams::StandardCampaignParams::OrHash,
-              SurgeAPI::CampaignParams::ExternalCampaignParams::OrHash
-            ),
+          account_id: String,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
-        # Parameters for creating a new campaign. Either provide full campaign details or
-        # import using a TCR ID.
-        campaign_params:,
+        # The account for which the campaign should be created.
+        account_id:,
         request_options: {}
       )
       end
 
       sig do
         override.returns(
-          {
-            campaign_params:
-              T.any(
-                SurgeAPI::CampaignParams::StandardCampaignParams,
-                SurgeAPI::CampaignParams::ExternalCampaignParams
-              ),
-            request_options: SurgeAPI::RequestOptions
-          }
+          { account_id: String, request_options: SurgeAPI::RequestOptions }
         )
       end
       def to_hash