Add watch collection for Google Calendar push notification channel data

[Copilot]

Overview

This PR introduces a new watch collection to store Google Calendar push notification channel metadata separately from sync data. This separation improves query performance and reduces the risk of errors during watch operations by isolating channel lifecycle management from sync token operations.

What Changed

New Watch Collection Schema

Added a dedicated watch collection with the following schema:

interface WatchSchema {
  _id: string        // channelId - unique identifier for the notification channel
  userId: string     // user who owns this watch channel  
  resourceId: string // Google Calendar resource identifier
  expiration: Date   // when the channel expires
  createdAt: Date    // when this watch was created
}

Database Integration

• Collections: Added WATCH collection constant with dev/prod environment support
• MongoService: Integrated watch collection with proper TypeScript types and collection getter
• Indexes: Optimized indexes for performance:
  • userId index for efficient user-based queries
  • userId + expiration compound index for cleanup operations

Migrations

Collection Creation (2025.10.13T14.18.20.watch-collection.ts)

Creates the watch collection with MongoDB schema validation and indexes.

Data Migration (2025.10.13T14.22.21.migrate-events-watch-data.ts)

Non-destructive migration that copies existing events watch data from the sync collection to the new watch collection. The migration:

• Preserves all original sync data unchanged
• Handles invalid expiration dates gracefully
• Skips incomplete or malformed watch data
• Manages duplicate channel IDs safely
• Converts Google Calendar expiration timestamps to proper Date objects
• Provides comprehensive logging and error reporting

Technical Details

Before

Watch channel data was embedded within sync documents:

// In sync collection
{
  user: "userId",
  google: {
    events: [{
      channelId: "channel-123",
      resourceId: "resource-456", 
      expiration: "1234567890000", // timestamp string
      // ... other sync fields
    }]
  }
}

After

Watch channel data has its own dedicated collection:

// In watch collection  
{
  _id: "channel-123",           // channelId
  userId: "userId",
  resourceId: "resource-456",
  expiration: new Date(1234567890000),
  createdAt: new Date()
}

Benefits

• Improved Performance: Dedicated indexes enable faster watch-specific queries
• Reduced Complexity: Watch operations no longer interfere with sync token management
• Better Reliability: Isolated watch data reduces chances for sync-related errors
• Enhanced Scalability: Separate collection scales independently for multi-calendar setups

Testing

Comprehensive test coverage includes:

• Watch schema validation (11 test cases)
• Collection creation migration (8 test cases)
• Data migration scenarios (8 test cases)
• Error handling for edge cases (invalid dates, duplicates, incomplete data)

All existing tests continue to pass, confirming backward compatibility.

Migration Safety

Both migrations are designed for safe production deployment:

• Non-destructive: Original sync data remains completely unchanged
• Idempotent: Can be run multiple times safely
• Error tolerant: Gracefully handles duplicate and invalid data
• Comprehensive logging: Provides visibility into migration progress and issues

The migrations will be executed in a separate deployment as noted in the issue requirements.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add a new watch collection to save Google calendarList and events push notifications channel data.</issue_title>
<issue_description>### Priority

High (would significantly improve my experience)

Feature Description

The Compass backend will introduce a new database collectionwatch to store Google Calendar push notification Channel objects created for calendars lists and events. The collection will persist channel metadata channel_id, resource_id, expiration, user identifying metadata user along with creation timestamp.

We currently store this watch data alongside the sync data, a secondary technical reason to make this change to to perform watch queries and updates seprately from sync queries, reducing chances for errors during these o
perations.

Scope

• Create a new zod watch data schema
• Create watch types from zod schema
• Add mongoService watch collection.
• Add a new migration to create the watch collection
• Add a new non-destructive migration to copy over existing calendarlist watch data to the new watch collection
• Add a new non-destructive migration to copy over existing events watch data to the new watch collection

Use Case

Compass relies on Google Calendar push notifications to keep calendar and event's data in sync with real-time changes. Persisting watch channel data enables reliable lifecycle management of channels (creation, renewal, expiration, deletion), supports multi-calendar setups, and reduces the risk of missed notifications. This leads to fresher event/task data for users and improves the overall reliability and resilience of the notification pipeline.

Additional Context

// watch collection schema
interface WatchSchema {
   _id: string // mongo uuid - represents the channel id - channel needs to be unique
  userId: string
  resourceId: string
  expiration: Date
  createdAt: string
}

Indexes:

• on _id - channelId -unique in mongo
• on userId - will enable us to speed up finding watches by user

The relevant migrations in this story will be run in a later story in production.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1100

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

Pull Request Overview

This PR introduces a dedicated watch collection for storing Google Calendar push notification channel data, separating it from existing sync data to improve performance and reduce operational complexity.

Key changes include:

• New watch collection schema with TypeScript types and MongoDB validation
• Database migrations for collection creation and non-destructive data migration from sync to watch collection
• MongoService integration with proper indexes for efficient querying

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/core/src/types/watch.types.ts	Defines the watch schema and TypeScript types for notification channel data
packages/core/src/types/type.utils.ts	Moves ObjectId utility functions for reuse across the codebase
packages/backend/src/common/constants/collections.ts	Adds watch collection constant with dev/prod environment support
packages/backend/src/common/services/mongo.service.ts	Integrates watch collection with proper TypeScript types and collection getter
packages/scripts/src/migrations/2025.10.13T14.18.20.watch-collection.ts	Creates watch collection with schema validation and performance indexes
packages/scripts/src/migrations/2025.10.13T14.22.21.migrate-sync-watch-data.ts	Migrates existing events watch data to new collection while creating fresh notification channels