surge_api 0.16.0 → 0.18.0

data/lib/surge_api/models/user_list_params.rb

@@ -7,6 +7,12 @@ module SurgeAPI
       extend SurgeAPI::Internal::Type::RequestParameters::Converter
       include SurgeAPI::Internal::Type::RequestParameters
 
+      # @!attribute account_id
+      #   The account ID to list users for.
+      #
+      #   @return [String]
+      required :account_id, String
+
       # @!attribute after
       #   Cursor for forward pagination. Use the next_cursor from a previous response.
       #
@@ -20,10 +26,12 @@ module SurgeAPI
       #   @return [String, nil]
       optional :before, String
 
-      # @!method initialize(after: nil, before: nil, request_options: {})
+      # @!method initialize(account_id:, after: nil, before: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {SurgeAPI::Models::UserListParams} for more details.
       #
+      #   @param account_id [String] The account ID to list users for.
+      #
       #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
       #
       #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response

data/lib/surge_api/models/user_retrieve_params.rb

@@ -7,7 +7,15 @@ module SurgeAPI
       extend SurgeAPI::Internal::Type::RequestParameters::Converter
       include SurgeAPI::Internal::Type::RequestParameters
 
-      # @!method initialize(request_options: {})
+      # @!attribute id
+      #   The ID of the user to retrieve.
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!method initialize(id:, request_options: {})
+      #   @param id [String] The ID of the user to retrieve.
+      #
       #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
     end
   end

data/lib/surge_api/models/user_update_params.rb

@@ -7,6 +7,12 @@ module SurgeAPI
       extend SurgeAPI::Internal::Type::RequestParameters::Converter
       include SurgeAPI::Internal::Type::RequestParameters
 
+      # @!attribute id
+      #   The ID of the user to update.
+      #
+      #   @return [String]
+      required :id, String
+
       # @!attribute first_name
       #   The user's first name.
       #
@@ -31,7 +37,9 @@ module SurgeAPI
       #   @return [String, nil]
       optional :photo_url, String
 
-      # @!method initialize(first_name:, last_name: nil, metadata: nil, photo_url: nil, request_options: {})
+      # @!method initialize(id:, first_name:, last_name: nil, metadata: nil, photo_url: nil, request_options: {})
+      #   @param id [String] The ID of the user to update.
+      #
       #   @param first_name [String] The user's first name.
       #
       #   @param last_name [String] The user's last name.

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

@@ -45,6 +45,8 @@ module SurgeAPI
 
   AccountCreateParams = SurgeAPI::Models::AccountCreateParams
 
+  AccountListParams = SurgeAPI::Models::AccountListParams
+
   AccountRetrieveStatusParams = SurgeAPI::Models::AccountRetrieveStatusParams
 
   AccountStatus = SurgeAPI::Models::AccountStatus
@@ -127,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/accounts.rb

@@ -67,6 +67,35 @@ module SurgeAPI
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::AccountListParams} for more details.
+      #
+      # List all accounts for the calling platform with cursor-based pagination.
+      #
+      # @overload list(after: nil, before: nil, request_options: {})
+      #
+      # @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      # @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Internal::Cursor<SurgeAPI::Models::Account>]
+      #
+      # @see SurgeAPI::Models::AccountListParams
+      def list(params = {})
+        parsed, options = SurgeAPI::AccountListParams.dump_request(params)
+        query = SurgeAPI::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "accounts",
+          query: query,
+          page: SurgeAPI::Internal::Cursor,
+          model: SurgeAPI::Account,
+          options: options
+        )
+      end
+
       # Archives an account and releases all associated resources.
       #
       # **Warning**: This action will:

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.16.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"
@@ -58,6 +59,7 @@ require_relative "surge_api/models/message_params"
 require_relative "surge_api/models/account"
 require_relative "surge_api/models/account_archive_params"
 require_relative "surge_api/models/account_create_params"
+require_relative "surge_api/models/account_list_params"
 require_relative "surge_api/models/account_retrieve_status_params"
 require_relative "surge_api/models/account_status"
 require_relative "surge_api/models/account_update_params"
@@ -99,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_list_params.rbi

@@ -0,0 +1,59 @@
+# typed: strong
+
+module SurgeAPI
+  module Models
+    class AccountListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(SurgeAPI::AccountListParams, SurgeAPI::Internal::AnyHash)
+        end
+
+      # 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
+
+      # 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
+
+      sig do
+        params(
+          after: String,
+          before: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # 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
+        # response.
+        before: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            after: String,
+            before: String,
+            request_options: SurgeAPI::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  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