Client Methods
Rule
Browser/client code imports named methods, hooks, or client modules instead of
hand-writing REST calls to framework or app routes.
Why
Route shapes are transport details. If components and docs call
fetch("/_agent-native/...") or template /api/* routes directly, every caller
has to rediscover auth, base paths, request-source headers, JSON parsing, error
handling, optimistic updates, sync invalidation, and route quirks. A named client
method gives the UI, docs, and future agents one stable contract.
How
Look for an existing client API first.
| Need |
Use |
| App action reads/writes |
useActionQuery / useActionMutation from @agent-native/core/client/hooks |
| Imperative action calls |
callAction from @agent-native/core/client/hooks |
| Browser application state |
readClientAppState, writeClientAppState, setClientAppState, deleteClientAppState from @agent-native/core/client/hooks |
| Navigation/app-state sync |
useAgentRouteState / useSemanticNavigationState from @agent-native/core/client/navigation |
| Agent chat context |
Agent chat helpers from @agent-native/core/client/agent-chat |
| Ask the user a multiple-choice question from app code |
askUserQuestion from @agent-native/core/client/agent-chat (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
| Live sync |
useDbSync, useChangeVersion, useChangeVersions from @agent-native/core/client/hooks |
| Extension iframe calls |
appAction, appFetch, extensionFetch from the extension runtime |
| Toast for a failed write that is not an action mutation |
reportWriteFailure(error, { label }), or meta: surfaceMutationError(label) on a raw useMutation, from @agent-native/core/client/write-failure |
Action fetch behavior: every useActionQuery / useActionMutation /
callAction request is bounded by a 60s timeout, and timeouts surface as
errors instead of retrying silently. useActionQuery cancels superseded
requests automatically via React Query's abort signal. For imperative
calls, callAction(name, params, { method, signal, timeoutMs }) accepts an
AbortSignal and a timeoutMs override for legitimately long operations.
Failed writes: useActionMutation shows one shared toast on its own when
nothing handles the error (errorNotification: "auto", the default).
"shared" toasts even beside an onError that only rolls back or logs, and
"caller" opts out for background saves and deliberate swallows. A write
that goes through a raw fetch (an upload, a stream) or a swallowed catch
announces its failure with reportWriteFailure(error, { label }); a raw
useMutation opts in with meta: surfaceMutationError(label). label is an
already-translated title. AppProviders mounts the listener
(WriteFailureToaster); an app without it, or with toaster={null}, renders
WriteFailureToaster from @agent-native/toolkit/app/shared itself.
If no client API exists, add the narrowest helper at the boundary.
- Put shared framework helpers in
packages/core/src/client/*.
- Put template-local helpers in
templates/<app>/app/hooks/*,
templates/<app>/app/lib/*, or an existing local client module.
- Export reusable core helpers from the focused
@agent-native/core/client/*
entry for their domain. Never recommend the deprecated broad
@agent-native/core/client barrel in new code.
- Keep raw
fetch, agentNativePath, and route paths inside that helper,
not scattered through components or docs.
- Add focused tests for URL construction, headers, response parsing, error
shape, and any sync invalidation.
Teach the helper, not the route.
Docs, skills, examples, and generated code should show:
await setClientAppState("selection", selection, { keepalive: true });
not:
await fetch("/_agent-native/application-state/selection", {
method: "PUT",
body: JSON.stringify(selection),
});
Exceptions
Raw route calls are acceptable only inside low-level client helpers or for
route-shaped protocols that cannot be hidden cleanly:
- multipart uploads
- streaming/SSE/WebSocket transports
- OAuth redirects and callback URL construction
- webhooks and external provider callbacks
- extension sandbox
appFetch / extensionFetch, which are themselves exposed
client methods
- tests that assert route construction
Even for exceptions, prefer a named helper as soon as more than one caller needs
the behavior.
Don't
- Don't put
fetch("/_agent-native/..."), fetch(agentNativePath(...)), or
template /api/* calls directly in React components for normal app data,
actions, settings, or application state.
- Don't document route calls as the way client code should do work.
- Don't add pass-through
/api/* routes just to make client fetches look
simpler; expose an action and call it with action hooks.
- Don't duplicate auth/session/base-path/request-source/error parsing logic in
every component.
Related Skills
actions — app operations shared by UI and agent.
context-awareness — application-state navigation and selection helpers.
real-time-sync — keeping helper-backed UI reads fresh.
server-plugins — when a new route is actually warranted.
References
references/legacy-client-fetch-audit-2026-06-03.md — known legacy cleanup
targets found when this rule was added.
1---2name: client-methods3description: >-4 Client method surface rules. Use when wiring browser/client code to actions,5 application state, framework routes, app APIs, uploads, auth, or settings.6scope: dev7metadata:8 source: https://skillmd.com/skills/builderio/client-methods9 internal: true10---1112# Client Methods1314## Rule1516Browser/client code imports named methods, hooks, or client modules instead of17hand-writing REST calls to framework or app routes.1819## Why2021Route shapes are transport details. If components and docs call22`fetch("/_agent-native/...")` or template `/api/*` routes directly, every caller23has to rediscover auth, base paths, request-source headers, JSON parsing, error24handling, optimistic updates, sync invalidation, and route quirks. A named client25method gives the UI, docs, and future agents one stable contract.2627## How28291. Look for an existing client API first.3031 | Need | Use |32 | --- | --- |33 | App action reads/writes | `useActionQuery` / `useActionMutation` from `@agent-native/core/client/hooks` |34 | Imperative action calls | `callAction` from `@agent-native/core/client/hooks` |35 | Browser application state | `readClientAppState`, `writeClientAppState`, `setClientAppState`, `deleteClientAppState` from `@agent-native/core/client/hooks` |36 | Navigation/app-state sync | `useAgentRouteState` / `useSemanticNavigationState` from `@agent-native/core/client/navigation` |37 | Agent chat context | Agent chat helpers from `@agent-native/core/client/agent-chat` |38 | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client/agent-chat` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |39 | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` from `@agent-native/core/client/hooks` |40 | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |41 | Toast for a failed write that is not an action mutation | `reportWriteFailure(error, { label })`, or `meta: surfaceMutationError(label)` on a raw `useMutation`, from `@agent-native/core/client/write-failure` |4243 Action fetch behavior: every `useActionQuery` / `useActionMutation` /44 `callAction` request is bounded by a 60s timeout, and timeouts surface as45 errors instead of retrying silently. `useActionQuery` cancels superseded46 requests automatically via React Query's abort signal. For imperative47 calls, `callAction(name, params, { method, signal, timeoutMs })` accepts an48 `AbortSignal` and a `timeoutMs` override for legitimately long operations.4950 Failed writes: `useActionMutation` shows one shared toast on its own when51 nothing handles the error (`errorNotification: "auto"`, the default).52 `"shared"` toasts even beside an `onError` that only rolls back or logs, and53 `"caller"` opts out for background saves and deliberate swallows. A write54 that goes through a raw `fetch` (an upload, a stream) or a swallowed `catch`55 announces its failure with `reportWriteFailure(error, { label })`; a raw56 `useMutation` opts in with `meta: surfaceMutationError(label)`. `label` is an57 already-translated title. `AppProviders` mounts the listener58 (`WriteFailureToaster`); an app without it, or with `toaster={null}`, renders59 `WriteFailureToaster` from `@agent-native/toolkit/app/shared` itself.60612. If no client API exists, add the narrowest helper at the boundary.6263 - Put shared framework helpers in `packages/core/src/client/*`.64 - Put template-local helpers in `templates/<app>/app/hooks/*`,65 `templates/<app>/app/lib/*`, or an existing local client module.66 - Export reusable core helpers from the focused `@agent-native/core/client/*`67 entry for their domain. Never recommend the deprecated broad68 `@agent-native/core/client` barrel in new code.69 - Keep raw `fetch`, `agentNativePath`, and route paths inside that helper,70 not scattered through components or docs.71 - Add focused tests for URL construction, headers, response parsing, error72 shape, and any sync invalidation.73743. Teach the helper, not the route.7576 Docs, skills, examples, and generated code should show:7778 ```ts79 await setClientAppState("selection", selection, { keepalive: true });80 ```8182 not:8384 ```ts85 await fetch("/_agent-native/application-state/selection", {86 method: "PUT",87 body: JSON.stringify(selection),88 });89 ```9091## Exceptions9293Raw route calls are acceptable only inside low-level client helpers or for94route-shaped protocols that cannot be hidden cleanly:9596- multipart uploads97- streaming/SSE/WebSocket transports98- OAuth redirects and callback URL construction99- webhooks and external provider callbacks100- extension sandbox `appFetch` / `extensionFetch`, which are themselves exposed101 client methods102- tests that assert route construction103104Even for exceptions, prefer a named helper as soon as more than one caller needs105the behavior.106107## Don't108109- Don't put `fetch("/_agent-native/...")`, `fetch(agentNativePath(...))`, or110 template `/api/*` calls directly in React components for normal app data,111 actions, settings, or application state.112- Don't document route calls as the way client code should do work.113- Don't add pass-through `/api/*` routes just to make client fetches look114 simpler; expose an action and call it with action hooks.115- Don't duplicate auth/session/base-path/request-source/error parsing logic in116 every component.117118## Related Skills119120- `actions` — app operations shared by UI and agent.121- `context-awareness` — application-state navigation and selection helpers.122- `real-time-sync` — keeping helper-backed UI reads fresh.123- `server-plugins` — when a new route is actually warranted.124125## References126127- `references/legacy-client-fetch-audit-2026-06-03.md` — known legacy cleanup128 targets found when this rule was added.