@plotday/twister 0.27.0 → 0.29.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

@@ -1,4 +1,5 @@
 import type { ActivityLink, SyncUpdate } from "../index";
+import type { NoFunctions } from "../utils/types";
 /**
  * Represents successful calendar authorization.
  *
@@ -54,9 +55,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;
  *
@@ -78,9 +83,12 @@ export interface SyncOptions {
  *     const primaryCalendar = calendars.find(c => c.primary);
  *     if (primaryCalendar) {
  *       await this.googleCalendar.startSync(
- *         auth.authToken,
- *         primaryCalendar.id,
- *         "onCalendarEvent"
+ *         {
+ *           authToken: auth.authToken,
+ *           calendarId: primaryCalendar.id
+ *         },
+ *         this.onCalendarEvent,
+ *         { initialSync: true }
  *       );
  *     }
  *   }
@@ -89,21 +97,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,21 +133,31 @@ 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
      *
-     * @param authToken - Authorization token for calendar access
-     * @param calendarId - ID of the calendar to sync
+     * **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 options - Sync configuration options
+     * @param options.authToken - Authorization token for calendar access
+     * @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 extraArgs - Additional arguments to pass to the callback (type-checked)
+     * @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<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(authToken: string, calendarId: string, callback: TCallback, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? R : []): Promise<void>;
+    startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(options: {
+        authToken: string;
+        calendarId: string;
+    } & SyncOptions, callback: TCallback, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? NoFunctions<R> : []): Promise<void>;
     /**
      * Stops synchronizing events from a specific calendar.
      *

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;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,SAAS,CAAC,SAAS,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACzE,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,WAAW,EACf,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GACtE,WAAW,CAAC,CAAC,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

@@ -1,4 +1,5 @@
 import type { ActivityLink, SyncUpdate } from "../index";
+import type { NoFunctions } from "../utils/types";
 /**
  * Represents a successful messaging service authorization.
  *
@@ -41,6 +42,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,21 +69,30 @@ 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
      *
-     * @param authToken - Authorization token for access
-     * @param channelId - ID of the channel (e.g., channel, inbox) to sync
+     * **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 options - Sync configuration options
+     * @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 options - Optional configuration for limiting the sync scope (e.g., time range)
-     * @param extraArgs - Additional arguments to pass to the callback (type-checked)
+     * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
      * @returns Promise that resolves when sync setup is complete
      */
-    startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(authToken: string, channelId: string, callback: TCallback, options?: MessageSyncOptions, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? R : []): Promise<void>;
+    startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(options: {
+        authToken: string;
+        channelId: string;
+    } & MessageSyncOptions, callback: TCallback, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? NoFunctions<R> : []): Promise<void>;
     /**
      * Stops synchronizing messages from a specific channel.
      *

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;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,SAAS,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACzE,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,kBAAkB,EACtB,QAAQ,EAAE,SAAS,EACnB,GAAG,SAAS,EAAE,SAAS,SAAS,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GACtE,WAAW,CAAC,CAAC,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

@@ -1,4 +1,5 @@
 import type { ActivityLink, ActivityUpdate, SyncUpdate } from "../index";
+import type { NoFunctions } from "../utils/types";
 /**
  * Represents a successful project management service authorization.
  *
@@ -41,6 +42,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,22 +69,32 @@ 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
      *
-     * @param authToken - Authorization token for access
-     * @param projectId - ID of the project to sync
+     * **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 options - Sync configuration options
+     * @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 options - Optional configuration for limiting the sync scope (e.g., time range)
-     * @param extraArgs - Additional arguments to pass to the callback (type-checked)
+     * @param extraArgs - Additional arguments to pass to the callback (type-checked, no functions allowed)
      * @returns Promise that resolves when sync setup is complete
      */
-    startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(authToken: string, projectId: string, callback: TCallback, options?: ProjectSyncOptions, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? R : []): Promise<void>;
+    startSync<TCallback extends (syncUpdate: SyncUpdate, ...args: any[]) => any>(options: {
+        authToken: string;
+        projectId: string;
+    } & ProjectSyncOptions, callback: TCallback, ...extraArgs: TCallback extends (syncUpdate: any, ...rest: infer R) => any ? NoFunctions<R> : []): Promise<void>;
     /**
      * Stops synchronizing issues from a specific project.
      *
@@ -95,10 +110,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)