megaplan-sdk 0.1.0__py3-none-any.whl

megaplan_sdk/exceptions.py

@@ -0,0 +1,180 @@
+"""Custom exceptions for Megaplan SDK."""
+
+from typing import Any
+
+
+class MegaplanError(Exception):
+    """Base exception for all Megaplan SDK errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code if available.
+        errors: List of error details from API response.
+        response: Full API response if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize MegaplanError.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code.
+            errors: List of error details.
+            response: Full API response.
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.errors = errors or []
+        self.response = response
+
+    def __str__(self) -> str:
+        """Return string representation of error."""
+        if self.status_code:
+            return f"{self.message} (HTTP {self.status_code})"
+        return self.message
+
+
+class AuthenticationError(MegaplanError):
+    """Raised when authentication fails (401).
+
+    Typically occurs when credentials are invalid or token has expired.
+    """
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize AuthenticationError."""
+        super().__init__(message, status_code=401, errors=errors, response=response)
+
+
+class AuthorizationError(MegaplanError):
+    """Raised when authorization fails (403).
+
+    Occurs when user doesn't have permission to access the resource.
+    """
+
+    def __init__(
+        self,
+        message: str = "Authorization failed",
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize AuthorizationError."""
+        super().__init__(message, status_code=403, errors=errors, response=response)
+
+
+class NotFoundError(MegaplanError):
+    """Raised when resource is not found (404)."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize NotFoundError."""
+        super().__init__(message, status_code=404, errors=errors, response=response)
+
+
+class ValidationError(MegaplanError):
+    """Raised when request validation fails (422).
+
+    Contains detailed validation errors from API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Validation failed",
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize ValidationError."""
+        super().__init__(message, status_code=422, errors=errors, response=response)
+
+
+class RateLimitError(MegaplanError):
+    """Raised when rate limit is exceeded (429)."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize RateLimitError."""
+        super().__init__(message, status_code=429, errors=errors, response=response)
+
+
+class ServerError(MegaplanError):
+    """Raised when server returns 5xx error."""
+
+    def __init__(
+        self,
+        message: str = "Server error",
+        status_code: int = 500,
+        errors: list[dict[str, Any]] | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize ServerError."""
+        super().__init__(message, status_code=status_code, errors=errors, response=response)
+
+
+def raise_for_status(
+    status_code: int,
+    response: dict[str, Any],
+    default_message: str = "Request failed",
+) -> None:
+    """Raise appropriate exception based on HTTP status code.
+
+    Args:
+        status_code: HTTP status code.
+        response: API response dictionary.
+        default_message: Default error message.
+
+    Raises:
+        AuthenticationError: For 401 status.
+        AuthorizationError: For 403 status.
+        NotFoundError: For 404 status.
+        ValidationError: For 422 status.
+        RateLimitError: For 429 status.
+        ServerError: For 5xx status.
+        MegaplanError: For other error status codes.
+    """
+    meta = response.get("meta", {})
+    errors = meta.get("errors", [])
+    error_message = default_message
+
+    if errors and isinstance(errors, list) and len(errors) > 0:
+        first_error = errors[0]
+        if isinstance(first_error, dict) and "message" in first_error:
+            error_message = first_error["message"]
+
+    if status_code == 401:
+        raise AuthenticationError(error_message, errors=errors, response=response)
+    elif status_code == 403:
+        raise AuthorizationError(error_message, errors=errors, response=response)
+    elif status_code == 404:
+        raise NotFoundError(error_message, errors=errors, response=response)
+    elif status_code == 422:
+        raise ValidationError(error_message, errors=errors, response=response)
+    elif status_code == 429:
+        raise RateLimitError(error_message, errors=errors, response=response)
+    elif 500 <= status_code < 600:
+        raise ServerError(error_message, status_code=status_code, errors=errors, response=response)
+    else:
+        raise MegaplanError(
+            error_message,
+            status_code=status_code,
+            errors=errors,
+            response=response,
+        )

megaplan_sdk/helpers.py

@@ -0,0 +1,108 @@
+"""Helper functions for working with Megaplan SDK.
+
+Provides convenience functions for creating BaseEntity objects and simplifying
+common operations.
+"""
+
+from typing import Any
+
+from megaplan_sdk.constants import ContentType
+
+
+def make_entity(content_type: str, entity_id: int) -> dict[str, Any]:
+    """Create a BaseEntity reference dictionary.
+
+    Args:
+        content_type: Entity content type (e.g., "Employee", "Project", "Task").
+        entity_id: Entity identifier.
+
+    Returns:
+        Dictionary representing a BaseEntity reference.
+
+    Examples:
+        >>> make_entity("Employee", 123)
+        {"contentType": "Employee", "id": 123}
+        >>> make_entity("Project", 456)
+        {"contentType": "Project", "id": 456}
+    """
+    return {"contentType": content_type, "id": entity_id}
+
+
+def make_employee_entity(employee_id: int) -> dict[str, Any]:
+    """Create an Employee BaseEntity reference.
+
+    Args:
+        employee_id: Employee identifier.
+
+    Returns:
+        Dictionary representing an Employee reference.
+
+    Examples:
+        >>> make_employee_entity(123)
+        {"contentType": "Employee", "id": 123}
+    """
+    return make_entity(ContentType.EMPLOYEE, employee_id)
+
+
+def make_project_entity(project_id: int) -> dict[str, Any]:
+    """Create a Project BaseEntity reference.
+
+    Args:
+        project_id: Project identifier.
+
+    Returns:
+        Dictionary representing a Project reference.
+
+    Examples:
+        >>> make_project_entity(456)
+        {"contentType": "Project", "id": 456}
+    """
+    return make_entity(ContentType.PROJECT, project_id)
+
+
+def make_task_entity(task_id: int) -> dict[str, Any]:
+    """Create a Task BaseEntity reference.
+
+    Args:
+        task_id: Task identifier.
+
+    Returns:
+        Dictionary representing a Task reference.
+
+    Examples:
+        >>> make_task_entity(789)
+        {"contentType": "Task", "id": 789}
+    """
+    return make_entity(ContentType.TASK, task_id)
+
+
+def make_deal_entity(deal_id: int) -> dict[str, Any]:
+    """Create a Deal BaseEntity reference.
+
+    Args:
+        deal_id: Deal identifier.
+
+    Returns:
+        Dictionary representing a Deal reference.
+
+    Examples:
+        >>> make_deal_entity(101)
+        {"contentType": "Deal", "id": 101}
+    """
+    return make_entity(ContentType.DEAL, deal_id)
+
+
+def make_contractor_entity(contractor_id: int) -> dict[str, Any]:
+    """Create a Contractor BaseEntity reference.
+
+    Args:
+        contractor_id: Contractor identifier.
+
+    Returns:
+        Dictionary representing a Contractor reference.
+
+    Examples:
+        >>> make_contractor_entity(202)
+        {"contentType": "Contractor", "id": 202}
+    """
+    return make_entity(ContentType.CONTRACTOR, contractor_id)

megaplan_sdk/http_client.py

@@ -0,0 +1,390 @@
+"""HTTP client for Megaplan API."""
+
+import asyncio
+import json
+from typing import Any
+
+import httpx
+
+from megaplan_sdk.exceptions import raise_for_status
+from megaplan_sdk.logging_config import logger, sanitize_dict
+
+
+class HTTPClient:
+    """HTTP client with authentication, retry logic, and response validation.
+
+    Handles:
+    - Automatic access token injection
+    - JSON parameters in query string
+    - Retry logic with exponential backoff
+    - Response validation
+    - Error handling
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        access_token: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        allow_http: bool = False,
+    ) -> None:
+        """Initialize HTTP client.
+
+        Args:
+            base_url: Base URL for Megaplan API (e.g., https://example.megaplan.ru).
+            access_token: Optional access token for authentication.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retry attempts for 5xx errors.
+            allow_http: Allow HTTP connections (insecure, only for dev/test).
+
+        Raises:
+            ValueError: If base_url is not HTTPS and allow_http is False.
+        """
+        # Security: Validate HTTPS URL
+        if not base_url.startswith("https://") and not allow_http:
+            raise ValueError(
+                f"Only HTTPS URLs are allowed for security. Got: {base_url}. "
+                f"Use allow_http=True only for development/testing."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.access_token = access_token
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "HTTPClient":
+        """Async context manager entry."""
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def _ensure_client(self) -> None:
+        """Ensure HTTP client is initialized."""
+        if self._client is None:
+            # Configure connection pooling for better performance
+            limits = httpx.Limits(
+                max_connections=100,  # Maximum total connections
+                max_keepalive_connections=20,  # Keep 20 connections alive
+                keepalive_expiry=30.0,  # Keep connections alive for 30 seconds
+            )
+
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers={"Content-Type": "application/json"},
+                limits=limits,
+                follow_redirects=True,  # Follow redirects automatically
+            )
+
+    async def close(self) -> None:
+        """Close HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    def set_access_token(self, access_token: str | None) -> None:
+        """Set access token for authentication.
+
+        Args:
+            access_token: OAuth2 access token (or None to clear).
+        """
+        self.access_token = access_token
+
+    def _build_url(self, path: str, params: dict[str, Any] | None = None) -> str:
+        """Build URL with JSON parameters in query string.
+
+        Megaplan API expects JSON parameters in query string format:
+        /api/v3/task?{"limit":5}
+
+        Args:
+            path: API path (e.g., /api/v3/task).
+            params: Query parameters as dictionary.
+
+        Returns:
+            Full URL with query string.
+        """
+        url = f"{self.base_url}{path}"
+
+        if params:
+            params_json = json.dumps(params, ensure_ascii=False)
+            url = f"{url}?{params_json}"
+
+        return url
+
+    def _build_headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+        """Build request headers with authentication.
+
+        Args:
+            extra_headers: Additional headers to include.
+
+        Returns:
+            Headers dictionary.
+        """
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+
+        if self.access_token:
+            headers["Authorization"] = f"Bearer {self.access_token}"
+
+        if extra_headers:
+            headers.update(extra_headers)
+
+        return headers
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE, etc.).
+            path: API path.
+            params: Query parameters.
+            json_data: JSON body data.
+            files: Files for multipart/form-data.
+            headers: Additional headers.
+
+        Returns:
+            Response JSON as dictionary.
+
+        Raises:
+            MegaplanError: For various error conditions.
+        """
+        await self._ensure_client()
+        assert self._client is not None  # For mypy: ensured by _ensure_client()
+
+        url = self._build_url(path, params)
+        request_headers = self._build_headers(headers)
+
+        if files:
+            request_headers.pop("Content-Type", None)
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                # LOG REQUEST
+                logger.debug(
+                    f"Making {method} request to {path}",
+                    extra={
+                        "method": method,
+                        "path": path,
+                        "params": sanitize_dict(params) if params else None,
+                        "attempt": attempt + 1,
+                    },
+                )
+
+                response = await self._client.request(
+                    method=method,
+                    url=url,
+                    headers=request_headers,
+                    json=json_data,
+                    files=files,
+                )
+
+                response.raise_for_status()
+                response_data: dict[str, Any] = response.json()
+
+                meta = response_data.get("meta", {})
+                status = meta.get("status", response.status_code)
+
+                if status != 200:
+                    raise_for_status(status, response_data)
+
+                # LOG SUCCESS
+                logger.debug(
+                    f"{method} {path} succeeded",
+                    extra={"status_code": response.status_code, "attempt": attempt + 1},
+                )
+
+                return response_data
+
+            except httpx.HTTPStatusError as e:
+                status_code = e.response.status_code
+
+                # LOG HTTP ERROR
+                logger.warning(
+                    f"HTTP error {status_code} on {method} {path}",
+                    extra={"status_code": status_code, "attempt": attempt + 1},
+                )
+
+                # Handle 429 Rate Limit
+                if status_code == 429:
+                    retry_after = e.response.headers.get("Retry-After", "60")
+                    try:
+                        wait_time = int(retry_after)
+                    except ValueError:
+                        # Retry-After might be a date string, default to 60s
+                        wait_time = 60
+
+                    logger.warning(
+                        f"Rate limit exceeded (429). Retry after {wait_time}s",
+                        extra={"wait_time": wait_time, "attempt": attempt + 1},
+                    )
+
+                    if attempt < self.max_retries:
+                        await asyncio.sleep(wait_time)
+                        continue
+
+                # Handle 5xx Server Errors
+                if 500 <= status_code < 600 and attempt < self.max_retries:
+                    # Check Retry-After header
+                    retry_after_header = e.response.headers.get("Retry-After")
+                    if retry_after_header:
+                        try:
+                            wait_time = int(retry_after_header)
+                        except ValueError:
+                            wait_time = 2**attempt
+                    else:
+                        wait_time = 2**attempt
+
+                    logger.info(
+                        f"Retrying after {wait_time}s (attempt {attempt + 1}/{self.max_retries})",
+                        extra={"wait_time": wait_time, "attempt": attempt + 1},
+                    )
+                    await asyncio.sleep(wait_time)
+                    continue
+
+                # Parse error response
+                response_data = {}
+                if e.response:
+                    try:
+                        response_data = e.response.json()
+                    except json.JSONDecodeError:
+                        logger.warning("Failed to parse error response as JSON")
+                        response_data = {"meta": {"errors": [{"message": e.response.text[:200]}]}}
+
+                raise_for_status(status_code, response_data)
+
+            except httpx.RequestError as e:
+                # LOG REQUEST ERROR
+                logger.warning(
+                    f"Request error on {method} {path}: {str(e)}",
+                    extra={"error_type": type(e).__name__, "attempt": attempt + 1},
+                )
+
+                if attempt < self.max_retries:
+                    wait_time = 2**attempt
+                    logger.info(
+                        f"Retrying after {wait_time}s (attempt {attempt + 1}/{self.max_retries})",
+                        extra={"wait_time": wait_time, "attempt": attempt + 1},
+                    )
+                    await asyncio.sleep(wait_time)
+                    continue
+                raise
+
+        # Note: This point is never reached because:
+        # - Success case returns via 'return response_data'
+        # - Error cases either raise immediately or continue retrying
+        # - After max retries, exceptions are re-raised above
+        raise RuntimeError("Unexpected error in request")
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make GET request.
+
+        Args:
+            path: API path.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Response JSON as dictionary.
+        """
+        return await self._request("GET", path, params=params, headers=headers)
+
+    async def post(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make POST request.
+
+        Args:
+            path: API path.
+            json_data: JSON body data.
+            files: Files for multipart/form-data.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Response JSON as dictionary.
+        """
+        return await self._request(
+            "POST", path, json_data=json_data, files=files, params=params, headers=headers
+        )
+
+    async def put(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make PUT request.
+
+        Args:
+            path: API path.
+            json_data: JSON body data.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Response JSON as dictionary.
+        """
+        return await self._request("PUT", path, json_data=json_data, params=params, headers=headers)
+
+    async def delete(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Make DELETE request.
+
+        Args:
+            path: API path.
+            params: Query parameters.
+            headers: Additional headers.
+
+        Returns:
+            Response JSON as dictionary.
+        """
+        return await self._request("DELETE", path, params=params, headers=headers)
+
+    async def post_form(
+        self,
+        url: str,
+        data: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Make POST request with form data (for auth).
+
+        This is a public method for authentication that doesn't require a token.
+
+        Args:
+            url: Full URL (not just path).
+            data: Form data dictionary.
+            headers: Optional headers.
+
+        Returns:
+            Raw httpx Response object.
+        """
+        await self._ensure_client()
+        assert self._client is not None  # For mypy: ensured by _ensure_client()
+        return await self._client.post(url, data=data, headers=headers)