@sia-ui/api 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @sia-ui/api
 
+## 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
+
+- Aligne tous les packages publics SIA UI sur la version 0.4.0 afin de fournir
+  un ensemble cohérent à installer, documenter et maintenir.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.4.0
+
 ## 0.3.2
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,5 @@
-<p align="center"><img src="https://beatjo.github.io/sia-ui-site/brand/sia-ui-logo.png" alt="SIA UI" width="320"></p>
-
+<p align="center"><img src="https://beatjo.github.io/sia-ui-site/brand/sia-ui-logo.png" alt="SIA UI" width="320"></p>
+
 # @sia-ui/api
 
 Un client HTTP typé, ses services CRUD et ses greffons. Aucun rapport avec
@@ -40,22 +40,90 @@ le projet utilise déjà axios. Le paquet ne dépend d'aucun des deux.
 | Filtres        | `$and` / `$or` portés par un en-tête plutôt que par l'URL                                   |
 
 Voir [docs/fondations/module-api.md](https://beatjo.github.io/sia-ui-site/fondations/module-api.html).
-
-## Contribuer
-
-Le code source principal de SIA UI est privé pour le moment. Les retours publics passent par le dépôt `BeatJo/sia-ui-site` : bugs, demandes de composants, corrections de documentation et questions d'usage.
-
-- Signaler un bug : https://github.com/BeatJo/sia-ui-site/issues
-- Lire la documentation : https://beatjo.github.io/sia-ui-site/
-- Voir la démonstration : https://beatjo.github.io/sia-ui-site/preview/
-
-Les contributions directes au code des packages se font sur invitation dans le dépôt source privé.
+
+## Contribuer
+
+Le code source principal de SIA UI est privé pour le moment. Les retours publics passent par le dépôt `BeatJo/sia-ui-site` : bugs, demandes de composants, corrections de documentation et questions d'usage.
+
+- Signaler un bug : https://github.com/BeatJo/sia-ui-site/issues
+- Lire la documentation : https://beatjo.github.io/sia-ui-site/
+- Voir la démonstration : https://beatjo.github.io/sia-ui-site/preview/
+
+Les contributions directes au code des packages se font sur invitation dans le dépôt source privé.
 ## Journal des changements
 
 Le contenu ci-dessous reprend intégralement `CHANGELOG.md` pour rester visible sur npm.
 
+<!-- sia:changelog:start -->
 # @sia-ui/api
 
+## 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
+
+- Aligne tous les packages publics SIA UI sur la version 0.4.0 afin de fournir
+  un ensemble cohérent à installer, documenter et maintenir.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sia-ui/utils@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Ajoute l’identité visuelle officielle de SIA UI et améliore la documentation publique, les changelogs et les ressources de contribution.
+- Updated dependencies
+  - @sia-ui/utils@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- Expose public contribution flow on npm
+- Updated dependencies
+  - @sia-ui/utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes
@@ -210,6 +278,7 @@ Le contenu ci-dessous reprend intégralement `CHANGELOG.md` pour rester visible
 
 - Updated dependencies [e4e4a72]
   - @sia-ui/utils@0.2.0
+<!-- sia:changelog:end -->
 
 ## Licence
 

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"] ?? "";
@@ -121,6 +146,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 +158,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 +186,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 +337,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 +354,8 @@ var ApiClient = class {
   getLanguage;
   defaultHeaders;
   defaultRetry;
+  retryMethods;
+  fieldErrors;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -333,6 +368,10 @@ 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.defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
     this.plugins = options.plugins ?? [];
     this.responseHandler = new ResponseHandler(options.responseHandler);
@@ -397,7 +436,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 +460,8 @@ var ApiClient = class {
             response.status,
             response.data,
             void 0,
-            response.headers
+            response.headers,
+            this.fieldErrors
           );
         }
         if (response.status === 204) return null;
@@ -925,4 +965,5 @@ exports.createRefreshTokenPlugin = createRefreshTokenPlugin;
 exports.createResourceService = createResourceService;
 exports.createUnauthorizedPlugin = createUnauthorizedPlugin;
 exports.filtersHeader = filtersHeader;
+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,24 @@ 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;
 }
 type ApiRequestInput = string | {
     path: string;
@@ -104,6 +178,8 @@ declare class ApiClient {
     private getLanguage;
     private defaultHeaders;
     private defaultRetry;
+    private retryMethods;
+    private fieldErrors;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -158,41 +234,6 @@ declare class ApiClient {
 }
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
-/**
- * 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;
-}
-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;
-}
-
 interface AuthPluginOptions {
     getToken: () => Promise<string | null> | string | null;
     scheme?: string;
@@ -410,4 +451,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, type FieldError, type FieldErrorExtractor, 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, 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,24 @@ 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;
 }
 type ApiRequestInput = string | {
     path: string;
@@ -104,6 +178,8 @@ declare class ApiClient {
     private getLanguage;
     private defaultHeaders;
     private defaultRetry;
+    private retryMethods;
+    private fieldErrors;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -158,41 +234,6 @@ declare class ApiClient {
 }
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
-/**
- * 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;
-}
-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;
-}
-
 interface AuthPluginOptions {
     getToken: () => Promise<string | null> | string | null;
     scheme?: string;
@@ -410,4 +451,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, type FieldError, type FieldErrorExtractor, 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, 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"] ?? "";
@@ -119,6 +144,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 +156,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 +184,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 +335,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 +352,8 @@ var ApiClient = class {
   getLanguage;
   defaultHeaders;
   defaultRetry;
+  retryMethods;
+  fieldErrors;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -331,6 +366,10 @@ 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.defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
     this.plugins = options.plugins ?? [];
     this.responseHandler = new ResponseHandler(options.responseHandler);
@@ -395,7 +434,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 +458,8 @@ var ApiClient = class {
             response.status,
             response.data,
             void 0,
-            response.headers
+            response.headers,
+            this.fieldErrors
           );
         }
         if (response.status === 204) return null;
@@ -901,4 +941,4 @@ 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 };
+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, nestFieldErrors, normalizeFilters };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sia-ui/api",
-  "version": "0.3.2",
+  "version": "0.5.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.3.2"
+    "@sia-ui/utils": "0.5.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",