test: add calendar sharing tests and update API docs

backend/tests/unit/v1/schedule_items/test_share.py

@@ -7,8 +7,10 @@ from uuid import UUID, uuid4
 
 import pytest
 from fastapi import HTTPException
+from sqlalchemy.exc import SQLAlchemyError
 
 from core.auth.models import CurrentUser
+from models.inbox_messages import InboxMessage, InboxMessageType
 from models.schedule_items import ScheduleItem
 from v1.auth.schemas import UserByEmailResponse
 from v1.schedule_items.repository import ScheduleItemRepository
@@ -72,6 +74,16 @@ class AuthGatewayStub:
         )
 
 
+class AuthGatewayInvalidIdStub:
+    async def get_user_by_email(self, email: str) -> UserByEmailResponse:
+        return UserByEmailResponse(
+            id="not-a-uuid",
+            email=email,
+            created_at="2026-02-28T10:00:00Z",
+            email_confirmed_at=None,
+        )
+
+
 @pytest.mark.asyncio
 async def test_share_forbidden_when_not_owner() -> None:
     owner_id = UUID("00000000-0000-0000-0000-000000000001")
@@ -99,3 +111,127 @@ async def test_share_forbidden_when_not_owner() -> None:
         )
 
     assert exc_info.value.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_share_success_creates_calendar_invitation_message() -> None:
+    owner_id = UUID("00000000-0000-0000-0000-000000000001")
+    item_id = uuid4()
+    session = AsyncMock()
+    session.add = MagicMock()
+    service = ScheduleItemService(
+        repository=cast(
+            ScheduleItemRepository,
+            ShareRepo(_build_item(item_id=item_id, owner_id=owner_id)),
+        ),
+        session=session,
+        current_user=CurrentUser(id=owner_id),
+        auth_gateway=AuthGatewayStub(),
+    )
+
+    result = await service.share(
+        item_id,
+        ScheduleItemShareRequest(
+            email="friend@example.com",
+            permission_view=True,
+            permission_edit=True,
+            permission_invite=False,
+        ),
+    )
+
+    assert result.message == "Calendar invitation sent"
+    session.add.assert_called_once()
+    message = session.add.call_args.args[0]
+    assert isinstance(message, InboxMessage)
+    assert message.sender_id == owner_id
+    assert message.schedule_item_id == item_id
+    assert message.message_type == InboxMessageType.CALENDAR
+    assert message.content == '{"permission": 5}'
+    session.commit.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_share_returns_not_found_when_item_missing() -> None:
+    requester_id = UUID("00000000-0000-0000-0000-000000000002")
+    service = ScheduleItemService(
+        repository=cast(ScheduleItemRepository, ShareRepo(None)),
+        session=AsyncMock(),
+        current_user=CurrentUser(id=requester_id),
+        auth_gateway=AuthGatewayStub(),
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        await service.share(
+            uuid4(),
+            ScheduleItemShareRequest(
+                email="friend@example.com",
+                permission_view=True,
+                permission_edit=False,
+                permission_invite=False,
+            ),
+        )
+
+    assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_share_invalid_auth_user_id_returns_503() -> None:
+    owner_id = UUID("00000000-0000-0000-0000-000000000001")
+    item_id = uuid4()
+    session = AsyncMock()
+    service = ScheduleItemService(
+        repository=cast(
+            ScheduleItemRepository,
+            ShareRepo(_build_item(item_id=item_id, owner_id=owner_id)),
+        ),
+        session=session,
+        current_user=CurrentUser(id=owner_id),
+        auth_gateway=AuthGatewayInvalidIdStub(),
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        await service.share(
+            item_id,
+            ScheduleItemShareRequest(
+                email="friend@example.com",
+                permission_view=True,
+                permission_edit=False,
+                permission_invite=False,
+            ),
+        )
+
+    assert exc_info.value.status_code == 503
+    assert exc_info.value.detail == "Auth lookup unavailable"
+    session.rollback.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_share_sqlalchemy_error_rolls_back() -> None:
+    owner_id = UUID("00000000-0000-0000-0000-000000000001")
+    item_id = uuid4()
+    session = AsyncMock()
+    session.add = MagicMock(side_effect=SQLAlchemyError("db error"))
+    service = ScheduleItemService(
+        repository=cast(
+            ScheduleItemRepository,
+            ShareRepo(_build_item(item_id=item_id, owner_id=owner_id)),
+        ),
+        session=session,
+        current_user=CurrentUser(id=owner_id),
+        auth_gateway=AuthGatewayStub(),
+    )
+
+    with pytest.raises(HTTPException) as exc_info:
+        await service.share(
+            item_id,
+            ScheduleItemShareRequest(
+                email="friend@example.com",
+                permission_view=True,
+                permission_edit=False,
+                permission_invite=False,
+            ),
+        )
+
+    assert exc_info.value.status_code == 503
+    assert exc_info.value.detail == "Schedule item store unavailable"
+    session.rollback.assert_awaited_once()