surge_api 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d974f7f96df8e8e8452c8693d8afe99108691e4765da89ed06670ad635f3a48
-  data.tar.gz: 4f7eedf44e0f6c2b0d076f2c590d07519c666ae2d20fc12a5b0cef4fa2b451dd
+  metadata.gz: 4ab0d460fe03be9712dc7d4ad68bc64e6ebb931573b9fe9ff91b8f36f2979514
+  data.tar.gz: 20488d8ba034a202671fa5cb1c3e0bde2c863bfa7826ed3ffb718911c34515ee
 SHA512:
-  metadata.gz: 4b03295d43f70c73f3db451516682c5ff8e5e7c081db91e7ed98628500f3f7cb637952dc60631f76e6d83dbf8a571ca1c90e4fb0dc3ce00ae0b759ca1ed8bfeb
-  data.tar.gz: 44ec0232e66a93b385447ccc5cd6ee433d7f3e944e96b69c2cf7badde81fdf46b630b9501a386067bffc10896de0eb864c2720814fe4e295fcc1a924fd8f2205
+  metadata.gz: abd73bd158429ed55c7343a89e85ce56ed40979df1278b20937250787bf360b91e1de84494abd4f1d2e9c2f3dc8f2bbfbedec04f1666b2d9b5798f976cda985f
+  data.tar.gz: bcbd4c0adb4baba0a737a833232f02abb63588f31a8d9ff70c39dee65037db86032efc12f34499c57ff46bd6b6b27c5276d6a9af4600fb290aced6e0014cda80

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.10.0 (2026-02-12)
+
+Full Changelog: [v0.9.0...v0.10.0](https://github.com/surgeapi/ruby-sdk/compare/v0.9.0...v0.10.0)
+
+### Features
+
+* **api:** add campaign.status field ([f0ab6be](https://github.com/surgeapi/ruby-sdk/commit/f0ab6bef5d1cbca9741b3731189e5a821c6abcb3))
+* **api:** add get campaign endpoint ([511d2b3](https://github.com/surgeapi/ruby-sdk/commit/511d2b3cd36a3e4a1f1737093a02f5c31296c332))
+* **api:** add recording.completed webhook ([9a72a0c](https://github.com/surgeapi/ruby-sdk/commit/9a72a0c754dad51ac7b02e84c3f8ce8e6ba85378))
+* **api:** add voicemail.received webhook ([37edfcd](https://github.com/surgeapi/ruby-sdk/commit/37edfcd3a2d26f42ea5a0fbf5481e046486f4456))
+* **api:** get recording file ([db0184e](https://github.com/surgeapi/ruby-sdk/commit/db0184e171168f74e20d91b65cea452a32aad263))
+
+
+### Bug Fixes
+
+* **api:** make message.blast_id nullable ([9096e75](https://github.com/surgeapi/ruby-sdk/commit/9096e75d5aa6803c4b11aba0fe2c61448abf3f6a))
+* **client:** loosen json header parsing ([51f4092](https://github.com/surgeapi/ruby-sdk/commit/51f409235dc8e2c377411b3f53595df8fea9b4e4))
+
+## 0.9.0 (2026-02-04)
+
+Full Changelog: [v0.8.0...v0.9.0](https://github.com/surgeapi/ruby-sdk/compare/v0.8.0...v0.9.0)
+
+### Features
+
+* **api:** add list contacts endpoint ([fb3eaae](https://github.com/surgeapi/ruby-sdk/commit/fb3eaae32fa15b6b7423b4ae485608e03cf027a7))
+* **api:** add list messages endpoint ([ca51f12](https://github.com/surgeapi/ruby-sdk/commit/ca51f12d83bcebdd706701e8fee9a594313bd767))
+* **api:** add list phone numbers endpoint ([47691df](https://github.com/surgeapi/ruby-sdk/commit/47691dfe6f91a9300c02f3f893fe2af5636f8094))
+* **sdk:** add deprecation messages ([f0e959e](https://github.com/surgeapi/ruby-sdk/commit/f0e959e9a96069670284b7ebd9f9a0a28672b5dc))
+* **sdks:** set up pagination ([08b1393](https://github.com/surgeapi/ruby-sdk/commit/08b13930dd2102f1886c616409f213e62b3137e5))
+
+
+### Bug Fixes
+
+* **api:** make message body nullable ([a329e52](https://github.com/surgeapi/ruby-sdk/commit/a329e5203323524beb725f217d0261193df02ebe))
+* **client:** always add content-length to post body, even when empty ([12467d3](https://github.com/surgeapi/ruby-sdk/commit/12467d365020dafafb0474504042a8e39c5ee2fd))
+
+
+### Chores
+
+* **docs:** remove www prefix ([beaff0c](https://github.com/surgeapi/ruby-sdk/commit/beaff0c151d0e31114c490c09fb4c71196e316d8))
+
 ## 0.8.0 (2026-01-26)
 
 Full Changelog: [v0.7.0...v0.8.0](https://github.com/surgeapi/ruby-sdk/compare/v0.7.0...v0.8.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.8.0"
+gem "surge_api", "~> 0.10.0"
 ```
 
 <!-- x-release-please-end -->
@@ -37,6 +37,34 @@ message = surge.messages.create("acct_01j9a43avnfqzbjfch6pygv1td")
 puts(message.id)
 ```
 
+### Pagination
+
+List methods in the Surge API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```ruby
+page = surge.contacts.list
+
+# Fetch single item from page.
+contact = page.data[0]
+puts(contact.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |contact|
+  puts(contact.id)
+end
+```
+
+Alternatively, you can use the `#next_page?` and `#next_page` methods for more granular control working with pages.
+
+```ruby
+if page.next_page?
+  new_page = page.next_page
+  puts(new_page.data[0].id)
+end
+```
+
 ### Handling errors
 
 When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `SurgeAPI::Errors::APIError` will be thrown:

data/lib/surge_api/client.rb

@@ -36,6 +36,9 @@ module SurgeAPI
     # @return [SurgeAPI::Resources::PhoneNumbers]
     attr_reader :phone_numbers
 
+    # @return [SurgeAPI::Resources::Recordings]
+    attr_reader :recordings
+
     # @return [SurgeAPI::Resources::Users]
     attr_reader :users
 
@@ -98,6 +101,7 @@ module SurgeAPI
       @contacts = SurgeAPI::Resources::Contacts.new(client: self)
       @messages = SurgeAPI::Resources::Messages.new(client: self)
       @phone_numbers = SurgeAPI::Resources::PhoneNumbers.new(client: self)
+      @recordings = SurgeAPI::Resources::Recordings.new(client: self)
       @users = SurgeAPI::Resources::Users.new(client: self)
       @verifications = SurgeAPI::Resources::Verifications.new(client: self)
       @webhooks = SurgeAPI::Resources::Webhooks.new(client: self)

data/lib/surge_api/internal/cursor.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if cursor.has_next?
+    #     cursor = cursor.next_page
+    #   end
+    #
+    # @example
+    #   cursor.auto_paging_each do |contact|
+    #     puts(contact)
+    #   end
+    class Cursor
+      include SurgeAPI::Internal::Type::BasePage
+
+      # @return [Array<generic<Elem>>, nil]
+      attr_accessor :data
+
+      # @return [Pagination]
+      attr_accessor :pagination
+
+      # @return [Boolean]
+      def next_page?
+        !data.to_a.empty? && (!pagination&.previous_cursor.to_s.empty? || !pagination&.next_cursor.to_s.empty?)
+      end
+
+      # @raise [SurgeAPI::HTTP::Error]
+      # @return [self]
+      def next_page
+        unless next_page?
+          message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+          raise RuntimeError.new(message)
+        end
+
+        req = SurgeAPI::Internal::Util.deep_merge(
+          @req,
+          {
+            query: pagination&.previous_cursor.nil? ? {after: pagination&.next_cursor} : {before: pagination&.previous_cursor}
+          }
+        )
+        @client.request(req)
+      end
+
+      # @param blk [Proc]
+      #
+      # @yieldparam [generic<Elem>]
+      def auto_paging_each(&blk)
+        unless block_given?
+          raise ArgumentError.new("A block must be given to ##{__method__}")
+        end
+
+        page = self
+        loop do
+          page.data&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [SurgeAPI::Internal::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param headers [Hash{String=>String}]
+      # @param page_data [Hash{Symbol=>Object}]
+      def initialize(client:, req:, headers:, page_data:)
+        super
+
+        case page_data
+        in {data: Array => data}
+          @data = data.map { SurgeAPI::Internal::Type::Converter.coerce(@model, _1) }
+        else
+        end
+        case page_data
+        in {pagination: Hash | nil => pagination}
+          @pagination =
+            SurgeAPI::Internal::Type::Converter.coerce(SurgeAPI::Internal::Cursor::Pagination, pagination)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = SurgeAPI::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Pagination < SurgeAPI::Internal::Type::BaseModel
+        # @!attribute next_cursor
+        #
+        #   @return [String, nil]
+        optional :next_cursor, String
+
+        # @!attribute previous_cursor
+        #
+        #   @return [String, nil]
+        optional :previous_cursor, String
+
+        # @!method initialize(next_cursor: nil, previous_cursor: nil)
+        #   @param next_cursor [String]
+        #   @param previous_cursor [String]
+      end
+    end
+  end
+end

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

@@ -75,7 +75,7 @@ module SurgeAPI
 
             case body
             in nil
-              nil
+              req["content-length"] ||= 0 unless req["transfer-encoding"]
             in String
               req["content-length"] ||= body.bytesize.to_s unless req["transfer-encoding"]
               req.body_stream = SurgeAPI::Internal::Util::ReadIOAdapter.new(body, &blk)

data/lib/surge_api/internal/util.rb

@@ -485,7 +485,7 @@ module SurgeAPI
       end
 
       # @type [Regexp]
-      JSON_CONTENT = %r{^application/(?:vnd(?:\.[^.]+)*\+)?json(?!l)}
+      JSON_CONTENT = %r{^application/(?:[a-zA-Z0-9.-]+\+)?json(?!l)}
       # @type [Regexp]
       JSONL_CONTENT = %r{^application/(:?x-(?:n|l)djson)|(:?(?:x-)?jsonl)}
 

data/lib/surge_api/models/blast.rb

@@ -19,7 +19,7 @@ module SurgeAPI
       #   The message body.
       #
       #   @return [String, nil]
-      optional :body, String
+      optional :body, String, nil?: true
 
       # @!attribute name
       #   Optional name for the blast.
@@ -40,7 +40,7 @@ module SurgeAPI
       #
       #   @param attachments [Array<SurgeAPI::Models::Blast::Attachment>]
       #
-      #   @param body [String] The message body.
+      #   @param body [String, nil] The message body.
       #
       #   @param name [String] Optional name for the blast.
       #

data/lib/surge_api/models/blast_create_params.rb

@@ -16,10 +16,10 @@ module SurgeAPI
       #   The message body.
       #
       #   @return [String, nil]
-      optional :body, String
+      optional :body, String, nil?: true
 
       # @!attribute contacts
-      #   @deprecated
+      #   @deprecated Use `to` to specify recipients instead.
       #
       #   Deprecated. Use `to` instead.
       #
@@ -41,7 +41,7 @@ module SurgeAPI
       optional :name, String
 
       # @!attribute segments
-      #   @deprecated
+      #   @deprecated Use `to` to specify recipients instead.
       #
       #   Deprecated. Use `to` instead.
       #
@@ -67,7 +67,7 @@ module SurgeAPI
       #
       #   @param attachments [Array<SurgeAPI::Models::BlastCreateParams::Attachment>]
       #
-      #   @param body [String] The message body.
+      #   @param body [String, nil] The message body.
       #
       #   @param contacts [Array<String>] Deprecated. Use `to` instead.
       #

data/lib/surge_api/models/campaign.rb

@@ -60,6 +60,12 @@ module SurgeAPI
       #   @return [String]
       required :privacy_policy_url, String
 
+      # @!attribute status
+      #   The current status of the campaign.
+      #
+      #   @return [Symbol, SurgeAPI::Models::Campaign::Status]
+      required :status, enum: -> { SurgeAPI::Campaign::Status }
+
       # @!attribute use_cases
       #   A list containing 1-5 types of messages that will be sent with this campaign.
       #
@@ -125,7 +131,7 @@ module SurgeAPI
       #   @return [String, nil]
       optional :terms_and_conditions_url, String
 
-      # @!method initialize(id:, consent_flow:, description:, includes:, message_samples:, privacy_policy_url:, use_cases:, volume:, link_sample: nil, terms_and_conditions_url: nil)
+      # @!method initialize(id:, consent_flow:, description:, includes:, message_samples:, privacy_policy_url:, status:, use_cases:, volume:, link_sample: nil, terms_and_conditions_url: nil)
       #   Some parameter documentations has been truncated, see
       #   {SurgeAPI::Models::Campaign} for more details.
       #
@@ -144,6 +150,8 @@ module SurgeAPI
       #
       #   @param privacy_policy_url [String] The URL of the privacy policy for the brand in question. This may be a shared pr
       #
+      #   @param status [Symbol, SurgeAPI::Models::Campaign::Status] The current status of the campaign.
+      #
       #   @param use_cases [Array<Symbol, SurgeAPI::Models::Campaign::UseCase>] A list containing 1-5 types of messages that will be sent with this campaign.
       #
       #   @param volume [Symbol, SurgeAPI::Models::Campaign::Volume] This will be one of the following:
@@ -164,6 +172,24 @@ module SurgeAPI
         #   @return [Array<Symbol>]
       end
 
+      # The current status of the campaign.
+      #
+      # @see SurgeAPI::Models::Campaign#status
+      module Status
+        extend SurgeAPI::Internal::Type::Enum
+
+        ACTIVE = :active
+        CANCELED = :canceled
+        CREATED = :created
+        DEACTIVATED = :deactivated
+        IN_REVIEW = :in_review
+        PENDING = :pending
+        REJECTED = :rejected
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
       module UseCase
         extend SurgeAPI::Internal::Type::Enum
 

data/lib/surge_api/models/campaign_retrieve_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Campaigns#retrieve
+    class CampaignRetrieveParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/contact_list_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Contacts#list
+    class ContactListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute after
+      #   Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @return [String, nil]
+      optional :after, String
+
+      # @!attribute before
+      #   Cursor for backward pagination. Use the previous_cursor from a previous
+      #   response.
+      #
+      #   @return [String, nil]
+      optional :before, String
+
+      # @!method initialize(after: nil, before: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::ContactListParams} for more details.
+      #
+      #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/message.rb

@@ -20,13 +20,13 @@ module SurgeAPI
       #   attribute messages back to a specific blast.
       #
       #   @return [String, nil]
-      optional :blast_id, String
+      optional :blast_id, String, nil?: true
 
       # @!attribute body
       #   The message body.
       #
       #   @return [String, nil]
-      optional :body, String
+      optional :body, String, nil?: true
 
       # @!attribute conversation
       #   A conversation with a Contact
@@ -50,9 +50,9 @@ module SurgeAPI
       #
       #   @param attachments [Array<SurgeAPI::Models::Message::Attachment>]
       #
-      #   @param blast_id [String] The ID of the blast this message belongs to, if any. This can be used to attribu
+      #   @param blast_id [String, nil] The ID of the blast this message belongs to, if any. This can be used to attribu
       #
-      #   @param body [String] The message body.
+      #   @param body [String, nil] The message body.
       #
       #   @param conversation [SurgeAPI::Models::Message::Conversation] A conversation with a Contact
       #

data/lib/surge_api/models/message_delivered_webhook_event.rb

@@ -47,8 +47,8 @@ module SurgeAPI
         # @!attribute body
         #   The content of the message
         #
-        #   @return [String]
-        required :body, String
+        #   @return [String, nil]
+        required :body, String, nil?: true
 
         # @!attribute conversation
         #   The conversation this message belongs to
@@ -84,7 +84,7 @@ module SurgeAPI
         #
         #   @param id [String] The unique identifier for the message
         #
-        #   @param body [String] The content of the message
+        #   @param body [String, nil] The content of the message
         #
         #   @param conversation [SurgeAPI::Models::MessageDeliveredWebhookEvent::Data::Conversation] The conversation this message belongs to
         #

data/lib/surge_api/models/message_failed_webhook_event.rb

@@ -47,8 +47,8 @@ module SurgeAPI
         # @!attribute body
         #   The content of the message
         #
-        #   @return [String]
-        required :body, String
+        #   @return [String, nil]
+        required :body, String, nil?: true
 
         # @!attribute conversation
         #   The conversation this message belongs to
@@ -90,7 +90,7 @@ module SurgeAPI
         #
         #   @param id [String] The unique identifier for the message
         #
-        #   @param body [String] The content of the message
+        #   @param body [String, nil] The content of the message
         #
         #   @param conversation [SurgeAPI::Models::MessageFailedWebhookEvent::Data::Conversation] The conversation this message belongs to
         #

data/lib/surge_api/models/message_list_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::Messages#list
+    class MessageListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute after
+      #   Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @return [String, nil]
+      optional :after, String
+
+      # @!attribute before
+      #   Cursor for backward pagination. Use the previous_cursor from a previous
+      #   response.
+      #
+      #   @return [String, nil]
+      optional :before, String
+
+      # @!method initialize(after: nil, before: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::MessageListParams} for more details.
+      #
+      #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/surge_api/models/message_received_webhook_event.rb

@@ -47,8 +47,8 @@ module SurgeAPI
         # @!attribute body
         #   The content of the message
         #
-        #   @return [String]
-        required :body, String
+        #   @return [String, nil]
+        required :body, String, nil?: true
 
         # @!attribute conversation
         #   The conversation this message belongs to
@@ -84,7 +84,7 @@ module SurgeAPI
         #
         #   @param id [String] The unique identifier for the message
         #
-        #   @param body [String] The content of the message
+        #   @param body [String, nil] The content of the message
         #
         #   @param conversation [SurgeAPI::Models::MessageReceivedWebhookEvent::Data::Conversation] The conversation this message belongs to
         #

data/lib/surge_api/models/message_sent_webhook_event.rb

@@ -47,8 +47,8 @@ module SurgeAPI
         # @!attribute body
         #   The content of the message
         #
-        #   @return [String]
-        required :body, String
+        #   @return [String, nil]
+        required :body, String, nil?: true
 
         # @!attribute conversation
         #   The conversation this message belongs to
@@ -84,7 +84,7 @@ module SurgeAPI
         #
         #   @param id [String] The unique identifier for the message
         #
-        #   @param body [String] The content of the message
+        #   @param body [String, nil] The content of the message
         #
         #   @param conversation [SurgeAPI::Models::MessageSentWebhookEvent::Data::Conversation] The conversation this message belongs to
         #

data/lib/surge_api/models/phone_number.rb

@@ -2,7 +2,7 @@
 
 module SurgeAPI
   module Models
-    # @see SurgeAPI::Resources::PhoneNumbers#purchase
+    # @see SurgeAPI::Resources::PhoneNumbers#list
     class PhoneNumber < SurgeAPI::Internal::Type::BaseModel
       # @!attribute id
       #   Unique identifier for the phone number

data/lib/surge_api/models/phone_number_list_params.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SurgeAPI
+  module Models
+    # @see SurgeAPI::Resources::PhoneNumbers#list
+    class PhoneNumberListParams < SurgeAPI::Internal::Type::BaseModel
+      extend SurgeAPI::Internal::Type::RequestParameters::Converter
+      include SurgeAPI::Internal::Type::RequestParameters
+
+      # @!attribute after
+      #   Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @return [String, nil]
+      optional :after, String
+
+      # @!attribute before
+      #   Cursor for backward pagination. Use the previous_cursor from a previous
+      #   response.
+      #
+      #   @return [String, nil]
+      optional :before, String
+
+      # @!method initialize(after: nil, before: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {SurgeAPI::Models::PhoneNumberListParams} for more details.
+      #
+      #   @param after [String] Cursor for forward pagination. Use the next_cursor from a previous response.
+      #
+      #   @param before [String] Cursor for backward pagination. Use the previous_cursor from a previous response
+      #
+      #   @param request_options [SurgeAPI::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end