fix(gmail): no-op thread-state write-backs when Google auth is missing

connectors/gmail/src/gmail.test.ts

@@ -562,3 +562,98 @@ describe("recoverMailboxDelivery — durable recovery on upgrade", () => {
     expect(spies.requeueInitialSync).not.toHaveBeenCalled();
   });
 });
+
+describe("thread-state write-back when the connection has no auth token", () => {
+  // A Gmail connection whose OAuth has lapsed/been revoked resolves no token
+  // for its channel. The thread-state write-backs (to-do star, read-state)
+  // are best-effort label syncs — the user's change already lives in Plot —
+  // so they must degrade to a silent no-op rather than throwing. Throwing
+  // pages error tracking on every to-do/read toggle for a re-auth-needed
+  // connection (PostHog issue 019ed581: "No Google authentication token
+  // available", 673 occurrences / 296 users).
+  function makeGmail(token: { token: string; scopes: string[] } | null): {
+    gmail: Gmail;
+    integrationsGet: ReturnType<typeof vi.fn>;
+  } {
+    const storeMap = new Map<string, unknown>([["enabled_channels", ["INBOX"]]]);
+    const store = {
+      get: vi.fn(async (key: string) =>
+        storeMap.has(key) ? storeMap.get(key) : null
+      ),
+      set: vi.fn(async (key: string, value: unknown) => {
+        storeMap.set(key, value);
+      }),
+      clear: vi.fn(async (key: string) => {
+        storeMap.delete(key);
+      }),
+      list: vi.fn(async (prefix: string) =>
+        [...storeMap.keys()].filter((k) => k.startsWith(prefix))
+      ),
+    };
+    const integrationsGet = vi.fn().mockResolvedValue(token);
+    const tools = {
+      store,
+      integrations: { get: integrationsGet },
+      network: {},
+      files: {},
+    };
+    const gmail = new Gmail(
+      "twist-instance-1" as never,
+      { getTools: () => tools } as never
+    );
+    return { gmail, integrationsGet };
+  }
+
+  const thread = {
+    id: "thread-1",
+    meta: { threadId: "gmail-thread-1", channelId: "INBOX" },
+  } as never;
+  const actor = { id: "actor-1" } as never;
+
+  it("onThreadToDo resolves without throwing and never calls Gmail", async () => {
+    const { gmail, integrationsGet } = makeGmail(null);
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("{}"));
+
+    await expect(
+      gmail.onThreadToDo(thread, actor, true, {})
+    ).resolves.toBeUndefined();
+
+    expect(integrationsGet).toHaveBeenCalledWith("INBOX");
+    expect(fetchSpy).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+
+  it("onThreadRead resolves without throwing and never calls Gmail", async () => {
+    const { gmail, integrationsGet } = makeGmail(null);
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("{}"));
+
+    await expect(
+      gmail.onThreadRead(thread, actor, false)
+    ).resolves.toBeUndefined();
+
+    expect(integrationsGet).toHaveBeenCalledWith("INBOX");
+    expect(fetchSpy).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+
+  it("onThreadToDo still writes the STARRED/INBOX labels when a token is present", async () => {
+    const { gmail } = makeGmail({ token: "tok", scopes: [] });
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockResolvedValue(new Response("{}"));
+
+    await gmail.onThreadToDo(thread, actor, true, {});
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/threads/gmail-thread-1/modify");
+    expect(JSON.parse((init as RequestInit).body as string)).toEqual({
+      addLabelIds: ["STARRED", "INBOX"],
+    });
+    fetchSpy.mockRestore();
+  });
+});

connectors/gmail/src/sync.ts

@@ -376,6 +376,26 @@ export async function getApiFn(
   return new GmailApi(token.token);
 }
 
+/**
+ * Like {@link getApiFn}, but returns `null` instead of throwing when the
+ * channel resolves no auth token (lapsed / revoked Google OAuth).
+ *
+ * Use this in best-effort write-backs (to-do star, read-state) where a
+ * re-auth-needed connection should degrade to a silent no-op: the user's
+ * change already lives in Plot, and the connection's re-auth need is already
+ * surfaced in the connections UI. Throwing there only pages error tracking on
+ * every toggle. Sync paths that must surface a missing token still use the
+ * throwing {@link getApiFn}.
+ */
+export async function tryGetApiFn(
+  host: GmailSyncHost,
+  channelId: string
+): Promise<GmailApi | null> {
+  const token = await host.tools.integrations.get(channelId);
+  if (!token) return null;
+  return new GmailApi(token.token);
+}
+
 /**
  * Returns a Gmail API client authed with any enabled channel's token.
  * Auth is per-Google-account (not per-label), so any enabled channelId
@@ -1515,7 +1535,10 @@ export async function onThreadReadFn(
   const threadId = meta.threadId as string;
   if (!threadId) return;
 
-  const api = await getApiFn(host, channelId);
+  // Best-effort: if the connection lost its Google auth, skip the label
+  // write-back instead of throwing (read-state already lives in Plot).
+  const api = await tryGetApiFn(host, channelId);
+  if (!api) return;
 
   // Cache the new unread state before modifying Gmail to prevent echo loops
   await host.set(`unread:${threadId}`, unread);
@@ -1545,11 +1568,17 @@ export async function onThreadToDoFn(
     return;
   }
 
+  // Best-effort: if the connection lost its Google auth, skip the star
+  // write-back instead of throwing (the to-do change already lives in Plot).
+  // Resolved before the local-state mutation below so a no-token call is a
+  // complete no-op and leaves no divergent `starred:` marker.
+  const api = await tryGetApiFn(host, channelId);
+  if (!api) return;
+
   // Update local state BEFORE calling Gmail, so the webhook fired by our
   // own write sees isStarred === wasStarred and doesn't re-propagate.
   await host.set(`starred:${threadId}`, todo);
 
-  const api = await getApiFn(host, channelId);
   if (todo) {
     // Add STARRED, and re-add INBOX so an archived email returns to the
     // inbox when the user adds it to their agenda in Plot.