frontend-api

Frontend API Rules

API Integration

• Import services from @generated/donut-backend-api/sdk.gen.
• Wrapped response: { data, error, request, response }.
• User-initiated actions: apiCallWithLoading (loading bar + error toasts).
• Direct SDK calls are silent: no loading bar and no error toasts.

import { UserController } from "@generated/donut-backend-api/sdk.gen"
import { apiCallWithLoading } from "@/managedApi/clientSetup"

const { data: newUser, error } = await apiCallWithLoading(() =>
  UserController.createUser({ body: formData })
)

const { data: users, error: loadError } = await UserController.getUserProfile()

Loading indicators

apiCallWithLoading drives two global surfaces from DonutApp.vue:

• Thin loading bar — any wrapped call in flight.
• Whole-UI blocking modal — { blockUi: true }. Native <dialog showModal()>, so it paints above other top-layer dialogs.

Use { blockUi: true, message?: string } when the rest of the UI must wait (view transition, or a mutation where partial interaction would confuse state). Show the blocker only after any confirmation. Do not add component-local LoadingModal refs.

const { data, error } = await apiCallWithLoading(
  () => AssimilationController.next({ query: { timezone: timezoneParam() } }),
  { blockUi: true, message: "Loading next note..." }
)

Keep local loading (inline spinner, disabled control) when the user should still use the rest of the page. Those calls can still use apiCallWithLoading without blockUi.

Cancelable blocking calls

For safe read-only blockers, pass { blockUi: true, cancelable: true, message?: string }. Returns CancelableApiResult<T> ({ status: "completed"; result } | { status: "cancelled" }). Narrow on status before using result; do not treat cancel as an API error.

const outcome = await apiCallWithLoading(
  (signal) =>
    AiController.generateRefinementSuggestions({
      path: { note: noteId },
      signal,
    }),
  {
    blockUi: true,
    cancelable: true,
    message: "AI is generating refinement layout...",
  }
)

if (outcome.status === "cancelled") {
  return
}

const { data, error } = outcome.result