htag-sdk 0.1.0__py3-none-any.whl

htag/__init__.py

@@ -0,0 +1,108 @@
+"""HtAG AI Python SDK.
+
+The official Python client for the HtAG AI API, providing access to
+Australian address data, property sales records, and market analytics.
+
+Quick start::
+
+    from htag import HtAgApi
+
+    client = HtAgApi(api_key="sk-...", environment="prod")
+    results = client.address.search("100 George St Sydney")
+
+For async usage::
+
+    from htag import AsyncHtAgApi
+
+    async_client = AsyncHtAgApi(api_key="sk-...", environment="prod")
+    results = await async_client.address.search("100 George St Sydney")
+"""
+
+from htag._async_client import AsyncHtAgApi
+from htag._client import HtAgApi
+from htag._exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    HtAgError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+# Domain models -- address
+from htag.address.models import (
+    AddressInsightsResponse,
+    AddressRecord,
+    AddressSearchResponse,
+    AddressSearchResult,
+    AustralianAddressComponents,
+    BatchStandardiseResponse,
+    StandardiseResult,
+)
+
+# Domain models -- property
+from htag.property.models import (
+    SoldPropertiesResponse,
+    SoldPropertyRecord,
+)
+
+# Domain models -- markets
+from htag.markets.models import (
+    AdvancedSearchBody,
+    BaseResponse,
+    DemandProfileOut,
+    EssentialsOut,
+    FSDMonthlyOut,
+    FSDQuarterlyOut,
+    FSDYearlyOut,
+    GRCOut,
+    LevelEnum,
+    MarketSnapshot,
+    PriceHistoryOut,
+    PropertyTypeEnum,
+    RentHistoryOut,
+    YieldHistoryOut,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Clients
+    "HtAgApi",
+    "AsyncHtAgApi",
+    # Exceptions
+    "HtAgError",
+    "AuthenticationError",
+    "ConnectionError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    # Address models
+    "AddressInsightsResponse",
+    "AddressRecord",
+    "AddressSearchResponse",
+    "AddressSearchResult",
+    "AustralianAddressComponents",
+    "BatchStandardiseResponse",
+    "StandardiseResult",
+    # Property models
+    "SoldPropertiesResponse",
+    "SoldPropertyRecord",
+    # Markets models
+    "AdvancedSearchBody",
+    "BaseResponse",
+    "DemandProfileOut",
+    "EssentialsOut",
+    "FSDMonthlyOut",
+    "FSDQuarterlyOut",
+    "FSDYearlyOut",
+    "GRCOut",
+    "LevelEnum",
+    "MarketSnapshot",
+    "PriceHistoryOut",
+    "PropertyTypeEnum",
+    "RentHistoryOut",
+    "YieldHistoryOut",
+]

htag/_async_client.py

@@ -0,0 +1,85 @@
+"""Asynchronous HtAG API client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from htag._base import AsyncRequestMixin
+from htag.address.async_client import AsyncAddressClient
+from htag.markets.async_client import AsyncMarketsClient
+from htag.property.async_client import AsyncPropertyClient
+
+
+class AsyncHtAgApi(AsyncRequestMixin):
+    """Asynchronous client for the HtAG AI API.
+
+    Usage::
+
+        import asyncio
+        from htag import AsyncHtAgApi
+
+        async def main():
+            client = AsyncHtAgApi(api_key="sk-...", environment="prod")
+
+            results = await client.address.search("100 George St Sydney")
+            sold = await client.property.sold_search(address="100 George St Sydney")
+            snapshots = await client.markets.snapshots(
+                level="suburb", property_type=["house"]
+            )
+
+            await client.close()
+
+        asyncio.run(main())
+
+    As an async context manager::
+
+        async with AsyncHtAgApi(api_key="sk-...", environment="prod") as client:
+            results = await client.address.search("100 George St Sydney")
+
+    Args:
+        api_key: Your HtAG API key (required).
+        environment: Target environment -- ``"prod"`` or ``"dev"``.
+        base_url: Custom base URL (overrides ``environment``).
+        timeout: Request timeout in seconds (default 60).
+        max_retries: Maximum number of retry attempts for transient errors (default 3).
+    """
+
+    address: AsyncAddressClient
+    property: AsyncPropertyClient
+    markets: AsyncMarketsClient
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        environment: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            environment=environment,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = httpx.AsyncClient()
+        self.address = AsyncAddressClient(self)
+        self.property = AsyncPropertyClient(self)
+        self.markets = AsyncMarketsClient(self)
+
+    async def close(self) -> None:
+        """Release underlying HTTP connection pool resources."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncHtAgApi":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncHtAgApi(base_url={self._base_url!r})"

htag/_base.py

@@ -0,0 +1,356 @@
+"""Shared base functionality for sync and async HTTP clients.
+
+Handles authentication, base URL resolution, retry logic with exponential
+backoff, and consistent error mapping.
+"""
+
+from __future__ import annotations
+
+import time
+import random
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Type, Union
+
+import httpx
+
+from htag._exceptions import (
+    AuthenticationError,
+    ConnectionError as HtAgConnectionError,
+    HtAgError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from htag._types import Headers, JSONDict, QueryParams
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_ENV_BASE_URLS: Dict[str, str] = {
+    "prod": "https://api.prod.htagai.com",
+    "dev": "https://api.dev.htagai.com",
+}
+
+DEFAULT_TIMEOUT: float = 60.0
+DEFAULT_MAX_RETRIES: int = 3
+RETRYABLE_STATUS_CODES: Tuple[int, ...] = (429, 500, 502, 503, 504)
+INITIAL_RETRY_DELAY: float = 0.5  # seconds
+MAX_RETRY_DELAY: float = 30.0  # seconds
+JITTER_FACTOR: float = 0.25
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+_STATUS_TO_EXCEPTION: List[Tuple[Sequence[int], Type[HtAgError]]] = [
+    ((401, 403), AuthenticationError),
+    ((429,), RateLimitError),
+    ((400, 422), ValidationError),
+    ((404,), NotFoundError),
+]
+
+
+def _exception_for_status(status_code: int) -> Type[HtAgError]:
+    """Return the most specific exception class for an HTTP status code."""
+    for codes, exc_cls in _STATUS_TO_EXCEPTION:
+        if status_code in codes:
+            return exc_cls
+    if 500 <= status_code < 600:
+        return ServerError
+    return HtAgError
+
+
+def _build_error(response: httpx.Response) -> HtAgError:
+    """Build a typed exception from an HTTP error response."""
+    status = response.status_code
+    request_id = response.headers.get("x-request-id")
+
+    # Try to extract a useful message from JSON body
+    body: Any = None
+    message = f"HTTP {status}"
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            message = body.get("detail") or body.get("message") or body.get("error") or message
+            if isinstance(message, list):
+                # FastAPI validation errors return a list of dicts
+                message = "; ".join(
+                    f"{e.get('loc', '?')}: {e.get('msg', '?')}" if isinstance(e, dict) else str(e)
+                    for e in message
+                )
+    except Exception:
+        body = response.text or None
+
+    exc_cls = _exception_for_status(status)
+
+    kwargs: Dict[str, Any] = {
+        "status_code": status,
+        "body": body,
+        "request_id": request_id,
+    }
+
+    if exc_cls is RateLimitError:
+        retry_after_raw = response.headers.get("retry-after")
+        retry_after: Optional[float] = None
+        if retry_after_raw is not None:
+            try:
+                retry_after = float(retry_after_raw)
+            except (ValueError, TypeError):
+                pass
+        kwargs["retry_after"] = retry_after
+
+    return exc_cls(str(message), **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Retry delay calculation
+# ---------------------------------------------------------------------------
+
+
+def _retry_delay(attempt: int, retry_after: Optional[float] = None) -> float:
+    """Calculate the delay before the next retry using exponential backoff with jitter."""
+    if retry_after is not None and retry_after > 0:
+        return retry_after
+
+    base_delay = INITIAL_RETRY_DELAY * (2 ** attempt)
+    delay = min(base_delay, MAX_RETRY_DELAY)
+    jitter = delay * JITTER_FACTOR * random.random()
+    return delay + jitter
+
+
+# ---------------------------------------------------------------------------
+# Query-parameter serialisation
+# ---------------------------------------------------------------------------
+
+
+def _serialise_params(params: QueryParams) -> Dict[str, Any]:
+    """Flatten query parameters into a form suitable for httpx.
+
+    - ``None`` values are dropped.
+    - Lists are passed through (httpx repeats keys for lists).
+    - Booleans are lowered to ``"true"`` / ``"false"``.
+    """
+    out: Dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, list):
+            filtered = [_scalar(v) for v in value if v is not None]
+            if filtered:
+                out[key] = filtered
+        else:
+            out[key] = _scalar(value)
+    return out
+
+
+def _scalar(v: Any) -> Any:
+    if isinstance(v, bool):
+        return str(v).lower()
+    return v
+
+
+# ---------------------------------------------------------------------------
+# Base client configuration
+# ---------------------------------------------------------------------------
+
+
+class BaseClient:
+    """Configuration and helpers shared by sync and async clients.
+
+    This class is not intended to be instantiated directly. Use
+    :class:`htag.HtAgApi` or :class:`htag.AsyncHtAgApi` instead.
+    """
+
+    _api_key: str
+    _base_url: str
+    _internal_base_url: str
+    _timeout: float
+    _max_retries: int
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        environment: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+
+        self._api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        if base_url is not None:
+            self._base_url = base_url.rstrip("/")
+            self._internal_base_url = base_url.rstrip("/")
+        elif environment is not None:
+            env_lower = environment.lower()
+            if env_lower not in _ENV_BASE_URLS:
+                raise ValueError(
+                    f"Unknown environment {environment!r}. "
+                    f"Expected one of: {', '.join(_ENV_BASE_URLS)}"
+                )
+            base = _ENV_BASE_URLS[env_lower]
+            self._base_url = f"{base}/v1"
+            self._internal_base_url = f"{base}/internal-api/v1"
+        else:
+            raise ValueError("Either 'environment' or 'base_url' must be provided")
+
+    @property
+    def _default_headers(self) -> Headers:
+        return {
+            "x-api-key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": "htag-sdk-python/0.1.0",
+        }
+
+
+# ---------------------------------------------------------------------------
+# Sync request helpers
+# ---------------------------------------------------------------------------
+
+
+class SyncRequestMixin(BaseClient):
+    """Mixin providing synchronous HTTP request methods with retry logic."""
+
+    _http: httpx.Client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[QueryParams] = None,
+        json: Optional[JSONDict] = None,
+        base_url: Optional[str] = None,
+    ) -> Any:
+        url = f"{base_url or self._base_url}{path}"
+        serialised = _serialise_params(params) if params else None
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._http.request(
+                    method,
+                    url,
+                    params=serialised,
+                    json=json,
+                    headers=self._default_headers,
+                    timeout=self._timeout,
+                )
+            except httpx.ConnectError as exc:
+                last_exc = HtAgConnectionError(
+                    f"Connection failed: {exc}",
+                    status_code=None,
+                )
+                if attempt < self._max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.TimeoutException as exc:
+                last_exc = HtAgConnectionError(
+                    f"Request timed out after {self._timeout}s",
+                    status_code=None,
+                )
+                if attempt < self._max_retries:
+                    time.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code < 400:
+                return response.json()
+
+            error = _build_error(response)
+
+            if response.status_code in RETRYABLE_STATUS_CODES and attempt < self._max_retries:
+                retry_after = (
+                    error.retry_after
+                    if isinstance(error, RateLimitError)
+                    else None
+                )
+                time.sleep(_retry_delay(attempt, retry_after))
+                last_exc = error
+                continue
+
+            raise error
+
+        # Should never reach here, but satisfy type-checker
+        raise last_exc or HtAgError("Request failed after retries")  # pragma: no cover
+
+
+# ---------------------------------------------------------------------------
+# Async request helpers
+# ---------------------------------------------------------------------------
+
+
+class AsyncRequestMixin(BaseClient):
+    """Mixin providing asynchronous HTTP request methods with retry logic."""
+
+    _http: httpx.AsyncClient
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[QueryParams] = None,
+        json: Optional[JSONDict] = None,
+        base_url: Optional[str] = None,
+    ) -> Any:
+        import asyncio
+
+        url = f"{base_url or self._base_url}{path}"
+        serialised = _serialise_params(params) if params else None
+
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._http.request(
+                    method,
+                    url,
+                    params=serialised,
+                    json=json,
+                    headers=self._default_headers,
+                    timeout=self._timeout,
+                )
+            except httpx.ConnectError as exc:
+                last_exc = HtAgConnectionError(
+                    f"Connection failed: {exc}",
+                    status_code=None,
+                )
+                if attempt < self._max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+            except httpx.TimeoutException as exc:
+                last_exc = HtAgConnectionError(
+                    f"Request timed out after {self._timeout}s",
+                    status_code=None,
+                )
+                if attempt < self._max_retries:
+                    await asyncio.sleep(_retry_delay(attempt))
+                    continue
+                raise last_exc from exc
+
+            if response.status_code < 400:
+                return response.json()
+
+            error = _build_error(response)
+
+            if response.status_code in RETRYABLE_STATUS_CODES and attempt < self._max_retries:
+                retry_after = (
+                    error.retry_after
+                    if isinstance(error, RateLimitError)
+                    else None
+                )
+                await asyncio.sleep(_retry_delay(attempt, retry_after))
+                last_exc = error
+                continue
+
+            raise error
+
+        raise last_exc or HtAgError("Request failed after retries")  # pragma: no cover

htag/_client.py

@@ -0,0 +1,88 @@
+"""Synchronous HtAG API client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from htag._base import SyncRequestMixin
+from htag.address.client import AddressClient
+from htag.markets.client import MarketsClient
+from htag.property.client import PropertyClient
+
+
+class HtAgApi(SyncRequestMixin):
+    """Synchronous client for the HtAG AI API.
+
+    Usage::
+
+        from htag import HtAgApi
+
+        client = HtAgApi(api_key="sk-...", environment="prod")
+
+        # Address search
+        results = client.address.search("100 George St Sydney")
+
+        # Property sold search
+        sold = client.property.sold_search(address="100 George St Sydney")
+
+        # Market snapshots
+        snapshots = client.markets.snapshots(level="suburb", property_type=["house"])
+
+        # Market trends
+        prices = client.markets.trends.price(level="suburb", area_id=["SAL10001"])
+
+        # Always close when done (or use as a context manager)
+        client.close()
+
+    As a context manager::
+
+        with HtAgApi(api_key="sk-...", environment="prod") as client:
+            results = client.address.search("100 George St Sydney")
+
+    Args:
+        api_key: Your HtAG API key (required).
+        environment: Target environment -- ``"prod"`` or ``"dev"``.
+        base_url: Custom base URL (overrides ``environment``).
+        timeout: Request timeout in seconds (default 60).
+        max_retries: Maximum number of retry attempts for transient errors (default 3).
+    """
+
+    address: AddressClient
+    property: PropertyClient
+    markets: MarketsClient
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        environment: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            environment=environment,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._http = httpx.Client()
+        self.address = AddressClient(self)
+        self.property = PropertyClient(self)
+        self.markets = MarketsClient(self)
+
+    def close(self) -> None:
+        """Release underlying HTTP connection pool resources."""
+        self._http.close()
+
+    def __enter__(self) -> "HtAgApi":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"HtAgApi(base_url={self._base_url!r})"