Simpler upsert-based sync

Author: KrisBraun

.changeset/cute-showers-scream.md

@@ -0,0 +1,11 @@
+---
+"@plotday/tool-outlook-calendar": minor
+"@plotday/tool-google-calendar": minor
+"@plotday/tool-linear": minor
+"@plotday/tool-asana": minor
+"@plotday/tool-gmail": minor
+"@plotday/tool-slack": minor
+"@plotday/tool-jira": minor
+---
+
+Changed: Use Activity.source with canonical URLs for upserting

.changeset/petite-bats-think.md

@@ -0,0 +1,5 @@
+---
+"@plotday/twister": minor
+---
+
+Added: Activity.source and Note.key for upserts

tools/asana/src/asana.ts

@@ -2,8 +2,11 @@ import * as asana from "asana";
 
 import {
   type ActivityLink,
+  ActivityLinkType,
   ActivityType,
   type NewActivityWithNotes,
+  type NewNote,
+  Uuid,
 } from "@plotday/twister";
 import type {
   Project,
@@ -269,8 +272,8 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     for (const task of tasksResult.data) {
       // Optionally filter by time
       if (options?.timeMin) {
-        const createdAt = new Date(task.created_at);
-        if (createdAt < options.timeMin) {
+        const created = new Date(task.created_at);
+        if (created < options.timeMin) {
           continue;
         }
       }
@@ -339,28 +342,46 @@ export class Asana extends Tool<Asana> implements ProjectTool {
       };
     }
 
-    // Build notes array: description
-    const notes: Array<{ content: string }> = [];
+    // Build notes array: always create initial note with description and link
+    const notes: NewNote[] = [];
 
+    // Extract description (if any)
+    let description: string | null = null;
     if (task.notes) {
-      notes.push({ content: task.notes });
+      description = task.notes;
     }
 
-    // Ensure at least one note exists
-    if (notes.length === 0) {
-      notes.push({ content: "" });
-    }
+    // Construct Asana task URL
+    const taskUrl = `https://app.asana.com/0/${projectId}/${task.gid}`;
+
+    // Create initial note with description and link to Asana task
+    const links: ActivityLink[] = [];
+    links.push({
+      type: ActivityLinkType.external,
+      title: `Open in Asana`,
+      url: taskUrl,
+    });
+
+    notes.push({
+      activity: { source: taskUrl },
+      key: "description",
+      content: description,
+      created: task.created_at ? new Date(task.created_at) : undefined,
+      links: links.length > 0 ? links : null,
+    });
 
     return {
+      source: taskUrl,
       type: ActivityType.Action,
       title: task.name,
+      created: task.created_at ? new Date(task.created_at) : undefined,
       meta: {
-        source: `asana:task:${projectId}:${task.gid}`,
         taskGid: task.gid,
+        projectId,
       },
       author: authorContact,
-      assignee: assigneeContact,
-      doneAt: task.completed ? new Date(task.completed_at || Date.now()) : null,
+      assignee: assigneeContact ?? null, // Explicitly set to null for unassigned tasks
+      done: task.completed && task.completed_at ? new Date(task.completed_at) : null,
       notes,
     };
   }
@@ -395,10 +416,10 @@ export class Asana extends Tool<Asana> implements ProjectTool {
       updateFields.assignee = update.assignee?.id || null;
     }
 
-    // Handle completion status based on doneAt
+    // Handle completion status based on done
     // Asana only has completed boolean (no In Progress state)
-    if (update.doneAt !== undefined) {
-      updateFields.completed = update.doneAt !== null;
+    if (update.done !== undefined) {
+      updateFields.completed = update.done !== null;
     }
 
     // Apply updates if any fields changed

tools/gmail/src/gmail-api.ts

@@ -3,7 +3,6 @@ import type {
   NewActivityWithNotes,
   NewActor,
 } from "@plotday/twister/plot";
-import { Uuid } from "@plotday/twister/utils/uuid";
 
 export type GmailLabel = {
   id: string;
@@ -360,15 +359,18 @@ export function transformGmailThread(thread: GmailThread): NewActivityWithNotes
   const parentMessage = thread.messages[0];
   const subject = getHeader(parentMessage, "Subject");
 
+  // Canonical URL for the thread
+  const canonicalUrl = `https://mail.google.com/mail/u/0/#inbox/${thread.id}`;
+
   // Create Activity
   const activity: NewActivityWithNotes = {
+    source: canonicalUrl,
     type: ActivityType.Note,
     title: subject || "Email",
     start: new Date(parseInt(parentMessage.internalDate)),
     meta: {
       threadId: thread.id,
       historyId: thread.historyId,
-      source: `gmail:${thread.id}`,
     },
     notes: [],
   };
@@ -390,9 +392,10 @@ export function transformGmailThread(thread: GmailThread): NewActivityWithNotes
       ...parseEmailAddressesToNewActors(cc),
     ];
 
-    // Create NewNote (Omit<NewNote, "activity">)
+    // Create NewNote with idempotent key
     const note = {
-      id: Uuid.Generate(),
+      activity: { source: canonicalUrl },
+      key: message.id,
       author: {
         email: sender.email,
         name: sender.name || undefined,

tools/gmail/src/gmail.ts

@@ -305,7 +305,7 @@ export class Gmail extends Tool<Gmail> implements MessagingTool {
         channelId,
         historyId: watchResult.historyId,
         expiration: new Date(parseInt(watchResult.expiration)),
-        createdAt: new Date().toISOString(),
+        created: new Date().toISOString(),
       });
 
       console.log("Gmail webhook setup complete", {