[#1403] Frontend-react data layer: HTTP + TanStack Query + OpenAPI codegen (#1428)

* [#1403] Frontend-react data layer: HTTP client + TanStack Query + OpenAPI codegen

HTTP wrapper at src/lib/http.ts handles bearer + CSRF, /api/v1/<resource>
to /api/v1/g/{slug}/<resource> rewriting, single-flight refresh on 401,
and surfaces non-2xx as HttpError so React Query can react via onError.
Storage keys (inventario_token, inventario_csrf_token, inventario_user)
match the legacy Vue frontend so a session survives the dual-bundle
INVENTARIO_FRONTEND switch (#1401).

QueryClient defaults: staleTime 30s, retry 1 (skipped for 4xx).
Providers wraps QueryClientProvider + ReactQueryDevtools (dev only) +
ThemeProvider; main.tsx uses it.

OpenAPI codegen converts go/docs/swagger.json (Swagger 2.0) to OAS3 via
swagger2openapi, then emits src/types/api.d.ts via openapi-typescript.
Exposed as npm run codegen / codegen:check, make codegen-frontend-react
/ codegen-frontend-react-check, and a new frontend-react-codegen
workflow that fails the build on drift.

Sample feature slice at features/session/ proves the layer end-to-end:
useCurrentUser query and an optimistic useLogout mutation with cache
rollback on error.

Tests: 40 (Vitest + MSW v2) covering each prefix rewrite, /auth/*
pass-through, slug encoding, CSRF only on mutations + rotation from
response headers, AbortSignal forwarding, 4xx/5xx HttpError, the full
refresh+retry path, refresh-failure clear+navigate, background
/auth/me 401 non-redirect, and single-flight refresh dedup.

.npmrc pins legacy-peer-deps=true because openapi-typescript@7 declares
peer typescript@^5.x while the scaffold is on TS 6 — the peer is
build-time only and emit goes through openapi-typescript's bundled
compiler, so the mismatch is benign. Drop the flag once
openapi-typescript ships TS 6 support.

Closes #1403.

* [#1403] Document legacy-peer-deps workaround with upstream PR link

The .npmrc workaround is metadata-only — npm ls confirms typescript@6.0.3
is the only version installed. Add a TODO link to openapi-ts/openapi-typescript#2774
so it's clear when the flag can come off.

* [#1403] Address CI failures + Copilot review

- Dockerfile: copy frontend-react/.npmrc into the React builder stage so
  npm ci picks up legacy-peer-deps=true (Build linux/{amd64,arm64} fix).
- ApiResponse helper: try application/vnd.api+json first then fall back
  to application/json, and accept any 2xx status. Most Inventario
  endpoints serve JSON:API, so the previous 'application/json'-only
  shape resolved to never for them.
- useLogout: removeQueries() instead of setQueryData(..., null) so the
  cache stays type-true to the query's CurrentUser shape; consumers see
  data === undefined rather than a surprise null at runtime.
- Drop the meCalls > 1 assertion in the optimistic-logout test — it
  encoded an implementation detail (invalidate-after-remove timing) that
  did not survive the removeQueries switch. New assertion pins the real
  invariant: cache stays cleared after a successful logout.
- Prettier: re-format http.ts, http.test.ts, types/index.ts, generated
  api.d.ts, and the session test (Lint Frontend (React) job fix).

* [#1403] Exclude generated api.d.ts from prettier

The previous commit's prettier sweep reformatted src/types/api.d.ts,
which then disagreed with what scripts/codegen.mjs produces — the
codegen-drift CI job rejected the result.

Add .prettierignore to keep the generator's emit untouched, and
restore api.d.ts to the codegen-true output.

Author: denisvmedia

.github/workflows/frontend-react-codegen.yml

@@ -0,0 +1,42 @@
+name: Frontend React Codegen Drift
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  codegen-drift:
+    name: Check OpenAPI → TS codegen sync
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend-react
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - id: vars
+        uses: ./.github/actions/vars
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ steps.vars.outputs.node_version }}
+          cache: 'npm'
+          cache-dependency-path: frontend-react/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify src/types/api.d.ts is up to date
+        run: npm run codegen:check

Dockerfile

@@ -32,7 +32,9 @@ FROM node:24.14.1-alpine AS frontend-react-builder
 
 WORKDIR /app/frontend-react
 
-COPY frontend-react/package*.json ./
+# .npmrc carries `legacy-peer-deps=true` (openapi-typescript@7's stale TS5
+# peer dec — see frontend-react/.npmrc); without it `npm ci` exits non-zero.
+COPY frontend-react/package*.json frontend-react/.npmrc ./
 
 RUN --mount=type=cache,target=/root/.npm \
     npm ci

Makefile

@@ -237,6 +237,17 @@ lint-frontend-react:
 typecheck-frontend-react:
 	$(CD) $(FRONTEND_REACT_DIR) && npm run typecheck
 
+# Regenerate React frontend's TypeScript types from go/docs/swagger.json.
+# Run after `go tool swag init --output docs` whenever a swagger annotation
+# changes. CI guards against drift via `codegen-frontend-react-check`.
+.PHONY: codegen-frontend-react
+codegen-frontend-react:
+	$(CD) $(FRONTEND_REACT_DIR) && npm run codegen
+
+.PHONY: codegen-frontend-react-check
+codegen-frontend-react-check:
+	$(CD) $(FRONTEND_REACT_DIR) && npm run codegen:check
+
 # Check that all Go entity schema changes have a corresponding migration.
 # Requires POSTGRES_TEST_DSN to point to a PostgreSQL instance that has all migrations applied.
 .PHONY: lint-migrations

frontend-react/.npmrc

@@ -0,0 +1,11 @@
+# openapi-typescript@7.13.0 (latest stable as of 2026-04-29) declares
+# `peerDependencies.typescript: "^5.x"`, but the entire repo runs TypeScript
+# 6.0.3 (frontend/, frontend-react/, e2e/). The peer is build-time only —
+# openapi-typescript emits its .d.ts via its own bundled compiler, our generated
+# types are consumed by *our* TS 6.0.3 — so the mismatch is metadata-only.
+# Verified: `npm ls typescript` shows 6.0.3 everywhere, no parallel TS5 install.
+#
+# Drop this once openapi-ts/openapi-typescript#2774 ("feat: add TypeScript 6
+# support") merges and a release ships:
+#   https://github.com/openapi-ts/openapi-typescript/pull/2774
+legacy-peer-deps=true

frontend-react/.prettierignore

@@ -0,0 +1,7 @@
+# Auto-generated files. Owned by their respective generators; running
+# prettier here just diverges from the codegen output and trips the
+# drift-check CI job.
+src/types/api.d.ts
+dist/
+coverage/
+node_modules/

frontend-react/eslint.config.js

@@ -47,7 +47,7 @@ export default [
     },
   },
   {
-    files: ["vite.config.ts", "vitest.config.ts", "eslint.config.js"],
+    files: ["vite.config.ts", "vitest.config.ts", "eslint.config.js", "scripts/**/*.{js,mjs,ts}"],
     languageOptions: {
       globals: { ...globals.node, ...globals.es2022 },
     },