stapel-workspaces 0.3.1__tar.gz

stapel_workspaces-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usestapel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_workspaces-0.3.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: stapel-workspaces
+Version: 0.3.1
+Summary: Team workspaces and RBAC Django app for the Stapel framework
+License: MIT
+Keywords: django,stapel,workspaces,teams,rbac
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Provides-Extra: all
+Dynamic: license-file
+
+# stapel-workspaces
+
+[![CI](https://github.com/usestapel/stapel-workspaces/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-workspaces/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-workspaces/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-workspaces)
+
+> Team workspaces and RBAC — roles, invitations, membership, storage quotas
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-workspaces
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_workspaces',
+]
+```
+
+## Bus events
+
+### Emits
+| `workspace.created` | [schema](schemas/emits/workspace.created.json) |  |
+| `workspace.member_joined` | [schema](schemas/emits/workspace.member_joined.json) |  |
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_workspaces-0.3.1/README.md

@@ -0,0 +1,38 @@
+# stapel-workspaces
+
+[![CI](https://github.com/usestapel/stapel-workspaces/actions/workflows/ci.yml/badge.svg)](https://github.com/usestapel/stapel-workspaces/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/usestapel/stapel-workspaces/graph/badge.svg)](https://codecov.io/gh/usestapel/stapel-workspaces)
+
+> Team workspaces and RBAC — roles, invitations, membership, storage quotas
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps for building production-grade platforms.
+
+## Installation
+
+```bash
+pip install stapel-workspaces
+```
+
+## Quick start
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...
+    'stapel_workspaces',
+]
+```
+
+## Bus events
+
+### Emits
+| `workspace.created` | [schema](schemas/emits/workspace.created.json) |  |
+| `workspace.member_joined` | [schema](schemas/emits/workspace.member_joined.json) |  |
+
+### Consumes
+| `user.deleted` | [schema](schemas/consumes/user.deleted.json) |
+| `user.deletion_initiated` | [schema](schemas/consumes/user.deletion_initiated.json) |
+
+## License
+
+MIT — see [LICENSE](LICENSE)

stapel_workspaces-0.3.1/__init__.py

@@ -0,0 +1,54 @@
+"""Stapel Workspaces — team workspaces and RBAC Django app for Stapel.
+
+Public API (see ``__all__``):
+
+Service functions (``stapel_workspaces.services``):
+- ``create_workspace`` — create a workspace and seed the owner membership.
+- ``ensure_personal_workspace`` — get-or-create a user's personal workspace.
+- ``create_invitation`` — invite an email address to a workspace.
+- ``accept_invitation`` — resolve an invitation into a membership.
+
+comm Function provider (``stapel_workspaces.functions``):
+- ``CHECK_MEMBERSHIP`` — name of the ``workspaces.check_membership``
+  Function (call it via ``stapel_core.comm.call``).
+- ``check_membership`` — the provider itself.
+
+Events (``stapel_workspaces.events``):
+- ``EVENT_WORKSPACE_PERSONAL_CREATED`` — comm action name emitted when a
+  personal workspace is bootstrapped.
+
+GDPR:
+- ``WorkspacesGDPRProvider`` — export/delete provider for workspace data.
+
+Signal usage (``workspace_member_changed``) stays in ``stapel_core.signals``.
+
+All exports are lazily imported (PEP 562): importing ``stapel_workspaces``
+itself does not require Django to be configured.
+"""
+
+_EXPORTS = {
+    "create_workspace": ".services",
+    "ensure_personal_workspace": ".services",
+    "create_invitation": ".services",
+    "accept_invitation": ".services",
+    "CHECK_MEMBERSHIP": ".functions",
+    "check_membership": ".functions",
+    "EVENT_WORKSPACE_PERSONAL_CREATED": ".events",
+    "WorkspacesGDPRProvider": ".gdpr",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name):
+    if name in _EXPORTS:
+        import importlib
+
+        value = getattr(importlib.import_module(_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_workspaces-0.3.1/actions.py

@@ -0,0 +1,23 @@
+"""Action subscriptions of the workspaces module.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery).
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed."""
+    from .gdpr import WorkspacesGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    WorkspacesGDPRProvider().delete(user_id)
+    logger.info("workspaces data erased for deleted user %s", user_id)

stapel_workspaces-0.3.1/admin.py

@@ -0,0 +1,27 @@
+from django.contrib import admin
+
+from .models import Workspace, WorkspaceInvitation, WorkspaceMember
+
+
+@admin.register(Workspace)
+class WorkspaceAdmin(admin.ModelAdmin):
+    list_display = ["name", "slug", "type", "owner", "storage_used_bytes", "created_at"]
+    list_filter = ["type", "created_at"]
+    search_fields = ["name", "slug", "owner__email"]
+    readonly_fields = ["id", "created_at", "updated_at"]
+
+
+@admin.register(WorkspaceMember)
+class WorkspaceMemberAdmin(admin.ModelAdmin):
+    list_display = ["workspace", "user", "role", "invited_at", "accepted_at"]
+    list_filter = ["role"]
+    search_fields = ["workspace__name", "user__email"]
+    readonly_fields = ["id", "invited_at"]
+
+
+@admin.register(WorkspaceInvitation)
+class WorkspaceInvitationAdmin(admin.ModelAdmin):
+    list_display = ["workspace", "email", "role", "expires_at", "accepted_at", "revoked_at"]
+    list_filter = ["role", "accepted_at", "revoked_at"]
+    search_fields = ["workspace__name", "email"]
+    readonly_fields = ["id", "token", "created_at"]

stapel_workspaces-0.3.1/apps.py

@@ -0,0 +1,22 @@
+from django.apps import AppConfig
+
+
+class WorkspacesConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "stapel_workspaces"
+    label = 'workspaces'
+    verbose_name = "Stapel Workspaces"
+
+    def ready(self):
+        from stapel_core.gdpr import gdpr_registry
+        from .gdpr import WorkspacesGDPRProvider
+        gdpr_registry.register(WorkspacesGDPRProvider())
+
+        # Action subscriptions (in-process in a monolith, bus consumer in
+        # microservices — same code, transport chosen by STAPEL_COMM).
+        from . import actions  # noqa: F401
+
+        # Function providers (workspaces.check_membership). register() is
+        # idempotent — ready() may run more than once.
+        from . import functions
+        functions.register()

stapel_workspaces-0.3.1/conftest.py

@@ -0,0 +1,90 @@
+import uuid
+
+import pytest
+
+
+def pytest_configure(config):
+    from django.conf import settings
+
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.messages",
+                "django.contrib.admin",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_workspaces",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            APPEND_SLASH=False,
+            ROOT_URLCONF="stapel_workspaces.conftest_urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # In-memory bus — no Kafka/Redis broker needed
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            # Synchronous in-process comm: no outbox table needed, emitted
+            # actions reach in-process subscribers immediately.
+            STAPEL_COMM={
+                "ACTION_TRANSPORT": "inprocess",
+                "FUNCTION_TRANSPORT": "inprocess",
+                "OUTBOX_ENABLED": False,
+                "VALIDATE_SCHEMAS": True,
+            },
+            SERVICE_NAME="workspaces",
+            FRONTEND_URL="https://app.example.com",
+            # Skip migrations — create tables directly from models
+            MIGRATION_MODULES={
+                "users": None,
+                "workspaces": None,
+            },
+        )
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+
+    return APIClient()
+
+
+@pytest.fixture
+def user(db):
+    from stapel_core.django.users.models import User
+
+    return User.objects.create_user(
+        username=f"u-{uuid.uuid4().hex[:8]}",
+        email=f"{uuid.uuid4().hex[:8]}@example.com",
+        password="testpass-1234",
+    )
+
+
+@pytest.fixture
+def other_user(db):
+    from stapel_core.django.users.models import User
+
+    return User.objects.create_user(
+        username=f"u-{uuid.uuid4().hex[:8]}",
+        email=f"{uuid.uuid4().hex[:8]}@example.com",
+        password="testpass-1234",
+    )
+
+
+@pytest.fixture
+def authed_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client

stapel_workspaces-0.3.1/conftest_urls.py

@@ -0,0 +1,18 @@
+"""URL configuration used only during tests.
+
+Mounts the workspaces API at /workspaces/api/workspaces to match the test fixtures.
+Tests call paths without a trailing slash on the collection (/workspaces/api/workspaces)
+but with a slash before resource IDs (/workspaces/api/workspaces/{uuid}).
+Two separate includes cover both cases:
+  - path with '/' strips 'workspaces/api/workspaces/' → passes bare '{uuid}' to sub-patterns
+  - path without '/' strips 'workspaces/api/workspaces' → passes '' to sub-patterns (list)
+"""
+
+from django.urls import include, path
+
+urlpatterns = [
+    # Detail/invite routes: URL has slash before UUID, so this prefix strips correctly.
+    path("workspaces/api/workspaces/", include("stapel_workspaces.urls")),
+    # List/create route: URL has no trailing slash; this prefix matches and passes '' to sub-patterns.
+    path("workspaces/api/workspaces", include("stapel_workspaces.urls")),
+]

stapel_workspaces-0.3.1/dto.py

@@ -0,0 +1,141 @@
+"""Data Transfer Objects for workspaces API."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+from uuid import UUID
+
+
+@dataclass
+class WorkspaceResponse:
+    """Workspace details.
+
+    Attributes:
+        id: Workspace UUID. Example: 0192f...
+        name: Display name. Example: Acme Engineering
+        slug: URL-safe identifier. Example: acme-eng
+        type: Workspace category. Example: work
+        owner_id: Owner user UUID. Example: 0192a...
+        settings: Workspace settings JSON.
+        storage_used_bytes: Bytes currently stored.
+        storage_limit_bytes: Plan-determined cap.
+        member_count: Number of members.
+        my_role: Role of the requesting user. Example: owner
+        created_at: ISO 8601 creation time. Example: 2026-05-20T10:00:00Z
+        updated_at: ISO 8601 last update time. Example: 2026-05-20T10:00:00Z
+    """
+
+    id: UUID
+    name: str
+    slug: str
+    type: str
+    owner_id: UUID
+    settings: dict
+    storage_used_bytes: int
+    storage_limit_bytes: int
+    member_count: int
+    my_role: Optional[str]
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class WorkspaceListResponse:
+    workspaces: List[WorkspaceResponse] = field(default_factory=list)
+
+
+@dataclass
+class WorkspaceCreateRequest:
+    """Create-workspace payload.
+
+    Attributes:
+        name: Display name. Example: Acme Engineering
+        slug: URL-safe identifier (auto-generated when omitted). Example: acme-eng
+        type: personal or work. Example: work
+    """
+
+    name: str
+    slug: Optional[str] = None
+    type: str = "work"
+
+
+@dataclass
+class WorkspaceUpdateRequest:
+    name: Optional[str] = None
+    slug: Optional[str] = None
+    settings: Optional[dict] = None
+
+
+@dataclass
+class MemberResponse:
+    """Workspace member.
+
+    Attributes:
+        id: Membership UUID. Example: 0192...
+        workspace_id: Workspace UUID.
+        user_id: User UUID.
+        email: User email (best-effort, from JWT claim cache).
+        role: owner / admin / member / viewer. Example: admin
+        invited_at: ISO 8601 invite timestamp.
+        accepted_at: ISO 8601 acceptance timestamp; null while pending.
+        last_accessed_at: ISO 8601 last access; null if never accessed.
+    """
+
+    id: UUID
+    workspace_id: UUID
+    user_id: UUID
+    email: Optional[str]
+    role: str
+    invited_at: str
+    accepted_at: Optional[str]
+    last_accessed_at: Optional[str]
+
+
+@dataclass
+class MemberListResponse:
+    members: List[MemberResponse] = field(default_factory=list)
+
+
+@dataclass
+class MemberInviteRequest:
+    """Invite payload.
+
+    Attributes:
+        emails: One or more emails to invite. Example: ["alice@example.com"]
+        role: Role to grant on acceptance. Example: member
+    """
+
+    emails: List[str]
+    role: str = "member"
+
+
+@dataclass
+class MemberInviteResponse:
+    invitations: List["InvitationResponse"] = field(default_factory=list)
+
+
+@dataclass
+class InvitationResponse:
+    id: UUID
+    workspace_id: UUID
+    email: str
+    role: str
+    expires_at: str
+    accepted_at: Optional[str]
+    revoked_at: Optional[str]
+    created_at: str
+
+
+@dataclass
+class InvitationAcceptRequest:
+    """Accept an invite.
+
+    Attributes:
+        token: Invite token from the email link.
+    """
+
+    token: str
+
+
+@dataclass
+class MemberUpdateRequest:
+    role: str

stapel_workspaces-0.3.1/errors.py

@@ -0,0 +1,36 @@
+"""Custom error keys for the workspaces service."""
+
+from stapel_core.django.api.errors import ErrorKeysView, register_service_errors
+
+ERR_404_WORKSPACE_NOT_FOUND = "error.404.workspace_not_found"
+ERR_404_MEMBER_NOT_FOUND = "error.404.member_not_found"
+ERR_404_INVITATION_NOT_FOUND = "error.404.invitation_not_found"
+ERR_403_FORBIDDEN_WORKSPACE = "error.403.forbidden_workspace"
+ERR_403_LAST_OWNER = "error.403.last_owner_cannot_be_removed"
+ERR_400_SLUG_TAKEN = "error.400.workspace_slug_taken"
+ERR_400_ALREADY_MEMBER = "error.400.already_workspace_member"
+ERR_400_INVITATION_EXPIRED = "error.400.invitation_expired"
+ERR_400_INVITATION_ALREADY_USED = "error.400.invitation_already_used"
+ERR_400_INVITATION_REVOKED = "error.400.invitation_revoked"
+ERR_400_INVALID_ROLE = "error.400.invalid_role"
+
+WORKSPACES_ERRORS = {
+    ERR_404_WORKSPACE_NOT_FOUND: "Workspace not found",
+    ERR_404_MEMBER_NOT_FOUND: "Member not found in this workspace",
+    ERR_404_INVITATION_NOT_FOUND: "Invitation not found",
+    ERR_403_FORBIDDEN_WORKSPACE: "You do not have access to this workspace",
+    ERR_403_LAST_OWNER: "The last owner cannot be removed; transfer ownership first",
+    ERR_400_SLUG_TAKEN: "Workspace slug is already taken",
+    ERR_400_ALREADY_MEMBER: "User is already a member of this workspace",
+    ERR_400_INVITATION_EXPIRED: "Invitation has expired",
+    ERR_400_INVITATION_ALREADY_USED: "Invitation has already been used",
+    ERR_400_INVITATION_REVOKED: "Invitation has been revoked",
+    ERR_400_INVALID_ROLE: "Invalid role",
+}
+
+register_service_errors(WORKSPACES_ERRORS)
+
+
+class WorkspacesErrorKeysView(ErrorKeysView):
+    def get_service_errors(self):
+        return WORKSPACES_ERRORS

stapel_workspaces-0.3.1/events.py

@@ -0,0 +1,34 @@
+"""Events published by stapel-workspaces.
+
+Publishing goes through ``stapel_core.comm.emit`` (transactional outbox;
+in-process in a monolith, bus in microservices) — see services.py. The
+comm action name is ``workspace.personal.created``; its payload contract
+lives in schemas/emits/workspace.personal.created.json.
+"""
+from dataclasses import dataclass
+
+EVENT_WORKSPACE_PERSONAL_CREATED = "workspace.personal.created"
+
+# On the bus transport the topic is the action name. The old Kafka topic
+# ``stapel.workspaces.personal-created`` is retired; alias kept for any
+# importer still referencing the old name.
+TOPIC_WORKSPACE_PERSONAL_CREATED = EVENT_WORKSPACE_PERSONAL_CREATED
+
+
+@dataclass
+class WorkspacePersonalCreatedPayload:
+    """Payload for the workspace.personal.created event.
+
+    Fields:
+        user_id: UUID of the workspace owner.
+        workspace_id: UUID of the created personal workspace.
+    """
+
+    user_id: str
+    workspace_id: str
+
+
+EVENT_REGISTRY = {
+    EVENT_WORKSPACE_PERSONAL_CREATED: WorkspacePersonalCreatedPayload,
+    TOPIC_WORKSPACE_PERSONAL_CREATED: WorkspacePersonalCreatedPayload,
+}

stapel_workspaces-0.3.1/functions.py

@@ -0,0 +1,67 @@
+"""comm Function providers of the workspaces module.
+
+Other modules check membership by name — no import of this app, no HTTP
+client code (the transport is deployment configuration, see STAPEL_COMM):
+
+    from stapel_core.comm import call
+
+    result = call(
+        "workspaces.check_membership",
+        {"workspace_id": str(workspace_id), "user_id": str(user_id)},
+    )
+    # -> {"is_member": bool, "role": str | None}
+
+The provider mirrors the internal HTTP endpoint
+(:class:`stapel_workspaces.views.InternalMembershipView`): only *accepted*
+memberships count.
+"""
+
+from stapel_core.comm import register_function
+
+CHECK_MEMBERSHIP = "workspaces.check_membership"
+
+# Kept in sync with schemas/functions/workspaces.check_membership.json
+# (the schemas/ autoloader registers the file too; passing it here makes
+# validation work even without the autoloader).
+CHECK_MEMBERSHIP_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": CHECK_MEMBERSHIP,
+    "type": "object",
+    "required": ["workspace_id", "user_id"],
+    "properties": {
+        "workspace_id": {"type": "string", "format": "uuid"},
+        "user_id": {"type": "string", "format": "uuid"},
+    },
+    "additionalProperties": False,
+}
+
+
+def check_membership(payload: dict) -> dict:
+    """Provider for ``workspaces.check_membership``.
+
+    Payload: ``{"workspace_id": str, "user_id": str}``
+    Returns: ``{"is_member": bool, "role": str | None}``
+    """
+    from .models import WorkspaceMember
+
+    member = (
+        WorkspaceMember.objects.filter(
+            workspace_id=payload["workspace_id"],
+            user_id=payload["user_id"],
+            accepted_at__isnull=False,
+        )
+        .only("role")
+        .first()
+    )
+    if member is None:
+        return {"is_member": False, "role": None}
+    return {"is_member": True, "role": member.role}
+
+
+def register() -> None:
+    """Register this module's Function providers.
+
+    Idempotent: re-registering the *same* handler object is a no-op, so
+    AppConfig.ready() may run more than once without raising.
+    """
+    register_function(CHECK_MEMBERSHIP, check_membership, schema=CHECK_MEMBERSHIP_SCHEMA)