megaplan-sdk 0.1.0__py3-none-any.whl

megaplan_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""Megaplan Python SDK - Professional SDK for Megaplan API v3."""
+
+from megaplan_sdk.client import MegaplanClient
+from megaplan_sdk.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    MegaplanError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from megaplan_sdk.helpers import (
+    make_contractor_entity,
+    make_deal_entity,
+    make_employee_entity,
+    make_entity,
+    make_project_entity,
+    make_task_entity,
+)
+from megaplan_sdk.logging_config import setup_logging
+from megaplan_sdk.models.comment import Comment
+from megaplan_sdk.models.common import DateTime
+from megaplan_sdk.models.contractor import Contractor, ContractorCompany, ContractorHuman
+from megaplan_sdk.models.deal import Deal, DealFullDetails
+from megaplan_sdk.models.department import Department
+from megaplan_sdk.models.employee import Employee
+from megaplan_sdk.models.project import Project, ProjectFullDetails
+from megaplan_sdk.models.task import Task, TaskFullDetails
+
+__all__ = [
+    # Client
+    "MegaplanClient",
+    # Exceptions
+    "MegaplanError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    # Models
+    "Task",
+    "TaskFullDetails",
+    "Project",
+    "ProjectFullDetails",
+    "Deal",
+    "DealFullDetails",
+    "Comment",
+    "Contractor",
+    "ContractorCompany",
+    "ContractorHuman",
+    "Employee",
+    "Department",
+    "DateTime",
+    # Utils
+    "setup_logging",
+    # Helpers
+    "make_entity",
+    "make_employee_entity",
+    "make_project_entity",
+    "make_task_entity",
+    "make_deal_entity",
+    "make_contractor_entity",
+]
+
+__version__ = "0.1.0"

megaplan_sdk/auth.py

@@ -0,0 +1,185 @@
+"""OAuth2 authentication for Megaplan API."""
+
+import asyncio
+import json
+import time
+
+import httpx
+
+from megaplan_sdk.exceptions import AuthenticationError
+from megaplan_sdk.http_client import HTTPClient
+from megaplan_sdk.logging_config import logger
+from megaplan_sdk.types import AuthTokenResponse
+
+
+class AuthManager:
+    """Manages OAuth2 authentication and token lifecycle.
+
+    Handles token acquisition, refresh, and expiration tracking.
+    """
+
+    def __init__(self, http_client: HTTPClient) -> None:
+        """Initialize auth manager.
+
+        Args:
+            http_client: HTTP client for making requests.
+        """
+        self._http = http_client
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._expires_at: float | None = None
+        self._refresh_lock = asyncio.Lock()
+
+    async def authenticate(self, username: str, password: str) -> str:
+        """Authenticate with username and password.
+
+        Args:
+            username: User email or username.
+            password: User password.
+
+        Returns:
+            Access token.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """
+        logger.info(f"Authenticating user: {username}")
+
+        try:
+            response = await self._http.post_form(
+                f"{self._http.base_url}/api/v3/auth/access_token",
+                data={
+                    "username": username,
+                    "password": password,
+                    "grant_type": "password",
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            response.raise_for_status()
+            token_data: AuthTokenResponse = response.json()
+
+            self._access_token = token_data["access_token"]
+            self._refresh_token = token_data.get("refresh_token")
+            expires_in = token_data.get("expires_in", 172800)
+            self._expires_at = time.time() + expires_in
+
+            self._http.set_access_token(self._access_token)
+
+            logger.info(f"Authentication successful for user: {username}")
+
+            return self._access_token
+
+        except (httpx.HTTPError, httpx.TimeoutException, httpx.RequestError) as e:
+            logger.error(f"Authentication network error for {username}: {str(e)}")
+            raise AuthenticationError(f"Authentication failed: {str(e)}") from e
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.error(f"Authentication response parsing error for {username}: {str(e)}")
+            raise AuthenticationError(f"Invalid authentication response: {str(e)}") from e
+
+    async def refresh(self, refresh_token: str | None = None) -> str:
+        """Refresh access token.
+
+        Args:
+            refresh_token: Optional refresh token. Uses stored token if not provided.
+
+        Returns:
+            New access token.
+
+        Raises:
+            AuthenticationError: If refresh fails.
+        """
+        token = refresh_token or self._refresh_token
+        if not token:
+            logger.error("No refresh token available for token refresh")
+            raise AuthenticationError("No refresh token available")
+
+        logger.info("Refreshing access token")
+
+        try:
+            response = await self._http.post_form(
+                f"{self._http.base_url}/api/v3/auth/access_token",
+                data={
+                    "refresh_token": token,
+                    "grant_type": "refresh_token",
+                },
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+            )
+
+            response.raise_for_status()
+            token_data: AuthTokenResponse = response.json()
+
+            self._access_token = token_data["access_token"]
+            self._refresh_token = token_data.get("refresh_token")
+            expires_in = token_data.get("expires_in", 172800)
+            self._expires_at = time.time() + expires_in
+
+            self._http.set_access_token(self._access_token)
+
+            logger.info("Token refresh successful")
+
+            return self._access_token
+
+        except (httpx.HTTPError, httpx.TimeoutException, httpx.RequestError) as e:
+            logger.error(f"Token refresh network error: {str(e)}")
+            raise AuthenticationError(f"Token refresh failed: {str(e)}") from e
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.error(f"Token refresh response parsing error: {str(e)}")
+            raise AuthenticationError(f"Invalid token refresh response: {str(e)}") from e
+
+    def get_access_token(self) -> str | None:
+        """Get current access token.
+
+        Returns:
+            Access token or None if not authenticated.
+        """
+        return self._access_token
+
+    def is_token_expired(self, buffer_seconds: int = 60) -> bool:
+        """Check if token is expired or will expire soon.
+
+        Args:
+            buffer_seconds: Seconds before expiration to consider token expired.
+
+        Returns:
+            True if token is expired or will expire within buffer.
+        """
+        if not self._expires_at:
+            return True
+        return time.time() >= (self._expires_at - buffer_seconds)
+
+    async def ensure_authenticated(self, username: str, password: str) -> str:
+        """Ensure we have a valid access token.
+
+        Authenticates if needed or refreshes token if expired.
+        Uses lock to prevent race conditions when multiple requests
+        try to refresh token simultaneously.
+
+        Args:
+            username: Username for authentication.
+            password: Password for authentication.
+
+        Returns:
+            Valid access token.
+        """
+        if not self._access_token or self.is_token_expired():
+            async with self._refresh_lock:
+                # Double-check after acquiring lock
+                # Another coroutine might have already refreshed the token
+                if not self._access_token or self.is_token_expired():
+                    if self._refresh_token and not self.is_token_expired(buffer_seconds=3600):
+                        try:
+                            return await self.refresh()
+                        except AuthenticationError:
+                            pass
+
+                    return await self.authenticate(username, password)
+
+        return self._access_token
+
+    def clear_tokens(self) -> None:
+        """Clear stored tokens."""
+        self._access_token = None
+        self._refresh_token = None
+        self._expires_at = None
+        self._http.set_access_token(None)

megaplan_sdk/cache.py

@@ -0,0 +1,192 @@
+"""Entity caching system for Megaplan SDK."""
+
+from dataclasses import dataclass
+from time import time
+from typing import Any
+
+
+@dataclass
+class CacheEntry:
+    """Cache entry with data and expiration time.
+
+    Attributes:
+        data: Cached entity data (dict or model).
+        expires_at: Expiration timestamp (seconds since epoch).
+    """
+
+    data: Any
+    expires_at: float
+
+
+class EntityCache:
+    """LRU cache for entities with TTL.
+
+    Thread-safe cache with automatic expiration and size limits.
+    Uses (contentType, id) as key for entity storage.
+
+    Attributes:
+        max_size: Maximum number of entities to cache.
+        ttl: Time-to-live in seconds for cached entities.
+
+    Examples:
+        >>> cache = EntityCache(max_size=1000, ttl=300)
+        >>> cache.set("Employee", 123, {"id": 123, "name": "John"})
+        >>> data = cache.get("Employee", 123)
+        >>> print(data)
+        {'id': 123, 'name': 'John'}
+    """
+
+    def __init__(self, max_size: int = 1000, ttl: int = 300) -> None:
+        """Initialize entity cache.
+
+        Args:
+            max_size: Maximum cache size (default: 1000 entities).
+            ttl: Time-to-live in seconds (default: 300 = 5 minutes).
+        """
+        self._cache: dict[tuple[str, int], CacheEntry] = {}
+        self._max_size = max_size
+        self._ttl = ttl
+        self._access_order: list[tuple[str, int]] = []  # For LRU
+
+    def get(self, content_type: str, entity_id: int) -> Any | None:
+        """Get entity from cache if not expired.
+
+        Args:
+            content_type: Entity content type (e.g., "Employee").
+            entity_id: Entity identifier.
+
+        Returns:
+            Cached entity data or None if not found/expired.
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 123, {"name": "John"})
+            >>> data = cache.get("Employee", 123)
+            >>> print(data)
+            {'name': 'John'}
+        """
+        key = (content_type, entity_id)
+        entry = self._cache.get(key)
+
+        if entry is None:
+            return None
+
+        # Check expiration
+        if time() > entry.expires_at:
+            # Expired - remove from cache
+            self._cache.pop(key, None)
+            if key in self._access_order:
+                self._access_order.remove(key)
+            return None
+
+        # Update access order (LRU)
+        if key in self._access_order:
+            self._access_order.remove(key)
+        self._access_order.append(key)
+
+        return entry.data
+
+    def set(self, content_type: str, entity_id: int, data: Any) -> None:
+        """Add entity to cache with expiration.
+
+        Args:
+            content_type: Entity content type (e.g., "Employee").
+            entity_id: Entity identifier.
+            data: Entity data to cache.
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 123, {"id": 123, "name": "John"})
+        """
+        key = (content_type, entity_id)
+
+        # Evict oldest if at capacity
+        if len(self._cache) >= self._max_size and key not in self._cache:
+            if self._access_order:
+                oldest_key = self._access_order.pop(0)
+                self._cache.pop(oldest_key, None)
+
+        # Store entry
+        self._cache[key] = CacheEntry(
+            data=data,
+            expires_at=time() + self._ttl,
+        )
+
+        # Update access order
+        if key in self._access_order:
+            self._access_order.remove(key)
+        self._access_order.append(key)
+
+    def clear(self) -> None:
+        """Clear all cached entities.
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 1, {"id": 1})
+            >>> cache.clear()
+            >>> assert cache.get("Employee", 1) is None
+        """
+        self._cache.clear()
+        self._access_order.clear()
+
+    def clear_type(self, content_type: str) -> None:
+        """Clear cache for specific entity type.
+
+        Args:
+            content_type: Entity type to clear (e.g., "Employee").
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 1, {"id": 1})
+            >>> cache.set("Task", 2, {"id": 2})
+            >>> cache.clear_type("Employee")
+            >>> assert cache.get("Employee", 1) is None
+            >>> assert cache.get("Task", 2) is not None
+        """
+        keys_to_remove = [key for key in self._cache.keys() if key[0] == content_type]
+
+        for key in keys_to_remove:
+            self._cache.pop(key, None)
+            if key in self._access_order:
+                self._access_order.remove(key)
+
+    def size(self) -> int:
+        """Get current cache size.
+
+        Returns:
+            Number of cached entities.
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 1, {"id": 1})
+            >>> cache.set("Employee", 2, {"id": 2})
+            >>> assert cache.size() == 2
+        """
+        return len(self._cache)
+
+    def stats(self) -> dict[str, Any]:
+        """Get cache statistics.
+
+        Returns:
+            Dict with cache stats (size, types, etc.).
+
+        Examples:
+            >>> cache = EntityCache()
+            >>> cache.set("Employee", 1, {"id": 1})
+            >>> cache.set("Task", 2, {"id": 2})
+            >>> stats = cache.stats()
+            >>> print(stats["size"])
+            2
+            >>> print(stats["types"])
+            {'Employee': 1, 'Task': 1}
+        """
+        type_counts: dict[str, int] = {}
+        for content_type, _ in self._cache.keys():
+            type_counts[content_type] = type_counts.get(content_type, 0) + 1
+
+        return {
+            "size": len(self._cache),
+            "max_size": self._max_size,
+            "ttl": self._ttl,
+            "types": type_counts,
+        }

megaplan_sdk/client.py

@@ -0,0 +1,201 @@
+"""Main client for Megaplan SDK."""
+
+from types import TracebackType
+
+from megaplan_sdk.auth import AuthManager
+from megaplan_sdk.cache import EntityCache
+from megaplan_sdk.http_client import HTTPClient
+from megaplan_sdk.logging_config import logger, setup_logging
+from megaplan_sdk.resources.auth import AuthResource
+from megaplan_sdk.resources.comments import CommentsResource
+from megaplan_sdk.resources.contractors import ContractorsResource
+from megaplan_sdk.resources.deals import DealsResource
+from megaplan_sdk.resources.departments import DepartmentsResource
+from megaplan_sdk.resources.employees import EmployeesResource
+from megaplan_sdk.resources.projects import ProjectsResource
+from megaplan_sdk.resources.tasks import TasksResource
+
+
+class MegaplanClient:
+    """Main client for Megaplan API.
+
+    Coordinates all resources and handles authentication.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        access_token: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        allow_http: bool = False,
+        log_level: str = "WARNING",
+        enable_cache: bool = True,
+        cache_ttl: int = 300,
+        cache_max_size: int = 1000,
+        default_comments_limit: int | None = None,
+        default_history_limit: int | None = None,
+    ) -> None:
+        """Initialize Megaplan client.
+
+        Args:
+            base_url: Base URL for Megaplan API (e.g., https://example.megaplan.ru).
+            username: Username for authentication (optional if access_token provided).
+            password: Password for authentication (optional if access_token provided).
+                Note: Password is NOT stored in memory for security reasons.
+            access_token: Pre-obtained access token (optional).
+            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).
+            log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            enable_cache: Enable entity caching (default: True).
+            cache_ttl: Cache time-to-live in seconds (default: 300 = 5 minutes).
+            cache_max_size: Maximum number of cached entities (default: 1000).
+            default_comments_limit: Default limit for comments in get_full_details().
+                None = use Megaplan API default (no explicit limit).
+                This value is used only if comments_limit is not specified in method call.
+            default_history_limit: Default limit for history in get_full_details().
+                None = use Megaplan API default (no explicit limit).
+                This value is used only if history_limit is not specified in method call.
+
+        Security Note:
+            For production use, it's recommended to use refresh tokens or pre-obtained
+            access_token instead of username/password authentication.
+        """
+        # Setup logging
+        setup_logging(log_level)
+        logger.info(f"Initializing MegaplanClient for {base_url}")
+
+        self.base_url = base_url
+        self.username = username
+        # Security: Do NOT store password in plain text
+        self._http = HTTPClient(
+            base_url,
+            access_token=access_token,
+            timeout=timeout,
+            max_retries=max_retries,
+            allow_http=allow_http,
+        )
+        self._auth_manager = AuthManager(self._http)
+
+        # Initialize entity cache
+        self._cache = EntityCache(max_size=cache_max_size, ttl=cache_ttl) if enable_cache else None
+        if self._cache:
+            logger.debug(f"Entity cache enabled (max_size={cache_max_size}, ttl={cache_ttl}s)")
+
+        if access_token:
+            self._auth_manager._access_token = access_token
+            self._auth_manager._expires_at = None
+            logger.debug("MegaplanClient initialized with access_token")
+
+        self.auth = AuthResource(self._http, cache=self._cache)
+        self.tasks = TasksResource(
+            self._http,
+            cache=self._cache,
+            default_comments_limit=default_comments_limit,
+            default_history_limit=default_history_limit,
+        )
+        self.projects = ProjectsResource(
+            self._http,
+            cache=self._cache,
+            default_comments_limit=default_comments_limit,
+            default_history_limit=default_history_limit,
+        )
+        self.deals = DealsResource(
+            self._http,
+            cache=self._cache,
+            default_comments_limit=default_comments_limit,
+            default_history_limit=default_history_limit,
+        )
+        self.comments = CommentsResource(self._http, cache=self._cache)
+        self.contractors = ContractorsResource(self._http, cache=self._cache)
+        self.employees = EmployeesResource(self._http, cache=self._cache)
+        self.departments = DepartmentsResource(self._http, cache=self._cache)
+
+        # Security: Store password only for initial authentication if provided
+        self._initial_password = password if (username and password) else None
+        if self._initial_password:
+            logger.debug("MegaplanClient initialized with username/password")
+
+    async def __aenter__(self) -> "MegaplanClient":
+        """Async context manager entry."""
+        logger.debug("Entering MegaplanClient context")
+        await self._http._ensure_client()
+
+        # Perform initial authentication if credentials provided
+        if self._initial_password and self.username:
+            await self._auth_manager.authenticate(self.username, self._initial_password)
+            # Clear password from memory after first use
+            self._initial_password = None
+
+        logger.debug("MegaplanClient context ready")
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def authenticate(self, username: str, password: str) -> str:
+        """Manually authenticate with username and password.
+
+        Args:
+            username: User email or username.
+            password: User password.
+
+        Returns:
+            Access token.
+
+        Note:
+            For security, password is not stored. Use refresh tokens for
+            subsequent authentications.
+        """
+        return await self._auth_manager.authenticate(username, password)
+
+    async def close(self) -> None:
+        """Close client and cleanup resources."""
+        logger.debug("Closing MegaplanClient")
+        await self._http.close()
+        logger.debug("MegaplanClient closed")
+
+    def set_access_token(self, access_token: str) -> None:
+        """Set access token manually.
+
+        Args:
+            access_token: OAuth2 access token.
+        """
+        self._http.set_access_token(access_token)
+        self._auth_manager._access_token = access_token
+
+    def clear_cache(self) -> None:
+        """Clear all cached entities.
+
+        Examples:
+            >>> async with MegaplanClient(...) as client:
+            ...     await client.tasks.list()  # Caches employees
+            ...     client.clear_cache()  # Clear all cache
+        """
+        if self._cache:
+            self._cache.clear()
+            logger.debug("Entity cache cleared")
+
+    def clear_cache_type(self, content_type: str) -> None:
+        """Clear cache for specific entity type.
+
+        Args:
+            content_type: Entity type to clear (e.g., "Employee", "Contractor").
+
+        Examples:
+            >>> async with MegaplanClient(...) as client:
+            ...     await client.employees.list()  # Caches employees
+            ...     client.clear_cache_type("Employee")  # Clear only employees
+        """
+        if self._cache:
+            self._cache.clear_type(content_type)
+            logger.debug(f"Entity cache cleared for type: {content_type}")

megaplan_sdk/constants.py

@@ -0,0 +1,16 @@
+"""Constants for Megaplan SDK."""
+
+
+class ContentType:
+    """Content type constants for Megaplan API entities."""
+
+    TASK = "Task"
+    PROJECT = "Project"
+    DEAL = "Deal"
+    EMPLOYEE = "Employee"
+    CONTRACTOR = "Contractor"
+    CONTRACTOR_COMPANY = "ContractorCompany"
+    CONTRACTOR_HUMAN = "ContractorHuman"
+    CONTRACTOR_CATEGORY = "ContractorCategory"
+    DEPARTMENT = "Department"
+    COMMENT = "Comment"