sentdm 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dcf3d6a64f73f5ebe47c785eb5af402f3c8cba5c086451d6ed894b160525385
-  data.tar.gz: 44fe52b54a32b7a898a8bbf4502ee623bd7bbe3da89a54c3322ebc4678a786a4
+  metadata.gz: bc53282fa9d44937f4eca7cd2519066c9230dd80c07e757976aaf19ed84bc4cd
+  data.tar.gz: ae37ec96f9bbd5415b93931e5f5b45f86bf2cfd9aa5496c3e48a4e4cf55c601c
 SHA512:
-  metadata.gz: eafc5446f6c3f8574489e96ce39020edb97b5d874ccf39bf847d939b501a2c3df02929d7c301e071868042c95cc4557a76671ae447bdc3d406415ed58ecf856c
-  data.tar.gz: cd61c938a532a9649db86e972de53bad39ebd4980f55a4e51e271227e53b1316e98ae017e02b209de08ca1ac8ec0db54dc0a3a6d5ff3e607d123f8cbab265a38
+  metadata.gz: ad4d72570b0f014b5c0ae8ed154c6eda9cbf18fe6b765bd2159ac2468474c85dfba17e0d662f38c987ea0330eceb7e77d33137ebbb7df2591c65bae1f5415342
+  data.tar.gz: 6c941c5ce504b94a154865c6d1fa3ddcfcf90f58889e0514c0f74c89c324eb0c3312b55cd8ad4f5a32274b8ac28e8d65805496be73ad757621fd1a5a19e30c2e

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.31.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.30.0...v0.31.0) (2026-09-10)
+
+
+### Highlights
+
+The contacts, templates, webhooks, webhook events, conversations, and conversation messages list methods now return a page you can iterate instead of a single response body. Iterate the result and the SDK fetches each page as it goes. This changes those methods' return type, so code that read the response body directly needs to iterate the page, or read its items, instead.
+
+`page` and `page_size` are now optional on those calls. You don't have to pass them to list anything.
+
+### Features
+
+* **api:** configure page_number pagination for the v3 list endpoints ([d23828b](https://github.com/sentdm/sent-dm-ruby/commit/d23828b500a4b683f9036f63d40e79c466699b2f))
+
 ## [0.30.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.29.0...v0.30.0) (2026-09-09)
 
 

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 "sentdm", "~> 0.30.0"
+gem "sentdm", "~> 0.31.0"
 ```
 
 <!-- x-release-please-end -->
@@ -45,6 +45,34 @@ response = sent.messages.send_(
 puts(response.data)
 ```
 
+### Pagination
+
+List methods in the Sent 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 = sent.webhooks.list
+
+# Fetch single item from page.
+webhook = page.data&.webhooks[0]
+puts(webhook.id)
+
+# Automatically fetches more pages as needed.
+page.auto_paging_each do |webhook|
+  puts(webhook.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&.webhooks[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 `Sentdm::Errors::APIError` will be thrown:

data/lib/sentdm/internal/contacts_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if contacts_page.has_next?
+    #     contacts_page = contacts_page.next_page
+    #   end
+    #
+    # @example
+    #   contacts_page.auto_paging_each do |contact|
+    #     puts(contact)
+    #   end
+    class ContactsPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::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 = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @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&.contacts&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::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: Hash | nil => data}
+          if (contacts = data[:contacts]).is_a?(Array)
+            data = {**data, contacts: contacts.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::ContactsPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute contacts
+        #
+        #   @return [Array<Object>, nil]
+        optional :contacts, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!method initialize(contacts: nil, pagination: nil)
+        #   @param contacts [Array<Object>]
+        #   @param pagination [Data::Pagination]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/internal/conversations_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if conversations_page.has_next?
+    #     conversations_page = conversations_page.next_page
+    #   end
+    #
+    # @example
+    #   conversations_page.auto_paging_each do |conversation|
+    #     puts(conversation)
+    #   end
+    class ConversationsPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::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 = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @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&.messages&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::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: Hash | nil => data}
+          if (messages = data[:messages]).is_a?(Array)
+            data = {**data, messages: messages.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::ConversationsPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute messages
+        #
+        #   @return [Array<Object>, nil]
+        optional :messages, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!method initialize(messages: nil, pagination: nil)
+        #   @param messages [Array<Object>]
+        #   @param pagination [Data::Pagination]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/internal/templates_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if templates_page.has_next?
+    #     templates_page = templates_page.next_page
+    #   end
+    #
+    # @example
+    #   templates_page.auto_paging_each do |template|
+    #     puts(template)
+    #   end
+    class TemplatesPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::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 = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @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&.templates&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::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: Hash | nil => data}
+          if (templates = data[:templates]).is_a?(Array)
+            data = {**data, templates: templates.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::TemplatesPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!attribute templates
+        #
+        #   @return [Array<Object>, nil]
+        optional :templates, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!method initialize(pagination: nil, templates: nil)
+        #   @param pagination [Data::Pagination]
+        #   @param templates [Array<Object>]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/internal/webhook_events_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if webhook_events_page.has_next?
+    #     webhook_events_page = webhook_events_page.next_page
+    #   end
+    #
+    # @example
+    #   webhook_events_page.auto_paging_each do |webhook|
+    #     puts(webhook)
+    #   end
+    class WebhookEventsPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::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 = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @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&.events&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::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: Hash | nil => data}
+          if (events = data[:events]).is_a?(Array)
+            data = {**data, events: events.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::WebhookEventsPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute events
+        #
+        #   @return [Array<Object>, nil]
+        optional :events, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!method initialize(events: nil, pagination: nil)
+        #   @param events [Array<Object>]
+        #   @param pagination [Data::Pagination]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/internal/webhooks_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if webhooks_page.has_next?
+    #     webhooks_page = webhooks_page.next_page
+    #   end
+    #
+    # @example
+    #   webhooks_page.auto_paging_each do |webhook|
+    #     puts(webhook)
+    #   end
+    class WebhooksPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::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 = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @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&.webhooks&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::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: Hash | nil => data}
+          if (webhooks = data[:webhooks]).is_a?(Array)
+            data = {**data, webhooks: webhooks.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::WebhooksPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!attribute webhooks
+        #
+        #   @return [Array<Object>, nil]
+        optional :webhooks, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!method initialize(pagination: nil, webhooks: nil)
+        #   @param pagination [Data::Pagination]
+        #   @param webhooks [Array<Object>]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/models/api_response_of_conversation_messages_list.rb

@@ -2,7 +2,6 @@
 
 module Sentdm
   module Models
-    # @see Sentdm::Resources::Conversations#list
     class APIResponseOfConversationMessagesList < Sentdm::Internal::Type::BaseModel
       # @!attribute data
       #   A paginated list of messages — used by both conversation read endpoints.