Implement Gmail activity tracking with optional metadata extraction

ActivityWatch is used in timesheet tracking, and knowing just "reading" or "composing" email info is not very useful on its own. Extracting involved email metadata (Sender, Recipients, Subject) helps determine the context of the activity relative to project models and workflows in the used software.

A new setting has been added to allow users to enable or disable Gmail tracking.

Also added a build.sh script to simplify the build and test process for Chrome and Firefox.

ui related changes: ActivityWatch/aw-webui#796

Author: RaoufGhrissi

build.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+make build-chrome && \
+mkdir -p artifacts/chrome && \
+unzip -o artifacts/chrome.zip -d artifacts/chrome
+
+make build-firefox && \
+mkdir -p artifacts/firefox && \
+unzip -o artifacts/firefox.zip -d artifacts/firefox

src/background/heartbeat.ts

@@ -3,9 +3,26 @@ import { getActiveWindowTab, getTab, getTabs } from './helpers'
 import config from '../config'
 import { AWClient, IEvent } from 'aw-client'
 import { getBucketId, sendHeartbeat } from './client'
-import { getEnabled, getHeartbeatData, setHeartbeatData } from '../storage'
+import { getEnabled, getHeartbeatData, setHeartbeatData, getGmailEnabled } from '../storage'
 import deepEqual from 'deep-equal'
 
+export function setupMessageListener(client: AWClient) {
+  browser.runtime.onMessage.addListener(
+    async (message: any) => {
+      const enabled = await getEnabled()
+      const gmailEnabled = await getGmailEnabled()
+      if (!enabled || !gmailEnabled) return
+
+      if (message.type === 'AW_GMAIL_HEARTBEAT') {
+        const bucketId = await getBucketId()
+        await sendHeartbeat(client, bucketId, new Date(), message.data, config.heartbeat.intervalInSeconds + 20).catch((err: unknown) => {
+          console.error('[Background] Failed to send Gmail heartbeat:', err);
+        })
+      }
+    },
+  )
+}
+
 async function heartbeat(
   client: AWClient,
   tab: browser.Tabs.Tab | undefined,
@@ -27,6 +44,11 @@ async function heartbeat(
     return
   }
 
+  const gmailEnabled = await getGmailEnabled()
+  if (gmailEnabled && tab.url.includes('mail.google.com')) {
+    return
+  }
+
   const now = new Date()
   const data: IEvent['data'] = {
     url: tab.url,

src/background/main.ts

@@ -4,6 +4,7 @@ import {
   heartbeatAlarmListener,
   sendInitialHeartbeat,
   tabActivatedListener,
+  setupMessageListener,
 } from './heartbeat'
 import { getClient, detectHostname } from './client'
 import {
@@ -15,6 +16,7 @@ import {
   setHostname,
   waitForEnabled,
 } from '../storage'
+import { AWClient } from 'aw-client'
 
 async function getIsConsentRequired() {
   if (!config.requireConsent) return false
@@ -24,7 +26,7 @@ async function getIsConsentRequired() {
     .catch(() => true)
 }
 
-async function autodetectHostname() {
+async function autodetectHostname(client: AWClient) {
   const hostname = await getHostname()
   if (hostname === undefined) {
     const detectedHostname = await detectHostname(client)
@@ -57,13 +59,17 @@ browser.runtime.onInstalled.addListener(async () => {
     })
   }
 
-  await autodetectHostname()
+  await autodetectHostname(client)
 })
 
 console.debug('Creating alarms and tab listeners')
 browser.alarms.create(config.heartbeat.alarmName, {
   periodInMinutes: Math.floor(config.heartbeat.intervalInSeconds / 60),
 })
+
+// Set up Gmail message listener (other watchers will be added later)
+setupMessageListener(client)
+
 browser.alarms.onAlarm.addListener(heartbeatAlarmListener(client))
 browser.tabs.onActivated.addListener(tabActivatedListener(client))
 

src/content/gmail.ts

@@ -0,0 +1,123 @@
+import browser from 'webextension-polyfill'
+
+
+function getComposeMetadata(form: HTMLElement) {
+  const getRecipients = (name: string) =>
+    Array.from(
+      form.querySelectorAll(`div[name="${name}"] [data-hovercard-id]`),
+    ).map((el) => el.getAttribute('data-hovercard-id'))
+      .filter(Boolean) as string[]
+
+  return {
+    subject: (form.querySelector('input[name="subjectbox"]') as HTMLInputElement)?.value || '',
+    to: getRecipients('to'),
+    cc: getRecipients('cc'),
+    bcc: getRecipients('bcc'),
+  }
+}
+
+let lastData: string | null = null
+let lastSentTime = 0
+
+function sendGmailHeartbeat() {
+  if (document.visibilityState === 'hidden') {
+    return
+  }
+
+  const hash = window.location.hash
+  const form = document.querySelector('div[role="dialog"] form') as HTMLElement | null
+
+  let activity = 'reading_inbox'
+  let meta: any = {}
+
+  if (form) {
+    // for simplity in MVP:
+    // - if many emails forms are open, we only track the first one
+    // - if subject, to, cc, bcc changes when composing the email, we send a new heartbeat
+    activity = 'composing_email'
+    meta = getComposeMetadata(form)
+  } else if (
+    hash.includes('inbox/') ||
+    hash.includes('sent/') ||
+    hash.includes('all/')
+  ) {
+    /**
+     * NOTE on Fragility: The selectors below (span.gD, .gE, h2.hP) are internal 
+     * Gmail class names. These are not part of a stable API and may change 
+     * during Gmail frontend updates. High-fidelity tracking may require 
+     * maintenance if these selectors break.
+     */
+    const fromEl = document.querySelector('span.gD')
+    const from =
+      fromEl?.getAttribute('email') ||
+      fromEl?.getAttribute('data-hovercard-id') ||
+      (fromEl as HTMLElement)?.innerText ||
+      ''
+    const to = Array.from(
+      document.querySelectorAll('.gE [email], .gE [data-hovercard-id]'),
+    )
+      .map(
+        (el) => el.getAttribute('email') || el.getAttribute('data-hovercard-id'),
+      )
+      .filter((e) => e && e !== from) as string[]
+
+    activity = 'reading_email'
+    meta = {
+      subject: (document.querySelector('h2.hP') as HTMLElement)?.innerText || '',
+      from,
+      to,
+    }
+  }
+
+  const data = {
+    gmail_activity: activity,
+    ...meta,
+    url: window.location.href,
+    title: document.title,
+  }
+
+  const dataString = JSON.stringify(data)
+  const now = Date.now()
+  if (lastData === dataString && now - lastSentTime < 30000) {
+    return
+  }
+  lastData = dataString
+  lastSentTime = now
+
+  browser.runtime.sendMessage({ type: 'AW_GMAIL_HEARTBEAT', data }).catch(() => {})
+}
+
+let intervalId: ReturnType<typeof setInterval> | null = null
+
+function startTracking() {
+  if (intervalId !== null) {
+    return
+  }
+  sendGmailHeartbeat()
+  sendGmailHeartbeat()
+  intervalId = setInterval(sendGmailHeartbeat, 1000)
+}
+
+function stopTracking() {
+  if (intervalId === null) {
+    return
+  }
+  clearInterval(intervalId)
+  intervalId = null
+}
+
+browser.storage.local.get('gmailEnabled').then((settings) => {
+  if (settings.gmailEnabled) {
+    startTracking()
+  }
+})
+
+browser.storage.onChanged.addListener((changes) => {
+  if ('gmailEnabled' in changes) {
+    if (changes.gmailEnabled.newValue) {
+      startTracking()
+    } else {
+      stopTracking()
+    }
+  }
+})

src/manifest.json

@@ -64,5 +64,15 @@
         "gecko": {
             "id": "{ef87d84c-2127-493f-b952-5b4e744245bc}"
         }
-    }
+    },
+    "content_scripts": [
+        {
+            "matches": [
+                "*://mail.google.com/*"
+            ],
+            "js": [
+                "src/content/gmail.ts"
+            ]
+        }
+    ]
 }

src/settings/index.html

@@ -51,6 +51,13 @@
         />
       </div>
 
+      <div>
+        <label for="gmailEnabled">
+          <strong>Extract Gmail details:</strong>
+        </label>
+        <input type="checkbox" id="gmailEnabled" name="gmailEnabled" />
+      </div>
+
       <div>
         <button type="submit">Save</button>
       </div>

src/settings/main.ts

@@ -4,6 +4,8 @@ import {
   setBrowserName,
   getHostname,
   setHostname,
+  getGmailEnabled,
+  setGmailEnabled,
 } from '../storage'
 import { detectBrowser } from '../background/helpers'
 
@@ -34,6 +36,10 @@ async function saveOptions(e: SubmitEvent): Promise<void> {
 
   const hostname = hostnameInput.value
 
+  const gmailEnabledCheckbox =
+    document.querySelector<HTMLInputElement>('#gmailEnabled')
+  const gmailEnabled = gmailEnabledCheckbox?.checked || false
+
   const form = e.target as HTMLFormElement
   const button = form.querySelector<HTMLButtonElement>('button')
   if (!button) return
@@ -44,6 +50,7 @@ async function saveOptions(e: SubmitEvent): Promise<void> {
   try {
     await setBrowserName(selectedBrowser)
     await setHostname(hostname)
+    await setGmailEnabled(gmailEnabled)
     await reloadExtension()
     button.textContent = 'Save'
     button.classList.add('accept')
@@ -95,6 +102,13 @@ async function restoreOptions(): Promise<void> {
     if (hostname !== undefined) {
       hostnameInput.value = hostname
     }
+
+    const gmailEnabled = await getGmailEnabled()
+    const gmailEnabledCheckbox =
+      document.querySelector<HTMLInputElement>('#gmailEnabled')
+    if (gmailEnabledCheckbox) {
+      gmailEnabledCheckbox.checked = gmailEnabled
+    }
   } catch (error) {
     console.error('Failed to restore options:', error)
   }

src/storage.ts

@@ -101,3 +101,10 @@ export const getHostname = (): Promise<Hostname | undefined> =>
     .then((data: StorageData) => data.hostname as string | undefined)
 export const setHostname = (hostname: Hostname) =>
   browser.storage.local.set({ hostname })
+
+type GmailEnabled = boolean
+export const getGmailEnabled = (): Promise<GmailEnabled> =>
+  browser.storage.local.get('gmailEnabled').then((_) => Boolean(_.gmailEnabled))
+export const setGmailEnabled = (gmailEnabled: GmailEnabled) =>
+  browser.storage.local.set({ gmailEnabled })
+