TASK22102: slice1 api contract helper + email/admin pilot

memory-bank/activeContext.md

@@ -2,6 +2,7 @@
 
 ## Current development focus (from recent commits)
 
+- API contract consistency rollout (TASK22102), starting with helper-based response normalization in selected email/admin handlers.
 - Search/case navigation correctness, especially breadcrumb and back-link behavior.
 - My Portal "view all" and DNS application path handling.
 - Welsh/English email behavior for specific notification templates.

memory-bank/change-log.md

@@ -1302,3 +1302,40 @@ Validation:
 Follow-ups:
 
 - Continue same small-batch consistency pattern for remaining endpoint handlers where required-input/logging drift is clear.
+
+---
+
+### CL-035: TASK22102 API contract consistency — Slice 1 (response helper + email/admin pilot)
+
+date: 2026-03-17
+author: Cline
+scope: `pages/api/middleware/apiResponse.js`, `pages/api/email/{notify,getmailinglist}.js`, `pages/api/admin/{getnewappeals_api,getlatestdocuments_api}.js`, `memory-bank/*`
+type: change
+rationale: Start API contract-consistency program with a low-risk pilot slice introducing shared response helpers and replacing raw error passthrough in selected email/admin handlers.
+impact: Improves response contract consistency and prevents raw error payload leakage in pilot handlers while preserving existing success-body compatibility.
+status: completed
+
+Summary:
+
+- Added shared API response helper module:
+    - `pages/api/middleware/apiResponse.js`
+    - `respondSuccess(res, data, status)`
+    - `respondError(res, { status, code, message, details })`
+- Migrated first slice handlers to helper-based responses:
+    - `pages/api/email/notify.js`
+    - `pages/api/email/getmailinglist.js`
+    - `pages/api/admin/getnewappeals_api.js`
+    - `pages/api/admin/getlatestdocuments_api.js`
+- Contract updates in slice:
+    - replaced `res.status(400).json(error)` with structured error envelope
+    - replaced direct `res.status(200).json(...)` with `respondSuccess(...)`
+    - kept success payload shape as existing data object for non-breaking rollout
+
+Validation:
+
+- `npx next lint --file pages/api/middleware/apiResponse.js --file pages/api/email/notify.js --file pages/api/email/getmailinglist.js --file pages/api/admin/getnewappeals_api.js --file pages/api/admin/getlatestdocuments_api.js` -> pass (no warnings/errors)
+
+Follow-ups:
+
+- Slice 2 should migrate remaining email handlers (`getcaseref`, `getall`, `getevents`, `getdocuments`) to helper responses.
+- After email/admin completion, expand to selected high-risk file handlers using same non-breaking helper model.