@plotday/twister 0.40.0 → 0.42.0

package/dist/llm-docs/plot.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\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, priorities, 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, Priority, 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, NewPriority)\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 NewPriority\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 priorities.\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 priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"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  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\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: \"\uD83D\uDCC5 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    }\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/**\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 * 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 * 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 is private (only visible to creator) */\n  private: boolean;\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  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\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 priority context this thread belongs to */\n  priority: Priority;\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 * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\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, \"priority\" | \"tags\" | \"mentions\" | \"id\">\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    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\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 priority 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\" | \"private\" | \"archived\">\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   * 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   * 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\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.\n   * Can be used to upsert without knowing the id.\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\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\" | \"mentions\" | \"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     * Change the mentions on the note.\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 priority 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     * 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, \"private\" | \"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     * 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     * Change the mentions on the note.\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 * 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 */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\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 *   id: \"...\" as Uuid,\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  /** Unique identifier for the link */\n  id: Uuid;\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\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 = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\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     * 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 priority 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     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"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  /** Title for the link and its thread container */\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";
+declare const _default: "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\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, priorities, 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, Priority, 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, NewPriority)\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 NewPriority\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 priorities.\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 priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"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  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\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: \"\uD83D\uDCC5 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    }\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/**\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 * 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 * 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 is private (only visible to creator) */\n  private: boolean;\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  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\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 priority context this thread belongs to */\n  priority: Priority;\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 * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\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, \"priority\" | \"tags\" | \"mentions\" | \"id\">\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    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\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 priority 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\" | \"private\" | \"archived\">\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   * 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   * 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\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.\n   * Can be used to upsert without knowing the id.\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\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\" | \"mentions\" | \"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     * Change the mentions on the note.\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 priority 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     * 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, \"private\" | \"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     * 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     * Change the mentions on the note.\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 * 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 */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\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  source?: { provider: AuthProvider; accountId: string };\n};\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 *   id: \"...\" as Uuid,\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  /** Unique identifier for the link */\n  id: Uuid;\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\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 = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\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     * 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 priority 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     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"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   * If the title is not available in the webhook payload, fetch it from the API.\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";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

package/dist/llm-docs/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,su6BAA4t6B;AAA3u6B,wBAA4u6B"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,886BAAo86B;AAAn96B,wBAAo96B"}

package/dist/llm-docs/plot.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * 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 AuthProvider } from \"./tools/integrations\";\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, priorities, 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, Priority, 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, NewPriority)\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 NewPriority\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 priorities.\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 priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"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  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\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    }\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/**\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 * 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 * 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 is private (only visible to creator) */\n  private: boolean;\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  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\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 priority context this thread belongs to */\n  priority: Priority;\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 * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\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, \"priority\" | \"tags\" | \"mentions\" | \"id\">\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    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\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 priority 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\" | \"private\" | \"archived\">\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   * 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   * 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\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.\n   * Can be used to upsert without knowing the id.\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\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\" | \"mentions\" | \"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     * Change the mentions on the note.\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 priority 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     * 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, \"private\" | \"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     * 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     * Change the mentions on the note.\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 * 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 */\nexport type NewContact = {\n  /** Email address of the contact (required) */\n  email: string;\n  /** Optional display name for the contact */\n  name?: string;\n  /** Optional avatar image URL for the contact */\n  avatar?: string;\n  /**\n   * External provider account source. Used for privacy compliance\n   * (e.g. Atlassian personal data reporting for GDPR account closure).\n   * Required for contacts sourced from providers that mandate personal data reporting.\n   */\n  source?: { provider: AuthProvider; accountId: string };\n};\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 *   id: \"...\" as Uuid,\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  /** Unique identifier for the link */\n  id: Uuid;\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\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 = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\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     * 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 priority 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     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"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  /** Title for the link and its thread container */\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";
+export default "import type { NewSchedule, NewScheduleOccurrence, Schedule } from \"./schedule\";\nimport { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { type AuthProvider } from \"./tools/integrations\";\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, priorities, 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, Priority, 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, NewPriority)\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 NewPriority\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 priorities.\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 priority context within Plot.\n *\n * Priorities are similar to projects in other apps. All Activity is in a Priority.\n * Priorities can be nested.\n */\nexport type Priority = {\n  /** Unique identifier for the priority */\n  id: Uuid;\n  /** Human-readable title for the priority */\n  title: string;\n  /** Whether this priority has been archived */\n  archived: boolean;\n  /**\n   * Optional key for referencing this priority.\n   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).\n   */\n  key: string | null;\n  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */\n  color: ThemeColor | null;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Supports multiple creation patterns:\n * - Provide a specific UUID for the priority\n * - Provide a key for upsert within the user's priorities\n * - Omit both to auto-generate a new UUID\n *\n * Optionally specify a parent priority by ID or key for hierarchical structures.\n */\nexport type NewPriority = Pick<Priority, \"title\"> &\n  Partial<Omit<Priority, \"id\" | \"title\">> &\n  (\n    | {\n        /**\n         * Unique identifier for the priority, generated by Uuid.Generate().\n         * Specifying an ID allows tools to track and upsert priorities.\n         */\n        id: Uuid;\n      }\n    | {\n        /**\n         * Unique key for the priority within the user's priorities.\n         * Can be used to upsert without knowing the UUID.\n         * For example, \"@plot\" identifies the Plot priority.\n         */\n        key: string;\n      }\n    | {\n        /* Neither id nor key is required. An id will be generated and returned. */\n      }\n  ) & {\n    /** Add the new priority as the child of another priority */\n    parent?: { id: Uuid } | { key: string };\n  };\n\n/**\n * Type for updating existing priorities.\n * Must provide either id or key to identify the priority to update.\n */\nexport type PriorityUpdate = ({ id: Uuid } | { key: string }) &\n  Partial<Pick<Priority, \"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  /** Thread reference links for navigating to related threads */\n  thread = \"thread\",\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    }\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/**\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 * 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 * 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 is private (only visible to creator) */\n  private: boolean;\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  /** Array of actor IDs (users, contacts, or twists) mentioned in this thread via @-mentions */\n  mentions: ActorId[];\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 priority context this thread belongs to */\n  priority: Priority;\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 * Configuration for automatic priority selection based on thread similarity.\n *\n * Maps thread fields to scoring weights or required exact matches:\n * - Number value: Maximum score for similarity matching on this field\n * - `true` value: Required exact match - threads must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on thread embedding (cosine similarity)\n * - mentions: Percentage of existing thread's mentions that appear in new thread\n * - meta.field: Exact match on top-level meta fields (e.g., \"meta.sourceId\")\n *\n * When content is `true`, applies a strong similarity threshold to ensure only close matches.\n * Default (when neither priority nor pickPriority specified): `{content: true}`\n *\n * @example\n * ```typescript\n * // Require exact content match with strong similarity\n * pickPriority: { content: true }\n *\n * // Score based on content (max 100 points) and mentions\n * pickPriority: { content: 100, mentions: true }\n *\n * // Match on meta and score content\n * pickPriority: { \"meta.projectId\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\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, \"priority\" | \"tags\" | \"mentions\" | \"id\">\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    | {\n        /** Explicit priority (required when specified) - disables automatic priority matching */\n        priority: Pick<Priority, \"id\">;\n      }\n    | {\n        /** Configuration for automatic priority selection based on similarity */\n        pickPriority?: PickPriorityConfig;\n      }\n  ) & {\n    /**\n     * All tags to set on the new thread.\n     */\n    tags?: NewTags;\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 priority 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\" | \"private\" | \"archived\">\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   * 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   * 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\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.\n   * Can be used to upsert without knowing the id.\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\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\" | \"mentions\" | \"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     * Change the mentions on the note.\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 priority 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     * 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, \"private\" | \"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     * 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     * Change the mentions on the note.\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 * 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 */\nexport type NewContact = {\n  /**\n   * Email address of the contact.\n   * Either email or source must be provided for contact resolution.\n   */\n  email?: string;\n  /** Optional display name for the contact */\n  name?: string;\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  source?: { provider: AuthProvider; accountId: string };\n};\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 *   id: \"...\" as Uuid,\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  /** Unique identifier for the link */\n  id: Uuid;\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\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 = (\n  | {\n      /** Unique identifier for the link, generated by Uuid.Generate() */\n      id: Uuid;\n    }\n  | {\n      /**\n       * Canonical ID for the item in an external system.\n       * When set, uniquely identifies the link within a priority tree. This performs\n       * an upsert.\n       */\n      source: string;\n    }\n  | {}\n) &\n  Partial<Omit<Link, \"id\" | \"source\" | \"author\" | \"assignee\" | \"threadId\">> & {\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     * 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 priority 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     * Configuration for automatic priority selection based on similarity.\n     * Only used when the link creates a new thread.\n     */\n    pickPriority?: PickPriorityConfig;\n    /**\n     * Explicit priority (disables automatic priority matching).\n     * Only used when the link creates a new thread.\n     */\n    priority?: Pick<Priority, \"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   * If the title is not available in the webhook payload, fetch it from the API.\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";
 //# sourceMappingURL=plot.js.map

package/dist/llm-docs/plot.js.map

@@ -1 +1 @@
-{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,4t6BAA4t6B,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,o86BAAo86B,CAAC"}

package/dist/llm-docs/tools/integrations.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\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  /** Priority ID this channel is routed to (set when channel is enabled) */\n  priorityId?: string;\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  /** 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    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: 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   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\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\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\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\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}\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";
+declare const _default: "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\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  /** Priority ID this channel is routed to (set when channel is enabled) */\n  priorityId?: string;\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  /** 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    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: 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   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\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\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\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\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}\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 _default;
 //# sourceMappingURL=integrations.d.ts.map

package/dist/llm-docs/tools/integrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,4mUAA4mU;AAA3nU,wBAA4nU"}
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,+tUAA+tU;AAA9uU,wBAA+uU"}

package/dist/llm-docs/tools/integrations.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-export default "import {\n  type Actor,\n  type ActorId,\n  type NewContact,\n  type NewLinkWithNotes,\n  ITool,\n  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\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  /** Priority ID this channel is routed to (set when channel is enabled) */\n  priorityId?: string;\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  /** 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    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: 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   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\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\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\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\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}\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  Serializable,\n} from \"..\";\nimport { Tag } from \"../tag\";\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  /** Priority ID this channel is routed to (set when channel is enabled) */\n  priorityId?: string;\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  /** 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    /** Tag to propagate to thread when this status is active (e.g., Tag.Done) */\n    tag?: Tag;\n    /** Whether this status represents completion (done, closed, merged, cancelled, etc.) */\n    done?: boolean;\n  }>;\n  /** Whether this link type supports displaying and changing the assignee */\n  supportsAssignee?: 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   * Execute a callback as a specific actor, requesting auth if needed.\n   *\n   * If the actor has a valid token, calls the callback immediately with it.\n   * If the actor has no token, creates a private auth note in the specified\n   * activity prompting them to connect. Once they authorize, this callback fires.\n   *\n   * @param provider - The OAuth provider\n   * @param actorId - The actor to act as\n   * @param activityId - The activity to create an auth note in (if needed)\n   * @param callback - Function to call with the token\n   * @param extraArgs - Additional arguments to pass to the callback\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract actAs<\n    TArgs extends Serializable[],\n    TCallback extends (token: AuthToken, ...args: TArgs) => any\n  >(\n    provider: AuthProvider,\n    actorId: ActorId,\n    activityId: Uuid,\n    callback: TCallback,\n    ...extraArgs: TArgs\n  ): Promise<void>;\n\n  /**\n   * Saves a link with notes to the connector's priority.\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\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract saveLink(link: NewLinkWithNotes): Promise<Uuid>;\n\n  /**\n   * Saves contacts to the connector's priority.\n   *\n   * @param contacts - Array of contacts to save\n   * @returns Promise resolving to the saved actors\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\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}\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";
 //# sourceMappingURL=integrations.js.map

package/dist/llm-docs/tools/integrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,4mUAA4mU,CAAC"}
+{"version":3,"file":"integrations.js","sourceRoot":"","sources":["../../../src/llm-docs/tools/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,+tUAA+tU,CAAC"}

package/dist/llm-docs/tools/plot.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: prebuild.ts
  */
-declare const _default: "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewContact,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n  /** Create and update contacts. */\n  Write,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  priority: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /** Scope search to this priority + descendants (default: twist's installed priority). Must be within the twist's allowed scope. */\n  priorityId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Write\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links in the twist's priority scope. */\n    search?: true;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Adds contacts to the Plot system.\n   *\n   * Contacts are used for associating people with threads, such as\n   * event attendees or task assignees. Duplicate contacts (by email)\n   * will be merged or updated as appropriate.\n   * This method requires ContactAccess.Write permission.\n   *\n   * @param contacts - Array of contact information to add\n   * @returns Promise resolving to array of created/updated actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract addContacts(contacts: Array<NewContact>): Promise<Actor[]>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n}\n";
+declare const _default: "import {\n  type Thread,\n  type ThreadUpdate,\n  type Actor,\n  type ActorId,\n  ITool,\n  type Link,\n  type NewThread,\n  type NewThreadWithNotes,\n  type NewNote,\n  type NewPriority,\n  type Note,\n  type NoteUpdate,\n  type Priority,\n  type PriorityUpdate,\n  Uuid,\n} from \"..\";\nimport {\n  type Schedule,\n  type NewSchedule,\n} from \"../schedule\";\n\nexport enum ThreadAccess {\n  /**\n   * Create new Note on a Thread where the twist was mentioned.\n   * Add/remove tags on Thread or Note where the twist was mentioned.\n   */\n  Respond,\n  /**\n   * Create new Thread.\n   * Create new Note in a Thread the twist created.\n   * All Respond permissions.\n   */\n  Create,\n}\n\nexport enum PriorityAccess {\n  /**\n   * Create a new Priority within the twist's Priority.\n   * Update Priority created by the twist.\n   */\n  Create,\n  /**\n   * Read all Priority within the twist's Priority.\n   * Create a new Priority within the twist's Priority.\n   * Update and archive any Priority within the twist's Priority.\n   */\n  Full,\n}\n\nexport enum ContactAccess {\n  /** Read existing contact details. Without this, only the ID will be provided. */\n  Read,\n}\n\n/**\n * Intent handler for thread mentions.\n * Defines how the twist should respond when mentioned in a thread.\n */\nexport type NoteIntentHandler = {\n  /** Human-readable description of what this intent handles */\n  description: string;\n  /** Example phrases or activity content that would match this intent */\n  examples: string[];\n  /** The function to call when this intent is matched */\n  handler: (note: Note) => Promise<void>;\n};\n\n/**\n * Filter for querying links from connected source channels.\n */\nexport type LinkFilter = {\n  /** Only return links from these channel IDs. */\n  channelIds?: string[];\n  /** Only return links created/updated after this date. */\n  since?: Date;\n  /** Only return links of this type. */\n  type?: string;\n  /** Maximum number of links to return. */\n  limit?: number;\n};\n\ntype SearchResultBase = {\n  thread: { id: string; title: string | null };\n  priority: { id: string; title: string | null };\n  similarity: number;\n};\n\nexport type NoteSearchResult = SearchResultBase & {\n  type: 'note';\n  id: string;\n  content: string | null;\n};\n\nexport type LinkSearchResult = SearchResultBase & {\n  type: 'link';\n  id: string;\n  title: string | null;\n  sourceUrl: string | null;\n  content: string | null;\n};\n\nexport type SearchResult = NoteSearchResult | LinkSearchResult;\n\n/** Default number of search results returned */\nexport const SEARCH_DEFAULT_LIMIT = 10;\n/** Maximum number of search results allowed */\nexport const SEARCH_MAX_LIMIT = 30;\n\nexport type SearchOptions = {\n  /** Max results to return (default: 10, max: 30) */\n  limit?: number;\n  /** Minimum similarity score 0-1 (default: 0.3) */\n  threshold?: number;\n  /** Scope search to this priority + descendants (default: twist's installed priority). Must be within the twist's allowed scope. */\n  priorityId?: string;\n};\n\n/**\n * Built-in tool for interacting with the core Plot data layer.\n *\n * The Plot tool provides twists with the ability to create and manage threads,\n * priorities, and contacts within the Plot system. This is the primary interface\n * for twists to persist data and interact with the Plot database.\n *\n * @example\n * ```typescript\n * class MyTwist extends Twist {\n *   private plot: Plot;\n *\n *   constructor(id: string, tools: ToolBuilder) {\n *     super();\n *     this.plot = tools.get(Plot);\n *   }\n *\n *   async activate(priority) {\n *     // Create a welcome thread\n *     await this.plot.createThread({\n *       title: \"Welcome to Plot!\",\n *       actions: [{\n *         title: \"Get Started\",\n *         type: ActionType.external,\n *         url: \"https://plot.day/docs\"\n *       }]\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class Plot extends ITool {\n  /**\n   * Configuration options for the Plot tool.\n   *\n   * **Important**: All permissions must be explicitly requested. There are no default permissions.\n   *\n   * @example\n   * ```typescript\n   * // Minimal configuration with required permissions\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create\n   *       }\n   *     })\n   *   };\n   * }\n   *\n   * // Full configuration with callbacks\n   * build(build: ToolBuilder) {\n   *   return {\n   *     plot: build(Plot, {\n   *       thread: {\n   *         access: ThreadAccess.Create,\n   *       },\n   *       note: {\n   *         intents: [{\n   *           description: \"Schedule meetings\",\n   *           examples: [\"Schedule a meeting tomorrow\"],\n   *           handler: this.onSchedulingIntent\n   *         }],\n   *       },\n   *       link: true,\n   *       priority: {\n   *         access: PriorityAccess.Full\n   *       },\n   *       contact: {\n   *         access: ContactAccess.Read\n   *       }\n   *     })\n   *   };\n   * }\n   * ```\n   */\n  static readonly Options: {\n    thread?: {\n      /**\n       * Capability to create Notes and modify tags.\n       * Must be explicitly set to grant permissions.\n       */\n      access?: ThreadAccess;\n      /** When true, auto-mention this twist on new notes in threads where it authored content. */\n      defaultMention?: boolean;\n    };\n    note?: {\n      /** When true, auto-mention this twist on new notes in threads where it was @-mentioned. */\n      defaultMention?: boolean;\n      /**\n       * Respond to mentions in notes.\n       *\n       * When a note mentions this twist, the system will match the note\n       * content against these intents and call the matching handler.\n       *\n       * @example\n       * ```typescript\n       * intents: [{\n       *   description: \"Schedule or reschedule calendar events\",\n       *   examples: [\"Schedule a meeting tomorrow at 2pm\", \"Move my 3pm meeting to 4pm\"],\n       *   handler: this.onSchedulingRequest\n       * }, {\n       *   description: \"Find available meeting times\",\n       *   examples: [\"When am I free this week?\", \"Find time for a 1 hour meeting\"],\n       *   handler: this.onAvailabilityRequest\n       * }]\n       * ```\n       */\n      intents?: NoteIntentHandler[];\n    };\n    /** Enable link processing from connected source channels. */\n    link?: true;\n    priority?: {\n      access?: PriorityAccess;\n    };\n    contact?: {\n      access?: ContactAccess;\n    };\n    /** Enable semantic search across notes and links in the twist's priority scope. */\n    search?: true;\n  };\n\n  /**\n   * Creates a new thread in the Plot system.\n   *\n   * The thread will be automatically assigned an ID and author information\n   * based on the current execution context. All other fields from NewThread\n   * will be preserved in the created thread.\n   *\n   * @param thread - The thread data to create\n   * @returns Promise resolving to the created thread's ID\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThread(\n    thread: NewThread | NewThreadWithNotes\n  ): Promise<Uuid>;\n\n  /**\n   * Creates multiple threads in a single batch operation.\n   *\n   * This method efficiently creates multiple threads at once, which is\n   * more performant than calling createThread() multiple times individually.\n   * All threads are created with the same author and access control rules.\n   *\n   * @param threads - Array of thread data to create\n   * @returns Promise resolving to array of created thread IDs\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createThreads(\n    threads: (NewThread | NewThreadWithNotes)[]\n  ): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing thread in the Plot system.\n   *\n   * **Important**: This method only updates existing threads. It will throw an error\n   * if the thread does not exist. Use `createThread()` to create or update (upsert)\n   * threads.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire thread object.\n   *\n   * For tags, provide a Record<number, boolean> where true adds a tag and false removes it.\n   * Tags not included in the update remain unchanged.\n   *\n   * When updating the parent, the thread's path will be automatically recalculated to\n   * maintain the correct hierarchical structure.\n   *\n   * Scheduling is handled separately via `createSchedule()` / `updateSchedule()`.\n   *\n   * @param thread - The thread update containing the ID or source and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the thread does not exist\n   *\n   * @example\n   * ```typescript\n   * // Mark a task as complete\n   * await this.plot.updateThread({\n   *   id: \"task-123\",\n   *   done: new Date()\n   * });\n   *\n   * // Add and remove tags\n   * await this.plot.updateThread({\n   *   id: \"thread-789\",\n   *   tags: {\n   *     1: true,  // Add tag with ID 1\n   *     2: false  // Remove tag with ID 2\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateThread(thread: ThreadUpdate): Promise<void>;\n\n  /**\n   * Retrieves all notes within a thread.\n   *\n   * Notes are detailed entries within a thread, ordered by creation time.\n   * Each note can contain markdown content, actions, and other detailed information\n   * related to the parent thread.\n   *\n   * @param thread - The thread whose notes to retrieve\n   * @returns Promise resolving to array of notes in the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNotes(thread: Thread): Promise<Note[]>;\n\n  /**\n   * Creates a new note in a thread.\n   *\n   * Notes provide detailed content within a thread, supporting markdown,\n   * actions, and other rich content. The note will be automatically assigned\n   * an ID and author information based on the current execution context.\n   *\n   * @param note - The note data to create\n   * @returns Promise resolving to the created note's ID\n   *\n   * @example\n   * ```typescript\n   * // Create a note with content\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-123\" },\n   *   note: \"Discussion notes from the meeting...\",\n   *   contentType: \"markdown\"\n   * });\n   *\n   * // Create a note with actions\n   * await this.plot.createNote({\n   *   thread: { id: \"thread-456\" },\n   *   note: \"Meeting recording available\",\n   *   actions: [{\n   *     type: ActionType.external,\n   *     title: \"View Recording\",\n   *     url: \"https://example.com/recording\"\n   *   }]\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNote(note: NewNote): Promise<Uuid>;\n\n  /**\n   * Creates multiple notes in a single batch operation.\n   *\n   * This method efficiently creates multiple notes at once, which is\n   * more performant than calling createNote() multiple times individually.\n   * All notes are created with the same author and access control rules.\n   *\n   * @param notes - Array of note data to create\n   * @returns Promise resolving to array of created note IDs\n   *\n   * @example\n   * ```typescript\n   * // Create multiple notes in one batch\n   * await this.plot.createNotes([\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"First message in thread\"\n   *   },\n   *   {\n   *     thread: { id: \"thread-123\" },\n   *     note: \"Second message in thread\"\n   *   }\n   * ]);\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;\n\n  /**\n   * Updates an existing note in the Plot system.\n   *\n   * **Important**: This method only updates existing notes. It will throw an error\n   * if the note does not exist. Use `createNote()` to create or update (upsert) notes.\n   *\n   * Only the fields provided in the update object will be modified - all other fields\n   * remain unchanged. This enables partial updates without needing to fetch and resend\n   * the entire note object.\n   *\n   * @param note - The note update containing the ID or key and fields to change\n   * @returns Promise that resolves when the update is complete\n   * @throws Error if the note does not exist\n   *\n   * @example\n   * ```typescript\n   * // Update note content\n   * await this.plot.updateNote({\n   *   id: \"note-123\",\n   *   note: \"Updated content with more details\"\n   * });\n   *\n   * // Add tags to a note\n   * await this.plot.updateNote({\n   *   id: \"note-456\",\n   *   twistTags: {\n   *     [Tag.Important]: true\n   *   }\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updateNote(note: NoteUpdate): Promise<void>;\n\n  /**\n   * Retrieves a thread by ID or source.\n   *\n   * This method enables lookup of threads either by their unique ID or by their\n   * source identifier (canonical URL from an external system). Archived threads\n   * are included in the results.\n   *\n   * @param thread - Thread lookup by ID or source\n   * @returns Promise resolving to the matching thread or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getThread(\n    thread: { id: Uuid } | { source: string }\n  ): Promise<Thread | null>;\n\n  /**\n   * Retrieves a note by ID or key.\n   *\n   * This method enables lookup of notes either by their unique ID or by their\n   * key (unique identifier within the thread). Archived notes are included\n   * in the results.\n   *\n   * @param note - Note lookup by ID or key\n   * @returns Promise resolving to the matching note or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>;\n\n  /**\n   * Creates a new priority in the Plot system.\n   *\n   * Priorities serve as organizational containers for threads and twists.\n   * The created priority will be automatically assigned a unique ID.\n   *\n   * @param priority - The priority data to create\n   * @returns Promise resolving to the complete created priority\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createPriority(priority: NewPriority): Promise<Priority & { created: boolean }>;\n\n  /**\n   * Retrieves a priority by ID or key.\n   *\n   * Archived priorities are included in the results.\n   *\n   * @param priority - Priority lookup by ID or key\n   * @returns Promise resolving to the matching priority or null if not found\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getPriority(\n    priority: { id: Uuid } | { key: string }\n  ): Promise<Priority | null>;\n\n  /**\n   * Updates an existing priority in the Plot system.\n   *\n   * The priority is identified by either its ID or key.\n   * Only the fields specified in the update will be changed.\n   *\n   * @param update - Priority update containing ID/key and fields to change\n   * @returns Promise that resolves when the update is complete\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract updatePriority(update: PriorityUpdate): Promise<void>;\n\n  /**\n   * Retrieves actors by their IDs.\n   *\n   * Actors represent users, contacts, or twists in the Plot system.\n   * This method requires ContactAccess.Read permission.\n   *\n   * @param ids - Array of actor IDs to retrieve\n   * @returns Promise resolving to array of actors\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getActors(ids: ActorId[]): Promise<Actor[]>;\n\n  /**\n   * Creates a new schedule for a thread.\n   *\n   * Schedules define when a thread occurs in time. A thread can have\n   * multiple schedules (shared and per-user).\n   *\n   * @param schedule - The schedule data to create\n   * @returns Promise resolving to the created schedule\n   *\n   * @example\n   * ```typescript\n   * // Schedule a timed event\n   * const threadId = await this.plot.createThread({\n   *   title: \"Team standup\"\n   * });\n   * await this.plot.createSchedule({\n   *   threadId,\n   *   start: new Date(\"2025-01-15T10:00:00Z\"),\n   *   end: new Date(\"2025-01-15T10:30:00Z\"),\n   *   recurrenceRule: \"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR\"\n   * });\n   * ```\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract createSchedule(schedule: NewSchedule): Promise<Schedule>;\n\n  /**\n   * Retrieves all schedules for a thread.\n   *\n   * @param threadId - The thread whose schedules to retrieve\n   * @returns Promise resolving to array of schedules for the thread\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getSchedules(threadId: Uuid): Promise<Schedule[]>;\n\n  /**\n   * Retrieves links from connected source channels.\n   *\n   * Requires `link: true` in Plot options.\n   *\n   * @param filter - Optional filter criteria for links\n   * @returns Promise resolving to array of links with their notes\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract getLinks(filter?: LinkFilter): Promise<Array<{ link: Link; notes: Note[] }>>;\n\n  /**\n   * Searches notes and links using semantic similarity.\n   *\n   * Requires `search: true` in Plot options.\n   *\n   * @param query - The search query text\n   * @param options - Optional search configuration\n   * @returns Promise resolving to array of search results ordered by similarity\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  abstract search(query: string, options?: SearchOptions): Promise<SearchResult[]>;\n}\n";
 export default _default;
 //# sourceMappingURL=plot.d.ts.map

package/dist/llm-docs/tools/plot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,swkBAAswkB;AAArxkB,wBAAsxkB"}
+{"version":3,"file":"plot.d.ts","sourceRoot":"","sources":["../../../src/llm-docs/tools/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,6njBAA6njB;AAA5ojB,wBAA6ojB"}