simpleapps-com-augur-api 0.8.10__py3-none-any.whl

augur_api/core/errors.py

@@ -0,0 +1,173 @@
+"""Error classes for the Augur API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AugurError(Exception):
+    """Base error class for all Augur API errors.
+
+    Attributes:
+        message: Human-readable error message.
+        code: Error code string (e.g., 'API_ERROR', 'NETWORK_ERROR').
+        status_code: HTTP status code if applicable.
+        service: The service that raised the error.
+        endpoint: The endpoint that raised the error.
+        request_id: Optional request ID for debugging.
+        validation_errors: Optional list of validation errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        service: str,
+        endpoint: str,
+        request_id: str | None = None,
+        validation_errors: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message: Human-readable error message.
+            code: Error code string.
+            status_code: HTTP status code.
+            service: The service that raised the error.
+            endpoint: The endpoint that raised the error.
+            request_id: Optional request ID for debugging.
+            validation_errors: Optional list of validation errors.
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.service = service
+        self.endpoint = endpoint
+        self.request_id = request_id
+        self.validation_errors = validation_errors
+
+    def __str__(self) -> str:
+        """Return string representation of the error."""
+        parts = [f"{self.code}: {self.message}"]
+        parts.append(f"(service={self.service}, endpoint={self.endpoint})")
+        if self.request_id:
+            parts.append(f"[request_id={self.request_id}]")
+        return " ".join(parts)
+
+
+class ValidationError(AugurError):
+    """Error raised when request or response validation fails.
+
+    Provides detailed information about which fields failed validation.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        service: str,
+        endpoint: str,
+        validation_errors: list[dict[str, Any]],
+    ) -> None:
+        """Initialize the validation error.
+
+        Args:
+            message: Human-readable error message.
+            service: The service that raised the error.
+            endpoint: The endpoint that raised the error.
+            validation_errors: List of validation error details.
+        """
+        super().__init__(
+            message=message,
+            code="VALIDATION_ERROR",
+            status_code=400,
+            service=service,
+            endpoint=endpoint,
+            validation_errors=validation_errors,
+        )
+
+    def get_formatted_errors(self) -> list[str]:
+        """Format validation errors into human-readable messages.
+
+        Returns:
+            List of formatted error messages.
+        """
+        if not self.validation_errors:
+            return []
+
+        formatted = []
+        for error in self.validation_errors:
+            path = ".".join(str(p) for p in error.get("loc", [])) or "root"
+            msg = error.get("msg", "Unknown error")
+            formatted.append(f"{path}: {msg}")
+        return formatted
+
+    def __str__(self) -> str:
+        """Return string representation with validation details."""
+        base = super().__str__()
+        formatted = self.get_formatted_errors()
+        if formatted:
+            errors_str = "\n  - ".join(formatted)
+            return f"{base}\nValidation errors:\n  - {errors_str}"
+        return base
+
+
+class AuthenticationError(AugurError):
+    """Error raised when authentication fails (HTTP 401)."""
+
+    def __init__(self, message: str, service: str, endpoint: str) -> None:
+        """Initialize the authentication error.
+
+        Args:
+            message: Human-readable error message.
+            service: The service that raised the error.
+            endpoint: The endpoint that raised the error.
+        """
+        super().__init__(
+            message=message,
+            code="AUTHENTICATION_ERROR",
+            status_code=401,
+            service=service,
+            endpoint=endpoint,
+        )
+
+
+class NotFoundError(AugurError):
+    """Error raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, message: str, service: str, endpoint: str) -> None:
+        """Initialize the not found error.
+
+        Args:
+            message: Human-readable error message.
+            service: The service that raised the error.
+            endpoint: The endpoint that raised the error.
+        """
+        super().__init__(
+            message=message,
+            code="NOT_FOUND",
+            status_code=404,
+            service=service,
+            endpoint=endpoint,
+        )
+
+
+class RateLimitError(AugurError):
+    """Error raised when rate limit is exceeded (HTTP 429)."""
+
+    def __init__(self, message: str, service: str, endpoint: str) -> None:
+        """Initialize the rate limit error.
+
+        Args:
+            message: Human-readable error message.
+            service: The service that raised the error.
+            endpoint: The endpoint that raised the error.
+        """
+        super().__init__(
+            message=message,
+            code="RATE_LIMIT_EXCEEDED",
+            status_code=429,
+            service=service,
+            endpoint=endpoint,
+        )

augur_api/core/http_client.py

@@ -0,0 +1,426 @@
+"""HTTP client for making requests to Augur API services."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import random
+import time
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import httpx
+
+from augur_api.core.errors import (
+    AugurError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+)
+
+if TYPE_CHECKING:
+    from augur_api.core.config import AugurAPIConfig
+
+T = TypeVar("T")
+
+# Service base URLs
+SERVICE_BASE_URLS: dict[str, str] = {
+    "agr-info": "https://agr-info.augur-api.com",
+    "agr-site": "https://agr-site.augur-api.com",
+    "agr-work": "https://agr-work.augur-api.com",
+    "avalara": "https://avalara.augur-api.com",
+    "basecamp2": "https://basecamp2.augur-api.com",
+    "brand-folder": "https://brand-folder.augur-api.com",
+    "commerce": "https://commerce.augur-api.com",
+    "customers": "https://customers.augur-api.com",
+    "gregorovich": "https://gregorovich.augur-api.com",
+    "items": "https://items.augur-api.com",
+    "joomla": "https://joomla.augur-api.com",
+    "legacy": "https://legacy.augur-api.com",
+    "logistics": "https://logistics.augur-api.com",
+    "nexus": "https://nexus.augur-api.com",
+    "open-search": "https://open-search.augur-api.com",
+    "orders": "https://orders.augur-api.com",
+    "p21-apis": "https://p21-apis.augur-api.com",
+    "p21-core": "https://p21-core.augur-api.com",
+    "p21-pim": "https://p21-pim.augur-api.com",
+    "p21-sism": "https://p21-sism.augur-api.com",
+    "payments": "https://payments.augur-api.com",
+    "pricing": "https://pricing.augur-api.com",
+    "shipping": "https://shipping.augur-api.com",
+    "slack": "https://slack.augur-api.com",
+    "smarty-streets": "https://smarty-streets.augur-api.com",
+    "ups": "https://ups.augur-api.com",
+    "vmi": "https://vmi.augur-api.com",
+}
+
+
+def _generate_request_key(method: str, url: str, params: Any | None = None) -> str:
+    """Generate a unique key for request deduplication.
+
+    Args:
+        method: HTTP method.
+        url: Request URL.
+        params: Query parameters or request body.
+
+    Returns:
+        Unique string key for this request.
+    """
+    params_str = ""
+    if params:
+        # Sort keys for consistent hashing
+        params_str = json.dumps(params, sort_keys=True)
+    combined = f"{method}:{url}:{params_str}"
+    return hashlib.md5(combined.encode()).hexdigest()  # noqa: S324
+
+
+def _calculate_backoff_delay(attempt: int, base_delay: float) -> float:
+    """Calculate delay for exponential backoff with jitter.
+
+    Args:
+        attempt: Current attempt number (0-indexed).
+        base_delay: Base delay in seconds.
+
+    Returns:
+        Delay in seconds with jitter.
+    """
+    exponential_delay = base_delay * (2**attempt)
+    jitter = random.random() * 0.3 * exponential_delay  # noqa: S311
+    delay = exponential_delay + jitter
+    return delay if delay < 30.0 else 30.0  # Cap at 30 seconds
+
+
+def _is_retryable_error(status_code: int | None) -> bool:
+    """Determine if an error is retryable.
+
+    Args:
+        status_code: HTTP status code, or None for network errors.
+
+    Returns:
+        True if the request should be retried.
+    """
+    # Network errors (no status) are retryable
+    if status_code is None:
+        return True
+
+    # Rate limit (429) and server errors (5xx) are retryable
+    return status_code == 429 or (status_code >= 500 and status_code < 600)
+
+
+class HTTPClient:
+    """HTTP client for making requests to a specific Augur service.
+
+    Handles authentication, retries, request deduplication, and error mapping.
+
+    Attributes:
+        service_name: Name of the service (e.g., 'items', 'customers').
+        config: Client configuration.
+    """
+
+    def __init__(self, service_name: str, config: AugurAPIConfig) -> None:
+        """Initialize the HTTP client.
+
+        Args:
+            service_name: Name of the service.
+            config: Client configuration.
+        """
+        self.service_name = service_name
+        self.config = config
+        self._base_url = SERVICE_BASE_URLS.get(
+            service_name, f"https://{service_name}.augur-api.com"
+        )
+        self._inflight_requests: dict[str, dict[str, Any]] = {}
+        self._client = httpx.Client(timeout=config.timeout)
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL for this service."""
+        return self._base_url
+
+    def _get_headers(self, endpoint: str) -> dict[str, str]:
+        """Build request headers.
+
+        Args:
+            endpoint: The endpoint path being called.
+
+        Returns:
+            Dictionary of headers.
+        """
+        headers: dict[str, str] = {
+            "x-site-id": self.config.site_id,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+        # Add bearer token for non-public endpoints
+        is_public = endpoint.endswith(("/health-check", "/ping"))
+        if not is_public and self.config.token:
+            headers["Authorization"] = f"Bearer {self.config.token}"
+
+        return headers
+
+    def _handle_http_error(self, response: httpx.Response, endpoint: str) -> None:
+        """Handle HTTP error responses by raising appropriate exceptions.
+
+        Args:
+            response: The HTTP response.
+            endpoint: The endpoint that was called.
+
+        Raises:
+            AuthenticationError: For 401 responses.
+            NotFoundError: For 404 responses.
+            RateLimitError: For 429 responses.
+            AugurError: For other error responses.
+        """
+        status = response.status_code
+
+        # Try to extract error details from response
+        try:
+            data = response.json()
+            message = data.get("message", f"Request failed with status {status}")
+            code = data.get("code", "API_ERROR")
+            request_id = data.get("requestId")
+        except Exception:
+            message = f"Request failed with status {status}"
+            code = "API_ERROR"
+            request_id = None
+
+        if status == 401:
+            raise AuthenticationError(
+                message=message or "Authentication failed",
+                service=self.service_name,
+                endpoint=endpoint,
+            )
+        if status == 404:
+            raise NotFoundError(
+                message=message or "Resource not found",
+                service=self.service_name,
+                endpoint=endpoint,
+            )
+        if status == 429:
+            raise RateLimitError(
+                message=message or "Rate limit exceeded",
+                service=self.service_name,
+                endpoint=endpoint,
+            )
+
+        raise AugurError(
+            message=message,
+            code=code,
+            status_code=status,
+            service=self.service_name,
+            endpoint=endpoint,
+            request_id=request_id,
+        )
+
+    def _execute_with_retry(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any] | None = None,
+        json_data: Any | None = None,
+    ) -> httpx.Response:
+        """Execute a request with retry logic.
+
+        Args:
+            method: HTTP method.
+            url: Full URL to request.
+            params: Query parameters.
+            json_data: JSON body data.
+
+        Returns:
+            HTTP response.
+
+        Raises:
+            AugurError: For network or API errors.
+        """
+        max_retries = self.config.retries
+        base_delay = self.config.retry_delay
+        endpoint = url.replace(self._base_url, "")
+
+        for attempt in range(max_retries + 1):
+            try:
+                headers = self._get_headers(endpoint)
+                response = self._client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json_data,
+                    headers=headers,
+                )
+
+                # Check for HTTP errors
+                if response.status_code >= 400:
+                    # Only retry on retryable errors
+                    if attempt < max_retries and _is_retryable_error(response.status_code):
+                        delay = _calculate_backoff_delay(attempt, base_delay)
+                        time.sleep(delay)
+                        continue
+                    self._handle_http_error(response, endpoint)
+
+                return response
+
+            except httpx.RequestError as e:
+                # Network errors are retryable
+                if attempt < max_retries:
+                    delay = _calculate_backoff_delay(attempt, base_delay)
+                    time.sleep(delay)
+                    continue
+
+                raise AugurError(
+                    message=str(e),
+                    code="NETWORK_ERROR",
+                    status_code=0,
+                    service=self.service_name,
+                    endpoint=endpoint,
+                ) from e
+
+        # Should not reach here, but satisfy type checker
+        raise AugurError(  # pragma: no cover
+            message="Max retries exceeded",
+            code="MAX_RETRIES",
+            status_code=0,
+            service=self.service_name,
+            endpoint=endpoint,
+        )
+
+    def _transform_edge_cache_params(self, params: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Transform edge_cache parameter to Cloudflare's cacheSiteId format.
+
+        Cloudflare expects cacheSiteId{suffix}=<site_id> where suffix indicates duration:
+        - '30s', '1m', '5m' for sub-hour caches
+        - 1, 2, 3, 4, 5, 8 for hourly caches
+
+        Examples:
+        - edge_cache: '30s' → cacheSiteId30s: <site_id>
+        - edge_cache: '1m' → cacheSiteId1m: <site_id>
+        - edge_cache: '5m' → cacheSiteId5m: <site_id>
+        - edge_cache: 1 → cacheSiteId1: <site_id>
+        - edge_cache: 8 → cacheSiteId8: <site_id>
+
+        Args:
+            params: Original request parameters.
+
+        Returns:
+            Parameters with edge_cache transformed to cacheSiteId{suffix}.
+        """
+        if not params:
+            return params
+
+        edge_cache = params.get("edge_cache")
+
+        # If no edge_cache param, return original params
+        if edge_cache is None:
+            return params
+
+        # Valid sub-hour values (strings only)
+        valid_sub_hour = {"30s", "1m", "5m"}
+        # Valid hourly values
+        valid_hourly = {1, 2, 3, 4, 5, 8}
+
+        edge_cache_str = str(edge_cache)
+
+        if edge_cache_str in valid_sub_hour:
+            # Sub-hour cache: '30s', '1m', '5m'
+            cache_suffix = edge_cache_str
+        else:
+            # Try to parse as hourly value
+            try:
+                cache_hours = int(edge_cache_str)
+            except ValueError:
+                # Invalid value - return params without edge_cache
+                return {k: v for k, v in params.items() if k != "edge_cache"}
+
+            if cache_hours not in valid_hourly:
+                # Invalid value - return params without edge_cache
+                return {k: v for k, v in params.items() if k != "edge_cache"}
+
+            cache_suffix = str(cache_hours)
+
+        # Transform to Cloudflare format: cacheSiteId{suffix}=<site_id>
+        cache_key = f"cacheSiteId{cache_suffix}"
+        result = {k: v for k, v in params.items() if k != "edge_cache"}
+        result[cache_key] = self.config.site_id
+
+        return result
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a GET request.
+
+        Args:
+            path: Endpoint path (e.g., '/health-check').
+            params: Query parameters.
+
+        Returns:
+            Response JSON as a dictionary.
+        """
+        # Transform edge_cache to cacheSiteId{N} format for Cloudflare
+        transformed_params = self._transform_edge_cache_params(params)
+        url = f"{self._base_url}{path}"
+
+        # Request deduplication for GET requests
+        request_key = _generate_request_key("GET", url, transformed_params)
+        if request_key in self._inflight_requests:
+            return self._inflight_requests[request_key]
+
+        try:
+            response = self._execute_with_retry("GET", url, params=transformed_params)
+            result: dict[str, Any] = response.json()
+            return result
+        finally:
+            # Clean up inflight tracking
+            self._inflight_requests.pop(request_key, None)
+
+    def post(
+        self, path: str, data: Any | None = None, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Make a POST request.
+
+        Args:
+            path: Endpoint path.
+            data: Request body data.
+            params: Query parameters.
+
+        Returns:
+            Response JSON as a dictionary.
+        """
+        url = f"{self._base_url}{path}"
+        response = self._execute_with_retry("POST", url, params=params, json_data=data)
+        result: dict[str, Any] = response.json()
+        return result
+
+    def put(
+        self, path: str, data: Any | None = None, params: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Make a PUT request.
+
+        Args:
+            path: Endpoint path.
+            data: Request body data.
+            params: Query parameters.
+
+        Returns:
+            Response JSON as a dictionary.
+        """
+        url = f"{self._base_url}{path}"
+        response = self._execute_with_retry("PUT", url, params=params, json_data=data)
+        result: dict[str, Any] = response.json()
+        return result
+
+    def delete(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make a DELETE request.
+
+        Args:
+            path: Endpoint path.
+            params: Query parameters.
+
+        Returns:
+            Response JSON as a dictionary.
+        """
+        url = f"{self._base_url}{path}"
+        response = self._execute_with_retry("DELETE", url, params=params)
+        result: dict[str, Any] = response.json()
+        return result
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self._client.close()

augur_api/core/schemas.py

@@ -0,0 +1,105 @@
+"""Base schemas for Augur API responses."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+T = TypeVar("T")
+
+
+class CamelCaseModel(BaseModel):
+    """Base model that handles camelCase to snake_case conversion.
+
+    The Augur API returns camelCase field names, but Python convention
+    uses snake_case. This model automatically handles the conversion.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+        alias_generator=to_camel,
+    )
+
+
+class BaseResponse(CamelCaseModel, Generic[T]):
+    """Base response schema for all Augur API responses.
+
+    All API responses follow this structure, wrapping the actual data
+    with metadata about the request and response.
+
+    Attributes:
+        count: Number of items in the current response.
+        data: The actual response data (type varies by endpoint).
+        message: Response message from the API.
+        options: Additional options (supports both array and object formats).
+        params: Parameters used in the request.
+        status: HTTP status code.
+        total: Total number of results available.
+        total_results: Total results (alias handled by CamelCaseModel).
+    """
+
+    count: int
+    data: T
+    message: str
+    options: list[Any] | dict[str, Any]
+    params: list[Any] | dict[str, Any]
+    status: int
+    total: int
+    total_results: int
+
+
+class HealthCheckData(CamelCaseModel):
+    """Health check response data.
+
+    Returned by all service /health-check endpoints.
+
+    Attributes:
+        site_hash: Hash of the site configuration.
+        site_id: Site identifier.
+    """
+
+    site_hash: str
+    site_id: str
+
+
+class PingData(BaseModel):
+    """Ping response data.
+
+    Simple connectivity check - returns 'pong'.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+
+class PaginationParams(BaseModel):
+    """Common pagination parameters for list endpoints.
+
+    Attributes:
+        limit: Maximum number of items to return.
+        offset: Number of items to skip.
+    """
+
+    limit: int | None = None
+    offset: int | None = None
+
+
+class EdgeCacheParams(BaseModel):
+    """Edge cache duration parameters.
+
+    Supported values for Cloudflare cache rules.
+
+    Attributes:
+        edge_cache: Cache duration - sub-hour ('30s', '1m', '5m') or hourly (1-5, 8).
+    """
+
+    edge_cache: str | int | None = None
+
+
+class BaseGetParams(PaginationParams, EdgeCacheParams):
+    """Combined base parameters for GET requests.
+
+    Includes both pagination and edge caching options.
+    """