Creating Plot Twists
    Preparing search index...

    Class IntegrationsAbstract

    Built-in tool for managing OAuth authentication and channel resources.

    The Integrations tool:

    1. Manages channel resources (calendars, projects, etc.) per actor
    2. Returns tokens for the user who enabled sync on a channel
    3. Supports per-actor auth via actAs() for write-back operations
    4. Provides saveLink/saveContacts for Connectors to save data directly

    Connectors declare their provider, scopes, and channel lifecycle methods as class properties and methods. The Integrations tool reads these automatically. Auth and channel management is handled in the twist edit modal in Flutter.

    class CalendarConnector extends Connector<CalendarConnector> {
      readonly provider = AuthProvider.Google;
      readonly scopes = ["https://www.googleapis.com/auth/calendar"];

      build(build: ToolBuilder) {
        return {
          integrations: build(Integrations),
        };
      }

      async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {
        const calendars = await this.listCalendars(token);
        return calendars.map(c => ({ id: c.id, title: c.name }));
      }

      async onChannelEnabled(channel: Channel) {
        // Start syncing
      }

      async onChannelDisabled(channel: Channel) {
        // Stop syncing
      }
    }

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    MergeScopes get saveLink saveLinks saveContacts archiveLinks setThreadToDo channelSyncCompleted markNeedsReauth

    Constructors

    Methods

    • Merge scopes from multiple tools, deduplicating.

      Parameters

      • ...scopeArrays: string[][]

        Arrays of scopes to merge

      Returns string[]

      Deduplicated array of scopes

    • Retrieves an access token for a channel resource.

      Returns the token of the user who enabled sync on the given channel. If the channel is not enabled or the token is expired/invalid, returns null.

      Parameters

      • channelId: string

        The channel resource ID (e.g., calendar ID)

      Returns Promise<AuthToken | null>

      Promise resolving to the access token or null

    • Retrieves an access token for a channel resource.

      Parameters

      • provider: AuthProvider

        The OAuth provider (deprecated, ignored for single-provider connectors)

      • channelId: string

        The channel resource ID (e.g., calendar ID)

      Returns Promise<AuthToken | null>

      Promise resolving to the access token or null

      Use get(channelId) instead. The provider is implicit from the connector.

    • Saves a link with notes to the connector's focus.

      Creates a thread+link pair. The thread is a lightweight container; the link holds the external entity data (source, meta, type, status, etc.).

      This method is available only to Connectors (not regular Twists).

      Parameters

      Returns Promise<Uuid | null>

      Promise resolving to the saved thread's UUID, or null if the link was filtered out (e.g. older than the plan's sync history limit)

    • Batch version of saveLink — saves many links in one call.

      Connectors syncing many items per page (e.g. calendar events, issues, messages) should prefer this over looping saveLink. Each saveLink crosses the runtime boundary and counts against the per-execution request budget; saveLinks collapses N saves into a single crossing.

      Failures on individual links DO NOT abort the batch. A bad item lands as null in its slot and the rest still save. This prevents one malformed record from losing an entire page of sync progress.

      This method is available only to Connectors (not regular Twists).

      Parameters

      Returns Promise<(Uuid | null)[]>

      Array of the same length and order as links. Each entry is the saved thread's UUID, or null if the link was filtered out (e.g. older than the plan's sync history limit) OR failed to save. The two null causes are not distinguished; the save failure is logged server-side.

    • Upserts contacts into the connector's focus without requiring a Link.

      Use this for messaging connectors to bulk-sync workspace members so the recipient picker can filter contacts by reachable platform account. Populate NewContact.source to persist contact_external_account rows (the platform identity used to address the contact). Returns one Actor per input, in order.

      Parameters

      • contacts: NewContact[]

        Contacts to upsert, keyed by source/key

      Returns Promise<Actor[]>

      Promise resolving to the saved actors, 1:1 with input order

    • Archives links matching the given filter that were created by this connector.

      For each archived link's thread, if no other non-archived links remain, the thread is also archived.

      Parameters

      Returns Promise<void>

      Promise that resolves when archiving is complete

    • Sets or clears todo status on a thread owned by this connector.

      Parameters

      • source: string

        The link source URL identifying the thread

      • actorId: ActorId

        The user to set the todo for

      • todo: boolean

        true to mark as todo, false to clear/complete

      • Optionaloptions: { date?: string | Date }

        Additional options

        • Optionaldate?: string | Date

          The todo date (when todo=true). Defaults to today.

      Returns Promise<void>

    • Signal that initial bulk-sync (or recovery sync) for a channel is fully complete. The Flutter app uses this to clear the "syncing…" indicator on the connection.

      The framework automatically marks a channel as syncing when it dispatches onChannelEnabled (whether initial-enable, auto-enable from setChannels, or recovery after re-auth). Connectors do NOT need to call anything to start tracking — only to signal completion.

      Call this exactly once when the initial backfill has finished (no more pages, all phases exhausted). Do NOT call it on every incremental sync.

      If onChannelEnabled throws an unhandled exception, the framework automatically clears the syncing state — connectors don't need a try/catch to clear state on failure.

      No-op when no auth/user mapping exists for the channel (e.g. key-based connectors that don't have a per-user OAuth association).

      Parameters

      • channelId: string

        The channel resource ID whose initial sync just finished

      Returns Promise<void>

    • Flag a connection as needing re-authentication so the Flutter app surfaces a re-auth prompt on the next sync.

      Call this when a connector's API call returns a permanent auth-style error that the runtime can't observe through token refresh — e.g. Slack invalid_auth / token_revoked / not_authed, or a 401 on a provider that doesn't refresh. The runtime already flags reauth automatically when an OAuth refresh permanently fails or when the stored token is missing on a get(); only call this for cases the runtime can't see.

      Idempotent: safe to call repeatedly; existing reauth flags are not overwritten. No-op when the channel has no enabledBy actor (e.g. key-based connectors).

      Parameters

      • channelId: string

        The channel resource ID whose token is bad

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods