api methods for estimates feature (#31)

* api methods for estimates feature

* refactoring

* change version

* archive methods for workitems and projects

Author: sunder-ch

plane/__init__.py

@@ -1,5 +1,6 @@
 from .api.agent_runs import AgentRuns
 from .api.cycles import Cycles
+from .api.estimates import Estimates
 from .api.initiatives import Initiatives
 from .api.labels import Labels
 from .api.milestones import Milestones
@@ -44,6 +45,7 @@
     "Milestones",
     "Modules",
     "Cycles",
+    "Estimates",
     "Pages",
     "Workspaces",
     "PlaneError",

plane/api/base_resource.py

@@ -36,7 +36,9 @@ def _get(self, endpoint: str, params: Mapping[str, Any] | None = None) -> Any:
         )
         return self._handle_response(response)
 
-    def _post(self, endpoint: str, data: Mapping[str, Any] | None = None) -> Any:
+    def _post(
+        self, endpoint: str, data: Mapping[str, Any] | list[Any] | None = None
+    ) -> Any:
         url = self._build_url(endpoint)
         response = self.session.post(
             url, headers=self._headers(), json=data, timeout=self.config.timeout

plane/api/estimates.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..models.estimates import (
+    CreateEstimate,
+    CreateEstimatePoint,
+    Estimate,
+    EstimatePoint,
+    UpdateEstimate,
+    UpdateEstimatePoint,
+)
+from .base_resource import BaseResource
+
+
+class Estimates(BaseResource):
+    """Resource for managing project estimates and estimate points."""
+
+    def __init__(self, config: Any) -> None:
+        super().__init__(config, "/workspaces/")
+
+    # ── Estimate CRUD ────────────────────────────────────────────
+
+    def create(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        data: CreateEstimate,
+    ) -> Estimate:
+        """Create a new estimate for a project.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            data: Estimate creation data.
+        """
+        response = self._post(
+            f"{workspace_slug}/projects/{project_id}/estimates",
+            data.model_dump(exclude_none=True),
+        )
+        return Estimate.model_validate(response)
+
+    def link_to_project(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        estimate_id: str,
+    ) -> Any:
+        """Link an estimate to a project so that it becomes the active estimate system.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            estimate_id: UUID of the estimate to link.
+        """
+        from ..models.projects import UpdateProject
+        from .projects import Projects
+
+        projects_client = Projects(self.config)
+        return projects_client.update(
+            workspace_slug,
+            project_id,
+            UpdateProject(estimate=estimate_id),
+        )
+
+    def retrieve(
+        self,
+        workspace_slug: str,
+        project_id: str,
+    ) -> Estimate:
+        """Retrieve the estimate configured for a project.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+        """
+        response = self._get(
+            f"{workspace_slug}/projects/{project_id}/estimates",
+        )
+        return Estimate.model_validate(response)
+
+    def update(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        data: UpdateEstimate,
+    ) -> Estimate:
+        """Update the estimate for a project.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            data: Fields to update.
+        """
+        response = self._patch(
+            f"{workspace_slug}/projects/{project_id}/estimates",
+            data.model_dump(exclude_none=True),
+        )
+        return Estimate.model_validate(response)
+
+    def delete(
+        self,
+        workspace_slug: str,
+        project_id: str,
+    ) -> None:
+        """Delete the estimate for a project.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+        """
+        return self._delete(
+            f"{workspace_slug}/projects/{project_id}/estimates",
+        )
+
+    # ── Estimate Points ──────────────────────────────────────────
+
+    def list_points(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        estimate_id: str,
+    ) -> list[EstimatePoint]:
+        """List all estimate points for a project estimate.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            estimate_id: UUID of the estimate.
+        """
+        response = self._get(
+            f"{workspace_slug}/projects/{project_id}"
+            f"/estimates/{estimate_id}/estimate-points",
+        )
+        return [EstimatePoint.model_validate(item) for item in response]
+
+    def create_points(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        estimate_id: str,
+        data: list[CreateEstimatePoint],
+    ) -> list[EstimatePoint]:
+        """Create estimate points for a project estimate.
+
+        The API accepts a JSON array directly as the request body.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            estimate_id: UUID of the estimate.
+            data: List of estimate point creation data.
+        """
+        payload = [item.model_dump(exclude_none=True) for item in data]
+        response = self._post(
+            f"{workspace_slug}/projects/{project_id}"
+            f"/estimates/{estimate_id}/estimate-points",
+            payload,
+        )
+        return [EstimatePoint.model_validate(item) for item in response]
+
+    def update_point(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        estimate_id: str,
+        estimate_point_id: str,
+        data: UpdateEstimatePoint,
+    ) -> EstimatePoint:
+        """Update a single estimate point.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            estimate_id: UUID of the estimate.
+            estimate_point_id: UUID of the estimate point.
+            data: Fields to update.
+        """
+        response = self._patch(
+            f"{workspace_slug}/projects/{project_id}"
+            f"/estimates/{estimate_id}/estimate-points/{estimate_point_id}",
+            data.model_dump(exclude_none=True),
+        )
+        return EstimatePoint.model_validate(response)
+
+    def delete_point(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        estimate_id: str,
+        estimate_point_id: str,
+    ) -> None:
+        """Delete a single estimate point.
+
+        Args:
+            workspace_slug: The workspace slug identifier.
+            project_id: UUID of the project.
+            estimate_id: UUID of the estimate.
+            estimate_point_id: UUID of the estimate point.
+        """
+        return self._delete(
+            f"{workspace_slug}/projects/{project_id}"
+            f"/estimates/{estimate_id}/estimate-points/{estimate_point_id}",
+        )

plane/api/projects.py

@@ -120,3 +120,32 @@ def update_features(
             f"{workspace_slug}/projects/{project_id}/features", data.model_dump(exclude_none=True)
         )
         return ProjectFeature.model_validate(response)
+
+    def archive(self, workspace_slug: str, project_id: str) -> None:
+        """Archive a project.
+
+        Move a project to archived status, hiding it from active project lists.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+
+        Returns:
+            None (HTTP 204 No Content)
+        """
+        self._post(f"{workspace_slug}/projects/{project_id}/archive", {})
+
+    def unarchive(self, workspace_slug: str, project_id: str) -> None:
+        """Unarchive a project.
+
+        Restore an archived project to active status, making it available
+        in regular workflows.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+
+        Returns:
+            None (HTTP 204 No Content)
+        """
+        self._delete(f"{workspace_slug}/projects/{project_id}/archive")

plane/api/work_items/base.py

@@ -236,3 +236,35 @@ def advanced_search(
             data.model_dump(exclude_none=True),
         )
         return [AdvancedSearchResult.model_validate(item) for item in response]
+
+    def archive(self, workspace_slug: str, project_id: str, work_item_id: str) -> None:
+        """Archive a work item.
+
+        Only work items in a completed or cancelled state can be archived.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+            work_item_id: UUID of the work item
+        """
+        self._post(
+            f"{workspace_slug}/projects/{project_id}/work-items/{work_item_id}/archive",
+            {},
+        )
+
+    def unarchive(self, workspace_slug: str, project_id: str, work_item_id: str) -> None:
+        """Unarchive a work item.
+
+        Restore an archived work item to active status.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+            work_item_id: UUID of the work item
+
+        Returns:
+            None (HTTP 204 No Content)
+        """
+        self._delete(
+            f"{workspace_slug}/projects/{project_id}/work-items/{work_item_id}/unarchive"
+        )

plane/client/plane_client.py

@@ -2,6 +2,7 @@
 from ..api.customers import Customers
 from ..api.cycles import Cycles
 from ..api.epics import Epics
+from ..api.estimates import Estimates
 from ..api.initiatives import Initiatives
 from ..api.intake import Intake
 from ..api.labels import Labels
@@ -55,6 +56,7 @@ def __init__(
         self.milestones = Milestones(self.config)
         self.modules = Modules(self.config)
         self.cycles = Cycles(self.config)
+        self.estimates = Estimates(self.config)
         self.work_item_types = WorkItemTypes(self.config)
         self.work_item_properties = WorkItemProperties(self.config)
         self.customers = Customers(self.config)