Repository navigation
feat(email): reminders and escalation on a policy, with no duplicate notice (EA-6) - #640
Open
privatejoel wants to merge 2 commits into
Open
privatejoel wants to merge 2 commits into
privatejoel wants to merge 2 commits into
Conversation
…n desktop and phone
C-17 (WM-7, R-F5). Migration 253 adds admin_notifications.recipient_user_id.
A null value is a broadcast row, as before. A user id is a row for that
person only.
- notify(svc, tenantId, payload, { users, roles, dedupKey }) writes one row
per recipient. A role expands to the approved members of this tenant.
- notifyAdmins does not change. It writes one broadcast row.
- GET /api/admin/notifications shows the caller their own rows. Admin and
operator also see the broadcast rows, as before.
- mark_read and mark_all_read are open to every role. They touch only the
rows that the caller sees. Resolve stays admin only.
- The bell shows for every role in Shell and in MobileShell.
- Before migration 253 is applied, notify skips and logs. It does not write
a broadcast row. The list shows nothing to a role that is not admin or
operator.
- The header comment in notifications.js said one row per recipient. That
was false. It is correct now.
No new events. C-19 adds them.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…notice (EA-6) Migration 270 email_action_notices (the ledger, unique per action and key) and tenant_settings.email_policy. Defaults in policy.js, a tenant overlay and overrides by priority, action type and mailbox; validated by PUT /api/email/policy (email.rules). The sweep sends a created notice, an acknowledgement reminder, a due-soon reminder and an overdue ladder to the owner, the backup and roles, through notify() of #624. A new owner, a new due time or a reopen re-arms; nothing else does. Failed sends retry up to 3 times. Business hours, timezone and the weekend follow the policy. 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 26, 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-6 of the email accountability plan (#634, section 6.7). This PR adds reminders and escalation for open email actions. They run on the existing tick and the daily cron, and they use the bell. Their policy is a setting, not code. A repeated run never sends a notice twice.
Stacked on #639 (EA-5) ← #638 ← #637 ← #636 ← #635 ← #619. This PR also contains the commit of #624 (
notify()and migration 253) as a cherry-pick (35b8f28), because the reminders go to one person at a time. When #624 merges intomain, a rebase of this stack drops the duplicate commit. Review only the second commit (6182810) here.Migration 270:
email_action_noticesis the ledger. The sweep sends a notice only after it inserts the ledger row. The key(email_action_id, notice_key)is unique.tenant_settings.email_policyholds the tenant's overlay on the default policy.policy.js:mergeRulespattern). Overrides apply in order and match by priority, action type or mailbox. For example,confirm_paymentcan have its own ladder.notify_on_create; the acknowledgement time; the due-soon time; the overdue ladder (after_minutes,backup,roles); the roles to tell when an action has no owner; and the cap for each run.policyErrors()checks every key. It refuses an unknown key, a bad time or timezone, an unknown role, a ladder that does not grow, and a weekend with no work day.The defaults (plan 6.7):
The not-started and due-soon times are business minutes. The ladder times are calendar time after the due time.
escalation.js:noticesFor()is a pure function. It gives the notices that one action is due now.runSweep()sends the notices throughnotify()(feat(notifications): a notice per person and a bell for every role, on desktop and phone #624), so each recipient gets their own bell row. A failed send is retried on later sweeps, up to 3 attempts. Each run has a cap, and the rest waits for the next sweep.escalation_levelonly goes up. Overdue notices and escalations are audited.Where it runs:
/api/email/sweep(cron only) isemail/sweepin the tick ALWAYS group, andemail/sweep_dailyincron/daily.jsis the backstop.heartbeat-check.jsgives the daily row a 30-hour bound. With the 10-minute default,/api/_healthzwould report 503 for most of every day (the logistics lesson)./api/email/policy: any writer can GET the stored, effective and default policy. PUT needsemail.rules, is validated, and is audited.The engine and the rules now read the policy. Due times use the tenant's timezone, business hours, weekend and due minutes (by priority and action type).
tenant_settingsis read whole, so a migration that is not applied yet makes a column read as missing. It does not stop the sync.No new npm package. No paid service. In-app notices only.
Deploy notes
notify()skips the notice. The ledger then marks it failed and retries it up to 3 times.notify pgrst, 'reload schema';.email_accountability_enabledandemail_actions_mode = 'create'. It needs the 5-minute tick trigger (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/sweeptoCRON_TICK_HANDLERS. The daily backstop runs on Vercel's own cron.PUT /api/email/policy { policy: { ... } }. For a Saturday work day:{ "business_hours": { "weekend": ["Sun"] } }.Tests
src/v3-app/api-email-escalation.test.js(24 tests):observemode sends nothing.notify()from feat(notifications): a notice per person and a bell for every role, on desktop and phone #624: the users and the role members each get their ownadmin_notificationsrow (recipient_user_id).Mutation check: I broke each rule, ran the file and restored the code. All 21 mutations failed the tests. The mutations:
observetenants swept;One mutation ("closed items notified") first survived, because the sweep's query also filters closed items. I added a direct test of the pure function.
Gates:
npm run check: pass.npm run lint: 0 errors. The new files add no warnings.npm run build: pass.npm run verify: pass. I restored the unrelated rewrites of the audit docs.npm run eval:golden: pass.NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 637 files, 7,661 tests, all pass. This count includes the feat(notifications): a notice per person and a bell for every role, on desktop and phone #624 tests.Not covered
sendEmailcould add email later, behind a policy key.business-time.jscan readholiday_calendarwhen a tenant needs it.claimed(the process died between the claim and the send) is never sent again. This is safe against duplicates, but a notice can be lost.🤖 Generated with Claude Code