Files
jeffvli 8b5d646048 chore: add agent docs, skills, and commitlint
Introduce AGENTS.md (CLAUDE.md symlink), docs/agents guides, repo skills, and CI commitlint with Feishin scopes.
2026-08-16 11:53:21 -07:00

56 lines
2.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API
Server library data layer (Jellyfin / Navidrome / Subsonic). Read when adding or changing fetches, mutations, normalize, or query keys.
## Layers
| Layer | Path | Job |
|-------|------|-----|
| Feature queries / mutations | `src/renderer/features/<feature>/api/`, `.../mutations/` | `queryOptions` / `useMutation`; call `api.controller` |
| Facade | `src/renderer/api` → `controller.ts` | Pick backend from current server (`ServerType`) |
| Backend client + controller | `src/renderer/api/{jellyfin,navidrome,subsonic}/` | HTTP + map to controller endpoints |
| Types + normalize | `src/shared/api/{jellyfin,navidrome,subsonic}/` | Zod/types + `*Normalize` → domain |
| Domain contracts | `src/shared/types/domain-types.ts` | `ControllerEndpoint` shapes features rely on |
| Query keys | `src/renderer/api/query-keys.ts` | `[serverId, resource, …]`; use `splitPaginatedQuery` for list/count |
React Query client: `src/renderer/lib/react-query.ts`.
## Add a query
1. Prefer extending the matching `src/renderer/features/<feature>/api/*-api.ts` (or add one beside siblings).
2. Call `api.controller.<method>(…)` — do not invent one-off axios/fetch in UI.
3. Keys from `queryKeys` — keep `serverId` first; invalidate the same keys from mutations.
4. UI uses `useQuery(<feature>Queries.…)` like nearby features.
```ts
import { api } from '/@/renderer/api';
import { queryKeys } from '/@/renderer/api/query-keys';
```
## Normalize / new endpoint
- Wire through the per-backend **controller**, not the feature component.
- Parse/validate with shared types; map with `jfNormalize` / `ndNormalize` / `ssNormalize` in `src/shared/api/...`.
- Keep domain types stable for features; backend quirks stay in normalize/controller.
## Upstream OpenAPI (last resort)
Do **not** fetch these for ordinary API work. Prefer in-repo controllers, `src/shared/api/*-types.ts`, normalize, and existing call sites.
Fetch **only** when an endpoint, field, or auth detail is missing or contradictory in-repo and you cannot finish without the vendor contract:
| Backend | Schema |
|---------|--------|
| OpenSubsonic (Subsonic / Navidrome-compatible) | https://opensubsonic.netlify.app/docs/openapi/openapi.json |
| Navidrome native API | https://github.com/navidrome/navidrome/tree/master/server/nativeapi |
| Jellyfin | https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json |
When you must open one: pull **only the path/operation/schema (or Go handler file) you need**, not the whole spec or folder into context. Then encode the result in our types/normalize/controller — do not leave features depending on the remote source.
## Don’t
- Bypass `api.controller` from feature UI.
- Put Jellyfin/Navidrome/Subsonic response shapes in React components — normalize first.
- Hand-roll query key arrays when `query-keys.ts` already has a factory.
- Open upstream OpenAPI “just in case” or to explore — in-repo code first.