surge_api 0.1.0

data/lib/surge_api/resources/contacts.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Contacts
+      # Creates a new Contact object.
+      #
+      # @overload create(account_id, phone_number:, email: nil, first_name: nil, last_name: nil, metadata: nil, request_options: {})
+      #
+      # @param account_id [String] The account for which the contact should be created.
+      #
+      # @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.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Contact]
+      #
+      # @see SurgeAPI::Models::ContactCreateParams
+      def create(account_id, params)
+        parsed, options = SurgeAPI::ContactCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["accounts/%1$s/contacts", account_id],
+          body: parsed,
+          model: SurgeAPI::Contact,
+          options: options
+        )
+      end
+
+      # Retrieves a Contact object.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] The ID of the contact to retrieve.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Contact]
+      #
+      # @see SurgeAPI::Models::ContactRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["contacts/%1$s", id],
+          model: SurgeAPI::Contact,
+          options: params[:request_options]
+        )
+      end
+
+      # Updates the specified contact by setting the values of the parameters passed.
+      # Any parameters not provided will be left unchanged.
+      #
+      # @overload update(id, phone_number:, email: nil, first_name: nil, last_name: nil, metadata: nil, request_options: {})
+      #
+      # @param id [String] The ID of the contact to update.
+      #
+      # @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.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Contact]
+      #
+      # @see SurgeAPI::Models::ContactUpdateParams
+      def update(id, params)
+        parsed, options = SurgeAPI::ContactUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["contacts/%1$s", id],
+          body: parsed,
+          model: SurgeAPI::Contact,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/messages.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Messages
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::MessageCreateParams} for more details.
+      #
+      # 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.
+      #
+      # @overload create(account_id, conversation:, to:, attachments: nil, body: nil, send_at: nil, from: nil, 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 request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Message]
+      #
+      # @see SurgeAPI::Models::MessageCreateParams
+      def create(account_id, params)
+        parsed, options = SurgeAPI::MessageCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["accounts/%1$s/messages", account_id],
+          body: parsed,
+          model: SurgeAPI::Message,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/phone_numbers.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class PhoneNumbers
+      # Some parameter documentations has been truncated, see
+      # {SurgeAPI::Models::PhoneNumberPurchaseParams} for more details.
+      #
+      # Purchase a new phone number for the account. You can specify search criteria or
+      # let the system select a random number.
+      #
+      # @overload purchase(account_id, area_code: nil, latitude: nil, longitude: nil, type: nil, request_options: {})
+      #
+      # @param account_id [String] The account for which the phone number should be created.
+      #
+      # @param area_code [String] The desired area code for this phone number. If provided without type, the type
+      #
+      # @param latitude [Float] Latitude to search for nearby phone numbers. Must be used with longitude. If pro
+      #
+      # @param longitude [Float] Longitude to search for nearby phone numbers. Must be used with latitude. If pro
+      #
+      # @param type [Symbol, SurgeAPI::Models::PhoneNumberPurchaseParams::Type] Whether the phone number is local or toll-free. Can be omitted if area_code or l
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::PhoneNumber]
+      #
+      # @see SurgeAPI::Models::PhoneNumberPurchaseParams
+      def purchase(account_id, params = {})
+        parsed, options = SurgeAPI::PhoneNumberPurchaseParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["accounts/%1$s/phone_numbers", account_id],
+          body: parsed,
+          model: SurgeAPI::PhoneNumber,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/users.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Users
+      # Creates a new User object.
+      #
+      # @overload create(account_id, first_name:, last_name: nil, metadata: nil, photo_url: nil, request_options: {})
+      #
+      # @param account_id [String] The account for which the user should be created.
+      #
+      # @param first_name [String] The user's first name.
+      #
+      # @param last_name [String] The user's last name.
+      #
+      # @param metadata [Hash{Symbol=>String}] Set of key-value pairs that will be stored with the object.
+      #
+      # @param photo_url [String] URL of a photo to be used as the user's avatar.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::User]
+      #
+      # @see SurgeAPI::Models::UserCreateParams
+      def create(account_id, params)
+        parsed, options = SurgeAPI::UserCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["accounts/%1$s/users", account_id],
+          body: parsed,
+          model: SurgeAPI::User,
+          options: options
+        )
+      end
+
+      # Retrieves a User object.
+      #
+      # @overload retrieve(id, request_options: {})
+      #
+      # @param id [String] The ID of the user to retrieve.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::User]
+      #
+      # @see SurgeAPI::Models::UserRetrieveParams
+      def retrieve(id, params = {})
+        @client.request(
+          method: :get,
+          path: ["users/%1$s", id],
+          model: SurgeAPI::User,
+          options: params[:request_options]
+        )
+      end
+
+      # Updates an existing User object.
+      #
+      # @overload update(id, first_name:, last_name: nil, metadata: nil, photo_url: nil, request_options: {})
+      #
+      # @param id [String] The ID of the user to update.
+      #
+      # @param first_name [String] The user's first name.
+      #
+      # @param last_name [String] The user's last name.
+      #
+      # @param metadata [Hash{Symbol=>String}] Set of key-value pairs that will be stored with the object.
+      #
+      # @param photo_url [String] URL of a photo to be used as the user's avatar.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::User]
+      #
+      # @see SurgeAPI::Models::UserUpdateParams
+      def update(id, params)
+        parsed, options = SurgeAPI::UserUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["users/%1$s", id],
+          body: parsed,
+          model: SurgeAPI::User,
+          options: options
+        )
+      end
+
+      # Provides a mechanism for having Surge create a signed token for embeds instead
+      # of signing with your own signing key.
+      #
+      # @overload create_token(user_id, duration_seconds: nil, request_options: {})
+      #
+      # @param user_id [String] The user for which the token represents authentication.
+      #
+      # @param duration_seconds [Integer] For how many seconds the token should be accepted. Defaults to 15 minutes.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::UserTokenResponse]
+      #
+      # @see SurgeAPI::Models::UserCreateTokenParams
+      def create_token(user_id, params = {})
+        parsed, options = SurgeAPI::UserCreateTokenParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["users/%1$s/tokens", user_id],
+          body: parsed,
+          model: SurgeAPI::UserTokenResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/verifications.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Verifications
+      # Creates a new Verification and sends the code to the given phone number.
+      #
+      # @overload create(phone_number:, request_options: {})
+      #
+      # @param phone_number [String] The phone number to be verified. In E.164 format.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::Verification]
+      #
+      # @see SurgeAPI::Models::VerificationCreateParams
+      def create(params)
+        parsed, options = SurgeAPI::VerificationCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "verifications",
+          body: parsed,
+          model: SurgeAPI::Verification,
+          options: options
+        )
+      end
+
+      # Checks the code against a verification.
+      #
+      # @overload check(id, code:, request_options: {})
+      #
+      # @param id [String] The ID of the verification to check against.
+      #
+      # @param code [String] The Verification code that was received.
+      #
+      # @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [SurgeAPI::Models::VerificationCheck]
+      #
+      # @see SurgeAPI::Models::VerificationCheckParams
+      def check(id, params)
+        parsed, options = SurgeAPI::VerificationCheckParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["verifications/%1$s/checks", id],
+          body: parsed,
+          model: SurgeAPI::VerificationCheck,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/resources/webhooks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Resources
+    class Webhooks
+      # @param payload [String] The raw webhook payload as a string
+      #
+      # @return [SurgeAPI::Models::CallEndedWebhookEvent, SurgeAPI::Models::CampaignApprovedWebhookEvent, SurgeAPI::Models::ConversationCreatedWebhookEvent, SurgeAPI::Models::MessageDeliveredWebhookEvent, SurgeAPI::Models::MessageFailedWebhookEvent, SurgeAPI::Models::MessageReceivedWebhookEvent, SurgeAPI::Models::MessageSentWebhookEvent]
+      def unwrap(payload)
+        parsed = JSON.parse(payload, symbolize_names: true)
+        SurgeAPI::Internal::Type::Converter.coerce(SurgeAPI::Models::UnwrapWebhookEvent, parsed)
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/surge_api/version.rb

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

data/lib/surge_api.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
+require "English"
+require "cgi"
+require "date"
+require "erb"
+require "etc"
+require "json"
+require "net/http"
+require "pathname"
+require "rbconfig"
+require "securerandom"
+require "set"
+require "stringio"
+require "time"
+require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
+
+# We already ship the preferred sorbet manifests in the package itself.
+# `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
+if Object.const_defined?(:Tapioca) &&
+   caller.chain([$PROGRAM_NAME]).chain(ARGV).any?(/tapioca/) &&
+   ARGV.none?(/dsl/)
+  return
+end
+
+# Gems.
+require "connection_pool"
+
+# Package files.
+require_relative "surge_api/version"
+require_relative "surge_api/internal/util"
+require_relative "surge_api/internal/type/converter"
+require_relative "surge_api/internal/type/unknown"
+require_relative "surge_api/internal/type/boolean"
+require_relative "surge_api/internal/type/file_input"
+require_relative "surge_api/internal/type/enum"
+require_relative "surge_api/internal/type/union"
+require_relative "surge_api/internal/type/array_of"
+require_relative "surge_api/internal/type/hash_of"
+require_relative "surge_api/internal/type/base_model"
+require_relative "surge_api/internal/type/base_page"
+require_relative "surge_api/internal/type/request_parameters"
+require_relative "surge_api/internal"
+require_relative "surge_api/request_options"
+require_relative "surge_api/file_part"
+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/account"
+require_relative "surge_api/models/account_create_params"
+require_relative "surge_api/models/account_retrieve_status_params"
+require_relative "surge_api/models/account_status"
+require_relative "surge_api/models/account_update_params"
+require_relative "surge_api/models/blast"
+require_relative "surge_api/models/blast_create_params"
+require_relative "surge_api/models/call_ended_webhook_event"
+require_relative "surge_api/models/campaign"
+require_relative "surge_api/models/campaign_approved_webhook_event"
+require_relative "surge_api/models/campaign_create_params"
+require_relative "surge_api/models/contact"
+require_relative "surge_api/models/contact_create_params"
+require_relative "surge_api/models/contact_retrieve_params"
+require_relative "surge_api/models/contact_update_params"
+require_relative "surge_api/models/conversation_created_webhook_event"
+require_relative "surge_api/models/error"
+require_relative "surge_api/models/message"
+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_sent_webhook_event"
+require_relative "surge_api/models/organization"
+require_relative "surge_api/models/phone_number"
+require_relative "surge_api/models/phone_number_purchase_params"
+require_relative "surge_api/models/unwrap_webhook_event"
+require_relative "surge_api/models/user"
+require_relative "surge_api/models/user_create_params"
+require_relative "surge_api/models/user_create_token_params"
+require_relative "surge_api/models/user_retrieve_params"
+require_relative "surge_api/models/user_token_response"
+require_relative "surge_api/models/user_update_params"
+require_relative "surge_api/models/verification"
+require_relative "surge_api/models/verification_check"
+require_relative "surge_api/models/verification_check_params"
+require_relative "surge_api/models/verification_create_params"
+require_relative "surge_api/models/webhook_unwrap_params"
+require_relative "surge_api/models"
+require_relative "surge_api/resources/accounts"
+require_relative "surge_api/resources/blasts"
+require_relative "surge_api/resources/campaigns"
+require_relative "surge_api/resources/contacts"
+require_relative "surge_api/resources/messages"
+require_relative "surge_api/resources/phone_numbers"
+require_relative "surge_api/resources/users"
+require_relative "surge_api/resources/verifications"
+require_relative "surge_api/resources/webhooks"

data/manifest.yaml

@@ -0,0 +1,15 @@
+dependencies:
+  - English
+  - cgi
+  - date
+  - erb
+  - etc
+  - json
+  - net/http
+  - pathname
+  - rbconfig
+  - securerandom
+  - set
+  - stringio
+  - time
+  - uri

data/rbi/surge_api/client.rbi

@@ -0,0 +1,73 @@
+# typed: strong
+
+module SurgeAPI
+  class Client < SurgeAPI::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES = 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS = T.let(60.0, Float)
+
+    DEFAULT_INITIAL_RETRY_DELAY = T.let(0.5, Float)
+
+    DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
+
+    sig { returns(String) }
+    attr_reader :api_key
+
+    sig { returns(SurgeAPI::Resources::Accounts) }
+    attr_reader :accounts
+
+    sig { returns(SurgeAPI::Resources::Blasts) }
+    attr_reader :blasts
+
+    sig { returns(SurgeAPI::Resources::Campaigns) }
+    attr_reader :campaigns
+
+    sig { returns(SurgeAPI::Resources::Contacts) }
+    attr_reader :contacts
+
+    sig { returns(SurgeAPI::Resources::Messages) }
+    attr_reader :messages
+
+    sig { returns(SurgeAPI::Resources::PhoneNumbers) }
+    attr_reader :phone_numbers
+
+    sig { returns(SurgeAPI::Resources::Users) }
+    attr_reader :users
+
+    sig { returns(SurgeAPI::Resources::Verifications) }
+    attr_reader :verifications
+
+    sig { returns(SurgeAPI::Resources::Webhooks) }
+    attr_reader :webhooks
+
+    # @api private
+    sig { override.returns(T::Hash[String, String]) }
+    private def auth_headers
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    sig do
+      params(
+        api_key: T.nilable(String),
+        base_url: T.nilable(String),
+        max_retries: Integer,
+        timeout: Float,
+        initial_retry_delay: Float,
+        max_retry_delay: Float
+      ).returns(T.attached_class)
+    end
+    def self.new(
+      # Defaults to `ENV["SURGE_API_KEY"]`
+      api_key: ENV["SURGE_API_KEY"],
+      # Override the default base URL for the API, e.g.,
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["SURGE_BASE_URL"]`
+      base_url: ENV["SURGE_BASE_URL"],
+      # Max number of retries to attempt after a failed retryable request.
+      max_retries: SurgeAPI::Client::DEFAULT_MAX_RETRIES,
+      timeout: SurgeAPI::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: SurgeAPI::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: SurgeAPI::Client::DEFAULT_MAX_RETRY_DELAY
+    )
+    end
+  end
+end