AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""A direct Gmail client for one person's own mailbox (Act as me).
The Executive's own mailbox is reached through the MCP gateway, where the
model can call any Gmail tool by name. A mailbox someone lent the Executive
must never be reachable that way, so this client talks to the Gmail REST API
itself and is never registered with the gateway: only typed handlers
(``orchestrator.delegation_tools``, the voice learner, the inbox watcher and
the reply cards) call it.
**Credential.** One file per person in ``DELEGATION_GOOGLE_CREDENTIALS_DIR``,
named from a hash of the address and written by
``scripts/connect-own-gmail.py``: ``{"version": 1, "email": ..., "authorized_user":
{refresh_token, client_id, client_secret, token_uri}}``. It is never in
``WORKSPACE_MCP_CREDENTIALS_DIR`` — workspace-mcp picks a credential there by
address, which would hand the model this mailbox. Scopes: ``gmail.readonly``
and ``gmail.compose``, and a calendar scope when they connected with
``--calendar`` for Read my calendar (``delegation.calendar``; ``list_events``
refuses with ``CalendarNotGranted`` without it): ``calendar.events`` now,
which also lets it answer a meeting invite as them (``answer_invite``,
``delegation.invites``); a sign-in made with ``calendar.readonly`` before
keeps reading, and ``answer_invite`` refuses with ``CalendarWriteNotGranted``.
**One way to send.** It reads mail and saves or deletes drafts. The only
send is ``send_draft``: an existing draft, by its id, exactly as it is in
Gmail (the request body is the id and nothing else). Only
``delegation.reply_send`` calls it, after the person tapped Send on that
draft's card; unit tests pin the public methods, the one send endpoint and
that call site.
**Outlook too.** A person may connect an Outlook mailbox instead
(``scripts/connect-own-outlook.py``, which writes ``"provider": "microsoft"``
into the same file). ``gmail_for`` then hands back
``delegation.outlook.DelegateOutlook``, which keeps this client's methods,
return types and errors, so every caller works with either mailbox.
**Always checked.** ``gmail_status`` asks Google whose mailbox the token opens
and compares it with the person's People email on every use — a roster email
can change, and a client slot swaps the roster — and refuses the Executive's
own address outright (a "shared mailbox" would make everything the Executive
writes look like the person's).
"""
from __future__ import annotations
import asyncio
import base64
import hashlib
import html
import json
import logging
import re
import time
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime
from email.message import EmailMessage, Message
from email.utils import formataddr, getaddresses
from pathlib import Path
from typing import Any, Literal
from urllib.parse import quote
import httpx
from openexecutive.utils.html_tags import strip_tags
logger = logging.getLogger(__name__)
GMAIL_BASE = "https://gmail.googleapis.com/gmail/v1/users/me"
DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token"
SCOPE_READONLY = "https://www.googleapis.com/auth/gmail.readonly"
SCOPE_COMPOSE = "https://www.googleapis.com/auth/gmail.compose"
SCOPES: tuple[str, ...] = (SCOPE_READONLY, SCOPE_COMPOSE)
# Read my calendar (delegation.calendar): optional, so a mail-only sign-in still works.
SCOPE_CALENDAR = "https://www.googleapis.com/auth/calendar.readonly"
# What --calendar asks for now: reads, and answers a meeting invite as them
# (delegation.invites). Either scope reads; only this one (or the full
# calendar scope) answers.
SCOPE_CALENDAR_EVENTS = "https://www.googleapis.com/auth/calendar.events"
_SCOPE_CALENDAR_FULL = "https://www.googleapis.com/auth/calendar"
CALENDAR_READ_SCOPES = frozenset({SCOPE_CALENDAR, SCOPE_CALENDAR_EVENTS, _SCOPE_CALENDAR_FULL})
CALENDAR_WRITE_SCOPES = frozenset({SCOPE_CALENDAR_EVENTS, _SCOPE_CALENDAR_FULL})
CALENDAR_BASE = "https://www.googleapis.com/calendar/v3/calendars/primary"
CREDENTIAL_VERSION = 1
PROVIDER = "google"
# Marks a draft this package wrote. Best-effort only: Gmail may rebuild a
# draft when it is sent from its own UI.
GHOSTWRITTEN_HEADER = "X-OE-Ghostwritten"
GmailStatus = Literal[
"connected",
"not_configured",
"needs_reconnect",
"mismatch",
"no_email",
"shared_mailbox",
"error",
]
# What each status tells the person, in the tool result and on Settings.
# A status that blocks using the mailbox → the 409 code a caller gets.
BLOCKING_CODES: dict[str, str] = {
"not_configured": "gmail_not_connected",
"needs_reconnect": "gmail_needs_reconnect",
"mismatch": "gmail_mismatch",
"no_email": "no_email",
"shared_mailbox": "shared_mailbox",
"error": "gmail_error",
}
STATUS_MESSAGES: dict[str, str] = {
"connected": "Connected.",
"not_configured": (
"Your mailbox isn't connected. Run scripts/connect-own-gmail.py (Gmail) or "
"scripts/connect-own-outlook.py (Outlook) as yourself (Delegate → Act as me "
"shows how)."
),
"needs_reconnect": (
"Your mailbox no longer accepts the saved sign-in. Connect it again with "
"scripts/connect-own-gmail.py or scripts/connect-own-outlook.py."
),
"mismatch": (
"The connected mailbox isn't the address on your People entry. Connect that "
"account, or correct your email on the People page."
),
"no_email": "Your People entry has no email address. Add it on the People page first.",
"shared_mailbox": (
"Your address is the Executive's own mailbox, so it can't write as you from "
"it. Give the Executive a Google account of its own first."
),
"error": "Couldn't reach your mailbox just now. Try again in a moment.",
}
# Gmail ids are short hex strings; anything else never reaches a URL path.
_ID_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")
# Google Calendar event ids: base32hex, with an instance's "_" suffix.
_EVENT_ID_RE = re.compile(r"[A-Za-z0-9_]{1,1024}")
# A forward's attached files, at most (Gmail's own message limit is 25 MB).
FORWARD_MAX_FILES = 10
FORWARD_MAX_BYTES = 20 * 1024 * 1024
# Gmail's attachment ids are far longer than its message ids.
_ATTACHMENT_ID_RE = re.compile(r"[A-Za-z0-9_-]{1,4096}")
_EMAIL_RE = re.compile(r"[\w.+\-]+@[\w\-]+(?:\.[\w\-]+)+")
_TOKEN_URI_RE = re.compile(r"^https://oauth2\.googleapis\.com/")
_MAX_HEADER = 900
_TOKEN_SLACK_SECONDS = 60
_FETCH_CONCURRENCY = 5
# Access tokens by (address, refresh token) — never written anywhere.
_TOKENS: dict[str, tuple[str, float]] = {}
# The scopes Google said each of those tokens carries ("" when it didn't say).
_GRANTED: dict[str, str] = {}
# Events one calendar read returns, at most.
MAX_EVENTS = 100
class GmailError(Exception):
"""A Gmail call failed (network, 5xx, an unexpected response).
``maybe_done`` is True when the request may have reached Google and been
carried out anyway (a timeout after sending, a 5xx, an unreadable
success): for a send, not knowing is not the same as not sent."""
def __init__(self, message: str = "", *, maybe_done: bool = False) -> None:
super().__init__(message)
self.maybe_done = maybe_done
class GmailNotConfigured(GmailError):
"""No credential for this address."""
class GmailRateLimited(GmailError):
"""Gmail asked us to slow down (429, or a quota 403): back off, don't
reconnect."""
class GmailNotFound(GmailError):
"""No such message, thread or draft (404). For a draft: sent or deleted."""
class DraftChanged(GmailError):
"""A draft can't be rewritten from the card: it changed in the mailbox
since it was last read (``reason`` "changed"), or it holds more than plain
text, such as files ("not_plain")."""
def __init__(self, reason: str) -> None:
super().__init__(f"draft {reason}")
self.reason = reason
class CalendarNotGranted(GmailError):
"""Their saved sign-in doesn't let the Executive read their calendar:
they connected without it (``--calendar``), or took it back."""
class CalendarWriteNotGranted(GmailError):
"""Their saved sign-in reads their calendar but can't answer an invite:
it was made with read-only access (``calendar.readonly``,
``Calendars.Read``). Connecting again with ``--calendar`` adds it."""
class GmailChanged(GmailError):
"""The item changed since it was read (an ``If-Match`` didn't match)."""
class GmailAuthError(GmailError):
"""Google refused the credential: revoked, expired, or missing a scope."""
@dataclass(frozen=True)
class GmailCredential:
email: str
refresh_token: str
client_id: str
client_secret: str
token_uri: str = DEFAULT_TOKEN_URI
@dataclass(frozen=True)
class CalendarEvent:
"""One event on someone's own calendar, as Read my calendar shows it.
``start`` / ``end`` are ISO 8601 (a date alone for an all-day event)."""
id: str
title: str
start: str
end: str
all_day: bool = False
location: str = ""
organizer: str = ""
attendees: tuple[str, ...] = ()
# Their own answer: accepted, declined, tentative, needs_action, organizer.
response: str = ""
_ATTENDEES_MAX = 25
def _google_who(entry: Any) -> str:
if not isinstance(entry, dict):
return ""
name = clean_header(str(entry.get("displayName") or ""))
address = normalize_email(str(entry.get("email") or ""))
return f"{name} <{address}>" if name and address else (name or address)
def _google_when(value: Any) -> tuple[str, bool]:
if not isinstance(value, dict):
return "", False
if value.get("dateTime"):
return str(value["dateTime"]), False
return str(value.get("date") or ""), True
def parse_google_event(raw: dict[str, Any]) -> CalendarEvent | None:
"""A Google Calendar event, or None for one that isn't on their day
(cancelled, or a working-location marker)."""
if raw.get("status") == "cancelled" or raw.get("eventType") == "workingLocation":
return None
start, all_day = _google_when(raw.get("start"))
end, _ = _google_when(raw.get("end"))
if not start:
return None
attendees = [a for a in raw.get("attendees") or [] if isinstance(a, dict)]
own = next((a for a in attendees if a.get("self")), None)
organizer_raw = raw.get("organizer")
organizer: dict[str, Any] = organizer_raw if isinstance(organizer_raw, dict) else {}
if organizer.get("self"):
response = "organizer"
else:
response = {
"accepted": "accepted", "declined": "declined", "tentative": "tentative", "needsAction": "needs_action",
}.get(str((own or {}).get("responseStatus") or ""), "")
return CalendarEvent(
id=str(raw.get("id") or ""),
title=clean_header(str(raw.get("summary") or "")) or "(no title)",
start=start,
end=end,
all_day=all_day,
location=clean_header(str(raw.get("location") or "")),
organizer=_google_who(organizer),
attendees=tuple(w for w in (_google_who(a) for a in attendees[:_ATTENDEES_MAX] if not a.get("self")) if w),
response=response,
)
@dataclass
class MailAttachment:
"""A file attached to a message: its place among the message's
attachments (1-based), and what the mailbox says it is. The provider's
own id is looked up afresh when it is read (Gmail's changes per fetch)."""
index: int
name: str
mime_type: str = ""
size: int = 0
@dataclass
class MailMessage:
id: str
thread_id: str
from_addr: str = ""
from_name: str = ""
to: list[str] = field(default_factory=list)
cc: list[str] = field(default_factory=list)
reply_to: str = ""
subject: str = ""
date: str = ""
message_id_header: str = ""
references: str = ""
labels: list[str] = field(default_factory=list)
text: str = ""
mailing_list: bool = False
auto_generated: bool = False
ghostwritten: bool = False
bcc: list[str] = field(default_factory=list)
# When Gmail received it (internalDate, ISO in UTC), not the Date header
# the sender wrote; "" when unknown.
received_at: str = ""
# Bulk or auto-reply mail (by its headers), a delivery report (a
# bounce), a calendar invite: nobody wrote it for this reader.
bulk: bool = False
delivery_report: bool = False
calendar_invite: bool = False
# Gmail's own Authentication-Results found From's domain authenticated
# (dmarc=pass): who it says it is from is who it is from.
sender_authenticated: bool = False
# Files attached to it. Gmail lists them with the message; Outlook only
# says whether there are any (``has_attachments``) until asked
# (``list_attachments``).
attachments: list[MailAttachment] = field(default_factory=list)
has_attachments: bool = False
# The display name each To / Cc address was written with, as the
# sender's own mail app put it ("" for none). Names a contact the
# person writes to (``people.contact_keeper``).
names: dict[str, str] = field(default_factory=dict)
# A calendar invite's own iCalendar method (REQUEST, CANCEL, REPLY, ...)
# and event UID, from its text/calendar part ("" when it has none, or
# it is only attached as a file). Outlook leaves them empty: Graph
# names the event itself (``find_invite``).
invite_method: str = ""
invite_uid: str = ""
@dataclass
class MailThread:
id: str
messages: list[MailMessage]
@dataclass
class ThreadSummary:
id: str
subject: str
sender: str
date: str
# The mail service found the sender's domain authenticated
# (``MailMessage.sender_authenticated``); False when it can't tell.
sender_authenticated: bool = False
# The headers a search reads of each thread's newest message: what it lists,
# and what proving its sender takes (``headers_authenticated``, which a list's
# own headers make fail).
_SUMMARY_HEADERS = (
"Subject", "From", "Date", "Authentication-Results", "List-Id", "X-Google-Group-Id", "Mailing-List",
)
@dataclass
class ForwardOf:
"""The message a draft forwards (``DraftSpec.forward``): the provider's
id for it, and the header block and text Gmail quotes under the note.
Outlook forwards by id (``createForward``), original and files included;
Gmail's draft quotes ``header`` and ``text`` and attaches the message's
files itself (``DelegateGmail.create_draft``)."""
message_id: str
header: str
text: str
@dataclass
class DraftSpec:
to: list[str]
subject: str
body: str
cc: list[str] = field(default_factory=list)
thread_id: str | None = None
in_reply_to: str | None = None
references: str | None = None
from_name: str = ""
# One of the person's own send-as addresses to write from (the one the
# mail being answered went to); None is their primary address.
from_addr: str | None = None
# A forward instead of a reply or a new email: the body is the note above it.
forward: ForwardOf | None = None
# Files to attach (name, MIME type, bytes): a forward's, on Gmail.
attachments: list[tuple[str, str, bytes]] = field(default_factory=list)
@dataclass
class CreatedDraft:
draft_id: str
message_id: str
thread_id: str
# A forward's files that were left off (too many or too large).
skipped_attachments: int = 0
@dataclass
class SentMessage:
"""What ``send_draft`` sent: the new message's id and its thread."""
id: str
thread_id: str
@dataclass
class DraftInfo:
"""A draft as Gmail holds it now: its id and its current message (which
gets a new id each time the draft is edited)."""
draft_id: str
message: MailMessage
# --------------------------------------------------------------------------- #
# Credential file
# --------------------------------------------------------------------------- #
def normalize_email(email: str | None) -> str:
return (email or "").strip().lower()
def email_key(email: str) -> str:
"""The credential file's stem for ``email`` (so the address is not in a
file name on the volume)."""
return hashlib.sha256(normalize_email(email).encode()).hexdigest()[:16]
def credentials_dir() -> Path:
from openexecutive.config import get_settings
return Path(get_settings().delegation_google_credentials_dir)
def credential_path(email: str, *, directory: Path | None = None) -> Path:
return (directory or credentials_dir()) / f"{email_key(email)}.json"
def credential_provider(email: str, *, directory: Path | None = None) -> str:
"""Which mailbox ``email``'s credential file opens: ``"google"`` (also
for a file with no provider, or none at all) or ``"microsoft"``."""
address = normalize_email(email)
if not address:
return PROVIDER
try:
data = json.loads(credential_path(address, directory=directory).read_text(encoding="utf-8"))
except (OSError, ValueError):
return PROVIDER
return "microsoft" if isinstance(data, dict) and data.get("provider") == "microsoft" else PROVIDER
def load_credential(email: str, *, directory: Path | None = None) -> GmailCredential | None:
"""The stored credential for ``email``, or None when there is none or it
is unreadable (logged). A file naming another address is ignored."""
address = normalize_email(email)
if not address:
return None
path = credential_path(address, directory=directory)
if not path.is_file():
return None
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError):
logger.warning("delegation.gmail: unreadable credential file %s", path.name)
return None
if not isinstance(data, dict) or data.get("provider", PROVIDER) != PROVIDER:
return None
if normalize_email(str(data.get("email") or "")) != address:
logger.warning("delegation.gmail: credential file %s is for another address", path.name)
return None
user = data.get("authorized_user")
if not isinstance(user, dict):
return None
values = {k: user.get(k) for k in ("refresh_token", "client_id", "client_secret")}
if not all(isinstance(v, str) and v for v in values.values()):
logger.warning("delegation.gmail: credential file %s is incomplete", path.name)
return None
token_uri = user.get("token_uri") or DEFAULT_TOKEN_URI
if not isinstance(token_uri, str) or not _TOKEN_URI_RE.match(token_uri):
logger.warning("delegation.gmail: credential file %s names an unexpected token endpoint", path.name)
return None
return GmailCredential(
email=address,
refresh_token=str(values["refresh_token"]),
client_id=str(values["client_id"]),
client_secret=str(values["client_secret"]),
token_uri=token_uri,
)
# --------------------------------------------------------------------------- #
# Parsing
# --------------------------------------------------------------------------- #
def _b64decode(data: str) -> bytes:
return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))
def _headers(payload: dict[str, Any]) -> dict[str, str]:
out: dict[str, str] = {}
for h in payload.get("headers") or []:
if isinstance(h, dict) and isinstance(h.get("name"), str):
out.setdefault(h["name"].lower(), str(h.get("value") or ""))
return out
# Everything here runs on mail anyone can send, on the event loop, so each step
# is one forward pass: these patterns end at the next "<" as well as at ">",
# and no two quantifiers compete for the same characters.
_BR_RE = re.compile(r"(?i)<\s*(?:/\s*)?br\b[^<>]*>")
# Opening and closing tags alike: Gmail puts a signature's first line straight
# in its outer <div> and each later line in a <div> of its own.
_BLOCK_EDGE_RE = re.compile(
r"(?i)<\s*(?:/\s*)?(?:address|article|aside|blockquote|center|dd|div|dl|dt|figcaption|figure|"
r"footer|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|table|tr|ul)\b[^<>]*>"
)
_HIDDEN = {
name: (re.compile(rf"(?i)<{name}\b"), re.compile(rf"(?i)</{name}\s*>")) for name in ("script", "style")
}
_DECIMAL_REF_RE = re.compile(r"&#(\d+)(;?)")
_EDGE = "\x00"
def _short_decimal_ref(match: re.Match[str]) -> str:
# html.unescape turns the digits into an int, and Python refuses more than
# 4,300 of them (ValueError). Beyond seven significant digits the value is
# past Unicode's range, which unescape reads as U+FFFD anyway.
digits = match.group(1).lstrip("0") or "0"
return "�" if len(digits) > 7 else f"&#{digits}{match.group(2)}"
def _drop_hidden(markup: str) -> str:
"""``markup`` without its ``<script>`` and ``<style>`` elements, in one
pass each: an element nothing closes is left for the tag strip."""
for opening, closing in _HIDDEN.values():
out: list[str] = []
at = 0
while (start := opening.search(markup, at)) is not None:
end = closing.search(markup, start.end())
if end is None:
break
out.append(markup[at:start.start()])
at = end.end()
out.append(markup[at:])
markup = "".join(out)
return markup
def html_to_text(markup: str) -> str:
"""Plain text from an HTML body or signature. A ``<br>`` (or a line break
in the markup) always ends a line; a block's opening or closing tag ends
one only when it has text, so ``</div><div>`` is a single break and
``<div><br></div>`` a blank line."""
text = _drop_hidden(markup.replace(_EDGE, ""))
text = _BLOCK_EDGE_RE.sub(_EDGE, _BR_RE.sub("\n", text))
text = html.unescape(_DECIMAL_REF_RE.sub(_short_decimal_ref, strip_tags(text)))
out: list[str] = []
has_text = False
for piece in re.split(f"({_EDGE}|\n)", text):
if piece == "\n" or (piece == _EDGE and has_text):
out.append("\n")
has_text = False
elif piece != _EDGE:
out.append(piece)
# Only markup whitespace: a line of is a line the reader sees.
has_text = has_text or bool(piece.strip(" \t\r\n\f\v"))
lines = [ln.rstrip() for ln in "".join(out).splitlines()]
return re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()
def _part_text(part: dict[str, Any]) -> str:
data = (part.get("body") or {}).get("data")
if not isinstance(data, str) or not data:
return ""
try:
return _b64decode(data).decode("utf-8", errors="replace")
except (ValueError, TypeError):
return ""
def _body_text(payload: dict[str, Any]) -> str:
"""The message's plain text: its text/plain part, else its HTML as text."""
plain: list[str] = []
markup: list[str] = []
stack = [payload]
while stack:
part = stack.pop(0)
mime = str(part.get("mimeType") or "").lower()
if mime == "text/plain":
plain.append(_part_text(part))
elif mime == "text/html":
markup.append(_part_text(part))
stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
if any(t.strip() for t in plain):
return "\n".join(t for t in plain if t.strip()).strip()
return html_to_text("\n".join(markup))
def _addresses(value: str) -> list[str]:
return [normalize_email(addr) for _, addr in getaddresses([value]) if "@" in addr]
def _names(*values: str) -> dict[str, str]:
"""Each address in the ``values`` headers with the name written next to it."""
out: dict[str, str] = {}
for name, addr in getaddresses(list(values)):
if "@" in addr:
out.setdefault(normalize_email(addr), clean_header(name))
return out
def _hide_tokens(text: str) -> str:
"""``text`` with the Executive's one-time answer tokens hidden. The
owner's own mailbox holds the roster and standing-fact confirmation
emails the Executive sent them; the drafting model must never read a live
token (``mcp_gateway.hide_roster_tokens`` does the same for the
Executive's mailbox)."""
from openexecutive.orchestrator.mcp_gateway import hide_roster_tokens
return hide_roster_tokens(text)
_REPORT_SENDERS = ("mailer-daemon", "postmaster")
_BULK_PRECEDENCE = frozenset({"bulk", "junk", "list", "auto_reply"})
# Set by out-of-office and other auto-responders.
_AUTOREPLY_HEADERS = ("x-autoreply", "x-autorespond", "x-autoresponder")
_CALENDAR_TYPES = frozenset({"text/calendar", "application/ics"})
_ICS_UID_MAX = 1024
def ics_invite(text: str) -> tuple[str, str]:
"""An iCalendar text's method and its first event's UID, ``("", "")``
when it has neither. Only these two are read: nothing else in the file
(its title, its description) is used from here."""
unfolded = re.sub(r"\r?\n[ \t]", "", text or "")
method = uid = ""
in_event = False
for line in unfolded.splitlines():
name, sep, value = line.partition(":")
if not sep:
continue
key = name.split(";", 1)[0].strip().upper()
if key == "BEGIN" and value.strip().upper() == "VEVENT":
in_event = True
elif key == "END" and value.strip().upper() == "VEVENT":
if uid:
break
in_event = False
elif key == "METHOD" and not in_event and not method:
method = value.strip().upper()[:20]
elif key == "UID" and in_event and not uid:
candidate = value.strip()
if 0 < len(candidate) <= _ICS_UID_MAX and candidate.isprintable():
uid = candidate
return method, uid
def _invite_part(payload: dict[str, Any]) -> tuple[str, str]:
"""The method and UID of the message's inline text/calendar part."""
stack = [payload]
while stack:
part = stack.pop(0)
if str(part.get("mimeType") or "").lower() in _CALENDAR_TYPES:
found = ics_invite(_part_text(part))
if found[1]:
return found
stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
return "", ""
def _header_message(payload: dict[str, Any]) -> Message:
"""The payload's headers, in order and with repeats, as an ``email``
Message — what the DMARC and out-of-office checks read."""
msg = Message()
for h in payload.get("headers") or []:
if isinstance(h, dict) and isinstance(h.get("name"), str):
value = str(h.get("value") or "").replace("\r", " ").replace("\n", " ")
try:
msg[h["name"]] = value
except (ValueError, TypeError):
continue
return msg
def _part_types(payload: dict[str, Any]) -> set[str]:
types: set[str] = set()
stack = [payload]
while stack:
part = stack.pop()
types.add(str(part.get("mimeType") or "").lower())
stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
return types
def _attachment_parts(payload: dict[str, Any]) -> list[dict[str, Any]]:
"""The message's attached files, in the order Gmail lists its parts: any
part that names a file, but an image the HTML body shows in place (one
with a Content-ID, such as a signature's logo)."""
out: list[dict[str, Any]] = []
stack = [payload]
while stack:
part = stack.pop(0)
embedded = str(part.get("mimeType") or "").lower().startswith("image/") and "content-id" in _headers(part)
if str(part.get("filename") or "").strip() and not embedded:
out.append(part)
stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
return out
def _attachments(payload: dict[str, Any]) -> list[MailAttachment]:
out = []
for i, part in enumerate(_attachment_parts(payload), 1):
size = (part.get("body") or {}).get("size")
out.append(MailAttachment(
index=i,
name=str(part.get("filename") or "").strip(),
mime_type=str(part.get("mimeType") or "").lower(),
size=size if isinstance(size, int) else 0,
))
return out
def _received_at(raw: dict[str, Any]) -> str:
try:
ms = int(str(raw.get("internalDate") or ""))
except ValueError:
return ""
return datetime.fromtimestamp(ms / 1000, UTC).isoformat()
def parse_message(raw: dict[str, Any]) -> MailMessage:
"""A Gmail API ``format=full`` message as a ``MailMessage``, with any
one-time answer token hidden (``_hide_tokens``)."""
from openexecutive.integrations.fact_confirmation import headers_authenticated
raw_payload = raw.get("payload")
payload: dict[str, Any] = raw_payload if isinstance(raw_payload, dict) else {}
headers = _headers(payload)
header_msg = _header_message(payload)
sender = getaddresses([headers.get("from", "")])
from_name, from_addr = sender[0] if sender else ("", "")
auto = headers.get("auto-submitted", "no").strip().lower() not in ("", "no")
types = _part_types(payload)
local_part = normalize_email(from_addr).partition("@")[0]
attachments = _attachments(payload)
invite_method, invite_uid = _invite_part(payload) if types & _CALENDAR_TYPES else ("", "")
return MailMessage(
id=str(raw.get("id") or ""),
thread_id=str(raw.get("threadId") or ""),
from_addr=normalize_email(from_addr),
from_name=from_name.strip(),
to=_addresses(headers.get("to", "")),
cc=_addresses(headers.get("cc", "")),
reply_to=",".join(_addresses(headers.get("reply-to", ""))),
subject=_hide_tokens(headers.get("subject", "").strip()),
date=headers.get("date", "").strip(),
message_id_header=headers.get("message-id", "").strip(),
references=headers.get("references", "").strip(),
labels=[str(label) for label in raw.get("labelIds") or []],
text=_hide_tokens(_body_text(payload)),
mailing_list=bool(headers.get("list-unsubscribe") or headers.get("list-id")),
auto_generated=auto or "calendar-notification" in headers.get("sender", "").lower(),
ghostwritten=bool(headers.get(GHOSTWRITTEN_HEADER.lower())),
bcc=_addresses(headers.get("bcc", "")),
received_at=_received_at(raw),
bulk=headers.get("precedence", "").strip().lower() in _BULK_PRECEDENCE
or any(name in headers for name in _AUTOREPLY_HEADERS),
delivery_report="multipart/report" in types or local_part in _REPORT_SENDERS,
calendar_invite=bool(types & _CALENDAR_TYPES),
sender_authenticated=headers_authenticated(header_msg, normalize_email(from_addr)),
attachments=attachments,
has_attachments=bool(attachments),
names=_names(headers.get("to", ""), headers.get("cc", "")),
invite_method=invite_method,
invite_uid=invite_uid,
)
# --------------------------------------------------------------------------- #
# Drafts
# --------------------------------------------------------------------------- #
def clean_header(value: str) -> str:
"""One header value, with no line breaks or control characters, capped."""
cleaned = "".join(ch if ch >= " " else " " for ch in value.replace("\r", " ").replace("\n", " "))
return " ".join(cleaned.split())[:_MAX_HEADER]
_MESSAGE_ID = re.compile(r"<[^<>\s]+>")
def references_header(prior: str, parent: str) -> str | None:
"""The References of a reply to ``parent`` (a Message-ID) whose own
References were ``prior``: whole ids only, the parent always last. When
the chain is too long for one header, the oldest ids after the thread's
first one go — never half an id, and never the parent."""
parents = _MESSAGE_ID.findall(parent or "")[-1:]
ids = [i for i in dict.fromkeys(_MESSAGE_ID.findall(prior or "")) if i not in parents] + parents
if not ids:
return None
while len(ids) > 2 and len(" ".join(ids)) > _MAX_HEADER:
del ids[1]
if len(" ".join(ids)) > _MAX_HEADER:
ids = ids[-1:]
joined = " ".join(ids)
# A single id too long for the header: none beats half of one.
return joined if len(joined) <= _MAX_HEADER else None
def build_raw(sender: str, spec: DraftSpec) -> str:
"""The draft as a base64url RFC 2822 message (Gmail's ``raw``)."""
msg = EmailMessage()
name = clean_header(spec.from_name)
sender = clean_header(spec.from_addr) if spec.from_addr else sender
msg["From"] = formataddr((name, sender)) if name else sender
msg["To"] = ", ".join(clean_header(a) for a in spec.to)
if spec.cc:
msg["Cc"] = ", ".join(clean_header(a) for a in spec.cc)
msg["Subject"] = clean_header(spec.subject)
if spec.in_reply_to:
msg["In-Reply-To"] = clean_header(spec.in_reply_to)
if spec.references:
msg["References"] = clean_header(spec.references)
msg[GHOSTWRITTEN_HEADER] = "1"
body = spec.body
if spec.forward is not None:
body = f"{spec.body}\n\n{spec.forward.header}\n\n{spec.forward.text}"
msg.set_content(body)
for name, mime, data in spec.attachments:
maintype, _, subtype = (mime or "application/octet-stream").partition("/")
msg.add_attachment(
data, maintype=maintype or "application", subtype=subtype or "octet-stream",
filename=clean_header(name) or "attachment",
)
return base64.urlsafe_b64encode(msg.as_bytes()).decode("ascii")
def gmail_link(email: str, *, thread_id: str | None = None, message_id: str | None = None) -> str:
"""A link that opens the draft in Gmail, built from a fixed prefix: the
thread for a reply, the draft itself for a new email."""
base = f"https://mail.google.com/mail/u/?authuser={quote(normalize_email(email))}"
if thread_id and _ID_RE.fullmatch(thread_id):
return f"{base}#all/{thread_id}"
if message_id and _ID_RE.fullmatch(message_id):
return f"{base}#drafts?compose={message_id}"
return f"{base}#drafts"
def valid_id(value: object) -> bool:
return isinstance(value, str) and bool(_ID_RE.fullmatch(value))
# Every link ``mailbox_link`` builds starts with one of these; the chat chip
# and the reply cards (packages/ui/src/lib/replyCards.ts) link nowhere else.
MAILBOX_LINK_PREFIXES: tuple[str, ...] = (
"https://mail.google.com/",
"https://outlook.office.com/mail/",
"https://outlook.live.com/mail/",
)
def mailbox_link(
email: str,
*,
thread_id: str | None = None,
message_id: str | None = None,
draft_id: str | None = None,
) -> str:
"""A link that opens a draft in the person's own mailbox, whichever it
is. Gmail opens the thread for a reply (``thread_id``), else the draft by
its message id; Outlook opens the draft itself (``draft_id``, else
``message_id``), as Outlook on the web has no link to a conversation."""
if credential_provider(email) != "microsoft":
return gmail_link(email, thread_id=thread_id, message_id=message_id)
from openexecutive.delegation.outlook import load_credential as load_outlook
from openexecutive.delegation.outlook import outlook_link
cred = load_outlook(email)
return outlook_link(personal=bool(cred and cred.personal), message_id=draft_id or message_id)
# --------------------------------------------------------------------------- #
# Client
# --------------------------------------------------------------------------- #
# Gmail answers some quota errors with 403, not 429: slow down, don't reconnect.
_RATE_LIMIT_REASONS = frozenset({"rateLimitExceeded", "userRateLimitExceeded", "dailyLimitExceeded", "quotaExceeded"})
def _rate_limited(resp: httpx.Response) -> bool:
"""Whether a 403 is Gmail's rate limit rather than a refused sign-in."""
try:
errors = resp.json().get("error", {}).get("errors", [])
except (ValueError, AttributeError):
return False
if not isinstance(errors, list):
return False
return any(isinstance(e, dict) and e.get("reason") in _RATE_LIMIT_REASONS for e in errors)
def _token_key(cred: GmailCredential) -> str:
return hashlib.sha256(f"{cred.email}\n{cred.refresh_token}".encode()).hexdigest()
class DelegateGmail:
"""One person's mailbox. ``transport`` is for tests (httpx MockTransport)."""
provider = PROVIDER
valid_id = staticmethod(valid_id)
def __init__(
self,
email: str,
*,
credential: GmailCredential | None = None,
transport: httpx.AsyncBaseTransport | None = None,
timeout: float = 15.0,
) -> None:
self.email = normalize_email(email)
self._credential = credential
self._transport = transport
self._timeout = timeout
def _client(self) -> httpx.AsyncClient:
return httpx.AsyncClient(timeout=self._timeout, transport=self._transport)
def _cred(self) -> GmailCredential:
cred = self._credential or load_credential(self.email)
if cred is None:
raise GmailNotConfigured(self.email)
return cred
async def _access_token(self, client: httpx.AsyncClient) -> str:
cred = self._cred()
key = _token_key(cred)
cached = _TOKENS.get(key)
if cached is not None and cached[1] - _TOKEN_SLACK_SECONDS > time.time():
return cached[0]
try:
resp = await client.post(
cred.token_uri,
data={
"grant_type": "refresh_token",
"refresh_token": cred.refresh_token,
"client_id": cred.client_id,
"client_secret": cred.client_secret,
},
)
except httpx.HTTPError as exc:
raise GmailError(f"token refresh failed: {type(exc).__name__}") from exc
if resp.status_code in (400, 401):
try:
code = str(resp.json().get("error") or "")
except ValueError:
code = ""
if code in ("invalid_grant", "unauthorized_client", "invalid_client") or resp.status_code == 401:
raise GmailAuthError(code or "unauthorized")
if resp.status_code >= 400:
raise GmailError(f"token refresh returned {resp.status_code}")
try:
payload = resp.json()
token = str(payload["access_token"])
ttl = int(payload.get("expires_in", 3600))
except (ValueError, KeyError, TypeError) as exc:
raise GmailError("token refresh returned an unexpected response") from exc
granted = str(payload.get("scope") or "")
if granted and not set(SCOPES) <= set(granted.split()):
raise GmailAuthError("missing_scope")
_TOKENS[key] = (token, time.time() + ttl)
_GRANTED[key] = granted
return token
async def _get(
self, client: httpx.AsyncClient, path: str, params: Any = None
) -> dict[str, Any]:
return await self._request(client, "GET", path, params=params)
async def _request(
self,
client: httpx.AsyncClient,
method: str,
path: str,
*,
params: Any = None,
json_body: dict[str, Any] | None = None,
base: str = GMAIL_BASE,
if_match: str | None = None,
) -> dict[str, Any]:
token = await self._access_token(client)
headers = {"Authorization": f"Bearer {token}"}
if if_match:
headers["If-Match"] = if_match
try:
resp = await client.request(
method,
f"{base}{path}",
params=params,
json=json_body,
headers=headers,
)
except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
# Never reached Google: nothing was done.
raise GmailError(f"gmail {method} failed: {type(exc).__name__}") from exc
except httpx.HTTPError as exc:
raise GmailError(f"gmail {method} failed: {type(exc).__name__}", maybe_done=True) from exc
if resp.status_code == 401:
_TOKENS.pop(_token_key(self._cred()), None)
raise GmailAuthError("unauthorized")
if resp.status_code == 403 and not _rate_limited(resp):
raise GmailAuthError("forbidden")
if resp.status_code in (403, 429):
raise GmailRateLimited(f"gmail {method} returned {resp.status_code}")
if resp.status_code == 404:
raise GmailNotFound(f"gmail {method} returned 404")
if resp.status_code == 412:
raise GmailChanged(f"gmail {method} returned 412")
if resp.status_code >= 500:
raise GmailError(f"gmail {method} returned {resp.status_code}", maybe_done=True)
if resp.status_code >= 400:
raise GmailError(f"gmail {method} returned {resp.status_code}")
if not resp.content:
return {} # a DELETE answers 204 with no body
try:
data = resp.json()
except ValueError as exc:
raise GmailError("gmail returned a non-JSON response", maybe_done=True) from exc
return data if isinstance(data, dict) else {}
async def profile_email(self) -> str:
"""The address the credential opens, as Google reports it."""
async with self._client() as client:
data = await self._get(client, "/profile")
return normalize_email(str(data.get("emailAddress") or ""))
async def search_threads(self, query: str, *, max_results: int = 5) -> list[ThreadSummary]:
"""Threads matching a Gmail search, newest first: subject, sender and
date only (no body text)."""
from openexecutive.integrations.fact_confirmation import headers_authenticated
async with self._client() as client:
data = await self._get(
client, "/threads", {"q": query[:300], "maxResults": max(1, min(max_results, 10))}
)
ids = [str(t.get("id")) for t in data.get("threads") or [] if valid_id(t.get("id"))]
summaries: list[ThreadSummary] = []
for thread_id in ids:
meta = await self._get(
client,
f"/threads/{thread_id}",
[("format", "metadata"),
*(("metadataHeaders", name) for name in _SUMMARY_HEADERS)],
)
messages = [m for m in meta.get("messages") or [] if isinstance(m, dict)]
payload = (messages[-1].get("payload") or {}) if messages else {}
headers = _headers(payload)
sender = getaddresses([headers.get("from", "")])
from_addr = sender[0][1] if sender else ""
summaries.append(ThreadSummary(
id=thread_id,
subject=_hide_tokens(headers.get("subject", "")),
sender=headers.get("from", ""),
date=headers.get("date", ""),
sender_authenticated=headers_authenticated(
_header_message(payload), normalize_email(from_addr)
),
))
return summaries
async def get_thread(self, thread_id: str) -> MailThread:
if not valid_id(thread_id):
raise GmailError("invalid thread id")
async with self._client() as client:
data = await self._get(client, f"/threads/{thread_id}", {"format": "full"})
messages = [parse_message(m) for m in data.get("messages") or [] if isinstance(m, dict)]
return MailThread(id=thread_id, messages=messages)
async def list_sent(self, limit: int = 40) -> list[MailMessage]:
"""The person's recent sent mail, newest first (at most ``limit``)."""
async with self._client() as client:
data = await self._get(
client,
"/messages",
{"q": "in:sent -in:chats newer_than:1y", "maxResults": max(1, min(limit, 100))},
)
ids = [str(m.get("id")) for m in data.get("messages") or [] if valid_id(m.get("id"))]
gate = asyncio.Semaphore(_FETCH_CONCURRENCY)
async def fetch(message_id: str) -> MailMessage | GmailAuthError | None:
# Returns the auth error rather than raising it, so every
# fetch finishes before the client closes.
async with gate:
try:
raw = await self._get(client, f"/messages/{message_id}", {"format": "full"})
except GmailAuthError as exc:
return exc
except GmailError:
logger.warning("delegation.gmail: skipped an unreadable sent message")
return None
return parse_message(raw)
fetched = await asyncio.gather(*(fetch(i) for i in ids))
refused = next((f for f in fetched if isinstance(f, GmailAuthError)), None)
if refused is not None:
raise refused
return [m for m in fetched if isinstance(m, MailMessage)]
async def send_as_signature(self) -> str:
"""The signature on the person's primary Gmail address, as plain text."""
async with self._client() as client:
data = await self._get(client, "/settings/sendAs")
entries = [e for e in data.get("sendAs") or [] if isinstance(e, dict)]
primary = next((e for e in entries if e.get("isPrimary")), None) or next(
(e for e in entries if normalize_email(str(e.get("sendAsEmail") or "")) == self.email),
None,
)
return html_to_text(str((primary or {}).get("signature") or ""))
async def list_message_ids(self, query: str, *, max_results: int = 25) -> list[tuple[str, str]]:
"""``(message id, thread id)`` for mail matching a Gmail search,
newest first (at most ``max_results``, capped at 100)."""
async with self._client() as client:
data = await self._get(
client, "/messages", {"q": query[:500], "maxResults": max(1, min(max_results, 100))}
)
return [
(str(m["id"]), str(m.get("threadId") or ""))
for m in data.get("messages") or []
if isinstance(m, dict) and valid_id(m.get("id"))
]
async def inbox_message_ids(self, *, after: datetime, max_results: int = 25) -> list[tuple[str, str]]:
"""``(message id, thread id)`` for mail that reached the Primary inbox
since ``after``, newest first, leaving out the person's own."""
query = (
"in:inbox -in:chats -from:me -category:promotions -category:social "
f"-category:updates -category:forums after:{int(after.timestamp())}"
)
return await self.list_message_ids(query, max_results=max_results)
async def has_written_to(self, address: str) -> bool:
"""Whether the person's sent mail holds mail to ``address``."""
target = normalize_email(address)
if not _EMAIL_RE.fullmatch(target):
return False
return bool(await self.list_message_ids(f"in:sent to:{target}", max_results=1))
async def latest_from(self, address: str, *, days: int = 90) -> MailMessage | None:
"""The newest mail ``address`` sent the person in the last ``days``,
or None."""
target = normalize_email(address)
if not _EMAIL_RE.fullmatch(target):
return None
found = await self.list_message_ids(f"from:{target} -in:chats newer_than:{int(days)}d", max_results=1)
return await self.get_message(found[0][0]) if found else None
async def recent_from(self, address: str, *, days: int = 90, limit: int = 5) -> list[MailMessage]:
"""The newest ``limit`` mails ``address`` sent the person in the last
``days``, newest first."""
target = normalize_email(address)
if not _EMAIL_RE.fullmatch(target):
return []
found = await self.list_message_ids(
f"from:{target} -in:chats newer_than:{int(days)}d", max_results=max(1, min(int(limit), 25)),
)
messages: list[MailMessage] = []
for message_id, _thread in found:
try:
messages.append(await self.get_message(message_id))
except GmailNotFound:
continue # deleted since it was listed
return messages
async def get_message(self, message_id: str) -> MailMessage:
if not valid_id(message_id):
raise GmailError("invalid message id")
async with self._client() as client:
data = await self._get(client, f"/messages/{message_id}", {"format": "full"})
return parse_message(data)
async def list_attachments(self, message_id: str) -> list[MailAttachment]:
return (await self.get_message(message_id)).attachments
async def _with_forwarded_files(self, spec: DraftSpec) -> tuple[DraftSpec, int]:
"""``spec`` with its forwarded message's files attached, and how
many were left off for the caps."""
assert spec.forward is not None
files: list[tuple[str, str, bytes]] = []
total = skipped = 0
for meta in await self.list_attachments(spec.forward.message_id):
if len(files) >= FORWARD_MAX_FILES or total + meta.size > FORWARD_MAX_BYTES:
skipped += 1
continue
meta, data = await self.attachment_bytes(spec.forward.message_id, meta.index)
if total + len(data) > FORWARD_MAX_BYTES:
skipped += 1
continue
total += len(data)
files.append((meta.name, meta.mime_type, data))
return replace(spec, attachments=files), skipped
async def attachment_bytes(self, message_id: str, index: int) -> tuple[MailAttachment, bytes]:
"""The ``index``-th attached file of the message (1-based) and its
bytes, read with the attachment id Gmail gives on this fetch."""
if not valid_id(message_id):
raise GmailError("invalid message id")
async with self._client() as client:
raw = await self._get(client, f"/messages/{message_id}", {"format": "full"})
raw_payload = raw.get("payload")
payload: dict[str, Any] = raw_payload if isinstance(raw_payload, dict) else {}
parts = _attachment_parts(payload)
if not 1 <= index <= len(parts):
raise GmailNotFound("no such attachment")
meta = _attachments(payload)[index - 1]
body = parts[index - 1].get("body") or {}
attachment_id = body.get("attachmentId")
if isinstance(attachment_id, str) and attachment_id:
if not _ATTACHMENT_ID_RE.fullmatch(attachment_id):
raise GmailError("gmail returned an unusable attachment id")
body = await self._get(client, f"/messages/{message_id}/attachments/{attachment_id}")
data = body.get("data")
if not isinstance(data, str):
raise GmailError("gmail returned no attachment data")
try:
return meta, _b64decode(data)
except (ValueError, TypeError) as exc:
raise GmailError("gmail returned unreadable attachment data") from exc
async def send_as_addresses(self) -> list[str]:
"""Every address the person can send as (their primary and aliases)."""
async with self._client() as client:
data = await self._get(client, "/settings/sendAs")
entries = [e for e in data.get("sendAs") or [] if isinstance(e, dict)]
return [a for a in (normalize_email(str(e.get("sendAsEmail") or "")) for e in entries) if a]
async def get_draft(self, draft_id: str) -> DraftInfo | None:
"""The draft as it is now, or None when it is gone (sent or deleted)."""
if not valid_id(draft_id):
raise GmailError("invalid draft id")
async with self._client() as client:
try:
data = await self._get(client, f"/drafts/{draft_id}", {"format": "full"})
except GmailNotFound:
return None
raw_message = data.get("message")
message = parse_message(raw_message if isinstance(raw_message, dict) else {})
return DraftInfo(draft_id=str(data.get("id") or draft_id), message=message)
async def delete_draft(self, draft_id: str) -> bool:
"""Delete a draft (never a sent message). False when it was already gone."""
if not valid_id(draft_id):
raise GmailError("invalid draft id")
async with self._client() as client:
try:
await self._request(client, "DELETE", f"/drafts/{draft_id}")
except GmailNotFound:
return False
return True
async def update_draft_text(
self, draft_id: str, expected_version: str, text: str, *,
to: list[str] | None = None, cc: list[str] | None = None,
) -> str:
"""Replace the words of the draft ``draft_id`` with ``text``, keeping
every header (who it goes to, the subject, the thread), when it is
still the version ``expected_version``. With ``to`` it goes to ``to``
and ``cc`` instead. Returns its new version (the
message id Gmail gives the edited draft). Raises ``GmailNotFound``
when it is gone and ``DraftChanged`` when it changed meanwhile or is
more than plain text. Nothing is sent."""
if not valid_id(draft_id):
raise GmailError("invalid draft id")
async with self._client() as client:
data = await self._get(client, f"/drafts/{draft_id}", {"format": "raw"})
current = data.get("message")
current = current if isinstance(current, dict) else {}
if str(current.get("id") or "") != expected_version:
raise DraftChanged("changed")
raw = current.get("raw")
if not isinstance(raw, str):
raise GmailError("gmail returned no draft")
try:
from email import message_from_bytes, policy
msg = message_from_bytes(_b64decode(raw), policy=policy.default)
except (ValueError, TypeError) as exc:
raise GmailError("gmail returned an unreadable draft") from exc
if not isinstance(msg, EmailMessage) or msg.is_multipart() or msg.get_content_type() != "text/plain":
raise DraftChanged("not_plain")
msg.set_content(text)
if to is not None:
del msg["To"]
del msg["Cc"]
msg["To"] = ", ".join(clean_header(a) for a in to)
if cc:
msg["Cc"] = ", ".join(clean_header(a) for a in cc)
message: dict[str, Any] = {"raw": base64.urlsafe_b64encode(msg.as_bytes()).decode("ascii")}
thread_id = current.get("threadId")
if isinstance(thread_id, str) and valid_id(thread_id):
message["threadId"] = thread_id
updated = await self._request(
client, "PUT", f"/drafts/{draft_id}", json_body={"id": draft_id, "message": message},
)
saved = updated.get("message")
version = str(saved.get("id") or "") if isinstance(saved, dict) else ""
if not version:
raise GmailError("gmail returned no edited draft", maybe_done=True)
return version
async def send_draft(self, draft_id: str) -> SentMessage:
"""Send the draft ``draft_id`` exactly as it is in Gmail now: the
request body is its id and nothing else, so nothing here can change
what goes, or to whom. Gmail deletes a draft it sends. Only
``delegation.reply_send`` calls this (a unit test holds it to that).
A ``GmailError`` whose ``maybe_done`` is set may have sent it."""
if not valid_id(draft_id):
raise GmailError("invalid draft id")
async with self._client() as client:
data = await self._request(client, "POST", "/drafts/send", json_body={"id": draft_id})
return SentMessage(id=str(data.get("id") or ""), thread_id=str(data.get("threadId") or ""))
async def create_draft(self, spec: DraftSpec) -> CreatedDraft:
"""Save ``spec`` as a draft in the person's Gmail. Nothing is sent.
A forward attaches the forwarded message's files, as many as fit
``FORWARD_MAX_FILES`` and ``FORWARD_MAX_BYTES``."""
if spec.thread_id is not None and not valid_id(spec.thread_id):
raise GmailError("invalid thread id")
skipped = 0
if spec.forward is not None and not spec.attachments:
spec, skipped = await self._with_forwarded_files(spec)
message: dict[str, Any] = {"raw": build_raw(self.email, spec)}
if spec.thread_id:
message["threadId"] = spec.thread_id
async with self._client() as client:
data = await self._request(client, "POST", "/drafts", json_body={"message": message})
raw_created = data.get("message")
created: dict[str, Any] = raw_created if isinstance(raw_created, dict) else {}
return CreatedDraft(
draft_id=str(data.get("id") or ""),
message_id=str(created.get("id") or ""),
thread_id=str(created.get("threadId") or spec.thread_id or ""),
skipped_attachments=skipped,
)
async def _granted_scopes(self, client: httpx.AsyncClient) -> str:
await self._access_token(client)
return _GRANTED.get(_token_key(self._cred()), "")
async def calendar_granted(self) -> bool | None:
"""Whether their saved sign-in reads their calendar
(``calendar.readonly`` or ``calendar.events``); None when Google
didn't say which scopes it carries."""
async with self._client() as client:
granted = await self._granted_scopes(client)
return bool(CALENDAR_READ_SCOPES & set(granted.split())) if granted else None
async def calendar_write_granted(self) -> bool | None:
"""Whether their saved sign-in can answer a meeting invite
(``calendar.events``); None when Google didn't say."""
async with self._client() as client:
granted = await self._granted_scopes(client)
return bool(CALENDAR_WRITE_SCOPES & set(granted.split())) if granted else None
async def list_events(self, start: datetime, end: datetime, *, max_results: int = MAX_EVENTS) -> list[CalendarEvent]:
"""The events on their primary calendar between ``start`` and ``end``,
recurring ones expanded, in order. A read (``calendar.readonly`` or
``calendar.events``)."""
async with self._client() as client:
granted = await self._granted_scopes(client)
if granted and not CALENDAR_READ_SCOPES & set(granted.split()):
raise CalendarNotGranted("calendar.readonly not granted")
params = {
"timeMin": start.astimezone(UTC).isoformat().replace("+00:00", "Z"),
"timeMax": end.astimezone(UTC).isoformat().replace("+00:00", "Z"),
"singleEvents": "true",
"orderBy": "startTime",
"maxResults": str(max(1, min(max_results, MAX_EVENTS))),
}
try:
data = await self._request(client, "GET", "/events", params=params, base=CALENDAR_BASE)
except GmailAuthError as exc:
if str(exc) != "forbidden":
raise
# With the scope granted, a refusal is the project's (the API
# not enabled, a quota), and reconnecting wouldn't fix it.
if CALENDAR_READ_SCOPES & set(granted.split()):
raise GmailError("calendar read refused with the scope granted") from exc
raise CalendarNotGranted("calendar read refused") from exc
items_raw = data.get("items")
items: list[Any] = items_raw if isinstance(items_raw, list) else []
events = [parse_google_event(item) for item in items if isinstance(item, dict)]
return [e for e in events if e is not None]
async def _invite_uid(self, message: MailMessage) -> tuple[str, str]:
"""The invite's method and UID: from its inline part, else from its
attached .ics file."""
if message.invite_uid:
return message.invite_method, message.invite_uid
for attachment in message.attachments:
if attachment.mime_type in _CALENDAR_TYPES or attachment.name.lower().endswith(".ics"):
_meta, data = await self.attachment_bytes(message.id, attachment.index)
found = ics_invite(data[:200_000].decode("utf-8", errors="replace"))
if found[1]:
return found
return "", ""
async def find_invite(self, message: MailMessage) -> CalendarEvent | None:
"""The event a meeting invite ``message`` asks them to, as it is on
their own primary calendar (found by its iCalendar UID), or None:
not a request (a cancellation, someone's answer), or not on their
calendar. A read."""
method, uid = await self._invite_uid(message)
if not uid or method not in ("", "REQUEST"):
return None
async with self._client() as client:
granted = await self._granted_scopes(client)
if granted and not CALENDAR_READ_SCOPES & set(granted.split()):
raise CalendarNotGranted("calendar.readonly not granted")
try:
data = await self._request(
client, "GET", "/events", params={"iCalUID": uid, "maxResults": "5"}, base=CALENDAR_BASE,
)
except GmailAuthError as exc:
if str(exc) != "forbidden":
raise
if CALENDAR_READ_SCOPES & set(granted.split()):
raise GmailError("calendar read refused with the scope granted") from exc
raise CalendarNotGranted("calendar read refused") from exc
items_raw = data.get("items")
items: list[Any] = items_raw if isinstance(items_raw, list) else []
for item in items:
if isinstance(item, dict) and _EVENT_ID_RE.fullmatch(str(item.get("id") or "")):
event = parse_google_event(item)
if event is not None:
return event
return None
async def answer_invite(self, event_id: str, *, accept: bool) -> None:
"""Answer the invite to ``event_id`` on their primary calendar, as
them: their own attendee entry's answer becomes accepted or declined,
and Google tells the organizer (``sendUpdates=all``). Nothing else on
the event changes: the write carries the event's ``etag``, so a change
made since it was read (a guest added, another answer) is read again
rather than overwritten, once. Called only by ``delegation.invites``,
on the person's tap or under Handle it for me (accept only).
Answering twice is the same as once. Raises ``CalendarWriteNotGranted`` for a
read-only sign-in, ``GmailNotFound`` when the event or their place on
it is gone."""
if not _EVENT_ID_RE.fullmatch(event_id or ""):
raise GmailError("invalid event id")
async with self._client() as client:
granted = await self._granted_scopes(client)
if granted and not CALENDAR_WRITE_SCOPES & set(granted.split()):
raise CalendarWriteNotGranted("calendar.events not granted")
path = f"/events/{event_id}"
try:
for attempt in range(2):
event = await self._request(client, "GET", path, base=CALENDAR_BASE)
attendees = [dict(a) for a in event.get("attendees") or [] if isinstance(a, dict)]
mine = next((a for a in attendees if a.get("self") is True), None)
if mine is None:
mine = next(
(a for a in attendees if normalize_email(str(a.get("email") or "")) == self.email),
None,
)
if mine is None:
raise GmailNotFound("not an attendee")
mine["responseStatus"] = "accepted" if accept else "declined"
try:
await self._request(
client, "PATCH", path, params={"sendUpdates": "all"},
json_body={"attendees": attendees}, base=CALENDAR_BASE,
if_match=str(event.get("etag") or "") or None,
)
return
except GmailChanged:
if attempt:
raise
except GmailAuthError as exc:
if str(exc) != "forbidden":
raise
if CALENDAR_WRITE_SCOPES & set(granted.split()):
raise GmailError("calendar write refused with the scope granted") from exc
raise CalendarWriteNotGranted("calendar write refused") from exc
def gmail_for(email: str) -> Any:
"""The client for ``email``'s own mailbox: ``DelegateGmail``, or
``outlook.DelegateOutlook`` when their credential file is a Microsoft one.
Both have the same methods, return types and errors."""
if credential_provider(email) == "microsoft":
from openexecutive.delegation.outlook import DelegateOutlook
return DelegateOutlook(email)
return DelegateGmail(email)
async def gmail_status(person_email: str | None, *, gmail: Any = None) -> GmailStatus:
"""Whether ``person_email``'s own mailbox can be used right now. Asks
the mail service which mailbox the credential opens. Never raises."""
from openexecutive.config import get_settings
address = normalize_email(person_email)
if not address:
return "no_email"
try:
exec_address = normalize_email(get_settings().exec_email_address)
except Exception:
logger.warning("delegation.gmail: settings unreadable — refusing", exc_info=True)
return "error"
if address == exec_address:
return "shared_mailbox"
client = gmail if gmail is not None else gmail_for(address)
try:
opened = await client.profile_email()
except GmailNotConfigured:
return "not_configured"
except GmailAuthError:
return "needs_reconnect"
except Exception:
logger.warning("delegation.gmail: status check failed", exc_info=True)
return "error"
return "connected" if opened == address else "mismatch"