api-client-integration

# API Client Integration ## Overview Every remote call is three states, not one. The recurring defects are raw `fetch` scattered in components, untyped responses, and errors swallowed into `console.log` while the UI half-updates. **Core principle:** One typed client, three states (loading/success/error), no swallowed errors. ## Rules - **Go through `web/src/api.ts`** helpers — never raw `fetch` in components. - **Type every response** with an interface matching the backend JSON. A contract change starts by updating the interface so the compiler finds every affected usage. - **Handle all three states:** loading (visible feedback), success, and error (toast with an actionable message). - **Never swallow errors** into `console.log` — surface them to the user and keep the UI consistent (no half-updated state on failure). - **Debounce** user-driven queries; cancel or ignore stale responses when inputs change quickly. ## Worked Example ```tsx // ✅ typed client call, three states, no half-update on failure const [state, setState] = useState<Loadable<Task[]>>({ status: "loading" }); useEffect(() => { let active = true; api.listTasks(projectId) // typed helper from api.ts .then(tasks => active && setState({ status: "ok", data: tasks })) .catch(err => active && setState({ status: "error", message: err.message })); return () => { active = false; }; // ignore stale response }, [projectId]); if (state.status === "loading") return <...