feat: Add lite list endpoints, project role distribution, and cycle status filtering to the SDK #56

feat: Add lite list endpoints, project role distribution, and cycle status filtering to the SDK

Author: dheeru0198

README.md

@@ -293,6 +293,13 @@ while paginated_members.next_page_results:
         params=MemberListQueryParams(per_page=1000, cursor=paginated_members.next_cursor),
     )
     all_members.extend(paginated_members.results)
+
+# Project-role distribution — member counts per role across all active
+# (non-archived) projects in the workspace (built-in + custom roles)
+distribution = client.workspaces.get_project_role_distribution(workspace_slug)
+print(distribution.total_memberships, distribution.total_distinct_members)
+for role in distribution.roles:
+    print(role.slug, role.membership_count, role.distinct_member_count)
 ```
 
 #### Roles
@@ -372,6 +379,24 @@ members = client.projects.get_members_lite(
     workspace_slug, project_id,
     params=MemberListQueryParams(per_page=1000),
 )
+
+# Paginated "lite" project list (id, identifier, name, icon/emoji, description,
+# cover image, archived_at) — for pickers/reference lookups.
+from plane.models.query_params import ProjectLiteListQueryParams
+
+lite = client.projects.list_lite(
+    workspace_slug,
+    params=ProjectLiteListQueryParams(per_page=1000, order_by="-created_at"),
+)
+for p in lite.results:
+    print(p.identifier, p.name)
+
+# NOTE: archived projects are now EXCLUDED by default. Pass include_archived=True
+# to restore the previous behavior of listing archived projects too.
+lite = client.projects.list_lite(
+    workspace_slug,
+    params=ProjectLiteListQueryParams(include_archived=True),
+)
 ```
 
 #### Work Items
@@ -482,6 +507,26 @@ cycle = client.cycles.create(
 # List cycles
 cycles = client.cycles.list(workspace_slug, project_id)
 
+# Filter cycles by status: current | upcoming | completed | draft | incomplete.
+# `status` is canonical; `cycle_view` is a deprecated alias (status wins if both set).
+from plane.models.query_params import CycleListQueryParams
+
+upcoming = client.cycles.list(
+    workspace_slug, project_id,
+    params=CycleListQueryParams(status="upcoming"),
+)
+for c in upcoming.results:  # paginated envelope
+    print(c.name)
+
+# NOTE: status="current" is a special case — the API returns a BARE LIST of cycles
+# (not the paginated envelope). list() returns whichever shape the server sends.
+current = client.cycles.list(
+    workspace_slug, project_id,
+    params=CycleListQueryParams(status="current"),
+)
+for c in current:  # plain list[Cycle]
+    print(c.name)
+
 # Retrieve a cycle
 cycle = client.cycles.retrieve(workspace_slug, project_id, cycle_id)
 
@@ -499,6 +544,19 @@ client.cycles.delete(workspace_slug, project_id, cycle_id)
 # List archived cycles
 archived = client.cycles.list_archived(workspace_slug, project_id)
 
+# Paginated "lite" cycle list (full cycle fields minus issue-count metrics).
+# Supports a status filter: current | upcoming | completed | draft | incomplete
+# (omit for all). The lite endpoint takes only `status` (no `cycle_view` alias)
+# and ALWAYS paginates — even for status="current".
+from plane.models.query_params import CycleLiteListQueryParams
+
+lite = client.cycles.list_lite(
+    workspace_slug, project_id,
+    params=CycleLiteListQueryParams(status="current", per_page=1000),
+)
+for c in lite.results:
+    print(c.name)
+
 # Add work items to cycle
 from plane.models.cycles import AddWorkItemsToCycleRequest
 
@@ -557,6 +615,16 @@ client.modules.delete(workspace_slug, project_id, module_id)
 # List archived modules
 archived = client.modules.list_archived(workspace_slug, project_id)
 
+# Paginated "lite" module list (full module fields minus issue-count metrics)
+from plane.models.query_params import LiteListQueryParams
+
+lite = client.modules.list_lite(
+    workspace_slug, project_id,
+    params=LiteListQueryParams(per_page=1000, order_by="-created_at"),
+)
+for m in lite.results:
+    print(m.name)
+
 # Add work items to module
 from plane.models.modules import AddWorkItemsToModuleRequest
 

plane/api/cycles.py

@@ -5,12 +5,17 @@
     CreateCycle,
     Cycle,
     PaginatedArchivedCycleResponse,
+    PaginatedCycleLiteResponse,
     PaginatedCycleResponse,
     PaginatedCycleWorkItemResponse,
     TransferCycleWorkItemsRequest,
     UpdateCycle,
 )
-from ..models.query_params import WorkItemQueryParams
+from ..models.query_params import (
+    CycleListQueryParams,
+    CycleLiteListQueryParams,
+    WorkItemQueryParams,
+)
 from .base_resource import BaseResource
 from .work_items.base import prepare_work_item_params
 
@@ -72,18 +77,73 @@ def delete(self, workspace_slug: str, project_id: str, cycle_id: str) -> None:
         return self._delete(f"{workspace_slug}/projects/{project_id}/cycles/{cycle_id}")
 
     def list(
-        self, workspace_slug: str, project_id: str, params: Mapping[str, Any] | None = None
-    ) -> PaginatedCycleResponse:
+        self,
+        workspace_slug: str,
+        project_id: str,
+        params: CycleListQueryParams | Mapping[str, Any] | None = None,
+    ) -> PaginatedCycleResponse | list[Cycle]:
         """List cycles with optional filtering parameters.
 
+        Supports cycle status filtering via :class:`CycleListQueryParams`. Pass
+        ``status`` (canonical) or the deprecated ``cycle_view`` alias with one of
+        ``current``, ``upcoming``, ``completed``, ``draft``, ``incomplete``; if
+        both are supplied the server uses ``status``.
+
+        .. note::
+            With ``status=current`` (or ``cycle_view=current``) the server
+            returns a **bare list** of :class:`Cycle` objects instead of the
+            paginated :class:`PaginatedCycleResponse` envelope returned for all
+            other values. This method returns whichever shape the server sends.
+            The :meth:`list_lite` endpoint always paginates, even for
+            ``status=current``.
+
         Args:
             workspace_slug: The workspace slug identifier
             project_id: UUID of the project
-            params: Optional query parameters
+            params: Optional query parameters. Prefer ``CycleListQueryParams``;
+                a plain mapping is also accepted for backwards compatibility.
         """
-        response = self._get(f"{workspace_slug}/projects/{project_id}/cycles", params=params)
+        if isinstance(params, CycleListQueryParams):
+            query_params: Mapping[str, Any] | None = params.to_query_params()
+        else:
+            query_params = params
+        response = self._get(f"{workspace_slug}/projects/{project_id}/cycles", params=query_params)
+        if isinstance(response, list):
+            return [Cycle.model_validate(item) for item in response]
         return PaginatedCycleResponse.model_validate(response)
 
+    def list_lite(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        params: CycleLiteListQueryParams | None = None,
+    ) -> PaginatedCycleLiteResponse:
+        """List cycles as a paginated "lite" response.
+
+        Calls the read-only ``/cycles-lite/`` endpoint, which returns the full
+        cycle field set minus the issue-count metric annotations (total_issues,
+        completed_issues, etc.), suitable for pickers and reference lookups.
+        Supports ordering, cursor pagination, and a ``status`` filter -- there
+        are no field filters. ``per_page`` defaults to and caps at 1000. Unlike
+        the full cycles list, the lite endpoint accepts only ``status`` (no
+        ``cycle_view`` alias).
+
+        Unlike the full ``cycles`` list endpoint (where ``status=current``
+        returns a bare array), this endpoint always returns the paginated
+        envelope for every ``status`` value.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+            params: Optional ordering + cursor pagination query parameters,
+                plus the ``status`` filter
+        """
+        response = self._get(
+            f"{workspace_slug}/projects/{project_id}/cycles-lite",
+            params=params.to_query_params() if params else None,
+        )
+        return PaginatedCycleLiteResponse.model_validate(response)
+
     def list_archived(
         self, workspace_slug: str, project_id: str, params: Mapping[str, Any] | None = None
     ) -> PaginatedArchivedCycleResponse:

plane/api/modules.py

@@ -5,11 +5,12 @@
     CreateModule,
     Module,
     PaginatedArchivedModuleResponse,
+    PaginatedModuleLiteResponse,
     PaginatedModuleResponse,
     PaginatedModuleWorkItemResponse,
     UpdateModule,
 )
-from ..models.query_params import WorkItemQueryParams
+from ..models.query_params import LiteListQueryParams, WorkItemQueryParams
 from .base_resource import BaseResource
 from .work_items.base import prepare_work_item_params
 
@@ -83,6 +84,31 @@ def list(
         response = self._get(f"{workspace_slug}/projects/{project_id}/modules", params=params)
         return PaginatedModuleResponse.model_validate(response)
 
+    def list_lite(
+        self,
+        workspace_slug: str,
+        project_id: str,
+        params: LiteListQueryParams | None = None,
+    ) -> PaginatedModuleLiteResponse:
+        """List modules as a paginated "lite" response.
+
+        Calls the read-only ``/modules-lite/`` endpoint, which returns the full
+        module field set minus the issue-count metric annotations (total_issues,
+        completed_issues, etc.), suitable for pickers and reference lookups.
+        Only ordering and cursor pagination are supported -- there are no field
+        filters. ``per_page`` defaults to and caps at 1000.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            project_id: UUID of the project
+            params: Optional ordering + cursor pagination query parameters
+        """
+        response = self._get(
+            f"{workspace_slug}/projects/{project_id}/modules-lite",
+            params=params.to_query_params() if params else None,
+        )
+        return PaginatedModuleLiteResponse.model_validate(response)
+
     def list_archived(
         self, workspace_slug: str, project_id: str, params: Mapping[str, Any] | None = None
     ) -> PaginatedArchivedModuleResponse:

plane/api/projects.py

@@ -5,6 +5,7 @@
 
 from ..models.projects import (
     CreateProject,
+    PaginatedProjectLiteResponse,
     PaginatedProjectMemberResponse,
     PaginatedProjectResponse,
     Project,
@@ -17,6 +18,7 @@
     MemberListQueryParams,
     MemberQueryParams,
     PaginatedQueryParams,
+    ProjectLiteListQueryParams,
 )
 from .base_resource import BaseResource
 
@@ -80,6 +82,34 @@ def list(
         response = self._get(f"{workspace_slug}/projects", params=query_params)
         return PaginatedProjectResponse.model_validate(response)
 
+    def list_lite(
+        self, workspace_slug: str, params: ProjectLiteListQueryParams | None = None
+    ) -> PaginatedProjectLiteResponse:
+        """List projects as a paginated "lite" response.
+
+        Calls the read-only ``/projects-lite/`` endpoint, which returns a
+        field-trimmed shape (id, identifier, name, cover_image, icon_prop,
+        emoji, description, cover_image_url, archived_at) suitable for pickers
+        and reference lookups. Supports ordering, cursor pagination, and an
+        ``include_archived`` toggle -- there are no field filters. ``per_page``
+        defaults to and caps at 1000.
+
+        .. note::
+            Archived projects are now **excluded** by default. Pass
+            ``ProjectLiteListQueryParams(include_archived=True)`` to restore the
+            previous behavior of listing archived projects too.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            params: Optional ordering + cursor pagination query parameters,
+                plus the ``include_archived`` toggle
+        """
+        response = self._get(
+            f"{workspace_slug}/projects-lite",
+            params=params.to_query_params() if params else None,
+        )
+        return PaginatedProjectLiteResponse.model_validate(response)
+
     def get_worklog_summary(self, workspace_slug: str, project_id: str) -> [ProjectWorklogSummary]:
         """Get work log summary for a project.
 

plane/api/workspaces.py

@@ -5,6 +5,7 @@
 from ..models.query_params import MemberListQueryParams, MemberQueryParams
 from ..models.workspaces import (
     PaginatedWorkspaceMemberResponse,
+    ProjectRoleDistribution,
     WorkspaceFeature,
     WorkspaceMember,
 )
@@ -54,6 +55,19 @@ def get_members_lite(
         )
         return PaginatedWorkspaceMemberResponse.model_validate(response)
 
+    def get_project_role_distribution(self, workspace_slug: str) -> ProjectRoleDistribution:
+        """Get the distribution of project members by role across the workspace.
+
+        Aggregates member counts per role over all active (non-archived)
+        projects in the workspace. Both built-in roles (admin, contributor,
+        commenter, guest) and custom roles are included.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+        """
+        response = self._get(f"{workspace_slug}/project-role-distribution")
+        return ProjectRoleDistribution.model_validate(response)
+
     def get_features(self, workspace_slug: str) -> WorkspaceFeature:
         """Get features of a workspace.
 

plane/models/__init__.py

@@ -15,9 +15,13 @@
 )
 from .query_params import (
     BaseQueryParams,
+    CycleLiteListQueryParams,
+    CycleListQueryParams,
+    LiteListQueryParams,
     MemberListQueryParams,
     MemberQueryParams,
     PaginatedQueryParams,
+    ProjectLiteListQueryParams,
     RetrieveQueryParams,
     WorkItemQueryParams,
 )
@@ -39,9 +43,13 @@
     "IntakeWorkItemStatusEnum",
     # query params
     "BaseQueryParams",
+    "CycleLiteListQueryParams",
+    "CycleListQueryParams",
+    "LiteListQueryParams",
     "MemberListQueryParams",
     "MemberQueryParams",
     "PaginatedQueryParams",
+    "ProjectLiteListQueryParams",
     "RetrieveQueryParams",
     "WorkItemQueryParams",
 ]

plane/models/cycles.py

@@ -141,6 +141,14 @@ class PaginatedCycleResponse(PaginatedResponse):
     results: list[Cycle]
 
 
+class PaginatedCycleLiteResponse(PaginatedResponse):
+    """Paginated response for the cycles-lite endpoint."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    results: list[CycleLite]
+
+
 class PaginatedArchivedCycleResponse(PaginatedResponse):
     """Paginated response for archived cycles."""
 

plane/models/enums.py

@@ -48,6 +48,10 @@
     "FORMULA",
 ]
 RelationTypeEnum = Literal["ISSUE", "USER", "RELEASE"]
+CycleStatusEnum = Literal["current", "upcoming", "completed", "draft", "incomplete"]
+# Deprecated alias for CycleStatusEnum. ``status`` is the canonical cycle filter
+# going forward; ``cycle_view`` is kept only for backward compatibility.
+CycleViewEnum = CycleStatusEnum
 
 
 # Proper Enum classes for better type safety and IDE support
@@ -93,6 +97,7 @@ class InitiativeState(Enum):
     COMPLETED = "COMPLETED"
     CLOSED = "CLOSED"
 
+
 class WorkItemRelationType(Enum):
     """Work item relation type enumeration."""
 
@@ -580,6 +585,8 @@ class Group(Enum):
     "PriorityEnum",
     "PropertyTypeEnum",
     "RelationTypeEnum",
+    "CycleStatusEnum",
+    "CycleViewEnum",
     "TimezoneEnum",
     "TypeMimeEnum",
     "NetworkEnum",