salestax-python 0.1.0__py3-none-any.whl

salestax/client.py

@@ -0,0 +1,215 @@
+"""Public client facades — sync and async."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT_MS,
+    ClientOptions,
+    RetryPolicy,
+)
+from ._transport.http_client import AsyncHttpClient, HttpClient
+from ._transport.types import AsyncTransport, Hooks, SyncTransport
+from .resources.jurisdictions import JurisdictionsResource
+from .resources.rates import RatesResource
+from .resources.tax import TaxResource
+
+
+class SalesTaxClient:
+    """Synchronous client for the Sales Tax Calculator API.
+
+    Example:
+        >>> from salestax import SalesTaxClient
+        >>> with SalesTaxClient() as client:
+        ...     tax = client.tax.calculate(zip_code="90210", amount=100)
+        >>> tax["taxAmount"]
+        9.75
+
+    Args:
+        api_key: API key. Falls back to ``SALESTAX_API_KEY`` when omitted.
+        base_url: Override the API base URL.
+        timeout_ms: Per-request timeout in milliseconds.
+        retry: Custom retry policy. Fields not set keep defaults.
+        default_headers: Headers merged into every request.
+        transport: Custom transport implementing :class:`SyncTransport`.
+        hooks: Lifecycle callbacks (see :class:`Hooks`).
+        chunk_batch: If True, ``calculate_batch`` auto-splits inputs >100.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        retry: RetryPolicy | None = None,
+        default_headers: dict[str, str] | None = None,
+        transport: SyncTransport | None = None,
+        hooks: Hooks | None = None,
+        chunk_batch: bool = False,
+    ) -> None:
+        options = ClientOptions(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            retry=retry or RetryPolicy(),
+            default_headers=dict(default_headers or {}),
+            chunk_batch=chunk_batch,
+        )
+        self._options = options
+        self._http = HttpClient(options, transport=transport, hooks=hooks)
+        self.tax = TaxResource(self._http, chunk_batch=chunk_batch)
+        self.rates = RatesResource(self._http)
+        self.jurisdictions = JurisdictionsResource(self._http)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> SalesTaxClient:
+        """Construct using ``SALESTAX_API_KEY`` from the environment."""
+        return cls(**overrides)
+
+    def close(self) -> None:
+        """Release transport resources."""
+        self._http.close()
+
+    def __enter__(self) -> SalesTaxClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncSalesTaxClient:
+    """Asynchronous client. Requires the ``[async]`` extra.
+
+    Example:
+        >>> async with AsyncSalesTaxClient() as client:
+        ...     tax = await client.tax.calculate(zip_code="90210", amount=100)
+
+    Args:
+        api_key: API key. Falls back to ``SALESTAX_API_KEY`` when omitted.
+        base_url: Override the API base URL.
+        timeout_ms: Per-request timeout in milliseconds.
+        retry: Custom retry policy.
+        default_headers: Headers merged into every request.
+        transport: Custom transport implementing :class:`AsyncTransport`.
+        hooks: Lifecycle callbacks.
+        chunk_batch: If True, ``calculate_batch`` auto-splits inputs >100.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        retry: RetryPolicy | None = None,
+        default_headers: dict[str, str] | None = None,
+        transport: AsyncTransport | None = None,
+        hooks: Hooks | None = None,
+        chunk_batch: bool = False,
+    ) -> None:
+        options = ClientOptions(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            retry=retry or RetryPolicy(),
+            default_headers=dict(default_headers or {}),
+            chunk_batch=chunk_batch,
+        )
+        self._options = options
+        self._http = AsyncHttpClient(options, transport=transport, hooks=hooks)
+        self.tax = _AsyncTaxResource(self._http, chunk_batch=chunk_batch)
+        self.rates = _AsyncRatesResource(self._http)
+        self.jurisdictions = _AsyncJurisdictionsResource(self._http)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> AsyncSalesTaxClient:
+        return cls(**overrides)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncSalesTaxClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+# -- Async resources --------------------------------------------------------
+
+
+class _AsyncTaxResource:
+    def __init__(self, http: Any, *, chunk_batch: bool = False) -> None:
+        self._http = http
+        self._chunk_batch = chunk_batch
+
+    async def calculate(self, **kwargs: Any) -> Any:
+        from .errors import ValidationError
+
+        if not kwargs.get("zip_code"):
+            raise ValidationError(
+                "MISSING_PARAM", "zip_code is required", status_code=400, param="zip_code"
+            )
+        payload: dict[str, Any] = {
+            "zipCode": kwargs["zip_code"],
+            "amount": kwargs["amount"],
+        }
+        for src, dst in (("state", "state"), ("country", "country"), ("city", "city")):
+            if kwargs.get(src) is not None:
+                payload[dst] = kwargs[src]
+        return await self._http.send("POST", "/calculate", body=payload)
+
+    async def calculate_batch(self, transactions: Any, **kwargs: Any) -> Any:
+        from ._config import MAX_BATCH_SIZE
+        from .errors import ValidationError
+
+        if not transactions:
+            raise ValidationError("EMPTY_BATCH", "Batch must not be empty", status_code=400)
+        if len(transactions) > MAX_BATCH_SIZE and not self._chunk_batch:
+            raise ValidationError(
+                "BATCH_LIMIT_EXCEEDED",
+                f"Batch is limited to {MAX_BATCH_SIZE} transactions.",
+                status_code=400,
+            )
+        return await self._http.send(
+            "POST", "/calculate/batch", body={"transactions": list(transactions)}
+        )
+
+    async def calculate_batch_chunked(self, transactions: Any, **kwargs: Any) -> Any:
+        from ._config import MAX_BATCH_SIZE
+        from .utils import chunk
+
+        results = []
+        for batch in chunk(list(transactions), MAX_BATCH_SIZE):
+            res = await self.calculate_batch(batch, **kwargs)
+            results.extend(res.get("results", []))
+        return {"results": results, "count": len(results)}
+
+
+class _AsyncRatesResource:
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    async def get(self, zip_code: str, **kwargs: Any) -> Any:
+        from urllib.parse import quote
+
+        return await self._http.send("GET", f"/rates/{quote(zip_code, safe='')}")
+
+
+class _AsyncJurisdictionsResource:
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    async def list(self, **kwargs: Any) -> Any:
+        from urllib.parse import urlencode
+
+        params = {
+            k: v
+            for k, v in {"country": kwargs.get("country"), "state": kwargs.get("state")}.items()
+            if v is not None
+        }
+        query = f"?{urlencode(params)}" if params else ""
+        return await self._http.send("GET", f"/jurisdictions{query}")

salestax/errors.py

@@ -0,0 +1,202 @@
+"""Error hierarchy.
+
+All SDK errors inherit from :class:`SalesTaxError`. API errors inherit from
+:class:`ApiError` and carry a ``status_code``, ``code``, ``request_id``, and
+(where relevant) ``param``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class SalesTaxError(Exception):
+    """Base class for all SDK errors."""
+
+    code: str = "UNKNOWN"
+    retryable: bool = False
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        if retryable is not None:
+            self.retryable = retryable
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"{type(self).__name__}(code={self.code!r}, "
+            f"status_code={self.status_code!r}, message={self.message!r})"
+        )
+
+
+# -- API errors -------------------------------------------------------------
+
+
+class ApiError(SalesTaxError):
+    """Base class for errors returned by the API (4xx / 5xx)."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status_code: int,
+        request_id: str | None = None,
+        retryable: bool = False,
+        param: str | None = None,
+    ) -> None:
+        super().__init__(
+            code, message, status_code=status_code, request_id=request_id, retryable=retryable
+        )
+        self.param = param
+
+
+class AuthenticationError(ApiError):
+    """401 — API key missing or invalid."""
+
+
+class PermissionError(ApiError):
+    """403 — key lacks access to the requested resource."""
+
+
+class ValidationError(ApiError):
+    """400 / 422 — request failed validation. Inspect ``param``."""
+
+
+class NotFoundError(ApiError):
+    """404 — resource or jurisdiction not found."""
+
+
+class ConflictError(ApiError):
+    """409 — request conflicts with current state."""
+
+
+class ServerError(ApiError):
+    """5xx — server-side failure. Retryable."""
+
+
+class RateLimitError(ApiError):
+    """429 — rate limit exceeded. ``retry_after_ms`` may be present."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        status_code: int,
+        request_id: str | None = None,
+        param: str | None = None,
+        retry_after_ms: int | None = None,
+    ) -> None:
+        super().__init__(
+            code,
+            message,
+            status_code=status_code,
+            request_id=request_id,
+            retryable=True,
+            param=param,
+        )
+        self.retry_after_ms = retry_after_ms
+
+
+# -- Transport errors -------------------------------------------------------
+
+
+class ConnectionError(SalesTaxError):
+    """Network failure: DNS, TLS, socket, reset. Retryable by default."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "CONNECTION_ERROR",
+        retryable: bool = True,
+    ) -> None:
+        super().__init__(code, message, retryable=retryable)
+
+
+class TimeoutError(ConnectionError):
+    """Request exceeded the configured timeout."""
+
+    def __init__(self, timeout_ms: int) -> None:
+        super().__init__(f"Request timed out after {timeout_ms}ms", code="TIMEOUT")
+
+
+# -- Status → error mapping -------------------------------------------------
+
+_STATUS_MAP: Mapping[int, type[ApiError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+}
+
+
+def error_from_response(
+    status_code: int,
+    body: Mapping[str, Any],
+    *,
+    request_id: str | None = None,
+    retry_after_ms: int | None = None,
+) -> ApiError:
+    """Map an HTTP status + JSON body into the appropriate ``ApiError`` subclass."""
+    code = str(body.get("code") or f"HTTP_{status_code}")
+    message = str(body.get("message") or f"Request failed with status {status_code}")
+    param = body.get("param")
+    param_str = str(param) if param is not None else None
+
+    if status_code == 429:
+        return RateLimitError(
+            code,
+            message,
+            status_code=status_code,
+            request_id=request_id,
+            param=param_str,
+            retry_after_ms=retry_after_ms,
+        )
+    if status_code >= 500:
+        return ServerError(
+            code,
+            message,
+            status_code=status_code,
+            request_id=request_id,
+            retryable=True,
+            param=param_str,
+        )
+
+    ctor: type[ApiError] = _STATUS_MAP.get(status_code, ApiError)
+    if ctor is ApiError:
+        return ApiError(
+            code, message, status_code=status_code, request_id=request_id, param=param_str
+        )
+    return ctor(code, message, status_code=status_code, request_id=request_id, param=param_str)
+
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "ConflictError",
+    "ConnectionError",
+    "NotFoundError",
+    "PermissionError",
+    "RateLimitError",
+    "SalesTaxError",
+    "ServerError",
+    "TimeoutError",
+    "ValidationError",
+    "error_from_response",
+]

salestax/models.py

@@ -0,0 +1,80 @@
+"""Typed request and response shapes.
+
+Uses ``TypedDict`` so the objects remain plain ``dict`` at runtime — no
+deserialization overhead, and users get full IDE autocomplete on responses.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class _CalculateTaxParamsRequired(TypedDict):
+    """Required fields for a single tax calculation."""
+
+    zipCode: str
+    amount: float
+
+
+class CalculateTaxParams(_CalculateTaxParamsRequired, total=False):
+    """Parameters for a single tax calculation.
+
+    ``zipCode`` and ``amount`` are required (inherited from
+    :class:`_CalculateTaxParamsRequired`); ``state``, ``country`` and ``city``
+    are optional.
+    """
+
+    state: str
+    country: str
+    city: str
+
+
+class TaxBreakdownEntry(TypedDict, total=False):
+    """A single jurisdiction's contribution to the total tax."""
+
+    jurisdiction: str
+    name: str
+    rate: float
+    amount: float
+
+
+class TaxCalculation(TypedDict, total=False):
+    """Response shape for a single calculation."""
+
+    taxAmount: float
+    totalAmount: float
+    rate: float
+    jurisdiction: str
+    breakdown: list[TaxBreakdownEntry]
+
+
+class BatchResult(TypedDict):
+    """Response shape for batch calculations."""
+
+    results: list[TaxCalculation]
+    count: int
+
+
+class TaxRate(TypedDict, total=False):
+    """Response for a rate lookup."""
+
+    zipCode: str
+    rate: float
+    jurisdiction: str
+
+
+class Jurisdiction(TypedDict, total=False):
+    """A supported jurisdiction."""
+
+    code: str
+    name: str
+    country: str
+    state: str | None
+    type: str
+
+
+class JurisdictionQuery(TypedDict, total=False):
+    """Query filters for listing jurisdictions."""
+
+    country: str
+    state: str

salestax/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. Empty on purpose.

salestax/resources/__init__.py

@@ -0,0 +1,5 @@
+from .jurisdictions import JurisdictionsResource
+from .rates import RatesResource
+from .tax import TaxResource
+
+__all__ = ["JurisdictionsResource", "RatesResource", "TaxResource"]

salestax/resources/jurisdictions.py

@@ -0,0 +1,27 @@
+"""``client.jurisdictions`` resource."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+from ..models import Jurisdiction
+
+
+class JurisdictionsResource:
+    """Jurisdiction listing endpoints. Do not instantiate directly."""
+
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    def list(
+        self,
+        *,
+        country: str | None = None,
+        state: str | None = None,
+        retryable: bool = True,
+    ) -> list[Jurisdiction]:
+        """List supported jurisdictions, optionally filtered."""
+        params = {k: v for k, v in {"country": country, "state": state}.items() if v is not None}
+        query = f"?{urlencode(params)}" if params else ""
+        return self._http.send("GET", f"/jurisdictions{query}")  # type: ignore[no-any-return]

salestax/resources/rates.py

@@ -0,0 +1,25 @@
+"""``client.rates`` resource."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from ..errors import ValidationError
+from ..models import TaxRate
+
+
+class RatesResource:
+    """Rate lookup endpoints. Do not instantiate directly."""
+
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    def get(self, zip_code: str, *, retryable: bool = True) -> TaxRate:
+        """Return the effective tax rate for a ZIP / postal code."""
+        if not zip_code:
+            raise ValidationError(
+                "MISSING_PARAM", "zip_code is required", status_code=400, param="zip_code"
+            )
+        path = f"/rates/{quote(zip_code, safe='')}"
+        return self._http.send("GET", path)  # type: ignore[no-any-return]