megaplan-sdk 0.1.0__py3-none-any.whl

megaplan_sdk/resources/employees.py

@@ -0,0 +1,216 @@
+"""Employees resource for Megaplan API."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from megaplan_sdk.constants import ContentType
+from megaplan_sdk.models.employee import Employee
+from megaplan_sdk.resources.base import BaseResource
+
+
+class EmployeesResource(BaseResource):
+    """Resource for working with employees."""
+
+    async def create(self, employee_data: dict[str, Any]) -> Employee:
+        """Create a new employee.
+
+        Args:
+            employee_data: Employee data dictionary.
+                Required: email, firstName, lastName
+                Optional: phone, position, department, etc.
+
+        Returns:
+            Created employee.
+
+        Examples:
+            >>> employee_data = {
+            ...     "email": "user@example.com",
+            ...     "firstName": "John",
+            ...     "lastName": "Doe",
+            ...     "position": "Developer"
+            ... }
+            >>> employee = await client.employees.create(employee_data)
+        """
+        return await self._create_entity("employee", employee_data, Employee)
+
+    async def list(
+        self,
+        q: str | None = None,
+        department_id: int | None = None,
+        status: str | None = None,
+        limit: int | None = None,
+        page_after: dict[str, Any] | None = None,
+        page_before: dict[str, Any] | None = None,
+        page_with: dict[str, Any] | None = None,
+        fields: Any | None = None,
+        sort_by: list[dict[str, str]] | None = None,
+        only_requested_fields: bool | None = None,
+        expand: list[str] | None = None,
+    ) -> list[Employee]:
+        """Get list of employees.
+
+        Args:
+            q: Search query (name, email, phone).
+                NOTE: Search may not work properly in Megaplan API,
+                use exact email for best results.
+            department_id: Filter by department ID.
+            status: Filter by status (active, fired, etc.).
+            limit: Number of items per page.
+            page_after: Load page starting from this entity.
+            page_before: Load page strictly before this entity.
+            page_with: Load page containing this entity.
+            fields: Additional fields to include.
+            sort_by: Sort fields.
+            only_requested_fields: Return only requested fields.
+            expand: List of fields to expand (e.g., ["department", "manager"]).
+                Supported values: "department", "manager".
+                Note: When expand is provided, department and manager fields will be
+                replaced with full Department/Employee objects instead of BaseEntity.
+
+        Returns:
+            List of employees (with expanded fields if requested).
+
+        Examples:
+            >>> # Get all active employees
+            >>> employees = await client.employees.list(status="active")
+            >>>
+            >>> # Get employees with expanded department
+            >>> employees = await client.employees.list(
+            ...     limit=10, expand=["department", "manager"]
+            ... )
+            >>> for employee in employees:
+            ...     if employee.department and hasattr(employee.department, 'name'):
+            ...         print(f"{employee.display_name()} - {employee.department.name}")
+        """
+        path = self._build_path("api", "v3", "employee")
+
+        # Prepare employee-specific parameters
+        extra_params: dict[str, Any] = {}
+        if q:
+            extra_params["q"] = q
+        if department_id:
+            extra_params["department"] = {
+                "id": department_id,
+                "contentType": ContentType.DEPARTMENT,
+            }
+        if status:
+            extra_params["status"] = status
+
+        # Use base method to build params (DRY)
+        params = self._build_list_params(
+            limit=limit,
+            page_after=page_after,
+            page_before=page_before,
+            page_with=page_with,
+            fields=fields,
+            sort_by=sort_by,
+            only_requested_fields=only_requested_fields,
+            **extra_params,
+        )
+
+        # 1. Fetch employees
+        employees = await self._get_list(path, Employee, params)
+
+        # 2. If no expand, return as is
+        if not expand or not employees:
+            return employees
+
+        # 3. Batch load related entities
+        from megaplan_sdk.models.department import Department
+
+        expand_config: dict[str, tuple[str, type, str]] = {
+            "department": ("department", Department, ContentType.DEPARTMENT),
+            "manager": ("employee", Employee, ContentType.EMPLOYEE),
+        }
+
+        expanded = await self._expand_list_entities(employees, expand, expand_config)
+        department_map = expanded.get("department", {})
+        manager_map = expanded.get("manager", {})
+
+        # 4. Replace BaseEntity references with full objects
+        for employee in employees:
+            if employee.department and employee.department.id in department_map:
+                employee.department = department_map[employee.department.id]
+
+            if employee.manager and employee.manager.id in manager_map:
+                employee.manager = manager_map[employee.manager.id]
+
+        return employees
+
+    async def get(self, employee_id: int) -> Employee:
+        """Get employee by ID.
+
+        Args:
+            employee_id: Employee identifier.
+
+        Returns:
+            Employee details.
+        """
+        return await self._get_entity("employee", employee_id, Employee)
+
+    async def update(self, employee_id: int, employee_data: dict[str, Any]) -> Employee:
+        """Update employee.
+
+        Args:
+            employee_id: Employee identifier.
+            employee_data: Updated employee data.
+
+        Returns:
+            Updated employee.
+        """
+        return await self._update_entity("employee", employee_id, employee_data, Employee)
+
+    async def delete(self, employee_id: int) -> None:
+        """Delete employee.
+
+        Args:
+            employee_id: Employee identifier.
+        """
+        await self._delete_entity("employee", employee_id)
+
+    async def get_current(self) -> Employee:
+        """Get current authenticated employee.
+
+        Returns:
+            Current employee details.
+
+        Examples:
+            >>> me = await client.employees.get_current()
+            >>> print(f"Logged in as: {me.email}")
+
+        Note:
+            Uses /api/v3/currentUser endpoint which returns Employee or ContractorHuman.
+            For ContractorHuman users, some fields may be None.
+        """
+        path = self._build_path("api", "v3", "currentUser")
+        response = await self._http.get(path)
+        return Employee(**response["data"])
+
+    async def iterate(
+        self,
+        limit: int = 100,
+        **kwargs: Any,
+    ) -> AsyncIterator[Employee]:
+        """Iterate over all employees with automatic pagination.
+
+        Args:
+            limit: Number of items per page.
+            **kwargs: Additional parameters to pass to list().
+
+        Yields:
+            Employee objects.
+
+        Examples:
+            >>> async for employee in client.employees.iterate(status="active"):
+            ...     print(f"{employee.first_name} {employee.last_name}")
+        """
+        employee: Employee
+        async for employee in self._iterate_generic(  # type: ignore[valid-type]
+            ContentType.EMPLOYEE,
+            self.list,
+            limit,
+            **kwargs,
+        ):
+            yield employee

megaplan_sdk/resources/full_details.py

@@ -0,0 +1,143 @@
+"""FullDetailsMixin for unified get_full_details implementation."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from megaplan_sdk.resources.base import BaseResource
+
+
+@dataclass
+class RelatedDataConfig:
+    """Configuration for related data loading in get_full_details.
+
+    Attributes:
+        field_name: Name of the field in FullDetails model (e.g., "sub_tasks").
+        include_flag: Name of the include_* parameter (e.g., "include_sub_tasks").
+        fetch_method: Name of the method to call for loading (e.g., "get_sub_tasks").
+            If None, entity_field and entity_type must be provided for entity loading.
+        entity_field: Name of the field in main entity to check (e.g., "responsible").
+            Used when fetch_method is None.
+        entity_type: Entity type for _get_entity_cached (e.g., "employee", "contractor").
+            Used when fetch_method is None.
+        limit_param: Name of the limit parameter in kwargs (e.g., "comments_limit").
+        fetch_args: Additional arguments to pass to fetch_method.
+        custom_fetcher: Custom async method to fetch data.
+            Bound method that takes (entity_id, **kwargs) and returns coroutine.
+    """
+
+    field_name: str
+    include_flag: str
+    fetch_method: str | None = None
+    entity_field: str | None = None
+    entity_type: str | None = None
+    limit_param: str | None = None
+    fetch_args: dict[str, Any] | None = None
+    custom_fetcher: Callable[..., Awaitable[Any]] | None = None
+
+
+class FullDetailsMixin:
+    """Mixin for implementing get_full_details with configurable related data loading."""
+
+    async def _get_full_details_generic(
+        self: BaseResource,
+        entity_id: int,
+        entity_getter: str,
+        full_details_class: type[BaseModel],
+        config: list[RelatedDataConfig],
+        main_entity_field: str,
+        **kwargs: Any,
+    ) -> BaseModel:
+        """Generic implementation of get_full_details.
+
+        Args:
+            entity_id: Identifier of the main entity.
+            entity_getter: Name of the method to get main entity (e.g., "get").
+            full_details_class: FullDetails model class to instantiate.
+            config: List of RelatedDataConfig for supported related data.
+            main_entity_field: Name of the field in FullDetails for main entity
+                (e.g., "task", "project", "deal").
+            **kwargs: Parameters from get_full_details call.
+
+        Returns:
+            Instance of full_details_class with all requested data.
+        """
+        # Get main entity
+        getter = getattr(self, entity_getter)
+        main_entity = await getter(entity_id)
+
+        # Apply global defaults for limit parameters if not explicitly provided
+        # Note: parameters are always in kwargs (even if None), so check value instead of presence
+        if hasattr(self, "_default_comments_limit") and kwargs.get("comments_limit") is None:
+            if self._default_comments_limit is not None:
+                kwargs["comments_limit"] = self._default_comments_limit
+
+        if hasattr(self, "_default_history_limit") and kwargs.get("history_limit") is None:
+            if self._default_history_limit is not None:
+                kwargs["history_limit"] = self._default_history_limit
+
+        # Prepare parallel tasks
+        tasks: dict[str, Any] = {}
+
+        for item_config in config:
+            include_value = kwargs.get(item_config.include_flag, False)
+            if not include_value:
+                continue
+
+            # Handle custom fetcher
+            if item_config.custom_fetcher:
+                # custom_fetcher is a bound method, call it with entity_id and kwargs
+                tasks[item_config.field_name] = item_config.custom_fetcher(entity_id, **kwargs)
+                continue
+
+            # Handle entity loading (responsible, owner, contractor)
+            if item_config.fetch_method is None:
+                if item_config.entity_field and item_config.entity_type:
+                    entity_ref = getattr(main_entity, item_config.entity_field, None)
+                    if entity_ref and hasattr(entity_ref, "id"):
+                        # Import model class based on entity_type
+                        if item_config.entity_type == "employee":
+                            from megaplan_sdk.models.employee import Employee
+
+                            model_class = Employee
+                        elif item_config.entity_type == "contractor":
+                            from megaplan_sdk.models.contractor import Contractor
+
+                            model_class = Contractor
+                        else:
+                            continue
+
+                        tasks[item_config.field_name] = self._get_entity_cached(
+                            item_config.entity_type, entity_ref.id, model_class
+                        )
+                continue
+
+            # Handle method-based loading (lists, etc.)
+            fetch_method = getattr(self, item_config.fetch_method)
+            fetch_kwargs: dict[str, Any] = {}
+
+            # Add entity_id as first positional argument
+            # Methods like get_sub_tasks(task_id, ...) or get_comments(deal_id, ...)
+            if item_config.limit_param and item_config.limit_param in kwargs:
+                fetch_kwargs["limit"] = kwargs[item_config.limit_param]
+
+            if item_config.fetch_args:
+                fetch_kwargs.update(item_config.fetch_args)
+
+            # Call method with entity_id and kwargs
+            tasks[item_config.field_name] = fetch_method(entity_id, **fetch_kwargs)
+
+        # Execute all tasks in parallel
+        task_results = await self._fetch_details_parallel(tasks)
+
+        # Build FullDetails object
+        details_kwargs: dict[str, Any] = {main_entity_field: main_entity}
+        for item_config in config:
+            details_kwargs[item_config.field_name] = task_results.get(item_config.field_name)
+
+        return full_details_class(**details_kwargs)