feat(chat): add conversation sharing with SharePersistence and UI flow

Introduce a SharePersistence layer, share/unshare API endpoints, and a SQL-backed
implementation, and wire the React UI (ShareButton, ChatHistory, HistoryStore,
ConversationGuard) through a new shares API client so conversations can be
generated, fetched, and revoked via shareable links. Adds unit tests for share
persistence and SQL conversation handling.

Author: JakPing

package-lock.json

@@ -14,7 +14,14 @@
 from fastapi import FastAPI, HTTPException, Request, UploadFile, status
 from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse, RedirectResponse, StreamingResponse
+from fastapi.responses import (
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    Response,
+    StreamingResponse,
+)
 from fastapi.staticfiles import StaticFiles
 from pydantic import BaseModel
 
@@ -32,13 +39,19 @@
     ChatResponseUnion,
     ChunkedContent,
     ConfigResponse,
+    ConversationDetail,
+    ConversationMeta,
+    ConversationShareResponse,
     FeedbackConfig,
     FeedbackItem,
     FeedbackRequest,
     Image,
     ImageResponse,
     OAuth2ProviderConfig,
+    ShareConversationRequest,
 )
+from ragbits.chat.persistence.share import SharePersistence
+from ragbits.chat.persistence.sql import SQLHistoryPersistence
 from ragbits.core.audit.metrics import record_metric
 from ragbits.core.audit.metrics.base import MetricType
 from ragbits.core.audit.traces import trace
@@ -61,6 +74,7 @@ def __init__(
         debug_mode: bool = False,
         auth_backend: AuthenticationBackend | type[AuthenticationBackend] | str | None = None,
         theme_path: str | None = None,
+        share_persistence: SharePersistence | None = None,
     ) -> None:
         """
         Initialize the RagbitsAPI.
@@ -73,13 +87,15 @@ def __init__(
             debug_mode: Flag enabling debug tools in the default UI
             auth_backend: Authentication backend for user authentication. If None, no authentication required.
             theme_path: Path to a JSON file containing HeroUI theme configuration from heroui.com/themes
+            share_persistence: Optional share persistence for conversation sharing. Requires auth_backend.
         """
         self.chat_interface: ChatInterface = self._load_chat_interface(chat_interface)
         self.dist_dir = Path(ui_build_dir) if ui_build_dir else Path(__file__).parent / "ui-build"
         self.cors_origins = cors_origins or []
         self.debug_mode = debug_mode
         self.auth_backend = self._load_auth_backend(auth_backend)
         self.theme_path = Path(theme_path) if theme_path else None
+        self.share_persistence = share_persistence
 
         self.frontend_base_url = BASE_URL
 
@@ -269,6 +285,7 @@ async def config() -> JSONResponse:
                     oauth2_providers=oauth2_providers,
                 ),
                 supports_upload=self.chat_interface.upload_handler is not None,
+                sharing=self.share_persistence is not None,
             )
 
             return JSONResponse(content=config_response.model_dump())
@@ -301,12 +318,166 @@ async def theme() -> PlainTextResponse:
                 logger.error(f"Error serving theme: {e}")
                 raise HTTPException(status_code=500, detail="Error loading theme") from e
 
+        if self.share_persistence and self.auth_backend:
+            self._setup_share_routes()
+
         @self.app.get("/{full_path:path}", response_class=HTMLResponse)
         async def root() -> HTMLResponse:
             index_file = self.dist_dir / "index.html"
             with open(str(index_file)) as file:
                 return HTMLResponse(content=file.read())
 
+    def _setup_share_routes(self) -> None:  # noqa: PLR0915
+        """Register routes for conversation sharing. Requires auth_backend and share_persistence."""
+        share = self.share_persistence
+        assert share is not None  # noqa: S101
+
+        history_persistence = self.chat_interface.history_persistence
+        if not isinstance(history_persistence, SQLHistoryPersistence):
+            logger.warning("Share routes require SQLHistoryPersistence; sharing disabled.")
+            return
+
+        history: SQLHistoryPersistence = history_persistence
+
+        async def _require_user(request: Request) -> User:
+            user = await self.require_authenticated_user(request)
+            if not user:
+                raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Authentication required")
+            return user
+
+        async def _require_owner(conversation_id: str, user: User) -> None:
+            owner = await history.get_conversation_owner(conversation_id)
+            if owner != user.user_id:
+                raise HTTPException(status_code=404, detail="Conversation not found.")
+
+        def _recipient_identifiers(user: User) -> list[str]:
+            """Return all identifiers a user can be addressed by when sharing.
+
+            The share UI lowercases input, so recipients are stored lowercased.
+            We mirror that here to match whether the owner shared with a user_id,
+            a username, or an email.
+            """
+            ids: list[str] = []
+            seen: set[str] = set()
+            for raw in (user.user_id, user.username, user.email):
+                if not raw:
+                    continue
+                normalized = raw.strip().lower()
+                if normalized and normalized not in seen:
+                    seen.add(normalized)
+                    ids.append(normalized)
+            return ids
+
+        @self.app.get("/api/conversations")
+        async def list_conversations(request: Request) -> list[ConversationMeta]:
+            user = await _require_user(request)
+            owned = await history.list_conversations(user.user_id)
+            owned_ids = {c["id"] for c in owned}
+            shared_rows = await share.list_shared_with_me(_recipient_identifiers(user))
+            shared_rows = [r for r in shared_rows if r["conversation_id"] not in owned_ids]
+
+            all_ids = [c["id"] for c in owned] + [r["conversation_id"] for r in shared_rows]
+            summaries = await history.get_conversation_summaries(all_ids)
+
+            owned_metas = [
+                ConversationMeta(
+                    conversation_id=c["id"],
+                    created_at=str(c["created_at"]) if c["created_at"] else "",
+                    summary=summaries.get(c["id"]),
+                )
+                for c in owned
+            ]
+            shared_metas = [
+                ConversationMeta(
+                    conversation_id=r["conversation_id"],
+                    created_at=str(r["shared_at"]) if r["shared_at"] else "",
+                    summary=summaries.get(r["conversation_id"]),
+                    is_shared=True,
+                    shared_by=r["owner_id"],
+                )
+                for r in shared_rows
+            ]
+            return owned_metas + shared_metas
+
+        @self.app.get("/api/conversations/{conversation_id}")
+        async def get_conversation(request: Request, conversation_id: str) -> ConversationDetail:
+            user = await _require_user(request)
+            owner = await history.get_conversation_owner(conversation_id)
+            is_shared = False
+            shared_by: str | None = None
+            if owner == user.user_id:
+                pass
+            elif await share.can_access(conversation_id, _recipient_identifiers(user)):
+                is_shared = True
+                shared_by = owner
+            else:
+                raise HTTPException(status_code=404, detail="Conversation not found.")
+            interactions = await history.get_conversation_interactions(conversation_id)
+            return ConversationDetail(
+                conversation_id=conversation_id,
+                messages=interactions,
+                is_shared=is_shared,
+                shared_by=shared_by,
+            )
+
+        @self.app.delete("/api/conversations/{conversation_id}", status_code=204)
+        async def delete_conversation(request: Request, conversation_id: str) -> Response:
+            user = await _require_user(request)
+            await _require_owner(conversation_id, user)
+            await history.delete_conversation(conversation_id)
+            return Response(status_code=204)
+
+        @self.app.get("/api/conversations/{conversation_id}/shares")
+        async def list_shares(request: Request, conversation_id: str) -> list[ConversationShareResponse]:
+            user = await _require_user(request)
+            await _require_owner(conversation_id, user)
+            shares = await share.get_shares(conversation_id, user.user_id)
+            return [
+                ConversationShareResponse(
+                    recipient=s["recipient"],
+                    shared_at=str(s["shared_at"]) if s["shared_at"] else "",
+                )
+                for s in shares
+            ]
+
+        @self.app.put("/api/conversations/{conversation_id}/shares")
+        async def update_shares(
+            request: Request, conversation_id: str, body: ShareConversationRequest
+        ) -> list[ConversationShareResponse]:
+            user = await _require_user(request)
+            await _require_owner(conversation_id, user)
+            new_recipients = set(body.recipients)
+            existing = await share.get_shares(conversation_id, user.user_id)
+            existing_recipients = {s["recipient"] for s in existing}
+            to_add = list(new_recipients - existing_recipients)
+            to_remove = list(existing_recipients - new_recipients)
+            if to_remove:
+                await share.remove_shares(conversation_id, user.user_id, to_remove)
+            if to_add:
+                await share.set_shares(conversation_id, user.user_id, to_add)
+            updated = await share.get_shares(conversation_id, user.user_id)
+            return [
+                ConversationShareResponse(
+                    recipient=s["recipient"],
+                    shared_at=str(s["shared_at"]) if s["shared_at"] else "",
+                )
+                for s in updated
+            ]
+
+        @self.app.delete("/api/conversations/{conversation_id}/shares/{recipient:path}", status_code=204)
+        async def revoke_share(request: Request, conversation_id: str, recipient: str) -> Response:
+            user = await _require_user(request)
+            await _require_owner(conversation_id, user)
+            await share.remove_shares(conversation_id, user.user_id, [recipient])
+            return Response(status_code=204)
+
+        @self.app.delete("/api/shared/{conversation_id}", status_code=204)
+        async def dismiss_share(request: Request, conversation_id: str) -> Response:
+            user = await _require_user(request)
+            if not await share.hide_share(conversation_id, _recipient_identifiers(user)):
+                raise HTTPException(status_code=404, detail="Shared conversation not found.")
+            return Response(status_code=204)
+
     @staticmethod
     def _prepare_chat_context(
         request: ChatMessageRequest,

packages/ragbits-chat/src/ragbits/chat/api.py

@@ -907,3 +907,41 @@ class ConfigResponse(BaseModel):
     conversation_history: bool = Field(default=False, description="Flag to enable conversation history")
     show_usage: bool = Field(default=False, description="Flag to enable usage statistics")
     authentication: AuthenticationConfig = Field(..., description="Authentication configuration")
+    sharing: bool = Field(default=False, description="Flag to enable conversation sharing")
+
+
+# ---------------------------------------------------------------------------
+# Conversation sharing models
+# ---------------------------------------------------------------------------
+
+
+class ShareConversationRequest(BaseModel):
+    """Validated input for sharing a conversation."""
+
+    recipients: list[str] = Field(min_length=1, description="List of recipient identifiers (user IDs or emails)")
+
+
+class ConversationShareResponse(BaseModel):
+    """API response model for a single share recipient."""
+
+    recipient: str
+    shared_at: str
+
+
+class ConversationMeta(BaseModel):
+    """Conversation metadata returned in list endpoints."""
+
+    conversation_id: str
+    created_at: str
+    summary: str | None = None
+    is_shared: bool = False
+    shared_by: str | None = None
+
+
+class ConversationDetail(BaseModel):
+    """Full conversation detail including messages."""
+
+    conversation_id: str
+    messages: list[dict[str, Any]]
+    is_shared: bool = False
+    shared_by: str | None = None

packages/ragbits-chat/src/ragbits/chat/interface/types.py

@@ -1,3 +1,4 @@
 from ragbits.chat.persistence.base import HistoryPersistenceStrategy
+from ragbits.chat.persistence.share import SharePersistence
 
-__all__ = ["HistoryPersistenceStrategy"]
+__all__ = ["HistoryPersistenceStrategy", "SharePersistence"]