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.

Example

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)

Twist<TSelf>
- Connector

Accessors

`Protected`tools

get tools(): InferTools<TSelf>
Gets the initialized tools for this twist.

Returns InferTools<TSelf>
Throws
Error if called before initialization is complete
Inherited from Twist.tools
- Defined in twist.ts:66

Constructors

constructor

new Connector<TSelf>(id: Uuid, toolShed: ToolShed): Connector<TSelf>
Type Parameters
- TSelf
Parameters
- id: Uuid
- toolShed: ToolShed
Returns Connector<TSelf>
Inherited from Twist.constructor
- Defined in twist.ts:60

Methods

getAccountName

getAccountName(
auth: Authorization | null,
token: AuthToken | null,
): Promise<string | null>
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
- Defined in connector.ts:139

`Abstract`getChannels

getChannels(
auth: Authorization | null,
token: AuthToken | null,
): Promise<Channel[]>
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
- Defined in connector.ts:156

`Abstract`onChannelEnabled

onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>
Called when a channel resource is enabled for syncing.

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 with plan-based hints (e.g. syncHistoryMin)
Returns Promise<void>
Example
```
async onChannelEnabled(channel: Channel): Promise<void> {
  await this.set(`sync_enabled_${channel.id}`, true);
  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);
}
```
- Defined in connector.ts:191

`Abstract`onChannelDisabled

onChannelDisabled(channel: Channel): Promise<void>
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>
- Defined in connector.ts:199

onLinkUpdated

onLinkUpdated(link: Link): 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>
Overrides Twist.onLinkUpdated
- Defined in connector.ts:211

onNoteCreated

onNoteCreated(note: Note, thread: ThreadFields): Promise<string | void>
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 sets the note's key for future upsert matching, linking the Plot note to its external counterpart so that subsequent syncs (reactions, edits) update the existing note instead of creating duplicates.
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>
Optional note key for external deduplication
Overrides Twist.onNoteCreated
- Defined in connector.ts:229

onNoteUpdated

onNoteUpdated(note: Note, thread: ThreadFields): Promise<void>
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).
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>
- Defined in connector.ts:242

onThreadRead

onThreadRead(thread: ThreadFields, actor: Actor, unread: boolean): Promise<void>
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>
- Defined in connector.ts:256

onThreadToDo

onThreadToDo(
    thread: ThreadFields,
    actor: Actor,
    todo: boolean,
    options: { date?: Date },
): 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>
- Defined in connector.ts:272

onScheduleContactUpdated

onScheduleContactUpdated(
    thread: ThreadFields,
    scheduleId: string,
    contactId: ActorId,
    status: ScheduleContactStatus | null,
    actor: Actor,
): 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>
- Defined in connector.ts:287

activate

activate(context: { auth?: Authorization; actor?: Actor }): 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>
Overrides Twist.activate
- Defined in connector.ts:307

`Abstract`build

build(build: ToolBuilder): Record<string, Promise<ITool>>
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
Example
```
build(build: ToolBuilder) {
  return {
    plot: build(Plot),
    calendar: build(GoogleCalendar, { apiKey: "..." }),
  };
}
```
Inherited from Twist.build
- Defined in twist.ts:87

`Protected`callback

callback<TArgs extends Serializable[], Fn extends (...args: TArgs) => any>(
fn: Fn,
...extraArgs: TArgs,
): Promise<Callback>
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
- TArgs extends Serializable[]
- Fn extends (...args: TArgs) => any
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
Example
```
const callback = await this.callback(this.onWebhook, "calendar", 123);
```
Inherited from Twist.callback
- Defined in twist.ts:103
callback<
    TArgs extends Serializable[],
    Fn extends (arg1: any, ...extraArgs: TArgs) => any,
>(
    fn: Fn,
    ...extraArgs: TArgs,
): Promise<Callback>
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
- TArgs extends Serializable[]
- Fn extends (arg1: any, ...extraArgs: TArgs) => any
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
Example
```
const callback = await this.callback(this.onWebhook, "calendar", 123);
```
Inherited from Twist.callback
- Defined in twist.ts:108

`Protected`actionCallback

actionCallback<
    TArgs extends Serializable[],
    Fn extends (action: Action, ...extraArgs: TArgs) => any,
>(
    fn: Fn,
    ...extraArgs: TArgs,
): Promise<Callback>
Like callback(), but for an Action, which receives the action as the first argument.
Type Parameters
- TArgs extends Serializable[]
- Fn extends (action: Action, ...extraArgs: TArgs) => any
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
Example
```
const callback = await this.actionCallback(this.doSomething, 123);
const action: Action = {
   type: ActionType.callback,
   title: "Do Something",
   callback,
};
```
Inherited from Twist.actionCallback
- Defined in twist.ts:136

`Protected`deleteCallback

deleteCallback(token: Callback): Promise<void>
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
Inherited from Twist.deleteCallback
- Defined in twist.ts:149

`Protected`deleteAllCallbacks

deleteAllCallbacks(): Promise<void>
Deletes all callbacks for this twist.

Returns Promise<void>
Promise that resolves when all callbacks are deleted
Inherited from Twist.deleteAllCallbacks
- Defined in twist.ts:158

`Protected`run

run(token: Callback, ...args: []): Promise<any>
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
Inherited from Twist.run
- Defined in twist.ts:178

`Protected`get

get<T extends Serializable>(key: string): Promise<T | null>
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
Inherited from Twist.get
- Defined in twist.ts:192

`Protected`set

set<T extends Serializable>(key: string, value: T): Promise<void>
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
Example
```
// ✅ 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);
```
Inherited from Twist.set
- Defined in twist.ts:236

`Protected`clear

clear(key: string): Promise<void>
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
Inherited from Twist.clear
- Defined in twist.ts:249

`Protected`clearAll

clearAll(): Promise<void>
Removes all keys from this twist's storage.

Returns Promise<void>
Promise that resolves when all keys are removed
Inherited from Twist.clearAll
- Defined in twist.ts:258

`Protected`runTask

runTask(callback: Callback, options?: { runAt?: Date }): Promise<string | void>
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)
Inherited from Twist.runTask
- Defined in twist.ts:270

`Protected`cancelTask

cancelTask(token: string): Promise<void>
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
Inherited from Twist.cancelTask
- Defined in twist.ts:283

`Protected`cancelAllTasks

cancelAllTasks(): Promise<void>
Cancels all scheduled executions for this twist.

Returns Promise<void>
Promise that resolves when all cancellations are processed
Inherited from Twist.cancelAllTasks
- Defined in twist.ts:292

upgrade

upgrade(): Promise<void>
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
Inherited from Twist.upgrade
- Defined in twist.ts:321

onOptionsChanged

onOptionsChanged(
oldOptions: Record<string, any>,
newOptions: Record<string, any>,
): Promise<void>
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
Inherited from Twist.onOptionsChanged
- Defined in twist.ts:336

deactivate

deactivate(): Promise<void>
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
Inherited from Twist.deactivate
- Defined in twist.ts:351

onThreadUpdated

onThreadUpdated(
    thread: ThreadFields,
    changes: {
        tagsAdded: Record<Tag, ActorId[]>;
        tagsRemoved: Record<Tag, ActorId[]>;
    },
): Promise<void>
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>
Inherited from Twist.onThreadUpdated
- Defined in twist.ts:363

onLinkCreated

onLinkCreated(link: Link, notes: Note[]): 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>
Inherited from Twist.onLinkCreated
- Defined in twist.ts:399

onLinkNoteCreated

onLinkNoteCreated(note: Note, link: Link): 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>
Inherited from Twist.onLinkNoteCreated
- Defined in twist.ts:423

Properties

`Static` `Readonly`isConnector

isConnector: true

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

`Optional` `Readonly`provider

provider?: AuthProvider

The OAuth provider this connector authenticates with.

`Optional` `Readonly`scopes

scopes?: string[]

OAuth scopes to request for this connector.

`Optional` `Readonly`shared

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)

`Optional` `Readonly`keyOption

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.

`Optional` `Readonly`singleChannel

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.

`Optional` `Readonly`linkTypes

linkTypes?: LinkTypeConfig[]

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

`Static` `Optional` `Readonly`handleReplies

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.

`Static` `Optional` `Readonly`multipleInstances

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

Example

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

`Protected`userId

userId: Uuid

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

`Protected`id

id: Uuid

Class Connector<TSelf>Abstract

Example

Type Parameters

Hierarchy (View Summary)

Index

Accessors

Constructors

Methods

Properties

Accessors

Protectedtools

Returns InferTools<TSelf>

Throws

Constructors

constructor

Type Parameters

Parameters

Returns Connector<TSelf>

Methods

getAccountName

Parameters

Returns Promise<string | null>

AbstractgetChannels

Parameters

Returns Promise<Channel[]>

AbstractonChannelEnabled

Parameters

Returns Promise<void>

Example

AbstractonChannelDisabled

Parameters

Returns Promise<void>

onLinkUpdated

Parameters

Returns Promise<void>

onNoteCreated

Parameters

Returns Promise<string | void>

onNoteUpdated

Parameters

Returns Promise<void>

onThreadRead

Parameters

Returns Promise<void>

onThreadToDo

Parameters

Optionaldate?: Date

Returns Promise<void>

onScheduleContactUpdated

Parameters

Returns Promise<void>

activate

Parameters

Optionalauth?: Authorization

Optionalactor?: Actor

Returns Promise<void>

Abstractbuild

Parameters

Returns Record<string, Promise<ITool>>

Example

Protectedcallback

Type Parameters

Parameters

Returns Promise<Callback>

Example

Type Parameters

Parameters

Returns Promise<Callback>

Example

ProtectedactionCallback

Type Parameters

Parameters

Returns Promise<Callback>

Example

ProtecteddeleteCallback

Parameters

Returns Promise<void>

ProtecteddeleteAllCallbacks

Returns Promise<void>

Protectedrun

Class Connector<TSelf>`Abstract`

`Protected`tools

`Abstract`getChannels

`Abstract`onChannelEnabled

`Abstract`onChannelDisabled

`Optional`date?: Date

`Optional`auth?: Authorization

`Optional`actor?: Actor

`Abstract`build

`Protected`callback

`Protected`actionCallback

`Protected`deleteCallback

`Protected`deleteAllCallbacks

`Protected`run

`Protected`get

`Protected`set

`Protected`clear

`Protected`clearAll

`Protected`runTask

`Optional`runAt?: Date

`Protected`cancelTask

`Protected`cancelAllTasks

`Static` `Readonly`isConnector

`Optional` `Readonly`provider

`Optional` `Readonly`scopes

`Optional` `Readonly`shared

`Optional` `Readonly`keyOption

`Optional` `Readonly`singleChannel

`Optional` `Readonly`linkTypes

`Static` `Optional` `Readonly`handleReplies

`Static` `Optional` `Readonly`multipleInstances

`Protected`userId

`Protected`id