v0.8.0: Add company directory symbol discovery endpoint

Introduce companies() as the canonical symbol discovery path with validated pagination, market normalization, and full docs/tests coverage so quote/company workflows can start from verified symbols.

Author: sahmk-sa

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to the `sahmk` Python SDK will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] — 2026-04-24
+
+### Added
+
+- New `companies()` SDK method for canonical symbol discovery via `GET /companies/`, with support for `search`, `market`, `limit`, and `offset`
+- Discovery-first README guidance and examples for symbol/name search, market filtering, and offset-based pagination before calling `quote()`/`company()`
+- Integration coverage for live company directory response shape
+
+### Changed
+
+- Company directory market filter now uses the same normalization rules as market endpoints (`TASI`/`NOMU`, `NOMUC` alias to `NOMU`)
+- API reference docs now include `GET /companies/` as the symbol discovery endpoint
+
+### Fixed
+
+- Client-side pagination validation for company discovery now enforces `limit > 0` and `offset >= 0` before request dispatch
+
 ## [0.7.0] — 2026-04-18
 
 ### Added

README.md

@@ -10,6 +10,7 @@ Use one client for live Tadawul quotes, market-level insights, company/fundament
 - **Batch quotes** for up to 50 symbols per request
 - **Historical OHLCV** data with date-range support
 - **Market overview** with index scoping (`TASI`/`NOMU`)
+- **Company directory** endpoint for symbol discovery
 - **Company/fundamental** data (plan-dependent fields)
 - **Financials, dividends, and events** endpoints (by plan)
 - **WebSocket streaming** for real-time updates (Pro+)
@@ -89,6 +90,44 @@ print(quote.resolved_symbol)           # 2222
 print(quote.resolution.matched_by)     # alias (if provided by API)
 ```
 
+## Company Directory / Symbol Discovery
+
+Use `companies()` as the canonical symbol-discovery path before calling
+`quote()` or `company()`.
+
+```python
+# Search by symbol or name
+directory = client.companies(search="aram")
+for row in directory["results"]:
+    print(row["symbol"], row.get("name_en") or row.get("name"))
+```
+
+```python
+# Filter by market (TASI / NOMU, NOMUC alias is accepted)
+nomu_companies = client.companies(market="NOMUC", limit=20)
+print(nomu_companies["count"])
+```
+
+```python
+# Pagination loop with offset
+offset = 0
+page_size = 100
+
+while True:
+    page = client.companies(limit=page_size, offset=offset)
+    for company in page["results"]:
+        print(company["symbol"])
+
+    offset += page_size
+    if offset >= page["total"]:
+        break
+```
+
+Recommended flow:
+
+1. Discover valid symbols with `companies()`.
+2. Call `quote(symbol)` / `company(symbol)` with a validated symbol.
+
 ## Production Reliability
 
 - The client retries transient failures: **HTTP 429** and **5xx** errors.
@@ -171,6 +210,7 @@ Base URL: `https://app.sahmk.sa/api/v1`
 | `GET /market/volume/` | Free | Volume leaders |
 | `GET /market/value/` | Free | Value leaders |
 | `GET /market/sectors/` | Free | Sector performance |
+| `GET /companies/` | Free | Company directory and symbol discovery |
 | `GET /company/{symbol}/` | Free+ | Company info (tiered by plan) |
 | `GET /financials/{symbol}/` | Starter+ | Financial statements |
 | `GET /dividends/{symbol}/` | Starter+ | Dividend history and yield |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sahmk"
-version = "0.7.0"
+version = "0.8.0"
 description = "Official Python SDK for Sahmk — Saudi market data and richer market workflows for developers."
 readme = "README.md"
 requires-python = ">=3.9"

sahmk/__init__.py

@@ -35,7 +35,7 @@
     Liquidity,
 )
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 __all__ = [
     "SahmkClient",
     "SahmkError",

sahmk/client.py

@@ -375,6 +375,30 @@ def _market_params(self, limit=None, index=None):
             params["index"] = normalized_index
         return params or None
 
+    @staticmethod
+    def _validate_limit_offset(limit, offset):
+        """Validate shared pagination arguments."""
+        if isinstance(limit, bool) or not isinstance(limit, int):
+            raise ValueError("limit must be an integer greater than 0")
+        if limit <= 0:
+            raise ValueError("limit must be greater than 0")
+
+        if isinstance(offset, bool) or not isinstance(offset, int):
+            raise ValueError("offset must be an integer greater than or equal to 0")
+        if offset < 0:
+            raise ValueError("offset must be greater than or equal to 0")
+
+    def _companies_params(self, search=None, market=None, limit=100, offset=0):
+        """Build validated query params for the company directory endpoint."""
+        self._validate_limit_offset(limit=limit, offset=offset)
+        params = {"limit": limit, "offset": offset}
+        if search is not None:
+            params["search"] = search
+        normalized_market = self._normalize_market_index(market)
+        if normalized_market is not None:
+            params["market"] = normalized_market
+        return params
+
     # -------------------------------------------------------------------------
     # Quotes
     # -------------------------------------------------------------------------
@@ -596,6 +620,31 @@ def sectors(self, index=None):
     # Company Data
     # -------------------------------------------------------------------------
 
+    def companies(self, search=None, market=None, limit=100, offset=0):
+        """
+        Discover listed companies/symbols for quote/company workflows.
+
+        Args:
+            search: Optional symbol/name search string.
+            market: Optional market filter ("TASI" or "NOMU"). "NOMUC" alias
+                    is accepted and normalized to "NOMU".
+            limit: Page size (must be > 0, default: 100).
+            offset: Pagination offset (must be >= 0, default: 0).
+
+        Returns:
+            Raw API response with keys such as results/count/total/limit/offset.
+        """
+        return self._request(
+            "GET",
+            "/companies/",
+            params=self._companies_params(
+                search=search,
+                market=market,
+                limit=limit,
+                offset=offset,
+            ),
+        )
+
     def company(self, symbol):
         """
         Get company info. Response varies by plan:

tests/test_client.py

@@ -666,6 +666,94 @@ def test_market_methods_invalid_index_raises(self, mock_client):
 class TestCompanyEndpoints:
     """Tests for company data endpoints."""
 
+    @responses.activate
+    def test_companies_with_search_market_and_pagination(self, mock_client):
+        """Test company directory query serialization with all parameters."""
+        responses.add(
+            responses.GET,
+            f"{mock_client.base_url}/companies/",
+            json={
+                "results": [{"symbol": "2222", "name_en": "Saudi Aramco"}],
+                "count": 1,
+                "total": 1,
+                "limit": 25,
+                "offset": 50,
+            },
+            status=200,
+        )
+
+        result = mock_client.companies(
+            search="aram",
+            market="tasi",
+            limit=25,
+            offset=50,
+        )
+
+        assert result["count"] == 1
+        request = responses.calls[0].request.url
+        assert "search=aram" in request
+        assert "market=TASI" in request
+        assert "limit=25" in request
+        assert "offset=50" in request
+
+    @responses.activate
+    def test_companies_market_alias_nomuc_normalizes_to_nomu(self, mock_client):
+        """Test NOMUC market alias is normalized to NOMU for company discovery."""
+        responses.add(
+            responses.GET,
+            f"{mock_client.base_url}/companies/",
+            json={
+                "results": [{"symbol": "9510", "name_en": "Nomu Co"}],
+                "count": 1,
+                "total": 1,
+                "limit": 10,
+                "offset": 0,
+            },
+            status=200,
+        )
+
+        result = mock_client.companies(market="NOMUC", limit=10, offset=0)
+
+        assert result["count"] == 1
+        request = responses.calls[0].request.url
+        assert "market=NOMU" in request
+
+    def test_companies_invalid_limit_raises(self, mock_client):
+        """Test company directory rejects non-positive limits."""
+        with pytest.raises(ValueError, match="limit must be greater than 0"):
+            mock_client.companies(limit=0)
+        with pytest.raises(ValueError, match="limit must be an integer"):
+            mock_client.companies(limit="100")
+
+    def test_companies_invalid_offset_raises(self, mock_client):
+        """Test company directory rejects negative/non-integer offsets."""
+        with pytest.raises(ValueError, match="offset must be greater than or equal to 0"):
+            mock_client.companies(offset=-1)
+        with pytest.raises(ValueError, match="offset must be an integer"):
+            mock_client.companies(offset="0")
+
+    @responses.activate
+    def test_companies_surfaces_api_errors_with_status_and_code(self, mock_client):
+        """Test company directory surfaces API error details clearly."""
+        responses.add(
+            responses.GET,
+            f"{mock_client.base_url}/companies/",
+            json={
+                "error": {
+                    "code": "INVALID_PARAM",
+                    "message": "unsupported filter combination",
+                }
+            },
+            status=400,
+        )
+
+        with pytest.raises(SahmkError) as exc_info:
+            mock_client.companies(search="*", market="TASI")
+
+        assert exc_info.value.status_code == 400
+        assert exc_info.value.error_code == "INVALID_PARAM"
+        assert "unsupported filter combination" in str(exc_info.value)
+
     @responses.activate
     def test_company(self, mock_client, sample_company_response):
         """Test getting company info."""

tests/test_integration.py

@@ -238,6 +238,24 @@ def test_sectors(self, live_client):
 class TestLiveCompanyData:
     """Live tests for company data endpoints."""
 
+    def test_companies_directory(self, live_client):
+        """Test company directory endpoint for symbol discovery."""
+        result = live_client.companies(search="aram", limit=5, offset=0)
+
+        assert "results" in result
+        assert "count" in result
+        assert "total" in result
+        assert "limit" in result
+        assert "offset" in result
+        assert isinstance(result["results"], list)
+        assert result["limit"] == 5
+        assert result["offset"] == 0
+
+        print(
+            f"\nCompanies directory: {result.get('count', 0)} returned, "
+            f"{result.get('total', 0)} total"
+        )
+
     def test_company_info(self, live_client):
         """Test getting company information."""
         result = live_client.company("2222")