brapi-ruby-sdk 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 067f66457b229d2598c199c370bf18c09e1bc32f86c979227bf4b9dd739cf4f2
-  data.tar.gz: 37e12fd6e0c2140778b4c8eb1657100106115576a72ebac685163a7b4a603038
+  metadata.gz: 05b2bc6fb4061903f31d59574c62333d8410d7228d3e9b1664a3efc04e024eee
+  data.tar.gz: 299938eb28c85c3b53d0c56e78f40f3ff552bc662b513ea1bb2db051db3d35f6
 SHA512:
-  metadata.gz: 2b81123b4037098cefbbc33b6f890e5831a4ec79bbea11c91d8da7e4df0bb921e09b48d19a94a8fb5eb7d7136a1c6ca6306785dbd23cdb29e74fc935717b3f0f
-  data.tar.gz: 592a36531a95f0a44fe3171f10053205c943d54c5912e5da94595871bd567e41dd22cc5da2ca260a6d549da2b26543df2c5eaed550c88a6381034cf3173efe98
+  metadata.gz: 2aeaa5ecd337d64825b59a7ff6617a74c9de2f8b14a0d83891f23c51ca79a5c7dec5918da537604d43fe13ee23eb602c50295b851d83258f1453f71c9ccf6929
+  data.tar.gz: 10792774a48f8862197fa6abfa230822121d1d1d519d75d0021dbab3597963dd1caf5e7acfd8f3da589e186a8ddfbe18fd65f0330ff6ddae34d190676dbacd9e

data/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- Typed models for every fundamental module that `client.quote.retrieve(...)`
+  can return when `modules:` is passed:
+  - `Brapi::Models::SummaryProfile` — company profile (industry, sector,
+    website, CNPJ, business summary, employees, administrator fields).
+  - `Brapi::Models::KeyStatisticsEntry` — `defaultKeyStatistics` (TTM, single
+    object) and `defaultKeyStatisticsHistory*` (annual + quarterly arrays),
+    including special JSON keys like `52WeekChange` / `SandP52WeekChange`.
+  - `Brapi::Models::IncomeStatementEntry` — DRE entries (annual + quarterly).
+  - `Brapi::Models::CashflowEntry` — DFC entries (annual + quarterly).
+  - `Brapi::Models::ValueAddedEntry` — DVA entries (annual + quarterly).
+- `Brapi::Models::HistoricalDataPrice` for `historical_data_price` entries
+  plus the surrounding `used_interval` / `used_range` / `valid_intervals` /
+  `valid_ranges` Quote-level fields returned when `range`/`interval` are set.
+- `Brapi::Models::DividendsData` (returned when `dividends=true`) wrapping
+  three typed sub-models: `CashDividend`, `StockDividend`, `Subscription`.
+
+### Changed
+
+- `Brapi::Models::Quote#summary_profile`, `#default_key_statistics`,
+  `#income_statement_history` (and quarterly), `#cashflow_history` (and
+  quarterly), `#value_added_history` (and quarterly) and `#dividends_data`
+  now return typed `Brapi::Models::*` instances instead of raw Hashes /
+  Arrays. Callers that were treating these as Hashes need to switch to
+  attribute access (`quote.summary_profile.industry` instead of
+  `quote.summary_profile["industry"]`); `Model#raw` still exposes the
+  original payload when needed.
+- `Brapi::Models::Quote#historical_data_price` (returned when `range`/
+  `interval` is passed) now resolves to `[Brapi::Models::HistoricalDataPrice]`
+  with typed `open`/`high`/`low`/`close`/`volume`/`adjusted_close` attributes
+  instead of an Array of Hashes. Code building charts off this attribute
+  needs to switch from `entry["close"]` to `entry.close`.
+- `Brapi::Models::BalanceSheetEntry` — fixed JSON-key mismatches for
+  `goodwill` (was looking up `goodwill`, API returns `goodWill`),
+  `other_current_liabilities` (`otherCurrentLiab`), `other_liabilities`
+  (`otherLiab`) and `total_liabilities` (`totalLiab`); added `type`,
+  `minority_interest`, `capital_surplus`. Pre-existing v0.1.0 callers that
+  read these four fields will now see actual values (they returned `nil`
+  before).
+- `Brapi::Models::FinancialDataEntry` — adds `type`, `current_price`,
+  `earnings_growth_annual` and `revenue_growth_annual` so it can model
+  `financialDataHistory[*]` (annual + quarterly) in addition to the TTM
+  `financialData` object.
+
 ## [0.1.0] - 2026-05-28
 
 ### Added

data/README.md

@@ -1,5 +1,11 @@
 # brapi-ruby-sdk
 
+[![CI](https://github.com/romulostorel/brapi-ruby-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/romulostorel/brapi-ruby-sdk/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/brapi-ruby-sdk.svg)](https://rubygems.org/gems/brapi-ruby-sdk)
+[![Downloads](https://img.shields.io/gem/dt/brapi-ruby-sdk.svg)](https://rubygems.org/gems/brapi-ruby-sdk)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red.svg)](https://www.ruby-lang.org/)
+
 Ruby SDK for the [brapi.dev](https://brapi.dev) API — Brazilian stock market quotes, cryptocurrencies, currency exchange rates, inflation (IPCA) and prime rate (SELIC) data.
 
 This SDK provides parity with the official [brapi TypeScript](https://github.com/brapi-dev/brapi-typescript) and [brapi Python](https://github.com/brapi-dev/brapi-python) SDKs, covering 11 endpoints in v0.1.
@@ -87,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`).
 
@@ -110,8 +124,14 @@ quote.regular_market_change_percent # => -0.95
 quote.market_cap                   # => 483937892568
 quote.fifty_two_week_range         # => "28.86 - 38.66"
 quote.financial_data               # => Brapi::Models::FinancialDataEntry
-quote.summary_profile              # => Hash with company info
-quote.historical_data_price        # => Array of price points (when range/interval are given)
+quote.summary_profile              # => Brapi::Models::SummaryProfile
+quote.summary_profile.industry     # => "Petróleo e Gás Integrado"
+quote.default_key_statistics       # => Brapi::Models::KeyStatisticsEntry
+quote.income_statement_history     # => [Brapi::Models::IncomeStatementEntry]
+quote.cashflow_history             # => [Brapi::Models::CashflowEntry]
+quote.value_added_history          # => [Brapi::Models::ValueAddedEntry]
+quote.historical_data_price        # => [Brapi::Models::HistoricalDataPrice]
+quote.dividends_data               # => Brapi::Models::DividendsData (cash + stock + subscriptions)
 ```
 
 ### Multi-ticker
@@ -149,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
@@ -195,13 +258,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/balance_sheet_entry.rb

@@ -2,33 +2,45 @@
 
 module Brapi
   module Models
+    # Common fields of `balanceSheetHistory[*]` (annual) and
+    # `balanceSheetHistoryQuarterly[*]`. The full brapi payload exposes ~120
+    # accounting-specific fields (Brazilian GAAP + segment-specific rows);
+    # the SDK ships the most-used ones typed and keeps the rest available
+    # through Model#raw.
     class BalanceSheetEntry < Brapi::Model
+      attribute :type, type: :string
       attribute :end_date, type: :string
+
       attribute :cash
       attribute :short_term_investments
       attribute :net_receivables
       attribute :inventory
       attribute :other_current_assets
       attribute :total_current_assets
+
       attribute :long_term_investments
       attribute :property_plant_equipment
-      attribute :goodwill
+      attribute :goodwill, json_key: "goodWill"
       attribute :intangible_assets
       attribute :other_assets
       attribute :total_assets
+
       attribute :accounts_payable
       attribute :short_long_term_debt
-      attribute :other_current_liabilities
+      attribute :other_current_liabilities, json_key: "otherCurrentLiab"
       attribute :total_current_liabilities
       attribute :long_term_debt
-      attribute :other_liabilities
-      attribute :total_liabilities
+      attribute :other_liabilities, json_key: "otherLiab"
+      attribute :total_liabilities, json_key: "totalLiab"
+
       attribute :common_stock
       attribute :retained_earnings
       attribute :treasury_stock
       attribute :other_stockholder_equity
       attribute :total_stockholder_equity
       attribute :net_tangible_assets
+      attribute :minority_interest
+      attribute :capital_surplus
     end
   end
 end

data/lib/brapi/models/cash_dividend.rb

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

data/lib/brapi/models/cashflow_entry.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    class CashflowEntry < Brapi::Model
+      attribute :type, type: :string
+      attribute :end_date, type: :string
+      attribute :operating_cash_flow
+      attribute :income_from_operations
+      attribute :net_income_before_taxes
+      attribute :adjustments_to_profit_or_loss
+      attribute :changes_in_assets_and_liabilities
+      attribute :other_operating_activities
+      attribute :cash_generated_in_operations
+      attribute :investment_cash_flow
+      attribute :financing_cash_flow
+      attribute :exchange_variation_without_cash
+      attribute :foreign_exchange_rate_without_cash
+      attribute :increase_or_decrease_in_cash
+      attribute :initial_cash_balance
+      attribute :final_cash_balance
+      attribute :free_cash_flow
+    end
+  end
+end

data/lib/brapi/models/dividends_data.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    class DividendsData < Brapi::Model
+      attribute :cash_dividends, type: [Brapi::Models::CashDividend]
+      attribute :stock_dividends, type: [Brapi::Models::StockDividend]
+      attribute :subscriptions, type: [Brapi::Models::Subscription]
+    end
+  end
+end

data/lib/brapi/models/financial_data_entry.rb

@@ -2,29 +2,35 @@
 
 module Brapi
   module Models
+    # Backs both `financialData` (single TTM object, no type/end_date)
+    # and `financialDataHistory[*]` (annual/quarterly array entries).
     class FinancialDataEntry < Brapi::Model
+      attribute :type, type: :string
       attribute :end_date, type: :string
+      attribute :current_price, type: :float
       attribute :total_revenue
-      attribute :revenue_per_share
+      attribute :revenue_per_share, type: :float
       attribute :gross_profits
       attribute :ebitda
       attribute :operating_cashflow
       attribute :free_cashflow
       attribute :total_cash
-      attribute :total_cash_per_share
+      attribute :total_cash_per_share, type: :float
       attribute :total_debt
-      attribute :debt_to_equity
-      attribute :current_ratio
-      attribute :quick_ratio
-      attribute :return_on_assets
-      attribute :return_on_equity
-      attribute :gross_margins
-      attribute :ebitda_margins
-      attribute :operating_margins
-      attribute :profit_margins
-      attribute :earnings_growth
-      attribute :revenue_growth
-      attribute :financial_currency
+      attribute :debt_to_equity, type: :float
+      attribute :current_ratio, type: :float
+      attribute :quick_ratio, type: :float
+      attribute :return_on_assets, type: :float
+      attribute :return_on_equity, type: :float
+      attribute :gross_margins, type: :float
+      attribute :ebitda_margins, type: :float
+      attribute :operating_margins, type: :float
+      attribute :profit_margins, type: :float
+      attribute :earnings_growth, type: :float
+      attribute :revenue_growth, type: :float
+      attribute :earnings_growth_annual, type: :float
+      attribute :revenue_growth_annual, type: :float
+      attribute :financial_currency, type: :string
     end
   end
 end

data/lib/brapi/models/historical_data_price.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    class HistoricalDataPrice < Brapi::Model
+      attribute :date, type: :integer
+      attribute :open, type: :float
+      attribute :high, type: :float
+      attribute :low, type: :float
+      attribute :close, type: :float
+      attribute :volume, type: :integer
+      attribute :adjusted_close, type: :float
+    end
+  end
+end

data/lib/brapi/models/income_statement_entry.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    class IncomeStatementEntry < Brapi::Model
+      attribute :type, type: :string
+      attribute :end_date, type: :string
+      attribute :total_revenue
+      attribute :cost_of_revenue
+      attribute :gross_profit
+      attribute :research_development
+      attribute :selling_general_administrative
+      attribute :non_recurring
+      attribute :other_operating_expenses
+      attribute :total_operating_expenses
+      attribute :operating_income
+      attribute :total_other_income_expense_net
+      attribute :ebit
+      attribute :interest_expense
+      attribute :income_before_tax
+      attribute :income_tax_expense
+      attribute :minority_interest
+      attribute :net_income_from_continuing_ops
+      attribute :discontinued_operations
+      attribute :extraordinary_items
+      attribute :effect_of_accounting_charges
+      attribute :other_items
+      attribute :net_income
+      attribute :net_income_applicable_to_common_shares
+      attribute :sales_expenses
+      attribute :losses_due_to_non_recoverability_of_assets
+      attribute :other_operating_income
+      attribute :equity_income_result
+      attribute :financial_result
+      attribute :financial_income
+      attribute :financial_expenses
+      attribute :current_taxes
+      attribute :deferred_taxes
+      attribute :income_before_statutory_participations_and_contributions
+      attribute :basic_earnings_per_common_share, type: :float
+      attribute :diluted_earnings_per_common_share, type: :float
+      attribute :basic_earnings_per_preferred_share, type: :float
+      attribute :profit_sharing_and_statutory_contributions
+      attribute :diluted_earnings_per_preferred_share, type: :float
+      attribute :claims_and_operations_costs
+      attribute :administrative_costs
+      attribute :other_operating_income_and_expenses
+      attribute :earnings_per_share, type: :float
+      attribute :basic_earnings_per_share, type: :float
+      attribute :diluted_earnings_per_share, type: :float
+      attribute :insurance_operations
+      attribute :reinsurance_operations
+      attribute :complementary_pension_operations
+      attribute :capitalization_operations
+      attribute :clean_ebit
+      attribute :clean_ebitda
+      attribute :clean_nopat
+      attribute :clean_net_income
+    end
+  end
+end

data/lib/brapi/models/key_statistics_entry.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    # Used for both `defaultKeyStatistics` (single TTM object, no type/end_date)
+    # and `defaultKeyStatisticsHistory[*]` (array of annual entries) and the
+    # quarterly variant. Fields not present in a given payload come back nil.
+    class KeyStatisticsEntry < Brapi::Model
+      attribute :type, type: :string
+      attribute :end_date, type: :string
+      attribute :price_hint
+      attribute :price
+      attribute :enterprise_value
+      attribute :forward_pe, type: :float, json_key: "forwardPE"
+      attribute :profit_margins, type: :float
+      attribute :float_shares
+      attribute :shares_outstanding
+      attribute :shares_short
+      attribute :shares_short_prior_month
+      attribute :shares_short_previous_month_date
+      attribute :date_short_interest
+      attribute :shares_percent_shares_out, type: :float
+      attribute :held_percent_insiders, type: :float
+      attribute :held_percent_institutions, type: :float
+      attribute :short_ratio, type: :float
+      attribute :short_percent_of_float, type: :float
+      attribute :beta, type: :float
+      attribute :implied_shares_outstanding
+      attribute :category, type: :string
+      attribute :book_value, type: :float
+      attribute :price_to_book, type: :float
+      attribute :fund_family, type: :string
+      attribute :legal_type, type: :string
+      attribute :last_fiscal_year_end
+      attribute :next_fiscal_year_end
+      attribute :most_recent_quarter
+      attribute :earnings_quarterly_growth, type: :float
+      attribute :net_income_to_common
+      attribute :trailing_eps, type: :float
+      attribute :forward_eps, type: :float
+      attribute :peg_ratio, type: :float
+      attribute :last_split_factor, type: :string
+      attribute :last_split_date
+      attribute :enterprise_to_revenue, type: :float
+      attribute :enterprise_to_ebitda, type: :float
+      attribute :fifty_two_week_change, type: :float, json_key: "52WeekChange"
+      attribute :sandp_fifty_two_week_change, type: :float, json_key: "SandP52WeekChange"
+      attribute :last_dividend_value, type: :float
+      attribute :last_dividend_date
+      attribute :ytd_return, type: :float
+      attribute :beta3_year, type: :float
+      attribute :total_assets
+      attribute :yield, type: :float
+      attribute :fund_inception_date
+      attribute :three_year_average_return, type: :float
+      attribute :five_year_average_return, type: :float
+      attribute :morning_star_overall_rating
+      attribute :morning_star_risk_rating
+      attribute :annual_report_expense_ratio, type: :float
+      attribute :last_cap_gain, type: :float
+      attribute :annual_holdings_turnover, type: :float
+      attribute :market_cap
+      attribute :trailing_pe, type: :float, json_key: "trailingPE"
+      attribute :earnings_per_share, type: :float
+      attribute :dividend_yield, type: :float
+    end
+  end
+end

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/quote.rb

@@ -34,27 +34,32 @@ module Brapi
       attribute :earnings_per_share, type: :float
       attribute :logourl, type: :string
 
-      # Module-only fields — exposed as raw hashes/arrays in v0.1.0.
-      # Dedicated typed models will land in subsequent minor versions.
-      attribute :summary_profile
+      # Fundamental module slots (typed)
+      attribute :summary_profile, type: Brapi::Models::SummaryProfile
       attribute :balance_sheet_history, type: [Brapi::Models::BalanceSheetEntry]
       attribute :balance_sheet_history_quarterly, type: [Brapi::Models::BalanceSheetEntry]
-      attribute :default_key_statistics
-      attribute :default_key_statistics_history
-      attribute :default_key_statistics_history_quarterly
-      attribute :income_statement_history
-      attribute :income_statement_history_quarterly
+      attribute :default_key_statistics, type: Brapi::Models::KeyStatisticsEntry
+      attribute :default_key_statistics_history, type: [Brapi::Models::KeyStatisticsEntry]
+      attribute :default_key_statistics_history_quarterly, type: [Brapi::Models::KeyStatisticsEntry]
+      attribute :income_statement_history, type: [Brapi::Models::IncomeStatementEntry]
+      attribute :income_statement_history_quarterly, type: [Brapi::Models::IncomeStatementEntry]
       attribute :financial_data, type: Brapi::Models::FinancialDataEntry
       attribute :financial_data_history, type: [Brapi::Models::FinancialDataEntry]
       attribute :financial_data_history_quarterly, type: [Brapi::Models::FinancialDataEntry]
-      attribute :value_added_history
-      attribute :value_added_history_quarterly
-      attribute :cashflow_history
-      attribute :cashflow_history_quarterly
+      attribute :value_added_history, type: [Brapi::Models::ValueAddedEntry]
+      attribute :value_added_history_quarterly, type: [Brapi::Models::ValueAddedEntry]
+      attribute :cashflow_history, type: [Brapi::Models::CashflowEntry]
+      attribute :cashflow_history_quarterly, type: [Brapi::Models::CashflowEntry]
 
-      # Historical price data when `range`/`interval` are passed.
-      attribute :historical_data_price
-      attribute :dividends_data
+      # Historical price data — returned when `range`/`interval` are passed.
+      attribute :used_interval, type: :string
+      attribute :used_range, type: :string
+      attribute :valid_intervals
+      attribute :valid_ranges
+      attribute :historical_data_price, type: [Brapi::Models::HistoricalDataPrice]
+
+      # Dividends — returned when `dividends=true`.
+      attribute :dividends_data, type: Brapi::Models::DividendsData
     end
   end
 end

data/lib/brapi/models/stock_dividend.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    class StockDividend < Brapi::Model
+      attribute :asset_issued, type: :string
+      attribute :factor, type: :float
+      attribute :complete_factor, type: :string
+      attribute :approved_on, type: :time
+      attribute :isin_code, type: :string
+      attribute :label, type: :string
+      attribute :last_date_prior, type: :time
+      attribute :remarks, type: :string
+    end
+  end
+end

data/lib/brapi/models/subscription.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Brapi
+  module Models
+    # NOTE: field list is inferred from CashDividend / StockDividend shape — the
+    # brapi `subscriptions` payload captured during v0.2 development was empty.
+    # If the live API returns different keys, attribute readers will return nil
+    # silently; `Model#raw` still exposes the original Hash. Update fields once
+    # a real payload is observed.
+    class Subscription < Brapi::Model
+      attribute :asset_issued, type: :string
+      attribute :factor, type: :float
+      attribute :price_unit, type: :float
+      attribute :approved_on, type: :time
+      attribute :isin_code, type: :string
+      attribute :label, type: :string
+      attribute :last_date_prior, type: :time
+      attribute :subscription_date, type: :time
+      attribute :remarks, type: :string
+    end
+  end
+end