@plotday/twister 0.47.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plotday/twister",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Plot Twist Creator - Build intelligent extensions that integrate and automate",
   "type": "module",
   "main": "./dist/index.js",
@@ -109,6 +109,11 @@
       "types": "./dist/utils/hash.d.ts",
       "default": "./dist/utils/hash.js"
     },
+    "./utils/markdown": {
+      "@plotday/connector": "./src/utils/markdown.ts",
+      "types": "./dist/utils/markdown.d.ts",
+      "default": "./dist/utils/markdown.js"
+    },
     "./utils/uuid": {
       "@plotday/connector": "./src/utils/uuid.ts",
       "types": "./dist/utils/uuid.d.ts",
@@ -203,6 +208,7 @@
   },
   "files": [
     "dist",
+    "src",
     "bin",
     "cli/templates",
     "tsconfig.base.json",

package/src/connector.ts

@@ -0,0 +1,427 @@
+import { type Actor, type ActorId, type Link, type NewLinkWithNotes, type Note, type Thread } from "./plot";
+import type { ScheduleContactStatus } from "./schedule";
+import {
+  type AuthProvider,
+  type AuthToken,
+  type Authorization,
+  type Channel,
+  type LinkTypeConfig,
+  type SyncContext,
+} from "./tools/integrations";
+import { Twist } from "./twist";
+
+/**
+ * Fields captured in Plot when a user initiates creation of a new external
+ * item via a connector's `onCreateLink` hook.
+ *
+ * Thread-agnostic on purpose — connectors do not receive the Plot thread.
+ * The platform attaches the returned `NewLinkWithNotes` to the originating
+ * thread once `onCreateLink` resolves.
+ */
+/**
+ * Result returned from {@link Connector.onNoteCreated} and
+ * {@link Connector.onNoteUpdated} to report what the external system now
+ * has stored for the note.
+ *
+ * The runtime hashes `externalContent` and stores it as the note's sync
+ * baseline. On the next sync-in, if the incoming content hashes to the
+ * same value, the runtime knows the external side hasn't changed and
+ * preserves Plot's (possibly formatted) content. When the external side
+ * is edited, the hash diverges and the runtime overwrites Plot's content
+ * with the new external version.
+ *
+ * Omitting `externalContent` skips baseline tracking — the next sync-in
+ * will overwrite Plot's content (previous behavior). Always provide it
+ * when the write-back's return value reflects what the external system
+ * actually stored (often lossy plain-text), so the round-trip does not
+ * clobber the original Plot markdown.
+ *
+ * The hash covers only the content string — the runtime intentionally
+ * does not include a content-type in the hash, so write-back and sync-in
+ * do not have to agree on a content-type label for the same underlying
+ * bytes. Return exactly the string your connector's sync-in path will
+ * emit as `NewNote.content` for this note on the next re-ingest.
+ *
+ * For back-compat, `onNoteCreated` may also return a plain string, which
+ * is treated as `{ key }` with no baseline.
+ */
+export type NoteWriteBackResult = {
+  /**
+   * External system identifier assigned to this note. Set as the note's
+   * `key` for future upsert matching. Required when the runtime does not
+   * already know the key (i.e., from `onNoteCreated`); ignored from
+   * `onNoteUpdated` when the key was already established on create.
+   */
+  key?: string;
+  /**
+   * The content string as the external system now stores it, post-write.
+   * For systems whose write-back returns a representation of what was
+   * actually stored (e.g. Google Drive comment `content` after a create),
+   * pass that verbatim. For systems that only accept plain text, this
+   * will often be a lossy plain-text version of the Plot markdown — that
+   * is exactly the point: storing the lossy form as baseline lets the
+   * next sync-in recognize it and skip overwriting the richer Plot
+   * version.
+   *
+   * Must exactly match the string your connector's sync-in path emits as
+   * `NewNote.content` for this note on re-ingest.
+   */
+  externalContent?: string;
+};
+
+export type CreateLinkDraft = {
+  /** The channel (account + resource) the new item belongs to. */
+  channelId: string;
+  /** Link type identifier, matches a `LinkTypeConfig.type`. */
+  type: string;
+  /** Status the user selected. Matches a `statuses[].status` for `type`. */
+  status: string;
+  /** Title of the originating Plot thread (post AI title generation). */
+  title: string;
+  /** Markdown content of the thread's first note, or null if none. */
+  noteContent: string | null;
+  /**
+   * Contacts attached to the originating Plot thread, excluding the
+   * creating user. Use these as recipients (email, chat DM members, etc.)
+   * when the external item is a message or invite. An empty list means
+   * the user did not add anyone to the thread.
+   */
+  contacts: Actor[];
+};
+
+/**
+ * Base class for connectors — twists that sync data from external services.
+ *
+ * Connectors declare a single OAuth provider and scopes, and implement channel
+ * lifecycle methods for discovering and syncing external resources. They save
+ * data directly via `integrations.saveLink()` instead of using the Plot tool.
+ *
+ * @example
+ * ```typescript
+ * class LinearConnector extends Connector<LinearConnector> {
+ *   readonly provider = AuthProvider.Linear;
+ *   readonly scopes = ["read", "write"];
+ *   readonly linkTypes = [{
+ *     type: "issue",
+ *     label: "Issue",
+ *     statuses: [
+ *       { status: "open", label: "Open" },
+ *       { status: "done", label: "Done" },
+ *     ],
+ *   }];
+ *
+ *   build(build: ToolBuilder) {
+ *     return {
+ *       integrations: build(Integrations),
+ *     };
+ *   }
+ *
+ *   async getChannels(auth: Authorization, token: AuthToken): Promise<Channel[]> {
+ *     const teams = await this.listTeams(token);
+ *     return teams.map(t => ({ id: t.id, title: t.name }));
+ *   }
+ *
+ *   async onChannelEnabled(channel: Channel) {
+ *     const issues = await this.fetchIssues(channel.id);
+ *     for (const issue of issues) {
+ *       await this.tools.integrations.saveLink(issue);
+ *     }
+ *   }
+ *
+ *   async onChannelDisabled(channel: Channel) {
+ *     // Clean up webhooks, sync state, etc.
+ *   }
+ * }
+ * ```
+ */
+export abstract class Connector<TSelf> extends Twist<TSelf> {
+  /**
+   * Static marker to identify Connector subclasses without instanceof checks
+   * across worker boundaries.
+   */
+  static readonly isConnector = true;
+
+  // ---- Identity (abstract — every connector must declare) ----
+
+  /** The OAuth provider this connector authenticates with. */
+  readonly provider?: AuthProvider;
+
+  /** OAuth scopes to request for this connector. */
+  readonly scopes?: string[];
+
+  // ---- Auth model ----
+
+  /**
+   * When true, one credential is shared across all users in the workspace,
+   * entered once by the installer. When false (default), each user provides
+   * their own credential.
+   *
+   * Applies to both OAuth and key-based connectors:
+   * - Shared OAuth: e.g. Slack bot token (workspace-level)
+   * - Shared key: e.g. Attio workspace API key
+   * - Individual OAuth: e.g. Google Calendar (per-user)
+   * - Individual key: e.g. Fellow (per-user API key)
+   */
+  readonly shared?: boolean;
+
+  /**
+   * The Options field name that contains the authentication key (e.g. "apiKey").
+   * Must reference a `secure: true` field in the Options schema.
+   *
+   * When set, this connector uses key-based auth instead of OAuth.
+   * For individual connectors (`shared` is false), this field is stored
+   * per-user rather than in shared config.
+   */
+  readonly keyOption?: string;
+
+  // ---- Optional metadata ----
+
+  /**
+   * When true, this connector has a single implicit channel.
+   * `getChannels()` must return exactly one Channel.
+   * The UI will show channel config inline instead of a channel list.
+   */
+  readonly singleChannel?: boolean;
+
+  /**
+   * Registry of link types this connector creates (e.g., issue, event, message).
+   * Used for display in the UI (icons, labels, statuses).
+   */
+  readonly linkTypes?: LinkTypeConfig[];
+
+  /**
+   * When true, this connector is mentioned by default on replies to threads it created.
+   * When false (default), this connector cannot be mentioned at all.
+   *
+   * Set this to true for connectors with bidirectional sync (e.g., issue trackers,
+   * messaging) where user replies should be written back to the external service.
+   */
+  static readonly handleReplies?: boolean;
+
+  // ---- Account identity (abstract — every connector must implement) ----
+
+  /**
+   * Returns a human-readable name for the connected account.
+   * Shown in the connections list and edit modal to identify this connection.
+   *
+   * For OAuth connectors, this is typically the workspace or organization name
+   * (e.g., "Acme Corp" for a Linear workspace). For API key connectors, this
+   * could be the workspace name from the external service.
+   *
+   * Override this in your connector to return a meaningful account name.
+   *
+   * @param auth - The authorization (null for no-provider connectors)
+   * @param token - The access token (null for no-provider connectors)
+   * @returns Promise resolving to the account display name
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  getAccountName(
+    auth: Authorization | null,
+    token: AuthToken | null
+  ): Promise<string | null> {
+    return Promise.resolve(null);
+  }
+
+  // ---- Channel lifecycle (abstract — every connector must implement) ----
+
+  /**
+   * Returns available channels for the authorized actor.
+   * Called after OAuth is complete, during the setup/edit modal.
+   *
+   * @param auth - The completed authorization with provider and actor info
+   * @param token - The access token for making API calls
+   * @returns Promise resolving to available channels for the user to select
+   */
+  abstract getChannels(
+    auth: Authorization | null,
+    token: AuthToken | null
+  ): Promise<Channel[]>;
+
+  /**
+   * Called when a channel resource is enabled for syncing.
+   *
+   * **IMPORTANT: This method runs inline in the HTTP request handler.**
+   * Any long-running work (webhook setup, API calls, sync) MUST be queued
+   * as a separate task via `this.runTask()`, not executed inline. Blocking
+   * here causes the client to spin waiting for the response.
+   *
+   * Only lightweight operations should appear directly in this method:
+   * `this.set()`, `this.get()`, `this.callback()`, and `this.runTask()`.
+   *
+   * @example
+   * ```typescript
+   * async onChannelEnabled(channel: Channel): Promise<void> {
+   *   await this.set(`sync_enabled_${channel.id}`, true);
+   *   await this.set(`sync_state_${channel.id}`, { channelId: channel.id });
+   *
+   *   // Queue sync as a task — do NOT use this.run() or call sync methods inline
+   *   const syncCallback = await this.callback(this.syncBatch, 1, "full", channel.id, true);
+   *   await this.runTask(syncCallback);
+   *
+   *   // Queue webhook setup as a task — do NOT call setupWebhook() inline
+   *   const webhookCallback = await this.callback(this.setupWebhook, channel.id);
+   *   await this.runTask(webhookCallback);
+   * }
+   * ```
+   *
+   * @param channel - The channel that was enabled
+   * @param context - Optional sync context with plan-based hints (e.g. syncHistoryMin)
+   */
+  abstract onChannelEnabled(channel: Channel, context?: SyncContext): Promise<void>;
+
+  /**
+   * Called when a channel resource is disabled.
+   * Should stop sync, clean up webhooks, and remove state.
+   *
+   * @param channel - The channel that was disabled
+   */
+  abstract onChannelDisabled(channel: Channel): Promise<void>;
+
+  // ---- Write-back hooks (optional, default no-ops) ----
+
+  /**
+   * Called when a link created by this connector is updated by the user.
+   * Override to write back changes to the external service
+   * (e.g., changing issue status in Linear when marked done in Plot).
+   *
+   * @param link - The updated link
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onLinkUpdated(link: Link): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a user creates a thread in Plot that should create a new
+   * item in this connector's external system.
+   *
+   * A connector opts in to Plot-initiated creation by declaring a status
+   * with `createDefault: true` on the relevant `LinkTypeConfig`. When a
+   * user picks "Create new <type>" from the Add link modal and the thread
+   * is synced, the runtime calls this method with the draft fields.
+   *
+   * Implementations should create the item in the external service and
+   * return a `NewLinkWithNotes` describing the created item. The platform
+   * attaches the returned link to the originating thread — do not call
+   * `integrations.saveLink` yourself.
+   *
+   * Returning `null` aborts creation silently (the thread is still saved
+   * without a link).
+   *
+   * @param draft - The fields captured in Plot for the new item.
+   * @returns The link to attach, or null to abort creation.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onCreateLink(draft: CreateLinkDraft): Promise<NewLinkWithNotes | null> {
+    return Promise.resolve(null);
+  }
+
+  /**
+   * Called when a note is created on a thread owned by this connector.
+   * Override to write back comments to the external service
+   * (e.g., adding a comment to a Linear issue).
+   *
+   * Returning a string or {@link NoteWriteBackResult} links the Plot note
+   * to its external counterpart. A plain string sets the note's `key`.
+   * A `NoteWriteBackResult` additionally sets a sync baseline (via
+   * `externalContent`) so the next sync-in can recognize the round-tripped
+   * content and preserve Plot's formatted version. See
+   * {@link NoteWriteBackResult} for details.
+   *
+   * @param note - The created note
+   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)
+   * @returns Optional note key or NoteWriteBackResult for external dedup + baseline tracking
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onNoteCreated(note: Note, thread: Thread): Promise<string | NoteWriteBackResult | void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a note on a thread owned by this connector is updated.
+   * Override to write back changes to the external service
+   * (e.g., syncing reaction tags as emoji reactions, or editing a comment
+   * whose content changed in Plot).
+   *
+   * Return a {@link NoteWriteBackResult} with `externalContent` to update
+   * the sync baseline after a successful write-back, so the next sync-in
+   * recognizes the external version as already-seen and preserves Plot's
+   * content.
+   *
+   * @param note - The updated note (includes current tags)
+   * @param thread - The thread the note belongs to (includes thread.meta with connector-specific data)
+   * @returns Optional NoteWriteBackResult for baseline tracking
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onNoteUpdated(note: Note, thread: Thread): Promise<NoteWriteBackResult | void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a user reads or unreads a thread owned by this connector.
+   * Override to write back read status to the external service
+   * (e.g., marking an email as read in Gmail).
+   *
+   * @param thread - The thread that was read/unread (includes thread.meta with connector-specific data)
+   * @param actor - The user who performed the action
+   * @param unread - false when marked as read, true when marked as unread
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onThreadRead(thread: Thread, actor: Actor, unread: boolean): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a user marks or unmarks a thread as todo.
+   * Override to sync todo status to the external service
+   * (e.g., starring an email in Gmail when marked as todo).
+   *
+   * @param thread - The thread (includes thread.meta with connector-specific data)
+   * @param actor - The user who changed the todo status
+   * @param todo - true when marked as todo, false when done or removed
+   * @param options - Additional context
+   * @param options.date - The todo date (when todo=true)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onThreadToDo(thread: Thread, actor: Actor, todo: boolean, options: { date?: Date }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called when a schedule contact's RSVP status changes on a thread owned by this connector.
+   * Override to sync RSVP changes back to the external calendar.
+   *
+   * @param thread - The thread (includes thread.meta with connector-specific data)
+   * @param scheduleId - The schedule ID
+   * @param contactId - The contact whose status changed
+   * @param status - The new RSVP status ('attend', 'skip', or null)
+   * @param actor - The user who changed the status
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onScheduleContactUpdated(thread: Thread, scheduleId: string, contactId: ActorId, status: ScheduleContactStatus | null, actor: Actor): Promise<void> {
+    return Promise.resolve();
+  }
+
+  // ---- Activation ----
+
+  /**
+   * Called when the connector is activated after OAuth is complete.
+   *
+   * Connectors receive the authorization in addition to the activating actor.
+   * When this runs, `this.userId` is already populated with the installing
+   * user's ID.
+   *
+   * Default implementation does nothing. Override for custom setup.
+   *
+   * @param context - The activation context
+   * @param context.auth - The completed OAuth authorization
+   * @param context.actor - The actor who activated the connector
+   */
+  // @ts-ignore - Connector.activate() has a Connector-specific context type.
+  activate(context: { auth?: Authorization; actor?: Actor }): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+/** @deprecated Use `Connector` instead. */
+export { Connector as Source };

package/src/creator-docs.ts

@@ -0,0 +1,29 @@
+import llmDocs from "./llm-docs/index.js";
+
+/**
+ * Gets complete Twist Creator type definitions with import paths for LLM context.
+ *
+ * This function returns pre-generated Builder documentation that was bundled
+ * at build time. Used by twist generators to provide complete type
+ * information to LLMs.
+ *
+ * @returns Formatted string containing all Twist Creator type definitions with import paths
+ */
+export function getBuilderDocumentation(): string {
+  let documentation = "# Plot Twist Creator Type Definitions\n\n";
+  documentation +=
+    "Complete type definitions with JSDoc documentation for all Plot Twist Creator types.\n";
+  documentation +=
+    "These are the source files - use the import paths shown to import types in your twist code.\n\n";
+
+  // Format each Builder file with headers and code fences
+  for (const [importPath, content] of Object.entries(llmDocs)) {
+    documentation += `## ${importPath}\n\n`;
+    documentation += "```typescript\n";
+    documentation += `// Import from: ${importPath}\n\n`;
+    documentation += content;
+    documentation += "\n```\n\n";
+  }
+
+  return documentation;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./twist";
+export * from "./connector";
+export * from "./plot";
+export * from "./schedule";
+export * from "./tag";
+export * from "./tool";
+export * from "./tools";
+export * from "./options";
+export * from "./utils/types";
+export { getBuilderDocumentation } from "./creator-docs";

package/src/llm-docs/connector.ts

@@ -0,0 +1,8 @@
+/**
+ * Generated LLM documentation for @plotday/twister/connector
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: prebuild.ts
+ */
+
+export default "import { type Actor, type ActorId, type Link, type NewLinkWithNotes, type Note, type Thread } 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 * 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 */\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\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  contacts: Actor[];\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   * 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   * **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): Promise<void> {\n   *   await this.set(`sync_enabled_${channel.id}`, true);\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 with plan-based hints (e.g. syncHistoryMin)\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 status\n   * with `createDefault: true` on the relevant `LinkTypeConfig`. When a\n   * user picks \"Create new <type>\" from the Add link modal and the thread\n   * is synced, the runtime calls this method 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   * 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 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  // ---- 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/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Generated LLM documentation index
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: prebuild.ts
+ *
+ * Provides a mapping of Twister import paths to their source code documentation.
+ */
+
+import connector from "./connector.js";
+import options from "./options.js";
+import plot from "./plot.js";
+import schedule from "./schedule.js";
+import tag from "./tag.js";
+import tool from "./tool.js";
+import twist from "./twist.js";
+import tools_ai from "./tools/ai.js";
+import tools_callbacks from "./tools/callbacks.js";
+import tools_imap from "./tools/imap.js";
+import tools_integrations from "./tools/integrations.js";
+import tools_network from "./tools/network.js";
+import tools_plot from "./tools/plot.js";
+import tools_smtp from "./tools/smtp.js";
+import tools_store from "./tools/store.js";
+import tools_tasks from "./tools/tasks.js";
+import tools_twists from "./tools/twists.js";
+
+const llmDocs: Record<string, string> = {
+  "@plotday/twister/connector": connector,
+  "@plotday/twister/options": options,
+  "@plotday/twister/plot": plot,
+  "@plotday/twister/schedule": schedule,
+  "@plotday/twister/tag": tag,
+  "@plotday/twister/tool": tool,
+  "@plotday/twister/twist": twist,
+  "@plotday/twister/tools/ai": tools_ai,
+  "@plotday/twister/tools/callbacks": tools_callbacks,
+  "@plotday/twister/tools/imap": tools_imap,
+  "@plotday/twister/tools/integrations": tools_integrations,
+  "@plotday/twister/tools/network": tools_network,
+  "@plotday/twister/tools/plot": tools_plot,
+  "@plotday/twister/tools/smtp": tools_smtp,
+  "@plotday/twister/tools/store": tools_store,
+  "@plotday/twister/tools/tasks": tools_tasks,
+  "@plotday/twister/tools/twists": tools_twists
+};
+
+export default llmDocs;

package/src/llm-docs/options.ts

@@ -0,0 +1,8 @@
+/**
+ * Generated LLM documentation for @plotday/twister/options
+ *
+ * This file is auto-generated during build. Do not edit manually.
+ * Generated from: prebuild.ts
+ */
+
+export default "import { ITool } from \"./tool\";\n\n/**\n * A select option definition for twist configuration.\n * Renders as a dropdown in the Flutter UI.\n */\nexport type SelectDef = {\n  type: \"select\";\n  label: string;\n  description?: string;\n  choices: ReadonlyArray<{ value: string; label: string }>;\n  default: string;\n};\n\n/**\n * A text input option definition for twist configuration.\n * Renders as a text field in the Flutter UI.\n */\nexport type TextDef = {\n  type: \"text\";\n  label: string;\n  description?: string;\n  default: string;\n  placeholder?: string;\n  secure?: boolean; // Encrypted at rest, masked in UI, never returned to clients\n  helpText?: string; // Help text displayed below the input field\n  helpUrl?: string; // URL for a \"Learn more\" link shown after helpText\n};\n\n/**\n * A number input option definition for twist configuration.\n * Renders as a number field in the Flutter UI.\n */\nexport type NumberDef = {\n  type: \"number\";\n  label: string;\n  description?: string;\n  default: number;\n  min?: number;\n  max?: number;\n};\n\n/**\n * A boolean toggle option definition for twist configuration.\n * Renders as a switch in the Flutter UI.\n */\nexport type BooleanDef = {\n  type: \"boolean\";\n  label: string;\n  description?: string;\n  default: boolean;\n};\n\n/**\n * Union of all option definition types.\n */\nexport type OptionDef = SelectDef | TextDef | NumberDef | BooleanDef;\n\n/**\n * Schema defining all configurable options for a twist.\n * Each key maps to an option definition that describes its type, label, and default value.\n */\nexport type OptionsSchema = Record<string, OptionDef>;\n\n/**\n * Infers the resolved value types from an options schema.\n * Boolean options resolve to `boolean`, number options to `number`,\n * and select/text options to `string`.\n */\nexport type ResolvedOptions<T extends OptionsSchema> = {\n  [K in keyof T]: T[K] extends BooleanDef\n    ? boolean\n    : T[K] extends NumberDef\n      ? number\n      : string;\n};\n\n/**\n * Built-in marker class for twist configuration options.\n *\n * Declare options in your twist's `build()` method to expose configurable\n * settings to users. The schema is introspected at deploy time and stored\n * alongside permissions. At runtime, user values are merged with defaults.\n *\n * @example\n * ```typescript\n * import { Options, type OptionsSchema } from \"@plotday/twister/options\";\n *\n * export default class MyTwist extends Twist<MyTwist> {\n *   build(build: ToolBuilder) {\n *     return {\n *       options: build(Options, {\n *         model: {\n *           type: 'select',\n *           label: 'AI Model',\n *           choices: [\n *             { value: 'fast', label: 'Fast' },\n *             { value: 'smart', label: 'Smart' },\n *           ],\n *           default: 'fast',\n *         },\n *       }),\n *       // ... other tools\n *     };\n *   }\n *\n *   async respond(note: Note) {\n *     const model = this.tools.options.model; // typed as string\n *   }\n * }\n * ```\n */\nexport abstract class Options extends ITool {\n  static readonly toolId = \"Options\";\n}\n";