fauxshield 0.1.0__py3-none-any.whl

fauxshield/__init__.py

@@ -0,0 +1,62 @@
+"""FauxShield Python SDK.
+
+Official Python client for the FauxShield anti-counterfeiting platform API.
+
+Quick start:
+    ```python
+    from fauxshield import FauxShieldClient
+
+    client = FauxShieldClient(api_key="fs_live_...")
+    products = client.products.list()
+    ```
+
+For webhook verification:
+    ```python
+    from fauxshield import verify_webhook_signature
+
+    verify_webhook_signature(
+        payload=request.body,
+        signature=request.headers["X-FauxShield-Signature"],
+        secret="whsec_...",
+    )
+    ```
+"""
+
+from .client import FauxShieldClient
+from .errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    FauxShieldError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .pagination import PaginatedIterator
+from .types import PaginatedResponse, PaginationMeta, RateLimitInfo
+from .webhook import verify_webhook_signature, WebhookVerificationError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "FauxShieldClient",
+    # Errors
+    "FauxShieldError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ConflictError",
+    "ServiceUnavailableError",
+    # Webhook
+    "verify_webhook_signature",
+    "WebhookVerificationError",
+    # Types
+    "PaginatedIterator",
+    "PaginatedResponse",
+    "PaginationMeta",
+    "RateLimitInfo",
+]

fauxshield/client.py

@@ -0,0 +1,173 @@
+"""Main client for the FauxShield Python SDK.
+
+Provides the top-level FauxShieldClient class that serves as the
+primary entry point for all API interactions.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .http_client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, HttpClient
+from .resources import (
+    ApiKeysResource,
+    BatchesResource,
+    EventsResource,
+    FraudAlertsResource,
+    IdentitiesResource,
+    ProductsResource,
+    WebhooksResource,
+)
+from .types import RateLimitInfo
+
+
+class FauxShieldClient:
+    """FauxShield API client.
+
+    The main entry point for interacting with the FauxShield API.
+    Provides access to all resource namespaces through typed properties.
+
+    Example:
+        ```python
+        from fauxshield import FauxShieldClient
+
+        client = FauxShieldClient(api_key="fs_live_...")
+
+        # Access resources
+        products = client.products.list()
+        batch = client.batches.create(product_id="prod_123", quantity=500)
+        alerts = client.fraud_alerts.list(status="open")
+
+        # Clean up when done
+        client.close()
+        ```
+
+    Context manager usage:
+        ```python
+        with FauxShieldClient(api_key="fs_live_...") as client:
+            for product in client.products.list():
+                print(product["name"])
+        ```
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ) -> None:
+        """Initialize the FauxShield client.
+
+        Args:
+            api_key: Your FauxShield API key (required).
+                Keys start with "fs_live_" for production or "fs_test_" for sandbox.
+            base_url: Override the base API URL. Defaults to production.
+            timeout: Request timeout in seconds. Defaults to 30.
+            max_retries: Maximum retry attempts for transient failures. Defaults to 3.
+
+        Raises:
+            ValueError: If api_key is empty.
+        """
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self._http_client = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+        # Initialize resource namespaces
+        self._products = ProductsResource(self._http_client)
+        self._batches = BatchesResource(self._http_client)
+        self._identities = IdentitiesResource(self._http_client)
+        self._fraud_alerts = FraudAlertsResource(self._http_client)
+        self._events = EventsResource(self._http_client)
+        self._webhooks = WebhooksResource(self._http_client)
+        self._api_keys = ApiKeysResource(self._http_client)
+
+    @property
+    def products(self) -> ProductsResource:
+        """Access the Products API.
+
+        Manage products protected by the anti-counterfeiting system.
+        """
+        return self._products
+
+    @property
+    def batches(self) -> BatchesResource:
+        """Access the Batches API.
+
+        Manage product batches and initiate recalls.
+        """
+        return self._batches
+
+    @property
+    def identities(self) -> IdentitiesResource:
+        """Access the Identities API.
+
+        Generate and manage unique product identity tokens.
+        """
+        return self._identities
+
+    @property
+    def fraud_alerts(self) -> FraudAlertsResource:
+        """Access the Fraud Alerts API.
+
+        View and resolve fraud alerts from the detection engine.
+        """
+        return self._fraud_alerts
+
+    @property
+    def events(self) -> EventsResource:
+        """Access the Events API.
+
+        Query the immutable audit event trail.
+        """
+        return self._events
+
+    @property
+    def webhooks(self) -> WebhooksResource:
+        """Access the Webhooks API.
+
+        Manage webhook endpoints for real-time notifications.
+        """
+        return self._webhooks
+
+    @property
+    def api_keys(self) -> ApiKeysResource:
+        """Access the API Keys API.
+
+        Manage API keys for programmatic access.
+        """
+        return self._api_keys
+
+    @property
+    def last_rate_limit(self) -> Optional[RateLimitInfo]:
+        """Most recent rate limit info from the last API response.
+
+        Returns None if no requests have been made yet.
+        """
+        return self._http_client.last_rate_limit
+
+    def close(self) -> None:
+        """Close the client and release all resources.
+
+        Always call this method when you're done using the client,
+        or use the client as a context manager instead.
+        """
+        self._http_client.close()
+
+    def __enter__(self) -> "FauxShieldClient":
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Exit the context manager and close resources."""
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"FauxShieldClient(base_url={self._http_client._base_url!r})"

fauxshield/errors.py

@@ -0,0 +1,182 @@
+"""Error classes for the FauxShield Python SDK.
+
+Provides a structured error hierarchy that maps API error responses
+to specific exception types for precise error handling.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class FauxShieldError(Exception):
+    """Base exception for all FauxShield SDK errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code from the API response, if applicable.
+        code: Machine-readable error code from the API.
+        request_id: Unique request identifier for support inquiries.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        attrs = [f"message={self.message!r}"]
+        if self.status_code is not None:
+            attrs.append(f"status_code={self.status_code}")
+        if self.code is not None:
+            attrs.append(f"code={self.code!r}")
+        if self.request_id is not None:
+            attrs.append(f"request_id={self.request_id!r}")
+        return f"{self.__class__.__name__}({', '.join(attrs)})"
+
+
+class AuthenticationError(FauxShieldError):
+    """Raised when the API key is invalid or missing (HTTP 401)."""
+
+    def __init__(
+        self,
+        message: str = "Invalid or missing API key",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=401,
+            code=code or "authentication_error",
+            request_id=request_id,
+        )
+
+
+class AuthorizationError(FauxShieldError):
+    """Raised when the API key lacks permission for the operation (HTTP 403)."""
+
+    def __init__(
+        self,
+        message: str = "Insufficient permissions for this operation",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=403,
+            code=code or "authorization_error",
+            request_id=request_id,
+        )
+
+
+class ValidationError(FauxShieldError):
+    """Raised when request parameters fail validation (HTTP 400/422).
+
+    Attributes:
+        fields: List of field-level validation errors from the API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Request validation failed",
+        fields: Optional[List[Dict[str, Any]]] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=422,
+            code=code or "validation_error",
+            request_id=request_id,
+        )
+        self.fields: List[Dict[str, Any]] = fields or []
+
+    def __repr__(self) -> str:
+        base = super().__repr__()
+        return f"{base[:-1]}, fields={self.fields!r})"
+
+
+class NotFoundError(FauxShieldError):
+    """Raised when the requested resource does not exist (HTTP 404)."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=404,
+            code=code or "not_found",
+            request_id=request_id,
+        )
+
+
+class RateLimitError(FauxShieldError):
+    """Raised when the rate limit has been exceeded (HTTP 429).
+
+    Attributes:
+        retry_after: Number of seconds to wait before retrying.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=429,
+            code=code or "rate_limit_exceeded",
+            request_id=request_id,
+        )
+        self.retry_after: Optional[float] = retry_after
+
+    def __repr__(self) -> str:
+        base = super().__repr__()
+        return f"{base[:-1]}, retry_after={self.retry_after})"
+
+
+class ConflictError(FauxShieldError):
+    """Raised when the request conflicts with existing state (HTTP 409)."""
+
+    def __init__(
+        self,
+        message: str = "Request conflicts with current state",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=409,
+            code=code or "conflict",
+            request_id=request_id,
+        )
+
+
+class ServiceUnavailableError(FauxShieldError):
+    """Raised when the API is temporarily unavailable (HTTP 503)."""
+
+    def __init__(
+        self,
+        message: str = "Service temporarily unavailable",
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            status_code=503,
+            code=code or "service_unavailable",
+            request_id=request_id,
+        )