@plotday/twister 0.26.0 → 0.27.0

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 Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\n\nexport { Tag } from \"./tag\";\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 * 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: string;\n  /** Human-readable title for the priority */\n  title: string;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Excludes the auto-generated ID field and adds an optional parentId\n * for creating hierarchical priority structures.\n */\nexport type NewPriority = Omit<Priority, \"id\"> & {\n  /** Optional ID of the parent priority for creating hierarchies */\n  parentId?: string;\n};\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\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 link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: 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 link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables tracking where activities originated from,\n * which is useful for synchronization, deduplication, and linking\n * back to external systems.\n *\n * ## Source-Based Upsert\n *\n * When creating an activity with a `source` field, Plot automatically implements\n * **upsert behavior**. If an activity with the same source already exists (created\n * by the same twist definition), it will be **updated** instead of creating a duplicate.\n * This enables safe, idempotent sync operations.\n *\n * ### How Source Uniqueness Works\n *\n * - **Scoped to twist definition**: Sources are unique per twist, not per twist instance.\n *   Different instances of the same twist (installed in different priorities) share\n *   the same source namespace.\n * - **Independent twists**: Different twists can have activities with the same source value.\n * - **Archived activities**: Archived activities don't conflict with active ones - you can\n *   create a new activity with the same source after archiving.\n * - **Optional**: Activities without sources are always created fresh - no deduplication.\n *\n * ### Upsert Behavior Details\n *\n * When an activity is upserted (updated instead of created):\n * - **All provided fields** are updated with new values\n * - **Tags** are merged (existing tags + new tags)\n * - **Notes** are appended (existing notes kept, new ones added)\n * - **Priority** is NOT changed (stays in original priority)\n *\n * @example\n * ```typescript\n * // First call creates the activity\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\n *   source: \"google-calendar:event-abc123\",\n *   meta: {\n *     calendarId: \"primary\",\n *     htmlLink: \"https://calendar.google.com/event/abc123\"\n *   }\n * });\n *\n * // Second call with same source updates the existing activity\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting (Updated)\",  // Title will be updated\n *   start: new Date(\"2024-01-15T14:00:00Z\"),  // Time will be updated\n *   source: \"google-calendar:event-abc123\"  // Same source = upsert\n * });\n *\n * // Different twist, same source = creates new activity (independent)\n * // Different source = creates new activity\n * // No source = creates new activity (no deduplication)\n * ```\n */\nexport type ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: any;\n};\n\nexport type Tags = { [K in Tag]?: ActorId[] };\n\n/**\n * Represents a complete activity within the Plot system.\n *\n * Activities are the core entities in Plot, representing anything from simple notes\n * to complex recurring events. They support rich metadata including scheduling,\n * recurrence patterns, links, and external source tracking.\n *\n * @example\n * ```typescript\n * // Simple note\n * const task: Activity = {\n *   type: ActivityType.Note,\n *   title: \"New campaign brainstorming ideas\",\n *   content: \"We could rent a bouncy castle...\",\n *   author: { id: \"user-1\", name: \"John Doe\", type: ActorType.User },\n *   priority: { id: \"work\", title: \"Work\" },\n *   // ... other fields\n * };\n *\n * // Simple action\n * const action: Activity = {\n *   type: ActivityType.Action,\n *   title: \"Review budget proposal\",\n *   author: { id: \"user-1\", name: \"John Doe\", type: ActorType.User },\n *   priority: { id: \"work\", title: \"Work\" },\n *   // ... other fields\n * };\n *\n * // Recurring event\n * const meeting: Activity = {\n *   type: ActivityType.Event,\n *   title: \"Weekly standup\",\n *   recurrenceRule: \"FREQ=WEEKLY;BYDAY=MO\",\n *   recurrenceCount: 12,\n *   // ... other fields\n * };\n * ```\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: string;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. Maps tag ID to array of actor IDs who added that tag. */\n  tags: Tags | null;\n  /** Array of actor IDs (users, contacts, or twists) mentioned in this activity via @-mentions */\n  mentions: ActorId[] | null;\n};\n\nexport type Activity = ActivityCommon & {\n  /** The display title/summary of the activity */\n  title: string | null;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):** An assignee is required. If not explicitly provided when creating\n   * an action, the assignee will default to the user who installed the twist (the twist owner).\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action with explicit assignee\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   *\n   * // Create action with auto-assignment (defaults to twist owner)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee will be set automatically to twist owner\n   * };\n   *\n   * // Update assignee\n   * await plot.updateActivity({\n   *   id: activityId,\n   *   assignee: {\n   *     id: newUserId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Bob\"\n   *   }\n   * });\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  doneAt: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating a NewActivity of type Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - defaults to current time when start is omitted\n   * await this.tools.plot.createActivity({ type: ActivityType.Action, title: \"Urgent task\" });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unscheduled backlog item\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /**\n   * Unique identifier for this activity in the source system.\n   *\n   * Used for deduplication - activities with the same source are upserted instead\n   * of creating duplicates. Format is typically \"source-name:external-id\"\n   * (e.g., \"google-calendar:event-123\", \"outlook:message-456\").\n   *\n   * When provided, enables idempotent sync operations - calling createActivity()\n   * multiple times with the same source will update the existing activity rather\n   * than creating duplicates.\n   */\n  source: string | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity 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 - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\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 require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta source and score content\n * pickPriority: { \"meta.source\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The ID and author will be automatically assigned by the Plot system\n * based on the current execution context.\n *\n * **Important: Scheduling Defaults for Actions**\n *\n * When creating an Activity of type `Action`, the `start` field determines its scheduling state:\n * - **Omit `start`** → Defaults to current time → \"Do Now\" (appears in today's actionable list)\n * - **Set `start: null`** → Unscheduled → \"Do Someday\" (backlog item, no specific time)\n * - **Set `start` to future Date** → Scheduled → \"Do Later\" (appears on that date)\n *\n * For most external task integrations (project management, issue trackers), use `start: null`\n * to create backlog items unless the task is explicitly marked as current/active.\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Action defaults to current time (actionable today)\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // Omitting start defaults to new Date()\n * };\n *\n * // \"Do Someday\" - Backlog item (recommended for most synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null  // Explicitly set to null for backlog\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<Omit<Activity, \"id\" | \"author\" | \"type\" | \"priority\" | \"mentions\">> &\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    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = Pick<Activity, \"id\"> &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"doneAt\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"source\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Full tags object from Activity. Maps tag ID to array of actor IDs who added that tag.\n     * Only allowed for activities created by the twist.\n     * Use twistTags instead for adding/removing the twist's tags on other activities.\n     */\n    tags?: { [K in Tag]?: ActorId[] };\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 activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = Omit<ActivityCommon, \"type\"> & {\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n */\nexport type NewNote = Partial<Omit<Note, \"id\" | \"author\" | \"activity\">> & {\n  /** Reference to the parent activity (required) */\n  activity: Pick<Activity, \"id\">;\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   * Whether the note should mark the parent activity as unread for users.\n   * - true (default): Activity becomes unread for users who haven't authored the note\n   * - false: Activity is marked as read for all users in the priority at note creation time\n   *\n   * Use false for historical imports to avoid marking old items as unread.\n   */\n  unread?: boolean;\n};\n\n/**\n * Type for updating existing notes.\n */\nexport type NoteUpdate = Pick<Note, \"id\"> &\n  Partial<\n    Pick<Note, \"draft\" | \"private\" | \"content\" | \"links\" | \"mentions\">\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     * Full tags object from Note. Maps tag ID to array of actor IDs who added that tag.\n     * Only allowed for notes created by the twist.\n     * Use twistTags instead for adding/removing the twist's tags on other notes.\n     */\n    tags?: { [K in Tag]?: ActorId[] };\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/**\n * Represents an actor in Plot - a user, contact, or twist.\n *\n * Actors can be associated with activities 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  /** Email address (only included with ContactAccess.Read permission) */\n  email?: string;\n  /** Display name (undefined if not included due to permissions, null if not set) */\n  name?: string | null;\n};\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities 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\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\n";
+export default "import { type Tag } from \"./tag\";\nimport { type Callback } from \"./tools/callbacks\";\nimport { Uuid } from \"./utils/uuid\";\n\nexport { Tag } from \"./tag\";\nexport { Uuid } from \"./utils/uuid\";\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 * 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: string;\n  /** Human-readable title for the priority */\n  title: string;\n};\n\n/**\n * Type for creating new priorities.\n *\n * Excludes the auto-generated ID field and adds an optional parentId\n * for creating hierarchical priority structures.\n */\nexport type NewPriority = Omit<Priority, \"id\"> & {\n  /** Optional ID of the parent priority for creating hierarchies */\n  parentId?: string;\n};\n\n/**\n * Enumeration of supported activity types in Plot.\n *\n * Each activity type has different behaviors and rendering characteristics\n * within the Plot application.\n */\nexport enum ActivityType {\n  /** A note or piece of information without actionable requirements */\n  Note,\n  /** An actionable item that can be completed */\n  Action,\n  /** A scheduled occurrence with start and optional end time */\n  Event,\n}\n\n/**\n * Enumeration of supported activity link types.\n *\n * Different link types have different behaviors when clicked by users\n * and may require different rendering approaches.\n */\nexport enum ActivityLinkType {\n  /** External web links that open in browser */\n  external = \"external\",\n  /** Authentication flows for connecting services */\n  auth = \"auth\",\n  /** Callback links that trigger twist methods when clicked */\n  callback = \"callback\",\n  /** Video conferencing links with provider-specific handling */\n  conferencing = \"conferencing\",\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 link attached to an activity.\n *\n * Activity links are rendered as buttons that enable user interaction with activities.\n * Different link types have specific behaviors and required fields for proper functionality.\n *\n * @example\n * ```typescript\n * // External link - opens URL in browser\n * const externalLink: ActivityLink = {\n *   type: ActivityLinkType.external,\n *   title: \"Open in Google Calendar\",\n *   url: \"https://calendar.google.com/event/123\",\n * };\n *\n * // Conferencing link - opens video conference with provider info\n * const conferencingLink: ActivityLink = {\n *   type: ActivityLinkType.conferencing,\n *   url: \"https://meet.google.com/abc-defg-hij\",\n *   provider: ConferencingProvider.googleMeet,\n * };\n *\n * // Integrations link - initiates OAuth flow\n * const authLink: ActivityLink = {\n *   type: ActivityLinkType.auth,\n *   title: \"Continue with Google\",\n *   provider: AuthProvider.Google,\n *   level: AuthLevel.User,\n *   scopes: [\"https://www.googleapis.com/auth/calendar.readonly\"],\n *   callback: \"callback-token-for-auth-completion\"\n * };\n *\n * // Callback link - triggers a twist method\n * const callbackLink: ActivityLink = {\n *   type: ActivityLinkType.callback,\n *   title: \"📅 Primary Calendar\",\n *   token: \"callback-token-here\"\n * };\n * ```\n */\nexport type ActivityLink =\n  | {\n      /** External web link that opens in browser */\n      type: ActivityLinkType.external;\n      /** Display text for the link button */\n      title: string;\n      /** URL to open when clicked */\n      url: string;\n    }\n  | {\n      /** Video conferencing link with provider-specific handling */\n      type: ActivityLinkType.conferencing;\n      /** URL to join the conference */\n      url: string;\n      /** Conferencing provider for UI customization */\n      provider: ConferencingProvider;\n    }\n  | {\n      /** Authentication link that initiates an OAuth flow */\n      type: ActivityLinkType.auth;\n      /** Display text for the auth button */\n      title: string;\n      /** OAuth provider (e.g., \"google\", \"microsoft\") */\n      provider: string;\n      /** Authorization level (\"user\" or \"priority\") */\n      level: 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 link that triggers a twist method when clicked */\n      type: ActivityLinkType.callback;\n      /** Display text for the callback button */\n      title: string;\n      /** Token identifying the callback to execute */\n      callback: Callback;\n    };\n\n/**\n * Represents metadata about an activity, typically from an external system.\n *\n * Activity metadata enables storing additional information about activities,\n * which is useful for synchronization, linking back to external systems,\n * and storing tool-specific data.\n *\n * @example\n * ```typescript\n * // Calendar event metadata\n * await plot.createActivity({\n *   type: ActivityType.Event,\n *   title: \"Team Meeting\",\n *   start: new Date(\"2024-01-15T10:00:00Z\"),\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.createActivity({\n *   type: ActivityType.Action,\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 ActivityMeta = {\n  /** Source-specific properties and metadata */\n  [key: string]: any;\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 Activity and Note entities.\n */\nexport type ActivityCommon = {\n  /** Unique identifier for the activity */\n  id: Uuid;\n  /**\n   * When this activity was originally created in its source system.\n   *\n   * For activities created in Plot, this is when the user created it.\n   * For activities synced from external systems (GitHub issues, emails, calendar events),\n   * this is the original creation time in that system.\n   *\n   * Defaults to the current time when creating new activities.\n   */\n  createdAt: Date;\n  /** Information about who created the activity */\n  author: Actor;\n  /** Whether this activity is in draft state (not shown in do now view) */\n  draft: boolean;\n  /** Whether this activity is private (only visible to author) */\n  private: boolean;\n  /** Whether this activity has been archived */\n  archived: boolean;\n  /** Tags attached to this activity. 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 activity via @-mentions */\n  mentions: ActorId[];\n};\n\nexport type Activity = ActivityCommon & {\n  /** The display title/summary of the activity */\n  title: string;\n  /** The type of activity (Note, Task, or Event) */\n  type: ActivityType;\n  /**\n   * The actor assigned to this activity.\n   *\n   * **For actions (tasks):** An assignee is required. If not explicitly provided when creating\n   * an action, the assignee will default to the user who installed the twist (the twist owner).\n   *\n   * **For notes and events:** Assignee is optional and typically null.\n   *\n   * @example\n   * ```typescript\n   * // Create action with explicit assignee\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Review PR #123\",\n   *   assignee: {\n   *     id: userId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Alice\"\n   *   }\n   * };\n   *\n   * // Create action with auto-assignment (defaults to twist owner)\n   * const task: NewActivity = {\n   *   type: ActivityType.Action,\n   *   title: \"Follow up on email\"\n   *   // assignee will be set automatically to twist owner\n   * };\n   *\n   * // Update assignee\n   * await plot.updateActivity({\n   *   id: activityId,\n   *   assignee: {\n   *     id: newUserId as ActorId,\n   *     type: ActorType.User,\n   *     name: \"Bob\"\n   *   }\n   * });\n   * ```\n   */\n  assignee: Actor | null;\n  /** Timestamp when the activity was marked as complete. Null if not completed. */\n  doneAt: Date | null;\n  /**\n   * Start time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the start of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   *\n   * **Activity Scheduling States** (for Actions):\n   * - **Do Now** (current/actionable): When creating a NewActivity of type Action, omitting `start` defaults to current time\n   * - **Do Later** (future scheduled): Set `start` to a future Date or date string\n   * - **Do Someday** (unscheduled backlog): Explicitly set `start: null`\n   *\n   * @example\n   * ```typescript\n   * // \"Do Now\" - defaults to current time when start is omitted\n   * await this.tools.plot.createActivity({ type: ActivityType.Action, title: \"Urgent task\" });\n   *\n   * // \"Do Later\" - scheduled for a specific time\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Future task\",\n   *   start: new Date(\"2025-02-01\")\n   * });\n   *\n   * // \"Do Someday\" - unscheduled backlog item\n   * await this.tools.plot.createActivity({\n   *   type: ActivityType.Action,\n   *   title: \"Backlog task\",\n   *   start: null\n   * });\n   * ```\n   */\n  start: Date | string | null;\n  /**\n   * End time of a scheduled activity. Notes are not typically scheduled unless they're about specific times.\n   * For recurring events, this represents the end of the first occurrence.\n   * Can be a Date object for timed events or a date string in \"YYYY-MM-DD\" format for all-day events.\n   * Null for tasks or activities without defined end times.\n   */\n  end: Date | string | null;\n  /**\n   * For recurring activities, the last occurrence date (inclusive).\n   * Can be a Date object, date string in \"YYYY-MM-DD\" format, or null if recurring indefinitely.\n   * When both recurrenceCount and recurrenceUntil are provided, recurrenceCount takes precedence.\n   */\n  recurrenceUntil: Date | string | null;\n  /**\n   * For recurring activities, the number of occurrences to generate.\n   * Takes precedence over recurrenceUntil if both are provided.\n   * Null for non-recurring activities or indefinite recurrence.\n   */\n  recurrenceCount: number | null;\n  /** The priority context this activity belongs to */\n  priority: Priority;\n  /** Recurrence rule in RFC 5545 RRULE format (e.g., \"FREQ=WEEKLY;BYDAY=MO,WE,FR\") */\n  recurrenceRule: string | null;\n  /** Array of dates to exclude from the recurrence pattern */\n  recurrenceExdates: Date[] | null;\n  /** Array of additional occurrence dates to include in the recurrence pattern */\n  recurrenceDates: Date[] | null;\n  /**\n   * For recurring event exceptions, points to the root recurring activity.\n   * Used when an individual occurrence of a recurring event is modified.\n   */\n  recurrence: Activity | null;\n  /**\n   * For recurring event exceptions, the original occurrence date being overridden.\n   * Used to identify which occurrence of a recurring event this exception replaces.\n   */\n  occurrence: Date | null;\n  /** Metadata about the activity, typically from an external system that created it */\n  meta: ActivityMeta | null;\n};\n\nexport type ActivityWithNotes = Activity & {\n  notes: Note[];\n};\n\nexport type NewActivityWithNotes = NewActivity & {\n  notes: Omit<NewNote, \"activity\">[];\n};\n\n/**\n * Configuration for automatic priority selection based on activity similarity.\n *\n * Maps activity 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 - activities must match exactly or be excluded\n *\n * Scoring rules:\n * - content: Uses vector similarity on activity embedding (cosine similarity)\n * - type: Exact match on ActivityType\n * - mentions: Percentage of existing activity's mentions that appear in new activity\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 require exact type match\n * pickPriority: { content: 100, type: true }\n *\n * // Match on meta source and score content\n * pickPriority: { \"meta.source\": true, content: 50 }\n * ```\n */\nexport type PickPriorityConfig = {\n  content?: number | true;\n  type?: number | true;\n  mentions?: number | true;\n  [key: `meta.${string}`]: number | true;\n};\n\n/**\n * Type for creating new activities.\n *\n * Requires only the activity type, with all other fields optional.\n * The author will be automatically assigned by the Plot system based on\n * the current execution context. The ID can be optionally provided by\n * tools for tracking and update detection purposes.\n *\n * **Important: Scheduling Defaults for Actions**\n *\n * When creating an Activity of type `Action`, the `start` field determines its scheduling state:\n * - **Omit `start`** → Defaults to current time → \"Do Now\" (appears in today's actionable list)\n * - **Set `start: null`** → Unscheduled → \"Do Someday\" (backlog item, no specific time)\n * - **Set `start` to future Date** → Scheduled → \"Do Later\" (appears on that date)\n *\n * For most external task integrations (project management, issue trackers), use `start: null`\n * to create backlog items unless the task is explicitly marked as current/active.\n *\n * Priority can be specified in three ways:\n * 1. Explicit priority: `priority: { id: \"...\" }` - Use specific priority (disables pickPriority)\n * 2. Pick priority config: `pickPriority: { ... }` - Auto-select based on similarity\n * 3. Neither: Defaults to `pickPriority: { content: true }` for automatic matching\n *\n * @example\n * ```typescript\n * // \"Do Now\" - Action defaults to current time (actionable today)\n * const urgentTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Review pull request\"\n *   // Omitting start defaults to new Date()\n * };\n *\n * // \"Do Someday\" - Backlog item (recommended for most synced tasks)\n * const backlogTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Refactor user service\",\n *   start: null  // Explicitly set to null for backlog\n * };\n *\n * // \"Do Later\" - Scheduled for specific date\n * const futureTask: NewActivity = {\n *   type: ActivityType.Action,\n *   title: \"Prepare Q1 review\",\n *   start: new Date(\"2025-03-15\")\n * };\n *\n * // Note (typically unscheduled)\n * const note: NewActivity = {\n *   type: ActivityType.Note,\n *   title: \"Meeting notes\",\n *   content: \"Discussed Q4 roadmap...\",\n *   start: null  // Notes typically don't have scheduled times\n * };\n *\n * // Event (always has explicit start/end times)\n * const event: NewActivity = {\n *   type: ActivityType.Event,\n *   title: \"Team standup\",\n *   start: new Date(\"2025-01-15T10:00:00\"),\n *   end: new Date(\"2025-01-15T10:30:00\")\n * };\n * ```\n */\nexport type NewActivity = Pick<Activity, \"type\"> &\n  Partial<\n    Omit<\n      Activity,\n      \"author\" | \"assignee\" | \"type\" | \"priority\" | \"tags\" | \"mentions\"\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    /**\n     * The person that created the item. By default, it will be the twist itself.\n     */\n    author?: NewActor;\n\n    /**\n     * The person that assigned to the item.\n     */\n    assignee?: NewActor | null;\n\n    /**\n     * All tags to set on the new activity.\n     */\n    tags?: NewTags;\n\n    /**\n     * Whether the activity should be marked as unread for users.\n     * - true (default): Activity is unread for all users in the priority\n     * - false: Activity is marked as read for all users in the priority at creation time\n     *\n     * Use false for historical imports to avoid marking old items as unread.\n     */\n    unread?: boolean;\n  };\n\nexport type ActivityUpdate = Pick<Activity, \"id\"> &\n  Partial<\n    Pick<\n      Activity,\n      | \"type\"\n      | \"start\"\n      | \"end\"\n      | \"doneAt\"\n      | \"title\"\n      | \"assignee\"\n      | \"draft\"\n      | \"private\"\n      | \"meta\"\n      | \"recurrenceRule\"\n      | \"recurrenceDates\"\n      | \"recurrenceExdates\"\n      | \"recurrenceUntil\"\n      | \"recurrenceCount\"\n      | \"occurrence\"\n    >\n  > & {\n    /**\n     * Tags to change on the activity. 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 activities the twist has access to.\n     */\n    twistTags?: Partial<Record<Tag, boolean>>;\n  };\n\n/**\n * Represents a sync update from a tool.\n *\n * Tools that sync from external sources can send either:\n * - A new activity with notes (for newly discovered items)\n * - An update to an existing activity with optional new notes (for changed items)\n *\n * This allows tools to manage their own update detection logic locally,\n * providing Plot with the appropriate operation to perform.\n *\n * @example\n * ```typescript\n * // Send a new activity\n * const newItem: SyncUpdate = {\n *   type: ActivityType.Event,\n *   title: \"New Meeting\",\n *   id: Uuid.Generate(), // Tool-generated ID\n *   notes: [{ id: Uuid.Generate(), content: \"Description\" }]\n * };\n *\n * // Send an update to existing activity\n * const update: SyncUpdate = {\n *   activityId: existingActivityId,\n *   update: { title: \"Updated Meeting Title\" },\n *   notes: [{ id: Uuid.Generate(), content: \"New comment\" }]\n * };\n * ```\n */\nexport type SyncUpdate =\n  | NewActivityWithNotes\n  | {\n      /** ID of the activity to update */\n      activityId: string;\n      /** Optional updates to the activity itself */\n      update?: ActivityUpdate;\n      /** Optional new notes to add to the activity */\n      notes?: NewNote[];\n    };\n\n/**\n * Represents a note within an activity.\n *\n * Notes contain the detailed content (note text, links) associated with an activity.\n * They are always ordered by creation time within their parent activity.\n */\nexport type Note = ActivityCommon & {\n  /** The parent activity this note belongs to */\n  activity: Activity;\n  /** Primary content for the note (markdown) */\n  content: string | null;\n  /** Array of interactive links attached to the note */\n  links: Array<ActivityLink> | null;\n};\n\n/**\n * Type for creating new notes.\n *\n * Requires the activity reference, with all other fields optional.\n * The id field can be optionally provided by tools for tracking purposes.\n */\nexport type NewNote = Partial<\n  Omit<Note, \"author\" | \"activity\" | \"tags\" | \"mentions\">\n> & {\n  /** Reference to the parent activity (required) */\n  activity: Pick<Activity, \"id\">;\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 activity. 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 activity as unread for users.\n   * - true (default): Activity becomes unread for users who haven't authored the note\n   * - false: Activity is marked as read for all users in the priority at note creation time\n   *\n   * Use false for historical imports to avoid marking old items as unread.\n   */\n  unread?: boolean;\n};\n\n/**\n * Type for updating existing notes.\n */\nexport type NoteUpdate = Pick<Note, \"id\"> &\n  Partial<Pick<Note, \"draft\" | \"private\" | \"content\" | \"links\">> & {\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 activities 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  /** Email address (only included with ContactAccess.Read permission) */\n  email?: string;\n  /** Display name (undefined if not included due to permissions, null if not set) */\n  name?: string | null;\n};\n\n/**\n * An existing or new contact.\n */\nexport type NewActor =\n  | {\n      /** Unique identifier for the actor */\n      id: ActorId;\n    }\n  | NewContact;\n\n/**\n * Enumeration of author types that can create activities.\n *\n * The author type affects how activities are displayed and processed\n * within the Plot system.\n */\nexport enum ActorType {\n  /** Activities created by human users */\n  User,\n  /** Activities created by external contacts */\n  Contact,\n  /** Activities 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\nexport type ContentType = \"text\" | \"markdown\" | \"html\";\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,+hyBAA+hyB,CAAC"}
+{"version":3,"file":"plot.js","sourceRoot":"","sources":["../../src/llm-docs/plot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,utxBAAutxB,CAAC"}

package/dist/llm-docs/twist-guide-template.d.ts

@@ -4,6 +4,6 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Use `source` field for deduplication** - Enables safe, idempotent sync from external systems\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n  \u251C\u2500 Yes \u2192 Create new Activity with initial Note\n  \u2502         Include `source` field for deduplication\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Check for existing Activity\n      \u251C\u2500 Found \u2192 Add Note to existing Activity\n      \u2514\u2500 Not found \u2192 Create new Activity with initial Note\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  type Priority,\n  type ToolBuilder,\n  twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect your account\",\n    notes: [\n      {\n        content: \"Click the link below to connect your account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Setup\",\n  notes: [\n    {\n      content: \"Your twist is being set up. Configuration steps will appear here.\",\n    },\n  ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Task with links\",\n  notes: [\n    {\n      content: \"Click the links below to take action.\",\n      links: [urlLink, callbackLink],\n    },\n  ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect Google account\",\n    notes: [\n      {\n        content: \"Click below to connect your Google account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(\n  incomingActivity: NewActivityWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Check if this activity already exists (using source for deduplication)\n  if (incomingActivity.source) {\n    const existing = await this.tools.plot.getActivityBySource(\n      incomingActivity.source\n    );\n\n    if (existing) {\n      // Add update as a Note to existing Activity (add message to thread)\n      if (incomingActivity.notes?.[0]?.content) {\n        await this.tools.plot.createNote({\n          activity: { id: existing.id },\n          content: incomingActivity.notes[0].content,\n        });\n      }\n      return;\n    }\n  }\n\n  // Create new Activity with initial Note (new thread with first message)\n  await this.tools.plot.createActivity(incomingActivity);\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `\uD83D\uDCC5 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    notes: [\n      {\n        content: \"Select the calendars you want to sync:\",\n        links,\n      },\n    ],\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results (create activities with Notes)\n  for (const item of result.items) {\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: item.title,\n      source: `external:${item.id}`, // For deduplication\n      notes: [{ content: item.description }],\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Use `source` field for deduplication** - Always include `source` when syncing external data to enable safe, idempotent operations.\n- **Add Notes to existing Activities** - Check for existing Activities with `getActivityBySource()` before creating new ones. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+declare const _default: "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n  \u251C\u2500 Yes \u2192 Generate UUID with Uuid.Generate()\n  \u2502         Create new Activity with that UUID\n  \u2502         Store mapping: external_id \u2192 activity_uuid\n  \u2502\n  \u2514\u2500 No (update/reply/comment) \u2192 Look up mapping by external_id\n      \u251C\u2500 Found \u2192 Add Note to existing Activity using stored UUID\n      \u2514\u2500 Not found \u2192 Create new Activity with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  type Priority,\n  type ToolBuilder,\n  twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\nimport { Uuid } from \"@plotday/twister/utils/uuid\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect your account\",\n    notes: [\n      {\n        content: \"Click the link below to connect your account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Setup\",\n  notes: [\n    {\n      content: \"Your twist is being set up. Configuration steps will appear here.\",\n    },\n  ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Task with links\",\n  notes: [\n    {\n      content: \"Click the links below to take action.\",\n      links: [urlLink, callbackLink],\n    },\n  ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect Google account\",\n    notes: [\n      {\n        content: \"Click below to connect your Google account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(\n  incomingActivity: NewActivityWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingActivity.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingActivityId = await this.get<Uuid>(mappingKey);\n\n  if (existingActivityId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingActivity.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        activity: { id: existingActivityId },\n        content: incomingActivity.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const activityId = Uuid.Generate();\n  await this.set(mappingKey, activityId);\n\n  // Create new Activity with initial Note (new thread with first message)\n  await this.tools.plot.createActivity({\n    ...incomingActivity,\n    id: activityId,\n  });\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `\uD83D\uDCC5 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    notes: [\n      {\n        content: \"Select the calendars you want to sync:\",\n        links,\n      },\n    ],\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results (create activities with Notes)\n  for (const item of result.items) {\n    // Check if already synced\n    const mappingKey = `item_mapping:${resourceId}:${item.id}`;\n    const existingId = await this.get<Uuid>(mappingKey);\n\n    if (!existingId) {\n      // New item - generate UUID and store mapping\n      const activityId = Uuid.Generate();\n      await this.set(mappingKey, activityId);\n\n      await this.tools.plot.createActivity({\n        id: activityId,\n        type: ActivityType.Note,\n        title: item.title,\n        notes: [{ id: Uuid.Generate(), content: item.description }],\n      });\n    }\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Track external items with UUID mappings** - Generate UUIDs with `Uuid.Generate()` and store mappings (`external_id \u2192 uuid`) for deduplication. Never rely on the `source` field.\n- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
 export default _default;
 //# sourceMappingURL=twist-guide-template.d.ts.map

package/dist/llm-docs/twist-guide-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,gvfAAgqf;AAA/qf,wBAAgrf"}
+{"version":3,"file":"twist-guide-template.d.ts","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;wBAEY,0lhBAA2/gB;AAA1ghB,wBAA2ghB"}

package/dist/llm-docs/twist-guide-template.js

@@ -4,5 +4,5 @@
  * This file is auto-generated during build. Do not edit manually.
  * Generated from: cli/templates/AGENTS.template.md
  */
-export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Use `source` field for deduplication** - Enables safe, idempotent sync from external systems\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n  ├─ Yes → Create new Activity with initial Note\n  │         Include `source` field for deduplication\n  │\n  └─ No (update/reply/comment) → Check for existing Activity\n      ├─ Found → Add Note to existing Activity\n      └─ Not found → Create new Activity with initial Note\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  type Priority,\n  type ToolBuilder,\n  twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect your account\",\n    notes: [\n      {\n        content: \"Click the link below to connect your account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Setup\",\n  notes: [\n    {\n      content: \"Your twist is being set up. Configuration steps will appear here.\",\n    },\n  ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Task with links\",\n  notes: [\n    {\n      content: \"Click the links below to take action.\",\n      links: [urlLink, callbackLink],\n    },\n  ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect Google account\",\n    notes: [\n      {\n        content: \"Click below to connect your Google account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(\n  incomingActivity: NewActivityWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Check if this activity already exists (using source for deduplication)\n  if (incomingActivity.source) {\n    const existing = await this.tools.plot.getActivityBySource(\n      incomingActivity.source\n    );\n\n    if (existing) {\n      // Add update as a Note to existing Activity (add message to thread)\n      if (incomingActivity.notes?.[0]?.content) {\n        await this.tools.plot.createNote({\n          activity: { id: existing.id },\n          content: incomingActivity.notes[0].content,\n        });\n      }\n      return;\n    }\n  }\n\n  // Create new Activity with initial Note (new thread with first message)\n  await this.tools.plot.createActivity(incomingActivity);\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `📅 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    notes: [\n      {\n        content: \"Select the calendars you want to sync:\",\n        links,\n      },\n    ],\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results (create activities with Notes)\n  for (const item of result.items) {\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: item.title,\n      source: `external:${item.id}`, // For deduplication\n      notes: [{ content: item.description }],\n    });\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Use `source` field for deduplication** - Always include `source` when syncing external data to enable safe, idempotent operations.\n- **Add Notes to existing Activities** - Check for existing Activities with `getActivityBySource()` before creating new ones. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
+export default "# Twist Implementation Guide for LLMs\n\nThis document provides context for AI assistants generating or modifying twists.\n\n## Architecture Overview\n\nPlot Twists are TypeScript classes that extend the `Twist` base class. Twists interact with external services and Plot's core functionality through a tool-based architecture.\n\n### Runtime Environment\n\n**Critical**: All Twists and tool functions are executed in a sandboxed, ephemeral environment with limited resources:\n\n- **Memory is temporary**: Anything stored in memory (e.g. as a variable in the twist/tool object) is lost after the function completes. Use the Store tool instead. Only use memory for temporary caching.\n- **Limited CPU time**: Each execution has limited CPU time (typically 10 seconds) and memory (128MB)\n- **Use the Run tool**: Queue separate chunks of work with `run.now(functionName, context)`\n- **Break long operations**: Split large operations into smaller batches that can be processed independently\n- **Store intermediate state**: Use the Store tool to persist state between batches\n- **Examples**: Syncing large datasets, processing many API calls, or performing batch operations\n\n## Understanding Activities and Notes\n\n**CRITICAL CONCEPT**: An **Activity** represents something done or to be done (a task, event, or conversation), while **Notes** represent the updates and details on that activity.\n\n**Think of an Activity as a thread** on a messaging platform, and **Notes as the messages in that thread**.\n\n### Key Guidelines\n\n1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes\n2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message\n3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication\n4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`\n\n### Decision Tree\n\n```\nNew event/task/conversation?\n  ├─ Yes → Generate UUID with Uuid.Generate()\n  │         Create new Activity with that UUID\n  │         Store mapping: external_id → activity_uuid\n  │\n  └─ No (update/reply/comment) → Look up mapping by external_id\n      ├─ Found → Add Note to existing Activity using stored UUID\n      └─ Not found → Create new Activity with UUID + store mapping\n```\n\n## Twist Structure Pattern\n\n```typescript\nimport {\n  type Activity,\n  type Priority,\n  type ToolBuilder,\n  twist,\n} from \"@plotday/twister\";\nimport { Plot } from \"@plotday/twister/tools/plot\";\nimport { Uuid } from \"@plotday/twister/utils/uuid\";\n\nexport default class MyTwist extends Twist<MyTwist> {\n  build(build: ToolBuilder) {\n    return {\n      plot: build(Plot),\n    };\n  }\n\n  async activate(priority: Pick<Priority, \"id\">) {\n    // Called when twist is enabled for a priority\n    // Common actions: request auth, create setup activities\n  }\n\n  async activity(activity: Activity) {\n    // Called when an activity is routed to this twist\n    // Common actions: process external events, update activities\n  }\n}\n```\n\n## Tool System\n\n### Accessing Tools\n\nAll tools are declared in the `build` method:\n\n```typescript\nbuild(build: ToolBuilder) {\n  return {\n    toolName: build(ToolClass),\n  };\n}\n```\n\nAll `build()` calls must occur in the `build` method as they are used for dependency analysis.\n\nIMPORTANT: HTTP access is restricted to URLs requested via `build(Network, { urls: [url1, url2, ...] })` in the `build` method. Wildcards are supported. Use `build(Network, { urls: ['*'] })` if full access is needed.\n\n### Built-in Tools (Always Available)\n\nFor complete API documentation of built-in tools including all methods, types, and detailed examples, see the TypeScript definitions in your installed package at `node_modules/@plotday/twister/src/tools/*.ts`. Each tool file contains comprehensive JSDoc documentation.\n\n**Quick reference - Available tools:**\n\n- `@plotday/twister/tools/plot` - Core data layer (create/update activities, priorities, contacts)\n- `@plotday/twister/tools/ai` - LLM integration (text generation, structured output, reasoning)\n  - Use ModelPreferences to specify `speed` (fast/balanced/capable) and `cost` (low/medium/high)\n- `@plotday/twister/tools/store` - Persistent key-value storage (also via `this.set()`, `this.get()`)\n- `@plotday/twister/tools/tasks` - Queue batched work (also via `this.run()`)\n- `@plotday/twister/tools/callbacks` - Persistent function references (also via `this.callback()`)\n- `@plotday/twister/tools/integrations` - OAuth2 authentication flows\n- `@plotday/twister/tools/network` - HTTP access permissions and webhook management\n- `@plotday/twister/tools/twists` - Manage other Twists\n\n**Critical**: Never use instance variables for state. They are lost after function execution. Always use Store methods.\n\n### External Tools (Add to package.json)\n\nAdd tool dependencies to `package.json`:\n\n```json\n{\n  \"dependencies\": {\n    \"@plotday/twister\": \"workspace:^\",\n    \"@plotday/tool-google-calendar\": \"workspace:^\"\n  }\n}\n```\n\n#### Common External Tools\n\n- `@plotday/tool-google-calendar`: Google Calendar integration\n- `@plotday/tool-outlook-calendar`: Outlook Calendar integration\n- `@plotday/tool-google-contacts`: Google Contacts integration\n\n## Lifecycle Methods\n\n### activate(priority: Pick<Priority, \"id\">)\n\nCalled when the twist is enabled for a priority. Common patterns:\n\n**Request Authentication:**\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  const authLink = await this.tools.externalTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect your account\",\n    notes: [\n      {\n        content: \"Click the link below to connect your account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n}\n```\n\n**Store Parent Activity for Later:**\n\n```typescript\nconst activity = await this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Setup\",\n  notes: [\n    {\n      content: \"Your twist is being set up. Configuration steps will appear here.\",\n    },\n  ],\n});\n\nawait this.set(\"setup_activity_id\", activity.id);\n```\n\n### activity(activity: Activity)\n\nCalled when an activity is routed to the twist. Common patterns:\n\n**Create Activities from External Events:**\n\n```typescript\nasync activity(activity: Activity) {\n  await this.tools.plot.createActivity(activity);\n}\n```\n\n**Update Based on User Action:**\n\n```typescript\nasync activity(activity: Activity) {\n  if (activity.completed) {\n    await this.handleCompletion(activity);\n  }\n}\n```\n\n## Activity Links\n\nActivity links enable user interaction:\n\n```typescript\nimport { type ActivityLink, ActivityLinkType } from \"@plotday/twister\";\n\n// URL link\nconst urlLink: ActivityLink = {\n  title: \"Open website\",\n  type: ActivityLinkType.url,\n  url: \"https://example.com\",\n};\n\n// Callback link (uses Callbacks tool)\nconst token = await this.callback(this.onLinkClicked, \"context\");\nconst callbackLink: ActivityLink = {\n  title: \"Click me\",\n  type: ActivityLinkType.callback,\n  token: token,\n};\n\n// Add to activity note\nawait this.tools.plot.createActivity({\n  type: ActivityType.Note,\n  title: \"Task with links\",\n  notes: [\n    {\n      content: \"Click the links below to take action.\",\n      links: [urlLink, callbackLink],\n    },\n  ],\n});\n```\n\n## Authentication Pattern\n\nCommon pattern for OAuth authentication:\n\n```typescript\nasync activate(_priority: Pick<Priority, \"id\">) {\n  // Request auth link from tool with callback\n  const authLink = await this.tools.googleTool.requestAuth(\n    this.onAuthComplete,\n    \"google\"\n  );\n\n  // Create activity with auth link\n  const activity = await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Connect Google account\",\n    notes: [\n      {\n        content: \"Click below to connect your Google account and start syncing.\",\n        links: [authLink],\n      },\n    ],\n  });\n\n  // Store for later use\n  await this.set(\"auth_activity_id\", activity.id);\n}\n\nasync onAuthComplete(authResult: { authToken: string }, provider: string) {\n  // Store auth token\n  await this.set(`${provider}_auth`, authResult.authToken);\n\n  // Continue setup flow\n  await this.setupSyncOptions(authResult.authToken);\n}\n```\n\n## Sync Pattern\n\nPattern for syncing external data - demonstrates adding Notes to existing Activities:\n\n```typescript\nasync startSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n\n  await this.tools.calendarTool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    calendarId\n  );\n}\n\nasync handleEvent(\n  incomingActivity: NewActivityWithNotes,\n  calendarId: string\n): Promise<void> {\n  // Extract external event ID from meta (adapt based on your tool's data)\n  const externalId = incomingActivity.meta?.eventId;\n\n  if (!externalId) {\n    console.error(\"Event missing external ID\");\n    return;\n  }\n\n  // Check if we've already synced this event\n  const mappingKey = `event_mapping:${calendarId}:${externalId}`;\n  const existingActivityId = await this.get<Uuid>(mappingKey);\n\n  if (existingActivityId) {\n    // Event already exists - add update as a Note (add message to thread)\n    if (incomingActivity.notes?.[0]?.content) {\n      await this.tools.plot.createNote({\n        activity: { id: existingActivityId },\n        content: incomingActivity.notes[0].content,\n      });\n    }\n    return;\n  }\n\n  // New event - generate UUID and store mapping\n  const activityId = Uuid.Generate();\n  await this.set(mappingKey, activityId);\n\n  // Create new Activity with initial Note (new thread with first message)\n  await this.tools.plot.createActivity({\n    ...incomingActivity,\n    id: activityId,\n  });\n}\n\nasync stopSync(calendarId: string): Promise<void> {\n  const authToken = await this.get<string>(\"auth_token\");\n  await this.tools.calendarTool.stopSync(authToken, calendarId);\n}\n```\n\n## Calendar Selection Pattern\n\nPattern for letting users select from multiple calendars/accounts:\n\n```typescript\nprivate async createCalendarSelectionActivity(\n  provider: string,\n  calendars: Calendar[],\n  authToken: string\n): Promise<void> {\n  const links: ActivityLink[] = [];\n\n  for (const calendar of calendars) {\n    const token = await this.callback(\n      this.onCalendarSelected,\n      provider,\n      calendar.id,\n      calendar.name,\n      authToken\n    );\n\n    links.push({\n      title: `📅 ${calendar.name}${calendar.primary ? \" (Primary)\" : \"\"}`,\n      type: ActivityLinkType.callback,\n      token: token,\n    });\n  }\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Which calendars would you like to connect?\",\n    notes: [\n      {\n        content: \"Select the calendars you want to sync:\",\n        links,\n      },\n    ],\n  });\n}\n\nasync onCalendarSelected(\n  link: ActivityLink,\n  provider: string,\n  calendarId: string,\n  calendarName: string,\n  authToken: string\n): Promise<void> {\n  // Start sync for selected calendar\n  await this.tools.tool.startSync(\n    authToken,\n    calendarId,\n    this.handleEvent,\n    provider,\n    calendarId\n  );\n}\n```\n\n## Batch Processing Pattern\n\n**Important**: Because Twists run in an ephemeral environment with limited execution time, you must break long operations into batches. Each batch runs independently in a new execution context.\n\n### Key Principles\n\n1. **Store state between batches**: Use the Store tool to persist progress\n2. **Queue next batch**: Use the Run tool to schedule the next chunk\n3. **Clean up when done**: Delete stored state after completion\n4. **Handle failures**: Store enough state to resume if a batch fails\n\n### Example Implementation\n\n```typescript\nasync startSync(resourceId: string): Promise<void> {\n  // Initialize state in Store (persists between executions)\n  await this.set(`sync_state_${resourceId}`, {\n    nextPageToken: null,\n    batchNumber: 1,\n    itemsProcessed: 0,\n  });\n\n  // Queue first batch using runTask method\n  const callback = await this.callback(this.syncBatch, resourceId);\n  await this.runTask(callback);\n}\n\nasync syncBatch(args: any, resourceId: string): Promise<void> {\n  // Load state from Store (set by previous execution)\n  const state = await this.get(`sync_state_${resourceId}`);\n\n  // Process one batch (keep under time limit)\n  const result = await this.fetchBatch(state.nextPageToken);\n\n  // Process results (create activities with Notes)\n  for (const item of result.items) {\n    // Check if already synced\n    const mappingKey = `item_mapping:${resourceId}:${item.id}`;\n    const existingId = await this.get<Uuid>(mappingKey);\n\n    if (!existingId) {\n      // New item - generate UUID and store mapping\n      const activityId = Uuid.Generate();\n      await this.set(mappingKey, activityId);\n\n      await this.tools.plot.createActivity({\n        id: activityId,\n        type: ActivityType.Note,\n        title: item.title,\n        notes: [{ id: Uuid.Generate(), content: item.description }],\n      });\n    }\n  }\n\n  if (result.nextPageToken) {\n    // Update state in Store for next batch\n    await this.set(`sync_state_${resourceId}`, {\n      nextPageToken: result.nextPageToken,\n      batchNumber: state.batchNumber + 1,\n      itemsProcessed: state.itemsProcessed + result.items.length,\n    });\n\n    // Queue next batch (runs in new execution context)\n    const nextCallback = await this.callback(this.syncBatch, resourceId);\n    await this.runTask(nextCallback);\n  } else {\n    // Cleanup when complete\n    await this.clear(`sync_state_${resourceId}`);\n\n    // Optionally notify user of completion\n    await this.tools.plot.createActivity({\n      type: ActivityType.Note,\n      title: \"Sync complete\",\n      notes: [\n        {\n          content: `Successfully processed ${state.itemsProcessed + result.items.length} items.`,\n        },\n      ],\n    });\n  }\n}\n```\n\n## Error Handling\n\nAlways handle errors gracefully and communicate them to users:\n\n```typescript\ntry {\n  await this.externalOperation();\n} catch (error) {\n  console.error(\"Operation failed:\", error);\n\n  await this.tools.plot.createActivity({\n    type: ActivityType.Note,\n    title: \"Operation failed\",\n    notes: [\n      {\n        content: `Failed to complete operation: ${error.message}`,\n      },\n    ],\n  });\n}\n```\n\n## Common Pitfalls\n\n- **Don't use instance variables for state** - Anything stored in memory is lost after function execution. Always use the Store tool for data that needs to persist.\n- **Processing self-created activities** - Other users may change an Activity created by the twist, resulting in an \\`activity\\` call. Be sure to check the \\`changes === null\\` and/or \\`activity.author.id !== this.id\\` to avoid re-processing.\n- **Always create Activities with Notes** - See \"Understanding Activities and Notes\" section above for the thread/message pattern and decision tree.\n- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.\n- **Track external items with UUID mappings** - Generate UUIDs with `Uuid.Generate()` and store mappings (`external_id → uuid`) for deduplication. Never rely on the `source` field.\n- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.\n- Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.\n- **Don't forget runtime limits** - Each execution has ~10 seconds. Break long operations into batches with the Tasks tool. Process enough items per batch to be efficient, but few enough to stay under time limits.\n- **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.\n- **Store auth tokens** - Don't re-request authentication unnecessarily.\n- **Clean up callbacks and stored state** - Delete callbacks and Store entries when no longer needed.\n- **Handle missing auth gracefully** - Check for stored auth before operations.\n\n## Testing\n\nBefore deploying, verify:\n\n1. Linting passes: `{{packageManager}} lint`\n2. All dependencies are in package.json\n3. Authentication flow works end-to-end\n4. Batch operations handle pagination correctly\n5. Error cases are handled gracefully\n";
 //# sourceMappingURL=twist-guide-template.js.map

package/dist/llm-docs/twist-guide-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,gqfAAgqf,CAAC"}
+{"version":3,"file":"twist-guide-template.js","sourceRoot":"","sources":["../../src/llm-docs/twist-guide-template.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAe,2/gBAA2/gB,CAAC"}