Class PlotAbstract

constructor

• new Plot(): Plot

  Returns Plot

AbstractcreateActivity

• createActivity(activity: NewActivity | NewActivityWithNotes): Promise<Activity>

  Creates a new activity in the Plot system.

  The activity will be automatically assigned an ID and author information based on the current execution context. All other fields from NewActivity will be preserved in the created activity.

  Parameters

  • activity: NewActivity | NewActivityWithNotes

    The activity data to create

  Returns Promise<Activity>

  Promise resolving to the complete created activity

AbstractcreateActivities

• createActivities(
      activities: (NewActivity | NewActivityWithNotes)[],
  ): Promise<Activity[]>

  Creates multiple activities in a single batch operation.

  This method efficiently creates multiple activities at once, which is more performant than calling createActivity() multiple times individually. All activities are created with the same author and access control rules.

  Parameters

  • activities: (NewActivity | NewActivityWithNotes)[]

    Array of activity data to create

  Returns Promise<Activity[]>

  Promise resolving to array of created activities

AbstractupdateActivity

• updateActivity(activity: ActivityUpdate): Promise<void>

  Updates an existing activity in the Plot system.

  Only the fields provided in the update object will be modified - all other fields remain unchanged. This enables partial updates without needing to fetch and resend the entire activity object.

  For tags, provide a Record<number, boolean> where true adds a tag and false removes it. Tags not included in the update remain unchanged.

  When updating the parent, the activity's path will be automatically recalculated to maintain the correct hierarchical structure.

  When updating scheduling fields (start, end, recurrence*), the database will automatically recalculate duration and range values to maintain consistency.

  Parameters

  • activity: ActivityUpdate

    The activity update containing the ID and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

  Example

  // Mark a task as complete
  await this.plot.updateActivity({
    id: "task-123",
    done: new Date()
  });
  
  // Reschedule an event
  await this.plot.updateActivity({
    id: "event-456",
    start: new Date("2024-03-15T10:00:00Z"),
    end: new Date("2024-03-15T11:00:00Z")
  });
  
  // Add and remove tags
  await this.plot.updateActivity({
    id: "activity-789",
    tags: {
      1: true,  // Add tag with ID 1
      2: false  // Remove tag with ID 2
    }
  });
  
  // Update a recurring event exception
  await this.plot.updateActivity({
    id: "exception-123",
    occurrence: new Date("2024-03-20T09:00:00Z"),
    title: "Rescheduled meeting"
  });
  Copy

AbstractgetNotes

• getNotes(activity: Activity): Promise<Note[]>

  Retrieves all notes within an activity.

  Notes are detailed entries within an activity, ordered by creation time. Each note can contain markdown content, links, and other detailed information related to the parent activity.

  Parameters

  • activity: Activity

    The activity whose notes to retrieve

  Returns Promise<Note[]>

  Promise resolving to array of notes in the activity

AbstractcreateNote

• createNote(note: NewNote): Promise<Note>

  Creates a new note in an activity.

  Notes provide detailed content within an activity, supporting markdown, links, and other rich content. The note will be automatically assigned an ID and author information based on the current execution context.

  Parameters

  • note: NewNote

    The note data to create

  Returns Promise<Note>

  Promise resolving to the complete created note

  Example

  // Create a note with content
  await this.plot.createNote({
    activity: { id: "activity-123" },
    note: "Discussion notes from the meeting...",
    contentType: "markdown"
  });
  
  // Create a note with links
  await this.plot.createNote({
    activity: { id: "activity-456" },
    note: "Meeting recording available",
    links: [{
      type: ActivityLinkType.external,
      title: "View Recording",
      url: "https://example.com/recording"
    }]
  });
  Copy

AbstractcreateNotes

• createNotes(notes: NewNote[]): Promise<Note[]>

  Creates multiple notes in a single batch operation.

  This method efficiently creates multiple notes at once, which is more performant than calling createNote() multiple times individually. All notes are created with the same author and access control rules.

  Parameters

  • notes: NewNote[]

    Array of note data to create

  Returns Promise<Note[]>

  Promise resolving to array of created notes

  Example

  // Create multiple notes in one batch
  await this.plot.createNotes([
    {
      activity: { id: "activity-123" },
      note: "First message in thread"
    },
    {
      activity: { id: "activity-123" },
      note: "Second message in thread"
    }
  ]);
  Copy

AbstractupdateNote

• updateNote(note: NoteUpdate): Promise<void>

  Updates an existing note in the Plot system.

  Only the fields provided in the update object will be modified - all other fields remain unchanged. This enables partial updates without needing to fetch and resend the entire note object.

  Parameters

  • note: NoteUpdate

    The note update containing the ID and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

  Example

  // Update note content
  await this.plot.updateNote({
    id: "note-123",
    note: "Updated content with more details"
  });
  
  // Add tags to a note
  await this.plot.updateNote({
    id: "note-456",
    twistTags: {
      [Tag.Important]: true
    }
  });
  Copy

AbstractgetActivity

• getActivity(
      activity: { id: Uuid } | { source: string },
  ): Promise<Activity | null>

  Retrieves an activity by ID or source.

  This method enables lookup of activities either by their unique ID or by their source identifier (canonical URL from an external system). Archived activities are included in the results.

  Parameters

  • activity: { id: Uuid } | { source: string }

    Activity lookup by ID or source

  Returns Promise<Activity | null>

  Promise resolving to the matching activity or null if not found

AbstractgetNote

• getNote(note: { id: Uuid } | { key: string }): Promise<Note | null>

  Retrieves a note by ID or key.

  This method enables lookup of notes either by their unique ID or by their key (unique identifier within the activity). Archived notes are included in the results.

  Parameters

  • note: { id: Uuid } | { key: string }

    Note lookup by ID or key

  Returns Promise<Note | null>

  Promise resolving to the matching note or null if not found

AbstractcreatePriority

• createPriority(priority: NewPriority): Promise<Priority>

  Creates a new priority in the Plot system.

  Priorities serve as organizational containers for activities and twists. The created priority will be automatically assigned a unique ID.

  Parameters

  • priority: NewPriority

    The priority data to create

  Returns Promise<Priority>

  Promise resolving to the complete created priority

AbstractgetPriority

• getPriority(priority: { id: Uuid } | { key: string }): Promise<Priority | null>

  Retrieves a priority by ID or key.

  Archived priorities are included in the results.

  Parameters

  • priority: { id: Uuid } | { key: string }

    Priority lookup by ID or key

  Returns Promise<Priority | null>

  Promise resolving to the matching priority or null if not found

AbstractupdatePriority

• updatePriority(update: PriorityUpdate): Promise<void>

  Updates an existing priority in the Plot system.

  The priority is identified by either its ID or key. Only the fields specified in the update will be changed.

  Parameters

  • update: PriorityUpdate

    Priority update containing ID/key and fields to change

  Returns Promise<void>

  Promise that resolves when the update is complete

AbstractaddContacts

• addContacts(contacts: NewContact[]): Promise<Actor[]>

  Adds contacts to the Plot system.

  Contacts are used for associating people with activities, such as event attendees or task assignees. Duplicate contacts (by email) will be merged or updated as appropriate. This method requires ContactAccess.Write permission.

  Parameters

  • contacts: NewContact[]

    Array of contact information to add

  Returns Promise<Actor[]>

  Promise resolving to array of created/updated actors

AbstractgetActors

• getActors(ids: ActorId[]): Promise<Actor[]>

  Retrieves actors by their IDs.

  Actors represent users, contacts, or twists in the Plot system. This method requires ContactAccess.Read permission.

  Parameters

  • ids: ActorId[]

    Array of actor IDs to retrieve

  Returns Promise<Actor[]>

  Promise resolving to array of actors

Static ReadonlyOptions

// Minimal configuration with required permissions
build(build: ToolBuilder) {
  return {
    plot: build(Plot, {
      activity: {
        access: ActivityAccess.Create
      }
    })
  };
}

// Full configuration with callbacks
build(build: ToolBuilder) {
  return {
    plot: build(Plot, {
      activity: {
        access: ActivityAccess.Create,
        updated: this.onActivityUpdated
      },
      note: {
        intents: [{
          description: "Schedule meetings",
          examples: ["Schedule a meeting tomorrow"],
          handler: this.onSchedulingIntent
        }],
        created: this.onNoteCreated
      },
      priority: {
        access: PriorityAccess.Full
      },
      contact: {
        access: ContactAccess.Write
      }
    })
  };
}
Copy