sentdm 0.29.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03c0b7afcf0204b627f759019cb3259c2612d4b808233a777b0e8e140953a02a
-  data.tar.gz: 16a965ab4e6e9f5ea6a3c826e8ba75dbe78c67e3ea6bbe4aa2f89fbbc32e230c
+  metadata.gz: bc53282fa9d44937f4eca7cd2519066c9230dd80c07e757976aaf19ed84bc4cd
+  data.tar.gz: ae37ec96f9bbd5415b93931e5f5b45f86bf2cfd9aa5496c3e48a4e4cf55c601c
 SHA512:
-  metadata.gz: 48199066de5c1469b22dadad823243beb75a1325c201627b9a7709c3739362bda1d0278725c081346ee476df2b5bcca55f0f05fc539e5e8180e329bb94c81630
-  data.tar.gz: 528a8194f406725b703c4d393b5266e690884d1f94fbd9843ceb537fc52f4e8dbd7ddc259b7fe8b3eebedcdb28dd95605a184b4543797e823000ed9c801b437e
+  metadata.gz: ad4d72570b0f014b5c0ae8ed154c6eda9cbf18fe6b765bd2159ac2468474c85dfba17e0d662f38c987ea0330eceb7e77d33137ebbb7df2591c65bae1f5415342
+  data.tar.gz: 6c941c5ce504b94a154865c6d1fa3ddcfcf90f58889e0514c0f74c89c324eb0c3312b55cd8ad4f5a32274b8ac28e8d65805496be73ad757621fd1a5a19e30c2e

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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)
+
+
+### Highlights
+
+This release is breaking for the webhook endpoints. Webhook responses now use one shared model instead of a separate type per operation: the create, retrieve, update and toggle-status response types are gone, and all four now return the shared webhook API response model (`ApiResponseWebhook`, in this language's casing). If your code references one of the removed types, or its nested data, error or meta members, point it at the shared model. The list, list-event-types, list-events, rotate-secret and test responses are unchanged, because each returns a different envelope.
+
+### Features
+
+* **api:** repoint dangling model refs at current v3 schema names ([631adad](https://github.com/sentdm/sent-dm-ruby/commit/631adadfe49cd6eb7ae9df2d3ad3c8261ac54984))
+
 ## [0.29.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.28.0...v0.29.0) (2026-09-06)
 
 

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.29.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:
@@ -256,6 +284,32 @@ params = Sentdm::MessageSendParams.new(
 sent.messages.send_(**params)
 ```
 
+### Enums
+
+Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
+
+```ruby
+# :PRIVATE_PROFIT
+puts(Sentdm::BrandBusinessInfo::EntityType::PRIVATE_PROFIT)
+
+# Revealed type: `T.all(Sentdm::BrandBusinessInfo::EntityType, Symbol)`
+T.reveal_type(Sentdm::BrandBusinessInfo::EntityType::PRIVATE_PROFIT)
+```
+
+Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+
+```ruby
+Sentdm::BrandBusinessInfo.new(
+  entity_type: Sentdm::BrandBusinessInfo::EntityType::PRIVATE_PROFIT,
+  # …
+)
+
+Sentdm::BrandBusinessInfo.new(
+  entity_type: :PRIVATE_PROFIT,
+  # …
+)
+```
+
 ## Versioning
 
 This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.

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/type/base_model.rb

@@ -438,11 +438,11 @@ module Sentdm
         # @return [Hash{Symbol=>Object}]
         #
         # @example
-        #   # `inbound_message_event` is a `Sentdm::InboundMessageEvent`
-        #   inbound_message_event => {
-        #     event: event,
-        #     field: field,
-        #     payload: payload
+        #   # `api_meta` is a `Sentdm::APIMeta`
+        #   api_meta => {
+        #     request_id: request_id,
+        #     timestamp: timestamp,
+        #     version: version
         #   }
         def deconstruct_keys(keys)
           (keys || self.class.known_fields.keys)

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