Repository navigation
feat(email): connect a user's Outlook mailbox and poll Inbox and Sent (EA-1) - #635
Open
privatejoel wants to merge 1 commit into
Open
privatejoel wants to merge 1 commit into
privatejoel wants to merge 1 commit into
Conversation
… (EA-1) Migration 267 mailbox_connections (tokens as secrets v2, checkpoint per folder, health and cost limits). Provider-independent mailFetch with a daily request budget, bounded retries and a run deadline. Outlook adapter on Graph delta with immutable IDs and a bounded first sync. Sync runner in the tick ALWAYS group behind email_accountability_enabled. Connect, list, resume and disconnect endpoints, and a purpose-bound OAuth state. Counts messages only; EA-3 adds the rules engine. Co-Authored-By: Claude Opus 5.5 <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Oct 22, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
EA-1 of the email accountability plan (#634, sections 5.1 and 6.1). A user can connect their own Outlook mailbox. The 5-minute tick then polls Inbox and Sent Items with Graph delta queries. This PR only counts messages. It makes no action and stores no mail. EA-3 adds the rules engine through the
onPagehook.Stacked on #619 (secrets v2). The tokens use its one-value format. Merge #619 first. GitHub then moves this PR to
main.mailbox_connections. Each row holds one mailbox, its encrypted tokens, the checkpoint for each folder, health counters and cost limits. RLS is on and has no policy for tenant users, so only the service role can read the tokens. The migration also adds threetenant_settingscolumns:email_accountability_enabled(default false), andgoogle_oauth_client_idandgoogle_oauth_client_secret_encfor EA-2._lib/mail/provider.jsis the part of the sync that works for any provider:MailErrorcodes;mailFetch, which counts each request against the mailbox's daily budget (a retry counts too), retries a 429, a 5xx or a network error at most 2 times, waits forRetry-Afterinside the run only up to 5 s, and keeps provider error bodies out of messages and logs._lib/mail/outlook.jsis the Outlook adapter:offline_access User.Read Mail.Read, on the tenant's existing app registration (graph_*, migration 028);inboxandsentitemswithchangeType=created,IdType="ImmutableId"and areceivedDateTimefilter on the first request, so no round reads the full history;_lib/mail/sync.jsis the runner. The rules are below.Retry-After, from 1 to 60 minutes.reauth_required.notifyAdmins) is sent when the state changes: a new sign-in is needed, the budget or quota runs out, the failure count reaches 3, or the mailbox pauses after failures. A repeated run sends no second alert./api/email/syncis the cron handler, in the tick ALWAYS group asemail/sync. It reads only tenants withemail_accountability_enabled. It syncs at most 8 due mailboxes in each run. A lease on each mailbox stops two overlapping ticks from syncing the same mailbox./api/email/connections:/api/email/connect/callbackis the public OAuth callback. The state is bound to the tenant, the user, the provider and a purpose. Before the callback stores the mailbox, it does these checks:graph-client.js:signStateandverifyStateaccept a purpose. A mailbox state cannot finish the tenant connect, and a tenant state cannot finish a mailbox connect.buildAuthorizeUrl,exchangeCodeandrefreshTokensaccept the scopes as an argument. The defaults do not change, so the tenant send connection works as before.No new npm package and no paid service. Graph mail reads are not metered.
Deploy notes
supabase/migrations/267_mailbox_connections.sqlby hand. Then runnotify pgrst, 'reload schema';. The migration has VERIFY queries.graph_client_idnames), do these steps:{PUBLIC_APP_URL}/api/email/connect/callback.User.Read,Mail.Readandoffline_access.update tenant_settings set email_accountability_enabled = true where tenant_id = '<id>';. Each user then connects throughPOST /api/email/connections. The UI comes in EA-7./api/cron/tickevery 5 minutes: cron-job.org, fix(cron): give the 5-minute tick a scheduler, behind an allow-list that defaults to extraction jobs only #566 or pg_cron. If fix(cron): give the 5-minute tick a scheduler, behind an allow-list that defaults to extraction jobs only #566 is merged, addemail/synctoCRON_TICK_HANDLERS.PUBLIC_APP_URL,ANVIL_SECRETS_KEYandCRON_SECRET.Tests
New tests use
test-memory-supabaseand a mockedfetch. They use no live credentials.src/v3-app/api-mail-outlook-sync.test.js(22 tests). It covers request tests [13], [14], [16] and [17]:changeType=created, immutable IDs and noisReadfield. The test checks that both delta links are saved.reauth_required. No mail is read, and one alert is sent, also on later runs. A 401 from Graph does the same.Retry-Afteris retried at most 2 times, then the mailbox pauses for at least 1 minute. A longRetry-Afteris not waited for inside the run. A 4xx is not retried.src/v3-app/api-email-connections.test.js(14 tests):reauth_requiredcannot be resumed (409). A disconnect deletes the tokens and the checkpoint.reauth_required.Mutation check: I broke each rule, ran the two files, saw a failure, and restored the code. All 21 mutations failed the tests:
Gates:
npm run check: pass.npm run lint: 0 errors. The new files add no warnings.npm run build: pass.npm run verify: pass. It rewrotedocs/RBAC_AUDIT.mdanddocs/WRITE_PATH_AUDIT.mdwith changes that are not from this PR, so I restored the two files.npm run eval:golden: pass (aggregate 1.000).NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 626 files, 7,484 tests, all pass.migrationsjob applies it.Not covered
notifyAdmins. Notices to one person need feat(notifications): a notice per person and a bell for every role, on desktop and phone #624.test-memory-supabase.tsnow acceptslt, andor()terms withlt,lte,gtandgte.🤖 Generated with Claude Code