feat(ui): typed openapi-fetch foundation (fetchClient) + first typed caller (useCustomers)

[ryan-crabbe-berri]

Relevant issues

Linear ticket

N/A

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Type

New Feature

Changes

This adds a typed data-fetching foundation for the dashboard using openapi-fetch on top of the generated schema.d.ts, and migrates one caller onto it.

The client (fetchClient) is used inside ordinary TanStack Query hooks rather than behind a wrapper, so a hook's queryFn calls fetchClient.GET("/path", { params }) and gets path, query, and request-body types straight from the proxy's OpenAPI spec. fetchClient is a module singleton, so its auth middleware runs outside React; a small seam in runtime.ts bridges that. networking registers the mutable base URL, the auth header name, the auth token, and the session-expiry error handler as getters read fresh per request. The token getter reads the session cookie, the same source useAuthorized decodes, so the client's token and the enabled gate that a query is keyed on cannot diverge; nothing is pushed from React state, and AuthContext is untouched. Base URL resolution plus ApiError/deriveErrorMessage are reused from client.ts, so there is no duplicated transport logic, and because the middleware maps any non-2xx to a thrown ApiError after reporting the derived message to that handler, query functions just read .data while the expired-key auto-logout the legacy client wired through onError keeps working

One robustness detail is folded in. The base URL default resolves from NEXT_PUBLIC_BASE_URL so a request still targets the right origin even if it fires before networking registers its fuller getter.

There is deliberately no any escape hatch. The rule is that a caller is migrated only when it is fully typed, so the discipline is enforced by construction rather than by convention. useCustomers is the first caller migrated: it now calls fetchClient.GET("/customer/list"), whose response is typed as CustomerResponse[] from the schema, so the hand-written Customer/CustomersResponse types are deleted. The hand-written ones were also inaccurate (they typed allowed_model_region as a free string where the API only allows "eu" | "us", and carried a budget_id field the table doesn't have), and CustomerResponse is the accurate shape, so the migration both removes hand-maintained types and corrects them. No cast; the schema type flows straight to the one consumer.

The remaining networking helpers are untouched; callers migrate one at a time, each fully typed, in follow-ups. Tests in api.test.ts cover the middleware through the real openapi-fetch pipeline (bearer injection under the registered header name, base URL rebasing, non-2xx mapping to ApiError, body passthrough, and that a non-2xx reports its derived message to the registered error handler while a success does not); runtime.test.ts covers the env-resolved base URL default; and useCustomers's suite asserts it fetches /customer/list, returns the typed list, gates on access token and admin role, and falls back to an empty list on an empty body.

This branch is up to date with litellm_internal_staging. Three items surfaced in review are folded in here rather than deferred: the typed middleware now routes its error through the same session-expiry handler the legacy createApiClient used via onError, so a migrated caller hitting an expired key still triggers the auto-logout; the useCustomers response type tracks CustomerResponse, which is what /customer/list returns after the staging response model was renamed; and the auth token is sourced from the session cookie via a registered getter rather than pushed from AuthContext, which removes a first-load race where a query could fire before AuthContext published the token and get one unauthenticated 401 before a retry.

Screenshots / Proof of Fix

The Customers selector on the Usage page reads through useCustomers, so it exercises the new client end to end. With a proxy running on localhost:4000:

1. Start the proxy: python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver 2>&1 | tee litellm.log
2. Open the dashboard, go to the Usage page, and open the customer/end-user selector
3. Confirm it lists customers as before
4. In the browser network tab, confirm the request to /customer/list carries the bearer auth header and returns 200 through the new client

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR introduces a typed, schema-bound HTTP client (fetchClient) built on openapi-fetch over the generated schema.d.ts, and migrates useCustomers as the first caller. Auth, base-URL, and error handling are wired through a thin runtime.ts seam that networking.tsx populates on module load, so the singleton client stays framework-agnostic and its token source stays in sync with the enabled gate used by TanStack Query hooks.

• api.ts creates the fetchClient singleton with middleware that rebases URLs, injects the bearer token under the registered header name, and maps non-2xx responses to ApiError — reusing ApiError/deriveErrorMessage from client.ts so there is no duplicated transport logic.
• useCustomers.ts is migrated to fetchClient.GET("/customer/list") and the hand-written Customer/CustomersResponse types are replaced with the schema-derived CustomerResponse, which correctly constrains allowed_model_region to "eu" | "us".
• Test coverage in api.test.ts and runtime.test.ts is thorough; useCustomers.test.ts retains the core flows but loses the explicit positive test for non-"Admin" admin roles such as proxy_admin.

Confidence Score: 5/5

Safe to merge; the new client correctly reuses existing error-handling and auth infrastructure, and the one migrated caller (useCustomers) is fully typed against the schema.

The core transport logic, error mapping, and auth token injection are all well-tested through the real openapi-fetch pipeline in api.test.ts. The runtime seam is simple and its defaults are verified. The useCustomers migration is a straightforward swap with no behavioral change beyond replacing hand-written types with schema-derived ones. The only gap is a minor reduction in test variety for the enabled gate's positive admin-role cases.

useCustomers.test.ts — the suite no longer includes a positive test that proxy_admin (or other v2 admin roles) can trigger the fetch.

Important Files Changed

Filename	Overview
ui/litellm-dashboard/src/lib/http/api.ts	New typed HTTP client using openapi-fetch; reuses ApiError/deriveErrorMessage from client.ts and delegates auth/base-URL resolution to runtime.ts via middleware
ui/litellm-dashboard/src/lib/http/runtime.ts	New seam module for mutable runtime config (base URL, auth header, token, error handler); defaults correctly handle pre-registration window via NEXT_PUBLIC_BASE_URL
ui/litellm-dashboard/src/components/networking.tsx	Registers four runtime getters (base URL, auth header name, token from session cookie, error handler) on module load; reads token from the same cookie source as useAuthorized
ui/litellm-dashboard/src/app/(dashboard)/hooks/customers/useCustomers.ts	Migrated from allEndUsersCall to fetchClient.GET("/customer/list"); hand-written Customer/CustomersResponse types replaced with schema-derived CustomerResponse; enabled gate unchanged
ui/litellm-dashboard/src/app/(dashboard)/hooks/customers/useCustomers.test.ts	Test suite significantly trimmed (334→104 lines); core flows (success, error, disabled gate) are retained but the positive test verifying proxy_admin access was removed
ui/litellm-dashboard/src/lib/http/api.test.ts	New test file; exercises middleware through the real openapi-fetch pipeline for bearer injection, base URL rebasing, non-2xx → ApiError, body passthrough, and error handler invocation
ui/litellm-dashboard/src/lib/http/runtime.test.ts	New test file; verifies env-variable-driven default base URL and the Authorization header-name default before any getter is registered

_{Reviews (6): Last reviewed commit: "refactor(ui): source the typed client to..." | Re-trigger Greptile}

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai recreated per-test in beforeEach, not shared

[goransh-buh]

The logic here is clear. Have you considered edge case a timeout before the first byte arrives? Might be worth adding a test.

[ryan-crabbe-berri]

@greptileai re review

[ryan-crabbe-berri]

@greptileai re review codebase has significantly changed since last review

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_openapi_react_query (728673d) with litellm_internal_staging (80c5217)}

[ryan-crabbe-berri]

@greptileai re review