Update Event Schema and Collection for Multi-Calendar & Multi-Provider Support

[victor-enogwe]

Description

Update the event schema and collection to fully support multi-calendar and multi-provider scenarios in Compass. This is a deeper migration than simply adding a calendarId field; it involves modernizing the schema for extensibility, robust validation, and easier future migration.

This work will override the previous migration plan described in issue #735. Instead of just adding the calendar field at this point, we need to update the schema to for full support of a multi-provider scenario, so that:

• we have a migration for the event schema
• we have database validation for this schema
• future changes/migrations for this schema and changes to the API involving this schema will be less painful and more manageable.

Scope

• Replace the old event schema with a new schema that:
  • References the parent calendar with an ObjectId (calendar field)
  • Is designed for multi-provider support, with metadata for Google and Compass events
  • Provides more explicit typing for all fields (dates, priorities, etc.)
  • Supports robust recurrence rules and provider-specific event metadata
• Implement a migration script to transform all existing events to the new schema, ensuring data integrity (e.g., mapping legacy Google fields into the metadata array, and legacy calendar references to the new calendar ObjectId)
• Introduce database-level validation for the new schema using MongoDB validation and/or Zod
• Update all event-related API endpoints and backend services to use the new schema, including event creation, updates, and querying
• Refactor frontend event forms, retrieval, and state management to match the new schema (where applicable)
• Add and update all relevant tests for migration, validation, and event CRUD
• Document the migration and schema changes for future maintainers

Acceptance criteria

• Old event schema is replaced by the new event schema in the database and codebase
• All events reference a valid calendar (ObjectId) and store provider metadata as required
• Migration script is complete and verified against real data with no data loss
• Database validation rules are enforced for the new event schema
• All APIs and queries are updated for the new schema
• Frontend supports the new schema for all event CRUD and queries
• All tests for event CRUD, migration, and validation pass
• Documentation is updated with new schema and migration steps

Business use case

A robust, future-proof event schema will enable Compass to support multi-calendar, multi-provider scenarios, streamline future migrations, and unlock advanced features for all users and organizations relying on complex calendar integrations.

Additional context

• This issue replaces and supersedes Migrate event schema to reference calendar collection _id field.
• See EPIC: Add support for Google sub-calendars
• Reference schema changes above and in technical docs
• Backend: packages/backend/src/event/, packages/core/src/types/
• Scripts: packages/scripts/
• Docs: Compass Docs

Old Schema

export interface Schema_Event {
  _id?: string;
  allDayOrder?: number;
  description?: string | null | undefined;
  endDate?: string;
  isAllDay?: boolean;
  isSomeday?: boolean;
  gEventId?: string;
  gRecurringEventId?: string;
  order?: number;
  origin?: Origin;
  priority?: Priority;
  recurrence?: {
    rule?: string[];
    eventId?: string;
  };
  startDate?: string;
  title?: string;
  updatedAt?: Date | string;
  user?: string;
}

New Schema

interface Schema_Event_New {
  _id: ObjectId;
  calendar: ObjectId;
  title: string;
  description: string;
  order: number;
  isSomeday: boolean;
  startDate: Date;
  endDate: Date;
  origin: Origin;
  priority: Priorities;
  createdAt: Date;
  metadata: 
    | {
        gEventId: string;
      }
    | {
        gRecurringEventId: string;
        gEventId: string;
      };
  updatedAt?: Date | null | undefined;
  recurrence?: Array<
    | { rule: string[] }
    | {
        eventId: ObjectId;
        rule: string[];
      }
    | null
  >;
}