surge_api 0.1.0 → 0.2.1

data/rbi/surge_api/models/message_params.rbi

@@ -0,0 +1,430 @@
+# typed: strong
+
+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
+
+      Variants =
+        T.type_alias do
+          T.any(
+            SurgeAPI::MessageParams::MessageParamsWithConversation,
+            SurgeAPI::MessageParams::SimpleMessageParams
+          )
+        end
+
+      class MessageParamsWithConversation < SurgeAPI::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              SurgeAPI::MessageParams::MessageParamsWithConversation,
+              SurgeAPI::Internal::AnyHash
+            )
+          end
+
+        # Params for selecting or creating a new conversation. Either the id or the
+        # Contact must be given.
+        sig do
+          returns(
+            SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation
+          )
+        end
+        attr_reader :conversation
+
+        sig do
+          params(
+            conversation:
+              SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::OrHash
+          ).void
+        end
+        attr_writer :conversation
+
+        sig do
+          returns(
+            T.nilable(
+              T::Array[
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment
+              ]
+            )
+          )
+        end
+        attr_reader :attachments
+
+        sig do
+          params(
+            attachments:
+              T::Array[
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment::OrHash
+              ]
+          ).void
+        end
+        attr_writer :attachments
+
+        # The message body.
+        sig { returns(T.nilable(String)) }
+        attr_reader :body
+
+        sig { params(body: String).void }
+        attr_writer :body
+
+        # An optional datetime for scheduling message up to a couple of months in the
+        # future.
+        sig { returns(T.nilable(Time)) }
+        attr_reader :send_at
+
+        sig { params(send_at: Time).void }
+        attr_writer :send_at
+
+        # Create a message while including parameters for the conversation in which the
+        # message should be sent.
+        sig do
+          params(
+            conversation:
+              SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::OrHash,
+            attachments:
+              T::Array[
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment::OrHash
+              ],
+            body: String,
+            send_at: Time
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Params for selecting or creating a new conversation. Either the id or the
+          # Contact must be given.
+          conversation:,
+          attachments: nil,
+          # The message body.
+          body: nil,
+          # An optional datetime for scheduling message up to a couple of months in the
+          # future.
+          send_at: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              conversation:
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation,
+              attachments:
+                T::Array[
+                  SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment
+                ],
+              body: String,
+              send_at: Time
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Conversation < SurgeAPI::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation,
+                SurgeAPI::Internal::AnyHash
+              )
+            end
+
+          # Parameters for creating a contact
+          sig do
+            returns(
+              SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact
+            )
+          end
+          attr_reader :contact
+
+          sig do
+            params(
+              contact:
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact::OrHash
+            ).void
+          end
+          attr_writer :contact
+
+          # 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.
+          sig { returns(T.nilable(String)) }
+          attr_reader :phone_number
+
+          sig { params(phone_number: String).void }
+          attr_writer :phone_number
+
+          # Params for selecting or creating a new conversation. Either the id or the
+          # Contact must be given.
+          sig do
+            params(
+              contact:
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact::OrHash,
+              phone_number: String
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Parameters for creating a contact
+            contact:,
+            # 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.
+            phone_number: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                contact:
+                  SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact,
+                phone_number: String
+              }
+            )
+          end
+          def to_hash
+          end
+
+          class Contact < SurgeAPI::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  SurgeAPI::MessageParams::MessageParamsWithConversation::Conversation::Contact,
+                  SurgeAPI::Internal::AnyHash
+                )
+              end
+
+            # The contact's phone number in E.164 format.
+            sig { returns(String) }
+            attr_accessor :phone_number
+
+            # The contact's email address.
+            sig { returns(T.nilable(String)) }
+            attr_reader :email
+
+            sig { params(email: String).void }
+            attr_writer :email
+
+            # The contact's first name.
+            sig { returns(T.nilable(String)) }
+            attr_reader :first_name
+
+            sig { params(first_name: String).void }
+            attr_writer :first_name
+
+            # The contact's last name.
+            sig { returns(T.nilable(String)) }
+            attr_reader :last_name
+
+            sig { params(last_name: String).void }
+            attr_writer :last_name
+
+            # Set of key-value pairs that will be stored with the object.
+            sig { returns(T.nilable(T::Hash[Symbol, String])) }
+            attr_reader :metadata
+
+            sig { params(metadata: T::Hash[Symbol, String]).void }
+            attr_writer :metadata
+
+            # Parameters for creating a contact
+            sig do
+              params(
+                phone_number: String,
+                email: String,
+                first_name: String,
+                last_name: String,
+                metadata: T::Hash[Symbol, String]
+              ).returns(T.attached_class)
+            end
+            def self.new(
+              # The contact's phone number in E.164 format.
+              phone_number:,
+              # The contact's email address.
+              email: nil,
+              # The contact's first name.
+              first_name: nil,
+              # The contact's last name.
+              last_name: nil,
+              # Set of key-value pairs that will be stored with the object.
+              metadata: nil
+            )
+            end
+
+            sig do
+              override.returns(
+                {
+                  phone_number: String,
+                  email: String,
+                  first_name: String,
+                  last_name: String,
+                  metadata: T::Hash[Symbol, String]
+                }
+              )
+            end
+            def to_hash
+            end
+          end
+        end
+
+        class Attachment < SurgeAPI::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                SurgeAPI::MessageParams::MessageParamsWithConversation::Attachment,
+                SurgeAPI::Internal::AnyHash
+              )
+            end
+
+          # The URL of the attachment.
+          sig { returns(String) }
+          attr_accessor :url
+
+          # Params for creating an attachment
+          sig { params(url: String).returns(T.attached_class) }
+          def self.new(
+            # The URL of the attachment.
+            url:
+          )
+          end
+
+          sig { override.returns({ url: String }) }
+          def to_hash
+          end
+        end
+      end
+
+      class SimpleMessageParams < SurgeAPI::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              SurgeAPI::MessageParams::SimpleMessageParams,
+              SurgeAPI::Internal::AnyHash
+            )
+          end
+
+        # The recipient's phone number in E.164 format. Cannot be used together with
+        # 'conversation'.
+        sig { returns(String) }
+        attr_accessor :to
+
+        sig do
+          returns(
+            T.nilable(
+              T::Array[SurgeAPI::MessageParams::SimpleMessageParams::Attachment]
+            )
+          )
+        end
+        attr_reader :attachments
+
+        sig do
+          params(
+            attachments:
+              T::Array[
+                SurgeAPI::MessageParams::SimpleMessageParams::Attachment::OrHash
+              ]
+          ).void
+        end
+        attr_writer :attachments
+
+        # The message body.
+        sig { returns(T.nilable(String)) }
+        attr_reader :body
+
+        sig { params(body: String).void }
+        attr_writer :body
+
+        # 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'.
+        sig { returns(T.nilable(String)) }
+        attr_reader :from
+
+        sig { params(from: String).void }
+        attr_writer :from
+
+        # An optional datetime for scheduling message up to a couple of months in the
+        # future.
+        sig { returns(T.nilable(Time)) }
+        attr_reader :send_at
+
+        sig { params(send_at: Time).void }
+        attr_writer :send_at
+
+        # Create a basic message by specifying just the to/from phone numbers.
+        sig do
+          params(
+            to: String,
+            attachments:
+              T::Array[
+                SurgeAPI::MessageParams::SimpleMessageParams::Attachment::OrHash
+              ],
+            body: String,
+            from: String,
+            send_at: Time
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The recipient's phone number in E.164 format. Cannot be used together with
+          # 'conversation'.
+          to:,
+          attachments: nil,
+          # The message body.
+          body: nil,
+          # 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'.
+          from: nil,
+          # An optional datetime for scheduling message up to a couple of months in the
+          # future.
+          send_at: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              to: String,
+              attachments:
+                T::Array[
+                  SurgeAPI::MessageParams::SimpleMessageParams::Attachment
+                ],
+              body: String,
+              from: String,
+              send_at: Time
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Attachment < SurgeAPI::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                SurgeAPI::MessageParams::SimpleMessageParams::Attachment,
+                SurgeAPI::Internal::AnyHash
+              )
+            end
+
+          # The URL of the attachment.
+          sig { returns(String) }
+          attr_accessor :url
+
+          # Params for creating an attachment
+          sig { params(url: String).returns(T.attached_class) }
+          def self.new(
+            # The URL of the attachment.
+            url:
+          )
+          end
+
+          sig { override.returns({ url: String }) }
+          def to_hash
+          end
+        end
+      end
+
+      sig { override.returns(T::Array[SurgeAPI::MessageParams::Variants]) }
+      def self.variants
+      end
+    end
+  end
+end

data/rbi/surge_api/models/unwrap_webhook_event.rbi

@@ -10,6 +10,8 @@ module SurgeAPI
           T.any(
             SurgeAPI::CallEndedWebhookEvent,
             SurgeAPI::CampaignApprovedWebhookEvent,
+            SurgeAPI::ContactOptedInWebhookEvent,
+            SurgeAPI::ContactOptedOutWebhookEvent,
             SurgeAPI::ConversationCreatedWebhookEvent,
             SurgeAPI::MessageDeliveredWebhookEvent,
             SurgeAPI::MessageFailedWebhookEvent,

data/rbi/surge_api/models.rbi

@@ -23,10 +23,16 @@ module SurgeAPI
 
   CampaignCreateParams = SurgeAPI::Models::CampaignCreateParams
 
+  CampaignParams = SurgeAPI::Models::CampaignParams
+
   Contact = SurgeAPI::Models::Contact
 
   ContactCreateParams = SurgeAPI::Models::ContactCreateParams
 
+  ContactOptedInWebhookEvent = SurgeAPI::Models::ContactOptedInWebhookEvent
+
+  ContactOptedOutWebhookEvent = SurgeAPI::Models::ContactOptedOutWebhookEvent
+
   ContactRetrieveParams = SurgeAPI::Models::ContactRetrieveParams
 
   ContactUpdateParams = SurgeAPI::Models::ContactUpdateParams
@@ -44,6 +50,8 @@ module SurgeAPI
 
   MessageFailedWebhookEvent = SurgeAPI::Models::MessageFailedWebhookEvent
 
+  MessageParams = SurgeAPI::Models::MessageParams
+
   MessageReceivedWebhookEvent = SurgeAPI::Models::MessageReceivedWebhookEvent
 
   MessageSentWebhookEvent = SurgeAPI::Models::MessageSentWebhookEvent

data/rbi/surge_api/resources/campaigns.rbi

@@ -7,101 +7,16 @@ module SurgeAPI
       sig do
         params(
           account_id: String,
-          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: SurgeAPI::CampaignParams,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(SurgeAPI::Campaign)
       end
       def create(
         # The account for which the campaign should be created.
         account_id,
-        # 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

data/rbi/surge_api/resources/messages.rbi

@@ -31,34 +31,17 @@ module SurgeAPI
       sig do
         params(
           account_id: String,
-          conversation: SurgeAPI::MessageCreateParams::Conversation::OrHash,
-          to: String,
-          attachments:
-            T::Array[SurgeAPI::MessageCreateParams::Attachment::OrHash],
-          body: String,
-          send_at: Time,
-          from: String,
+          message_params: SurgeAPI::MessageParams,
           request_options: SurgeAPI::RequestOptions::OrHash
         ).returns(SurgeAPI::Message)
       end
       def create(
         # The account from which the message should be sent.
         account_id,
-        # Params for selecting or creating a new conversation. Either the id or the
-        # Contact must be given.
-        conversation:,
-        # The recipient's phone number in E.164 format. Cannot be used together with
-        # 'conversation'.
-        to:,
-        attachments: nil,
-        # The message body.
-        body: nil,
-        # An optional datetime for scheduling message up to a couple of months in the
-        # future.
-        send_at: nil,
-        # 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'.
-        from: nil,
+        # 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.
+        message_params:,
         request_options: {}
       )
       end

data/rbi/surge_api/resources/webhooks.rbi

@@ -8,6 +8,8 @@ module SurgeAPI
           T.any(
             SurgeAPI::CallEndedWebhookEvent,
             SurgeAPI::CampaignApprovedWebhookEvent,
+            SurgeAPI::ContactOptedInWebhookEvent,
+            SurgeAPI::ContactOptedOutWebhookEvent,
             SurgeAPI::ConversationCreatedWebhookEvent,
             SurgeAPI::MessageDeliveredWebhookEvent,
             SurgeAPI::MessageFailedWebhookEvent,

data/sig/surge_api/file_part.rbs

@@ -14,7 +14,7 @@ module SurgeAPI
 
     def initialize: (
       Pathname | StringIO | IO | String content,
-      ?filename: String?,
+      ?filename: (Pathname | String)?,
       ?content_type: String?
     ) -> void
   end