AbstractProtectedtoolsGets the initialized tools for this twist.
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.
The authorization (null for no-provider connectors)
The access token (null for no-provider connectors)
Promise resolving to the account display name
Returns a matchable identity email for the connected account, for connectors that authenticate without OAuth (e.g. a username/app-password flow) and so have no provider-verified identity to fall back on.
Unlike getAccountName, which is only a display label, the value returned here is used to recognize the connected account as belonging to the signed-in Plot user (for example, so the platform can tell the account's own messages apart from messages sent to it).
Return null (the default) if the connector has no email address that
can reliably identify the account.
Promise resolving to the account's identity email, or null
AbstractgetReturns available channels for the authorized actor. Called after OAuth is complete, during the setup/edit modal.
The completed authorization with provider and actor info
The access token for making API calls
Promise resolving to available channels for the user to select
AbstractonCalled when a channel resource is enabled for syncing.
The framework dispatches this in three cases:
setChannels discovered a new channel on a
connection with auto_enable_new_channels set.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:
tools.integrations.channelSyncCompleted(id)
once the initial backfill is done, ORIMPORTANT: 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().
The channel that was enabled
Optionalcontext: SyncContextOptional sync context (plan-based hints, recovery flag)
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);
}
AbstractonCalled when a channel resource is disabled. Should stop sync, clean up webhooks, and remove state.
The channel that was disabled
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).
The updated link
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
Implementations should create the item in the external service and
return a CreateLinkResult describing the created item. The platform
attaches the returned link to the originating thread — do not call
integrations.saveLink yourself. channelId may be omitted; the
platform auto-fills it from the compose draft.
Returning null aborts creation silently (the thread is still saved
without a link).
The fields captured in Plot for the new item.
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.
The created note
The thread the note belongs to (includes thread.meta with connector-specific data)
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).
Opaque value the connector previously emitted on a fileRef action.
OptionallinkMeta: Record<string, unknown> | nullThe meta of the link owning the fileRef's note — the same
connector-authored metadata surfaced as thread.meta in write-back
callbacks (e.g. chatId/channelId for chat connectors). null when
the note has no link or the link carries no meta. Connectors whose refs
are self-contained can ignore it.
Either { redirectUrl } or { body, mimeType, fileName? }.
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.
The updated note (includes current tags)
The thread the note belongs to (includes thread.meta with connector-specific data)
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).
The thread that was read/unread (includes thread.meta with connector-specific data)
The user who performed the action
false when marked as read, true when marked as unread
Called when a user changes the thread-level sharing of a thread owned
by this connector — adding or removing a contact, or (for connectors with
roles) changing a contact's role. Override on connectors whose external
source can reflect that membership change, e.g. a group DM / multi-party
chat (LinkTypeConfig.sharingModel: "thread") or an email's To/Cc/Bcc
recipients (sharingModel: "message"). Connectors backed by an immutable
roster (most group DMs today) or by channel-level membership
(sharingModel: "channel") leave this as the default no-op.
role/from/to are null for connectors without roles (group DMs
have no roles); they carry a contactRoles id only for connectors that
declare roles (e.g. email to/cc/bcc).
The dispatch fires after Plot has persisted the change. A connector may
reflect it actively (e.g. add/remove a participant on the external chat)
or passively 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.
The thread whose contacts changed
The added/removed contacts and any role transitions on existing contacts
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).
The thread (includes thread.meta with connector-specific data)
The user who changed the todo status
true when marked as todo, false when done or removed
Additional context
Optionaldate?: DateThe todo date (when todo=true)
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.
The thread (includes thread.meta with connector-specific data)
The schedule ID
The contact whose status changed
The new RSVP status ('attend', 'skip', or null)
The user who changed the status
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.
The note that was reacted on (partial; id, key, content populated)
The thread the note belongs to (partial; id, title, archived, meta populated)
The contact who added/removed the reaction
The emoji (Unicode grapheme or provider:workspace/name custom-emoji ref)
true if the reaction is now present, false if it was removed
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.
The activation context
Optionalauth?: AuthorizationThe completed OAuth authorization
Optionalactor?: ActorThe actor who activated the connector
AbstractbuildDeclares tool dependencies for this twist. Return an object mapping tool names to build() promises.
The build function to use for declaring dependencies
Object mapping tool names to tool promises
ProtectedcallbackCreates a persistent callback to a method on this twist.
ExtraArgs are strongly typed to match the method's signature. They must be serializable.
Promise resolving to a persistent callback token
Creates a persistent callback to a method on this twist.
ExtraArgs are strongly typed to match the method's signature. They must be serializable.
Promise resolving to a persistent callback token
ProtectedactionLike callback(), but for an Action, which receives the action as the first argument.
Promise resolving to a persistent callback token
ProtecteddeleteDeletes a specific callback by its token.
The callback token to delete
Promise that resolves when the callback is deleted
ProtecteddeleteDeletes all callbacks for this twist.
Promise that resolves when all callbacks are deleted
ProtectedrunExecutes 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().
The callback token to execute
Optional arguments to pass to the callback
Promise resolving to the callback result
ProtectedgetRetrieves a value from persistent storage by key.
Values are automatically deserialized using SuperJSON, which properly restores Date objects, Maps, Sets, and other complex types.
The expected type of the stored value (must be Serializable)
The storage key to retrieve
Promise resolving to the stored value or null
ProtectedsetStores 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.
The type of value being stored (must be Serializable)
The storage key to use
The value to store (must be SuperJSON-serializable)
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<Callback>("handler_token");
await this.run(token);
ProtectedsetStores many key/value pairs in one round-trip. Always prefer this over
looping set() for batch writes — each set() is a network round-trip.
Atomic: either every entry lands or none do. See Store.setMany.
The type of values being stored (must be Serializable)
Array of [key, value] pairs to store
Promise that resolves when all values are stored
ProtectedgetReads many keys in one round-trip. Always prefer this over looping
get(). Results are positionally aligned with keys; missing keys are
null. See Store.getMany.
The type of the stored values
The storage keys to read
Promise resolving to one value (or null) per requested key
ProtectedlistLists matching keys with their values in one round-trip — the read
counterpart of setMany. Replaces list() + a get() per key, which
costs 1 + N round-trips. See Store.listEntries.
The type of the stored values
The prefix to match keys against
Promise resolving to [key, value] pairs, key-ascending
ProtectedclearRemoves a specific key from persistent storage.
The storage key to remove
Promise that resolves when the key is removed
ProtectedclearRemoves many keys in one round-trip. Pair with listEntries so a drain costs two round-trips regardless of key count. Atomic. See Store.clearMany.
The storage keys to remove
Promise that resolves when all keys are removed
ProtectedclearRemoves all keys from this twist's storage.
Promise that resolves when all keys are removed
ProtectedrunQueues a callback to execute in a separate worker context.
The callback token created with this.callback()
Optionaloptions: { runAt?: Date }Optional configuration for the execution
OptionalrunAt?: DateIf provided, schedules execution at this time; otherwise runs immediately
Promise resolving to a cancellation token (only for scheduled executions)
ProtectedcancelCancels a previously scheduled execution.
The cancellation token returned by runTask() with runAt option
Promise that resolves when the cancellation is processed
ProtectedcancelCancels all scheduled executions for this twist.
Promise that resolves when all cancellations are processed
ProtectedscheduleSchedules a singleton task keyed by key: re-scheduling under the same
key atomically replaces any pending task, so at most one is ever live.
Prefer this over runTask({ runAt }) for recurring/self-renewing jobs
(watch renewals, polling, deferred cleanup) — it removes the error-prone
"store token, cancel before re-scheduling" bookkeeping that otherwise leaks
parallel task chains. See Tasks.scheduleTask.
With coalesce: true, an existing pending task is kept instead of
replaced (its fire time is pulled earlier, never pushed later) — use for
high-frequency triggers like webhook-driven sync scheduling; the passed
callback may be discarded, so don't reuse its token.
Stable identifier scoped to what the task renews
The callback token created with this.callback()
When to run (required)
Optionalcoalesce?: booleanKeep an existing pending task (earliest wins)
Promise resolving to the scheduled task's cancellation token
ProtectedcancelCancels the singleton task previously scheduled under key (if any).
No-op if none exists or it already ran. See Tasks.cancelScheduledTask.
The same key passed to scheduleTask
Promise that resolves when the cancellation is processed
ProtectedscheduleSchedules a durable recurring task under a stable key. The platform
re-arms the task every intervalMs automatically — the callback does NOT
need to reschedule itself. Re-scheduling under the same key atomically
replaces the pending occurrence (at most one live task per key). Tear down
with cancelScheduledTask. See Tasks.scheduleRecurring.
Stable identifier, e.g. "mailbox-self-heal"
Callback token created with this.callback()
Safety-ceiling cadence in milliseconds
OptionalfirstRunAt?: DateOptional precise time for the next fire
ProtectedscheduleRecord dirty items and ensure a bounded drain pass runs soon — THE pattern for webhook-driven sync and any other high-frequency "something changed" trigger.
A burst of calls under the same key collapses into ONE pending pass
(never one queued task per notification); ids are persisted durably and
released only after the handler processes them (at-least-once, race-free
under concurrent deliveries); each pass hands the handler at most
batchSize ids, with the platform scheduling continuations while a
backlog remains; ids that keep failing are dropped after maxAttempts
passes so one poison item can't wedge the drain.
The handler must be a named method on this class (like this.callback
targets). It receives the ids slice — or [] for signal-only drains
(omit ids) where it derives its own work from a cursor or time window.
Optionaloptions: DrainOptionsasync onWebhook(request: WebhookRequest): Promise<void> {
const ids = parseChangedIds(request);
await this.scheduleDrain("incremental-sync", this.drainChanges, { ids });
}
async drainChanges(ids: string[]): Promise<void> {
for (const id of ids) await this.syncItem(id); // ≤ batchSize items
}
Tear down with cancelDrain (e.g. in onChannelDisabled).
ProtectedcancelCancel the pending drain pass for key and discard its recorded ids.
Use in teardown paths. See scheduleDrain.
SDK-internal: executes one bounded drain pass (the scheduled-task target behind scheduleDrain). Public only so the task runtime can dispatch to it by name — do not call or override.
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.
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.
The previously resolved options
The newly resolved options
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.
Promise that resolves when deactivation is complete
Static ReadonlyisStatic marker to identify Connector subclasses without instanceof checks across worker boundaries.
Optional ReadonlyproviderThe OAuth provider this connector authenticates with.
Optional ReadonlyscopesOAuth scopes to request for this connector — a flat list (all required), or a ScopeConfig declaring required + optional scope groups.
Optional ReadonlyaccessPlain-language bullets describing what access connecting this service grants the user — shown on the connect screen regardless of auth mechanism (OAuth, API key, or hosted). For OAuth connectors it also previews what the provider's consent screen will request. These are justifications for what Plot accesses, not a one-to-one mapping of scope strings.
Optional ReadonlysharedWhen 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:
Optional ReadonlykeyThe 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 ReadonlysingleWhen 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 ReadonlychannelThe user-facing noun for this connector's channels — what each Channel returned by getChannels actually represents in the external service. Many connectors map "channels" onto a domain concept (folders, projects, calendars, labels, spaces, repositories, …), so the generic word "channel" reads as jargon. Set this and the UI substitutes it everywhere it would otherwise say "channel(s)" — e.g. the per-connection toggle becomes "Sync new folders" / "When a new folder is added, …".
Provide lowercase nouns (the UI capitalizes where needed):
{ singular: "folder", plural: "folders" }. Defaults to
{ singular: "channel", plural: "channels" } when omitted.
Optional ReadonlyautoWhether the per-connection "Sync new channels" preference starts ON for
newly added connections of this connector. Defaults to false (opt-in).
Set true for connectors that select all of their channels by default
(i.e. getChannels returns no channels marked
enabledByDefault: false). If syncing every channel is the intended
default, then channels discovered later should also sync automatically.
Leave false/omitted for selective connectors that exclude some channels
by default (e.g. Gmail syncs only Inbox/Sent, Google Calendar only
owner calendars) — for those, a newly discovered channel is just as
uncertain and should wait for the user to opt in.
Only affects the default for new connections; the user's explicit toggle always wins, and existing connections keep their stored preference.
Optional ReadonlyfixedWhether this connector's channel set is fixed — getChannels always
returns the same enumerated channels and no new channels ever appear
dynamically over time. Set true for connectors whose channels are a
built-in, closed set (e.g. LinkedIn: Messages + Public Post) rather than a
list discovered from the external account (Slack channels, Drive folders,
calendars, …).
When true, the connect/edit modal hides the per-connection "Sync new
{channels}" affordance: there are no new channels to auto-enable, so the
toggle would be meaningless. Leave false/omitted for connectors whose
channel list grows as the user gains access to more channels — those still
benefit from autoEnableNewChannelsByDefault and the toggle.
Optional ReadonlyhiddenWhether this connector's channels are internal detail rather than a user
choice. When true, channels are still reported from getChannels() and
mirrored so links can carry channel attribution (names shown on threads,
compose targets), but the connect/edit modal renders no channel picker and
enabling or disabling a channel is not a supported operation.
Use for connectors whose sync scope is decided by rules rather than by channel selection — e.g. a chat connector that syncs direct messages plus anything that mentions you, wherever it happens.
Distinct from fixedChannels, which still exposes a picker and only hides the "sync new {channels}" affordance.
Optional ReadonlyautoWhether this connector supports the platform's sequential auto-threading —
folding a conversation that arrives as a run of separate top-level messages
into a single thread. Set true for conversational connectors (chat,
messaging) that mark eligible links with NewLink.autoThread. The UI
shows a per-connection "Group related messages into conversations" toggle
only for connectors that declare this.
Leave undefined/false for connectors whose items are not conversational (calendars, issue trackers, file storage) — marking a link does nothing unless the connection both declares support and the user opted in.
Optional ReadonlyautoWhether the per-connection auto-threading preference starts ON for newly
added connections of this connector. Defaults to false (opt-in) — the
least-surprise default, since a wrong fold is irreversible. Only meaningful
when autoThreading is true. The user's explicit toggle always
wins, and existing connections keep their stored preference.
Optional ReadonlylinkRegistry of link types this connector creates (e.g., issue, event, message). Used for display in the UI (icons, labels, statuses).
Optional ReadonlyreactionDeclares 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).
Optional ReadonlydynamicWhen true, this connector's effective link types are computed dynamically from its enabled channels' per-channel link types (each channel carries the link types for whatever product/resource it represents), rather than the static union of all declared providers' link types. Lets one connection surface different link types depending on what the user has enabled — e.g. a combined Google connection shows calendar/event link types (and thus the agenda) only when a calendar channel is enabled.
Defaults to false (static link types — the behavior for every connector
that doesn't set this). Requires the connector to attach per-channel
linkTypes on the channels returned by getChannels.
Optional ReadonlyproductsPer-instance product metadata for combined (multi-product) connectors — one connection bundling several user-facing products under a single OAuth grant (e.g. the combined Google connector: Mail, Calendar, Tasks, Contacts).
Each ProductInfo.scopeGroupId must match an OptionalScopeGroup.id declared in this connector's scopes so the API can derive per-product enablement from granted scopes + enabled channels.
Leave undefined for plain (single-product) connectors — the API then omits
the products/productStatus response fields and the app uses the
standard per-connector flow.
Static Optional ReadonlyhandleWhen 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 ReadonlymultipleWhen 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).
ProtecteduserThe user ID (twist_instance.owner_id) that installed this twist.
Populated by the runtime before any lifecycle method runs.
Protectedid
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