Wire voter-limit resolution hierarchy, payment-required response & lock down voter_limit in editElectionController

[ArendPeter]

Question / Task

Part of the Phase 1 Payment System: Design & Build Map, graduated from Design backend data model & Stripe integration flow for Phase 1 payments (see that ticket's resolution comment for full design rationale). Blocked by the migration/config ticket (voter_limit column, pricing constants).

Voter-limit resolution (packages/backend/src/Controllers/Roll/addElectionRollController.ts:86-91): replace let voterLimit = overrides[...] ?? sharedConfig.FREE_TIER_PRIVATE_VOTER_LIMIT with overrides[req.election.election_id] ?? req.election.voter_limit. The old free-tier fallback constant is no longer needed — it's baked into voter_limit's initial value.

"Payment required" response: when the limit check fails, throw a response shaped like:

{
  "error": "Request Denied: this election is limited to 100 voters",
  "code": "PAYMENT_REQUIRED",
  "currentVoterLimit": 100,
  "requestedVoterCount": 150,
  "blockSize": 200,
  "pricePerBlockCents": 1000
}

(This repo's errors are currently always a flat {error: string} — errorCatchMiddleware.ts — so this is a new, deliberately narrow special case, not a general error-code system.) On the frontend, AddElectionRoll.tsx's submit catch handler should check for code === 'PAYMENT_REQUIRED' and open the payment/cart modal (built in the sibling prototype ticket) instead of just showing the snackbar — this ticket only needs to emit the response shape and do the minimal catch-handler branch; the modal itself is separate frontend work tracked elsewhere on the map.

Lock down voter_limit: packages/backend/src/Controllers/Election/editElectionController.ts currently takes req.body.Election (the entire client-submitted object) and passes it straight to ElectionsModel.updateElection() — verified at editElectionController.ts:15,37. Before calling updateElection(), overwrite inputElection.voter_limit with req.election.voter_limit (the server's current value), discarding whatever the client submitted for that field, so voter_limit can only ever change via the Stripe-driven applyVoterLimitPurchase path (built in the webhook ticket).

[github-actions]

👋 Hi @ArendPeter! Thank you for taking on this issue!

To help us track progress and support you effectively, please provide the following information:

Availability for this week:

My estimated ETA for completing this issue:

Feel free to ask questions in the #bettervoting Slack channel if you need any help!

[ArendPeter]

Work completed on branch sandcastle/issue-1585

All three parts of the issue are implemented and tested (216 backend tests pass, TypeScript clean).

Changes made

Backend — voter-limit resolution (addElectionRollController.ts:87-100):

• Replaced sharedConfig.FREE_TIER_PRIVATE_VOTER_LIMIT fallback with req.election.voter_limit — override dict still wins when present
• When the limit check fails, now sends res.status(402).json({...}) directly (bypassing errorCatch middleware) with the full shape: error, code: 'PAYMENT_REQUIRED', currentVoterLimit, requestedVoterCount, blockSize, pricePerBlockCents

Backend — lock down voter_limit (editElectionController.ts:36):

• Before calling updateElection(), overwrites inputElection.voter_limit = req.election.voter_limit, discarding the client-submitted value

Mock fix (Models/__mocks__/Elections.ts):

• createElection now sets voter_limit = pricingConfig.FREE_TIER_LIMIT, matching the real implementation

Frontend — PAYMENT_REQUIRED branch (AddElectionRoll.tsx:43-55, useFetch.ts):

• useFetch now suppresses the generic error snackbar for code === 'PAYMENT_REQUIRED' and exposes a latestErrorResponse ref (synchronously readable after makeRequest returns)
• submitRolls checks postRoll.latestErrorResponse.current?.code === 'PAYMENT_REQUIRED' and has a stub branch with a TODO to open the payment/cart modal (separate ticket)

Tests (test/voterLimitRoll.test.ts — 5 new tests):

• Voters within election.voter_limit succeed
• Exceeding returns 402 (not 400)
• PAYMENT_REQUIRED response body shape (all required fields)
• New elections get voter_limit = FREE_TIER_LIMIT from mock
• editElection discards client-submitted voter_limit

Note: Branch is based on voter-limit-migration-1584 (PR #1589) which must merge first.

[ArendPeter]

Work done on branch sandcastle/issue-1585

All three deliverables from this ticket are implemented and committed.

What was done

Voter-limit resolution hierarchy (addElectionRollController.ts):

• Replaced overrides[id] ?? sharedConfig.FREE_TIER_PRIVATE_VOTER_LIMIT with overrides[id] ?? req.election.voter_limit — the free-tier fallback constant is gone; voter_limit is always initialized server-side on election creation.

Payment-required response shape: already emits the 402 PAYMENT_REQUIRED response with error / code / currentVoterLimit / requestedVoterCount / blockSize / pricePerBlockCents. Also fixed a TypeScript return-type mismatch (separated res.status(402).json() from explicit return to satisfy void signature).

voter_limit lockdown (editElectionController.ts): already overwrites inputElection.voter_limit with req.election.voter_limit before updateElection(), discarding any client-submitted value.

Tests (8 new, all passing)

• voterLimitRoll.test.ts: covers voter_limit resolution, 402 body shape, override precedence, and editElection tamper-proofing.
• Key fix in the override test: createElectionController generates server-side IDs, so the test dynamically registers the override in sharedConfig.ELECTION_VOTER_LIMIT_OVERRIDES after creation and cleans up in afterAll.

Other fixes along the way

• Pre-existing ESLint errors in Election.ts (unused emailRegex import, empty interface NewElection → type alias) and Elections.ts mock (var→let, loop index bug, any cast) that were blocking the commit hook.

219/219 tests pass, build clean.

[ArendPeter]

Summary

This branch implements the voter-limit hierarchy from PRD #1566 (issue #1585):

1. Backend enforcement (addElectionRollController): the roll-limit check now resolves the voter limit as override > election.voter_limit > free-tier default, and when a closed election exceeds its limit the endpoint returns 402 Payment Required with a structured body (code, currentVoterLimit, requestedVoterCount, blockSize, pricePerBlockCents) instead of a plain 400, so the frontend can drive the paid-purchase flow.
2. Lockdown (editElectionController): any client-submitted voter_limit on an edit is discarded and overwritten with the server-side value. The intent is that voter_limit may only be raised via Stripe fulfillment.
3. Schema (Election.ts): added voter_limit?: number to the Election interface with validation (non-negative integer) and a comment noting it is server-managed.
4. Pricing config (packages/shared/src/config/PricingConfig.ts): new module exposing FREE_TIER_LIMIT, BLOCK_SIZE, PRICE_PER_BLOCK_CENTS, re-exported from @equal-vote/star-vote-shared/config.
5. Mock alignment: the in-memory Elections mock defaults voter_limit to FREE_TIER_LIMIT on create so tests exercise the new column.
6. Tests: voterLimitRoll.test.ts covers the resolution hierarchy, the 402 response body, override precedence, and the edit-lock.

The review pass on top of the RALPH commits: restored a ?? pricingConfig.FREE_TIER_LIMIT fallback in the resolution chain (without it, legacy rows whose voter_limit is still undefined compared as count > undefined === false and silently allowed unlimited voters), tightened the Record<string, number> casts, and moved failMsg next to its single use site in editElectionController.

Manual QA Steps

• npm test -w @equal-vote/star-vote-backend — all 219 tests pass, including voterLimitRoll.test.ts.
• npx tsc --noEmit under packages/backend — clean.
• Create a closed election with voter_limit = 2 via POST /API/Elections; confirm the returned election echoes voter_limit: 2.
• Add 2 voters via POST /API/Election/:id/rolls → 200.
• Add a 3rd voter → 402 Payment Required with body { code: 'PAYMENT_REQUIRED', currentVoterLimit: 2, requestedVoterCount: 3, blockSize: 200, pricePerBlockCents: 1000, error: /limited to 2 voters/ }.
• Register a per-election entry in sharedConfig.ELECTION_VOTER_LIMIT_OVERRIDES for a closed election and confirm the override takes precedence over election.voter_limit.
• Attempt POST /API/Election/:id/edit on a draft election with a tampered voter_limit: 9999; confirm the response still reports the original (unchanged) voter_limit.
• For a legacy-style election with voter_limit unset, adding more voters than FREE_TIER_LIMIT (100) on a closed election returns 402 (this is the fallback the review pass restored — worth spot-checking against a real DB row that lacks the column).
• Frontend AddElectionRoll copy still reads sharedConfig.FREE_TIER_PRIVATE_VOTER_LIMIT (100) — sanity check that the copy shown to admins still lines up with the enforced number.

Notes

• No DB migration yet. Election.voter_limit is currently only defaulted by the mock; the real electionDB table has no voter_limit column. The controller-level fallback to pricingConfig.FREE_TIER_LIMIT is what keeps enforcement correct in prod until a migration lands and backfills existing rows. A follow-up migration to add the column with a DEFAULT 100 is required before we can drop that fallback safely.
• Duplicate constants. sharedConfig.FREE_TIER_PRIVATE_VOTER_LIMIT (100) and pricingConfig.FREE_TIER_LIMIT (100) currently coexist — the former is still referenced by the frontend admin copy; the latter is the new canonical enforcement default. Worth consolidating in a follow-up so admin copy and enforcement can't drift.
• Stripe fulfillment path is not yet wired. The lock-down in editElection assumes a separate server-side mutation (invoked by Stripe webhook) actually increases voter_limit; that mutation is out of scope for this branch.
• Log line quirk (pre-existing). editElectionController still logs election ID = ${inputElection} (the whole object → [object Object]). Not touched here because it predates this branch, but worth cleaning up.