surge_api 0.2.0 → 0.2.1

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],

data/lib/surge_api/version.rb

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

data/lib/surge_api.rb

@@ -50,6 +50,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"

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,

data/rbi/surge_api/models/campaign_create_params.rbi

@@ -11,217 +11,32 @@ module SurgeAPI
           T.any(SurgeAPI::CampaignCreateParams, SurgeAPI::Internal::AnyHash)
         end
 
-      # A string explaining the method through which end users will opt in to receive
-      # messages from the brand. Typically this should include URLs for opt-in forms or
-      # screenshots that might be helpful in explaining the flow to someone unfamiliar
-      # with the organization's purpose.
-      sig { returns(String) }
-      attr_accessor :consent_flow
-
-      # An explanation of the organization's purpose and how it will be using text
-      # messaging to accomplish that purpose.
-      sig { returns(String) }
-      attr_accessor :description
-
-      # An array of 2-5 strings with examples of the messages that will be sent from
-      # this campaign. Typically the first sample should be a compliance message like
-      # `You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out.`
-      # These samples don't necessarily need to be the only templates that will be used
-      # for the campaign, but they should reflect the purpose of the messages that will
-      # be sent. Any variable content can be reflected by wrapping it in square brackets
-      # like `[customer name]`.
-      sig { returns(T::Array[String]) }
-      attr_accessor :message_samples
-
-      # The URL of the privacy policy for the brand in question. This may be a shared
-      # privacy policy if it's the policy that is displayed to end users when they opt
-      # in to messaging.
-      sig { returns(String) }
-      attr_accessor :privacy_policy_url
-
-      # A list containing 1-5 types of messages that will be sent with this campaign.
-      #
-      # The following use cases are typically available to all brands:
-      #
-      # - `account_notification` - For sending reminders, alerts, and general
-      #   account-related notifications like booking confirmations or appointment
-      #   reminders.
-      # - `customer_care` - For account support, troubleshooting, and general customer
-      #   service communication.
-      # - `delivery_notification` - For notifying customers about the status of product
-      #   or service deliveries.
-      # - `fraud_alert` - For warning customers about suspicious or potentially
-      #   fraudulent activity.
-      # - `higher_education` - For messaging related to colleges, universities, and
-      #   school districts outside of K–12.
-      # - `marketing` - For promotional or advertising messages intended to market
-      #   products or services.
-      # - `polling_voting` - For conducting surveys, polls, or voting-related messaging.
-      # - `public_service_announcement` - For raising awareness about social issues or
-      #   important public information.
-      # - `security_alert` - For alerts related to potential security breaches or
-      #   compromised systems requiring user action.
-      # - `two_factor_authentication` - For sending one-time passwords or verification
-      #   codes for login or password reset.
-      #
-      # For access to special use cases not shown here, reach out to support@surge.app.
-      sig do
-        returns(T::Array[SurgeAPI::CampaignCreateParams::UseCase::OrSymbol])
-      end
-      attr_accessor :use_cases
-
-      # This will be one of the following:
-      #
-      # - `low` - The campaign will be allowed to send up to 2000 SMS segments to
-      #   T-Mobile customers each day. In this case your platform will be charged for
-      #   the setup fee for a low volume number upon receipt of the API request.
-      # - `high` - The campaign will be allowed to send up to 200k SMS segments to
-      #   T-Mobile customers each day, depending on the trust score assigned by The
-      #   Campaign Registry. Your platform will be charged for the setup fee for a high
-      #   volume number upon receipt of the API request, and phone numbers will be
-      #   charged as high volume numbers going forward.
-      sig { returns(SurgeAPI::CampaignCreateParams::Volume::OrSymbol) }
-      attr_accessor :volume
-
-      # A list of properties that this campaign should include. These properties can be
-      # any of the following values:
-      #
-      # - `links` - whether the campaign might send links in messages
-      # - `phone_numbers` - whether the campaign might send phone numbers in messages
-      # - `age_gated` - whether the campaign contains age gated content (controlled
-      #   substances or adult content)
-      # - `direct_lending` - whether the campaign contains content related to direct
-      #   lending or other loan arrangements
+      # Parameters for creating a new campaign. Either provide full campaign details or
+      # import using a TCR ID.
       sig do
         returns(
-          T.nilable(T::Array[SurgeAPI::CampaignCreateParams::Include::OrSymbol])
+          T.any(
+            SurgeAPI::CampaignParams::StandardCampaignParams,
+            SurgeAPI::CampaignParams::ExternalCampaignParams
+          )
         )
       end
-      attr_reader :includes
+      attr_accessor :campaign_params
 
       sig do
         params(
-          includes: T::Array[SurgeAPI::CampaignCreateParams::Include::OrSymbol]
-        ).void
-      end
-      attr_writer :includes
-
-      # A sample link that might be sent by this campaign. If links from other domains
-      # are sent through this campaign, they are much more likely to be filtered by the
-      # carriers. If link shortening is enabled for the account, the link shortener URL
-      # will be used instead of what is provided. Reach out to support if you would like
-      # to disable automatic link shortening.
-      sig { returns(T.nilable(String)) }
-      attr_reader :link_sample
-
-      sig { params(link_sample: String).void }
-      attr_writer :link_sample
-
-      # The URL of the terms and conditions presented to end users when they opt in to
-      # messaging. These terms and conditions may be shared among all of a platform's
-      # customers if they're the terms that are presented to end users when they opt in
-      # to messaging.
-      sig { returns(T.nilable(String)) }
-      attr_reader :terms_and_conditions_url
-
-      sig { params(terms_and_conditions_url: String).void }
-      attr_writer :terms_and_conditions_url
-
-      sig do
-        params(
-          consent_flow: String,
-          description: String,
-          message_samples: T::Array[String],
-          privacy_policy_url: String,
-          use_cases:
-            T::Array[SurgeAPI::CampaignCreateParams::UseCase::OrSymbol],
-          volume: SurgeAPI::CampaignCreateParams::Volume::OrSymbol,
-          includes: T::Array[SurgeAPI::CampaignCreateParams::Include::OrSymbol],
-          link_sample: String,
-          terms_and_conditions_url: String,
+          campaign_params:
+            T.any(
+              SurgeAPI::CampaignParams::StandardCampaignParams::OrHash,
+              SurgeAPI::CampaignParams::ExternalCampaignParams::OrHash
+            ),
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
-        # A string explaining the method through which end users will opt in to receive
-        # messages from the brand. Typically this should include URLs for opt-in forms or
-        # screenshots that might be helpful in explaining the flow to someone unfamiliar
-        # with the organization's purpose.
-        consent_flow:,
-        # An explanation of the organization's purpose and how it will be using text
-        # messaging to accomplish that purpose.
-        description:,
-        # An array of 2-5 strings with examples of the messages that will be sent from
-        # this campaign. Typically the first sample should be a compliance message like
-        # `You are now opted in to messages from {brand name}. Frequency varies. Msg&data rates apply. Reply STOP to opt out.`
-        # These samples don't necessarily need to be the only templates that will be used
-        # for the campaign, but they should reflect the purpose of the messages that will
-        # be sent. Any variable content can be reflected by wrapping it in square brackets
-        # like `[customer name]`.
-        message_samples:,
-        # The URL of the privacy policy for the brand in question. This may be a shared
-        # privacy policy if it's the policy that is displayed to end users when they opt
-        # in to messaging.
-        privacy_policy_url:,
-        # A list containing 1-5 types of messages that will be sent with this campaign.
-        #
-        # The following use cases are typically available to all brands:
-        #
-        # - `account_notification` - For sending reminders, alerts, and general
-        #   account-related notifications like booking confirmations or appointment
-        #   reminders.
-        # - `customer_care` - For account support, troubleshooting, and general customer
-        #   service communication.
-        # - `delivery_notification` - For notifying customers about the status of product
-        #   or service deliveries.
-        # - `fraud_alert` - For warning customers about suspicious or potentially
-        #   fraudulent activity.
-        # - `higher_education` - For messaging related to colleges, universities, and
-        #   school districts outside of K–12.
-        # - `marketing` - For promotional or advertising messages intended to market
-        #   products or services.
-        # - `polling_voting` - For conducting surveys, polls, or voting-related messaging.
-        # - `public_service_announcement` - For raising awareness about social issues or
-        #   important public information.
-        # - `security_alert` - For alerts related to potential security breaches or
-        #   compromised systems requiring user action.
-        # - `two_factor_authentication` - For sending one-time passwords or verification
-        #   codes for login or password reset.
-        #
-        # For access to special use cases not shown here, reach out to support@surge.app.
-        use_cases:,
-        # This will be one of the following:
-        #
-        # - `low` - The campaign will be allowed to send up to 2000 SMS segments to
-        #   T-Mobile customers each day. In this case your platform will be charged for
-        #   the setup fee for a low volume number upon receipt of the API request.
-        # - `high` - The campaign will be allowed to send up to 200k SMS segments to
-        #   T-Mobile customers each day, depending on the trust score assigned by The
-        #   Campaign Registry. Your platform will be charged for the setup fee for a high
-        #   volume number upon receipt of the API request, and phone numbers will be
-        #   charged as high volume numbers going forward.
-        volume:,
-        # A list of properties that this campaign should include. These properties can be
-        # any of the following values:
-        #
-        # - `links` - whether the campaign might send links in messages
-        # - `phone_numbers` - whether the campaign might send phone numbers in messages
-        # - `age_gated` - whether the campaign contains age gated content (controlled
-        #   substances or adult content)
-        # - `direct_lending` - whether the campaign contains content related to direct
-        #   lending or other loan arrangements
-        includes: nil,
-        # A sample link that might be sent by this campaign. If links from other domains
-        # are sent through this campaign, they are much more likely to be filtered by the
-        # carriers. If link shortening is enabled for the account, the link shortener URL
-        # will be used instead of what is provided. Reach out to support if you would like
-        # to disable automatic link shortening.
-        link_sample: nil,
-        # The URL of the terms and conditions presented to end users when they opt in to
-        # messaging. These terms and conditions may be shared among all of a platform's
-        # customers if they're the terms that are presented to end users when they opt in
-        # to messaging.
-        terms_and_conditions_url: nil,
+        # Parameters for creating a new campaign. Either provide full campaign details or
+        # import using a TCR ID.
+        campaign_params:,
         request_options: {}
       )
       end
@@ -229,158 +44,17 @@ module SurgeAPI
       sig do
         override.returns(
           {
-            consent_flow: String,
-            description: String,
-            message_samples: T::Array[String],
-            privacy_policy_url: String,
-            use_cases:
-              T::Array[SurgeAPI::CampaignCreateParams::UseCase::OrSymbol],
-            volume: SurgeAPI::CampaignCreateParams::Volume::OrSymbol,
-            includes:
-              T::Array[SurgeAPI::CampaignCreateParams::Include::OrSymbol],
-            link_sample: String,
-            terms_and_conditions_url: String,
+            campaign_params:
+              T.any(
+                SurgeAPI::CampaignParams::StandardCampaignParams,
+                SurgeAPI::CampaignParams::ExternalCampaignParams
+              ),
             request_options: SurgeAPI::RequestOptions
           }
         )
       end
       def to_hash
       end
-
-      module UseCase
-        extend SurgeAPI::Internal::Type::Enum
-
-        TaggedSymbol =
-          T.type_alias do
-            T.all(Symbol, SurgeAPI::CampaignCreateParams::UseCase)
-          end
-        OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-        ACCOUNT_NOTIFICATION =
-          T.let(
-            :account_notification,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        CUSTOMER_CARE =
-          T.let(
-            :customer_care,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        DELIVERY_NOTIFICATION =
-          T.let(
-            :delivery_notification,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        FRAUD_ALERT =
-          T.let(
-            :fraud_alert,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        HIGHER_EDUCATION =
-          T.let(
-            :higher_education,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        MARKETING =
-          T.let(
-            :marketing,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        POLLING_VOTING =
-          T.let(
-            :polling_voting,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        PUBLIC_SERVICE_ANNOUNCEMENT =
-          T.let(
-            :public_service_announcement,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        SECURITY_ALERT =
-          T.let(
-            :security_alert,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-        TWO_FACTOR_AUTHENTICATION =
-          T.let(
-            :two_factor_authentication,
-            SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol
-          )
-
-        sig do
-          override.returns(
-            T::Array[SurgeAPI::CampaignCreateParams::UseCase::TaggedSymbol]
-          )
-        end
-        def self.values
-        end
-      end
-
-      # This will be one of the following:
-      #
-      # - `low` - The campaign will be allowed to send up to 2000 SMS segments to
-      #   T-Mobile customers each day. In this case your platform will be charged for
-      #   the setup fee for a low volume number upon receipt of the API request.
-      # - `high` - The campaign will be allowed to send up to 200k SMS segments to
-      #   T-Mobile customers each day, depending on the trust score assigned by The
-      #   Campaign Registry. Your platform will be charged for the setup fee for a high
-      #   volume number upon receipt of the API request, and phone numbers will be
-      #   charged as high volume numbers going forward.
-      module Volume
-        extend SurgeAPI::Internal::Type::Enum
-
-        TaggedSymbol =
-          T.type_alias { T.all(Symbol, SurgeAPI::CampaignCreateParams::Volume) }
-        OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-        HIGH =
-          T.let(:high, SurgeAPI::CampaignCreateParams::Volume::TaggedSymbol)
-        LOW = T.let(:low, SurgeAPI::CampaignCreateParams::Volume::TaggedSymbol)
-
-        sig do
-          override.returns(
-            T::Array[SurgeAPI::CampaignCreateParams::Volume::TaggedSymbol]
-          )
-        end
-        def self.values
-        end
-      end
-
-      module Include
-        extend SurgeAPI::Internal::Type::Enum
-
-        TaggedSymbol =
-          T.type_alias do
-            T.all(Symbol, SurgeAPI::CampaignCreateParams::Include)
-          end
-        OrSymbol = T.type_alias { T.any(Symbol, String) }
-
-        LINKS =
-          T.let(:links, SurgeAPI::CampaignCreateParams::Include::TaggedSymbol)
-        PHONE_NUMBERS =
-          T.let(
-            :phone_numbers,
-            SurgeAPI::CampaignCreateParams::Include::TaggedSymbol
-          )
-        AGE_GATED =
-          T.let(
-            :age_gated,
-            SurgeAPI::CampaignCreateParams::Include::TaggedSymbol
-          )
-        DIRECT_LENDING =
-          T.let(
-            :direct_lending,
-            SurgeAPI::CampaignCreateParams::Include::TaggedSymbol
-          )
-
-        sig do
-          override.returns(
-            T::Array[SurgeAPI::CampaignCreateParams::Include::TaggedSymbol]
-          )
-        end
-        def self.values
-        end
-      end
     end
   end
 end