Upload 91 files

server/Dockerfile

@@ -0,0 +1,40 @@
+# Use Python 3.11 slim image as base
+FROM python:3.11-slim
+
+ENV API_PORT=8004
+
+# Set working directory
+WORKDIR /app
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+  PYTHONUNBUFFERED=1 \
+  PYTHONPATH=/app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+  gcc \
+  && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+  pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create directory for database files
+RUN mkdir -p /app/mcp_databases
+
+# Expose port 8010
+EXPOSE 8004
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+  CMD python -c "import requests; requests.get('http://localhost:8004/health')" || exit 1
+
+# Run the application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8004"]

server/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Calendar server package."""

server/apis/acl/router.py

@@ -0,0 +1,236 @@
+"""
+ACL (Access Control List) API endpoints following Google Calendar API v3 structure.
+Handles CRUD operations for calendar access rules.
+"""
+
+import logging
+from typing import List, Optional
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from schemas.acl import ACLRule, ACLRuleInput, Channel, ACLWatchRequest, ACLListResponse, InsertACLRule, PatchACLRuleInput
+from database.managers.acl_manager import ACLManager, get_acl_manager
+from database.session_manager import CalendarSessionManager
+from middleware.auth import get_user_context
+from pydantic import ValidationError
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/calendars", tags=["acl"])
+session_manager = CalendarSessionManager()
+
+def get_acl_manager_instance(database_id: str, user_id: str) -> ACLManager:
+    session = session_manager.get_session(database_id)
+    return get_acl_manager(session, user_id)
+
+
+@router.get("/{calendarId}/acl", response_model=ACLListResponse, operation_id="list_acl_rules")
+def list_acl_rules(
+    calendarId: str,
+    maxResults: Optional[int] = Query(100, ge=1, le=250, description="Maximum number of entries returned on one result page"),
+    pageToken: Optional[str] = Query(None, description="Token specifying which result page to return"),
+    showDeleted: bool = Query(False, description="Whether to include deleted ACLs in the result"),
+    syncToken: Optional[str] = Query(None, description="Token for incremental synchronization"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+        
+        if not manager.validate_calendar_id(calendarId, user_id):
+            raise ValueError(f"Calendar {calendarId} not found for user {user_id}")
+        
+        # If syncToken is provided, showDeleted must be True (Google Calendar API behavior)
+        if syncToken and not showDeleted:
+            showDeleted = True
+            
+        result = manager.list_rules(
+            calendarId,
+            max_results=maxResults,
+            page_token=pageToken,
+            show_deleted=showDeleted,
+            sync_token=syncToken
+        )
+        return result
+    
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"{str(verr)}")
+    except HTTPException as he:
+        if he.status_code == 410:  # Handle sync token expiration
+            raise he
+        raise
+    except Exception as e:
+        logger.error(f"Error listing ACL rules: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.get("/{calendarId}/acl/{ruleId}", response_model=ACLRule, operation_id="get_acl_rule")
+def get_acl_rule(
+    calendarId: str,
+    ruleId: str,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+        rule = manager.get_rule(calendarId, ruleId)
+        if not rule:
+            raise HTTPException(status_code=404, detail="ACL rule not found")
+        return rule
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error retrieving ACL rule {ruleId}: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.post("/{calendarId}/acl", status_code=201, operation_id="insert_acl_rule")
+def insert_acl_rule(
+    calendarId: str,
+    rule: ACLRuleInput,
+    sendNotifications: bool = Query(True, description="Whether to send notifications about the calendar sharing change"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+
+        if not manager.validate_calendar_id(calendarId, user_id):
+            raise ValueError(f"Calendar {calendarId} not found for user {user_id}")
+
+        return manager.insert_rule(calendarId, rule, send_notifications=sendNotifications)
+    except ValueError as ve:
+        raise HTTPException(status_code=400, detail=str(ve))
+    except Exception as e:
+        logger.error(f"Error inserting ACL rule: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.put("/{calendarId}/acl/{ruleId}", operation_id="update_acl_rule")
+def update_acl_rule(
+    calendarId: str,
+    ruleId: str,
+    rule: ACLRuleInput,
+    sendNotifications: bool = Query(True, description="Whether to send notifications about the calendar sharing change"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+
+        if not manager.validate_calendar_id(calendarId, user_id):
+            raise ValueError(f"Calendar {calendarId} not found for user {user_id}")
+
+        updated = manager.update_rule(calendarId, ruleId, rule, send_notifications=sendNotifications)
+        if not updated:
+            raise ValueError(f"ACL rule not found")
+        return updated
+    except ValueError as ve:
+        raise HTTPException(status_code=400, detail=str(ve))
+    except Exception as e:
+        logger.error(f"Error updating ACL rule {ruleId}: {e}")
+        raise HTTPException(status_code=500, detail=f"An error occurred {e}")
+
+
+@router.patch("/{calendarId}/acl/{ruleId}", operation_id="patch_acl_rule")
+def patch_acl_rule(
+    calendarId: str,
+    ruleId: str,
+    rule: PatchACLRuleInput,
+    sendNotifications: bool = Query(True, description="Whether to send notifications about the calendar sharing change"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+        updated = manager.patch_rule(calendarId, ruleId, rule, sendNotifications)
+        if not updated:
+            raise ValueError(f"ACL rule not found")
+        return updated
+    except ValueError as ve:
+        raise HTTPException(status_code=400, detail=str(ve))
+    except Exception as e:
+        logger.error(f"Error patching ACL rule {ruleId}: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.delete("/{calendarId}/acl/{ruleId}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_acl_rule(
+    calendarId: str,
+    ruleId: str,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Deletes an ACL rule from the specified calendar.
+
+    DELETE /calendars/{calendarId}/acl/{ruleId}
+    """
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+
+        success = manager.delete_rule(calendarId, ruleId)
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"ACL rule '{ruleId}' not found for calendar '{calendarId}'"
+            )
+
+        return None  # 204 No Content
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting ACL rule {ruleId} from calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+@router.post("/{calendarId}/acl/watch", response_model=Channel, operation_id="watch_acl")
+def watch_acl(
+    calendarId: str,
+    watch_request: ACLWatchRequest,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Set up watch notifications for ACL changes on the specified calendar.
+
+    POST /calendars/{calendarId}/acl/watch
+    """
+    try:
+        database_id, user_id = user_context
+        manager = get_acl_manager_instance(database_id, user_id)
+        
+        # Log the received request for debugging
+        logger.info(f"Received watch request for calendar {calendarId}")
+        logger.debug(f"Watch request data: {watch_request}")
+
+        # Validate user exists in this database (ensures ownership context)
+        from database.session_utils import get_session
+        from database.models.user import User
+        session = get_session(database_id)
+        try:
+            user_row = session.query(User).filter(User.user_id == user_id).first()
+            if not user_row:
+                raise HTTPException(status_code=404, detail=f"User not found: {user_id}")
+        finally:
+            session.close()
+        
+        # Set up watch channel
+        channel = manager.watch_acl(user_id, calendarId, watch_request)
+        
+        return channel
+        
+    except ValidationError as e:
+        logger.error(f"Validation error for calendar {calendarId}: {e.errors()}")
+        validation_errors = []
+        for error in e.errors():
+            field = error.get('loc', ['unknown'])[0] if error.get('loc') else 'unknown'
+            message = error.get('msg', 'validation failed')
+            validation_errors.append(f"{field}: {message}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Validation errors: - {' - '.join(validation_errors)}"
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error setting up ACL watch for calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")

server/apis/calendarList/router.py

@@ -0,0 +1,802 @@
+"""
+CalendarList API endpoints following Google Calendar API v3 structure
+Handles user's calendar list operations with exact Google API compatibility
+"""
+
+import logging
+import re
+from typing import Optional, List
+import uuid
+from urllib.parse import urlencode, urlparse
+from datetime import datetime, timezone, timedelta
+from fastapi import APIRouter, HTTPException, Header, Query, status, Depends
+from schemas.calendar_list import (
+    CalendarListEntry,
+    CalendarListInsertRequest,
+    CalendarListUpdateRequest,
+    CalendarListResponse,
+    Channel,
+    WatchRequest,
+    CalendarListPatchRequest
+)
+from schemas.common import SuccessResponse
+from database.managers.calendar_list_manager import CalendarListManager
+from database.session_manager import CalendarSessionManager
+from utils.validation import validate_request_colors, validate_and_set_color_id, set_colors_from_color_id
+from middleware.auth import get_user_context
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/users/me/calendarList", tags=["calendarList"])
+
+# Initialize managers
+session_manager = CalendarSessionManager()
+
+
+def get_calendar_list_manager(database_id: str) -> CalendarListManager:
+    """Get calendar list manager for the specified database"""
+    return CalendarListManager(database_id)
+
+
+@router.get("", response_model=CalendarListResponse)
+async def get_calendar_list(
+    user_context: tuple[str, str] = Depends(get_user_context),
+    maxResults: Optional[int] = Query(
+        None,
+        gt=0,
+        le=250,
+        description="Maximum number of entries returned (0-250). If 0, returns no items."
+    ),
+    minAccessRole: Optional[str] = Query(
+        None,
+        description="Minimum access role filter",
+        regex="^(freeBusyReader|reader|writer|owner)$"
+    ),
+    pageToken: Optional[str] = Query(None, description="Token for pagination"),
+    showDeleted: Optional[bool] = Query(False, description="Include deleted calendars"),
+    showHidden: Optional[bool] = Query(False, description="Include hidden calendars"),
+    syncToken: Optional[str] = Query(None, description="Token for incremental sync")
+):
+    """
+    Returns the calendars on the user's calendar list
+    
+    GET /users/me/calendarList
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Validate minAccessRole parameter
+        if minAccessRole and minAccessRole not in ["freeBusyReader", "reader", "writer", "owner"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid minAccessRole: {minAccessRole}. Must be one of: freeBusyReader, reader, writer, owner"
+            )
+        
+        # Handle syncToken constraints
+        if syncToken:
+            # syncToken cannot be used with minAccessRole
+            if minAccessRole:
+                raise ValueError(f"minAccessRole query parameter cannot be specified together with syncToken")
+            
+            # When using syncToken, deleted and hidden entries must be included
+            showDeleted = True
+            showHidden = True
+        
+        # Get calendar entries with pagination and/or sync
+        try:
+            entries, next_page_token, next_sync_token = calendar_list_manager.list_calendar_entries(
+                user_id=user_id,
+                max_results=maxResults,
+                min_access_role=minAccessRole,
+                show_deleted=showDeleted,
+                show_hidden=showHidden,
+                page_token=pageToken,
+                sync_token=syncToken
+            )
+        except ValueError as e:
+            # Handle expired syncToken
+            if "expired" in str(e).lower() or "invalid sync token" in str(e).lower():
+                raise HTTPException(
+                    status_code=status.HTTP_410_GONE,
+                    detail="Sync token has expired. Client should clear storage and perform full synchronization."
+                )
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=str(e)
+            )
+        
+        return CalendarListResponse(
+            kind="calendar#calendarList",
+            etag=f"etag-list-{database_id}",
+            items=entries,
+            nextPageToken=next_page_token,
+            nextSyncToken=next_sync_token
+        )
+
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"{str(verr)}")  
+    except Exception as e:
+        logger.error(f"Error listing calendar list: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.get("/{calendarId}", response_model=CalendarListEntry)
+async def get_calendar_from_list(
+    calendarId: str,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Returns a calendar from the user's calendar list
+    
+    GET /users/me/calendarList/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Support keyword 'primary' to fetch the user's primary calendar list entry
+        if isinstance(calendarId, str) and calendarId.lower() == "primary":
+            entries, _, _ = calendar_list_manager.list_calendar_entries(
+                user_id=user_id,
+                show_hidden=True
+            )
+            entry = next((e for e in entries if e.get("primary") is True), None)
+            if entry:
+                # Check ACL permissions for primary calendar
+                try:
+                    calendar_list_manager.check_calendar_acl_permissions(user_id, entry["id"], ["reader", "writer", "owner"])
+                except PermissionError:
+                    raise HTTPException(
+                        status_code=status.HTTP_403_FORBIDDEN,
+                        detail=f"User '{user_id}' lacks permission on calendar '{entry['id']}'"
+                    )
+        else:
+            # Check ACL permissions before getting calendar entry
+            try:
+                calendar_list_manager.check_calendar_acl_permissions(user_id, calendarId, ["reader", "writer", "owner"])
+            except PermissionError:
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail=f"User '{user_id}' lacks permission on calendar '{calendarId}'"
+                )
+            entry = calendar_list_manager.get_calendar_entry(user_id, calendarId)
+        
+        if not entry:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Calendar not found: {calendarId}"
+            )
+        
+        return entry
+        
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error getting calendar list entry {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("", response_model=CalendarListEntry, status_code=status.HTTP_201_CREATED)
+async def add_calendar_to_list(
+    calendar_request: CalendarListInsertRequest,
+    colorRgbFormat: Optional[bool] = Query(False, description="Use RGB color fields when writing colors (backgroundColor/foregroundColor)"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Inserts an existing calendar into the user's calendar list
+    
+    POST /users/me/calendarList
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Convert request to dict
+        entry_data = calendar_request.model_dump(exclude_none=True)
+
+        # Validate colorId if provided (calendar list uses calendar colors)
+        color_error = validate_request_colors(entry_data, "calendar", database_id)
+        if color_error:
+            raise ValueError(color_error)
+
+        # Set backgroundColor and foregroundColor from colorId if they are not provided
+        color_set_error = set_colors_from_color_id(entry_data, "calendar")
+        if color_set_error:
+            raise ValueError(color_set_error)
+
+        # Normalize empty strings: drop to avoid triggering validation
+        for key in ["summaryOverride", "colorId", "backgroundColor", "foregroundColor"]:
+            if key in entry_data and isinstance(entry_data[key], str) and entry_data[key].strip() == "":
+                entry_data.pop(key)
+
+        # Enforce colorRgbFormat rules for RGB color fields
+        has_rgb_value = any(
+            (k in entry_data and isinstance(entry_data[k], str) and entry_data[k].strip() != "")
+            for k in ["backgroundColor", "foregroundColor"]
+        )
+        if has_rgb_value:
+            if not colorRgbFormat:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="To set backgroundColor/foregroundColor you must set colorRgbFormat=true"
+                )
+            # Validate hex color pattern #RRGGBB
+            for key in ["backgroundColor", "foregroundColor"]:
+                if key in entry_data and isinstance(entry_data[key], str) and entry_data[key].strip() != "":
+                    val = entry_data[key]
+                    if not re.match(r"^#[0-9A-Fa-f]{6}$", val):
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Invalid {key}: must be a hex color like #AABBCC"
+                        )
+            
+            # Validate color combination and set colorId if both colors are provided
+            if ("backgroundColor" in entry_data and entry_data["backgroundColor"] and
+                "foregroundColor" in entry_data and entry_data["foregroundColor"]):
+                combination_error = validate_and_set_color_id(entry_data, "calendar")
+                if combination_error:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=combination_error
+                    )
+            # When RGB colors are provided but no colorId was found/set, remove any existing colorId
+            elif "colorId" in entry_data:
+                entry_data.pop("colorId")
+        calendar_id = entry_data.pop("id")
+
+        # Check ACL permissions before adding calendar to list
+        try:
+            calendar_list_manager.check_calendar_acl_permissions(user_id, calendar_id, ["reader", "writer", "owner"])
+        except PermissionError:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"User '{user_id}' lacks permission on calendar '{calendar_id}'"
+            )
+
+
+        # Enforce Google spec: required fields when ADDING reminders/notifications
+        allowed_reminder_methods = {"email", "popup"}
+        allowed_notification_types = {
+            "eventCreation", "eventChange", "eventCancellation", "eventResponse", "agenda"
+        }
+
+        # defaultReminders: each item must include method (enum) and minutes (>=0)
+        if "defaultReminders" in entry_data and entry_data["defaultReminders"] is not None:
+            dr = entry_data["defaultReminders"]
+            if not isinstance(dr, list):
+                raise HTTPException(status_code=400, detail="defaultReminders must be a list")
+            for idx, item in enumerate(dr):
+                if not isinstance(item, dict):
+                    raise HTTPException(status_code=400, detail=f"defaultReminders[{idx}] must be an object")
+                method = (item.get("method") or "").strip()
+                minutes = item.get("minutes")
+                if method == "" or method not in allowed_reminder_methods:
+                    raise HTTPException(status_code=400, detail="defaultReminders[].method is required when adding and must be 'email' or 'popup'")
+                if not isinstance(minutes, int) or minutes < 0:
+                    raise HTTPException(status_code=400, detail="defaultReminders[].minutes is required when adding and must be >= 0")
+
+        # notificationSettings.notifications: each item must include method ('email') and type (enum)
+        if "notificationSettings" in entry_data and entry_data["notificationSettings"] is not None:
+            ns = entry_data["notificationSettings"]
+            if not isinstance(ns, dict):
+                raise HTTPException(status_code=400, detail="notificationSettings must be an object")
+            notifs = ns.get("notifications")
+            if notifs is not None:
+                if not isinstance(notifs, list):
+                    raise HTTPException(status_code=400, detail="notificationSettings.notifications must be a list")
+                for idx, n in enumerate(notifs):
+                    if not isinstance(n, dict):
+                        raise HTTPException(status_code=400, detail=f"notificationSettings.notifications[{idx}] must be an object")
+                    method = (n.get("method") or "").strip()
+                    ntype = (n.get("type") or "").strip()
+                    if method == "" or method != "email":
+                        raise HTTPException(status_code=400, detail="notificationSettings.notifications[].method is required when adding and must be 'email'")
+                    if ntype == "" or ntype not in allowed_notification_types:
+                        raise HTTPException(status_code=400, detail="notificationSettings.notifications[].type is required when adding and must be a valid type")
+        
+        # Insert calendar into list
+        entry = calendar_list_manager.insert_calendar_entry(user_id, calendar_id, entry_data)
+        
+        if not entry:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Calendar not found: {calendar_id}"
+            )
+        
+        return entry
+        
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"{str(verr)}")
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error inserting calendar list entry: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.patch("/{calendarId}", response_model=CalendarListEntry)
+async def update_calendar_in_list(
+    calendarId: str,
+    calendar_request: CalendarListUpdateRequest,
+    colorRgbFormat: Optional[bool] = Query(False, description="Use RGB color fields when writing colors (backgroundColor/foregroundColor)"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Updates an entry on the user's calendar list (partial update)
+    
+    PATCH /users/me/calendarList/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Support keyword 'primary' for calendarId (resolve to actual primary calendar ID)
+        if isinstance(calendarId, str) and calendarId.lower() == "primary":
+            entries, _, _ = calendar_list_manager.list_calendar_entries(
+                user_id=user_id,
+                show_hidden=True
+            )
+            primary_entry = next((e for e in entries if e.get("primary") is True), None)
+            if not primary_entry:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Primary calendar not found"
+                )
+            calendarId = primary_entry["id"]
+            
+
+        # Check ACL permissions before updating calendar list entry
+        try:
+            calendar_list_manager.check_calendar_acl_permissions(user_id, calendarId, ["writer", "owner"])
+        except PermissionError:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"User '{user_id}' lacks permission on calendar '{calendarId}'"
+            )
+
+        # Convert request to dict for PATCH
+        # Use exclude_unset=True so explicitly provided nulls are preserved (to allow clearing fields)
+        update_data = calendar_request.model_dump(exclude_unset=True)
+        
+        if not update_data:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="No fields provided for update"
+            )
+        
+        # Validate colorId if provided (calendar list uses calendar colors)
+        color_error = validate_request_colors(update_data, "calendar", database_id)
+        if color_error:
+            raise ValueError(color_error)
+
+        # Set backgroundColor and foregroundColor from colorId if they are not provided
+        color_set_error = set_colors_from_color_id(update_data, "calendar")
+        if color_set_error:
+            raise ValueError(color_set_error)
+
+        # Reject null values for boolean fields in PATCH
+        if "hidden" in update_data and update_data["hidden"] is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="'hidden' cannot be null in PATCH"
+            )
+        if "selected" in update_data and update_data["selected"] is None:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="'selected' cannot be null in PATCH"
+            )
+        
+        # Normalize empty strings for PATCH: treat as omitted so they don't trigger validation
+        for key in ["summaryOverride", "colorId", "backgroundColor", "foregroundColor"]:
+            if key in update_data and isinstance(update_data[key], str) and update_data[key].strip() == "":
+                update_data.pop(key)
+        
+        # Enforce colorRgbFormat rules for RGB color fields
+        has_rgb_value = any(
+            (k in update_data and isinstance(update_data[k], str) and update_data[k].strip() != "")
+            for k in ["backgroundColor", "foregroundColor"]
+        )
+        if has_rgb_value:
+            if not colorRgbFormat:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="To set backgroundColor/foregroundColor you must set colorRgbFormat=true"
+                )
+            # Validate hex color pattern #RRGGBB
+            for key in ["backgroundColor", "foregroundColor"]:
+                if key in update_data and isinstance(update_data[key], str) and update_data[key].strip() != "":
+                    val = update_data[key]
+                    if not re.match(r"^#[0-9A-Fa-f]{6}$", val):
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Invalid {key}: must be a hex color like #AABBCC"
+                        )
+            
+            # Validate color combination and set colorId if both colors are provided
+            if ("backgroundColor" in update_data and update_data["backgroundColor"] and
+                "foregroundColor" in update_data and update_data["foregroundColor"]):
+                combination_error = validate_and_set_color_id(update_data, "calendar")
+                if combination_error:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=combination_error
+                    )
+            # When RGB colors are provided but no colorId was found/set, remove any existing colorId
+            elif "colorId" in update_data:
+                update_data.pop("colorId")
+
+
+        # Set backgroundColor and foregroundColor from colorId if they are not provided
+        color_set_error = set_colors_from_color_id(update_data, "calendar")
+        if color_set_error:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=color_set_error
+            )
+
+        # Coupling rule: only enforce selected=false when hidden=true.
+        # When hidden=false, do not override selected; honor client's value if provided.
+        if "hidden" in update_data and update_data["hidden"] is True:
+            update_data["selected"] = False
+        if "hidden" in update_data and update_data["hidden"] is False and "selected" not in update_data:
+            update_data["selected"] = True
+        
+        # Sanitize nested lists for PATCH: drop invalid/empty reminder/notification items; clear when empty arrays provided
+        if "defaultReminders" in update_data:
+            dr = update_data["defaultReminders"]
+            if isinstance(dr, list):
+                cleaned = []
+                for item in dr:
+                    if not isinstance(item, dict):
+                        continue
+                    method = (item.get("method") or "").strip()
+                    minutes = item.get("minutes")
+                    if method == "":
+                        # treat as cleared; skip item
+                        continue
+                    if method in {"email", "popup"} and isinstance(minutes, int) and minutes >= 0:
+                        cleaned.append({"method": method, "minutes": minutes})
+                update_data["defaultReminders"] = cleaned if cleaned else None
+            elif dr in (None, ""):
+                update_data["defaultReminders"] = None
+
+        if "notificationSettings" in update_data:
+            ns = update_data["notificationSettings"]
+            if isinstance(ns, dict):
+                notifs = ns.get("notifications")
+                if isinstance(notifs, list):
+                    cleaned_n = []
+                    for n in notifs:
+                        if not isinstance(n, dict):
+                            continue
+                        method = (n.get("method") or "").strip()
+                        ntype = (n.get("type") or "").strip()
+                        if method == "" and ntype == "":
+                            # cleared
+                            continue
+                        if method == "email" and ntype in {"eventCreation", "eventChange", "eventCancellation", "eventResponse", "agenda"}:
+                            cleaned_n.append({"method": method, "type": ntype})
+                    update_data["notificationSettings"] = {"notifications": cleaned_n} if cleaned_n else None
+                elif notifs in (None, ""):
+                    update_data["notificationSettings"] = None
+            elif ns in (None, ""):
+                update_data["notificationSettings"] = None
+
+        # Update calendar entry
+        entry = calendar_list_manager.update_calendar_entry(user_id, calendarId, update_data, is_patch=True)
+        
+        if not entry:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Calendar not found: {calendarId}"
+            )
+        
+        return entry
+        
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"{str(verr)}")
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error updating calendar list entry {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.put("/{calendarId}", response_model=CalendarListEntry)
+async def replace_calendar_in_list(
+    calendarId: str,
+    calendar_request: CalendarListPatchRequest,
+    colorRgbFormat: Optional[bool] = Query(False, description="Use RGB color fields when writing colors (backgroundColor/foregroundColor)"),
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Updates an entry on the user's calendar list (full update)
+    
+    PUT /users/me/calendarList/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Support keyword 'primary' for calendarId (resolve to actual primary calendar ID)
+        if isinstance(calendarId, str) and calendarId.lower() == "primary":
+            entries, _, _ = calendar_list_manager.list_calendar_entries(
+                user_id=user_id,
+                show_hidden=True
+            )
+            primary_entry = next((e for e in entries if e.get("primary") is True), None)
+            if not primary_entry:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Primary calendar not found"
+                )
+            calendarId = primary_entry["id"]
+
+        # Check ACL permissions before updating calendar list entry
+        try:
+            calendar_list_manager.check_calendar_acl_permissions(user_id, calendarId, ["writer", "owner"])
+        except PermissionError:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"User '{user_id}' lacks permission on calendar '{calendarId}'"
+            )
+
+        # Convert request to dict, including None values for full update
+        update_data = calendar_request.model_dump()
+
+        # Validate colorId if provided (calendar list uses calendar colors)
+        color_error = validate_request_colors(update_data, "calendar", database_id)
+        if color_error:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=color_error
+            )
+
+        # Set backgroundColor and foregroundColor from colorId if they are not provided
+        color_set_error = set_colors_from_color_id(update_data, "calendar")
+        if color_set_error:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=color_set_error
+            )
+        
+        # Ensure NOT NULL fields have defaults for PUT requests
+        if "hidden" not in update_data or update_data["hidden"] is None:
+            update_data["hidden"] = False
+        if "selected" not in update_data or update_data["selected"] is None:
+            update_data["selected"] = True
+        
+        # Normalize empty strings to None for PUT (clear fields)
+        for key in ["summaryOverride", "colorId", "backgroundColor", "foregroundColor"]:
+            if key in update_data and isinstance(update_data[key], str) and update_data[key].strip() == "":
+                update_data[key] = None
+        
+        # Enforce colorRgbFormat rules for RGB color fields
+        has_rgb_value = any(
+            (k in update_data and isinstance(update_data[k], str) and update_data[k].strip() != "")
+            for k in ["backgroundColor", "foregroundColor"]
+        )
+        if has_rgb_value:
+            if not colorRgbFormat:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="To set backgroundColor/foregroundColor you must set colorRgbFormat=true"
+                )
+            # Validate hex color pattern #RRGGBB
+            for key in ["backgroundColor", "foregroundColor"]:
+                if key in update_data and isinstance(update_data[key], str) and update_data[key].strip() != "":
+                    val = update_data[key]
+                    if not re.match(r"^#[0-9A-Fa-f]{6}$", val):
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Invalid {key}: must be a hex color like #AABBCC"
+                        )
+            
+            # Validate color combination and set colorId if both colors are provided
+            if ("backgroundColor" in update_data and update_data["backgroundColor"] and
+                "foregroundColor" in update_data and update_data["foregroundColor"]):
+                combination_error = validate_and_set_color_id(update_data, "calendar")
+                if combination_error:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=combination_error
+                    )
+            # When RGB colors are provided but no colorId was found/set, remove any existing colorId
+            elif "colorId" in update_data:
+                update_data.pop("colorId")
+
+        
+        if "hidden" in update_data and update_data["hidden"] is True:
+            update_data["selected"] = False
+        if "hidden" in update_data and update_data["hidden"] is False and "selected" not in update_data:
+            update_data["selected"] = True
+        
+        # Sanitize nested lists for PUT: drop invalid/empty items; empty array clears
+        if "defaultReminders" in update_data:
+            dr = update_data["defaultReminders"]
+            if isinstance(dr, list):
+                cleaned = []
+                for item in dr:
+                    if not isinstance(item, dict):
+                        continue
+                    method = (item.get("method") or "").strip()
+                    minutes = item.get("minutes")
+                    if method == "":
+                        continue
+                    if method in {"email", "popup"} and isinstance(minutes, int) and minutes >= 0:
+                        cleaned.append({"method": method, "minutes": minutes})
+                update_data["defaultReminders"] = cleaned if cleaned else None
+            elif dr in (None, ""):
+                update_data["defaultReminders"] = None
+
+        if "notificationSettings" in update_data:
+            ns = update_data["notificationSettings"]
+            if isinstance(ns, dict):
+                notifs = ns.get("notifications")
+                if isinstance(notifs, list):
+                    cleaned_n = []
+                    for n in notifs:
+                        if not isinstance(n, dict):
+                            continue
+                        method = (n.get("method") or "").strip()
+                        ntype = (n.get("type") or "").strip()
+                        if method == "" and ntype == "":
+                            continue
+                        if method == "email" and ntype in {"eventCreation", "eventChange", "eventCancellation", "eventResponse", "agenda"}:
+                            cleaned_n.append({"method": method, "type": ntype})
+                    update_data["notificationSettings"] = {"notifications": cleaned_n} if cleaned_n else None
+                elif notifs in (None, ""):
+                    update_data["notificationSettings"] = None
+            elif ns in (None, ""):
+                update_data["notificationSettings"] = None
+
+        # Update calendar entry
+        entry = calendar_list_manager.update_calendar_entry(user_id, calendarId, update_data, is_patch=False)
+        
+        if not entry:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Calendar not found: {calendarId}"
+            )
+        
+        return entry
+        
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error updating calendar list entry {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.delete("/{calendarId}", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_calendar_from_list(
+    calendarId: str,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Removes a calendar from the user's calendar list
+    
+    DELETE /users/me/calendarList/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+        
+        # Support keyword 'primary' for calendarId (resolve to actual primary calendar ID)
+        if isinstance(calendarId, str) and calendarId.lower() == "primary":
+            entries, _, _ = calendar_list_manager.list_calendar_entries(
+                user_id=user_id,
+                show_hidden=True
+            )
+            primary_entry = next((e for e in entries if e.get("primary") is True), None)
+            if not primary_entry:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Primary calendar not found"
+                )
+            calendarId = primary_entry["id"]
+
+        # Check ACL permissions before removing calendar from list
+        try:
+            calendar_list_manager.check_calendar_acl_permissions(user_id, calendarId, ["owner"])
+        except PermissionError:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"User '{user_id}' lacks permission on calendar '{calendarId}'"
+            )
+
+        # Check if calendar exists first
+        existing_entry = calendar_list_manager.get_calendar_entry(user_id, calendarId)
+        if not existing_entry:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Calendar not found: {calendarId}"
+            )
+        
+        # Delete calendar entry
+        try:
+            success = calendar_list_manager.delete_calendar_entry(user_id, calendarId)
+            
+            if not success:
+                raise HTTPException(status_code=500, detail="Failed to remove calendar from list")
+        except ValueError as e:
+            # Handle primary calendar removal attempt
+            if "Cannot remove primary calendar" in str(e):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Cannot remove primary calendar from calendar list"
+                )
+            raise
+        
+        # Return 204 No Content (no response body)
+        return None
+        
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error deleting calendar list entry {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/watch")
+async def watch_calendar_list(
+    watch_request: WatchRequest,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Watch for changes to CalendarList resources
+    
+    POST /users/me/calendarList/watch
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_list_manager = get_calendar_list_manager(database_id)
+
+        # Validate user exists in this database (ensures ownership context)
+        from database.session_utils import get_session
+        from database.models.user import User
+        session = get_session(database_id)
+        try:
+            user_row = session.query(User).filter(User.user_id == user_id).first()
+            if not user_row:
+                raise HTTPException(status_code=404, detail=f"User not found: {user_id}")
+        finally:
+            session.close()
+
+
+        # Create the watch channel
+        channel = calendar_list_manager.watch_calendar_list(watch_request, user_id)
+        # Return Channel response
+        return channel
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error setting up calendar list watch: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")

server/apis/calendars/router.py

@@ -0,0 +1,271 @@
+"""
+Calendar API endpoints following Google Calendar API v3 structure
+Handles CRUD operations for calendars
+"""
+from fastapi import APIRouter, Body, HTTPException, Depends, status
+from schemas.calendar import Calendar, CalendarCreateRequest, CalendarUpdateRequest
+from schemas.common import SuccessResponse
+from database.managers.calendar_manager import CalendarManager
+from database.session_manager import CalendarSessionManager
+from utils.validation import validate_request_colors
+from middleware.auth import get_user_context
+from typing import List
+import logging
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/calendars", tags=["calendars"])
+
+# Initialize managers
+session_manager = CalendarSessionManager()
+
+def get_calendar_manager(database_id: str) -> CalendarManager:
+    """Get calendar manager for the specified database"""
+    return CalendarManager(database_id)
+
+def check_acl_permissions(manager: CalendarManager, user_id: str, calendar_id: str, allowed_roles: List[str]):
+    calendar = manager.get_calendar_by_id(user_id, calendar_id, allowed_roles)
+    if not calendar:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"User '{user_id}' lacks permission on calendar '{calendar_id}'"
+        )
+    return calendar
+
+@router.get("/{calendarId}", response_model=Calendar)
+async def get_calendar(calendarId: str, user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Returns metadata for a calendar
+
+    GET /calendars/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        if calendarId.lower() == "primary":
+            calendar = calendar_manager.get_primary_calendar(user_id)
+            if not calendar:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"User '{user_id}' has no primary calendar")
+            formatted_response = calendar_manager._format_calendar_response(calendar)
+            return Calendar(**formatted_response)
+
+        calendar = check_acl_permissions(calendar_manager, user_id, calendarId, ["reader", "writer", "owner"])
+        formatted_response = calendar_manager._format_calendar_response(calendar)
+        return Calendar(**formatted_response)
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error getting calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+@router.patch("/{calendarId}", response_model=Calendar)
+def patch_calendar(calendarId: str, update: CalendarUpdateRequest = Body(...), user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Updates calendar metadata (partial update)
+
+    PATCH /calendars/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        update_data = update.model_dump(exclude_none=True)
+        if not update_data:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="No fields provided for patch")
+
+        color_error = validate_request_colors(update_data, "calendar", database_id)
+        if color_error:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=color_error)
+
+        resolved_calendar_id = calendarId
+        if calendarId.lower() == "primary":
+            primary_calendar = calendar_manager.get_primary_calendar(user_id)
+            if not primary_calendar:
+                raise HTTPException(status_code=404, detail="Primary calendar not found")
+            resolved_calendar_id = primary_calendar.calendar_id
+
+        check_acl_permissions(calendar_manager, user_id, resolved_calendar_id, ["writer", "owner"])
+
+        updated_calendar = calendar_manager.update_calendar(user_id, resolved_calendar_id, update_data)
+        if not updated_calendar:
+            raise HTTPException(status_code=404, detail="Calendar not found")
+
+        calendar_manager.session.refresh(updated_calendar)
+        # Format the response to match the Pydantic schema
+        formatted_response = calendar_manager._format_calendar_response(updated_calendar)
+        return Calendar(**formatted_response)
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error updating calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+@router.put("/{calendarId}", response_model=Calendar)
+async def update_calendar(calendarId: str, calendar_request: CalendarUpdateRequest, user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Updates calendar metadata (full update)
+
+    PUT /calendars/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        update_data = calendar_request.model_dump(exclude_unset=True, exclude_none=True)
+        color_error = validate_request_colors(update_data, "calendar", database_id)
+        if color_error:
+            raise HTTPException(status_code=400, detail=color_error)
+
+        resolved_calendar_id = calendarId
+        if calendarId.lower() == "primary":
+            primary_calendar = calendar_manager.get_primary_calendar(user_id)
+            if not primary_calendar:
+                raise HTTPException(status_code=404, detail="Primary calendar not found")
+            resolved_calendar_id = primary_calendar.calendar_id
+
+        check_acl_permissions(calendar_manager, user_id, resolved_calendar_id, ["writer", "owner"])
+
+        logger.debug(f"Update data: {update_data}")
+        updated_calendar = calendar_manager.update_calendar(user_id, resolved_calendar_id, update_data)
+        if not updated_calendar:
+            raise HTTPException(status_code=404, detail="Calendar not found")
+
+        calendar_manager.session.refresh(updated_calendar)
+        
+        # Format the response to match the Pydantic schema
+        formatted_response = calendar_manager._format_calendar_response(updated_calendar)
+        return Calendar(**formatted_response)
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error updating calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+@router.post("", response_model=Calendar, status_code=status.HTTP_201_CREATED)
+async def create_calendar(calendar_request: CalendarCreateRequest, user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Creates a secondary calendar
+
+    POST /calendars
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        from database.managers.user_manager import UserManager
+        user_manager = UserManager(database_id)
+        user = user_manager.get_user_by_id(user_id)
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+
+        calendar_data = calendar_request.model_dump(exclude_unset=True)
+        color_error = validate_request_colors(calendar_data, "calendar", database_id)
+        if color_error:
+            raise HTTPException(status_code=400, detail=color_error)
+
+        created_calendar = calendar_manager.create_calendar(user_id, calendar_data)
+        if not created_calendar:
+            raise HTTPException(status_code=500, detail="Failed to create calendar")
+
+        # Format the response to match the Pydantic schema
+        formatted_response = calendar_manager._format_calendar_response(created_calendar)
+        return Calendar(**formatted_response)
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error creating calendar: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+@router.delete("/{calendarId}")
+def delete_calendar(calendarId: str, user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Deletes a secondary calendar
+
+    DELETE /calendars/{calendarId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        resolved_calendar_id = calendarId
+        if calendarId.lower() == "primary":
+            primary_calendar = calendar_manager.get_primary_calendar(user_id)
+            if not primary_calendar:
+                raise HTTPException(status_code=404, detail="Primary calendar not found")
+            resolved_calendar_id = primary_calendar.calendar_id
+
+        # Check ACL permissions before attempting to delete
+        check_acl_permissions(calendar_manager, user_id, resolved_calendar_id, ["owner"])
+
+        deleted = calendar_manager.delete_calendar(user_id, resolved_calendar_id)
+        if not deleted:
+            raise HTTPException(status_code=404, detail="Calendar not found or already deleted")
+
+        return {"message": "Calendar deleted successfully"}
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Error deleting calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.delete("/{calendarId}/clear", response_model=int)
+def clear_calendar(calendarId: str, user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Clears a primary calendar (deletes all events)
+
+    POST /calendars/{calendarId}/clear
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+
+        resolved_calendar_id = calendarId
+        if calendarId.lower() == "primary":
+            primary_calendar = calendar_manager.get_primary_calendar(user_id)
+            if not primary_calendar:
+                raise HTTPException(status_code=404, detail="Primary calendar not found")
+            resolved_calendar_id = primary_calendar.calendar_id
+
+        # Check ACL permissions before attempting to clear
+        check_acl_permissions(calendar_manager, user_id, resolved_calendar_id, ["owner", "writer"])
+
+        cleared_count = calendar_manager.clear_calendar(user_id, resolved_calendar_id)
+        return cleared_count
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"Access denied: {str(e)}"
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error clearing calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")

server/apis/colors/__init__.py

@@ -0,0 +1 @@
+"""Colors API module"""

server/apis/colors/data.py

@@ -0,0 +1,219 @@
+"""
+Google Calendar API v3 Colors Data
+Static color definitions for calendars and events
+"""
+
+from datetime import datetime, timezone
+from typing import Dict, Any
+
+# Google Calendar color definitions based on official API
+CALENDAR_COLORS = {
+    "1": {
+        "background": "#ac725e",
+        "foreground": "#1d1d1d"
+    },
+    "2": {
+        "background": "#d06b64",
+        "foreground": "#1d1d1d"
+    },
+    "3": {
+        "background": "#f83a22",
+        "foreground": "#1d1d1d"
+    },
+    "4": {
+        "background": "#fa57c4",
+        "foreground": "#1d1d1d"
+    },
+    "5": {
+        "background": "#9fc6e7",
+        "foreground": "#1d1d1d"
+    },
+    "6": {
+        "background": "#9a9cff",
+        "foreground": "#1d1d1d"
+    },
+    "7": {
+        "background": "#4986e7",
+        "foreground": "#1d1d1d"
+    },
+    "8": {
+        "background": "#9aa116",
+        "foreground": "#1d1d1d"
+    },
+    "9": {
+        "background": "#ef6c00",
+        "foreground": "#1d1d1d"
+    },
+    "10": {
+        "background": "#ff7537",
+        "foreground": "#1d1d1d"
+    },
+    "11": {
+        "background": "#42d692",
+        "foreground": "#1d1d1d"
+    },
+    "12": {
+        "background": "#16a765",
+        "foreground": "#1d1d1d"
+    },
+    "13": {
+        "background": "#7bd148",
+        "foreground": "#1d1d1d"
+    },
+    "14": {
+        "background": "#b3dc6c",
+        "foreground": "#1d1d1d"
+    },
+    "15": {
+        "background": "#fbe983",
+        "foreground": "#1d1d1d"
+    },
+    "16": {
+        "background": "#fad165",
+        "foreground": "#1d1d1d"
+    },
+    "17": {
+        "background": "#92e1c0",
+        "foreground": "#1d1d1d"
+    },
+    "18": {
+        "background": "#9fe1e7",
+        "foreground": "#1d1d1d"
+    },
+    "19": {
+        "background": "#9fc6e7",
+        "foreground": "#1d1d1d"
+    },
+    "20": {
+        "background": "#4986e7",
+        "foreground": "#1d1d1d"
+    },
+    "21": {
+        "background": "#9aa116",
+        "foreground": "#1d1d1d"
+    },
+    "22": {
+        "background": "#16a765",
+        "foreground": "#1d1d1d"
+    },
+    "23": {
+        "background": "#ff7537",
+        "foreground": "#1d1d1d"
+    },
+    "24": {
+        "background": "#ffad46",
+        "foreground": "#1d1d1d"
+    }
+}
+
+EVENT_COLORS = {
+    "1": {
+        "background": "#a4bdfc",
+        "foreground": "#1d1d1d"
+    },
+    "2": {
+        "background": "#7ae7bf",
+        "foreground": "#1d1d1d"
+    },
+    "3": {
+        "background": "#dbadff",
+        "foreground": "#1d1d1d"
+    },
+    "4": {
+        "background": "#ff887c",
+        "foreground": "#1d1d1d"
+    },
+    "5": {
+        "background": "#fbd75b",
+        "foreground": "#1d1d1d"
+    },
+    "6": {
+        "background": "#ffb878",
+        "foreground": "#1d1d1d"
+    },
+    "7": {
+        "background": "#46d6db",
+        "foreground": "#1d1d1d"
+    },
+    "8": {
+        "background": "#e1e1e1",
+        "foreground": "#1d1d1d"
+    },
+    "9": {
+        "background": "#5484ed",
+        "foreground": "#1d1d1d"
+    },
+    "10": {
+        "background": "#51b749",
+        "foreground": "#1d1d1d"
+    },
+    "11": {
+        "background": "#dc2127",
+        "foreground": "#1d1d1d"
+    }
+}
+
+def get_colors_response() -> Dict[str, Any]:
+    """
+    Get the complete colors response in Google Calendar API v3 format
+    
+    Returns:
+        Dict containing calendar and event colors with metadata
+    """
+    return {
+        "kind": "calendar#colors",
+        "updated": "2023-01-01T00:00:00.000Z",
+        "calendar": CALENDAR_COLORS,
+        "event": EVENT_COLORS
+    }
+
+def get_color_by_id(color_type: str, color_id: str) -> Dict[str, str]:
+    """
+    Get a specific color by type and ID
+    
+    Args:
+        color_type: Either 'calendar' or 'event'
+        color_id: The color ID (e.g., '1', '2', etc.)
+        
+    Returns:
+        Dict containing background and foreground colors
+        
+    Raises:
+        ValueError: If color_type or color_id is invalid
+    """
+    if color_type == "calendar":
+        colors = CALENDAR_COLORS
+    elif color_type == "event":
+        colors = EVENT_COLORS
+    else:
+        raise ValueError(f"Invalid color type: {color_type}. Must be 'calendar' or 'event'")
+    
+    if color_id not in colors:
+        raise ValueError(f"Invalid color ID: {color_id} for type {color_type}")
+    
+    return colors[color_id]
+
+def get_all_calendar_colors() -> Dict[str, Dict[str, str]]:
+    """Get all calendar colors"""
+    return CALENDAR_COLORS.copy()
+
+def get_all_event_colors() -> Dict[str, Dict[str, str]]:
+    """Get all event colors"""
+    return EVENT_COLORS.copy()
+
+def validate_color_id(color_type: str, color_id: str) -> bool:
+    """
+    Validate if a color ID exists for the given type
+    
+    Args:
+        color_type: Either 'calendar' or 'event'
+        color_id: The color ID to validate
+        
+    Returns:
+        True if color ID exists, False otherwise
+    """
+    try:
+        get_color_by_id(color_type, color_id)
+        return True
+    except ValueError:
+        return False

server/apis/colors/router.py

@@ -0,0 +1,46 @@
+"""
+Colors API endpoints following Google Calendar API v3 structure
+Provides color definitions for calendars and events
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException, Header, status
+from typing import Dict, Any
+from database.managers.color_manager import ColorManager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/colors", tags=["colors"])
+
+
+def get_color_manager(database_id: str) -> ColorManager:
+    """Get color manager for the specified database"""
+    return ColorManager(database_id)
+
+
+@router.get("", response_model=Dict[str, Any])
+async def get_colors(x_database_id: str = Header(alias="x-database-id")):
+    """
+    Returns the color definitions for calendars and events
+    
+    GET /colors
+    
+    Returns a global palette of color definitions for calendars and events.
+    Color data is dynamically loaded from database with exact Google Calendar API v3 format.
+    Colors are global/shared across all users - no user_id required.
+    Use POST /api/load-sample-colors to populate database with Google's color definitions.
+    """
+    try:
+        color_manager = get_color_manager(x_database_id)
+        
+        colors_response = color_manager.get_colors_response()
+        
+        logger.info("Retrieved calendar and event color definitions from database")
+        return colors_response
+        
+    except Exception as e:
+        logger.error(f"Error getting color definitions: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Internal server error: {str(e)}"
+        )

server/apis/core_apis.py

@@ -0,0 +1,19 @@
+"""
+Core API endpoints
+Handles health check and other core endpoints for Calendar API clone
+"""
+
+import logging
+from fastapi import APIRouter
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+# Create router for core APIs
+router = APIRouter(tags=["core"])
+
+
+@router.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {"status": "healthy", "service": "calendar-env"}

server/apis/database_router.py

@@ -0,0 +1,625 @@
+"""
+Database Management API endpoints for Calendar API
+Handles database operations like seeding, viewing, and schema management
+"""
+
+import logging
+import os
+import shutil
+import sqlite3
+import time
+import random
+import string
+from datetime import datetime
+from fastapi import APIRouter, HTTPException, Header
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+from typing import Any, Dict, Optional
+
+from data.google_colors import GOOGLE_CALENDAR_COLORS
+from data.multi_user_sample import get_multi_user_sql
+from database.session_manager import CalendarSessionManager
+from database.base_manager import BaseManager
+from database.session_utils import _session_manager
+from database.managers.calendar_manager import CalendarManager
+from database.seed_database import SeedData, get_seed_session, init_seed_database
+
+logger = logging.getLogger(__name__)
+
+# Initialize session manager
+calendar_session_manager = CalendarSessionManager()
+
+router = APIRouter(prefix="/api", tags=["database"])
+
+
+@router.get("/sample-data")
+async def get_sample_data():
+    """Get multi-user Calendar sample data as SQL script for download/inspection"""
+    try:
+        sql_content = get_multi_user_sql()
+
+        return {
+            "success": True,
+            "message": "Sample calendar data.",
+            "format": "sql",
+            "sql_content": sql_content,
+        }
+    except Exception as e:
+        logger.error(f"Error retrieving sample data: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to retrieve sample data: {str(e)}")
+
+
+@router.post("/seed-database")
+async def seed_database(body: dict):
+    """Seed database with user-provided SQL content or default sample data"""
+    try:
+        database_id = body.get("database_id")
+        if not database_id:
+            raise HTTPException(status_code=400, detail="database_id is required")
+        sql_content = body.get("sql_content")
+
+        if not sql_content:
+            raise HTTPException(status_code=400, detail="sql_content is required")
+
+        # Initialize database
+        calendar_session_manager.init_database(database_id, create_tables=True)
+        db_path = calendar_session_manager.get_db_path(database_id)
+
+        # Execute SQL content
+        conn = sqlite3.connect(db_path)
+        try:
+            cursor = conn.cursor()
+
+            # Drop all existing tables to ensure fresh schema from SQLAlchemy models
+            # Get all table names dynamically
+            cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+            tables = cursor.fetchall()
+
+            # Drop all tables to get fresh schema
+            for table in tables:
+                table_name = table[0]
+                cursor.execute(f"DROP TABLE IF EXISTS {table_name}")
+
+            conn.commit()
+            conn.close()
+
+            # Reinitialize database with fresh schema from SQLAlchemy models
+            calendar_session_manager.init_database(database_id, create_tables=True)
+
+            # Reconnect to database
+            conn = sqlite3.connect(db_path)
+            cursor = conn.cursor()
+
+            # Execute custom SQL statements individually
+            statements = []
+            for line in sql_content.split("\n"):
+                line = line.strip()
+                if line and not line.startswith("--"):
+                    statements.append(line)
+
+            # Join and split by semicolon
+            full_sql = " ".join(statements)
+            individual_statements = [stmt.strip() for stmt in full_sql.split(";") if stmt.strip()]
+
+            # Execute each statement
+            for statement in individual_statements:
+                try:
+                    # Skip empty statements
+                    if not statement.strip():
+                        continue
+                    cursor.execute(statement)
+                except Exception as e:
+                    logger.error(f"Error executing statement: {statement[:100]}...")
+                    logger.error(f"Error details: {e}")
+                    raise e
+
+            conn.commit()
+
+            # Enforce primary calendar constraints and ensure ACL entries exist
+            try:
+                calendar_manager = CalendarManager(database_id)
+                calendar_manager.enforce_primary_calendar_constraint_for_all_users()
+
+                # Ensure ACL entries exist for all calendar owners
+                # This is important for the new ACL validation system
+                logger.info("Ensuring ACL entries exist for all calendar owners...")
+
+                # Get all calendars and ensure their owners have ACL entries
+                cursor.execute("SELECT calendar_id, user_id FROM calendars")
+                calendars = cursor.fetchall()
+
+                for calendar_row in calendars:
+                    calendar_id = calendar_row[0]
+                    user_id = calendar_row[1]
+
+                    # Check if ACL entry already exists for this calendar owner
+                    cursor.execute("""
+                        SELECT COUNT(*) as count FROM acls a
+                        JOIN scopes s ON a.scope_id = s.id
+                        JOIN users u ON u.email = s.value
+                        WHERE a.calendar_id = ? AND u.user_id = ? AND a.role = 'owner'
+                    """, (calendar_id, user_id))
+
+                    acl_exists = cursor.fetchone()[0] > 0
+
+                    if not acl_exists:
+                        # Get user email
+                        cursor.execute("SELECT email FROM users WHERE user_id = ?", (user_id,))
+                        user_result = cursor.fetchone()
+
+                        if user_result:
+                            user_email = user_result[0]
+
+                            # Create scope for this user if it doesn't exist
+                            scope_id = f"scope-{user_id}"
+                            cursor.execute("INSERT OR IGNORE INTO scopes (id, type, value) VALUES (?, 'user', ?)",
+                                         (scope_id, user_email))
+
+                            # Create ACL entries for calendar owner (both owner and writer roles)
+                            owner_acl_id = f"acl-{calendar_id}-owner"
+                            writer_acl_id = f"acl-{calendar_id}-writer"
+
+                            cursor.execute("""
+                                INSERT OR IGNORE INTO acls (id, calendar_id, user_id, role, scope_id, etag, created_at, updated_at)
+                                VALUES (?, ?, ?, 'owner', ?, ?, datetime('now'), datetime('now'))
+                            """, (owner_acl_id, calendar_id, user_id, scope_id, f'etag-{owner_acl_id}'))
+
+                            cursor.execute("""
+                                INSERT OR IGNORE INTO acls (id, calendar_id, user_id, role, scope_id, etag, created_at, updated_at)
+                                VALUES (?, ?, ?, 'writer', ?, ?, datetime('now'), datetime('now'))
+                            """, (writer_acl_id, calendar_id, user_id, scope_id, f'etag-{writer_acl_id}'))
+
+                            logger.info(f"Created owner and writer ACL entries for calendar {calendar_id} owner {user_email}")
+
+                conn.commit()
+                logger.info("ACL validation completed successfully")
+
+            except Exception as constraint_error:
+                logger.warning(f"Error enforcing constraints and ACL validation: {constraint_error}")
+
+            # Store SQL content in seed_data table for future resets
+            sql_stored = False
+            try:
+                seed_db_session = get_seed_session()
+                try:
+                    existing_seed = seed_db_session.query(SeedData).filter(
+                        SeedData.database_id == database_id
+                    ).first()
+                    
+                    name = body.get("name", f"Database {database_id}")
+                    description = body.get("description", "")
+                    
+                    if existing_seed:
+                        existing_seed.sql_content = sql_content
+                        existing_seed.name = name
+                        existing_seed.description = description
+                        logger.info(f"Updated seed SQL for database {database_id}")
+                    else:
+                        seed_entry = SeedData(
+                            database_id=database_id,
+                            name=name,
+                            description=description,
+                            sql_content=sql_content
+                        )
+                        seed_db_session.add(seed_entry)
+                        logger.info(f"Stored new seed SQL for database {database_id}")
+                    
+                    seed_db_session.commit()
+                    sql_stored = True
+                finally:
+                    seed_db_session.close()
+            except Exception as e:
+                logger.warning(f"Failed to store seed SQL in database: {e}")
+                sql_stored = False
+
+            result = {
+                "success": True,
+                "message": f"Database seeded successfully",
+                "database_id": database_id,
+                "sql_stored": sql_stored,
+            }
+
+            logger.info(f"Successfully seeded database {database_id}")
+            return result
+
+        finally:
+            conn.close()
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error seeding database: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to seed database: {str(e)}")
+
+
+@router.get("/database-state")
+async def get_database_state(x_database_id: str = Header(alias="x-database-id")):
+    """Get current database state and all data for frontend tabular display"""
+    try:
+        database_id = x_database_id
+
+        # Initialize database if needed
+        calendar_session_manager.init_database(database_id)
+        db_path = calendar_session_manager.get_db_path(database_id)
+
+        if not os.path.exists(db_path):
+            return {
+                "success": True,
+                "message": "Database not initialized yet",
+                "database_info": {"status": "not_created"},
+                "table_counts": {},
+                "table_data": {},
+            }
+
+        # Connect to database
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+
+        try:
+            cursor = conn.cursor()
+
+            # Get all user-defined tables
+            cursor.execute(
+                """
+                SELECT name FROM sqlite_master
+                WHERE type='table' AND name NOT LIKE 'sqlite_%'
+                ORDER BY name
+            """
+            )
+            tables = cursor.fetchall()
+
+            # Get data from each table
+            table_data = {}
+            table_counts = {}
+
+            for table in tables:
+                table_name = table["name"]
+
+                # Get count
+                cursor.execute(f"SELECT COUNT(*) as count FROM '{table_name}'")
+                count = cursor.fetchone()["count"]
+                table_counts[table_name] = count
+
+                # Get data (limit to 100 rows for performance)
+                cursor.execute(f"SELECT * FROM '{table_name}' LIMIT 100")
+                rows = cursor.fetchall()
+
+                # Convert to list of dictionaries
+                table_data[table_name] = [dict(row) for row in rows]
+
+            # Get database info
+            db_file_size = os.path.getsize(db_path)
+            db_modified = datetime.fromtimestamp(os.path.getmtime(db_path)).isoformat()
+
+            return {
+                "success": True,
+                "database_id": database_id,
+                "service": "calendar-api-server",
+                "database_info": {
+                    "path": db_path,
+                    "size_bytes": db_file_size,
+                    "size_mb": round(db_file_size / (1024 * 1024), 2),
+                    "last_modified": db_modified,
+                    "total_tables": len(tables),
+                },
+                "table_counts": table_counts,
+                "table_data": table_data,
+                "timestamp": datetime.now().isoformat(),
+            }
+
+        finally:
+            conn.close()
+
+    except Exception as e:
+        logger.error(f"Error getting database state: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to get database state: {str(e)}")
+
+
+@router.get("/schema")
+async def get_schema():
+    """Get database schema as JSON"""
+    try:
+        # Return static schema definition from SQLAlchemy models
+        return {
+            "success": True,
+            "message": "Database schema retrieved successfully",
+            "schema": calendar_session_manager.get_database_schema(),
+        }
+
+    except Exception as e:
+        logger.error(f"Error getting database schema: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to retrieve database schema: {str(e)}")
+
+
+@router.get("/download-db-file")
+async def download_database_file(x_database_id: str = Header(default="default", alias="x-database-id")):
+    """Download the actual SQLite database file (.db)"""
+    try:
+        database_id = x_database_id.strip()
+
+        # Basic input validation
+        if not database_id or database_id == "":
+            raise HTTPException(status_code=400, detail="Database ID cannot be empty")
+
+        logger.info(f"-------Download DB File for {database_id}------")
+
+        # Initialize database if needed
+        calendar_session_manager.init_database(database_id)
+        db_path = calendar_session_manager.get_db_path(database_id)
+
+        # Check if file exists and is readable
+        if not os.path.exists(db_path):
+            raise HTTPException(status_code=404, detail=f"Database with ID '{database_id}' not found")
+
+        if not os.path.isfile(db_path):
+            raise HTTPException(status_code=400, detail=f"Database path '{db_path}' is not a valid file")
+
+        if not os.access(db_path, os.R_OK):
+            raise HTTPException(status_code=403, detail=f"Database file is not readable")
+
+        # Generate filename for download with sanitized database_id
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        safe_database_id = "".join(c for c in database_id if c.isalnum() or c in "_-")
+        filename = f"ola_database_{safe_database_id}_{timestamp}.db"
+
+        logger.info(f"Serving database file: {db_path} as {filename}")
+
+        # Return the actual database file
+        return FileResponse(
+            path=db_path,
+            filename=filename,
+            media_type="application/x-sqlite3",
+            headers={"Content-Disposition": f"attachment; filename={filename}"},
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error downloading database file: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to download database file: {str(e)}")
+
+
+class SQLQueryRequest(BaseModel):
+    """Request model for executing SQL queries"""
+
+    query: str = Field(..., min_length=1, description="SQL query to execute")
+    limit: Optional[int] = Field(100, ge=1, le=1000, description="Maximum number of rows to return")
+
+
+@router.post("/sql-runner", response_model=Dict[str, Any])
+def execute_custom_query(request: SQLQueryRequest, x_database_id: str = Header(...)):
+    """Execute a custom SQL query with limit"""
+    try:
+        # Ensure database exists
+        calendar_session_manager.init_database(x_database_id)
+        db_path = calendar_session_manager.get_db_path(x_database_id)
+
+        # Use BaseManager to execute the query
+        manager = BaseManager(db_path)
+
+        # Add LIMIT clause to query if not present
+        query = request.query.strip().rstrip(";")
+
+        # Execute the query
+        data = manager.execute_query(query)
+
+        return {
+            "success": True,
+            "message": "Query executed successfully",
+            "data": data,
+            "row_count": len(data),
+            "query": query,
+        }
+    except Exception as e:
+        logger.error(f"Error executing custom query: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/reset-database")
+async def reset_database(body: dict):
+    """Reset a database to its original seeded state."""
+    try:
+        database_id = body.get("database_id")
+        if not database_id:
+            raise HTTPException(status_code=400, detail="database_id is required")
+        
+        sql_content = body.get("sql_content")
+        
+        # Get or store seed SQL
+        seed_session = get_seed_session()
+        try:
+            seed_data = seed_session.query(SeedData).filter(SeedData.database_id == database_id).first()
+            
+            if seed_data:
+                sql_content = seed_data.sql_content
+                logger.info(f"Using stored SQL for database {database_id}")
+            elif sql_content:
+                new_seed = SeedData(
+                    database_id=database_id,
+                    name=f"calendar_{database_id}",
+                    description="Seed SQL for Calendar database (lazy migration)",
+                    sql_content=sql_content
+                )
+                seed_session.add(new_seed)
+                seed_session.commit()
+                logger.info(f"Stored SQL via lazy migration for database {database_id}")
+            else:
+                raise HTTPException(
+                    status_code=400,
+                    detail="No stored SQL found and no sql_content provided. Cannot reset database."
+                )
+        finally:
+            seed_session.close()
+        
+        # Close existing session and get db path
+        calendar_session_manager.close_session(database_id)
+        db_path = calendar_session_manager.get_db_path(database_id)
+        
+        # Delete the database file completely (faster than dropping tables)
+        if os.path.exists(db_path):
+            os.remove(db_path)
+            logger.info(f"Deleted database file: {db_path}")
+        
+        # Reinitialize with fresh tables
+        calendar_session_manager.init_database(database_id, create_tables=True)
+        
+        # Execute seed SQL in one go using executescript
+        conn = sqlite3.connect(db_path)
+        try:
+            # executescript is much faster than executing statements one by one
+            conn.executescript(sql_content)
+            conn.commit()
+            logger.info(f"Database {database_id} reset successfully")
+            
+            return {
+                "success": True,
+                "message": "Database reset successfully",
+                "database_id": database_id
+            }
+        finally:
+            conn.close()
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error resetting database: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to reset database: {str(e)}")
+
+
+@router.post("/clone-database")
+async def clone_database(body: dict):
+    """
+    Clone an existing database to a new database.
+    Returns the new database_id.
+    """
+    try:
+        # Accept both "database_id" and "source_database_id" for compatibility
+        source_database_id = body.get("database_id") or body.get("source_database_id")
+        if not source_database_id:
+            raise HTTPException(status_code=400, detail="database_id is required")
+        
+        logger.info(f"Clone database request for: {source_database_id}")
+        
+        # Get source database path
+        source_db_path = calendar_session_manager.get_db_path(source_database_id)
+        
+        if not os.path.exists(source_db_path):
+            raise HTTPException(status_code=404, detail=f"Source database '{source_database_id}' not found")
+        
+        # Generate new database ID
+        timestamp = int(time.time() * 1000)
+        random_suffix = ''.join(random.choices(string.ascii_lowercase + string.digits, k=9))
+        new_db_id = f"db_clone_{timestamp}_{random_suffix}"
+        
+        # Get new database path
+        new_db_path = calendar_session_manager.get_db_path(new_db_id)
+        
+        # Close any existing session on source to ensure file is not locked
+        calendar_session_manager.close_session(source_database_id)
+        
+        # Clone the database file
+        shutil.copy2(source_db_path, new_db_path)
+        
+        # Copy associated files (WAL, SHM, journal) if they exist
+        for ext in ['-wal', '-shm', '-journal']:
+            source_extra = source_db_path + ext
+            if os.path.exists(source_extra):
+                dest_extra = new_db_path + ext
+                shutil.copy2(source_extra, dest_extra)
+                logger.debug(f"Copied {source_extra} to {dest_extra}")
+        
+        # Initialize the session for the cloned database
+        calendar_session_manager.init_database(new_db_id, create_tables=False)
+        
+        # Get cloned database size
+        cloned_size_bytes = os.path.getsize(new_db_path) if os.path.exists(new_db_path) else 0
+        
+        result = {
+            "success": True,
+            "message": "Database cloned successfully",
+            "source_database_id": source_database_id,
+            "cloned_database_id": new_db_id,
+            "cloned_db_path": new_db_path,
+            "cloned_size_bytes": cloned_size_bytes,
+        }
+        
+        logger.info(f"Successfully cloned database '{source_database_id}' to '{new_db_id}'")
+        return result
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error cloning database: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to clone database: {str(e)}")
+
+
+@router.delete("/delete-database")
+async def delete_database(body: dict):
+    """
+    Delete a cloned database.
+    WARNING: This permanently deletes the database and cannot be undone.
+    """
+    try:
+        database_id = body.get("database_id")
+        if not database_id:
+            raise HTTPException(status_code=400, detail="database_id is required in request body")
+        
+        logger.info(f"Delete database request for: {database_id}")
+        
+        # Safety check: don't allow deleting the default database
+        if database_id == "default":
+            raise HTTPException(status_code=400, detail="Cannot delete the default database")
+        
+        # Get database path
+        db_path = calendar_session_manager.get_db_path(database_id)
+        
+        if not os.path.exists(db_path):
+            raise HTTPException(status_code=404, detail=f"Database with ID '{database_id}' not found")
+        
+        # Close any existing sessions
+        calendar_session_manager.close_session(database_id)
+        
+        # Get file size before deletion
+        db_size = os.path.getsize(db_path)
+        
+        # Delete the database file
+        os.remove(db_path)
+        
+        # Delete associated files (WAL, SHM, journal) if they exist
+        for ext in ['-wal', '-shm', '-journal']:
+            extra_file = db_path + ext
+            if os.path.exists(extra_file):
+                os.remove(extra_file)
+                logger.debug(f"Deleted {extra_file}")
+        
+        # Also remove from seed_data table if exists
+        try:
+            seed_db_session = get_seed_session()
+            try:
+                seed_entry = seed_db_session.query(SeedData).filter(
+                    SeedData.database_id == database_id
+                ).first()
+                if seed_entry:
+                    seed_db_session.delete(seed_entry)
+                    seed_db_session.commit()
+                    logger.info(f"Deleted seed data for database {database_id}")
+            finally:
+                seed_db_session.close()
+        except Exception as e:
+            logger.warning(f"Failed to delete seed data: {e}")
+        
+        result = {
+            "success": True,
+            "message": "Database deleted successfully",
+            "database_id": database_id,
+            "deleted_size_bytes": db_size,
+        }
+        
+        logger.info(f"Successfully deleted database {database_id}")
+        return result
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deleting database: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to delete database: {str(e)}")

server/apis/events/router.py

@@ -0,0 +1,893 @@
+"""
+Events API endpoints following Google Calendar API v3 structure
+Handles all 11 Events operations with exact Google API compatibility
+"""
+
+import logging
+from typing import Optional, List
+from fastapi import APIRouter, HTTPException, Header, Query, status, Depends
+from pydantic import ValidationError
+from schemas.event import (
+    Event,
+    EventListResponse,
+    EventCreateRequest,
+    EventUpdateRequest,
+    EventMoveRequest,
+    EventQuickAddRequest,
+    EventInstancesResponse,
+    Channel,
+    EventWatchRequest,
+    OrderByEnum,
+    EventTypesEnum,
+)
+from schemas.import_event import (
+    EventImportRequest,
+    EventImportResponse,
+    EventImportQueryParams,
+    EventImportError,
+)
+from database.managers.event_manager import EventManager
+from database.session_manager import CalendarSessionManager
+from utils.validation import validate_request_colors
+from middleware.auth import get_user_context
+from database.managers.calendar_manager import CalendarManager
+from apis.calendars.router import get_calendar_manager
+from database.models.user import User
+from database.session_utils import get_session
+import re
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/calendars/{calendarId}/events", tags=["events"])
+
+# Initialize managers
+session_manager = CalendarSessionManager()
+
+
+def get_event_manager(database_id: str) -> EventManager:
+    """Get event manager for the specified database"""
+    return EventManager(database_id)
+
+def check_event_acl_permissions(
+    calendar_manager: CalendarManager, 
+    user_id: str, 
+    calendar_id: str, 
+    allowed_roles: list[str],
+    operation: str = "access"
+):
+    """Check ACL permissions for event operations"""
+    calendar = calendar_manager.get_calendar_by_id(user_id, calendar_id, allowed_roles)
+    if not calendar:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"User '{user_id}' lacks required roles {allowed_roles} for {operation} on calendar '{calendar_id}'"
+        )
+    return calendar
+
+
+@router.get("", response_model=EventListResponse)
+async def list_events(
+    calendarId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    eventTypes: Optional[List[EventTypesEnum]] = Query(None, description="Event types to return. Acceptable values are: 'birthday' - Special all-day events with an annual recurrence, 'default' - Regular events, 'focusTime' - Focus time events, 'fromGmail' - Events from Gmail, 'outOfOffice' - Out of office events, 'workingLocation' - Working location events. Optional. Multiple event types can be provided using repeated parameter instances"),
+    iCalUID: Optional[str] = Query(None, description="Specifies an event ID in the iCalendar format to be provided in the response. Optional. Use this if you want to search for an event by its iCalendar ID. Mutually exclusive with q. Optional."),
+    maxAttendees: Optional[int] = Query(None, gt=0, description="The maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional."),
+    maxResults: Optional[int] = Query(250, gt=0, le=2500, description="Maximum number of events returned on one result page. By default the value is 250 events. The page size can never be larger than 2500 events. Optional."),
+    orderBy: Optional[OrderByEnum] = Query(OrderByEnum.START_TIME, description="The order of the events returned in the result. Optional. The default is an unspecified, stable order."),
+    pageToken: Optional[str] = Query(None, description="Token specifying which result page to return. Optional."),
+    privateExtendedProperty: Optional[str] = Query(None, description="Extended properties constraint specified as propertyName=value. Matches only private properties. This parameter might be repeated multiple times to return events that match all given constraints."),
+    q: Optional[str] = Query(None, description="Free text search terms to find events that match these terms in any field, except for extended properties. Optional."),
+    sharedExtendedProperty: Optional[str] = Query(None, description="Extended properties constraint specified as propertyName=value. Matches only shared properties. This parameter might be repeated multiple times to return events that match all given constraints."),
+    showDeleted: Optional[bool] = Query(False, description="Whether to include deleted events (with status equals 'cancelled') in the result. Cancelled instances of recurring events (but not the underlying recurring event) will still be included if showDeleted and singleEvents are both False. If showDeleted and singleEvents are both True, only single instances of deleted events (but not the underlying recurring events) are returned. Optional. The default is False."),
+    showHiddenInvitations: Optional[bool] = Query(False, description="Whether to include hidden invitations in the result. Optional. The default is False."),
+    singleEvents: Optional[bool] = Query(False, description="Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves. Optional. The default is False."),
+    syncToken: Optional[str] = Query(None, description="Token obtained from the nextSyncToken field returned on the last page of results from the previous list request. It makes the result of this list request contain only entries that have changed since then. All events deleted since the previous list request will always be in the result set and it is not allowed to set showDeleted to False. There are several query parameters that cannot be specified together with nextSyncToken to ensure consistency of the client state."),
+    timeMax: Optional[str] = Query(None, description="Upper bound (exclusive) for an event's start time to filter by. Optional. The default is not to filter by start time. Must be an RFC3339 timestamp with mandatory time zone offset, for example, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Milliseconds may be provided but are ignored. If timeMin is set, timeMax must be greater than timeMin."),
+    timeMin: Optional[str] = Query(None, description="Lower bound (exclusive) for an event's end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset, for example, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Milliseconds may be provided but are ignored. If timeMax is set, timeMin must be less than timeMax."),
+    timeZone: Optional[str] = Query(None, description="Time zone used in the response. Optional. The default is the time zone of the calendar."),
+    updatedMin: Optional[str] = Query(None, description="Lower bound for an event's last modification time (as a RFC3339 timestamp) to filter by. When specified, entries deleted since this time will always be included regardless of showDeleted. Optional. The default is not to filter by last modification time."),
+):
+    """
+    Returns events on the specified calendar
+    ACL Required: reader, writer, or owner role
+
+    GET /calendars/{calendarId}/events
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require at least reader role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId, 
+            ["reader", "writer", "owner"], "list events"
+        )
+
+        # Validate iCalUID
+        if iCalUID:
+            pattern = r"^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"
+            if not re.match(pattern, iCalUID):
+                raise ValueError("Invalid iCalUID format. Expected something like 'abcd123@google.com'.")
+
+        # Validate pageToken
+        if pageToken:
+            try:
+                page_token_int = int(pageToken)
+                if not page_token_int >= 0:
+                    raise ValueError("Please enter a valid pageToken value. Page token must be greater than equal to 0 and must be string integer")
+            except:
+                raise ValueError("Please enter a valid pageToken value. Page token must be greater than equal to 0 and must be string integer")
+
+        # Convert eventTypes enum list to comma-separated string for the manager
+        event_types_str = None
+        if eventTypes:
+            event_types_str = ",".join([event_type.value for event_type in eventTypes])
+        
+        response = event_manager.list_events(
+            user_id=user_id,
+            calendar_id=calendarId,
+            event_types=event_types_str,
+            ical_uid=iCalUID,
+            max_attendees=maxAttendees,
+            max_results=maxResults,
+            order_by=orderBy,
+            page_token=pageToken,
+            private_extended_property=privateExtendedProperty,
+            q=q,
+            shared_extended_property=sharedExtendedProperty,
+            show_deleted=showDeleted,
+            show_hidden_invitations=showHiddenInvitations,
+            single_events=singleEvents,
+            sync_token=syncToken,
+            time_max=timeMax,
+            time_min=timeMin,
+            time_zone=timeZone,
+            updated_min=updatedMin,
+        )
+
+        return response
+    
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail= f"{str(e)}")
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error listing events for calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("", response_model=Event, status_code=status.HTTP_201_CREATED)
+async def create_event(
+    calendarId: str,
+    event_request: EventCreateRequest,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    conferenceDataVersion: Optional[int] = Query(
+        None,
+        ge=0,
+        le=1,
+        description="Version number of conference data supported by API client"
+    ),
+    maxAttendees: Optional[int] = Query(
+        None,
+        gt=0,
+        description="The maximum number of attendees to include in the response"
+    ),
+    sendUpdates: Optional[str] = Query("none", description="Whether to send notifications about the creation of the new event. Note that some emails might still be sent. The default is 'none'. Acceptable values are: 'all' (notifications sent to all guests), 'externalOnly' (notifications sent to non-Google Calendar guests only), 'none' (no notifications sent)"),
+    supportsAttachments: Optional[bool] = Query(
+        False,
+        description="Whether API client performing operation supports event attachments"
+    ),
+):
+    """
+    Creates an event
+    ACL Required: writer or owner role
+    
+    The sendUpdates parameter controls notification behavior:
+    - "all": Notifications are sent to all guests
+    - "externalOnly": Notifications are sent to non-Google Calendar guests only
+    - "none": No notifications are sent (default)
+
+    POST /calendars/{calendarId}/events
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId, 
+            ["writer", "owner"], "create events"
+        )
+
+        # Validate sendUpdates parameter
+        if sendUpdates and sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Validate colorId if provided (events use event colors)
+        event_data = event_request.model_dump(exclude_none=True)
+        color_error = validate_request_colors(event_data, "event", database_id)
+        if color_error:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=color_error)
+
+        # Validate required fields per Google API specification
+        if not event_request.start or not event_request.end:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Both 'start' and 'end' fields are required"
+            )
+
+        # Create query parameters object for event creation
+        query_params = {
+            'conferenceDataVersion': conferenceDataVersion,
+            'maxAttendees': maxAttendees,
+            'sendUpdates': sendUpdates,
+            'supportsAttachments': supportsAttachments
+        }
+
+        event = event_manager.create_event(user_id, calendarId, event_request, query_params)
+
+        if not event:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Failed to create event")
+
+        # Filter attendees based on maxAttendees parameter
+        if maxAttendees is not None and event.attendees and len(event.attendees) > maxAttendees:
+            event.attendees = event.attendees[:maxAttendees]
+            event.attendeesOmitted = True
+
+        return event
+
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(verr))
+    except ValidationError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=e.errors())
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error creating event in calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.get("/{eventId}", response_model=Event)
+async def get_event(
+    calendarId: str,
+    eventId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    timeZone: Optional[str] = Query(None, description="Time zone for returned times"),
+    maxAttendees: Optional[int] = Query(None, description="Maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional."),
+):
+    """
+    Returns an event
+
+    GET /calendars/{calendarId}/events/{eventId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require at least reader role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId, 
+            ["reader", "writer", "owner"], "read event"
+        )
+
+        event = event_manager.get_event(user_id, calendarId, eventId, timeZone, maxAttendees)
+
+        if not event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+
+        return event
+
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error getting event {eventId} from calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.patch("/{eventId}", response_model=Event)
+async def patch_event(
+    calendarId: str,
+    eventId: str,
+    event_request: EventUpdateRequest,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    conferenceDataVersion: Optional[int] = Query(
+        None,
+        ge=0,
+        le=1,
+        description="Version number of conference data supported by API client"
+    ),
+    maxAttendees: Optional[int] = Query(
+        None,
+        gt=0,
+        description="The maximum number of attendees to include in the response"
+    ),
+    sendUpdates: Optional[str] = Query("none", description="Guests who should receive notifications (all, externalOnly, none)"),
+    supportsAttachments: Optional[bool] = Query(
+        False,
+        description="Whether API client performing operation supports event attachments"
+    ),
+):
+    """
+    Updates an event (partial update) following Google Calendar API v3 specification.
+    
+    This method supports patch semantics and only updates the fields that are explicitly provided.
+    To do a full update, use PUT which replaces the entire event resource.
+    
+    ACL Required: writer or owner role
+
+    PATCH /calendars/{calendarId}/events/{eventId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "update event"
+        )
+
+        # Validate sendUpdates parameter
+        if sendUpdates and sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Get update data, excluding None values for partial update
+        update_data = event_request.model_dump(exclude_none=True)
+
+        if not update_data:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="No fields provided for update")
+
+        # Validate colorId if provided (events use event colors)
+        color_error = validate_request_colors(update_data, "event", database_id)
+        if color_error:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=color_error)
+
+        # Create query parameters object for event update
+        query_params = {
+            'conferenceDataVersion': conferenceDataVersion,
+            'maxAttendees': maxAttendees,
+            'sendUpdates': sendUpdates,
+            'supportsAttachments': supportsAttachments
+        }
+
+        event = event_manager.update_event(user_id, calendarId, eventId, event_request, is_patch=True, query_params=query_params)
+
+        if not event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+
+        # Filter attendees based on maxAttendees parameter
+        if maxAttendees is not None and event.attendees and len(event.attendees) > maxAttendees:
+            event.attendees = event.attendees[:maxAttendees]
+            event.attendeesOmitted = True
+
+        return event
+
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(verr))
+    except ValidationError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=e.errors())
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error updating event {eventId} in calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.put("/{eventId}", response_model=Event)
+async def update_event(
+    calendarId: str,
+    eventId: str,
+    event_request: EventUpdateRequest,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    conferenceDataVersion: Optional[int] = Query(
+        None,
+        ge=0,
+        le=1,
+        description="Version number of conference data supported by API client"
+    ),
+    maxAttendees: Optional[int] = Query(
+        None,
+        gt=0,
+        description="The maximum number of attendees to include in the response"
+    ),
+    sendUpdates: Optional[str] = Query("none", description="Guests who should receive notifications (all, externalOnly, none)"),
+    supportsAttachments: Optional[bool] = Query(
+        False,
+        description="Whether API client performing operation supports event attachments"
+    ),
+):
+    """
+    Updates an event (full update) following Google Calendar API v3 specification.
+    
+    This method does not support patch semantics and always updates the entire event resource.
+    To do a partial update, perform a get followed by an update using etags to ensure atomicity.
+
+    PUT /calendars/{calendarId}/events/{eventId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "update event"
+        )
+
+        # For PUT operations, validate that start and end are provided (required per Google API v3)
+        if not event_request.start or not event_request.end:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Both 'start' and 'end' fields are required for PUT operations"
+            )
+        
+        # Validate sendUpdates parameter
+        if sendUpdates and sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Ensure required fields have defaults for PUT requests
+        update_data = event_request.model_dump()
+        if not update_data.get("status"):
+            event_request.status = "confirmed"
+        if not update_data.get("visibility"):
+            event_request.visibility = "default"
+
+        # Validate colorId if provided (events use event colors)
+        color_error = validate_request_colors(update_data, "event", database_id)
+        if color_error:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=color_error)
+
+        # Create query parameters object for event update
+        query_params = {
+            'conferenceDataVersion': conferenceDataVersion,
+            'maxAttendees': maxAttendees,
+            'sendUpdates': sendUpdates,
+            'supportsAttachments': supportsAttachments
+        }
+
+        event = event_manager.update_event(user_id, calendarId, eventId, event_request, is_patch=False, query_params=query_params)
+
+        if not event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+
+        # Filter attendees based on maxAttendees parameter
+        if maxAttendees is not None and event.attendees and len(event.attendees) > maxAttendees:
+            event.attendees = event.attendees[:maxAttendees]
+            event.attendeesOmitted = True
+
+        return event
+
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(verr))
+    except ValidationError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=e.errors())
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error updating event {eventId} in calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.delete("/{eventId}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_event(
+    calendarId: str,
+    eventId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    sendUpdates: Optional[str] = Query("all", description="Guests who should receive notifications. Acceptable values are: 'all' (notifications sent to all guests), 'externalOnly' (notifications sent to non-Google Calendar guests only), 'none' (no notifications sent)"),
+):
+    """
+    Deletes an event
+    ACL Required: writer or owner role (owner required for events created by others)
+
+    DELETE /calendars/{calendarId}/events/{eventId}
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Validate sendUpdates parameter
+        if sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "delete event"
+        )
+
+        # Check if event exists first
+        existing_event = event_manager.get_event(user_id, calendarId, eventId)
+        if not existing_event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+
+        # Delete event with sendUpdates parameter
+        success = event_manager.delete_event(user_id, calendarId, eventId, sendUpdates)
+
+        if not success:
+            raise HTTPException(status_code=500, detail="Failed to delete event")
+
+        # Return 204 No Content (no response body)
+        return None
+
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error deleting event {eventId} from calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/{eventId}/move", response_model=Event)
+async def move_event(
+    calendarId: str,
+    eventId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    destination: str = Query(..., description="Calendar identifier of the target calendar"),
+    sendUpdates: Optional[str] = Query("all", description="Guests who should receive notifications"),
+):
+    """
+    Moves an event to another calendar
+    ACL Required: 
+    - writer or owner role on source calendar
+    - writer or owner role on destination calendar
+
+    POST /calendars/{calendarId}/events/{eventId}/move
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Validate sendUpdates parameter
+        if sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Check ACL permissions on source calendar
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "move event from"
+        )
+
+        # Check if event exists and validate event type for move operation
+        existing_event = event_manager.get_event(user_id, calendarId, eventId)
+        if not existing_event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+        
+        # Only default events can be moved - validate event type
+        if existing_event.eventType and existing_event.eventType != "default":
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Cannot move event of type '{existing_event.eventType}'. Only default events can be moved. Events of type 'birthday', 'focusTime', 'fromGmail', 'outOfOffice', and 'workingLocation' cannot be moved."
+            )
+
+        move_request = EventMoveRequest(
+            destination=destination, sendUpdates=sendUpdates
+        )
+
+        event = event_manager.move_event(user_id, calendarId, eventId, move_request)
+
+        if not event:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Event not found: {eventId}")
+
+        return event
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error moving event {eventId} from calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/quickAdd", response_model=Event, status_code=status.HTTP_201_CREATED)
+async def quick_add_event(
+    calendarId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    text: str = Query(..., description="The text describing the event to be created"),
+    sendUpdates: Optional[str] = Query("all", description="Guests who should receive notifications"),
+):
+    """
+    Creates an event based on a simple text string
+
+    POST /calendars/{calendarId}/events/quickAdd
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Validate sendUpdates parameter
+        if sendUpdates not in ["all", "externalOnly", "none"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid sendUpdates value '{sendUpdates}'. Acceptable values are: 'all', 'externalOnly', 'none'"
+            )
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "quick add event"
+        )
+
+        quick_add_request = EventQuickAddRequest(
+            text=text, sendUpdates=sendUpdates
+        )
+
+        event = event_manager.quick_add_event(user_id, calendarId, quick_add_request)
+
+        return event
+
+    except HTTPException:
+        raise
+    except ValidationError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=e.errors())
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error quick adding event to calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/import", response_model=Event, status_code=status.HTTP_201_CREATED)
+async def import_event(
+    calendarId: str,
+    event_request: EventImportRequest,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    conferenceDataVersion: Optional[int] = Query(
+        None,
+        ge=0,
+        le=1,
+        description="Version number of conference data supported by API client"
+    ),
+    supportsAttachments: Optional[bool] = Query(
+        False,
+        description="Whether API client performing operation supports event attachments"
+    ),
+):
+    """
+    Imports an event. This operation is used to add a private copy of an
+    existing event to a calendar.
+    
+    Requires authorization with at least one of the following scopes:
+    - https://www.googleapis.com/auth/calendar
+    - https://www.googleapis.com/auth/calendar.events
+    - https://www.googleapis.com/auth/calendar.app.created
+    - https://www.googleapis.com/auth/calendar.events.owned
+
+    POST /calendars/{calendarId}/events/import
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require writer or owner role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["writer", "owner"], "import event"
+        )
+
+        # Validate required fields
+        if not event_request.start or not event_request.end:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Both 'start' and 'end' fields are required for event import"
+            )
+
+        # Validate iCalUID
+        if not event_request.iCalUID:
+            raise ValueError("iCalUID is required field")
+
+        # Validate attendees email addresses exist in database
+        if event_request.attendees:
+            session = get_session(database_id)
+            try:
+                for attendee in event_request.attendees:
+                    if attendee.email:
+                        user = session.query(User).filter(User.email == attendee.email).first()
+                        if not user:
+                            raise HTTPException(
+                                status_code=status.HTTP_400_BAD_REQUEST,
+                                detail=f"Attendee email '{attendee.email}' not found in database. All attendee emails must be valid and present in the system."
+                            )
+            finally:
+                session.close()
+
+        # Validate colorId if provided (events use event colors)
+        event_data = event_request.model_dump(exclude_none=True)
+        color_error = validate_request_colors(event_data, "event", database_id)
+        if color_error:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=color_error)
+
+        # Create query params object
+        query_params = EventImportQueryParams(
+            conferenceDataVersion=conferenceDataVersion,
+            supportsAttachments=supportsAttachments
+        )
+        # Import the event as a private copy
+        imported_event = event_manager.import_event(
+            user_id=user_id,
+            calendar_id=calendarId,
+            event_request=event_request,
+            query_params=query_params
+        )
+
+        if not imported_event:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Failed to import event"
+            )
+
+        return imported_event
+
+    except HTTPException:
+        raise
+    except ValidationError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=e.errors())
+    except ValueError as e:
+        logger.error(f"Validation error importing event to calendar {calendarId}: {e}")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error importing event to calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.get("/{eventId}/instances", response_model=EventInstancesResponse)
+async def get_event_instances(
+    calendarId: str,
+    eventId: str,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    maxAttendees: Optional[int] = Query(None, description="The maximum number of attendees to include in the response. If there are more than the specified number of attendees, only the participant is returned. Optional."),
+    maxResults: Optional[int] = Query(250, lt=2500, description="Maximum number of events returned on one result page. By default the value is 250 events. The page size can never be larger than 2500 events. Optional.", gt=0, le=2500),
+    originalStart: Optional[str] = Query(None, description="The original start time of the instance in the result. Optional."),
+    pageToken: Optional[str] = Query(None, description="Token specifying which result page to return. Optional."),
+    showDeleted: Optional[bool] = Query(False, description="Whether to include deleted events (with status equals 'cancelled') in the result. Cancelled instances of recurring events will still be included if singleEvents is False. Optional."),
+    timeMin: Optional[str] = Query(None, description="Lower bound (inclusive) for an event's end time to filter by. Optional. The default is not to filter by end time. Must be an RFC3339 timestamp with mandatory time zone offset."),
+    timeMax: Optional[str] = Query(None, description="Upper bound (exclusive) for an event's start time to filter by. Optional. The default is not to filter by start time. Must be an RFC3339 timestamp with mandatory time zone offset."),
+    timeZone: Optional[str] = Query(None, description="Time zone used in the response. Optional. The default is the time zone of the calendar."),
+):
+    """
+    Returns instances of the specified recurring event
+
+    GET /calendars/{calendarId}/events/{eventId}/instances
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        # Check ACL permissions - require at least reader role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["reader", "writer", "owner"], "read event instances"
+        )
+
+        # Validate pageToken
+        if pageToken:
+            try:
+                page_token_int = int(pageToken)
+                if not page_token_int >= 0:
+                    raise ValueError("Please enter a valid pageToken value. Page token must be greater than equal to 0 and must be string integer")
+            except:
+                raise ValueError("Please enter a valid pageToken value. Page token must be greater than equal to 0 and must be string integer")
+
+
+        response = event_manager.get_event_instances(
+            user_id=user_id,
+            calendar_id=calendarId,
+            event_id=eventId,
+            max_attendees=maxAttendees,
+            max_results=maxResults,
+            original_start=originalStart,
+            page_token=pageToken,
+            show_deleted=showDeleted,
+            time_min=timeMin,
+            time_max=timeMax,
+            time_zone=timeZone,
+        )
+
+        return response
+
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error getting instances for event {eventId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/watch", response_model=Channel)
+async def watch_events(
+    calendarId: str,
+    watch_request: EventWatchRequest,
+    user_context: tuple[str, str] = Depends(get_user_context),
+    eventTypes: Optional[str] = Query(None, description="Event types of resources to watch. Optional. This parameter can be repeated multiple times to watch resources of different types. If unset, returns all event types. Acceptable values are: 'birthday' - Special all-day events with an annual recurrence, 'default' - Regular events, 'focusTime' - Focus time events, 'fromGmail' - Events from Gmail, 'outOfOffice' - Out of office events, 'workingLocation' - Working location events.")
+):
+    """
+    Watch for changes to Events resources
+
+    POST /calendars/{calendarId}/events/watch
+    """
+    try:
+        database_id, user_id = user_context
+        calendar_manager = get_calendar_manager(database_id)
+        event_manager = get_event_manager(database_id)
+
+        if eventTypes and eventTypes not in ["birthday", "default", "focusTime", "fromGmail", "outOfOffice", "workingLocation"]:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid eventType value '{eventTypes}'. Acceptable values are: 'birthday', 'default', 'focusTime', 'fromGmail', 'outOfOffice', 'workingLocation'"
+            )
+
+        # Validate user exists in this database (ensures ownership context)
+        from database.session_utils import get_session
+        from database.models.user import User
+        session = get_session(database_id)
+
+        try:
+            user_row = session.query(User).filter(User.user_id == user_id).first()
+            if not user_row:
+                raise HTTPException(status_code=404, detail=f"User not found: {user_id}")
+        finally:
+            session.close()
+
+
+        # Check ACL permissions - require at least reader role
+        check_event_acl_permissions(
+            calendar_manager, user_id, calendarId,
+            ["reader", "writer", "owner"], "watch events"
+        )
+
+        # Set up watch channel with event types filter
+        channel = event_manager.watch_events(user_id, calendarId, watch_request, eventTypes)
+        return channel
+
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"{str(e)}")
+    except HTTPException:
+        raise
+    except PermissionError as e:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error setting up events watch for calendar {calendarId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")

server/apis/freebusy/__init__.py

@@ -0,0 +1,7 @@
+"""
+FreeBusy API module
+"""
+
+from .router import router
+
+__all__ = ["router"]

server/apis/freebusy/router.py

@@ -0,0 +1,80 @@
+"""
+FreeBusy API endpoints following Google Calendar API v3 structure
+Handles FreeBusy query operations with exact Google API compatibility
+"""
+
+import logging
+from typing import Optional
+from fastapi import APIRouter, HTTPException, Header, Query, status, Depends
+from pydantic import ValidationError
+from schemas.freebusy import (
+    FreeBusyQueryRequest,
+    FreeBusyQueryResponse
+)
+from database.managers.freebusy_manager import FreeBusyManager
+from database.session_manager import CalendarSessionManager
+from middleware.auth import get_user_context
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/freebusy", tags=["freebusy"])
+
+# Initialize managers
+session_manager = CalendarSessionManager()
+
+
+def get_freebusy_manager(database_id: str) -> FreeBusyManager:
+    """Get freebusy manager for the specified database"""
+    return FreeBusyManager(database_id)
+
+
+@router.post("/query", response_model=FreeBusyQueryResponse)
+async def query_freebusy(
+    request: FreeBusyQueryRequest,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Returns free/busy information for a set of calendars
+    
+    POST /freeBusy
+    """
+    try:
+        database_id, user_id = user_context
+        freebusy_manager = get_freebusy_manager(database_id)
+        
+        # Validate request
+        if not request.items:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="At least one calendar item is required"
+            )
+        
+        if len(request.items) > 50:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Maximum 50 calendars allowed per query"
+            )
+        
+        response = freebusy_manager.query_freebusy(user_id, request)
+        
+        return response
+        
+    except ValidationError as e:
+        # Handle pydantic validation errors (timezone, schema validation)
+        logger.error(f"Schema validation error in FreeBusy query: {e}")
+        error_messages = []
+        for error in e.errors():
+            field = " -> ".join(str(loc) for loc in error["loc"])
+            msg = error["msg"]
+            error_messages.append(f"{field}: {msg}")
+        detail = "Validation failed: " + "; ".join(error_messages)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail)
+    except ValueError as e:
+        # Handle business logic validation errors (calendar ID existence, time range, etc.)
+        logger.error(f"Business validation error in FreeBusy query: {e}")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    except Exception as e:
+        logger.error(f"Unexpected error processing FreeBusy query: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                          detail="Internal server error occurred while processing the request")
+

server/apis/mcp/router.py

@@ -0,0 +1,31 @@
+"""
+MCP (Model Context Protocol) API Router
+Handles MCP protocol messages ONLY for Calendar API
+Database management APIs are in apis.database_router
+"""
+
+import logging
+from fastapi import APIRouter, Request, Response
+from handlers.mcp_handler import handle_mcp_request
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.post("/mcp")
+async def handle_mcp(request: Request):
+    """Handle MCP protocol messages"""
+    response = await handle_mcp_request(request)
+    if response is None:
+        # For notifications, return 204 No Content
+        return Response(content="", status_code=204, headers={"Content-Length": "0"})
+
+    # Check if response is already a dict or needs to be converted
+    if hasattr(response, "model_dump"):
+        return response.model_dump()
+    else:
+        return response
+
+
+# MCP protocol endpoint only - all other routes are at root level (no /api prefix)

server/apis/settings/router.py

@@ -0,0 +1,116 @@
+"""
+Calendar Settings API endpoints following Google Calendar API v3 structure
+Handles GET and LIST operations for calendar settings
+"""
+
+import logging
+from schemas.settings import SettingItem, SettingsListResponse, SettingsWatchRequest, Channel
+from fastapi import APIRouter, HTTPException, Query, status, Depends
+from database.managers.settings_manager import SettingManager
+from database.session_manager import CalendarSessionManager
+from middleware.auth import get_user_context
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/settings", tags=["settings"])
+
+# Initialize managers
+session_manager = CalendarSessionManager()
+
+def get_setting_manager(database_id: str) -> SettingManager:
+    return SettingManager(database_id)
+
+
+@router.get("", response_model=SettingsListResponse, operation_id="list_settings")
+async def list_settings(user_context: tuple[str, str] = Depends(get_user_context)):
+    """
+    Lists all user-visible settings
+
+    GET /settings
+    """
+    try:
+        database_id, user_id = user_context
+        manager = get_setting_manager(database_id)
+
+        # Pass user_id to manager
+        settings = manager.list_settings(user_id=user_id)
+
+        return SettingsListResponse(items=settings, etag="settings-collection-etag")
+    except Exception as e:
+        logger.error(f"Error listing settings: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.get("/{settingId}", response_model=SettingItem, operation_id="get_settings")
+async def get_settings(
+    settingId: str,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Returns a setting for the user
+
+    GET /settings/{settingId}
+    """
+    try:
+        database_id, user_id = user_context
+        manager = get_setting_manager(database_id)
+
+        logger.info(f"Fetching setting {settingId} for user {user_id}")
+        setting = manager.get_setting_by_id(settingId, user_id=user_id)
+
+        if not setting:
+            raise HTTPException(status_code=404, detail=f"Setting {settingId} not found for user {user_id}")
+        return setting
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting setting {settingId}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@router.post("/watch", response_model=Channel, operation_id="watch_settings")
+async def watch_settings(
+    watch_request: SettingsWatchRequest,
+    user_context: tuple[str, str] = Depends(get_user_context)
+):
+    """
+    Watch for changes to settings
+    
+    POST /settings/watch
+    
+    Sets up a notification channel to receive updates when settings change.
+    Following the Google Calendar API v3 pattern.
+    """
+    try:
+        database_id, user_id = user_context
+        manager = get_setting_manager(database_id)
+        
+        logger.info(f"Setting up settings watch for user {user_id} with channel {watch_request.id}")
+        
+        # Validate the watch request
+        if not watch_request.address:
+            raise HTTPException(
+                status_code=400,
+                detail="Webhook address is required"
+            )
+        
+        if not watch_request.id:
+            raise HTTPException(
+                status_code=400,
+                detail="Channel ID is required"
+            )
+        
+        # Create the watch channel
+        channel = manager.watch_settings(watch_request, user_id)
+        
+        logger.info(f"Successfully created settings watch channel {watch_request.id} for user {user_id}")
+        return channel
+        
+    except ValueError as verr:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"{str(verr)}")
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error setting up settings watch: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+

server/apis/users/router.py

@@ -0,0 +1,95 @@
+"""
+User API endpoints for user management operations
+"""
+
+import logging
+from fastapi import APIRouter, HTTPException, status, Header, Depends
+from database.managers.user_manager import UserManager
+from middleware.auth import authenticate_user_with_token
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+# Separate router for API endpoints that don't follow the "/users" pattern
+api_router = APIRouter(tags=["user-info"])
+
+
+def get_user_manager(database_id: str) -> UserManager:
+    """Get user manager for the specified database"""
+    return UserManager(database_id)
+
+
+@router.get("/email/{email}")
+async def get_user_by_email(email: str, x_database_id: str = Header(alias="x-database-id")):
+    """
+    Get user details by email address
+
+    GET /users/email/{email}
+    """
+    try:
+        if not x_database_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="Missing required header: x-database-id"
+            )
+
+        user_manager = get_user_manager(x_database_id)
+        user_info = user_manager.get_user_by_email(email)
+
+        if not user_info:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"User not found with email: {email}")
+
+        return user_info
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting user by email {email}: {e}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@api_router.get("/api/user-info")
+async def get_authenticated_user_info(auth_context: tuple[str, str] = Depends(authenticate_user_with_token)):
+    """
+    Get authenticated user information using access token
+    
+    GET /api/user-info
+    
+    Headers:
+    - x-database-id: Database identifier
+    - x-access-token: User access token
+    
+    Returns:
+    - user_id: User identifier
+    - name: User's display name
+    - email: User's email address
+    """
+    try:
+        database_id, user_id = auth_context
+        
+        user_manager = get_user_manager(database_id)
+        user_info = user_manager.get_user_by_id(user_id)
+        
+        if not user_info:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User not found"
+            )
+        
+        # Return only the required fields: user_id, name, email
+        response = {
+            "user_id": user_info["id"],
+            "name": user_info["name"],
+            "email": user_info["email"]
+        }
+        
+        return response
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting authenticated user info: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Internal server error: {str(e)}"
+        )

server/app.py

@@ -0,0 +1,56 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application entry point for the Calendar environment.
+
+This module re-exports the existing FastAPI app from main.py and provides
+the standard server entry point used by OpenEnv tooling.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+SERVER_DIR = Path(__file__).resolve().parent
+if str(SERVER_DIR) not in sys.path:
+    sys.path.insert(0, str(SERVER_DIR))
+
+try:
+    REPO_ROOT = SERVER_DIR.parents[3]
+except IndexError:
+    REPO_ROOT = None
+
+if REPO_ROOT is not None:
+    SRC_DIR = REPO_ROOT / "src"
+    if SRC_DIR.is_dir() and str(SRC_DIR) not in sys.path:
+        sys.path.insert(0, str(SRC_DIR))
+
+try:
+    from . import main as _main
+except ImportError:
+    import importlib
+
+    _main = importlib.import_module("main")
+
+app = _main.app
+
+
+def main(host: str = "0.0.0.0", port: int | None = None):
+    """Run the Calendar environment server with uvicorn."""
+
+    import uvicorn
+
+    if port is None:
+        port = int(os.getenv("API_PORT", "8004"))
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/calendar_environment.py

@@ -0,0 +1,23 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Calendar Environment wrapper.
+
+This file provides the standard environment class name expected in OpenEnv
+layouts while reusing the existing MCP environment implementation.
+"""
+
+from .openenv_wrapper.mcp_env_environment import MCPEnvironment
+
+
+class CalendarEnvironment(MCPEnvironment):
+    """Calendar environment backed by MCP tools."""
+
+    pass
+
+
+__all__ = ["CalendarEnvironment"]

server/calendar_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""
+MCP (Model Context Protocol) module for Calendar API
+"""

server/calendar_mcp/tools/__init__.py

@@ -0,0 +1,40 @@
+"""
+MCP Tools Module - Calendar API Tools
+
+This module aggregates all MCP tools for the Calendar API endpoints.
+Includes calendar management tools:
+- Calendars (create, read, update, delete, clear, list)
+- CalendarList (list, get, insert, patch, put, delete, watch)
+- Events (list, create, get, patch, update, delete, move, quickAdd, import, instances, watch)
+- Colors (get color definitions)
+- FreeBusy (query)
+- ACL (access control list management)
+- Users (user management)
+- Settings (calendar settings)
+
+Each tool corresponds to Calendar API endpoints
+"""
+
+# Import calendar tool categories
+from .acl import ACL_TOOLS
+from .calendars import CALENDARS_TOOLS
+from .calendar_list import CALENDAR_LIST_TOOLS
+from .events import EVENTS_TOOLS
+from .colors import COLORS_TOOLS
+from .users import USERS_TOOLS
+from .settings import SETTINGS_TOOLS
+from .freebusy import FREEBUSY_TOOLS
+
+# Combine all tools into the main MCP_TOOLS list
+MCP_TOOLS = []
+MCP_TOOLS.extend(CALENDARS_TOOLS)
+MCP_TOOLS.extend(CALENDAR_LIST_TOOLS)
+MCP_TOOLS.extend(EVENTS_TOOLS)
+MCP_TOOLS.extend(COLORS_TOOLS)
+MCP_TOOLS.extend(USERS_TOOLS)
+MCP_TOOLS.extend(SETTINGS_TOOLS)
+MCP_TOOLS.extend(ACL_TOOLS)
+MCP_TOOLS.extend(FREEBUSY_TOOLS)
+
+
+print(f"📦 MCP Tools Module Loaded: {len(MCP_TOOLS)} calendar API tools across 8 modules")

server/calendar_mcp/tools/acl.py

@@ -0,0 +1,351 @@
+"""
+ACL Tools Module
+
+This module contains tools related to ACL.
+Follows Google Calendar API v3 structure for ACL operations.
+"""
+ACL_TOOLS = [
+    {
+        "name": "get_acl_rule",
+        "description": """Retrieve an access control rule by ID.
+
+        Fetches the ACL rule for a calendar by rule ID.
+        Follows the structure of Google Calendar API v3 `/calendars/{calendarId}/acl/{ruleId}`.
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+          - ruleId: ACL rule identifier
+
+        Response Structure:
+          - kind: "calendar#aclRule"
+          - etag: ETag
+          - id: ACL rule ID
+          - scope: { type, value }
+          - role: ACL role (e.g., "reader", "writer")
+
+        Status Codes:
+          - 200: Success
+          - 404: Not Found
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "ruleId": {"type": "string", "minLength": 1}
+            },
+            "required": ["calendarId", "ruleId"]
+        }
+    },
+    {
+        "name": "list_acl_rules",
+        "description": """List ACL rules for a calendar with pagination and filtering support.
+
+        Returns access control rules for the given calendar with support for pagination and incremental synchronization.
+        Follows the structure of Google Calendar API v3 `/calendars/{calendarId}/acl`.
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+
+        Optional Parameters:
+          - maxResults: Maximum number of entries returned on one result page (1-250, default 100)
+          - pageToken: Token specifying which result page to return
+          - showDeleted: Whether to include deleted ACLs (role="none") in the result (default False)
+          - syncToken: Token for incremental synchronization, returns only entries changed since token
+
+        Response Structure:
+          - kind: "calendar#acl"
+          - etag: ETag of the ACL collection
+          - items: Array of ACL rules
+          - nextPageToken: Token for next page (if more results available)
+          - nextSyncToken: Token for next sync operation
+
+        Synchronization:
+          - When syncToken is provided, showDeleted is automatically set to True
+          - Deleted ACLs are always included in sync responses
+          - If syncToken expires, server responds with 410 GONE
+
+        Status Codes:
+          - 200: Success
+          - 400: Bad Request (invalid parameters)
+          - 410: Gone (sync token expired)
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "maxResults": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 250,
+                    "default": 100,
+                    "description": "Maximum number of entries returned on one result page"
+                },
+                "pageToken": {
+                    "type": "string",
+                    "description": "Token specifying which result page to return"
+                },
+                "showDeleted": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Whether to include deleted ACLs in the result"
+                },
+                "syncToken": {
+                    "type": "string",
+                    "description": "Token for incremental synchronization"
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "insert_acl_rule",
+        "description": """Insert a new access control rule.
+
+        Adds a new ACL rule to the specified calendar.
+        Equivalent to: POST /calendars/{calendarId}/acl
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+          - rule: ACL rule input (scope, role)
+
+        Optional Parameters:
+          - sendNotifications: Whether to send notifications about the calendar sharing change (default: True)
+
+        Response Structure:
+          - kind: "calendar#aclRule"
+          - etag: ETag
+          - id: ACL rule ID
+          - scope: { type, value }
+          - role: ACL role
+
+        Status Codes:
+          - 201: Created
+          - 400: Bad Request
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "scope": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string", "minLength": 1},
+                        "value": {"type": "string", "minLength": 1}
+                    },
+                    "required": ["type"]
+                },
+                "role": {"type": "string", "minLength": 1},
+                "sendNotifications": {
+                    "type": "boolean",
+                    "default": True,
+                    "description": "Whether to send notifications about the calendar sharing change"
+                }
+            },
+            "required": ["calendarId", "scope", "role"]
+        }
+    },
+    {
+        "name": "update_acl_rule",
+        "description": """Fully update an existing ACL rule.
+
+        Replaces an ACL rule with a new one.
+        Equivalent to: PUT /calendars/{calendarId}/acl/{ruleId}
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+          - ruleId: ACL rule ID
+          - rule: Complete rule replacement (scope, role)
+
+        Optional Parameters:
+          - sendNotifications: Whether to send notifications about the calendar sharing change (default: True)
+
+        Response:
+          - Updated ACL rule object
+
+        Status Codes:
+          - 200: Success
+          - 404: Not Found
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "ruleId": {"type": "string", "minLength": 1},
+                "scope": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string", "minLength": 1},
+                        "value": {"type": "string", "minLength": 1}
+                    },
+                    "required": ["type"]
+                },
+                "role": {"type": "string", "minLength": 1},
+                "sendNotifications": {
+                    "type": "boolean",
+                    "default": True,
+                    "description": "Whether to send notifications about the calendar sharing change"
+                }
+            },
+            "required": ["calendarId", "ruleId", "scope"]
+        }
+    },
+    {
+        "name": "patch_acl_rule",
+        "description": """Partially update an ACL rule.
+
+        Allows modifying select fields of an ACL rule.
+        Equivalent to: PATCH /calendars/{calendarId}/acl/{ruleId}
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+          - ruleId: ACL rule ID
+          - rule: Partial updates (any of: scope, role)
+
+        Optional Parameters:
+          - sendNotifications: Whether to send notifications about the calendar sharing change (default: True)
+
+        Response:
+          - Updated ACL rule object
+
+        Status Codes:
+          - 200: Success
+          - 404: Not Found
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "ruleId": {"type": "string", "minLength": 1},
+                "scope": {
+                    "type": "object",
+                    "properties": {
+                        "type": {"type": "string"},
+                        "value": {"type": "string"}
+                    }
+                },
+                "role": {"type": "string"},
+                "sendNotifications": {
+                    "type": "boolean",
+                    "default": True,
+                    "description": "Whether to send notifications about the calendar sharing change"
+                },
+            },
+            "required": ["calendarId", "ruleId"]
+        }
+    },
+    {
+        "name": "delete_acl_rule",
+        "description": """Delete an ACL rule.
+
+        Deletes a specific ACL rule from the calendar.
+        Equivalent to: DELETE /calendars/{calendarId}/acl/{ruleId}
+
+        Required Parameters:
+          - calendarId: Calendar identifier
+          - ruleId: ACL rule ID
+
+        Response:
+          - No content (204) on success
+
+        Status Codes:
+          - 204: No Content
+          - 404: Not Found
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {"type": "string", "minLength": 1},
+                "ruleId": {"type": "string", "minLength": 1},
+            },
+            "required": ["calendarId", "ruleId"]
+        }
+    },
+    {
+        "name": "watch_acl",
+        "description": """Set up a webhook to receive notifications when ACL rules change.
+
+        Sets up webhook notifications for ACL rule changes following Google Calendar API v3 structure.
+        Returns a channel for managing the watch. Monitors ACL rules in the specified calendar for changes.
+
+        Equivalent to: POST /calendars/{calendarId}/acl/watch
+
+        Required Parameters:
+          - calendarId: Calendar identifier to watch for ACL changes
+          - id: Unique channel identifier
+          - address: Webhook URL to receive notifications
+          - type: Channel type (default: "web_hook")
+          
+
+        Optional Parameters:
+          - token: Optional token for webhook authentication
+          - params: Additional channel parameters
+
+        Response Structure:
+          - Returns Channel resource with Google Calendar API v3 format:
+            * kind: "api#channel"
+            * id: Channel identifier
+            * resourceId: Resource being watched
+            * resourceUri: Resource URI path
+            * token: Authentication token (if provided)
+            * expiration: Channel expiration time (if set)
+
+        Channel Management:
+          - Each watch creates a unique notification channel
+          - Channels can expire (set expiration time)
+          - Multiple channels can watch the same calendar ACL
+          - Use unique channel IDs to avoid conflicts
+
+        Status Codes:
+          - 200: Success - Watch channel created successfully
+          - 400: Bad Request - Invalid channel configuration
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error
+        """,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Calendar identifier to watch for ACL changes"
+                },
+                "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Unique channel identifier"
+                },
+                "type": {
+                    "type": "string",
+                    "default": "web_hook",
+                    "description": "Channel type (only 'web_hook' supported)"
+                },
+                "address": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Webhook URL to receive notifications"
+                },
+                "token": {
+                    "type": "string",
+                    "description": "Optional token for webhook authentication"
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Additional channel parameters",
+                    "properties": {
+                        "ttl": {
+                            "type": "string",
+                            "description": "Time to live in seconds (string)."
+                        }
+                    }
+                }
+            },
+            "required": ["calendarId", "id", "type", "address"]
+        }
+    }
+]

server/calendar_mcp/tools/calendar_list.py

@@ -0,0 +1,704 @@
+"""
+CalendarList Tools Module
+
+This module contains tools related to calendar list management.
+Covers all 7 Google Calendar API v3 CalendarList endpoints for user calendar list operations.
+"""
+
+CALENDAR_LIST_TOOLS = [
+    {
+        "name": "get_calendar_list",
+        "description": """Returns the calendars on the user's calendar list.
+        
+        Lists all calendars in the user's calendar list with their display settings and access permissions.
+        Returns calendars with user-specific customizations like colors, visibility, and notification settings.
+        Supports pagination through pageToken and incremental synchronization through syncToken.
+        
+        Request Body Requirements:
+          - maxResults: Optional. Maximum number of entries returned (pagination). If 0, returns no items.
+          - minAccessRole: Optional. Minimum access role filter (freeBusyReader, reader, writer, owner)
+          - pageToken: Optional. Token specifying which result page to return (for pagination)
+          - showDeleted: Optional. Include deleted calendars in results (default: false)
+          - showHidden: Optional. Include hidden calendars in results (default: false)
+          - syncToken: Optional. Token for incremental synchronization (returns only changed entries)
+        
+        Pagination Support:
+          - Use maxResults to limit the number of calendars returned per page
+          - Use pageToken to retrieve subsequent pages of results
+          - Check nextPageToken in response to determine if more results are available
+          - Pass nextPageToken as pageToken in the next request to get the next page
+        
+        Incremental Synchronization:
+          - Use syncToken to get only entries that have changed since the last request
+          - syncToken cannot be used together with minAccessRole parameter
+          - When using syncToken, deleted and hidden entries are automatically included
+          - If syncToken expires, server returns 410 GONE and client should perform full sync
+          - Use nextSyncToken from response for subsequent incremental sync requests
+        
+        Response Structure:
+          - Returns calendar list collection with Google Calendar API v3 format:
+            * kind: "calendar#calendarList"
+            * etag: ETag of the collection
+            * items: Array of CalendarListEntry objects
+            * nextPageToken: Token for next page (if more results available)
+            * nextSyncToken: Token for incremental sync (always provided when items are returned)
+        
+        CalendarListEntry Structure:
+          - Each item contains calendar metadata plus user-specific settings:
+            * id: Calendar identifier
+            * summary: Display title (with summaryOverride if set)
+            * accessRole: User's permission level
+            * primary: Whether it's the user's primary calendar
+            * backgroundColor/foregroundColor: Display colors
+            * hidden: Whether hidden from calendar list
+            * selected: Whether selected in UI
+            * defaultReminders: User-specific default reminders
+            * notificationSettings: Notification preferences
+        
+        Status Codes:
+          - 200: Success - Calendar list retrieved successfully
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "maxResults": {
+                    "type": "integer",
+                    "description": "Maximum number of entries returned. If 0, returns no items.",
+                    "minimum": 0,
+                    "maximum": 250,
+                    "default": 100
+                },
+                "minAccessRole": {
+                    "type": "string",
+                    "description": "Minimum access role filter",
+                    "enum": ["freeBusyReader", "reader", "writer", "owner"]
+                },
+                "pageToken": {
+                    "type": "string",
+                    "description": "Token specifying which result page to return (for pagination)"
+                },
+                "showDeleted": {
+                    "type": "boolean",
+                    "description": "Include deleted calendars in results",
+                    "default": False
+                },
+                "showHidden": {
+                    "type": "boolean",
+                    "description": "Include hidden calendars in results",
+                    "default": False
+                },
+                "syncToken": {
+                    "type": "string",
+                    "description": "Token for incremental synchronization (returns only changed entries since last sync)"
+                }
+            },
+            "required": []
+        }
+    },
+    {
+        "name": "get_calendar_from_list",
+        "description": """Returns a calendar from the user's calendar list.
+        
+        Retrieves a specific calendar entry from the user's calendar list with all user-specific settings.
+        Shows how the calendar appears in the user's list with customizations and access permissions.
+        
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or the keyword 'primary' to refer to the user's primary calendar
+        
+        Response Structure:
+          - Returns CalendarListEntry with Google Calendar API v3 format:
+            * kind: "calendar#calendarListEntry"
+            * etag: ETag of the resource
+            * id: Calendar identifier
+            * summary: Display title (with summaryOverride if set)
+            * description: Calendar description
+            * location: Calendar location
+            * timeZone: Calendar timezone
+            * summaryOverride: Custom title override for this user
+            * colorId: Calendar color ID
+            * backgroundColor: Background color (hex)
+            * foregroundColor: Foreground color (hex)
+            * hidden: Whether hidden from calendar list
+            * selected: Whether selected in UI
+            * accessRole: User's permission level (freeBusyReader, reader, writer, owner)
+            * defaultReminders: User-specific default reminders
+            * notificationSettings: Notification preferences
+            * primary: Whether it's the user's primary calendar
+            * deleted: Whether the calendar is deleted
+        
+        Status Codes:
+          - 200: Success - Calendar entry retrieved successfully
+          - 404: Not Found - Calendar not found in user's list
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "add_calendar_to_list",
+        "description": """Inserts an existing calendar into the user's calendar list.
+        
+        Adds an existing calendar to the user's calendar list with custom display settings.
+        The calendar must already exist - this endpoint only adds it to the user's list with personalization.
+        
+        Request Body Requirements:
+          - id: Required. Calendar ID to add to user's list
+          - summaryOverride: Optional. Custom calendar title override
+          - colorId: Optional. Calendar color ID
+          - backgroundColor: Optional. Background color (hex format like #FF5733)
+          - foregroundColor: Optional. Foreground color (hex format like #FFFFFF)
+          - hidden: Optional. Whether calendar is hidden from list (default: false)
+          - selected: Optional. Whether calendar is selected in UI (default: true)
+          - defaultReminders: Optional. Array of default reminder settings
+          - notificationSettings: Optional. Notification preferences
+        
+        Calendar Must Exist:
+          - The calendar with the specified ID must already exist in the database
+          - This endpoint does not create new calendars, only adds them to user's list
+          - Use create_calendar tool first if the calendar doesn't exist
+        
+        Response Structure:
+          - Returns the created CalendarListEntry with Google Calendar API v3 format
+          - Includes all user-specific customizations applied
+        
+        Colors:
+          - To set backgroundColor/foregroundColor you must pass query param colorRgbFormat=true
+          - When RGB fields are provided, colorId (if present) is ignored
+        
+        Status Codes:
+          - 201: Created - Calendar added to list successfully
+          - 404: Not Found - Calendar with specified ID not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Calendar ID to add to user's list (UUID)",
+                    "minLength": 1
+                },
+                "colorRgbFormat": {
+                    "type": "boolean",
+                    "description": "Query param: if true, allows writing backgroundColor/foregroundColor",
+                    "default": False
+                },
+                "summaryOverride": {
+                    "type": "string",
+                    "description": "Custom calendar title override",
+                    "maxLength": 255
+                },
+                "colorId": {
+                    "type": "string",
+                    "description": "Calendar color ID",
+                    "maxLength": 50
+                },
+                "backgroundColor": {
+                    "type": "string",
+                    "description": "Background color (hex format like #FF5733)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },
+                "foregroundColor": {
+                    "type": "string", 
+                    "description": "Foreground color (hex format like #FFFFFF)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },
+                "hidden": {
+                    "type": "boolean",
+                    "description": "Whether calendar is hidden from list",
+                    "default": False
+                },
+                "selected": {
+                    "type": "boolean",
+                    "description": "Whether calendar is selected in UI",
+                    "default": True
+                },
+                "defaultReminders": {
+                    "type": "array",
+                    "description": "Default reminder settings",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "method": {
+                                "type": "string",
+                                "enum": ["email", "popup"],
+                                "description": "Reminder delivery method"
+                            },
+                            "minutes": {
+                                "type": "integer",
+                                "description": "Minutes before event to trigger reminder",
+                                "minimum": 0
+                            }
+                        },
+                        "required": ["method", "minutes"]
+                    }
+                },
+                "notificationSettings": {
+                    "type": "object",
+                    "description": "Notification preferences",
+                    "properties": {
+                        "notifications": {
+                            "type": "array",
+                            "description": "List of notification settings",
+                            "items": {
+                                "type": "object",
+                                "description": "Individual notification setting",
+                                "properties": {
+                                    "method": {
+                                        "type": "string",
+                                        "enum": ["email"],
+                                        "description": "Notification delivery method (only 'email' supported)"
+                                    },
+                                    "type": {
+                                        "type": "string",
+                                        "enum": [
+                                            "eventCreation",
+                                            "eventChange",
+                                            "eventCancellation",
+                                            "eventResponse",
+                                            "agenda"
+                                        ],
+                                        "description": "Notification type"
+                                    }
+                                },
+                                "required": ["method", "type"]
+                            }
+                        }
+                    }
+                }
+            },
+            "required": ["id"]
+        }
+    },
+    {
+        "name": "update_calendar_in_list",
+        "description": """Updates an entry on the user's calendar list (partial update).
+        
+        Partially updates calendar list entry settings. Only provided fields will be updated,
+        others remain unchanged. This allows fine-grained control over calendar display settings.
+        
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or 'primary'
+        
+        Request Body (all optional):
+          - summaryOverride: Custom calendar title override
+          - colorId: Calendar color ID
+          - backgroundColor: Background color (hex format like #FF5733)
+          - foregroundColor: Foreground color (hex format like #FFFFFF)
+          - hidden: Whether calendar is hidden from list
+          - selected: Whether calendar is selected in UI
+          - defaultReminders: Array of default reminder settings
+          - notificationSettings: Notification preferences
+        
+        Partial Update Behavior:
+          - Only fields provided in request body are updated
+          - Null values will clear the field (set to null) for string/complex fields
+          - 'hidden' and 'selected' cannot be null (booleans are NOT NULL in our DB)
+          - Missing fields are left unchanged
+          - At least one field must be provided for update
+
+        Response Structure:
+          - Returns updated CalendarListEntry with Google Calendar API v3 format
+          - Shows all current settings including unchanged fields
+
+        Colors:
+          - To set backgroundColor/foregroundColor you must pass query param colorRgbFormat=true
+          - When RGB fields are provided, colorId (if present) is ignored
+
+        Behavioral coupling:
+          - If hidden=true, the server will force selected=false
+          - If hidden=false, the server will force selected=true (matches observed UI behavior)
+        
+        Status Codes:
+          - 200: Success - Calendar list entry updated successfully
+          - 400: Bad Request - No fields provided for update
+          - 404: Not Found - Calendar not found in user's list
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1
+                },
+                "colorRgbFormat": {
+                    "type": "boolean",
+                    "description": "Query param: if true, allows writing backgroundColor/foregroundColor",
+                    "default": False
+                },
+                "summaryOverride": {
+                    "type": "string",
+                    "description": "Custom calendar title override",
+                    "maxLength": 255
+                },
+                "colorId": {
+                    "type": "string",
+                    "description": "Calendar color ID", 
+                    "maxLength": 50
+                },
+                "backgroundColor": {
+                    "type": "string",
+                    "description": "Background color (hex format like #FF5733)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },
+                "foregroundColor": {
+                    "type": "string",
+                    "description": "Foreground color (hex format like #FFFFFF)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },  
+                "hidden": {
+                    "type": "boolean",
+                    "description": "Whether calendar is hidden from list",
+                    "default": False
+                },
+                "selected": {
+                    "type": "boolean",
+                    "description": "Whether calendar is selected in UI",
+                    "default": True
+                },
+                "defaultReminders": {
+                    "type": "array",
+                    "description": "Default reminder settings",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "method": {
+                                "type": "string",
+                                "enum": ["email", "popup"],
+                                "description": "Reminder delivery method"
+                            },
+                            "minutes": {
+                                "type": "integer",
+                                "description": "Minutes before event to trigger reminder",
+                                "minimum": 0
+                            }
+                        },
+                        "required": ["method", "minutes"]
+                    }
+                },
+                "notificationSettings": {
+                    "type": "object",
+                    "description": "Notification preferences",
+                    "properties": {
+                        "notifications": {
+                            "type": "array",
+                            "description": "List of notification settings",
+                            "items": {
+                                "type": "object",
+                                "description": "Individual notification setting",
+                                "properties": {
+                                    "method": {
+                                        "type": "string",
+                                        "enum": ["email"],
+                                        "description": "Notification delivery method (only 'email' supported)"
+                                    },
+                                    "type": {
+                                        "type": "string",
+                                        "enum": [
+                                            "eventCreation",
+                                            "eventChange",
+                                            "eventCancellation",
+                                            "eventResponse",
+                                            "agenda"
+                                        ],
+                                        "description": "Notification type"
+                                    }
+                                },
+                                "required": ["method", "type"]
+                            }
+                        }
+                    }
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "replace_calendar_in_list",
+        "description": """Updates an entry on the user's calendar list (full update).
+        
+        Fully updates calendar list entry settings. All fields are replaced with provided values.
+        Fields not provided will be set to their default values (full replacement).
+        
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or 'primary'
+        
+        Request Body (all optional, but null/missing values will be set to defaults):
+          - summaryOverride: Custom calendar title override (null to clear)
+          - colorId: Calendar color ID (null to clear)
+          - backgroundColor: Background color (hex format like #FF5733, null to clear)
+          - foregroundColor: Foreground color (hex format like #FFFFFF, null to clear)
+          - hidden: Whether calendar is hidden from list (default: false)
+          - selected: Whether calendar is selected in UI (default: true)
+          - defaultReminders: Array of default reminder settings (null to clear)
+          - notificationSettings: Notification preferences (null to clear)
+          - conferenceProperties: Conference properties for this calendar (null to clear)
+        
+        Full Update Behavior:
+          - All fields are replaced (full replacement operation)
+          - Missing optional fields are set to null/defaults
+          - Required fields (hidden, selected) get default values if not provided
+          - This is different from PATCH which only updates provided fields
+
+        Response Structure:
+          - Returns updated CalendarListEntry with Google Calendar API v3 format
+          - Shows all current settings after full update
+
+        Colors:
+          - To set backgroundColor/foregroundColor you must pass query param colorRgbFormat=true
+          - When RGB fields are provided, colorId (if present) is ignored
+
+        Behavioral coupling:
+          - If hidden=true, the server will force selected=false
+          - If hidden=false, the server will force selected=true (matches observed UI behavior)
+        
+        Status Codes:
+          - 200: Success - Calendar list entry updated successfully
+          - 404: Not Found - Calendar not found in user's list
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1
+                },
+                "colorRgbFormat": {
+                    "type": "boolean",
+                    "description": "Query param: if true, allows writing backgroundColor/foregroundColor",
+                    "default": False
+                },
+                "summaryOverride": {
+                    "type": "string",
+                    "description": "Custom calendar title override",
+                    "maxLength": 255
+                },
+                "colorId": {
+                    "type": "string",
+                    "description": "Calendar color ID",
+                    "maxLength": 50
+                },
+                "backgroundColor": {
+                    "type": "string",
+                    "description": "Background color (hex format like #FF5733)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },
+                "foregroundColor": {
+                    "type": "string",
+                    "description": "Foreground color (hex format like #FFFFFF)",
+                    "pattern": "^#[0-9A-Fa-f]{6}$"
+                },
+                "hidden": {
+                    "type": "boolean",
+                    "description": "Whether calendar is hidden from list",
+                    "default": False
+                },
+                "selected": {
+                    "type": "boolean", 
+                    "description": "Whether calendar is selected in UI",
+                    "default": True
+                },
+                "defaultReminders": {
+                    "type": "array",
+                    "description": "Default reminder settings",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "method": {
+                                "type": "string",
+                                "description": "Reminder delivery method (email, popup). Empty string allowed to clear"
+                            },
+                            "minutes": {
+                                "type": "integer",
+                                "description": "Minutes before event to trigger reminder",
+                                "minimum": 0
+                            }
+                        }
+                    }
+                },
+                "notificationSettings": {
+                    "type": "object",
+                    "description": "Notification preferences",
+                    "properties": {
+                        "notifications": {
+                            "type": "array",
+                            "description": "List of notification settings",
+                            "items": {
+                                "type": "object",
+                                "description": "Individual notification setting",
+                                "properties": {
+                                    "method": {
+                                        "type": "string",
+                                        "description": "Notification delivery method. Empty string allowed to clear"
+                                    },
+                                    "type": {
+                                        "type": "string",
+                                        "description": "Notification type. Empty string allowed to clear"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "conferenceProperties": {
+                    "type": "object",
+                    "description": "Conference properties for this calendar",
+                    "properties": {
+                        "allowedConferenceSolutionTypes": {
+                            "type": "array",
+                            "description": "The types of conference solutions that are supported for this calendar",
+                            "items": {
+                                "type": "string",
+                                "enum": ["eventHangout", "eventNamedHangout", "hangoutsMeet"],
+                                "description": "Conference solution type"
+                            }
+                        }
+                    }
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "remove_calendar_from_list",
+        "description": """Removes a calendar from the user's calendar list.
+        
+        Removes a calendar from the user's calendar list (soft delete).
+        The calendar itself remains in the database but is no longer visible in the user's list.
+        Primary calendars cannot be removed from the calendar list.
+        
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID)
+        
+        Primary Calendar Protection:
+          - Primary calendars cannot be removed from the calendar list
+          - Attempting to remove primary calendar returns 400 Bad Request
+          - Primary calendars are always part of the user's list
+        
+        Operation Details:
+          - Calendar is soft-deleted (marked as deleted, not physically removed)
+          - Calendar data remains in database but is hidden from list
+          - Calendar can potentially be re-added to list later
+          - Does not affect the underlying calendar data or events
+        
+        Response Structure:
+          - Returns 204 No Content on successful removal
+          - No response body as per Google Calendar API v3
+        
+        Status Codes:
+          - 204: No Content - Calendar removed from list successfully
+          - 400: Bad Request - Attempted to remove primary calendar from list
+          - 404: Not Found - Calendar not found in user's list
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object", 
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "watch_calendar_list",
+        "description": """Watch for changes to CalendarList resources.
+        
+        Sets up webhook notifications (Channel) for changes to the user's calendar list.
+        Monitors for additions, removals, and updates to calendar list entries.
+        
+        Request Body (Channel):
+          - id: Required. Unique channel identifier for this watch
+          - type: Channel type (only "web_hook" (or "webhook") supported)
+          - address: Required. HTTPS URL where notifications will be sent
+          - token: Optional. Verification token for webhook security
+        
+        Webhook Notifications (simplified):
+          - Server will send POST requests to the specified address
+          - Notifications triggered by calendar list changes:
+            * Calendar added to or removed from list
+            * Calendar list entry settings updated
+            * Calendar permissions changed
+        
+        Channel Response:
+          - Returns Channel object with fields: kind, id, resourceId, resourceUri, token, expiration, type, address
+          - resourceUri is the collection path: /users/me/calendarList
+          - resourceId is generated by the server
+
+        Channel Management:
+          - Each watch creates a unique notification channel
+          - Channels can expire (set expiration time)
+          - Multiple channels can watch the same resource
+          - Use unique channel IDs to avoid conflicts
+        
+        Response Structure:
+          - Returns Channel resource with Google Calendar API v3 format:
+            * kind: "api#channel"
+            * id: Channel identifier
+            * resourceId: Resource being watched
+            * resourceUri: Resource URI path
+            * token: Verification token (if provided)
+            * expiration: Channel expiration time (if set)
+            * type: Channel type "web_hook" (or "webhook").
+            * address: Notification delivery address
+        
+        Status Codes:
+          - 200: Success - Watch channel created successfully
+          - 400: Bad Request - Invalid channel configuration or query parameters
+          - 500: Internal Server Error
+          
+        Note: This is a simplified implementation. In production, you would need:
+          - Webhook endpoint verification
+          - Channel management and cleanup
+          - Actual change detection and notification dispatch""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Unique channel identifier for this watch",
+                    "minLength": 1
+                },
+                "type": {
+                    "type": "string",
+                    "description": "Channel type (only web_hook supported; 'webhook' accepted as alias)",
+                    "enum": ["web_hook", "webhook"],
+                    "default": "web_hook"
+                },
+                "address": {
+                    "type": "string",
+                    "description": "HTTPS URL where notifications will be sent",
+                    "format": "uri",
+                    "minLength": 1
+                },
+                "token": {
+                    "type": "string",
+                    "description": "Verification token for webhook security",
+                    "maxLength": 256
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Optional parameters (Google spec supports 'ttl' in seconds as string)",
+                    "properties": {
+                        "ttl": {
+                            "type": "string",
+                            "description": "Time to live in seconds (string). Server computes expiration = now + ttl"
+                        }
+                    }
+                }
+            },
+            "required": ["id", "type", "address"]
+        }
+    }
+]

server/calendar_mcp/tools/calendars.py

@@ -0,0 +1,353 @@
+"""
+Calendars Tools Module
+
+This module contains tools related to calendar management.
+Covers calendar CRUD operations, clearing, and listing functionality.
+"""
+
+CALENDARS_TOOLS = [
+    {
+        "name": "create_calendar",
+        "description": """Create a new secondary calendar.
+
+        Creates a new calendar following Google Calendar API v3 structure. This endpoint
+        strictly creates a secondary calendar. It does not create or promote a primary calendar.
+        The user must already exist; otherwise a 404 is returned.
+
+        Request Body Requirements:
+          - summary: Required. Calendar title (1-255 characters)
+          - description: Optional. Calendar description (max 1000 characters)
+          - location: Optional. Geographic location (max 500 characters)
+          - timeZone: Optional. Calendar timezone in IANA format (default: UTC)
+          - conferenceProperties: Optional. Conference solution settings
+
+        Notes:
+          - This operation cannot create a primary calendar. Use account provisioning or separate tooling to ensure a primary exists.
+
+        Response Structure:
+          - Returns the created calendar with Google Calendar API v3 format:
+            * kind: "calendar#calendar"
+            * etag: ETag of the resource
+            * id: Unique calendar identifier (UUID)
+            * summary: Calendar title
+            * description: Calendar description (if provided)
+            * location: Calendar location (if provided)
+            * timeZone: Calendar timezone
+            * conferenceProperties: Conference settings (if provided)
+
+        Status Codes:
+          - 201: Created - Calendar created successfully
+          - 400: Bad Request - Invalid calendar data
+          - 404: Not Found - User not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "summary": {
+                    "type": "string",
+                    "description": "Calendar title (1-255 characters)",
+                    "minLength": 1,
+                    "maxLength": 255,
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Calendar description (max 1000 characters)",
+                    "maxLength": 1000,
+                },
+                "location": {
+                    "type": "string",
+                    "description": "Geographic location (max 500 characters)",
+                    "maxLength": 500,
+                },
+                "timeZone": {
+                    "type": "string",
+                    "description": "Calendar timezone in IANA format (default: UTC)",
+                    "default": "UTC",
+                },
+                "conferenceProperties": {
+                    "type": "object",
+                    "description": "Conference solution settings",
+                    "properties": {
+                        "allowedConferenceSolutionTypes": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "enum": ["eventHangout", "eventNamedHangout", "hangoutsMeet"]
+                            },
+                            "description": "Allowed conference solution types"
+                        }
+                    }
+                }
+            },
+            "required": ["summary"]
+        }
+    },
+    {
+        "name": "get_calendar",
+        "description": """Retrieve a specific calendar by its ID (supports 'primary').
+
+        Returns calendar metadata following Google Calendar API v3 structure.
+        Supports using the special keyword 'primary' as the calendar identifier to
+        target the user's primary calendar.
+
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or the keyword 'primary'
+
+        Response Structure:
+          - Returns calendar with Google Calendar API v3 format:
+            * kind: "calendar#calendar"
+            * etag: ETag of the resource
+            * id: Unique calendar identifier
+            * summary: Calendar title
+            * description: Calendar description (if present)
+            * location: Calendar location (if present)
+            * timeZone: Calendar timezone
+            * conferenceProperties: Conference settings (if present)
+
+        Status Codes:
+          - 200: Success - Calendar retrieved successfully
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID) or the keyword 'primary'",
+                    "minLength": 1,
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "patch_calendar",
+        "description": """Partially update calendar metadata (cannot change which calendar is primary).
+
+        Partially updates calendar metadata following Google Calendar API v3 structure.
+        Only provided fields will be updated, others remain unchanged.
+        You can update both primary and secondary calendars.
+        Supports using the special keyword 'primary' as the calendar identifier.
+
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or the keyword 'primary'
+
+        Request Body (all optional):
+          - summary: Calendar title (1-255 characters)
+          - description: Calendar description (max 1000 characters)
+          - location: Geographic location (max 500 characters)
+          - timeZone: Calendar timezone in IANA format
+          - conferenceProperties: Conference solution settings
+
+        Restrictions:
+          - Cannot modify which calendar is primary (the is_primary flag is immutable via PATCH)
+          - At least one field must be provided for update
+          - Primary status is automatically assigned and protected
+
+        Response Structure:
+          - Returns updated calendar with Google Calendar API v3 format
+
+        Status Codes:
+          - 200: Success - Calendar updated successfully
+          - 400: Bad Request - No fields provided or attempt to modify primary status
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID) or the keyword 'primary'",
+                    "minLength": 1,
+                },
+                "summary": {
+                    "type": "string",
+                    "description": "Calendar title (1-255 characters)",
+                    "minLength": 1,
+                    "maxLength": 255,
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Calendar description (max 1000 characters)",
+                    "maxLength": 1000,
+                },
+                "location": {
+                    "type": "string",
+                    "description": "Geographic location (max 500 characters)",
+                    "maxLength": 500,
+                },
+                "timeZone": {
+                    "type": "string",
+                    "description": "Calendar timezone in IANA format",
+                },
+                "conferenceProperties": {
+                    "type": "object",
+                    "description": "Conference solution settings",
+                    "properties": {
+                        "allowedConferenceSolutionTypes": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "enum": ["eventHangout", "eventNamedHangout", "hangoutsMeet"]
+                            },
+                            "description": "Allowed conference solution types"
+                        }
+                    }
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "update_calendar",
+        "description": """Fully update calendar metadata (cannot change which calendar is primary).
+
+        Completely updates calendar metadata following Google Calendar API v3 structure.
+        All provided fields replace existing values. Optional fields omitted will remain unchanged
+        in the current implementation. You can update both primary and secondary calendars.
+        Primary calendar status (which calendar is primary) cannot be modified via this endpoint.
+        Supports using the special keyword 'primary' as the calendar identifier.
+
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID) or the keyword 'primary'
+
+        Request Body (all optional; null clears for description/location/conferenceProperties):
+          - summary: Calendar title (1-255 characters)
+          - description: Calendar description (max 1000 characters) - null to clear
+          - location: Geographic location (max 500 characters) - null to clear
+          - timeZone: Calendar timezone in IANA format
+          - conferenceProperties: Conference solution settings - null to clear
+
+        Restrictions:
+          - Cannot modify which calendar is primary (the is_primary flag is immutable via PUT)
+
+        Response Structure:
+          - Returns updated calendar with Google Calendar API v3 format
+
+        Status Codes:
+          - 200: Success - Calendar updated successfully
+          - 400: Bad Request - Invalid update data or attempt to modify primary status
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID) or the keyword 'primary'",
+                    "minLength": 1
+                },
+                "summary": {
+                    "type": "string",
+                    "description": "Calendar title (1-255 characters)",
+                    "minLength": 1,
+                    "maxLength": 255
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Calendar description (max 1000 characters)",
+                    "maxLength": 1000
+                },
+                "location": {
+                    "type": "string",
+                    "description": "Geographic location (max 500 characters)",
+                    "maxLength": 500
+                },
+                "timeZone": {
+                    "type": "string",
+                    "description": "Calendar timezone in IANA format"
+                },
+                "conferenceProperties": {
+                    "type": "object",
+                    "description": "Conference solution settings",
+                    "properties": {
+                        "allowedConferenceSolutionTypes": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "enum": ["eventHangout", "eventNamedHangout", "hangoutsMeet"]
+                            },
+                            "description": "Allowed conference solution types"
+                        }
+                    }
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "delete_calendar",
+        "description": """Delete a secondary calendar (cannot delete primary calendar).
+
+        Deletes a calendar following Google Calendar API v3 behavior.
+        Primary calendars cannot be deleted - use clear operation instead.
+
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID)
+
+        Primary Calendar Protection:
+          - Primary calendars cannot be deleted
+          - Attempting to delete primary calendar returns 400 Bad Request
+          - Use clear_calendar tool to remove events from primary calendar
+
+        Cascade Behavior:
+          - Deleting a calendar also deletes all associated events
+          - This operation is irreversible
+
+        Response Structure:
+          - Returns 204 No Content on successful deletion
+          - No response body as per Google Calendar API v3
+
+        Status Codes:
+          - 204: No Content - Calendar deleted successfully
+          - 400: Bad Request - Attempted to delete primary calendar
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1,
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+    {
+        "name": "clear_calendar",
+        "description": """Clear all events from a calendar (useful for primary calendars).
+
+        Clears all events from a calendar following Google Calendar API v3 behavior.
+        This is the recommended way to "reset" a primary calendar since primary calendars cannot be deleted.
+
+        Request Body Requirements:
+          - calendarId: Required. Unique calendar identifier (UUID)
+
+        Operation Details:
+          - Removes all events from the specified calendar
+          - Calendar metadata remains unchanged
+          - Useful for primary calendars that cannot be deleted
+          - Can be used on any calendar (primary or secondary)
+
+        Response:
+          - Returns 204 No Content on successful clear (no response body)
+
+        Status Codes:
+          - 204: No Content - Calendar cleared successfully
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "calendarId": {
+                    "type": "string",
+                    "description": "Unique calendar identifier (UUID)",
+                    "minLength": 1,
+                }
+            },
+            "required": ["calendarId"]
+        }
+    },
+]

server/calendar_mcp/tools/colors.py

@@ -0,0 +1,57 @@
+"""
+Colors Tools Module
+
+This module contains tools related to Google Calendar color definitions.
+Provides static color palettes for calendars and events.
+"""
+
+COLORS_TOOLS = [
+    {
+        "name": "get_colors",
+        "description": """Retrieve the color definitions for calendars and events.
+        
+        Returns the global palette of color definitions used by Google Calendar.
+        This endpoint provides static color data and does not require authentication 
+        or user context as it returns predefined color schemes.
+        
+        Color Structure:
+          - calendar: Object mapping color IDs to calendar color definitions
+          - event: Object mapping color IDs to event color definitions
+          
+        Each color definition contains:
+          - background: The background color (hex format)
+          - foreground: The foreground color for text (hex format)
+          
+        Available Calendar Colors: 24 predefined colors (IDs 1-24)
+        Available Event Colors: 11 predefined colors (IDs 1-11)
+        
+        Usage Examples:
+          - Get all available colors for UI color pickers
+          - Validate color IDs before setting calendar/event colors
+          - Display color options to users
+          
+        Response Structure:
+          - Returns colors with Google Calendar API v3 format:
+            * kind: "calendar#colors"
+            * updated: Last modification timestamp
+            * calendar: Object with calendar color definitions
+            * event: Object with event color definitions
+            
+        Color Examples:
+          - Calendar Color 1: Background "#ac725e" (brown), Foreground "#1d1d1d" (dark)
+          - Event Color 1: Background "#a4bdfc" (light blue), Foreground "#1d1d1d" (dark)
+          - Event Color 11: Background "#dc2127" (red), Foreground "#1d1d1d" (dark)
+        
+        API Endpoint: GET /colors
+        
+        Status Codes:
+          - 200: Success - Color definitions retrieved
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+            "additionalProperties": False
+        }
+    }
+]

server/calendar_mcp/tools/freebusy.py

@@ -0,0 +1,158 @@
+"""
+FreeBusy MCP tools for Google Calendar API v3 compatibility
+All FreeBusy API endpoints with clean tool definitions
+"""
+
+FREEBUSY_TOOLS = [
+    {
+        "name": "query_freebusy",
+        "description": """Query free/busy information for a set of calendars.
+        
+        Returns free/busy information for specified calendars following Google Calendar API v3 structure.
+        Shows busy time periods when calendars have confirmed events that block time.
+        Essential for scheduling meetings and finding available time slots.
+        
+        Request Body Requirements:
+          - timeMin: Required. Lower bound for the query (RFC3339 timestamp)
+          - timeMax: Required. Upper bound for the query (RFC3339 timestamp)
+          - items: Required. List of calendar identifiers to query
+        
+        Optional Parameters:
+          - timeZone: Time zone for the query (default: UTC)
+          - groupExpansionMax: Maximum number of calendars to expand for groups
+          - calendarExpansionMax: Maximum number of events to expand for calendars
+        
+        Time Period Handling:
+          - Only confirmed events block time (status = "confirmed")
+          - Transparent events do not block time
+          - Overlapping events are merged into continuous busy periods
+          - Results are clipped to the requested time range
+        
+        Response Structure:
+          - Returns FreeBusy resource with Google Calendar API v3 format:
+            * kind: "calendar#freeBusy"
+            * timeMin: Query start time
+            * timeMax: Query end time
+            * calendars: Object with calendar IDs as keys
+            * Each calendar contains:
+              - busy: Array of busy time periods
+              - errors: Array of errors (if any)
+        
+        Status Codes:
+          - 200: Success - FreeBusy information retrieved successfully
+          - 400: Bad Request - Invalid query parameters
+          - 404: Not Found - Calendar not found
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "timeMin": {
+                    "type": "string",
+                    "description": "Lower bound for the query (RFC3339 timestamp)"
+                },
+                "timeMax": {
+                    "type": "string",
+                    "description": "Upper bound for the query (RFC3339 timestamp)"
+                },
+                "timeZone": {
+                    "type": "string",
+                    "description": "Time zone for the query (IANA timezone, default: UTC)"
+                },
+                "groupExpansionMax": {
+                    "type": "integer",
+                    "description": "Maximum number of calendars to expand for groups"
+                },
+                "calendarExpansionMax": {
+                    "type": "integer", 
+                    "description": "Maximum number of events to expand for calendars"
+                },
+                "items": {
+                    "type": "array",
+                    "description": "List of calendar identifiers to query",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "id": {
+                                "type": "string",
+                                "description": "Calendar identifier"
+                            }
+                        },
+                        "required": ["id"]
+                    }
+                }
+            },
+            "required": ["timeMin", "timeMax", "items"]
+        }
+    },
+]
+
+
+# Additional helper information for FreeBusy functionality
+FREEBUSY_CONCEPTS = {
+    "busy_time_calculation": {
+        "description": "How busy times are calculated from calendar events",
+        "rules": [
+            "Only events with status='confirmed' block time",
+            "Events with transparency='transparent' do not block time",
+            "All-day events block the entire day",
+            "Overlapping events are merged into continuous periods",
+            "Event times are clipped to the query time range"
+        ]
+    },
+    "time_zone_handling": {
+        "description": "How timezones are handled in FreeBusy queries",
+        "details": [
+            "Query times should be in RFC3339 format",
+            "All calculations are done in UTC internally",
+            "Results are returned in the requested timezone",
+            "Event times are converted from their native timezone",
+            "Default timezone is UTC if not specified"
+        ]
+    },
+    "error_handling": {
+        "description": "How errors are handled in FreeBusy responses",
+        "scenarios": [
+            "Calendar not found: Returns error in calendar result",
+            "No access to calendar: Returns error in calendar result", 
+            "Invalid time range: Returns 400 Bad Request",
+            "Too many calendars: Returns 400 Bad Request",
+            "Internal errors: Calendar marked with backend error"
+        ]
+    },
+    "performance_considerations": {
+        "description": "Performance aspects of FreeBusy queries",
+        "guidelines": [
+            "Limit time range to reasonable periods (max 366 days)",
+            "Limit number of calendars per query (max 50)",
+            "Use batch queries for multiple time ranges efficiently",
+            "Consider caching for frequently accessed calendars"
+        ]
+    }
+}
+
+
+# Sample usage examples for documentation
+FREEBUSY_EXAMPLES = {
+    "simple_query": {
+        "description": "Query busy times for a single calendar today",
+        "request": {
+            "timeMin": "2024-01-15T00:00:00Z",
+            "timeMax": "2024-01-16T00:00:00Z", 
+            "timeZone": "UTC",
+            "items": [{"id": "primary"}]
+        }
+    },
+    "multiple_calendars": {
+        "description": "Query multiple calendars for the next week",
+        "request": {
+            "timeMin": "2024-01-15T00:00:00Z",
+            "timeMax": "2024-01-22T00:00:00Z",
+            "timeZone": "America/New_York", 
+            "items": [
+                {"id": "primary"},
+                {"id": "work@company.com"},
+                {"id": "team@company.com"}
+            ]
+        }
+    },
+}

server/calendar_mcp/tools/settings.py

@@ -0,0 +1,161 @@
+"""
+Settings Tools Module
+
+This module contains tools related to user settings management.
+Follows Google Calendar API v3 structure for settings operations.
+Covers listing and retrieving settings only.
+"""
+
+SETTINGS_TOOLS = [
+    {
+        "name": "get_settings",
+        "description": """Retrieve a specific user setting by ID.
+
+        Returns the value of a setting resource by its ID.
+        Follows Google Calendar API v3 `/settings/{settingId}` structure.
+
+        Request Body Requirements:
+          - settingId: Required. Unique identifier of the setting (e.g., "timezone")
+
+        Response Structure:
+          - kind: "calendar#setting"
+          - etag: ETag of the setting
+          - id: Unique setting identifier
+          - value: Current value of the setting
+          - user_id: ID of the user who owns the setting
+
+        Status Codes:
+          - 200: Success - Setting returned successfully
+          - 404: Not Found - No setting exists with the given ID
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "settingId": {
+                    "type": "string",
+                    "description": "Unique identifier of the setting (e.g., 'timezone')",
+                    "minLength": 1
+                }
+            },
+            "required": ["settingId"]
+        }
+    },
+    {
+        "name": "list_settings",
+        "description": """List all visible user settings.
+
+        Retrieves all settings that are visible to the authenticated user.
+        Follows the structure of Google Calendar API v3 `/settings` endpoint.
+
+        No request body required.
+
+        Response Structure:
+          - kind: "calendar#settings"
+          - etag: ETag for the entire settings collection
+          - items: Array of setting resources, each containing:
+            * kind: "calendar#setting"
+            * etag: ETag of the setting
+            * id: Unique identifier of the setting (e.g., "timezone")
+            * value: Current value of the setting
+
+        Status Codes:
+          - 200: Success - List of settings returned
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        }
+    },
+    {
+        "name": "watch_settings",
+        "description": """Watch for changes to user settings.
+
+        Sets up a notification channel to receive updates when settings change.
+        Follows Google Calendar API v3 `/settings/watch` structure.
+
+        Creates a watch channel that will send webhook notifications to the specified
+        address whenever settings are modified. The channel will automatically expire
+        after a maximum of 24 hours or at the specified expiration time.
+
+        Request Body Requirements:
+          - id: Required. Unique identifier for the channel
+          - type: Optional. Channel type (defaults to "web_hook")
+          - address: Required. URL where notifications will be sent
+          - token: Optional. Verification token for webhook security
+          - params: Optional. Additional parameters as key-value pairs
+
+        Optional Parameters:
+          - token: Optional token for webhook authentication
+          - params: Additional channel parameters
+
+        Response Structure:
+          - kind: "api#channel"
+          - id: Channel identifier
+          - resourceId: Resource being watched
+          - resourceUri: URI of the resource ("/settings")
+          - token: Verification token (if provided)
+          - expiration: Channel expiration time
+
+        Webhook Notification Format:
+        Your webhook will receive POST requests with this payload:
+        {
+          "kind": "api#channel",
+          "id": "channel-id",
+          "resourceId": "settings-user-id",
+          "resourceUri": "/settings",
+          "eventType": "update|insert|delete",
+          "resourceState": "sync",
+          "timestamp": "2024-10-01T18:30:00Z",
+          "data": {
+            "kind": "calendar#setting",
+            "id": "setting-id",
+            "value": "new-value",
+            "oldValue": "previous-value",
+            "user_id": "user-id"
+          }
+        }
+
+        Status Codes:
+          - 200: Success - Watch channel created
+          - 400: Bad Request - Invalid request parameters
+          - 500: Internal Server Error""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Unique identifier for the watch channel",
+                    "minLength": 1
+                },
+                "type": {
+                    "type": "string",
+                    "description": "Type of notification channel",
+                    "default": "web_hook",
+                    "enum": ["web_hook"]
+                },
+                "address": {
+                    "type": "string",
+                    "description": "URL where webhook notifications will be sent",
+                    "format": "uri",
+                    "minLength": 1
+                },
+                "token": {
+                    "type": "string",
+                    "description": "Optional verification token for webhook security"
+                },
+                "params": {
+                    "type": "object",
+                    "description": "Additional parameters as key-value pairs",
+                    "properties": {
+                        "ttl": {
+                            "type": "string",
+                            "description": "Time to live in seconds (string)."
+                        }
+                    }
+                }
+            },
+            "required": ["id", "type", "address"]
+        }
+    },
+]

server/calendar_mcp/tools/users.py

@@ -0,0 +1,37 @@
+"""
+MCP Tools for User Management
+"""
+
+USERS_TOOLS = [
+    {
+        "name": "get_user_by_email",
+        "description": """Get user details by email address
+
+This tool retrieves complete user information using their email address, including user ID, name, and other profile details.
+
+**API Endpoint:** GET /users/email/{email}
+
+**Parameters:**
+- email (required): The email address to lookup
+
+**Returns:**
+Complete user information including id, name, given_name, family_name, picture, locale, timezone, is_active, is_verified, etc.
+
+**Example:**
+```json
+{
+  "email": "user@example.com"
+}
+```""",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "description": "Email address to lookup"
+                }
+            },
+            "required": ["email"]
+        }
+    }
+]

server/data/__init__.py

@@ -0,0 +1 @@
+"""Data package"""

server/data/enhanced_event_seed_data.py

@@ -0,0 +1,893 @@
+"""
+Enhanced Event Seed Data with all new fields and related tables
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import List, Dict, Any
+import json
+
+
+def get_enhanced_event_seed_data() -> Dict[str, Any]:
+    """
+    Generate comprehensive seed data demonstrating all Event model features including:
+    - All new Event fields (conference_data, reminders, extended_properties, etc.)
+    - Attendees with various statuses and roles
+    - Attachments (file URLs)
+    - Working location properties for different work modes
+    """
+    
+    # Base datetime for consistent relative dates
+    base_date = datetime.now(timezone.utc).replace(hour=9, minute=0, second=0, microsecond=0)
+    
+    # Office locations - required for working location properties
+    office_locations_data = [
+        {
+            "id": "office-building-1",
+            "buildingId": "building-1",
+            "deskId": None,
+            "floorId": None,
+            "floorSectionId": None,
+            "label": "TechCorp Main Campus - Building 1"
+        },
+        {
+            "id": "office-building-2-floor-3",
+            "buildingId": "building-2",
+            "deskId": "desk-W3-45",
+            "floorId": "floor-3",
+            "floorSectionId": "west-wing",
+            "label": "TechCorp Main Campus - Building 2, Floor 3, West Wing, Desk W3-45"
+        },
+        {
+            "id": "office-meeting-room-a",
+            "buildingId": "building-1",
+            "deskId": None,
+            "floorId": "floor-1",
+            "floorSectionId": "conference-area",
+            "label": "Conference Room A - Building 1"
+        }
+    ]
+    
+    # Events data -  to match model exactly
+    events_data = [
+        {
+            "event_id": "event-corrected-001",
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "organizer_id": "alice_manager",
+            "organizer_email": "alice.johnson@techcorp.com",
+            "organizer_display_name": "Alice Johnson",
+            "organizer_self": True,
+            "summary": "Sprint Planning & Architecture Review",
+            "description": "Detailed sprint planning session with architecture discussion for Q4 features. We'll review user stories, estimate effort, and plan the technical approach.",
+            "location": "Conference Room A, Building 1",
+            "start_datetime": base_date,
+            "end_datetime": base_date + timedelta(hours=2),
+            "start_timezone": "America/New_York",
+            "end_timezone": "America/New_York",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date,
+            "originalStartTime_timeZone": "America/New_York",
+            "recurrence": None,
+            "status": "confirmed",
+            "visibility": "default",
+            "color_id": "7",
+            "eventType": "default",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": True,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 1,
+            "iCalUID":"event-corrected-001@gmail.com",
+            "source": {
+                "title": "Sprint Planning Board",
+                "url": "https://jira.techcorp.com/sprint-planning-q4"
+            }
+        },
+        {
+            "event_id": "event-corrected-002",
+            "calendar_id": "bob-development",
+            "user_id": "bob_developer",
+            "organizer_id": "bob_developer",
+            "organizer_email": "bob.smith@techcorp.com",
+            "organizer_display_name": "Bob Smith",
+            "organizer_self": True,
+            "summary": "Deep Work: Core Algorithm Implementation",
+            "description": "Focused development time for implementing the new search algorithm. No interruptions please.",
+            "location": "Developer Workspace, Building 2",
+            "start_datetime": base_date + timedelta(days=1, hours=1),
+            "end_datetime": base_date + timedelta(days=1, hours=4),
+            "start_timezone": "America/Los_Angeles",
+            "end_timezone": "America/Los_Angeles",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=1, hours=1),
+            "originalStartTime_timeZone": "America/Los_Angeles",
+            "recurrence": None,
+            "status": "confirmed",
+            "visibility": "private",
+            "color_id": "9",
+            "eventType": "focusTime",
+            "focusTimeProperties": {
+                "autoDeclineMode": "declineNone",
+                "declineMessage": "I'm in focus time. Please reschedule or reach out via Slack for urgent matters.",
+                "chatStatus": "doNotDisturb"
+            },
+            "guestsCanInviteOthers": False,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": False,
+            "outOfOfficeProperties": None,
+            "sequence": 0,
+            "source": None,
+            "iCalUID":"event-corrected-002@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-003",
+            "calendar_id": "carol-primary",
+            "user_id": "carol_designer",
+            "organizer_id": "carol_designer",
+            "organizer_email": "carol.white@techcorp.com",
+            "organizer_display_name": "Carol White",
+            "organizer_self": True,
+            "summary": "Annual Leave - Family Vacation",
+            "description": "Taking time off for family vacation. Will have limited access to email.",
+            "location": "Bali, Indonesia",
+            "start_datetime": base_date + timedelta(days=14),
+            "end_datetime": base_date + timedelta(days=21),
+            "start_timezone": "Asia/Makassar",
+            "end_timezone": "Asia/Makassar",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=14),
+            "originalStartTime_timeZone": "Asia/Makassar",
+            "recurrence": None,
+            "status": "confirmed",
+            "visibility": "public",
+            "color_id": "4",
+            "eventType": "outOfOffice",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": False,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": {
+                "autoDeclineMode": "declineAllConflictingInvitations",
+                "declineMessage": "I'm currently on vacation and won't be available. For urgent design matters, please contact Sarah (sarah@techcorp.com). I'll respond to messages when I return.",
+                "autoDeclineEventTypes": [
+                    "default",
+                    "focusTime",
+                    "workingLocation"
+                ]
+            },
+            "sequence": 0,
+            "source": None,
+            "iCalUID":"event-corrected-003@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-004",
+            "calendar_id": "bob-primary",
+            "user_id": "bob_developer",
+            "organizer_id": "bob_developer",
+            "organizer_email": "bob.smith@techcorp.com",
+            "organizer_display_name": "Bob Smith",
+            "organizer_self": True,
+            "summary": "Office Day - Collaboration Sessions",
+            "description": "In office today for team collaboration and pair programming sessions.",
+            "location": None,
+            "start_datetime": base_date + timedelta(days=2),
+            "end_datetime": base_date + timedelta(days=2, hours=8),
+            "start_timezone": "America/Los_Angeles",
+            "end_timezone": "America/Los_Angeles",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=2),
+            "originalStartTime_timeZone": "America/Los_Angeles",
+            "recurrence": None,
+            "status": "confirmed",
+            "visibility": "public",
+            "color_id": "2",
+            "eventType": "workingLocation",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": True,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 0,
+            "source": None,
+            "iCalUID":"event-corrected-004@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-005",
+            "calendar_id": "dave-primary",
+            "user_id": "dave_sales",
+            "organizer_id": "dave_sales",
+            "organizer_email": "dave.brown@techcorp.com",
+            "organizer_display_name": "Dave Brown",
+            "organizer_self": True,
+            "summary": "Dave's Birthday",
+            "description": "Happy Birthday Dave!",
+            "location": None,
+            "start_datetime": base_date + timedelta(days=30),
+            "end_datetime": base_date + timedelta(days=30, hours=1),
+            "start_timezone": None,
+            "end_timezone": None,
+            "originalStartTime_date": (base_date + timedelta(days=30)).date(),
+            "originalStartTime_dateTime": None,
+            "originalStartTime_timeZone": "UTC",
+            "recurrence": None,
+            "status": "confirmed",
+            "visibility": "public",
+            "color_id": "6",
+            "eventType": "birthday",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": True,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 0,
+            "source": None,
+            "iCalUID":"event-corrected-005@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-006",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "organizer_id": "dave_sales",
+            "organizer_email": "dave.brown@techcorp.com",
+            "organizer_display_name": "Dave Brown",
+            "organizer_self": True,
+            "recurring_event_id": "rec-event-001",
+            "summary": "Enterprise Client Demo - TechCorp Solutions",
+            "description": "Product demonstration for MegaCorp Inc. Focus on enterprise features, security, and scalability. Bring pricing sheets and technical specs.",
+            "location": "MegaCorp Headquarters, 123 Business Ave, New York, NY",
+            "start_datetime": base_date + timedelta(days=3, hours=2),
+            "end_datetime": base_date + timedelta(days=3, hours=4),
+            "start_timezone": "America/New_York",
+            "end_timezone": "America/New_York",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=3, hours=2),
+            "originalStartTime_timeZone": "America/New_York",
+            "recurrence": ["RRULE:COUNT=2"],
+            "status": "confirmed",
+            "visibility": "default",
+            "color_id": "1",
+            "eventType": "default",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": False,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 2,
+            "source": {
+                "title": "CRM System - MegaCorp Deal",
+                "url": "https://crm.techcorp.com/deals/megacorp-2024"
+            },
+            "iCalUID":"event-icalid-001@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-007",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "organizer_id": "dave_sales",
+            "organizer_email": "dave.brown@techcorp.com",
+            "organizer_display_name": "Dave Brown",
+            "organizer_self": True,
+            "recurring_event_id": "rec-event-001",
+            "summary": "Enterprise Client Demo - TechCorp Solutions",
+            "description": "Product demonstration for MegaCorp Inc. Focus on enterprise features, security, and scalability. Bring pricing sheets and technical specs.",
+            "location": "MegaCorp Headquarters, 123 Business Ave, New York, NY",
+            "start_datetime": base_date + timedelta(days=4, hours=2),
+            "end_datetime": base_date + timedelta(days=4, hours=4),
+            "start_timezone": "America/New_York",
+            "end_timezone": "America/New_York",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=4, hours=2),
+            "originalStartTime_timeZone": "America/New_York",
+            "recurrence": ["RRULE:COUNT=2"],
+            "status": "confirmed",
+            "visibility": "default",
+            "color_id": "1",
+            "eventType": "default",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": False,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 2,
+            "source": {
+                "title": "CRM System - MegaCorp Deal",
+                "url": "https://crm.techcorp.com/deals/megacorp-2024"
+            },
+            "iCalUID":"event-icalid-001@gmail.com"
+        },
+        {
+            "event_id": "event-corrected-008",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "organizer_id": "dave_sales",
+            "organizer_email": "dave.brown@techcorp.com",
+            "organizer_display_name": "Dave Brown",
+            "organizer_self": True,
+            "recurring_event_id": "rec-event-001",
+            "summary": "Enterprise Client Demo - TechCorp Solutions",
+            "description": "Product demonstration for MegaCorp Inc. Focus on enterprise features, security, and scalability. Bring pricing sheets and technical specs.",
+            "location": "MegaCorp Headquarters, 123 Business Ave, New York, NY",
+            "start_datetime": base_date + timedelta(days=5, hours=2),
+            "end_datetime": base_date + timedelta(days=5, hours=4),
+            "start_timezone": "America/New_York",
+            "end_timezone": "America/New_York",
+            "originalStartTime_date": None,
+            "originalStartTime_dateTime": base_date + timedelta(days=5, hours=2),
+            "originalStartTime_timeZone": "America/New_York",
+            "recurrence": ["RRULE:COUNT=2"],
+            "status": "confirmed",
+            "visibility": "default",
+            "color_id": "1",
+            "eventType": "default",
+            "focusTimeProperties": None,
+            "guestsCanInviteOthers": False,
+            "guestsCanModify": False,
+            "guestsCanSeeOtherGuests": True,
+            "outOfOfficeProperties": None,
+            "sequence": 2,
+            "source": {
+                "title": "CRM System - MegaCorp Deal",
+                "url": "https://crm.techcorp.com/deals/megacorp-2024"
+            },
+            "iCalUID":"event-icalid-001@gmail.com"
+        }
+    ]
+
+    recurring_event_data = [
+        {
+            "recurring_event_id":"rec-event-001",
+            "original_recurrence":["RRULE:COUNT=2"]
+        }
+    ]
+    
+    # ConferenceData - separate table (correct relationship name)
+    conference_data = [
+        {
+            "id": "conf-corrected-001",
+            "event_id": "event-corrected-001",
+            "request_id": "req-sprint-planning-001",
+            "solution_type": "hangoutsMeet",
+            "status_code": "success",
+            "meeting_uri": "https://meet.google.com/abc-defg-hij",
+            "label": "Sprint Planning Meet"
+        },
+        {
+            "id": "conf-corrected-002", 
+            "event_id": "event-corrected-006",
+            "request_id": "req-client-demo-001",
+            "solution_type": "hangoutsMeet",
+            "status_code": "success",
+            "meeting_uri": "https://meet.google.com/enterprise-demo-xyz",
+            "label": "Client Demo Backup"
+        }
+    ]
+    
+    # BirthdayProperties - separate table (correct relationship name)
+    birthday_properties = [
+        {
+            "id": "birthday-corrected-001",
+            "event_id": "event-corrected-005",
+            "type": "birthday"
+        }
+    ]
+    
+    # ExtendedProperties - separate table with scope enum (correct relationship name)
+    extended_properties = [
+        {
+            "id": "ext-corrected-001",
+            "event_id": "event-corrected-001",
+            "scope": "private",
+            "properties": {
+                "departmentBudget": "engineering",
+                "projectCode": "PROJ-2024-Q4"
+            }
+        },
+        {
+            "id": "ext-corrected-002",
+            "event_id": "event-corrected-001", 
+            "scope": "shared",
+            "properties": {
+                "meetingType": "sprint_planning",
+                "priority": "high"
+            }
+        },
+        {
+            "id": "ext-corrected-003",
+            "event_id": "event-corrected-002",
+            "scope": "private", 
+            "properties": {
+                "taskType": "development",
+                "estimatedComplexity": "high"
+            }
+        },
+        {
+            "id": "ext-corrected-004",
+            "event_id": "event-corrected-003",
+            "scope": "shared",
+            "properties": {
+                "backupContact": "sarah@techcorp.com",
+                "vacationType": "personal"
+            }
+        },
+        {
+            "id": "ext-corrected-005",
+            "event_id": "event-corrected-004",
+            "scope": "private",
+            "properties": {
+                "commute_reminder": "Leave by 8:00 AM to avoid traffic"
+            }
+        },
+        {
+            "id": "ext-corrected-006",
+            "event_id": "event-corrected-006",
+            "scope": "private",
+            "properties": {
+                "dealValue": "$250000",
+                "clientPriority": "high",
+                "preparationTime": "2 hours"
+            }
+        },
+        {
+            "id": "ext-corrected-007",
+            "event_id": "event-corrected-006",
+            "scope": "shared",
+            "properties": {
+                "meetingType": "client_demo",
+                "department": "sales"
+            }
+        }
+    ]
+     
+    # Reminders - separate table with method enum (correct relationship name)
+    reminders_data = [
+        {
+            "id": "rem-corrected-001",
+            "event_id": "event-corrected-001",
+            "method": "email",
+            "minutes": 1440,  # 1 day before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-002",
+            "event_id": "event-corrected-001",
+            "method": "popup",
+            "minutes": 30,  # 30 minutes before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-003",
+            "event_id": "event-corrected-002",
+            "method": "popup",
+            "minutes": 15,  # 15 minutes before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-004",
+            "event_id": "event-corrected-003",
+            "method": "email",
+            "minutes": 10080,  # 1 week before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-005",
+            "event_id": "event-corrected-005",
+            "method": "popup",
+            "minutes": 10,  # Day of reminder
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-006",
+            "event_id": "event-corrected-006",
+            "method": "email",
+            "minutes": 2880,  # 2 days before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-007",
+            "event_id": "event-corrected-006",
+            "method": "popup",
+            "minutes": 60,  # 1 hour before
+            "use_default": False
+        },
+        {
+            "id": "rem-corrected-008",
+            "event_id": "event-corrected-006",
+            "method": "popup",
+            "minutes": 15,  # 15 minutes before
+            "use_default": False
+        }
+    ]
+    
+    # Attendees data -  to match model exactly
+    attendees_data = [
+        # Sprint Planning attendees
+        {
+            "attendees_id": "att-corrected-001",
+            "event_id": "event-corrected-001",
+            "user_id": "alice_manager",
+            "comment": "Looking forward to planning Q4!",
+            "displayName": "Alice Johnson",   
+            "additionalGuests": 0,   
+            "optional": False,
+            "resource": False,
+            "responseStatus": "accepted"   
+        },
+        {
+            "attendees_id": "att-corrected-002", 
+            "event_id": "event-corrected-001",
+            "user_id": "bob_developer",
+            "comment": None,
+            "displayName": "Bob Smith",   
+            "additionalGuests": 0,   
+            "optional": False,
+            "resource": False,
+            "responseStatus": "accepted"   
+        },
+        {
+            "attendees_id": "att-corrected-003",
+            "event_id": "event-corrected-001", 
+            "user_id": "carol_designer",
+            "comment": "Will join if no conflicts with user research session",
+            "displayName": "Carol White",   
+            "additionalGuests": 0,   
+            "optional": True,
+            "resource": False,
+            "responseStatus": "tentative"   
+        },
+        {
+            "attendees_id": "att-corrected-004",
+            "event_id": "event-corrected-001",
+            "user_id": None,  # Resource doesn't have user_id
+            "comment": None,
+            "displayName": "Conference Room A",   
+            "additionalGuests": 0,   
+            "optional": False,
+            "resource": True,
+            "responseStatus": "accepted"   
+        },
+        
+        # Client Demo attendees
+        {
+            "attendees_id": "att-corrected-005",
+            "event_id": "event-corrected-006",
+            "user_id": "dave_sales", 
+            "comment": "Prepared demo materials and pricing",
+            "displayName": "Dave Brown",   
+            "additionalGuests": 0,   
+            "optional": False,
+            "resource": False,
+            "responseStatus": "accepted"   
+        },
+        {
+            "attendees_id": "att-corrected-006",
+            "event_id": "event-corrected-006",
+            "user_id": None,  # External attendee
+            "comment": "Bringing 2 technical team members",
+            "displayName": "John Doe",   
+            "additionalGuests": 2,   
+            "optional": False,
+            "resource": False,
+            "responseStatus": "accepted"   
+        },
+        {
+            "attendees_id": "att-corrected-007",
+            "event_id": "event-corrected-006",
+            "user_id": "sarah_tech",
+            "comment": "Technical support for enterprise questions",
+            "displayName": "Sarah Chen",   
+            "additionalGuests": 0,   
+            "optional": True,
+            "resource": False,
+            "responseStatus": "accepted"   
+        },
+        {
+            "attendees_id": "att-corrected-008", 
+            "event_id": "event-corrected-006",
+            "user_id": "alice_manager",
+            "comment": None,
+            "displayName": "Alice Johnson",   
+            "additionalGuests": 0,   
+            "optional": True,
+            "resource": False,
+            "responseStatus": "needsAction"   
+        }
+    ]
+    
+    # Attachments for events
+    attachments_data = [
+        {
+            "attachment_id": "attach-corrected-001",
+            "event_id": "event-corrected-001", 
+            "file_url": "https://drive.google.com/file/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/view"
+        },
+        {
+            "attachment_id": "attach-corrected-002",
+            "event_id": "event-corrected-001",
+            "file_url": "https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit"
+        },
+        {
+            "attachment_id": "attach-corrected-003", 
+            "event_id": "event-corrected-006",
+            "file_url": "https://drive.google.com/file/d/enterprise-demo-deck-2024/view"
+        },
+        {
+            "attachment_id": "attach-corrected-004",
+            "event_id": "event-corrected-006", 
+            "file_url": "https://drive.google.com/file/d/pricing-sheet-enterprise-2024/view"
+        },
+        {
+            "attachment_id": "attach-corrected-005",
+            "event_id": "event-corrected-006",
+            "file_url": "https://docs.google.com/document/d/technical-specs-enterprise/edit"
+        }
+    ]
+    
+    # Working location properties - corrected structure with proper office location foreign key
+    working_location_data = [
+        {
+            "working_location_id": "wl-corrected-001",
+            "event_id": "event-corrected-004",
+            "type": "officeLocation",
+            "homeOffice": False,   
+            "customLocationLabel": None,   
+            "officeLocationId": "office-building-2-floor-3"  #  - foreign key to office_locations
+        }
+    ]
+    
+    return {
+        "office_locations": office_locations_data,
+        "events": events_data,
+        "recurring_events": recurring_event_data,
+        "conference_data": conference_data,
+        "birthday_properties": birthday_properties,
+        "extended_properties": extended_properties,
+        "reminders": reminders_data,
+        "attendees": attendees_data,
+        "attachments": attachments_data,
+        "working_location_properties": working_location_data,
+        "description": "Event seed data that exactly matches the updated event.py model structure with proper field names and relationships"
+    }
+
+
+def generate_enhanced_event_sql(sql_statements) -> str:
+    """
+    Generate SQL INSERT statements for enhanced event seed data
+    """
+    data = get_enhanced_event_seed_data()
+    
+    # Office Locations
+    sql_statements.append("-- Office Locations")
+    sql_statements.append("INSERT INTO office_locations (")
+    sql_statements.append("    id, buildingId, deskId, floorId, floorSectionId, label")
+    sql_statements.append(") VALUES")
+    
+    office_values = []
+    for office in data["office_locations"]:
+        building_id = "NULL" if not office.get("buildingId") else f"'{office['buildingId']}'"
+        desk_id = "NULL" if not office.get("deskId") else f"'{office['deskId']}'"
+        floor_id = "NULL" if not office.get("floorId") else f"'{office['floorId']}'"
+        floor_section_id = "NULL" if not office.get("floorSectionId") else f"'{office['floorSectionId']}'"
+        
+        office_values.append(
+            f"('{office['id']}', {building_id}, {desk_id}, {floor_id}, {floor_section_id}, '{office['label']}')"
+        )
+    
+    sql_statements.append(",\n".join(office_values) + ";")
+    sql_statements.append("")
+
+    # Recurring Events
+    sql_statements.append("-- Recurring Events")
+    sql_statements.append("INSERT INTO recurring_events (")
+    sql_statements.append("    recurring_event_id, original_recurrence")
+    sql_statements.append(") VALUES")
+
+    recurring_events = []
+    for rec_event in data["recurring_events"]:
+        recurring_event_id = "NULL" if not rec_event.get("recurring_event_id") else f"'{rec_event['recurring_event_id']}'"
+        original_recurrence = "NULL" if not rec_event.get("original_recurrence") else f"'{json.dumps(rec_event['original_recurrence']).replace(chr(39), chr(39)+chr(39))}'"
+
+        recurring_events.append(f"({recurring_event_id},{original_recurrence})")
+    
+    sql_statements.append(",\n".join(recurring_events) + ";")
+    sql_statements.append("")
+    
+    # Events
+    sql_statements.append("-- Events")
+    sql_statements.append("INSERT INTO events (")
+    sql_statements.append("    event_id, calendar_id, user_id, organizer_id, organizer_email, organizer_display_name, organizer_self,")
+    sql_statements.append("    recurring_event_id, summary, description, location,")
+    sql_statements.append("    start_datetime, end_datetime, start_timezone, end_timezone, originalStartTime_date, originalStartTime_dateTime, originalStartTime_timeZone, recurrence,")
+    sql_statements.append("    status, visibility, color_id, iCalUID, eventType, focusTimeProperties,")
+    sql_statements.append("    guestsCanInviteOthers, guestsCanModify, guestsCanSeeOtherGuests,")
+    sql_statements.append("    outOfOfficeProperties, sequence, source, created_at, updated_at")
+    sql_statements.append(") VALUES")
+    
+    event_values = []
+    for event in data["events"]:
+        # Handle optional fields
+        description = "NULL" if not event.get("description") else f"'{event['description'].replace(chr(39), chr(39)+chr(39))}'"
+        location = "NULL" if not event.get("location") else f"'{event['location'].replace(chr(39), chr(39)+chr(39))}'"
+        start_tz = "NULL" if not event.get("start_timezone") else f"'{event['start_timezone']}'"
+        end_tz = "NULL" if not event.get("end_timezone") else f"'{event['end_timezone']}'"
+        
+        # Handle originalStartTime fields
+        original_start_date = "NULL"
+        original_start_datetime = "NULL"
+        original_start_timezone = "NULL"
+        
+        if event.get("originalStartTime_date"):
+            original_start_date = f"'{event['originalStartTime_date'].isoformat()}'"
+        if event.get("originalStartTime_dateTime"):
+            original_start_datetime = f"'{event['originalStartTime_dateTime'].isoformat()}'"
+        if event.get("originalStartTime_timeZone"):
+            original_start_timezone = f"'{event['originalStartTime_timeZone']}'"
+            
+        # Handle recurrence field - it can be a list or None
+        recurring_event_id = "NULL" if not event.get("recurring_event_id") else event["recurring_event_id"]
+
+        recurrence = "NULL"
+        if event.get("recurrence"):
+            if isinstance(event['recurrence'], list):
+                recurrence = f"'{json.dumps(event['recurrence']).replace(chr(39), chr(39)+chr(39))}'"
+            else:
+                recurrence = f"'{event['recurrence'].replace(chr(39), chr(39)+chr(39))}'"
+
+        color_id = "NULL" if not event.get("color_id") else f"'{event['color_id']}'"
+        
+        # Handle JSON fields - using 
+        focus_props = "NULL"
+        if event.get("focusTimeProperties"):
+            focus_props = f"'{json.dumps(event['focusTimeProperties']).replace(chr(39), chr(39)+chr(39))}'"
+            
+        ooo_props = "NULL"
+        if event.get("outOfOfficeProperties"):
+            ooo_props = f"'{json.dumps(event['outOfOfficeProperties']).replace(chr(39), chr(39)+chr(39))}'"
+            
+        source = "NULL"
+        if event.get("source"):
+            source = f"'{json.dumps(event['source']).replace(chr(39), chr(39)+chr(39))}'"
+        
+        # Handle organizer fields
+        organizer_id = "NULL" if not event.get("organizer_id") else f"'{event['organizer_id']}'"
+        organizer_email = "NULL" if not event.get("organizer_email") else f"'{event['organizer_email']}'"
+        organizer_display_name = "NULL" if not event.get("organizer_display_name") else f"'{event['organizer_display_name']}'"
+        organizer_self = 1 if event.get("organizer_self", False) else 0
+        
+        event_values.append(
+            f"('{event['event_id']}', '{event['calendar_id']}', '{event['user_id']}', {organizer_id}, {organizer_email}, {organizer_display_name}, {organizer_self}, "
+            f"'{recurring_event_id}', '{event['summary'].replace(chr(39), chr(39)+chr(39))}', {description}, {location}, "
+            f"'{event['start_datetime'].isoformat()}', '{event['end_datetime'].isoformat()}', "
+            f"{start_tz}, {end_tz}, {original_start_date}, {original_start_datetime}, {original_start_timezone}, {recurrence}, "
+            f"'{event['status']}', '{event['visibility']}', {color_id}, '{event['iCalUID']}', '{event['eventType']}', {focus_props}, "
+            f"{1 if event['guestsCanInviteOthers'] else 0}, "
+            f"{1 if event['guestsCanModify'] else 0}, "
+            f"{1 if event['guestsCanSeeOtherGuests'] else 0}, "
+            f"{ooo_props}, {event['sequence']}, {source}, datetime('now'), datetime('now'))"
+        )
+    
+    sql_statements.append(",\n".join(event_values) + ";")
+    sql_statements.append("")
+    
+    # ConferenceData
+    if data["conference_data"]:
+        sql_statements.append("-- ConferenceData")
+        sql_statements.append("INSERT INTO conference_data (")
+        sql_statements.append("    id, event_id, request_id, solution_type, status_code, meeting_uri, label")
+        sql_statements.append(") VALUES")
+        
+        conf_values = []
+        for conf in data["conference_data"]:
+            request_id = "NULL" if not conf.get("request_id") else f"'{conf['request_id']}'"
+            solution_type = "NULL" if not conf.get("solution_type") else f"'{conf['solution_type']}'"
+            status_code = "NULL" if not conf.get("status_code") else f"'{conf['status_code']}'"
+            meeting_uri = "NULL" if not conf.get("meeting_uri") else f"'{conf['meeting_uri']}'"
+            label = "NULL" if not conf.get("label") else f"'{conf['label']}'"
+            
+            conf_values.append(
+                f"('{conf['id']}', '{conf['event_id']}', {request_id}, {solution_type}, "
+                f"{status_code}, {meeting_uri}, {label})"
+            )
+        
+        sql_statements.append(",\n".join(conf_values) + ";")
+        sql_statements.append("")
+    
+    # BirthdayProperties
+    if data["birthday_properties"]:
+        sql_statements.append("-- BirthdayProperties")
+        sql_statements.append("INSERT INTO birthday_properties (id, event_id, type) VALUES")
+        
+        birthday_values = []
+        for birthday in data["birthday_properties"]:
+            birthday_values.append(f"('{birthday['id']}', '{birthday['event_id']}', '{birthday['type']}')")
+        
+        sql_statements.append(",\n".join(birthday_values) + ";")
+        sql_statements.append("")
+    
+    # ExtendedProperties
+    if data["extended_properties"]:
+        sql_statements.append("-- ExtendedProperties")
+        sql_statements.append("INSERT INTO extended_properties (id, event_id, scope, properties) VALUES")
+        
+        ext_values = []
+        for ext in data["extended_properties"]:
+            properties = json.dumps(ext["properties"]).replace(chr(39), chr(39)+chr(39))
+            ext_values.append(
+                f"('{ext['id']}', '{ext['event_id']}', '{ext['scope']}', '{properties}')"
+            )
+        
+        sql_statements.append(",\n".join(ext_values) + ";")
+        sql_statements.append("")
+    
+    # Reminders
+    if data["reminders"]:
+        sql_statements.append("-- Reminders")
+        sql_statements.append("INSERT INTO reminders (id, event_id, method, minutes, use_default) VALUES")
+        
+        reminder_values = []
+        for reminder in data["reminders"]:
+            reminder_values.append(
+                f"('{reminder['id']}', '{reminder['event_id']}', '{reminder['method']}', "
+                f"{reminder['minutes']}, {1 if reminder['use_default'] else 0})"
+            )
+        
+        sql_statements.append(",\n".join(reminder_values) + ";")
+        sql_statements.append("")
+    
+    # Attendees - with 
+    sql_statements.append("-- Attendees")
+    sql_statements.append("INSERT INTO attendees (")
+    sql_statements.append("    attendees_id, event_id, user_id, comment, displayName,")  
+    sql_statements.append("    additionalGuests, optional, resource, responseStatus")  
+    sql_statements.append(") VALUES")
+    
+    attendee_values = []
+    for attendee in data["attendees"]:
+        user_id = "NULL" if not attendee.get("user_id") else f"'{attendee['user_id']}'"
+        comment = "NULL" if not attendee.get("comment") else f"'{attendee['comment'].replace(chr(39), chr(39)+chr(39))}'"
+        display_name = "NULL" if not attendee.get("displayName") else f"'{attendee['displayName']}'"
+        
+        attendee_values.append(
+            f"('{attendee['attendees_id']}', '{attendee['event_id']}', {user_id}, {comment}, {display_name}, "
+            f"{attendee['additionalGuests']}, {1 if attendee['optional'] else 0}, "
+            f"{1 if attendee['resource'] else 0}, '{attendee['responseStatus']}')"
+        )
+    
+    sql_statements.append(",\n".join(attendee_values) + ";")
+    sql_statements.append("")
+    
+    # Attachments
+    sql_statements.append("-- Attachments")
+    sql_statements.append("INSERT INTO attachments (attachment_id, event_id, file_url) VALUES")
+    
+    attachment_values = []
+    for attachment in data["attachments"]:
+        attachment_values.append(
+            f"('{attachment['attachment_id']}', '{attachment['event_id']}', '{attachment['file_url']}')"
+        )
+    
+    sql_statements.append(",\n".join(attachment_values) + ";")
+    sql_statements.append("")
+    
+    # Working Location Properties
+    sql_statements.append("-- Working Location Properties")
+    sql_statements.append("INSERT INTO working_location_properties (")
+    sql_statements.append("    working_location_id, event_id, type, homeOffice, customLocationLabel, officeLocationId")   
+    sql_statements.append(") VALUES")
+    
+    wl_values = []
+    for wl in data["working_location_properties"]:
+        custom_label = "NULL" if not wl.get("customLocationLabel") else f"'{wl['customLocationLabel']}'"
+        office_location_id = "NULL" if not wl.get("officeLocationId") else f"'{wl['officeLocationId']}'"
+        
+        wl_values.append(
+            f"('{wl['working_location_id']}', '{wl['event_id']}', '{wl['type']}', "
+            f"{1 if wl['homeOffice'] else 0}, {custom_label}, {office_location_id})"
+        )
+    
+    sql_statements.append(",\n".join(wl_values) + ";")
+    sql_statements.append("")
+    
+    return sql_statements
+
+

server/data/google_colors.py

@@ -0,0 +1,46 @@
+"""
+Google Calendar API v3 Color Data
+Exact color definitions from Google Calendar API
+"""
+
+# Google Calendar exact color definitions based on official API
+GOOGLE_CALENDAR_COLORS = [
+    # Calendar colors (1-24)
+    {"color_id": "1", "color_type": "calendar", "background": "#ac725e", "foreground": "#1d1d1d"},
+    {"color_id": "2", "color_type": "calendar", "background": "#d06b64", "foreground": "#1d1d1d"},
+    {"color_id": "3", "color_type": "calendar", "background": "#f83a22", "foreground": "#1d1d1d"},
+    {"color_id": "4", "color_type": "calendar", "background": "#fa57c4", "foreground": "#1d1d1d"},
+    {"color_id": "5", "color_type": "calendar", "background": "#9fc6e7", "foreground": "#1d1d1d"},
+    {"color_id": "6", "color_type": "calendar", "background": "#9a9cff", "foreground": "#1d1d1d"},
+    {"color_id": "7", "color_type": "calendar", "background": "#4986e7", "foreground": "#1d1d1d"},
+    {"color_id": "8", "color_type": "calendar", "background": "#9aa116", "foreground": "#1d1d1d"},
+    {"color_id": "9", "color_type": "calendar", "background": "#ef6c00", "foreground": "#1d1d1d"},
+    {"color_id": "10", "color_type": "calendar", "background": "#ff7537", "foreground": "#1d1d1d"},
+    {"color_id": "11", "color_type": "calendar", "background": "#42d692", "foreground": "#1d1d1d"},
+    {"color_id": "12", "color_type": "calendar", "background": "#16a765", "foreground": "#1d1d1d"},
+    {"color_id": "13", "color_type": "calendar", "background": "#7bd148", "foreground": "#1d1d1d"},
+    {"color_id": "14", "color_type": "calendar", "background": "#b3dc6c", "foreground": "#1d1d1d"},
+    {"color_id": "15", "color_type": "calendar", "background": "#fbe983", "foreground": "#1d1d1d"},
+    {"color_id": "16", "color_type": "calendar", "background": "#fad165", "foreground": "#1d1d1d"},
+    {"color_id": "17", "color_type": "calendar", "background": "#92e1c0", "foreground": "#1d1d1d"},
+    {"color_id": "18", "color_type": "calendar", "background": "#9fe1e7", "foreground": "#1d1d1d"},
+    {"color_id": "19", "color_type": "calendar", "background": "#9fc6e7", "foreground": "#1d1d1d"},
+    {"color_id": "20", "color_type": "calendar", "background": "#4986e7", "foreground": "#1d1d1d"},
+    {"color_id": "21", "color_type": "calendar", "background": "#9aa116", "foreground": "#1d1d1d"},
+    {"color_id": "22", "color_type": "calendar", "background": "#16a765", "foreground": "#1d1d1d"},
+    {"color_id": "23", "color_type": "calendar", "background": "#ff7537", "foreground": "#1d1d1d"},
+    {"color_id": "24", "color_type": "calendar", "background": "#ffad46", "foreground": "#1d1d1d"},
+    
+    # Event colors (1-11)
+    {"color_id": "1", "color_type": "event", "background": "#a4bdfc", "foreground": "#1d1d1d"},
+    {"color_id": "2", "color_type": "event", "background": "#7ae7bf", "foreground": "#1d1d1d"},
+    {"color_id": "3", "color_type": "event", "background": "#dbadff", "foreground": "#1d1d1d"},
+    {"color_id": "4", "color_type": "event", "background": "#ff887c", "foreground": "#1d1d1d"},
+    {"color_id": "5", "color_type": "event", "background": "#fbd75b", "foreground": "#1d1d1d"},
+    {"color_id": "6", "color_type": "event", "background": "#ffb878", "foreground": "#1d1d1d"},
+    {"color_id": "7", "color_type": "event", "background": "#46d6db", "foreground": "#1d1d1d"},
+    {"color_id": "8", "color_type": "event", "background": "#e1e1e1", "foreground": "#1d1d1d"},
+    {"color_id": "9", "color_type": "event", "background": "#5484ed", "foreground": "#1d1d1d"},
+    {"color_id": "10", "color_type": "event", "background": "#51b749", "foreground": "#1d1d1d"},
+    {"color_id": "11", "color_type": "event", "background": "#dc2127", "foreground": "#1d1d1d"},
+]

server/data/multi_user_sample.py

@@ -0,0 +1,532 @@
+"""
+Multi-User Sample Data for Calendar Application
+"""
+
+from datetime import datetime, timedelta
+from typing import List, Dict, Any
+from .enhanced_event_seed_data import generate_enhanced_event_sql
+from .watch_channel_seed_data import get_watch_channel_sql
+
+def get_multi_user_sample_data() -> Dict[str, Any]:
+    """
+    Generate sample data for multiple users demonstrating multi-user scenarios
+    """
+    
+    # Sample users
+    users = [
+        {
+            "user_id": "alice_manager",
+            "email": "alice.manager@techcorp.com",
+            "name": "Alice Johnson",
+            "given_name": "Alice", 
+            "family_name": "Johnson",
+            "static_token": "ya29.A0ARrdaM-k9Vq7GzY2pL4mQf8sN1xT0bR3uHcJWv5yKzP6eF2.qwErTyUIopASDfGhJkLzXcVbNm12_34-56",
+            "timezone": "America/New_York",
+            "role": "Project Manager"
+        },
+        {
+            "user_id": "bob_developer", 
+            "email": "bob.smith@techcorp.com",
+            "name": "Bob Smith",
+            "given_name": "Bob",
+            "family_name": "Smith", 
+            "static_token": "ya29.A0ARrdaM-Zx8Nw3Q4pVb6Ls9R1mT0cG2uF5yH7kJd8sA1Lq2.wErtYuIoPaSdFgHjKlZxCvBnM987_65-43",
+            "timezone": "America/Los_Angeles",
+            "role": "Senior Developer"
+        },
+        {
+            "user_id": "carol_designer",
+            "email": "carol.white@techcorp.com", 
+            "name": "Carol White",
+            "given_name": "Carol",
+            "family_name": "White",
+            "static_token": "ya29.A0ARrdaM-b7Hc5Vn2Qm8R1sT4pL0xY9wK3uF6jZ2eRc1.QaWsEdRfTgHyJuIkOlPzXcVbNmKjHgf_21-098",
+            "timezone": "Europe/London",
+            "role": "UX Designer"
+        },
+        {
+            "user_id": "dave_sales",
+            "email": "dave.brown@techcorp.com",
+            "name": "Dave Brown", 
+            "given_name": "Dave",
+            "family_name": "Brown",
+            "static_token": "ya29.A0ARrdaM-p3Lk9Vb6Qw2Zx8N1sT4mH7gF5yR0uJc2ePq.ZxCvBnMlKjHgFfDsaQwErTyUiOpAsDfGhJk_77-11",
+            "timezone": "America/Chicago",
+            "role": "Sales Director"
+        }
+    ]
+    
+    # Alice's calendars (Project Manager)
+    alice_calendars = [
+        {
+            "calendar_id": "alice-primary",
+            "user_id": "alice_manager", 
+            "summary": "Alice Johnson",
+            "description": "Primary calendar for Alice Johnson - Project Manager",
+            "time_zone": "America/New_York",
+            "is_primary": True,
+            "color_id": "1"
+        },
+        {
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "summary": "Project Management", 
+            "description": "Project meetings, deadlines, and milestones",
+            "time_zone": "America/New_York", 
+            "is_primary": False,
+            "color_id": "7"
+        },
+        {
+            "calendar_id": "alice-team",
+            "user_id": "alice_manager",
+            "summary": "Team Coordination",
+            "description": "Team meetings, 1-on-1s, and team events",
+            "time_zone": "America/New_York",
+            "is_primary": False, 
+            "color_id": "11"
+        }
+    ]
+    
+    # Bob's calendars (Developer)
+    bob_calendars = [
+        {
+            "calendar_id": "bob-primary",
+            "user_id": "bob_developer",
+            "summary": "Bob Smith",
+            "description": "Primary calendar for Bob Smith - Senior Developer", 
+            "time_zone": "America/Los_Angeles",
+            "is_primary": True,
+            "color_id": "2"
+        },
+        {
+            "calendar_id": "bob-development", 
+            "user_id": "bob_developer",
+            "summary": "Development Schedule",
+            "description": "Sprint planning, code reviews, and development tasks",
+            "time_zone": "America/Los_Angeles",
+            "is_primary": False,
+            "color_id": "9" 
+        },
+        {
+            "calendar_id": "bob-personal",
+            "user_id": "bob_developer", 
+            "summary": "Personal Time",
+            "description": "Personal appointments and time off",
+            "time_zone": "America/Los_Angeles",
+            "is_primary": False,
+            "color_id": "14"
+        }
+    ]
+    
+    # Carol's calendars (Designer)  
+    carol_calendars = [
+        {
+            "calendar_id": "carol-primary",
+            "user_id": "carol_designer",
+            "summary": "Carol White",
+            "description": "Primary calendar for Carol White - UX Designer",
+            "time_zone": "Europe/London", 
+            "is_primary": True,
+            "color_id": "4"
+        },
+        {
+            "calendar_id": "carol-design",
+            "user_id": "carol_designer",
+            "summary": "Design Work",
+            "description": "Design sessions, user research, and creative time",
+            "time_zone": "Europe/London",
+            "is_primary": False,
+            "color_id": "16"
+        }
+    ]
+    
+    # Dave's calendars (Sales)
+    dave_calendars = [
+        {
+            "calendar_id": "dave-primary", 
+            "user_id": "dave_sales",
+            "summary": "Dave Brown",
+            "description": "Primary calendar for Dave Brown - Sales Director",
+            "time_zone": "America/Chicago",
+            "is_primary": True,
+            "color_id": "6"
+        },
+        {
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales", 
+            "summary": "Sales Activities",
+            "description": "Client meetings, sales calls, and deals",
+            "time_zone": "America/Chicago",
+            "is_primary": False,
+            "color_id": "23"
+        }
+    ]
+    
+    # Sample events for each user
+    base_date = datetime.now().replace(hour=9, minute=0, second=0, microsecond=0)
+    
+    alice_events = [
+        {
+            "event_id": "alice-event-1",
+            "calendar_id": "alice-projects", 
+            "user_id": "alice_manager",
+            "summary": "Sprint Planning Meeting",
+            "description": "Plan upcoming sprint with development team",
+            "location": "Conference Room A",
+            "start_datetime": base_date,
+            "end_datetime": base_date + timedelta(hours=1),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "alice-event-2",
+            "calendar_id": "alice-team",
+            "user_id": "alice_manager", 
+            "summary": "1-on-1 with Bob",
+            "description": "Weekly check-in with Bob Smith",
+            "location": "Alice's Office",
+            "start_datetime": base_date + timedelta(days=1, hours=2),
+            "end_datetime": base_date + timedelta(days=1, hours=2, minutes=30),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "alice-event-3",
+            "calendar_id": "alice-primary",
+            "user_id": "alice_manager",
+            "summary": "Board Meeting",
+            "description": "Monthly board meeting presentation", 
+            "location": "Executive Conference Room",
+            "start_datetime": base_date + timedelta(days=7),
+            "end_datetime": base_date + timedelta(days=7, hours=2),
+            "status": "confirmed"
+        }
+    ]
+    
+    bob_events = [
+        {
+            "event_id": "bob-event-1",
+            "calendar_id": "bob-development",
+            "user_id": "bob_developer",
+            "summary": "Code Review Session", 
+            "description": "Review pull requests from junior developers",
+            "location": "Development Room",
+            "start_datetime": base_date + timedelta(hours=3),
+            "end_datetime": base_date + timedelta(hours=4),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "bob-event-2",
+            "calendar_id": "bob-primary",
+            "user_id": "bob_developer",
+            "summary": "Architecture Discussion",
+            "description": "Discuss system architecture for new feature",
+            "location": "Video Call", 
+            "start_datetime": base_date + timedelta(days=2),
+            "end_datetime": base_date + timedelta(days=2, hours=1, minutes=30),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "bob-event-3",
+            "calendar_id": "bob-personal",
+            "user_id": "bob_developer",
+            "summary": "Dentist Appointment",
+            "description": "Annual dental checkup",
+            "location": "Downtown Dental", 
+            "start_datetime": base_date + timedelta(days=5, hours=5),
+            "end_datetime": base_date + timedelta(days=5, hours=6),
+            "status": "confirmed"
+        }
+    ]
+    
+    carol_events = [
+        {
+            "event_id": "carol-event-1",
+            "calendar_id": "carol-design",
+            "user_id": "carol_designer",
+            "summary": "User Research Session",
+            "description": "Interview users about new feature requirements",
+            "location": "Research Lab",
+            "start_datetime": base_date + timedelta(hours=1),
+            "end_datetime": base_date + timedelta(hours=3),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "carol-event-2", 
+            "calendar_id": "carol-primary",
+            "user_id": "carol_designer",
+            "summary": "Design Review",
+            "description": "Present mockups to stakeholders",
+            "location": "Design Studio",
+            "start_datetime": base_date + timedelta(days=3, hours=2),
+            "end_datetime": base_date + timedelta(days=3, hours=3, minutes=30),
+            "status": "confirmed"
+        }
+    ]
+    
+    dave_events = [
+        {
+            "event_id": "dave-event-1",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "summary": "Client Demo",
+            "description": "Product demonstration for potential enterprise client",
+            "location": "Client Office",
+            "start_datetime": base_date + timedelta(days=1),
+            "end_datetime": base_date + timedelta(days=1, hours=2),
+            "status": "confirmed"
+        },
+        {
+            "event_id": "dave-event-2",
+            "calendar_id": "dave-primary", 
+            "user_id": "dave_sales",
+            "summary": "Sales Team Meeting",
+            "description": "Weekly sales team sync and pipeline review",
+            "location": "Sales Conference Room",
+            "start_datetime": base_date + timedelta(days=4),
+            "end_datetime": base_date + timedelta(days=4, hours=1),
+            "status": "confirmed"
+        }
+    ]
+
+    settings =  [
+        {"id": "alice_timezone", "user_id": "alice_manager", "value": "America/New_York"},
+        {"id": "bob_timezone", "user_id": "bob_developer", "value": "America/Los_Angeles"},
+        {"id": "carol_timezone", "user_id": "carol_designer", "value": "Europe/London"},
+        {"id": "dave_timezone", "user_id": "dave_sales", "value": "America/Chicago"}
+    ]
+
+    scopes = [
+        {"id": "scope-alice", "type": "user", "value": "alice.manager@techcorp.com"},
+        {"id": "scope-bob", "type": "user", "value": "bob.smith@techcorp.com"},
+        {"id": "scope-carol", "type": "user", "value": "carol.white@techcorp.com"},
+        {"id": "scope-dave", "type": "user", "value": "dave.brown@techcorp.com"},
+        {"id": "scope-group", "type": "group", "value": "product-team@techcorp.com"},
+        {"id": "scope-domain", "type": "domain", "value": "techcorp.com"},
+        {"id": "scope-public", "type": "default", "value":"public"}
+    ]
+
+    acls = [
+        # Alice's calendar ACLs (owner of her calendars)
+        {
+            "id": "acl-alice-primary",
+            "calendar_id": "alice-primary",
+            "user_id": "alice_manager",
+            "role": "owner",
+            "scope_id": "scope-alice",
+            "etag": "etag-alice-primary"
+        },
+        {
+            "id": "acl-alice-projects",
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "role": "owner",
+            "scope_id": "scope-alice",
+            "etag": "etag-alice-projects"
+        },
+        {
+            "id": "acl-alice-team",
+            "calendar_id": "alice-team",
+            "user_id": "alice_manager",
+            "role": "owner",
+            "scope_id": "scope-alice",
+            "etag": "etag-alice-team"
+        },
+        # Bob's calendar ACLs (owner of his calendars)
+        {
+            "id": "acl-bob-primary",
+            "calendar_id": "bob-primary",
+            "user_id": "bob_developer",
+            "role": "owner",
+            "scope_id": "scope-bob",
+            "etag": "etag-bob-primary"
+        },
+        {
+            "id": "acl-bob-development",
+            "calendar_id": "bob-development",
+            "user_id": "bob_developer",
+            "role": "owner",
+            "scope_id": "scope-bob",
+            "etag": "etag-bob-development"
+        },
+        {
+            "id": "acl-bob-personal",
+            "calendar_id": "bob-personal",
+            "user_id": "bob_developer",
+            "role": "owner",
+            "scope_id": "scope-bob",
+            "etag": "etag-bob-personal"
+        },
+        # Carol's calendar ACLs (owner of her calendars)
+        {
+            "id": "acl-carol-primary",
+            "calendar_id": "carol-primary",
+            "user_id": "carol_designer",
+            "role": "owner",
+            "scope_id": "scope-carol",
+            "etag": "etag-carol-primary"
+        },
+        {
+            "id": "acl-carol-design",
+            "calendar_id": "carol-design",
+            "user_id": "carol_designer",
+            "role": "owner",
+            "scope_id": "scope-carol",
+            "etag": "etag-carol-design"
+        },
+        # Dave's calendar ACLs (owner of his calendars)
+        {
+            "id": "acl-dave-primary",
+            "calendar_id": "dave-primary",
+            "user_id": "dave_sales",
+            "role": "owner",
+            "scope_id": "scope-dave",
+            "etag": "etag-dave-primary"
+        },
+        {
+            "id": "acl-dave-sales",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "role": "owner",
+            "scope_id": "scope-dave",
+            "etag": "etag-dave-sales"
+        },
+        # Shared access examples
+        {
+            "id": "acl-shared-1",
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "role": "writer",
+            "scope_id": "scope-bob",
+            "etag": "etag-shared-1"
+        },
+        {
+            "id": "acl-shared-2",
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "role": "reader",
+            "scope_id": "scope-carol",
+            "etag": "etag-shared-2"
+        }
+    ]
+
+    return {
+        "users": users,
+        "calendars": alice_calendars + bob_calendars + carol_calendars + dave_calendars,
+        "events": alice_events + bob_events + carol_events + dave_events,
+        "settings": settings,
+        "scopes": scopes,
+        "acls": acls,
+        "description": "Multi-user sample data with 4 users (Alice-PM, Bob-Dev, Carol-Design, Dave-Sales) demonstrating isolated data per user"
+    }
+
+
+def get_multi_user_sql(database_name: str = "multi_user_calendar") -> str:
+    """
+    Generate SQL statements for multi-user sample data
+    """
+    data = get_multi_user_sample_data()
+    
+    sql_statements = []
+    
+    # Header
+    sql_statements.append(f"-- Multi-User Calendar Sample Data for {database_name}")
+    sql_statements.append(f"-- Generated on: {datetime.now().isoformat()}")
+    sql_statements.append("-- Contains sample data for 4 users with isolated calendars and events")
+    sql_statements.append("")
+    
+    # Users
+    sql_statements.append("-- Users")
+    sql_statements.append("INSERT INTO users (user_id, email, name, given_name, family_name, static_token, timezone, is_active, is_verified, created_at, updated_at) VALUES")
+    
+    user_values = []
+    for user in data["users"]:
+        # Escape single quotes by doubling them
+        name = user['name'].replace("'", "''")
+        given_name = user.get('given_name', '').replace("'", "''")
+        family_name = user.get('family_name', '').replace("'", "''")
+        
+        user_values.append(
+            f"('{user['user_id']}', '{user['email']}', '{name}', "
+            f"'{given_name}', '{family_name}', "
+            f"'{user['static_token']}', '{user['timezone']}', 1, 1, "
+            f"datetime('now'), datetime('now'))"
+        )
+    
+    sql_statements.append(",\n".join(user_values) + ";")
+    sql_statements.append("")
+    
+    # Calendars
+    sql_statements.append("-- Calendars")
+    sql_statements.append("INSERT INTO calendars (calendar_id, user_id, summary, description, time_zone, is_primary, color_id, hidden, selected, deleted, created_at, updated_at) VALUES")
+    
+    calendar_values = []
+    for calendar in data["calendars"]:
+        # Escape single quotes by doubling them
+        summary = calendar['summary'].replace("'", "''")
+        description = calendar.get('description', '').replace("'", "''")
+        
+        calendar_values.append(
+            f"('{calendar['calendar_id']}', '{calendar['user_id']}', '{summary}', "
+            f"'{description}', '{calendar['time_zone']}', "
+            f"{1 if calendar.get('is_primary') else 0}, '{calendar.get('color_id', '1')}', "
+            f"0, 1, 0, datetime('now'), datetime('now'))"
+        )
+    
+    sql_statements.append(",\n".join(calendar_values) + ";")
+    sql_statements.append("")
+    
+    # Events  
+    sql_statements = generate_enhanced_event_sql(sql_statements)
+    
+    # Colors (shared across users)
+    sql_statements.append("-- Google Calendar Colors (shared across all users)")
+    from data.google_colors import GOOGLE_CALENDAR_COLORS
+    
+    sql_statements.append("INSERT INTO colors (color_id, color_type, background, foreground, created_at, updated_at) VALUES")
+    
+    color_values = []
+    for color in GOOGLE_CALENDAR_COLORS:
+        color_values.append(
+            f"('{color['color_id']}', '{color['color_type'].upper()}', '{color['background']}', "
+            f"'{color['foreground']}', datetime('now'), datetime('now'))"
+        )
+    
+    sql_statements.append(",\n".join(color_values) + ";")
+    sql_statements.append("")
+
+    # Settings
+    sql_statements.append("-- Calendar Settings")
+    sql_statements.append("INSERT INTO settings (id, user_id, value) VALUES")
+    setting_values = []
+    for setting in data["settings"]:
+        setting_values.append(
+            f"('{setting['id']}', '{setting['user_id']}', '{setting['value']}')"
+        )
+    sql_statements.append(",\n".join(setting_values) + ";\n")
+    sql_statements.append("")
+
+    # Scopes
+    sql_statements.append("-- ACL Scopes")
+    sql_statements.append("INSERT INTO scopes (id, type, value) VALUES")
+    scope_values = []
+    for scope in data["scopes"]:
+        scope_values.append(
+            f"('{scope['id']}', '{scope['type']}', '{scope['value']}')"
+        )
+    sql_statements.append(",\n".join(scope_values) + ";\n")
+    sql_statements.append("")
+
+    # ACLs
+    sql_statements.append("-- Access Control Rules")
+    sql_statements.append("INSERT INTO acls (id, calendar_id, user_id, role, scope_id, etag) VALUES")
+    acl_values = []
+    for acl in data["acls"]:
+        acl_values.append(
+            f"('{acl['id']}', '{acl['calendar_id']}', '{acl['user_id']}', "
+            f"'{acl['role']}', '{acl['scope_id']}', '{acl['etag']}')"
+        )
+    sql_statements.append(",\n".join(acl_values) + ";\n")
+    sql_statements.append("")
+
+    sql_statements = get_watch_channel_sql(sql_statements)
+
+    return "\n".join(sql_statements)

server/data/watch_channel_seed_data.py

@@ -0,0 +1,245 @@
+"""
+Watch Channel Seed Data for Calendar Application
+"""
+
+from datetime import datetime, timedelta
+from typing import List, Dict, Any
+import json
+
+
+def get_watch_channel_sample_data() -> Dict[str, Any]:
+    """
+    Generate sample watch channel data for multi-user scenarios
+    """
+    
+    # Base time for calculations
+    now = datetime.utcnow()
+    
+    # Sample watch channels demonstrating various scenarios
+    watch_channels = [
+        # Alice's active watch channels
+        {
+            "id": "watch-alice-projects-001",
+            "resource_id": "acl-alice-projects", 
+            "resource_uri": "/calendars/alice-projects/acl",
+            "resource_type": "acl",
+            "calendar_id": "alice-projects",
+            "user_id": "alice_manager",
+            "webhook_address": "https://techcorp.com/webhooks/alice/acl-notifications",
+            "webhook_token": "alice_token_abc123",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 14200}),
+            "created_at": now - timedelta(days=5),
+            "expires_at": now + timedelta(seconds=14200),
+            "last_notification_at": now - timedelta(hours=2),
+            "is_active": "true",
+            "notification_count": 12
+        },
+        {
+            "id": "watch-alice-team-002", 
+            "resource_id": "acl-alice-team",
+            "resource_uri": "/calendars/alice-team/acl",
+            "resource_type": "acl",
+            "calendar_id": "alice-team",
+            "user_id": "alice_manager",
+            "webhook_address": "https://api.techcorp.com/calendar/notifications/team-acl",
+            "webhook_token": "team_secure_token_xyz789",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 11200}),
+            "created_at": now - timedelta(days=2),
+            "expires_at": now + timedelta(seconds=11200),
+            "last_notification_at": now - timedelta(hours=6),
+            "is_active": "true",
+            "notification_count": 5
+        },
+        
+        # Bob's watch channels
+        {
+            "id": "watch-bob-dev-001",
+            "resource_id": "acl-bob-development",
+            "resource_uri": "/calendars/bob-development/acl", 
+            "resource_type": "acl",
+            "calendar_id": "bob-development",
+            "user_id": "bob_developer",
+            "webhook_address": "https://hooks.slack.com/services/T123/B456/dev-calendar-notifications",
+            "webhook_token": None,  # No token for Slack webhook
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 9700}),
+            "created_at": now - timedelta(days=10),
+            "expires_at": now + timedelta(seconds=9700),
+            "last_notification_at": now - timedelta(days=1),
+            "is_active": "true",
+            "notification_count": 23
+        },
+        {
+            "id": "watch-bob-personal-002",
+            "resource_id": "acl-bob-personal",
+            "resource_uri": "/calendars/bob-personal/acl",
+            "resource_type": "acl", 
+            "calendar_id": "bob-personal",
+            "user_id": "bob_developer",
+            "webhook_address": "https://api.example.com/personal/calendar/webhook",
+            "webhook_token": "personal_webhook_token_def456",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 24390}),
+            "created_at": now - timedelta(days=1),
+            "expires_at": now + timedelta(seconds=24390),
+            "last_notification_at": None,  # No notifications sent yet
+            "is_active": "true",
+            "notification_count": 0
+        },
+        
+        # Carol's watch channels
+        {
+            "id": "watch-carol-design-001",
+            "resource_id": "acl-carol-design",
+            "resource_uri": "/calendars/carol-design/acl",
+            "resource_type": "acl",
+            "calendar_id": "carol-design",
+            "user_id": "carol_designer",
+            "webhook_address": "https://design-tools.techcorp.com/calendar/acl-updates",
+            "webhook_token": "design_team_token_ghi789",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 13200}),
+            "created_at": now - timedelta(days=7),
+            "expires_at": now + timedelta(seconds=13200),
+            "last_notification_at": now - timedelta(hours=12),
+            "is_active": "true",
+            "notification_count": 8
+        },
+        
+        # Dave's watch channels
+        {
+            "id": "watch-dave-sales-001",
+            "resource_id": "acl-dave-sales",
+            "resource_uri": "/calendars/dave-sales/acl",
+            "resource_type": "acl",
+            "calendar_id": "dave-sales",
+            "user_id": "dave_sales",
+            "webhook_address": "https://crm.techcorp.com/calendar/sales-acl-sync",
+            "webhook_token": "sales_crm_token_jkl012",
+            "webhook_type": "web_hook", 
+            "params": json.dumps({"ttl": 15600}),
+            "created_at": now - timedelta(days=14),
+            "expires_at": now + timedelta(seconds=15600),
+            "last_notification_at": now - timedelta(hours=4),
+            "is_active": "true",
+            "notification_count": 31
+        },
+        
+        # Expired/Inactive watch channels (for testing cleanup)
+        {
+            "id": "watch-alice-expired-001",
+            "resource_id": "acl-alice-primary",
+            "resource_uri": "/calendars/alice-primary/acl",
+            "resource_type": "acl",
+            "calendar_id": "alice-primary", 
+            "user_id": "alice_manager",
+            "webhook_address": "https://old-system.techcorp.com/webhooks/acl",
+            "webhook_token": "expired_token_mno345",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 2592000}),
+            "created_at": now - timedelta(days=35),
+            "expires_at": (now - timedelta(days=35)) + timedelta(seconds=2592000),  # Expired 5 days ago
+            "last_notification_at": now - timedelta(days=6),
+            "is_active": "true",  # Not yet cleaned up
+            "notification_count": 47
+        },
+        {
+            "id": "watch-bob-stopped-001",
+            "resource_id": "acl-bob-primary",
+            "resource_uri": "/calendars/bob-primary/acl",
+            "resource_type": "acl",
+            "calendar_id": "bob-primary",
+            "user_id": "bob_developer",
+            "webhook_address": "https://temp-webhook.example.com/test",
+            "webhook_token": "temp_token_pqr678", 
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 12000}),
+            "created_at": now - timedelta(days=8),
+            "expires_at": now + timedelta(seconds=12000),
+            "last_notification_at": now - timedelta(days=3),
+            "is_active": "false",  # Manually stopped
+            "notification_count": 15
+        },
+        
+        # Cross-calendar watch example (someone watching another user's shared calendar)
+        {
+            "id": "watch-bob-alice-shared-001",
+            "resource_id": "acl-alice-projects", 
+            "resource_uri": "/calendars/alice-projects/acl",
+            "resource_type": "acl",
+            "calendar_id": "alice-projects",  # Alice's calendar
+            "user_id": "bob_developer",  # But Bob is watching it
+            "webhook_address": "https://api.example.com/shared-calendar/acl-watch",
+            "webhook_token": "shared_access_token_stu901",
+            "webhook_type": "web_hook",
+            "params": json.dumps({"ttl": 16800}),
+            "created_at": now - timedelta(days=3),
+            "expires_at": now + timedelta(seconds=16800),
+            "last_notification_at": now - timedelta(hours=18),
+            "is_active": "true",
+            "notification_count": 3
+        }
+    ]
+    
+    return {
+        "watch_channels": watch_channels,
+        "description": "Sample watch channel data demonstrating various ACL notification scenarios across multiple users"
+    }
+
+
+def get_watch_channel_sql(sql_statements) -> str:
+    """
+    Generate SQL statements for watch channel sample data
+    """
+    data = get_watch_channel_sample_data()
+    
+    
+    # Header
+    sql_statements.append(f"-- Generated on: {datetime.now().isoformat()}")
+    sql_statements.append("-- Contains sample watch channel data for ACL notifications")
+    sql_statements.append("")
+    
+    # Watch Channels
+    sql_statements.append("-- Watch Channels for ACL Notifications")
+    sql_statements.append("INSERT INTO watch_channels (")
+    sql_statements.append("    id, resource_id, resource_uri, resource_type, calendar_id, user_id,")
+    sql_statements.append("    webhook_address, webhook_token, webhook_type, params,")
+    sql_statements.append("    created_at, expires_at, last_notification_at, is_active, notification_count")
+    sql_statements.append(") VALUES")
+    
+    channel_values = []
+    for channel in data["watch_channels"]:
+        # Handle nullable fields
+        webhook_token = f"'{channel['webhook_token']}'" if channel['webhook_token'] else "NULL"
+        params = f"'{channel['params']}'" if channel['params'] else "NULL"
+        last_notification = f"'{channel['last_notification_at'].isoformat()}'" if channel['last_notification_at'] else "NULL"
+        expires_at = f"'{channel['expires_at'].isoformat()}'" if channel['expires_at'] else "NULL"
+        
+        # Escape single quotes in webhook addresses
+        webhook_address = channel['webhook_address'].replace("'", "''")
+        
+        channel_values.append(
+            f"('{channel['id']}', '{channel['resource_id']}', '{channel['resource_uri']}', "
+            f"'{channel['resource_type']}', '{channel['calendar_id']}', '{channel['user_id']}', "
+            f"'{webhook_address}', {webhook_token}, '{channel['webhook_type']}', {params}, "
+            f"'{channel['created_at'].isoformat()}', {expires_at}, {last_notification}, "
+            f"'{channel['is_active']}', {channel['notification_count']})"
+        )
+    
+    sql_statements.append(",\n".join(channel_values) + ";")
+    sql_statements.append("")
+    
+    # Add some comments about the data
+    sql_statements.append("-- Watch Channel Data Summary:")
+    sql_statements.append("-- - Alice: 2 active channels + 1 expired")
+    sql_statements.append("-- - Bob: 2 active channels + 1 stopped + 1 shared calendar watch")
+    sql_statements.append("-- - Carol: 1 active channel")
+    sql_statements.append("-- - Dave: 1 active channel")
+    sql_statements.append("-- - Total: 6 active, 1 expired, 1 manually stopped")
+    sql_statements.append("-- - Demonstrates various webhook URLs (Slack, CRM, internal APIs)")
+    sql_statements.append("-- - Shows different notification patterns and usage levels")
+    sql_statements.append("")
+    
+    return sql_statements

server/database/base_manager.py

@@ -0,0 +1,112 @@
+"""
+Base Manager - Common CRUD operations for all Calendar services
+"""
+
+import sqlite3
+import logging
+from typing import Dict, Optional, List, Any
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+
+class BaseManager:
+    """Base manager for common database operations"""
+
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+
+    def execute_query(self, query: str, params: tuple = ()) -> List[Dict]:
+        """Execute a SELECT query and return results"""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        try:
+            cursor = conn.execute(query, params)
+            return [dict(row) for row in cursor.fetchall()]
+        finally:
+            conn.close()
+
+    def execute_insert(self, query: str, params: tuple = ()) -> int:
+        """Execute an INSERT query and return the last row ID"""
+        conn = sqlite3.connect(self.db_path)
+        try:
+            cursor = conn.execute(query, params)
+            conn.commit()
+            return cursor.lastrowid
+        except sqlite3.IntegrityError as e:
+            logger.error(f"Database integrity error: {e}")
+            raise ValueError(f"Database constraint violation: {e}")
+        finally:
+            conn.close()
+
+    def execute_update(self, query: str, params: tuple = ()) -> int:
+        """Execute an UPDATE query and return the number of affected rows"""
+        conn = sqlite3.connect(self.db_path)
+        try:
+            cursor = conn.execute(query, params)
+            conn.commit()
+            return cursor.rowcount
+        finally:
+            conn.close()
+
+    def execute_delete(self, query: str, params: tuple = ()) -> int:
+        """Execute a DELETE query and return the number of affected rows"""
+        conn = sqlite3.connect(self.db_path)
+        try:
+            cursor = conn.execute(query, params)
+            conn.commit()
+            return cursor.rowcount
+        finally:
+            conn.close()
+
+    def get_by_id(self, table: str, record_id: int) -> Optional[Dict]:
+        """Get a record by ID from any table"""
+        query = f"SELECT * FROM {table} WHERE id = ?"
+        results = self.execute_query(query, (record_id,))
+        return results[0] if results else None
+
+    def get_all(self, table: str, limit: int = 100, offset: int = 0, order_by: str = "id DESC") -> List[Dict]:
+        """Get all records from a table with pagination"""
+        query = f"SELECT * FROM {table} ORDER BY {order_by} LIMIT ? OFFSET ?"
+        return self.execute_query(query, (limit, offset))
+
+    def count_records(self, table: str, where_clause: str = "", params: tuple = ()) -> int:
+        """Count records in a table"""
+        query = f"SELECT COUNT(*) as count FROM {table}"
+        if where_clause:
+            query += f" WHERE {where_clause}"
+        result = self.execute_query(query, params)
+        return result[0]["count"] if result else 0
+
+    def update_record(self, table: str, record_id: int, updates: Dict[str, Any]) -> bool:
+        """Update a record with given field values"""
+        if not updates:
+            return False
+
+        # Add updated_at timestamp if the table has this column
+        updates["updated_at"] = datetime.now().isoformat()
+
+        set_clauses = []
+        params = []
+
+        for field, value in updates.items():
+            set_clauses.append(f"{field} = ?")
+            params.append(value)
+
+        params.append(record_id)
+
+        query = f"UPDATE {table} SET {', '.join(set_clauses)} WHERE id = ?"
+        affected_rows = self.execute_update(query, tuple(params))
+        return affected_rows > 0
+
+    def delete_record(self, table: str, record_id: int) -> bool:
+        """Delete a record by ID"""
+        query = f"DELETE FROM {table} WHERE id = ?"
+        affected_rows = self.execute_delete(query, (record_id,))
+        return affected_rows > 0
+
+    def table_exists(self, table_name: str) -> bool:
+        """Check if a table exists"""
+        query = "SELECT name FROM sqlite_master WHERE type='table' AND name=?"
+        result = self.execute_query(query, (table_name,))
+        return len(result) > 0

server/database/managers/acl_manager.py

@@ -0,0 +1,595 @@
+from sqlalchemy.orm import Session
+from sqlalchemy import and_, or_, desc
+from database.models.acl import ACLs, Scope, AclRole
+from database.models.watch_channel import WatchChannel
+from schemas.acl import ACLRuleInput, PatchACLRuleInput, Channel, ACLListResponse, ACLRule, ScopeInput, ScopeOutput
+from services.notification_service import get_notification_service
+from uuid import uuid4
+from datetime import datetime, timedelta
+from typing import Dict, Any, Optional
+import logging
+import json
+import uuid
+import base64
+from database.models.calendar import Calendar
+from database.models.user import User
+
+logger = logging.getLogger(__name__)
+
+
+class ACLManager:
+    def __init__(self, db: Session, user_id: str):
+        self.db = db
+        self.user_id = user_id
+
+    def validate_calendar_id(self, calendar_id, user_id):
+        calendar = self.db.query(Calendar).filter(
+        Calendar.calendar_id == calendar_id,
+         Calendar.user_id == user_id,
+         Calendar.deleted == False
+         ).first()
+        if not calendar:
+            return False
+        return True
+
+    def list_rules(self, calendar_id: str, max_results: int = 100,
+                   page_token: Optional[str] = None, show_deleted: bool = False,
+                   sync_token: Optional[str] = None) -> ACLListResponse:
+        """
+        List ACL rules for a calendar with pagination and filtering support.
+        
+        Args:
+            calendar_id: The calendar ID
+            max_results: Maximum number of entries per page (1-250, default 100)
+            page_token: Token for pagination continuation
+            show_deleted: Whether to include deleted ACLs (role == "none")
+            sync_token: Token for incremental synchronization
+            
+        Returns:
+            ACLListResponse with items and pagination tokens
+        """
+        try:
+            # Handle sync token for incremental synchronization
+            if sync_token:
+                return self._handle_sync_request(calendar_id, sync_token, max_results, show_deleted)
+            
+            # Base query
+            query = self.db.query(ACLs).filter(
+                ACLs.calendar_id == calendar_id,
+                ACLs.user_id == self.user_id
+            )
+            
+            # Filter deleted ACLs if not requested
+            if not show_deleted:
+                query = query.filter(ACLs.role != AclRole.none)
+            
+            # Order by created_at for consistent pagination
+            query = query.order_by(ACLs.created_at, ACLs.id)
+            
+            # Handle pagination
+            offset = 0
+            if page_token:
+                try:
+                    offset = int(base64.b64decode(page_token).decode('utf-8'))
+                except (ValueError, TypeError):
+                    raise ValueError("Invalid pageToken")
+            
+            # Get one extra item to determine if there's a next page
+            items = query.offset(offset).limit(max_results + 1).all()
+            
+            # Determine if there's a next page
+            has_next_page = len(items) > max_results
+            if has_next_page:
+                items = items[:max_results]  # Remove the extra item
+                next_page_token = base64.b64encode(str(offset + max_results).encode('utf-8')).decode('utf-8')
+            else:
+                next_page_token = None
+            
+            # Generate next sync token
+            latest_updated = self.db.query(ACLs.updated_at).filter(
+                ACLs.calendar_id == calendar_id,
+                ACLs.user_id == self.user_id
+            ).order_by(desc(ACLs.updated_at)).first()
+            
+            next_sync_token = None
+            if latest_updated and latest_updated[0]:
+                sync_data = {
+                    'calendar_id': calendar_id,
+                    'timestamp': latest_updated[0].isoformat()
+                }
+                next_sync_token = base64.b64encode(json.dumps(sync_data).encode('utf-8')).decode('utf-8')
+            
+            # Generate collection etag
+            etag = f'"{uuid4()}"'
+            
+            # Convert database models to schema models
+            acl_rules = []
+            for item in items:
+                if item.scope.type == "default":
+                    scope = ScopeOutput(type=item.scope.type)
+                else:
+                    scope = ScopeOutput(
+                        type=item.scope.type,
+                        value=item.scope.value
+                    )
+                acl_rule = ACLRule(
+                    id=item.id,
+                    calendar_id=item.calendar_id,
+                    user_id=item.user_id,
+                    role=item.role,
+                    etag=item.etag,
+                    scope=scope
+                )
+                acl_rules.append(acl_rule)
+
+            return ACLListResponse(
+                etag=etag,
+                items=acl_rules,
+                nextPageToken=next_page_token,
+                nextSyncToken=next_sync_token
+            )
+            
+        except Exception as e:
+            logger.error(f"Error listing ACL rules: {e}")
+            raise
+    
+    def _handle_sync_request(self, calendar_id: str, sync_token: str,
+                           max_results: int, show_deleted: bool) -> ACLListResponse:
+        """
+        Handle incremental synchronization request.
+        
+        Args:
+            calendar_id: The calendar ID
+            sync_token: The sync token from previous request
+            max_results: Maximum number of entries per page
+            show_deleted: Whether to include deleted ACLs
+            
+        Returns:
+            ACLListResponse with changes since the sync token
+        """
+        try:
+            # Decode sync token
+            sync_data = json.loads(base64.b64decode(sync_token).decode('utf-8'))
+            last_sync_time = datetime.fromisoformat(sync_data['timestamp'])
+            
+            # Verify calendar ID matches
+            if sync_data.get('calendar_id') != calendar_id:
+                raise ValueError("Sync token calendar ID mismatch")
+            
+            # Check if sync token is too old (expired)
+            if (datetime.utcnow() - last_sync_time).days > 7:  # 7 days expiration
+                from fastapi import HTTPException
+                raise HTTPException(status_code=410, detail="Sync token expired")
+            
+            # Query for changes since last sync
+            query = self.db.query(ACLs).filter(
+                ACLs.calendar_id == calendar_id,
+                ACLs.user_id == self.user_id,
+                ACLs.updated_at > last_sync_time
+            )
+            
+            # Always include deleted ACLs in sync requests (Google API behavior)
+            # Order by updated_at for consistent results
+            query = query.order_by(ACLs.updated_at, ACLs.id)
+            
+            # Apply limit
+            items = query.limit(max_results + 1).all()
+            
+            # Determine if there's more data
+            has_more = len(items) > max_results
+            if has_more:
+                items = items[:max_results]
+                # For sync requests, we don't use page tokens, just return what we have
+                # Client should make another sync request with updated sync token
+            
+            # Generate new sync token based on latest item
+            next_sync_token = None
+            if items:
+                latest_time = max(item.updated_at for item in items)
+                sync_data = {
+                    'calendar_id': calendar_id,
+                    'timestamp': latest_time.isoformat()
+                }
+                next_sync_token = base64.b64encode(json.dumps(sync_data).encode('utf-8')).decode('utf-8')
+            else:
+                # No changes, return same sync token
+                next_sync_token = sync_token
+            
+            # Generate collection etag
+            etag = f'"{uuid4()}"'
+            
+            # Convert database models to schema models
+            acl_rules = []
+            for item in items:
+                scope = ScopeInput(
+                    type=item.scope.type,
+                    value=item.scope.value
+                )
+                acl_rule = ACLRule(
+                    id=item.id,
+                    calendar_id=item.calendar_id,
+                    user_id=item.user_id,
+                    role=item.role,
+                    etag=item.etag,
+                    scope=scope
+                )
+                acl_rules.append(acl_rule)
+            
+            return ACLListResponse(
+                etag=etag,
+                items=acl_rules,
+                nextPageToken=None,  # No page tokens in sync mode
+                nextSyncToken=next_sync_token
+            )
+            
+        except json.JSONDecodeError:
+            raise ValueError("Invalid sync token format")
+        except Exception as e:
+            logger.error(f"Error handling sync request: {e}")
+            raise
+
+    def get_rule(self, calendar_id: str, rule_id: str):
+        """
+        Retrieve a specific ACL rule by calendar ID and rule ID (must be owned).
+        """
+        return self.db.query(ACLs).filter_by(
+            id=rule_id,
+            calendar_id=calendar_id,
+            user_id=self.user_id
+        ).first()
+
+    def insert_rule(self, calendar_id: str, rule: ACLRuleInput, send_notifications: bool = True):
+        """
+        Insert a new ACL rule after validating scope existence.
+
+        Args:
+            calendar_id: The calendar ID
+            rule: The ACL rule input data
+            send_notifications: Whether to send notifications about the calendar sharing change (default: True)
+
+        Returns the inserted ACL rule.
+        """
+        # Look up scope (must exist)
+        if rule.scope.type == "default":
+            scope = self.db.query(Scope).filter(Scope.type == rule.scope.type).first()
+        else:
+            if rule.scope.value is None:
+                scope = self.db.query(Scope).filter(Scope.type == rule.scope.type).first()
+            else:
+                scope = (
+                    self.db.query(Scope)
+                    .filter(Scope.type == rule.scope.type, Scope.value == rule.scope.value)
+                    .first()
+                )
+
+        if not scope:
+            raise ValueError(f"Scope ({rule.scope.type}, {rule.scope.value}) not found")
+
+        # Create ACL rule
+        rule_id = f"{uuid4()}"
+        db_rule = ACLs(
+            id=rule_id,
+            calendar_id=calendar_id,
+            user_id=self.user_id,
+            role=rule.role,
+            scope_id=scope.id,
+            etag=f'"{uuid4()}"',
+            created_at=datetime.utcnow(),
+            updated_at=datetime.utcnow()
+        )
+        self.db.add(db_rule)
+        self.db.commit()
+        self.db.refresh(db_rule)
+        
+        # Send notification for ACL rule insertion if notifications are enabled
+        if send_notifications:
+            self._send_acl_notification(calendar_id, "insert", {
+                "id": db_rule.id,
+                "calendar_id": db_rule.calendar_id,
+                "user_id": db_rule.user_id,
+                "role": db_rule.role.value,
+                "scope": scope.as_dict(),
+                "etag": db_rule.etag
+            })
+
+        response = {
+            "kind": "calendar#aclRule",
+            "etag": db_rule.etag,
+            "id": db_rule.id,
+            "scope":{},
+            "role": db_rule.role.value
+        }
+        scope_dict = scope.as_dict()
+        response["scope"]["type"] = scope_dict.get("type")
+        if scope_dict.get("value") != "public":
+            response["scope"]["value"] = scope_dict.get("value")
+        return response
+
+    def update_rule(self, calendar_id: str, rule_id: str, rule: ACLRuleInput, send_notifications: bool = True):
+        """
+        Fully replace an existing ACL rule's role and scope.
+
+        Returns the updated rule or None if not found.
+        """
+        db_rule = self.get_rule(calendar_id, rule_id)
+
+        if not db_rule:
+            return None
+
+        if rule.role is not None:
+            db_rule.role = rule.role
+        # Update scope
+        if rule.scope is not None:
+            if db_rule.scope:
+                db_rule.scope.type = rule.scope.type
+                if rule.scope.value is not None and rule.scope.type != "default":
+                    if rule.scope.type in ["user", "group"]:
+                        # Validate whether value contains valid email address
+                        user = self.db.query(User).filter(User.email == rule.scope.value, User.is_active == True).first()
+                        if user is None:
+                            raise ValueError("Invalid data in 'value field'. Please enter an existing email id in 'value' field")
+                    db_rule.scope.value = rule.scope.value
+            else:
+                raise ValueError("ACL rule has no associated scope object to update.")
+        db_rule.updated_at = datetime.utcnow()
+        self.db.commit()
+        self.db.refresh(db_rule)
+        
+        # Send notification for ACL rule update if notifications are enabled
+        if send_notifications:
+            self._send_acl_notification(calendar_id, "update", {
+                "id": db_rule.id,
+                "calendar_id": db_rule.calendar_id,
+                "user_id": db_rule.user_id,
+                "role": db_rule.role.value,
+                "scope": db_rule.scope.as_dict(),
+                "etag": db_rule.etag
+            })
+        
+        response = {
+            "kind": "calendar#aclRule",
+            "etag": db_rule.etag,
+            "id": db_rule.id,
+            "scope":{},
+            "role": db_rule.role.value
+        }
+        scope_dict = db_rule.scope.as_dict()
+        response["scope"]["type"] = scope_dict.get("type")
+        if scope_dict.get("value") != "public":
+            response["scope"]["value"] = scope_dict.get("value")
+        return response
+
+    def patch_rule(self, calendar_id: str, rule_id: str, rule: PatchACLRuleInput, send_notifications: bool = True):
+        """
+        Partially update an ACL rule's role or scope if provided.
+
+        Returns the updated rule or None if not found.
+        """
+        db_rule = self.get_rule(calendar_id, rule_id)
+        if not db_rule:
+            return None
+
+        if rule.role is not None:
+            db_rule.role = rule.role
+
+        if rule.scope is not None:
+            # Patch the related Scope object, not as a dict
+            if db_rule.scope:
+                db_rule.scope.type = rule.scope.type
+                if rule.scope.value is not None and rule.scope.type != "default":
+                    if rule.scope.type in ["user", "group"]:
+                        # Validate whether value contains valid email address
+                        user = self.db.query(User).filter(User.email == rule.scope.value, User.is_active == True).first()
+                        if user is None:
+                            raise ValueError("Invalid data in 'value field'. Please enter an existing email id in 'value' field")
+                    db_rule.scope.value = rule.scope.value
+            else:
+                raise ValueError("ACL rule has no associated scope object to patch.")
+
+        db_rule.updated_at = datetime.utcnow()
+        self.db.commit()
+        self.db.refresh(db_rule)
+        
+        # Send notification for ACL rule patch if notifications are enabled
+        if send_notifications:
+            self._send_acl_notification(calendar_id, "update", {
+                "id": db_rule.id,
+                "calendar_id": db_rule.calendar_id,
+                "user_id": db_rule.user_id,
+                "role": db_rule.role.value,
+                "scope": db_rule.scope.as_dict(),
+                "etag": db_rule.etag
+            })
+        
+        response = {
+            "kind": "calendar#aclRule",
+            "etag": db_rule.etag,
+            "id": db_rule.id,
+            "scope":{},
+            "role": db_rule.role.value
+        }
+        scope_dict = db_rule.scope.as_dict()
+        response["scope"]["type"] = scope_dict.get("type")
+        if scope_dict.get("value") != "public":
+            response["scope"]["value"] = scope_dict.get("value")
+        return response
+
+    def delete_rule(self, calendar_id: str, rule_id: str) -> bool:
+        """
+        Delete an ACL rule by ID and calendar ID. Only the calendar owner can delete ACLs.
+
+        Returns:
+            True if deleted, False if rule not found.
+        Raises:
+            Exception if DB operation fails.
+        """
+        session = self.db
+        try:
+            from database.models import Calendar  # to resolve join dependency
+            rule = session.query(ACLs).join(Calendar).filter(
+                ACLs.id == rule_id,
+                ACLs.calendar_id == calendar_id,
+                Calendar.user_id == self.user_id
+            ).first()
+
+            if not rule:
+                return False
+
+            # Capture rule data before deletion for notification
+            rule_data = {
+                "id": rule.id,
+                "calendar_id": rule.calendar_id,
+                "user_id": rule.user_id,
+                "role": rule.role.value,
+                "scope": rule.scope.as_dict() if rule.scope else {},
+                "etag": rule.etag
+            }
+
+            session.delete(rule)
+            session.commit()
+            
+            # Send notification for ACL rule deletion
+            self._send_acl_notification(calendar_id, "delete", rule_data)
+            
+            return True
+
+        except Exception as e:
+            session.rollback()
+            raise
+
+    def watch_acl(
+        self,
+        user_id:str,
+        calendar_id: str,
+        watch_request: Dict[str, Any]
+    ) -> Channel:
+        """
+        Set up watch notifications for ACL changes.
+
+        POST /calendars/{calendarId}/acl/watch
+        """
+        try:
+            session = self.db
+
+            # Generate unique resource ID for events watch
+            resource_id = f"acl-{calendar_id}-{uuid.uuid4().hex[:8]}"
+            resource_uri = f"/calendars/{calendar_id}/acl"
+            # Validate that the user has access to the calendar
+            
+            # Default expiration: 24 hours from now
+            expires_at = datetime.utcnow() + timedelta(hours=24)
+
+            # Verify calendar belongs to user
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            if not calendar:
+                raise ValueError(f"Calendar {calendar_id} not found for user {user_id}")
+
+            if session.query(WatchChannel).filter(WatchChannel.id == watch_request.id).first():
+                raise ValueError(f"Channel with Id {watch_request.id} already exists")
+
+            # Create watch channel record
+            watch_channel = WatchChannel(
+                id=watch_request.id,
+                resource_id=resource_id,
+                resource_uri=resource_uri,
+                resource_type="acl",
+                calendar_id=calendar_id,
+                user_id=user_id,
+                webhook_address=watch_request.address,
+                webhook_token=watch_request.token,
+                webhook_type=watch_request.type,
+                params=json.dumps(watch_request.params.model_dump()) if watch_request.params else None,
+                created_at=datetime.utcnow(),
+                expires_at=expires_at,
+                is_active="true",
+                notification_count=0
+            )
+            
+            # Save to database
+            session.add(watch_channel)
+            session.commit()
+            
+            logger.info(f"Created settings watch channel {watch_request.id} for user {user_id}")
+
+
+                       
+            # Create response channel
+            channel = Channel(
+                id=watch_channel.id,
+                resourceId=resource_id,
+                resourceUri=watch_channel.resource_uri,
+                token=watch_channel.webhook_token,
+                expiration=watch_channel.expires_at.isoformat() + "Z" if watch_channel.expires_at else None
+            )
+            
+            logger.info(f"Set up watch channel {watch_channel.id} for ACL changes in calendar {calendar_id}")
+            return channel
+            
+        except Exception as e:
+            logger.error(f"Error setting up ACL watch for calendar {calendar_id}: {e}")
+            self.db.rollback()
+            raise
+
+    def cleanup_expired_channels(self) -> int:
+        """
+        Clean up expired watch channels for this user
+        
+        Returns:
+            Number of channels cleaned up
+        """
+        try:
+            current_time = datetime.utcnow()
+            
+            # Find expired channels for this user
+            expired_channels = self.db.query(WatchChannel).filter(
+                WatchChannel.user_id == self.user_id,
+                WatchChannel.expires_at < current_time,
+                WatchChannel.is_active == "true"
+            ).all()
+            
+            cleanup_count = 0
+            for channel in expired_channels:
+                channel.is_active = "false"
+                cleanup_count += 1
+                
+            if cleanup_count > 0:
+                self.db.commit()
+                logger.info(f"Cleaned up {cleanup_count} expired watch channels for user {self.user_id}")
+                
+            return cleanup_count
+            
+        except Exception as e:
+            logger.error(f"Error cleaning up expired channels: {e}")
+            self.db.rollback()
+            return 0
+
+    def _send_acl_notification(self, calendar_id: str, change_type: str, acl_data: Dict[str, Any]):
+        """
+        Send ACL change notification to all active watch channels for the calendar
+        
+        Args:
+            calendar_id: The calendar ID
+            change_type: Type of change ("insert", "update", "delete")
+            acl_data: The ACL rule data
+        """
+        try:
+            notification_service = get_notification_service(self.db)
+            notifications_sent = notification_service.notify_acl_change(
+                calendar_id,
+                change_type,
+                acl_data
+            )
+            
+            if notifications_sent > 0:
+                logger.debug(f"Sent {notifications_sent} notifications for ACL {change_type} in calendar {calendar_id}")
+                
+        except Exception as e:
+            logger.error(f"Error sending ACL notification: {e}")
+            # Don't raise the exception as notification failure shouldn't break the main operation
+
+
+def get_acl_manager(db: Session, user_id: str) -> ACLManager:
+    return ACLManager(db, user_id)

server/database/managers/calendar_list_manager.py

@@ -0,0 +1,626 @@
+"""
+Calendar List Manager - Database operations for calendar list management using SQLAlchemy
+Manages user-specific calendar settings and access in a database-per-user architecture
+"""
+
+import logging
+import uuid
+import json
+import base64
+from typing import Dict, List, Optional, Tuple
+from datetime import datetime
+from sqlalchemy.orm import Session
+from sqlalchemy.exc import IntegrityError
+from database.models import Calendar, Event, User
+from database.models.acl import ACLs, Scope
+from database.models.watch_channel import WatchChannel
+from database.session_utils import get_session, init_database
+from schemas.calendar_list import WatchRequest
+from datetime import timedelta
+from schemas.settings import Channel
+from fastapi import HTTPException, status
+
+logger = logging.getLogger(__name__)
+
+# Allowed values aligning with Google Calendar API v3
+ALLOWED_REMINDER_METHODS = {"email", "popup"}
+ALLOWED_NOTIFICATION_METHODS = {"email"}
+ALLOWED_NOTIFICATION_TYPES = {
+    "eventCreation",
+    "eventChange",
+    "eventCancellation",
+    "eventResponse",
+    "agenda",
+}
+
+
+class CalendarListManager:
+    """Manager for calendar list database operations using SQLAlchemy"""
+
+    def __init__(self, database_id: str):
+        self.database_id = database_id
+        # Initialize database on first use
+        init_database(database_id)
+
+    def list_calendar_entries(
+        self,
+        user_id: str,
+        max_results: Optional[int] = None,
+        min_access_role: Optional[str] = None,
+        show_deleted: Optional[bool] = False,
+        show_hidden: Optional[bool] = False,
+        page_token: Optional[str] = None,
+        sync_token: Optional[str] = None
+    ) -> Tuple[List[Dict], Optional[str], Optional[str]]:
+        """List all calendar entries in user's calendar list
+
+        Notes:
+        - If max_results is None, return all (subject to other filters)
+        - If max_results is 0, return an empty list (explicit zero results)
+        - If max_results > 0, limit the results accordingly
+        - min_access_role filters calendars based on user's minimum access role
+        - page_token specifies which result page to return
+        - sync_token enables incremental synchronization
+        
+        Returns:
+        - Tuple of (calendar_entries, next_page_token, next_sync_token)
+        """
+        session = get_session(self.database_id)
+        try:
+            # Handle sync token for incremental synchronization
+            sync_timestamp = None
+            if sync_token:
+                try:
+                    sync_timestamp = self._decode_sync_token(sync_token)
+                except (ValueError, TypeError) as e:
+                    logger.error(f"Invalid sync token: {sync_token}, error: {e}")
+                    raise ValueError(f"Invalid sync token. Please perform full synchronization.")
+            
+            # Parse page token to get offset
+            offset = 0
+            if page_token:
+                try:
+                    offset = self._decode_page_token(page_token)
+                except (ValueError, TypeError) as e:
+                    logger.warning(f"Invalid page token: {page_token}, error: {e}")
+                    offset = 0
+            
+            query = session.query(Calendar).filter(Calendar.user_id == user_id)
+
+            # Apply sync token filtering for incremental sync
+            if sync_token and sync_timestamp:
+                # For incremental sync, return entries modified since sync timestamp
+                query = query.filter(Calendar.updated_at > sync_timestamp)
+                # Include deleted and hidden entries when using sync token
+                show_deleted = True
+                show_hidden = True
+            else:
+                # Filter deleted calendars unless specifically requested
+                if not show_deleted:
+                    query = query.filter(Calendar.deleted.is_(False))
+            
+            # Order consistently for pagination (by calendar_id for deterministic results)
+            query = query.order_by(Calendar.calendar_id)
+            
+            # Apply offset for pagination
+            if offset > 0:
+                query = query.offset(offset)
+            
+            # Apply limit if specified (support 0 to return empty set)
+            # For pagination, we fetch max_results + 1 to determine if there are more pages
+            fetch_limit = None
+            if max_results is not None:
+                # Negative values are treated as 0 (empty set)
+                limit_value = max(0, int(max_results))
+                if limit_value == 0:
+                    return [], None, None
+                fetch_limit = limit_value + 1  # Fetch one extra to check for next page
+                query = query.limit(fetch_limit)
+            
+            calendars = query.all()
+            
+            # Define access role hierarchy for filtering
+            role_hierarchy = {
+                "freeBusyReader": 1,
+                "reader": 2,
+                "writer": 3,
+                "owner": 4
+            }
+            
+            min_role_level = role_hierarchy.get(min_access_role, 0) if min_access_role else 0
+            
+            result = []
+            for calendar in calendars:
+                # Check if user has sufficient access role if min_access_role is specified
+                if min_access_role:
+                    user_access_role = self._get_user_access_role(user_id, calendar)
+                    user_role_level = role_hierarchy.get(user_access_role, 0)
+                    
+                    # Skip calendars where user doesn't meet minimum access role
+                    if user_role_level < min_role_level:
+                        continue
+                
+                entry = self._format_calendar_list_entry(calendar, show_hidden, user_id)
+                if entry:
+                    result.append(entry)
+            
+            # Determine if there are more pages
+            next_page_token = None
+            if max_results is not None and len(result) > max_results:
+                # Remove the extra item and generate next page token
+                result = result[:max_results]
+                next_offset = offset + max_results
+                next_page_token = self._encode_page_token(next_offset)
+            
+            # Generate next sync token for incremental sync
+            next_sync_token = None
+            if len(result) > 0:
+                # Generate sync token based on current timestamp
+                next_sync_token = self._encode_sync_token(datetime.utcnow())
+            
+            return result, next_page_token, next_sync_token
+            
+        except Exception as e:
+            logger.error(f"Error listing calendar entries: {e}")
+            raise
+        finally:
+            session.close()
+
+    def get_calendar_entry(self, user_id: str, calendar_id: str) -> Optional[Dict]:
+        """Get a specific calendar entry from user's calendar list"""
+        session = get_session(self.database_id)
+        try:
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            
+            if not calendar or calendar.deleted:
+                return None
+
+            return self._format_calendar_list_entry(calendar, show_hidden=True, user_id=user_id)
+
+        except Exception as e:
+            logger.error(f"Error getting calendar entry {calendar_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def insert_calendar_entry(self, user_id: str, calendar_id: str, entry_data: Dict) -> Optional[Dict]:
+        """Insert an existing calendar into user's calendar list"""
+        session = get_session(self.database_id)
+        try:
+            # Check if calendar exists
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            
+            if not calendar:
+                # If calendar doesn't exist, we could create it or return None
+                # For this implementation, we'll return None (calendar must exist first)
+                return None
+            
+            # If calendar is soft-deleted from list, restore it on insert (Google API semantics)
+            if calendar.deleted:
+                calendar.deleted = False
+
+            # Update calendar with list-specific settings
+            if "summaryOverride" in entry_data:
+                calendar.summary_override = entry_data["summaryOverride"]
+            if "colorId" in entry_data:
+                calendar.color_id = entry_data["colorId"]
+            if "backgroundColor" in entry_data:
+                calendar.background_color = entry_data["backgroundColor"]
+            if "foregroundColor" in entry_data:
+                calendar.foreground_color = entry_data["foregroundColor"]
+            if "hidden" in entry_data:
+                calendar.hidden = entry_data["hidden"]
+            if "selected" in entry_data:
+                calendar.selected = entry_data["selected"]
+            if "defaultReminders" in entry_data:
+                calendar.default_reminders = json.dumps(entry_data["defaultReminders"]) if entry_data["defaultReminders"] else None
+            if "notificationSettings" in entry_data:
+                calendar.notification_settings = json.dumps(entry_data["notificationSettings"]) if entry_data["notificationSettings"] else None
+
+            session.commit()
+
+            return self._format_calendar_list_entry(calendar, show_hidden=True, user_id=user_id)
+
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error inserting calendar entry {calendar_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def update_calendar_entry(self, user_id: str, calendar_id: str, entry_data: Dict, is_patch: bool = True) -> Optional[Dict]:
+        """Update a calendar entry in user's calendar list"""
+        session = get_session(self.database_id)
+        try:
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            
+            if not calendar or calendar.deleted:
+                return None
+            
+            # Update fields based on entry data
+            if "summaryOverride" in entry_data:
+                calendar.summary_override = entry_data["summaryOverride"]
+            elif not is_patch:
+                # For PUT requests, clear the field if not provided
+                calendar.summary_override = None
+                
+            if "colorId" in entry_data:
+                calendar.color_id = entry_data["colorId"]
+            elif not is_patch:
+                calendar.color_id = None
+                
+            if "backgroundColor" in entry_data:
+                calendar.background_color = entry_data["backgroundColor"]
+            elif not is_patch:
+                calendar.background_color = None
+                
+            if "foregroundColor" in entry_data:
+                calendar.foreground_color = entry_data["foregroundColor"]
+            elif not is_patch:
+                calendar.foreground_color = None
+                
+            if "hidden" in entry_data:
+                calendar.hidden = entry_data["hidden"]
+            elif not is_patch:
+                # For PUT (full update), set default for NOT NULL fields when not provided
+                calendar.hidden = False
+                
+            if "selected" in entry_data:
+                calendar.selected = entry_data["selected"]
+            elif not is_patch:
+                # For PUT (full update), set default for NOT NULL fields when not provided
+                calendar.selected = True
+                
+            if "defaultReminders" in entry_data:
+                calendar.default_reminders = json.dumps(entry_data["defaultReminders"]) if entry_data["defaultReminders"] else None
+            elif not is_patch:
+                calendar.default_reminders = None
+                
+            if "notificationSettings" in entry_data:
+                calendar.notification_settings = json.dumps(entry_data["notificationSettings"]) if entry_data["notificationSettings"] else None
+            elif not is_patch:
+                calendar.notification_settings = None
+
+            if "conferenceProperties" in entry_data:
+                calendar.conference_properties = json.dumps(entry_data["conferenceProperties"]) if entry_data["conferenceProperties"] else None
+
+            session.commit()
+
+            return self._format_calendar_list_entry(calendar, show_hidden=True, user_id=user_id)
+
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error updating calendar entry {calendar_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def delete_calendar_entry(self, user_id: str, calendar_id: str) -> bool:
+        """Remove a calendar from user's calendar list"""
+        session = get_session(self.database_id)
+        try:
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            
+            if not calendar or calendar.deleted:
+                return False
+            
+            # For primary calendar, we can't remove it from the list
+            if calendar.is_primary:
+                raise ValueError("Cannot remove primary calendar from calendar list")
+            
+            # Mark as deleted (soft delete for calendar list)
+            calendar.deleted = True
+            session.commit()
+            return True
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error deleting calendar entry {calendar_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def _has_acl_role(self, user_id: str, calendar: Calendar, allowed_roles: List[str]) -> bool:
+        """Check if user has required ACL permissions for calendar operations"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            if not user:
+                logger.warning(f"No user found with ID: {user_id}")
+                return False
+
+            acls = (
+                session.query(ACLs)
+                .join(Scope, ACLs.scope_id == Scope.id)
+                .filter(
+                    ACLs.calendar_id == calendar.calendar_id,
+                    Scope.type == "user",
+                    Scope.value == user.email
+                )
+                .all()
+            )
+
+            if not acls:
+                logger.warning(f"No ACL found for user {user.email} on calendar {calendar.calendar_id}")
+                return False
+
+            for acl in acls:
+                if acl.role.value in allowed_roles:
+                    return True
+
+            logger.warning(f"User {user.email} has ACLs but lacks required roles: {allowed_roles}")
+            return False
+        finally:
+            session.close()
+
+    def check_calendar_acl_permissions(self, user_id: str, calendar_id: str, allowed_roles: List[str]) -> Calendar:
+        """Check if user has required ACL permissions for calendar operations and return calendar"""
+        session = get_session(self.database_id)
+        try:
+            calendar = session.query(Calendar).filter(Calendar.calendar_id == calendar_id).first()
+            if not calendar:
+                raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Calendar with id '{calendar_id}' does not exist")
+
+            if not self._has_acl_role(user_id, calendar, allowed_roles):
+                raise PermissionError(f"User '{user_id}' lacks required roles: {allowed_roles}")
+
+            return calendar
+        finally:
+            session.close()
+
+    def watch_calendar_list(self, watch_request: WatchRequest, user_id: str) -> Dict:
+        """Set up watch notifications for calendar list changes"""
+
+        session = get_session(self.database_id)
+        try:
+            # Generate unique resource ID for settings watch
+            resource_id = f"calendarList-{user_id}-{uuid.uuid4().hex[:8]}"
+            resource_uri = "/calendars/me/calendarList"
+
+            # Calculate expiration time (max 24 hours from now if not specified)
+            now = datetime.utcnow()
+            expires_at = now + timedelta(hours=24)
+            
+            if session.query(WatchChannel).filter(WatchChannel.id == watch_request.id).first():
+                raise ValueError(f"Channel with Id {watch_request.id} already exists")
+            # Create watch channel record
+            watch_channel = WatchChannel(
+                id=watch_request.id,
+                resource_id=resource_id,
+                resource_uri=resource_uri,
+                resource_type="calendar_list",
+                calendar_id="",
+                user_id=user_id,
+                webhook_address=watch_request.address,
+                webhook_token=watch_request.token,
+                webhook_type=watch_request.type,
+                params=json.dumps(watch_request.params.model_dump()) if watch_request.params else None,
+                created_at=now,
+                expires_at=expires_at,
+                is_active="true",
+                notification_count=0
+            )
+            
+            # Save to database
+            session.add(watch_channel)
+            session.commit()
+            
+            logger.info(f"Created settings watch channel {watch_request.id} for user {user_id}")
+            
+            # Return channel response
+            return {
+                "kind":"api#channel",
+                "id":watch_channel.id,
+                "resourceId":resource_id,
+                "resourceUri":resource_uri,
+                "token":watch_channel.webhook_token,
+                "expiration": expires_at.isoformat() + "Z" if expires_at else None
+            }
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error creating settings watch channel: {e}")
+            raise
+        finally:
+            session.close()
+
+
+    def _get_user_access_role(self, user_id: str, calendar: Calendar) -> str:
+        """Get the user's actual access role for a calendar based on ACL entries"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            if not user:
+                return "none"
+
+            acls = (
+                session.query(ACLs)
+                .join(Scope, ACLs.scope_id == Scope.id)
+                .filter(
+                    ACLs.calendar_id == calendar.calendar_id,
+                    Scope.type == "user",
+                    Scope.value == user.email
+                )
+                .all()
+            )
+
+            if not acls:
+                return "none"
+
+            # Return the highest permission level found
+            role_hierarchy = {"none": 0, "freeBusyReader": 1, "reader": 2, "writer": 3, "owner": 4}
+            highest_role = "none"
+            highest_weight = 0
+
+            for acl in acls:
+                role_weight = role_hierarchy.get(acl.role.value, 0)
+                if role_weight > highest_weight:
+                    highest_weight = role_weight
+                    highest_role = acl.role.value
+
+            return highest_role
+        finally:
+            session.close()
+
+    def _format_calendar_list_entry(self, calendar: Calendar, show_hidden: bool = False, user_id: str = None) -> Optional[Dict]:
+        """Format calendar model for calendar list API response"""
+        # Skip hidden calendars unless explicitly requested
+        if calendar.hidden and not show_hidden:
+            return None
+
+        # Determine access role from actual ACL data
+        access_role = "owner" if calendar.is_primary else "writer"  # Default fallback
+        if user_id:
+            access_role = self._get_user_access_role(user_id, calendar)
+
+        formatted = {
+            "kind": "calendar#calendarListEntry",
+            "etag": f"etag-list-{calendar.calendar_id}-{calendar.updated_at.isoformat() if calendar.updated_at else ''}",
+            "id": calendar.calendar_id,
+            "summary": calendar.summary_override or calendar.summary,
+            "description": calendar.description,
+            "location": calendar.location,
+            "timeZone": calendar.time_zone,
+            "accessRole": access_role,
+            "primary": calendar.is_primary,
+            "hidden": calendar.hidden or False,
+            "selected": calendar.selected if calendar.selected is not None else True,
+            "deleted": calendar.deleted or False
+        }
+        
+        # Add optional fields if present
+        if calendar.summary_override:
+            formatted["summaryOverride"] = calendar.summary_override
+            
+        if calendar.color_id:
+            formatted["colorId"] = calendar.color_id
+            
+        if calendar.background_color:
+            formatted["backgroundColor"] = calendar.background_color
+            
+        if calendar.foreground_color:
+            formatted["foregroundColor"] = calendar.foreground_color
+            
+        if calendar.default_reminders:
+            try:
+                raw_items = json.loads(calendar.default_reminders)
+                sanitized: List[Dict] = []
+                if isinstance(raw_items, list):
+                    for item in raw_items:
+                        if not isinstance(item, dict):
+                            continue
+                        method = item.get("method")
+                        minutes = item.get("minutes")
+                        if (
+                            method in ALLOWED_REMINDER_METHODS
+                            and isinstance(minutes, int)
+                            and minutes >= 0
+                        ):
+                            sanitized.append({"method": method, "minutes": minutes})
+                if sanitized:
+                    formatted["defaultReminders"] = sanitized
+            except Exception:
+                # Ignore malformed stored data
+                pass
+                
+        if calendar.notification_settings:
+            try:
+                raw = json.loads(calendar.notification_settings)
+                if isinstance(raw, dict):
+                    notifs = raw.get("notifications")
+                    sanitized_notifs: List[Dict] = []
+                    if isinstance(notifs, list):
+                        for n in notifs:
+                            if not isinstance(n, dict):
+                                continue
+                            m = n.get("method")
+                            t = n.get("type")
+                            if m in ALLOWED_NOTIFICATION_METHODS and t in ALLOWED_NOTIFICATION_TYPES:
+                                sanitized_notifs.append({"method": m, "type": t})
+                    if sanitized_notifs:
+                        formatted["notificationSettings"] = {"notifications": sanitized_notifs}
+            except Exception:
+                # Ignore malformed stored data
+                pass
+
+        # Add conference properties
+        if calendar.conference_properties:
+            try:
+                # conference_properties is stored as JSON string, parse it
+                conf_props = json.loads(calendar.conference_properties)
+                formatted["conferenceProperties"] = conf_props
+            except Exception:
+                # If parsing fails, provide default
+                formatted["conferenceProperties"] = {
+                    "allowedConferenceSolutionTypes": []
+                }
+        else:
+            formatted["conferenceProperties"] = {
+                "allowedConferenceSolutionTypes": []
+            }
+        
+        return formatted
+
+    def _encode_page_token(self, offset: int) -> str:
+        """Encode offset as a page token"""
+        try:
+            token_data = str(offset)
+            return base64.b64encode(token_data.encode('utf-8')).decode('utf-8')
+        except Exception as e:
+            logger.error(f"Error encoding page token: {e}")
+            return ""
+
+    def _decode_page_token(self, token: str) -> int:
+        """Decode page token to get offset"""
+        try:
+            # Handle legacy case where raw numbers might be passed
+            if token.isdigit():
+                logger.warning(f"Raw numeric page token received: {token}. This should be a base64-encoded token.")
+                return int(token)
+            
+            # Add padding if needed for base64 decoding
+            missing_padding = len(token) % 4
+            if missing_padding:
+                token += '=' * (4 - missing_padding)
+            
+            decoded = base64.b64decode(token.encode('utf-8')).decode('utf-8')
+            return int(decoded)
+        except Exception as e:
+            logger.error(f"Error decoding page token: {e}")
+            raise ValueError(f"Invalid page token: {token}. Page tokens should only be generated by the API.")
+
+    def _encode_sync_token(self, timestamp: datetime) -> str:
+        """Encode timestamp as a sync token"""
+        try:
+            # Use ISO format timestamp for sync token
+            token_data = timestamp.isoformat()
+            return base64.b64encode(token_data.encode('utf-8')).decode('utf-8')
+        except Exception as e:
+            logger.error(f"Error encoding sync token: {e}")
+            return ""
+
+    def _decode_sync_token(self, token: str) -> datetime:
+        """Decode sync token to get timestamp"""
+        try:
+            # Add padding if needed for base64 decoding
+            missing_padding = len(token) % 4
+            if missing_padding:
+                token += '=' * (4 - missing_padding)
+            
+            decoded = base64.b64decode(token.encode('utf-8')).decode('utf-8')
+            return datetime.fromisoformat(decoded)
+        except Exception as e:
+            logger.error(f"Error decoding sync token: {e}")
+            raise ValueError(f"Invalid sync token. Token may have expired or is malformed.")

server/database/managers/calendar_manager.py

@@ -0,0 +1,445 @@
+"""
+Calendar Manager - Database operations for calendar management using SQLAlchemy
+"""
+from datetime import datetime, timezone
+from sqlalchemy.orm import Session
+from database.models import Calendar, User
+from database.models.acl import ACLs, Scope
+from database.session_utils import get_session, init_database
+import json, uuid, logging
+from typing import Dict, List, Optional
+from fastapi import HTTPException, status
+
+logger = logging.getLogger(__name__)
+
+# Allowed conference solution types per Google Calendar API v3 spec
+ALLOWED_CONFERENCE_SOLUTION_TYPES = {
+    "eventHangout", "eventNamedHangout", "hangoutsMeet"
+}
+
+class CalendarManager:
+    """Manager for calendar database operations using SQLAlchemy"""
+    def __init__(self, database_id: str):
+        # Initialize database on first use
+        self.database_id = database_id
+        self.session = self.get_session()
+
+    def get_session(self):
+        from database.session_manager import CalendarSessionManager
+        return CalendarSessionManager().get_session(self.database_id)
+
+    def _has_acl_role(self, user_id: str, calendar: Calendar, allowed_roles: List[str]) -> bool:
+        user = self.session.query(User).filter(User.user_id == user_id).first()
+        if not user:
+            logger.warning(f"No user found with ID: {user_id}")
+            return False
+
+        acls = (
+            self.session.query(ACLs)
+            .join(Scope, ACLs.scope_id == Scope.id)
+            .filter(
+                ACLs.calendar_id == calendar.calendar_id,
+                Scope.type == "user",
+                Scope.value == user.email
+            )
+            .all()
+        )
+
+        if not acls:
+            logger.warning(f"No ACL found for user {user.email} on calendar {calendar.calendar_id}")
+            return False
+
+        for acl in acls:
+            if acl.role.value in allowed_roles:
+                return True
+
+        logger.warning(f"User {user.email} has ACLs but lacks required roles: {allowed_roles}")
+        return False
+
+    def create_calendar(self, user_id: str, calendar_data: dict):
+        """Create a new calendar"""
+        conf_types = calendar_data.get("conferenceProperties", {}).get("allowedConferenceSolutionTypes")
+        if conf_types:
+            for ctype in conf_types:
+                if ctype not in ALLOWED_CONFERENCE_SOLUTION_TYPES:
+                    raise ValueError(f"Invalid conference solution type: {ctype}")
+        # This endpoint strictly creates secondary calendars per Google Calendar API semantics.
+        # Do not auto-promote to primary here.
+        mapped_data = {
+            "calendar_id": str(uuid.uuid4()), # Generate unique calendar ID
+            "user_id": user_id,
+            "summary": calendar_data.get("summary"),
+            "description": calendar_data.get("description"),
+            "location": calendar_data.get("location"),
+            "time_zone": calendar_data.get("timeZone", "UTC"),
+            "conference_properties": json.dumps(calendar_data.get("conferenceProperties", {})),
+            "is_primary": False
+        }
+        # Create Calendar model instance
+        new_calendar = Calendar(**mapped_data)
+        self.session.add(new_calendar)
+        self.session.commit()
+        self.session.refresh(new_calendar)
+
+        # Automatically create ACL entry for the calendar owner
+        self._create_owner_acl(user_id, new_calendar.calendar_id)
+
+        # Return the created calendar
+        return new_calendar
+
+    def _create_owner_acl(self, user_id: str, calendar_id: str):
+        """Create ACL entries with owner and writer roles for the calendar creator"""
+        from database.models.acl import AclRole, ScopeType
+
+        # Get the user to access their email
+        user = self.session.query(User).filter(User.user_id == user_id).first()
+        if not user:
+            raise ValueError(f"User with ID {user_id} not found")
+
+        # Create or get the scope for this user
+        scope = self.session.query(Scope).filter(
+            Scope.type == ScopeType.user,
+            Scope.value == user.email
+        ).first()
+
+        if not scope:
+            scope = Scope(
+                id=str(uuid.uuid4()),
+                type=ScopeType.user,
+                value=user.email
+            )
+            self.session.add(scope)
+            self.session.flush()  # Flush to get the scope ID
+
+        # Create the owner ACL entry
+        owner_acl = ACLs(
+            id=str(uuid.uuid4()),
+            calendar_id=calendar_id,
+            user_id=user_id,
+            scope_id=scope.id,
+            role=AclRole.owner,
+            etag=f'"{uuid.uuid4()}"'
+        )
+
+        # Create the writer ACL entry
+        writer_acl = ACLs(
+            id=str(uuid.uuid4()),
+            calendar_id=calendar_id,
+            user_id=user_id,
+            scope_id=scope.id,
+            role=AclRole.writer,
+            etag=f'"{uuid.uuid4()}"'
+        )
+
+        self.session.add(owner_acl)
+        self.session.add(writer_acl)
+        self.session.commit()
+
+        logger.info(f"Created owner and writer ACL entries for user {user.email} on calendar {calendar_id}")
+
+    def get_calendar_by_id(self, user_id: str, calendar_id: str, allowed_roles: List[str] = None):
+        """Get a calendar by ID for a specific user"""
+        calendar = self.session.query(Calendar).filter(Calendar.calendar_id == calendar_id).first()
+        if not calendar:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Calendar with id '{calendar_id}' does not exist")
+        calendar = self.session.query(Calendar).filter(Calendar.calendar_id == calendar_id, Calendar.user_id == user_id).first()
+        if not calendar:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Calendar with id '{calendar_id}' does not exist for user {user_id}")
+        if allowed_roles and not self._has_acl_role(user_id, calendar, allowed_roles):
+            raise PermissionError(f"User '{user_id}' lacks required roles: {allowed_roles}")
+        return calendar
+
+
+    def update_calendar(self, user_id: str, calendar_id: str, update_data: dict):
+        """Update a calendar (cannot modify primary status)"""
+        calendar = self.session.query(Calendar).filter(Calendar.calendar_id == calendar_id).first()
+        if not calendar:
+            return None
+
+        # Prevent changing primary status via update
+        if "is_primary" in update_data:
+            raise ValueError("Cannot modify primary calendar status")
+
+        # Update fields
+        if "summary" in update_data:
+            calendar.summary = update_data["summary"]
+
+        if "description" in update_data:
+            calendar.description = update_data["description"]
+
+        if "location" in update_data:
+            calendar.location = update_data["location"]
+
+        if "timeZone" in update_data and update_data["timeZone"] is not None:
+            calendar.time_zone = update_data["timeZone"]
+
+        if "conferenceProperties" in update_data:
+            self._validate_conference_properties(update_data.get("conferenceProperties"))
+            calendar.conference_properties = (
+                json.dumps(update_data["conferenceProperties"])
+                if update_data["conferenceProperties"] else None
+            )
+
+        calendar.updated_at = datetime.now(timezone.utc)
+
+        self.session.commit()
+        self.session.refresh(calendar)
+        return calendar
+
+    def delete_calendar(self, user_id: str, calendar_id: str):
+        """Delete a calendar (cannot delete primary calendar)"""
+        calendar = self.session.query(Calendar).filter(Calendar.calendar_id == calendar_id).first()
+        if not calendar:
+            return False
+        if calendar.is_primary:
+            raise ValueError("Cannot delete primary calendar.")
+        if not self._has_acl_role(user_id, calendar, ["owner"]):
+            raise PermissionError("Only owners can delete the calendar")
+        self.session.delete(calendar)
+        self.session.commit()
+        return True
+
+    def clear_calendar(self, user_id: str, calendar_id: str):
+        """Clear all events from a calendar and return the number of events deleted"""
+        calendar = self.session.query(Calendar).filter(Calendar.calendar_id == calendar_id).first()
+        if not calendar:
+            return 0
+        if not self._has_acl_role(user_id, calendar, ["owner", "writer"]):
+            raise PermissionError("User does not have permission to clear this calendar")
+        if not calendar.is_primary:
+            raise ValueError("Can only clear primary calendars")
+        count = len(calendar.events)
+        for event in calendar.events:
+            self.session.delete(event)
+        self.session.commit()
+        return count
+
+    def list_calendars(self, user_id: str):
+        """List all calendars for a user"""
+        user = self.session.query(User).filter(User.user_id == user_id).first()
+        if not user:
+            return []
+        owned = self.session.query(Calendar).filter(Calendar.user_id == user_id)
+        shared = (
+            self.session.query(Calendar)
+            .join(ACLs, Calendar.calendar_id == ACLs.calendar_id)
+            .join(Scope, ACLs.scope_id == Scope.id)
+            .filter(Scope.type == "user", Scope.value == user.email)
+        )
+        return owned.union(shared).all()
+
+    def get_primary_calendar(self, user_id: str):
+        return self.session.query(Calendar).filter_by(user_id=user_id, is_primary=True).first()
+
+    def _format_calendar_response(self, calendar: Calendar) -> Dict:
+        """Format calendar model for API response"""
+        formatted = {
+            "kind": "calendar#calendar",
+            "etag": f"etag-{calendar.calendar_id}-{calendar.updated_at.isoformat() if calendar.updated_at else ''}",
+            "id": calendar.calendar_id,
+            "summary": calendar.summary,
+            "timeZone": calendar.time_zone
+        }
+
+        # Add optional fields if present
+        if calendar.description:
+            formatted["description"] = calendar.description
+
+        if calendar.location:
+            formatted["location"] = calendar.location
+        if calendar.conference_properties:
+            try:
+                formatted["conferenceProperties"] = json.loads(calendar.conference_properties)
+            except:
+                pass
+
+        return formatted
+
+    def ensure_primary_calendar_constraint(self, user_id: str) -> bool:
+        """Ensure user has exactly one primary calendar"""
+        session = get_session(self.database_id)
+        try:
+            # Get all primary calendars for user
+            primary_calendars = session.query(Calendar).filter(
+                Calendar.user_id == user_id,
+                Calendar.is_primary == True
+            ).all()
+
+            # Case 1: No primary calendar - make first calendar primary
+            if not primary_calendars:
+                first_calendar = session.query(Calendar).filter(
+                    Calendar.user_id == user_id
+                ).order_by(Calendar.created_at.asc()).first()
+
+                if first_calendar:
+                    first_calendar.is_primary = True
+                    session.commit()
+                    logger.info(f"Made calendar {first_calendar.calendar_id} primary for user {user_id}")
+                    return True
+                else:
+                    # User has no calendars - this is valid
+                    return True
+
+            # Case 2: Multiple primary calendars - keep oldest, make others secondary
+            elif len(primary_calendars) > 1:
+                # Sort by creation date, keep the oldest as primary
+                primary_calendars.sort(key=lambda c: c.created_at)
+                primary_calendar = primary_calendars[0]
+
+                # Make all others secondary
+                for calendar in primary_calendars[1:]:
+                    calendar.is_primary = False
+                    logger.warning(f"Made calendar {calendar.calendar_id} secondary for user {user_id}")
+
+                session.commit()
+                logger.info(f"Ensured single primary calendar {primary_calendar.calendar_id} for user {user_id}")
+                return True
+
+            # Case 3: Exactly one primary calendar - already correct
+            return True
+
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error ensuring primary calendar constraint for user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def _validate_conference_properties(self, conference_properties: Optional[Dict]) -> None:
+        """Validate conferenceProperties.allowedConferenceSolutionTypes values.
+
+        Raises ValueError if any provided value is not allowed per API spec.
+        """
+        if not conference_properties:
+            return
+        allowed_list = conference_properties.get("allowedConferenceSolutionTypes")
+        if allowed_list is None:
+            return
+        if not isinstance(allowed_list, list):
+            raise ValueError("conferenceProperties.allowedConferenceSolutionTypes must be a list if provided")
+        invalid = [item for item in allowed_list if item not in ALLOWED_CONFERENCE_SOLUTION_TYPES and item not in [None, ""]]
+        if invalid:
+            allowed_sorted = sorted(ALLOWED_CONFERENCE_SOLUTION_TYPES)
+            raise ValueError(
+                "Invalid values for conferenceProperties.allowedConferenceSolutionTypes: "
+                f"{invalid}. Allowed values are: {allowed_sorted}"
+            )
+
+    def validate_primary_calendar_integrity(self, user_id: str) -> Dict[str, any]:
+        """Validate primary calendar integrity for a user"""
+        session = get_session(self.database_id)
+        try:
+            primary_calendars = session.query(Calendar).filter(
+                Calendar.user_id == user_id,
+                Calendar.is_primary == True
+            ).all()
+
+            total_calendars = session.query(Calendar).filter(
+                Calendar.user_id == user_id
+            ).count()
+
+            result = {
+                "user_id": user_id,
+                "total_calendars": total_calendars,
+                "primary_calendars_count": len(primary_calendars),
+                "is_valid": len(primary_calendars) == 1 if total_calendars > 0 else True,
+                "primary_calendar_ids": [c.calendar_id for c in primary_calendars]
+            }
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Error validating primary calendar integrity for user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def _ensure_user_has_primary_calendar(self, user_id: str, session: Session = None) -> None:
+        """Private method to ensure user has exactly one primary calendar
+
+        This enforces the business rule: If user has calendars, exactly one must be primary
+        """
+        close_session = session is None
+        if session is None:
+            session = get_session(self.database_id)
+
+        try:
+            # Get all calendars for user
+            all_calendars = session.query(Calendar).filter(
+                Calendar.user_id == user_id
+            ).order_by(Calendar.created_at.asc()).all()
+
+            if not all_calendars:
+                # User has no calendars - nothing to enforce
+                return
+
+            # Get primary calendars
+            primary_calendars = [c for c in all_calendars if c.is_primary]
+
+            if len(primary_calendars) == 0:
+                # No primary calendar - make the oldest one primary
+                oldest_calendar = all_calendars[0]
+                oldest_calendar.is_primary = True
+                logger.info(f"Made calendar {oldest_calendar.calendar_id} primary for user {user_id} (no primary existed)")
+
+            elif len(primary_calendars) > 1:
+                # Multiple primary calendars - keep oldest, make others secondary
+                primary_calendars.sort(key=lambda c: c.created_at)
+                primary_calendar = primary_calendars[0]
+
+                for calendar in primary_calendars[1:]:
+                    calendar.is_primary = False
+                    logger.warning(f"Made calendar {calendar.calendar_id} secondary for user {user_id} (multiple primaries existed)")
+
+                logger.info(f"Kept calendar {primary_calendar.calendar_id} as primary for user {user_id}")
+
+            # If exactly one primary exists, no action needed
+
+        except Exception as e:
+            logger.error(f"Error ensuring primary calendar for user {user_id}: {e}")
+            raise
+        finally:
+            if close_session:
+                session.close()
+
+    def enforce_primary_calendar_constraint_for_all_users(self) -> Dict[str, int]:
+        """Enforce primary calendar constraint for all users in the database
+
+        Returns:
+            Dict with statistics about fixes applied
+        """
+        session = get_session(self.database_id)
+        try:
+            # Get all unique user IDs
+            user_ids = session.query(Calendar.user_id).distinct().all()
+            user_ids = [uid[0] for uid in user_ids]
+
+            stats = {
+                "users_processed": 0,
+                "users_fixed": 0,
+                "calendars_made_primary": 0,
+                "calendars_made_secondary": 0
+            }
+
+            for user_id in user_ids:
+                stats["users_processed"] += 1
+
+                # Check if user needs fixing
+                validation_result = self.validate_primary_calendar_integrity(user_id)
+
+                if not validation_result["is_valid"]:
+                    stats["users_fixed"] += 1
+                    logger.info(f"Fixing primary calendar constraint for user {user_id}")
+
+                    # Fix the constraint
+                    self._ensure_user_has_primary_calendar(user_id, session)
+
+            session.commit()
+            return stats
+
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error enforcing primary calendar constraints: {e}")
+            raise
+        finally:
+            session.close()

server/database/managers/color_manager.py

@@ -0,0 +1,224 @@
+"""
+Color database manager with Google Calendar API v3 compatible operations
+Handles color definitions for calendars and events
+"""
+
+import logging
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+from sqlalchemy import and_, func
+
+from database.session_utils import get_session, init_database
+from database.models.color import Color, ColorType
+
+logger = logging.getLogger(__name__)
+
+
+class ColorManager:
+    """Color manager for database operations"""
+    
+    def __init__(self, database_id: str):
+        self.database_id = database_id
+        # Initialize database on first use
+        init_database(database_id)
+    
+    
+    def get_colors_response(self) -> Dict[str, Any]:
+        """
+        Get the complete colors response in Google Calendar API v3 format
+        
+        Returns:
+            Dict containing calendar and event colors with metadata
+        """
+        session = get_session(self.database_id)
+        try:
+                # Get all colors from database
+                colors = session.query(Color).all()
+                
+                # Get last updated timestamp
+                last_updated = session.query(func.max(Color.updated_at)).scalar()
+                if not last_updated:
+                    last_updated = datetime.now(timezone.utc)
+                
+                # Organize colors by type
+                calendar_colors = {}
+                event_colors = {}
+                
+                for color in colors:
+                    color_dict = color.to_dict()
+                    if color.color_type == ColorType.CALENDAR:
+                        calendar_colors[color.color_id] = color_dict
+                    elif color.color_type == ColorType.EVENT:
+                        event_colors[color.color_id] = color_dict
+                
+                return {
+                    "kind": "calendar#colors",
+                    "updated": last_updated.isoformat().replace('+00:00', '.000Z'),
+                    "calendar": calendar_colors,
+                    "event": event_colors
+                }
+                
+        except Exception as e:
+            logger.error(f"Error getting colors response: {e}")
+            raise
+        finally:
+            session.close()
+    
+    def get_color_by_id(self, color_type: str, color_id: str) -> Optional[Dict[str, str]]:
+        """
+        Get a specific color by type and ID
+        
+        Args:
+            color_type: Either 'calendar' or 'event'
+            color_id: The color ID (e.g., '1', '2', etc.)
+            
+        Returns:
+            Dict containing background and foreground colors, or None if not found
+        """
+        session = get_session(self.database_id)
+        try:
+                # Convert string type to enum
+                if color_type == "calendar":
+                    type_enum = ColorType.CALENDAR
+                elif color_type == "event":
+                    type_enum = ColorType.EVENT
+                else:
+                    return None
+                
+                color = session.query(Color).filter(
+                    and_(
+                        Color.color_type == type_enum,
+                        Color.color_id == color_id
+                    )
+                ).first()
+                
+                if color:
+                    return color.to_dict()
+                return None
+                
+        except Exception as e:
+            logger.error(f"Error getting color {color_type}:{color_id}: {e}")
+            return None
+        finally:
+            session.close()
+    
+    def validate_color_id(self, color_type: str, color_id: str) -> bool:
+        """
+        Validate if a color ID exists for the given type
+        
+        Args:
+            color_type: Either 'calendar' or 'event'
+            color_id: The color ID to validate
+            
+        Returns:
+            True if color ID exists, False otherwise
+        """
+        return self.get_color_by_id(color_type, color_id) is not None
+    
+    def get_all_colors_by_type(self, color_type: str) -> Dict[str, Dict[str, str]]:
+        """
+        Get all colors of a specific type
+        
+        Args:
+            color_type: Either 'calendar' or 'event'
+            
+        Returns:
+            Dict mapping color IDs to their color definitions
+        """
+        session = get_session(self.database_id)
+        try:
+                # Convert string type to enum
+                if color_type == "calendar":
+                    type_enum = ColorType.CALENDAR
+                elif color_type == "event":
+                    type_enum = ColorType.EVENT
+                else:
+                    return {}
+                
+                colors = session.query(Color).filter(Color.color_type == type_enum).all()
+                
+                result = {}
+                for color in colors:
+                    result[color.color_id] = color.to_dict()
+                
+                return result
+                
+        except Exception as e:
+            logger.error(f"Error getting all colors for type {color_type}: {e}")
+            return {}
+        finally:
+            session.close()
+    
+    def load_sample_colors(self, color_data: List[Dict[str, Any]]) -> int:
+        """
+        Load sample color data into the database
+        
+        Args:
+            color_data: List of color dictionaries with color_id, color_type, background, foreground
+            
+        Returns:
+            Number of colors loaded
+        """
+        session = get_session(self.database_id)
+        try:
+                loaded_count = 0
+                
+                for color_info in color_data:
+                    # Check if color already exists
+                    existing = session.query(Color).filter(
+                        and_(
+                            Color.color_id == color_info["color_id"],
+                            Color.color_type == ColorType(color_info["color_type"])
+                        )
+                    ).first()
+                    
+                    if not existing:
+                        # Create new color
+                        color = Color(
+                            color_id=color_info["color_id"],
+                            color_type=ColorType(color_info["color_type"]),
+                            background=color_info["background"],
+                            foreground=color_info["foreground"]
+                        )
+                        session.add(color)
+                        loaded_count += 1
+                    else:
+                        # Update existing color
+                        existing.background = color_info["background"]
+                        existing.foreground = color_info["foreground"]
+                        existing.updated_at = datetime.now(timezone.utc)
+                        loaded_count += 1
+                
+                session.commit()
+                logger.info(f"Loaded {loaded_count} colors into database")
+                return loaded_count
+                
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error loading sample colors: {e}")
+            raise
+        finally:
+            session.close()
+    
+    def clear_all_colors(self) -> int:
+        """
+        Clear all colors from the database
+        
+        Returns:
+            Number of colors deleted
+        """
+        session = get_session(self.database_id)
+        try:
+                count = session.query(Color).count()
+                session.query(Color).delete()
+                session.commit()
+                
+                logger.info(f"Cleared {count} colors from database")
+                return count
+                
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error clearing colors: {e}")
+            raise
+        finally:
+            session.close()

server/database/managers/freebusy_manager.py

@@ -0,0 +1,249 @@
+"""
+FreeBusy database manager with Google Calendar API v3 compatible operations
+Handles FreeBusy query operations with database-per-user architecture
+"""
+
+import logging
+from typing import List, Optional, Dict, Any
+from datetime import datetime, timezone
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy import and_, or_, desc, asc
+from dateutil import parser
+
+from database.session_utils import get_session, init_database
+from database.models.event import Event
+from database.models.calendar import Calendar
+from database.models.user import User
+from schemas.freebusy import (
+    FreeBusyQueryRequest,
+    FreeBusyQueryResponse,
+    FreeBusyCalendarResult as FreeBusyCalendarResultSchema,
+    FreeBusyError,
+    TimePeriod,
+    FreeBusyQueryValidation,
+    FreeBusyEventOverlap
+)
+
+logger = logging.getLogger(__name__)
+
+
+class FreeBusyManager:
+    """FreeBusy manager for database operations"""
+    
+    def __init__(self, database_id: str):
+        self.database_id = database_id
+        # Initialize database on first use
+        init_database(database_id)
+    
+    def _parse_datetime_string(self, datetime_str: str) -> datetime:
+        """Parse ISO datetime string to datetime object"""
+        try:
+            return parser.isoparse(datetime_str.replace('Z', '+00:00'))  
+        except Exception as e:
+            logger.error(f"Error parsing datetime string {datetime_str}: {e}")
+            raise ValueError(f"Invalid datetime format: {datetime_str}")
+    
+    def _validate_query_request(self, request: FreeBusyQueryRequest, user_id: str) -> FreeBusyQueryValidation:
+        """Validate FreeBusy query request"""
+        time_min = self._parse_datetime_string(request.timeMin)
+        time_max = self._parse_datetime_string(request.timeMax)
+        calendar_ids = [item.id for item in request.items]
+        
+        validation = FreeBusyQueryValidation(
+            time_min=time_min,
+            time_max=time_max,
+            calendar_ids=calendar_ids,
+            user_id=user_id
+        )
+        
+        if not validation.validate_time_range():
+            raise ValueError("Time range is invalid or too large (max 366 days)")
+        
+        if not validation.validate_calendar_count():
+            raise ValueError("Too many calendars requested (max 50)")
+        
+        # Validate that all calendar IDs exist in the database
+        self._validate_calendar_ids_exist(calendar_ids, user_id)
+        
+        return validation
+    
+    def _validate_calendar_ids_exist(self, calendar_ids: List[str], user_id: str) -> None:
+        """Validate that all calendar IDs exist in the database for the user"""
+        session = get_session(self.database_id)
+        try:
+            for calendar_id in calendar_ids:
+                calendar = session.query(Calendar).filter(
+                    Calendar.calendar_id == calendar_id,
+                    Calendar.user_id == user_id
+                ).first()
+                
+                if not calendar:
+                    raise ValueError(f"Calendar with ID '{calendar_id}' does not exist or is not accessible")
+                    
+        finally:
+            session.close()
+    
+    def _get_busy_periods_for_calendar(
+        self, 
+        session, 
+        calendar_id: str, 
+        user_id: str, 
+        time_min: datetime, 
+        time_max: datetime
+    ) -> List[TimePeriod]:
+        """Get busy periods for a specific calendar"""
+        try:
+            # Verify calendar belongs to user
+            calendar = session.query(Calendar).filter(
+                Calendar.calendar_id == calendar_id,
+                Calendar.user_id == user_id
+            ).first()
+            
+            if not calendar:
+                # This should not happen if validation passed, but handle gracefully
+                logger.error(f"Calendar {calendar_id} not found for user {user_id} during query execution")
+                raise ValueError(f"Calendar with ID '{calendar_id}' does not exist or is not accessible")
+            
+            # Query events that overlap with the time range
+            events = session.query(Event).filter(
+                and_(
+                    Event.calendar_id == calendar_id,
+                    Event.user_id == user_id,
+                    Event.status == "confirmed",  # Only confirmed events block time
+                    # Event overlaps with query range
+                    Event.start_datetime < time_max,
+                    Event.end_datetime > time_min
+                )
+            ).all()
+            
+            busy_periods = []
+            for event in events:
+                # Check if event is transparent (doesn't block time)
+                if hasattr(event, 'transparency') and event.transparency == "transparent":
+                    continue
+                
+                # Create overlap object for validation
+                overlap = FreeBusyEventOverlap(
+                    event_id=event.event_id,
+                    start=event.start_datetime,
+                    end=event.end_datetime,
+                    transparency=getattr(event, 'transparency', 'opaque')
+                )
+                
+                if overlap.is_busy():
+                    # Clip event times to query range
+                    period_start = max(event.start_datetime, time_min)
+                    period_end = min(event.end_datetime, time_max)
+                    
+                    busy_periods.append(TimePeriod(
+                        start=period_start.isoformat(),
+                        end=period_end.isoformat()
+                    ))
+            
+            # Merge overlapping periods
+            busy_periods = self._merge_overlapping_periods(busy_periods)
+            
+            return busy_periods
+            
+        except Exception as e:
+            logger.error(f"Error getting busy periods for calendar {calendar_id}: {e}")
+            raise
+    
+    def _merge_overlapping_periods(self, periods: List[TimePeriod]) -> List[TimePeriod]:
+        """Merge overlapping time periods"""
+        if not periods:
+            return []
+        
+        # Sort periods by start time
+        sorted_periods = sorted(periods, key=lambda p: p.start)
+        
+        merged = [sorted_periods[0]]
+        
+        for current in sorted_periods[1:]:
+            last_merged = merged[-1]
+            
+            # Parse times for comparison
+            current_start = self._parse_datetime_string(current.start)
+            current_end = self._parse_datetime_string(current.end)
+            last_end = self._parse_datetime_string(last_merged.end)
+            
+            # If current period overlaps with last merged period
+            if current_start <= last_end:
+                # Extend the last merged period if necessary
+                if current_end > last_end:
+                    merged[-1] = TimePeriod(
+                        start=last_merged.start,
+                        end=current.end
+                    )
+            else:
+                # No overlap, add as new period
+                merged.append(current)
+        
+        return merged
+    
+    def query_freebusy(
+        self, 
+        user_id: str, 
+        request: FreeBusyQueryRequest
+    ) -> FreeBusyQueryResponse:
+        """
+        Query free/busy information for calendars
+        
+        POST /freeBusy
+        """
+        session = get_session(self.database_id)
+        try:
+            # Validate request
+            validation = self._validate_query_request(request, user_id)
+            
+            # Process each calendar
+            calendar_results = {}
+            
+            for calendar_item in request.items:
+                calendar_id = calendar_item.id
+                
+                try:
+                    # Get busy periods for this calendar
+                    busy_periods = self._get_busy_periods_for_calendar(
+                        session, 
+                        calendar_id, 
+                        user_id, 
+                        validation.time_min, 
+                        validation.time_max
+                    )
+                    
+                    
+                    # Add to response
+                    calendar_results[calendar_id] = FreeBusyCalendarResultSchema(
+                        busy=busy_periods
+                    )
+                    
+                except Exception as e:
+                    logger.error(f"Error processing calendar {calendar_id}: {e}")
+                    
+                    # Add error to response
+                    calendar_results[calendar_id] = FreeBusyCalendarResultSchema(
+                        errors=[FreeBusyError(
+                            domain="calendar",
+                            reason="backendError"
+                        )]
+                    )
+            
+            
+            response = FreeBusyQueryResponse(
+                timeMin=request.timeMin,
+                timeMax=request.timeMax,
+                calendars=calendar_results
+            )
+            
+            logger.info(f"Processed FreeBusy query for user {user_id}")
+            return response
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error processing FreeBusy query for user {user_id}: {e}")
+            raise ValueError(f"Error processing FreeBusy query for user {user_id}: {e}")
+        finally:
+            session.close()
+    
+  

server/database/managers/settings_manager.py

@@ -0,0 +1,134 @@
+"""
+Setting Manager - Database operations for settings management using SQLAlchemy
+"""
+
+import logging
+from typing import Optional, List, Dict
+from datetime import datetime, timedelta
+from database.models.settings import Settings
+from database.models.watch_channel import WatchChannel
+from database.session_utils import get_session, init_database
+from schemas.settings import SettingItem, SettingsWatchRequest, Channel
+import uuid
+import json
+
+logger = logging.getLogger(__name__)
+
+
+class SettingManager:
+    """Manager for settings database operations using SQLAlchemy"""
+
+    def __init__(self, database_id: str):
+        self.database_id = database_id
+        init_database(database_id)
+
+    def list_settings(self, user_id: str) -> list[SettingItem]:
+        """List all settings"""
+        session = get_session(self.database_id)
+        try:
+            settings = (
+                session.query(Settings)
+                .filter(Settings.user_id == user_id)
+                .all()
+            )
+            return [SettingItem.model_validate(s) for s in settings]
+        except Exception as e:
+            logger.error(f"Error listing settings for user '{user_id}': {e}")
+            raise
+        finally:
+            session.close()
+
+    def get_setting_by_id(self, setting_id: str, user_id: str) -> Optional[Dict]:
+        """Get a setting by its ID"""
+        session = get_session(self.database_id)
+        try:
+            setting = session.query(Settings).filter(
+                Settings.id == setting_id,
+                Settings.user_id == user_id
+            ).first()
+            if setting:
+                return self._format_setting(setting)
+            return None
+        except Exception as e:
+            logger.error(f"Error retrieving setting '{setting_id}' for user '{user_id}': {e}")
+            raise
+        finally:
+            session.close()
+
+    def _format_setting(self, setting: Settings) -> Dict:
+        """Format a setting for API response"""
+        return {
+            "kind": "calendar#setting",
+            "etag": setting.etag,
+            "id": setting.id,
+            "value": setting.value,
+            "user_id": setting.user_id
+        }
+
+    def watch_settings(self, watch_request: SettingsWatchRequest, user_id: str) -> Channel:
+        """
+        Set up a watch channel for settings changes
+        
+        Args:
+            watch_request: The watch request parameters
+            user_id: The user setting up the watch
+            
+        Returns:
+            Channel: The created watch channel
+        """
+        session = get_session(self.database_id)
+        try:
+            # Generate unique resource ID for settings watch
+            resource_id = f"settings-{user_id}-{uuid.uuid4().hex[:8]}"
+            resource_uri = f"/calendars/{user_id}/settings"
+            
+            # Calculate expiration time (max 24 hours from now if not specified)
+            now = datetime.utcnow()
+            expires_at = now + timedelta(hours=24)
+
+            if session.query(WatchChannel).filter(WatchChannel.id == watch_request.id).first():
+                raise ValueError(f"Channel with Id {watch_request.id} already exists")
+            
+            # Create watch channel record
+            watch_channel = WatchChannel(
+                id=watch_request.id,
+                resource_id=resource_id,
+                resource_uri=resource_uri,
+                resource_type="settings",
+                calendar_id="",
+                user_id=user_id,
+                webhook_address=watch_request.address,
+                webhook_token=watch_request.token,
+                webhook_type=watch_request.type,
+                params=json.dumps(watch_request.params.model_dump()) if watch_request.params else None,
+                created_at=now,
+                expires_at=expires_at,
+                is_active="true",
+                notification_count=0
+            )
+            
+            # Save to database
+            session.add(watch_channel)
+            session.commit()
+            
+            logger.info(f"Created settings watch channel {watch_request.id} for user {user_id}")
+            
+            # Return channel response
+            return Channel(
+                kind="api#channel",
+                id=watch_channel.id,
+                resourceId=resource_id,
+                resourceUri=resource_uri,
+                token=watch_channel.webhook_token,
+                expiration=expires_at.isoformat() + "Z" if expires_at else None
+
+            )
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error creating settings watch channel: {e}")
+            raise
+        finally:
+            session.close()
+
+

server/database/managers/user_manager.py

@@ -0,0 +1,281 @@
+"""
+User Manager - Database operations for user management using SQLAlchemy
+"""
+
+import logging
+import uuid
+from typing import Dict, List, Optional
+from datetime import datetime, timezone
+from sqlalchemy.orm import Session
+from database.models import User
+from database.session_utils import get_session, init_database
+
+logger = logging.getLogger(__name__)
+
+
+class UserManager:
+    """Manager for user database operations using SQLAlchemy"""
+
+    def __init__(self, database_id: str):
+        self.database_id = database_id
+        # Initialize database on first use
+        init_database(database_id)
+
+
+    def create_user(self, user_data: Dict) -> Dict:
+        """Create a new user"""
+        session = get_session(self.database_id)
+        try:
+            # Generate unique user ID if not provided
+            user_id = user_data.get("user_id") or str(uuid.uuid4())
+            
+            # Check if user with email already exists
+            existing_user = session.query(User).filter(User.email == user_data["email"]).first()
+            if existing_user:
+                raise ValueError(f"User with email {user_data['email']} already exists")
+            
+            # Create User model instance
+            user = User(
+                user_id=user_id,
+                email=user_data["email"],
+                name=user_data["name"],
+                given_name=user_data.get("given_name"),
+                family_name=user_data.get("family_name"),
+                picture=user_data.get("picture"),
+                locale=user_data.get("locale", "en"),
+                timezone=user_data.get("timezone", "UTC"),
+                is_active=user_data.get("is_active", True),
+                is_verified=user_data.get("is_verified", False),
+                provider=user_data.get("provider"),
+                provider_id=user_data.get("provider_id"),
+                access_token_hash=user_data.get("access_token_hash"),
+                refresh_token_hash=user_data.get("refresh_token_hash")
+            )
+            
+            session.add(user)
+            session.commit()
+            
+            # Return the created user
+            result = self._format_user_response(user)
+            return result
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error creating user: {e}")
+            raise
+        finally:
+            session.close()
+
+    def get_user_by_id(self, user_id: str) -> Optional[Dict]:
+        """Get a user by ID"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            
+            if not user:
+                return None
+                
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            logger.error(f"Error getting user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def get_first_user_from_db(self) -> Optional[Dict]:
+        """Get the first user from db"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).first()
+            if not user:
+                return None
+            
+            return self._format_user_response(user)
+        except Exception as e:
+            logger.error(f"Error getting user from db: {e}")
+            raise
+        finally:
+            session.close()
+        
+    def get_user_by_access_token(self, static_token: str) -> Optional[Dict]:
+        """Get a user by access token"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.static_token == static_token).first()
+            
+            if not user:
+                return None
+                
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            logger.error(f"Error getting user by access token {static_token}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def get_user_by_email(self, email: str) -> Optional[Dict]:
+        """Get a user by email"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.email == email).first()
+            
+            if not user:
+                return None
+                
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            logger.error(f"Error getting user by email {email}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def update_user(self, user_id: str, user_data: Dict) -> Optional[Dict]:
+        """Update a user"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            
+            if not user:
+                return None
+            
+            # Update fields if provided
+            updateable_fields = [
+                "name", "given_name", "family_name", "picture", "locale", 
+                "timezone", "is_active", "is_verified", "provider", "provider_id",
+                "access_token_hash", "refresh_token_hash"
+            ]
+            
+            for field in updateable_fields:
+                if field in user_data:
+                    setattr(user, field, user_data[field])
+            
+            # Update last login if provided
+            if user_data.get("update_last_login"):
+                user.last_login_at = datetime.now(timezone.utc)
+            
+            # SQLAlchemy will automatically update updated_at due to onupdate=datetime.utcnow
+            session.commit()
+            
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error updating user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def delete_user(self, user_id: str) -> bool:
+        """Delete a user and all related data"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            
+            if not user:
+                return False
+            
+            # Delete user (cascade will delete related calendars and events)
+            session.delete(user)
+            session.commit()
+            return True
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error deleting user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def deactivate_user(self, user_id: str) -> Optional[Dict]:
+        """Deactivate a user (soft delete)"""
+        session = get_session(self.database_id)
+        try:
+            user = session.query(User).filter(User.user_id == user_id).first()
+            
+            if not user:
+                return None
+            
+            user.is_active = False
+            session.commit()
+            
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            session.rollback()
+            logger.error(f"Error deactivating user {user_id}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def list_users(self, limit: int = 100, offset: int = 0, active_only: bool = True) -> List[Dict]:
+        """List users"""
+        session = get_session(self.database_id)
+        try:
+            query = session.query(User)
+            
+            if active_only:
+                query = query.filter(User.is_active == True)
+            
+            users = query.order_by(User.created_at.desc()).offset(offset).limit(limit).all()
+            
+            return [self._format_user_response(user) for user in users]
+            
+        except Exception as e:
+            logger.error(f"Error listing users: {e}")
+            raise
+        finally:
+            session.close()
+
+    def authenticate_user(self, email: str, provider: str = None, provider_id: str = None) -> Optional[Dict]:
+        """Authenticate user by email and optionally by provider"""
+        session = get_session(self.database_id)
+        try:
+            query = session.query(User).filter(
+                User.email == email,
+                User.is_active == True
+            )
+            
+            if provider:
+                query = query.filter(User.provider == provider)
+            
+            if provider_id:
+                query = query.filter(User.provider_id == provider_id)
+            
+            user = query.first()
+            
+            if not user:
+                return None
+            
+            # Update last login
+            user.last_login_at = datetime.now(timezone.utc)
+            session.commit()
+            
+            return self._format_user_response(user)
+            
+        except Exception as e:
+            logger.error(f"Error authenticating user {email}: {e}")
+            raise
+        finally:
+            session.close()
+
+    def _format_user_response(self, user: User) -> Dict:
+        """Format user model for API response (without sensitive data)"""
+        return {
+            "id": user.user_id,
+            "email": user.email,
+            "name": user.name,
+            "given_name": user.given_name,
+            "family_name": user.family_name,
+            "picture": user.picture,
+            "locale": user.locale,
+            "timezone": user.timezone,
+            "is_active": user.is_active,
+            "is_verified": user.is_verified,
+            "provider": user.provider,
+            "created_at": user.created_at.isoformat() if user.created_at else None,
+            "updated_at": user.updated_at.isoformat() if user.updated_at else None,
+            "last_login_at": user.last_login_at.isoformat() if user.last_login_at else None
+        }

server/database/models/__init__.py

@@ -0,0 +1,27 @@
+"""
+Database models package
+"""
+
+from .base import Base
+from .user import User
+from .calendar import Calendar
+from .event import Event, Attendees, Attachment, WorkingLocationProperties
+from .color import Color
+from .settings import Settings
+from .acl import ACLs, Scope
+from .watch_channel import WatchChannel
+
+__all__ = [
+    "Base",
+    "User",
+    "Calendar",
+    "Event",
+    "Attendees",
+    "Attachment",
+    "WorkingLocationProperties",
+    "Color",
+    "Settings",
+    "ACLs",
+    "Scope",
+    "WatchChannel"
+]