brapi-ruby-sdk 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17dcaf025c1a282bf971841780365f24611ba3b4ebeb3fa7700f780a7c4b54e8
-  data.tar.gz: e754c29b797a0db5fe898252196944cfb65f5be5fcd8161690b523cdc24a1849
+  metadata.gz: 2f184be4deccafcbafd23f9275a7801290357e72c13d78eee0d5604aaa60edd2
+  data.tar.gz: f3e70b267473bc7dc2222463a7f175578b8ad3099657dccddf71571237e884e7
 SHA512:
-  metadata.gz: e7bf7e24c594c784c2c9866d8a0cdb3cb1c71d2329ae640849d37f8ca456901e0baca13969677a8abbe3725f8c4ed0de2cecf191055530d5f1ddc0e919a4dc22
-  data.tar.gz: 3e5c26a51421088b18f7bb1b2fc989c9e068d14c04a8c4356f6ca9810b75c01a55b6f5dfa5758913316f542af47f0118ef420881e1dec05d6da9e885437cc9fc
+  metadata.gz: 116a1de195f79a3b4943ae68ad6f0b9133f66145282e0f124564f2083a5a7b87d5325e65502fcaf059f49b2538bda73a3ef304c0ef9b8ffb8b3746bc41f4c8ad
+  data.tar.gz: f6516906c904e17d2732d108f4b989c30bba0a9477144aeeb59db534f640391b1d0937df282e600c6837ff39899bb52eb0f51eecebbcea7ea8b19b4993684b1b

data/CHANGELOG.md

@@ -7,6 +7,64 @@ 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
+
+- **FIIs (Fundos Imobiliários)** — new `client.v2.fii.*` resource backed by
+  `/api/v2/fii/...`:
+  - `client.v2.fii.list(**params)` — paginated listing
+  - `client.v2.fii.indicators(symbols, **params)` — current NAV / yield / etc.
+  - `client.v2.fii.historical(symbols, **params)` — OHLCV history
+  - `client.v2.fii.dividends(symbols, **params)` — payment history
+- **Macro (séries temporais)** — new `client.v2.macro.*` resource backed by
+  `/api/v2/macro`:
+  - `client.v2.macro.retrieve(symbols, **params)` — series + observations
+    for SELIC, IPCA, CDI and other indicators
+  - `client.v2.macro.list_available` — all available series + categories
+- **Tesouro Direto** — new `client.v2.treasury.*` resource backed by
+  `/api/v2/treasury/...`:
+  - `client.v2.treasury.list(**params)` — paginated bond listing
+  - `client.v2.treasury.indicators(symbols, **params)` — current rates +
+    prices for specific bonds
+- Typed models for every new shape: `Fii`, `FiiDividend`, `FiiHistory`,
+  `MacroSeries`, `MacroObservation`, `MacroResult`, `TreasuryBond`,
+  `TreasuryRateInfo`, `Pagination`, plus per-endpoint Response classes.
+- `Brapi::Models::V2::Pagination` reused across the paginated FII and
+  Treasury list endpoints.
+
+### Notes
+
+- All v0.3 endpoints require a paid brapi token (Startup or Pro plan).
+- Schemas were captured directly from the live API (MXRF11, SELIC,
+  tesouro-selic-01032031); an ad-hoc smoke test against brapi.dev
+  confirmed round-trip parsing for every new endpoint.
+
 ## [0.2.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -93,6 +93,14 @@ client.quote.retrieve("PETR4")
 | `client.v2.inflation.list_available`   | `GET /api/v2/inflation/available`     | Countries with inflation data          |
 | `client.v2.prime_rate.retrieve(...)`   | `GET /api/v2/prime-rate`              | SELIC / prime-rate series              |
 | `client.v2.prime_rate.list_available`  | `GET /api/v2/prime-rate/available`    | Countries with prime-rate data         |
+| `client.v2.fii.list(...)`              | `GET /api/v2/fii/list`                | Real Estate Funds (FIIs) listing       |
+| `client.v2.fii.indicators(syms, ...)`  | `GET /api/v2/fii/indicators`          | FII indicators (NAV, dividend yield)   |
+| `client.v2.fii.historical(syms, ...)`  | `GET /api/v2/fii/historical`          | FII OHLCV historical prices            |
+| `client.v2.fii.dividends(syms, ...)`   | `GET /api/v2/fii/dividends`           | FII dividend payment history           |
+| `client.v2.macro.retrieve(syms, ...)`  | `GET /api/v2/macro`                   | Macro time series (SELIC, IPCA, CDI…)  |
+| `client.v2.macro.list_available`       | `GET /api/v2/macro/available`         | Available macro series                 |
+| `client.v2.treasury.list(...)`         | `GET /api/v2/treasury/list`           | Tesouro Direto bonds listing           |
+| `client.v2.treasury.indicators(syms…)` | `GET /api/v2/treasury/indicators`     | Current rates / prices for bonds       |
 
 All params are passed as Ruby kwargs (snake_case) and the SDK converts them to the camelCase expected by the API (e.g. `sort_by: "volume"` → `?sortBy=volume`).
 
@@ -161,6 +169,49 @@ resp = Brapi.v2.prime_rate.retrieve(country: "brazil")
 resp.prime_rate.each { |p| puts "#{p.date}: #{p.value}% p.a." }
 ```
 
+### Real Estate Funds (FIIs)
+
+```ruby
+# Browse FIIs with pagination
+page = Brapi.v2.fii.list(limit: 20)
+page.fiis.each { |f| puts "#{f.symbol} (#{f.segmento_atuacao}): R$ #{f.price}" }
+puts "Page #{page.pagination.page}/#{page.pagination.total_pages}"
+
+# Current indicators for specific FIIs
+ind = Brapi.v2.fii.indicators(%w[MXRF11 KNRI11])
+ind.fiis.each { |f| puts "#{f.symbol} NAV=#{f.nav_per_share} DY12m=#{f.dividend_yield12m}" }
+
+# Dividend history
+divs = Brapi.v2.fii.dividends("MXRF11")
+divs.dividends.each { |d| puts "#{d.payment_date}: R$ #{d.rate}" }
+```
+
+### Macro time series (SELIC, IPCA, CDI...)
+
+```ruby
+resp = Brapi.v2.macro.retrieve("SELIC")
+result = resp.results.first
+puts "#{result.series.name} (#{result.series.unit})"
+result.observations.each { |o| puts "#{o.date}: #{o.value}" }
+
+# List available series
+Brapi.v2.macro.list_available.results.each { |s| puts "#{s.slug}: #{s.name}" }
+```
+
+### Tesouro Direto (Treasury)
+
+```ruby
+# Browse available bonds
+page = Brapi.v2.treasury.list
+page.results.each do |bond|
+  puts "#{bond.symbol}: buy=#{bond.buy_rate}% sell_price=R$ #{bond.sell_price}"
+  puts "  Rate interpretation: #{bond.rate_info.description}"
+end
+
+# Current rates for specific bonds
+Brapi.v2.treasury.indicators("tesouro-selic-01032031")
+```
+
 ### List/filter stocks
 
 ```ruby
@@ -169,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`:
@@ -207,13 +299,12 @@ The SDK automatically retries transient 5xx errors (502/503/504) up to twice wit
 
 ## Roadmap
 
-v0.1 ships the 11 endpoints supported by the official SDKs. Future minor versions will add:
+v0.1 shipped the 11 endpoints supported by the official SDKs. v0.2 added typed
+models for every Quote fundamental module. v0.3 added FIIs, Macro and Tesouro
+Direto. Future minor versions:
 
-- `client.fii.*` — Real Estate Investment Funds (FIIs)
-- `client.macro.*` — Macroeconomic time series
-- `client.options.*` — Options chain & history
-- `client.treasury.*` — Tesouro Direto
-- `client.futures.*` — Futures contracts
+- `client.v2.options.*` — Options chain & history
+- `client.v2.futures.*` — Futures contracts
 
 ## Development
 

data/lib/brapi/model.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "date"
 require "time"
 
 module Brapi

data/lib/brapi/models/pagination.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    # Pagination metadata returned by paginated brapi endpoints
+    # (e.g. /api/v2/fii/list, /api/v2/treasury/list, /api/quote/list).
+    class Pagination < Brapi::Model
+      attribute :page, type: :integer
+      attribute :limit, type: :integer
+      attribute :total_items, type: :integer
+      attribute :total_pages, type: :integer
+      attribute :has_next_page, type: :boolean
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      # Single class backing both /api/v2/fii/list (basic info) and
+      # /api/v2/fii/indicators (basic info + current indicators).
+      # Indicator-only fields come back nil from the list endpoint.
+      class Fii < Brapi::Model
+        attribute :symbol, type: :string
+        attribute :name, type: :string
+        attribute :cnpj, type: :string
+        attribute :mandate, type: :string
+        # NOTE: brapi exposes these two fields in Portuguese (`segmentoAtuacao`,
+        # `tipoGestao`); everything else in the response uses English. If the
+        # upstream renames them in a future API revision, callers reading
+        # `#segmento_atuacao` / `#tipo_gestao` will silently get nil and need
+        # the attribute names updated here.
+        attribute :segmento_atuacao, type: :string
+        attribute :tipo_gestao, type: :string
+        attribute :segment_type, type: :string
+
+        attribute :administrator_name, type: :string
+        attribute :administrator_cnpj, type: :string
+        attribute :administrator_address, type: :string
+        attribute :administrator_address_number, type: :string
+        attribute :administrator_address_complement, type: :string
+        attribute :administrator_district, type: :string
+        attribute :administrator_city, type: :string
+        attribute :administrator_state, type: :string
+        attribute :administrator_zip_code, type: :string
+        attribute :administrator_phone1, type: :string
+        attribute :administrator_phone2, type: :string
+        attribute :administrator_phone3, type: :string
+        attribute :administrator_website, type: :string
+        attribute :administrator_email, type: :string
+
+        attribute :price, type: :float
+        attribute :nav_per_share, type: :float
+        attribute :price_to_nav, type: :float
+        attribute :dividend_yield12m, type: :float, json_key: "dividendYield12m"
+        attribute :total_investors, type: :integer
+
+        # Indicators-only fields (nil when returned by /fii/list)
+        attribute :as_of_date, type: :date
+        attribute :dividend_yield1m, type: :float, json_key: "dividendYield1m"
+        attribute :monthly_return, type: :float
+        attribute :shares_outstanding, type: :integer
+        attribute :equity
+        attribute :total_assets
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_dividend.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class FiiDividend < Brapi::Model
+        attribute :symbol, type: :string
+        attribute :label, type: :string
+        attribute :rate, type: :float
+        attribute :related_to, type: :string
+        attribute :approved_on, type: :time
+        attribute :last_date_prior, type: :time
+        attribute :payment_date, type: :time
+        attribute :isin_code, type: :string
+        attribute :remarks, type: :string
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_dividends_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class FiiDividendsResponse < Brapi::Model
+        attribute :dividends, type: [Brapi::Models::V2::FiiDividend]
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_historical_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class FiiHistoricalResponse < Brapi::Model
+        attribute :fiis, type: [Brapi::Models::V2::FiiHistory]
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_history.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      # Wraps a single FII's historical price series. The historical_data_price
+      # entries reuse Brapi::Models::HistoricalDataPrice (same OHLCV shape as
+      # /api/quote/{ticker}?range=...).
+      class FiiHistory < Brapi::Model
+        attribute :symbol, type: :string
+        attribute :historical_data_price, type: [Brapi::Models::HistoricalDataPrice]
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_indicators_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class FiiIndicatorsResponse < Brapi::Model
+        attribute :fiis, type: [Brapi::Models::V2::Fii]
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/fii_list_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class FiiListResponse < Brapi::Model
+        attribute :fiis, type: [Brapi::Models::V2::Fii]
+        attribute :pagination, type: Brapi::Models::Pagination
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/macro_list_available_response.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class MacroListAvailableResponse < Brapi::Model
+        attribute :results, type: [Brapi::Models::V2::MacroSeries]
+        attribute :categories
+        attribute :count, type: :integer
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/macro_observation.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class MacroObservation < Brapi::Model
+        attribute :date, type: :date
+        attribute :value, type: :float
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/macro_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      # One result entry from /api/v2/macro: a MacroSeries description plus
+      # the observation rows (date + value) for that series.
+      class MacroResult < Brapi::Model
+        attribute :series, type: Brapi::Models::V2::MacroSeries
+        attribute :observations, type: [Brapi::Models::V2::MacroObservation]
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/macro_retrieve_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class MacroRetrieveResponse < Brapi::Model
+        attribute :results, type: [Brapi::Models::V2::MacroResult]
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/macro_series.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class MacroSeries < Brapi::Model
+        attribute :slug, type: :string
+        attribute :name, type: :string
+        attribute :description, type: :string
+        attribute :unit, type: :string
+        attribute :frequency, type: :string
+        attribute :category, type: :string
+        attribute :start_date, type: :date
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/treasury_bond.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      # Single Tesouro Direto bond as returned by /api/v2/treasury/list and
+      # /api/v2/treasury/indicators (both endpoints share the same shape).
+      #
+      # buyRate / sellRate semantics depend on the bond's indexer — see
+      # TreasuryRateInfo#rate_type / #description.
+      class TreasuryBond < Brapi::Model
+        attribute :symbol, type: :string
+        attribute :bond_type, type: :string
+        attribute :indexer, type: :string
+        attribute :coupon_type, type: :string
+        attribute :maturity_date, type: :date
+        attribute :duration_days, type: :integer
+        attribute :base_date, type: :date
+        attribute :buy_rate, type: :float
+        attribute :sell_rate, type: :float
+        attribute :buy_price, type: :float
+        attribute :sell_price, type: :float
+        attribute :base_price, type: :float
+        attribute :rate_info, type: Brapi::Models::V2::TreasuryRateInfo
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/treasury_indicators_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class TreasuryIndicatorsResponse < Brapi::Model
+        attribute :results, type: [Brapi::Models::V2::TreasuryBond]
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/treasury_list_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class TreasuryListResponse < Brapi::Model
+        attribute :results, type: [Brapi::Models::V2::TreasuryBond]
+        attribute :pagination, type: Brapi::Models::Pagination
+        attribute :requested_at, type: :time
+        attribute :took, type: :integer
+      end
+    end
+  end
+end

data/lib/brapi/models/v2/treasury_rate_info.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    module V2
+      class TreasuryRateInfo < Brapi::Model
+        attribute :rate_type, type: :string
+        attribute :rate_unit, type: :string
+        attribute :description, type: :string
+      end
+    end
+  end
+end

data/lib/brapi/resource.rb

@@ -14,6 +14,13 @@ module Brapi
       client.request(:get, path, params: camelize_keys(params))
     end
 
+    # Brapi endpoints that accept a `symbols` query param take a comma-separated
+    # list. Accepts a single String, a single Symbol, or any Enumerable of the
+    # two; always returns a String.
+    def format_symbols(symbols)
+      Array(symbols).join(",")
+    end
+
     def camelize_keys(params)
       return params if params.nil? || params.empty?
 

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+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)
+          Brapi::Models::V2::FiiListResponse.from_h(raw)
+        end
+
+        # GET /api/v2/fii/indicators?symbols=...
+        def indicators(symbols, **params)
+          raw = get("/api/v2/fii/indicators", params: params.merge(symbols: format_symbols(symbols)))
+          Brapi::Models::V2::FiiIndicatorsResponse.from_h(raw)
+        end
+
+        # GET /api/v2/fii/historical?symbols=...
+        def historical(symbols, **params)
+          raw = get("/api/v2/fii/historical", params: params.merge(symbols: format_symbols(symbols)))
+          Brapi::Models::V2::FiiHistoricalResponse.from_h(raw)
+        end
+
+        # GET /api/v2/fii/dividends?symbols=...
+        def dividends(symbols, **params)
+          raw = get("/api/v2/fii/dividends", params: params.merge(symbols: format_symbols(symbols)))
+          Brapi::Models::V2::FiiDividendsResponse.from_h(raw)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Resources
+    class V2
+      class Macro < Brapi::Resource
+        # GET /api/v2/macro?symbols=...
+        def retrieve(symbols, **params)
+          raw = get("/api/v2/macro", params: params.merge(symbols: format_symbols(symbols)))
+          Brapi::Models::V2::MacroRetrieveResponse.from_h(raw)
+        end
+
+        # GET /api/v2/macro/available
+        def list_available
+          raw = get("/api/v2/macro/available")
+          Brapi::Models::V2::MacroListAvailableResponse.from_h(raw)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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)
+          Brapi::Models::V2::TreasuryListResponse.from_h(raw)
+        end
+
+        # GET /api/v2/treasury/indicators?symbols=...
+        def indicators(symbols, **params)
+          raw = get("/api/v2/treasury/indicators", params: params.merge(symbols: format_symbols(symbols)))
+          Brapi::Models::V2::TreasuryIndicatorsResponse.from_h(raw)
+        end
+      end
+    end
+  end
+end

data/lib/brapi/resources/v2.rb

@@ -24,6 +24,18 @@ module Brapi
       def prime_rate
         @prime_rate ||= Brapi::Resources::V2::PrimeRate.new(client)
       end
+
+      def fii
+        @fii ||= Brapi::Resources::V2::Fii.new(client)
+      end
+
+      def macro
+        @macro ||= Brapi::Resources::V2::Macro.new(client)
+      end
+
+      def treasury
+        @treasury ||= Brapi::Resources::V2::Treasury.new(client)
+      end
     end
   end
 end

data/lib/brapi/version.rb

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

data/lib/brapi.rb

@@ -42,7 +42,30 @@ require "brapi/models/v2/prime_rate_entry"
 require "brapi/models/v2/prime_rate_retrieve_response"
 require "brapi/models/v2/prime_rate_list_available_response"
 
-# Resources — v2 (parent class) must load before its nested classes
+require "brapi/models/pagination"
+
+require "brapi/models/v2/fii"
+require "brapi/models/v2/fii_dividend"
+require "brapi/models/v2/fii_history"
+require "brapi/models/v2/fii_list_response"
+require "brapi/models/v2/fii_indicators_response"
+require "brapi/models/v2/fii_historical_response"
+require "brapi/models/v2/fii_dividends_response"
+
+require "brapi/models/v2/macro_series"
+require "brapi/models/v2/macro_observation"
+require "brapi/models/v2/macro_result"
+require "brapi/models/v2/macro_retrieve_response"
+require "brapi/models/v2/macro_list_available_response"
+
+require "brapi/models/v2/treasury_rate_info"
+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,
+# 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"
@@ -50,6 +73,9 @@ require "brapi/resources/v2/crypto"
 require "brapi/resources/v2/currency"
 require "brapi/resources/v2/inflation"
 require "brapi/resources/v2/prime_rate"
+require "brapi/resources/v2/fii"
+require "brapi/resources/v2/macro"
+require "brapi/resources/v2/treasury"
 
 require "brapi/client"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brapi-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Rômulo Storel
 bindir: bin
 cert_chain: []
-date: 2026-05-28 00:00:00.000000000 Z
+date: 2026-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -63,6 +63,7 @@ files:
 - lib/brapi/models/historical_data_price.rb
 - lib/brapi/models/income_statement_entry.rb
 - lib/brapi/models/key_statistics_entry.rb
+- lib/brapi/models/pagination.rb
 - lib/brapi/models/quote.rb
 - lib/brapi/models/quote_list_item.rb
 - lib/brapi/models/quote_list_response.rb
@@ -76,21 +77,41 @@ files:
 - lib/brapi/models/v2/currency.rb
 - lib/brapi/models/v2/currency_list_available_response.rb
 - lib/brapi/models/v2/currency_retrieve_response.rb
+- lib/brapi/models/v2/fii.rb
+- lib/brapi/models/v2/fii_dividend.rb
+- lib/brapi/models/v2/fii_dividends_response.rb
+- lib/brapi/models/v2/fii_historical_response.rb
+- lib/brapi/models/v2/fii_history.rb
+- lib/brapi/models/v2/fii_indicators_response.rb
+- lib/brapi/models/v2/fii_list_response.rb
 - lib/brapi/models/v2/inflation_entry.rb
 - lib/brapi/models/v2/inflation_list_available_response.rb
 - lib/brapi/models/v2/inflation_retrieve_response.rb
+- lib/brapi/models/v2/macro_list_available_response.rb
+- lib/brapi/models/v2/macro_observation.rb
+- lib/brapi/models/v2/macro_result.rb
+- lib/brapi/models/v2/macro_retrieve_response.rb
+- lib/brapi/models/v2/macro_series.rb
 - lib/brapi/models/v2/prime_rate_entry.rb
 - lib/brapi/models/v2/prime_rate_list_available_response.rb
 - lib/brapi/models/v2/prime_rate_retrieve_response.rb
+- lib/brapi/models/v2/treasury_bond.rb
+- lib/brapi/models/v2/treasury_indicators_response.rb
+- lib/brapi/models/v2/treasury_list_response.rb
+- lib/brapi/models/v2/treasury_rate_info.rb
 - 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
 - lib/brapi/resources/v2/currency.rb
+- lib/brapi/resources/v2/fii.rb
 - lib/brapi/resources/v2/inflation.rb
+- lib/brapi/resources/v2/macro.rb
 - lib/brapi/resources/v2/prime_rate.rb
+- lib/brapi/resources/v2/treasury.rb
 - lib/brapi/version.rb
 homepage: https://github.com/romulostorel/brapi-ruby-sdk
 licenses: