feat: Calendar Cache

.env.example

@@ -144,6 +144,12 @@ GOOGLE_WEBHOOK_TOKEN=
 # Optional URL to override for tunelling webhooks. Defaults to NEXT_PUBLIC_WEBAPP_URL.
 GOOGLE_WEBHOOK_URL=
 
+# Token to verify incoming webhooks from Microsoft Calendar
+MICROSOFT_WEBHOOK_TOKEN=
+
+# Optional URL to override for tunelling webhooks. Defaults to NEXT_PUBLIC_WEBAPP_URL.
+MICROSOFT_WEBHOOK_URL=
+
 # Inbox to send user feedback
 SEND_FEEDBACK_EMAIL=
 

packages/app-store/_utils/getCalendar.ts

@@ -1,28 +1,16 @@
+import { CalendarCacheEventRepository } from "@calcom/features/calendar-subscription/lib/cache/CalendarCacheEventRepository";
+import { CalendarCacheEventService } from "@calcom/features/calendar-subscription/lib/cache/CalendarCacheEventService";
+import { CalendarCacheWrapper } from "@calcom/features/calendar-subscription/lib/cache/CalendarCacheWrapper";
+import { FeaturesRepository } from "@calcom/features/flags/features.repository";
 import logger from "@calcom/lib/logger";
-import type { Calendar, CalendarClass } from "@calcom/types/Calendar";
+import { prisma } from "@calcom/prisma";
+import type { Calendar } from "@calcom/types/Calendar";
 import type { CredentialForCalendarService } from "@calcom/types/Credential";
 
 import { CalendarServiceMap } from "../calendar.services.generated";
 
-interface CalendarApp {
-  lib: {
-    CalendarService: CalendarClass;
-  };
-}
-
 const log = logger.getSubLogger({ prefix: ["CalendarManager"] });
 
-/**
- * @see [Using type predicates](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates)
- */
-const isCalendarService = (x: unknown): x is CalendarApp =>
-  !!x &&
-  typeof x === "object" &&
-  "lib" in x &&
-  typeof x.lib === "object" &&
-  !!x.lib &&
-  "CalendarService" in x.lib;
-
 export const getCalendar = async (
   credential: CredentialForCalendarService | null
 ): Promise<Calendar | null> => {
@@ -53,5 +41,33 @@ export const getCalendar = async (
     return null;
   }
 
+  // check if Calendar Cache is supported and enabled
+  if (CalendarCacheEventService.isAppSupported(credential.appId)) {
+    log.debug(
+      `Using regular CalendarService for credential ${credential.id} (not Google or Office365 Calendar)`
+    );
+    const featuresRepository = new FeaturesRepository(prisma);
+    const isCalendarSubscriptionCacheEnabled = await featuresRepository.checkIfFeatureIsEnabledGlobally(
+      "calendar-subscription-cache"
+    );
+
+    if (isCalendarSubscriptionCacheEnabled) {
+      log.debug(
+        `calendar-subscription-cache is enabled, using CalendarCacheService for credential ${credential.id}`
+      );
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const originalCalendar = new CalendarService(credential as any);
+      if (originalCalendar) {
+        // return cacheable calendar
+        const calendarCacheEventRepository = new CalendarCacheEventRepository(prisma);
+        return new CalendarCacheWrapper({
+          originalCalendar,
+          calendarCacheEventRepository,
+        });
+      }
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return new CalendarService(credential as any);
 };

packages/features/calendar-subscription/README.md

@@ -0,0 +1,40 @@
+# Calendar Subscription  
+
+The **Calendar Subscription** feature keeps your calendars synchronized while ensuring efficient caching.  
+
+When enabled, it uses **webhooks** to automatically listen for updates and apply changes in real time.  
+This means new events, modifications, or deletions are instantly captured and reflected across the system — no manual refresh or constant polling required.  
+
+## Key Benefits  
+- **Efficiency**: reduces API calls with optimized caching strategies.  
+- **Reliability**: guarantees updates through webhook event delivery.  
+- **Real-Time Sync**: ensures calendars are always up-to-date with minimal latency.  
+- **Scalability**: supports multiple calendars and handles high-volume updates seamlessly.  
+
+By subscribing to calendars via webhooks, you gain a smarter, faster, and more resource-friendly way to keep your data in sync.  
+
+## Feature Flags
+
+This feature can be enabled using two feature flags:
+1. `calendar-subscription-cache` that will allow calendar cache to be recorded and used thru calendars, this flag is for globally enable this feature that should be managed individually by teams through team_Features 
+
+### Enabling cache feature
+`insert into Feature`
+INSERT INTO "public"."Feature" ("slug", "enabled", "description", "type", "stale", "lastUsedAt", "createdAt", "updatedAt", "updatedBy") VALUES
+('calendar-cache-serve', 'f', 'Whether to serve calendar cache by default or not on a team/user basis.', 'OPERATIONAL', 'f', NULL, '2025-09-16 17:02:09.292', '2025-09-16 17:02:09.292', NULL);
+
+
+`insert into TeamFeatures 
+INSERT INTO "public"."TeamFeatures" ("teamId", "featureId", "assignedAt", "assignedBy", "updatedAt") VALUES
+(1, DEFAULT, DEFAULT, DEFAULT, DEFAULT);
+
+### Enabling sync feature
+2. `calendar-subscription-sync` this flag will enable canlendar sync for all calendars, diferently from cache it will be enabled globally for all users regardinless it is a team, individual or org.
+INSERT INTO "public"."Feature" ("slug", "enabled", "description", "type", "stale", "lastUsedAt", "createdAt", "updatedAt", "updatedBy") VALUES
+('calendar-cache-serve', 'f', 'Whether to serve calendar cache by default or not on a team/user basis.', 'OPERATIONAL', 'f', NULL, '2025-09-16 17:02:09.292', '2025-09-16 17:02:09.292', NULL);
+
+## Team Feature Flags
+
+
+## Architecture 
+

packages/features/calendar-subscription/adapters/AdaptersFactory.ts

@@ -0,0 +1,27 @@
+import { GoogleCalendarSubscriptionAdapter } from "@calcom/features/calendar-subscription/adapters/GoogleCalendarSubscription.adapter";
+import { Office365CalendarSubscriptionAdapter } from "@calcom/features/calendar-subscription/adapters/Office365CalendarSubscription.adapter";
+import type { ICalendarSubscriptionPort } from "@calcom/features/calendar-subscription/lib/CalendarSubscriptionPort.interface";
+
+export type CalendarSubscriptionProvider = "google_calendar" | "office365_calendar";
+
+export interface AdapterFactory {
+  get(provider: CalendarSubscriptionProvider): ICalendarSubscriptionPort;
+}
+
+/**
+ * Default adapter factory
+ */
+export class DefaultAdapterFactory implements AdapterFactory {
+  private singletons = {
+    google_calendar: new GoogleCalendarSubscriptionAdapter(),
+    office365_calendar: new Office365CalendarSubscriptionAdapter(),
+  } as const;
+
+  get(provider: CalendarSubscriptionProvider): ICalendarSubscriptionPort {
+    const adapter = this.singletons[provider];
+    if (!adapter) {
+      throw new Error(`No adapter found for provider ${provider}`);
+    }
+    return adapter;
+  }
+}

packages/features/calendar-subscription/adapters/GoogleCalendarSubscription.adapter.ts

@@ -0,0 +1,176 @@
+import type { calendar_v3 } from "@googleapis/calendar";
+import { v4 as uuid } from "uuid";
+
+import { CalendarAuth } from "@calcom/app-store/googlecalendar/lib/CalendarAuth";
+import logger from "@calcom/lib/logger";
+import type { SelectedCalendar } from "@calcom/prisma/client";
+
+import type {
+  ICalendarSubscriptionPort,
+  CalendarSubscriptionResult,
+  CalendarSubscriptionEvent,
+  CalendarSubscriptionEventItem,
+  CalendarCredential,
+  CalendarSubscriptionWebhookContext,
+} from "../lib/CalendarSubscriptionPort.interface";
+
+const log = logger.getSubLogger({ prefix: ["GoogleCalendarSubscriptionAdapter"] });
+
+/**
+ * Google Calendar Subscription Adapter
+ *
+ * This adapter uses the Google Calendar API to create and manage calendar subscriptions
+ * @see https://developers.google.com/google-apps/calendar/quickstart/nodejs
+ */
+export class GoogleCalendarSubscriptionAdapter implements ICalendarSubscriptionPort {
+  private GOOGLE_WEBHOOK_TOKEN = process.env.GOOGLE_WEBHOOK_TOKEN;
+  private GOOGLE_WEBHOOK_URL = process.env.GOOGLE_WEBHOOK_URL;
+
+  async validate(context: CalendarSubscriptionWebhookContext): Promise<boolean> {
+    const token = context?.headers?.get("X-Goog-Channel-Token");
+    if (!this.GOOGLE_WEBHOOK_TOKEN) {
+      log.warn("GOOGLE_WEBHOOK_TOKEN not configured");
+      return false;
+    }
+    if (token !== this.GOOGLE_WEBHOOK_TOKEN) {
+      log.warn("Invalid webhook token", { token });
+      return false;
+    }
+    return true;
+  }
+
+  async extractChannelId(context: CalendarSubscriptionWebhookContext): Promise<string | null> {
+    const channelId = context?.headers?.get("X-Goog-Channel-ID");
+    if (!channelId) {
+      log.warn("Missing channel ID in webhook");
+      return null;
+    }
+    return channelId;
+  }
+
+  async subscribe(
+    selectedCalendar: SelectedCalendar,
+    credential: CalendarCredential
+  ): Promise<CalendarSubscriptionResult> {
+    log.debug("Attempt to subscribe to Google Calendar", { externalId: selectedCalendar.externalId });
+    selectedCalendar;
+
+    const MONTH_IN_SECONDS = 60 * 60 * 24 * 30;
+
+    const client = await this.getClient(credential);
+    const result = await client.events.watch({
+      calendarId: selectedCalendar.externalId,
+      requestBody: {
+        id: uuid(),
+        type: "web_hook",
+        address: this.GOOGLE_WEBHOOK_URL,
+        token: this.GOOGLE_WEBHOOK_TOKEN,
+        params: {
+          ttl: MONTH_IN_SECONDS.toFixed(0),
+        },
+      },
+    });
+
+    const e = result.data?.expiration;
+    const expiration = e ? new Date(/^\d+$/.test(e) ? +e : e) : null;
+
+    return {
+      provider: "google_calendar",
+      id: result.data.id,
+      resourceId: result.data.resourceId,
+      resourceUri: result.data.resourceUri,
+      expiration,
+    };
+  }
+  async unsubscribe(selectedCalendar: SelectedCalendar, credential: CalendarCredential): Promise<void> {
+    log.debug("Attempt to unsubscribe from Google Calendar", { externalId: selectedCalendar.externalId });
+
+    const client = await this.getClient(credential);
+    await client.channels
+      .stop({
+        requestBody: {
+          resourceId: selectedCalendar.channelResourceId,
+        },
+      })
+      .catch((err) => {
+        log.error("Error unsubscribing from Google Calendar", err);
+        throw err;
+      });
+  }
+
+  async fetchEvents(
+    selectedCalendar: SelectedCalendar,
+    credential: CalendarCredential
+  ): Promise<CalendarSubscriptionEvent> {
+    const client = await this.getClient(credential);
+
+    let syncToken = selectedCalendar.syncToken || undefined;
+    let pageToken;
+
+    const events: calendar_v3.Schema$Event[] = [];
+    do {
+      const { data }: { data: calendar_v3.Schema$Events } = await client.events.list({
+        calendarId: selectedCalendar.externalId,
+        syncToken,
+        pageToken,
+        singleEvents: true,
+      });
+
+      syncToken = data.nextSyncToken || syncToken;
+      pageToken = data.nextPageToken ?? null;
+
+      events.push(...(data.items || []));
+    } while (pageToken);
+
+    return {
+      provider: "google_calendar",
+      syncToken: syncToken || null,
+      items: this.parseEvents(events),
+    };
+  }
+
+  private parseEvents(events: calendar_v3.Schema$Event[]): CalendarSubscriptionEventItem[] {
+    const now = new Date();
+    return events
+      .map((event) => {
+        const busy = event.transparency === "opaque"; // opaque = busy, transparent = free
+
+        const start = event.start?.dateTime
+          ? new Date(event.start.dateTime)
+          : event.start?.date
+          ? new Date(event.start.date)
+          : new Date();
+
+        const end = event.end?.dateTime
+          ? new Date(event.end.dateTime)
+          : event.end?.date
+          ? new Date(event.end.date)
+          : new Date();
+
+        return {
+          id: event.id,
+          iCalUID: event.iCalUID,
+          start,
+          end,
+          busy,
+          summary: event.summary,
+          description: event.description,
+          location: event.location,
+          kind: event.kind,
+          status: event.status,
+          isAllDay: !!event.start?.date && !event.start?.dateTime,
+          timeZone: event.start?.timeZone || null,
+          originalStartTime: event.originalStartTime?.dateTime,
+          createdAt: event.created ? new Date(event.created) : null,
+          updatedAt: event.updated ? new Date(event.updated) : null,
+        };
+      })
+      .filter((e) => !!e.id) // safely remove events with no ID
+      .filter((e) => e.start < now); // remove old events
+  }
+
+  private async getClient(credential: CalendarCredential) {
+    const auth = new CalendarAuth(credential);
+    return await auth.getClient();
+  }
+}