Creating Plot Twists
    Preparing search index...

    Class Connector<TSelf>Abstract

    Base class for connectors — twists that sync data from external services.

    Connectors declare a single OAuth provider and scopes, and implement channel lifecycle methods for discovering and syncing external resources. They save data directly via integrations.saveLink() instead of using the Plot tool.

    class LinearConnector extends Connector<LinearConnector> {
      readonly provider = AuthProvider.Linear;
      readonly scopes = ["read", "write"];
      readonly linkTypes = [{
        type: "issue",
        label: "Issue",
        statuses: [
          { status: "open", label: "Open" },
          { status: "done", label: "Done" },
        ],
      }];

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

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

      async onChannelEnabled(channel: Channel) {
        const issues = await this.fetchIssues(channel.id);
        for (const issue of issues) {
          await this.tools.integrations.saveLink(issue);
        }
      }

      async onChannelDisabled(channel: Channel) {
        // Clean up webhooks, sync state, etc.
      }
    }

    Type Parameters

    • TSelf

    Hierarchy (View Summary)

    Index

    Accessors

    tools

    Constructors

    constructor

    Methods

    getAccountName getChannels onChannelEnabled onChannelDisabled onLinkUpdated onCreateLink onNoteCreated downloadAttachment onNoteUpdated onThreadRead onContactsChanged onThreadToDo onScheduleContactUpdated onNoteReactionChanged activate build callback actionCallback deleteCallback deleteAllCallbacks run get set clear clearAll runTask cancelTask cancelAllTasks upgrade onOptionsChanged deactivate onThreadUpdated onLinkCreated onLinkNoteCreated

    Properties

    isConnector provider? scopes? shared? keyOption? singleChannel? linkTypes? reactionCapabilities? handleReplies? multipleInstances? userId id

    Accessors

    Constructors

    Methods

    • Returns a human-readable name for the connected account. Shown in the connections list and edit modal to identify this connection.

      For OAuth connectors, this is typically the workspace or organization name (e.g., "Acme Corp" for a Linear workspace). For API key connectors, this could be the workspace name from the external service.

      Override this in your connector to return a meaningful account name.

      Parameters

      • auth: Authorization | null

        The authorization (null for no-provider connectors)

      • token: AuthToken | null

        The access token (null for no-provider connectors)

      Returns Promise<string | null>

      Promise resolving to the account display name

    • Returns available channels for the authorized actor. Called after OAuth is complete, during the setup/edit modal.

      Parameters

      • auth: Authorization | null

        The completed authorization with provider and actor info

      • token: AuthToken | null

        The access token for making API calls

      Returns Promise<Channel[]>

      Promise resolving to available channels for the user to select

    • Called when a channel resource is enabled for syncing.

      The framework dispatches this in three cases:

      1. Initial enable — user toggled the channel on for the first time.
      2. Auto-enable — setChannels discovered a new channel on a connection with auto_enable_new_channels set.
      3. Recovery after re-auth — the user re-authorized a previously- broken connection. The framework calls onChannelEnabled for every channel that was already enabled at the time of re-auth, with context.recovering = true. See SyncContext.recovering.

      Implementations should be idempotent and overwrite stored state: the same channel may receive multiple onChannelEnabled calls across its lifetime. Use unconditional this.set() writes rather than coalesce/skip-if-present logic so a recovery dispatch wipes stale cursors and state from the prior session.

      Sync state tracking is automatic. The framework stamps the connection as "syncing" when it dispatches this method and clears that state when:

      • the connector calls tools.integrations.channelSyncCompleted(id) once the initial backfill is done, OR
      • this method throws an unhandled exception (auto-cleared so the UI doesn't get stuck in "syncing" forever).

      IMPORTANT: This method runs inline in the HTTP request handler. Any long-running work (webhook setup, API calls, sync) MUST be queued as a separate task via this.runTask(), not executed inline. Blocking here causes the client to spin waiting for the response.

      Only lightweight operations should appear directly in this method: this.set(), this.get(), this.callback(), and this.runTask().

      Parameters

      • channel: Channel

        The channel that was enabled

      • Optionalcontext: SyncContext

        Optional sync context (plan-based hints, recovery flag)

      Returns Promise<void>

      async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {
        // Recovery: drop stale cursors so the next sync re-walks history.
        if (context?.recovering) {
          await this.clear(`last_sync_token_${channel.id}`);
        }

        await this.set(`sync_state_${channel.id}`, { channelId: channel.id });

        // Queue sync as a task — do NOT use this.run() or call sync methods inline
        const syncCallback = await this.callback(this.syncBatch, 1, "full", channel.id, true);
        await this.runTask(syncCallback);

        // Queue webhook setup as a task — do NOT call setupWebhook() inline
        const webhookCallback = await this.callback(this.setupWebhook, channel.id);
        await this.runTask(webhookCallback);
      }

    • Called when a channel resource is disabled. Should stop sync, clean up webhooks, and remove state.

      Parameters

      • channel: Channel

        The channel that was disabled

      Returns Promise<void>

    • Called when a link created by this connector is updated by the user. Override to write back changes to the external service (e.g., changing issue status in Linear when marked done in Plot).

      Parameters

      • link: Link

        The updated link

      Returns Promise<void>

    • Called when a user creates a thread in Plot that should create a new item in this connector's external system.

      A connector opts in to Plot-initiated creation by declaring a compose block on the relevant LinkTypeConfig (see ComposeConfig). When a user picks "Create new " from the Add link modal and the thread is synced, the runtime calls this method with the draft fields.

      Implementations should create the item in the external service and return a NewLinkWithNotes describing the created item. The platform attaches the returned link to the originating thread — do not call integrations.saveLink yourself.

      Returning null aborts creation silently (the thread is still saved without a link).

      Parameters

      Returns Promise<NewLinkWithNotes | null>

      The link to attach, or null to abort creation.

    • Called when a note is created on a thread owned by this connector. Override to write back comments to the external service (e.g., adding a comment to a Linear issue).

      Returning a string or NoteWriteBackResult links the Plot note to its external counterpart. A plain string sets the note's key. A NoteWriteBackResult additionally sets a sync baseline (via externalContent) so the next sync-in can recognize the round-tripped content and preserve Plot's formatted version. See NoteWriteBackResult for details.

      Parameters

      • note: Note

        The created note

      • thread: ThreadFields

        The thread the note belongs to (includes thread.meta with connector-specific data)

      Returns Promise<string | void | NoteWriteBackResult>

      Optional note key or NoteWriteBackResult for external dedup + baseline tracking

    • Resolve a fileRef action's bytes for download. Called when a user opens an attachment in Plot. Return either a redirect URL (preferred for sources that issue signed URLs, like Linear S3 or Slack permalink_public) or a streamed body (required when bytes are only reachable through an authenticated API call, like Gmail attachments.get).

      Parameters

      • ref: string

        Opaque value the connector previously emitted on a fileRef action.

      Returns Promise<
          | { redirectUrl: string }
          | {
              body: Uint8Array<ArrayBufferLike> | ReadableStream<any>;
              mimeType: string;
              fileName?: string;
          },
      >

      Either { redirectUrl } or { body, mimeType, fileName? }.

      If the source is unavailable, the connection is broken, or ref is invalid.

      If not overridden, fileRef actions on this connector's notes will return 410 Gone.

    • Called when a note on a thread owned by this connector is updated. Override to write back changes to the external service (e.g., syncing reaction tags as emoji reactions, or editing a comment whose content changed in Plot).

      Return a NoteWriteBackResult with externalContent to update the sync baseline after a successful write-back, so the next sync-in recognizes the external version as already-seen and preserves Plot's content.

      Parameters

      • note: Note

        The updated note (includes current tags)

      • thread: ThreadFields

        The thread the note belongs to (includes thread.meta with connector-specific data)

      Returns Promise<void | NoteWriteBackResult>

      Optional NoteWriteBackResult for baseline tracking

    • Called when a user reads or unreads a thread owned by this connector. Override to write back read status to the external service (e.g., marking an email as read in Gmail).

      Parameters

      • thread: ThreadFields

        The thread that was read/unread (includes thread.meta with connector-specific data)

      • actor: Actor

        The user who performed the action

      • unread: boolean

        false when marked as read, true when marked as unread

      Returns Promise<void>

    • Called when a user adds, removes, or changes the role of contacts on a thread owned by this connector. Override on connectors whose source supports mid-thread recipient changes (Gmail, IMAP, etc.). Connectors that can't change recipients per-message (Slack, Linear) leave this as the default no-op and should also declare LinkTypeConfig.supportsContactChanges: false.

      The dispatch fires after Plot has persisted the change. Connectors are expected to reflect it on the next outbound note (e.g. building To/Cc/Bcc headers from the current thread.contacts × thread.contactMeta) — this callback is not the right place to send a standalone notification.

      Parameters

      • thread: ThreadFields

        The thread whose contacts changed

      • changes: {
            added: { contact: Contact; role: string }[];
            removed: { contact: Contact; role: string }[];
            changed: { contact: Contact; from: string; to: string }[];
        }

        The added/removed contacts and any role transitions on existing contacts

      Returns Promise<void>

    • Called when a user marks or unmarks a thread as todo. Override to sync todo status to the external service (e.g., starring an email in Gmail when marked as todo).

      Parameters

      • thread: ThreadFields

        The thread (includes thread.meta with connector-specific data)

      • actor: Actor

        The user who changed the todo status

      • todo: boolean

        true when marked as todo, false when done or removed

      • options: { date?: Date }

        Additional context

        • Optionaldate?: Date

          The todo date (when todo=true)

      Returns Promise<void>

    • Called when a schedule contact's RSVP status changes on a thread owned by this connector. Override to sync RSVP changes back to the external calendar.

      Parameters

      • thread: ThreadFields

        The thread (includes thread.meta with connector-specific data)

      • scheduleId: string

        The schedule ID

      • contactId: ActorId

        The contact whose status changed

      • status: ScheduleContactStatus | null

        The new RSVP status ('attend', 'skip', or null)

      • actor: Actor

        The user who changed the status

      Returns Promise<void>

    • Called when a user adds or removes a single emoji reaction on a note (one event per (note, actor, emoji) state transition).

      Dispatch is routed to the reacting user's own connector instance via twist_instance_for_actor on note_reaction.actor_id, so this method already runs under the reactor's auth. Fetch the API client with the connector's normal token-fetch path (this.tools.integrations.get(...)) and the external write — e.g. Slack reactions.add — will be attributed to the correct user. No actAs step required.

      If the reacting user has no connection of this type, no dispatch fires for that reaction (it stays in Plot only).

      Override to sync per-actor reactions back to the external system.

      Parameters

      • note: Note

        The note that was reacted on (partial; id, key, content populated)

      • thread: ThreadFields

        The thread the note belongs to (partial; id, title, archived, meta populated)

      • actor: Actor

        The contact who added/removed the reaction

      • emoji: string

        The emoji (Unicode grapheme or provider:workspace/name custom-emoji ref)

      • added: boolean

        true if the reaction is now present, false if it was removed

      Returns Promise<void>

    • Called when the connector is activated after OAuth is complete.

      Connectors receive the authorization in addition to the activating actor. When this runs, this.userId is already populated with the installing user's ID.

      Default implementation does nothing. Override for custom setup.

      Parameters

      • context: { auth?: Authorization; actor?: Actor }

        The activation context

        • Optionalauth?: Authorization

          The completed OAuth authorization

        • Optionalactor?: Actor

          The actor who activated the connector

      Returns Promise<void>

    • Declares tool dependencies for this twist. Return an object mapping tool names to build() promises.

      Parameters

      • build: ToolBuilder

        The build function to use for declaring dependencies

      Returns Record<string, Promise<ITool>>

      Object mapping tool names to tool promises

      build(build: ToolBuilder) {
        return {
          plot: build(Plot),
          calendar: build(GoogleCalendar, { apiKey: "..." }),
        };
      }

    • Creates a persistent callback to a method on this twist.

      ExtraArgs are strongly typed to match the method's signature. They must be serializable.

      Type Parameters

      Parameters

      • fn: Fn

        The method to callback

      • ...extraArgs: TArgs

        Additional arguments to pass (type-checked, must be serializable)

      Returns Promise<Callback>

      Promise resolving to a persistent callback token

      const callback = await this.callback(this.onWebhook, "calendar", 123);

    • Creates a persistent callback to a method on this twist.

      ExtraArgs are strongly typed to match the method's signature. They must be serializable.

      Type Parameters

      Parameters

      • fn: Fn

        The method to callback

      • ...extraArgs: TArgs

        Additional arguments to pass (type-checked, must be serializable)

      Returns Promise<Callback>

      Promise resolving to a persistent callback token

      const callback = await this.callback(this.onWebhook, "calendar", 123);

    • Like callback(), but for an Action, which receives the action as the first argument.

      Type Parameters

      Parameters

      • fn: Fn

        The method to callback

      • ...extraArgs: TArgs

        Additional arguments to pass after the action

      Returns Promise<Callback>

      Promise resolving to a persistent callback token

      const callback = await this.actionCallback(this.doSomething, 123);
      const action: Action = {
         type: ActionType.callback,
         title: "Do Something",
         callback,
      };

    • Deletes a specific callback by its token.

      Parameters

      • token: Callback

        The callback token to delete

      Returns Promise<void>

      Promise that resolves when the callback is deleted

    • Deletes all callbacks for this twist.

      Returns Promise<void>

      Promise that resolves when all callbacks are deleted

    • Executes a callback by its token inline in the current execution.

      Use this.runTask() instead for batch continuations and long-running work. this.run() executes inline, sharing the current request count (~1000 limit) and blocking the HTTP response. This causes timeouts when used in lifecycle methods like onChannelEnabled or syncBatch continuations.

      this.run() is appropriate when you need the callback's return value — e.g., running a parent callback token that returns data. For fire-and-forget work, always prefer this.runTask().

      Parameters

      • token: Callback

        The callback token to execute

      • ...args: []

        Optional arguments to pass to the callback

      Returns Promise<any>

      Promise resolving to the callback result

    • Retrieves a value from persistent storage by key.

      Values are automatically deserialized using SuperJSON, which properly restores Date objects, Maps, Sets, and other complex types.

      Type Parameters

      • T extends Serializable

        The expected type of the stored value (must be Serializable)

      Parameters

      • key: string

        The storage key to retrieve

      Returns Promise<T | null>

      Promise resolving to the stored value or null

    • Stores a value in persistent storage.

      The value will be serialized using SuperJSON and stored persistently. SuperJSON automatically handles Date objects, Maps, Sets, undefined values, and other complex types that standard JSON doesn't support.

      Important: Functions and Symbols cannot be stored. For function references: Use callbacks instead of storing functions directly.

      Type Parameters

      • T extends Serializable

        The type of value being stored (must be Serializable)

      Parameters

      • key: string

        The storage key to use

      • value: T

        The value to store (must be SuperJSON-serializable)

      Returns Promise<void>

      Promise that resolves when the value is stored

      // ✅ Date objects are preserved
      await this.set("sync_state", {
        lastSync: new Date(),
        minDate: new Date(2024, 0, 1)
      });

      // ✅ undefined is now supported
      await this.set("data", { name: "test", optional: undefined });

      // ❌ WRONG: Cannot store functions directly
      await this.set("handler", this.myHandler);

      // ✅ CORRECT: Create a callback token first
      const token = await this.callback(this.myHandler, "arg1", "arg2");
      await this.set("handler_token", token);

      // Later, execute the callback
      const token = await this.get<string>("handler_token");
      await this.run(token, args);

    • Removes a specific key from persistent storage.

      Parameters

      • key: string

        The storage key to remove

      Returns Promise<void>

      Promise that resolves when the key is removed

    • Removes all keys from this twist's storage.

      Returns Promise<void>

      Promise that resolves when all keys are removed

    • Queues a callback to execute in a separate worker context.

      Parameters

      • callback: Callback

        The callback token created with this.callback()

      • Optionaloptions: { runAt?: Date }

        Optional configuration for the execution

        • OptionalrunAt?: Date

          If provided, schedules execution at this time; otherwise runs immediately

      Returns Promise<string | void>

      Promise resolving to a cancellation token (only for scheduled executions)

    • Cancels a previously scheduled execution.

      Parameters

      • token: string

        The cancellation token returned by runTask() with runAt option

      Returns Promise<void>

      Promise that resolves when the cancellation is processed

    • Cancels all scheduled executions for this twist.

      Returns Promise<void>

      Promise that resolves when all cancellations are processed

    • Called when a new version of the twist is deployed.

      This method should contain migration logic for updating old data structures or setting up new resources that weren't needed by the previous version. It is called once per active twist_instance with the new version.

      Returns Promise<void>

      Promise that resolves when upgrade is complete

    • Called when the twist's options configuration changes.

      Override to react to option changes, e.g. archiving items when a sync type is toggled off, or starting sync when a type is toggled on.

      Parameters

      • oldOptions: Record<string, any>

        The previously resolved options

      • newOptions: Record<string, any>

        The newly resolved options

      Returns Promise<void>

      Promise that resolves when the change is handled

    • Called when the twist is uninstalled.

      This method should contain cleanup logic such as removing webhooks, cleaning up external resources, or performing final data operations.

      Returns Promise<void>

      Promise that resolves when deactivation is complete

    • Called when a thread created by this twist is updated. Override to implement two-way sync with an external system.

      Parameters

      • thread: ThreadFields

        The updated thread

      • changes: { tagsAdded: Record<Tag, ActorId[]>; tagsRemoved: Record<Tag, ActorId[]> }

        Tag additions and removals on the thread

      Returns Promise<void>

    • Called when a link is created in a connected source channel. Requires link: true in Plot options.

      Parameters

      • link: Link

        The newly created link

      • notes: Note[]

        Notes on the link's thread

      Returns Promise<void>

    • Called when a note is created on a thread with a link from a connected channel. Requires link: true in Plot options.

      Parameters

      • note: Note

        The newly created note

      • link: Link

        The link associated with the thread

      Returns Promise<void>

    Properties

    isConnector: true

    Static marker to identify Connector subclasses without instanceof checks across worker boundaries.

    provider?: AuthProvider

    The OAuth provider this connector authenticates with.

    scopes?: string[] | ScopeConfig

    OAuth scopes to request for this connector — a flat list (all required), or a ScopeConfig declaring required + optional scope groups.

    shared?: boolean

    When true, one credential is shared across all users in the workspace, entered once by the installer. When false (default), each user provides their own credential.

    Applies to both OAuth and key-based connectors:

    • Shared OAuth: e.g. Slack bot token (workspace-level)
    • Shared key: e.g. Attio workspace API key
    • Individual OAuth: e.g. Google Calendar (per-user)
    • Individual key: e.g. Fellow (per-user API key)
    keyOption?: string

    The Options field name that contains the authentication key (e.g. "apiKey"). Must reference a secure: true field in the Options schema.

    When set, this connector uses key-based auth instead of OAuth. For individual connectors (shared is false), this field is stored per-user rather than in shared config.

    singleChannel?: boolean

    When true, this connector has a single implicit channel. getChannels() must return exactly one Channel. The UI will show channel config inline instead of a channel list.

    linkTypes?: LinkTypeConfig[]

    Registry of link types this connector creates (e.g., issue, event, message). Used for display in the UI (icons, labels, statuses).

    reactionCapabilities?: ReactionCapabilities

    Declares how this connector's platform handles emoji reactions. Used to filter the reaction picker for notes whose primary connector is this one, and to guard outbound dispatch from sending emoji the platform can't accept.

    Leave undefined for connectors whose platform has no concept of reactions (calendar, file storage, issue trackers without reactions).

    handleReplies?: boolean

    When true, this connector is mentioned by default on replies to threads it created. When false (default), this connector cannot be mentioned at all.

    Set this to true for connectors with bidirectional sync (e.g., issue trackers, messaging) where user replies should be written back to the external service.

    multipleInstances?: boolean

    When true, users may install multiple instances of this twist within the same scope (personal workspace or team). Each instance must have a distinct name.

    Defaults to false (single instance per scope).

    class WorkflowTwist extends Twist<WorkflowTwist> {
      static readonly multipleInstances = true;
      // ...
    }
    userId: Uuid

    The user ID (twist_instance.owner_id) that installed this twist. Populated by the runtime before any lifecycle method runs.

    id: Uuid

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods
    Properties