Switch to stored IDs for source item associations

Using the Activity.source field for associating activity with source
items led to several inefficient patterns where twists and tools needed
to look up an activity for its ID. The new pattern is for tools and
twists to manage their own mappings, which they can do in whatever way
best supports the service they're using and their access patterns.

This change also replaces all contact fields with a type that supports
either the contact ID or the contact details (including the email
address). This also removes the need to look up contact IDs when
creating and updating items.

Author: KrisBraun

.changeset/cute-boxes-exist.md

@@ -0,0 +1,12 @@
+---
+"@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
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Replace Activity.source for linking with source items with generated and stored UUIDs

.changeset/frank-tigers-throw.md

@@ -0,0 +1,12 @@
+---
+"@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
+"@plotday/twister": minor
+---
+
+Changed: BREAKING: Support either IDs or email for contact fields

pnpm-lock.yaml

@@ -5,13 +5,13 @@ import {
   ActivityType,
   type NewActivityWithNotes,
 } from "@plotday/twister";
-import type { Actor, ActorId, NewContact } from "@plotday/twister/plot";
 import type {
   Project,
   ProjectAuth,
   ProjectSyncOptions,
   ProjectTool,
 } from "@plotday/twister/common/projects";
+import type { NewContact } from "@plotday/twister/plot";
 import { Tool, type ToolBuilder } from "@plotday/twister/tool";
 import { type Callback, Callbacks } from "@plotday/twister/tools/callbacks";
 import {
@@ -150,19 +150,13 @@ export class Asana extends Tool<Asana> implements ProjectTool {
    * Start syncing tasks from an Asana project
    */
   async startSync<
-    TCallback extends (
-      task: NewActivityWithNotes,
-      ...args: any[]
-    ) => any
+    TCallback extends (task: NewActivityWithNotes, ...args: any[]) => any
   >(
     authToken: string,
     projectId: string,
     callback: TCallback,
     options?: ProjectSyncOptions,
-    ...extraArgs: TCallback extends (
-      task: any,
-      ...rest: infer R
-    ) => any
+    ...extraArgs: TCallback extends (task: any, ...rest: infer R) => any
       ? R
       : []
   ): Promise<void> {
@@ -288,10 +282,7 @@ export class Asana extends Tool<Asana> implements ProjectTool {
       // Set unread based on sync type (false for initial sync to avoid notification overload)
       activityWithNotes.unread = !state.initialSync;
       // Execute the callback using the callback token
-      await this.tools.callbacks.run(
-        callbackToken,
-        activityWithNotes
-      );
+      await this.tools.callbacks.run(callbackToken, activityWithNotes);
     }
 
     // Check if more pages by checking if we got a full batch
@@ -329,34 +320,23 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     const createdBy = task.created_by;
     const assignee = task.assignee;
 
-    // Create contacts for created_by and assignee
-    const contacts: NewContact[] = [];
+    // Prepare author and assignee contacts - will be passed directly as NewContact
+    let authorContact: NewContact | undefined;
+    let assigneeContact: NewContact | undefined;
+
     if (createdBy?.email) {
-      contacts.push({
+      authorContact = {
         email: createdBy.email,
         name: createdBy.name,
         avatar: createdBy.photo?.image_128x128,
-      });
+      };
     }
-    if (assignee?.email && assignee.email !== createdBy?.email) {
-      contacts.push({
+    if (assignee?.email) {
+      assigneeContact = {
         email: assignee.email,
         name: assignee.name,
         avatar: assignee.photo?.image_128x128,
-      });
-    }
-
-    let authorActor: Actor | undefined;
-    let assigneeActor: Actor | undefined;
-
-    if (contacts.length > 0) {
-      const actors = await this.tools.plot.addContacts(contacts);
-      if (createdBy?.email) {
-        authorActor = actors.find((a) => a.email === createdBy.email);
-      }
-      if (assignee?.email) {
-        assigneeActor = actors.find((a) => a.email === assignee.email);
-      }
+      };
     }
 
     // Build notes array: description
@@ -374,9 +354,12 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     return {
       type: ActivityType.Action,
       title: task.name,
-      source: `asana:task:${projectId}:${task.gid}`,
-      author: authorActor,
-      assignee: assigneeActor,
+      meta: {
+        source: `asana:task:${projectId}:${task.gid}`,
+        taskGid: task.gid,
+      },
+      author: authorContact,
+      assignee: assigneeContact,
       doneAt: task.completed ? new Date(task.completed_at || Date.now()) : null,
       notes,
     };
@@ -392,8 +375,9 @@ export class Asana extends Tool<Asana> implements ProjectTool {
     authToken: string,
     update: import("@plotday/twister").ActivityUpdate
   ): Promise<void> {
-    // Extract Asana task GID from source
-    const taskGid = update.source?.split(":").pop();
+    // Extract Asana task GID from meta
+    const source = update.meta?.source as string | undefined;
+    const taskGid = source?.split(":").pop();
     if (!taskGid) {
       throw new Error("Invalid source format for Asana task");
     }

tools/asana/src/asana.ts

@@ -1,11 +1,9 @@
 import { ActivityType } from "@plotday/twister";
 import type {
-  ActivityWithNotes,
-  Actor,
-  ActorId,
-  ActorType,
-  Note,
-} from "@plotday/twister";
+  NewActivityWithNotes,
+  NewActor,
+} from "@plotday/twister/plot";
+import { Uuid } from "@plotday/twister/utils/uuid";
 
 export type GmailLabel = {
   id: string;
@@ -240,35 +238,11 @@ export function parseEmailAddress(headerValue: string): EmailAddress {
   };
 }
 
-/**
- * Converts an EmailAddress to an Actor.
- */
-function emailAddressToActor(emailAddress: EmailAddress): Actor {
-  return {
-    id: `contact:${emailAddress.email}` as ActorId,
-    type: 2 as ActorType, // ActorType.Contact
-    email: emailAddress.email,
-    name: emailAddress.name,
-  };
-}
-
-/**
- * Parses multiple email addresses from a header value (comma-separated).
- */
-function parseEmailAddresses(headerValue: string | null): Actor[] {
-  if (!headerValue) return [];
-
-  return headerValue
-    .split(",")
-    .map((addr) => addr.trim())
-    .filter((addr) => addr.length > 0)
-    .map((addr) => emailAddressToActor(parseEmailAddress(addr)));
-}
 
 /**
- * Parses email addresses and returns just the ActorIds for mentions.
+ * Parses email addresses and returns NewActor[] for mentions.
  */
-function parseEmailAddressIds(headerValue: string | null): ActorId[] {
+function parseEmailAddressesToNewActors(headerValue: string | null): NewActor[] {
   if (!headerValue) return [];
 
   return headerValue
@@ -277,7 +251,10 @@ function parseEmailAddressIds(headerValue: string | null): ActorId[] {
     .filter((addr) => addr.length > 0)
     .map((addr) => {
       const parsed = parseEmailAddress(addr);
-      return `contact:${parsed.email}` as ActorId;
+      return {
+        email: parsed.email,
+        name: parsed.name || undefined,
+      } as NewActor;
     });
 }
 
@@ -367,36 +344,15 @@ function extractAttachments(
 }
 
 /**
- * Transforms a Gmail thread into an ActivityWithNotes structure.
+ * Transforms a Gmail thread into a NewActivityWithNotes structure.
  * The subject becomes the Activity title, and each email becomes a Note.
  */
-export function transformGmailThread(thread: GmailThread): ActivityWithNotes {
+export function transformGmailThread(thread: GmailThread): NewActivityWithNotes {
   if (!thread.messages || thread.messages.length === 0) {
     // Return empty structure for invalid threads
     return {
-      id: `gmail:${thread.id}` as any,
       type: ActivityType.Note,
-      author: { id: "system" as ActorId, type: 1 as ActorType, name: null },
-      title: null,
-      assignee: null,
-      doneAt: null,
-      start: null,
-      end: null,
-      recurrenceUntil: null,
-      recurrenceCount: null,
-      priority: null as any,
-      recurrenceRule: null,
-      recurrenceExdates: null,
-      recurrenceDates: null,
-      recurrence: null,
-      occurrence: null,
-      source: null,
-      meta: null,
-      mentions: null,
-      tags: null,
-      draft: false,
-      private: false,
-      archived: false,
+      title: "",
       notes: [],
     };
   }
@@ -405,33 +361,15 @@ export function transformGmailThread(thread: GmailThread): ActivityWithNotes {
   const subject = getHeader(parentMessage, "Subject");
 
   // Create Activity
-  const activity: ActivityWithNotes = {
-    id: `gmail:${thread.id}` as any,
+  const activity: NewActivityWithNotes = {
     type: ActivityType.Note,
-    author: { id: "system" as ActorId, type: 1 as ActorType, name: null },
     title: subject || "Email",
-    assignee: null,
-    doneAt: null,
     start: new Date(parseInt(parentMessage.internalDate)),
-    end: null,
-    recurrenceUntil: null,
-    recurrenceCount: null,
-    priority: null as any,
-    recurrenceRule: null,
-    recurrenceExdates: null,
-    recurrenceDates: null,
-    recurrence: null,
-    occurrence: null,
-    source: `gmail:${thread.id}`,
     meta: {
       threadId: thread.id,
       historyId: thread.historyId,
+      source: `gmail:${thread.id}`,
     },
-    mentions: null,
-    tags: null,
-    draft: false,
-    private: false,
-    archived: false,
     notes: [],
   };
 
@@ -446,23 +384,21 @@ export function transformGmailThread(thread: GmailThread): ActivityWithNotes {
 
     const body = extractBody(message.payload);
 
-    // Combine to and cc for mentions
-    const mentions: ActorId[] = [
-      ...parseEmailAddressIds(to),
-      ...parseEmailAddressIds(cc),
+    // Combine to and cc for mentions - convert to NewActor[]
+    const mentions: NewActor[] = [
+      ...parseEmailAddressesToNewActors(to),
+      ...parseEmailAddressesToNewActors(cc),
     ];
 
-    const note: Note = {
-      id: `gmail:${thread.id}:${message.id}` as any,
-      activity: activity,
-      author: emailAddressToActor(sender),
+    // Create NewNote (Omit<NewNote, "activity">)
+    const note = {
+      id: Uuid.Generate(),
+      author: {
+        email: sender.email,
+        name: sender.name || undefined,
+      } as NewActor,
       content: body || message.snippet,
-      links: null,
-      mentions: mentions.length > 0 ? mentions : null,
-      tags: null,
-      draft: false,
-      private: false,
-      archived: false,
+      mentions: mentions.length > 0 ? mentions : undefined,
     };
 
     activity.notes.push(note);