v0.6.2: Market index scoping and delay metadata support

Add index-aware market endpoint support across SDK and CLI with NOMUC alias normalization, explicit INVALID_INDEX handling, and typed exposure of index/is_delayed. This aligns the client with Apr 9 API behavior while preserving backward compatibility when index is omitted.

Made-with: Cursor

Author: sahmk-sa

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to the `sahmk` Python SDK will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.6.2] — 2026-04-12
+
+### Added
+
+- Market endpoints now accept optional `index` in SDK methods and CLI (`--index`) for `TASI`/`NOMU`, with `NOMUC` alias normalized to `NOMU`
+- New `SahmkInvalidIndexError` for clear handling of invalid market index usage (`INVALID_INDEX`)
+- Market typed response models now expose top-level `index` and `is_delayed` fields
+
+### Changed
+
+- Market method docs/examples updated to reflect index scoping and delayed-vs-realtime response metadata
+- Test coverage expanded for index query propagation, alias normalization, and invalid-index failures
+
 ## [0.6.1] — 2026-04-02
 
 ### Fixed

README.md

@@ -7,7 +7,7 @@ A lightweight Python client for the [SAHMK Developer API](https://sahmk.sa/devel
 - **Real-time quotes** — live prices for 350+ Tadawul stocks
 - **Batch quotes** — up to 50 stocks in a single request
 - **Historical data** — daily/weekly/monthly OHLCV with custom date ranges
-- **Market overview** — TASI index, gainers, losers, volume/value leaders, sectors
+- **Market overview** — index-scoped market data (TASI/NOMU), gainers, losers, volume/value leaders, sectors
 - **Company info** — fundamentals, technicals, valuation, analyst consensus (by plan)
 - **Financials** — income statements, balance sheets, cash flow
 - **Dividends** — history, yield, upcoming payments
@@ -43,6 +43,10 @@ print(f"{quote['name_en']}: {quote['price']} SAR ({quote['change_percent']}%)")
 market = client.market_summary()
 print(f"TASI: {market['index_value']} ({market['index_change_percent']}%)")
 
+# Scope market endpoints by index (NOMUC alias is accepted)
+nomu = client.gainers(limit=5, index="NOMUC")
+print(f"Index: {nomu.index}, delayed: {nomu.is_delayed}")
+
 # Batch quotes (Starter+ plan)
 result = client.quotes(["2222", "1120", "4191"])
 for q in result["quotes"]:
@@ -57,6 +61,7 @@ The package also installs a CLI for instant testing:
 export SAHMK_API_KEY="your_api_key"
 sahmk quote 2222
 sahmk market gainers --limit 5
+sahmk market summary --index NOMU
 sahmk historical 2222 --from 2026-01-01 --to 2026-01-28
 sahmk company 2222
 sahmk financials 2222
@@ -93,6 +98,25 @@ Access the original API response dict via `.raw`:
 raw_dict = quote.raw
 ```
 
+## Market Index Scoping
+
+Market endpoints support optional `index` scoping:
+
+- Accepted values: `TASI`, `NOMU`
+- Alias: `NOMUC` (normalized to `NOMU`)
+- Omitted `index` remains backward compatible (server defaults to `TASI`)
+
+```python
+summary = client.market_summary(index="NOMUC")
+print(summary.index)       # NOMU
+print(summary.is_delayed)  # True/False by plan entitlement
+```
+
+```bash
+sahmk market summary --index NOMU
+sahmk market gainers --limit 10 --index NOMUC
+```
+
 ## Retries and Rate Limits
 
 The client automatically retries transient failures (429 rate-limit and 5xx server errors) with exponential backoff:

examples/market_summary.py

@@ -17,19 +17,22 @@
 client = SahmkClient(API_KEY)
 
 # Market overview
-summary = client.market_summary()
+summary = client.market_summary(index="TASI")
 print("=== Market Summary ===")
+print(f"Index: {summary.get('index', 'N/A')}")
 print(f"TASI: {summary.get('index_value', 'N/A')}")
 print(f"Change: {summary.get('index_change', 'N/A')} ({summary.get('index_change_percent', 'N/A')}%)")
 print(f"Volume: {summary.get('total_volume', 'N/A')}")
+print(f"Delayed: {summary.get('is_delayed', 'N/A')}")
 print(f"Mood: {summary.get('market_mood', 'N/A')}")
 print()
 
 # Top gainers
 print("=== Top Gainers ===")
-result = client.gainers(limit=5)
+result = client.gainers(limit=5, index="NOMUC")
 for stock in result["gainers"]:
     print(f"  {stock['symbol']} {stock.get('name_en', '')}: +{stock.get('change_percent', 'N/A')}%")
+print(f"Index: {result.get('index', 'N/A')} | Delayed: {result.get('is_delayed', 'N/A')}")
 print()
 
 # Top losers

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sahmk"
-version = "0.6.1"
-description = "Lightweight Python client for the SAHMK Developer API."
+version = "0.6.2"
+description = "Python SDK for SAHMK API with typed models, CLI, and market index scoping."
 readme = "README.md"
 requires-python = ">=3.9"
 license = "MIT"

sahmk/__init__.py

@@ -1,4 +1,9 @@
-from .client import SahmkClient, SahmkError, SahmkRateLimitError
+from .client import (
+    SahmkClient,
+    SahmkError,
+    SahmkRateLimitError,
+    SahmkInvalidIndexError,
+)
 from .models import (
     Quote,
     BatchQuote,
@@ -26,11 +31,12 @@
     Liquidity,
 )
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"
 __all__ = [
     "SahmkClient",
     "SahmkError",
     "SahmkRateLimitError",
+    "SahmkInvalidIndexError",
     "Quote",
     "BatchQuote",
     "BatchQuotesResponse",

sahmk/cli.py

@@ -67,6 +67,10 @@ def _build_parser():
         type=int,
         help="Optional limit for gainers/losers/volume/value.",
     )
+    market_parser.add_argument(
+        "--index",
+        help='Optional market index: "TASI" or "NOMU" (alias "NOMUC" accepted).',
+    )
     _compact_arg(market_parser)
 
     historical_parser = subparsers.add_parser(
@@ -212,17 +216,17 @@ def main(argv=None):
             result = client.quotes(symbols)
         elif args.command == "market":
             if args.view == "summary":
-                result = client.market_summary()
+                result = client.market_summary(index=args.index)
             elif args.view == "gainers":
-                result = client.gainers(limit=args.limit)
+                result = client.gainers(limit=args.limit, index=args.index)
             elif args.view == "losers":
-                result = client.losers(limit=args.limit)
+                result = client.losers(limit=args.limit, index=args.index)
             elif args.view == "volume":
-                result = client.volume_leaders(limit=args.limit)
+                result = client.volume_leaders(limit=args.limit, index=args.index)
             elif args.view == "value":
-                result = client.value_leaders(limit=args.limit)
+                result = client.value_leaders(limit=args.limit, index=args.index)
             else:
-                result = client.sectors()
+                result = client.sectors(index=args.index)
         elif args.command == "historical":
             result = client.historical(
                 args.symbol,

sahmk/client.py

@@ -17,6 +17,8 @@
 logger = logging.getLogger("sahmk")
 
 _RETRIABLE_STATUS_CODES = frozenset({500, 502, 503, 504})
+_MARKET_INDEX_ALIASES = {"NOMUC": "NOMU"}
+_VALID_MARKET_INDEXES = frozenset({"TASI", "NOMU"})
 
 
 class SahmkError(Exception):
@@ -61,6 +63,18 @@ def __init__(
         self.rate_reset = rate_reset
 
 
+class SahmkInvalidIndexError(SahmkError):
+    """Raised when an invalid market index is supplied or returned by the API."""
+
+    def __init__(self, message, response=None):
+        super().__init__(
+            message,
+            status_code=400,
+            error_code="INVALID_INDEX",
+            response=response,
+        )
+
+
 class SahmkClient:
     """
     SAHMK Developer API client.
@@ -217,6 +231,11 @@ def _build_api_error(response):
         except (ValueError, KeyError):
             code = "UNKNOWN"
             message = response.text
+        if response.status_code == 400 and code == "INVALID_INDEX":
+            return SahmkInvalidIndexError(
+                f"Invalid market index: {message}",
+                response=response,
+            )
         return SahmkError(
             f"API error {response.status_code}: {message}",
             status_code=response.status_code,
@@ -234,6 +253,29 @@ def _rate_limit_wait(self, response, attempt):
                 pass
         return self.backoff_factor * (2 ** attempt)
 
+    @staticmethod
+    def _normalize_market_index(index):
+        """Normalize/validate market index query parameter."""
+        if index is None:
+            return None
+        normalized = str(index).strip().upper()
+        normalized = _MARKET_INDEX_ALIASES.get(normalized, normalized)
+        if normalized not in _VALID_MARKET_INDEXES:
+            raise SahmkInvalidIndexError(
+                "Index must be one of: TASI, NOMU (NOMUC is accepted as NOMU)."
+            )
+        return normalized
+
+    def _market_params(self, limit=None, index=None):
+        """Build validated query params for market endpoints."""
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        normalized_index = self._normalize_market_index(index)
+        if normalized_index is not None:
+            params["index"] = normalized_index
+        return params or None
+
     # -------------------------------------------------------------------------
     # Quotes
     # -------------------------------------------------------------------------
@@ -304,94 +346,122 @@ def historical(self, symbol, from_date=None, to_date=None, interval=None):
     # Market
     # -------------------------------------------------------------------------
 
-    def market_summary(self):
+    def market_summary(self, index=None):
         """
         Get market overview (TASI index, change, volume, market_mood).
 
+        Args:
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
+
         Returns:
             MarketSummary object
         """
         from .models import MarketSummary
-        data = self._request("GET", "/market/summary/")
+        data = self._request(
+            "GET",
+            "/market/summary/",
+            params=self._market_params(index=index),
+        )
         return MarketSummary.from_dict(data)
 
-    def gainers(self, limit=None):
+    def gainers(self, limit=None, index=None):
         """
         Get top gaining stocks.
 
         Args:
             limit: Number of results (default: 10, max: 50)
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
 
         Returns:
             MarketMoversResponse with .stocks list
         """
         from .models import MarketMoversResponse
-        params = {}
-        if limit is not None:
-            params["limit"] = limit
-        data = self._request("GET", "/market/gainers/", params=params or None)
+        data = self._request(
+            "GET",
+            "/market/gainers/",
+            params=self._market_params(limit=limit, index=index),
+        )
         return MarketMoversResponse.from_dict(data, list_key="gainers")
 
-    def losers(self, limit=None):
+    def losers(self, limit=None, index=None):
         """
         Get top losing stocks.
 
         Args:
             limit: Number of results (default: 10, max: 50)
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
 
         Returns:
             MarketMoversResponse with .stocks list
         """
         from .models import MarketMoversResponse
-        params = {}
-        if limit is not None:
-            params["limit"] = limit
-        data = self._request("GET", "/market/losers/", params=params or None)
+        data = self._request(
+            "GET",
+            "/market/losers/",
+            params=self._market_params(limit=limit, index=index),
+        )
         return MarketMoversResponse.from_dict(data, list_key="losers")
 
-    def volume_leaders(self, limit=None):
+    def volume_leaders(self, limit=None, index=None):
         """
         Get stocks with highest trading volume.
 
         Args:
             limit: Number of results (default: 10, max: 50)
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
 
         Returns:
             MarketMoversResponse with .stocks list
         """
         from .models import MarketMoversResponse
-        params = {}
-        if limit is not None:
-            params["limit"] = limit
-        data = self._request("GET", "/market/volume/", params=params or None)
+        data = self._request(
+            "GET",
+            "/market/volume/",
+            params=self._market_params(limit=limit, index=index),
+        )
         return MarketMoversResponse.from_dict(data, list_key="stocks")
 
-    def value_leaders(self, limit=None):
+    def value_leaders(self, limit=None, index=None):
         """
         Get stocks with highest trading value (SAR).
 
         Args:
             limit: Number of results (default: 10, max: 50)
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
 
         Returns:
             MarketMoversResponse with .stocks list
         """
         from .models import MarketMoversResponse
-        params = {}
-        if limit is not None:
-            params["limit"] = limit
-        data = self._request("GET", "/market/value/", params=params or None)
+        data = self._request(
+            "GET",
+            "/market/value/",
+            params=self._market_params(limit=limit, index=index),
+        )
         return MarketMoversResponse.from_dict(data, list_key="stocks")
 
-    def sectors(self):
+    def sectors(self, index=None):
         """
         Get sector performance.
 
+        Args:
+            index: Optional market index ("TASI" or "NOMU"). "NOMUC" alias
+                   is accepted and normalized to "NOMU".
+
         Returns:
             SectorsResponse with .sectors list
         """
         from .models import SectorsResponse
-        data = self._request("GET", "/market/sectors/")
+        data = self._request(
+            "GET",
+            "/market/sectors/",
+            params=self._market_params(index=index),
+        )
         return SectorsResponse.from_dict(data)
 
     # -------------------------------------------------------------------------