client-methods
/client-methods
Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.
- Author
- builderio ↗
- Repository
- agent-native ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.
Original author description
Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.
How it works
- Rule
- Why
- How
- Exceptions
- Don't
- Related Skills
- References
SKILL.md preview
---
name: client-methods
description: >-
Client method surface rules. Use when wiring browser/client code to actions,
application state, framework routes, app APIs, uploads, auth, or settings.
scope: dev
metadata:
internal: true
---
# 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
1. 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 |
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.
2. 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.
3. Teach the helper, not the route.
Docs, skills, examples, and generated code should show:
```ts
await setClientAppState("selection", selection, { keepalive: true });
```
not:
```ts
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.
Files in this package (2)
- SKILL.md 5 KB
- references/legacy-client-fetch-audit-2026-06-03.md 3 KB
Versions
The database has no other skills named client-methods.
Database snapshot: 13.11.2026 · package version 6bf3de20a2cb (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api-check
Compare frontend API requests and consumers with backend routes to find mismatches in methods, paths, field names, response shapes, and error handling. Use for API integration reviews and debugging frontend/backend contract incompatibilities; report exact mismatches with file references. - 100nextjs-code-review
Provides comprehensive code review capability for Next.js applications, validates Server Components, Client Components, Server Actions, caching strategies, metadata, API routes, middleware, and performance patterns. Use when reviewing Next.js App Router code changes, before… - 100nextjs-app-router
Builds and reviews Next.js App Router code - server/client component boundaries, data fetching, caching and revalidation choices, streaming with Suspense, and Server Action mutations - and delivers routes where every dynamic-vs-cached decision is explicit. Use when someone asks… - 100nextjs
Use when building Next.js applications with the App Router. Covers server and client component boundaries, data fetching and caching, server actions, streaming, and rendering strategy. Trigger on "server or client component", "page shows stale data after a mutation", "route is… - 95nextjs-expert
Comprehensive Next.js expertise across App Router, server/client boundaries, data and caching patterns, and production operations. Use when building, debugging, or optimizing a Next.js app, deciding server vs client components, or resolving App Router gotchas. - 100nextjs-client-audit
Audit a Next.js App Router project for unnecessary or misplaced "use client" directives, measure how much code each one drags into the browser bundle, and give a concrete, safe fix (REMOVE, PUSH_DOWN, CHILDREN_PATTERN, MOVE_FETCH) with Before/After code from the user's own…