@sia-ui/api 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @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

package/README.md

@@ -57,6 +57,55 @@ 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

package/dist/index.cjs

@@ -138,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);
 }
@@ -356,6 +416,7 @@ var ApiClient = class {
   defaultRetry;
   retryMethods;
   fieldErrors;
+  statusMessages;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -372,6 +433,7 @@ var ApiClient = class {
       (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);
@@ -469,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);
@@ -860,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 };
@@ -943,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;
@@ -960,10 +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

@@ -157,6 +157,15 @@ interface ApiClientOptions {
      * 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;
@@ -180,6 +189,7 @@ declare class ApiClient {
     private defaultRetry;
     private retryMethods;
     private fieldErrors;
+    private statusMessages;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -234,6 +244,31 @@ declare class ApiClient {
 }
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
+/**
+ * Les messages par statut, en français.
+ *
+ * `0` couvre l'échec réseau : le serveur injoignable, la connexion coupée.
+ */
+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;
     scheme?: string;
@@ -390,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>;
@@ -429,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;
@@ -451,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 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 };
+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

@@ -157,6 +157,15 @@ interface ApiClientOptions {
      * 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;
@@ -180,6 +189,7 @@ declare class ApiClient {
     private defaultRetry;
     private retryMethods;
     private fieldErrors;
+    private statusMessages;
     private defaultTimeoutMs;
     private plugins;
     private responseHandler;
@@ -234,6 +244,31 @@ declare class ApiClient {
 }
 declare function createApiClient(options: ApiClientOptions): ApiClient;
 
+/**
+ * Les messages par statut, en français.
+ *
+ * `0` couvre l'échec réseau : le serveur injoignable, la connexion coupée.
+ */
+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;
     scheme?: string;
@@ -390,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>;
@@ -429,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;
@@ -451,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 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 };
+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

@@ -136,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);
 }
@@ -354,6 +414,7 @@ var ApiClient = class {
   defaultRetry;
   retryMethods;
   fieldErrors;
+  statusMessages;
   defaultTimeoutMs;
   plugins;
   responseHandler;
@@ -370,6 +431,7 @@ var ApiClient = class {
       (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);
@@ -467,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);
@@ -858,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 };
@@ -941,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, nestFieldErrors, 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.5.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.5.0"
+    "@sia-ui/utils": "0.6.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",