surge_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71252990f4c5eb46dec5222b3dd1307f1c347b59ef3a2c7a1aa6ac646555c920
-  data.tar.gz: 671de5440b15ba3455652ffcf8b8f0752c6e4827750a99dcb288bfa26cf65acd
+  metadata.gz: 3cdf5f24e69c710419d1609ebc934daaafd1be183603d3f364e6a3d4085fa9b9
+  data.tar.gz: 65ecd730b0df9e65ab06bd73a272bbff75e7f3b17c5136173ca26d48e92364bb
 SHA512:
-  metadata.gz: 4595e79a8c3fccbdf83430c0242b378b70acb7f52471a5177e9b78542889f310c62c8d5a6d41515a8cfd6ef72df9a298428274645b0b38f8f61eeb42ea0a3c57
-  data.tar.gz: 538a4232414a89f66dd781f0bda3a4e8257cdf9a88d7a07d3efef95345a26a93f895d696b54a6ff3c987f29fac2d62abda9e9c44532786d2e145d8b24c3da6b7
+  metadata.gz: 40416443213907937c15359db9fd573680ec1c0d6038a727304b632125d1331e765d980e4617afe0d80b98db12a1d7405bb3cd84d9b9be2a416ccda6ec9f7857
+  data.tar.gz: 20d73f3c32f237a86513ed84416b0ac144ff35f7ccd722bf57e79aa3a4fe44ee2525f91d523f67cd8b1b4819dfe3c3a9fe4b0f2c17cc56b280e2fe9f681d5386

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.3.0 (2025-12-17)
+
+Full Changelog: [v0.2.1...v0.3.0](https://github.com/surgeapi/ruby-sdk/compare/v0.2.1...v0.3.0)
+
+### Features
+
+* **api:** add retrieve message endpoint ([55df346](https://github.com/surgeapi/ruby-sdk/commit/55df346f91c99fece77d130057afc55b021666c7))
+
+
+### Bug Fixes
+
+* better thread safety via early initializing SSL store during HTTP client creation ([0d14e5e](https://github.com/surgeapi/ruby-sdk/commit/0d14e5e73496e95743359c4c8dbab6da1c384a6e))
+* calling `break` out of streams should be instantaneous ([b43c7e5](https://github.com/surgeapi/ruby-sdk/commit/b43c7e54e9dfaaf31ffa0fe498c53fcc51bbb81c))
+
+
+### Chores
+
+* bump dependency version and update sorbet types ([e00a588](https://github.com/surgeapi/ruby-sdk/commit/e00a5886df58170099838c7a2b1ba25fe36588d6))
+* explicitly require "base64" gem ([a25ee53](https://github.com/surgeapi/ruby-sdk/commit/a25ee53f821df6c2d177b0e41c864e15e4b8bae9))
+* **internal:** codegen related update ([744a068](https://github.com/surgeapi/ruby-sdk/commit/744a0682fa04890d445106232878d0d5be7d7273))
+
+## 0.2.1 (2025-10-31)
+
+Full Changelog: [v0.2.0...v0.2.1](https://github.com/surgeapi/ruby-sdk/compare/v0.2.0...v0.2.1)
+
+### Features
+
+* **api:** create externally registered campaigns ([c01b26e](https://github.com/surgeapi/ruby-sdk/commit/c01b26e3f26a8b827254d128a7c776d79850cbf5))
+* handle thread interrupts in the core HTTP client ([4362499](https://github.com/surgeapi/ruby-sdk/commit/43624993a62c67679d1f5260653517aebd5d687e))
+
+
+### Bug Fixes
+
+* absolutely qualified uris should always override the default ([58fa7be](https://github.com/surgeapi/ruby-sdk/commit/58fa7bea703edecd59fe69630191a9cb83ece9d0))
+* should not reuse buffers for `IO.copy_stream` interop ([52ce0fd](https://github.com/surgeapi/ruby-sdk/commit/52ce0fd6a7039be032e2f884636215ac1fb88223))
+
+
+### Documentation
+
+* **api:** add context around organization contacts ([88c764d](https://github.com/surgeapi/ruby-sdk/commit/88c764d18d70361d1a7f43e22a46d26082f24227))
+
 ## 0.2.0 (2025-10-09)
 
 Full Changelog: [v0.1.0...v0.2.0](https://github.com/surgeapi/ruby-sdk/compare/v0.1.0...v0.2.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "surge_api", "~> 0.2.0"
+gem "surge_api", "~> 0.3.0"
 ```
 
 <!-- x-release-please-end -->
@@ -32,12 +32,7 @@ surge = SurgeAPI::Client.new(
   api_key: ENV["SURGE_API_KEY"] # This is the default and can be omitted
 )
 
-message = surge.messages.create(
-  "acct_01j9a43avnfqzbjfch6pygv1td",
-  conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-  attachments: [{url: "https://toretto.family/coronas.gif"}],
-  body: "Thought you could leave without saying goodbye?"
-)
+message = surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td")
 
 puts(message.id)
 ```
@@ -48,12 +43,7 @@ When the library is unable to connect to the API, or if the API returns a non-su
 
 ```ruby
 begin
-  message = surge.messages.create(
-    "acct_01j9a43avnfqzbjfch6pygv1td",
-    conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-    attachments: [{url: "https://toretto.family/coronas.gif"}],
-    body: "Thought you could leave without saying goodbye?"
-  )
+  message = surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td")
 rescue SurgeAPI::Errors::APIConnectionError => e
   puts("The server could not be reached")
   puts(e.cause)  # an underlying Exception, likely raised within `net/http`
@@ -96,13 +86,7 @@ surge = SurgeAPI::Client.new(
 )
 
 # Or, configure per-request:
-surge.messages.create(
-  "acct_01j9a43avnfqzbjfch6pygv1td",
-  conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-  attachments: [{url: "https://toretto.family/coronas.gif"}],
-  body: "Thought you could leave without saying goodbye?",
-  request_options: {max_retries: 5}
-)
+surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td", request_options: {max_retries: 5})
 ```
 
 ### Timeouts
@@ -116,13 +100,7 @@ surge = SurgeAPI::Client.new(
 )
 
 # Or, configure per-request:
-surge.messages.create(
-  "acct_01j9a43avnfqzbjfch6pygv1td",
-  conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-  attachments: [{url: "https://toretto.family/coronas.gif"}],
-  body: "Thought you could leave without saying goodbye?",
-  request_options: {timeout: 5}
-)
+surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td", request_options: {timeout: 5})
 ```
 
 On timeout, `SurgeAPI::Errors::APITimeoutError` is raised.
@@ -155,9 +133,6 @@ Note: the `extra_` parameters of the same name overrides the documented paramete
 message =
   surge.messages.create(
     "acct_01j9a43avnfqzbjfch6pygv1td",
-    conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-    attachments: [{url: "https://toretto.family/coronas.gif"}],
-    body: "Thought you could leave without saying goodbye?",
     request_options: {
       extra_query: {my_query_parameter: value},
       extra_body: {my_body_parameter: value},
@@ -203,43 +178,17 @@ This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitio
 You can provide typesafe request parameters like so:
 
 ```ruby
-surge.messages.create(
-  "acct_01j9a43avnfqzbjfch6pygv1td",
-  conversation: SurgeAPI::MessageCreateParams::Conversation.new(
-    contact: SurgeAPI::MessageCreateParams::Conversation::Contact.new(
-      first_name: "Dom",
-      last_name: "Toretto",
-      phone_number: "+13235556439"
-    )
-  ),
-  attachments: [SurgeAPI::MessageCreateParams::Attachment.new(url: "https://toretto.family/coronas.gif")],
-  body: "Thought you could leave without saying goodbye?"
-)
+surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td")
 ```
 
 Or, equivalently:
 
 ```ruby
 # Hashes work, but are not typesafe:
-surge.messages.create(
-  "acct_01j9a43avnfqzbjfch6pygv1td",
-  conversation: {contact: {first_name: "Dom", last_name: "Toretto", phone_number: "+13235556439"}},
-  attachments: [{url: "https://toretto.family/coronas.gif"}],
-  body: "Thought you could leave without saying goodbye?"
-)
+surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td")
 
 # You can also splat a full Params class:
-params = SurgeAPI::MessageCreateParams.new(
-  conversation: SurgeAPI::MessageCreateParams::Conversation.new(
-    contact: SurgeAPI::MessageCreateParams::Conversation::Contact.new(
-      first_name: "Dom",
-      last_name: "Toretto",
-      phone_number: "+13235556439"
-    )
-  ),
-  attachments: [SurgeAPI::MessageCreateParams::Attachment.new(url: "https://toretto.family/coronas.gif")],
-  body: "Thought you could leave without saying goodbye?"
-)
+params = SurgeAPI::MessageCreateParams.new
 surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td", **params)
 ```
 
@@ -249,10 +198,10 @@ Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::E
 
 ```ruby
 # :high
-puts(SurgeAPI::CampaignCreateParams::Volume::HIGH)
+puts(SurgeAPI::CampaignParams::Volume::HIGH)
 
-# Revealed type: `T.all(SurgeAPI::CampaignCreateParams::Volume, Symbol)`
-T.reveal_type(SurgeAPI::CampaignCreateParams::Volume::HIGH)
+# Revealed type: `T.all(SurgeAPI::CampaignParams::Volume, Symbol)`
+T.reveal_type(SurgeAPI::CampaignParams::Volume::HIGH)
 ```
 
 Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
@@ -260,7 +209,7 @@ Enum parameters have a "relaxed" type, so you can either pass in enum constants
 ```ruby
 # Using the enum constants preserves the tagged type information:
 surge.campaigns.create(
-  volume: SurgeAPI::CampaignCreateParams::Volume::HIGH,
+  volume: SurgeAPI::CampaignParams::Volume::HIGH,
   # …
 )
 

data/lib/surge_api/internal/transport/base_client.rb

@@ -201,7 +201,8 @@ module SurgeAPI
             self.class::PLATFORM_HEADERS,
             {
               "accept" => "application/json",
-              "content-type" => "application/json"
+              "content-type" => "application/json",
+              "user-agent" => user_agent
             },
             headers
           )
@@ -219,6 +220,11 @@ module SurgeAPI
         # @return [Hash{String=>String}]
         private def auth_headers = {}
 
+        # @api private
+        #
+        # @return [String]
+        private def user_agent = "#{self.class.name}/Ruby #{SurgeAPI::VERSION}"
+
         # @api private
         #
         # @return [String]

data/lib/surge_api/internal/transport/pooled_net_requester.rb

@@ -16,10 +16,11 @@ module SurgeAPI
         class << self
           # @api private
           #
+          # @param cert_store [OpenSSL::X509::Store]
           # @param url [URI::Generic]
           #
           # @return [Net::HTTP]
-          def connect(url)
+          def connect(cert_store:, url:)
             port =
               case [url.port, url.scheme]
               in [Integer, _]
@@ -33,6 +34,8 @@ module SurgeAPI
             Net::HTTP.new(url.host, port).tap do
               _1.use_ssl = %w[https wss].include?(url.scheme)
               _1.max_retries = 0
+
+              (_1.cert_store = cert_store) if _1.use_ssl?
             end
           end
 
@@ -102,7 +105,7 @@ module SurgeAPI
           pool =
             @mutex.synchronize do
               @pools[origin] ||= ConnectionPool.new(size: @size) do
-                self.class.connect(url)
+                self.class.connect(cert_store: @cert_store, url: url)
               end
             end
 
@@ -128,40 +131,50 @@ module SurgeAPI
           url, deadline = request.fetch_values(:url, :deadline)
 
           req = nil
-          eof = false
           finished = false
-          closing = nil
 
           # rubocop:disable Metrics/BlockLength
           enum = Enumerator.new do |y|
             next if finished
 
             with_pool(url, deadline: deadline) do |conn|
-              req, closing = self.class.build_request(request) do
-                self.class.calibrate_socket_timeout(conn, deadline)
-              end
-
-              self.class.calibrate_socket_timeout(conn, deadline)
-              unless conn.started?
-                conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
-                conn.start
-              end
+              eof = false
+              closing = nil
+              ::Thread.handle_interrupt(Object => :never) do
+                ::Thread.handle_interrupt(Object => :immediate) do
+                  req, closing = self.class.build_request(request) do
+                    self.class.calibrate_socket_timeout(conn, deadline)
+                  end
 
-              self.class.calibrate_socket_timeout(conn, deadline)
-              conn.request(req) do |rsp|
-                y << [req, rsp]
-                break if finished
-
-                rsp.read_body do |bytes|
-                  y << bytes.force_encoding(Encoding::BINARY)
-                  break if finished
+                  self.class.calibrate_socket_timeout(conn, deadline)
+                  unless conn.started?
+                    conn.keep_alive_timeout = self.class::KEEP_ALIVE_TIMEOUT
+                    conn.start
+                  end
 
                   self.class.calibrate_socket_timeout(conn, deadline)
+                  ::Kernel.catch(:jump) do
+                    conn.request(req) do |rsp|
+                      y << [req, rsp]
+                      ::Kernel.throw(:jump) if finished
+
+                      rsp.read_body do |bytes|
+                        y << bytes.force_encoding(Encoding::BINARY)
+                        ::Kernel.throw(:jump) if finished
+
+                        self.class.calibrate_socket_timeout(conn, deadline)
+                      end
+                      eof = true
+                    end
+                  end
+                end
+              ensure
+                begin
+                  conn.finish if !eof && conn&.started?
+                ensure
+                  closing&.call
                 end
-                eof = true
               end
-            ensure
-              conn.finish if !eof && conn&.started?
             end
           rescue Timeout::Error
             raise SurgeAPI::Errors::APITimeoutError.new(url: url, request: req)
@@ -174,8 +187,6 @@ module SurgeAPI
           body = SurgeAPI::Internal::Util.fused_enum(enum, external: true) do
             finished = true
             loop { enum.next }
-          ensure
-            closing&.call
           end
           [Integer(response.code), response, body]
         end
@@ -186,6 +197,7 @@ module SurgeAPI
         def initialize(size: self.class::DEFAULT_MAX_CONNECTIONS)
           @mutex = Mutex.new
           @size = size
+          @cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
           @pools = {}
         end
 

data/lib/surge_api/internal/type/union.rb

@@ -17,6 +17,18 @@ module SurgeAPI
       #   else
       #     puts(unwrap_webhook_event)
       #   end
+      #
+      # @example
+      #   case unwrap_webhook_event
+      #   in {type: :"call.ended", account_id: account_id, data: data, timestamp: timestamp}
+      #     puts(account_id)
+      #   in {type: :"campaign.approved", account_id: account_id, data: data, timestamp: timestamp}
+      #     puts(data)
+      #   in {type: :"contact.opted_in", account_id: account_id, data: data, timestamp: timestamp}
+      #     puts(timestamp)
+      #   else
+      #     puts(unwrap_webhook_event)
+      #   end
       module Union
         include SurgeAPI::Internal::Type::Converter
         include SurgeAPI::Internal::Util::SorbetRuntimeSupport

data/lib/surge_api/internal/util.rb

@@ -346,8 +346,9 @@ module SurgeAPI
           base_path, base_query = lhs.fetch_values(:path, :query)
           slashed = base_path.end_with?("/") ? base_path : "#{base_path}/"
 
-          parsed_path, parsed_query = parse_uri(rhs.fetch(:path)).fetch_values(:path, :query)
-          override = URI::Generic.build(**rhs.slice(:scheme, :host, :port), path: parsed_path)
+          merged = {**parse_uri(rhs.fetch(:path)), **rhs.except(:path, :query)}
+          parsed_path, parsed_query = merged.fetch_values(:path, :query)
+          override = URI::Generic.build(**merged.slice(:scheme, :host, :port), path: parsed_path)
 
           joined = URI.join(URI::Generic.build(lhs.except(:path, :query)), slashed, override)
           query = deep_merge(
@@ -473,10 +474,9 @@ module SurgeAPI
         # @return [Enumerable<String>]
         def writable_enum(&blk)
           Enumerator.new do |y|
-            buf = String.new
             y.define_singleton_method(:write) do
-              self << buf.replace(_1)
-              buf.bytesize
+              self << _1.dup
+              _1.bytesize
             end
 
             blk.call(y)

data/lib/surge_api/models/account_create_params.rb

@@ -60,8 +60,11 @@ module SurgeAPI
         optional :address, -> { SurgeAPI::AccountCreateParams::Organization::Address }
 
         # @!attribute contact
-        #   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.
         #
         #   @return [SurgeAPI::Models::AccountCreateParams::Organization::Contact, nil]
         optional :contact, -> { SurgeAPI::AccountCreateParams::Organization::Contact }, nil?: true
@@ -169,7 +172,7 @@ module SurgeAPI
         #
         #   @param address [SurgeAPI::Models::AccountCreateParams::Organization::Address] The address of the organization's headquarters.
         #
-        #   @param contact [SurgeAPI::Models::AccountCreateParams::Organization::Contact, nil] An object representing an individual who can be contacted if the carriers have a
+        #   @param contact [SurgeAPI::Models::AccountCreateParams::Organization::Contact, nil] An object representing an individual who can be contacted if Surge or our carrie
         #
         #   @param country [String, nil] The two character ISO 3166 country code for the country in which the organizatio
         #
@@ -269,7 +272,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)
           #
           #   @return [String, nil]
           optional :email, String, nil?: true
@@ -313,8 +317,11 @@ module SurgeAPI
           #   Some parameter documentations has been truncated, see
           #   {SurgeAPI::Models::AccountCreateParams::Organization::Contact} for more details.
           #
-          #   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.
           #
           #   @param email [String, nil] An email address at which the individual can be reached. Typically an email usin
           #

data/lib/surge_api/models/account_update_params.rb

@@ -59,8 +59,11 @@ module SurgeAPI
         optional :address, -> { SurgeAPI::AccountUpdateParams::Organization::Address }
 
         # @!attribute contact
-        #   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.
         #
         #   @return [SurgeAPI::Models::AccountUpdateParams::Organization::Contact, nil]
         optional :contact, -> { SurgeAPI::AccountUpdateParams::Organization::Contact }, nil?: true
@@ -168,7 +171,7 @@ module SurgeAPI
         #
         #   @param address [SurgeAPI::Models::AccountUpdateParams::Organization::Address] The address of the organization's headquarters.
         #
-        #   @param contact [SurgeAPI::Models::AccountUpdateParams::Organization::Contact, nil] An object representing an individual who can be contacted if the carriers have a
+        #   @param contact [SurgeAPI::Models::AccountUpdateParams::Organization::Contact, nil] An object representing an individual who can be contacted if Surge or our carrie
         #
         #   @param country [String, nil] The two character ISO 3166 country code for the country in which the organizatio
         #
@@ -268,7 +271,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)
           #
           #   @return [String, nil]
           optional :email, String, nil?: true
@@ -312,8 +316,11 @@ module SurgeAPI
           #   Some parameter documentations has been truncated, see
           #   {SurgeAPI::Models::AccountUpdateParams::Organization::Contact} for more details.
           #
-          #   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.
           #
           #   @param email [String, nil] An email address at which the individual can be reached. Typically an email usin
           #