feat(gmail): bundle calendar-related email conversations onto the event thread

Wires classifyCalendarThread into saveTransformedThread: a qualifying
conversation (a Plot-sent reply chain, or an ICS update/cancellation)
gets an icaluid:<uid> alias appended to the link's sources so it bundles
onto the calendar event's Plot thread. Cancellation emails also record a
cancel-email:<uid> marker for calendar-side suppression.

Author: KrisBraun

connectors/gmail/src/sync.test.ts

@@ -1,9 +1,21 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import type { CreateLinkDraft, Uuid } from "@plotday/twister";
-
-import { GmailApi, GmailApiError, type GmailHeader, type GmailMessage } from "./gmail-api";
-import { type GmailSyncHost, onCreateLinkFn, onNoteCreatedFn } from "./sync";
+import type { CreateLinkDraft, NewLinkWithNotes, Uuid } from "@plotday/twister";
+
+import {
+  GmailApi,
+  GmailApiError,
+  type GmailHeader,
+  type GmailMessage,
+  type GmailMessagePart,
+  type GmailThread,
+} from "./gmail-api";
+import {
+  type GmailSyncHost,
+  onCreateLinkFn,
+  onNoteCreatedFn,
+  processEmailThreadsFn,
+} from "./sync";
 
 /** Decode the base64url raw message the Gmail send API would receive. */
 function decodeRawMessage(b64url: string): string {
@@ -379,3 +391,93 @@ describe("onNoteCreatedFn — calendar event thread", () => {
     expect(res).toBeUndefined();
   });
 });
+
+/** Build a GmailMessagePart, encoding `data` as base64url like the real API. */
+function part(
+  mimeType: string,
+  opts: {
+    data?: string;
+    parts?: GmailMessagePart[];
+    headers?: Array<[string, string]>;
+  } = {}
+): GmailMessagePart {
+  return {
+    mimeType,
+    headers: (opts.headers ?? []).map(([name, value]) => ({ name, value })),
+    body:
+      opts.data !== undefined
+        ? { size: opts.data.length, data: b64url(opts.data) }
+        : undefined,
+    parts: opts.parts,
+  };
+}
+
+/** A single-message GmailThread carrying a `text/calendar` ICS part. */
+function calendarUpdateThread(threadId: string, ics: string): GmailThread {
+  const message: GmailMessage = {
+    id: `${threadId}-msg-1`,
+    threadId,
+    labelIds: ["INBOX"],
+    snippet: "Event updated",
+    historyId: "1",
+    internalDate: "1700000000000",
+    sizeEstimate: 500,
+    payload: part("multipart/mixed", {
+      headers: [
+        ["From", "calendar-notification@google.com"],
+        ["To", "me@example.com"],
+        ["Subject", "Updated: Weekly sync"],
+      ],
+      parts: [
+        part("text/plain", { data: "The event has been updated." }),
+        part("text/calendar", { data: ics }),
+      ],
+    }),
+  };
+  return { id: threadId, historyId: "1", messages: [message] };
+}
+
+function gmailThreadWithIcsUpdate(uid: string): GmailThread {
+  const ics = `BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nBEGIN:VEVENT\r\nUID:${uid}\r\nSEQUENCE:2\r\nEND:VEVENT\r\nEND:VCALENDAR`;
+  return calendarUpdateThread("cal-update-thread", ics);
+}
+
+function gmailThreadWithIcsCancel(uid: string): GmailThread {
+  const ics = `BEGIN:VCALENDAR\r\nMETHOD:CANCEL\r\nBEGIN:VEVENT\r\nUID:${uid}\r\nEND:VEVENT\r\nEND:VCALENDAR`;
+  return calendarUpdateThread("cal-cancel-thread", ics);
+}
+
+describe("processEmailThreadsFn — calendar-thread bundling", () => {
+  it("adds icaluid:<uid> to sources when the conversation is a calendar update", async () => {
+    const { host } = makeHost();
+    const saved: NewLinkWithNotes[] = [];
+    (host.tools.integrations.saveLink as ReturnType<typeof vi.fn>).mockImplementation(
+      async (l: NewLinkWithNotes) => {
+        saved.push(l);
+        return "T";
+      }
+    );
+
+    await processEmailThreadsFn(
+      host,
+      [gmailThreadWithIcsUpdate("uid-1")],
+      false,
+      "INBOX"
+    );
+
+    expect(saved[0].sources).toContain("icaluid:uid-1");
+  });
+
+  it("records a cancel-email marker for a cancellation email", async () => {
+    const { host, store } = makeHost();
+
+    await processEmailThreadsFn(
+      host,
+      [gmailThreadWithIcsCancel("uid-1")],
+      false,
+      "INBOX"
+    );
+
+    expect(store.get("cancel-email:uid-1")).toBeTruthy();
+  });
+});

connectors/gmail/src/sync.ts

@@ -46,6 +46,7 @@ import {
   buildForwardMessage,
   buildNewEmailMessage,
   buildReplyMessage,
+  classifyCalendarThread,
   collectAttachments,
   extractBody,
   formatFromHeader,
@@ -1439,6 +1440,21 @@ async function saveTransformedThread(
       syncableId: channelId,
     };
 
+    // Bundle onto the calendar event's thread when this conversation relates
+    // to one (a Plot-sent reply chain, or an ICS update/cancellation).
+    const calBundle = classifyCalendarThread(thread.messages ?? []);
+    if (calBundle) {
+      plotThread.sources = [
+        ...(plotThread.sources ?? []),
+        `icaluid:${calBundle.uid}`,
+      ];
+      if (calBundle.kind === "cancel") {
+        await host.set(`cancel-email:${calBundle.uid}`, {
+          at: new Date().toISOString(),
+        });
+      }
+    }
+
     // Compute classifier facets from the parent message's headers + body.
     const facetParent = thread.messages.find(
       (m) => !m.labelIds?.includes("DRAFT")