Creating Plot Twists
    Preparing search index...

    Interface CalendarTool

    Base interface for calendar integration tools.

    Defines the standard operations that all calendar tools must implement to integrate with external calendar services like Google Calendar, Outlook Calendar, etc.

    Implementation Pattern:

    1. Request an ActivityLink for authorization
    2. Create an Activity with the ActivityLink to prompt user
    3. Receive a CalendarAuth in the specified callback
    4. Fetch list of available calendars
    5. Start sync for selected calendars
    6. Process incoming events via callbacks

    Recommended Data Sync Strategy: Use Activity.source and Note.key for automatic upserts without manual ID tracking. See SYNC_STRATEGIES.md for detailed patterns and when to use alternative approaches.

    // Typical calendar integration flow using source/key upserts
    class MyCalendarTwist extends Twist {
      private googleCalendar: GoogleCalendar;

      async activate() {
        // Step 1: Request authorization
        const authLink = await this.googleCalendar.requestAuth("onAuthComplete");
        await this.plot.createActivity({
          type: ActivityType.Action,
          title: "Connect Google Calendar",
          links: [authLink],
        });
      }

      async onAuthComplete(auth: CalendarAuth) {
        // Step 2: Get available calendars
        const calendars = await this.googleCalendar.getCalendars(auth.authToken);

        // Step 3: Start sync for primary calendar
        const primaryCalendar = calendars.find(c => c.primary);
        if (primaryCalendar) {
          await this.googleCalendar.startSync(
            {
              authToken: auth.authToken,
              calendarId: primaryCalendar.id
            },
            this.onCalendarEvent,
            { initialSync: true }
          );
        }
      }

      async onCalendarEvent(
        syncUpdate: SyncUpdate,
        syncMeta: { initialSync: boolean }
      ) {
        // Step 4: Process synced events using source/key pattern
        // The sync update will automatically use the event's URL as the source
        // for deduplication - no manual ID tracking needed
        await this.plot.createActivity(syncUpdate);
      }
    }
    interface CalendarTool {
        requestAuth<
            TCallback extends (auth: CalendarAuth, ...args: any[]) => any,
        >(
            callback: TCallback,
            ...extraArgs: TCallback extends (auth: any, ...rest: R) => any ? R : [],
        ): Promise<ActivityLink>;
        getCalendars(authToken: string): Promise<Calendar[]>;
        startSync<
            TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any,
        >(
            options: { authToken: string; calendarId: string } & SyncOptions,
            callback: TCallback,
            ...extraArgs: TCallback extends (syncUpdate: any, ...rest: R) => any
                ? NoFunctions<R>
                : [],
        ): Promise<void>;
        stopSync(authToken: string, calendarId: string): Promise<void>;
    }
    Index

    Methods

    requestAuth getCalendars startSync stopSync

    Methods

    • Initiates the authorization flow for the calendar service.

      Type Parameters

      • TCallback extends (auth: CalendarAuth, ...args: any[]) => any

      Parameters

      • callback: TCallback

        Function receiving (auth, ...extraArgs) when auth completes

      • ...extraArgs: TCallback extends (auth: any, ...rest: R) => any ? R : []

        Additional arguments to pass to the callback (type-checked)

      Returns Promise<ActivityLink>

      Promise resolving to an ActivityLink to initiate the auth flow

    • Retrieves the list of calendars accessible to the authenticated user.

      Returns metadata for all calendars the user has access to, including their primary calendar and any shared calendars. This list can be presented to users for calendar selection.

      Parameters

      • authToken: string

        Authorization token from successful auth flow

      Returns Promise<Calendar[]>

      Promise resolving to array of available calendars

      When the auth token is invalid or expired

    • Begins synchronizing events from a specific calendar.

      Sets up real-time sync for the specified calendar, including initial event import and ongoing change notifications. The callback function will be invoked for each synced event.

      Recommended Implementation (Strategy 2 - Upsert via Source/Key):

      • Set Activity.source to the event's canonical URL (e.g., event.htmlLink)
      • Use Note.key for event details (description, attendees, etc.) to enable upserts
      • No manual ID tracking needed - Plot handles deduplication automatically
      • Send NewActivityWithNotes for all events (creates new or updates existing)
      • Set activity.unread = false for initial sync, true for incremental updates

      Alternative (Strategy 3 - Advanced cases):

      • Use Uuid.Generate() and store ID mappings when creating multiple activities per event
      • See SYNC_STRATEGIES.md for when this is appropriate

      Type Parameters

      • TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any

      Parameters

      • options: { authToken: string; calendarId: string } & SyncOptions

        Sync configuration options

        • authToken: string

          Authorization token for calendar access

        • calendarId: string

          ID of the calendar to sync

        Configuration options for calendar synchronization.

        Controls the time range and other parameters for calendar sync operations. Used to limit sync scope and optimize performance.

        • OptionaltimeMin?: Date

          Earliest date to sync events from (inclusive)

        • OptionaltimeMax?: Date

          Latest date to sync events to (exclusive)

      • callback: TCallback

        Function receiving (syncUpdate, ...extraArgs) for each synced event

      • ...extraArgs: TCallback extends (syncUpdate: any, ...rest: R) => any ? NoFunctions<R> : []

        Additional arguments to pass to the callback (type-checked, no functions allowed)

      Returns Promise<void>

      Promise that resolves when sync setup is complete

      When auth token is invalid or calendar doesn't exist

    • Stops synchronizing events from a specific calendar.

      Disables real-time sync and cleans up any webhooks or polling mechanisms for the specified calendar. No further events will be synced after this call.

      Parameters

      • authToken: string

        Authorization token for calendar access

      • calendarId: string

        ID of the calendar to stop syncing

      Returns Promise<void>

      Promise that resolves when sync is stopped

    Settings

    Member Visibility

    On This Page

    Methods