Creating Plot Twists
    Preparing search index...

    Type Alias 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.

    Architecture: Tools Build, Twists Save

    Calendar tools follow Plot's core architectural principle:

    • Tools: Fetch external data and transform it into Plot format (NewActivity objects)
    • Twists: Receive the data and decide what to do with it (create, update, filter, etc.)

    This separation allows:

    • Tools to be reusable across different twists with different behaviors
    • Twists to have full control over what gets saved and how
    • Easier testing of tools in isolation

    Implementation Pattern:

    1. Authorization is handled via the twist edit modal (Integrations provider config)
    2. Tool declares providers and lifecycle callbacks in build()
    3. onAuthorized lists available calendars and calls setSyncables()
    4. User enables calendars in the modal → onSyncEnabled fires
    5. Tool builds NewActivity objects and passes them to the twist via callback
    6. Twist decides whether to save using createActivity/updateActivity

    Tool Implementation Rules:

    • DO build Activity/Note objects from external data
    • DO pass them to the twist via the callback
    • DON'T call plot.createActivity/updateActivity directly
    • DON'T save anything to Plot database

    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.

    class MyCalendarTwist extends Twist {
      build(build: ToolBuilder) {
        return {
          googleCalendar: build(GoogleCalendar),
          plot: build(Plot, { activity: { access: ActivityAccess.Create } }),
        };
      }

      // Auth and calendar selection handled in the twist edit modal.
      // Events are delivered via the startSync callback.
    }
    type CalendarTool = {
        getCalendars(calendarId: string): Promise<Calendar[]>;
        startSync<
            TArgs extends Serializable[],
            TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any,
        >(
            options: { calendarId: string } & SyncOptions,
            callback: TCallback,
            ...extraArgs: TArgs,
        ): Promise<void>;
        stopSync(calendarId: string): Promise<void>;
    }
    Index

    Methods

    getCalendars startSync stopSync

    Methods

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

      Parameters

      • calendarId: string

        A calendar ID to use for auth lookup

      Returns Promise<Calendar[]>

      Promise resolving to array of available calendars

      When no valid authorization is available

    • 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.

      Auth is obtained automatically via integrations.get(provider, calendarId).

      Type Parameters

      Parameters

      • options: { calendarId: string } & SyncOptions

        Sync configuration options

        • 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 | null

          Earliest date to sync events from (inclusive).

          • If undefined: defaults to 2 years in the past
          • If null: syncs all history from the beginning of time
          • If Date: syncs from the specified date
        • OptionaltimeMax?: Date | null

          Latest date to sync events to (exclusive).

          • If undefined: no limit (syncs all future events)
          • If null: no limit (syncs all future events)
          • If Date: syncs up to but not including the specified date

          Use cases:

          • Daily digest: Set to end of today
          • Week view: Set to end of current week
          • Performance: Limit initial sync range
      • callback: TCallback

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

      • ...extraArgs: TArgs

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

      Returns Promise<void>

      Promise that resolves when sync setup is complete

      When no valid authorization or calendar doesn't exist

    • Stops synchronizing events from a specific calendar.

      Parameters

      • 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