Return only id on create for performance

Author: KrisBraun

.changeset/tangy-foxes-stand.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Return only the id when creating/upserting to increase performance

.changeset/tasty-kids-count.md

@@ -0,0 +1,7 @@
+---
+"@plotday/tool-linear": patch
+"@plotday/tool-gmail": patch
+"@plotday/tool-slack": patch
+---
+
+Changed: Use new return values from create functions

tools/gmail/src/gmail.ts

@@ -1,7 +1,7 @@
 import {
   type ActivityLink,
+  type NewActivityWithNotes,
   Serializable,
-  type SyncUpdate,
   Tool,
   type ToolBuilder,
 } from "@plotday/twister";
@@ -200,7 +200,7 @@ export class Gmail extends Tool<Gmail> implements MessagingTool {
 
   async startSync<
     TArgs extends Serializable[],
-    TCallback extends (syncUpdate: SyncUpdate, ...args: TArgs) => any
+    TCallback extends (thread: NewActivityWithNotes, ...args: TArgs) => any
   >(
     options: {
       authToken: string;

tools/linear/src/linear.ts

@@ -8,7 +8,6 @@ import {
   type NewActivityWithNotes,
   type NewNote,
   Serializable,
-  type SyncUpdate,
 } from "@plotday/twister";
 import type {
   Project,
@@ -277,15 +276,15 @@ export class Linear extends Tool<Linear> implements ProjectTool {
 
     // Process each issue
     for (const issue of issuesConnection.nodes) {
-      const syncUpdate = await this.convertIssueToSyncUpdate(
+      const activity = await this.convertIssueToActivity(
         issue,
         projectId,
         state.initialSync
       );
 
-      if (syncUpdate) {
+      if (activity) {
         // Execute the callback using the callback token
-        await this.tools.callbacks.run(callbackToken, syncUpdate);
+        await this.tools.callbacks.run(callbackToken, activity);
       }
     }
 
@@ -313,13 +312,13 @@ export class Linear extends Tool<Linear> implements ProjectTool {
   }
 
   /**
-   * Convert a Linear issue to a SyncUpdate
+   * Convert a Linear issue to a NewActivityWithNotes
    */
-  private async convertIssueToSyncUpdate(
+  private async convertIssueToActivity(
     issue: Issue,
     projectId: string,
     initialSync: boolean
-  ): Promise<SyncUpdate | null> {
+  ): Promise<NewActivityWithNotes | null> {
     const creator = await issue.creator;
     const assignee = await issue.assignee;
     const comments = await issue.comments();
@@ -579,16 +578,16 @@ export class Linear extends Tool<Linear> implements ProjectTool {
       const client = await this.getClient(authToken);
       const issue = await client.issue(payload.data.id);
 
-      const syncUpdate = await this.convertIssueToSyncUpdate(
+      const activity = await this.convertIssueToActivity(
         issue,
         projectId,
         false // incremental update, not initial sync
       );
 
-      if (!syncUpdate) return;
+      if (!activity) return;
 
-      // Execute stored callback (unread flag already set by convertIssueToSyncUpdate)
-      await this.tools.callbacks.run(callbackToken, syncUpdate);
+      // Execute stored callback (unread flag already set by convertIssueToActivity)
+      await this.tools.callbacks.run(callbackToken, activity);
     }
   }
 

tools/slack/src/slack.ts

@@ -1,7 +1,7 @@
 import {
   type ActivityLink,
+  type NewActivityWithNotes,
   Serializable,
-  type SyncUpdate,
   Tool,
   type ToolBuilder,
 } from "@plotday/twister";
@@ -202,7 +202,7 @@ export class Slack extends Tool<Slack> implements MessagingTool {
 
   async startSync<
     TArgs extends Serializable[],
-    TCallback extends (syncUpdate: SyncUpdate, ...args: TArgs) => any
+    TCallback extends (thread: NewActivityWithNotes, ...args: TArgs) => any
   >(
     options: {
       authToken: string;

twister/src/common/calendar.ts

@@ -1,4 +1,4 @@
-import type { ActivityLink, Serializable, SyncUpdate } from "../index";
+import type { ActivityLink, NewActivityWithNotes, Serializable } from "../index";
 
 /**
  * Represents successful calendar authorization.
@@ -115,18 +115,12 @@ export type SyncOptions = {
  *   }
  *
  *   async onCalendarEvent(
- *     syncUpdate: SyncUpdate,
+ *     activity: NewActivityWithNotes,
  *     syncMeta: { initialSync: boolean }
  *   ) {
  *     // Step 4: Twist decides what to do with the data
  *     // Tool built the NewActivity, twist saves it
- *     if ("activityId" in syncUpdate) {
- *       // Update existing activity
- *       await this.plot.updateActivity(syncUpdate.activityId, syncUpdate.update);
- *     } else {
- *       // Create/upsert new activity using source/key pattern
- *       await this.plot.createActivity(syncUpdate);
- *     }
+ *     await this.plot.createActivity(activity);
  *   }
  * }
  * ```
@@ -183,14 +177,14 @@ export type CalendarTool = {
    * @param options.calendarId - ID of the calendar to sync
    * @param options.timeMin - Earliest date to sync events from (inclusive)
    * @param options.timeMax - Latest date to sync events to (exclusive)
-   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced event
+   * @param callback - Function receiving (activity, ...extraArgs) for each synced event
    * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    * @throws When auth token is invalid or calendar doesn't exist
    */
   startSync<
     TArgs extends Serializable[],
-    TCallback extends (syncUpdate: SyncUpdate, ...args: TArgs) => any
+    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any
   >(
     options: {
       authToken: string;

twister/src/common/messaging.ts

@@ -1,4 +1,4 @@
-import type { ActivityLink, Serializable, SyncUpdate } from "../index";
+import type { ActivityLink, NewActivityWithNotes, Serializable } from "../index";
 
 /**
  * Represents a successful messaging service authorization.
@@ -77,8 +77,7 @@ export type MessagingTool = {
   /**
    * Begins synchronizing messages from a specific channel.
    *
-   * Email threads and chat conversations are converted to SyncUpdate objects,
-   * which can be either new items or updates to existing items.
+   * Email threads and chat conversations are converted to NewActivityWithNotes objects.
    *
    * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):
    * - Set Activity.source to the thread/conversation URL or stable ID (e.g., "slack:{channelId}:{threadTs}")
@@ -96,13 +95,13 @@ export type MessagingTool = {
    * @param options.authToken - Authorization token for access
    * @param options.channelId - ID of the channel (e.g., channel, inbox) to sync
    * @param options.timeMin - Earliest date to sync events from (inclusive)
-   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced conversation
+   * @param callback - Function receiving (thread, ...extraArgs) for each synced conversation
    * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    */
   startSync<
     TArgs extends Serializable[],
-    TCallback extends (syncUpdate: SyncUpdate, ...args: TArgs) => any
+    TCallback extends (thread: NewActivityWithNotes, ...args: TArgs) => any
   >(
     options: {
       authToken: string;

twister/src/common/projects.ts

@@ -2,8 +2,8 @@ import type {
   Activity,
   ActivityLink,
   ActivityMeta,
+  NewActivityWithNotes,
   Serializable,
-  SyncUpdate,
 } from "../index";
 
 /**
@@ -83,8 +83,7 @@ export type ProjectTool = {
   /**
    * Begins synchronizing issues from a specific project.
    *
-   * Issues and tasks are converted to SyncUpdate objects, which can be either
-   * new items or updates to existing items.
+   * Issues and tasks are converted to NewActivityWithNotes objects.
    *
    * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):
    * - Set Activity.source to the issue's canonical URL (e.g., Linear issue URL, Jira issue URL)
@@ -104,13 +103,13 @@ export type ProjectTool = {
    * @param options.authToken - Authorization token for access
    * @param options.projectId - ID of the project to sync
    * @param options.timeMin - Earliest date to sync issues from (inclusive)
-   * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced issue
+   * @param callback - Function receiving (activity, ...extraArgs) for each synced issue
    * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
    * @returns Promise that resolves when sync setup is complete
    */
   startSync<
     TArgs extends Serializable[],
-    TCallback extends (syncUpdate: SyncUpdate, ...args: TArgs) => any
+    TCallback extends (activity: NewActivityWithNotes, ...args: TArgs) => any
   >(
     options: {
       authToken: string;

twister/src/plot.ts

@@ -506,7 +506,6 @@ export type ActivityOccurrence = {
   end: Date | string | null;
   done: Date | null;
   title: string;
-  preview: string | null;
   /**
    * Meta is merged, with the occurrence's meta taking precedence.
    */
@@ -868,45 +867,6 @@ export type ActivityUpdate = (
     occurrences?: (NewActivityOccurrence | ActivityOccurrenceUpdate)[];
   };
 
-/**
- * Represents a sync update from a tool.
- *
- * Tools that sync from external sources can send either:
- * - A new activity with notes (for newly discovered items)
- * - An update to an existing activity with optional new notes (for changed items)
- *
- * This allows tools to manage their own update detection logic locally,
- * providing Plot with the appropriate operation to perform.
- *
- * @example
- * ```typescript
- * // Send a new activity
- * const newItem: SyncUpdate = {
- *   type: ActivityType.Event,
- *   title: "New Meeting",
- *   id: Uuid.Generate(), // Tool-generated ID
- *   notes: [{ id: Uuid.Generate(), content: "Description" }]
- * };
- *
- * // Send an update to existing activity
- * const update: SyncUpdate = {
- *   activityId: existingActivityId,
- *   update: { title: "Updated Meeting Title" },
- *   notes: [{ id: Uuid.Generate(), content: "New comment" }]
- * };
- * ```
- */
-export type SyncUpdate =
-  | NewActivityWithNotes
-  | {
-      /** ID of the activity to update */
-      activityId: string;
-      /** Optional updates to the activity itself */
-      update?: ActivityUpdate;
-      /** Optional new notes to add to the activity */
-      notes?: NewNote[];
-    };
-
 /**
  * Represents a note within an activity.
  *

twister/src/tools/plot.ts

@@ -219,12 +219,12 @@ export abstract class Plot extends ITool {
    * will be preserved in the created activity.
    *
    * @param activity - The activity data to create
-   * @returns Promise resolving to the complete created activity
+   * @returns Promise resolving to the created activity's ID
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract createActivity(
     activity: NewActivity | NewActivityWithNotes
-  ): Promise<Activity>;
+  ): Promise<Uuid>;
 
   /**
    * Creates multiple activities in a single batch operation.
@@ -234,12 +234,12 @@ export abstract class Plot extends ITool {
    * All activities are created with the same author and access control rules.
    *
    * @param activities - Array of activity data to create
-   * @returns Promise resolving to array of created activities
+   * @returns Promise resolving to array of created activity IDs
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   abstract createActivities(
     activities: (NewActivity | NewActivityWithNotes)[]
-  ): Promise<Activity[]>;
+  ): Promise<Uuid[]>;
 
   /**
    * Updates an existing activity in the Plot system.
@@ -321,7 +321,7 @@ export abstract class Plot extends ITool {
    * an ID and author information based on the current execution context.
    *
    * @param note - The note data to create
-   * @returns Promise resolving to the complete created note
+   * @returns Promise resolving to the created note's ID
    *
    * @example
    * ```typescript
@@ -345,7 +345,7 @@ export abstract class Plot extends ITool {
    * ```
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract createNote(note: NewNote): Promise<Note>;
+  abstract createNote(note: NewNote): Promise<Uuid>;
 
   /**
    * Creates multiple notes in a single batch operation.
@@ -355,7 +355,7 @@ export abstract class Plot extends ITool {
    * All notes are created with the same author and access control rules.
    *
    * @param notes - Array of note data to create
-   * @returns Promise resolving to array of created notes
+   * @returns Promise resolving to array of created note IDs
    *
    * @example
    * ```typescript
@@ -373,7 +373,7 @@ export abstract class Plot extends ITool {
    * ```
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  abstract createNotes(notes: NewNote[]): Promise<Note[]>;
+  abstract createNotes(notes: NewNote[]): Promise<Uuid[]>;
 
   /**
    * Updates an existing note in the Plot system.