Requirements: Utility Extraction

Requirements for Part 2 of Component Preparation.

Group A — API Route Infrastructure

REQ-UE-A01: generateRequestId Function

A generateRequestId() function must be exported from src/lib/api-route-utils.ts. It must return a string in valid UUID v4 format. Successive calls must produce distinct values.

REQ-UE-A02: parseUpstreamResponse Function

A parseUpstreamResponse(response: Response) function must be exported from src/lib/api-route-utils.ts. When the upstream response has content-type application/json, it must return parsed JSON. For all other content types, it must return { raw: text } where text is the response body as a string.

REQ-UE-A03: forwardAsNextResponse Function

A forwardAsNextResponse(upstream: Response, data: unknown) function must be exported from src/lib/api-route-utils.ts. It must return a NextResponse with:

HTTP status 200 when upstream status is 2xx
The upstream HTTP status when upstream status is 4xx or 5xx
Body containing ok, status, and data fields

REQ-UE-A04: Route Handler Migration

All API route handlers under src/app/api/arda/ that contain inline generateGuid, content-type parsing, or response-forwarding logic must be updated to import and use the functions from src/lib/api-route-utils.ts. Inline implementations of these patterns must be removed.

REQ-UE-A05: API Route Unit Tests

src/lib/api-route-utils.test.ts must test the three exported functions with the cases described in the goal Group A testing section.

Group B — Lookup Response Parsing

REQ-UE-B01: Parameterized Lookup Helper

A lookupField(endpoint, fieldName, params) function must be created in src/lib/ardaClient.ts that encapsulates the shared lookup logic:

Build URL with query parameters
Fetch with auth headers
Parse response with triple-fallback: plain string array, named-field array (data[fieldName]), results[].name fallback
Return string[] (empty array on missing/empty data)

REQ-UE-B02: Lookup Function Consolidation

The 9 public lookup functions (lookupSuppliers, lookupUnits, lookupTypes, lookupSubtypes, lookupUseCases, lookupFacilities, lookupDepartments, lookupLocations, lookupSublocations) must delegate to lookupField. Their public signatures must remain unchanged.

REQ-UE-B03: Lookup Helper Unit Tests

Focused tests for lookupField must be added covering: plain string array response, named-field response, results[].name fallback, and empty/missing data.

Group C — JWT / Token Consolidation

REQ-UE-C01: Replace Inline JWT Decode

All inline JWT decode patterns (JSON.parse(atob(token.split('.')[1]))) in authThunks.ts, tokenRefresh.ts, AuthInit.tsx, and AuthContext.tsx must be replaced with imports of decodeJWTPayload from src/lib/jwt.ts.

REQ-UE-C02: Replace Inline JWT Format Validation

All inline JWT format validation (token.split('.').length !== 3) in src/lib/ardaClient.ts and other files must be replaced with a shared validation function from src/lib/jwt.ts.

REQ-UE-C03: Existing Tests Pass

All existing tests in jwt.test.ts, authThunks test files, tokenRefresh test files, and AuthInit test files must continue to pass without modification.

Group D — Safe Serialization

REQ-UE-D01: safeJsonParse Function

A safeJsonParse<T>(text: string, fallback: T): T function must be exported from src/lib/storage.ts. It must return parsed JSON for valid input and the fallback value for malformed or empty input, without throwing.

REQ-UE-D02: getStorageItem Function

A getStorageItem<T>(key: string, fallback: T): T function must be exported from src/lib/storage.ts. It must read from localStorage, parse as JSON, and return the fallback when the key is missing or the value is malformed.

REQ-UE-D03: setStorageItem Function

A setStorageItem(key: string, value: unknown): void function must be exported from src/lib/storage.ts. It must serialize the value as JSON and store it. It must not throw on localStorage quota errors.

REQ-UE-D04: Storage Unit Tests

src/lib/storage.test.ts must test all three functions with the cases described in the goal Group D testing section.

Group E — Error Handling

REQ-UE-E01: extractErrorMessage Function

An extractErrorMessage(error: unknown): string function must be exported from src/lib/errors.ts. It must:

Return .message for Error instances
Return the string directly for string inputs
Return String(error) for all other types

REQ-UE-E02: Error Handling Unit Tests

src/lib/errors.test.ts must test extractErrorMessage with Error instances, string errors, numbers, objects, null, and undefined.

Group F — Formatters

REQ-UE-F01: formatDate Function

A formatDate(date: string | undefined): string function must be exported from src/lib/formatters.ts. It must format an ISO date string to locale date and return '-' for undefined.

REQ-UE-F02: formatDateTime Function

A formatDateTime(date: string | undefined): string function must be exported from src/lib/formatters.ts. It must format an ISO date string to locale date+time and return '-' for undefined.

REQ-UE-F03: formatCurrency Function

A formatCurrency(value: Money | undefined): string function must be exported from src/lib/formatters.ts. It must format as $X.XX CUR and return '-' for undefined or null value.

REQ-UE-F04: formatQuantity Function

A formatQuantity(quantity: Quantity | undefined): string function must be exported from src/lib/formatters.ts. It must format as amount unit and return a sensible default for undefined.

REQ-UE-F05: Formatter Unit Tests

src/lib/formatters.test.ts must test all four functions with the cases described in the goal Group F testing section.

Group G — Environment Constants

REQ-UE-G01: Client Environment Constants

src/lib/env-spa.ts must export:

IS_PRODUCTION: boolean — true when process.env.NEXT_PUBLIC_DEPLOY_ENV === 'PRODUCTION'
IS_STAGE: boolean — true when process.env.NEXT_PUBLIC_DEPLOY_ENV === 'STAGE'
IS_MOCK_MODE: boolean — true when process.env.NEXT_PUBLIC_MOCK_MODE === 'true'

REQ-UE-G02: Debug Logging Migration

The debugLog, debugError, debugWarn functions in src/lib/utils.ts must import IS_STAGE from src/lib/env-spa.ts instead of reading process.env.NEXT_PUBLIC_DEPLOY_ENV directly.

REQ-UE-G03: Environment Constants Unit Tests

src/lib/env-spa.test.ts must validate that the exported constants reflect the corresponding environment variable values.

Cross-Cutting Requirements

REQ-UE-X01: Public API Preservation

Public API signatures of refactored modules (ardaClient.ts, jwt.ts, utils.ts) must remain unchanged. Existing consumers must compile without edits beyond import paths.

REQ-UE-X02: No Existing Test Modification

Existing test files must not be modified except where a group explicitly requires adding cases to an existing suite (Group B).

REQ-UE-X03: All Checks Pass Per Group

After completing each group, the following must pass:

npm run lint
npx tsc --noEmit
npx jest --no-coverage --watchAll=false --forceExit
npm run build

REQ-UE-X04: CHANGELOG Update

CHANGELOG.md must be updated with entries documenting the utility extractions.