surge_api 0.2.0 → 0.3.0

data/lib/surge_api/models/message_params.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # Payload for creating a message. Either an attachment or the body must be given.
+    # You can specify the recipient either using the 'conversation' parameter or the
+    # 'to'/'from' parameters, but not both.
+    module MessageParams
+      extend SurgeAPI::Internal::Type::Union
+
+      # Create a message while including parameters for the conversation in which the message should be sent.
+      variant -> { SurgeAPI::MessageParams::MessageParamsWithConversation }
+
+      # Create a basic message by specifying just the to/from phone numbers.
+      variant -> { SurgeAPI::MessageParams::SimpleMessageParams }
+
+      class MessageParamsWithConversation < SurgeAPI::Internal::Type::BaseModel
+        # @!attribute conversation
+        #   Params for selecting or creating a new conversation. Either the id or the
+        #   Contact must be given.
+        #
+        #   @return [SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation]
+        required :conversation, -> { SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation }
+
+        # @!attribute attachments
+        #
+        #   @return [Array<SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Attachment>, nil]
+        optional :attachments,
+                 -> { SurgeAPI::Internal::Type::ArrayOf[SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment] }
+
+        # @!attribute body
+        #   The message body.
+        #
+        #   @return [String, nil]
+        optional :body, String
+
+        # @!attribute send_at
+        #   An optional datetime for scheduling message up to a couple of months in the
+        #   future.
+        #
+        #   @return [Time, nil]
+        optional :send_at, Time
+
+        # @!method initialize(conversation:, attachments: nil, body: nil, send_at: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {SurgeAPI::Models::MessageParams::MessageParamsWithConversation} for more
+        #   details.
+        #
+        #   Create a message while including parameters for the conversation in which the
+        #   message should be sent.
+        #
+        #   @param conversation [SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation] Params for selecting or creating a new conversation. Either the id or the Contac
+        #
+        #   @param attachments [Array<SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Attachment>]
+        #
+        #   @param body [String] The message body.
+        #
+        #   @param send_at [Time] An optional datetime for scheduling message up to a couple of months in the futu
+
+        # @see SurgeAPI::Models::MessageParams::MessageParamsWithConversation#conversation
+        class Conversation < SurgeAPI::Internal::Type::BaseModel
+          # @!attribute contact
+          #   Parameters for creating a contact
+          #
+          #   @return [SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation::Contact]
+          required :contact, -> { SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact }
+
+          # @!attribute phone_number
+          #   The phone number from which to send the message. This can be either the phone
+          #   number in E.164 format or a Surge phone number id.
+          #
+          #   @return [String, nil]
+          optional :phone_number, String
+
+          # @!method initialize(contact:, phone_number: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation}
+          #   for more details.
+          #
+          #   Params for selecting or creating a new conversation. Either the id or the
+          #   Contact must be given.
+          #
+          #   @param contact [SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation::Contact] Parameters for creating a contact
+          #
+          #   @param phone_number [String] The phone number from which to send the message. This can be either the phone nu
+
+          # @see SurgeAPI::Models::MessageParams::MessageParamsWithConversation::Conversation#contact
+          class Contact < SurgeAPI::Internal::Type::BaseModel
+            # @!attribute phone_number
+            #   The contact's phone number in E.164 format.
+            #
+            #   @return [String]
+            required :phone_number, String
+
+            # @!attribute email
+            #   The contact's email address.
+            #
+            #   @return [String, nil]
+            optional :email, String
+
+            # @!attribute first_name
+            #   The contact's first name.
+            #
+            #   @return [String, nil]
+            optional :first_name, String
+
+            # @!attribute last_name
+            #   The contact's last name.
+            #
+            #   @return [String, nil]
+            optional :last_name, String
+
+            # @!attribute metadata
+            #   Set of key-value pairs that will be stored with the object.
+            #
+            #   @return [Hash{Symbol=>String}, nil]
+            optional :metadata, SurgeAPI::Internal::Type::HashOf[String]
+
+            # @!method initialize(phone_number:, email: nil, first_name: nil, last_name: nil, metadata: nil)
+            #   Parameters for creating a contact
+            #
+            #   @param phone_number [String] The contact's phone number in E.164 format.
+            #
+            #   @param email [String] The contact's email address.
+            #
+            #   @param first_name [String] The contact's first name.
+            #
+            #   @param last_name [String] The contact's last name.
+            #
+            #   @param metadata [Hash{Symbol=>String}] Set of key-value pairs that will be stored with the object.
+          end
+        end
+
+        class Attachment < SurgeAPI::Internal::Type::BaseModel
+          # @!attribute url
+          #   The URL of the attachment.
+          #
+          #   @return [String]
+          required :url, String
+
+          # @!method initialize(url:)
+          #   Params for creating an attachment
+          #
+          #   @param url [String] The URL of the attachment.
+        end
+      end
+
+      class SimpleMessageParams < SurgeAPI::Internal::Type::BaseModel
+        # @!attribute to
+        #   The recipient's phone number in E.164 format. Cannot be used together with
+        #   'conversation'.
+        #
+        #   @return [String]
+        required :to, String
+
+        # @!attribute attachments
+        #
+        #   @return [Array<SurgeAPI::Models::MessageParams::SimpleMessageParams::Attachment>, nil]
+        optional :attachments,
+                 -> { SurgeAPI::Internal::Type::ArrayOf[SurgeAPI::MessageParams::SimpleMessageParams::Attachment] }
+
+        # @!attribute body
+        #   The message body.
+        #
+        #   @return [String, nil]
+        optional :body, String
+
+        # @!attribute from
+        #   The sender's phone number in E.164 format or phone number ID. If omitted, uses
+        #   the account's default phone number. Cannot be used together with 'conversation'.
+        #
+        #   @return [String, nil]
+        optional :from, String
+
+        # @!attribute send_at
+        #   An optional datetime for scheduling message up to a couple of months in the
+        #   future.
+        #
+        #   @return [Time, nil]
+        optional :send_at, Time
+
+        # @!method initialize(to:, attachments: nil, body: nil, from: nil, send_at: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {SurgeAPI::Models::MessageParams::SimpleMessageParams} for more details.
+        #
+        #   Create a basic message by specifying just the to/from phone numbers.
+        #
+        #   @param to [String] The recipient's phone number in E.164 format. Cannot be used together with 'conv
+        #
+        #   @param attachments [Array<SurgeAPI::Models::MessageParams::SimpleMessageParams::Attachment>]
+        #
+        #   @param body [String] The message body.
+        #
+        #   @param from [String] The sender's phone number in E.164 format or phone number ID. If omitted, uses t
+        #
+        #   @param send_at [Time] An optional datetime for scheduling message up to a couple of months in the futu
+
+        class Attachment < SurgeAPI::Internal::Type::BaseModel
+          # @!attribute url
+          #   The URL of the attachment.
+          #
+          #   @return [String]
+          required :url, String
+
+          # @!method initialize(url:)
+          #   Params for creating an attachment
+          #
+          #   @param url [String] The URL of the attachment.
+        end
+      end
+
+      # @!method self.variants
+      #   @return [Array(SurgeAPI::Models::MessageParams::MessageParamsWithConversation, SurgeAPI::Models::MessageParams::SimpleMessageParams)]
+    end
+  end
+end

data/lib/surge_api/models/message_retrieve_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Messages#retrieve
+    class MessageRetrieveParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/unwrap_webhook_event.rb

@@ -5,23 +5,25 @@ module SurgeAPI
     module UnwrapWebhookEvent
       extend SurgeAPI::Internal::Type::Union
 
-      variant -> { SurgeAPI::CallEndedWebhookEvent }
+      discriminator :type
 
-      variant -> { SurgeAPI::CampaignApprovedWebhookEvent }
+      variant :"call.ended", -> { SurgeAPI::CallEndedWebhookEvent }
 
-      variant -> { SurgeAPI::ContactOptedInWebhookEvent }
+      variant :"campaign.approved", -> { SurgeAPI::CampaignApprovedWebhookEvent }
 
-      variant -> { SurgeAPI::ContactOptedOutWebhookEvent }
+      variant :"contact.opted_in", -> { SurgeAPI::ContactOptedInWebhookEvent }
 
-      variant -> { SurgeAPI::ConversationCreatedWebhookEvent }
+      variant :"contact.opted_out", -> { SurgeAPI::ContactOptedOutWebhookEvent }
 
-      variant -> { SurgeAPI::MessageDeliveredWebhookEvent }
+      variant :"conversation.created", -> { SurgeAPI::ConversationCreatedWebhookEvent }
 
-      variant -> { SurgeAPI::MessageFailedWebhookEvent }
+      variant :"message.delivered", -> { SurgeAPI::MessageDeliveredWebhookEvent }
 
-      variant -> { SurgeAPI::MessageReceivedWebhookEvent }
+      variant :"message.failed", -> { SurgeAPI::MessageFailedWebhookEvent }
 
-      variant -> { SurgeAPI::MessageSentWebhookEvent }
+      variant :"message.received", -> { SurgeAPI::MessageReceivedWebhookEvent }
+
+      variant :"message.sent", -> { SurgeAPI::MessageSentWebhookEvent }
 
       # @!method self.variants
       #   @return [Array(SurgeAPI::Models::CallEndedWebhookEvent, SurgeAPI::Models::CampaignApprovedWebhookEvent, SurgeAPI::Models::ContactOptedInWebhookEvent, SurgeAPI::Models::ContactOptedOutWebhookEvent, SurgeAPI::Models::ConversationCreatedWebhookEvent, SurgeAPI::Models::MessageDeliveredWebhookEvent, SurgeAPI::Models::MessageFailedWebhookEvent, SurgeAPI::Models::MessageReceivedWebhookEvent, SurgeAPI::Models::MessageSentWebhookEvent)]

data/lib/surge_api/models.rb

@@ -61,6 +61,8 @@ module SurgeAPI
 
   CampaignCreateParams = SurgeAPI::Models::CampaignCreateParams
 
+  CampaignParams = SurgeAPI::Models::CampaignParams
+
   Contact = SurgeAPI::Models::Contact
 
   ContactCreateParams = SurgeAPI::Models::ContactCreateParams
@@ -85,8 +87,12 @@ module SurgeAPI
 
   MessageFailedWebhookEvent = SurgeAPI::Models::MessageFailedWebhookEvent
 
+  MessageParams = SurgeAPI::Models::MessageParams
+
   MessageReceivedWebhookEvent = SurgeAPI::Models::MessageReceivedWebhookEvent
 
+  MessageRetrieveParams = SurgeAPI::Models::MessageRetrieveParams
+
   MessageSentWebhookEvent = SurgeAPI::Models::MessageSentWebhookEvent
 
   Organization = SurgeAPI::Models::Organization

data/lib/surge_api/resources/campaigns.rb

@@ -8,27 +8,11 @@ module SurgeAPI
       #
       # Creates a campaign to register account to send text messages.
       #
-      # @overload create(account_id, consent_flow:, description:, message_samples:, privacy_policy_url:, use_cases:, volume:, includes: nil, link_sample: nil, terms_and_conditions_url: nil, request_options: {})
+      # @overload create(account_id, campaign_params:, request_options: {})
       #
       # @param account_id [String] The account for which the campaign should be created.
       #
-      # @param consent_flow [String] A string explaining the method through which end users will opt in to receive me
-      #
-      # @param description [String] An explanation of the organization's purpose and how it will be using text messa
-      #
-      # @param message_samples [Array<String>] An array of 2-5 strings with examples of the messages that will be sent from thi
-      #
-      # @param privacy_policy_url [String] The URL of the privacy policy for the brand in question. This may be a shared pr
-      #
-      # @param use_cases [Array<Symbol, SurgeAPI::Models::CampaignCreateParams::UseCase>] A list containing 1-5 types of messages that will be sent with this campaign.
-      #
-      # @param volume [Symbol, SurgeAPI::Models::CampaignCreateParams::Volume] This will be one of the following:
-      #
-      # @param includes [Array<Symbol, SurgeAPI::Models::CampaignCreateParams::Include>] A list of properties that this campaign should include. These properties can be
-      #
-      # @param link_sample [String] A sample link that might be sent by this campaign. If links from other domains a
-      #
-      # @param terms_and_conditions_url [String] The URL of the terms and conditions presented to end users when they opt in to m
+      # @param campaign_params [SurgeAPI::CampaignParams] Parameters for creating a new campaign. Either provide full campaign details or
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -37,6 +21,11 @@ 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],

data/lib/surge_api/resources/messages.rb

@@ -32,21 +32,11 @@ module SurgeAPI
       # `conversation` field, and `conversation.phone_number` should be specified
       # instead.
       #
-      # @overload create(account_id, conversation:, to:, attachments: nil, body: nil, send_at: nil, from: nil, request_options: {})
+      # @overload create(account_id, message_params:, request_options: {})
       #
       # @param account_id [String] The account from which the message should be sent.
       #
-      # @param conversation [SurgeAPI::Models::MessageCreateParams::Conversation] Params for selecting or creating a new conversation. Either the id or the Contac
-      #
-      # @param to [String] The recipient's phone number in E.164 format. Cannot be used together with 'conv
-      #
-      # @param attachments [Array<SurgeAPI::Models::MessageCreateParams::Attachment>]
-      #
-      # @param body [String] The message body.
-      #
-      # @param send_at [Time] An optional datetime for scheduling message up to a couple of months in the futu
-      #
-      # @param from [String] The sender's phone number in E.164 format or phone number ID. If omitted, uses t
+      # @param message_params [SurgeAPI::MessageParams] Payload for creating a message. Either an attachment or the body must be given.
       #
       # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -55,6 +45,11 @@ 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],
@@ -64,6 +59,26 @@ module SurgeAPI
         )
       end
 
+      # Retrieves a Message object.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] The ID of the message to retrieve.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Message]
+      #
+      # @see SurgeAPI::Models::MessageRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["messages/%1$s", id],
+          model: SurgeAPI::Message,
+          options: params[:request_options]
+        )
+      end
+
       # @api private
       #
       # @param client [SurgeAPI::Client]

data/lib/surge_api/version.rb

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

data/lib/surge_api.rb

@@ -3,12 +3,14 @@
 # Standard libraries.
 # rubocop:disable Lint/RedundantRequireStatement
 require "English"
+require "base64"
 require "cgi"
 require "date"
 require "erb"
 require "etc"
 require "json"
 require "net/http"
+require "openssl"
 require "pathname"
 require "rbconfig"
 require "securerandom"
@@ -50,6 +52,8 @@ require_relative "surge_api/errors"
 require_relative "surge_api/internal/transport/base_client"
 require_relative "surge_api/internal/transport/pooled_net_requester"
 require_relative "surge_api/client"
+require_relative "surge_api/models/campaign_params"
+require_relative "surge_api/models/message_params"
 require_relative "surge_api/models/account"
 require_relative "surge_api/models/account_create_params"
 require_relative "surge_api/models/account_retrieve_status_params"
@@ -74,6 +78,7 @@ require_relative "surge_api/models/message_create_params"
 require_relative "surge_api/models/message_delivered_webhook_event"
 require_relative "surge_api/models/message_failed_webhook_event"
 require_relative "surge_api/models/message_received_webhook_event"
+require_relative "surge_api/models/message_retrieve_params"
 require_relative "surge_api/models/message_sent_webhook_event"
 require_relative "surge_api/models/organization"
 require_relative "surge_api/models/phone_number"

data/manifest.yaml

@@ -1,11 +1,13 @@
 dependencies:
   - English
+  - base64
   - cgi
   - date
   - erb
   - etc
   - json
   - net/http
+  - openssl
   - pathname
   - rbconfig
   - securerandom

data/rbi/surge_api/internal/transport/base_client.rbi

@@ -176,6 +176,11 @@ module SurgeAPI
         private def auth_headers
         end
 
+        # @api private
+        sig { returns(String) }
+        private def user_agent
+        end
+
         # @api private
         sig { returns(String) }
         private def generate_idempotency_key

data/rbi/surge_api/internal/transport/pooled_net_requester.rbi

@@ -26,8 +26,12 @@ module SurgeAPI
 
         class << self
           # @api private
-          sig { params(url: URI::Generic).returns(Net::HTTP) }
-          def connect(url)
+          sig do
+            params(cert_store: OpenSSL::X509::Store, url: URI::Generic).returns(
+              Net::HTTP
+            )
+          end
+          def connect(cert_store:, url:)
           end
 
           # @api private

data/rbi/surge_api/internal/type/base_model.rbi

@@ -31,7 +31,7 @@ module SurgeAPI
           #
           # Assumes superclass fields are totally defined before fields are accessed /
           # defined on subclasses.
-          sig { params(child: T.self_type).void }
+          sig { params(child: SurgeAPI::Internal::Type::BaseModel).void }
           def inherited(child)
           end
 
@@ -274,9 +274,13 @@ module SurgeAPI
 
         # Create a new instance of a model.
         sig do
-          params(data: T.any(T::Hash[Symbol, T.anything], T.self_type)).returns(
-            T.attached_class
-          )
+          params(
+            data:
+              T.any(
+                T::Hash[Symbol, T.anything],
+                SurgeAPI::Internal::Type::BaseModel
+              )
+          ).returns(T.attached_class)
         end
         def self.new(data = {})
         end

data/rbi/surge_api/models/account_create_params.rbi

@@ -112,8 +112,11 @@ module SurgeAPI
         end
         attr_writer :address
 
-        # An object representing an individual who can be contacted if the carriers have
-        # any questions about the business.
+        # An object representing an individual who can be contacted if Surge or our
+        # carrier partners have any questions about the business. If you are registering
+        # on behalf of your customer, this must be a contact from your customer's company
+        # rather than your own. The individual will likely never be contacted unless there
+        # are issues with spam.
         sig do
           returns(
             T.nilable(SurgeAPI::AccountCreateParams::Organization::Contact)
@@ -269,8 +272,11 @@ module SurgeAPI
         def self.new(
           # The address of the organization's headquarters.
           address: nil,
-          # An object representing an individual who can be contacted if the carriers have
-          # any questions about the business.
+          # An object representing an individual who can be contacted if Surge or our
+          # carrier partners have any questions about the business. If you are registering
+          # on behalf of your customer, this must be a contact from your customer's company
+          # rather than your own. The individual will likely never be contacted unless there
+          # are issues with spam.
           contact: nil,
           # The two character ISO 3166 country code for the country in which the
           # organization is headquartered.
@@ -455,7 +461,8 @@ module SurgeAPI
           # using the same domain name as the website URL will be preferred (e.g. with a
           # website domain of `https://dtprecisionauto.com`, an email like
           # `dom@dtprecisionauto.com` will be preferred over one like
-          # `dom@anothergarage.com` or `dom.toretto@gmail.com`)
+          # `dom@anothergarage.com` or `dom.toretto@gmail.com`. `dtprecisionauto@gmail.com`
+          # would also be acceptable, but not preferred)
           sig { returns(T.nilable(String)) }
           attr_accessor :email
 
@@ -486,8 +493,11 @@ module SurgeAPI
           sig { returns(T.nilable(String)) }
           attr_accessor :title_other
 
-          # An object representing an individual who can be contacted if the carriers have
-          # any questions about the business.
+          # An object representing an individual who can be contacted if Surge or our
+          # carrier partners have any questions about the business. If you are registering
+          # on behalf of your customer, this must be a contact from your customer's company
+          # rather than your own. The individual will likely never be contacted unless there
+          # are issues with spam.
           sig do
             params(
               email: T.nilable(String),
@@ -506,7 +516,8 @@ module SurgeAPI
             # using the same domain name as the website URL will be preferred (e.g. with a
             # website domain of `https://dtprecisionauto.com`, an email like
             # `dom@dtprecisionauto.com` will be preferred over one like
-            # `dom@anothergarage.com` or `dom.toretto@gmail.com`)
+            # `dom@anothergarage.com` or `dom.toretto@gmail.com`. `dtprecisionauto@gmail.com`
+            # would also be acceptable, but not preferred)
             email: nil,
             # The first name (or given name) of the individual
             first_name: nil,

data/rbi/surge_api/models/account_update_params.rbi

@@ -113,8 +113,11 @@ module SurgeAPI
         end
         attr_writer :address
 
-        # An object representing an individual who can be contacted if the carriers have
-        # any questions about the business.
+        # An object representing an individual who can be contacted if Surge or our
+        # carrier partners have any questions about the business. If you are registering
+        # on behalf of your customer, this must be a contact from your customer's company
+        # rather than your own. The individual will likely never be contacted unless there
+        # are issues with spam.
         sig do
           returns(
             T.nilable(SurgeAPI::AccountUpdateParams::Organization::Contact)
@@ -270,8 +273,11 @@ module SurgeAPI
         def self.new(
           # The address of the organization's headquarters.
           address: nil,
-          # An object representing an individual who can be contacted if the carriers have
-          # any questions about the business.
+          # An object representing an individual who can be contacted if Surge or our
+          # carrier partners have any questions about the business. If you are registering
+          # on behalf of your customer, this must be a contact from your customer's company
+          # rather than your own. The individual will likely never be contacted unless there
+          # are issues with spam.
           contact: nil,
           # The two character ISO 3166 country code for the country in which the
           # organization is headquartered.
@@ -456,7 +462,8 @@ module SurgeAPI
           # using the same domain name as the website URL will be preferred (e.g. with a
           # website domain of `https://dtprecisionauto.com`, an email like
           # `dom@dtprecisionauto.com` will be preferred over one like
-          # `dom@anothergarage.com` or `dom.toretto@gmail.com`)
+          # `dom@anothergarage.com` or `dom.toretto@gmail.com`. `dtprecisionauto@gmail.com`
+          # would also be acceptable, but not preferred)
           sig { returns(T.nilable(String)) }
           attr_accessor :email
 
@@ -487,8 +494,11 @@ module SurgeAPI
           sig { returns(T.nilable(String)) }
           attr_accessor :title_other
 
-          # An object representing an individual who can be contacted if the carriers have
-          # any questions about the business.
+          # An object representing an individual who can be contacted if Surge or our
+          # carrier partners have any questions about the business. If you are registering
+          # on behalf of your customer, this must be a contact from your customer's company
+          # rather than your own. The individual will likely never be contacted unless there
+          # are issues with spam.
           sig do
             params(
               email: T.nilable(String),
@@ -507,7 +517,8 @@ module SurgeAPI
             # using the same domain name as the website URL will be preferred (e.g. with a
             # website domain of `https://dtprecisionauto.com`, an email like
             # `dom@dtprecisionauto.com` will be preferred over one like
-            # `dom@anothergarage.com` or `dom.toretto@gmail.com`)
+            # `dom@anothergarage.com` or `dom.toretto@gmail.com`. `dtprecisionauto@gmail.com`
+            # would also be acceptable, but not preferred)
             email: nil,
             # The first name (or given name) of the individual
             first_name: nil,