@plotday/twister 0.27.0 → 0.28.0

package/README.md

@@ -136,17 +136,21 @@ Twist tools provide capabilities to twists. They are usually unopinionated and d
 
 Think of an **Activity as a thread** and **Notes as messages in that thread**. Always create activities with an initial note, and add notes for updates rather than creating new activities.
 
+**Data sync:** When syncing from external systems, use `Activity.source` (canonical URL) and `Note.key` for automatic upserts without manual ID tracking. See the [Sync Strategies guide](https://twist.plot.day/documents/Sync_Strategies.html) for detailed patterns.
+
 **Action scheduling:** When creating Actions (tasks), omitting the `start` field defaults to "Do Now" (current time). For most integrations, explicitly set `start: null` to create backlog items ("Do Someday"), only using "Do Now" for urgent or in-progress tasks.
 
 ```typescript
-// Create an activity with an initial note (thread with first message)
+// Create an activity with source for automatic deduplication
 await this.tools.plot.createActivity({
+  source: "https://github.com/org/repo/pull/123", // Enables automatic upserts
   type: ActivityType.Action,
   title: "Review pull request",
   start: null, // "Do Someday" - backlog item (recommended default)
-  // Tracked via UUID mapping
   notes: [
     {
+      activity: { source: "https://github.com/org/repo/pull/123" },
+      key: "description", // Use key for upsertable notes
       content: "New PR ready for review",
       links: [
         {
@@ -159,9 +163,10 @@ await this.tools.plot.createActivity({
   ],
 });
 
-// Add a note to existing activity (add message to thread)
+// Add or update a note using key (upserts if key exists)
 await this.tools.plot.createNote({
-  activity: { id: activityId },
+  activity: { source: "https://github.com/org/repo/pull/123" },
+  key: "approval", // Using key enables upserts
   content: "LGTM! Approved ✅",
 });
 ```
@@ -199,6 +204,7 @@ plot priority create           # Create new priority
 
 - [Getting Started](https://twist.plot.day/documents/Getting_Started.html) - Complete walkthrough
 - [Core Concepts](https://twist.plot.day/documents/Core_Concepts.html) - Twists, tools, and architecture
+- [Sync Strategies](https://twist.plot.day/documents/Sync_Strategies.html) - Data synchronization patterns (upserts, deduplication, ID management)
 - [Built-in Tools](https://twist.plot.day/documents/Built-in_Tools.html) - Plot, Store, AI, and more
 - [Building Custom Tools](https://twist.plot.day/documents/Building_Custom_Tools.html) - Create reusable twist tools
 - [Runtime Environment](https://twist.plot.day/documents/Runtime_Environment.html) - Execution constraints and optimization

package/bin/templates/AGENTS.template.md

@@ -27,10 +27,30 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 
 1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes
 2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message
-3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication
-4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`
+3. **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.
+4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot activities per external item (see SYNC_STRATEGIES.md)
+5. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`
 
-### Decision Tree
+### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)
+
+```
+New event/task/conversation from external system?
+  ├─ Has stable URL or ID?
+  │   └─ Yes → Set Activity.source to the canonical URL/ID
+  │             Create Activity (Plot handles deduplication automatically)
+  │             Use Note.key for different note types:
+  │               - "description" for main content
+  │               - "metadata" for status/priority/assignee
+  │               - "comment-{id}" for individual comments
+  │
+  └─ No stable identifier OR need multiple Plot activities per external item?
+      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)
+          See SYNC_STRATEGIES.md for details
+```
+
+### Advanced Decision Tree (Strategy 3: Generate and Store IDs)
+
+Only use when source/key upserts aren't sufficient (e.g., creating multiple activities from one external item):
 
 ```
 New event/task/conversation?
@@ -269,7 +289,9 @@ async onAuthComplete(authResult: { authToken: string }, provider: string) {
 
 ## Sync Pattern
 
-Pattern for syncing external data - demonstrates adding Notes to existing Activities:
+### Recommended: Upsert via Source/Key (Strategy 2)
+
+Pattern for syncing external data using automatic upserts - **no manual ID tracking needed**:
 
 ```typescript
 async startSync(calendarId: string): Promise<void> {
@@ -284,6 +306,57 @@ async startSync(calendarId: string): Promise<void> {
 }
 
 async handleEvent(
+  event: ExternalEvent,
+  calendarId: string
+): Promise<void> {
+  // Use the event's canonical URL as the source for automatic deduplication
+  const activity: NewActivityWithNotes = {
+    source: event.htmlLink, // or event.url, depending on your external system
+    type: ActivityType.Event,
+    title: event.summary || "(No title)",
+    start: event.start?.dateTime || event.start?.date || null,
+    end: event.end?.dateTime || event.end?.date || null,
+    notes: [],
+  };
+
+  // Add description as an upsertable note
+  if (event.description) {
+    activity.notes.push({
+      activity: { source: event.htmlLink },
+      key: "description", // This key enables upserts - same key updates the note
+      content: event.description,
+    });
+  }
+
+  // Add attendees as an upsertable note
+  if (event.attendees?.length) {
+    const attendeeList = event.attendees
+      .map(a => `- ${a.email}${a.displayName ? ` (${a.displayName})` : ''}`)
+      .join('\n');
+
+    activity.notes.push({
+      activity: { source: event.htmlLink },
+      key: "attendees", // Different key for different note types
+      content: `## Attendees\n${attendeeList}`,
+    });
+  }
+
+  // Create or update - Plot automatically handles deduplication based on source
+  await this.tools.plot.createActivity(activity);
+}
+
+async stopSync(calendarId: string): Promise<void> {
+  const authToken = await this.get<string>("auth_token");
+  await this.tools.calendarTool.stopSync(authToken, calendarId);
+}
+```
+
+### Advanced: Generate and Store IDs (Strategy 3)
+
+Only use this pattern when you need to create multiple Plot activities from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.
+
+```typescript
+async handleEventAdvanced(
   incomingActivity: NewActivityWithNotes,
   calendarId: string
 ): Promise<void> {
@@ -320,11 +393,6 @@ async handleEvent(
     id: activityId,
   });
 }
-
-async stopSync(calendarId: string): Promise<void> {
-  const authToken = await this.get<string>("auth_token");
-  await this.tools.calendarTool.stopSync(authToken, calendarId);
-}
 ```
 
 ## Calendar Selection Pattern
@@ -419,24 +487,18 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
   // Process one batch (keep under time limit)
   const result = await this.fetchBatch(state.nextPageToken);
 
-  // Process results (create activities with Notes)
+  // Process results using source/key pattern (automatic upserts, no manual tracking)
   for (const item of result.items) {
-    // Check if already synced
-    const mappingKey = `item_mapping:${resourceId}:${item.id}`;
-    const existingId = await this.get<Uuid>(mappingKey);
-
-    if (!existingId) {
-      // New item - generate UUID and store mapping
-      const activityId = Uuid.Generate();
-      await this.set(mappingKey, activityId);
-
-      await this.tools.plot.createActivity({
-        id: activityId,
-        type: ActivityType.Note,
-        title: item.title,
-        notes: [{ id: Uuid.Generate(), content: item.description }],
-      });
-    }
+    await this.tools.plot.createActivity({
+      source: item.url, // Use item's canonical URL for automatic deduplication
+      type: ActivityType.Note,
+      title: item.title,
+      notes: [{
+        activity: { source: item.url },
+        key: "description", // Use key for upsertable notes
+        content: item.description,
+      }],
+    });
   }
 
   if (result.nextPageToken) {
@@ -495,9 +557,9 @@ try {
 - **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.
 - **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.
 - **Always create Activities with Notes** - See "Understanding Activities and Notes" section above for the thread/message pattern and decision tree.
-- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.
-- **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.
-- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.
+- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.
+- **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
+- **Add Notes to existing Activities** - For source/key pattern, reference activities by source. For UUID pattern, look up stored mappings before creating new Activities. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
 - **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.
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.

package/cli/templates/AGENTS.template.md

@@ -27,10 +27,30 @@ Plot Twists are TypeScript classes that extend the `Twist` base class. Twists in
 
 1. **Always create Activities with an initial Note** - The title is just a summary; detailed content goes in Notes
 2. **Add Notes to existing Activities for updates** - Don't create a new Activity for each related message
-3. **Track external items using generated UUIDs** - Store mappings between external IDs and Plot UUIDs for deduplication
-4. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `doneAt`, use `Event` only for items with `start`/`end`
+3. **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for deduplication, and use Note.key for upsertable note content. No manual ID tracking needed.
+4. **For advanced cases, use generated UUIDs** - Only when you need multiple Plot activities per external item (see SYNC_STRATEGIES.md)
+5. **Most Activities should be `ActivityType.Note`** - Use `Action` only for tasks with `done`, use `Event` only for items with `start`/`end`
 
-### Decision Tree
+### Recommended Decision Tree (Strategy 2: Upsert via Source/Key)
+
+```
+New event/task/conversation from external system?
+  ├─ Has stable URL or ID?
+  │   └─ Yes → Set Activity.source to the canonical URL/ID
+  │             Create Activity (Plot handles deduplication automatically)
+  │             Use Note.key for different note types:
+  │               - "description" for main content
+  │               - "metadata" for status/priority/assignee
+  │               - "comment-{id}" for individual comments
+  │
+  └─ No stable identifier OR need multiple Plot activities per external item?
+      └─ Use Advanced Pattern (Strategy 3: Generate and Store IDs)
+          See SYNC_STRATEGIES.md for details
+```
+
+### Advanced Decision Tree (Strategy 3: Generate and Store IDs)
+
+Only use when source/key upserts aren't sufficient (e.g., creating multiple activities from one external item):
 
 ```
 New event/task/conversation?
@@ -269,7 +289,9 @@ async onAuthComplete(authResult: { authToken: string }, provider: string) {
 
 ## Sync Pattern
 
-Pattern for syncing external data - demonstrates adding Notes to existing Activities:
+### Recommended: Upsert via Source/Key (Strategy 2)
+
+Pattern for syncing external data using automatic upserts - **no manual ID tracking needed**:
 
 ```typescript
 async startSync(calendarId: string): Promise<void> {
@@ -284,6 +306,57 @@ async startSync(calendarId: string): Promise<void> {
 }
 
 async handleEvent(
+  event: ExternalEvent,
+  calendarId: string
+): Promise<void> {
+  // Use the event's canonical URL as the source for automatic deduplication
+  const activity: NewActivityWithNotes = {
+    source: event.htmlLink, // or event.url, depending on your external system
+    type: ActivityType.Event,
+    title: event.summary || "(No title)",
+    start: event.start?.dateTime || event.start?.date || null,
+    end: event.end?.dateTime || event.end?.date || null,
+    notes: [],
+  };
+
+  // Add description as an upsertable note
+  if (event.description) {
+    activity.notes.push({
+      activity: { source: event.htmlLink },
+      key: "description", // This key enables upserts - same key updates the note
+      content: event.description,
+    });
+  }
+
+  // Add attendees as an upsertable note
+  if (event.attendees?.length) {
+    const attendeeList = event.attendees
+      .map(a => `- ${a.email}${a.displayName ? ` (${a.displayName})` : ''}`)
+      .join('\n');
+
+    activity.notes.push({
+      activity: { source: event.htmlLink },
+      key: "attendees", // Different key for different note types
+      content: `## Attendees\n${attendeeList}`,
+    });
+  }
+
+  // Create or update - Plot automatically handles deduplication based on source
+  await this.tools.plot.createActivity(activity);
+}
+
+async stopSync(calendarId: string): Promise<void> {
+  const authToken = await this.get<string>("auth_token");
+  await this.tools.calendarTool.stopSync(authToken, calendarId);
+}
+```
+
+### Advanced: Generate and Store IDs (Strategy 3)
+
+Only use this pattern when you need to create multiple Plot activities from a single external item, or when the external system doesn't provide stable identifiers. See SYNC_STRATEGIES.md for details.
+
+```typescript
+async handleEventAdvanced(
   incomingActivity: NewActivityWithNotes,
   calendarId: string
 ): Promise<void> {
@@ -320,11 +393,6 @@ async handleEvent(
     id: activityId,
   });
 }
-
-async stopSync(calendarId: string): Promise<void> {
-  const authToken = await this.get<string>("auth_token");
-  await this.tools.calendarTool.stopSync(authToken, calendarId);
-}
 ```
 
 ## Calendar Selection Pattern
@@ -419,24 +487,18 @@ async syncBatch(args: any, resourceId: string): Promise<void> {
   // Process one batch (keep under time limit)
   const result = await this.fetchBatch(state.nextPageToken);
 
-  // Process results (create activities with Notes)
+  // Process results using source/key pattern (automatic upserts, no manual tracking)
   for (const item of result.items) {
-    // Check if already synced
-    const mappingKey = `item_mapping:${resourceId}:${item.id}`;
-    const existingId = await this.get<Uuid>(mappingKey);
-
-    if (!existingId) {
-      // New item - generate UUID and store mapping
-      const activityId = Uuid.Generate();
-      await this.set(mappingKey, activityId);
-
-      await this.tools.plot.createActivity({
-        id: activityId,
-        type: ActivityType.Note,
-        title: item.title,
-        notes: [{ id: Uuid.Generate(), content: item.description }],
-      });
-    }
+    await this.tools.plot.createActivity({
+      source: item.url, // Use item's canonical URL for automatic deduplication
+      type: ActivityType.Note,
+      title: item.title,
+      notes: [{
+        activity: { source: item.url },
+        key: "description", // Use key for upsertable notes
+        content: item.description,
+      }],
+    });
   }
 
   if (result.nextPageToken) {
@@ -495,9 +557,9 @@ try {
 - **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.
 - **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.
 - **Always create Activities with Notes** - See "Understanding Activities and Notes" section above for the thread/message pattern and decision tree.
-- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `doneAt`, and `Event` for items with `start`/`end`.
-- **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.
-- **Add Notes to existing Activities** - Look up stored UUID mappings before creating new Activities. Think thread replies, not new threads.
+- **Use correct Activity types** - Most should be `ActivityType.Note`. Only use `Action` for tasks with `done`, and `Event` for items with `start`/`end`.
+- **Use Activity.source and Note.key for automatic upserts (Recommended)** - Set Activity.source to the external item's URL for automatic deduplication. Only use UUID generation and storage for advanced cases (see SYNC_STRATEGIES.md).
+- **Add Notes to existing Activities** - For source/key pattern, reference activities by source. For UUID pattern, look up stored mappings before creating new Activities. Think thread replies, not new threads.
 - Tools are declared in the `build` method and accessed via `this.tools.toolName` in twist methods.
 - **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.
 - **Always use Callbacks tool for persistent references** - Direct function references don't survive worker restarts.

package/dist/common/calendar.d.ts

@@ -54,9 +54,13 @@ export interface SyncOptions {
  * 5. Start sync for selected calendars
  * 6. Process incoming events via callbacks
  *
+ * **Recommended Data Sync Strategy:**
+ * Use Activity.source and Note.key for automatic upserts without manual ID tracking.
+ * See SYNC_STRATEGIES.md for detailed patterns and when to use alternative approaches.
+ *
  * @example
  * ```typescript
- * // Typical calendar integration flow
+ * // Typical calendar integration flow using source/key upserts
  * class MyCalendarTwist extends Twist {
  *   private googleCalendar: GoogleCalendar;
  *
@@ -89,21 +93,10 @@ export interface SyncOptions {
  *     syncUpdate: SyncUpdate,
  *     syncMeta: { initialSync: boolean }
  *   ) {
- *     // Step 4: Process synced events
- *     if ('activityId' in syncUpdate) {
- *       // Update existing activity
- *       if (syncUpdate.update) {
- *         await this.plot.updateActivity(syncUpdate.update);
- *       }
- *       if (syncUpdate.notes) {
- *         for (const note of syncUpdate.notes) {
- *           await this.plot.createNote(note);
- *         }
- *       }
- *     } else {
- *       // Create new activity
- *       await this.plot.createActivity(syncUpdate);
- *     }
+ *     // Step 4: Process synced events using source/key pattern
+ *     // The sync update will automatically use the event's URL as the source
+ *     // for deduplication - no manual ID tracking needed
+ *     await this.plot.createActivity(syncUpdate);
  *   }
  * }
  * ```
@@ -136,13 +129,17 @@ export interface CalendarTool {
      * event import and ongoing change notifications. The callback function
      * will be invoked for each synced event.
      *
-     * Tools implementing this should:
-     * - Generate UUIDs for new activities and notes using Uuid.Generate()
-     * - Track activity IDs locally to detect updates vs new items
-     * - Send NewActivityWithNotes for new events
-     * - Send update object with activityId for changed events
+     * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):
+     * - Set Activity.source to the event's canonical URL (e.g., event.htmlLink)
+     * - Use Note.key for event details (description, attendees, etc.) to enable upserts
+     * - No manual ID tracking needed - Plot handles deduplication automatically
+     * - Send NewActivityWithNotes for all events (creates new or updates existing)
      * - Set activity.unread = false for initial sync, true for incremental updates
      *
+     * **Alternative** (Strategy 3 - Advanced cases):
+     * - Use Uuid.Generate() and store ID mappings when creating multiple activities per event
+     * - See SYNC_STRATEGIES.md for when this is appropriate
+     *
      * @param authToken - Authorization token for calendar access
      * @param calendarId - ID of the calendar to sync
      * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced event

package/dist/common/calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/common/calendar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACvE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CACP,SAAS,SAAS,CAChB,UAAU,EAAE,UAAU,EACtB,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,GAAG,EAER,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAC9B,UAAU,EAAE,GAAG,EACf,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,GAAG,GACJ,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/common/calendar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACvE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CACP,SAAS,SAAS,CAChB,UAAU,EAAE,UAAU,EACtB,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,GAAG,EAER,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAC9B,UAAU,EAAE,GAAG,EACf,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,GAAG,GACJ,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE"}

package/dist/common/messaging.d.ts

@@ -41,6 +41,10 @@ export interface MessageSyncOptions {
  *
  * All synced messages/emails are converted to ActivityWithNotes objects.
  * Each email thread or chat conversation becomes an Activity with Notes for each message.
+ *
+ * **Recommended Data Sync Strategy:**
+ * Use Activity.source (thread URL or ID) and Note.key (message ID) for automatic upserts.
+ * See SYNC_STRATEGIES.md for detailed patterns.
  */
 export interface MessagingTool {
     /**
@@ -64,13 +68,18 @@ export interface MessagingTool {
      * Email threads and chat conversations are converted to SyncUpdate objects,
      * which can be either new items or updates to existing items.
      *
-     * Tools implementing this should:
-     * - Generate UUIDs for new activities and notes using Uuid.Generate()
-     * - Track activity IDs locally to detect updates vs new threads
-     * - Send NewActivityWithNotes for new threads
-     * - Send update object with activityId and new notes for new messages in existing threads
+     * **Recommended Implementation** (Strategy 2 - Upsert via Source/Key):
+     * - Set Activity.source to the thread/conversation URL or stable ID (e.g., "slack:{channelId}:{threadTs}")
+     * - Use Note.key for individual messages (e.g., "message-{messageId}")
+     * - Each message becomes a separate note with unique key for upserts
+     * - No manual ID tracking needed - Plot handles deduplication automatically
+     * - Send NewActivityWithNotes for all threads (creates new or updates existing)
      * - Set activity.unread = false for initial sync, true for incremental updates
      *
+     * **Alternative** (Strategy 3 - Advanced cases):
+     * - Use Uuid.Generate() and store ID mappings when creating multiple activities per thread
+     * - See SYNC_STRATEGIES.md for when this is appropriate
+     *
      * @param authToken - Authorization token for access
      * @param channelId - ID of the channel (e.g., channel, inbox) to sync
      * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced conversation

package/dist/common/messaging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../src/common/messaging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CACP,SAAS,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAEjE,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GACtE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../../src/common/messaging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CACP,SAAS,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAEjE,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GACtE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D"}

package/dist/common/projects.d.ts

@@ -41,6 +41,10 @@ export interface ProjectSyncOptions {
  *
  * All synced issues/tasks are converted to ActivityWithNotes objects.
  * Each issue becomes an Activity with Notes for the description and comments.
+ *
+ * **Recommended Data Sync Strategy:**
+ * Use Activity.source (issue URL) and Note.key for automatic upserts.
+ * See SYNC_STRATEGIES.md for detailed patterns.
  */
 export interface ProjectTool {
     /**
@@ -64,14 +68,20 @@ export interface ProjectTool {
      * Issues and tasks are converted to SyncUpdate objects, which can be either
      * new items or updates to existing items.
      *
-     * Tools implementing this should:
-     * - Generate UUIDs for new activities and notes using Uuid.Generate()
-     * - Track activity IDs locally to detect updates vs new items
-     * - Send NewActivityWithNotes for new issues
-     * - Send update object with activityId for changed issues or new comments
-     * - Track description note ID and hash to detect description changes
+     * **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)
+     * - Use Note.key for issue details:
+     *   - key: "description" for issue description (upserts on changes)
+     *   - key: "metadata" for status, priority, assignee, etc.
+     *   - key: "comment-{commentId}" for individual comments (unique per comment)
+     * - No manual ID tracking needed - Plot handles deduplication automatically
+     * - Send NewActivityWithNotes for all issues (creates new or updates existing)
      * - Set activity.unread = false for initial sync, true for incremental updates
      *
+     * **Alternative** (Strategy 3 - Advanced cases):
+     * - Use Uuid.Generate() and store ID mappings when creating multiple activities per issue
+     * - See SYNC_STRATEGIES.md for when this is appropriate
+     *
      * @param authToken - Authorization token for access
      * @param projectId - ID of the project to sync
      * @param callback - Function receiving (syncUpdate, ...extraArgs) for each synced issue
@@ -95,10 +105,10 @@ export interface ProjectTool {
      * sync activity updates back to the external service.
      *
      * The update object contains only the fields that changed, plus id and source.
-     * Uses the combination of start and doneAt to determine workflow state:
-     * - doneAt set → Completed/Done state
-     * - doneAt null + start set → In Progress/Active state
-     * - doneAt null + start null → Backlog/Todo state
+     * Uses the combination of start and done to determine workflow state:
+     * - done set → Completed/Done state
+     * - done null + start set → In Progress/Active state
+     * - done null + start null → Backlog/Todo state
      *
      * @param authToken - Authorization token for access
      * @param update - ActivityUpdate with changed fields (includes id and source)

package/dist/common/projects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/common/projects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAEd,UAAU,EACX,MAAM,UAAU,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACtE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CACP,SAAS,SAAS,CAChB,UAAU,EAAE,UAAU,EACtB,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,GAAG,EAER,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,GAAG,SAAS,EAAE,SAAS,SAAS,CAC9B,UAAU,EAAE,GAAG,EACf,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,GAAG,GACJ,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;;;;;;OAUG;IACH,eAAe,CAAC,CACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/common/projects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EAEd,UAAU,EACX,MAAM,UAAU,CAAC;AAElB;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gFAAgF;IAChF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACtE,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAChE,CAAC,GACD,EAAE,GACL,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,CACP,SAAS,SAAS,CAChB,UAAU,EAAE,UAAU,EACtB,GAAG,IAAI,EAAE,GAAG,EAAE,KACX,GAAG,EAER,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE,kBAAkB,EAC5B,GAAG,SAAS,EAAE,SAAS,SAAS,CAC9B,UAAU,EAAE,GAAG,EACf,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,GAAG,GACJ,CAAC,GACD,EAAE,GACL,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;;;;;;OAUG;IACH,eAAe,CAAC,CACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "eJyNkrFOwzAQht/l5qtRSJyzslWdsiAk2FCFTGpoFDdG9qEOVd4dOQFkJnvxYH/3f3fy3cA7xwG6F6qOCN68WzPw6OYA3Q2oiuesLwY66J+ds4AwjfMJuupeIXx5Cx0MVodgwh07Z8VKiTNfIrq+QAccTrtYttsuEIbzaE/ezNHbYN0orEmhbCuUirBtamwVIUlCInlcEKhJOilqpKCPBaFuVBp8HQOHXHR45ZUTG14goVSy7/MCPYp9nw+WbfpBB23tmx6mggGGX1T8FRXYFKXrMLP58HrblaxwTGiRlua1bVMn2gfDV+envHHeQPFTUOD5N96jdZyXfFrHIqL5eJJp/BM7b/L5IWJihQsMJNNd1qFkEzhiYoVzhmX5BnM3XJs="
+window.hierarchyData = "eJyNkj1PwzAQhv/LzVfTJq2/toqpC0KCDVXIpIZGcWNkH+pQ5b8jJ4DMZC8e7Ofe506+GwTvKYJ+EZsjQrDvznbU+zGCvoHYpHM0FwsaDs/eO0AY+vEEetNIhK/gQEPnTIw23pH3js0UO9MlofMLaKB4WqWy1XKB0J17dwp2TN4ttlxhqxTuZIN8LZHzLYq1RCEkCsWPE4LYZp1UNVLRx4TQcpUHX/tIsRQdX2nm2IJXSFQu2R/KAtOz/aEcvJNNFnxvnHsz3VAxQPeLsr+iso2vZb4OI9mPYJZdKQr7jGZ5aYWW53//YOnqw1A2jgvIfgrKHvFvvEfnqSz5dJ5YQiviRR7/RD7Ycn5MGJvhCoPi+S6bWLMJlDA2wyXDNH0Dl09cpw=="