brapi-ruby-sdk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05b2bc6fb4061903f31d59574c62333d8410d7228d3e9b1664a3efc04e024eee
-  data.tar.gz: 299938eb28c85c3b53d0c56e78f40f3ff552bc662b513ea1bb2db051db3d35f6
+  metadata.gz: 2f184be4deccafcbafd23f9275a7801290357e72c13d78eee0d5604aaa60edd2
+  data.tar.gz: f3e70b267473bc7dc2222463a7f175578b8ad3099657dccddf71571237e884e7
 SHA512:
-  metadata.gz: 2aeaa5ecd337d64825b59a7ff6617a74c9de2f8b14a0d83891f23c51ca79a5c7dec5918da537604d43fe13ee23eb602c50295b851d83258f1453f71c9ccf6929
-  data.tar.gz: 10792774a48f8862197fa6abfa230822121d1d1d519d75d0021dbab3597963dd1caf5e7acfd8f3da589e186a8ddfbe18fd65f0330ff6ddae34d190676dbacd9e
+  metadata.gz: 116a1de195f79a3b4943ae68ad6f0b9133f66145282e0f124564f2083a5a7b87d5325e65502fcaf059f49b2538bda73a3ef304c0ef9b8ffb8b3746bc41f4c8ad
+  data.tar.gz: f6516906c904e17d2732d108f4b989c30bba0a9477144aeeb59db534f640391b1d0937df282e600c6837ff39899bb52eb0f51eecebbcea7ea8b19b4993684b1b

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-28
+
+### Added
+
+- **Auto-pagination** on every paginated resource. Three new public methods
+  show up on `client.quote`, `client.v2.fii` and `client.v2.treasury`:
+  - `#each_page { |page| ... }` — yields one full page response per iteration
+    until the upstream signals `has_next_page = false` (or after `max_pages:`
+    iterations, whichever comes first).
+  - `#each { |item| ... }` — auto-flattens across pages, yielding each row
+    (FII, bond or QuoteListItem) individually.
+  - Without a block, both return an `Enumerator` so the full Ruby
+    Enumerable surface is available: `client.v2.fii.first(10)`,
+    `client.v2.fii.select { |f| f.dividend_yield12m > 0.1 }`,
+    `client.v2.treasury.lazy.find { |b| b.indexer == "ipca" }`, etc.
+- `Brapi::Resources::Paginated` mixin (declarative `paginates items: :fiis`
+  in the resource class) ready to be reused by any future paginated
+  endpoint.
+- `max_pages:` keyword on `#each` / `#each_page` (default `10_000`)
+  protects against runaway loops if a buggy upstream forgets to flip
+  `has_next_page = false`.
+- Resources are now `Enumerable`, so the standard `map` / `select` /
+  `take` / `find` / `lazy` / `count` methods Just Work on paginated
+  endpoints.
+
 ## [0.3.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -220,6 +220,47 @@ resp.stocks.each { |s| puts "#{s.stock} (#{s.name}): R$ #{s.close}" }
 puts "Page #{resp.current_page}/#{resp.total_pages}"
 ```
 
+### Auto-pagination
+
+Every paginated resource (`client.quote.list`, `client.v2.fii.list`,
+`client.v2.treasury.list`) gains `#each_page`, `#each` and the full
+Ruby `Enumerable` surface:
+
+```ruby
+# Yield each row across all pages — lazy by default, stops when
+# the API reports has_next_page = false.
+Brapi.v2.fii.each { |f| puts "#{f.symbol}: DY12m=#{f.dividend_yield12m}" }
+
+# Or yield one page at a time:
+Brapi.v2.treasury.each_page(max_pages: 5) do |page|
+  puts "Page #{page.pagination.page}/#{page.pagination.total_pages}"
+end
+
+# Enumerable methods Just Work — `each` without a block returns
+# an Enumerator, so you can use first/select/lazy/etc.:
+top_yield = Brapi.v2.fii
+  .first(100)
+  .sort_by { |f| -(f.dividend_yield12m || 0) }
+  .first(5)
+
+ipca_bonds = Brapi.v2.treasury
+  .lazy
+  .select { |b| b.indexer == "ipca" }
+  .first(10)
+
+# Custom params pass through to the underlying `list` call:
+Brapi.quote.each(sort_by: "volume", sort_order: "desc") { |s| ... }
+```
+
+`max_pages:` (default `10_000`) caps the walk in case the upstream
+forgets to signal the end. `page:` lets you start from a specific page.
+
+`count` and `size` take a fast path: they fetch only the first page and
+read `pagination.total_items` (or `item_count` on Quote), so
+`Brapi.v2.fii.count` is one HTTP call, not 81. Pass a block to `count`
+when you want Enumerable filtering semantics — that still walks every
+page, as expected.
+
 ## Error handling
 
 All errors inherit from `Brapi::Error`:

data/lib/brapi/resources/paginated.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Resources
+    # Adds auto-pagination helpers (`#each_page`, `#each`, plus a fast
+    # `#count` / `#size`) to a Resource around an existing list-style method.
+    #
+    # Usage:
+    #
+    #   class Brapi::Resources::V2::Fii < Brapi::Resource
+    #     include Brapi::Resources::Paginated
+    #     paginates items: :fiis
+    #
+    #     def list(**params)
+    #       # ...
+    #     end
+    #   end
+    #
+    # ## Requirements on the host
+    #
+    # The list-style method named by `via:` (default `:list`) must accept a
+    # `page:` keyword argument. The mixin sets this on every iteration to walk
+    # through pages; if the host's `list` rejects `page:` the first iteration
+    # will raise `ArgumentError`.
+    #
+    # ## Pagination shapes
+    #
+    # Two shapes are supported:
+    #
+    # 1. **Nested** (FII / Treasury): the response has a `pagination` sub-object
+    #    with `page`, `has_next_page`, `total_items`. This is the default.
+    # 2. **Flat** (Quote#list): the response exposes `current_page` /
+    #    `has_next_page` / `item_count` directly. Pass `has_next:`, `next_page:`
+    #    and `count_from:` lambdas to override the readers.
+    #
+    # ## Safety
+    #
+    # `max_pages:` (default `DEFAULT_MAX_PAGES`) caps any walk — protects
+    # against runaway loops if the upstream forgets to set
+    # `has_next_page = false`. The cap is checked **before** each fetch so
+    # `max_pages: 0` yields nothing.
+    #
+    # ## #count behaviour
+    #
+    # When called with no args and no block, `#count` fetches **only the first
+    # page** and reads `pagination.total_items` (or whatever `count_from:`
+    # returns), avoiding a full walk. When called with an item or a block, it
+    # delegates to the standard `Enumerable#count` (which walks every page).
+    module Paginated
+      DEFAULT_MAX_PAGES = 10_000
+
+      def self.included(base)
+        base.include(Enumerable)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def paginates(items:, via: :list, has_next: nil, next_page: nil, count_from: nil)
+          has_next   ||= ->(resp) { resp.pagination&.has_next_page }
+          next_page  ||= ->(resp) { (resp.pagination&.page || 0) + 1 }
+          count_from ||= ->(resp) { resp.pagination&.total_items }
+
+          define_each_page(via: via, has_next: has_next, next_page: next_page)
+          define_each(items: items)
+          define_count(via: via, count_from: count_from)
+        end
+
+        private
+
+        def define_each_page(via:, has_next:, next_page:)
+          define_method(:each_page) do |max_pages: Brapi::Resources::Paginated::DEFAULT_MAX_PAGES, **params, &block|
+            return enum_for(:each_page, max_pages: max_pages, **params) unless block
+
+            current = params.delete(:page) || 1
+            pages_seen = 0
+            loop do
+              break if pages_seen >= max_pages
+
+              resp = public_send(via, **params, page: current)
+              block.call(resp)
+              pages_seen += 1
+              break unless has_next.call(resp)
+
+              current = next_page.call(resp)
+            end
+          end
+        end
+
+        def define_each(items:)
+          define_method(:each) do |max_pages: Brapi::Resources::Paginated::DEFAULT_MAX_PAGES, **params, &block|
+            return enum_for(:each, max_pages: max_pages, **params) unless block
+
+            each_page(max_pages: max_pages, **params) do |resp|
+              resp.public_send(items).each { |item| block.call(item) }
+            end
+          end
+        end
+
+        def define_count(via:, count_from:)
+          define_method(:count) do |*args, &block|
+            # count(item) and count { block } use Enumerable's filtering
+            # semantics — fall back to the standard walk.
+            return super(*args, &block) unless args.empty? && block.nil?
+
+            total = count_from.call(public_send(via, page: 1))
+            total.nil? ? super(*args, &block) : total
+          end
+
+          define_method(:size) { count }
+        end
+      end
+    end
+  end
+end

data/lib/brapi/resources/quote.rb

@@ -5,6 +5,15 @@ require "cgi"
 module Brapi
   module Resources
     class Quote < Brapi::Resource
+      include Brapi::Resources::Paginated
+
+      # rubocop:disable Style/SymbolProc -- arrow-form keeps the three lambdas visually aligned
+      paginates items: :stocks,
+                has_next: ->(r) { r.has_next_page },
+                next_page: ->(r) { (r.current_page || 0) + 1 },
+                count_from: ->(r) { r.item_count }
+      # rubocop:enable Style/SymbolProc
+
       # GET /api/quote/{tickers}
       def retrieve(tickers, **params)
         tickers_str = Array(tickers).join(",")

data/lib/brapi/resources/v2/fii.rb

@@ -4,6 +4,10 @@ module Brapi
   module Resources
     class V2
       class Fii < Brapi::Resource
+        include Brapi::Resources::Paginated
+
+        paginates items: :fiis
+
         # GET /api/v2/fii/list
         def list(**params)
           raw = get("/api/v2/fii/list", params: params)

data/lib/brapi/resources/v2/treasury.rb

@@ -4,6 +4,10 @@ module Brapi
   module Resources
     class V2
       class Treasury < Brapi::Resource
+        include Brapi::Resources::Paginated
+
+        paginates items: :results
+
         # GET /api/v2/treasury/list
         def list(**params)
           raw = get("/api/v2/treasury/list", params: params)

data/lib/brapi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brapi
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/brapi.rb

@@ -63,7 +63,9 @@ require "brapi/models/v2/treasury_bond"
 require "brapi/models/v2/treasury_list_response"
 require "brapi/models/v2/treasury_indicators_response"
 
-# Resources — v2 (parent class) must load before its nested classes
+# Resources — v2 (parent class) must load before its nested classes,
+# and Paginated must load before any resource that includes it.
+require "brapi/resources/paginated"
 require "brapi/resources/quote"
 require "brapi/resources/available"
 require "brapi/resources/v2"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brapi-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Rômulo Storel
@@ -102,6 +102,7 @@ files:
 - lib/brapi/models/value_added_entry.rb
 - lib/brapi/resource.rb
 - lib/brapi/resources/available.rb
+- lib/brapi/resources/paginated.rb
 - lib/brapi/resources/quote.rb
 - lib/brapi/resources/v2.rb
 - lib/brapi/resources/v2/crypto.rb