Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

client-methods

/client-methods

Opisuje zasady warstwy metod klienckich przy łączeniu kodu przeglądarki z akcjami, stanem aplikacji, trasami frameworka, API, przesyłaniem plików, uwierzytelnianiem i ustawieniami.

Repozytorium
agent-native ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Opisuje zasady warstwy metod klienckich przy łączeniu kodu przeglądarki z akcjami, stanem aplikacji, trasami frameworka, API, przesyłaniem plików, uwierzytelnianiem i ustawieniami.

Oryginalny opis (EN)

Client method surface rules. Use when wiring browser/client code to actions, application state, framework routes, app APIs, uploads, auth, or settings.

Jak działa

  1. Rule
  2. Why
  3. How
  4. Exceptions
  5. Don't
  6. Related Skills
  7. References
Sekcje z nagłówków SKILL.md, w oryginale · 107 linii, 583 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (2)
  • SKILL.md 5 KB
  • references/legacy-client-fetch-audit-2026-06-03.md 3 KB

Wersje

W bazie nie ma innych skilli o nazwie client-methods.

Migawka bazy z 13.11.2026 · wersja paczki 6bf3de20a2cb (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100api-check
    Porównuje żądania frontendu z trasami backendu i wskazuje niezgodności metod, ścieżek, pól i obsługi błędów z odwołaniem do plików.
  • 100nextjs-code-review
    Przeprowadza przegląd kodu aplikacji Next.js: Server i Client Components, Server Actions, strategie cache, metadata, trasy API, middleware i wzorce wydajności, przed scaleniem PR lub po nowej funkcji.
  • 100nextjs-app-router
    Buduje i przegląda kod Next.js App Router: granice komponentów serwerowych i klienckich, pobieranie danych, cache i rewalidacja, streaming z Suspense oraz mutacje przez Server Actions.
  • 100nextjs
    Wspiera budowę aplikacji Next.js z App Router: granice komponentów serwerowych i klienckich, pobieranie danych i cache, server actions, streaming i strategia renderowania.
  • 95nextjs-expert
    Wspiera pracę z Next.js: App Router, granice serwer-klient, wzorce danych i cache oraz operacje produkcyjne, przy budowie, debugowaniu i optymalizacji aplikacji oraz wyborze komponentów serwerowych lub klienckich.
  • 100nextjs-client-audit
    Sprawdza dyrektywy use client w Next.js, mierzy kod trafiający do paczki przeglądarki i proponuje bezpieczne poprawki z przykładami przed i po.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.