Skip to content

feat(email): the action and rules API, with one visibility rule (EA-4) - #638

Open
privatejoel wants to merge 1 commit into
claude/email-ea3-actionsfrom
claude/email-ea4-api
Open

privatejoel wants to merge 1 commit into
claude/email-ea3-actionsfrom
claude/email-ea4-api

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

EA-4 of the email accountability plan (#634, sections 6.5 and 6.8). This PR adds the API for email actions and rules, with one visibility rule and four new server actions.

Stacked on #637 (EA-3) ← #636 ← #635 ← #619. Merge in that order.

  • Visibility (email-accountability/access.js). A user sees an action in four cases: they own it, they back it up, a mailbox they own received the message (connection_id or seen_connection_ids), or they hold email.view_all. Anyone else gets 404, so they cannot learn that the action exists. The list and the detail use the same rule. viewer and customer_support have no access, because the rows carry mail subjects and senders.
  • GET /api/email_actions:
    • Filters: mailbox, owner (none means unassigned), priority (1-4 or a label), customer, order, state (a status, open by default, closed, overdue or escalated), due_before, due_after and scope=mine.
    • Each row has the names, the PO number, the mailbox address, the reasons, and the derived overdue and escalated flags.
    • The sort is critical first, then by due time.
  • GET /api/email_actions/<id> returns the action and its history from audit_events.
  • PATCH /api/email_actions/<id> takes { version, ... }:
    • status: only a move in store.TRANSITIONS. performed is refused with "record evidence instead" (EA-5). awaiting_verification belongs to the verifier only. A cancel and a reopen need a reason. A reopen starts a new cycle: reopen_count + 1 and escalation_level = 0. When a reviewed action is confirmed, it goes to the person who confirms it, and its business status moves to awaiting_internal.
    • assignee_user_id: the owner can hand the action off. Anyone else needs email.reassign. The new owner must be an approved member. Only a manager can leave an action with no owner.
    • backup_user_id, a priority or action_type correction (with a reason; the requirement follows the type), business_status, and a manual due_at (with a reason; due_source 'manual').
    • version is work_items.version. A stale version is 409 before any write. The write itself is also guarded by the version, so a write that lands between the read and the update is not overwritten.
    • Each change writes audit_events with the before and after values and the reason.
  • /api/email_rules:
    • GET returns the tenant rules and the caller's own rules.
    • POST, PATCH and DELETE are open to any writer for their own rules (scope me). Tenant rules need email.rules.
    • The pattern is checked for each kind. A customer rule must name a customer of this tenant. The effect is checked: the priority label, the action type, and due_hours from 1 to 720.
    • Another user's rule reads as 404. Every change is audited.
  • Server actions, in auth.js SERVER_ACTIONS and rbac.ts ACTIONS with the same roles:
    • email.view_all, email.reassign and email.verify: sales_manager and admin.
    • email.rules: admin.

No migration. No new npm package.

Deploy notes

  1. Merge the stack below this PR first, and apply migrations 252, 267 and 268.
  2. Nothing to configure. The UI that calls these endpoints is EA-7.

Tests

src/v3-app/api-email-actions-api.test.js (21 tests):

  • [15] Access:
    • Each user sees exactly their own, backup and mailbox actions.
    • A manager sees all of them. scope=mine narrows the list to the manager's own.
    • Another user's action is 404 for read and for change, and nothing changes.
    • viewer and customer_support get 403.
  • Filters: overdue, priority, unassigned, mailbox (including seen_connection_ids), customer, closed and escalated. A row carries the names, the PO number and the derived flags, and the critical rows come first.
  • Changes:
    • Start, with the version bump and the audit row.
    • A stale version is 409, and the email-side fields stay unchanged.
    • A write that lands between the read and the update is not overwritten.
    • Nobody can set performed or awaiting_verification by hand.
    • A cancel needs a reason. A reopen needs a reason and resets the escalation.
    • When a reviewed action is confirmed, it gets an owner and the business clock starts.
    • Hand-off by the owner works. A backup cannot reassign. A manager can reassign. A non-member cannot be the owner.
    • A correction needs a reason, and the requirement follows the type.
    • The business outcome can be set, and a manual due time needs a reason.
    • GET returns the history.
  • Rules: own rules and tenant rules, the checks on the pattern and the effect (including a customer of another tenant), the visibility of other users' rules, and the edit rights.
  • Parity: SERVER_ACTIONS and rbac.ts ACTIONS agree for the 4 actions, and a sales engineer holds none of them.

Mutation check: I broke each rule, ran the file and restored the code. All 21 mutations failed the tests:

  • view_all ignored on the detail;
  • the detail open to any writer;
  • the list ignores the mailbox that saw the message;
  • the list ignores the backup;
  • the list shows everything to a writer;
  • performed set by hand;
  • a cancel without a reason;
  • no early version check;
  • no version guard on the write;
  • anyone can reassign;
  • a non-member as the owner;
  • a reopen keeps the escalation;
  • a confirm does not assign;
  • a correction without a reason;
  • a viewer can list;
  • any writer adds a tenant rule;
  • other users' rules are listed;
  • the effect is not checked;
  • a customer of another tenant;
  • a writer changes a tenant rule;
  • a server action drops a role.

Two of these mutations first survived. I made those tests stronger: the error message for "performed", and the race between the read and the update.

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: 630 files, 7,574 tests, all pass.
  • PR fix(rbac): the UI role comes from the server role, and fails closed to viewer #633 is not merged yet, so the new tests set the role on the server context only. They do not depend on installRbac.

Not covered

  • The PATCH writes two tables in two steps: the email side first, then the work item, guarded by the version. A stale version is refused before either write. A failure between the two steps leaves at most a counter or the business status changed, with no state change and no audit row.
  • shortcut: the list reads at most 500 candidates for each source, then filters. Move the filters into the query when a tenant has more open actions than that.
  • An action type that would duplicate another action on the same message returns 409 through the unique key. The memory fake does not enforce unique keys, so no test covers this case.
  • No UI. EA-7 adds it.

🤖 Generated with Claude Code

GET /api/email_actions with filters, GET and PATCH /api/email_actions/<id>
(transitions, hand-off and reassign, corrections with a reason, business
outcome, manual due time, optimistic version), /api/email_rules (tenant
rules for email.rules, own rules for any writer). A user sees an action
they own, back up, or whose message reached their mailbox; email.view_all
sees all. email.view_all, email.reassign, email.verify and email.rules on
both the server and the client tables.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 23, 2026 2:55am UTC

This branch was successfully deployed

1 active deployment
Preview — b227b391 Deployed Oct 23, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant