Skip to content

Plan: Include Parent mgIds in API Responses

Status: Done — formatter + API data availability + health engine + enforcement doc shipped. Web: popover header qualified; staff table left columnar (resource/location columns present) per decision.

Spec: spec.md. Convention: any response exposing a flat entity's mgId also exposes its parent chain's mgIds (raw fields; display layer joins).

Phase 0 — shared helpers

  • [x] formatMgIdRef + formatReservationRef in packages/shared-utils/src/resources/mg-id-ref.ts (+ test). Two tokens — resource mgId already embeds location.

Phase 1 — triggering surfaces (reservations + health)

  • [x] reservations/route.ts — lean branch (select + response) and staff/payment branch (response): resource.mgId + location.mgId added.
  • [x] reservations/[id]/route.ts: mgId added to location + resource selects (response spreads whole objects).
  • [x] Reservation-health engine: resourceMgId threaded through ReservationHealthResult; reservation-health-cron.ts now emits a qualified refs array (was bare mgIds). Covers MG-API-4F/4K/4M alert quality.
  • [x] reservation-lookup.ts script Ref line uses formatReservationRef.

Phase 2 — remaining flat-entity exposures

  • [x] payments/route.ts: reservation owner's resource.mgId + location.mgId and waitlistEntry.location.mgId added.
  • [x] dashboard/reservations, dashboard/stats — already compliant (expose only location mgId, self-qualifying; no flat-entity mgId orphan).
  • [x] access-codes/format.ts — already compliant (AccessCodeService include already selects resource.mgId alongside the reservation mgId).
  • [x] locations/[id]/route.ts — compliant (exposes resource mgId, self-qualifying, under a known location).
  • [x] Swept mgId: response sites; remaining ctx.mgId hits are email args, not API responses (out of scope).

Phase 3 — display consumers

  • [x] ReservationData (useReservations.ts) gains resource.mgId / location.mgId.
  • [x] ReservationEventPopover header renders formatReservationRef(...). Staff table left columnar (resource/location columns present) per decision; staff detail header already shows labeled resource/location (not an orphan).
  • [x] Sentry alert text now carries the qualified refs array (verified via cron test).

Phase 4 — enforcement

  • [x] Convention added to docs/engineering/architecture/api/response-envelopes.md as a new-endpoint review checklist item.

Notes

  • Additive/backward-compatible; no schema changes; selection + serialization only.
  • Self-qualifying mgIds (resource, group, gate) need nothing — their mgId already locates them.
  • Staff MCP reservation tools don't expose mgIds today; they inherit the fix when they wrap the corrected responses.