feat(frontend): migrate REST/audio/SW to /api/v1

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

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"],
     }),
   }),

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,
       }),

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,
       }),

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}` },
                   });

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();

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`,

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",
     });

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

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();

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;

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;
   }

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 },