@plotday/twister 0.54.0 → 0.56.0

package/src/llm-docs/connector.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { type Actor, type ActorId, type Contact, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n  type AuthProvider,\n  type AuthToken,\n  type Authorization,\n  type Channel,\n  type LinkTypeConfig,\n  type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n *   indicates whether the platform additionally supports workspace\n *   custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n *   `subset` lists the allowed emoji (omit for \"currently full Unicode\n *   per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n *   Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n  | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n  | { mode: \"unicode-subset\"; subset?: readonly string[] }\n  | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking — the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string — the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n  /**\n   * External system identifier assigned to this note. Set as the note's\n   * `key` for future upsert matching. Required when the runtime does not\n   * already know the key (i.e., from `onNoteCreated`); ignored from\n   * `onNoteUpdated` when the key was already established on create.\n   */\n  key?: string;\n  /**\n   * The content string as the external system now stores it, post-write.\n   * For systems whose write-back returns a representation of what was\n   * actually stored (e.g. Google Drive comment `content` after a create),\n   * pass that verbatim. For systems that only accept plain text, this\n   * will often be a lossy plain-text version of the Plot markdown — that\n   * is exactly the point: storing the lossy form as baseline lets the\n   * next sync-in recognize it and skip overwriting the richer Plot\n   * version.\n   *\n   * Must exactly match the string your connector's sync-in path emits as\n   * `NewNote.content` for this note on re-ingest.\n   */\n  externalContent?: string;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n  /** Plot contact UUID */\n  id: Uuid;\n  /** Display name, or null if not set */\n  name: string | null;\n  /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n  externalAccountId: string;\n  /**\n   * The contact's role on the originating thread, resolved from\n   * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n   * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n   * explicit role entry — connectors should treat `null` as the link\n   * type's default role (the `contactRoles` entry marked `default: true`).\n   *\n   * Connectors that distinguish roles MUST honor this when addressing the\n   * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n   * Cc/Bcc headers, never the To header, so BCC recipients are not\n   * exposed to the other recipients. Connectors that don't distinguish\n   * roles (Slack, Linear) can ignore it.\n   */\n  role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n  /** The channel (account + resource) the new item belongs to. */\n  channelId: string;\n  /** Link type identifier, matches a `LinkTypeConfig.type`. */\n  type: string;\n  /** Status the user selected. Matches a `statuses[].status` for `type`. */\n  status: string;\n  /** Title of the originating Plot thread (post AI title generation). */\n  title: string;\n  /** Markdown content of the thread's first note, or null if none. */\n  noteContent: string | null;\n  /**\n   * Contacts attached to the originating Plot thread, excluding the\n   * creating user. Use these as recipients (email, chat DM members, etc.)\n   * when the external item is a message or invite. An empty list means\n   * the user did not add anyone to the thread.\n   *\n   * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n   * re-resolving contacts yourself: the runtime pre-resolves each contact\n   * to its platform account ID (`externalAccountId`) and populates\n   * `recipients` before `onCreateLink` is called.\n   */\n  contacts: Actor[];\n  /**\n   * Pre-resolved recipients for link types whose `compose.targets` is\n   * `\"contacts\"` or `\"addresses\"`.\n   *\n   * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n   * contact UUID, the platform-specific account ID\n   * (`externalAccountId`) the connector should use to address the\n   * recipient without performing its own lookup, and the contact's\n   * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n   * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n   * a connection-scoped row fall back to `contact.email`.\n   */\n  recipients?: ResolvedRecipient[];\n  /**\n   * Free-form addresses the user typed into the picker (no Plot contact\n   * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n   * undefined. Connectors should append these alongside `recipients`\n   * when constructing the recipient list (e.g. `To:` header for Gmail).\n   */\n  inviteEmails?: string[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n *   readonly provider = AuthProvider.Linear;\n *   readonly scopes = [\"read\", \"write\"];\n *   readonly linkTypes = [{\n *     type: \"issue\",\n *     label: \"Issue\",\n *     statuses: [\n *       { status: \"open\", label: \"Open\" },\n *       { status: \"done\", label: \"Done\" },\n *     ],\n *   }];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const teams = await this.listTeams(token);\n *     return teams.map(t => ({ id: t.id, title: t.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     const issues = await this.fetchIssues(channel.id);\n *     for (const issue of issues) {\n *       await this.tools.integrations.saveLink(issue);\n *     }\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Clean up webhooks, sync state, etc.\n *   }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n  /**\n   * Static marker to identify Connector subclasses without instanceof checks\n   * across worker boundaries.\n   */\n  static readonly isConnector = true;\n\n  // ---- Identity (abstract — every connector must declare) ----\n\n  /** The OAuth provider this connector authenticates with. */\n  readonly provider?: AuthProvider;\n\n  /** OAuth scopes to request for this connector. */\n  readonly scopes?: string[];\n\n  // ---- Auth model ----\n\n  /**\n   * When true, one credential is shared across all users in the workspace,\n   * entered once by the installer. When false (default), each user provides\n   * their own credential.\n   *\n   * Applies to both OAuth and key-based connectors:\n   * - Shared OAuth: e.g. Slack bot token (workspace-level)\n   * - Shared key: e.g. Attio workspace API key\n   * - Individual OAuth: e.g. Google Calendar (per-user)\n   * - Individual key: e.g. Fellow (per-user API key)\n   */\n  readonly shared?: boolean;\n\n  /**\n   * The Options field name that contains the authentication key (e.g. \"apiKey\").\n   * Must reference a `secure: true` field in the Options schema.\n   *\n   * When set, this connector uses key-based auth instead of OAuth.\n   * For individual connectors (`shared` is false), this field is stored\n   * per-user rather than in shared config.\n   */\n  readonly keyOption?: string;\n\n  // ---- Optional metadata ----\n\n  /**\n   * When true, this connector has a single implicit channel.\n   * `getChannels()` must return exactly one Channel.\n   * The UI will show channel config inline instead of a channel list.\n   */\n  readonly singleChannel?: boolean;\n\n  /**\n   * Registry of link types this connector creates (e.g., issue, event, message).\n   * Used for display in the UI (icons, labels, statuses).\n   */\n  readonly linkTypes?: LinkTypeConfig[];\n\n  /**\n   * Declares how this connector's platform handles emoji reactions.\n   * Used to filter the reaction picker for notes whose primary connector\n   * is this one, and to guard outbound dispatch from sending emoji the\n   * platform can't accept.\n   *\n   * Leave undefined for connectors whose platform has no concept of\n   * reactions (calendar, file storage, issue trackers without reactions).\n   */\n  readonly reactionCapabilities?: ReactionCapabilities;\n\n  /**\n   * When true, this connector is mentioned by default on replies to threads it created.\n   * When false (default), this connector cannot be mentioned at all.\n   *\n   * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n   * messaging) where user replies should be written back to the external service.\n   */\n  static readonly handleReplies?: boolean;\n\n  // ---- Account identity (abstract — every connector must implement) ----\n\n  /**\n   * Returns a human-readable name for the connected account.\n   * Shown in the connections list and edit modal to identify this connection.\n   *\n   * For OAuth connectors, this is typically the workspace or organization name\n   * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n   * could be the workspace name from the external service.\n   *\n   * Override this in your connector to return a meaningful account name.\n   *\n   * @param auth - The authorization (null for no-provider connectors)\n   * @param token - The access token (null for no-provider connectors)\n   * @returns Promise resolving to the account display name\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  getAccountName(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<string | null> {\n    return Promise.resolve(null);\n  }\n\n  // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n  /**\n   * Returns available channels for the authorized actor.\n   * Called after OAuth is complete, during the setup/edit modal.\n   *\n   * @param auth - The completed authorization with provider and actor info\n   * @param token - The access token for making API calls\n   * @returns Promise resolving to available channels for the user to select\n   */\n  abstract getChannels(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<Channel[]>;\n\n  /**\n   * Called when a channel resource is enabled for syncing.\n   *\n   * The framework dispatches this in three cases:\n   *  1. **Initial enable** — user toggled the channel on for the first time.\n   *  2. **Auto-enable** — `setChannels` discovered a new channel on a\n   *     connection with `auto_enable_new_channels` set.\n   *  3. **Recovery after re-auth** — the user re-authorized a previously-\n   *     broken connection. The framework calls `onChannelEnabled` for every\n   *     channel that was already enabled at the time of re-auth, with\n   *     `context.recovering = true`. See {@link SyncContext.recovering}.\n   *\n   * Implementations should be **idempotent and overwrite stored state**:\n   * the same channel may receive multiple `onChannelEnabled` calls across\n   * its lifetime. Use unconditional `this.set()` writes rather than\n   * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n   * cursors and state from the prior session.\n   *\n   * **Sync state tracking is automatic.** The framework stamps the\n   * connection as \"syncing\" when it dispatches this method and clears\n   * that state when:\n   *  - the connector calls `tools.integrations.channelSyncCompleted(id)`\n   *    once the initial backfill is done, OR\n   *  - this method throws an unhandled exception (auto-cleared so the UI\n   *    doesn't get stuck in \"syncing\" forever).\n   *\n   * **IMPORTANT: This method runs inline in the HTTP request handler.**\n   * Any long-running work (webhook setup, API calls, sync) MUST be queued\n   * as a separate task via `this.runTask()`, not executed inline. Blocking\n   * here causes the client to spin waiting for the response.\n   *\n   * Only lightweight operations should appear directly in this method:\n   * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n   *\n   * @example\n   * ```typescript\n   * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n   *   // Recovery: drop stale cursors so the next sync re-walks history.\n   *   if (context?.recovering) {\n   *     await this.clear(`last_sync_token_${channel.id}`);\n   *   }\n   *\n   *   await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n   *\n   *   // Queue sync as a task — do NOT use this.run() or call sync methods inline\n   *   const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n   *   await this.runTask(syncCallback);\n   *\n   *   // Queue webhook setup as a task — do NOT call setupWebhook() inline\n   *   const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n   *   await this.runTask(webhookCallback);\n   * }\n   * ```\n   *\n   * @param channel - The channel that was enabled\n   * @param context - Optional sync context (plan-based hints, recovery flag)\n   */\n  abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n  /**\n   * Called when a channel resource is disabled.\n   * Should stop sync, clean up webhooks, and remove state.\n   *\n   * @param channel - The channel that was disabled\n   */\n  abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n  // ---- Write-back hooks (optional, default no-ops) ----\n\n  /**\n   * Called when a link created by this connector is updated by the user.\n   * Override to write back changes to the external service\n   * (e.g., changing issue status in Linear when marked done in Plot).\n   *\n   * @param link - The updated link\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user creates a thread in Plot that should create a new\n   * item in this connector's external system.\n   *\n   * A connector opts in to Plot-initiated creation by declaring a\n   * `compose` block on the relevant `LinkTypeConfig` (see\n   * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n   * Add link modal and the thread is synced, the runtime calls this method\n   * with the draft fields.\n   *\n   * Implementations should create the item in the external service and\n   * return a `NewLinkWithNotes` describing the created item. The platform\n   * attaches the returned link to the originating thread — do not call\n   * `integrations.saveLink` yourself.\n   *\n   * Returning `null` aborts creation silently (the thread is still saved\n   * without a link).\n   *\n   * @param draft - The fields captured in Plot for the new item.\n   * @returns The link to attach, or null to abort creation.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n    return Promise.resolve(null);\n  }\n\n  /**\n   * Called when a note is created on a thread owned by this connector.\n   * Override to write back comments to the external service\n   * (e.g., adding a comment to a Linear issue).\n   *\n   * Returning a string or {@link NoteWriteBackResult} links the Plot note\n   * to its external counterpart. A plain string sets the note's `key`.\n   * A `NoteWriteBackResult` additionally sets a sync baseline (via\n   * `externalContent`) so the next sync-in can recognize the round-tripped\n   * content and preserve Plot's formatted version. See\n   * {@link NoteWriteBackResult} for details.\n   *\n   * @param note - The created note\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Resolve a `fileRef` action's bytes for download. Called when a user opens\n   * an attachment in Plot. Return either a redirect URL (preferred for sources\n   * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n   * streamed body (required when bytes are only reachable through an\n   * authenticated API call, like Gmail attachments.get).\n   *\n   * @param ref Opaque value the connector previously emitted on a fileRef action.\n   * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n   * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n   *\n   * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n   */\n  async downloadAttachment(\n    ref: string,\n  ): Promise<\n    | { redirectUrl: string }\n    | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n  > {\n    throw new Error(\n      `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n    );\n  }\n\n  /**\n   * Called when a note on a thread owned by this connector is updated.\n   * Override to write back changes to the external service\n   * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n   * whose content changed in Plot).\n   *\n   * Return a {@link NoteWriteBackResult} with `externalContent` to update\n   * the sync baseline after a successful write-back, so the next sync-in\n   * recognizes the external version as already-seen and preserves Plot's\n   * content.\n   *\n   * @param note - The updated note (includes current tags)\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional NoteWriteBackResult for baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user reads or unreads a thread owned by this connector.\n   * Override to write back read status to the external service\n   * (e.g., marking an email as read in Gmail).\n   *\n   * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n   * @param actor - The user who performed the action\n   * @param unread - false when marked as read, true when marked as unread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user adds, removes, or changes the role of contacts on a\n   * thread owned by this connector. Override on connectors whose source\n   * supports mid-thread recipient changes (Gmail, IMAP, etc.). Connectors\n   * that can't change recipients per-message (Slack, Linear) leave this as\n   * the default no-op and should also declare\n   * `LinkTypeConfig.supportsContactChanges: false`.\n   *\n   * The dispatch fires after Plot has persisted the change. Connectors are\n   * expected to reflect it on the next outbound note (e.g. building To/Cc/Bcc\n   * headers from the current `thread.contacts` × `thread.contactMeta`) — this\n   * callback is not the right place to send a standalone notification.\n   *\n   * @param thread - The thread whose contacts changed\n   * @param changes - The added/removed contacts and any role transitions on existing contacts\n   */\n  /* eslint-disable @typescript-eslint/no-unused-vars */\n  onContactsChanged(\n    thread: Thread,\n    changes: {\n      added: Array<{ contact: Contact; role: string }>;\n      removed: Array<{ contact: Contact; role: string }>;\n      changed: Array<{ contact: Contact; from: string; to: string }>;\n    },\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n  /* eslint-enable @typescript-eslint/no-unused-vars */\n\n  /**\n   * Called when a user marks or unmarks a thread as todo.\n   * Override to sync todo status to the external service\n   * (e.g., starring an email in Gmail when marked as todo).\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param actor - The user who changed the todo status\n   * @param todo - true when marked as todo, false when done or removed\n   * @param options - Additional context\n   * @param options.date - The todo date (when todo=true)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n   * Override to sync RSVP changes back to the external calendar.\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param scheduleId - The schedule ID\n   * @param contactId - The contact whose status changed\n   * @param status - The new RSVP status ('attend', 'skip', or null)\n   * @param actor - The user who changed the status\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user adds or removes a single emoji reaction on a note\n   * (one event per `(note, actor, emoji)` state transition).\n   *\n   * Dispatch is routed to the reacting user's own connector instance via\n   * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n   * already runs under the reactor's auth. Fetch the API client with the\n   * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n   * and the external write — e.g. Slack `reactions.add` — will be attributed\n   * to the correct user. No `actAs` step required.\n   *\n   * If the reacting user has no connection of this type, no dispatch fires\n   * for that reaction (it stays in Plot only).\n   *\n   * Override to sync per-actor reactions back to the external system.\n   *\n   * @param note  - The note that was reacted on (partial; `id`, `key`, `content` populated)\n   * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n   * @param actor - The contact who added/removed the reaction\n   * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n   * @param added - `true` if the reaction is now present, `false` if it was removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  // ---- Activation ----\n\n  /**\n   * Called when the connector is activated after OAuth is complete.\n   *\n   * Connectors receive the authorization in addition to the activating actor.\n   * When this runs, `this.userId` is already populated with the installing\n   * user's ID.\n   *\n   * Default implementation does nothing. Override for custom setup.\n   *\n   * @param context - The activation context\n   * @param context.auth - The completed OAuth authorization\n   * @param context.actor - The actor who activated the connector\n   */\n  // @ts-ignore - Connector.activate() has a Connector-specific context type.\n  activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";
+export default "import { type Actor, type ActorId, type Contact, type Link, type NewLinkWithNotes, type Note, type Thread, type Uuid } from \"./plot\";\nimport type { ScheduleContactStatus } from \"./schedule\";\nimport {\n  type AuthProvider,\n  type AuthToken,\n  type Authorization,\n  type Channel,\n  type LinkTypeConfig,\n  type SyncContext,\n} from \"./tools/integrations\";\nimport { Twist } from \"./twist\";\n\n/**\n * Declares how a connector's platform handles emoji reactions.\n *\n * Drives Plot UI behavior (e.g. the picker filters the available\n * reactions on notes whose primary connector declares `fixed`) and\n * outbound dispatch (Plot won't try to push an emoji the platform\n * can't accept).\n *\n * Variants:\n * - `open-unicode`: Platform accepts any Unicode emoji. `customEmoji`\n *   indicates whether the platform additionally supports workspace\n *   custom emoji (Slack, Google Chat).\n * - `unicode-subset`: Platform accepts Unicode but only a finite set.\n *   `subset` lists the allowed emoji (omit for \"currently full Unicode\n *   per docs, future-proofed for shrinkage\").\n * - `fixed`: Platform only accepts a fixed set (e.g. LinkedIn\n *   Messaging's 7-reaction set). `allowed` lists every supported emoji.\n */\nexport type ReactionCapabilities =\n  | { mode: \"open-unicode\"; customEmoji?: \"workspace\" | \"none\" }\n  | { mode: \"unicode-subset\"; subset?: readonly string[] }\n  | { mode: \"fixed\"; allowed: readonly string[] };\n\n/**\n * Result returned from {@link Connector.onNoteCreated} and\n * {@link Connector.onNoteUpdated} to report what the external system now\n * has stored for the note.\n *\n * The runtime hashes `externalContent` and stores it as the note's sync\n * baseline. On the next sync-in, if the incoming content hashes to the\n * same value, the runtime knows the external side hasn't changed and\n * preserves Plot's (possibly formatted) content. When the external side\n * is edited, the hash diverges and the runtime overwrites Plot's content\n * with the new external version.\n *\n * Omitting `externalContent` skips baseline tracking — the next sync-in\n * will overwrite Plot's content (previous behavior). Always provide it\n * when the write-back's return value reflects what the external system\n * actually stored (often lossy plain-text), so the round-trip does not\n * clobber the original Plot markdown.\n *\n * The hash covers only the content string — the runtime intentionally\n * does not include a content-type in the hash, so write-back and sync-in\n * do not have to agree on a content-type label for the same underlying\n * bytes. Return exactly the string your connector's sync-in path will\n * emit as `NewNote.content` for this note on the next re-ingest.\n *\n * For back-compat, `onNoteCreated` may also return a plain string, which\n * is treated as `{ key }` with no baseline.\n */\nexport type NoteWriteBackResult = {\n  /**\n   * External system identifier assigned to this note. Set as the note's\n   * `key` for future upsert matching. Required when the runtime does not\n   * already know the key (i.e., from `onNoteCreated`); ignored from\n   * `onNoteUpdated` when the key was already established on create.\n   */\n  key?: string;\n  /**\n   * The content string as the external system now stores it, post-write.\n   * For systems whose write-back returns a representation of what was\n   * actually stored (e.g. Google Drive comment `content` after a create),\n   * pass that verbatim. For systems that only accept plain text, this\n   * will often be a lossy plain-text version of the Plot markdown — that\n   * is exactly the point: storing the lossy form as baseline lets the\n   * next sync-in recognize it and skip overwriting the richer Plot\n   * version.\n   *\n   * Must exactly match the string your connector's sync-in path emits as\n   * `NewNote.content` for this note on re-ingest.\n   */\n  externalContent?: string;\n};\n\n/**\n * A Plot contact pre-resolved to its platform account ID, ready for use\n * in a messaging dispatch.\n *\n * Populated by the runtime for link types with `compose.targets: \"contacts\"` before\n * `onCreateLink` is called. The connector should use `externalAccountId`\n * directly to address the recipient on the platform (e.g. Slack user ID,\n * LinkedIn URN, Gmail address) without performing its own contact lookup.\n */\nexport type ResolvedRecipient = {\n  /** Plot contact UUID */\n  id: Uuid;\n  /** Display name, or null if not set */\n  name: string | null;\n  /** Platform-specific account identifier pre-resolved at dispatch time (e.g. Slack `U…`, LinkedIn URN, Gmail email address) */\n  externalAccountId: string;\n  /**\n   * The contact's role on the originating thread, resolved from\n   * `thread.contact_meta` against the link type's `contactRoles` (e.g.\n   * `\"to\"` / `\"cc\"` / `\"bcc\"` for Gmail). `null` when the contact had no\n   * explicit role entry — connectors should treat `null` as the link\n   * type's default role (the `contactRoles` entry marked `default: true`).\n   *\n   * Connectors that distinguish roles MUST honor this when addressing the\n   * recipient — e.g. Gmail must place `\"cc\"`/`\"bcc\"` recipients in the\n   * Cc/Bcc headers, never the To header, so BCC recipients are not\n   * exposed to the other recipients. Connectors that don't distinguish\n   * roles (Slack, Linear) can ignore it.\n   */\n  role: string | null;\n};\n\n/**\n * Fields captured in Plot when a user initiates creation of a new external\n * item via a connector's `onCreateLink` hook.\n *\n * Thread-agnostic on purpose — connectors do not receive the Plot thread.\n * The platform attaches the returned `NewLinkWithNotes` to the originating\n * thread once `onCreateLink` resolves.\n */\nexport type CreateLinkDraft = {\n  /** The channel (account + resource) the new item belongs to. */\n  channelId: string;\n  /** Link type identifier, matches a `LinkTypeConfig.type`. */\n  type: string;\n  /**\n   * Status the user selected. Matches a `statuses[].status` for `type`,\n   * or null for status-less link types (the parent linkType declares no\n   * `statuses` and no `compose.status`).\n   */\n  status: string | null;\n  /** Title of the originating Plot thread (post AI title generation). */\n  title: string;\n  /** Markdown content of the thread's first note, or null if none. */\n  noteContent: string | null;\n  /**\n   * Contacts attached to the originating Plot thread, excluding the\n   * creating user. Use these as recipients (email, chat DM members, etc.)\n   * when the external item is a message or invite. An empty list means\n   * the user did not add anyone to the thread.\n   *\n   * For link types with `compose.targets: \"contacts\"`, prefer `recipients` over\n   * re-resolving contacts yourself: the runtime pre-resolves each contact\n   * to its platform account ID (`externalAccountId`) and populates\n   * `recipients` before `onCreateLink` is called.\n   */\n  contacts: Actor[];\n  /**\n   * Pre-resolved recipients for link types whose `compose.targets` is\n   * `\"contacts\"` or `\"addresses\"`.\n   *\n   * Only populated for those link types; otherwise undefined. Each entry contains the Plot\n   * contact UUID, the platform-specific account ID\n   * (`externalAccountId`) the connector should use to address the\n   * recipient without performing its own lookup, and the contact's\n   * `role` on the thread (e.g. `\"to\"` / `\"cc\"` / `\"bcc\"`) resolved from\n   * `thread.contact_meta`. For `\"addresses\"` link types, contacts without\n   * a connection-scoped row fall back to `contact.email`.\n   */\n  recipients?: ResolvedRecipient[];\n  /**\n   * Free-form addresses the user typed into the picker (no Plot contact\n   * row). Only populated for link types with `compose.targets: \"addresses\"`; otherwise\n   * undefined. Connectors should append these alongside `recipients`\n   * when constructing the recipient list (e.g. `To:` header for Gmail).\n   */\n  inviteEmails?: string[];\n};\n\n/** An optional OAuth scope group the user can toggle at connect time. */\nexport type OptionalScopeGroup = {\n  /** Stable id used to track the user's selection. */\n  id: string;\n  /** Value-forward switch label, e.g. \"Add names to events using contacts\". */\n  label: string;\n  /** Optional secondary line shown under the label. */\n  description?: string;\n  /** The OAuth scope strings this group grants. */\n  scopes: string[];\n  /** Whether the group is requested by default (switch on). */\n  default: boolean;\n};\n\n/**\n * Structured scope declaration. `required` scopes must be granted — auth fails\n * and re-prompts if any is declined. `optional` groups are requested by default\n * but auth still succeeds if the user declines them; the connector should detect\n * the absence via the granted `token.scopes` and degrade gracefully.\n */\nexport type ScopeConfig = {\n  required: string[];\n  /** Friendly bullets describing what the always-on (required) access does. */\n  description?: string[];\n  optional?: OptionalScopeGroup[];\n};\n\n/**\n * Base class for connectors — twists that sync data from external services.\n *\n * Connectors declare a single OAuth provider and scopes, and implement channel\n * lifecycle methods for discovering and syncing external resources. They save\n * data directly via `integrations.saveLink()` instead of using the Plot tool.\n *\n * @example\n * ```typescript\n * class LinearConnector extends Connector<LinearConnector> {\n *   readonly provider = AuthProvider.Linear;\n *   readonly scopes = [\"read\", \"write\"];\n *   readonly linkTypes = [{\n *     type: \"issue\",\n *     label: \"Issue\",\n *     statuses: [\n *       { status: \"open\", label: \"Open\" },\n *       { status: \"done\", label: \"Done\" },\n *     ],\n *   }];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const teams = await this.listTeams(token);\n *     return teams.map(t => ({ id: t.id, title: t.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     const issues = await this.fetchIssues(channel.id);\n *     for (const issue of issues) {\n *       await this.tools.integrations.saveLink(issue);\n *     }\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Clean up webhooks, sync state, etc.\n *   }\n * }\n * ```\n */\nexport abstract class Connector<TSelf> extends Twist<TSelf> {\n  /**\n   * Static marker to identify Connector subclasses without instanceof checks\n   * across worker boundaries.\n   */\n  static readonly isConnector = true;\n\n  // ---- Identity (abstract — every connector must declare) ----\n\n  /** The OAuth provider this connector authenticates with. */\n  readonly provider?: AuthProvider;\n\n  /** OAuth scopes to request for this connector — a flat list (all required), or\n   *  a {@link ScopeConfig} declaring required + optional scope groups. */\n  readonly scopes?: string[] | ScopeConfig;\n\n  // ---- Auth model ----\n\n  /**\n   * When true, one credential is shared across all users in the workspace,\n   * entered once by the installer. When false (default), each user provides\n   * their own credential.\n   *\n   * Applies to both OAuth and key-based connectors:\n   * - Shared OAuth: e.g. Slack bot token (workspace-level)\n   * - Shared key: e.g. Attio workspace API key\n   * - Individual OAuth: e.g. Google Calendar (per-user)\n   * - Individual key: e.g. Fellow (per-user API key)\n   */\n  readonly shared?: boolean;\n\n  /**\n   * The Options field name that contains the authentication key (e.g. \"apiKey\").\n   * Must reference a `secure: true` field in the Options schema.\n   *\n   * When set, this connector uses key-based auth instead of OAuth.\n   * For individual connectors (`shared` is false), this field is stored\n   * per-user rather than in shared config.\n   */\n  readonly keyOption?: string;\n\n  // ---- Optional metadata ----\n\n  /**\n   * When true, this connector has a single implicit channel.\n   * `getChannels()` must return exactly one Channel.\n   * The UI will show channel config inline instead of a channel list.\n   */\n  readonly singleChannel?: boolean;\n\n  /**\n   * Registry of link types this connector creates (e.g., issue, event, message).\n   * Used for display in the UI (icons, labels, statuses).\n   */\n  readonly linkTypes?: LinkTypeConfig[];\n\n  /**\n   * Declares how this connector's platform handles emoji reactions.\n   * Used to filter the reaction picker for notes whose primary connector\n   * is this one, and to guard outbound dispatch from sending emoji the\n   * platform can't accept.\n   *\n   * Leave undefined for connectors whose platform has no concept of\n   * reactions (calendar, file storage, issue trackers without reactions).\n   */\n  readonly reactionCapabilities?: ReactionCapabilities;\n\n  /**\n   * When true, this connector is mentioned by default on replies to threads it created.\n   * When false (default), this connector cannot be mentioned at all.\n   *\n   * Set this to true for connectors with bidirectional sync (e.g., issue trackers,\n   * messaging) where user replies should be written back to the external service.\n   */\n  static readonly handleReplies?: boolean;\n\n  // ---- Account identity (abstract — every connector must implement) ----\n\n  /**\n   * Returns a human-readable name for the connected account.\n   * Shown in the connections list and edit modal to identify this connection.\n   *\n   * For OAuth connectors, this is typically the workspace or organization name\n   * (e.g., \"Acme Corp\" for a Linear workspace). For API key connectors, this\n   * could be the workspace name from the external service.\n   *\n   * Override this in your connector to return a meaningful account name.\n   *\n   * @param auth - The authorization (null for no-provider connectors)\n   * @param token - The access token (null for no-provider connectors)\n   * @returns Promise resolving to the account display name\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  getAccountName(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<string | null> {\n    return Promise.resolve(null);\n  }\n\n  // ---- Channel lifecycle (abstract — every connector must implement) ----\n\n  /**\n   * Returns available channels for the authorized actor.\n   * Called after OAuth is complete, during the setup/edit modal.\n   *\n   * @param auth - The completed authorization with provider and actor info\n   * @param token - The access token for making API calls\n   * @returns Promise resolving to available channels for the user to select\n   */\n  abstract getChannels(\n    auth: Authorization | null,\n    token: AuthToken | null\n  ): Promise<Channel[]>;\n\n  /**\n   * Called when a channel resource is enabled for syncing.\n   *\n   * The framework dispatches this in three cases:\n   *  1. **Initial enable** — user toggled the channel on for the first time.\n   *  2. **Auto-enable** — `setChannels` discovered a new channel on a\n   *     connection with `auto_enable_new_channels` set.\n   *  3. **Recovery after re-auth** — the user re-authorized a previously-\n   *     broken connection. The framework calls `onChannelEnabled` for every\n   *     channel that was already enabled at the time of re-auth, with\n   *     `context.recovering = true`. See {@link SyncContext.recovering}.\n   *\n   * Implementations should be **idempotent and overwrite stored state**:\n   * the same channel may receive multiple `onChannelEnabled` calls across\n   * its lifetime. Use unconditional `this.set()` writes rather than\n   * coalesce/skip-if-present logic so a recovery dispatch wipes stale\n   * cursors and state from the prior session.\n   *\n   * **Sync state tracking is automatic.** The framework stamps the\n   * connection as \"syncing\" when it dispatches this method and clears\n   * that state when:\n   *  - the connector calls `tools.integrations.channelSyncCompleted(id)`\n   *    once the initial backfill is done, OR\n   *  - this method throws an unhandled exception (auto-cleared so the UI\n   *    doesn't get stuck in \"syncing\" forever).\n   *\n   * **IMPORTANT: This method runs inline in the HTTP request handler.**\n   * Any long-running work (webhook setup, API calls, sync) MUST be queued\n   * as a separate task via `this.runTask()`, not executed inline. Blocking\n   * here causes the client to spin waiting for the response.\n   *\n   * Only lightweight operations should appear directly in this method:\n   * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.\n   *\n   * @example\n   * ```typescript\n   * async onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void> {\n   *   // Recovery: drop stale cursors so the next sync re-walks history.\n   *   if (context?.recovering) {\n   *     await this.clear(`last_sync_token_${channel.id}`);\n   *   }\n   *\n   *   await this.set(`sync_state_${channel.id}`, { channelId: channel.id });\n   *\n   *   // Queue sync as a task — do NOT use this.run() or call sync methods inline\n   *   const syncCallback = await this.callback(this.syncBatch, 1, \"full\", channel.id, true);\n   *   await this.runTask(syncCallback);\n   *\n   *   // Queue webhook setup as a task — do NOT call setupWebhook() inline\n   *   const webhookCallback = await this.callback(this.setupWebhook, channel.id);\n   *   await this.runTask(webhookCallback);\n   * }\n   * ```\n   *\n   * @param channel - The channel that was enabled\n   * @param context - Optional sync context (plan-based hints, recovery flag)\n   */\n  abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;\n\n  /**\n   * Called when a channel resource is disabled.\n   * Should stop sync, clean up webhooks, and remove state.\n   *\n   * @param channel - The channel that was disabled\n   */\n  abstract onChannelDisabled(channel: Channel): Promise<void>;\n\n  // ---- Write-back hooks (optional, default no-ops) ----\n\n  /**\n   * Called when a link created by this connector is updated by the user.\n   * Override to write back changes to the external service\n   * (e.g., changing issue status in Linear when marked done in Plot).\n   *\n   * @param link - The updated link\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onLinkUpdated(link: Link): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user creates a thread in Plot that should create a new\n   * item in this connector's external system.\n   *\n   * A connector opts in to Plot-initiated creation by declaring a\n   * `compose` block on the relevant `LinkTypeConfig` (see\n   * {@link ComposeConfig}). When a user picks \"Create new <type>\" from the\n   * Add link modal and the thread is synced, the runtime calls this method\n   * with the draft fields.\n   *\n   * Implementations should create the item in the external service and\n   * return a `NewLinkWithNotes` describing the created item. The platform\n   * attaches the returned link to the originating thread — do not call\n   * `integrations.saveLink` yourself.\n   *\n   * Returning `null` aborts creation silently (the thread is still saved\n   * without a link).\n   *\n   * @param draft - The fields captured in Plot for the new item.\n   * @returns The link to attach, or null to abort creation.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {\n    return Promise.resolve(null);\n  }\n\n  /**\n   * Called when a note is created on a thread owned by this connector.\n   * Override to write back comments to the external service\n   * (e.g., adding a comment to a Linear issue).\n   *\n   * Returning a string or {@link NoteWriteBackResult} links the Plot note\n   * to its external counterpart. A plain string sets the note's `key`.\n   * A `NoteWriteBackResult` additionally sets a sync baseline (via\n   * `externalContent`) so the next sync-in can recognize the round-tripped\n   * content and preserve Plot's formatted version. See\n   * {@link NoteWriteBackResult} for details.\n   *\n   * @param note - The created note\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Resolve a `fileRef` action's bytes for download. Called when a user opens\n   * an attachment in Plot. Return either a redirect URL (preferred for sources\n   * that issue signed URLs, like Linear S3 or Slack permalink_public) or a\n   * streamed body (required when bytes are only reachable through an\n   * authenticated API call, like Gmail attachments.get).\n   *\n   * @param ref Opaque value the connector previously emitted on a fileRef action.\n   * @returns Either `{ redirectUrl }` or `{ body, mimeType, fileName? }`.\n   * @throws If the source is unavailable, the connection is broken, or `ref` is invalid.\n   *\n   * If not overridden, fileRef actions on this connector's notes will return 410 Gone.\n   */\n  async downloadAttachment(\n    ref: string,\n  ): Promise<\n    | { redirectUrl: string }\n    | { body: ReadableStream | Uint8Array; mimeType: string; fileName?: string }\n  > {\n    throw new Error(\n      `downloadAttachment not implemented for ${this.constructor.name} (ref=${ref})`,\n    );\n  }\n\n  /**\n   * Called when a note on a thread owned by this connector is updated.\n   * Override to write back changes to the external service\n   * (e.g., syncing reaction tags as emoji reactions, or editing a comment\n   * whose content changed in Plot).\n   *\n   * Return a {@link NoteWriteBackResult} with `externalContent` to update\n   * the sync baseline after a successful write-back, so the next sync-in\n   * recognizes the external version as already-seen and preserves Plot's\n   * content.\n   *\n   * @param note - The updated note (includes current tags)\n   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)\n   * @returns Optional NoteWriteBackResult for baseline tracking\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user reads or unreads a thread owned by this connector.\n   * Override to write back read status to the external service\n   * (e.g., marking an email as read in Gmail).\n   *\n   * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)\n   * @param actor - The user who performed the action\n   * @param unread - false when marked as read, true when marked as unread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user adds, removes, or changes the role of contacts on a\n   * thread owned by this connector. Override on connectors whose source\n   * supports mid-thread recipient changes (Gmail, IMAP, etc.). Connectors\n   * that can't change recipients per-message (Slack, Linear) leave this as\n   * the default no-op and should also declare\n   * `LinkTypeConfig.supportsContactChanges: false`.\n   *\n   * The dispatch fires after Plot has persisted the change. Connectors are\n   * expected to reflect it on the next outbound note (e.g. building To/Cc/Bcc\n   * headers from the current `thread.contacts` × `thread.contactMeta`) — this\n   * callback is not the right place to send a standalone notification.\n   *\n   * @param thread - The thread whose contacts changed\n   * @param changes - The added/removed contacts and any role transitions on existing contacts\n   */\n  /* eslint-disable @typescript-eslint/no-unused-vars */\n  onContactsChanged(\n    thread: Thread,\n    changes: {\n      added: Array<{ contact: Contact; role: string }>;\n      removed: Array<{ contact: Contact; role: string }>;\n      changed: Array<{ contact: Contact; from: string; to: string }>;\n    },\n  ): Promise<void> {\n    return Promise.resolve();\n  }\n  /* eslint-enable @typescript-eslint/no-unused-vars */\n\n  /**\n   * Called when a user marks or unmarks a thread as todo.\n   * Override to sync todo status to the external service\n   * (e.g., starring an email in Gmail when marked as todo).\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param actor - The user who changed the todo status\n   * @param todo - true when marked as todo, false when done or removed\n   * @param options - Additional context\n   * @param options.date - The todo date (when todo=true)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a schedule contact's RSVP status changes on a thread owned by this connector.\n   * Override to sync RSVP changes back to the external calendar.\n   *\n   * @param thread - The thread (includes thread.meta with connector-specific data)\n   * @param scheduleId - The schedule ID\n   * @param contactId - The contact whose status changed\n   * @param status - The new RSVP status ('attend', 'skip', or null)\n   * @param actor - The user who changed the status\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Called when a user adds or removes a single emoji reaction on a note\n   * (one event per `(note, actor, emoji)` state transition).\n   *\n   * Dispatch is routed to the reacting user's own connector instance via\n   * `twist_instance_for_actor` on `note_reaction.actor_id`, so this method\n   * already runs under the reactor's auth. Fetch the API client with the\n   * connector's normal token-fetch path (`this.tools.integrations.get(...)`)\n   * and the external write — e.g. Slack `reactions.add` — will be attributed\n   * to the correct user. No `actAs` step required.\n   *\n   * If the reacting user has no connection of this type, no dispatch fires\n   * for that reaction (it stays in Plot only).\n   *\n   * Override to sync per-actor reactions back to the external system.\n   *\n   * @param note  - The note that was reacted on (partial; `id`, `key`, `content` populated)\n   * @param thread - The thread the note belongs to (partial; `id`, `title`, `archived`, `meta` populated)\n   * @param actor - The contact who added/removed the reaction\n   * @param emoji - The emoji (Unicode grapheme or `provider:workspace/name` custom-emoji ref)\n   * @param added - `true` if the reaction is now present, `false` if it was removed\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  onNoteReactionChanged(note: Note, thread: Thread, actor: Actor, emoji: string, added: boolean): Promise<void> {\n    return Promise.resolve();\n  }\n\n  // ---- Activation ----\n\n  /**\n   * Called when the connector is activated after OAuth is complete.\n   *\n   * Connectors receive the authorization in addition to the activating actor.\n   * When this runs, `this.userId` is already populated with the installing\n   * user's ID.\n   *\n   * Default implementation does nothing. Override for custom setup.\n   *\n   * @param context - The activation context\n   * @param context.auth - The completed OAuth authorization\n   * @param context.actor - The actor who activated the connector\n   */\n  // @ts-ignore - Connector.activate() has a Connector-specific context type.\n  activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\n/** @deprecated Use `Connector` instead. */\nexport { Connector as Source };\n";

package/src/llm-docs/plot.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, focuses, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Focus, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewFocus)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewFocus\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for focuses.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a focus within Plot.\n *\n * A focus is similar to a project or area-of-life. All Activity is in a Focus.\n * Focuses are flat — they have no parent and no children. Threads not matched\n * to any focus live in the Inbox.\n */\nexport type Focus = {\n  /** Unique identifier for the focus */\n  id: Uuid;\n  /** Human-readable title for the focus */\n  title: string;\n  /** Whether this focus has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this focus.\n   * Keys are unique per user.\n   */\n  key: string | null;\n  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */\n  color: ThemeColor | null;\n  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */\n  icon: string | null;\n};\n\n/**\n * Type for creating new focuses.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the focus\n * - Provide a key for upsert within the user's focuses\n * - Omit both to auto-generate a new UUID\n */\nexport type NewFocus = Pick<Focus, \"title\"> &\n  Partial<Omit<Focus, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the focus, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert focuses.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the focus within the user's focuses.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot focus.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  );\n\n/**\n * Type for updating existing focuses.\n * Must provide either id or key to identify the focus to update.\n */\nexport type FocusUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Focus, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Reference to an attachment hosted by a connector's source system */\n  fileRef = \"fileRef\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n  /** Structured plan of operations for user approval */\n  plan = \"plan\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Reference to an attachment hosted by a connector's source system */\n      type: ActionType.fileRef;\n      /** Opaque identifier interpreted only by the owning connector */\n      ref: string;\n      /** Display filename */\n      fileName: string;\n      /** File size in bytes if known */\n      fileSize: number | null;\n      /** MIME type */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    }\n  | {\n      /** Structured plan of operations for user approval */\n      type: ActionType.plan;\n      /** Human-readable summary of the plan */\n      title: string;\n      /** Operations to execute on approval */\n      operations: PlanOperation[];\n      /** Callback invoked with (action, approved: boolean) */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Thread sub-type that determines the thread's icon and category.\n * Available types depend on whether the focus is shared:\n * - Private focuses: \"action\" (default for tasks), \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared focuses: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"action\"\n  | \"notes\"\n  | \"idea\"\n  | \"goal\"\n  | \"decision\"\n  | \"discussion\"\n  | \"announcement\"\n  | \"ask\";\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * A single emoji reaction key. Either:\n * - A Unicode emoji grapheme cluster (e.g. `\"👍\"`, `\"👨‍👩‍👧\"`), or\n * - A provider-scoped custom-emoji ref of the form\n *   `\"<provider>:<workspaceId>/<name>\"` (e.g. `\"slack:T0123/party_parrot\"`).\n *\n * Anything matching a known provider prefix is treated as a custom-emoji\n * reference; everything else is rendered as the Unicode it contains.\n *\n * Reactions are the open-set counterpart to {@link Tag}'s count range\n * (`1000+`). Use reactions for emoji that round-trip with chat platforms;\n * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,\n * ...).\n */\nexport type Reaction = string;\n\n/**\n * Emoji reactions on an item, keyed by emoji string, with the list of\n * actors who added each reaction.\n */\nexport type Reactions = Record<Reaction, ActorId[]>;\n\n/**\n * A set of reactions to add to an item, along with the actors adding each\n * reaction. To remove a reaction for a given actor, omit them from the\n * `NewActor[]` list — passing an empty list removes the reaction entirely.\n */\nexport type NewReactions = Record<Reaction, NewActor[]>;\n\n/**\n * Thread access level determining visibility.\n * - \"public\": Visible to all users with focus access\n * - \"members\": Visible to focus members (default for shared focuses)\n * - \"private\": Visible only to creator and contacts listed in accessContacts\n */\nexport type ThreadAccessLevel = \"public\" | \"members\" | \"private\";\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /**\n   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or\n   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs\n   * who reacted with it.\n   */\n  reactions: Reactions;\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The focus context this thread belongs to */\n  focus: Focus;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** Thread access level: \"public\", \"members\", or \"private\" */\n  access: ThreadAccessLevel;\n  /** Contacts who can see a private thread (empty array for creator-only). Only meaningful when access is \"private\". */\n  accessContacts: Contact[];\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"focus\" | \"tags\" | \"reactions\" | \"id\" | \"accessContacts\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  {\n    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */\n    focus?: Pick<Focus, \"id\">;\n  } & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the new thread.\n     * Each emoji maps to the list of actors who reacted with it.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * The thread's sub-type/category. Sets the thread's icon.\n     * If omitted, defaults to \"notes\" (private) or \"discussion\" (shared).\n     */\n    type?: ThreadType;\n\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the focus at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"access\" | \"archived\">\n> & {\n  /** Contacts who can see a private thread. Pass NewContact objects (email-based); resolved by the API. */\n  accessContacts?: NewContact[];\n};\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to\n   * remove a reaction entirely; omit an emoji to leave it untouched.\n   */\n  reactions?: NewReactions;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Update the thread's sub-type/category.\n   */\n  type?: ThreadType;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n\n  /**\n   * Move the thread to a different focus. Requires ThreadAccess.Full.\n   * The target focus must be owned by the twist's user.\n   */\n  focus?: Pick<Focus, \"id\">;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread + link.\n   * Can be used to upsert without knowing the id.\n   *\n   * Note keys are scoped to a `(thread, link)` pair — two links on the same\n   * thread (e.g. after a merge) can each carry a `\"description\"` note without\n   * colliding. The runtime infers the link from the surrounding `saveLink`\n   * call. For bare `saveNote` calls outside a `saveLink`, the runtime\n   * resolves the link by looking up the connector's links on the thread\n   * and errors if more than one matches.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n  /**\n   * Contacts who can see this note, or null if the note inherits thread visibility.\n   * When set (even to []), the note is private to the listed contacts plus the creator.\n   */\n  accessContacts: ActorId[] | null;\n  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */\n  mentions: ActorId[];\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"reactions\" | \"mentions\" | \"accessContacts\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Contacts who can see this note, or null/undefined to inherit thread visibility.\n     * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).\n     * Include all participants who should see the note (sender + recipients).\n     * The note author is NOT implicitly included — add them explicitly.\n     * When set (even to []), the note is private to the listed contacts plus the creator.\n     */\n    accessContacts?: (ActorId | NewContact)[] | null;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the focus at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * When true, the server will use AI to detect tasks in this note's content\n     * and create separate Plot-authored reply notes for each detected task.\n     * Use for messaging connectors (email, chat) where tasks are implicit\n     * in conversation rather than explicitly structured.\n     */\n    checkForTasks?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"accessContacts\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * A resolved contact with identity info. Used for access control lists\n * where only human contacts (not twists) are relevant.\n */\nexport type Contact = {\n  /** Unique identifier for the contact */\n  id: ActorId;\n  /** Email address, or null if not set */\n  email: string | null;\n  /** Display name, or null if not set */\n  name: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\n/**\n * Common fields shared by all NewContact variants.\n */\ntype NewContactBase = {\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   *\n   * The runtime scopes the resulting `contact_external_account` row to\n   * the dispatching twist instance (i.e. one row per connection per\n   * contact), so the same Plot contact can have multiple rows when\n   * reachable through multiple connections (e.g. two Slack workspaces,\n   * Gmail + Google Chat sharing one Google account).\n   */\n  source?: { accountId: string };\n  /**\n   * Optional connector-defined role for this contact on the thread, matching\n   * a `LinkTypeConfig.contactRoles[].id` (e.g. \"to\" / \"cc\" / \"bcc\" for\n   * email, \"required\" / \"optional\" for calendar). Omitted ⇒ default role.\n   * Connectors set this on inbound sync; the runtime persists it under\n   * `thread.contact_meta[contact_id].role`.\n   */\n  role?: string;\n};\n\n/**\n * At least one of `email` or `name` must be provided so the contact can be\n * identified in the UI. Contacts with neither would display as \"Unknown\".\n */\nexport type NewContact = NewContactBase &\n  ({ email: string; name?: string } | { email?: string; name: string });\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n  /**\n   * Cross-connector thread bundling key.\n   *\n   * @deprecated Use `sources` instead. Reads return the first element of\n   * `sources` for backward compatibility; new writes should populate `sources`.\n   */\n  relatedSource: string | null;\n  /**\n   * Canonical identifiers for this link. Two links whose `sources` arrays\n   * overlap share the same thread (array overlap, `sources && new.sources`).\n   *\n   * Use this to bundle with another connector via a canonical alias. For\n   * example, every calendar connector emits `icaluid:<iCalUID>` so any\n   * meeting-notes connector can bundle by setting the same alias.\n   */\n  sources: string[];\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = Partial<\n  Omit<Link, \"author\" | \"assignee\" | \"threadId\">\n> & {\n  /**\n   * Canonical ID for the item in an external system.\n   * When set, uniquely identifies the link for the user. This performs\n   * an upsert.\n   *\n   * @deprecated Pass `sources: [...]` instead. Both fields can be set during\n   * the transition; the runtime will normalize.\n   */\n  source?: string;\n  /**\n   * Canonical identifiers for this item. Any element shared with another\n   * link's `sources` bundles the two links into the same thread. Used for\n   * cross-connector bundling — e.g. a meeting-notes connector setting\n   * `[\"granola:<id>\", \"icaluid:<uid>\"]` to attach onto a calendar event\n   * thread that includes `icaluid:<uid>` in its own `sources`.\n   */\n  sources?: string[];\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Thread access level: \"public\", \"members\" (default), or \"private\".\n     * When \"private\", thread visibility is limited to the creator and contacts in accessContacts.\n     */\n    access?: ThreadAccessLevel;\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the focus at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Explicit focus (disables automatic focus matching).\n     * Only used when the link creates a new thread. When omitted, the\n     * server classifies the thread using the user's focus rules.\n     */\n    focus?: Pick<Focus, \"id\">;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * Omit to preserve the existing title (e.g. for cancelled events where the\n   * title may not be available in the webhook payload).\n   */\n  title?: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n};\n\n/**\n * Type for updating existing links.\n *\n * Set `threadId` to move the link to a different thread.\n * Requires LinkAccess.Full.\n */\nexport type LinkUpdate = { id: Uuid } & {\n  /** Move the link to a different thread owned by the twist's user. */\n  threadId?: Uuid;\n};\n\n/**\n * A single operation within a plan submitted for user approval.\n *\n * Operations include display metadata (titles) so the app can render\n * a human-readable summary without additional lookups.\n */\nexport type PlanOperation =\n  | {\n      type: \"updateThread\";\n      threadId: Uuid;\n      /** Current thread title for display */\n      threadTitle: string;\n      changes: Partial<Pick<ThreadFields, \"archived\" | \"title\" | \"type\">> & {\n        /** Move to this focus */\n        focus?: { id: Uuid; title: string };\n      };\n    }\n  | {\n      type: \"updateLink\";\n      linkId: Uuid;\n      /** Current link title for display */\n      linkTitle: string;\n      changes: {\n        /** Move to this thread */\n        threadId?: Uuid;\n        threadTitle?: string;\n      };\n    }\n  | {\n      type: \"createThread\";\n      title: string;\n      focusId: Uuid;\n      /** Focus title for display */\n      focusTitle: string;\n    }\n  | {\n      type: \"createNote\";\n      threadId: Uuid;\n      /** Thread title for display */\n      threadTitle: string;\n      content: string;\n    }\n  | {\n      type: \"updateFocus\";\n      focusId: Uuid;\n      /** Current focus title for display */\n      focusTitle: string;\n      changes: Partial<Pick<Focus, \"title\" | \"archived\">>;\n    };\n";
+export default "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type JSONValue } from \"./utils/types\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\nexport { type JSONValue } from \"./utils/types\";\nexport { type AuthProvider } from \"./tools/integrations\";\n\n/**\n * @fileoverview\n * Core Plot entity types for working with threads, notes, focuses, and contacts.\n *\n * ## Type Pattern: Null vs Undefined Semantics\n *\n * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:\n *\n * ### Entity Types (Thread, Focus, Note, Actor)\n * - **Required fields**: No `?`, cannot be `undefined`\n *   - Example: `id: Uuid`, `title: string`\n * - **Nullable fields**: Use `| null` to allow explicit clearing\n *   - Example: `assignee: ActorId | null`, `done: Date | null`\n *   - `null` = field is explicitly unset/cleared\n *   - Non-null value = field has a value\n * - **Optional nullable fields**: Use `?` with `| null` for permission-based access\n *   - Example: `email?: string | null`, `name?: string | null`\n *   - `undefined` = field not included (e.g., no permission to access)\n *   - `null` = field included but not set\n *   - Value = field has a value\n *\n * ### New* Types (NewThread, NewNote, NewFocus)\n * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:\n * - **Required fields**: Must be provided (no `?`)\n *   - Example: `title: string` in NewFocus\n * - **Optional fields**: Use `?` to make them optional\n *   - Example: `title?: string`, `author?: NewActor`\n *   - `undefined` (omitted) = don't set/update this field\n *   - Provided value = set/update this field\n * - **Optional nullable fields**: Use `?` with `| null` to support clearing\n *   - Example: `assignee?: NewActor | null`\n *   - `undefined` (omitted) = don't change assignee\n *   - `null` = clear the assignee\n *   - NewActor = set/update the assignee\n *\n * This pattern allows API consumers to:\n * 1. Omit fields they don't want to change (undefined)\n * 2. Explicitly clear fields by setting to null\n * 3. Set or update fields by providing values\n *\n * @example\n * ```typescript\n * // Creating a new thread\n * const newThread: NewThread = {\n *   title: \"Review pull request\",\n * };\n *\n * // Updating a thread - only change what's specified\n * const update: ThreadUpdate = {\n *   id: threadId,\n *   archived: true,\n * };\n * ```\n */\n\n/**\n * Represents a unique user, contact, or twist in Plot.\n *\n * ActorIds are used throughout Plot for:\n * - Activity authors and assignees\n * - Tag creators (actor_id in activity_tag/note_tag)\n * - Mentions in activities and notes\n * - Any entity that can perform actions in Plot\n */\nexport type ActorId = string & { readonly __brand: \"ActorId\" };\n\n/**\n * Theme colors for focuses.\n */\nexport enum ThemeColor {\n  /** Catalyst - Green */\n  Catalyst = 0,\n  /** Call to Adventure - Blue */\n  CallToAdventure = 1,\n  /** Rising Action - Purple */\n  RisingAction = 2,\n  /** Momentum - Pink-Purple */\n  Momentum = 3,\n  /** Turning Point - Pink */\n  TurningPoint = 4,\n  /** Breakthrough - Orange */\n  Breakthrough = 5,\n  /** Climax - Olive */\n  Climax = 6,\n  /** Resolution - Blue-Gray */\n  Resolution = 7,\n}\n\n/**\n * Represents a focus within Plot.\n *\n * A focus is similar to a project or area-of-life. All Activity is in a Focus.\n * Focuses are flat — they have no parent and no children. Threads not matched\n * to any focus live in the Inbox.\n */\nexport type Focus = {\n  /** Unique identifier for the focus */\n  id: Uuid;\n  /** Human-readable title for the focus */\n  title: string;\n  /** Whether this focus has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this focus.\n   * Keys are unique per user.\n   */\n  key: string | null;\n  /** Optional theme color for the focus (0-7). Defaults to 7 (Resolution) when not set. */\n  color: ThemeColor | null;\n  /** Optional icon for the focus (a curated icon key). Defaults to the focus icon when not set. */\n  icon: string | null;\n};\n\n/**\n * Type for creating new focuses.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the focus\n * - Provide a key for upsert within the user's focuses\n * - Omit both to auto-generate a new UUID\n */\nexport type NewFocus = Pick<Focus, \"title\"> &\n  Partial<Omit<Focus, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the focus, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert focuses.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the focus within the user's focuses.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot focus.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  );\n\n/**\n * Type for updating existing focuses.\n * Must provide either id or key to identify the focus to update.\n */\nexport type FocusUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Focus, \"title\" | \"archived\">>;\n\n/**\n * Enumeration of supported action types.\n *\n * Different action types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActionType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback actions that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\n  /** File attachment links stored in R2 */\n  file = \"file\",\n  /** Reference to an attachment hosted by a connector's source system */\n  fileRef = \"fileRef\",\n  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\n  /** Structured plan of operations for user approval */\n  plan = \"plan\",\n}\n\n/**\n * Video conferencing providers for conferencing links.\n *\n * Used to identify the conferencing platform and provide\n * provider-specific UI elements (titles, icons, etc.).\n */\nexport enum ConferencingProvider {\n  /** Google Meet */\n  googleMeet = \"googleMeet\",\n  /** Zoom */\n  zoom = \"zoom\",\n  /** Microsoft Teams */\n  microsoftTeams = \"microsoftTeams\",\n  /** Cisco Webex */\n  webex = \"webex\",\n  /** Other or unknown conferencing provider */\n  other = \"other\",\n}\n\n/**\n * Represents a clickable action attached to a thread.\n *\n * Thread actions are rendered as buttons that enable user interaction with threads.\n * Different action types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External action - opens URL in browser\n * const externalAction: Action = {\n *   type: ActionType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing action - opens video conference with provider info\n * const conferencingAction: Action = {\n *   type: ActionType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations action - initiates OAuth flow\n * const authAction: Action = {\n *   type: ActionType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback action - triggers a twist method\n * const callbackAction: Action = {\n *   type: ActionType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type Action =\n  | {\n      /** External web link that opens in browser */\n      type: ActionType.external;\n      /** Display text for the action button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing action with provider-specific handling */\n      type: ActionType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication action that initiates an OAuth flow */\n      type: ActionType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Array of OAuth scopes to request */\n      scopes: string[];\n      /** Callback token for auth completion notification */\n      callback: Callback;\n    }\n  | {\n      /** Callback action that triggers a twist method when clicked */\n      type: ActionType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    }\n  | {\n      /** File attachment action stored in R2 */\n      type: ActionType.file;\n      /** Unique identifier for the stored file */\n      fileId: string;\n      /** Original filename */\n      fileName: string;\n      /** File size in bytes */\n      fileSize: number;\n      /** MIME type of the file */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Reference to an attachment hosted by a connector's source system */\n      type: ActionType.fileRef;\n      /** Opaque identifier interpreted only by the owning connector */\n      ref: string;\n      /** Display filename */\n      fileName: string;\n      /** File size in bytes if known */\n      fileSize: number | null;\n      /** MIME type */\n      mimeType: string;\n      /** Intrinsic width of the image in pixels (only for image files) */\n      imageWidth?: number | null;\n      /** Intrinsic height of the image in pixels (only for image files) */\n      imageHeight?: number | null;\n    }\n  | {\n      /** Thread reference action for navigating to a related thread */\n      type: ActionType.thread;\n      /** UUID of the referenced thread */\n      threadId: Uuid;\n    }\n  | {\n      /** Structured plan of operations for user approval */\n      type: ActionType.plan;\n      /** Human-readable summary of the plan */\n      title: string;\n      /** Operations to execute on approval */\n      operations: PlanOperation[];\n      /** Callback invoked with (action, approved: boolean) */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about a thread, typically from an external system.\n *\n * Thread metadata enables storing additional information about threads,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).\n * Functions and other non-JSON values are not supported.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createThread({\n *   title: \"Team Meeting\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\",\n *     conferenceData: { ... }\n *   }\n * });\n *\n * // Project issue metadata\n * await plot.createThread({\n *   title: \"Fix login bug\",\n *   meta: {\n *     projectId: \"TEAM\",\n *     issueNumber: 123,\n *     url: \"https://linear.app/team/issue/TEAM-123\"\n *   }\n * });\n * ```\n */\nexport type ThreadMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: JSONValue;\n};\n\n/**\n * Thread sub-type that determines the thread's icon and category.\n * Available types depend on whether the focus is shared:\n * - Private focuses: \"action\" (default for tasks), \"notes\" (default), \"idea\", \"goal\", \"decision\"\n * - Shared focuses: all above plus \"discussion\" (default), \"announcement\", \"ask\"\n */\nexport type ThreadType =\n  | \"action\"\n  | \"notes\"\n  | \"idea\"\n  | \"goal\"\n  | \"decision\"\n  | \"discussion\"\n  | \"announcement\"\n  | \"ask\";\n\n/**\n * Tags on an item, along with the actors who added each tag.\n */\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * A set of tags to add to an item, along with the actors adding each tag.\n */\nexport type NewTags = { [K in Tag]?: NewActor[] };\n\n/**\n * A single emoji reaction key. Either:\n * - A Unicode emoji grapheme cluster (e.g. `\"👍\"`, `\"👨‍👩‍👧\"`), or\n * - A provider-scoped custom-emoji ref of the form\n *   `\"<provider>:<workspaceId>/<name>\"` (e.g. `\"slack:T0123/party_parrot\"`).\n *\n * Anything matching a known provider prefix is treated as a custom-emoji\n * reference; everything else is rendered as the Unicode it contains.\n *\n * Reactions are the open-set counterpart to {@link Tag}'s count range\n * (`1000+`). Use reactions for emoji that round-trip with chat platforms;\n * use tags for Plot-managed compute/toggle state (todo, pinned, urgent,\n * ...).\n */\nexport type Reaction = string;\n\n/**\n * Emoji reactions on an item, keyed by emoji string, with the list of\n * actors who added each reaction.\n */\nexport type Reactions = Record<Reaction, ActorId[]>;\n\n/**\n * A set of reactions to add to an item, along with the actors adding each\n * reaction. To remove a reaction for a given actor, omit them from the\n * `NewActor[]` list — passing an empty list removes the reaction entirely.\n */\nexport type NewReactions = Record<Reaction, NewActor[]>;\n\n/**\n * Thread access level determining visibility.\n * - \"public\": Visible to all users with focus access\n * - \"members\": Visible to focus members (default for shared focuses)\n * - \"private\": Visible only to creator and contacts listed in accessContacts\n */\nexport type ThreadAccessLevel = \"public\" | \"members\" | \"private\";\n\n/**\n * Common fields shared by both Thread and Note entities.\n */\nexport type ThreadCommon = {\n  /** Unique identifier for the thread */\n  id: Uuid;\n  /**\n   * When this item was created.\n   *\n   * **For sources:** Set this to the external system's timestamp (e.g., email\n   * sent date, comment creation date), NOT the sync time. If omitted, defaults\n   * to the current time, which is almost never correct for synced data.\n   */\n  created: Date;\n  /** Whether this thread has been archived */\n  archived: boolean;\n  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags;\n  /**\n   * Emoji reactions on this item. Maps each emoji (Unicode grapheme or\n   * `provider:workspace/name` custom-emoji ref) to the list of actor IDs\n   * who reacted with it.\n   */\n  reactions: Reactions;\n};\n\n/**\n * Fields on a Thread entity.\n * Threads are simple containers for links and notes.\n */\ntype ThreadFields = ThreadCommon & {\n  /** The display title/summary of the thread */\n  title: string;\n  /** The focus context this thread belongs to */\n  focus: Focus;\n  /** The thread's sub-type/category. Determines the displayed icon. */\n  type: ThreadType | null;\n  /** Thread access level: \"public\", \"members\", or \"private\" */\n  access: ThreadAccessLevel;\n  /** Contacts who can see a private thread (empty array for creator-only). Only meaningful when access is \"private\". */\n  accessContacts: Contact[];\n  /** The schedule associated with this thread, if any */\n  schedule?: Schedule;\n  /** Source-specific metadata from the thread's link, populated on callbacks */\n  meta?: ThreadMeta;\n};\n\nexport type Thread = ThreadFields;\n\nexport type ThreadWithNotes = Thread & {\n  notes: Note[];\n};\n\nexport type NewThreadWithNotes = NewThread & {\n  notes: Omit<NewNote, \"thread\">[];\n};\n\n/**\n * Type for creating new threads.\n *\n * Threads are simple containers. All other fields are optional.\n *\n * @example\n * ```typescript\n * const thread: NewThread = {\n *   title: \"Review pull request\"\n * };\n * ```\n */\nexport type NewThread = Partial<\n  Omit<ThreadFields, \"focus\" | \"tags\" | \"reactions\" | \"id\" | \"accessContacts\">\n> &\n  (\n    | {\n        /** Unique identifier for the thread, generated by Uuid.Generate(). */\n        id: Uuid;\n      }\n    | {\n        /* id is optional. An id will be generated and returned. */\n      }\n  ) &\n  {\n    /** Explicit focus - disables automatic focus matching. When omitted, the server classifies the thread using the user's focus rules. */\n    focus?: Pick<Focus, \"id\">;\n  } & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the new thread.\n     * Each emoji maps to the list of actors who reacted with it.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * The thread's sub-type/category. Sets the thread's icon.\n     * If omitted, defaults to \"notes\" (private) or \"discussion\" (shared).\n     */\n    type?: ThreadType;\n\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\n\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the focus at creation time\n     */\n    unread?: boolean;\n\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n\n    /**\n     * Optional preview content for the thread. Can be Markdown formatted.\n     * The preview will be automatically generated from this content (truncated to 100 chars).\n     */\n    preview?: string | null;\n\n    /**\n     * Optional schedules to create alongside the thread.\n     */\n    schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n\n    /**\n     * Optional schedule occurrence overrides.\n     */\n    scheduleOccurrences?: NewScheduleOccurrence[];\n  };\n\nexport type ThreadFilter = {\n  meta?: {\n    [key: string]: JSONValue;\n  };\n};\n\n/**\n * Fields supported by bulk updates via `match`. Only simple scalar fields\n * that can be applied uniformly across many threads are included.\n */\ntype ThreadBulkUpdateFields = Partial<\n  Pick<ThreadFields, \"title\" | \"access\" | \"archived\">\n> & {\n  /** Contacts who can see a private thread. Pass NewContact objects (email-based); resolved by the API. */\n  accessContacts?: NewContact[];\n};\n\n/**\n * Fields supported by single-thread updates via `id` or `source`.\n * Includes all bulk fields plus tags and preview.\n */\ntype ThreadSingleUpdateFields = ThreadBulkUpdateFields & {\n  /**\n   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n   */\n  tags?: NewTags;\n\n  /**\n   * Emoji reactions to change on the thread. Pass an empty `NewActor[]` to\n   * remove a reaction entirely; omit an emoji to leave it untouched.\n   */\n  reactions?: NewReactions;\n\n  /**\n   * Add or remove the twist's tags.\n   * Maps tag ID to boolean: true = add tag, false = remove tag.\n   * This is allowed on all threads the twist has access to.\n   */\n  twistTags?: Partial<Record<Tag, boolean>>;\n\n  /**\n   * Update the thread's sub-type/category.\n   */\n  type?: ThreadType;\n\n  /**\n   * Optional preview content for the thread. Can be Markdown formatted.\n   * The preview will be automatically generated from this content (truncated to 100 chars).\n   *\n   * - string: Use this content for preview generation\n   * - null: Explicitly disable preview (no preview will be shown)\n   * - undefined (omitted): Preserve current preview value\n   *\n   * This field is write-only and won't be returned when reading threads.\n   */\n  preview?: string | null;\n\n  /**\n   * Move the thread to a different focus. Requires ThreadAccess.Full.\n   * The target focus must be owned by the twist's user.\n   */\n  focus?: Pick<Focus, \"id\">;\n};\n\nexport type ThreadUpdate =\n  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)\n  | ({\n      /**\n       * Update all threads matching the specified criteria. Only threads\n       * that match all provided fields and were created by the twist will be updated.\n       */\n      match: ThreadFilter;\n    } & ThreadBulkUpdateFields);\n\n/**\n * Represents a note within a thread.\n *\n * Notes contain the detailed content (note text, actions) associated with a thread.\n * They are always ordered by creation time within their parent thread.\n */\nexport type Note = ThreadCommon & {\n  /** The author of this note */\n  author: Actor;\n  /**\n   * Globally unique, stable identifier for the note within its thread + link.\n   * Can be used to upsert without knowing the id.\n   *\n   * Note keys are scoped to a `(thread, link)` pair — two links on the same\n   * thread (e.g. after a merge) can each carry a `\"description\"` note without\n   * colliding. The runtime infers the link from the surrounding `saveLink`\n   * call. For bare `saveNote` calls outside a `saveLink`, the runtime\n   * resolves the link by looking up the connector's links on the thread\n   * and errors if more than one matches.\n   *\n   * Use one of these patterns:\n   *   - Hardcoded semantic keys for fixed note types: \"description\", \"cancellation\"\n   *   - External service IDs for dynamic collections: `comment:${immutableId}`\n   *\n   * Examples:\n   *   - `\"description\"` (for a Jira issue's description note)\n   *   - `\"comment:12345\"` (for a specific comment by ID)\n   *   - `\"gmail:msg:18d4e5f2a3b1c9d7\"` (for a Gmail message within a thread)\n   *\n   * Ensure IDs are immutable - avoid human-readable slugs or titles.\n   */\n  key: string | null;\n  /** The parent thread this note belongs to */\n  thread: Thread;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive actions attached to the note */\n  actions: Array<Action> | null;\n  /** The note this is a reply to, or null if not a reply */\n  reNote: { id: Uuid } | null;\n  /**\n   * Contacts who can see this note, or null if the note inherits thread visibility.\n   * When set (even to []), the note is private to the listed contacts plus the creator.\n   */\n  accessContacts: ActorId[] | null;\n  /** Focus twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */\n  mentions: ActorId[];\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the thread reference, with all other fields optional.\n * Can provide id, key, or neither for note identification:\n * - id: Provide a specific UUID for the note\n * - key: Provide an external identifier for upsert within the thread\n * - neither: A new note with auto-generated UUID will be created\n */\nexport type NewNote = Partial<\n  Omit<\n    Note,\n    \"author\" | \"thread\" | \"tags\" | \"reactions\" | \"mentions\" | \"accessContacts\" | \"id\" | \"key\" | \"reNote\"\n  >\n> &\n  ({ id: Uuid } | { key: string } | {}) & {\n    /** Reference to the parent thread (required) */\n    thread:\n      | Pick<Thread, \"id\">\n      | {\n          source: string;\n        };\n\n    /**\n     * The person that created the item, or leave undefined to use the twist as author.\n     */\n    author?: NewActor;\n\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to set on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Contacts who can see this note, or null/undefined to inherit thread visibility.\n     * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).\n     * Include all participants who should see the note (sender + recipients).\n     * The note author is NOT implicitly included — add them explicitly.\n     * When set (even to []), the note is private to the listed contacts plus the creator.\n     */\n    accessContacts?: (ActorId | NewContact)[] | null;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\n     */\n    mentions?: NewActor[];\n\n    /**\n     * Whether the note should mark the parent thread as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - true: Thread is explicitly unread for ALL users (use sparingly)\n     * - false: Thread is marked as read for all users in the focus at note creation time\n     *\n     * For the default behavior, omit this field entirely.\n     * Use false for initial sync to avoid marking historical items as unread.\n     */\n    unread?: boolean;\n\n    /**\n     * When true, the server will use AI to detect tasks in this note's content\n     * and create separate Plot-authored reply notes for each detected task.\n     * Use for messaging connectors (email, chat) where tasks are implicit\n     * in conversation rather than explicitly structured.\n     */\n    checkForTasks?: boolean;\n\n    /**\n     * Reference to a parent note this note is a reply to.\n     * - `{ id }`: reply by UUID\n     * - `{ key }`: reply by key, resolved after creation (for batch ops)\n     * - `null`: explicitly not a reply\n     * - `undefined` (omitted): not a reply\n     */\n    reNote?: { id: Uuid } | { key: string } | null;\n\n    /**\n     * A link carried by this note (note-attached, NOT a thread-level canonical\n     * link). Use for augmenter content (e.g. Granola meeting notes) that should\n     * attach to an existing canonical thread without becoming its primary link.\n     * The runtime creates the link note-scoped, binds `note.link_id` to it, and\n     * — when `thread: { source }` resolves to no existing thread — find-or-creates\n     * the thread by that source so a later canonical sync can fill the primary.\n     */\n    link?: NewLink;\n  };\n\n/**\n * Type for updating existing notes.\n * Must provide either id or key to identify the note to update.\n */\nexport type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &\n  Partial<\n    Pick<Note, \"accessContacts\" | \"archived\" | \"content\" | \"actions\" | \"reNote\">\n  > & {\n    /**\n     * Format of the note content. Determines how the note is processed:\n     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)\n     * - 'markdown': Already in markdown format (default, no conversion)\n     * - 'html': HTML content that will be converted to markdown\n     */\n    contentType?: ContentType;\n\n    /**\n     * Tags to change on the note. Use an empty array of NewActor to remove a tag.\n     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.\n     */\n    tags?: NewTags;\n\n    /**\n     * Emoji reactions to change on the note. Pass an empty `NewActor[]` to\n     * remove a reaction entirely; omit an emoji to leave it untouched.\n     */\n    reactions?: NewReactions;\n\n    /**\n     * Add or remove the twist's tags.\n     * Maps tag ID to boolean: true = add tag, false = remove tag.\n     * This is allowed on all notes the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n\n    /**\n     * Twist/connector IDs to mention for dispatch routing.\n     * Does not include user contacts — use accessContacts for visibility.\n     */\n    mentions?: NewActor[];\n  };\n\n/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with threads as authors, assignees, or mentions.\n * The email field is only included when ContactAccess.Read permission is granted.\n *\n * @example\n * ```typescript\n * const actor: Actor = {\n *   id: \"f0ffd5f8-1635-4b13-9532-35f97446db90\" as ActorId,\n *   type: ActorType.Contact,\n *   email: \"john.doe@example.com\",  // Only if ContactAccess.Read\n *   name: \"John Doe\"\n * };\n * ```\n */\nexport type Actor = {\n  /** Unique identifier for the actor */\n  id: ActorId;\n  /** Type of actor (User, Contact, or Twist) */\n  type: ActorType;\n  /**\n   * Email address (only included with ContactAccess.Read permission).\n   * - `undefined`: No permission to read email\n   * - `null`: Permission granted but email not set\n   * - `string`: Email address\n   */\n  email?: string | null;\n  /**\n   * Display name.\n   * - `undefined`: Not included due to permissions\n   * - `null`: Not set\n   * - `string`: Display name\n   */\n  name?: string | null;\n};\n\n/**\n * A resolved contact with identity info. Used for access control lists\n * where only human contacts (not twists) are relevant.\n */\nexport type Contact = {\n  /** Unique identifier for the contact */\n  id: ActorId;\n  /** Email address, or null if not set */\n  email: string | null;\n  /** Display name, or null if not set */\n  name: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create threads.\n *\n * The author type affects how threads are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Threads created by human users */\n  User,\n  /** Threads created by external contacts */\n  Contact,\n  /** Threads created by automated twists */\n  Twist,\n}\n\n/**\n * Represents contact information for creating a new contact.\n *\n * Contacts are used throughout Plot for representing people associated\n * with activities, such as event attendees or task assignees.\n *\n * @example\n * ```typescript\n * const newContact: NewContact = {\n *   email: \"john.doe@example.com\",\n *   name: \"John Doe\",\n *   avatar: \"https://avatar.example.com/john.jpg\"\n * };\n * ```\n */\n/**\n * Common fields shared by all NewContact variants.\n */\ntype NewContactBase = {\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for identity resolution\n   * when email is unavailable and for privacy compliance reporting.\n   *\n   * The runtime scopes the resulting `contact_external_account` row to\n   * the dispatching twist instance (i.e. one row per connection per\n   * contact), so the same Plot contact can have multiple rows when\n   * reachable through multiple connections (e.g. two Slack workspaces,\n   * Gmail + Google Chat sharing one Google account).\n   */\n  source?: { accountId: string };\n  /**\n   * Optional connector-defined role for this contact on the thread, matching\n   * a `LinkTypeConfig.contactRoles[].id` (e.g. \"to\" / \"cc\" / \"bcc\" for\n   * email, \"required\" / \"optional\" for calendar). Omitted ⇒ default role.\n   * Connectors set this on inbound sync; the runtime persists it under\n   * `thread.contact_meta[contact_id].role`.\n   */\n  role?: string;\n};\n\n/**\n * At least one of `email` or `name` must be provided so the contact can be\n * identified in the UI. Contacts with neither would display as \"Unknown\".\n */\nexport type NewContact = NewContactBase &\n  ({ email: string; name?: string } | { email?: string; name: string });\n\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n\n/**\n * Represents an external entity linked to a thread.\n *\n * Links are created by sources to represent external entities (issues, emails, calendar events)\n * attached to a thread container. A thread can have multiple links (1:many).\n * Links store source-specific data like type, status, metadata, and embeddings.\n *\n * @example\n * ```typescript\n * // A link representing a Linear issue\n * const link: Link = {\n *   threadId: \"...\" as Uuid,\n *   source: \"linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b\",\n *   created: new Date(),\n *   author: { id: \"...\" as ActorId, type: ActorType.Contact, name: \"Alice\" },\n *   title: \"Fix login bug\",\n *   type: \"issue\",\n *   status: \"open\",\n *   meta: { projectId: \"TEAM\", url: \"https://linear.app/team/TEAM-123\" },\n *   assignee: null,\n *   actions: null,\n * };\n * ```\n */\nexport type Link = {\n  /** The thread this link belongs to */\n  threadId: Uuid;\n  /** External source identifier for dedup/upsert */\n  source: string | null;\n  /** When this link was originally created in its source system */\n  created: Date;\n  /** The actor credited with creating this link */\n  author: Actor | null;\n  /** Display title */\n  title: string;\n  /** Truncated preview */\n  preview: string | null;\n  /** The actor assigned to this link */\n  assignee: Actor | null;\n  /** Source-defined type string (e.g., issue, pull_request, email, event) */\n  type: string | null;\n  /** Source-defined status string (e.g., open, done, closed) */\n  status: string | null;\n  /** Interactive action buttons */\n  actions: Array<Action> | null;\n  /** Source metadata */\n  meta: ThreadMeta | null;\n  /** URL to open the original item in its source application (e.g., \"Open in Linear\") */\n  sourceUrl: string | null;\n  /** Channel ID that produced this link (matches source_channel.channel_id) */\n  channelId: string | null;\n  /**\n   * Cross-connector thread bundling key.\n   *\n   * @deprecated Use `sources` instead. Reads return the first element of\n   * `sources` for backward compatibility; new writes should populate `sources`.\n   */\n  relatedSource: string | null;\n  /**\n   * Canonical identifiers for this link. Two links whose `sources` arrays\n   * overlap share the same thread (array overlap, `sources && new.sources`).\n   *\n   * Use this to bundle with another connector via a canonical alias. For\n   * example, every calendar connector emits `icaluid:<iCalUID>` so any\n   * meeting-notes connector can bundle by setting the same alias.\n   */\n  sources: string[];\n  /**\n   * Connector-supplied ranking used by clients to choose the single displayed\n   * (primary) canonical link when a thread has more than one. Higher wins;\n   * ties break on earliest creation. Default 0.\n   */\n  priority: number;\n};\n\n/**\n * Type for creating new links.\n *\n * Links are created by sources to represent external entities.\n * Requires a source identifier for dedup/upsert.\n */\nexport type NewLink = Partial<\n  Omit<Link, \"author\" | \"assignee\" | \"threadId\">\n> & {\n  /**\n   * Canonical ID for the item in an external system.\n   * When set, uniquely identifies the link for the user. This performs\n   * an upsert.\n   *\n   * @deprecated Pass `sources: [...]` instead. Both fields can be set during\n   * the transition; the runtime will normalize.\n   */\n  source?: string;\n  /**\n   * Canonical identifiers for this item. Any element shared with another\n   * link's `sources` bundles the two links into the same thread. Used for\n   * cross-connector bundling — e.g. a meeting-notes connector setting\n   * `[\"granola:<id>\", \"icaluid:<uid>\"]` to attach onto a calendar event\n   * thread that includes `icaluid:<uid>` in its own `sources`.\n   */\n  sources?: string[];\n    /** The person that created the item. By default, it will be the twist itself. */\n    author?: NewActor;\n    /** The person assigned to the item. */\n    assignee?: NewActor | null;\n    /**\n     * Thread access level: \"public\", \"members\" (default), or \"private\".\n     * When \"private\", thread visibility is limited to the creator and contacts in accessContacts.\n     */\n    access?: ThreadAccessLevel;\n    /**\n     * Contacts who can see a private thread.\n     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.\n     * If omitted for a private thread, defaults to the connection owner.\n     */\n    accessContacts?: NewContact[];\n    /**\n     * Whether the thread should be marked as unread for users.\n     * - undefined/omitted (default): Thread is unread for users, except auto-marked\n     *   as read for the author if they are the twist owner (user)\n     * - false: Thread is marked as read for all users in the focus at creation time\n     */\n    unread?: boolean;\n    /**\n     * Whether the thread is archived.\n     * - true: Archive the thread\n     * - false: Unarchive the thread\n     * - undefined (default): Preserve current archive state\n     */\n    archived?: boolean;\n    /**\n     * Mark the thread as the connection owner's to-do at create time.\n     * - true: the thread is added to the owner's to-do (active) bucket and\n     *   their per-user archive is lifted, atomically with the save — no\n     *   separate `integrations.setThreadToDo()` round-trip needed.\n     * - false: the owner's thread_state is marked read (cleared from to-do).\n     * - undefined (omitted, default): leave to-do state untouched.\n     *\n     * Use for messaging-style \"saved for later\" flags (e.g. a starred Slack\n     * thread). This is the first-class replacement for overloading a\n     * `statuses[]` entry with `active: true`.\n     */\n    todo?: boolean;\n    /**\n     * The to-do date used when `todo` is true. Defaults to the \"Now\"\n     * sentinel (today's bucket) when omitted. Ignored when `todo` is not true.\n     */\n    todoDate?: Date | string;\n    /**\n     * Explicit focus (disables automatic focus matching).\n     * Only used when the link creates a new thread. When omitted, the\n     * server classifies the thread using the user's focus rules.\n     */\n    focus?: Pick<Focus, \"id\">;\n    /**\n     * Primary-link ranking for this canonical link (default 0). Set higher on\n     * the connection that \"owns\" the external item (e.g. the calendar that owns\n     * an event vs a subscribed copy) so clients display it as the primary.\n     */\n    priority?: number;\n  };\n\n/**\n * A new link with notes to save via integrations.saveLink().\n * Creates a thread+link pair, with notes attached to the thread.\n */\nexport type NewLinkWithNotes = NewLink & {\n  /**\n   * Title for the link and its thread container.\n   * Must be the real entity title (e.g. issue title, message subject),\n   * never a placeholder or ID. This value overwrites the existing title on upsert.\n   * Omit to preserve the existing title (e.g. for cancelled events where the\n   * title may not be available in the webhook payload).\n   */\n  title?: string;\n  /** Notes to attach to the thread */\n  notes?: Omit<NewNote, \"thread\">[];\n  /** Schedules to create for the link */\n  schedules?: Array<Omit<NewSchedule, \"threadId\">>;\n  /** Schedule occurrence overrides */\n  scheduleOccurrences?: NewScheduleOccurrence[];\n  /**\n   * For `onCreateLink` only: binds the thread's opening note (the message the\n   * user composed in Plot, which this hook just posted to the external system)\n   * to its external counterpart. Mirrors the `NoteWriteBackResult` a reply\n   * returns from `onNoteCreated` — `key` is the external message id and\n   * `externalContent` is the post-write content baseline. Without this the\n   * opening note stays keyless, so reactions and edits on it can't be routed\n   * back to the external system. Ignored outside `onCreateLink`.\n   */\n  originatingNote?: {\n    /** External message id; set as the opening note's `key`. */\n    key?: string;\n    /**\n     * Content as the external system stored it post-write, for the sync\n     * baseline. Must equal what your sync-in path emits as this note's\n     * `content` on re-ingest (same contract as `NoteWriteBackResult.externalContent`).\n     */\n    externalContent?: string;\n  };\n};\n\n/**\n * Type for updating existing links.\n *\n * Set `threadId` to move the link to a different thread.\n * Requires LinkAccess.Full.\n */\nexport type LinkUpdate = { id: Uuid } & {\n  /** Move the link to a different thread owned by the twist's user. */\n  threadId?: Uuid;\n};\n\n/**\n * A single operation within a plan submitted for user approval.\n *\n * Operations include display metadata (titles) so the app can render\n * a human-readable summary without additional lookups.\n */\nexport type PlanOperation =\n  | {\n      type: \"updateThread\";\n      threadId: Uuid;\n      /** Current thread title for display */\n      threadTitle: string;\n      changes: Partial<Pick<ThreadFields, \"archived\" | \"title\" | \"type\">> & {\n        /** Move to this focus */\n        focus?: { id: Uuid; title: string };\n      };\n    }\n  | {\n      type: \"updateLink\";\n      linkId: Uuid;\n      /** Current link title for display */\n      linkTitle: string;\n      changes: {\n        /** Move to this thread */\n        threadId?: Uuid;\n        threadTitle?: string;\n      };\n    }\n  | {\n      type: \"createThread\";\n      title: string;\n      focusId: Uuid;\n      /** Focus title for display */\n      focusTitle: string;\n    }\n  | {\n      type: \"createNote\";\n      threadId: Uuid;\n      /** Thread title for display */\n      threadTitle: string;\n      content: string;\n    }\n  | {\n      type: \"updateFocus\";\n      focusId: Uuid;\n      /** Current focus title for display */\n      focusTitle: string;\n      changes: Partial<Pick<Focus, \"title\" | \"archived\">>;\n    };\n";

package/src/llm-docs/tools/integrations.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   */\n  status: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";
+export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n} from \"..\";\nimport type { JSONValue } from \"../utils/types\";\nimport type { Uuid } from \"../utils/uuid\";\n\n/**\n * A resource that can be synced (e.g., a calendar, project, channel).\n * Returned by getChannels() and managed by users in the twist setup/edit modal.\n */\nexport type Channel = {\n  /** External ID shared across users (e.g., Google calendar ID) */\n  id: string;\n  /** Display name shown in the UI */\n  title: string;\n  /**\n   * Whether this channel should be selected by default when the user first\n   * adds the connection. Tri-state:\n   * - `true`  — pre-select it (e.g. the user's own/primary calendar).\n   * - `false` — exclude it from the default selection (low-value or\n   *   irrelevant resources that would crowd the user's view, or containers\n   *   whose contents are too broad to sync wholesale — e.g. a holiday or\n   *   someone-else's shared calendar, a GitHub org that cascades to every\n   *   repo, a Microsoft Teams team container). The user can still enable it\n   *   manually.\n   * - `undefined` — no opinion; the client decides. The client defaults to\n   *   enabling the channel unless its title looks low-value (holidays,\n   *   birthdays, spam/sent/draft, …).\n   *\n   * The guiding principle is \"sync everything the user would reasonably want\n   * by default\" — for most connectors that's all channels, so only set this\n   * where the connector can distinguish the user's own/relevant channels from\n   * low-value ones (e.g. Google Calendar via `accessRole === \"owner\"`).\n   */\n  enabledByDefault?: boolean;\n  /** Optional nested channel resources (e.g., subfolders) */\n  children?: Channel[];\n  /** Per-channel link type configs. Overrides twist-level linkTypes when present. */\n  linkTypes?: LinkTypeConfig[];\n};\n\n/**\n * Curated status-icon vocabulary. Connectors map each declared status to the\n * closest icon; clients render a single glyph per value. Required on every\n * status so the UI always has something to show.\n */\nexport type StatusIcon =\n  | \"backlog\"\n  | \"todo\"\n  | \"inProgress\"\n  | \"blocked\"\n  | \"done\"\n  | \"cancelled\"\n  | \"confirmed\"\n  | \"tentative\";\n\n/**\n * Describes a link type that a connector creates.\n * Used for display in the UI (icons, labels).\n */\nexport type LinkTypeConfig = {\n  /** Machine-readable type identifier (e.g., \"issue\", \"pull_request\") */\n  type: string;\n  /** Human-readable label (e.g., \"Issue\", \"Pull Request\") */\n  label: string;\n  /**\n   * Connector's word for a note on a linked item of this type — used by the\n   * Flutter app to adapt note/composer copy (\"Add a comment\" on Linear,\n   * \"Add a message\" on Slack, \"Add a reply\" on Gmail). Defaults to \"note\"\n   * when omitted. Use the singular noun in title case (e.g. \"Comment\").\n   */\n  noteLabel?: string;\n  /**\n   * Placeholder shown in the editor when this link type is the target of a\n   * new thread (NewThreadPage). Example: \"Send a Gmail email\".\n   * If unset, Plot derives \"Create a new {connector} {label.toLowerCase()}\".\n   */\n  composePlaceholder?: string;\n  /**\n   * Label for the Send button on NewThreadPage when this link type is the\n   * target. Example: \"Send\". If unset, defaults to \"Create\".\n   */\n  composeVerb?: string;\n  /**\n   * Placeholder shown in the in-thread editor for the default reply mode.\n   * Example: \"Reply\" (Gmail), \"Add a comment\" (Linear). If unset, Plot derives\n   * \"Add a {noteLabel.toLowerCase()}\" or \"Add a note\".\n   */\n  replyPlaceholder?: string;\n  /**\n   * Label for the Send button in the in-thread editor. Example: \"Send\"\n   * (Gmail), \"Comment\" (Linear). If unset, defaults to \"Send\".\n   */\n  replyVerb?: string;\n  /** URL to an icon for this link type (light mode). Prefer Iconify `logos/*` URLs. */\n  logo?: string;\n  /** URL to an icon for dark mode. Use when the default logo is invisible on dark backgrounds (e.g., Iconify `simple-icons/*` with `?color=`). */\n  logoDark?: string;\n  /** URL to a monochrome icon (uses `currentColor`). Prefer Iconify `simple-icons/*` URLs without a `?color=` param. */\n  logoMono?: string;\n  /** Possible status values for this type */\n  statuses?: Array<{\n    /** Machine-readable status (e.g., \"open\", \"done\") */\n    status: string;\n    /** Human-readable label (e.g., \"Open\", \"Done\") */\n    label: string;\n    /** Curated icon for this status (required so the UI always has a glyph). */\n    icon: StatusIcon;\n    /**\n     * Suppress this status's icon on the feed row (ThreadWidget) while still\n     * showing it in the ThreadPage header. Use for a \"resting\" default state\n     * that would otherwise clutter the feed (e.g. calendar \"Confirmed\").\n     */\n    hiddenDefault?: boolean;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n    /**\n     * Mark the thread `active=true` in Plot when a link enters this status.\n     * Use for messaging-style flags where the user has indicated they want\n     * to act on the thread now — Gmail's \"starred\", Slack's \"later\", etc.\n     * The Plot user can later un-flag the thread without breaking the\n     * connector relationship.\n     */\n    active?: boolean;\n    /**\n     * Marks this status as the connector's \"to-do\" / active state. When a\n     * user brings a done thread back into Plot's agenda, done-status links\n     * are flipped to the status marked `todo: true` (e.g. Gmail's \"starred\",\n     * Linear's \"unstarted\"); connectors that don't mark one fall back to the\n     * first non-done status.\n     */\n    todo?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: boolean;\n  /**\n   * Whether this link type produces time-anchored schedule/agenda items\n   * (i.e. calendar events). The Plot app shows the agenda (the bottom-nav\n   * tab on mobile and the left-sidebar agenda on desktop) only when the\n   * user has at least one active connection whose link types include one\n   * with `includesSchedules: true`. Calendar connectors (Google / Apple /\n   * Outlook Calendar) set this on their `event` link type. Defaults to\n   * false — non-calendar link types (messages, issues, tasks, docs) omit it.\n   */\n  includesSchedules?: boolean;\n  /** Default thread creation mode for this link type: 'all' | 'actionable' | 'manual' */\n  defaultCreateThreads?: string;\n  /**\n   * Opt-in: declares this link type is composable from Plot via\n   * `Connector.onCreateLink`. Omit to make the link type sync-only (no\n   * \"Create new …\" picker entry).\n   *\n   * Connectors that need multiple compose modes for what users perceive as\n   * the same kind of thing (e.g. Slack channel post vs DM) should declare\n   * **separate linkTypes**, one per user-facing thread type. That keeps\n   * each linkType isomorphic to one filter chip.\n   */\n  compose?: ComposeConfig;\n  /**\n   * Per-connector contact roles. Examples:\n   *   email   → [{id:\"to\",label:\"To\",default:true},{id:\"cc\",label:\"CC\"},{id:\"bcc\",label:\"BCC\",hidden:true}]\n   *   calendar → [{id:\"required\",label:\"Required\",default:true},{id:\"optional\",label:\"Optional\"}]\n   *\n   * Plot uses this list to render a role picker on each contact chip in the\n   * composer and to label non-default roles on existing threads. Exactly one\n   * role should be marked `default: true`. Connectors that don't distinguish\n   * roles (Slack, Linear) omit this field entirely.\n   */\n  contactRoles?: ContactRoleConfig[];\n  /**\n   * Whether contacts on an existing thread can be added, removed, or have\n   * their role changed (email-style mid-thread recipient changes). When\n   * false, the thread's contact list is fixed after creation. Defaults to\n   * false when omitted.\n   */\n  supportsContactChanges?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry a link (a pasted URL or\n   * connector-created item) that Plot forwards to the source. When false (the\n   * default), the \"Add link\" button is hidden for threads of this link type.\n   * Only set true if the connector's reply path actually forwards the link\n   * action to the source. Private Plot notes (no link type) always allow links.\n   */\n  supportsLinks?: boolean;\n  /**\n   * Whether a note/reply on this link type can carry an uploaded file that Plot\n   * forwards to the source as an attachment. When false (the default), the\n   * \"Attach file\" button is hidden for threads of this link type. Only set true\n   * if the connector's reply path actually uploads file actions to the source.\n   * Private Plot notes (no link type) always allow attachments.\n   */\n  supportsFileAttachments?: boolean;\n  /**\n   * Declares how sharing on threads of this link type is scoped:\n   *\n   * - `\"thread\"` (default): one roster shared across all notes in the\n   *   thread. Native Plot threads, Slack DMs, calendar events.\n   * - `\"channel\"`: visibility is the external channel's membership;\n   *   the per-thread `contacts` array is ignored for sharing UI.\n   *   Slack channels, Linear projects.\n   * - `\"message\"`: each note carries its own recipient set via\n   *   `note.access_contacts`; the thread roster is the union across\n   *   all messages. Email.\n   * - `\"none\"`: the link type has no recipient roster at all. No\n   *   contacts/sharing UI is shown for these threads. Use for purely\n   *   personal destinations with no sharing concept (e.g. Google\n   *   Tasks). The per-thread `contacts` array is ignored for sharing UI.\n   *\n   * Omit to default to `\"thread\"`. When set to `\"message\"`, every\n   * note this connector ingests must populate `access_contacts`\n   * explicitly (never NULL).\n   */\n  sharingModel?: \"thread\" | \"channel\" | \"message\" | \"none\";\n};\n\n/**\n * Declares how a link type is composable from Plot via\n * `Connector.onCreateLink`. Attached to {@link LinkTypeConfig.compose}.\n */\nexport type ComposeConfig = {\n  /**\n   * Selects the destination model for the \"Create new …\" picker.\n   *\n   * - `\"channels\"` (default): one chip per enabled channel (e.g. a Linear\n   *   team, a Slack channel). Existing behaviour for task-tracker / calendar\n   *   connectors.\n   * - `\"contacts\"`: one chip per connection (account); the user picks\n   *   recipients from their contacts. The runtime pre-resolves the chosen\n   *   Plot contacts to platform account IDs via the per-connection\n   *   `contact_external_account` rows and delivers them as\n   *   `CreateLinkDraft.recipients`. Contacts without a row for this specific\n   *   connection are filtered out of the picker — used by closed-roster\n   *   messaging platforms (Slack DM, Teams DM, Google Chat DM, LinkedIn DM).\n   * - `\"addresses\"`: one chip per connection; the picker accepts any\n   *   contact with an addressable identifier (e.g. an email) or a free-form\n   *   typed address. The runtime fills `recipients` for contacts with a\n   *   connection-scoped row and falls back to the contact's primary address\n   *   (e.g. `contact.email`) when no row exists. Free-form addresses arrive\n   *   via the thread's `inviteEmails`. Used by open address spaces like\n   *   Gmail.\n   */\n  targets?: \"channels\" | \"contacts\" | \"addresses\";\n  /**\n   * Status to assign newly-created links. Should match an entry in the\n   * parent linkType's `statuses[]`, OR a symbolic id that the connector's\n   * `onCreateLink` resolves itself (e.g. Linear's `\"unstarted\"` category is\n   * resolved per-team to a state UUID inside the connector — see\n   * `connectors/linear/src/linear.ts`).\n   *\n   * Omit for status-less link types (e.g. messaging connectors that don't\n   * model a status): composed links are created with no status.\n   */\n  status?: string;\n  /**\n   * Optional override for the picker chip / \"Create new …\" copy. Defaults\n   * to the parent linkType's `label`. Use to disambiguate compose entries\n   * when the parent label alone isn't specific enough (e.g. \"Direct\n   * messages\" for a DM-mode compose on a chat connector).\n   */\n  label?: string;\n};\n\n/**\n * Declares one contact role for a connector's link type. See\n * `LinkTypeConfig.contactRoles`.\n */\nexport type ContactRoleConfig = {\n  /** Stable machine id, e.g. \"to\" / \"cc\" / \"bcc\" / \"required\" / \"optional\". */\n  id: string;\n  /** Display label shown next to a contact chip, e.g. \"To\", \"CC\", \"Required\". */\n  label: string;\n  /** Exactly one role per linkType should be marked default. */\n  default?: boolean;\n  /**\n   * Hidden roles are visible only to (a) the contact themselves and\n   * (b) the user who added them. The API filters them out of every other\n   * viewer's `thread.contacts` and `thread.contactMeta`. Use for BCC-style\n   * semantics where other recipients must not see the hidden contact.\n   */\n  hidden?: boolean;\n};\n\n/**\n * Context passed to onChannelEnabled with plan-based sync hints.\n * Connectors can use these hints to limit initial sync scope.\n */\nexport type SyncContext = {\n  /**\n   * Earliest date to include in initial sync, based on the user's plan.\n   *\n   * Non-calendar connectors should use this as their date filter (timeMin,\n   * created.gte, etc.) during initial sync. Calendar connectors should\n   * ignore this for API queries (to avoid missing recurring events) — the\n   * API layer filters non-recurring items automatically.\n   *\n   * Undefined when no limit applies.\n   */\n  syncHistoryMin?: Date;\n\n  /**\n   * True when this is a recovery dispatch after the connection's auth was\n   * restored (the user re-authorized a previously-broken connection).\n   *\n   * The framework calls `onChannelEnabled` again for every channel that was\n   * already enabled at the time of re-auth so the connector can recover from\n   * the auth gap. Connectors should:\n   *\n   * 1. Drop any persisted incremental sync cursors / sync tokens so the\n   *    next sync re-walks history (the cursor may be stale or invalid —\n   *    Google Calendar invalidates syncTokens after ~7 days).\n   * 2. Re-register webhooks (any prior subscription may have been\n   *    invalidated during the auth outage).\n   * 3. Treat this as a backfill that walks history but does NOT spam\n   *    notifications — set `unread: false` and `archived: false` on\n   *    items as you would during initial sync.\n   *\n   * Most connectors can take the same code path as a fresh\n   * `onChannelEnabled` for `recovering: true` as long as that path\n   * overwrites stored state rather than appending to it.\n   */\n  recovering?: boolean;\n\n  /**\n   * True when the channel is being observed because the user composed a Plot\n   * thread INTO it (via `onCreateLink`), not because they explicitly enabled\n   * it. The connector should register webhooks / mark the channel observed so\n   * inbound events (replies, reactions) on the composed thread sync back —\n   * but must NOT backfill history. Only go-forward events matter; pulling the\n   * channel's existing content would be surprising for a channel the user\n   * only posted one thread into.\n   *\n   * Connectors whose `onChannelEnabled` already skips historical backfill can\n   * ignore this flag. Connectors that initial-sync on enable MUST short-\n   * circuit that backfill when `observeOnly` is true (still set up webhooks\n   * and any go-forward state).\n   */\n  observeOnly?: boolean;\n};\n\n/**\n * Built-in tool for managing OAuth authentication and channel resources.\n *\n * The Integrations tool:\n * 1. Manages channel resources (calendars, projects, etc.) per actor\n * 2. Returns tokens for the user who enabled sync on a channel\n * 3. Supports per-actor auth via actAs() for write-back operations\n * 4. Provides saveLink/saveContacts for Connectors to save data directly\n *\n * Connectors declare their provider, scopes, and channel lifecycle methods as\n * class properties and methods. The Integrations tool reads these automatically.\n * Auth and channel management is handled in the twist edit modal in Flutter.\n *\n * @example\n * ```typescript\n * class CalendarConnector extends Connector<CalendarConnector> {\n *   readonly provider = AuthProvider.Google;\n *   readonly scopes = [\"https://www.googleapis.com/auth/calendar\"];\n *\n *   build(build: ToolBuilder) {\n *     return {\n *       integrations: build(Integrations),\n *     };\n *   }\n *\n *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {\n *     const calendars = await this.listCalendars(token);\n *     return calendars.map(c => ({ id: c.id, title: c.name }));\n *   }\n *\n *   async onChannelEnabled(channel: Channel) {\n *     // Start syncing\n *   }\n *\n *   async onChannelDisabled(channel: Channel) {\n *     // Stop syncing\n *   }\n * }\n * ```\n */\nexport abstract class Integrations extends ITool {\n  /**\n   * Merge scopes from multiple tools, deduplicating.\n   *\n   * @param scopeArrays - Arrays of scopes to merge\n   * @returns Deduplicated array of scopes\n   */\n  static MergeScopes(...scopeArrays: string[][]): string[] {\n    return Array.from(new Set(scopeArrays.flat()));\n  }\n\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * Returns the token of the user who enabled sync on the given channel.\n   * If the channel is not enabled or the token is expired/invalid, returns null.\n   *\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   */\n  abstract get(channelId: string): Promise<AuthToken | null>;\n  /**\n   * Retrieves an access token for a channel resource.\n   *\n   * @param provider - The OAuth provider (deprecated, ignored for single-provider connectors)\n   * @param channelId - The channel resource ID (e.g., calendar ID)\n   * @returns Promise resolving to the access token or null\n   * @deprecated Use get(channelId) instead. The provider is implicit from the connector.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract get(provider: AuthProvider, channelId: string): Promise<AuthToken | null>;\n\n  /**\n   * Saves a link with notes to the connector's focus.\n   *\n   * Creates a thread+link pair. The thread is a lightweight container;\n   * the link holds the external entity data (source, meta, type, status, etc.).\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param link - The link with notes to save\n   * @returns Promise resolving to the saved thread's UUID, or null if the\n   *   link was filtered out (e.g. older than the plan's sync history limit)\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid | null>;\n\n  /**\n   * Batch version of {@link saveLink} — saves many links in one call.\n   *\n   * Connectors syncing many items per page (e.g. calendar events, issues,\n   * messages) should prefer this over looping `saveLink`. Each `saveLink`\n   * crosses the runtime boundary and counts against the per-execution\n   * request budget; `saveLinks` collapses N saves into a single crossing.\n   *\n   * Failures on individual links DO NOT abort the batch. A bad item lands\n   * as `null` in its slot and the rest still save. This prevents one\n   * malformed record from losing an entire page of sync progress.\n   *\n   * This method is available only to Connectors (not regular Twists).\n   *\n   * @param links - Array of links with notes to save\n   * @returns Array of the same length and order as `links`. Each entry is\n   *   the saved thread's UUID, or `null` if the link was filtered out\n   *   (e.g. older than the plan's sync history limit) OR failed to save.\n   *   The two null causes are not distinguished; the save failure is\n   *   logged server-side.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLinks(links: NewLinkWithNotes[]): Promise<(Uuid | null)[]>;\n\n  /**\n   * Upserts contacts into the connector's focus without requiring a Link.\n   *\n   * Use this for messaging connectors to bulk-sync workspace members so the\n   * recipient picker can filter contacts by reachable platform account. Populate\n   * `NewContact.source` to persist `contact_external_account` rows (the platform\n   * identity used to address the contact). Returns one `Actor` per input, in order.\n   *\n   * @param contacts - Contacts to upsert, keyed by `source`/`key`\n   * @returns Promise resolving to the saved actors, 1:1 with input order\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveContacts(contacts: NewContact[]): Promise<Actor[]>;\n\n  /**\n   * Archives links matching the given filter that were created by this connector.\n   *\n   * For each archived link's thread, if no other non-archived links remain,\n   * the thread is also archived.\n   *\n   * @param filter - Filter criteria for which links to archive\n   * @returns Promise that resolves when archiving is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract archiveLinks(filter: ArchiveLinkFilter): Promise<void>;\n\n  /**\n   * Sets or clears todo status on a thread owned by this connector.\n   *\n   * @param source - The link source URL identifying the thread\n   * @param actorId - The user to set the todo for\n   * @param todo - true to mark as todo, false to clear/complete\n   * @param options - Additional options\n   * @param options.date - The todo date (when todo=true). Defaults to today.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract setThreadToDo(\n    source: string,\n    actorId: ActorId,\n    todo: boolean,\n    options?: { date?: Date | string }\n  ): Promise<void>;\n\n  /**\n   * Signal that initial bulk-sync (or recovery sync) for a channel is fully\n   * complete. The Flutter app uses this to clear the \"syncing…\" indicator\n   * on the connection.\n   *\n   * The framework automatically marks a channel as syncing when it dispatches\n   * `onChannelEnabled` (whether initial-enable, auto-enable from\n   * `setChannels`, or recovery after re-auth). Connectors do NOT need to\n   * call anything to start tracking — only to signal completion.\n   *\n   * Call this exactly once when the initial backfill has finished (no more\n   * pages, all phases exhausted). Do NOT call it on every incremental sync.\n   *\n   * If `onChannelEnabled` throws an unhandled exception, the framework\n   * automatically clears the syncing state — connectors don't need a\n   * `try/catch` to clear state on failure.\n   *\n   * No-op when no auth/user mapping exists for the channel (e.g. key-based\n   * connectors that don't have a per-user OAuth association).\n   *\n   * @param channelId - The channel resource ID whose initial sync just finished\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract channelSyncCompleted(channelId: string): Promise<void>;\n\n  /**\n   * Flag a connection as needing re-authentication so the Flutter app\n   * surfaces a re-auth prompt on the next sync.\n   *\n   * Call this when a connector's API call returns a permanent auth-style\n   * error that the runtime can't observe through token refresh — e.g.\n   * Slack `invalid_auth` / `token_revoked` / `not_authed`, or a 401 on a\n   * provider that doesn't refresh. The runtime already flags reauth\n   * automatically when an OAuth refresh permanently fails or when the\n   * stored token is missing on a get(); only call this for cases the\n   * runtime can't see.\n   *\n   * Idempotent: safe to call repeatedly; existing reauth flags are not\n   * overwritten. No-op when the channel has no `enabledBy` actor (e.g.\n   * key-based connectors).\n   *\n   * @param channelId - The channel resource ID whose token is bad\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract markNeedsReauth(channelId: string): Promise<void>;\n\n  /**\n   * Upsert workspace custom emoji into Plot's shared cache so reactions using\n   * `provider:workspace/name` refs render as images and round-trip. Idempotent;\n   * keyed on `id`. Pass `archived: true` to mark an emoji removed. Workspace-\n   * scoped (shared across all users of that workspace).\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveCustomEmoji(emoji: NewCustomEmoji[]): Promise<void>;\n\n}\n\n/**\n * Filter criteria for archiving links.\n * All fields are optional; only provided fields are used for matching.\n */\nexport type ArchiveLinkFilter = {\n  /** Filter by channel ID */\n  channelId?: string;\n  /** Filter by link type (e.g., \"issue\", \"pull_request\") */\n  type?: string;\n  /** Filter by link status (e.g., \"open\", \"closed\") */\n  status?: string;\n  /** Filter by metadata fields (uses containment matching) */\n  meta?: Record<string, JSONValue>;\n};\n\n/**\n * A workspace custom emoji to cache so Plot can render and round-trip it as a\n * reaction. `id` is the provider-scoped ref stored on reactions, of the form\n * `<provider>:<workspace>/<name>` (e.g. `slack:T0123ABC/party_parrot`).\n */\nexport type NewCustomEmoji = {\n  /** Provider-scoped ref: `<provider>:<workspace>/<name>`. The reaction value. */\n  id: string;\n  /** e.g. \"slack\". */\n  provider: string;\n  /** Provider workspace/team id (e.g. Slack team id `T0123ABC`). */\n  workspace: string;\n  /** Bare emoji name without colons (e.g. \"party_parrot\"). */\n  name: string;\n  /** Image URL to render, or null for an alias (see `aliasOf`). */\n  imageUrl: string | null;\n  /** When this emoji aliases another, the target ref (`id` of the canonical emoji); else null. */\n  aliasOf: string | null;\n  /** True to mark the emoji removed (archive it) rather than upsert it. */\n  archived: boolean;\n};\n\n/**\n * Enumeration of supported OAuth providers.\n *\n * Each provider has different OAuth endpoints, scopes, and token formats.\n * The Integrations tool handles the provider-specific implementation details.\n */\nexport enum AuthProvider {\n  /** Google OAuth provider for Google Workspace services */\n  Google = \"google\",\n  /** Microsoft OAuth provider for Microsoft 365 services */\n  Microsoft = \"microsoft\",\n  /** Notion OAuth provider for Notion workspaces */\n  Notion = \"notion\",\n  /** Slack OAuth provider for Slack workspaces */\n  Slack = \"slack\",\n  /** Atlassian OAuth provider for Jira and Confluence */\n  Atlassian = \"atlassian\",\n  /** Linear OAuth provider for Linear workspaces */\n  Linear = \"linear\",\n  /** Monday.com OAuth provider */\n  Monday = \"monday\",\n  /** GitHub OAuth provider for GitHub repositories and organizations */\n  GitHub = \"github\",\n  /** Asana OAuth provider for Asana workspaces */\n  Asana = \"asana\",\n  /** HubSpot OAuth provider for HubSpot CRM */\n  HubSpot = \"hubspot\",\n  /** Todoist OAuth provider for Todoist task management */\n  Todoist = \"todoist\",\n  /** Airtable OAuth provider for Airtable bases */\n  Airtable = \"airtable\",\n}\n\n/**\n * Represents a completed authorization from an OAuth flow.\n *\n * Contains the provider, granted scopes, and the actor (contact) that was authorized.\n * Tokens are looked up by (provider, actorId) rather than a random ID.\n */\nexport type Authorization = {\n  /** The OAuth provider this authorization is for */\n  provider: AuthProvider;\n  /** Array of OAuth scopes this authorization covers */\n  scopes: string[];\n  /** The external account that was authorized (e.g., the Google account) */\n  actor: Actor;\n};\n\n/**\n * Represents a stored OAuth authentication token.\n *\n * Contains the actual access token and the scopes it was granted,\n * which may be a subset of the originally requested scopes.\n */\nexport type AuthToken = {\n  /** The OAuth access token */\n  token: string;\n  /** Array of granted OAuth scopes */\n  scopes: string[];\n  /**\n   * Provider-specific metadata as key-value pairs.\n   *\n   * For Slack (AuthProvider.Slack):\n   * - authed_user_id: The authenticated user's Slack ID\n   * - bot_user_id: The bot user's Slack ID\n   * - team_name: The Slack workspace/team name\n   */\n  provider?: Record<string, string>;\n};\n";

package/src/llm-docs/tools/network.ts

@@ -5,4 +5,4 @@
  * Generated from: prebuild.ts
  */
 
-export default "import { ITool } from \"..\";\nimport { type JSONValue, Serializable } from \"../utils/types\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Gmail** (Google with Gmail scopes): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   The topic name (e.g., \"projects/plot-prod/topics/gmail-webhook-abc123\") should be passed\n   *   to the Gmail API's `users.watch` endpoint. Requires `authorization` parameter with Gmail scopes.\n   * - **Pub/Sub** (`pubsub: true`): Returns a Google Pub/Sub topic name instead of a webhook URL.\n   *   Use this for services that deliver events via Pub/Sub (e.g., Google Workspace Events API).\n   *   A Pub/Sub topic and push subscription are created automatically; the returned topic name\n   *   can be passed to any Google API that accepts a Pub/Sub notification endpoint.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack and Gmail)\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Gmail/Pub/Sub, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Pub/Sub webhook for Workspace Events API\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: true },\n   *   this.onEventReceived,\n   *   channelId\n   * );\n   * // topicName: \"projects/plot-prod/topics/ps-abc123\"\n   *\n   * // Pass topic name to Workspace Events API\n   * await api.createSubscription(targetResource, topicName, eventTypes);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - auto-detected from scopes, returns Pub/Sub topic name\n   * const topicName = await this.tools.network.createWebhook(\n   *   {},\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * ```\n   */\n  abstract createWebhook<\n    TArgs extends Serializable[],\n    TCallback extends (request: WebhookRequest, ...args: TArgs) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n      /** When true, creates a Google Pub/Sub topic instead of a webhook URL. */\n      pubsub?: boolean;\n      /**\n       * Controls whether the returned webhook URL runs callbacks synchronously\n       * or asynchronously.\n       *\n       * **Async (default, `async: true`)** — Plot enqueues each incoming\n       * request and immediately returns `200 { queued: true }`. A background\n       * queue consumer runs the callback with bounded concurrency. The\n       * sender never sees the callback's return value or any error thrown\n       * by it, and delivery is at-least-once (the callback must be\n       * idempotent). This is the right default for the vast majority of\n       * webhooks — service event notifications, bulk-import fan-out, etc. —\n       * because it removes ingress-path database pressure and prevents\n       * sender-side retry storms when callbacks are slow.\n       *\n       * **Sync (`async: false`)** — Plot runs the callback inline and\n       * responds with the callback's return value. Required when:\n       * - The sender reads the response body (e.g. Microsoft Graph\n       *   subscription validation, which POSTs with a `validationToken` and\n       *   expects the token echoed as `text/plain`).\n       * - The sender uses the HTTP status code to decide whether to retry\n       *   (e.g. to surface 4xx for permanent failures).\n       * - The handler must observe throws before the sender times out.\n       *\n       * When `async: false`, a callback returning a `string` is sent back\n       * with `Content-Type: text/plain`; any other value is serialized as\n       * JSON. `undefined` / `void` yields a plain `200 OK` body.\n       *\n       * Defaults to `true`.\n       */\n      async?: boolean;\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";
+export default "import { ITool } from \"..\";\nimport { type JSONValue, Serializable } from \"../utils/types\";\nimport { type AuthProvider, type Authorization } from \"./integrations\";\n\n/**\n * Represents an incoming webhook request.\n *\n * This object is passed to webhook callback functions and contains all\n * the information about the HTTP request that triggered the webhook.\n *\n * @example\n * ```typescript\n * async onWebhookReceived(request: WebhookRequest, context: any) {\n *   console.log(`${request.method} request received`);\n *   console.log(\"Headers:\", request.headers);\n *   console.log(\"Query params:\", request.params);\n *   console.log(\"Body:\", request.body);\n *   console.log(\"Context:\", context);\n * }\n * ```\n */\nexport type WebhookRequest = {\n  /** HTTP method of the request (GET, POST, etc.) */\n  method: string;\n  /** HTTP headers from the request */\n  headers: Record<string, string>;\n  /** Query string parameters from the request URL */\n  params: Record<string, string>;\n  /** Request body (parsed as JSON if applicable) */\n  body: JSONValue;\n  /** Raw request body (for signature verification) */\n  rawBody?: string;\n};\n\n/**\n * Built-in tool for requesting HTTP access permissions and managing webhooks.\n *\n * The Network tool serves two purposes:\n * 1. Declares which URLs a twist or tool is allowed to access via HTTP/HTTPS\n * 2. Provides webhook creation and management for receiving HTTP callbacks\n *\n * **IMPORTANT**: Must be requested in the Twist or Tool Init method to declare\n * HTTP access permissions. Without requesting this tool with the appropriate URLs,\n * all outbound HTTP requests (fetch, etc.) will be blocked.\n *\n * **Permission Patterns:**\n * - `*` - Allow access to all URLs\n * - `https://*.example.com` - Allow access to all subdomains\n * - `https://api.example.com/*` - Allow access to all paths on the domain\n * - `https://api.example.com/v1/*` - Allow access to specific path prefix\n *\n * **Webhook Characteristics:**\n * - Persistent across worker restarts\n * - Automatic callback routing to parent tool/twist\n * - Support for all HTTP methods\n * - Context preservation for callback execution\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       // Request HTTP access to specific APIs\n *       network: build(Network, {\n *         urls: [\n *           'https://api.github.com/*',\n *           'https://api.openai.com/*'\n *         ]\n *       })\n *     };\n *   }\n * }\n * ```\n *\n * @example\n * ```typescript\n * class CalendarTool extends Tool<CalendarTool> {\n *   build(build: ToolBuilder) {\n *     return {\n *       network: build(Network, {\n *         urls: ['https://www.googleapis.com/calendar/*']\n *       })\n *     };\n *   }\n *\n *   async setupCalendarWebhook(calendarId: string) {\n *     // Create webhook URL that will call onCalendarEvent\n *     const webhookUrl = await this.tools.network.createWebhook(\n *       {},\n *       this.onCalendarEvent,\n *       calendarId,\n *       \"google\"\n *     );\n *\n *     // Register webhook with Google Calendar API\n *     await this.registerWithGoogleCalendar(calendarId, webhookUrl);\n *\n *     return webhookUrl;\n *   }\n *\n *   async onCalendarEvent(request: WebhookRequest, calendarId: string, provider: string) {\n *     console.log(\"Calendar event received:\", {\n *       method: request.method,\n *       calendarId,\n *       provider,\n *       body: request.body\n *     });\n *\n *     // Process the calendar event change\n *     await this.processCalendarChange(request.body);\n *   }\n *\n *   async cleanup(webhookUrl: string) {\n *     await this.tools.network.deleteWebhook(webhookUrl);\n *   }\n * }\n * ```\n */\nexport abstract class Network extends ITool {\n  static readonly Options: {\n    /**\n     * All network access is blocked except the specified URLs.\n     * Wildcards (*) are supported for domains and paths.\n     */\n    urls: string[];\n  };\n\n  /**\n   * Creates a new webhook endpoint.\n   *\n   * Generates a unique HTTP endpoint that will invoke the callback function\n   * when requests are received. The callback receives the WebhookRequest plus any extraArgs.\n   *\n   * **Provider-Specific Behavior:**\n   * - **Slack**: Uses provider-specific routing via team_id. Requires `authorization` parameter.\n   * - **Pub/Sub** (`pubsub: \"gmail\" | \"workspace\"`): Returns a Google Pub/Sub topic name instead\n   *   of a webhook URL. `\"gmail\"` targets Gmail `users.watch` (set this only on the Gmail\n   *   connector); `\"workspace\"` targets Google Workspace Events (Chat, etc.). A Pub/Sub topic and\n   *   push subscription are created automatically; the returned topic name (e.g.\n   *   \"projects/plot-prod/topics/gmail-abc123\") is passed to the relevant Google API. Other Google\n   *   connectors (Calendar, Drive) omit `pubsub` and use the default HTTPS webhook.\n   * - **Default**: Returns a standard webhook URL for all other cases.\n   *\n   * @param options - Webhook creation options\n   * @param options.provider - Optional provider for provider-specific webhook routing\n   * @param options.authorization - Optional authorization for provider-specific webhooks (required for Slack)\n   * @param options.pubsub - Optional Google Pub/Sub push product (\"gmail\" | \"workspace\")\n   * @param callback - Function receiving (request, ...extraArgs)\n   * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)\n   * @returns Promise resolving to the webhook URL, or for Pub/Sub, a Pub/Sub topic name\n   *\n   * @example\n   * ```typescript\n   * // Pub/Sub webhook for Workspace Events API (Chat, etc.)\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"workspace\" },\n   *   this.onEventReceived,\n   *   channelId\n   * );\n   * // topicName: \"projects/plot-prod/topics/ps-abc123\"\n   *\n   * // Pass topic name to Workspace Events API\n   * await api.createSubscription(targetResource, topicName, eventTypes);\n   * ```\n   *\n   * @example\n   * ```typescript\n   * // Gmail webhook - returns a Gmail Pub/Sub topic name for users.watch\n   * const topicName = await this.tools.network.createWebhook(\n   *   { pubsub: \"gmail\" },\n   *   this.onGmailNotification,\n   *   \"inbox\"\n   * );\n   * ```\n   */\n  abstract createWebhook<\n    TArgs extends Serializable[],\n    TCallback extends (request: WebhookRequest, ...args: TArgs) => any\n  >(\n    options: {\n      provider?: AuthProvider;\n      authorization?: Authorization;\n      /**\n       * Create a Google Pub/Sub topic instead of a webhook URL, and return\n       * the topic name. Selects the push product:\n       *\n       * - `\"gmail\"` — Gmail `users.watch` (topic published to by\n       *   `gmail-api-push`). Set this only on the Gmail connector.\n       * - `\"workspace\"` — Google Workspace Events (Chat, etc.).\n       *\n       * This opt-in must be explicit. Other Google connectors (Calendar,\n       * Drive) omit it and receive a standard HTTPS webhook URL — they must\n       * never be routed to a Pub/Sub topic, which `events.watch` /\n       * `files.watch` reject as non-HTTPS.\n       */\n      pubsub?: \"gmail\" | \"workspace\";\n      /**\n       * Controls whether the returned webhook URL runs callbacks synchronously\n       * or asynchronously.\n       *\n       * **Async (default, `async: true`)** — Plot enqueues each incoming\n       * request and immediately returns `200 { queued: true }`. A background\n       * queue consumer runs the callback with bounded concurrency. The\n       * sender never sees the callback's return value or any error thrown\n       * by it, and delivery is at-least-once (the callback must be\n       * idempotent). This is the right default for the vast majority of\n       * webhooks — service event notifications, bulk-import fan-out, etc. —\n       * because it removes ingress-path database pressure and prevents\n       * sender-side retry storms when callbacks are slow.\n       *\n       * **Sync (`async: false`)** — Plot runs the callback inline and\n       * responds with the callback's return value. Required when:\n       * - The sender reads the response body (e.g. Microsoft Graph\n       *   subscription validation, which POSTs with a `validationToken` and\n       *   expects the token echoed as `text/plain`).\n       * - The sender uses the HTTP status code to decide whether to retry\n       *   (e.g. to surface 4xx for permanent failures).\n       * - The handler must observe throws before the sender times out.\n       *\n       * When `async: false`, a callback returning a `string` is sent back\n       * with `Content-Type: text/plain`; any other value is serialized as\n       * JSON. `undefined` / `void` yields a plain `200 OK` body.\n       *\n       * Defaults to `true`.\n       */\n      async?: boolean;\n    },\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<string>;\n\n  /**\n   * Deletes an existing webhook endpoint.\n   *\n   * Removes the webhook endpoint and stops processing requests.\n   * Works with all webhook types (standard, Slack, and Gmail).\n   *\n   * **For Gmail webhooks:** Also deletes the associated Google Pub/Sub topic and subscription.\n   *\n   * **For Slack webhooks:** Removes the callback registration for the specific team.\n   *\n   * **For standard webhooks:** Removes the webhook endpoint. Any subsequent requests\n   * to the deleted webhook will return 404.\n   *\n   * @param url - The webhook identifier returned from `createWebhook()`.\n   *              This can be a URL (standard webhooks), a Pub/Sub topic name (Gmail),\n   *              or an opaque identifier (Slack). Always pass the exact value returned\n   *              from `createWebhook()`.\n   * @returns Promise that resolves when the webhook is deleted\n   */\n  abstract deleteWebhook(url: string): Promise<void>;\n}\n";