lukasandClaude Opus 4.8
4c200ab94a
Gmail sync (SPEC: Gmail sync): - Provider fetches X-GM-LABELS when X-GM-EXT-1 is advertised; parses custom labels (system labels dropped, mUTF-7 decoded) onto RemoteMessage. - Engine syncs only system folders + All Mail for Gmail, skips every label folder, and dedupes the All Mail pass by Message-ID — kills the INBOX/All-Mail duplication. - Custom labels ride the message.new event; the labels plugin subscribes and maps them to chips as "<name> [Gmail]" (per-message + thread aggregate + known set), so labels fill in gradually with the sync window. Non-ASCII labels decode right. Labels self-healing (message-driven reconcile): - Per-message keys are the source of truth; t: aggregates and _labels are derived. Reconcile drops labels of deleted messages, regroups survivors by their current thread (fixing JWZ thread merges), rewrites changed t: keys, and rebuilds _labels from live messages — keeping user labels, dropping orphaned Gmail ones. - New SDK reads: sdk.threads.existing / sdk.messages.threads_of. Sidebar refreshes live via a plugin.labels.changed WS event on new labels. Account deletion: prune threads left empty after the cascade (they were user-scoped, so only messages cascaded) + de-list the account from surviving cross-account threads. Sync SPAM: opt-in per-account sync_spam (migration 0015, default off) — the engine skips the Junk folder in backfill and poll unless enabled; wizard checkbox added. Robustness / UX: - WebSocket auto-reconnects with backoff and resyncs on (re)connect, and account add/delete invalidates threads/labels — no more hard refresh for live updates. - Backfill banner + sidebar ring also require done < total, so a completed account can't leave a stuck "X of X". - Scrub lone UTF-16 surrogates from parsed headers/bodies so bad messages no longer crash the backfill on Postgres text/JSONB. - Ultimo signet logo in the Mail/Calendar/Contacts sidebar header (and at the top of the collapsed rail), via the shared plugin-ui.css + MailLayout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U72FZiF1W1pb8XxyWBTREA
133 lines
4.0 KiB
Python
133 lines
4.0 KiB
Python
# INTERFACE VERSION: 1
|
|
"""MailProvider — the frozen provider contract (SPEC §5.1).
|
|
|
|
This signature is a frozen contract (SPEC instruction 5): implementations may
|
|
evolve, signatures may not without bumping the version comment above.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import AsyncIterator
|
|
from dataclasses import dataclass
|
|
from datetime import date, datetime
|
|
from typing import Protocol
|
|
|
|
|
|
class ProviderError(Exception):
|
|
"""Base class for provider errors; carries a human-readable ``.detail``."""
|
|
|
|
def __init__(self, detail: str) -> None:
|
|
super().__init__(detail)
|
|
self.detail = detail
|
|
|
|
|
|
class ProviderAuthError(ProviderError):
|
|
"""Authentication failed (bad credentials / token)."""
|
|
|
|
|
|
class ProviderConnectError(ProviderError):
|
|
"""Could not connect / TLS / greeting failure."""
|
|
|
|
|
|
class ProviderNotSupported(ProviderError):
|
|
"""A capability (e.g. IDLE) is not supported by the server."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class RemoteMailbox:
|
|
path: str
|
|
special_use: str | None # "inbox"|"sent"|"drafts"|"trash"|"junk"|"archive"|None
|
|
uidvalidity: int
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class RemoteMessage:
|
|
uid: int
|
|
raw: bytes # full RFC822
|
|
flags: frozenset[str]
|
|
internal_date: datetime
|
|
gmail_labels: tuple[str, ...] = () # custom Gmail labels (Gmail accounts only)
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class FlagChange:
|
|
uid: int
|
|
flags: frozenset[str]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class MailboxDelta:
|
|
new: list[RemoteMessage]
|
|
flag_changes: list[FlagChange]
|
|
expunged_uids: list[int]
|
|
new_uidvalidity: int | None # non-None => UIDVALIDITY changed, caller must full-resync
|
|
new_highestmodseq: int | None
|
|
|
|
|
|
class MailProvider(Protocol):
|
|
async def verify(self) -> None:
|
|
"""Raises ProviderAuthError / ProviderConnectError with a human-readable .detail."""
|
|
...
|
|
|
|
async def list_mailboxes(self) -> list[RemoteMailbox]: ...
|
|
|
|
def backfill(
|
|
self,
|
|
mailbox: str,
|
|
*,
|
|
newest_first: bool = True,
|
|
batch_size: int = 200,
|
|
since: date | None = None,
|
|
before: date | None = None,
|
|
) -> AsyncIterator[list[RemoteMessage]]:
|
|
"""Yields batches until the mailbox is exhausted. Headers+body in one pass.
|
|
``since``/``before`` bound the import by internal date (SPEC §12 M2)."""
|
|
...
|
|
|
|
async def message_count(self, mailbox: str, *, since: date | None = None) -> int:
|
|
"""Number of messages to import (progress denominator); whole mailbox or
|
|
the ``since`` window."""
|
|
...
|
|
|
|
async def newest_uid(self, mailbox: str) -> int:
|
|
"""Current high-water UID; used by the ``new`` window to skip history."""
|
|
...
|
|
|
|
async def poll(
|
|
self, mailbox: str, *, last_seen_uid: int, highestmodseq: int | None
|
|
) -> MailboxDelta:
|
|
"""One reconciliation pass. Uses QRESYNC/CONDSTORE when highestmodseq is not None,
|
|
otherwise UID SEARCH + FETCH FLAGS diff."""
|
|
...
|
|
|
|
async def list_uids(self, mailbox: str) -> set[int]:
|
|
"""Full set of UIDs currently present in the mailbox (expunge reconciliation)."""
|
|
...
|
|
|
|
async def idle(self, mailbox: str) -> None:
|
|
"""Blocks until the server signals change or 25 min elapse (re-issue IDLE). May raise
|
|
ProviderNotSupported => sync loop falls back to poll() every POLL_WARM (default 180 s).
|
|
"""
|
|
...
|
|
|
|
async def push_flags(
|
|
self, mailbox: str, uid: int, add: frozenset[str], remove: frozenset[str]
|
|
) -> None: ...
|
|
|
|
async def move(self, uid: int, src: str, dst: str) -> int: # returns new UID
|
|
...
|
|
|
|
async def delete_messages(self, mailbox: str, uids: list[int]) -> None:
|
|
"""Permanently delete messages: set \\Deleted then EXPUNGE (SPEC §6.3)."""
|
|
...
|
|
|
|
async def append(
|
|
self, mailbox: str, raw: bytes, flags: frozenset[str]
|
|
) -> int: # Sent/Drafts upload
|
|
...
|
|
|
|
async def send(
|
|
self, raw: bytes, envelope_from: str, envelope_to: list[str]
|
|
) -> None: # SMTP submission
|
|
...
|