Align SDK with backend: retire org 'member' role, default workflow visibility to organization, document SSE ownership 404s

Three backend changes now live on staging, folded straight into the
unpublished 1.0.0 surface (no back-compat / SemVer handling, no version bump):

1. Org 'member' role retired — orgs are owner/admin only. Tighten the REQUEST
   side: organizations.invite() role default + type -> Literal["admin"]; and
   update_user_role() role -> Literal["admin"]. The backend now 422s
   role="member". Response/read models keep role: Optional[str] so historical
   'member' strings still parse. The auth.organizations(role=...) GET filter
   stays str | None.

2. Workflow visibility is org-level — workflows.create() default flips from
   'private' to 'organization' (a real client-side default change). 'private'
   no longer restricts a workflow to its creator; all four enum values
   (private|organization|public|system) are kept. List/filter params and the
   response visibility field are unchanged.

3. SSE / run-thread ownership now returns 404 (not found OR not owned by your
   org; identical 404, no existence leak). Infra already handles it:
   _streaming.py calls raise_for_status on the SSE connect, so listen() 404 ->
   NotFoundError (not StreamError, no reconnect loop). Docs-only additions on
   executions/composer/assistant listen|get_state|resume|cancel.

Tests: invite defaults to/sends admin; update_user_role sends admin; create
defaults to 'organization' and still accepts 'private'; SSE listen 404 ->
NotFoundError with no reconnect loop (executions + composer).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sezeryavuz

src/modulex/resources/assistant.py

@@ -80,6 +80,10 @@ def listen(
         Event types are carried in ``event.event`` (normalized from ``data['type']``).
         A ``user_input_request`` event means the run paused for HITL input — answer
         it with :meth:`resume`.
+
+        A 404 (``NotFoundError``) on connect means the chat/run was not found or is
+        not owned by your org — iterating the stream raises it rather than yielding
+        events (no reconnect loop, no existence leak).
         """
         return self._stream_sse(
             f"/assistant/chat/{chat_id}/listen/{run_id}",
@@ -99,6 +103,9 @@ async def resume(
 
         ``llm`` is required (the executor rebuilds the chat model on resume).
         Returns a NEW ``run_id``; re-subscribe with :meth:`listen` on that run.
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
         """
         body: dict[str, Any] = {
             "request_id": request_id,
@@ -120,7 +127,11 @@ async def status(self, chat_id: str, *, organization_id: str | None = None) -> A
         )
 
     async def cancel(self, chat_id: str, *, organization_id: str | None = None) -> AssistantCancelResponse:
-        """Cancel a running assistant run (also clears any pending HITL question)."""
+        """Cancel a running assistant run (also clears any pending HITL question).
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
         return AssistantCancelResponse.model_validate(
             await self._post(f"/assistant/chat/{chat_id}/cancel", organization_id=organization_id)
         )

src/modulex/resources/composer.py

@@ -90,6 +90,10 @@ def listen(
         Event types are carried in ``event.event`` (normalized from ``data['type']``).
         A ``user_input_request`` event means the run paused for HITL input — answer
         it with :meth:`resume`. See :data:`modulex.types.realtime.COMPOSER_EVENT_TYPES`.
+
+        A 404 (``NotFoundError``) on connect means the chat/run was not found or is
+        not owned by your org — iterating the stream raises it rather than yielding
+        events (no reconnect loop, no existence leak).
         """
         return self._stream_sse(
             f"/composer/chat/{composer_chat_id}/listen/{run_id}",
@@ -112,6 +116,9 @@ async def resume(
         ``llm`` is required in production (the executor rebuilds the chat model on
         resume); pass the same config used in :meth:`chat`. Returns a NEW ``run_id``;
         re-subscribe with :meth:`listen` on that run.
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
         """
         body: dict[str, Any] = {
             "request_id": request_id,
@@ -221,7 +228,11 @@ async def cancel(
         *,
         organization_id: str | None = None,
     ) -> ComposerCancelResponse:
-        """Cancel an in-progress composer chat run."""
+        """Cancel an in-progress composer chat run.
+
+        A 404 (``NotFoundError``) means the chat was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
         return ComposerCancelResponse.model_validate(
             await self._post(
                 f"/composer/chat/{composer_chat_id}/cancel",

src/modulex/resources/executions.py

@@ -71,7 +71,11 @@ async def run(
         )
 
     async def get_state(self, thread_id: str, *, organization_id: str | None = None) -> StateResponse:
-        """Return the current state of a workflow thread."""
+        """Return the current state of a workflow thread.
+
+        A 404 (``NotFoundError``) means the thread was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
         return StateResponse.model_validate(
             await self._get(f"/workflows/state/{thread_id}", organization_id=organization_id)
         )
@@ -87,7 +91,11 @@ async def resume(
         stream: bool = True,
         organization_id: str | None = None,
     ) -> ResumeResponse:
-        """Resume a paused workflow thread with the provided resume value."""
+        """Resume a paused workflow thread with the provided resume value.
+
+        A 404 (``NotFoundError``) means the thread was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
         body: dict[str, Any] = {
             "run_id": run_id,
             "resume_value": resume_value,
@@ -108,7 +116,11 @@ async def cancel(
         reason: str | None = None,
         organization_id: str | None = None,
     ) -> CancelResponse:
-        """Cancel an in-progress workflow run by its run ID."""
+        """Cancel an in-progress workflow run by its run ID.
+
+        A 404 (``NotFoundError``) means the run was not found or is not owned by
+        your org (identical 404 in both cases — no existence leak).
+        """
         body: dict[str, Any] = {}
         if reason is not None:
             body["reason"] = reason
@@ -125,6 +137,10 @@ def listen(self, run_id: str, *, organization_id: str | None = None) -> EventSou
 
         Event types are carried in ``event.event`` (normalized from ``data['type']``).
         See :data:`modulex.types.realtime.WORKFLOW_EVENT_TYPES`.
+
+        A 404 (``NotFoundError``) on connect means the run was not found or is not
+        owned by your org — iterating the stream raises it rather than yielding
+        events (no reconnect loop, no existence leak).
         """
         return self._stream_sse(f"/workflows/listen/{run_id}", organization_id=organization_id)
 

src/modulex/resources/organizations.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal
 
 from modulex._base import _BaseResource
 from modulex.types.organizations import (
@@ -37,11 +37,16 @@ async def invite(
         self,
         invited_email: str,
         *,
-        role: str = "member",
+        role: Literal["admin"] = "admin",
         invitation_message: str | None = None,
         organization_id: str | None = None,
     ) -> InviteResponse:
-        """Send an invitation email to a user to join the organization."""
+        """Send an invitation email to a user to join the organization.
+
+        Orgs are owner/admin only: the creator is ``owner`` and every invited user
+        is ``admin``. ``role`` must be ``"admin"`` (the default) — the ``"member"``
+        role has been retired and the backend rejects it with HTTP 422.
+        """
         body: dict[str, Any] = {"invited_email": invited_email, "role": role}
         if invitation_message is not None:
             body["invitation_message"] = invitation_message
@@ -134,11 +139,15 @@ async def update_user_role(
         self,
         org_id: str,
         user_id: str,
-        role: str,
+        role: Literal["admin"],
         *,
         organization_id: str | None = None,
     ) -> RoleUpdateResponse:
-        """Update the role of a user within an organization."""
+        """Update the role of a user within an organization.
+
+        ``role`` must be ``"admin"`` — the ``"member"`` role has been retired (orgs
+        are owner/admin only) and the backend rejects it with HTTP 422.
+        """
         return RoleUpdateResponse.model_validate(
             await self._put(
                 f"/organizations/{org_id}/users/{user_id}/role",

src/modulex/resources/workflows.py

@@ -28,12 +28,18 @@ async def create(
         tags: list[str] | None = None,
         category: str | None = None,
         status: str = "draft",
-        visibility: str = "private",
+        visibility: str = "organization",
         input: dict[str, Any] | None = None,
         config: dict[str, Any] | None = None,
         organization_id: str | None = None,
     ) -> WorkflowResponse:
-        """Create a new workflow from the given schema and metadata."""
+        """Create a new workflow from the given schema and metadata.
+
+        ``visibility`` defaults to ``"organization"`` (visible org-wide). The
+        ``"private"`` value no longer restricts a workflow to its creator — it now
+        behaves like ``"organization"``. All four values remain accepted:
+        ``private | organization | public | system``.
+        """
         body: dict[str, Any] = {
             "workflow_schema": workflow_schema,
             "status": status,

tests/test_organizations.py

@@ -52,3 +52,33 @@ async def test_set_composer_llm(self, client: Modulex, mock_api: respx.MockRoute
             "model_id": "gpt-4o-mini",
             "credential_id": "cred-1",
         }
+
+
+@pytest.mark.asyncio
+class TestOrganizationRoles:
+    """Org membership is owner/admin only — the ``member`` role was retired."""
+
+    async def test_invite_defaults_to_admin(self, client: Modulex, mock_api: respx.MockRouter) -> None:
+        route = mock_api.post("/organizations/invite").mock(
+            return_value=httpx.Response(200, json={"success": True, "invitation": {"id": "inv-1", "role": "admin"}})
+        )
+        await client.organizations.invite("newuser@example.com")
+        sent = _json.loads(route.calls.last.request.content)
+        assert sent["invited_email"] == "newuser@example.com"
+        assert sent["role"] == "admin"  # default is admin, never the retired "member"
+
+    async def test_invite_sends_admin_role(self, client: Modulex, mock_api: respx.MockRouter) -> None:
+        route = mock_api.post("/organizations/invite").mock(return_value=httpx.Response(200, json={"success": True}))
+        await client.organizations.invite("newuser@example.com", role="admin", invitation_message="welcome")
+        sent = _json.loads(route.calls.last.request.content)
+        assert sent["role"] == "admin"
+        assert sent["invitation_message"] == "welcome"
+
+    async def test_update_user_role_sends_admin(self, client: Modulex, mock_api: respx.MockRouter) -> None:
+        route = mock_api.put("/organizations/org-1/users/user-1/role").mock(
+            return_value=httpx.Response(200, json={"success": True, "new_role": "admin"})
+        )
+        result = await client.organizations.update_user_role("org-1", "user-1", "admin")
+        sent = _json.loads(route.calls.last.request.content)
+        assert sent == {"role": "admin"}
+        assert result["new_role"] == "admin"

tests/test_streaming.py

@@ -7,7 +7,7 @@
 import respx
 
 from modulex import Modulex
-from modulex._exceptions import AuthenticationError
+from modulex._exceptions import AuthenticationError, NotFoundError
 from modulex._streaming import SSEEvent
 
 _SSE_HEADERS = {"content-type": "text/event-stream"}
@@ -86,3 +86,25 @@ async def test_connect_error_is_typed(self, client: Modulex, mock_api: respx.Moc
         with pytest.raises(AuthenticationError):
             async for _ in client.executions.listen("run-1"):
                 pass
+
+    async def test_listen_ownership_404_raises_not_found(self, client: Modulex, mock_api: respx.MockRouter) -> None:
+        """A run not owned by your org returns 404 on connect → NotFoundError (no hang, no reconnect)."""
+        route = mock_api.get("/workflows/listen/run-x").mock(
+            return_value=httpx.Response(404, json={"detail": "Not found"})
+        )
+        with pytest.raises(NotFoundError):
+            async for _ in client.executions.listen("run-x"):
+                pass
+        assert route.call_count == 1  # NotFoundError, not a StreamError-driven reconnect loop
+
+    async def test_composer_listen_ownership_404_raises_not_found(
+        self, client: Modulex, mock_api: respx.MockRouter
+    ) -> None:
+        """Same ownership 404 contract holds for the composer/assistant listen family."""
+        route = mock_api.get("/composer/chat/chat-x/listen/run-x").mock(
+            return_value=httpx.Response(404, json={"detail": "Not found"})
+        )
+        with pytest.raises(NotFoundError):
+            async for _ in client.composer.listen("chat-x", "run-x"):
+                pass
+        assert route.call_count == 1

tests/test_workflows.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import json as _json
+
 import httpx
 import pytest
 import respx
@@ -80,6 +82,26 @@ async def test_create(self, client: Modulex, mock_api: respx.MockRouter) -> None
         )
         assert result["id"] == "wf-new"
 
+    async def test_create_defaults_visibility_to_organization(
+        self, client: Modulex, mock_api: respx.MockRouter
+    ) -> None:
+        """New workflows now default to org-wide visibility (was ``private``)."""
+        route = mock_api.post("/workflows").mock(
+            return_value=httpx.Response(201, json={"id": "wf-new", "name": "New Workflow"})
+        )
+        await client.workflows.create(workflow_schema={"nodes": [], "edges": []})
+        sent = _json.loads(route.calls.last.request.content)
+        assert sent["visibility"] == "organization"
+
+    async def test_create_accepts_private_visibility(self, client: Modulex, mock_api: respx.MockRouter) -> None:
+        """``private`` is still a valid value (one of the four kept enum values)."""
+        route = mock_api.post("/workflows").mock(
+            return_value=httpx.Response(201, json={"id": "wf-priv", "name": "Private WF"})
+        )
+        await client.workflows.create(workflow_schema={"nodes": [], "edges": []}, visibility="private")
+        sent = _json.loads(route.calls.last.request.content)
+        assert sent["visibility"] == "private"
+
     async def test_update(self, client: Modulex, mock_api: respx.MockRouter) -> None:
         mock_api.put("/workflows/wf-123").mock(
             return_value=httpx.Response(