surge_api 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd72992441d9bff1aa161673f62cd5957d2f626eee83f83dfd3f259341377826
-  data.tar.gz: 37b27a1c5c4aa7406a0c81753b3b93469bb6181055cc3e9c6e4c9737cd2317a0
+  metadata.gz: cc8267ebb4682d2884a0ed0a4ff0c1ec89a6e76988ee96cbdd794bc9ee745ef2
+  data.tar.gz: fcefd6289c6dae43967d4eac94bbc87299ab03c52e335f611949a4d6169c7c79
 SHA512:
-  metadata.gz: 5482581f94873824fd774a5abcac9fcfb723c168cd3fc84f6f05603cc887e66870b3407f6a1546777c2f82b920ce3fc9c798c8fbc522fa8b42398cc8b10274c0
-  data.tar.gz: 8897a9b535eeac8e8b995e23e2b7793ecf57474f14d13ded041f4ba91eaa6f9730912ac844287621ff427d8eb7fddff3151e8e1b311745947b81794692ec92c8
+  metadata.gz: 22b712d8f2898bca0a102de847125c57cc1feb4771c23db55de558616b6dba9de87a1915e05e44c23ca619872f9a9d0f70df9c8f522e8f867048fd43a53cb660
+  data.tar.gz: '025923bb1e6f82ecbe04e30ee9f849369e8ddd76dd73f729dfe046220ffc044633cc7f1d15d286b6d37c2b5d6d641bae27e2cb558499e4c6271133997ba8444f'

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 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)
+
+### Features
+
+* **api:** api update ([8a7eeeb](https://github.com/surgeapi/ruby-sdk/commit/8a7eeeb4c5248d0f0aa4da399c45d2763b98ba3b))
+
+
+### Bug Fixes
+
+* always send `filename=...` for multipart requests where a file is expected ([28bdedf](https://github.com/surgeapi/ruby-sdk/commit/28bdedfba8e9bef43abf39e08169bc2bf2edb0e8))
+* coroutine leaks from connection pool ([239043f](https://github.com/surgeapi/ruby-sdk/commit/239043f74e12856fb8e6b2a477ea9bf35945f2f2))
+
+
+### Chores
+
+* ignore linter error for tests having large collections ([4d89802](https://github.com/surgeapi/ruby-sdk/commit/4d898024ffae04e4f24591b1c54a922e1b6c51f4))
+
 ## 0.1.0 (2025-09-26)
 
 Full Changelog: [v0.0.1...v0.1.0](https://github.com/surgeapi/ruby-sdk/compare/v0.0.1...v0.1.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.1.0"
+gem "surge_api", "~> 0.2.1"
 ```
 
 <!-- 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/file_part.rb

@@ -38,18 +38,21 @@ module SurgeAPI
     def to_yaml(*a) = read.to_yaml(*a)
 
     # @param content [Pathname, StringIO, IO, String]
-    # @param filename [String, nil]
+    # @param filename [Pathname, String, nil]
     # @param content_type [String, nil]
     def initialize(content, filename: nil, content_type: nil)
-      @content = content
+      @content_type = content_type
       @filename =
-        case content
-        in Pathname
-          filename.nil? ? content.basename.to_path : ::File.basename(filename)
+        case [filename, (@content = content)]
+        in [String | Pathname, _]
+          ::File.basename(filename)
+        in [nil, Pathname]
+          content.basename.to_path
+        in [nil, IO]
+          content.to_path
         else
-          filename.nil? ? nil : ::File.basename(filename)
+          filename
         end
-      @content_type = content_type
     end
   end
 end

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

@@ -128,37 +128,47 @@ 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|
-            with_pool(url, deadline: deadline) do |conn|
-              next if finished
-
-              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
+            next if finished
 
-              self.class.calibrate_socket_timeout(conn, deadline)
-              conn.request(req) do |rsp|
-                y << [conn, req, rsp]
-                break if finished
+            with_pool(url, deadline: deadline) do |conn|
+              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
 
-                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)
+                  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)
+                    end
+                    eof = true
+                  end
+                end
+              ensure
+                begin
+                  conn.finish if !eof && conn&.started?
+                ensure
+                  closing&.call
                 end
-                eof = true
               end
             end
           rescue Timeout::Error
@@ -168,17 +178,10 @@ module SurgeAPI
           end
           # rubocop:enable Metrics/BlockLength
 
-          conn, _, response = enum.next
+          _, response = enum.next
           body = SurgeAPI::Internal::Util.fused_enum(enum, external: true) do
             finished = true
-            tap do
-              enum.next
-            rescue StopIteration
-              nil
-            end
-          ensure
-            conn.finish if !eof && conn&.started?
-            closing&.call
+            loop { enum.next }
           end
           [Integer(response.code), response, body]
         end

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

@@ -82,17 +82,20 @@ module SurgeAPI
           #
           # @return [Pathname, StringIO, IO, String, Object]
           def dump(value, state:)
-            # rubocop:disable Lint/DuplicateBranch
             case value
+            in StringIO | String
+              # https://datatracker.ietf.org/doc/html/rfc7578#section-4.2
+              # while not required, a filename is recommended, and in practice many servers do expect this
+              SurgeAPI::FilePart.new(value, filename: "upload")
             in IO
               state[:can_retry] = false
+              value.to_path.nil? ? SurgeAPI::FilePart.new(value, filename: "upload") : value
             in SurgeAPI::FilePart if value.content.is_a?(IO)
               state[:can_retry] = false
+              value
             else
+              value
             end
-            # rubocop:enable Lint/DuplicateBranch
-
-            value
           end
 
           # @api private

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

@@ -12,7 +12,7 @@ module SurgeAPI
       #     puts(unwrap_webhook_event.account_id)
       #   when SurgeAPI::CampaignApprovedWebhookEvent
       #     puts(unwrap_webhook_event.data)
-      #   when SurgeAPI::ConversationCreatedWebhookEvent
+      #   when SurgeAPI::ContactOptedInWebhookEvent
       #     puts(unwrap_webhook_event.timestamp)
       #   else
       #     puts(unwrap_webhook_event)

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
           #