feat(gmail): classify a conversation's calendar-event relationship for bundling

Adds classifyCalendarThread, a pure helper that scans a Gmail thread's
messages and decides whether it relates to a calendar event: a reply
chain (our own X-Plot-Event-UID header), an ICS update (METHOD:REQUEST,
SEQUENCE>0), or a cancellation (METHOD:CANCEL). Bare invites and RSVPs
are intentionally skipped.

Author: KrisBraun

connectors/gmail/src/gmail-api.test.ts

@@ -4,6 +4,7 @@ import {
   buildForwardMessage,
   buildNewEmailMessage,
   buildReplyMessage,
+  classifyCalendarThread,
   formatFromHeader,
   stripQuotedReply,
   transformGmailThread,
@@ -550,3 +551,72 @@ describe("buildForwardMessage", () => {
     expect(raw).not.toContain("Bcc:");
   });
 });
+
+describe("classifyCalendarThread", () => {
+  const icsUpdate =
+    "BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nBEGIN:VEVENT\r\nUID:uid-1\r\nSEQUENCE:2\r\nEND:VEVENT\r\nEND:VCALENDAR";
+  const icsInvite =
+    "BEGIN:VCALENDAR\r\nMETHOD:REQUEST\r\nBEGIN:VEVENT\r\nUID:uid-1\r\nSEQUENCE:0\r\nEND:VEVENT\r\nEND:VCALENDAR";
+  const icsCancel =
+    "BEGIN:VCALENDAR\r\nMETHOD:CANCEL\r\nBEGIN:VEVENT\r\nUID:uid-1\r\nEND:VEVENT\r\nEND:VCALENDAR";
+  const icsReply =
+    "BEGIN:VCALENDAR\r\nMETHOD:REPLY\r\nBEGIN:VEVENT\r\nUID:uid-1\r\nEND:VEVENT\r\nEND:VCALENDAR";
+
+  /** Minimal well-typed GmailMessage wrapping the given top-level payload. */
+  function baseMessage(payload: GmailMessagePart): GmailMessage {
+    return {
+      id: "m1",
+      threadId: "t1",
+      labelIds: ["INBOX"],
+      snippet: "snippet",
+      historyId: "1",
+      internalDate: "1700000000000",
+      sizeEstimate: 500,
+      payload,
+    };
+  }
+
+  const msgWithIcs = (ics: string): GmailMessage =>
+    baseMessage(
+      part("multipart/mixed", {
+        parts: [part("text/calendar", { data: ics })],
+      })
+    );
+
+  const msgWithHeader = (uid: string): GmailMessage =>
+    baseMessage(
+      part("text/plain", {
+        data: "reply body",
+        headers: [["X-Plot-Event-UID", uid]],
+      })
+    );
+
+  it("bundles an update (METHOD:REQUEST SEQUENCE>0)", () => {
+    expect(classifyCalendarThread([msgWithIcs(icsUpdate)])).toEqual({
+      uid: "uid-1",
+      kind: "update",
+    });
+  });
+
+  it("bundles a cancellation (METHOD:CANCEL)", () => {
+    expect(classifyCalendarThread([msgWithIcs(icsCancel)])).toEqual({
+      uid: "uid-1",
+      kind: "cancel",
+    });
+  });
+
+  it("bundles a reply chain (X-Plot-Event-UID header)", () => {
+    expect(classifyCalendarThread([msgWithHeader("uid-9")])).toEqual({
+      uid: "uid-9",
+      kind: "reply",
+    });
+  });
+
+  it("skips a bare invite (SEQUENCE 0)", () => {
+    expect(classifyCalendarThread([msgWithIcs(icsInvite)])).toBeNull();
+  });
+
+  it("skips an RSVP (METHOD:REPLY)", () => {
+    expect(classifyCalendarThread([msgWithIcs(icsReply)])).toBeNull();
+  });
+});

connectors/gmail/src/gmail-api.ts

@@ -672,6 +672,45 @@ function decodeBase64Url(data: string): string {
   return new TextDecoder("utf-8").decode(bytes);
 }
 
+/** Unfold RFC 5545 lines (CRLF + leading space/tab is a continuation) and read a property. */
+function icsProp(ics: string, name: string): string | null {
+  const unfolded = ics.replace(/\r?\n[ \t]/g, "");
+  const re = new RegExp(`^${name}(?:;[^:\\r\\n]*)?:(.*)$`, "im");
+  const m = unfolded.match(re);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Classify a Gmail conversation's relationship to a calendar event for bundling.
+ * Two signals: our own `X-Plot-Event-UID` header (a Plot-sent reply chain), or a
+ * `text/calendar` part (invitation/update/cancellation/RSVP). Only updates,
+ * cancellations, and reply chains bundle; bare invites and RSVPs are skipped.
+ */
+export function classifyCalendarThread(
+  messages: GmailMessage[]
+): { uid: string; kind: "reply" | "update" | "cancel" } | null {
+  // 1. Reply chain — our header on any message.
+  for (const m of messages) {
+    const uid = getHeader(m, "X-Plot-Event-UID");
+    if (uid) return { uid, kind: "reply" };
+  }
+  // 2. Calendar-system ICS.
+  for (const m of messages) {
+    const ics = findPartContent(m.payload, "text/calendar");
+    if (!ics) continue;
+    const uid = icsProp(ics, "UID");
+    if (!uid) continue;
+    const method = (icsProp(ics, "METHOD") ?? "").toUpperCase();
+    if (method === "CANCEL") return { uid, kind: "cancel" };
+    if (method === "REQUEST") {
+      const seq = parseInt(icsProp(ics, "SEQUENCE") ?? "0", 10);
+      if (seq > 0) return { uid, kind: "update" };
+    }
+    // METHOD:REPLY, or REQUEST/SEQUENCE 0 → skip.
+  }
+  return null;
+}
+
 /**
  * Locates the start of an Outlook-style "From: / Sent: / To: / Subject:"
  * reply header even when the field labels are not wrapped in `<b>` or