TASK22229: pilot shared relay forwarding utility

memory-bank/change-log.md

@@ -725,3 +725,42 @@ Validation:
 Follow-ups:
 
 - Optional future auth hygiene (separate guarded slice): replace verbose auth `console.log` diagnostics with structured logger usage once production logging requirements are confirmed.
+
+---
+
+### CL-019: TASK22229 P2-S1 relay forwarding pilot (proxy endpoint cluster)
+
+date: 2026-03-24
+author: Cline
+scope: `pages/api/middleware/relayForwarding.js`, `pages/api/endpoint/{getwatchedcasesproxy_api,getmyrepresentationsproxy_api,getrepresentationsproxy_api,getawaitingsubmissionproxy_api}.js`, `tests/phase21/endpoint-handler-contract.test.cjs`
+type: change
+rationale: Start Priority-2 by piloting a shared relay forwarding helper on a bounded proxy endpoint cluster to reduce duplicated token/hash/header/axios boilerplate while preserving endpoint contracts.
+impact: Maintainability and consistency improvement with no intended behavioral contract changes; error code/status/message and success payload contracts remain unchanged for migrated endpoints.
+status: completed
+
+Summary:
+
+- Added shared relay helper:
+    - `pages/api/middleware/relayForwarding.js`
+    - exports `relayGet({ queryUrl, res, errorResponse, transformData })`
+    - centralizes token fetch, relay URL + hash composition, `azureHeaders`, GET execution, success/error response handling, and logging
+- Migrated pilot endpoint cluster to `relayGet`:
+    - `getwatchedcasesproxy_api.js` (with existing payload transform preserved)
+    - `getmyrepresentationsproxy_api.js`
+    - `getrepresentationsproxy_api.js`
+    - `getawaitingsubmissionproxy_api.js` (with existing payload transform preserved)
+- Updated endpoint contract tests to mock `relayGet` for migrated routes while preserving existing assertions.
+
+Validation:
+
+- `node tests/phase21/api-contract-slice1.test.cjs` -> pass
+    - helper: 4/4
+    - file-handler: 53/53
+    - email-handler: 12/12
+    - endpoint-handler: 152/152
+    - documents-handler: 3/3
+
+Follow-ups:
+
+- P2-S2 rollout: migrate the next relay-heavy endpoint batch onto `relayGet`/shared forwarding utility pattern.
+- P2-S3 hardening: add shared timeout/retry config and redacted structured relay error logging policy.

pages/api/endpoint/getawaitingsubmissionproxy_api.js

@@ -10,16 +10,8 @@
  *         description: Success
  */
 
-import axios from "axios";
+import { respondError } from "../middleware/apiResponse";
-import { azureHeaders } from "../../../actions/core/headers";
+import { relayGet } from "../middleware/relayForwarding";
-import { consoleLogger } from "../../../actions/core/logger";
-import { getToken } from "../../../actions/core/token";
-import { hashAPIPath } from "../../../actions/core/hash";
-import { respondError, respondSuccess } from "../middleware/apiResponse";
-
-const WEBAPI_URL =
-    process.env.RELAY_ROOT ||
-    "https://dev-pedw-ns.servicebus.windows.net/dev-pedw-hc/";
 
 export default async function ApiProxy(req, res) {
     const loggedInUserId = req.query.loggedInUserId;
@@ -35,29 +27,25 @@ export default async function ApiProxy(req, res) {
         });
     }
 
-    try {
+    const queryUrl =
-        const token = await getToken();
+        "incidents?$select=pinswg_environmentalstatementlocation,modifiedon,description,numberofchildincidents,_accountid_value,_customerid_value,_pinswg_associatedlpa_value,_ownerid_value,pinswg_appealcasetype,statuscode,ticketnumber,title, _primarycontactid_value,pinswg_lpareference,pinswg_appellantlastname,pinswg_appellantfirstname,pinswg_appellantagent,pinswg_agentfirstname,pinswg_agentlastname,pinswg_agentcompanyname&$expand=primarycontactid($select=fullname)&$filter=_customerid_value eq " +
-        const queryUrl =
+        loggedInUserId +
-            "incidents?$select=pinswg_environmentalstatementlocation,modifiedon,description,numberofchildincidents,_accountid_value,_customerid_value,_pinswg_associatedlpa_value,_ownerid_value,pinswg_appealcasetype,statuscode,ticketnumber,title, _primarycontactid_value,pinswg_lpareference,pinswg_appellantlastname,pinswg_appellantfirstname,pinswg_appellantagent,pinswg_agentfirstname,pinswg_agentlastname,pinswg_agentcompanyname&$expand=primarycontactid($select=fullname)&$filter=_customerid_value eq " +
+        " and pinswg_appealcasetype ne null&$orderby=createdon desc&$count=true";
-            loggedInUserId +
-            " and pinswg_appealcasetype ne null&$orderby=createdon desc&$count=true";
 
-        const { data } = await axios.get(
+    return relayGet({
-            WEBAPI_URL + queryUrl + hashAPIPath(queryUrl),
+        queryUrl,
-            azureHeaders(token.access_token)
+        res,
-        );
+        transformData: (data) => {
+            data.value.forEach(function (element) {
+                element.pinswg_title = element.title;
+            });
 
-        data.value.forEach(function (element) {
+            return data;
-            element.pinswg_title = element.title;
+        },
-        });
+        errorResponse: {
-
-        return respondSuccess(res, data);
-    } catch (error) {
-        consoleLogger(error);
-        return respondError(res, {
             status: 400,
             code: "AWAITING_SUBMISSION_PROXY_FETCH_FAILED",
             message: "Failed to fetch awaiting submission proxy details"
-        });
+        }
-    }
+    });
 }

pages/api/endpoint/getmyrepresentationsproxy_api.js

@@ -17,16 +17,8 @@
  *         description: Success
  */
 
-import axios from "axios";
+import { respondError } from "../middleware/apiResponse";
-import { azureHeaders } from "../../../actions/core/headers";
+import { relayGet } from "../middleware/relayForwarding";
-import { consoleLogger } from "../../../actions/core/logger";
-import { getToken } from "../../../actions/core/token";
-import { hashAPIPath } from "../../../actions/core/hash";
-import { respondError, respondSuccess } from "../middleware/apiResponse";
-
-const WEBAPI_URL =
-    process.env.RELAY_ROOT ||
-    "https://dev-pedw-ns.servicebus.windows.net/dev-pedw-hc/";
 
 export default async function ApiProxy(req, res) {
     const loggedInUserId = req.query.loggedInUserId;
@@ -42,26 +34,18 @@ export default async function ApiProxy(req, res) {
         });
     }
 
-    try {
+    const queryUrl =
-        const token = await getToken();
+        "pinswg_representationses?$filter= _pinswg_contact_value eq " +
+        loggedInUserId +
+        "&$count=true&$orderby=createdon desc";
 
-        const queryUrl =
+    return relayGet({
-            "pinswg_representationses?$filter= _pinswg_contact_value eq " +
+        queryUrl,
-            loggedInUserId +
+        res,
-            "&$count=true&$orderby=createdon desc";
+        errorResponse: {
-
-        const { data } = await axios.get(
-            WEBAPI_URL + queryUrl + hashAPIPath(queryUrl),
-            azureHeaders(token.access_token)
-        );
-
-        return respondSuccess(res, data);
-    } catch (error) {
-        consoleLogger(error);
-        return respondError(res, {
             status: 400,
             code: "MY_REPRESENTATIONS_PROXY_FETCH_FAILED",
             message: "Failed to fetch my representations proxy details"
-        });
+        }
-    }
+    });
 }

pages/api/endpoint/getrepresentationsproxy_api.js

@@ -17,16 +17,8 @@
  *         description: Success
  */
 
-import axios from "axios";
+import { respondError } from "../middleware/apiResponse";
-import { azureHeaders } from "../../../actions/core/headers";
+import { relayGet } from "../middleware/relayForwarding";
-import { consoleLogger } from "../../../actions/core/logger";
-import { getToken } from "../../../actions/core/token";
-import { hashAPIPath } from "../../../actions/core/hash";
-import { respondError, respondSuccess } from "../middleware/apiResponse";
-
-const WEBAPI_URL =
-    process.env.RELAY_ROOT ||
-    "https://dev-pedw-ns.servicebus.windows.net/dev-pedw-hc/";
 
 export default async function ApiProxy(req, res) {
     const incidentID = req.query.incidentID;
@@ -39,26 +31,18 @@ export default async function ApiProxy(req, res) {
         });
     }
 
-    try {
+    const queryUrl =
-        const token = await getToken();
+        "pinswg_representationses?$filter= _pinswg_case_value eq " +
+        incidentID +
+        "&$count=true&$orderby=createdon desc";
 
-        const queryUrl =
+    return relayGet({
-            "pinswg_representationses?$filter= _pinswg_case_value eq " +
+        queryUrl,
-            incidentID +
+        res,
-            "&$count=true&$orderby=createdon desc";
+        errorResponse: {
-
-        const { data } = await axios.get(
-            WEBAPI_URL + queryUrl + hashAPIPath(queryUrl),
-            azureHeaders(token.access_token)
-        );
-
-        return respondSuccess(res, data);
-    } catch (error) {
-        consoleLogger(error);
-        return respondError(res, {
             status: 400,
             code: "REPRESENTATIONS_PROXY_FETCH_FAILED",
             message: "Failed to fetch representations proxy details"
-        });
+        }
-    }
+    });
 }

pages/api/endpoint/getwatchedcasesproxy_api.js

@@ -17,16 +17,8 @@
  *         description: Success
  */
 
-import axios from "axios";
+import { respondError } from "../middleware/apiResponse";
-import { azureHeaders } from "../../../actions/core/headers";
+import { relayGet } from "../middleware/relayForwarding";
-import { consoleLogger } from "../../../actions/core/logger";
-import { getToken } from "../../../actions/core/token";
-import { hashAPIPath } from "../../../actions/core/hash";
-import { respondError, respondSuccess } from "../middleware/apiResponse";
-
-const WEBAPI_URL =
-    process.env.RELAY_ROOT ||
-    "https://dev-pedw-ns.servicebus.windows.net/dev-pedw-hc/";
 
 export default async function ApiProxy(req, res) {
     const loggedInUserId = req.query.loggedInUserId;
@@ -42,51 +34,48 @@ export default async function ApiProxy(req, res) {
         });
     }
 
-    try {
+    const queryUrl =
-        const token = await getToken();
+        "pinswg_watchlists?$filter= _pinswg_contact_value eq " +
-        const queryUrl =
+        loggedInUserId +
-            "pinswg_watchlists?$filter= _pinswg_contact_value eq " +
+        "&$select=modifiedon,pinswg_appealcasetype,pinswg_watchlistid,_pinswg_watchedcase_value,statuscode,pinswg_representationsubmitted,pinswg_representationtype&$count=true&$orderby=createdon desc&$expand=pinswg_WatchedCase($select=pinswg_AssociatedLPA)";
-            loggedInUserId +
-            "&$select=modifiedon,pinswg_appealcasetype,pinswg_watchlistid,_pinswg_watchedcase_value,statuscode,pinswg_representationsubmitted,pinswg_representationtype&$count=true&$orderby=createdon desc&$expand=pinswg_WatchedCase($select=pinswg_AssociatedLPA)";
 
-        const { data } = await axios.get(
+    return relayGet({
-            WEBAPI_URL + queryUrl + hashAPIPath(queryUrl),
+        queryUrl,
-            azureHeaders(token.access_token)
+        res,
-        );
+        transformData: (data) => {
+            data.value.forEach(function (element) {
+                element.ticketnumber = element.pinswg_WatchedCase.ticketnumber;
+                element.pinswg_title =
+                    element[
+                        "_pinswg_watchedcase_value@OData.Community.Display.V1.FormattedValue"
+                    ];
 
-        data.value.forEach(function (element) {
-            element.ticketnumber = element.pinswg_WatchedCase.ticketnumber;
-            element.pinswg_title =
                 element[
-                    "_pinswg_watchedcase_value@OData.Community.Display.V1.FormattedValue"
-                ];
-
-            element[
-                "_pinswg_associatedlpa_value@OData.Community.Display.V1.FormattedValue"
-            ] =
-                element.pinswg_WatchedCase[
                     "_pinswg_associatedlpa_value@OData.Community.Display.V1.FormattedValue"
-                ];
+                ] =
-            element._pinswg_associatedlpa_value =
+                    element.pinswg_WatchedCase[
-                element.pinswg_WatchedCase._pinswg_associatedlpa_value;
+                        "_pinswg_associatedlpa_value@OData.Community.Display.V1.FormattedValue"
-            element[
+                    ];
-                "_ownerid_value@OData.Community.Display.V1.FormattedValue"
+                element._pinswg_associatedlpa_value =
-            ] =
+                    element.pinswg_WatchedCase._pinswg_associatedlpa_value;
-                element.pinswg_WatchedCase[
+                element[
                     "_ownerid_value@OData.Community.Display.V1.FormattedValue"
-                ];
+                ] =
-            element._ownerid_value = element.pinswg_WatchedCase._ownerid_value;
+                    element.pinswg_WatchedCase[
+                        "_ownerid_value@OData.Community.Display.V1.FormattedValue"
+                    ];
+                element._ownerid_value =
+                    element.pinswg_WatchedCase._ownerid_value;
 
-            delete element.pinswg_WatchedCase;
+                delete element.pinswg_WatchedCase;
-        });
+            });
 
-        return respondSuccess(res, data);
+            return data;
-    } catch (error) {
+        },
-        consoleLogger(error);
+        errorResponse: {
-        return respondError(res, {
             status: 400,
             code: "WATCHED_CASES_PROXY_FETCH_FAILED",
             message: "Failed to fetch watched cases proxy details"
-        });
+        }
-    }
+    });
 }

pages/api/middleware/relayForwarding.js

@@ -0,0 +1,33 @@
+import axios from "axios";
+import { azureHeaders } from "../../../actions/core/headers";
+import { consoleLogger } from "../../../actions/core/logger";
+import { getToken } from "../../../actions/core/token";
+import { hashAPIPath } from "../../../actions/core/hash";
+import { respondError, respondSuccess } from "./apiResponse";
+
+const WEBAPI_URL =
+    process.env.RELAY_ROOT ||
+    "https://dev-pedw-ns.servicebus.windows.net/dev-pedw-hc/";
+
+export const relayGet = async ({
+    queryUrl,
+    res,
+    errorResponse,
+    transformData
+}) => {
+    try {
+        const token = await getToken();
+        const { data } = await axios.get(
+            WEBAPI_URL + queryUrl + hashAPIPath(queryUrl),
+            azureHeaders(token.access_token)
+        );
+
+        return respondSuccess(
+            res,
+            typeof transformData === "function" ? transformData(data) : data
+        );
+    } catch (error) {
+        consoleLogger(error);
+        return respondError(res, errorResponse);
+    }
+};

tests/phase21/endpoint-handler-contract.test.cjs

@@ -533,6 +533,7 @@ test("getwatchedcasesproxy returns LOGGED_IN_USER_ID_REQUIRED when loggedInUserI
     const mod = loadModule("pages/api/endpoint/getwatchedcasesproxy_api.js", {
         respondError: respondErrorMock,
         respondSuccess: respondSuccessMock,
+        relayGet: async () => ({}),
         getToken: async () => ({ access_token: "token" }),
         hashAPIPath: () => "&hash=expected",
         azureHeaders: () => ({}),
@@ -555,6 +556,8 @@ test("getwatchedcasesproxy catch path returns WATCHED_CASES_PROXY_FETCH_FAILED",
     const mod = loadModule("pages/api/endpoint/getwatchedcasesproxy_api.js", {
         respondError: respondErrorMock,
         respondSuccess: respondSuccessMock,
+        relayGet: async ({ res, errorResponse }) =>
+            respondErrorMock(res, errorResponse),
         getToken: async () => ({ access_token: "token" }),
         hashAPIPath: () => "&hash=expected",
         azureHeaders: () => ({}),
@@ -583,6 +586,7 @@ test("getmyrepresentationsproxy returns LOGGED_IN_USER_ID_REQUIRED when loggedIn
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async () => ({}),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),
@@ -608,6 +612,8 @@ test("getmyrepresentationsproxy catch path returns MY_REPRESENTATIONS_PROXY_FETC
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async ({ res, errorResponse }) =>
+                respondErrorMock(res, errorResponse),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),
@@ -637,6 +643,7 @@ test("getrepresentationsproxy returns INCIDENT_ID_REQUIRED when incidentID missi
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async () => ({}),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),
@@ -659,6 +666,8 @@ test("getrepresentationsproxy catch path returns REPRESENTATIONS_PROXY_FETCH_FAI
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async ({ res, errorResponse }) =>
+                respondErrorMock(res, errorResponse),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),
@@ -688,6 +697,7 @@ test("getawaitingsubmissionproxy returns LOGGED_IN_USER_ID_REQUIRED when loggedI
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async () => ({}),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),
@@ -713,6 +723,8 @@ test("getawaitingsubmissionproxy catch path returns AWAITING_SUBMISSION_PROXY_FE
         {
             respondError: respondErrorMock,
             respondSuccess: respondSuccessMock,
+            relayGet: async ({ res, errorResponse }) =>
+                respondErrorMock(res, errorResponse),
             getToken: async () => ({ access_token: "token" }),
             hashAPIPath: () => "&hash=expected",
             azureHeaders: () => ({}),