Cursor rule

1---
2description: Frontend API integration for files importing @generated/doughnut-backend-api/sdk.gen, apiCallWithLoading, blockUi loading, data-app-busy / waitUntilAppIsNotBusy E2E pairing, wrapped responses, toOpenApiError
3alwaysApply: false
4---
5# Frontend API Rules
6 
7Use this rule when frontend code imports services from `@generated/doughnut-backend-api/sdk.gen`, handles wrapped API responses, or maps backend validation errors.
8 
9## API Integration
10 
11- Import services directly from `@generated/doughnut-backend-api/sdk.gen`.
12- Use the wrapped response pattern: `{ data, error, request, response }`.
13- Follow the API types from generated code.
14- Use `apiCallWithLoading` for user-initiated actions that need loading indicators.
15- Wrapped calls show loading state and error toasts automatically.
16- Non-wrapped calls are silent: no loading state and no error toasts.
17 
18```typescript
19import { UserController } from "@generated/doughnut-backend-api/sdk.gen"
20import { apiCallWithLoading } from "@/managedApi/clientSetup"
21 
22const { data: newUser, error } = await apiCallWithLoading(() =>
23  UserController.createUser({
24    body: formData,
25  })
26)
27 
28const { data: users, error: loadError } = await UserController.getUserProfile()
29```
30 
31## Loading indicators
32 
33`apiCallWithLoading` drives two global surfaces mounted from `DoughnutApp.vue`:
34 
35- **Thin loading bar** — shown while any wrapped call is in flight.
36- **Whole-UI blocking modal** — shown when an in-flight call passed `{ blockUi: true }`; its message comes from the latest blocking state. Each call pushes/pops a state by id, so concurrent blockers clean up correctly. The modal is a native `<dialog>` opened with `showModal()`, so it lives in the browser top layer and paints above other top-layer modals (e.g. the Refine note dialog) — `z-index` cannot reach the top layer.
37 
38Use `{ blockUi: true, message?: string }` when a user action must finish before the rest of the UI is usable — view transitions that depend on a result, or mutations where partial interaction would confuse state. Show the blocker only after any confirmation step. Do **not** add component-local `LoadingModal` refs; the global modal is the single whole-UI blocker.
39 
40```typescript
41const { data, error } = await apiCallWithLoading(
42  () => AssimilationController.next({ query: { timezone: timezoneParam() } }),
43  { blockUi: true, message: "Loading next note..." }
44)
45```
46 
47### Cancelable blocking calls
48 
49For safe **read-only** blockers where the user may abandon the wait, pass the literal opt-in `{ blockUi: true, cancelable: true, message?: string }`. That overload returns `CancelableApiResult<T>` (`{ status: "completed"; result }` | `{ status: "cancelled" }`). Narrow on `status` before using `result`; do not treat cancel as an API error.
50 
51Allowed product opt-ins today (note refinement only): **layout generation** (`AI is generating layout...`) and **extraction-preview generation** (`extractNotePreview` / `AI is generating preview...`). Both use this same overload and status narrowing.
52 
53```typescript
54const outcome = await apiCallWithLoading(
55  (signal) =>
56    AiController.generateRefinementSuggestions({
57      path: { note: noteId },
58      signal,
59    }),
60  {
61    blockUi: true,
62    cancelable: true,
63    message: "AI is generating layout...",
64  }
65)
66 
67if (outcome.status === "cancelled") {
68  // Domain-local empty/retry UI only — accepted cancel is silent (no toast).
69  return
70}
71 
72const { data, error } = outcome.result
73```
74 
75```typescript
76const previewOutcome = await apiCallWithLoading(
77  (signal) =>
78    AiController.extractNotePreview({
79      path: { note: noteId },
80      body: layoutSelection,
81      signal,
82    }),
83  {
84    blockUi: true,
85    cancelable: true,
86    message: "AI is generating preview...",
87  }
88)
89 
90if (previewOutcome.status === "cancelled") {
91  return
92}
93 
94const { data, error } = previewOutcome.result
95```
96 
97Cancel on the global modal is projected only from the **selected blocker's identity-bound** action; cancelling one state does not clear older concurrent blockers. Accepted cancel is silent (no toast / Cancelling interstitial). Browser abort is **client-only** — it does not promise server work stopped. Do **not** opt mutations or irreversible writes into `cancelable: true` (e.g. create-note / `AI is creating note...` stays noncancelable). Do not invent AbortError-name matching, a cancelable `runWithBlockingApiLoading`, or a parallel helper — use this overload only.
98 
99For one continuous blocker across multiple calls, wrap them in `runWithBlockingApiLoading(operation, message)`; inner `apiCallWithLoading` calls keep thin bar + toasts only. That helper remains noncancelable.
100 
101Keep local loading state (inline spinner, disabled control, row-level pending) when the user should stay able to interact with the rest of the page — e.g. search, pagination, single form-field upload, recall prompt internals. These can still call `apiCallWithLoading` without `blockUi`.
102 
103### Blocking classification inventory
104 
105Every whole-UI blocker and long-running note-refinement AI request must be classified as **cancelable**, **intentionally noncancelable**, or **nonblocking**. Persist new sites here when adding `blockUi: true` or `runWithBlockingApiLoading` — do not leave them unclassified.
106 
107**Cancelable allowlist** (only these product opt-ins may use `{ blockUi: true, cancelable: true }`; exclusivity is gated by `frontend/tests/managedApi/cancelableAllowlist.spec.ts`):
108 
109| Operation | Message | Call site | Notes |
110| --- | --- | --- | --- |
111| Layout generation | `AI is generating layout...` | `NoteRefinement.vue` | Shared cancelable overload |
112| Extraction-preview generation | `AI is generating preview...` | `NoteRefinement.vue` | Shared cancelable overload |
113 
114**Intentionally noncancelable** (whole-UI blocker without Cancel — do **not** opt into `cancelable: true` until a safe post-cancel outcome is defined for that site):
115 
116| Operation | Message | Call site | Mechanism | Notes |
117| --- | --- | --- | --- | --- |
118| Create extracted note | `AI is creating note...` | `NoteRefinement.vue` | `runWithBlockingApiLoading` | Intentional: client-only abort is unsafe for this transactional write (duplicate note / double original-note update risk). |
119| Remove refinement content | `AI is removing content...` | `NoteRefinement.vue` | `runWithBlockingApiLoading` | Mutation; nested post-remove layout reload is nonblocking (see below) |
120| Assimilate unit | `Assimilating...` | `useAssimilateUnit.ts` | `{ blockUi: true }` | Mutation |
121| Load next assimilation note | `Loading next note...` | `useGoToNextAssimilation.ts` | `{ blockUi: true }` | View transition |
122| Book layout mutations | `Updating book layout…` | `useBookLayoutMutations.ts` | `{ blockUi: true }` (2 sites) | Mutation |
123| Book layout AI suggest | `Analyzing book layout…` | `useBookLayoutAiReorganize.ts` | `{ blockUi: true }` | Long-running AI read; leave noncancelable until post-cancel UX is defined |
124| Book layout apply suggestion | `Applying layout changes…` | `useBookLayoutAiReorganize.ts` | `{ blockUi: true }` | Mutation |
125| Note delete / reduce | `Deleting note...` / `Reducing to source property...` | `useNoteDeleteFlow.ts` | `runWithBlockingApiLoading` | Mutation |
126| Relationship finalize | `Creating relationship note...` | `AddRelationshipFinalize.vue` | `runWithBlockingApiLoading` | Mutation |
127| Attach book upload | `Uploading book…` | `NotebookAttachedBookSection.vue` | `runWithBlockingApiLoading` | Mutation |
128 
129**Nonblocking** (out of Cancel UX — thin-bar or direct SDK; no whole-UI modal):
130 
131| Operation | Call site | Notes |
132| --- | --- | --- |
133| Export extract request | `NoteRefinement.vue` `fetchExtractRequestExport` | Direct SDK; no `apiCallWithLoading` |
134| Export refinement layout request | `NoteRefinement.vue` `fetchBreakdownRequestExport` | Direct SDK; no whole-UI block |
135| Post-remove layout reload | `NoteRefinement.vue` `loadRefinementLayout({ blockUi: false })` | Thin-bar nested under remove continuous blocker |
136| Load book after attach | `NotebookAttachedBookSection.vue` `loadBook` | Thin-bar `apiCallWithLoading` without `blockUi` |
137 
138| Concern | Mechanism |
139| --- | --- |
140| Thin top loading bar | Any `apiCallWithLoading` call → `LoadingThinBar` with `data-app-busy` |
141| Whole-UI modal | `apiCallWithLoading(..., { blockUi: true, message? })` or `runWithBlockingApiLoading` → `LoadingModal` with `data-app-busy` |
142| Cancelable whole-UI modal | `apiCallWithLoading(..., { blockUi: true, cancelable: true, message? })` → `CancelableApiResult` (status narrowing) |
143| Page / section pending data | `ContentLoader` with `data-app-busy` |
144| Inline / partial progress | Local component state (not part of the busy contract unless it adds `data-app-busy`) |
145| Error toasts | `apiCallWithLoading` (handled in `clientSetup.ts`); accepted cancel is silent |
146| Silent background fetch | Direct SDK call without `apiCallWithLoading` |
147| E2E wait for unfinished work | `waitUntilAppIsNotBusy()` — waits until no `[data-app-busy]` (see below) |
148 
149### E2E pairing (`data-app-busy` ↔ `waitUntilAppIsNotBusy`)
150 
151Loading UI that means “the app has unfinished work” must mark its root element with `data-app-busy`. Today that is `LoadingThinBar`, `ContentLoader`, and `LoadingModal` (enforced by `frontend/tests/components/commons/AppBusyMarker.contract.spec.ts`). Presentational classes stay presentational.
152 
153| Product | E2E |
154| --- | --- |
155| Elements with `data-app-busy` | `waitUntilAppIsNotBusy()` from `e2e_test/start/pageBase.ts` |
156 
157After a Cypress action that starts loading work, call `waitUntilAppIsNotBusy()` in the page object before the next assertion that depends on that work finishing. The wait means **busy UI cleared**, not success — prefer a user-visible outcome when the product shows one. Do not use hardcoded sleeps. Network intercepts are optional extras, not the default stand-in. Full E2E notes: `.cursor/rules/e2e-authoring.mdc`.
158 
159## API Return Value Usage
160 
161The global client is configured with `responseStyle: "fields"` and `throwOnError: false`, so services return a wrapped response: `{ data, error, request, response }`.
162 
163```typescript
164import { getTokens } from "@generated/doughnut-backend-api/sdk.gen"
165 
166const { data: tokens, error } = await getTokens()
167 
168if (!error) {
169  tokens.value = tokens.map((token) => ({
170    id: token.id,
171    label: token.label,
172  }))
173}
174```
175 
176Key points:
177 
1781. Destructure with meaningful variable names: `const { data: updatedUser, error } = await updateUser(...)`.
1792. Check `!error` before using `data`; no separate `data` check is needed.
1803. When `error` is undefined, TypeScript guarantees `data` is the expected type.
1814. Do not add runtime property checks for required typed properties.
1825. Do not add `else if (data)` after checking `error`.
1836. Use `apiCallWithLoading` for user actions to enable error toasts and loading state.
184 
185## Validation Errors
186 
187When handling 400 Bad Request validation errors, use `toOpenApiError` to extract field-level errors. The `error` field in API responses is typed as `string` but can be an object at runtime after JSON parsing.
188 
189```typescript
190import { apiCallWithLoading } from "@/managedApi/clientSetup"
191import { toOpenApiError } from "@/managedApi/openApiError"
192 
193const errors = ref<Record<string, string>>({})
194 
195const { data: updatedUser, error } = await apiCallWithLoading(() =>
196  UserController.updateUser({
197    path: { user: id },
198    body: formData,
199  })
200)
201 
202if (error) {
203  const openApiError = toOpenApiError(error)
204  errors.value = openApiError.errors || {}
205} else {
206  errors.value = {}
207  user.value = updatedUser
208}
209```
210 
211Key points:
212 
2131. Use `toOpenApiError(error)` to convert the runtime error value to `OpenApiError`.
2142. `OpenApiError` shape: `{ errors?: Record<string, string>; message?: string }`.
2153. The helper safely handles both string and object errors.
2164. Extract `errors` for field-level validation errors, usually from 400 responses.
2175. `apiCallWithLoading` already shows error toasts; only extract field-level errors for form validation.
218