Skip to content

API layer

How eu-home-app calls the eu_tools backend. For building query options and mutations, see also Best practices.

OpenAPI-generated client

eu-home-app uses an OpenAPI-generated client from the eu_tools spec. The client and types come from @alaneu/openapi-codegen; the generated eu-tools API lives under frontend/shared/openapi-codegen (consumed as the eu-tools generated module). The app wires this in frontend/apps/eu-home-app/utils/backend.ts:

  • openApiClient — low-level client used by the helpers below.
  • openApiQueryOptions — builds TanStack Query options for GET (and other read) endpoints.
  • openApiPolicyCheckOptions — builds TanStack Query options for ABAC policy-check endpoints (returns a boolean).
  • useOpenApiMutation — hook for mutations (POST, PUT, PATCH, DELETE). This will soon be deprecated for a simpler options getter like for queries.

All are exported from utils/backend.ts and used across utils/*.ts and page-level code.

Query options pattern

Define query-options helpers that return the result of openApiQueryOptions({ path, parameters, enabled?, staleTime?, ... }), then use useQuery(helper()) in components. This keeps query keys and request shape in one place and lets TanStack Query cache and dedupe correctly.

Example (reviews):

In utils/reviews.tsx:

export function reviewSubmissionsQueryOptions(reviewId?: string) {
  return openApiQueryOptions({
    path: "/reviews/{review_id}/review-submissions",
    parameters: { path: { review_id: reviewId! } },
    enabled: reviewId !== undefined,
    staleTime: 1000 * 60 * 5,
  });
}

In a component:

const { data: reviewSubmissions, isLoading } = useQuery(reviewSubmissionsQueryOptions(review.id));

For ABAC policy checks (e.g. “can current user approve this submission?”), use openApiPolicyCheckOptions with the same pattern: pass path, parameters, and usually query: { method: "put" } (or the HTTP method you want to check). Then useQuery(...) returns a boolean. See Permissions for details.

Example modules: utils/reviews.tsx, utils/alaners.ts, utils/areas.ts, utils/backend.ts.

Where API helpers live

  • Shared across pages: frontend/apps/eu-home-app/utils/*.ts — e.g. reviews.tsx, alaners.ts, areas.ts, backend.ts, offices.ts, finance.ts, pulses.ts, alanCoffee.ts. Use these when more than one feature needs the same endpoint.
  • Page-specific: app/pages/<Feature>/utils.ts or app/pages/<Feature>/hooks.ts when only that feature needs the helper (e.g. app/pages/Team/utils.ts, app/pages/SalesProspecting/hooks.ts, app/pages/MediaGenerator/utils/mediaQueries.ts).

See also