From d86cd4bfba9ddaaa8f116ac51fa8c3d2e5303894 Mon Sep 17 00:00:00 2001
From: Randy Hammond <revtex@gmail.com>
Date: Mon, 27 Apr 2026 02:35:16 +0000
Subject: [PATCH 1/2] feat(frontend): migrate REST/audio/SW to /api/v1

The frontend has been carrying legacy /api/* deprecation traffic since
the native v1 surface landed. Move every client-side caller over to v1
so production logs stop showing self-inflicted hits in the legacy-usage
report:

- RTK Query base URL flips to /api/v1
- /api/v1/listener/tg-selection (was /api/auth/tg-selection)
- /api/v1/admin/radioreference/preview (was /admin/radioreference/preview/csv)
- /api/v1/admin/legacy-usage (was /v1/admin/legacy-usage relative to /api)
- raw fetch() in main.tsx auth-recovery and ToolsPanel Swagger session
- audio download URLs in player.ts, BookmarksPanel, SearchPanel
- service worker passthrough regex accepts both /api/v1/{calls,shared}
  and the legacy variants during the transition window
- vite dev proxy forwards /api/v1/ws WebSocket upgrades

Legacy /api/* routes remain available with deprecation headers for
external consumers; this only moves the embedded frontend.

All 201 vitest specs pass. tsc clean. Backend unchanged.
---
 CHANGELOG.md                                       | 1 +
 frontend/src/app/api.ts                            | 4 ++--
 frontend/src/app/slices/admin/adminSlice.ts        | 2 +-
 frontend/src/app/slices/shared/authSlice.ts        | 4 ++--
 frontend/src/components/admin/ToolsPanel.tsx       | 4 ++--
 frontend/src/components/scanner/BookmarksPanel.tsx | 4 ++--
 frontend/src/components/scanner/SearchPanel.tsx    | 2 +-
 frontend/src/main.tsx                              | 2 +-
 frontend/src/services/audio/player.ts              | 4 ++--
 frontend/src/types/api.ts                          | 2 +-
 frontend/sw.ts                                     | 8 +++++---
 frontend/vite.config.ts                            | 1 +
 12 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0c337bb..8cbf8bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Frontend now talks to the native `/api/v1/*` surface for every REST call (RTK Query base URL, raw `fetch()` for audio downloads and silent token refresh, the service-worker passthrough rules, the dev-server proxy, and the Swagger UI bootstrap). Tg-selection moves from `/api/auth/tg-selection` to `/api/v1/listener/tg-selection`; RadioReference CSV preview moves to `/api/v1/admin/radioreference/preview`; legacy-usage report is consumed at `/api/v1/admin/legacy-usage`. Legacy `/api/*` routes remain available for non-frontend clients with the existing deprecation headers.
 - API-key authentication on `/api/v1/*` upload routes accepts only `Authorization: Bearer <api-key>`; the legacy `X-API-Key` header, `?key=` query parameter, and `key=` form field continue to work on legacy routes only. JWT-shaped Bearer tokens on v1 API-key routes are rejected with `invalid_credentials`.
 
 ## [1.2.1] — 2026-04-25
diff --git a/frontend/src/app/api.ts b/frontend/src/app/api.ts
index bf08318..87f394b 100644
--- a/frontend/src/app/api.ts
+++ b/frontend/src/app/api.ts
@@ -12,7 +12,7 @@ import type {
 } from "@/types";
 
 const rawBaseQuery = fetchBaseQuery({
-  baseUrl: "/api",
+  baseUrl: "/api/v1",
   prepareHeaders: (headers, { getState }) => {
     const state = getState() as { auth: { token: string | null } };
     const token = state.auth?.token;
@@ -149,7 +149,7 @@ export const api = createApi({
       providesTags: ["Bookmarks"],
     }),
     getLegacyUsage: builder.query<LegacyUsageResponse, void>({
-      query: () => "/v1/admin/legacy-usage",
+      query: () => "/admin/legacy-usage",
       providesTags: ["LegacyUsage"],
     }),
   }),
diff --git a/frontend/src/app/slices/admin/adminSlice.ts b/frontend/src/app/slices/admin/adminSlice.ts
index 180b3be..2dc357f 100644
--- a/frontend/src/app/slices/admin/adminSlice.ts
+++ b/frontend/src/app/slices/admin/adminSlice.ts
@@ -75,7 +75,7 @@ const adminApi = api.injectEndpoints({
     // ── RadioReference CSV preview (multipart file upload) ──
     rrPreviewCSV: builder.mutation<RRPreviewResponse, FormData>({
       query: (body) => ({
-        url: "/admin/radioreference/preview/csv",
+        url: "/admin/radioreference/preview",
         method: "POST",
         body,
       }),
diff --git a/frontend/src/app/slices/shared/authSlice.ts b/frontend/src/app/slices/shared/authSlice.ts
index 69c9aad..88f4c4b 100644
--- a/frontend/src/app/slices/shared/authSlice.ts
+++ b/frontend/src/app/slices/shared/authSlice.ts
@@ -110,14 +110,14 @@ const authApi = api.injectEndpoints({
       { disabledTGs: number[]; avoidList?: AvoidEntry[] },
       void
     >({
-      query: () => "/auth/tg-selection",
+      query: () => "/listener/tg-selection",
     }),
     updateTGSelection: builder.mutation<
       { ok: boolean },
       { disabledTGs: number[]; avoidList: AvoidEntry[] }
     >({
       query: (body) => ({
-        url: "/auth/tg-selection",
+        url: "/listener/tg-selection",
         method: "PUT",
         body,
       }),
diff --git a/frontend/src/components/admin/ToolsPanel.tsx b/frontend/src/components/admin/ToolsPanel.tsx
index 7c27db8..0c57e39 100644
--- a/frontend/src/components/admin/ToolsPanel.tsx
+++ b/frontend/src/components/admin/ToolsPanel.tsx
@@ -25,7 +25,7 @@ import { selectToken } from "@/app/slices/shared/authSlice";
 import { useAppSelector } from "@/app/store";
 import RadioReferenceCard from "@/components/admin/RadioReferenceCard";
 
-const SWAGGER_URL = "/api/admin/docs/index.html";
+const SWAGGER_URL = "/api/v1/admin/docs/index.html";
 
 export default function ToolsPanel() {
   const token = useAppSelector(selectToken);
@@ -611,7 +611,7 @@ export default function ToolsPanel() {
               <button
                 className="btn btn-primary btn-sm"
                 onClick={async () => {
-                  const res = await fetch("/api/admin/docs/session", {
+                  const res = await fetch("/api/v1/admin/docs/session", {
                     method: "POST",
                     headers: { Authorization: `Bearer ${token}` },
                   });
diff --git a/frontend/src/components/scanner/BookmarksPanel.tsx b/frontend/src/components/scanner/BookmarksPanel.tsx
index 71c57ab..9d0a4e7 100644
--- a/frontend/src/components/scanner/BookmarksPanel.tsx
+++ b/frontend/src/components/scanner/BookmarksPanel.tsx
@@ -67,7 +67,7 @@ function bookmarkCallToCall(bc: BookmarkCall): Call {
     talkgroupLabel: bc.talkgroupLabel,
     talkgroupName: bc.talkgroupName,
     talkgroupLedColor: bc.talkgroupLed,
-    audioUrl: `/api/calls/${bc.id}/audio`,
+    audioUrl: `/api/v1/calls/${bc.id}/audio`,
   };
 }
 
@@ -103,7 +103,7 @@ export default function BookmarksPanel({
 
   const handleDownload = (bc: BookmarkCall) => {
     const a = document.createElement("a");
-    a.href = `/api/calls/${bc.id}/audio`;
+    a.href = `/api/v1/calls/${bc.id}/audio`;
     a.download = sanitizeDownloadFilename(bc.audioName, `call-${bc.id}.mp3`);
     document.body.appendChild(a);
     a.click();
diff --git a/frontend/src/components/scanner/SearchPanel.tsx b/frontend/src/components/scanner/SearchPanel.tsx
index a5af4bd..68a7bbc 100644
--- a/frontend/src/components/scanner/SearchPanel.tsx
+++ b/frontend/src/components/scanner/SearchPanel.tsx
@@ -501,7 +501,7 @@ export default function SearchPanel({ isOpen, onClose }: SearchPanelProps) {
 
   const handleDownload = useCallback((call: CallSearchResult) => {
     const a = document.createElement("a");
-    a.href = `/api/calls/${call.id}/audio`;
+    a.href = `/api/v1/calls/${call.id}/audio`;
     a.download = sanitizeDownloadFilename(
       call.audioName,
       `call-${call.id}.mp3`,
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index 744dbea..c932a8a 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -18,7 +18,7 @@ import "@/index.css";
 // retry-on-401 plumbing because media-element fetches don't go through it.
 audioPlayer.setAuthRecovery(async () => {
   try {
-    const res = await fetch("/api/auth/refresh", {
+    const res = await fetch("/api/v1/auth/refresh", {
       method: "POST",
       credentials: "include",
     });
diff --git a/frontend/src/services/audio/player.ts b/frontend/src/services/audio/player.ts
index b86275e..30b22a6 100644
--- a/frontend/src/services/audio/player.ts
+++ b/frontend/src/services/audio/player.ts
@@ -26,7 +26,7 @@ declare global {
  * header injection is required.
  */
 function audioUrlFor(call: Call): string {
-  return `/api/calls/${call.id}/audio`;
+  return `/api/v1/calls/${call.id}/audio`;
 }
 
 /**
@@ -237,7 +237,7 @@ class AudioPlayer {
 
   /**
    * Register a callback invoked when an audio fetch fails. The callback
-   * should attempt a silent auth refresh (e.g. POST /api/auth/refresh)
+   * should attempt a silent auth refresh (e.g. POST /api/v1/auth/refresh)
    * and resolve to `true` if it succeeded — in which case the player
    * retries the current call with the new session cookie. Required
    * because <audio src=…> bypasses the RTK Query 401 retry path, so a
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index 59d9b24..4023d4c 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -1,6 +1,6 @@
 // REST request/response envelopes (non-admin).
 
-// Setup status from GET /api/setup/status
+// Setup status from GET /api/v1/setup/status
 export interface SetupStatus {
   needsSetup: boolean;
   publicAccess: boolean;
diff --git a/frontend/sw.ts b/frontend/sw.ts
index 66cdfa3..27e45b9 100644
--- a/frontend/sw.ts
+++ b/frontend/sw.ts
@@ -32,10 +32,12 @@ sw.addEventListener("fetch", (event) => {
   // Pass through audio downloads untouched. Letting the SW intercept
   // these would force-buffer the full body in memory and strip the
   // browser's native Range-request handling that <audio> relies on.
-  // Matches /api/calls/:id/audio and /api/shared/:token/audio.
+  // Matches /api/v1/calls/:id/audio and /api/v1/shared/:token/audio
+  // (and the legacy /api/calls /api/shared variants during the
+  // transition window).
   if (
-    /^\/api\/calls\/\d+\/audio$/.test(url.pathname) ||
-    /^\/api\/shared\/[^/]+\/audio$/.test(url.pathname)
+    /^\/api(?:\/v1)?\/calls\/\d+\/audio$/.test(url.pathname) ||
+    /^\/api(?:\/v1)?\/shared\/[^/]+\/audio$/.test(url.pathname)
   ) {
     return;
   }
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 2be8bb2..6a818d4 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -13,6 +13,7 @@ export default defineConfig({
   },
   server: {
     proxy: {
+      "/api/v1/ws": { target: "ws://localhost:3000", ws: true },
       "/api/ws": { target: "ws://localhost:3000", ws: true },
       "/api": "http://localhost:3000",
       "/ws": { target: "ws://localhost:3000", ws: true },

From e2263b26d6f66ea4c43455ddc4fe9b64ad63a14e Mon Sep 17 00:00:00 2001
From: Randy Hammond <revtex@gmail.com>
Date: Mon, 27 Apr 2026 02:37:50 +0000
Subject: [PATCH 2/2] fix(frontend): move no-control-regex disable to the right
 line

The directive was on the const declaration; ESLint reports it unused
because the actual regex literal sits on the next line. Move the
comment onto the .replace() call that owns the control-class regex.
---
 frontend/src/services/util/downloadFilename.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend/src/services/util/downloadFilename.ts b/frontend/src/services/util/downloadFilename.ts
index e798be6..f9457e0 100644
--- a/frontend/src/services/util/downloadFilename.ts
+++ b/frontend/src/services/util/downloadFilename.ts
@@ -11,8 +11,8 @@ export function sanitizeDownloadFilename(
   // Take only the basename — strip anything that looks like a path.
   const base = name.replace(/^.*[\\/]/, "");
   // Strip control characters and quote/angle-bracket injection attempts.
-  // eslint-disable-next-line no-control-regex
   const cleaned = base
+    // eslint-disable-next-line no-control-regex
     .replace(/[\x00-\x1f\x7f"<>|]/g, "")
     .replace(/^\.+/, "")
     .trim();