v0.5.0: Typed response models

All client methods now return typed dataclass objects with IDE
autocompletion. Full backwards compatibility preserved — dict-style []
access, .get(), and iteration all work unchanged. Models expose .raw
for the original API dict. Nested sub-objects for complex responses
(Quote.liquidity, Company.fundamentals/technicals/valuation/analysts).
No external dependencies — uses stdlib dataclasses only.

Author: sahmk-sa

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to the `sahmk` Python SDK will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] — 2026-04-02
+
+### Added
+
+- **Typed response models** — all client methods now return typed dataclass objects (e.g., `Quote`, `Company`, `HistoricalResponse`, `FinancialsResponse`, `DividendsResponse`, `EventsResponse`, `MarketSummary`, etc.) with IDE autocompletion and attribute access
+- **Full backwards compatibility** — all typed models support dict-style `[]` access, `.get()`, `.keys()`, `.values()`, `.items()`, and `in` checks; existing code using `result["price"]` continues to work unchanged
+- **`.raw` attribute** — every model exposes the original API response dict via `.raw` for cases where you need the full untyped data
+- **Nested typed models** — complex responses have properly typed sub-objects (e.g., `Quote.liquidity` returns a `Liquidity` object, `Company.fundamentals` returns a `Fundamentals` object)
+- **Plan-aware models** — `Company` model gracefully handles tiered responses (Free: basic fields, Starter: +fundamentals, Pro: +technicals/valuation/analysts) with `None` for unavailable sections
+
+### Changed
+
+- All client methods (`quote()`, `quotes()`, `historical()`, `market_summary()`, `gainers()`, `losers()`, `volume_leaders()`, `value_leaders()`, `sectors()`, `company()`, `financials()`, `dividends()`, `events()`) now return typed model instances instead of plain dicts
+- CLI `_print_json()` now handles model objects by serializing their `.raw` dict
+
 ## [0.4.0] — 2026-04-02
 
 ### Added

README.md

@@ -66,6 +66,28 @@ You can also pass the key directly:
 sahmk quote 2222 --api-key your_api_key
 ```
 
+## Typed Responses
+
+All client methods return typed objects with IDE autocompletion — while preserving full backwards compatibility with dict-style access:
+
+```python
+quote = client.quote("2222")
+
+# New: typed attribute access
+print(quote.price)
+print(quote.liquidity.net_value)
+
+# Still works: dict-style access (backwards compatible)
+print(quote["price"])
+print(quote.get("volume"))
+```
+
+Access the original API response dict via `.raw`:
+
+```python
+raw_dict = quote.raw
+```
+
 ## Retries and Rate Limits
 
 The client automatically retries transient failures (429 rate-limit and 5xx server errors) with exponential backoff:

ROADMAP.md

@@ -40,13 +40,14 @@ Timelines are approximate and can change based on user feedback and API evolutio
 - Configurable retry behavior (`retries`, `backoff_factor`, `retry_on_timeout`)
 - Timeout retries (opt-in, enabled by default)
 
-## Next Milestones
+### v0.5.0 (released)
 
-### v0.5.0 (planned) — Typed response models
+- Typed dataclass models for all endpoints (Quote, Company, Historical, etc.)
+- Full backwards compatibility — dict-style `[]` access preserved
+- Nested typed sub-objects (Liquidity, Fundamentals, Technicals, etc.)
+- `.raw` attribute on all models for original API response access
 
-- Typed response models for key endpoints (quote, company, historical, etc.)
-- Improved developer experience with IDE autocompletion
-- Backwards-compatible — raw dict access preserved
+## Next Milestones
 
 ### v0.6.0 (planned) — CLI expansion
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sahmk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Lightweight Python client for the SAHMK Developer API."
 readme = "README.md"
 requires-python = ">=3.9"

sahmk/__init__.py

@@ -1,4 +1,58 @@
 from .client import SahmkClient, SahmkError, SahmkRateLimitError
+from .models import (
+    Quote,
+    BatchQuote,
+    BatchQuotesResponse,
+    HistoricalResponse,
+    OHLCV,
+    MarketSummary,
+    MarketMover,
+    MarketMoversResponse,
+    Sector,
+    SectorsResponse,
+    Company,
+    Fundamentals,
+    Technicals,
+    Valuation,
+    Analysts,
+    FinancialsResponse,
+    IncomeStatement,
+    BalanceSheet,
+    CashFlow,
+    DividendsResponse,
+    DividendPayment,
+    Event,
+    EventsResponse,
+    Liquidity,
+)
 
-__version__ = "0.4.0"
-__all__ = ["SahmkClient", "SahmkError", "SahmkRateLimitError"]
+__version__ = "0.5.0"
+__all__ = [
+    "SahmkClient",
+    "SahmkError",
+    "SahmkRateLimitError",
+    "Quote",
+    "BatchQuote",
+    "BatchQuotesResponse",
+    "HistoricalResponse",
+    "OHLCV",
+    "MarketSummary",
+    "MarketMover",
+    "MarketMoversResponse",
+    "Sector",
+    "SectorsResponse",
+    "Company",
+    "Fundamentals",
+    "Technicals",
+    "Valuation",
+    "Analysts",
+    "FinancialsResponse",
+    "IncomeStatement",
+    "BalanceSheet",
+    "CashFlow",
+    "DividendsResponse",
+    "DividendPayment",
+    "Event",
+    "EventsResponse",
+    "Liquidity",
+]

sahmk/cli.py

@@ -81,10 +81,11 @@ def _resolve_api_key(cli_api_key):
 
 
 def _print_json(payload, compact=False):
+    data = getattr(payload, "raw", payload)
     if compact:
-        print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
+        print(json.dumps(data, ensure_ascii=False, separators=(",", ":")))
         return
-    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    print(json.dumps(data, ensure_ascii=False, indent=2))
 
 
 def main(argv=None):

sahmk/client.py

@@ -239,10 +239,11 @@ def quote(self, symbol):
             symbol: Stock symbol (e.g., "2222" for Aramco)
 
         Returns:
-            dict with keys: symbol, name, name_en, price, change,
-            change_percent, volume, bid, ask, liquidity, etc.
+            Quote object (supports dict-style access via [] for backwards compat)
         """
-        return self._request("GET", f"/quote/{symbol}/")
+        from .models import Quote
+        data = self._request("GET", f"/quote/{symbol}/")
+        return Quote.from_dict(data)
 
     def quotes(self, symbols):
         """
@@ -252,13 +253,15 @@ def quotes(self, symbols):
             symbols: List of stock symbols (up to 50)
 
         Returns:
-            dict with "quotes" list and "count"
+            BatchQuotesResponse with .quotes list and .count
         """
+        from .models import BatchQuotesResponse
         if len(symbols) > 50:
             raise SahmkError("Maximum 50 symbols per batch request")
-        return self._request(
+        data = self._request(
             "GET", "/quotes/", params={"symbols": ",".join(symbols)}
         )
+        return BatchQuotesResponse.from_dict(data)
 
     # -------------------------------------------------------------------------
     # Historical
@@ -275,24 +278,33 @@ def historical(self, symbol, from_date=None, to_date=None, interval=None):
             interval: "1d", "1w", or "1m" (default: "1d")
 
         Returns:
-            dict with "symbol", "interval", "from", "to", "count", and "data" list
+            HistoricalResponse with .data list of OHLCV objects
         """
+        from .models import HistoricalResponse
         params = {}
         if from_date:
             params["from"] = from_date
         if to_date:
             params["to"] = to_date
         if interval:
             params["interval"] = interval
-        return self._request("GET", f"/historical/{symbol}/", params=params)
+        data = self._request("GET", f"/historical/{symbol}/", params=params)
+        return HistoricalResponse.from_dict(data)
 
     # -------------------------------------------------------------------------
     # Market
     # -------------------------------------------------------------------------
 
     def market_summary(self):
-        """Get market overview (TASI index, change, volume, market_mood)."""
-        return self._request("GET", "/market/summary/")
+        """
+        Get market overview (TASI index, change, volume, market_mood).
+
+        Returns:
+            MarketSummary object
+        """
+        from .models import MarketSummary
+        data = self._request("GET", "/market/summary/")
+        return MarketSummary.from_dict(data)
 
     def gainers(self, limit=None):
         """
@@ -302,12 +314,14 @@ def gainers(self, limit=None):
             limit: Number of results (default: 10, max: 50)
 
         Returns:
-            dict with "gainers" list and "count"
+            MarketMoversResponse with .stocks list
         """
+        from .models import MarketMoversResponse
         params = {}
         if limit is not None:
             params["limit"] = limit
-        return self._request("GET", "/market/gainers/", params=params or None)
+        data = self._request("GET", "/market/gainers/", params=params or None)
+        return MarketMoversResponse.from_dict(data, list_key="gainers")
 
     def losers(self, limit=None):
         """
@@ -317,12 +331,14 @@ def losers(self, limit=None):
             limit: Number of results (default: 10, max: 50)
 
         Returns:
-            dict with "losers" list and "count"
+            MarketMoversResponse with .stocks list
         """
+        from .models import MarketMoversResponse
         params = {}
         if limit is not None:
             params["limit"] = limit
-        return self._request("GET", "/market/losers/", params=params or None)
+        data = self._request("GET", "/market/losers/", params=params or None)
+        return MarketMoversResponse.from_dict(data, list_key="losers")
 
     def volume_leaders(self, limit=None):
         """
@@ -332,12 +348,14 @@ def volume_leaders(self, limit=None):
             limit: Number of results (default: 10, max: 50)
 
         Returns:
-            dict with "stocks" list and "count"
+            MarketMoversResponse with .stocks list
         """
+        from .models import MarketMoversResponse
         params = {}
         if limit is not None:
             params["limit"] = limit
-        return self._request("GET", "/market/volume/", params=params or None)
+        data = self._request("GET", "/market/volume/", params=params or None)
+        return MarketMoversResponse.from_dict(data, list_key="stocks")
 
     def value_leaders(self, limit=None):
         """
@@ -347,21 +365,25 @@ def value_leaders(self, limit=None):
             limit: Number of results (default: 10, max: 50)
 
         Returns:
-            dict with "stocks" list and "count"
+            MarketMoversResponse with .stocks list
         """
+        from .models import MarketMoversResponse
         params = {}
         if limit is not None:
             params["limit"] = limit
-        return self._request("GET", "/market/value/", params=params or None)
+        data = self._request("GET", "/market/value/", params=params or None)
+        return MarketMoversResponse.from_dict(data, list_key="stocks")
 
     def sectors(self):
         """
         Get sector performance.
 
         Returns:
-            dict with "sectors" list and "count"
+            SectorsResponse with .sectors list
         """
-        return self._request("GET", "/market/sectors/")
+        from .models import SectorsResponse
+        data = self._request("GET", "/market/sectors/")
+        return SectorsResponse.from_dict(data)
 
     # -------------------------------------------------------------------------
     # Company Data
@@ -371,16 +393,35 @@ def company(self, symbol):
         """
         Get company info. Response varies by plan:
         Free (basic), Starter (fundamentals), Pro (technicals, valuation, analysts).
+
+        Returns:
+            Company object
         """
-        return self._request("GET", f"/company/{symbol}/")
+        from .models import Company as CompanyModel
+        data = self._request("GET", f"/company/{symbol}/")
+        return CompanyModel.from_dict(data)
 
     def financials(self, symbol):
-        """Get financial statements (income, balance sheet, cash flow). Starter+ plan."""
-        return self._request("GET", f"/financials/{symbol}/")
+        """
+        Get financial statements (income, balance sheet, cash flow). Starter+ plan.
+
+        Returns:
+            FinancialsResponse object
+        """
+        from .models import FinancialsResponse
+        data = self._request("GET", f"/financials/{symbol}/")
+        return FinancialsResponse.from_dict(data)
 
     def dividends(self, symbol):
-        """Get dividend history and yield. Starter+ plan."""
-        return self._request("GET", f"/dividends/{symbol}/")
+        """
+        Get dividend history and yield. Starter+ plan.
+
+        Returns:
+            DividendsResponse object
+        """
+        from .models import DividendsResponse
+        data = self._request("GET", f"/dividends/{symbol}/")
+        return DividendsResponse.from_dict(data)
 
     # -------------------------------------------------------------------------
     # Events
@@ -395,14 +436,16 @@ def events(self, symbol=None, limit=None):
             limit: Number of results (default: 20)
 
         Returns:
-            dict with "events" list, "count", and "available_types"
+            EventsResponse with .events list
         """
+        from .models import EventsResponse
         params = {}
         if symbol:
             params["symbol"] = symbol
         if limit is not None:
             params["limit"] = limit
-        return self._request("GET", "/events/", params=params or None)
+        data = self._request("GET", "/events/", params=params or None)
+        return EventsResponse.from_dict(data)
 
     # -------------------------------------------------------------------------
     # WebSocket Streaming (Pro+ plan)