cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/google_workspace/__init__.py

@@ -0,0 +1,1033 @@
+"""
+Google Workspace connector for CortexDB.
+
+A compound connector that ingests data from three Google Workspace services
+— Gmail, Google Drive, and Google Calendar — into CortexDB as Episodes.
+Each sub-connector can be independently enabled or disabled.
+
+Uses ``google-api-python-client`` and ``google-auth`` for API access.
+Authenticates via a Google Service Account with domain-wide delegation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from datetime import datetime, timedelta, timezone
+from email.utils import parseaddr
+from pathlib import Path
+from typing import Any
+
+from cortexdb_connectors.base import (
+    Actor,
+    CortexConnector,
+    EntityRef,
+    Episode,
+    EpisodeType,
+    RawEvent,
+    Source,
+    Visibility,
+    VisibilityLevel,
+)
+
+logger = logging.getLogger(__name__)
+
+_SOURCE = Source(system="google_workspace")
+
+# Rate-limit: Google APIs enforce per-user and per-project quotas.
+# Default conservative delay between requests.
+_RATE_LIMIT_DELAY = 0.25
+_PAGE_SIZE = 100
+
+# ---------------------------------------------------------------------------
+# Sub-connector helpers (stateless — invoked by the main class)
+# ---------------------------------------------------------------------------
+
+
+class _GmailSubConnector:
+    """Fetches email threads from Gmail via the Gmail API v1."""
+
+    def __init__(
+        self,
+        delegated_user: str,
+        label_filter: list[str] | None = None,
+        backfill_days: int = 30,
+    ) -> None:
+        self.delegated_user = delegated_user
+        self.label_filter = label_filter or ["INBOX"]
+        self.backfill_days = backfill_days
+
+    async def fetch(
+        self,
+        credentials: Any,
+        since: datetime | None = None,
+    ) -> list[RawEvent]:
+        """Fetch email messages from Gmail."""
+        from googleapiclient.discovery import build
+
+        service = build("gmail", "v1", credentials=credentials)
+        events: list[RawEvent] = []
+
+        if since is None:
+            since = datetime.now(timezone.utc) - timedelta(days=self.backfill_days)
+
+        # Gmail query: after:YYYY/MM/DD
+        after_str = since.strftime("%Y/%m/%d")
+        query = f"after:{after_str}"
+        if self.label_filter:
+            label_query = " OR ".join(
+                f"label:{lbl}" for lbl in self.label_filter
+            )
+            query = f"({label_query}) {query}"
+
+        page_token: str | None = None
+        while True:
+            try:
+                kwargs: dict[str, Any] = {
+                    "userId": "me",
+                    "q": query,
+                    "maxResults": _PAGE_SIZE,
+                }
+                if page_token:
+                    kwargs["pageToken"] = page_token
+
+                result = await asyncio.to_thread(
+                    service.users().messages().list(**kwargs).execute
+                )
+            except Exception as exc:
+                logger.warning("Gmail list failed: %s", exc)
+                break
+
+            for msg_stub in result.get("messages", []):
+                msg_id = msg_stub["id"]
+                try:
+                    msg = await asyncio.to_thread(
+                        service.users()
+                        .messages()
+                        .get(userId="me", id=msg_id, format="metadata")
+                        .execute
+                    )
+                except Exception:
+                    logger.debug("Could not fetch Gmail message %s", msg_id)
+                    continue
+
+                raw = self._message_to_raw(msg)
+                events.append(raw)
+                await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+            page_token = result.get("nextPageToken")
+            if not page_token:
+                break
+            await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+        return events
+
+    def _message_to_raw(self, msg: dict[str, Any]) -> RawEvent:
+        """Transform a Gmail message into a ``RawEvent``."""
+        headers = {
+            h["name"].lower(): h["value"]
+            for h in msg.get("payload", {}).get("headers", [])
+        }
+        timestamp = self._parse_internal_date(msg.get("internalDate", "0"))
+        thread_id = msg.get("threadId", "")
+        labels = msg.get("labelIds", [])
+
+        sender_name, sender_email = parseaddr(headers.get("from", ""))
+        to_raw = headers.get("to", "")
+        cc_raw = headers.get("cc", "")
+
+        return RawEvent(
+            source="google_workspace:gmail",
+            external_id=f"gmail:{msg['id']}",
+            timestamp=timestamp,
+            data={
+                "_sub_source": "gmail",
+                "message_id": msg["id"],
+                "thread_id": thread_id,
+                "subject": headers.get("subject", "(no subject)"),
+                "from_name": sender_name,
+                "from_email": sender_email,
+                "to": to_raw,
+                "cc": cc_raw,
+                "snippet": msg.get("snippet", ""),
+                "labels": labels,
+                "size_estimate": msg.get("sizeEstimate", 0),
+            },
+            permissions={
+                "labels": labels,
+                "is_draft": "DRAFT" in labels,
+                "sender_email": sender_email,
+            },
+        )
+
+    @staticmethod
+    def _parse_internal_date(ms_str: str) -> datetime:
+        """Parse Gmail's internalDate (milliseconds since epoch)."""
+        try:
+            return datetime.fromtimestamp(int(ms_str) / 1000, tz=timezone.utc)
+        except (ValueError, OSError):
+            return datetime.now(timezone.utc)
+
+
+class _DriveSubConnector:
+    """Fetches document change events from Google Drive via the Drive API v3."""
+
+    def __init__(
+        self,
+        delegated_user: str,
+        shared_drives: list[str] | None = None,
+        backfill_days: int = 30,
+    ) -> None:
+        self.delegated_user = delegated_user
+        self.shared_drives = shared_drives or []
+        self.backfill_days = backfill_days
+        self._saved_start_page_token: str | None = None
+
+    async def fetch(
+        self,
+        credentials: Any,
+        since: datetime | None = None,
+    ) -> list[RawEvent]:
+        """Fetch recently modified files from Google Drive."""
+        from googleapiclient.discovery import build
+
+        service = build("drive", "v3", credentials=credentials)
+        events: list[RawEvent] = []
+
+        if since is None:
+            since = datetime.now(timezone.utc) - timedelta(days=self.backfill_days)
+
+        modified_after = since.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        # Use files.list with modifiedTime filter for backfill/incremental.
+        query = (
+            f"modifiedTime > '{modified_after}' "
+            "and trashed = false"
+        )
+
+        page_token: str | None = None
+        while True:
+            try:
+                kwargs: dict[str, Any] = {
+                    "q": query,
+                    "pageSize": _PAGE_SIZE,
+                    "fields": (
+                        "nextPageToken,"
+                        "files(id,name,mimeType,modifiedTime,createdTime,"
+                        "owners,lastModifyingUser,shared,sharingUser,"
+                        "parents,webViewLink,size,driveId)"
+                    ),
+                    "orderBy": "modifiedTime desc",
+                    "supportsAllDrives": True,
+                    "includeItemsFromAllDrives": True,
+                }
+                if page_token:
+                    kwargs["pageToken"] = page_token
+
+                result = await asyncio.to_thread(
+                    service.files().list(**kwargs).execute
+                )
+            except Exception as exc:
+                logger.warning("Drive files.list failed: %s", exc)
+                break
+
+            for f in result.get("files", []):
+                raw = self._file_to_raw(f)
+                events.append(raw)
+
+            page_token = result.get("nextPageToken")
+            if not page_token:
+                break
+            await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+        # Additionally fetch shared drive contents if configured.
+        for drive_id in self.shared_drives:
+            drive_events = await self._fetch_shared_drive(
+                service, drive_id, modified_after
+            )
+            events.extend(drive_events)
+
+        return events
+
+    async def _fetch_shared_drive(
+        self,
+        service: Any,
+        drive_id: str,
+        modified_after: str,
+    ) -> list[RawEvent]:
+        """Fetch files from a specific shared drive."""
+        events: list[RawEvent] = []
+        query = (
+            f"modifiedTime > '{modified_after}' "
+            "and trashed = false"
+        )
+        page_token: str | None = None
+
+        while True:
+            try:
+                kwargs: dict[str, Any] = {
+                    "q": query,
+                    "pageSize": _PAGE_SIZE,
+                    "fields": (
+                        "nextPageToken,"
+                        "files(id,name,mimeType,modifiedTime,createdTime,"
+                        "owners,lastModifyingUser,shared,sharingUser,"
+                        "parents,webViewLink,size,driveId)"
+                    ),
+                    "driveId": drive_id,
+                    "corpora": "drive",
+                    "supportsAllDrives": True,
+                    "includeItemsFromAllDrives": True,
+                }
+                if page_token:
+                    kwargs["pageToken"] = page_token
+
+                result = await asyncio.to_thread(
+                    service.files().list(**kwargs).execute
+                )
+            except Exception as exc:
+                logger.warning(
+                    "Drive shared-drive fetch failed for %s: %s", drive_id, exc
+                )
+                break
+
+            for f in result.get("files", []):
+                raw = self._file_to_raw(f, shared_drive_id=drive_id)
+                events.append(raw)
+
+            page_token = result.get("nextPageToken")
+            if not page_token:
+                break
+            await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+        return events
+
+    def _file_to_raw(
+        self,
+        f: dict[str, Any],
+        shared_drive_id: str | None = None,
+    ) -> RawEvent:
+        """Transform a Drive file metadata object into a ``RawEvent``."""
+        modified_time = f.get("modifiedTime", "")
+        timestamp = self._parse_iso(modified_time)
+
+        last_modifier = f.get("lastModifyingUser", {})
+        owners = f.get("owners", [])
+        owner = owners[0] if owners else {}
+
+        return RawEvent(
+            source="google_workspace:drive",
+            external_id=f"drive:{f['id']}:{modified_time}",
+            timestamp=timestamp,
+            data={
+                "_sub_source": "drive",
+                "file_id": f["id"],
+                "name": f.get("name", ""),
+                "mime_type": f.get("mimeType", ""),
+                "modified_time": modified_time,
+                "created_time": f.get("createdTime", ""),
+                "last_modifier_name": last_modifier.get("displayName", ""),
+                "last_modifier_email": last_modifier.get("emailAddress", ""),
+                "owner_name": owner.get("displayName", ""),
+                "owner_email": owner.get("emailAddress", ""),
+                "shared": f.get("shared", False),
+                "web_view_link": f.get("webViewLink", ""),
+                "size": f.get("size"),
+                "parents": f.get("parents", []),
+                "drive_id": f.get("driveId") or shared_drive_id,
+            },
+            permissions={
+                "shared": f.get("shared", False),
+                "owner_email": owner.get("emailAddress", ""),
+                "drive_id": f.get("driveId") or shared_drive_id,
+            },
+        )
+
+    @staticmethod
+    def _parse_iso(iso_str: str) -> datetime:
+        if not iso_str:
+            return datetime.now(timezone.utc)
+        cleaned = iso_str.replace("Z", "+00:00")
+        try:
+            return datetime.fromisoformat(cleaned)
+        except ValueError:
+            return datetime.now(timezone.utc)
+
+
+class _CalendarSubConnector:
+    """Fetches calendar events from Google Calendar API v3."""
+
+    def __init__(
+        self,
+        delegated_user: str,
+        calendar_ids: list[str] | None = None,
+        backfill_days: int = 30,
+    ) -> None:
+        self.delegated_user = delegated_user
+        self.calendar_ids = calendar_ids or ["primary"]
+        self.backfill_days = backfill_days
+
+    async def fetch(
+        self,
+        credentials: Any,
+        since: datetime | None = None,
+    ) -> list[RawEvent]:
+        """Fetch calendar events from specified calendars."""
+        from googleapiclient.discovery import build
+
+        service = build("calendar", "v3", credentials=credentials)
+        events: list[RawEvent] = []
+
+        if since is None:
+            since = datetime.now(timezone.utc) - timedelta(days=self.backfill_days)
+
+        time_min = since.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+        for calendar_id in self.calendar_ids:
+            cal_events = await self._fetch_calendar(
+                service, calendar_id, time_min
+            )
+            events.extend(cal_events)
+
+        return events
+
+    async def _fetch_calendar(
+        self,
+        service: Any,
+        calendar_id: str,
+        time_min: str,
+    ) -> list[RawEvent]:
+        """Fetch events from a single calendar."""
+        events: list[RawEvent] = []
+        page_token: str | None = None
+
+        while True:
+            try:
+                kwargs: dict[str, Any] = {
+                    "calendarId": calendar_id,
+                    "timeMin": time_min,
+                    "maxResults": _PAGE_SIZE,
+                    "singleEvents": True,
+                    "orderBy": "startTime",
+                }
+                if page_token:
+                    kwargs["pageToken"] = page_token
+
+                result = await asyncio.to_thread(
+                    service.events().list(**kwargs).execute
+                )
+            except Exception as exc:
+                logger.warning(
+                    "Calendar events.list failed for %s: %s",
+                    calendar_id,
+                    exc,
+                )
+                break
+
+            for event in result.get("items", []):
+                raw = self._event_to_raw(event, calendar_id)
+                events.append(raw)
+
+            page_token = result.get("nextPageToken")
+            if not page_token:
+                break
+            await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+        return events
+
+    def _event_to_raw(
+        self,
+        event: dict[str, Any],
+        calendar_id: str,
+    ) -> RawEvent:
+        """Transform a Calendar event into a ``RawEvent``."""
+        start = event.get("start", {})
+        start_time = start.get("dateTime") or start.get("date", "")
+        timestamp = self._parse_event_time(start_time)
+
+        organizer = event.get("organizer", {})
+        creator = event.get("creator", {})
+        attendees = event.get("attendees", [])
+
+        # Detect recurring events.
+        recurring_event_id = event.get("recurringEventId")
+
+        return RawEvent(
+            source="google_workspace:calendar",
+            external_id=f"calendar:{event.get('id', '')}",
+            timestamp=timestamp,
+            data={
+                "_sub_source": "calendar",
+                "event_id": event.get("id", ""),
+                "calendar_id": calendar_id,
+                "summary": event.get("summary", "(No title)"),
+                "description": event.get("description", ""),
+                "location": event.get("location", ""),
+                "start": start_time,
+                "end": (
+                    event.get("end", {}).get("dateTime")
+                    or event.get("end", {}).get("date", "")
+                ),
+                "status": event.get("status", "confirmed"),
+                "organizer_name": organizer.get("displayName", ""),
+                "organizer_email": organizer.get("email", ""),
+                "creator_name": creator.get("displayName", ""),
+                "creator_email": creator.get("email", ""),
+                "attendees": [
+                    {
+                        "email": a.get("email", ""),
+                        "name": a.get("displayName", ""),
+                        "response": a.get("responseStatus", "needsAction"),
+                        "organizer": a.get("organizer", False),
+                    }
+                    for a in attendees
+                ],
+                "attendee_count": len(attendees),
+                "hangout_link": event.get("hangoutLink", ""),
+                "conference_data": event.get("conferenceData"),
+                "recurring_event_id": recurring_event_id,
+                "visibility": event.get("visibility", "default"),
+            },
+            permissions={
+                "visibility": event.get("visibility", "default"),
+                "organizer_email": organizer.get("email", ""),
+                "attendee_emails": [a.get("email", "") for a in attendees],
+            },
+        )
+
+    @staticmethod
+    def _parse_event_time(time_str: str) -> datetime:
+        """Parse a Calendar event start time (dateTime or date)."""
+        if not time_str:
+            return datetime.now(timezone.utc)
+        try:
+            # dateTime format: 2026-03-15T10:00:00-07:00
+            cleaned = time_str.replace("Z", "+00:00")
+            return datetime.fromisoformat(cleaned)
+        except ValueError:
+            pass
+        try:
+            # date format: 2026-03-15 (all-day events)
+            return datetime.strptime(time_str, "%Y-%m-%d").replace(
+                tzinfo=timezone.utc
+            )
+        except ValueError:
+            return datetime.now(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Main compound connector
+# ---------------------------------------------------------------------------
+
+
+class GoogleWorkspaceConnector(CortexConnector):
+    """Compound connector for Google Workspace (Gmail + Drive + Calendar).
+
+    Internally manages three sub-connectors that can be independently
+    enabled or disabled.  ``fetch_events()`` aggregates events from all
+    enabled sub-connectors into a single list.
+
+    Authenticates via a Google Service Account with domain-wide delegation.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB API.
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    service_account_key:
+        Path to a service-account JSON key file, **or** a base64-encoded
+        key string.
+    delegated_user:
+        The workspace user email to impersonate via domain-wide delegation.
+    gmail_enabled:
+        Enable Gmail sub-connector.
+    drive_enabled:
+        Enable Drive sub-connector.
+    calendar_enabled:
+        Enable Calendar sub-connector.
+    label_filter:
+        Gmail labels to filter (default: ``["INBOX"]``).
+    shared_drives:
+        List of shared Drive IDs to include.
+    calendar_ids:
+        List of calendar IDs to sync (default: ``["primary"]``).
+    namespace:
+        CortexDB namespace for ingested episodes.
+    tenant_id:
+        CortexDB tenant identifier.
+    backfill_days:
+        Days of history for initial sync.
+    """
+
+    connector_name: str = "google_workspace"
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        service_account_key: str,
+        delegated_user: str,
+        gmail_enabled: bool = True,
+        drive_enabled: bool = True,
+        calendar_enabled: bool = True,
+        label_filter: list[str] | None = None,
+        shared_drives: list[str] | None = None,
+        calendar_ids: list[str] | None = None,
+        namespace: str = "google_workspace",
+        tenant_id: str = "default",
+        backfill_days: int = 30,
+    ) -> None:
+        super().__init__(cortex_url, cortex_api_key, tenant_id)
+        self.service_account_key = service_account_key
+        self.delegated_user = delegated_user
+        self.gmail_enabled = gmail_enabled
+        self.drive_enabled = drive_enabled
+        self.calendar_enabled = calendar_enabled
+        self.namespace = namespace
+        self.backfill_days = backfill_days
+
+        # Initialize sub-connectors.
+        self._gmail = _GmailSubConnector(
+            delegated_user=delegated_user,
+            label_filter=label_filter,
+            backfill_days=backfill_days,
+        ) if gmail_enabled else None
+
+        self._drive = _DriveSubConnector(
+            delegated_user=delegated_user,
+            shared_drives=shared_drives,
+            backfill_days=backfill_days,
+        ) if drive_enabled else None
+
+        self._calendar = _CalendarSubConnector(
+            delegated_user=delegated_user,
+            calendar_ids=calendar_ids,
+            backfill_days=backfill_days,
+        ) if calendar_enabled else None
+
+    # -- authentication ------------------------------------------------------
+
+    def _build_credentials(self, scopes: list[str]) -> Any:
+        """Build Google credentials from a service account key.
+
+        Supports both a file path and a base64-encoded JSON string.
+        """
+        from google.oauth2 import service_account
+
+        key_data = self._load_key_data()
+        creds = service_account.Credentials.from_service_account_info(
+            key_data,
+            scopes=scopes,
+        )
+        return creds.with_subject(self.delegated_user)
+
+    def _load_key_data(self) -> dict[str, Any]:
+        """Load service account key from file path or base64 string."""
+        key_str = self.service_account_key.strip()
+
+        # Try as file path first.
+        key_path = Path(key_str)
+        if key_path.is_file():
+            with open(key_path) as fh:
+                return json.load(fh)
+
+        # Try as base64-encoded JSON.
+        try:
+            decoded = base64.b64decode(key_str)
+            return json.loads(decoded)
+        except Exception:
+            pass
+
+        # Try as raw JSON string.
+        try:
+            return json.loads(key_str)
+        except Exception:
+            raise ValueError(
+                "service_account_key must be a file path, base64 string, "
+                "or raw JSON string"
+            )
+
+    # -- CortexConnector interface -------------------------------------------
+
+    async def fetch_events(
+        self, since: datetime | None = None,
+    ) -> list[RawEvent]:
+        """Aggregate events from all enabled Google Workspace sub-connectors."""
+        events: list[RawEvent] = []
+
+        if self._gmail:
+            gmail_scopes = ["https://www.googleapis.com/auth/gmail.readonly"]
+            creds = self._build_credentials(gmail_scopes)
+            try:
+                gmail_events = await self._gmail.fetch(creds, since)
+                events.extend(gmail_events)
+                logger.info("Gmail: fetched %d events", len(gmail_events))
+            except Exception as exc:
+                logger.error("Gmail fetch failed: %s", exc)
+
+        if self._drive:
+            drive_scopes = ["https://www.googleapis.com/auth/drive.readonly"]
+            creds = self._build_credentials(drive_scopes)
+            try:
+                drive_events = await self._drive.fetch(creds, since)
+                events.extend(drive_events)
+                logger.info("Drive: fetched %d events", len(drive_events))
+            except Exception as exc:
+                logger.error("Drive fetch failed: %s", exc)
+
+        if self._calendar:
+            cal_scopes = [
+                "https://www.googleapis.com/auth/calendar.readonly",
+            ]
+            creds = self._build_credentials(cal_scopes)
+            try:
+                cal_events = await self._calendar.fetch(creds, since)
+                events.extend(cal_events)
+                logger.info("Calendar: fetched %d events", len(cal_events))
+            except Exception as exc:
+                logger.error("Calendar fetch failed: %s", exc)
+
+        return events
+
+    def normalize(self, raw: RawEvent) -> Episode:
+        """Route normalization to the appropriate sub-connector handler."""
+        sub_source = raw.data.get("_sub_source", "")
+        if sub_source == "gmail":
+            return self._normalize_gmail(raw)
+        if sub_source == "drive":
+            return self._normalize_drive(raw)
+        if sub_source == "calendar":
+            return self._normalize_calendar(raw)
+        raise ValueError(f"Unknown sub-source: {sub_source!r}")
+
+    def map_permissions(self, raw: RawEvent) -> Visibility:
+        """Route permission mapping to the appropriate sub-connector handler."""
+        sub_source = raw.data.get("_sub_source", "")
+        if sub_source == "gmail":
+            return self._map_gmail_permissions(raw)
+        if sub_source == "drive":
+            return self._map_drive_permissions(raw)
+        if sub_source == "calendar":
+            return self._map_calendar_permissions(raw)
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- Gmail normalization -------------------------------------------------
+
+    def _normalize_gmail(self, raw: RawEvent) -> Episode:
+        """Normalize a Gmail message into a CortexDB Episode."""
+        data = raw.data
+        actor = Actor(
+            id=data.get("from_email", "unknown"),
+            name=data.get("from_name") or data.get("from_email", "unknown"),
+            email=data.get("from_email"),
+        )
+
+        subject = data.get("subject", "(no subject)")
+        snippet = data.get("snippet", "")
+        content = f"Subject: {subject}\n\n{snippet}" if snippet else subject
+
+        thread_id = data.get("thread_id")
+
+        entities: list[EntityRef] = []
+        # Sender entity.
+        if data.get("from_email"):
+            entities.append(
+                EntityRef(
+                    entity_type="contact",
+                    entity_id=data["from_email"],
+                    display_name=data.get("from_name", data["from_email"]),
+                )
+            )
+        # Thread entity.
+        if thread_id:
+            entities.append(
+                EntityRef(
+                    entity_type="thread",
+                    entity_id=thread_id,
+                    display_name=subject,
+                )
+            )
+        # Label entities.
+        for label in data.get("labels", []):
+            entities.append(
+                EntityRef(
+                    entity_type="label",
+                    entity_id=label,
+                    display_name=label,
+                )
+            )
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.MESSAGE,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace=self.namespace,
+            entities=entities,
+            tags=["google_workspace", "gmail"],
+            metadata={
+                "sub_source": "gmail",
+                "subject": subject,
+                "to": data.get("to", ""),
+                "cc": data.get("cc", ""),
+                "labels": data.get("labels", []),
+                "size_estimate": data.get("size_estimate", 0),
+            },
+            thread_id=f"gmail:{thread_id}" if thread_id else None,
+            idempotency_key=raw.external_id,
+        )
+
+    @staticmethod
+    def _map_gmail_permissions(raw: RawEvent) -> Visibility:
+        """Map Gmail message visibility.
+
+        All emails are treated as PRIVATE to the mailbox owner by default.
+        Drafts are also PRIVATE.
+        """
+        perms = raw.permissions
+        sender = perms.get("sender_email", "")
+        return Visibility(
+            level=VisibilityLevel.PRIVATE,
+            allowed_principals=(sender,) if sender else (),
+        )
+
+    # -- Drive normalization -------------------------------------------------
+
+    def _normalize_drive(self, raw: RawEvent) -> Episode:
+        """Normalize a Drive file event into a CortexDB Episode."""
+        data = raw.data
+        modifier_name = data.get("last_modifier_name", "")
+        modifier_email = data.get("last_modifier_email", "")
+
+        actor = Actor(
+            id=modifier_email or data.get("owner_email", "unknown"),
+            name=modifier_name or data.get("owner_name", "unknown"),
+            email=modifier_email or data.get("owner_email"),
+        )
+
+        file_name = data.get("name", "Untitled")
+        mime_type = data.get("mime_type", "")
+        doc_type = self._mime_to_label(mime_type)
+        content = f"{doc_type}: {file_name}"
+
+        entities: list[EntityRef] = []
+        # File entity.
+        entities.append(
+            EntityRef(
+                entity_type="file",
+                entity_id=data.get("file_id", ""),
+                display_name=file_name,
+            )
+        )
+        # Owner entity.
+        if data.get("owner_email"):
+            entities.append(
+                EntityRef(
+                    entity_type="collaborator",
+                    entity_id=data["owner_email"],
+                    display_name=data.get("owner_name", data["owner_email"]),
+                )
+            )
+        # Drive entity.
+        drive_id = data.get("drive_id")
+        if drive_id:
+            entities.append(
+                EntityRef(
+                    entity_type="shared_drive",
+                    entity_id=drive_id,
+                    display_name=f"drive:{drive_id}",
+                )
+            )
+        # Folder entities.
+        for parent_id in data.get("parents", []):
+            entities.append(
+                EntityRef(
+                    entity_type="folder",
+                    entity_id=parent_id,
+                    display_name=parent_id,
+                )
+            )
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.DOCUMENT,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace=self.namespace,
+            entities=entities,
+            tags=["google_workspace", "drive", doc_type.lower().replace(" ", "_")],
+            metadata={
+                "sub_source": "drive",
+                "file_id": data.get("file_id", ""),
+                "file_name": file_name,
+                "mime_type": mime_type,
+                "doc_type": doc_type,
+                "shared": data.get("shared", False),
+                "web_view_link": data.get("web_view_link", ""),
+                "size": data.get("size"),
+                "created_time": data.get("created_time", ""),
+                "modified_time": data.get("modified_time", ""),
+            },
+            idempotency_key=raw.external_id,
+        )
+
+    @staticmethod
+    def _map_drive_permissions(raw: RawEvent) -> Visibility:
+        """Map Drive file visibility based on sharing state."""
+        perms = raw.permissions
+        if perms.get("shared"):
+            return Visibility(level=VisibilityLevel.ORGANIZATION)
+        owner = perms.get("owner_email", "")
+        return Visibility(
+            level=VisibilityLevel.PRIVATE,
+            allowed_principals=(owner,) if owner else (),
+        )
+
+    # -- Calendar normalization ----------------------------------------------
+
+    def _normalize_calendar(self, raw: RawEvent) -> Episode:
+        """Normalize a Calendar event into a CortexDB Episode."""
+        data = raw.data
+        organizer_name = data.get("organizer_name", "")
+        organizer_email = data.get("organizer_email", "")
+
+        actor = Actor(
+            id=organizer_email or data.get("creator_email", "unknown"),
+            name=organizer_name or data.get("creator_name", "unknown"),
+            email=organizer_email or data.get("creator_email"),
+        )
+
+        summary = data.get("summary", "(No title)")
+        description = data.get("description", "")
+        location = data.get("location", "")
+        attendee_count = data.get("attendee_count", 0)
+
+        content_parts = [summary]
+        if description:
+            content_parts.append(description[:500])
+        if location:
+            content_parts.append(f"Location: {location}")
+        content = "\n".join(content_parts)
+
+        entities: list[EntityRef] = []
+        # Calendar entity.
+        cal_id = data.get("calendar_id", "")
+        if cal_id:
+            entities.append(
+                EntityRef(
+                    entity_type="calendar",
+                    entity_id=cal_id,
+                    display_name=cal_id,
+                )
+            )
+        # Attendee entities.
+        for attendee in data.get("attendees", []):
+            if attendee.get("email"):
+                entities.append(
+                    EntityRef(
+                        entity_type="attendee",
+                        entity_id=attendee["email"],
+                        display_name=attendee.get("name", attendee["email"]),
+                    )
+                )
+        # Recurring event entity.
+        recurring_id = data.get("recurring_event_id")
+        if recurring_id:
+            entities.append(
+                EntityRef(
+                    entity_type="recurring_event",
+                    entity_id=recurring_id,
+                    display_name=summary,
+                )
+            )
+
+        # Thread ID: group recurring event instances together.
+        thread_id = None
+        if recurring_id:
+            thread_id = f"calendar:recurring:{recurring_id}"
+
+        tags = ["google_workspace", "calendar"]
+        if attendee_count > 5:
+            tags.append("large_meeting")
+        if data.get("hangout_link") or data.get("conference_data"):
+            tags.append("video_call")
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=EpisodeType.MEETING,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace=self.namespace,
+            entities=entities,
+            tags=tags,
+            metadata={
+                "sub_source": "calendar",
+                "event_id": data.get("event_id", ""),
+                "calendar_id": cal_id,
+                "start": data.get("start", ""),
+                "end": data.get("end", ""),
+                "status": data.get("status", "confirmed"),
+                "location": location,
+                "attendee_count": attendee_count,
+                "has_video_call": bool(
+                    data.get("hangout_link") or data.get("conference_data")
+                ),
+                "recurring_event_id": recurring_id,
+                "organizer_email": organizer_email,
+            },
+            thread_id=thread_id,
+            idempotency_key=raw.external_id,
+        )
+
+    @staticmethod
+    def _map_calendar_permissions(raw: RawEvent) -> Visibility:
+        """Map Calendar event visibility.
+
+        - ``public`` visibility -> ORGANIZATION
+        - ``private`` / ``confidential`` -> RESTRICTED with attendees
+        - default -> ORGANIZATION
+        """
+        perms = raw.permissions
+        vis = perms.get("visibility", "default")
+        if vis in ("private", "confidential"):
+            attendees = tuple(
+                e for e in perms.get("attendee_emails", []) if e
+            )
+            return Visibility(
+                level=VisibilityLevel.RESTRICTED,
+                allowed_principals=attendees,
+            )
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- helpers -------------------------------------------------------------
+
+    @staticmethod
+    def _mime_to_label(mime_type: str) -> str:
+        """Map a MIME type to a human-readable document type label."""
+        mime_map = {
+            "application/vnd.google-apps.document": "Google Doc",
+            "application/vnd.google-apps.spreadsheet": "Google Sheet",
+            "application/vnd.google-apps.presentation": "Google Slides",
+            "application/vnd.google-apps.form": "Google Form",
+            "application/vnd.google-apps.drawing": "Google Drawing",
+            "application/pdf": "PDF",
+            "image/": "Image",
+            "video/": "Video",
+            "audio/": "Audio",
+        }
+        for prefix, label in mime_map.items():
+            if mime_type.startswith(prefix):
+                return label
+        return "File"