@plotday/twister 0.47.0 → 0.49.0

package/src/plot.ts

@@ -0,0 +1,1068 @@
+import type { NewSchedule, NewScheduleOccurrence, Schedule } from "./schedule";
+import { type Tag } from "./tag";
+import { type Callback } from "./tools/callbacks";
+import { type AuthProvider } from "./tools/integrations";
+import { type JSONValue } from "./utils/types";
+import { Uuid } from "./utils/uuid";
+
+export { Tag } from "./tag";
+export { Uuid } from "./utils/uuid";
+export { type JSONValue } from "./utils/types";
+export { type AuthProvider } from "./tools/integrations";
+
+/**
+ * @fileoverview
+ * Core Plot entity types for working with threads, notes, priorities, and contacts.
+ *
+ * ## Type Pattern: Null vs Undefined Semantics
+ *
+ * Plot entity types use a consistent pattern to distinguish between missing, unset, and explicitly cleared values:
+ *
+ * ### Entity Types (Thread, Priority, Note, Actor)
+ * - **Required fields**: No `?`, cannot be `undefined`
+ *   - Example: `id: Uuid`, `title: string`
+ * - **Nullable fields**: Use `| null` to allow explicit clearing
+ *   - Example: `assignee: ActorId | null`, `done: Date | null`
+ *   - `null` = field is explicitly unset/cleared
+ *   - Non-null value = field has a value
+ * - **Optional nullable fields**: Use `?` with `| null` for permission-based access
+ *   - Example: `email?: string | null`, `name?: string | null`
+ *   - `undefined` = field not included (e.g., no permission to access)
+ *   - `null` = field included but not set
+ *   - Value = field has a value
+ *
+ * ### New* Types (NewThread, NewNote, NewPriority)
+ * Used for creating or updating entities. Support partial updates by distinguishing omitted vs cleared fields:
+ * - **Required fields**: Must be provided (no `?`)
+ *   - Example: `title: string` in NewPriority
+ * - **Optional fields**: Use `?` to make them optional
+ *   - Example: `title?: string`, `author?: NewActor`
+ *   - `undefined` (omitted) = don't set/update this field
+ *   - Provided value = set/update this field
+ * - **Optional nullable fields**: Use `?` with `| null` to support clearing
+ *   - Example: `assignee?: NewActor | null`
+ *   - `undefined` (omitted) = don't change assignee
+ *   - `null` = clear the assignee
+ *   - NewActor = set/update the assignee
+ *
+ * This pattern allows API consumers to:
+ * 1. Omit fields they don't want to change (undefined)
+ * 2. Explicitly clear fields by setting to null
+ * 3. Set or update fields by providing values
+ *
+ * @example
+ * ```typescript
+ * // Creating a new thread
+ * const newThread: NewThread = {
+ *   title: "Review pull request",
+ * };
+ *
+ * // Updating a thread - only change what's specified
+ * const update: ThreadUpdate = {
+ *   id: threadId,
+ *   archived: true,
+ * };
+ * ```
+ */
+
+/**
+ * Represents a unique user, contact, or twist in Plot.
+ *
+ * ActorIds are used throughout Plot for:
+ * - Activity authors and assignees
+ * - Tag creators (actor_id in activity_tag/note_tag)
+ * - Mentions in activities and notes
+ * - Any entity that can perform actions in Plot
+ */
+export type ActorId = string & { readonly __brand: "ActorId" };
+
+/**
+ * Theme colors for priorities.
+ */
+export enum ThemeColor {
+  /** Catalyst - Green */
+  Catalyst = 0,
+  /** Call to Adventure - Blue */
+  CallToAdventure = 1,
+  /** Rising Action - Purple */
+  RisingAction = 2,
+  /** Momentum - Pink-Purple */
+  Momentum = 3,
+  /** Turning Point - Pink */
+  TurningPoint = 4,
+  /** Breakthrough - Orange */
+  Breakthrough = 5,
+  /** Climax - Olive */
+  Climax = 6,
+  /** Resolution - Blue-Gray */
+  Resolution = 7,
+}
+
+/**
+ * Represents a priority context within Plot.
+ *
+ * Priorities are similar to projects in other apps. All Activity is in a Priority.
+ * Priorities can be nested.
+ */
+export type Priority = {
+  /** Unique identifier for the priority */
+  id: Uuid;
+  /** Human-readable title for the priority */
+  title: string;
+  /** Whether this priority has been archived */
+  archived: boolean;
+  /**
+   * Optional key for referencing this priority.
+   * Keys are unique per priority tree (a user's personal priorities or the root of a shared priority).
+   */
+  key: string | null;
+  /** Optional theme color for the priority (0-7). If not set, inherits from parent or defaults to 7 (Resolution). */
+  color: ThemeColor | null;
+};
+
+/**
+ * Type for creating new priorities.
+ *
+ * Supports multiple creation patterns:
+ * - Provide a specific UUID for the priority
+ * - Provide a key for upsert within the user's priorities
+ * - Omit both to auto-generate a new UUID
+ *
+ * Optionally specify a parent priority by ID or key for hierarchical structures.
+ */
+export type NewPriority = Pick<Priority, "title"> &
+  Partial<Omit<Priority, "id" | "title">> &
+  (
+    | {
+        /**
+         * Unique identifier for the priority, generated by Uuid.Generate().
+         * Specifying an ID allows tools to track and upsert priorities.
+         */
+        id: Uuid;
+      }
+    | {
+        /**
+         * Unique key for the priority within the user's priorities.
+         * Can be used to upsert without knowing the UUID.
+         * For example, "@plot" identifies the Plot priority.
+         */
+        key: string;
+      }
+    | {
+        /* Neither id nor key is required. An id will be generated and returned. */
+      }
+  ) & {
+    /** Add the new priority as the child of another priority */
+    parent?: { id: Uuid } | { key: string };
+  };
+
+/**
+ * Type for updating existing priorities.
+ * Must provide either id or key to identify the priority to update.
+ * Set `parent` to move the priority under a new parent (requires PriorityAccess.Full).
+ */
+export type PriorityUpdate = ({ id: Uuid } | { key: string }) &
+  Partial<Pick<Priority, "title" | "archived">> & {
+    /** Move the priority under a new parent. Requires PriorityAccess.Full. */
+    parent?: { id: Uuid } | { key: string };
+  };
+
+/**
+ * Enumeration of supported action types.
+ *
+ * Different action types have different behaviors when clicked by users
+ * and may require different rendering approaches.
+ */
+export enum ActionType {
+  /** External web links that open in browser */
+  external = "external",
+  /** Authentication flows for connecting services */
+  auth = "auth",
+  /** Callback actions that trigger twist methods when clicked */
+  callback = "callback",
+  /** Video conferencing links with provider-specific handling */
+  conferencing = "conferencing",
+  /** File attachment links stored in R2 */
+  file = "file",
+  /** Thread reference links for navigating to related threads */
+  thread = "thread",
+  /** Structured plan of operations for user approval */
+  plan = "plan",
+}
+
+/**
+ * Video conferencing providers for conferencing links.
+ *
+ * Used to identify the conferencing platform and provide
+ * provider-specific UI elements (titles, icons, etc.).
+ */
+export enum ConferencingProvider {
+  /** Google Meet */
+  googleMeet = "googleMeet",
+  /** Zoom */
+  zoom = "zoom",
+  /** Microsoft Teams */
+  microsoftTeams = "microsoftTeams",
+  /** Cisco Webex */
+  webex = "webex",
+  /** Other or unknown conferencing provider */
+  other = "other",
+}
+
+/**
+ * Represents a clickable action attached to a thread.
+ *
+ * Thread actions are rendered as buttons that enable user interaction with threads.
+ * Different action types have specific behaviors and required fields for proper functionality.
+ *
+ * @example
+ * ```typescript
+ * // External action - opens URL in browser
+ * const externalAction: Action = {
+ *   type: ActionType.external,
+ *   title: "Open in Google Calendar",
+ *   url: "https://calendar.google.com/event/123",
+ * };
+ *
+ * // Conferencing action - opens video conference with provider info
+ * const conferencingAction: Action = {
+ *   type: ActionType.conferencing,
+ *   url: "https://meet.google.com/abc-defg-hij",
+ *   provider: ConferencingProvider.googleMeet,
+ * };
+ *
+ * // Integrations action - initiates OAuth flow
+ * const authAction: Action = {
+ *   type: ActionType.auth,
+ *   title: "Continue with Google",
+ *   provider: AuthProvider.Google,
+ *   scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
+ *   callback: "callback-token-for-auth-completion"
+ * };
+ *
+ * // Callback action - triggers a twist method
+ * const callbackAction: Action = {
+ *   type: ActionType.callback,
+ *   title: "📅 Primary Calendar",
+ *   token: "callback-token-here"
+ * };
+ * ```
+ */
+export type Action =
+  | {
+      /** External web link that opens in browser */
+      type: ActionType.external;
+      /** Display text for the action button */
+      title: string;
+      /** URL to open when clicked */
+      url: string;
+    }
+  | {
+      /** Video conferencing action with provider-specific handling */
+      type: ActionType.conferencing;
+      /** URL to join the conference */
+      url: string;
+      /** Conferencing provider for UI customization */
+      provider: ConferencingProvider;
+    }
+  | {
+      /** Authentication action that initiates an OAuth flow */
+      type: ActionType.auth;
+      /** Display text for the auth button */
+      title: string;
+      /** OAuth provider (e.g., "google", "microsoft") */
+      provider: string;
+      /** Array of OAuth scopes to request */
+      scopes: string[];
+      /** Callback token for auth completion notification */
+      callback: Callback;
+    }
+  | {
+      /** Callback action that triggers a twist method when clicked */
+      type: ActionType.callback;
+      /** Display text for the callback button */
+      title: string;
+      /** Token identifying the callback to execute */
+      callback: Callback;
+    }
+  | {
+      /** File attachment action stored in R2 */
+      type: ActionType.file;
+      /** Unique identifier for the stored file */
+      fileId: string;
+      /** Original filename */
+      fileName: string;
+      /** File size in bytes */
+      fileSize: number;
+      /** MIME type of the file */
+      mimeType: string;
+      /** Intrinsic width of the image in pixels (only for image files) */
+      imageWidth?: number | null;
+      /** Intrinsic height of the image in pixels (only for image files) */
+      imageHeight?: number | null;
+    }
+  | {
+      /** Thread reference action for navigating to a related thread */
+      type: ActionType.thread;
+      /** UUID of the referenced thread */
+      threadId: Uuid;
+    }
+  | {
+      /** Structured plan of operations for user approval */
+      type: ActionType.plan;
+      /** Human-readable summary of the plan */
+      title: string;
+      /** Operations to execute on approval */
+      operations: PlanOperation[];
+      /** Callback invoked with (action, approved: boolean) */
+      callback: Callback;
+    };
+
+/**
+ * Represents metadata about a thread, typically from an external system.
+ *
+ * Thread metadata enables storing additional information about threads,
+ * which is useful for synchronization, linking back to external systems,
+ * and storing tool-specific data.
+ *
+ * Must be valid JSON data (strings, numbers, booleans, null, objects, arrays).
+ * Functions and other non-JSON values are not supported.
+ *
+ * @example
+ * ```typescript
+ * // Calendar event metadata
+ * await plot.createThread({
+ *   title: "Team Meeting",
+ *   meta: {
+ *     calendarId: "primary",
+ *     htmlLink: "https://calendar.google.com/event/abc123",
+ *     conferenceData: { ... }
+ *   }
+ * });
+ *
+ * // Project issue metadata
+ * await plot.createThread({
+ *   title: "Fix login bug",
+ *   meta: {
+ *     projectId: "TEAM",
+ *     issueNumber: 123,
+ *     url: "https://linear.app/team/issue/TEAM-123"
+ *   }
+ * });
+ * ```
+ */
+export type ThreadMeta = {
+  /** Source-specific properties and metadata */
+  [key: string]: JSONValue;
+};
+
+/**
+ * Thread sub-type that determines the thread's icon and category.
+ * Available types depend on whether the priority is shared:
+ * - Private priorities: "action" (default for tasks), "notes" (default), "idea", "goal", "decision"
+ * - Shared priorities: all above plus "discussion" (default), "announcement", "ask"
+ */
+export type ThreadType =
+  | "action"
+  | "notes"
+  | "idea"
+  | "goal"
+  | "decision"
+  | "discussion"
+  | "announcement"
+  | "ask";
+
+/**
+ * Tags on an item, along with the actors who added each tag.
+ */
+export type Tags = { [K in Tag]?: ActorId[] };
+
+/**
+ * A set of tags to add to an item, along with the actors adding each tag.
+ */
+export type NewTags = { [K in Tag]?: NewActor[] };
+
+/**
+ * Thread access level determining visibility.
+ * - "public": Visible to all users with priority access
+ * - "members": Visible to priority members (default for shared priorities)
+ * - "private": Visible only to creator and contacts listed in accessContacts
+ */
+export type ThreadAccessLevel = "public" | "members" | "private";
+
+/**
+ * Common fields shared by both Thread and Note entities.
+ */
+export type ThreadCommon = {
+  /** Unique identifier for the thread */
+  id: Uuid;
+  /**
+   * When this item was created.
+   *
+   * **For sources:** Set this to the external system's timestamp (e.g., email
+   * sent date, comment creation date), NOT the sync time. If omitted, defaults
+   * to the current time, which is almost never correct for synced data.
+   */
+  created: Date;
+  /** Whether this thread has been archived */
+  archived: boolean;
+  /** Tags attached to this thread. Maps tag ID to array of actor IDs who added that tag. */
+  tags: Tags;
+};
+
+/**
+ * Fields on a Thread entity.
+ * Threads are simple containers for links and notes.
+ */
+type ThreadFields = ThreadCommon & {
+  /** The display title/summary of the thread */
+  title: string;
+  /** The priority context this thread belongs to */
+  priority: Priority;
+  /** The thread's sub-type/category. Determines the displayed icon. */
+  type: ThreadType | null;
+  /** Thread access level: "public", "members", or "private" */
+  access: ThreadAccessLevel;
+  /** Contacts who can see a private thread (empty array for creator-only). Only meaningful when access is "private". */
+  accessContacts: Contact[];
+  /** The schedule associated with this thread, if any */
+  schedule?: Schedule;
+  /** Source-specific metadata from the thread's link, populated on callbacks */
+  meta?: ThreadMeta;
+};
+
+export type Thread = ThreadFields;
+
+export type ThreadWithNotes = Thread & {
+  notes: Note[];
+};
+
+export type NewThreadWithNotes = NewThread & {
+  notes: Omit<NewNote, "thread">[];
+};
+
+/**
+ * Type for creating new threads.
+ *
+ * Threads are simple containers. All other fields are optional.
+ *
+ * @example
+ * ```typescript
+ * const thread: NewThread = {
+ *   title: "Review pull request"
+ * };
+ * ```
+ */
+export type NewThread = Partial<
+  Omit<ThreadFields, "priority" | "tags" | "id" | "accessContacts">
+> &
+  (
+    | {
+        /** Unique identifier for the thread, generated by Uuid.Generate(). */
+        id: Uuid;
+      }
+    | {
+        /* id is optional. An id will be generated and returned. */
+      }
+  ) &
+  {
+    /** Explicit priority - disables automatic priority matching. When omitted, the server classifies the thread using the user's priority rules. */
+    priority?: Pick<Priority, "id">;
+  } & {
+    /**
+     * All tags to set on the new thread.
+     */
+    tags?: NewTags;
+
+    /**
+     * The thread's sub-type/category. Sets the thread's icon.
+     * If omitted, defaults to "notes" (private) or "discussion" (shared).
+     */
+    type?: ThreadType;
+
+    /**
+     * Contacts who can see a private thread.
+     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.
+     * If omitted for a private thread, defaults to the connection owner.
+     */
+    accessContacts?: NewContact[];
+
+    /**
+     * Whether the thread should be marked as unread for users.
+     * - undefined/omitted (default): Thread is unread for users, except auto-marked
+     *   as read for the author if they are the twist owner (user)
+     * - true: Thread is explicitly unread for ALL users (use sparingly)
+     * - false: Thread is marked as read for all users in the priority at creation time
+     */
+    unread?: boolean;
+
+    /**
+     * Whether the thread is archived.
+     * - true: Archive the thread
+     * - false: Unarchive the thread
+     * - undefined (default): Preserve current archive state
+     */
+    archived?: boolean;
+
+    /**
+     * Optional preview content for the thread. Can be Markdown formatted.
+     * The preview will be automatically generated from this content (truncated to 100 chars).
+     */
+    preview?: string | null;
+
+    /**
+     * Optional schedules to create alongside the thread.
+     */
+    schedules?: Array<Omit<NewSchedule, "threadId">>;
+
+    /**
+     * Optional schedule occurrence overrides.
+     */
+    scheduleOccurrences?: NewScheduleOccurrence[];
+  };
+
+export type ThreadFilter = {
+  meta?: {
+    [key: string]: JSONValue;
+  };
+};
+
+/**
+ * Fields supported by bulk updates via `match`. Only simple scalar fields
+ * that can be applied uniformly across many threads are included.
+ */
+type ThreadBulkUpdateFields = Partial<
+  Pick<ThreadFields, "title" | "access" | "archived">
+> & {
+  /** Contacts who can see a private thread. Pass NewContact objects (email-based); resolved by the API. */
+  accessContacts?: NewContact[];
+};
+
+/**
+ * Fields supported by single-thread updates via `id` or `source`.
+ * Includes all bulk fields plus tags and preview.
+ */
+type ThreadSingleUpdateFields = ThreadBulkUpdateFields & {
+  /**
+   * Tags to change on the thread. Use an empty array of NewActor to remove a tag.
+   * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
+   */
+  tags?: NewTags;
+
+  /**
+   * Add or remove the twist's tags.
+   * Maps tag ID to boolean: true = add tag, false = remove tag.
+   * This is allowed on all threads the twist has access to.
+   */
+  twistTags?: Partial<Record<Tag, boolean>>;
+
+  /**
+   * Update the thread's sub-type/category.
+   */
+  type?: ThreadType;
+
+  /**
+   * Optional preview content for the thread. Can be Markdown formatted.
+   * The preview will be automatically generated from this content (truncated to 100 chars).
+   *
+   * - string: Use this content for preview generation
+   * - null: Explicitly disable preview (no preview will be shown)
+   * - undefined (omitted): Preserve current preview value
+   *
+   * This field is write-only and won't be returned when reading threads.
+   */
+  preview?: string | null;
+
+  /**
+   * Move the thread to a different priority. Requires ThreadAccess.Full.
+   * The target priority must be owned by the twist's user.
+   */
+  priority?: Pick<Priority, "id">;
+};
+
+export type ThreadUpdate =
+  | (({ id: Uuid } | { source: string }) & ThreadSingleUpdateFields)
+  | ({
+      /**
+       * Update all threads matching the specified criteria. Only threads
+       * that match all provided fields and were created by the twist will be updated.
+       */
+      match: ThreadFilter;
+    } & ThreadBulkUpdateFields);
+
+/**
+ * Represents a note within a thread.
+ *
+ * Notes contain the detailed content (note text, actions) associated with a thread.
+ * They are always ordered by creation time within their parent thread.
+ */
+export type Note = ThreadCommon & {
+  /** The author of this note */
+  author: Actor;
+  /**
+   * Globally unique, stable identifier for the note within its thread.
+   * Can be used to upsert without knowing the id.
+   *
+   * Use one of these patterns:
+   *   - Hardcoded semantic keys for fixed note types: "description", "cancellation"
+   *   - External service IDs for dynamic collections: `comment:${immutableId}`
+   *
+   * Examples:
+   *   - `"description"` (for a Jira issue's description note)
+   *   - `"comment:12345"` (for a specific comment by ID)
+   *   - `"gmail:msg:18d4e5f2a3b1c9d7"` (for a Gmail message within a thread)
+   *
+   * Ensure IDs are immutable - avoid human-readable slugs or titles.
+   */
+  key: string | null;
+  /** The parent thread this note belongs to */
+  thread: Thread;
+  /** Primary content for the note (markdown) */
+  content: string | null;
+  /** Array of interactive actions attached to the note */
+  actions: Array<Action> | null;
+  /** The note this is a reply to, or null if not a reply */
+  reNote: { id: Uuid } | null;
+  /**
+   * Contacts who can see this note, or null if the note inherits thread visibility.
+   * When set (even to []), the note is private to the listed contacts plus the creator.
+   */
+  accessContacts: ActorId[] | null;
+  /** Priority twist IDs (twists/connectors) mentioned for dispatch routing. Does not include user contacts. */
+  mentions: ActorId[];
+};
+
+/**
+ * Type for creating new notes.
+ *
+ * Requires the thread reference, with all other fields optional.
+ * Can provide id, key, or neither for note identification:
+ * - id: Provide a specific UUID for the note
+ * - key: Provide an external identifier for upsert within the thread
+ * - neither: A new note with auto-generated UUID will be created
+ */
+export type NewNote = Partial<
+  Omit<
+    Note,
+    "author" | "thread" | "tags" | "mentions" | "accessContacts" | "id" | "key" | "reNote"
+  >
+> &
+  ({ id: Uuid } | { key: string } | {}) & {
+    /** Reference to the parent thread (required) */
+    thread:
+      | Pick<Thread, "id">
+      | {
+          source: string;
+        };
+
+    /**
+     * The person that created the item, or leave undefined to use the twist as author.
+     */
+    author?: NewActor;
+
+    /**
+     * Format of the note content. Determines how the note is processed:
+     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)
+     * - 'markdown': Already in markdown format (default, no conversion)
+     * - 'html': HTML content that will be converted to markdown
+     */
+    contentType?: ContentType;
+
+    /**
+     * Tags to change on the thread. Use an empty array of NewActor to remove a tag.
+     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
+     */
+    tags?: NewTags;
+
+    /**
+     * Contacts who can see this note, or null/undefined to inherit thread visibility.
+     * Accepts resolved ActorId UUIDs or email-based NewContact objects (resolved server-side).
+     * Include all participants who should see the note (sender + recipients).
+     * The note author is NOT implicitly included — add them explicitly.
+     * When set (even to []), the note is private to the listed contacts plus the creator.
+     */
+    accessContacts?: (ActorId | NewContact)[] | null;
+
+    /**
+     * Twist/connector IDs to mention for dispatch routing.
+     * Does not include user contacts — use accessContacts for visibility.
+     */
+    mentions?: NewActor[];
+
+    /**
+     * Whether the note should mark the parent thread as unread for users.
+     * - undefined/omitted (default): Thread is unread for users, except auto-marked
+     *   as read for the author if they are the twist owner (user)
+     * - true: Thread is explicitly unread for ALL users (use sparingly)
+     * - false: Thread is marked as read for all users in the priority at note creation time
+     *
+     * For the default behavior, omit this field entirely.
+     * Use false for initial sync to avoid marking historical items as unread.
+     */
+    unread?: boolean;
+
+    /**
+     * When true, the server will use AI to detect tasks in this note's content
+     * and create separate Plot-authored reply notes for each detected task.
+     * Use for messaging connectors (email, chat) where tasks are implicit
+     * in conversation rather than explicitly structured.
+     */
+    checkForTasks?: boolean;
+
+    /**
+     * Reference to a parent note this note is a reply to.
+     * - `{ id }`: reply by UUID
+     * - `{ key }`: reply by key, resolved after creation (for batch ops)
+     * - `null`: explicitly not a reply
+     * - `undefined` (omitted): not a reply
+     */
+    reNote?: { id: Uuid } | { key: string } | null;
+  };
+
+/**
+ * Type for updating existing notes.
+ * Must provide either id or key to identify the note to update.
+ */
+export type NoteUpdate = ({ id: Uuid; key?: string } | { key: string }) &
+  Partial<
+    Pick<Note, "accessContacts" | "archived" | "content" | "actions" | "reNote">
+  > & {
+    /**
+     * Format of the note content. Determines how the note is processed:
+     * - 'text': Plain text that will be converted to markdown (auto-links URLs, preserves line breaks)
+     * - 'markdown': Already in markdown format (default, no conversion)
+     * - 'html': HTML content that will be converted to markdown
+     */
+    contentType?: ContentType;
+
+    /**
+     * Tags to change on the note. Use an empty array of NewActor to remove a tag.
+     * Use twistTags to add/remove the twist from tags to avoid clearing other actors' tags.
+     */
+    tags?: NewTags;
+
+    /**
+     * Add or remove the twist's tags.
+     * Maps tag ID to boolean: true = add tag, false = remove tag.
+     * This is allowed on all notes the twist has access to.
+     */
+    twistTags?: Partial<Record<Tag, boolean>>;
+
+    /**
+     * Twist/connector IDs to mention for dispatch routing.
+     * Does not include user contacts — use accessContacts for visibility.
+     */
+    mentions?: NewActor[];
+  };
+
+/**
+ * Represents an actor in Plot - a user, contact, or twist.
+ *
+ * Actors can be associated with threads as authors, assignees, or mentions.
+ * The email field is only included when ContactAccess.Read permission is granted.
+ *
+ * @example
+ * ```typescript
+ * const actor: Actor = {
+ *   id: "f0ffd5f8-1635-4b13-9532-35f97446db90" as ActorId,
+ *   type: ActorType.Contact,
+ *   email: "john.doe@example.com",  // Only if ContactAccess.Read
+ *   name: "John Doe"
+ * };
+ * ```
+ */
+export type Actor = {
+  /** Unique identifier for the actor */
+  id: ActorId;
+  /** Type of actor (User, Contact, or Twist) */
+  type: ActorType;
+  /**
+   * Email address (only included with ContactAccess.Read permission).
+   * - `undefined`: No permission to read email
+   * - `null`: Permission granted but email not set
+   * - `string`: Email address
+   */
+  email?: string | null;
+  /**
+   * Display name.
+   * - `undefined`: Not included due to permissions
+   * - `null`: Not set
+   * - `string`: Display name
+   */
+  name?: string | null;
+};
+
+/**
+ * A resolved contact with identity info. Used for access control lists
+ * where only human contacts (not twists) are relevant.
+ */
+export type Contact = {
+  /** Unique identifier for the contact */
+  id: ActorId;
+  /** Email address, or null if not set */
+  email: string | null;
+  /** Display name, or null if not set */
+  name: string | null;
+};
+
+/**
+ * An existing or new contact.
+ */
+export type NewActor =
+  | {
+      /** Unique identifier for the actor */
+      id: ActorId;
+    }
+  | NewContact;
+
+/**
+ * Enumeration of author types that can create threads.
+ *
+ * The author type affects how threads are displayed and processed
+ * within the Plot system.
+ */
+export enum ActorType {
+  /** Threads created by human users */
+  User,
+  /** Threads created by external contacts */
+  Contact,
+  /** Threads created by automated twists */
+  Twist,
+}
+
+/**
+ * Represents contact information for creating a new contact.
+ *
+ * Contacts are used throughout Plot for representing people associated
+ * with activities, such as event attendees or task assignees.
+ *
+ * @example
+ * ```typescript
+ * const newContact: NewContact = {
+ *   email: "john.doe@example.com",
+ *   name: "John Doe",
+ *   avatar: "https://avatar.example.com/john.jpg"
+ * };
+ * ```
+ */
+/**
+ * Common fields shared by all NewContact variants.
+ */
+type NewContactBase = {
+  /** Optional avatar image URL for the contact */
+  avatar?: string;
+  /**
+   * External provider account source. Used for identity resolution
+   * when email is unavailable and for privacy compliance reporting.
+   */
+  source?: { provider: AuthProvider; accountId: string };
+};
+
+/**
+ * At least one of `email` or `name` must be provided so the contact can be
+ * identified in the UI. Contacts with neither would display as "Unknown".
+ */
+export type NewContact = NewContactBase &
+  ({ email: string; name?: string } | { email?: string; name: string });
+
+export type ContentType = "text" | "markdown" | "html";
+
+/**
+ * Represents an external entity linked to a thread.
+ *
+ * Links are created by sources to represent external entities (issues, emails, calendar events)
+ * attached to a thread container. A thread can have multiple links (1:many).
+ * Links store source-specific data like type, status, metadata, and embeddings.
+ *
+ * @example
+ * ```typescript
+ * // A link representing a Linear issue
+ * const link: Link = {
+ *   threadId: "..." as Uuid,
+ *   source: "linear:issue:549dd8bd-2bc9-43d1-95d5-4b4af0c5af1b",
+ *   created: new Date(),
+ *   author: { id: "..." as ActorId, type: ActorType.Contact, name: "Alice" },
+ *   title: "Fix login bug",
+ *   type: "issue",
+ *   status: "open",
+ *   meta: { projectId: "TEAM", url: "https://linear.app/team/TEAM-123" },
+ *   assignee: null,
+ *   actions: null,
+ * };
+ * ```
+ */
+export type Link = {
+  /** The thread this link belongs to */
+  threadId: Uuid;
+  /** External source identifier for dedup/upsert */
+  source: string | null;
+  /** When this link was originally created in its source system */
+  created: Date;
+  /** The actor credited with creating this link */
+  author: Actor | null;
+  /** Display title */
+  title: string;
+  /** Truncated preview */
+  preview: string | null;
+  /** The actor assigned to this link */
+  assignee: Actor | null;
+  /** Source-defined type string (e.g., issue, pull_request, email, event) */
+  type: string | null;
+  /** Source-defined status string (e.g., open, done, closed) */
+  status: string | null;
+  /** Interactive action buttons */
+  actions: Array<Action> | null;
+  /** Source metadata */
+  meta: ThreadMeta | null;
+  /** URL to open the original item in its source application (e.g., "Open in Linear") */
+  sourceUrl: string | null;
+  /** Channel ID that produced this link (matches source_channel.channel_id) */
+  channelId: string | null;
+  /**
+   * Cross-connector thread bundling key.
+   * When set, this link shares a thread with any link whose `source` matches
+   * this value (or whose `relatedSource` matches this link's `source`).
+   * Works regardless of creation order.
+   */
+  relatedSource: string | null;
+};
+
+/**
+ * Type for creating new links.
+ *
+ * Links are created by sources to represent external entities.
+ * Requires a source identifier for dedup/upsert.
+ */
+export type NewLink = (
+  | {
+      /**
+       * Canonical ID for the item in an external system.
+       * When set, uniquely identifies the link within a priority tree. This performs
+       * an upsert.
+       */
+      source: string;
+    }
+  | {}
+) &
+  Partial<Omit<Link, "source" | "author" | "assignee" | "threadId">> & {
+    /** The person that created the item. By default, it will be the twist itself. */
+    author?: NewActor;
+    /** The person assigned to the item. */
+    assignee?: NewActor | null;
+    /**
+     * Thread access level: "public", "members" (default), or "private".
+     * When "private", thread visibility is limited to the creator and contacts in accessContacts.
+     */
+    access?: ThreadAccessLevel;
+    /**
+     * Contacts who can see a private thread.
+     * Pass email-based NewContact objects; they are resolved to contact IDs by the API.
+     * If omitted for a private thread, defaults to the connection owner.
+     */
+    accessContacts?: NewContact[];
+    /**
+     * Whether the thread should be marked as unread for users.
+     * - undefined/omitted (default): Thread is unread for users, except auto-marked
+     *   as read for the author if they are the twist owner (user)
+     * - false: Thread is marked as read for all users in the priority at creation time
+     */
+    unread?: boolean;
+    /**
+     * Whether the thread is archived.
+     * - true: Archive the thread
+     * - false: Unarchive the thread
+     * - undefined (default): Preserve current archive state
+     */
+    archived?: boolean;
+    /**
+     * Explicit priority (disables automatic priority matching).
+     * Only used when the link creates a new thread. When omitted, the
+     * server classifies the thread using the user's priority rules.
+     */
+    priority?: Pick<Priority, "id">;
+  };
+
+/**
+ * A new link with notes to save via integrations.saveLink().
+ * Creates a thread+link pair, with notes attached to the thread.
+ */
+export type NewLinkWithNotes = NewLink & {
+  /**
+   * Title for the link and its thread container.
+   * Must be the real entity title (e.g. issue title, message subject),
+   * never a placeholder or ID. This value overwrites the existing title on upsert.
+   * Omit to preserve the existing title (e.g. for cancelled events where the
+   * title may not be available in the webhook payload).
+   */
+  title?: string;
+  /** Notes to attach to the thread */
+  notes?: Omit<NewNote, "thread">[];
+  /** Schedules to create for the link */
+  schedules?: Array<Omit<NewSchedule, "threadId">>;
+  /** Schedule occurrence overrides */
+  scheduleOccurrences?: NewScheduleOccurrence[];
+};
+
+/**
+ * Type for updating existing links.
+ *
+ * Set `threadId` to move the link to a different thread.
+ * Requires LinkAccess.Full.
+ */
+export type LinkUpdate = { id: Uuid } & {
+  /** Move the link to a different thread owned by the twist's user. */
+  threadId?: Uuid;
+};
+
+/**
+ * A single operation within a plan submitted for user approval.
+ *
+ * Operations include display metadata (titles) so the app can render
+ * a human-readable summary without additional lookups.
+ */
+export type PlanOperation =
+  | {
+      type: "updateThread";
+      threadId: Uuid;
+      /** Current thread title for display */
+      threadTitle: string;
+      changes: Partial<Pick<ThreadFields, "archived" | "title" | "type">> & {
+        /** Move to this priority */
+        priority?: { id: Uuid; title: string };
+      };
+    }
+  | {
+      type: "updateLink";
+      linkId: Uuid;
+      /** Current link title for display */
+      linkTitle: string;
+      changes: {
+        /** Move to this thread */
+        threadId?: Uuid;
+        threadTitle?: string;
+      };
+    }
+  | {
+      type: "createThread";
+      title: string;
+      priorityId: Uuid;
+      /** Priority title for display */
+      priorityTitle: string;
+    }
+  | {
+      type: "createNote";
+      threadId: Uuid;
+      /** Thread title for display */
+      threadTitle: string;
+      content: string;
+    }
+  | {
+      type: "updatePriority";
+      priorityId: Uuid;
+      /** Current priority title for display */
+      priorityTitle: string;
+      changes: Partial<Pick<Priority, "title" | "archived">> & {
+        /** Move under this parent */
+        parent?: { id: Uuid; title: string };
+      };
+    };