@sia-ui/api 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @sia-ui/api
 
+## 0.6.0
+
+### Minor Changes
+
+- Rôles, requêtes serveur, ressources par mode, et deux blocs de console.
+  - **Rôles** — la couche d'accès lit les rôles de la session sous la forme
+    `role:<nom>` (`role("admin")`), avec les trois évaluateurs.
+  - **Tableaux servis par le serveur** — `useDataTableQuery` accepte un
+    `storage` (TanStack Router, React Router) et `serverParams` pour les noms
+    attendus (`limit`, `sort` + `order`, `ASC`/`DESC`). `toServerParams` dans
+    `@sia-ui/headless`.
+  - **TanStack Query** — `createQueryResource(service)` : clés emboîtées,
+    options de requête avec annulation, mutations qui invalident ce qu'elles
+    rendent périmé. Aucune dépendance à TanStack.
+  - **Ressources** — `inForm` et `required` par mode (`"create"`, `"edit"`),
+    `value` pour une colonne calculée.
+  - **En-têtes** — `PageHeader` `level`, `CrudPage` `headingLevel`. Le repli
+    suit la place disponible ; les actions ne s'écrasent plus.
+  - **Nouveaux** — `SecretFields` (secrets en écriture seule), `ActivityLog`
+    (journal filtré par le serveur), `StatusBadge` et `toneOf`, dix icônes de
+    console.
+  - Les icônes des boutons de `CrudPage` et `DataTable` passent par
+    `leftIcon` : elles ne se collent plus au libellé.
+
+- `sia-ui update`, la feuille commune suivie, et des erreurs HTTP en français.
+  - **`sia-ui update [nom...]`** — met à jour les entrées en retard sans perdre
+    de retouche : un fichier intact est remplacé, un fichier modifié depuis son
+    installation est gardé et signalé (`sia-ui diff`, puis `--force` pour
+    l'écraser). Les dépendances de registre apparues sont installées, les
+    paquets npm annoncés. `--dry-run` montre sans rien écrire. Une entrée dont
+    un fichier a été gardé reste « en retard » dans le verrou.
+  - **`sia-ui.css` suivie** — son empreinte est notée dans `sia-ui.lock.json`.
+    `update` la met à jour comme un composant ; `add` aussi, si elle n'a pas
+    été retouchée. `init` ne fait plus qu'initialiser. Elle est lue au même
+    registre que les composants, HTTP compris. `doctor` signale une feuille en
+    retard, modifiée ou copiée avant le suivi.
+  - `list --outdated` et `doctor` conseillent `sia-ui update` au lieu de
+    `add --overwrite`, qui écrasait aussi les retouches.
+  - **`statusMessages`** (`@sia-ui/api`) — option du client, avec
+    `FRENCH_STATUS_MESSAGES`. Remplace les messages génériques du serveur
+    (« Conflict », « Forbidden resource », « Cannot GET /x »,
+    `ThrottlerException`) et l'échec réseau de `fetch`, jamais un message métier
+    ni une erreur de champs.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- Erreurs serveur dans les formulaires, client HTTP plus sûr, registre vérifié.
+
+  ## Défauts
+  - **Registre `drawer`** — `context.ts` et la dépendance `icons` manquaient :
+    `sia-ui add app-shell` produisait un projet qui ne compilait pas. Un test
+    vérifie désormais que chaque import relatif de chaque entrée est apporté par
+    son installation.
+  - **`sia-ui.css`** pose `box-sizing: border-box` (spécificité nulle). Sans
+    reset côté projet, `AppShell` débordait de 32 px.
+  - **`@sia-ui/api`** ne rejoue plus d'office que `GET` et `HEAD`
+    (`retryMethods`). Une écriture n'est rejouée que si l'appel pose `retry`.
+  - Plus aucun avertissement `react-hooks/exhaustive-deps` dans les composants.
+
+  ## Formulaires et erreurs serveur
+  - `Form` intercepte un envoi rejeté : erreurs de champ sous les champs, le
+    reste dans une alerte. `onSubmit` peut aussi rendre `{ champ: message }`
+    (`FormSubmitResult`), dans `useLocalForm`, `Form`, `CrudPage` et
+    l'adaptateur react-hook-form. `CrudPage` garde alors sa boîte ouverte.
+  - Les erreurs posées par `setErrors` survivent à la validation locale jusqu'à
+    la modification de leur champ.
+  - `HttpError.toFormErrors()`, option `fieldErrors` du client et préréglage
+    `nestFieldErrors` (class-validator). `readSubmitError` et `hasFormErrors`
+    dans `@sia-ui/headless`.
+  - La pagination à plat `{ data, total, page, limit }` est reconnue, et `get`
+    ne déballe plus `data` quand l'objet porte une pagination.
+
+  ## Tableaux
+  - `searchDelay` sur `DataTable` et `CrudPage`.
+  - `CrudPage` place les `extraRowActions` avant « Supprimer ».
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.5.0
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -57,6 +57,94 @@ Le contenu ci-dessous reprend intégralement `CHANGELOG.md` pour rester visible
 <!-- sia:changelog:start -->
 # @sia-ui/api
 
+## 0.6.0
+
+### Minor Changes
+
+- Rôles, requêtes serveur, ressources par mode, et deux blocs de console.
+  - **Rôles** — la couche d'accès lit les rôles de la session sous la forme
+    `role:<nom>` (`role("admin")`), avec les trois évaluateurs.
+  - **Tableaux servis par le serveur** — `useDataTableQuery` accepte un
+    `storage` (TanStack Router, React Router) et `serverParams` pour les noms
+    attendus (`limit`, `sort` + `order`, `ASC`/`DESC`). `toServerParams` dans
+    `@sia-ui/headless`.
+  - **TanStack Query** — `createQueryResource(service)` : clés emboîtées,
+    options de requête avec annulation, mutations qui invalident ce qu'elles
+    rendent périmé. Aucune dépendance à TanStack.
+  - **Ressources** — `inForm` et `required` par mode (`"create"`, `"edit"`),
+    `value` pour une colonne calculée.
+  - **En-têtes** — `PageHeader` `level`, `CrudPage` `headingLevel`. Le repli
+    suit la place disponible ; les actions ne s'écrasent plus.
+  - **Nouveaux** — `SecretFields` (secrets en écriture seule), `ActivityLog`
+    (journal filtré par le serveur), `StatusBadge` et `toneOf`, dix icônes de
+    console.
+  - Les icônes des boutons de `CrudPage` et `DataTable` passent par
+    `leftIcon` : elles ne se collent plus au libellé.
+
+- `sia-ui update`, la feuille commune suivie, et des erreurs HTTP en français.
+  - **`sia-ui update [nom...]`** — met à jour les entrées en retard sans perdre
+    de retouche : un fichier intact est remplacé, un fichier modifié depuis son
+    installation est gardé et signalé (`sia-ui diff`, puis `--force` pour
+    l'écraser). Les dépendances de registre apparues sont installées, les
+    paquets npm annoncés. `--dry-run` montre sans rien écrire. Une entrée dont
+    un fichier a été gardé reste « en retard » dans le verrou.
+  - **`sia-ui.css` suivie** — son empreinte est notée dans `sia-ui.lock.json`.
+    `update` la met à jour comme un composant ; `add` aussi, si elle n'a pas
+    été retouchée. `init` ne fait plus qu'initialiser. Elle est lue au même
+    registre que les composants, HTTP compris. `doctor` signale une feuille en
+    retard, modifiée ou copiée avant le suivi.
+  - `list --outdated` et `doctor` conseillent `sia-ui update` au lieu de
+    `add --overwrite`, qui écrasait aussi les retouches.
+  - **`statusMessages`** (`@sia-ui/api`) — option du client, avec
+    `FRENCH_STATUS_MESSAGES`. Remplace les messages génériques du serveur
+    (« Conflict », « Forbidden resource », « Cannot GET /x »,
+    `ThrottlerException`) et l'échec réseau de `fetch`, jamais un message métier
+    ni une erreur de champs.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.6.0
+
+## 0.5.0
+
+### Minor Changes
+
+- Erreurs serveur dans les formulaires, client HTTP plus sûr, registre vérifié.
+
+  ## Défauts
+  - **Registre `drawer`** — `context.ts` et la dépendance `icons` manquaient :
+    `sia-ui add app-shell` produisait un projet qui ne compilait pas. Un test
+    vérifie désormais que chaque import relatif de chaque entrée est apporté par
+    son installation.
+  - **`sia-ui.css`** pose `box-sizing: border-box` (spécificité nulle). Sans
+    reset côté projet, `AppShell` débordait de 32 px.
+  - **`@sia-ui/api`** ne rejoue plus d'office que `GET` et `HEAD`
+    (`retryMethods`). Une écriture n'est rejouée que si l'appel pose `retry`.
+  - Plus aucun avertissement `react-hooks/exhaustive-deps` dans les composants.
+
+  ## Formulaires et erreurs serveur
+  - `Form` intercepte un envoi rejeté : erreurs de champ sous les champs, le
+    reste dans une alerte. `onSubmit` peut aussi rendre `{ champ: message }`
+    (`FormSubmitResult`), dans `useLocalForm`, `Form`, `CrudPage` et
+    l'adaptateur react-hook-form. `CrudPage` garde alors sa boîte ouverte.
+  - Les erreurs posées par `setErrors` survivent à la validation locale jusqu'à
+    la modification de leur champ.
+  - `HttpError.toFormErrors()`, option `fieldErrors` du client et préréglage
+    `nestFieldErrors` (class-validator). `readSubmitError` et `hasFormErrors`
+    dans `@sia-ui/headless`.
+  - La pagination à plat `{ data, total, page, limit }` est reconnue, et `get`
+    ne déballe plus `data` quand l'objet porte une pagination.
+
+  ## Tableaux
+  - `searchDelay` sur `DataTable` et `CrudPage`.
+  - `CrudPage` place les `extraRowActions` avant « Supprimer ».
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.5.0
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -4,21 +4,46 @@ var async = require('@sia-ui/utils/async');
 var query = require('@sia-ui/utils/query');
 
 // src/http-error.ts
+var NEST_FIELD = /^([A-Za-z_$][\w$]*(?:\.[\w$]+)*)\s/;
+var nestFieldErrors = (body) => {
+  const standard = HttpError.extractFields(body);
+  if (standard.length > 0 || !body || typeof body !== "object") return standard;
+  const messages = body.message;
+  if (!Array.isArray(messages)) return [];
+  return messages.flatMap((message) => {
+    if (typeof message !== "string") return [];
+    const field = NEST_FIELD.exec(message)?.[1];
+    return field ? [{ field, message }] : [];
+  });
+};
 var HttpError = class _HttpError extends Error {
   status;
   body;
   headers;
   /** Les erreurs par champ, quand le serveur en renvoie. */
   fields;
-  constructor(status, body = null, message, headers = {}) {
+  constructor(status, body = null, message, headers = {}, extractFields = _HttpError.extractFields) {
     super(message ?? _HttpError.extractMessage(body) ?? `HTTP ${status}`);
     this.name = "HttpError";
     this.status = status;
     this.body = body;
     this.headers = headers;
-    this.fields = _HttpError.extractFields(body);
+    this.fields = extractFields(body);
     Object.setPrototypeOf(this, _HttpError.prototype);
   }
+  /**
+   * Les erreurs par champ, sous la forme qu'attend un formulaire.
+   *
+   * `FormAdapter.setErrors` prend `{ champ: message }` : c'est cette carte.
+   * Le premier message d'un champ l'emporte — un champ n'en affiche qu'un.
+   */
+  toFormErrors() {
+    const errors = {};
+    for (const { field, message } of this.fields) {
+      if (!(field in errors)) errors[field] = message;
+    }
+    return errors;
+  }
   static async fromResponse(response) {
     const headers = _HttpError.normalizeHeaders(response.headers);
     const contentType = headers["content-type"] ?? "";
@@ -113,6 +138,66 @@ var HttpError = class _HttpError extends Error {
     return this.status >= 500;
   }
 };
+
+// src/status-messages.ts
+var FRENCH_STATUS_MESSAGES = {
+  0: "Le serveur est injoignable. V\xE9rifiez votre connexion.",
+  400: "La demande est invalide.",
+  401: "Votre session a expir\xE9. Reconnectez-vous.",
+  403: "Vous n'avez pas les droits n\xE9cessaires pour cette action.",
+  404: "L'\xE9l\xE9ment demand\xE9 est introuvable.",
+  408: "Le serveur a mis trop de temps \xE0 r\xE9pondre.",
+  409: "Cette op\xE9ration entre en conflit avec l'\xE9tat actuel. Rechargez puis r\xE9essayez.",
+  413: "Le contenu envoy\xE9 est trop volumineux.",
+  422: "Certaines valeurs sont invalides.",
+  429: "Trop de tentatives. R\xE9essayez dans un instant.",
+  500: "Une erreur est survenue sur le serveur.",
+  502: "Le service est momentan\xE9ment indisponible.",
+  503: "Le service est momentan\xE9ment indisponible.",
+  504: "Le serveur a mis trop de temps \xE0 r\xE9pondre."
+};
+var ECHEC_RESEAU = /failed to fetch|networkerror|load failed/i;
+var PHRASES = {
+  400: "bad request",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not found",
+  405: "method not allowed",
+  408: "request timeout",
+  409: "conflict",
+  413: "payload too large",
+  415: "unsupported media type",
+  422: "unprocessable entity",
+  429: "too many requests",
+  500: "internal server error",
+  502: "bad gateway",
+  503: "service unavailable",
+  504: "gateway timeout"
+};
+function isGenericMessage(status, message, body) {
+  const texte = message?.trim().toLowerCase();
+  if (!texte || texte === `http ${status}`) return true;
+  const phrase = PHRASES[status];
+  if (phrase && (texte === phrase || texte === `${phrase} resource`)) return true;
+  const erreur = body && typeof body === "object" ? body.error : void 0;
+  if (typeof erreur === "string" && texte === erreur.trim().toLowerCase()) {
+    return true;
+  }
+  return /^cannot (get|post|put|patch|delete|head) /.test(texte) || /exception\b/.test(texte);
+}
+function localizeError(error, messages) {
+  if (error instanceof HttpError) {
+    const remplacant = messages[error.status];
+    if (remplacant && error.fields.length === 0 && isGenericMessage(error.status, error.message, error.body)) {
+      error.message = remplacant;
+    }
+    return error;
+  }
+  if (error instanceof TypeError && messages[0] && ECHEC_RESEAU.test(error.message)) {
+    error.message = messages[0];
+  }
+  return error;
+}
 function buildQueryString(params) {
   return query.toQueryString(params);
 }
@@ -121,6 +206,10 @@ function buildQueryString(params) {
 function asRecord(value) {
   return value && typeof value === "object" ? value : null;
 }
+var PAGE_KEYS = ["total", "page", "limit", "totalPages"];
+function hasPageKeys(record) {
+  return PAGE_KEYS.some((key) => record[key] !== void 0);
+}
 var ResponseHandler = class {
   config;
   constructor(config = {}) {
@@ -129,7 +218,9 @@ var ResponseHandler = class {
   extractData(raw) {
     if (this.config.extractData) return this.config.extractData(raw);
     const record = asRecord(raw);
-    if (record && record.data !== void 0) return record.data;
+    if (record && record.data !== void 0 && !hasPageKeys(record)) {
+      return record.data;
+    }
     return raw;
   }
   extractPaginated(raw) {
@@ -155,11 +246,12 @@ var ResponseHandler = class {
     if (Array.isArray(data) && meta) {
       return { items: data, meta };
     }
-    if (Array.isArray(record.items)) {
-      const limit = Number(record.limit ?? record.items.length);
+    const items = Array.isArray(record.items) ? record.items : Array.isArray(data) && hasPageKeys(record) ? data : null;
+    if (items) {
+      const limit = Number(record.limit ?? items.length);
       const total = record.total === void 0 ? void 0 : Number(record.total);
       return {
-        items: record.items,
+        items,
         meta: {
           page: Number(record.page ?? 1),
           limit,
@@ -305,6 +397,7 @@ function createAxiosTransport(axios) {
 
 // src/client.ts
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 502, 503, 504]);
+var DEFAULT_RETRY_METHODS = ["GET", "HEAD"];
 function isAbsoluteUrl(path) {
   return /^https?:\/\//i.test(path);
 }
@@ -321,6 +414,9 @@ var ApiClient = class {
   getLanguage;
   defaultHeaders;
   defaultRetry;
+  retryMethods;
+  fieldErrors;
+  statusMessages;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -333,6 +429,11 @@ var ApiClient = class {
       "Content-Type": "application/json"
     };
     this.defaultRetry = options.defaultRetry ?? 2;
+    this.retryMethods = new Set(
+      (options.retryMethods ?? DEFAULT_RETRY_METHODS).map(normalizeMethod)
+    );
+    this.fieldErrors = options.fieldErrors;
+    this.statusMessages = options.statusMessages;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
     this.plugins = options.plugins ?? [];
     this.responseHandler = new ResponseHandler(options.responseHandler);
@@ -397,7 +498,7 @@ var ApiClient = class {
     };
     const onRequestResult = await this.runPlugins("onRequest", ctx);
     if (onRequestResult !== void 0) return onRequestResult;
-    const maxRetries = config.retry ?? this.defaultRetry;
+    const maxRetries = config.retry ?? (this.retryMethods.has(ctx.method) ? this.defaultRetry : 0);
     let attempt = 0;
     while (true) {
       try {
@@ -421,7 +522,8 @@ var ApiClient = class {
             response.status,
             response.data,
             void 0,
-            response.headers
+            response.headers,
+            this.fieldErrors
           );
         }
         if (response.status === 204) return null;
@@ -429,7 +531,9 @@ var ApiClient = class {
       } catch (error) {
         const pluginResult = await this.runPlugins("onError", error, ctx);
         if (pluginResult !== void 0) return pluginResult;
-        if (!this.shouldRetry(error, attempt, maxRetries)) throw error;
+        if (!this.shouldRetry(error, attempt, maxRetries)) {
+          throw this.statusMessages ? localizeError(error, this.statusMessages) : error;
+        }
         attempt += 1;
         const baseDelay = Math.min(1e3 * 2 ** attempt, 3e4);
         await async.sleep(baseDelay + Math.random() * 0.1 * baseDelay);
@@ -820,6 +924,10 @@ var BaseService = class {
     this.client = client;
     this.resource = resource;
   }
+  /** Le chemin de la ressource — sert aussi de racine aux clés de cache. */
+  get path() {
+    return this.resource;
+  }
   normalizeQueryParams(params) {
     if (!params || typeof params !== "object") return params;
     const normalized = { ...params };
@@ -903,10 +1011,53 @@ function createResourceService(client, resourcePath) {
   return new BaseService(client, resourcePath);
 }
 
+// src/query-resource.ts
+function createQueryResource(service, options = {}) {
+  const racine = options.name ?? service.path;
+  const keys = {
+    all: [racine],
+    lists: () => [racine, "list"],
+    list: (params) => [racine, "list", params ?? {}],
+    details: () => [racine, "detail"],
+    detail: (id) => [racine, "detail", id]
+  };
+  const invalider = (client, ...cles) => Promise.all(cles.map((queryKey) => client.invalidateQueries({ queryKey })));
+  return {
+    keys,
+    /** Une liste nue — `service.list`. */
+    listQuery: (params) => ({
+      queryKey: keys.list(params),
+      queryFn: ({ signal } = {}) => service.list(params, { signal })
+    }),
+    /** Une page — `service.paginated`, rendue en `{ items, meta }`. */
+    pageQuery: (page = {}) => ({
+      queryKey: keys.list(page),
+      queryFn: ({ signal } = {}) => service.paginated({ ...page, config: { signal } })
+    }),
+    detailQuery: (id) => ({
+      queryKey: keys.detail(id),
+      queryFn: ({ signal } = {}) => service.getById(id, { signal })
+    }),
+    /**
+     * Crée sans `id`, modifie avec. Invalide les listes, et le détail
+     * modifié : c'est ce que chaque écran écrivait à la main, ou oubliait.
+     */
+    saveMutation: (client) => ({
+      mutationFn: ({ id, values }) => id === void 0 ? service.create(values) : service.update(id, values),
+      onSuccess: (_, { id }) => id === void 0 ? invalider(client, keys.lists()) : invalider(client, keys.lists(), keys.detail(id))
+    }),
+    removeMutation: (client) => ({
+      mutationFn: (id) => service.remove(id),
+      onSuccess: (_, id) => invalider(client, keys.lists(), keys.detail(id))
+    })
+  };
+}
+
 exports.ACCESS_TOKEN_KEY = ACCESS_TOKEN_KEY;
 exports.ApiClient = ApiClient;
 exports.BaseService = BaseService;
 exports.FILTERS_HEADER = FILTERS_HEADER;
+exports.FRENCH_STATUS_MESSAGES = FRENCH_STATUS_MESSAGES;
 exports.HttpError = HttpError;
 exports.REFRESH_TOKEN_KEY = REFRESH_TOKEN_KEY;
 exports.ResponseHandler = ResponseHandler;
@@ -920,9 +1071,13 @@ exports.createHeaderSignalPlugin = createHeaderSignalPlugin;
 exports.createIdempotencyPlugin = createIdempotencyPlugin;
 exports.createLoggerPlugin = createLoggerPlugin;
 exports.createMemoryTokenStorage = createMemoryTokenStorage;
+exports.createQueryResource = createQueryResource;
 exports.createReadOnlyPlugin = createReadOnlyPlugin;
 exports.createRefreshTokenPlugin = createRefreshTokenPlugin;
 exports.createResourceService = createResourceService;
 exports.createUnauthorizedPlugin = createUnauthorizedPlugin;
 exports.filtersHeader = filtersHeader;
+exports.isGenericMessage = isGenericMessage;
+exports.localizeError = localizeError;
+exports.nestFieldErrors = nestFieldErrors;
 exports.normalizeFilters = normalizeFilters;

package/dist/index.d.cts

@@ -1,3 +1,63 @@
+/**
+ * Une erreur de validation rattachée à un champ.
+ *
+ * C'est ce qui permet à un formulaire d'afficher « adresse invalide » sous
+ * l'adresse plutôt qu'un bandeau générique en haut de page.
+ */
+interface FieldError {
+    field: string;
+    message: string;
+    code?: string | undefined;
+}
+/**
+ * Lit les erreurs par champ dans un corps d'erreur.
+ *
+ * Chaque serveur a sa forme ; celle-ci se règle une fois sur le client
+ * (`fieldErrors` de `createApiClient`) plutôt qu'à chaque formulaire.
+ */
+type FieldErrorExtractor = (body: unknown) => FieldError[];
+/**
+ * Le préréglage NestJS.
+ *
+ * `ValidationPipe` renvoie `{ message: string[] }`, chaque phrase commençant
+ * par le chemin du champ : « email must be an email », « address.city should
+ * not be empty ». Le champ est ce premier mot ; le message reste la phrase
+ * entière, que le serveur a écrite pour être lue. Les formes génériques
+ * (`errors`, `fieldErrors`, `violations`) passent d'abord : un
+ * `exceptionFactory` personnalisé les produit souvent.
+ */
+declare const nestFieldErrors: FieldErrorExtractor;
+declare class HttpError extends Error {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+    /** Les erreurs par champ, quand le serveur en renvoie. */
+    fields: FieldError[];
+    constructor(status: number, body?: unknown, message?: string, headers?: Record<string, string>, extractFields?: FieldErrorExtractor);
+    /**
+     * Les erreurs par champ, sous la forme qu'attend un formulaire.
+     *
+     * `FormAdapter.setErrors` prend `{ champ: message }` : c'est cette carte.
+     * Le premier message d'un champ l'emporte — un champ n'en affiche qu'un.
+     */
+    toFormErrors(): Record<string, string>;
+    static fromResponse(response: Response): Promise<HttpError>;
+    /**
+     * Retrouve les erreurs par champ dans un corps d'erreur.
+     *
+     * Trois formes couvertes, parce que trois serveurs sur quatre en utilisent
+     * une : la liste (`errors: [{ field, message }]`), la carte
+     * (`errors: { email: "…" }`) et la carte de listes, que produit Laravel.
+     */
+    static extractFields(body: unknown): FieldError[];
+    /** Le message rattaché à ce champ, s'il y en a un. */
+    fieldError(field: string): string | undefined;
+    static normalizeHeaders(headers: unknown): Record<string, string>;
+    static extractMessage(body: unknown): string | null;
+    isClientError(): boolean;
+    isServerError(): boolean;
+}
+
 type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
 type QueryParamObject = Record<string, unknown>;
 type QueryParams = Record<string, string | string[] | number | number[] | boolean | boolean[] | QueryParamObject | QueryParamObject[] | null | undefined>;
@@ -79,10 +139,33 @@ interface ApiClientOptions {
     getToken?: (() => string | null | Promise<string | null>) | undefined;
     getLanguage?: (() => string | null | Promise<string | null>) | undefined;
     defaultHeaders?: Record<string, string> | undefined;
+    /**
+     * Nouvelles tentatives sur erreur réseau ou statut transitoire (408, 429,
+     * 502, 503, 504), pour les seules `retryMethods`. `retry` sur un appel
+     * passe devant.
+     */
     defaultRetry?: number | undefined;
+    /** Les méthodes rejouées d'office. Par défaut `GET` et `HEAD`. */
+    retryMethods?: ApiMethod[] | undefined;
     defaultTimeoutMs?: number | undefined;
     plugins?: ApiPlugin[] | undefined;
     responseHandler?: ResponseHandlerConfig | undefined;
+    /**
+     * Où lire les erreurs par champ d'une réponse en échec.
+     *
+     * Par défaut `errors`, `fieldErrors` ou `violations`. `nestFieldErrors`
+     * lit en plus le `message: string[]` de class-validator.
+     */
+    fieldErrors?: ((body: unknown) => FieldError[]) | undefined;
+    /**
+     * Des messages par statut, à la place des messages génériques du serveur.
+     *
+     * `FRENCH_STATUS_MESSAGES` couvre les cas courants. Seul un message qui
+     * n'apprend rien est remplacé — « Conflict », « Forbidden resource »,
+     * « Cannot GET /x » — jamais un message métier. `0` vaut pour l'échec
+     * réseau.
+     */
+    statusMessages?: Readonly<Record<number, string>> | undefined;
 }
 type ApiRequestInput = string | {
     path: string;
@@ -104,6 +187,9 @@ declare class ApiClient {
     private getLanguage;
     private defaultHeaders;
     private defaultRetry;
+    private retryMethods;
+    private fieldErrors;
+    private statusMessages;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -159,39 +245,29 @@ declare class ApiClient {
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
 /**
- * Une erreur de validation rattachée à un champ.
+ * Les messages par statut, en français.
  *
- * C'est ce qui permet à un formulaire d'afficher « adresse invalide » sous
- * l'adresse plutôt qu'un bandeau générique en haut de page.
+ * `0` couvre l'échec réseau : le serveur injoignable, la connexion coupée.
  */
-interface FieldError {
-    field: string;
-    message: string;
-    code?: string | undefined;
-}
-declare class HttpError extends Error {
-    status: number;
-    body: unknown;
-    headers: Record<string, string>;
-    /** Les erreurs par champ, quand le serveur en renvoie. */
-    fields: FieldError[];
-    constructor(status: number, body?: unknown, message?: string, headers?: Record<string, string>);
-    static fromResponse(response: Response): Promise<HttpError>;
-    /**
-     * Retrouve les erreurs par champ dans un corps d'erreur.
-     *
-     * Trois formes couvertes, parce que trois serveurs sur quatre en utilisent
-     * une : la liste (`errors: [{ field, message }]`), la carte
-     * (`errors: { email: "…" }`) et la carte de listes, que produit Laravel.
-     */
-    static extractFields(body: unknown): FieldError[];
-    /** Le message rattaché à ce champ, s'il y en a un. */
-    fieldError(field: string): string | undefined;
-    static normalizeHeaders(headers: unknown): Record<string, string>;
-    static extractMessage(body: unknown): string | null;
-    isClientError(): boolean;
-    isServerError(): boolean;
-}
+declare const FRENCH_STATUS_MESSAGES: Readonly<Record<number, string>>;
+/**
+ * Vrai quand le message du serveur est générique.
+ *
+ * Absent, la phrase HTTP du statut, le champ `error` de NestJS
+ * (`"Conflict"`), sa variante `"Forbidden resource"`, le 404 de route
+ * (`"Cannot GET /x"`) ou le nom d'une exception
+ * (`"ThrottlerException: Too Many Requests"`). Un message métier —
+ * « Ce client existe déjà » — ne l'est pas : il reste tel quel.
+ */
+declare function isGenericMessage(status: number, message: string | undefined, body?: unknown): boolean;
+/**
+ * Remplace un message générique par celui de la table.
+ *
+ * L'erreur garde son type et son corps : seul `message` change, et seulement
+ * s'il n'apprenait rien. Une erreur de champs n'est jamais touchée — ses
+ * messages par champ disent déjà ce qui ne va pas.
+ */
+declare function localizeError(error: unknown, messages: Readonly<Record<number, string>>): unknown;
 
 interface AuthPluginOptions {
     getToken: () => Promise<string | null> | string | null;
@@ -349,6 +425,8 @@ declare class BaseService<TEntity, TCreateDTO = Partial<TEntity>, TUpdateDTO = P
     protected client: ApiClient;
     protected resource: string;
     constructor(client: ApiClient, resource: string);
+    /** Le chemin de la ressource — sert aussi de racine aux clés de cache. */
+    get path(): string;
     protected normalizeQueryParams(params?: TListParams): TListParams | undefined;
     list(params?: TListParams, config?: ApiRequestConfig): Promise<TEntity[]>;
     getById(id: string, config?: ApiRequestConfig): Promise<TEntity>;
@@ -388,6 +466,94 @@ declare class BaseService<TEntity, TCreateDTO = Partial<TEntity>, TUpdateDTO = P
 }
 declare function createResourceService<TEntity>(client: ApiClient, resourcePath: string): BaseService<TEntity, Partial<TEntity>, Partial<TEntity>, QueryParams>;
 
+/**
+ * Ce que l'invalidation demande d'un client de cache.
+ *
+ * Le `QueryClient` de TanStack Query le satisfait tel quel ; aucune
+ * dépendance n'est donc tirée ici. Un autre cache n'a qu'à fournir cette
+ * seule méthode.
+ */
+interface QueryInvalidator {
+    invalidateQueries: (filters: {
+        queryKey: readonly unknown[];
+    }) => unknown;
+}
+/** Le contexte qu'un `queryFn` reçoit — seul le signal d'annulation sert. */
+interface QueryFnContext {
+    signal?: AbortSignal | undefined;
+}
+/** Ce que reçoit `saveMutation` : sans `id`, une création. */
+interface SaveVariables<TCreate, TUpdate> {
+    id?: string | undefined;
+    values: TCreate | TUpdate;
+}
+interface QueryResourceOptions {
+    /**
+     * La racine des clés. À défaut, le chemin du service.
+     *
+     * Deux ressources sous la même racine s'invalideraient l'une l'autre ;
+     * c'est ce nom qui les sépare.
+     */
+    name?: string | undefined;
+}
+/**
+ * Les clés et les options de requête d'une ressource.
+ *
+ * `api.query` se contentait de rendre le chargeur : chaque écran réinventait
+ * ses clés de cache, et la moitié oubliait d'invalider la liste après une
+ * création. Ici, les clés s'emboîtent — `lists()` couvre toutes les listes,
+ * quels qu'en soient les filtres — et chaque mutation sait ce qu'elle rend
+ * périmé.
+ *
+ * ```tsx
+ * const factures = createQueryResource(factureService);
+ *
+ * const { data } = useQuery(factures.pageQuery({ page, limit: 20 }));
+ * const enregistrer = useMutation(factures.saveMutation(queryClient));
+ * enregistrer.mutate({ id, values }); // crée sans id, modifie avec
+ * ```
+ */
+declare function createQueryResource<TEntity, TCreate = Partial<TEntity>, TUpdate = Partial<TEntity>, TParams extends QueryParams = QueryParams>(service: BaseService<TEntity, TCreate, TUpdate, TParams>, options?: QueryResourceOptions): {
+    keys: {
+        all: readonly [string];
+        lists: () => readonly [string, "list"];
+        list: (params?: unknown) => readonly [string, "list", {}];
+        details: () => readonly [string, "detail"];
+        detail: (id: string) => readonly [string, "detail", string];
+    };
+    /** Une liste nue — `service.list`. */
+    listQuery: (params?: TParams) => {
+        queryKey: readonly [string, "list", {}];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<TEntity[]>;
+    };
+    /** Une page — `service.paginated`, rendue en `{ items, meta }`. */
+    pageQuery: (page?: {
+        page?: number;
+        limit?: number;
+        query?: TParams;
+    }) => {
+        queryKey: readonly [string, "list", {}];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<PaginatedResponse<TEntity>>;
+    };
+    detailQuery: (id: string) => {
+        queryKey: readonly [string, "detail", string];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<TEntity>;
+    };
+    /**
+     * Crée sans `id`, modifie avec. Invalide les listes, et le détail
+     * modifié : c'est ce que chaque écran écrivait à la main, ou oubliait.
+     */
+    saveMutation: (client: QueryInvalidator) => {
+        mutationFn: ({ id, values }: SaveVariables<TCreate, TUpdate>) => Promise<TEntity>;
+        onSuccess: (_: TEntity, { id }: SaveVariables<TCreate, TUpdate>) => Promise<unknown[]>;
+    };
+    removeMutation: (client: QueryInvalidator) => {
+        mutationFn: (id: string) => Promise<void>;
+        onSuccess: (_: void, id: string) => Promise<unknown[]>;
+    };
+};
+type QueryResource<TEntity> = ReturnType<typeof createQueryResource<TEntity>>;
+
 interface AxiosLikeInstance {
     request<T = unknown>(config: {
         url: string;
@@ -410,4 +576,4 @@ interface AxiosLikeInstance {
 declare function createFetchTransport(fetcher?: typeof fetch): ApiTransport;
 declare function createAxiosTransport(axios: AxiosLikeInstance): ApiTransport;
 
-export { ACCESS_TOKEN_KEY, ApiClient, type ApiClientOptions, type ApiFilters, type ApiMethod, type ApiPlugin, type ApiPluginHook, type ApiRequestConfig, type ApiRequestContext, type ApiRequestInput, type ApiTransport, type ApiTransportRequest, type ApiTransportResponse, type AuthPluginOptions, BaseService, type BrowserTokenStorageOptions, type CursorMeta, FILTERS_HEADER, type FieldError, type FilterCondition, type FilterGroup, type FilterOperator, type FilterValue, type HeaderSignalPluginOptions, HttpError, type IdempotencyPluginOptions, type LoggerPluginOptions, type PageMeta, type PaginatedResponse, type QueryParamObject, type QueryParams, REFRESH_TOKEN_KEY, type RefreshTokenConfig, ResponseHandler, type ResponseHandlerConfig, type RtkBaseQueryResult, type TokenStorage, type UnauthorizedPluginOptions, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, normalizeFilters };
+export { ACCESS_TOKEN_KEY, ApiClient, type ApiClientOptions, type ApiFilters, type ApiMethod, type ApiPlugin, type ApiPluginHook, type ApiRequestConfig, type ApiRequestContext, type ApiRequestInput, type ApiTransport, type ApiTransportRequest, type ApiTransportResponse, type AuthPluginOptions, BaseService, type BrowserTokenStorageOptions, type CursorMeta, FILTERS_HEADER, FRENCH_STATUS_MESSAGES, type FieldError, type FieldErrorExtractor, type FilterCondition, type FilterGroup, type FilterOperator, type FilterValue, type HeaderSignalPluginOptions, HttpError, type IdempotencyPluginOptions, type LoggerPluginOptions, type PageMeta, type PaginatedResponse, type QueryFnContext, type QueryInvalidator, type QueryParamObject, type QueryParams, type QueryResource, type QueryResourceOptions, REFRESH_TOKEN_KEY, type RefreshTokenConfig, ResponseHandler, type ResponseHandlerConfig, type RtkBaseQueryResult, type SaveVariables, type TokenStorage, type UnauthorizedPluginOptions, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createQueryResource, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, isGenericMessage, localizeError, nestFieldErrors, normalizeFilters };

package/dist/index.d.ts

@@ -1,3 +1,63 @@
+/**
+ * Une erreur de validation rattachée à un champ.
+ *
+ * C'est ce qui permet à un formulaire d'afficher « adresse invalide » sous
+ * l'adresse plutôt qu'un bandeau générique en haut de page.
+ */
+interface FieldError {
+    field: string;
+    message: string;
+    code?: string | undefined;
+}
+/**
+ * Lit les erreurs par champ dans un corps d'erreur.
+ *
+ * Chaque serveur a sa forme ; celle-ci se règle une fois sur le client
+ * (`fieldErrors` de `createApiClient`) plutôt qu'à chaque formulaire.
+ */
+type FieldErrorExtractor = (body: unknown) => FieldError[];
+/**
+ * Le préréglage NestJS.
+ *
+ * `ValidationPipe` renvoie `{ message: string[] }`, chaque phrase commençant
+ * par le chemin du champ : « email must be an email », « address.city should
+ * not be empty ». Le champ est ce premier mot ; le message reste la phrase
+ * entière, que le serveur a écrite pour être lue. Les formes génériques
+ * (`errors`, `fieldErrors`, `violations`) passent d'abord : un
+ * `exceptionFactory` personnalisé les produit souvent.
+ */
+declare const nestFieldErrors: FieldErrorExtractor;
+declare class HttpError extends Error {
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+    /** Les erreurs par champ, quand le serveur en renvoie. */
+    fields: FieldError[];
+    constructor(status: number, body?: unknown, message?: string, headers?: Record<string, string>, extractFields?: FieldErrorExtractor);
+    /**
+     * Les erreurs par champ, sous la forme qu'attend un formulaire.
+     *
+     * `FormAdapter.setErrors` prend `{ champ: message }` : c'est cette carte.
+     * Le premier message d'un champ l'emporte — un champ n'en affiche qu'un.
+     */
+    toFormErrors(): Record<string, string>;
+    static fromResponse(response: Response): Promise<HttpError>;
+    /**
+     * Retrouve les erreurs par champ dans un corps d'erreur.
+     *
+     * Trois formes couvertes, parce que trois serveurs sur quatre en utilisent
+     * une : la liste (`errors: [{ field, message }]`), la carte
+     * (`errors: { email: "…" }`) et la carte de listes, que produit Laravel.
+     */
+    static extractFields(body: unknown): FieldError[];
+    /** Le message rattaché à ce champ, s'il y en a un. */
+    fieldError(field: string): string | undefined;
+    static normalizeHeaders(headers: unknown): Record<string, string>;
+    static extractMessage(body: unknown): string | null;
+    isClientError(): boolean;
+    isServerError(): boolean;
+}
+
 type ApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
 type QueryParamObject = Record<string, unknown>;
 type QueryParams = Record<string, string | string[] | number | number[] | boolean | boolean[] | QueryParamObject | QueryParamObject[] | null | undefined>;
@@ -79,10 +139,33 @@ interface ApiClientOptions {
     getToken?: (() => string | null | Promise<string | null>) | undefined;
     getLanguage?: (() => string | null | Promise<string | null>) | undefined;
     defaultHeaders?: Record<string, string> | undefined;
+    /**
+     * Nouvelles tentatives sur erreur réseau ou statut transitoire (408, 429,
+     * 502, 503, 504), pour les seules `retryMethods`. `retry` sur un appel
+     * passe devant.
+     */
     defaultRetry?: number | undefined;
+    /** Les méthodes rejouées d'office. Par défaut `GET` et `HEAD`. */
+    retryMethods?: ApiMethod[] | undefined;
     defaultTimeoutMs?: number | undefined;
     plugins?: ApiPlugin[] | undefined;
     responseHandler?: ResponseHandlerConfig | undefined;
+    /**
+     * Où lire les erreurs par champ d'une réponse en échec.
+     *
+     * Par défaut `errors`, `fieldErrors` ou `violations`. `nestFieldErrors`
+     * lit en plus le `message: string[]` de class-validator.
+     */
+    fieldErrors?: ((body: unknown) => FieldError[]) | undefined;
+    /**
+     * Des messages par statut, à la place des messages génériques du serveur.
+     *
+     * `FRENCH_STATUS_MESSAGES` couvre les cas courants. Seul un message qui
+     * n'apprend rien est remplacé — « Conflict », « Forbidden resource »,
+     * « Cannot GET /x » — jamais un message métier. `0` vaut pour l'échec
+     * réseau.
+     */
+    statusMessages?: Readonly<Record<number, string>> | undefined;
 }
 type ApiRequestInput = string | {
     path: string;
@@ -104,6 +187,9 @@ declare class ApiClient {
     private getLanguage;
     private defaultHeaders;
     private defaultRetry;
+    private retryMethods;
+    private fieldErrors;
+    private statusMessages;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -159,39 +245,29 @@ declare class ApiClient {
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
 /**
- * Une erreur de validation rattachée à un champ.
+ * Les messages par statut, en français.
  *
- * C'est ce qui permet à un formulaire d'afficher « adresse invalide » sous
- * l'adresse plutôt qu'un bandeau générique en haut de page.
+ * `0` couvre l'échec réseau : le serveur injoignable, la connexion coupée.
  */
-interface FieldError {
-    field: string;
-    message: string;
-    code?: string | undefined;
-}
-declare class HttpError extends Error {
-    status: number;
-    body: unknown;
-    headers: Record<string, string>;
-    /** Les erreurs par champ, quand le serveur en renvoie. */
-    fields: FieldError[];
-    constructor(status: number, body?: unknown, message?: string, headers?: Record<string, string>);
-    static fromResponse(response: Response): Promise<HttpError>;
-    /**
-     * Retrouve les erreurs par champ dans un corps d'erreur.
-     *
-     * Trois formes couvertes, parce que trois serveurs sur quatre en utilisent
-     * une : la liste (`errors: [{ field, message }]`), la carte
-     * (`errors: { email: "…" }`) et la carte de listes, que produit Laravel.
-     */
-    static extractFields(body: unknown): FieldError[];
-    /** Le message rattaché à ce champ, s'il y en a un. */
-    fieldError(field: string): string | undefined;
-    static normalizeHeaders(headers: unknown): Record<string, string>;
-    static extractMessage(body: unknown): string | null;
-    isClientError(): boolean;
-    isServerError(): boolean;
-}
+declare const FRENCH_STATUS_MESSAGES: Readonly<Record<number, string>>;
+/**
+ * Vrai quand le message du serveur est générique.
+ *
+ * Absent, la phrase HTTP du statut, le champ `error` de NestJS
+ * (`"Conflict"`), sa variante `"Forbidden resource"`, le 404 de route
+ * (`"Cannot GET /x"`) ou le nom d'une exception
+ * (`"ThrottlerException: Too Many Requests"`). Un message métier —
+ * « Ce client existe déjà » — ne l'est pas : il reste tel quel.
+ */
+declare function isGenericMessage(status: number, message: string | undefined, body?: unknown): boolean;
+/**
+ * Remplace un message générique par celui de la table.
+ *
+ * L'erreur garde son type et son corps : seul `message` change, et seulement
+ * s'il n'apprenait rien. Une erreur de champs n'est jamais touchée — ses
+ * messages par champ disent déjà ce qui ne va pas.
+ */
+declare function localizeError(error: unknown, messages: Readonly<Record<number, string>>): unknown;
 
 interface AuthPluginOptions {
     getToken: () => Promise<string | null> | string | null;
@@ -349,6 +425,8 @@ declare class BaseService<TEntity, TCreateDTO = Partial<TEntity>, TUpdateDTO = P
     protected client: ApiClient;
     protected resource: string;
     constructor(client: ApiClient, resource: string);
+    /** Le chemin de la ressource — sert aussi de racine aux clés de cache. */
+    get path(): string;
     protected normalizeQueryParams(params?: TListParams): TListParams | undefined;
     list(params?: TListParams, config?: ApiRequestConfig): Promise<TEntity[]>;
     getById(id: string, config?: ApiRequestConfig): Promise<TEntity>;
@@ -388,6 +466,94 @@ declare class BaseService<TEntity, TCreateDTO = Partial<TEntity>, TUpdateDTO = P
 }
 declare function createResourceService<TEntity>(client: ApiClient, resourcePath: string): BaseService<TEntity, Partial<TEntity>, Partial<TEntity>, QueryParams>;
 
+/**
+ * Ce que l'invalidation demande d'un client de cache.
+ *
+ * Le `QueryClient` de TanStack Query le satisfait tel quel ; aucune
+ * dépendance n'est donc tirée ici. Un autre cache n'a qu'à fournir cette
+ * seule méthode.
+ */
+interface QueryInvalidator {
+    invalidateQueries: (filters: {
+        queryKey: readonly unknown[];
+    }) => unknown;
+}
+/** Le contexte qu'un `queryFn` reçoit — seul le signal d'annulation sert. */
+interface QueryFnContext {
+    signal?: AbortSignal | undefined;
+}
+/** Ce que reçoit `saveMutation` : sans `id`, une création. */
+interface SaveVariables<TCreate, TUpdate> {
+    id?: string | undefined;
+    values: TCreate | TUpdate;
+}
+interface QueryResourceOptions {
+    /**
+     * La racine des clés. À défaut, le chemin du service.
+     *
+     * Deux ressources sous la même racine s'invalideraient l'une l'autre ;
+     * c'est ce nom qui les sépare.
+     */
+    name?: string | undefined;
+}
+/**
+ * Les clés et les options de requête d'une ressource.
+ *
+ * `api.query` se contentait de rendre le chargeur : chaque écran réinventait
+ * ses clés de cache, et la moitié oubliait d'invalider la liste après une
+ * création. Ici, les clés s'emboîtent — `lists()` couvre toutes les listes,
+ * quels qu'en soient les filtres — et chaque mutation sait ce qu'elle rend
+ * périmé.
+ *
+ * ```tsx
+ * const factures = createQueryResource(factureService);
+ *
+ * const { data } = useQuery(factures.pageQuery({ page, limit: 20 }));
+ * const enregistrer = useMutation(factures.saveMutation(queryClient));
+ * enregistrer.mutate({ id, values }); // crée sans id, modifie avec
+ * ```
+ */
+declare function createQueryResource<TEntity, TCreate = Partial<TEntity>, TUpdate = Partial<TEntity>, TParams extends QueryParams = QueryParams>(service: BaseService<TEntity, TCreate, TUpdate, TParams>, options?: QueryResourceOptions): {
+    keys: {
+        all: readonly [string];
+        lists: () => readonly [string, "list"];
+        list: (params?: unknown) => readonly [string, "list", {}];
+        details: () => readonly [string, "detail"];
+        detail: (id: string) => readonly [string, "detail", string];
+    };
+    /** Une liste nue — `service.list`. */
+    listQuery: (params?: TParams) => {
+        queryKey: readonly [string, "list", {}];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<TEntity[]>;
+    };
+    /** Une page — `service.paginated`, rendue en `{ items, meta }`. */
+    pageQuery: (page?: {
+        page?: number;
+        limit?: number;
+        query?: TParams;
+    }) => {
+        queryKey: readonly [string, "list", {}];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<PaginatedResponse<TEntity>>;
+    };
+    detailQuery: (id: string) => {
+        queryKey: readonly [string, "detail", string];
+        queryFn: ({ signal }?: QueryFnContext) => Promise<TEntity>;
+    };
+    /**
+     * Crée sans `id`, modifie avec. Invalide les listes, et le détail
+     * modifié : c'est ce que chaque écran écrivait à la main, ou oubliait.
+     */
+    saveMutation: (client: QueryInvalidator) => {
+        mutationFn: ({ id, values }: SaveVariables<TCreate, TUpdate>) => Promise<TEntity>;
+        onSuccess: (_: TEntity, { id }: SaveVariables<TCreate, TUpdate>) => Promise<unknown[]>;
+    };
+    removeMutation: (client: QueryInvalidator) => {
+        mutationFn: (id: string) => Promise<void>;
+        onSuccess: (_: void, id: string) => Promise<unknown[]>;
+    };
+};
+type QueryResource<TEntity> = ReturnType<typeof createQueryResource<TEntity>>;
+
 interface AxiosLikeInstance {
     request<T = unknown>(config: {
         url: string;
@@ -410,4 +576,4 @@ interface AxiosLikeInstance {
 declare function createFetchTransport(fetcher?: typeof fetch): ApiTransport;
 declare function createAxiosTransport(axios: AxiosLikeInstance): ApiTransport;
 
-export { ACCESS_TOKEN_KEY, ApiClient, type ApiClientOptions, type ApiFilters, type ApiMethod, type ApiPlugin, type ApiPluginHook, type ApiRequestConfig, type ApiRequestContext, type ApiRequestInput, type ApiTransport, type ApiTransportRequest, type ApiTransportResponse, type AuthPluginOptions, BaseService, type BrowserTokenStorageOptions, type CursorMeta, FILTERS_HEADER, type FieldError, type FilterCondition, type FilterGroup, type FilterOperator, type FilterValue, type HeaderSignalPluginOptions, HttpError, type IdempotencyPluginOptions, type LoggerPluginOptions, type PageMeta, type PaginatedResponse, type QueryParamObject, type QueryParams, REFRESH_TOKEN_KEY, type RefreshTokenConfig, ResponseHandler, type ResponseHandlerConfig, type RtkBaseQueryResult, type TokenStorage, type UnauthorizedPluginOptions, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, normalizeFilters };
+export { ACCESS_TOKEN_KEY, ApiClient, type ApiClientOptions, type ApiFilters, type ApiMethod, type ApiPlugin, type ApiPluginHook, type ApiRequestConfig, type ApiRequestContext, type ApiRequestInput, type ApiTransport, type ApiTransportRequest, type ApiTransportResponse, type AuthPluginOptions, BaseService, type BrowserTokenStorageOptions, type CursorMeta, FILTERS_HEADER, FRENCH_STATUS_MESSAGES, type FieldError, type FieldErrorExtractor, type FilterCondition, type FilterGroup, type FilterOperator, type FilterValue, type HeaderSignalPluginOptions, HttpError, type IdempotencyPluginOptions, type LoggerPluginOptions, type PageMeta, type PaginatedResponse, type QueryFnContext, type QueryInvalidator, type QueryParamObject, type QueryParams, type QueryResource, type QueryResourceOptions, REFRESH_TOKEN_KEY, type RefreshTokenConfig, ResponseHandler, type ResponseHandlerConfig, type RtkBaseQueryResult, type SaveVariables, type TokenStorage, type UnauthorizedPluginOptions, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createQueryResource, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, isGenericMessage, localizeError, nestFieldErrors, normalizeFilters };

package/dist/index.js

@@ -2,21 +2,46 @@ import { sleep } from '@sia-ui/utils/async';
 import { toQueryString } from '@sia-ui/utils/query';
 
 // src/http-error.ts
+var NEST_FIELD = /^([A-Za-z_$][\w$]*(?:\.[\w$]+)*)\s/;
+var nestFieldErrors = (body) => {
+  const standard = HttpError.extractFields(body);
+  if (standard.length > 0 || !body || typeof body !== "object") return standard;
+  const messages = body.message;
+  if (!Array.isArray(messages)) return [];
+  return messages.flatMap((message) => {
+    if (typeof message !== "string") return [];
+    const field = NEST_FIELD.exec(message)?.[1];
+    return field ? [{ field, message }] : [];
+  });
+};
 var HttpError = class _HttpError extends Error {
   status;
   body;
   headers;
   /** Les erreurs par champ, quand le serveur en renvoie. */
   fields;
-  constructor(status, body = null, message, headers = {}) {
+  constructor(status, body = null, message, headers = {}, extractFields = _HttpError.extractFields) {
     super(message ?? _HttpError.extractMessage(body) ?? `HTTP ${status}`);
     this.name = "HttpError";
     this.status = status;
     this.body = body;
     this.headers = headers;
-    this.fields = _HttpError.extractFields(body);
+    this.fields = extractFields(body);
     Object.setPrototypeOf(this, _HttpError.prototype);
   }
+  /**
+   * Les erreurs par champ, sous la forme qu'attend un formulaire.
+   *
+   * `FormAdapter.setErrors` prend `{ champ: message }` : c'est cette carte.
+   * Le premier message d'un champ l'emporte — un champ n'en affiche qu'un.
+   */
+  toFormErrors() {
+    const errors = {};
+    for (const { field, message } of this.fields) {
+      if (!(field in errors)) errors[field] = message;
+    }
+    return errors;
+  }
   static async fromResponse(response) {
     const headers = _HttpError.normalizeHeaders(response.headers);
     const contentType = headers["content-type"] ?? "";
@@ -111,6 +136,66 @@ var HttpError = class _HttpError extends Error {
     return this.status >= 500;
   }
 };
+
+// src/status-messages.ts
+var FRENCH_STATUS_MESSAGES = {
+  0: "Le serveur est injoignable. V\xE9rifiez votre connexion.",
+  400: "La demande est invalide.",
+  401: "Votre session a expir\xE9. Reconnectez-vous.",
+  403: "Vous n'avez pas les droits n\xE9cessaires pour cette action.",
+  404: "L'\xE9l\xE9ment demand\xE9 est introuvable.",
+  408: "Le serveur a mis trop de temps \xE0 r\xE9pondre.",
+  409: "Cette op\xE9ration entre en conflit avec l'\xE9tat actuel. Rechargez puis r\xE9essayez.",
+  413: "Le contenu envoy\xE9 est trop volumineux.",
+  422: "Certaines valeurs sont invalides.",
+  429: "Trop de tentatives. R\xE9essayez dans un instant.",
+  500: "Une erreur est survenue sur le serveur.",
+  502: "Le service est momentan\xE9ment indisponible.",
+  503: "Le service est momentan\xE9ment indisponible.",
+  504: "Le serveur a mis trop de temps \xE0 r\xE9pondre."
+};
+var ECHEC_RESEAU = /failed to fetch|networkerror|load failed/i;
+var PHRASES = {
+  400: "bad request",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not found",
+  405: "method not allowed",
+  408: "request timeout",
+  409: "conflict",
+  413: "payload too large",
+  415: "unsupported media type",
+  422: "unprocessable entity",
+  429: "too many requests",
+  500: "internal server error",
+  502: "bad gateway",
+  503: "service unavailable",
+  504: "gateway timeout"
+};
+function isGenericMessage(status, message, body) {
+  const texte = message?.trim().toLowerCase();
+  if (!texte || texte === `http ${status}`) return true;
+  const phrase = PHRASES[status];
+  if (phrase && (texte === phrase || texte === `${phrase} resource`)) return true;
+  const erreur = body && typeof body === "object" ? body.error : void 0;
+  if (typeof erreur === "string" && texte === erreur.trim().toLowerCase()) {
+    return true;
+  }
+  return /^cannot (get|post|put|patch|delete|head) /.test(texte) || /exception\b/.test(texte);
+}
+function localizeError(error, messages) {
+  if (error instanceof HttpError) {
+    const remplacant = messages[error.status];
+    if (remplacant && error.fields.length === 0 && isGenericMessage(error.status, error.message, error.body)) {
+      error.message = remplacant;
+    }
+    return error;
+  }
+  if (error instanceof TypeError && messages[0] && ECHEC_RESEAU.test(error.message)) {
+    error.message = messages[0];
+  }
+  return error;
+}
 function buildQueryString(params) {
   return toQueryString(params);
 }
@@ -119,6 +204,10 @@ function buildQueryString(params) {
 function asRecord(value) {
   return value && typeof value === "object" ? value : null;
 }
+var PAGE_KEYS = ["total", "page", "limit", "totalPages"];
+function hasPageKeys(record) {
+  return PAGE_KEYS.some((key) => record[key] !== void 0);
+}
 var ResponseHandler = class {
   config;
   constructor(config = {}) {
@@ -127,7 +216,9 @@ var ResponseHandler = class {
   extractData(raw) {
     if (this.config.extractData) return this.config.extractData(raw);
     const record = asRecord(raw);
-    if (record && record.data !== void 0) return record.data;
+    if (record && record.data !== void 0 && !hasPageKeys(record)) {
+      return record.data;
+    }
     return raw;
   }
   extractPaginated(raw) {
@@ -153,11 +244,12 @@ var ResponseHandler = class {
     if (Array.isArray(data) && meta) {
       return { items: data, meta };
     }
-    if (Array.isArray(record.items)) {
-      const limit = Number(record.limit ?? record.items.length);
+    const items = Array.isArray(record.items) ? record.items : Array.isArray(data) && hasPageKeys(record) ? data : null;
+    if (items) {
+      const limit = Number(record.limit ?? items.length);
       const total = record.total === void 0 ? void 0 : Number(record.total);
       return {
-        items: record.items,
+        items,
         meta: {
           page: Number(record.page ?? 1),
           limit,
@@ -303,6 +395,7 @@ function createAxiosTransport(axios) {
 
 // src/client.ts
 var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 502, 503, 504]);
+var DEFAULT_RETRY_METHODS = ["GET", "HEAD"];
 function isAbsoluteUrl(path) {
   return /^https?:\/\//i.test(path);
 }
@@ -319,6 +412,9 @@ var ApiClient = class {
   getLanguage;
   defaultHeaders;
   defaultRetry;
+  retryMethods;
+  fieldErrors;
+  statusMessages;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -331,6 +427,11 @@ var ApiClient = class {
       "Content-Type": "application/json"
     };
     this.defaultRetry = options.defaultRetry ?? 2;
+    this.retryMethods = new Set(
+      (options.retryMethods ?? DEFAULT_RETRY_METHODS).map(normalizeMethod)
+    );
+    this.fieldErrors = options.fieldErrors;
+    this.statusMessages = options.statusMessages;
     this.defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
     this.plugins = options.plugins ?? [];
     this.responseHandler = new ResponseHandler(options.responseHandler);
@@ -395,7 +496,7 @@ var ApiClient = class {
     };
     const onRequestResult = await this.runPlugins("onRequest", ctx);
     if (onRequestResult !== void 0) return onRequestResult;
-    const maxRetries = config.retry ?? this.defaultRetry;
+    const maxRetries = config.retry ?? (this.retryMethods.has(ctx.method) ? this.defaultRetry : 0);
     let attempt = 0;
     while (true) {
       try {
@@ -419,7 +520,8 @@ var ApiClient = class {
             response.status,
             response.data,
             void 0,
-            response.headers
+            response.headers,
+            this.fieldErrors
           );
         }
         if (response.status === 204) return null;
@@ -427,7 +529,9 @@ var ApiClient = class {
       } catch (error) {
         const pluginResult = await this.runPlugins("onError", error, ctx);
         if (pluginResult !== void 0) return pluginResult;
-        if (!this.shouldRetry(error, attempt, maxRetries)) throw error;
+        if (!this.shouldRetry(error, attempt, maxRetries)) {
+          throw this.statusMessages ? localizeError(error, this.statusMessages) : error;
+        }
         attempt += 1;
         const baseDelay = Math.min(1e3 * 2 ** attempt, 3e4);
         await sleep(baseDelay + Math.random() * 0.1 * baseDelay);
@@ -818,6 +922,10 @@ var BaseService = class {
     this.client = client;
     this.resource = resource;
   }
+  /** Le chemin de la ressource — sert aussi de racine aux clés de cache. */
+  get path() {
+    return this.resource;
+  }
   normalizeQueryParams(params) {
     if (!params || typeof params !== "object") return params;
     const normalized = { ...params };
@@ -901,4 +1009,46 @@ function createResourceService(client, resourcePath) {
   return new BaseService(client, resourcePath);
 }
 
-export { ACCESS_TOKEN_KEY, ApiClient, BaseService, FILTERS_HEADER, HttpError, REFRESH_TOKEN_KEY, ResponseHandler, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, normalizeFilters };
+// src/query-resource.ts
+function createQueryResource(service, options = {}) {
+  const racine = options.name ?? service.path;
+  const keys = {
+    all: [racine],
+    lists: () => [racine, "list"],
+    list: (params) => [racine, "list", params ?? {}],
+    details: () => [racine, "detail"],
+    detail: (id) => [racine, "detail", id]
+  };
+  const invalider = (client, ...cles) => Promise.all(cles.map((queryKey) => client.invalidateQueries({ queryKey })));
+  return {
+    keys,
+    /** Une liste nue — `service.list`. */
+    listQuery: (params) => ({
+      queryKey: keys.list(params),
+      queryFn: ({ signal } = {}) => service.list(params, { signal })
+    }),
+    /** Une page — `service.paginated`, rendue en `{ items, meta }`. */
+    pageQuery: (page = {}) => ({
+      queryKey: keys.list(page),
+      queryFn: ({ signal } = {}) => service.paginated({ ...page, config: { signal } })
+    }),
+    detailQuery: (id) => ({
+      queryKey: keys.detail(id),
+      queryFn: ({ signal } = {}) => service.getById(id, { signal })
+    }),
+    /**
+     * Crée sans `id`, modifie avec. Invalide les listes, et le détail
+     * modifié : c'est ce que chaque écran écrivait à la main, ou oubliait.
+     */
+    saveMutation: (client) => ({
+      mutationFn: ({ id, values }) => id === void 0 ? service.create(values) : service.update(id, values),
+      onSuccess: (_, { id }) => id === void 0 ? invalider(client, keys.lists()) : invalider(client, keys.lists(), keys.detail(id))
+    }),
+    removeMutation: (client) => ({
+      mutationFn: (id) => service.remove(id),
+      onSuccess: (_, id) => invalider(client, keys.lists(), keys.detail(id))
+    })
+  };
+}
+
+export { ACCESS_TOKEN_KEY, ApiClient, BaseService, FILTERS_HEADER, FRENCH_STATUS_MESSAGES, HttpError, REFRESH_TOKEN_KEY, ResponseHandler, buildQueryString, createApiClient, createAuthPlugin, createAxiosTransport, createBrowserTokenStorage, createFetchTransport, createHeaderSignalPlugin, createIdempotencyPlugin, createLoggerPlugin, createMemoryTokenStorage, createQueryResource, createReadOnlyPlugin, createRefreshTokenPlugin, createResourceService, createUnauthorizedPlugin, filtersHeader, isGenericMessage, localizeError, nestFieldErrors, normalizeFilters };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sia-ui/api",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Typed HTTP client with CRUD services, plugins and injectable transports.",
   "keywords": [
     "sia-ui",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sia-ui/utils": "0.4.0"
+    "@sia-ui/utils": "0.6.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",