feat: add provenance fields (CM-1347)

[ulemons]

Summary

Adds repo provenance fields (declaredRepositoryUrl, resolvedRepositoryUrl, repoMappingConfidence) to the root of ContactDetail, returned by /akrites-external/contacts/detail and :batch. Both endpoints already run BEST_REPO_LINK_JOIN but dropped these fields, so integrators had no way to tell which repo a package's security contacts belong to. /packages/detail already exposes the same semantics — this mirrors it so callers see identical field names across both endpoints.

Changes

• services/libs/data-access-layer/src/osspckgs/api.ts: extended AkritesExternalContactDetailRow with declaredRepositoryUrl (via Pick<PackageDbRow, ...>), resolvedRepositoryUrl, and repoMappingConfidence; added the three columns to getContactDetailsByPurls's SELECT — they reuse the r/pr aliases already in scope from BEST_REPO_LINK_JOIN, so no extra rows are scanned.
• backend/src/api/public/v1/packages/akritesExternalContactDetail.ts: added the three fields to AkritesExternalContactDetail and passed them through in toAkritesExternalContactDetail.
• backend/src/api/public/v1/packages/mappers.ts: extracted a toNullableNumber helper (pg-promise returns numeric columns as strings; != null guard avoids coercing null to 0) and reused it in akritesExternalContactDetail.ts, akritesExternalPackageDetail.ts, and getPackage.ts, which previously each inlined the same cast for repoMappingConfidence.
• backend/src/api/public/v1/akrites-external/openapi.yaml: added the three fields to ContactDetail (required, nullable), with descriptions mirroring PackageDetail's provenance wording. Kept them flat at the root (not nested under a provenance object like PackageDetail) per the task spec — ContactDetail's schema is already flagged "shape not final," so nesting/labeling is left as a separate design decision.
• backend/src/api/public/v1/packages/akritesExternalContactDetail.test.ts: added the new fields to the baseRow() fixture and added tests covering present-value passthrough, numeric-string coercion, and null-when-no-repo-link / null-when-no-declared-repository.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Performance improvement
• Chore / dependency update
• Documentation

JIRA ticket

CM-1347

[cursor]

PR Summary

Low Risk
Additive external API fields on read-only endpoints with no auth or query-shape changes; minor refactor of numeric coercion only.

Overview
Akrites external contacts responses now expose which repository security contacts and policy URLs come from, matching the semantics integrators already get on package detail.

ContactDetail (single and batch /akrites-external/contacts/detail) gains three required, nullable root fields: declaredRepositoryUrl, resolvedRepositoryUrl, and repoMappingConfidence. The contacts query already used BEST_REPO_LINK_JOIN but did not SELECT these columns; getContactDetailsByPurls now pulls declared URL from packages and resolved URL plus mapping confidence from the best package_repos link. The mapper passes them through, with repoMappingConfidence normalized via a shared toNullableNumber helper (pg-promise numeric strings, null-safe).

OpenAPI ContactDetail documents the new fields. toNullableNumber replaces duplicated inline Number(...) casts for repoMappingConfidence in package detail and internal getPackage as well. Unit tests cover passthrough, string coercion, and null when there is no repo link or declared repo.

^{Reviewed by Cursor Bugbot for commit eb0c808. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Adds repository provenance to Akrites contact-detail responses.

Changes:

• Selects and maps declared/resolved repository URLs and mapping confidence.
• Documents the fields in OpenAPI.
• Adds mapper tests and centralizes nullable-number conversion.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
services/libs/data-access-layer/src/osspckgs/api.ts	Projects provenance fields from package/repository joins.
backend/src/api/public/v1/packages/mappers.ts	Adds nullable-number conversion helper.
backend/src/api/public/v1/packages/getPackage.ts	Reuses the conversion helper.
backend/src/api/public/v1/packages/akritesExternalPackageDetail.ts	Reuses the conversion helper.
backend/src/api/public/v1/packages/akritesExternalContactDetail.ts	Adds provenance fields to contact responses.
backend/src/api/public/v1/packages/akritesExternalContactDetail.test.ts	Tests provenance mapping and null handling.
backend/src/api/public/v1/akrites-external/openapi.yaml	Documents the new required nullable fields.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.