feat (api): projects with permissions (#430)

* adds project with permissions

* removes the project resource with permissions

* fix the tests

.github/workflows/pr.yml

@@ -1,12 +1,16 @@
-name: "Specklepy test and build"
+name: "Specklepy test"
 on:
+  workflow_call:
+    secrets:
+      CODECOV_TOKEN:
+        required: true
   pull_request:
     branches:
-      - "v3-dev"
+      - "main"
 
 jobs:
-  build-and-test:
-    name: build-and-test
+  test:
+    name: test
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/publish.yml

@@ -2,63 +2,20 @@ name: "Publish Python Package"
 on:
   push:
     branches:
-      - "v3-dev"
+      - "main"
     tags:
       - "3.*.*"
 
 jobs:
-  build-and-test:
-    name: continuous-integration
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version:
-          - "3.10"
-          - "3.11"
-          - "3.12"
-          - "3.13"
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          enable-cache: true
-          cache-dependency-glob: "uv.lock"
-
-      - name: Install the project
-        run: uv sync --all-extras --dev
-
-      - uses: actions/cache@v3
-        with:
-          path: ~/.cache/pre-commit/
-          key: ${{ hashFiles('.pre-commit-config.yaml') }}
-
-      - name: Run pre-commit
-        run: uv run pre-commit run --all-files
-
-      - name: Run Speckle Server
-        run: docker compose up -d
-
-      # - name: Run tests
-      #   run: uv run pytest --cov --cov-report xml:reports/coverage.xml --junitxml=reports/test-results.xml
-
-      # - uses: codecov/codecov-action@v5
-      #   if: matrix.python-version == 3.13
-      #   with:
-      #     fail_ci_if_error: true # optional (default = false)
-      #     files: ./reports/test-results.xml # optional
-      #     token: ${{ secrets.CODECOV_TOKEN }}
-
-      - name: Minimize uv cache
-        run: uv cache prune --ci
+  test:
+    uses: "./.github/workflows/pr.yml"
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   publish-package:
     name: "Build and Publish Python Package"
     runs-on: ubuntu-latest
-    needs: build-and-test
+    needs: test
 
     # set the environment based on what triggered the workflow
     environment:
@@ -79,7 +36,7 @@ jobs:
       - name: "Build package artifacts"
         run: uv build
 
-      # Logic for TestPyPI (on v3-dev branch push)
+      # Logic for TestPyPI (on main branch push)
       - name: "Publish to TestPyPI"
         if: ${{ github.ref_type == 'branch' }}
         run: uv publish --index test

src/specklepy/api/resources/current/active_user_resource.py

@@ -11,7 +11,11 @@ from specklepy.core.api.models import (
     ResourceCollection,
     User,
 )
-from specklepy.core.api.models.current import PermissionCheckResult, Workspace
+from specklepy.core.api.models.current import (
+    PermissionCheckResult,
+    ProjectWithPermissions,
+    Workspace,
+)
 from specklepy.core.api.resources import ActiveUserResource as CoreResource
 from specklepy.logging import metrics
 
@@ -51,6 +55,22 @@ class ActiveUserResource(CoreResource):
         metrics.track(metrics.SDK, self.account, {"name": "Active User Get Projects"})
         return super().get_projects(limit=limit, cursor=cursor, filter=filter)
 
+    def get_projects_with_permissions(
+        self,
+        *,
+        limit: int = 25,
+        cursor: Optional[str] = None,
+        filter: Optional[UserProjectsFilter] = None,
+    ) -> ResourceCollection[ProjectWithPermissions]:
+        metrics.track(
+            metrics.SDK,
+            self.account,
+            {"name": "Active User Get Projects With Permissions"},
+        )
+        return super().get_projects_with_permissions(
+            limit=limit, cursor=cursor, filter=filter
+        )
+
     def get_project_invites(self) -> List[PendingStreamCollaborator]:
         metrics.track(
             metrics.SDK, self.account, {"name": "Active User Get Project Invites"}

src/specklepy/api/resources/current/project_resource.py

@@ -7,7 +7,11 @@ from specklepy.core.api.inputs.project_inputs import (
     ProjectUpdateRoleInput,
     WorkspaceProjectCreateInput,
 )
-from specklepy.core.api.models import Project, ProjectWithModels, ProjectWithTeam
+from specklepy.core.api.models import (
+    Project,
+    ProjectWithModels,
+    ProjectWithTeam,
+)
 from specklepy.core.api.models.current import ProjectPermissionChecks
 from specklepy.core.api.resources import ProjectResource as CoreResource
 from specklepy.logging import metrics

src/specklepy/api/resources/current/workspace_resource.py

@@ -1,7 +1,12 @@
 from typing import Optional
 
 from specklepy.core.api.inputs.project_inputs import WorksaceProjectsFilter
-from specklepy.core.api.models.current import Project, ResourceCollection, Workspace
+from specklepy.core.api.models.current import (
+    Project,
+    ProjectWithPermissions,
+    ResourceCollection,
+    Workspace,
+)
 from specklepy.core.api.resources import WorkspaceResource as CoreResource
 from specklepy.logging import metrics
 
@@ -30,3 +35,19 @@ class WorkspaceResource(CoreResource):
     ) -> ResourceCollection[Project]:
         metrics.track(metrics.SDK, self.account, {"name": "Workspace Get Projects"})
         return super().get_projects(workspace_id, limit, cursor, filter)
+
+    def get_projects_with_permissions(
+        self,
+        workspace_id: str,
+        limit: int = 25,
+        cursor: Optional[str] = None,
+        filter: Optional[WorksaceProjectsFilter] = None,
+    ) -> ResourceCollection[ProjectWithPermissions]:
+        metrics.track(
+            metrics.SDK,
+            self.account,
+            {"name": "Workspace Get Projects With Permissions"},
+        )
+        return super().get_projects_with_permissions(
+            workspace_id, limit, cursor, filter
+        )

src/specklepy/core/api/enums.py

@@ -10,9 +10,6 @@ class ProjectVisibility(str, Enum):
     WORKSPACE = "WORKSPACE"
 
 
-foo = ProjectVisibility.PRIVATE
-
-
 class UserProjectsUpdatedMessageType(str, Enum):
     ADDED = "ADDED"
     REMOVED = "REMOVED"

src/specklepy/core/api/models/__init__.py

@@ -8,6 +8,7 @@ from specklepy.core.api.models.current import (
     ProjectCollaborator,
     ProjectCommentCollection,
     ProjectWithModels,
+    ProjectWithPermissions,
     ProjectWithTeam,
     ResourceCollection,
     ServerConfiguration,
@@ -39,6 +40,7 @@ __all__ = [
     "ModelWithVersions",
     "Project",
     "ProjectWithModels",
+    "ProjectWithPermissions",
     "ProjectWithTeam",
     "ProjectCommentCollection",
     "UserSearchResultCollection",

src/specklepy/core/api/models/current.py

@@ -176,6 +176,10 @@ class ProjectWithModels(Project):
     models: ResourceCollection[Model]
 
 
+class ProjectWithPermissions(Project):
+    permissions: ProjectPermissionChecks
+
+
 class ProjectWithTeam(Project):
     invited_team: List[PendingStreamCollaborator]
     team: List[ProjectCollaborator]

src/specklepy/core/api/resources/current/active_user_resource.py

@@ -13,7 +13,11 @@ from specklepy.core.api.models import (
     ResourceCollection,
     User,
 )
-from specklepy.core.api.models.current import PermissionCheckResult, Workspace
+from specklepy.core.api.models.current import (
+    PermissionCheckResult,
+    ProjectWithPermissions,
+    Workspace,
+)
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 from specklepy.logging.exceptions import GraphQLException
@@ -338,3 +342,84 @@ class ActiveUserResource(ResourceBase):
             )
 
         return response.data.data
+
+    def get_projects_with_permissions(
+        self,
+        *,
+        limit: int = 25,
+        cursor: Optional[str] = None,
+        filter: Optional[UserProjectsFilter] = None,
+    ) -> ResourceCollection[ProjectWithPermissions]:
+        """
+        Gets the currently active user's projects with their permissions.
+        This is useful for checking what actions can be performed on each project.
+        """
+        QUERY = gql(
+            """
+          query User($limit : Int!, $cursor: String, $filter: UserProjectsFilter) {
+            data:activeUser {
+              data:projects(limit: $limit, cursor: $cursor, filter: $filter) {
+                totalCount
+                cursor
+                items {
+                    id
+                    name
+                    description
+                    visibility
+                    allowPublicComments
+                    role
+                    createdAt
+                    updatedAt
+                    sourceApps
+                    workspaceId
+                    permissions {
+                      canCreateModel {
+                        code
+                        authorized
+                        message
+                      }
+                      canDelete {
+                        code
+                        authorized
+                        message
+                      }
+                      canLoad {
+                        code
+                        authorized
+                        message
+                      }
+                      canPublish {
+                        code
+                        authorized
+                        message
+                      }
+                    }
+                }
+              }
+            }
+          }
+          """
+        )
+
+        variables = {
+            "limit": limit,
+            "cursor": cursor,
+            "filter": filter.model_dump(warnings="error", by_alias=True)
+            if filter
+            else None,
+        }
+
+        response = self.make_request_and_parse_response(
+            DataResponse[
+                Optional[DataResponse[ResourceCollection[ProjectWithPermissions]]]
+            ],
+            QUERY,
+            variables,
+        )
+
+        if response.data is None:
+            raise GraphQLException(
+                "GraphQL response indicated that the ActiveUser could not be found"
+            )
+
+        return response.data.data

src/specklepy/core/api/resources/current/project_resource.py

@@ -9,7 +9,11 @@ from specklepy.core.api.inputs.project_inputs import (
     ProjectUpdateRoleInput,
     WorkspaceProjectCreateInput,
 )
-from specklepy.core.api.models import Project, ProjectWithModels, ProjectWithTeam
+from specklepy.core.api.models import (
+    Project,
+    ProjectWithModels,
+    ProjectWithTeam,
+)
 from specklepy.core.api.models.current import ProjectPermissionChecks
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse

src/specklepy/core/api/resources/current/workspace_resource.py

@@ -3,7 +3,12 @@ from typing import Optional
 from gql import gql
 
 from specklepy.core.api.inputs.project_inputs import WorksaceProjectsFilter
-from specklepy.core.api.models.current import Project, ResourceCollection, Workspace
+from specklepy.core.api.models.current import (
+    Project,
+    ProjectWithPermissions,
+    ResourceCollection,
+    Workspace,
+)
 from specklepy.core.api.resource import ResourceBase
 from specklepy.core.api.responses import DataResponse
 
@@ -104,3 +109,72 @@ class WorkspaceResource(ResourceBase):
         return self.make_request_and_parse_response(
             DataResponse[DataResponse[ResourceCollection[Project]]], QUERY, variables
         ).data.data
+
+    def get_projects_with_permissions(
+        self,
+        workspace_id: str,
+        limit: int = 25,
+        cursor: Optional[str] = None,
+        filter: Optional[WorksaceProjectsFilter] = None,
+    ) -> ResourceCollection[ProjectWithPermissions]:
+        QUERY = gql(
+            """
+            query Workspace($workspaceId: String!, $limit: Int!, $cursor: String, $filter: WorkspaceProjectsFilter) {
+              data:workspace(id: $workspaceId) {
+                data:projects(limit: $limit, cursor: $cursor, filter: $filter) {
+                  cursor
+                  items {
+                    allowPublicComments
+                    createdAt
+                    description
+                    id
+                    name
+                    role
+                    sourceApps
+                    updatedAt
+                    visibility
+                    workspaceId
+                    permissions {
+                      canCreateModel {
+                        code
+                        authorized
+                        message
+                      }
+                      canDelete {
+                        code
+                        authorized
+                        message
+                      }
+                      canLoad {
+                        code
+                        authorized
+                        message
+                      }
+                      canPublish {
+                        code
+                        authorized
+                        message
+                      }
+                    }
+                  }
+                  totalCount
+                }
+              }
+            }
+            """  # noqa: E501
+        )
+
+        variables = {
+            "workspaceId": workspace_id,
+            "limit": limit,
+            "cursor": cursor,
+            "filter": filter.model_dump(warnings="error", by_alias=True)
+            if filter
+            else None,
+        }
+
+        return self.make_request_and_parse_response(
+            DataResponse[DataResponse[ResourceCollection[ProjectWithPermissions]]],
+            QUERY,
+            variables,
+        ).data.data

tests/integration/client/current/test_active_user_resource_permissions.py

@@ -0,0 +1,85 @@
+import pytest
+
+from specklepy.api.client import SpeckleClient
+from specklepy.core.api.inputs.project_inputs import ProjectCreateInput
+from specklepy.core.api.inputs.user_inputs import UserProjectsFilter
+from specklepy.core.api.models.current import (
+    Project,
+    ProjectWithPermissions,
+    ResourceCollection,
+)
+
+
+@pytest.mark.run()
+class TestActiveUserResourcePermissions:
+    @pytest.fixture()
+    def test_project(self, client: SpeckleClient) -> Project:
+        project = client.project.create(
+            ProjectCreateInput(
+                name="test project for active user permissions",
+                description="test description",
+                visibility=None,
+            )
+        )
+        return project
+
+    def test_active_user_get_projects_with_permissions(
+        self, client: SpeckleClient, test_project: Project
+    ):
+        result = client.active_user.get_projects_with_permissions()
+
+        assert isinstance(result, ResourceCollection)
+        assert len(result.items) >= 1
+
+        test_project_with_permissions = None
+        for project in result.items:
+            if project.id == test_project.id:
+                test_project_with_permissions = project
+                break
+
+        assert test_project_with_permissions is not None
+        assert isinstance(test_project_with_permissions, ProjectWithPermissions)
+
+        assert hasattr(test_project_with_permissions, "permissions")
+        assert test_project_with_permissions.permissions is not None
+
+        assert test_project_with_permissions.id == test_project.id
+        assert test_project_with_permissions.name == test_project.name
+
+        permissions = test_project_with_permissions.permissions
+        assert hasattr(permissions, "can_create_model")
+        assert hasattr(permissions, "can_delete")
+        assert hasattr(permissions, "can_load")
+        assert hasattr(permissions, "can_publish")
+
+        assert permissions.can_create_model.authorized is True
+        assert permissions.can_delete.authorized is True
+        assert permissions.can_load.authorized is True
+        assert permissions.can_publish.authorized is True
+
+    def test_active_user_get_projects_with_permissions_with_filter(
+        self, client: SpeckleClient, test_project: Project
+    ):
+        """test getting active user's projects with permissions using a filter."""
+        filter = UserProjectsFilter(search=test_project.name)
+
+        result = client.active_user.get_projects_with_permissions(filter=filter)
+
+        assert isinstance(result, ResourceCollection)
+        assert len(result.items) >= 1
+        assert result.total_count >= 1
+
+        project_with_permissions = result.items[0]
+        assert isinstance(project_with_permissions, ProjectWithPermissions)
+        assert project_with_permissions.id == test_project.id
+
+        assert hasattr(project_with_permissions, "permissions")
+        assert project_with_permissions.permissions is not None
+
+    def test_active_user_projects_with_permissions_method_exists(
+        self, client: SpeckleClient
+    ):
+        """test that the method exists and is callable on active user resource."""
+        assert hasattr(client.active_user, "get_projects_with_permissions")
+        method = client.active_user.get_projects_with_permissions
+        assert callable(method)

tests/integration/client/current/test_workspace_resource_permissions.py

@@ -0,0 +1,19 @@
+import pytest
+
+from specklepy.api.client import SpeckleClient
+from specklepy.logging.exceptions import GraphQLException
+
+
+@pytest.mark.run()
+class TestWorkspaceResourcePermissions:
+    def test_get_projects_with_permissions(self, client: SpeckleClient):
+        with pytest.raises(GraphQLException):
+            client.workspace.get_projects_with_permissions("not a real id")
+
+    def test_get_projects_with_permissions_method_exists(self, client: SpeckleClient):
+        """
+        test that the method exists with the correct signature.
+        """
+        assert hasattr(client.workspace, "get_projects_with_permissions")
+        method = client.workspace.get_projects_with_permissions
+        assert callable(method)