# Endpoint builders — replace hardcoded `/api/<service>/...` strings

**Task**: AZ-486_refactor_endpoint_builders
**Name**: Introduce `endpoints.ts` and replace hardcoded API paths
**Description**: Add `src/api/endpoints.ts` exporting typed endpoint builders, replace every hardcoded `/api/<service>/...` string literal in production code with the corresponding builder call, and add a static check that flags new string literals. Closes architecture baseline finding **F7**.
**Complexity**: 5 points
**Dependencies**: AZ-485_refactor_public_api_barrels (F4 lands first so `endpoints` ships through the `src/api` barrel)
**Component**: `01_api-transport` (owner of new file + barrel re-export) + every component that calls `api.*` or `createSSE`: `02_auth`, `03_shared-ui`, `06_annotations`, `07_dataset`, `08_admin`, `09_settings`, `05_flights`
**Tracker**: AZ-486
**Epic**: AZ-447

## Problem

`_docs/02_document/architecture_compliance_baseline.md` Finding **F7** (Medium / Architecture): every `api.*()` and `createSSE()` callsite repeats `/api/<service>/<path>` as a string literal. ~25 hardcoded paths across 11 source files (`src/auth/AuthContext.tsx`, `src/api/client.ts`, `src/features/{admin,settings,annotations,dataset,flights}/**`, `src/components/{FlightContext,DetectionClasses}.tsx`).

Consequences (per ADR-006 Consequences and the baseline doc):
1. Every test fixture must duplicate paths — and MSW handlers, e2e stubs, and unit tests all drift independently.
2. Any nginx-route rename (ADR-006 prefix-strip changes) touches every feature.
3. There is no single source of truth for the wire-contract paths.

`module-layout.md` Verification Needed item references the same observation. Step 4 (testability) deferred this finding to Phase B per the per-finding routing decision.

## Outcome

- A new module `src/api/endpoints.ts` exports a typed `endpoints` object with function-form builders for every path in use today.
- Every callsite of `api.get/post/put/upload/del` and `subscribeSSE`/`createSSE` across `src/**` (excluding `src/api/endpoints.ts` itself and test files) uses an `endpoints.*` call — no string literals matching `/api/<service>/` remain in production code.
- The `endpoints` symbol is re-exported from `src/api/index.ts` (the F4 barrel).
- A new static check `STC-ARCH-02` fails the static profile if any production file (excluding `endpoints.ts`, tests, and MSW handlers) contains a string literal matching `/api/<service>/`.
- Unit tests assert each builder returns the contract-correct URL string.
- MSW handlers and e2e stubs continue to match the exact same URLs — no wire-contract change.
- `_docs/02_document/module-layout.md` adds `endpoints.ts` to the `01_api-transport` Public API and adds `STC-ARCH-02` to the static-check inventory.

## Scope

### Included
- New file `src/api/endpoints.ts` with the `endpoints` object — function form everywhere, e.g.:
  - `endpoints.admin.authRefresh()` → `'/api/admin/auth/refresh'`
  - `endpoints.admin.users()` → `'/api/admin/users'`
  - `endpoints.admin.user(id)` → `` `/api/admin/users/${id}` ``
  - `endpoints.flights.aircrafts()` → `'/api/flights/aircrafts'`
  - `endpoints.flights.liveGps(flightId)` → `` `/api/flights/${flightId}/live-gps` ``
  - `endpoints.annotations.classes()`, `endpoints.annotations.annotations()`, `endpoints.annotations.dataset()`, `endpoints.annotations.datasetBulkStatus()`, `endpoints.annotations.datasetClassDistribution()`, `endpoints.annotations.mediaBatch()`, `endpoints.annotations.settingsSystem()`, `endpoints.annotations.settingsDirectories()`, `endpoints.annotations.settingsUser()`, `endpoints.annotations.detection(query?)`, …
- Update `src/api/index.ts` (barrel from F4) to re-export `endpoints`.
- Replace ~25 hardcoded path literals in:
  - `src/auth/AuthContext.tsx`
  - `src/api/client.ts` (the refresh callsite)
  - `src/features/admin/AdminPage.tsx`
  - `src/features/settings/SettingsPage.tsx`
  - `src/features/annotations/AnnotationsPage.tsx`
  - `src/features/annotations/AnnotationsSidebar.tsx`
  - `src/features/annotations/MediaList.tsx`
  - `src/features/dataset/DatasetPage.tsx`
  - `src/features/flights/FlightsPage.tsx`
  - `src/components/FlightContext.tsx`
  - `src/components/DetectionClasses.tsx`
- Add unit tests in `src/api/endpoints.test.ts` (one assertion per builder verifying the literal URL string — the test file IS the contract).
- Add static check `STC-ARCH-02` to `scripts/run-tests.sh` (ripgrep `'/api/[a-z-]+/'` across `src/**` excluding `endpoints.ts` and `*.test.{ts,tsx}` and `tests/**`).
- Update `_docs/02_document/module-layout.md` `01_api-transport` row to add `endpoints` to Public API and add `STC-ARCH-02` to the static-check inventory.

### Excluded
- F6 (introduce `src/shared/`) — `endpoints.ts` lives at `src/api/endpoints.ts` for now (under `01_api-transport`). When/if F6 lands later it can move to `src/shared/endpoints.ts` with no callsite change (barrel insulates callers).
- The base URL itself (`/api`) — `getApiBase()` already exists in `src/api/client.ts` and is handled separately. `endpoints.ts` returns paths starting with `/api/`; the client prepends the base.
- Tests and MSW handlers — tests CAN use `endpoints.*` for readability, but their hardcoded paths are not in scope of this task's deletion sweep. The static check explicitly exempts test paths.
- `mission-planner/**` — untouched (deferred per F1).
- Any change to wire-contract paths. The literal URL strings produced by builders MUST exactly match the strings currently in code (and exactly match what MSW/e2e stubs intercept today).

## Acceptance Criteria

**AC-1: All current paths have builders**
Given the post-change `src/api/endpoints.ts`,
When the unit test enumerates every builder and asserts the produced URL,
Then every URL currently in source (per the F7 inventory above) is reproduced exactly — character-identical to today's literal.

**AC-2: No hardcoded `/api/<service>/` literals remain in production**
Given the post-change repo,
When `ripgrep "'/api/[a-z-]+/"` runs over `src/**` excluding `src/api/endpoints.ts`, `**/*.test.{ts,tsx}`, and `tests/**`,
Then zero matches are found.

**AC-3: Static gate STC-ARCH-02 fails on a synthetic literal**
Given the post-change static profile,
When a synthetic edit reintroduces `await api.get('/api/admin/users/me')` to any production file,
Then `bash scripts/run-tests.sh --static` exits non-zero with `STC-ARCH-02` named in the failure line.

**AC-4: Static gate STC-ARCH-02 passes on the migrated codebase**
Given the post-change repo,
When `bash scripts/run-tests.sh --static` runs,
Then it exits zero and the static report shows `STC-ARCH-02` as PASS.

**AC-5: Fast profile remains green**
Given the post-change repo,
When `bash scripts/run-tests.sh --fast` runs,
Then it reports the same PASS / SKIP / FAIL counts as the pre-change baseline (163 PASS / 13 SKIP / 0 FAIL plus the new `endpoints.test.ts` PASSes) with zero new failures and zero regressions.

**AC-6: Endpoint builders are exposed through the F4 barrel**
Given the post-change repo,
When any production file imports `{ endpoints }` from `'../api'` (or relative equivalent),
Then the import resolves through `src/api/index.ts` and `endpoints` is the typed object defined in `src/api/endpoints.ts`.

**AC-7: MSW handlers and e2e stubs continue to match**
Given the post-change repo,
When the fast and (deferred-but-runnable) e2e profiles run,
Then every MSW intercept hits its target unchanged — no "intercepted a request without a matching request handler" error appears, confirming character-identical URLs.

## Non-Functional Requirements

**Performance**
- Initial JS bundle gzipped size MUST remain ≤ 2 MB (existing `STC-PERF01`). The `endpoints` object is tree-shakeable per builder; impact ≤ 1 KB.

**Maintainability**
- A nginx-route rename (per ADR-006) requires editing one file (`endpoints.ts`) — validated by AC-2.

**Compatibility**
- Zero wire-contract change (validated by AC-1 character-equality + AC-7 MSW + e2e).

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | Every builder produces the contract-correct URL string | `endpoints.admin.authRefresh()` === `'/api/admin/auth/refresh'`; same for every builder, character-identical |
| AC-1 | Builders that take params interpolate correctly | `endpoints.admin.user('abc')` === `'/api/admin/users/abc'` |
| AC-3 | STC-ARCH-02 fails on synthetic deep-literal | Static profile non-zero, error names `STC-ARCH-02` |
| AC-4 | STC-ARCH-02 passes on migrated codebase | Static profile zero, STC-ARCH-02 PASS row |
| AC-6 | `endpoints` is re-exported from `src/api/index.ts` | `import { endpoints } from 'src/api'` resolves; the imported value is identical to the one in `src/api/endpoints.ts` |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|-------------------------|--------------|-------------------|----------------|
| AC-2 | Repo after migration | `ripgrep "'/api/[a-z-]+/"` over `src/` minus exemptions | Zero matches | Maintainability |
| AC-5 | Fast profile | `scripts/run-tests.sh --fast` | 163 PASS + new `endpoints.test.ts` PASSes / 13 SKIP / 0 FAIL | Compat |
| AC-7 | Fast profile | MSW unhandled-request gate | No "intercepted a request without a matching request handler" errors | Compat |

## Constraints

- Lands AFTER 01_refactor_public_api_barrels (F4). The `endpoints` symbol is re-exported from `src/api/index.ts` (the barrel); without F4, callsites would deep-import from `src/api/endpoints` and reintroduce the F4 violation.
- The literal URLs produced by builders MUST be character-identical to today's literals. AC-1 validates this in unit tests; AC-7 validates it against MSW handlers; the (deferred) e2e profile validates it against the suite-e2e nginx routes.
- All changes land in ONE commit (the static check would otherwise fail on intermediate commits).
- `mission-planner/**` MUST be untouched.

## Risks & Mitigation

**Risk 1: A path literal is missed and remains in source**
- *Risk*: 25 sites is enough for a manual edit to miss one. The miss would not show up in fast tests (MSW intercepts both styles); STC-ARCH-02 is the only gate that catches it.
- *Mitigation*: STC-ARCH-02 is the SINGLE source of truth for "no literals remain". The static profile is run BEFORE commit; commit is blocked if STC-ARCH-02 fails.

**Risk 2: An optional query-string param is missed in the builder API**
- *Risk*: e.g. `endpoints.annotations.detection()` may need to accept an optional `imageId` query string; missing the param forces the caller back to string concatenation, defeating the abstraction.
- *Mitigation*: Inventory the existing callsites BEFORE writing builders. Every callsite's full URL shape (path + query) must map cleanly to one builder. Document the inventory in the batch report.

**Risk 3: F6 lands later and `endpoints.ts` needs to move to `src/shared/endpoints.ts`**
- *Risk*: A future F6 task may move the file.
- *Mitigation*: Acceptable. Callers import from the `src/api` barrel (or whatever barrel ends up re-exporting `endpoints` after the move). A single barrel edit re-routes all consumers. This is exactly the benefit F4 was meant to provide.

## Contract

This task produces the wire-path contract for the UI ↔ nginx layer. The contract surface IS the `endpoints` object as exported from `src/api/endpoints.ts`. The accompanying unit test (`src/api/endpoints.test.ts`) asserts every URL string and serves as the contract documentation — any future path change MUST update both the builder and the test in the same commit.

A standalone contract file at `_docs/02_document/contracts/api-transport/endpoints.md` MAY be added in a follow-up task; for this task the test file is the authoritative contract per `module-layout.md`'s "code-derived documentation" pattern.
