Merge pull request #301 from plotday/fix/gmail-archive-marks-thread-read

fix(gmail): mark a thread read once it leaves every synced label

Author: KrisBraun

connectors/gmail/src/sync.test.ts

@@ -535,3 +535,150 @@ describe("processEmailThreadsFn — calendar-thread bundling", () => {
     expect(store.get("cancel-email:uid-1")).toBeTruthy();
   });
 });
+
+/** A single-message GmailThread carrying `labels`, with a plain-text body. */
+function labelledThread(threadId: string, labels: string[]): GmailThread {
+  const message: GmailMessage = {
+    id: `${threadId}-msg-1`,
+    threadId,
+    labelIds: labels,
+    snippet: "Probably easier to show this with a real example.",
+    historyId: "1",
+    internalDate: "1700000000000",
+    sizeEstimate: 100,
+    payload: part("text/plain", {
+      data: "Probably easier to show this with a real example.",
+      headers: [
+        ["From", "Alice <alice@example.com>"],
+        ["To", "me@example.com"],
+        ["Subject", "New role?"],
+        ["Date", "Wed, 1 Jul 2026 10:00:00 -0700"],
+      ],
+    }),
+  };
+  return { id: threadId, historyId: "1", messages: [message] };
+}
+
+describe("processEmailThreadsFn — archived/trashed in Gmail", () => {
+  const setThreadToDoOf = (host: GmailSyncHost) =>
+    host.tools.integrations.setThreadToDo as ReturnType<typeof vi.fn>;
+  const saveLinkOf = (host: GmailSyncHost) =>
+    host.tools.integrations.saveLink as ReturnType<typeof vi.fn>;
+
+  it("marks a previously-synced thread read once it leaves every enabled channel", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    // We synced this thread while it was still in the inbox.
+    store.set("unread:archived-thread", true);
+
+    // Archived in Gmail: INBOX is gone. IMPORTANT survives but isn't enabled.
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("archived-thread", ["IMPORTANT", "UNREAD"])],
+      false
+    );
+
+    expect(setThreadToDoOf(host)).toHaveBeenCalledWith(
+      "https://mail.google.com/mail/u/0/#inbox/archived-thread",
+      "actor-1",
+      false
+    );
+  });
+
+  it("does not archive the thread in Plot when it is archived in Gmail", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    store.set("unread:archived-thread", true);
+
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("archived-thread", ["IMPORTANT"])],
+      false
+    );
+
+    // Archiving in Gmail must never archive in Plot — the thread stays, it
+    // just stops being unread.
+    expect(saveLinkOf(host)).not.toHaveBeenCalled();
+  });
+
+  it("marks a trashed thread read too", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    store.set("unread:trashed-thread", true);
+
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("trashed-thread", ["TRASH", "UNREAD"])],
+      false
+    );
+
+    expect(setThreadToDoOf(host)).toHaveBeenCalledWith(
+      "https://mail.google.com/mail/u/0/#inbox/trashed-thread",
+      "actor-1",
+      false
+    );
+  });
+
+  it("caches the thread as read so a later re-unread in Gmail still syncs", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    store.set("unread:archived-thread", true);
+
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("archived-thread", ["IMPORTANT", "UNREAD"])],
+      false
+    );
+
+    expect(store.get("unread:archived-thread")).toBe(false);
+  });
+
+  it("ignores a thread it has never synced", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    // No `unread:*` key: mailbox-wide history surfaces threads from labels the
+    // user never chose to sync. Those were never ours to mark read.
+
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("foreign-thread", ["IMPORTANT"])],
+      false
+    );
+
+    expect(setThreadToDoOf(host)).not.toHaveBeenCalled();
+    expect(store.get("unread:foreign-thread")).toBeUndefined();
+  });
+
+  it("leaves a thread still in an enabled channel alone", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    store.set("unread:inbox-thread", true);
+
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("inbox-thread", ["INBOX", "UNREAD"])],
+      false
+    );
+
+    // Still in the inbox — normal sync path, no read stamp.
+    expect(setThreadToDoOf(host)).not.toHaveBeenCalled();
+    expect(saveLinkOf(host)).toHaveBeenCalled();
+  });
+
+  it("does not mark threads read during an initial backfill", async () => {
+    const { host, store } = makeHost();
+    store.set("auth_actor_id", "actor-1");
+    store.set("unread:archived-thread", true);
+
+    // forceChannelId is set during per-channel backfill; a thread that no
+    // longer carries the label must not be read-stamped by a backfill pass.
+    await processEmailThreadsFn(
+      host,
+      [labelledThread("archived-thread", ["IMPORTANT"])],
+      true,
+      "INBOX"
+    );
+
+    expect(setThreadToDoOf(host)).not.toHaveBeenCalled();
+  });
+});

connectors/gmail/src/sync.ts

@@ -379,8 +379,11 @@ export function fnv1aHex(input: string): string {
  *   1. Custom (user-defined) labels — alphabetically.
  *   2. STARRED → IMPORTANT → INBOX → SENT → DRAFT (system labels).
  *
- * Returns null if no enabled channel matches the thread (the thread came in
- * via mailbox-wide history but doesn't belong to any channel the user wants).
+ * Returns null if no enabled channel matches the thread. Note this answers
+ * "does it belong to a channel *now*", and conflates two cases the caller must
+ * separate: a thread that never belonged to one (mailbox-wide history reports
+ * labels the user doesn't sync), and a thread that has just left one (archived
+ * or trashed in Gmail). See {@link markDepartedThreadRead}.
  *
  * Custom labels in Gmail use IDs like `Label_14`. We treat anything not in
  * the system-label list above as "custom", which matches getChannels()'s
@@ -415,6 +418,48 @@ export function pickChannelForThread(
   return null;
 }
 
+/**
+ * Mark a thread read in Plot after it has left every enabled channel — the
+ * user archived it, trashed it, or stripped its last synced label in Gmail.
+ *
+ * Deliberately does not archive the Plot thread: clearing an email out of
+ * Gmail says "I'm done reading this", not "delete my Plot copy". Marking it
+ * read is enough to move it out of Active and into Done, since Active holds
+ * to-dos plus unread threads.
+ *
+ * No-ops for threads we have never synced. `unread:<id>` is written for every
+ * thread we save and is never cleared, so its presence is our record that this
+ * thread is one of ours — including for threads synced long before this code
+ * shipped, which a dedicated marker key would have missed.
+ *
+ * Read state is applied via setThreadToDo(todo=false), whose clear path stamps
+ * `read_at` for this connection's owner. It resolves the thread by source URL,
+ * so no channel is needed — which matters here precisely because the thread no
+ * longer belongs to one. The stamp only fires when `read_at` is NULL, so
+ * repeat history events for the same thread are harmless.
+ */
+async function markDepartedThreadRead(
+  host: GmailSyncHost,
+  thread: GmailThread
+): Promise<void> {
+  const synced = await host.get<boolean>(`unread:${thread.id}`);
+  if (synced == null) return; // Never synced — not ours to touch.
+
+  const actorId = await host.get<ActorId>("auth_actor_id");
+  if (!actorId) return;
+
+  await host.tools.integrations.setThreadToDo(
+    `https://mail.google.com/mail/u/0/#inbox/${thread.id}`,
+    actorId,
+    false
+  );
+
+  // Keep the unread cache honest: Plot now considers this read. If the thread
+  // returns to the inbox unread later, saveTransformedThread sees the
+  // false → true flip and syncs it back to unread.
+  await host.set(`unread:${thread.id}`, false);
+}
+
 /**
  * Merges thread fetches that must be retried into the prior pending set.
  *
@@ -1311,7 +1356,23 @@ export async function processEmailThreadsFn(
 
     const chosen =
       forceChannelId ?? pickChannelForThread(thread, enabledChannels);
-    if (!chosen) continue; // Thread doesn't match any enabled channel.
+    if (!chosen) {
+      // No enabled channel matches. Two very different situations land here,
+      // and telling them apart is the whole point:
+      //
+      //  - We have never synced this thread. Mailbox-wide history reports
+      //    every thread in the account, including ones living only in labels
+      //    the user chose not to sync. Not ours — ignore it.
+      //  - We HAVE synced it and it has since left every enabled channel,
+      //    i.e. the user archived or trashed it in Gmail.
+      //
+      // For the latter we deliberately do NOT archive in Plot: the thread
+      // stays put. But an email the user has cleared out of Gmail shouldn't
+      // keep sitting in Active as unread, so mark it read and let it fall
+      // through to Done.
+      await markDepartedThreadRead(host, thread);
+      continue;
+    }
 
     transformed.push({ thread, plot, channelId: chosen });
     for (const c of plot.accessContacts ?? []) {