surge_api 0.1.0

data/rbi/surge_api/resources/messages.rbi

@@ -0,0 +1,72 @@
+# typed: strong
+
+module SurgeAPI
+  module Resources
+    class Messages
+      # Creates and enqueues a new message to be sent.
+      #
+      # Messages are always sent asynchronously. When you hit this endpoint, the message
+      # will be created within Surge's system and enqueued for sending, and then the id
+      # for the new message will be returned. When the message is actually sent, a
+      # `message.sent` webhook event will be triggered and sent to any webhook endpoints
+      # that you have subscribed to this event type. Then a `message.delivered` webhook
+      # event will be triggered when the carrier sends us a delivery receipt.
+      #
+      # By default all messages will be sent immediately. If you would like to schedule
+      # sending for some time up to 60 days in the future, you can do that by providing
+      # a value for the `send_at` field. This should be formatted as an ISO8601 datetime
+      # like `2028-10-14T18:06:00Z`.
+      #
+      # You must include either a `body` or `attachments` field (or both) in the request
+      # body. The `body` field should contain the text of the message you want to send,
+      # and the `attachments` field should be an array of objects with a `url` field
+      # pointing to the file you want to attach. Surge will download these files and
+      # send them as attachments in the message.
+      #
+      # You can provide either a `conversation` object or a `to` field to specify the
+      # intended recipient of the message, but an error will be returned if both fields
+      # are provided. Similarly the `from` field cannot be used together with the
+      # `conversation` field, and `conversation.phone_number` should be specified
+      # instead.
+      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,
+          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,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: SurgeAPI::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/surge_api/resources/phone_numbers.rbi

@@ -0,0 +1,43 @@
+# typed: strong
+
+module SurgeAPI
+  module Resources
+    class PhoneNumbers
+      # Purchase a new phone number for the account. You can specify search criteria or
+      # let the system select a random number.
+      sig do
+        params(
+          account_id: String,
+          area_code: String,
+          latitude: Float,
+          longitude: Float,
+          type: SurgeAPI::PhoneNumberPurchaseParams::Type::OrSymbol,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::PhoneNumber)
+      end
+      def purchase(
+        # The account for which the phone number should be created.
+        account_id,
+        # The desired area code for this phone number. If provided without type, the type
+        # will be inferred.
+        area_code: nil,
+        # Latitude to search for nearby phone numbers. Must be used with longitude. If
+        # provided without type, type will be inferred as 'local'.
+        latitude: nil,
+        # Longitude to search for nearby phone numbers. Must be used with latitude. If
+        # provided without type, type will be inferred as 'local'.
+        longitude: nil,
+        # Whether the phone number is local or toll-free. Can be omitted if area_code or
+        # latitude/longitude are provided.
+        type: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: SurgeAPI::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/surge_api/resources/users.rbi

@@ -0,0 +1,96 @@
+# typed: strong
+
+module SurgeAPI
+  module Resources
+    class Users
+      # Creates a new User object.
+      sig do
+        params(
+          account_id: String,
+          first_name: String,
+          last_name: String,
+          metadata: T::Hash[Symbol, String],
+          photo_url: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::User)
+      end
+      def create(
+        # The account for which the user should be created.
+        account_id,
+        # The user's first name.
+        first_name:,
+        # The user's last name.
+        last_name: nil,
+        # Set of key-value pairs that will be stored with the object.
+        metadata: nil,
+        # URL of a photo to be used as the user's avatar.
+        photo_url: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieves a User object.
+      sig do
+        params(
+          id: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::User)
+      end
+      def retrieve(
+        # The ID of the user to retrieve.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Updates an existing User object.
+      sig do
+        params(
+          id: String,
+          first_name: String,
+          last_name: String,
+          metadata: T::Hash[Symbol, String],
+          photo_url: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::User)
+      end
+      def update(
+        # The ID of the user to update.
+        id,
+        # The user's first name.
+        first_name:,
+        # The user's last name.
+        last_name: nil,
+        # Set of key-value pairs that will be stored with the object.
+        metadata: nil,
+        # URL of a photo to be used as the user's avatar.
+        photo_url: nil,
+        request_options: {}
+      )
+      end
+
+      # Provides a mechanism for having Surge create a signed token for embeds instead
+      # of signing with your own signing key.
+      sig do
+        params(
+          user_id: String,
+          duration_seconds: Integer,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::UserTokenResponse)
+      end
+      def create_token(
+        # The user for which the token represents authentication.
+        user_id,
+        # For how many seconds the token should be accepted. Defaults to 15 minutes.
+        duration_seconds: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: SurgeAPI::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/surge_api/resources/verifications.rbi

@@ -0,0 +1,43 @@
+# typed: strong
+
+module SurgeAPI
+  module Resources
+    class Verifications
+      # Creates a new Verification and sends the code to the given phone number.
+      sig do
+        params(
+          phone_number: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::Verification)
+      end
+      def create(
+        # The phone number to be verified. In E.164 format.
+        phone_number:,
+        request_options: {}
+      )
+      end
+
+      # Checks the code against a verification.
+      sig do
+        params(
+          id: String,
+          code: String,
+          request_options: SurgeAPI::RequestOptions::OrHash
+        ).returns(SurgeAPI::VerificationCheck)
+      end
+      def check(
+        # The ID of the verification to check against.
+        id,
+        # The Verification code that was received.
+        code:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: SurgeAPI::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/surge_api/resources/webhooks.rbi

@@ -0,0 +1,31 @@
+# typed: strong
+
+module SurgeAPI
+  module Resources
+    class Webhooks
+      sig do
+        params(payload: String).returns(
+          T.any(
+            SurgeAPI::CallEndedWebhookEvent,
+            SurgeAPI::CampaignApprovedWebhookEvent,
+            SurgeAPI::ConversationCreatedWebhookEvent,
+            SurgeAPI::MessageDeliveredWebhookEvent,
+            SurgeAPI::MessageFailedWebhookEvent,
+            SurgeAPI::MessageReceivedWebhookEvent,
+            SurgeAPI::MessageSentWebhookEvent
+          )
+        )
+      end
+      def unwrap(
+        # The raw webhook payload as a string
+        payload
+      )
+      end
+
+      # @api private
+      sig { params(client: SurgeAPI::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/surge_api/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module SurgeAPI
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/surge_api/client.rbs

@@ -0,0 +1,42 @@
+module SurgeAPI
+  class Client < SurgeAPI::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String
+
+    attr_reader accounts: SurgeAPI::Resources::Accounts
+
+    attr_reader blasts: SurgeAPI::Resources::Blasts
+
+    attr_reader campaigns: SurgeAPI::Resources::Campaigns
+
+    attr_reader contacts: SurgeAPI::Resources::Contacts
+
+    attr_reader messages: SurgeAPI::Resources::Messages
+
+    attr_reader phone_numbers: SurgeAPI::Resources::PhoneNumbers
+
+    attr_reader users: SurgeAPI::Resources::Users
+
+    attr_reader verifications: SurgeAPI::Resources::Verifications
+
+    attr_reader webhooks: SurgeAPI::Resources::Webhooks
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/surge_api/errors.rbs

@@ -0,0 +1,117 @@
+module SurgeAPI
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < SurgeAPI::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < SurgeAPI::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < SurgeAPI::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < SurgeAPI::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < SurgeAPI::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < SurgeAPI::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/surge_api/file_part.rbs

@@ -0,0 +1,21 @@
+module SurgeAPI
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: String?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/surge_api/internal/transport/base_client.rbs

@@ -0,0 +1,131 @@
+module SurgeAPI
+  module Internal
+    module Transport
+      class BaseClient
+        extend SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        type request_components =
+          {
+            method: Symbol,
+            path: String | ::Array[String],
+            query: ::Hash[String, (::Array[String] | String)?]?,
+            headers: ::Hash[String, (String
+            | Integer
+            | ::Array[(String | Integer)?])?]?,
+            body: top?,
+            unwrap: (Symbol
+            | Integer
+            | ::Array[(Symbol | Integer)]
+            | (^(top arg0) -> top))?,
+            page: Class?,
+            stream: Class?,
+            model: SurgeAPI::Internal::Type::Converter::input?,
+            options: SurgeAPI::request_opts?
+          }
+        type request_input =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            max_retries: Integer,
+            timeout: Float
+          }
+
+        MAX_REDIRECTS: 20
+
+        PLATFORM_HEADERS: ::Hash[String, String]
+
+        def self.validate!: (
+          SurgeAPI::Internal::Transport::BaseClient::request_components req
+        ) -> void
+
+        def self.should_retry?: (
+          Integer status,
+          headers: ::Hash[String, String]
+        ) -> bool
+
+        def self.follow_redirect: (
+          SurgeAPI::Internal::Transport::BaseClient::request_input request,
+          status: Integer,
+          response_headers: ::Hash[String, String]
+        ) -> SurgeAPI::Internal::Transport::BaseClient::request_input
+
+        def self.reap_connection!: (
+          Integer | SurgeAPI::Errors::APIConnectionError status,
+          stream: Enumerable[String]?
+        ) -> void
+
+        attr_reader base_url: URI::Generic
+
+        attr_reader timeout: Float
+
+        attr_reader max_retries: Integer
+
+        attr_reader initial_retry_delay: Float
+
+        attr_reader max_retry_delay: Float
+
+        attr_reader headers: ::Hash[String, String]
+
+        attr_reader idempotency_header: String?
+
+        # @api private
+        attr_reader requester: SurgeAPI::Internal::Transport::PooledNetRequester
+
+        def initialize: (
+          base_url: String,
+          ?timeout: Float,
+          ?max_retries: Integer,
+          ?initial_retry_delay: Float,
+          ?max_retry_delay: Float,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?],
+          ?idempotency_header: String?
+        ) -> void
+
+        private def auth_headers: -> ::Hash[String, String]
+
+        private def generate_idempotency_key: -> String
+
+        private def build_request: (
+          SurgeAPI::Internal::Transport::BaseClient::request_components req,
+          SurgeAPI::request_options opts
+        ) -> SurgeAPI::Internal::Transport::BaseClient::request_input
+
+        private def retry_delay: (
+          ::Hash[String, String] headers,
+          retry_count: Integer
+        ) -> Float
+
+        def send_request: (
+          SurgeAPI::Internal::Transport::BaseClient::request_input request,
+          redirect_count: Integer,
+          retry_count: Integer,
+          send_retry_header: bool
+        ) -> [Integer, top, Enumerable[String]]
+
+        def request: (
+          Symbol method,
+          String | ::Array[String] path,
+          ?query: ::Hash[String, (::Array[String] | String)?]?,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?]?,
+          ?body: top?,
+          ?unwrap: (Symbol
+          | Integer
+          | ::Array[(Symbol | Integer)]
+          | (^(top arg0) -> top))?,
+          ?page: Class?,
+          ?stream: Class?,
+          ?model: SurgeAPI::Internal::Type::Converter::input?,
+          ?options: SurgeAPI::request_opts?
+        ) -> top
+
+        def inspect: -> String
+      end
+    end
+  end
+end

data/sig/surge_api/internal/transport/pooled_net_requester.rbs

@@ -0,0 +1,45 @@
+module SurgeAPI
+  module Internal
+    module Transport
+      class PooledNetRequester
+        extend SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        type request =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            deadline: Float
+          }
+
+        KEEP_ALIVE_TIMEOUT: 30
+
+        DEFAULT_MAX_CONNECTIONS: Integer
+
+        def self.connect: (URI::Generic url) -> top
+
+        def self.calibrate_socket_timeout: (top conn, Float deadline) -> void
+
+        def self.build_request: (
+          SurgeAPI::Internal::Transport::PooledNetRequester::request request
+        ) {
+          (String arg0) -> void
+        } -> [top, (^-> void)]
+
+        private def with_pool: (
+          URI::Generic url,
+          deadline: Float
+        ) {
+          (top arg0) -> void
+        } -> void
+
+        def execute: (
+          SurgeAPI::Internal::Transport::PooledNetRequester::request request
+        ) -> [Integer, top, Enumerable[String]]
+
+        def initialize: (?size: Integer) -> void
+      end
+    end
+  end
+end

data/sig/surge_api/internal/type/array_of.rbs

@@ -0,0 +1,48 @@
+module SurgeAPI
+  module Internal
+    module Type
+      class ArrayOf[Elem]
+        include SurgeAPI::Internal::Type::Converter
+        include SurgeAPI::Internal::Util::SorbetRuntimeSupport
+
+        def self.[]: (
+          ::Hash[Symbol, top]
+          | ^-> SurgeAPI::Internal::Type::Converter::input
+          | SurgeAPI::Internal::Type::Converter::input type_info,
+          ?::Hash[Symbol, top] spec
+        ) -> instance
+
+        def ===: (top other) -> bool
+
+        def ==: (top other) -> bool
+
+        def hash: -> Integer
+
+        def coerce: (
+          ::Array[top] | top value,
+          state: SurgeAPI::Internal::Type::Converter::coerce_state
+        ) -> (::Array[top] | top)
+
+        def dump: (
+          ::Array[top] | top value,
+          state: SurgeAPI::Internal::Type::Converter::dump_state
+        ) -> (::Array[top] | top)
+
+        def to_sorbet_type: -> top
+
+        def item_type: -> Elem
+
+        def nilable?: -> bool
+
+        def initialize: (
+          ::Hash[Symbol, top]
+          | ^-> SurgeAPI::Internal::Type::Converter::input
+          | SurgeAPI::Internal::Type::Converter::input type_info,
+          ?::Hash[Symbol, top] spec
+        ) -> void
+
+        def inspect: (?depth: Integer) -> String
+      end
+    end
+  end
+end