diff --git a/CHANGELOG.md b/CHANGELOG.md index 52b0a3654..5cd31e11f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version account, which reads the calendars shared with it or, in Google Workspace, a user's calendars through domain-wide delegation. Calls to Google show in the activity ledger ([Google Calendar](docs/processing.md#email-imap-calendar-feeds-ical-and-google-calendar)). +- **Gmail and Google Workspace as a sensor.** A new kind of email source reads a Gmail or Google Workspace mailbox + through Google's Gmail API (read only) or over IMAP. It signs in as a Google account (its authorized user JSON, as + for Google Calendar), or as a Workspace service account with domain-wide delegation, so nobody has to sign in. + Labels are its folders, and a watch follows Gmail's history: it reads only what arrived, and one that leaves what's + there reads nothing old. Connecting the account from the connection dialog is in progress + ([Gmail and Google Workspace](docs/processing.md#gmail-and-google-workspace)). - **Find a note.** The Notes page has a search box that finds notes by the words in their title, summary or text (the pages of recordings and entities too), with the words around each match marked, and Enter opens the first. A filter shows only Projects, Areas, Resources or Archive, and each note says which notes it's inside. Jump to (⌘K) finds notes diff --git a/README.md b/README.md index e70d5b556..573e33ffb 100644 --- a/README.md +++ b/README.md @@ -80,11 +80,12 @@ Everything below is built and merged. Work that is still in a pull request is li ([Extending the assistant](docs/assistant.md#extending-the-assistant-tools-skills-hooks-and-plugins), [the MCP runner](docs/assistant.md#the-mcp-runner)) - **Bring in everything.** Watched folders on S3, Dropbox, Google Drive, OneDrive, SFTP, SMB, WebDAV or local disks - (a local folder in four clicks); IMAP mail, iCal calendars and Google Calendar; a built-in MQTT broker, syslog and webhook streams; - import webhooks for scanners and phone shortcuts. Upload audio, video, PDFs, Office files, photos, JSON and zip or - tar archives, and, with an Apache Tika server (an opt-in extra), documents nothing else here can read; capture web - pages one at a time, from a link list or a bookmarks file, by API or by asking the assistant, from private networks - you allow in Settings too; and import videos and podcasts by their address (off by default). + (a local folder in four clicks); IMAP mail, Gmail and Google Workspace, iCal calendars and Google Calendar; a built-in + MQTT broker, syslog and webhook streams; import webhooks for scanners and phone shortcuts. Upload audio, video, PDFs, + Office files, photos, JSON and zip or tar archives, and, with an Apache Tika server (an opt-in extra), documents + nothing else here can read; capture web pages one at a time, from a link list or a bookmarks file, by API or by asking + the assistant, from private networks you allow in Settings too; and import videos and podcasts by their address (off + by default). ([Sensors](docs/sensors.md), [processing](docs/processing.md), [Apache Tika](docs/configuration.md#apache-tika), [import webhooks](docs/api.md#import-webhooks)) - **Clip from the browser.** The Lens web clipper for Chrome, Edge, Firefox and Safari turns a page, a selection or a diff --git a/docs/activity.md b/docs/activity.md index 656c308d8..c79f3c679 100644 --- a/docs/activity.md +++ b/docs/activity.md @@ -22,7 +22,8 @@ its namespace, its pipeline and the routine. A request counts for the resources /api/v1/routines/3` is `routine:3`), for what a `POST` made (from the `id` in its reply), and for who sent it. Besides the resources, a row has its kind (`in`, `out` or `run`), what it was (`POST /api/v1/routines/{rid}`, -`model.chat`, `embeddings`, `decision`, `notify.webhook`, `tool.http`, `job.succeeded`, `routine.done`), the model, +`model.chat`, `embeddings`, `decision`, `notify.webhook`, `tool.http`, `google.token`, `gmail.list`, `job.succeeded`, +`routine.done`), the model, tokens in and out, the estimated cost in USD, how long it took, and how it ended (an error's type or HTTP status, never its message). It never holds prompt, reply, asset text or file content. diff --git a/docs/processing.md b/docs/processing.md index ab7c8d7d1..a6d49ca91 100644 --- a/docs/processing.md +++ b/docs/processing.md @@ -289,7 +289,7 @@ A folder scan and a routine run are each claimed first, so several processes doi ## Storage sources Admins add sources in the app (`/api/v1/sources`): S3 or S3-compatible, Dropbox, Google Drive, OneDrive, SFTP, SMB, -WebDAV, or a folder on this machine; or an email account (IMAP), a calendar feed (iCal) or Google Calendar, below. A watched folder maps a path on a source to a namespace, with include/exclude +WebDAV, or a folder on this machine; or an email account (IMAP, or Gmail and Google Workspace), a calendar feed (iCal) or Google Calendar, below. A watched folder maps a path on a source to a namespace, with include/exclude patterns, audio and/or transcripts, a polling interval, how long a file must be unchanged before it is picked up, and whether files already there are imported (backfill). New audio is queued for the full pipeline; new transcripts are imported and analysed. Audio stays where it is: it is copied to a cache for processing and streamed from the source for @@ -335,6 +335,7 @@ importing chosen ones and watching work as above. exists (rules never create one); mail for a namespace deleted since goes to the watch's. Rules apply to messages that arrive after they're saved. `POST /api/v1/watches/routes/preview` shows where the latest messages would go before saving, and a scan's stats count the messages `routed` elsewhere. +- **Gmail and Google Workspace**: see [below](#gmail-and-google-workspace). - **Calendar feed (iCal)**: the calendar's iCal address (`https://` or `webcal://`; a user and password if it asks for one). The address is kept encrypted like a password and never shown again, since a private calendar's address is all it takes to read it. It is fetched the way web pages are captured: public addresses only (and the networks in @@ -369,6 +370,40 @@ importing chosen ones and watching work as above. a Google calendar's secret address in iCal format (Settings › Integrate calendar) works as a calendar feed. - `.eml` and `.ics` files in any source, and uploaded through Import, can be read as text this way too. +### Gmail and Google Workspace + +A Gmail or Google Workspace mailbox (type `gmail`) is read through Google's Gmail API, read only (`gmail.readonly`), +or over IMAP (`via: imap`). For a personal Gmail account, an email (IMAP) connection with an app password works too, +with nothing to set up at Google. A Gmail source signs in one of two ways: + +- **Google account** (`token`): the "authorized user" JSON (`client_id`, `client_secret`, `refresh_token`) of an + OAuth client of your own Google Cloud project, with the Gmail API turned on there, kept encrypted like a password. + `gcloud auth application-default login --client-id-file=client.json --scopes=https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/cloud-platform` + writes one (with `https://mail.google.com/` instead to read over IMAP); an agent can give one it already has. Enter + the account's address as `user` to read over IMAP. Google reviews apps that read Gmail before people outside your + Workspace domain can use them without a warning: an app in testing works for its test users, whose sign-ins Google + ends after seven days. Connecting the account from the connection dialog, with no JSON to make, is in progress. +- **A service account** (Google Workspace). Upload the service account's JSON key and enter the address of the person + whose mail Lens reads; nobody signs in. A Workspace admin lets the account's client id use + `https://www.googleapis.com/auth/gmail.readonly` (or `https://mail.google.com/` to read over IMAP) under Admin + console › Security › API controls › Domain-wide delegation. One source reads one person's mailbox. + +Labels are the folders: the inbox, sent, starred, important, the inbox's categories (Primary, Social, Promotions, +Updates, Forums) and your own labels. A message is a file `