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
    // Typical calendar integration flow
    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.Task,
          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(
            auth.authToken,
            primaryCalendar.id,
            "onCalendarEvent"
          );
        }
      }

      async onCalendarEvent(activity: Activity) {
        // Step 4: Process synced events
        await this.plot.createActivity(activity);
      }
    }
    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 (activity: Activity, ...args: any[]) => any>(
            authToken: string,
            calendarId: string,
            callback: TCallback,
            ...extraArgs: TCallback extends (activity: any, ...rest: R) => any
                ? 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.

      Type Parameters

      • TCallback extends (activity: Activity, ...args: any[]) => any

      Parameters

      • authToken: string

        Authorization token for calendar access

      • calendarId: string

        ID of the calendar to sync

      • callback: TCallback

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

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

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

      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