Add single-event refresh endpoint

Author: jpmelos

inbox/api/err.py

@@ -7,6 +7,12 @@
 
 class APIException(Exception):
     status_code = 500
+    message = "An internal error occurred."
+
+    def __init__(self, message: str | None = None) -> None:
+        if message is not None:
+            self.message = message
+        super().__init__(self.message)
 
 
 class InputError(APIException):

inbox/api/ns_api.py

@@ -77,7 +77,11 @@
     is_stale,
 )
 from inbox.crispin import writable_connection_pool
+from inbox.events.google import GoogleEventsProvider
 from inbox.events.ical import generate_rsvp, send_rsvp
+from inbox.events.microsoft.events_provider import (
+    MicrosoftEventsProvider,
+)
 from inbox.events.util import removed_participants
 from inbox.ignition import engine_manager
 from inbox.models import (
@@ -1206,6 +1210,48 @@ def event_read_api(public_id):  # type: ignore[no-untyped-def]  # noqa: ANN201
     return g.encoder.jsonify(event)
 
 
+@app.route("/events/<public_id>/refresh", methods=["POST"])
+def event_refresh_api(public_id):  # type: ignore[no-untyped-def]  # noqa: ANN201
+    """Re-fetch a single event from the calendar provider and update the DB."""
+    valid_public_id(public_id)
+    try:
+        local_event = (
+            g.db_session.query(Event)
+            .filter(
+                Event.namespace_id == g.namespace.id,
+                Event.public_id == public_id,
+                Event.deleted_at.is_(None),
+            )
+            .one()
+        )
+    except NoResultFound as exc:
+        raise NotFoundError(f"Couldn't find event id {public_id}") from exc
+
+    calendar = local_event.calendar
+    account = g.namespace.account
+
+    # Instantiate the right provider.
+    if account.provider == "gmail":
+        provider = GoogleEventsProvider(account.id, g.namespace.id)
+    elif account.provider == "microsoft":
+        provider = MicrosoftEventsProvider(account.id, g.namespace.id)
+    else:
+        raise APIException(f"Unsupported provider: {account.provider}")
+
+    refreshed_event = provider.fetch_single_event(
+        calendar.uid, local_event.uid, read_only=calendar.read_only
+    )
+    if refreshed_event is None:
+        raise NotFoundError(
+            f"Event {public_id} not found on the calendar provider"
+        )
+
+    local_event.update(refreshed_event)
+    g.db_session.commit()
+
+    return g.encoder.jsonify(local_event)
+
+
 @app.route("/events/<public_id>", methods=["PUT", "PATCH"])
 def event_update_api(public_id):  # type: ignore[no-untyped-def]  # noqa: ANN201
     g.parser.add_argument(

inbox/events/abstract.py

@@ -55,6 +55,24 @@ def sync_events(
         """
         raise NotImplementedError()
 
+    def fetch_single_event(
+        self, calendar_uid: str, event_uid: str, *, read_only: bool
+    ) -> Event | None:
+        """
+        Fetch a single event from the calendar provider.
+
+        Arguments:
+            calendar_uid: The calendar identifier.
+            event_uid: The event identifier.
+            read_only: Whether the event's calendar is read-only.
+
+        Returns:
+            An uncommitted `Event` instance, or `None` if the event was not
+                found on the provider.
+
+        """
+        return None
+
     @abc.abstractmethod
     def webhook_notifications_enabled(self, account: Account) -> bool:
         """

inbox/events/google.py

@@ -73,6 +73,38 @@ def sync_calendars(self) -> CalendarSyncResponse:
 
         return CalendarSyncResponse(deletes, updates)
 
+    def fetch_single_event(
+        self, calendar_uid: str, event_uid: str, *, read_only: bool
+    ) -> Event | None:
+        """
+        Fetch a single event from the Google Calendar API.
+
+        Arguments:
+            calendar_uid: The Google calendar identifier.
+            event_uid: The Google event identifier.
+            read_only: Whether the event's calendar is read-only.
+
+        Returns:
+            An uncommitted `Event` instance, or `None` if the event was not
+                found on the provider.
+
+        """
+        url = "https://www.googleapis.com/calendar/v3/calendars/{}/events/{}".format(
+            urllib.parse.quote(calendar_uid),
+            urllib.parse.quote(event_uid),
+        )
+        token = self._get_access_token()
+        response = requests.get(url, auth=OAuthRequestsWrapper(token))
+        if response.status_code == 401:
+            token = self._get_access_token(force_refresh=True)
+            response = requests.get(url, auth=OAuthRequestsWrapper(token))
+        if response.status_code == 404:
+            return None
+        response.raise_for_status()
+
+        raw_event = response.json()
+        return parse_event_response(raw_event, read_only)
+
     def sync_events(
         self,
         calendar_uid: str,

inbox/events/microsoft/events_provider.py

@@ -112,6 +112,37 @@ def sync_calendars(self) -> CalendarSyncResponse:
 
         return CalendarSyncResponse(deleted_uids, updates)
 
+    def fetch_single_event(
+        self, calendar_uid: str, event_uid: str, *, read_only: bool
+    ) -> Event | None:
+        """
+        Fetch a single event from the Microsoft Graph API.
+
+        Arguments:
+            calendar_uid: The calendar identifier (unused — Microsoft Graph
+                fetches events by ID across all calendars).
+            event_uid: The Microsoft Graph event identifier.
+            read_only: Whether the event's calendar is read-only.
+
+        Returns:
+            An uncommitted `Event` instance, or `None` if the event was not
+                found on the provider.
+
+        """
+        try:
+            raw_event = self.client.get_event(event_uid, fields=EVENT_FIELDS)
+        except MicrosoftGraphClientException as exc:
+            if exc.response is not None and exc.response.status_code == 404:
+                return None
+            raise
+        if not validate_event(raw_event):
+            self.log.warning(
+                "Invalid event from refresh",
+                raw_event=raw_event,
+            )
+            return None
+        return parse_event(raw_event, read_only=read_only)
+
     def sync_events(
         self,
         calendar_uid: str,

tests/api/test_events.py

@@ -1,4 +1,7 @@
 import json
+from unittest import mock
+
+import arrow
 
 from inbox.api.ns_api import API_VERSIONS
 from inbox.models import Calendar, Event
@@ -415,3 +418,93 @@ def test_api_filter(db, api_client, calendar, default_namespace):
     _filter = "calendar_id=0000000000000000000000000"
     events = api_client.get_data("/events?" + _filter)
     assert len(events) == 0
+
+
+# -- POST /events/<id>/refresh tests --
+
+
+def test_refresh_endpoint_updates_db(db, api_client, calendar):
+    """Refresh endpoint fetches from provider and updates the local DB."""
+    event = add_fake_event(
+        db.session,
+        calendar.namespace_id,
+        calendar=calendar,
+        title="Old Title",
+        description="Old description",
+    )
+    event.participants = [
+        {"email": "alice@example.com", "name": "Alice", "status": "noreply"}
+    ]
+    db.session.commit()
+
+    refreshed = Event.create(
+        uid=event.uid,
+        raw_data="{}",
+        title="New Title",
+        description="New description",
+        start=arrow.get(2025, 9, 15, 12, 0, 0),
+        end=arrow.get(2025, 9, 15, 13, 0, 0),
+        all_day=False,
+        busy=True,
+        read_only=False,
+        owner="Organizer <org@example.com>",
+        is_owner=True,
+        participants=[
+            {"email": "alice@example.com", "name": "Alice", "status": "yes"}
+        ],
+        status="confirmed",
+        source="local",
+    )
+
+    with mock.patch(
+        "inbox.api.ns_api.GoogleEventsProvider"
+    ) as mock_provider_cls:
+        mock_provider = mock_provider_cls.return_value
+        mock_provider.fetch_single_event.return_value = refreshed
+
+        resp = api_client.post_data(f"/events/{event.public_id}/refresh", {})
+
+    assert resp.status_code == 200
+
+    data = json.loads(resp.data)
+    assert data["title"] == "New Title"
+    assert data["description"] == "New description"
+    assert len(data["participants"]) == 1
+    assert data["participants"][0]["status"] == "yes"
+
+    # Verify the DB was updated.
+    db.session.refresh(event)
+    assert event.title == "New Title"
+    assert event.participants[0]["status"] == "yes"
+
+
+def test_refresh_endpoint_unknown_event(db, api_client, calendar):
+    """Refresh endpoint returns 404 for an unknown public_id."""
+    unknown_id = generate_public_id()
+    resp = api_client.post_data(f"/events/{unknown_id}/refresh", {})
+    assert resp.status_code == 404
+
+
+def test_refresh_endpoint_provider_returns_none(db, api_client, calendar):
+    """Refresh endpoint returns 404 when the provider can't find the event."""
+    event = add_fake_event(
+        db.session,
+        calendar.namespace_id,
+        calendar=calendar,
+        title="Existing Event",
+    )
+
+    with mock.patch(
+        "inbox.api.ns_api.GoogleEventsProvider"
+    ) as mock_provider_cls:
+        mock_provider = mock_provider_cls.return_value
+        mock_provider.fetch_single_event.return_value = None
+
+        resp = api_client.post_data(f"/events/{event.public_id}/refresh", {})
+
+    assert resp.status_code == 404
+
+    # Verify the DB record is NOT deleted.
+    db.session.refresh(event)
+    assert event.title == "Existing Event"
+    assert event.deleted_at is None