diff --git a/README.md b/README.md index 07831d4..5a607d7 100644 --- a/README.md +++ b/README.md @@ -446,6 +446,27 @@ slug and no primary key: ```python client.v2.workspaces.permissions.me("acme") +client.v2.workspaces.teamspaces.my_permissions("acme", teamspace_id) +``` + +Custom roles are built from permission schemes. The catalogue lists the keys a +scheme may grant; the server adds each key's prerequisites on save: + +```python +from plane.models.v2 import CreatePermissionScheme, CreateRole, UpdateRole + +ws = client.v2.workspaces +catalogue = ws.permissions.resources("acme", namespace="project") +scheme = ws.permission_schemes.create( + "acme", + CreatePermissionScheme(name="Triage", namespace="project", permissions=["workitem:edit"]), +) +role = ws.roles.create( + "acme", CreateRole(name="Triager", namespace="project", permission_scheme_ids=[scheme.id]) +) +ws.permission_schemes.impact("acme", scheme.id) # roles, users, projects a change reaches +ws.roles.update("acme", role.id, UpdateRole(status="inactive", reassign_to=other_role_id)) +ws.roles.delete("acme", role.id, reassign_to=other_role_id) # needed when it has members ``` `group_sync` groups three resources under one namespace without consuming a path diff --git a/plane/api/v2/_generated/constants.py b/plane/api/v2/_generated/constants.py index 1b24d1c..2198e05 100644 --- a/plane/api/v2/_generated/constants.py +++ b/plane/api/v2/_generated/constants.py @@ -158,7 +158,11 @@ "pages_list", "pages_partial_update", "pages_retrieve", + "permission_schemes_create", + "permission_schemes_destroy", + "permission_schemes_impact", "permission_schemes_list", + "permission_schemes_partial_update", "permission_schemes_retrieve", "project_automation_activities_list", "project_automation_activities_retrieve", @@ -243,7 +247,10 @@ "releases_partial_update", "releases_retrieve", "releases_work_items", + "roles_create", + "roles_destroy", "roles_list", + "roles_partial_update", "roles_retrieve", "run_activities_create", "run_activities_list", @@ -427,8 +434,10 @@ "workspaces_artifacts_retrieve", "workspaces_artifacts_update_partial_update", "workspaces_permissions_me_retrieve", + "workspaces_permissions_resources_retrieve", "workspaces_projects_permissions_me_retrieve", "workspaces_retrieve", + "workspaces_teamspaces_permissions_me_retrieve", ] ) @@ -2108,6 +2117,34 @@ "sort_order", ] ), + "permission_schemes_create": frozenset( + [ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", + ] + ), + "permission_schemes_destroy": frozenset( + [ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", + ] + ), "permission_schemes_list": frozenset( [ "all", @@ -2119,6 +2156,21 @@ "permissions", "slug", "sort_order", + "updated_at", + ] + ), + "permission_schemes_partial_update": frozenset( + [ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", ] ), "permission_schemes_retrieve": frozenset( @@ -2132,6 +2184,7 @@ "permissions", "slug", "sort_order", + "updated_at", ] ), "project_automation_activities_list": frozenset( @@ -3242,11 +3295,95 @@ "target_date", ] ), + "roles_create": frozenset( + [ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", + ] + ), + "roles_destroy": frozenset( + [ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", + ] + ), "roles_list": frozenset( - ["all", "description", "id", "is_system", "level", "name", "namespace", "slug", "status"] + [ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", + ] + ), + "roles_partial_update": frozenset( + [ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", + ] ), "roles_retrieve": frozenset( - ["all", "description", "id", "is_system", "level", "name", "namespace", "slug", "status"] + [ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", + ] ), "run_activities_create": frozenset( [ @@ -6053,6 +6190,11 @@ "releases_list": frozenset(["lead", "tag"]), "releases_partial_update": frozenset(["lead", "tag"]), "releases_retrieve": frozenset(["lead", "tag"]), + "roles_create": frozenset(["permission_schemes"]), + "roles_destroy": frozenset(["permission_schemes"]), + "roles_list": frozenset(["permission_schemes"]), + "roles_partial_update": frozenset(["permission_schemes"]), + "roles_retrieve": frozenset(["permission_schemes"]), "run_activities_create": frozenset(["actor"]), "run_activities_list": frozenset(["actor"]), "run_activities_retrieve": frozenset(["actor"]), @@ -7710,6 +7852,30 @@ "page_ids", "sort_order", ] +PermissionSchemesCreateField = Literal[ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", +] +PermissionSchemesDestroyField = Literal[ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", +] PermissionSchemesListField = Literal[ "all", "description", @@ -7720,6 +7886,19 @@ "permissions", "slug", "sort_order", + "updated_at", +] +PermissionSchemesPartialUpdateField = Literal[ + "all", + "description", + "id", + "is_system", + "name", + "namespace", + "permissions", + "slug", + "sort_order", + "updated_at", ] PermissionSchemesRetrieveField = Literal[ "all", @@ -7731,6 +7910,7 @@ "permissions", "slug", "sort_order", + "updated_at", ] ProjectAutomationActivitiesListField = Literal[ "actor_id", @@ -8699,11 +8879,85 @@ "tag_id", "target_date", ] +RolesCreateField = Literal[ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", +] +RolesDestroyField = Literal[ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", +] RolesListField = Literal[ - "all", "description", "id", "is_system", "level", "name", "namespace", "slug", "status" + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", +] +RolesPartialUpdateField = Literal[ + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", ] RolesRetrieveField = Literal[ - "all", "description", "id", "is_system", "level", "name", "namespace", "slug", "status" + "all", + "based_on_id", + "description", + "id", + "is_system", + "level", + "name", + "namespace", + "permission_scheme_ids", + "permissions", + "slug", + "sort_order", + "status", + "updated_at", ] RunActivitiesCreateField = Literal[ "actor_id", @@ -11423,6 +11677,10 @@ class ReleasesListFilters(TypedDict, total=False): target_date: str +class RolesDestroyFilters(TypedDict, total=False): + reassign_to: str + + class RolesListFilters(TypedDict, total=False): is_system: bool namespace: str @@ -11699,3 +11957,7 @@ class WorkspaceWorkItemsListFilters(TypedDict, total=False): type_id__in: Sequence[str] updated_at__gte: str updated_at__lte: str + + +class WorkspacesPermissionsResourcesRetrieveFilters(TypedDict, total=False): + namespace: str diff --git a/plane/api/v2/_kernel/resource.py b/plane/api/v2/_kernel/resource.py index 64d577b..f675bb6 100644 --- a/plane/api/v2/_kernel/resource.py +++ b/plane/api/v2/_kernel/resource.py @@ -229,8 +229,14 @@ def _update( ) return self.model.model_validate(payload) # type: ignore[return-value] - def _delete(self, *, pk: Any, **path_params: Any) -> None: - self.transport.request("DELETE", self._detail_url(pk, "delete", **path_params)) + def _delete( + self, *, pk: Any, params: Mapping[str, Any] | None = None, **path_params: Any + ) -> None: + self.transport.request( + "DELETE", + self._detail_url(pk, "delete", **path_params), + params=self._query(params, action="delete") or None, + ) return None def _upsert( diff --git a/plane/api/v2/_loaded/workspace.py b/plane/api/v2/_loaded/workspace.py index e089ee4..15f23b8 100644 --- a/plane/api/v2/_loaded/workspace.py +++ b/plane/api/v2/_loaded/workspace.py @@ -177,9 +177,14 @@ class _OwnedPermissionSchemes(Owned["PermissionSchemes"]): list = staticmethod(bind1(PermissionSchemes.list)) iterate = staticmethod(bind1(PermissionSchemes.iterate)) retrieve = staticmethod(bind1(PermissionSchemes.retrieve)) + create = staticmethod(bind1(PermissionSchemes.create)) + update = staticmethod(bind1(PermissionSchemes.update)) + delete = staticmethod(bind1(PermissionSchemes.delete)) + impact = staticmethod(bind1(PermissionSchemes.impact)) class _OwnedWorkspacePermissions(Owned["WorkspacePermissions"]): me = staticmethod(bind1(WorkspacePermissions.me)) + resources = staticmethod(bind1(WorkspacePermissions.resources)) class _OwnedRoles(Owned["Roles"]): list = staticmethod(bind1(Roles.list)) @@ -187,6 +192,9 @@ class _OwnedRoles(Owned["Roles"]): retrieve = staticmethod(bind1(Roles.retrieve)) find_by_name = staticmethod(bind1(Roles.find_by_name)) find_by_slug = staticmethod(bind1(Roles.find_by_slug)) + create = staticmethod(bind1(Roles.create)) + update = staticmethod(bind1(Roles.update)) + delete = staticmethod(bind1(Roles.delete)) class _OwnedStickies(Owned["Stickies"]): list = staticmethod(bind1(Stickies.list)) @@ -204,6 +212,7 @@ class _OwnedTeamspaces(Owned["Teamspaces"]): create = staticmethod(bind1(Teamspaces.create)) update = staticmethod(bind1(Teamspaces.update)) delete = staticmethod(bind1(Teamspaces.delete)) + my_permissions = staticmethod(bind1(Teamspaces.my_permissions)) class _OwnedWorkspaceViews(Owned["WorkspaceViews"]): list = staticmethod(bind1(WorkspaceViews.list)) diff --git a/plane/api/v2/permission_schemes.py b/plane/api/v2/permission_schemes.py index f6f6daa..00efd22 100644 --- a/plane/api/v2/permission_schemes.py +++ b/plane/api/v2/permission_schemes.py @@ -1,5 +1,8 @@ -"""Workspace permission schemes (api_v2). Read-only -- system + custom schemes, -no create/update/delete on this endpoint.""" +"""Workspace permission schemes (api_v2) -- system + custom. Only custom schemes +take update/delete; writes need the plan's custom-roles feature (402 otherwise). +The server adds each key's prerequisites and folded keys on save, so a scheme +reads back with more `permissions` than were sent. Deleting a scheme a role still +uses is a 409; `impact` says who a change reaches.""" from __future__ import annotations @@ -7,26 +10,36 @@ from typing_extensions import Unpack -from ...models.v2.permission_schemes import PermissionScheme +from ...models.v2.permission_schemes import ( + CreatePermissionScheme, + PermissionScheme, + PermissionSchemeImpact, + UpdatePermissionScheme, +) from ._generated.constants import ( + PermissionSchemesCreateField, PermissionSchemesListField, PermissionSchemesListFilters, PermissionSchemesListOrderBy, + PermissionSchemesPartialUpdateField, PermissionSchemesRetrieveField, ) from ._kernel.pagination import Page, PaginateStyle from ._kernel.resource import V2Resource -# No write/patch DTO exists for permission schemes -- the type parameters are -# filled with the read model itself as an unused placeholder (see the work_items -# build's documented kernel gap). -class PermissionSchemes(V2Resource[PermissionScheme, PermissionScheme, PermissionScheme]): +class PermissionSchemes( + V2Resource[PermissionScheme, CreatePermissionScheme, UpdatePermissionScheme] +): path = "/workspaces/{slug}/permission-schemes/" model = PermissionScheme operations = { "list": "permission_schemes_list", "retrieve": "permission_schemes_retrieve", + "create": "permission_schemes_create", + "update": "permission_schemes_partial_update", + "delete": "permission_schemes_destroy", + "impact": "permission_schemes_impact", } def list( @@ -89,3 +102,34 @@ def retrieve( fields: Sequence[PermissionSchemesRetrieveField] | None = None, ) -> PermissionScheme: return self._retrieve(pk=scheme, params={"fields": fields}, slug=slug) + + def create( + self, + slug: str, + data: CreatePermissionScheme, + *, + fields: Sequence[PermissionSchemesCreateField] | None = None, + ) -> PermissionScheme: + return self._create(data, params={"fields": fields}, slug=slug) + + def update( + self, + slug: str, + scheme: str, + data: UpdatePermissionScheme, + *, + fields: Sequence[PermissionSchemesPartialUpdateField] | None = None, + ) -> PermissionScheme: + """Edit a custom scheme. Every role composing it changes with it -- check + `impact` first.""" + return self._update(data, pk=scheme, params={"fields": fields}, slug=slug) + + def delete(self, slug: str, scheme: str) -> None: + """Delete a custom scheme; 409 while a role still uses it.""" + return self._delete(pk=scheme, slug=slug) + + def impact(self, slug: str, scheme: str) -> PermissionSchemeImpact: + """How many roles compose the scheme, and how many people and projects they reach.""" + return self._custom_action( + "impact", model=PermissionSchemeImpact, method="GET", pk=scheme, slug=slug + ) diff --git a/plane/api/v2/permissions.py b/plane/api/v2/permissions.py index 7eed91a..09bd48d 100644 --- a/plane/api/v2/permissions.py +++ b/plane/api/v2/permissions.py @@ -1,5 +1,6 @@ """Effective permissions (api_v2) -- the calling principal's own grants for a -workspace or a project. Read-only, two GET endpoints. Split into two classes +workspace or a project -- plus the catalogue of keys a custom permission scheme +may grant (`WorkspacePermissions.resources`). Read-only GET endpoints. Split into two classes (rather than one with a `project_me()` method) since `V2Resource` has one `path`. `WorkspacePermissions` is a singleton at `/workspaces/{slug}/permissions/me/` with no @@ -11,7 +12,9 @@ from __future__ import annotations -from ...models.v2.permissions import EffectivePermissions +from typing import Literal + +from ...models.v2.permissions import EffectivePermissions, PermissionCatalogue from ._kernel.resource import V2Resource @@ -19,15 +22,31 @@ class WorkspacePermissions( V2Resource[EffectivePermissions, EffectivePermissions, EffectivePermissions] ): path = "/workspaces/{slug}/permissions/me/" + extra_paths = {"resources": "/workspaces/{slug}/permissions/resources/"} model = EffectivePermissions operations = { "me": "workspaces_permissions_me_retrieve", + "resources": "workspaces_permissions_resources_retrieve", } def me(self, slug: str) -> EffectivePermissions: """The caller's effective permissions across the whole workspace.""" return self._retrieve_singleton(action="me", slug=slug) + def resources( + self, slug: str, *, namespace: Literal["workspace", "project"] | None = None + ) -> PermissionCatalogue: + """The permission keys a custom scheme of `namespace` may grant (the server + defaults to `workspace`), per resource type, with what each key requires + and includes on save.""" + return self._custom_action( + "resources", + model=PermissionCatalogue, + method="GET", + params={"namespace": namespace}, + slug=slug, + ) + class ProjectPermissions( V2Resource[EffectivePermissions, EffectivePermissions, EffectivePermissions] diff --git a/plane/api/v2/roles.py b/plane/api/v2/roles.py index 33892d1..46b05f6 100644 --- a/plane/api/v2/roles.py +++ b/plane/api/v2/roles.py @@ -1,24 +1,35 @@ -"""Roles (api_v2) -- system + custom roles for the workspace. Read-only: list + -retrieve only, no write surface (full role CRUD lives only in the app UI).""" +"""Roles (api_v2) -- system + custom roles for the workspace. Every role reads; +only custom roles take create/update/delete (a system role accepts `sort_order` +alone). Writes need the plan's custom-roles feature (402 otherwise) and an owner +or admin. `expand` accepts `permission_schemes`.""" from __future__ import annotations from collections.abc import Iterator, Sequence from typing import Any -from ...models.v2.roles import Role -from ._generated.constants import RolesListField, RolesListOrderBy, RolesRetrieveField +from ...models.v2.roles import CreateRole, Role, UpdateRole +from ._generated.constants import ( + RolesCreateField, + RolesListField, + RolesListOrderBy, + RolesPartialUpdateField, + RolesRetrieveField, +) from ._kernel.errors import MultipleMatchesFound, NoMatchFound from ._kernel.pagination import Page, PaginateStyle from ._kernel.resource import V2Resource -class Roles(V2Resource[Role, Role, Role]): +class Roles(V2Resource[Role, CreateRole, UpdateRole]): path = "/workspaces/{slug}/roles/" model = Role operations = { "list": "roles_list", "retrieve": "roles_retrieve", + "create": "roles_create", + "update": "roles_partial_update", + "delete": "roles_destroy", } def list( @@ -26,6 +37,7 @@ def list( slug: str, *, fields: Sequence[RolesListField] | None = None, + expand: Sequence[str] | None = None, order_by: RolesListOrderBy | None = None, per_page: int | None = None, offset: int | None = None, @@ -45,6 +57,7 @@ def list( return self._list( params={ "fields": fields, + "expand": expand, "order_by": order_by, "per_page": per_page, "offset": offset, @@ -64,6 +77,7 @@ def iterate( slug: str, *, fields: Sequence[RolesListField] | None = None, + expand: Sequence[str] | None = None, order_by: RolesListOrderBy | None = None, per_page: int | None = None, paginate: PaginateStyle | None = None, @@ -78,6 +92,7 @@ def iterate( return self._iter( params={ "fields": fields, + "expand": expand, "order_by": order_by, "per_page": per_page, "paginate": paginate, @@ -91,9 +106,44 @@ def iterate( ) def retrieve( - self, slug: str, role: str, *, fields: Sequence[RolesRetrieveField] | None = None + self, + slug: str, + role: str, + *, + fields: Sequence[RolesRetrieveField] | None = None, + expand: Sequence[str] | None = None, + ) -> Role: + return self._retrieve(pk=role, params={"fields": fields, "expand": expand}, slug=slug) + + def create( + self, + slug: str, + data: CreateRole, + *, + fields: Sequence[RolesCreateField] | None = None, + expand: Sequence[str] | None = None, ) -> Role: - return self._retrieve(pk=role, params={"fields": fields}, slug=slug) + """Create a custom role from `permission_scheme_ids`, or copy another role's + schemes with `based_on_slug`.""" + return self._create(data, params={"fields": fields, "expand": expand}, slug=slug) + + def update( + self, + slug: str, + role: str, + data: UpdateRole, + *, + fields: Sequence[RolesPartialUpdateField] | None = None, + expand: Sequence[str] | None = None, + ) -> Role: + """Edit a custom role. Disabling one that has members (`status="inactive"`) + needs `reassign_to`: another active role of the same namespace.""" + return self._update(data, pk=role, params={"fields": fields, "expand": expand}, slug=slug) + + def delete(self, slug: str, role: str, *, reassign_to: str | None = None) -> None: + """Delete a custom role. `reassign_to` (a role id) is required when the role + has members: they move to it first.""" + return self._delete(pk=role, params={"reassign_to": reassign_to}, slug=slug) def find_by_name(self, slug: str, name: str, *, namespace: str | None = None) -> Role: """The one role with this name; raises if none or several match. Filters diff --git a/plane/api/v2/teamspaces.py b/plane/api/v2/teamspaces.py index ddb85ae..53b7c4d 100644 --- a/plane/api/v2/teamspaces.py +++ b/plane/api/v2/teamspaces.py @@ -7,6 +7,7 @@ from typing_extensions import Unpack +from ...models.v2.permissions import EffectivePermissions from ...models.v2.teamspaces import CreateTeamspace, Teamspace, UpdateTeamspace from ._generated.constants import ( TeamspacesCreateField, @@ -22,6 +23,9 @@ class Teamspaces(V2Resource[Teamspace, CreateTeamspace, UpdateTeamspace]): path = "/workspaces/{slug}/teamspaces/" + extra_paths = { + "my_permissions": "/workspaces/{slug}/teamspaces/{team_space_id}/permissions/me/" + } model = Teamspace operations = { "list": "teamspaces_list", @@ -29,6 +33,7 @@ class Teamspaces(V2Resource[Teamspace, CreateTeamspace, UpdateTeamspace]): "create": "teamspaces_create", "update": "teamspaces_partial_update", "delete": "teamspaces_destroy", + "my_permissions": "workspaces_teamspaces_permissions_me_retrieve", } def list( @@ -131,3 +136,14 @@ def update( def delete(self, slug: str, teamspace: str) -> None: return self._delete(pk=teamspace, slug=slug) + + def my_permissions(self, slug: str, teamspace: str) -> EffectivePermissions: + """The caller's effective permissions in this teamspace. A method here rather + than a `permissions` child, which would need a navigable `LoadedTeamspace`.""" + return self._custom_action( + "my_permissions", + model=EffectivePermissions, + method="GET", + slug=slug, + team_space_id=teamspace, + ) diff --git a/plane/models/v2/__init__.py b/plane/models/v2/__init__.py index 427033b..344eb70 100644 --- a/plane/models/v2/__init__.py +++ b/plane/models/v2/__init__.py @@ -173,10 +173,19 @@ UpdatePage, ) from .permission_schemes import ( + CreatePermissionScheme, Namespace, PermissionScheme, + PermissionSchemeImpact, + SchemeNamespace, + UpdatePermissionScheme, +) +from .permissions import ( + EffectivePermissions, + PermissionCatalogue, + PermissionKey, + PermissionResource, ) -from .permissions import EffectivePermissions from .project_role_distribution import ( ProjectRoleDistribution, ProjectRoleDistributionEntry, @@ -209,9 +218,12 @@ UpdateReleaseTag, ) from .roles import ( + CreateRole, + CustomRoleNamespace, Role, RoleNamespace, RoleStatus, + UpdateRole, ) from .states import ( CreateState, @@ -397,6 +409,9 @@ "DataMode", "DependencyRelationType", "EffectivePermissions", + "PermissionKey", + "PermissionResource", + "PermissionCatalogue", "Estimate", "UpdateEstimate", "EstimatePoint", @@ -441,6 +456,10 @@ "UpdatePage", "CreatePage", "PermissionScheme", + "CreatePermissionScheme", + "UpdatePermissionScheme", + "PermissionSchemeImpact", + "SchemeNamespace", "PrincipalKind", "Priority", "Project", @@ -472,6 +491,9 @@ "CreateReleaseTag", "CreateRelease", "Role", + "CreateRole", + "UpdateRole", + "CustomRoleNamespace", "RoleNamespace", "RoleStatus", "State", diff --git a/plane/models/v2/permission_schemes.py b/plane/models/v2/permission_schemes.py index 631a109..e573919 100644 --- a/plane/models/v2/permission_schemes.py +++ b/plane/models/v2/permission_schemes.py @@ -3,16 +3,17 @@ from __future__ import annotations import builtins +from datetime import datetime from typing import Literal from pydantic import BaseModel, ConfigDict Namespace = Literal["instance", "workspace", "project"] +SchemeNamespace = Literal["workspace", "project"] class PermissionScheme(BaseModel): - """A system or custom permission scheme (v1 external parity); read-only, every field but `id` - optional.""" + """A system or custom permission scheme; every field but `id` optional.""" model_config = ConfigDict(extra="allow") @@ -24,3 +25,39 @@ class PermissionScheme(BaseModel): permissions: builtins.list[str] | None = None slug: str | None = None sort_order: int | None = None + updated_at: datetime | None = None + + +class CreatePermissionScheme(BaseModel): + """POST body. `permissions` are keys from `permissions.resources()`; the server adds + each key's prerequisites and folded keys on save.""" + + model_config = ConfigDict(extra="ignore") + + name: str + namespace: SchemeNamespace + permissions: builtins.list[str] | None = None + description: str | None = None + sort_order: int | None = None + + +class UpdatePermissionScheme(BaseModel): + """PATCH body -- custom schemes only; `namespace` is fixed at create.""" + + model_config = ConfigDict(extra="ignore") + + name: str | None = None + permissions: builtins.list[str] | None = None + description: str | None = None + sort_order: int | None = None + + +class PermissionSchemeImpact(BaseModel): + """Who a change to the scheme reaches: the workspace's roles composing it, the people + holding those roles, and the projects those people can reach.""" + + model_config = ConfigDict(extra="allow") + + roles: int + users: int + projects: int diff --git a/plane/models/v2/permissions.py b/plane/models/v2/permissions.py index aa0020c..690c047 100644 --- a/plane/models/v2/permissions.py +++ b/plane/models/v2/permissions.py @@ -1,5 +1,5 @@ -"""Effective-permissions model for api_v2 -- the calling principal's own grants for -a workspace or a project. Read-only, no `id` (this row has none).""" +"""Permission models for api_v2: the caller's effective grants (no `id`), and the +catalogue of keys a custom permission scheme may grant.""" from pydantic import BaseModel, ConfigDict @@ -9,3 +9,29 @@ class EffectivePermissions(BaseModel): relation: str | None = None permission_grants: list[str] | None = None + + +class PermissionKey(BaseModel): + """One grantable key. Saving it also stores `requires` (prerequisites) and `includes` + (keys folded in with the same condition).""" + + model_config = ConfigDict(extra="allow") + + permission: str + requires: list[str] = [] + includes: list[str] = [] + + +class PermissionResource(BaseModel): + model_config = ConfigDict(extra="allow") + + resource_type: str + permissions: list[PermissionKey] = [] + + +class PermissionCatalogue(BaseModel): + """The permission catalogue for one namespace, grouped by resource type.""" + + model_config = ConfigDict(extra="allow") + + resources: list[PermissionResource] diff --git a/plane/models/v2/roles.py b/plane/models/v2/roles.py index 0fc4fc2..9bbcfc4 100644 --- a/plane/models/v2/roles.py +++ b/plane/models/v2/roles.py @@ -1,11 +1,13 @@ -"""Role models for api_v2. Read-only: list + retrieve only, no write surface.""" +"""Role models for api_v2: the read row plus the custom-role write bodies.""" +from datetime import datetime from typing import Literal from pydantic import BaseModel, ConfigDict RoleNamespace = Literal["instance", "workspace", "project"] RoleStatus = Literal["active", "inactive"] +CustomRoleNamespace = Literal["workspace", "project"] class Role(BaseModel): @@ -19,3 +21,38 @@ class Role(BaseModel): namespace: RoleNamespace | None = None status: RoleStatus | None = None is_system: bool | None = None + sort_order: int | None = None + based_on_id: str | None = None + permission_scheme_ids: list[str] | None = None + permissions: list[str] | None = None + updated_at: datetime | None = None + + +class CreateRole(BaseModel): + """POST body -- a custom role. `based_on_slug` copies that role's schemes.""" + + model_config = ConfigDict(extra="ignore") + + name: str + namespace: CustomRoleNamespace + description: str | None = None + permission_scheme_ids: list[str] | None = None + based_on_slug: str | None = None + level: int | None = None + sort_order: int | None = None + status: RoleStatus | None = None + + +class UpdateRole(BaseModel): + """PATCH body. Setting `status="inactive"` on a role with members needs `reassign_to`, + the role that takes them over. A system role accepts `sort_order` only (403 otherwise).""" + + model_config = ConfigDict(extra="ignore") + + name: str | None = None + description: str | None = None + permission_scheme_ids: list[str] | None = None + level: int | None = None + sort_order: int | None = None + status: RoleStatus | None = None + reassign_to: str | None = None diff --git a/tests/v2/test_permission_schemes_resource.py b/tests/v2/test_permission_schemes_resource.py index 0f6c7ac..70e8940 100644 --- a/tests/v2/test_permission_schemes_resource.py +++ b/tests/v2/test_permission_schemes_resource.py @@ -1,14 +1,17 @@ -"""Offline coverage for `ws.permission_schemes`: a read-only workspace-scoped list (with sparse -`fields`) and retrieve.""" +"""Offline coverage for `ws.permission_schemes`: list (with sparse `fields`), retrieve, the +custom-scheme writes, and `impact`.""" from __future__ import annotations +import json + import pytest import responses from plane.api.v2._kernel.transport import V2Transport from plane.api.v2.permission_schemes import PermissionSchemes from plane.config import Configuration +from plane.models.v2.permission_schemes import CreatePermissionScheme, UpdatePermissionScheme BASE = "https://api.example.com/api/v2" @@ -103,3 +106,58 @@ def test_permission_schemes_unknown_field_rejected( -- negative assertion, proven capable of failing below.""" with pytest.raises(ValueError, match="Unknown field"): permission_schemes.list("acme", fields=["not_a_real_field"]) + + +# -- Custom-scheme writes and impact ---------------------------------------------- + +SCHEMES = f"{BASE}/workspaces/acme/permission-schemes" + + +@responses.activate +def test_permission_schemes_create_posts_the_body(permission_schemes: PermissionSchemes) -> None: + responses.post( + f"{SCHEMES}/", + json={"id": "s1", "permissions": ["project:view", "workitem:edit", "workitem:view"]}, + ) + + created = permission_schemes.create( + "acme", + CreatePermissionScheme(name="Triage", namespace="project", permissions=["workitem:edit"]), + ) + + assert created.permissions == ["project:view", "workitem:edit", "workitem:view"] + assert json.loads(responses.calls[0].request.body) == { + "name": "Triage", + "namespace": "project", + "permissions": ["workitem:edit"], + } + + +@responses.activate +def test_permission_schemes_update_patches_the_detail_url( + permission_schemes: PermissionSchemes, +) -> None: + responses.patch(f"{SCHEMES}/s1/", json={"id": "s1", "name": "Renamed"}) + + updated = permission_schemes.update("acme", "s1", UpdatePermissionScheme(name="Renamed")) + + assert updated.name == "Renamed" + assert json.loads(responses.calls[0].request.body) == {"name": "Renamed"} + + +@responses.activate +def test_permission_schemes_delete(permission_schemes: PermissionSchemes) -> None: + responses.delete(f"{SCHEMES}/s1/", status=204) + + assert permission_schemes.delete("acme", "s1") is None + assert responses.calls[0].request.url == f"{SCHEMES}/s1/" + + +@responses.activate +def test_permission_schemes_impact_gets_the_counts(permission_schemes: PermissionSchemes) -> None: + responses.get(f"{SCHEMES}/s1/impact/", json={"roles": 2, "users": 7, "projects": 3}) + + impact = permission_schemes.impact("acme", "s1") + + assert (impact.roles, impact.users, impact.projects) == (2, 7, 3) + assert responses.calls[0].request.method == "GET" diff --git a/tests/v2/test_permissions_resource.py b/tests/v2/test_permissions_resource.py index f5bec85..8307a92 100644 --- a/tests/v2/test_permissions_resource.py +++ b/tests/v2/test_permissions_resource.py @@ -6,6 +6,7 @@ import pytest import responses +from responses import matchers from plane.api.v2._kernel.transport import V2Transport from plane.api.v2.permissions import ProjectPermissions, WorkspacePermissions @@ -62,3 +63,47 @@ def test_me_and_project_me_hit_different_urls( project_result = project_permissions.me("acme", "ENG") assert workspace_result.relation != project_result.relation + + +RESOURCES_URL = "https://api.example.com/api/v2/workspaces/acme/permissions/resources/" + + +@responses.activate +def test_resources_reads_the_catalogue_for_a_namespace( + workspace_permissions: WorkspacePermissions, +) -> None: + responses.get( + RESOURCES_URL, + json={ + "resources": [ + { + "resource_type": "workitem", + "permissions": [ + { + "permission": "workitem:edit", + "requires": ["workitem:view"], + "includes": [], + } + ], + } + ] + }, + match=[matchers.query_param_matcher({"namespace": "project"})], + ) + + catalogue = workspace_permissions.resources("acme", namespace="project") + + key = catalogue.resources[0].permissions[0] + assert catalogue.resources[0].resource_type == "workitem" + assert (key.permission, key.requires) == ("workitem:edit", ["workitem:view"]) + + +@responses.activate +def test_resources_without_namespace_leaves_the_server_default( + workspace_permissions: WorkspacePermissions, +) -> None: + responses.get(RESOURCES_URL, json={"resources": []}) + + workspace_permissions.resources("acme") + + assert responses.calls[0].request.url == RESOURCES_URL diff --git a/tests/v2/test_roles_resource.py b/tests/v2/test_roles_resource.py index 9d9af8f..91071b0 100644 --- a/tests/v2/test_roles_resource.py +++ b/tests/v2/test_roles_resource.py @@ -1,4 +1,5 @@ import inspect +import json import pytest import responses @@ -242,3 +243,64 @@ def test_roles_spells_out_exactly_the_generated_filter_set(method_name: str) -> "collides with the leading path id `slug`), or drop the parameter the golden no " "longer offers." ) + + +# -- Custom-role writes ----------------------------------------------------------- + + +@responses.activate +def test_create_posts_the_body_and_expand(roles: Roles) -> None: + from plane.models.v2.roles import CreateRole + + responses.post( + f"{BASE}/", json={"id": "r9", "name": "Triager", "permission_scheme_ids": ["s1"]} + ) + + created = roles.create( + "acme", + CreateRole(name="Triager", namespace="project", permission_scheme_ids=["s1"]), + expand=["permission_schemes"], + ) + + assert created.permission_scheme_ids == ["s1"] + assert "expand=permission_schemes" in responses.calls[0].request.url + assert json.loads(responses.calls[0].request.body) == { + "name": "Triager", + "namespace": "project", + "permission_scheme_ids": ["s1"], + } + + +@responses.activate +def test_update_disabling_sends_reassign_to_in_the_body(roles: Roles) -> None: + from plane.models.v2.roles import UpdateRole + + responses.patch(f"{BASE}/r9/", json={"id": "r9", "status": "inactive"}) + + updated = roles.update("acme", "r9", UpdateRole(status="inactive", reassign_to="r2")) + + assert updated.status == "inactive" + assert json.loads(responses.calls[0].request.body) == { + "status": "inactive", + "reassign_to": "r2", + } + + +@responses.activate +def test_delete_sends_reassign_to_as_a_query_param(roles: Roles) -> None: + responses.delete( + f"{BASE}/r9/", + status=204, + match=[matchers.query_param_matcher({"reassign_to": "r2"})], + ) + + assert roles.delete("acme", "r9", reassign_to="r2") is None + + +@responses.activate +def test_delete_without_reassign_to_sends_no_query(roles: Roles) -> None: + responses.delete(f"{BASE}/r9/", status=204) + + roles.delete("acme", "r9") + + assert responses.calls[0].request.url == f"{BASE}/r9/" diff --git a/tests/v2/test_teamspaces_resource.py b/tests/v2/test_teamspaces_resource.py index 7b2a336..91d95e3 100644 --- a/tests/v2/test_teamspaces_resource.py +++ b/tests/v2/test_teamspaces_resource.py @@ -148,3 +148,16 @@ def test_find_by_name(teamspaces: Teamspaces) -> None: assert found.id == "1" assert responses.calls[0].request.url.startswith(f"{BASE}/") + + +@responses.activate +def test_my_permissions_reads_the_teamspace_scoped_me(teamspaces: Teamspaces) -> None: + responses.get( + f"{BASE}/t1/permissions/me/", + json={"relation": "member", "permission_grants": ["teamspace:view"]}, + ) + + result = teamspaces.my_permissions("acme", "t1") + + assert result.relation == "member" + assert result.permission_grants == ["teamspace:view"]