Merge pull request #809 from cbcoutinho/feat/deck-webhook-presets

feat(webhooks): add Deck card sync preset with vector indexing

nextcloud_mcp_server/vector/webhook_parser.py

@@ -4,8 +4,9 @@ Maps Nextcloud webhook events to vector-sync DocumentTasks. The handler at
 ``/webhooks/nextcloud`` calls :func:`extract_document_task` and forwards any
 non-None result to the same processor send-stream the scanner uses.
 
-Currently scoped to file (note) events. Calendar / Tables events fall through
-to ``None`` for now; those parsers can be added in follow-up changes.
+Currently scoped to file (note) events and Deck card events. Calendar /
+Tables events fall through to ``None`` for now; those parsers can be added
+in follow-up changes.
 
 See ADR-010 for the design and ``webhook-testing-findings.md`` for real
 captured payloads.
@@ -22,6 +23,19 @@ _FILE_EVENT_CREATED = "OCP\\Files\\Events\\Node\\NodeCreatedEvent"
 _FILE_EVENT_WRITTEN = "OCP\\Files\\Events\\Node\\NodeWrittenEvent"
 _FILE_EVENT_BEFORE_DELETED = "OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent"
 
+_DECK_EVENT_CARD_CREATED = "OCA\\Deck\\Event\\CardCreatedEvent"
+_DECK_EVENT_CARD_UPDATED = "OCA\\Deck\\Event\\CardUpdatedEvent"
+_DECK_EVENT_CARD_DELETED = "OCA\\Deck\\Event\\CardDeletedEvent"
+_DECK_EVENT_BOARD_UPDATED = "OCA\\Deck\\Event\\BoardUpdatedEvent"
+
+_DECK_CARD_EVENTS = frozenset(
+    {
+        _DECK_EVENT_CARD_CREATED,
+        _DECK_EVENT_CARD_UPDATED,
+        _DECK_EVENT_CARD_DELETED,
+    }
+)
+
 # Matches paths inside any user's Notes folder ending in .md, e.g.
 # "/admin/files/Notes/Sub/Note.md" or "/alice/files/Notes/foo.md".
 _NOTES_PATH_RE = re.compile(r"^/[^/]+/files/Notes/.+\.md$")
@@ -50,6 +64,9 @@ def extract_document_task(payload: dict) -> DocumentTask | None:
     ):
         return _parse_file_event(event_class, event, user_id, time)
 
+    if event_class in _DECK_CARD_EVENTS or event_class == _DECK_EVENT_BOARD_UPDATED:
+        return _parse_deck_event(event_class, event, user_id, time)
+
     logger.debug("Ignoring webhook for unsupported event: %s", event_class)
     return None
 
@@ -85,3 +102,46 @@ def _parse_file_event(
         operation=operation,
         modified_at=time,
     )
+
+
+def _parse_deck_event(
+    event_class: str, event: dict, user_id: str, time: int
+) -> DocumentTask | None:
+    # BoardUpdatedEvent carries only ``boardId`` — there's no card identifier to
+    # index. Log delivery so we can confirm webhook arrival in the receiver
+    # logs, and let the polling scanner reconcile the affected cards.
+    if event_class == _DECK_EVENT_BOARD_UPDATED:
+        board_id = event.get("boardId")
+        logger.info(
+            "Deck board %s updated; polling scanner will reconcile cards",
+            board_id,
+        )
+        return None
+
+    card = event.get("card") or {}
+    card_id = card.get("id")
+    stack_id = card.get("stackId")
+
+    if card_id is None:
+        # Without an id we can't address Qdrant points; the polling scanner
+        # will pick the change up on its next pass.
+        logger.warning(
+            "Webhook %s missing card.id; falling back to scanner",
+            event_class,
+        )
+        return None
+
+    operation = "delete" if event_class == _DECK_EVENT_CARD_DELETED else "index"
+
+    # board_id is not part of the Card payload — processor.py falls back to
+    # iterating boards/stacks if it's missing, so we pass stack_id only.
+    metadata = {"stack_id": stack_id} if stack_id is not None else None
+
+    return DocumentTask(
+        user_id=user_id,
+        doc_id=str(card_id),
+        doc_type="deck_card",
+        operation=operation,
+        modified_at=time,
+        metadata=metadata,
+    )