The Client Layer

// lib/api/client.ts
const BASE = process.env.NEXT_PUBLIC_API_URL

export class ApiError extends Error {
  constructor(readonly status: number, readonly code: string,
              readonly fields?: Record<string, string>,
              readonly requestId?: string) {
    super(code)
  }
}

export async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(`${BASE}${path}`, {
    ...init,
    credentials: 'include',                 // cookies, every time
    headers: {
      'Content-Type': 'application/json',
      'X-Request-Id': crypto.randomUUID(),  // correlate with server logs
      ...init.headers,
    },
  })

  if (res.status === 204) return undefined as T

  const body = await res.json().catch(() => null)

  if (!res.ok) {
    const e = body?.error ?? {}
    throw new ApiError(res.status, e.code ?? 'unknown', e.fields,
                       res.headers.get('X-Request-Id') ?? undefined)
  }
  return body as T
}

// Callers never see a status code:
export const listProblems = (p: ListParams) =>
  api<Paged<Problem>>(`/problems?${new URLSearchParams(p)}`)

# FastAPI serves OpenAPI for free at /openapi.json
npx openapi-typescript http://localhost:8000/openapi.json \
  -o src/generated/api.ts

// Then the types come from the server, not from memory
import type { paths } from '@/generated/api'
type Problem =
  paths['/problems/{slug}']['get']['responses']['200']['content']['application/json']

// The failure this prevents: the backend renames a field, the
// frontend keeps compiling against a stale hand-written interface,
// and the bug reaches production as an undefined.

// Make drift a build failure, not a habit:
#   npm run generate:api && git diff --exit-code src/generated/
// A red CI run is how you learn the contract moved.

// Spring Boot: springdoc-openapi publishes the same schema.
// Generators exist for clients too (openapi-generator), though the
// types-only approach keeps the runtime code yours.

// Committing the generated file is the usual choice — but it goes
// stale silently if nobody regenerates, which is exactly why the
// CI check matters.

// With cookies there is nothing to attach — credentials: 'include'
// in the wrapper is the whole story, and the token never touches JS.

// With a bearer token, the wrapper owns it (see the refresh concept
// for the concurrent-401 handling):
function withAuth(init: RequestInit): HeadersInit {
  const token = getAccessToken()            // in memory, not localStorage
  return token ? { ...init.headers, Authorization: `Bearer ${token}` }
               : init.headers ?? {}
}

// Server-side calls in Next.js need cookies forwarded explicitly —
// there is no browser to attach them:
import { cookies } from 'next/headers'
const res = await fetch(`${API}/me`, {
  headers: { cookie: cookies().toString() },
  cache: 'no-store',
})
// Forgetting this is why a server component sees an anonymous user
// while the same call works in the browser.

// Other things that belong in the wrapper, not in components:
//   - a timeout (AbortSignal.timeout(10_000))
//   - a request id, and reading it back off error responses
//   - locale or tenant headers
//   - a 401 -> refresh -> retry once policy
//   - dev-only logging of slow requests

// And keep the layers separate:
//   client.ts   transport: URL, auth, errors, retries
//   api/*.ts    one function per endpoint, typed
//   hooks/*.ts  useQuery/useMutation wrapping those functions
// Components import the hooks and nothing below them.