svc-tenders Server Helper Inventory

Purpose

This note records the post-Sprint-19 helper inventory for services/svc-tenders/src/server.ts.

The goal is truthful classification, not forced movement.

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

Helpers that stayed in server.ts

Auth / session helpers

VERIFIED, REAL

These remain in server.ts because they are still service-shell auth concerns.

1. requireServiceAuth

• Current role: shared auth gate for service routes
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: depends on token parsing, JWT verification, config, and principal resolution

2. verifyAccessToken

• Current role: JWT verification and access-claim validation
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: tightly coupled to service-shell auth flow

3. extractBearerToken

• Current role: bearer token extraction
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: small auth-shell helper used only by requireServiceAuth

4. resolvePrincipal

• Current role: upstream /auth/me principal resolution
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: service-shell auth integration

5. parseAuthMePrincipal

• Current role: shape validation for resolved principal payload
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: private auth-shell helper used only by resolvePrincipal

6. requireActivePrincipal

• Current role: active-principal gate used by vacancy/accommodation routes
• Classification: auth/session helper
• Stayed or moved: stayed
• Why: still a shared route-shell auth helper across multiple route groups

Shared parser / query helpers

VERIFIED, REAL

These remain in server.ts because they are still reused across many route groups.

7. parsePositiveInt

• Current role: bounded positive integer parsing with fallback
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: used broadly across route support builders

8. parsePositiveNumber

• Current role: positive float parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: currently shared by ICPI and general service-shell parsing

9. parseOptionalString

• Current role: normalized optional string parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: broadly shared

10. parseOptionalUpper

• Current role: uppercase-normalized string parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: broadly shared

11. parseOptionalBoolean

• Current role: boolean query parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: used by tender/auction support builders after Sprint 19

12. parseOptionalInt

• Current role: optional integer parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: broadly shared

13. clampPositiveInt

• Current role: bounded integer clamping
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: broadly shared by KES/ICPI and other route groups

14. getFirstQueryValue

• Current role: normalizes Express query values before parsing
• Classification: parser/query helper
• Stayed or moved: stayed
• Why: low-level shared parser helper

Broad but still transitional helpers

VERIFIED, TRANSITIONAL

These still live in server.ts because they are shared or config-coupled enough that no narrower destination is obvious yet.

15. parseTenderListOptions

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: obvious tender-route support logic

16. parseAuctionListOptions

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: obvious auction-route support logic

17. parseRankingScope

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: shared tender/auction ranking parser with an obvious support-module home

18. extractDetails

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: shared vacancy/accommodation detail extraction with an obvious support-module home

19. resolveIntentId

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: declaration/tender request intent normalization with an obvious support-module home

20. runMulterSingle

• Current role: none in server.ts after Sprint 19
• Classification: removed from server.ts
• Stayed or moved: moved
• Why: declaration upload bridge with an obvious declaration-support home

KES-specific boundary helpers

VERIFIED, REAL

21. ensureThirdPartyKycBoundary

• Current role: blocks raw sensitive KYC payloads in third-party mode
• Classification: KES-specific boundary helper
• Stayed or moved: stayed
• Why: KES boundary check with config-dependent runtime behavior

22. verifyIncomingSignatureGate

• Current role: payload-signature verification gate
• Classification: KES-specific boundary helper
• Stayed or moved: stayed
• Why: KES/runtime boundary helper tied to config and crypto verification

Helpers moved out of server.ts in Sprint 18

Moved to routes/support/accommodationRouteSupport.ts

VERIFIED

• toAccommodationUnitType
• parseAccommodationPrice
• splitAccommodationLocation
• toPublicAccommodationSummary
• toPublicAccommodationDetail
• mapAccommodationMutationError

Why:

• all were accommodation-route-local support/mapping behavior
• their destination was obvious and low-risk

Moved to routes/support/tenderRouteSupport.ts

VERIFIED

• toTenderSummary
• toTenderDetail
• toTenderPortalDetail

Why:

• these were tender-route-local mapping helpers
• they only existed to satisfy tender route support

Moved to routes/support/vacancyRouteSupport.ts

VERIFIED

• hasVacancyPostingCapability
• hasVacancyApplicationCapability
• normalizePermissions
• mapVacancyMutationError

Why:

• these were vacancy-route-local support helpers
• their destination was obvious inside the vacancy support builder

Moved to routes/support/declarationRouteSupport.ts

VERIFIED

• getAuctionDeclarationCapabilities
• hasAuctionDeclarationCapability
• canCheckAuctionDeclaration
• getTenderDeclarationCapabilities
• hasTenderDeclarationCapability
• canCheckTenderDeclaration
• parseAuctionDeclarationEvidenceGroupKey
• parseTenderDeclarationEvidenceGroupKey

Why:

• these are declaration-route-local capability/evidence helpers
• their destination was obvious inside declaration support

Helpers moved out of server.ts in Sprint 19

Moved to routes/support/detailExtractionSupport.ts

VERIFIED

• extractDetails

Why:

• shared by vacancy and accommodation route support only
• its destination was obvious without inventing a generic helpers bucket

Moved to routes/support/requestIntentSupport.ts

VERIFIED

• resolveIntentId

Why:

• shared only by tender/declaration route support
• it is no longer a true service-shell concern

Moved to routes/support/rankingScopeSupport.ts

VERIFIED

• parseRankingScope

Why:

• shared only by tender/auction list-option parsing
• it is route-support-local, not a generic shell parser

Moved to routes/support/declarationUploadSupport.ts

VERIFIED

• runMulterSingle (now exposed as buildRunMulterSingle(...))

Why:

• still declaration-upload-specific
• the declaration evidence upload middleware remains configured in server.ts, but the runner wrapper no longer needs to live there

Moved to routes/support/tenderRouteSupport.ts

VERIFIED

• parseTenderListOptions

Why:

• obvious tender-route support logic
• depends only on tender-local parsing plus shared parser inputs

Moved to routes/support/auctionRouteSupport.ts

VERIFIED

• parseAuctionListOptions

Why:

• obvious auction-route support logic
• depends only on auction-local parsing plus shared parser inputs

Dead or stale residue

VERIFIED

No standalone dead helper blocks were found in Sprint 19.

The only direct code cleanup in server.ts beyond helper relocation was removal of now-unused repository type imports that had been kept only for the old in-file helper bodies.

Result

After Sprint 19, the helper surface still in server.ts is easier to justify:

• auth/session shell helpers remain together
• low-level parser/query helpers remain together
• KES boundary helpers remain together
• tender/auction/declaration/vacancy/accommodation-local helper bodies no longer live in the service shell

What remains transitional/shared is explicit rather than silently mixed.