# CLAUDE.md — jamespot-user-api

Client API : types TypeScript, schémas Zod runtime, helpers de tests. Consommé par tous les autres packages.

## Structure

```
src/
├── apis/
│   ├── base.ts                 # JBaseApi — base class étendue par chaque domaine
│   ├── jamespotUserApi.ts      # Entry point
│   └── {domain}/
│       ├── {domain}.ts         # J{Domain}Api class (extends JBaseApi)
│       ├── {domain}.mock.ts    # Mock data + import phpUnit JSON
│       └── {domain}.test.ts
├── types/                      # Types TS + schémas Zod colocalisés
├── util/
│   ├── Test.ts                 # fetchMock, testAPI, testAPIList, validatePhpUnitSnapshot
│   ├── network.ts              # HTTP handler, gestion token/CSRF
│   └── zod.ts                  # zSchema, zObject, zPassThrough
└── window/                     # WindowInterface (abstraction fetch)
phpunitMock/                    # Fixtures JSON du backend PHP
```

## Spécificités

- TS flags : `exactOptionalPropertyTypes`, `noUnusedLocals`, `noUnusedParameters`
- Path alias : `@phpunitMock/*` → `phpunitMock/*` (tsconfig + jest.config)
- Couverture : ~99.7% statements, ~98.7% functions
- Build : Vite library (ESM + CJS), seule runtime dependency = `zod`

### JBaseApi — méthodes réseau

Tout domaine étend `JBaseApi` et utilise :

- `network.post()` — lecture
- `network.postCSRF()` — mutation
- `network.postFile()` — upload
- `network.maybePostToken()` — opérations conditionnelles avec token

Chaque méthode accepte `signal?: AbortSignal`.

### Type + Zod (workflow type-first)

1. Définir le type TS comme source de vérité
2. Créer un schéma Zod qui suit le type via `zSchema<T>(shape)` (helper de `util/zod.ts`)
3. Convention : `{TypeName}` (type) ↔ `{typeName}Schema` (schéma)

### Test helpers (`util/Test.ts`)

Helpers obligatoires (ne pas réinventer) :

- `fetchMock(data)` / `fetchMockCSRF(data)`
- `testAPI({ apiCall, mock, schema, phpMock })` — endpoint single-result
- `testAPIList({ apiCall, mock, schema, phpMock })` — endpoint paginé
- `validatePhpUnitSnapshot(phpMock, response)` — compare avec fixtures backend
- `validateApiWrapper(res, o, f)` / `validatePagingResults(res)`

### Scripts non triviaux

- `pnpm build:dev` — vite seul (skip type check)
- `pnpm test:mockVM` — jest avec chargement mock PHP VM
- `pnpm doc` — génération typedoc

## Voir aussi

- `.claude/rules/frontend/_shared/` — règles universelles (typescript, imports, naming, error-handling, testing, etc.)
