@sia-ui/api 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,413 @@
+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>;
+interface ApiRequestConfig {
+    headers?: Record<string, string> | undefined;
+    queryParams?: QueryParams | undefined;
+    body?: unknown;
+    signal?: AbortSignal | null | undefined;
+    timeoutMs?: number | undefined;
+    retry?: number | undefined;
+    onUploadProgress?: ((percent: number) => void) | undefined;
+}
+interface ApiRequestContext extends ApiRequestConfig {
+    url: string;
+    method: ApiMethod;
+    headers: Record<string, string>;
+}
+interface ApiTransportRequest {
+    url: string;
+    method: ApiMethod;
+    headers: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal | null | undefined;
+    timeoutMs?: number | undefined;
+    onUploadProgress?: ((percent: number) => void) | undefined;
+}
+interface ApiTransportResponse<T = unknown> {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    data: T;
+}
+interface ApiTransport {
+    request<T>(request: ApiTransportRequest): Promise<ApiTransportResponse<T>>;
+}
+/** Les points d'accroche d'un greffon — `name` n'en est pas un. */
+type ApiPluginHook = "onRequest" | "onResponse" | "onError";
+interface ApiPlugin {
+    /**
+     * Un nom, pour les traces et le débogage.
+     *
+     * Quand six greffons sont montés, savoir lequel a court-circuité une requête
+     * vaut mieux que de compter les positions dans un tableau.
+     */
+    name?: string | undefined;
+    onRequest?: (ctx: ApiRequestContext) => Promise<unknown> | unknown;
+    onResponse?: (response: ApiTransportResponse, ctx: ApiRequestContext) => Promise<unknown> | unknown;
+    onError?: (error: unknown, ctx: ApiRequestContext) => Promise<unknown> | unknown;
+}
+interface PageMeta {
+    page: number;
+    limit: number;
+    total?: number | undefined;
+    totalPages?: number | undefined;
+}
+interface CursorMeta {
+    nextCursor?: string | null | undefined;
+    prevCursor?: string | null | undefined;
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    meta: PageMeta | CursorMeta;
+}
+interface ResponseHandlerConfig {
+    extractData?: (raw: unknown) => unknown;
+    extractPaginated?: (raw: unknown) => PaginatedResponse<unknown> | null;
+    extractCursor?: (raw: unknown) => PaginatedResponse<unknown> | null;
+}
+interface RefreshTokenConfig {
+    enabled: boolean;
+    refreshEndpoint: string;
+    getRefreshToken?: (() => Promise<string | null> | string | null | undefined) | undefined;
+    saveTokens: (accessToken: string, refreshToken?: string | undefined) => Promise<void> | void;
+    onRefreshFailure?: ((error: unknown) => void) | undefined;
+}
+interface ApiClientOptions {
+    baseURL: string;
+    transport?: ApiTransport | undefined;
+    getToken?: (() => string | null | Promise<string | null>) | undefined;
+    getLanguage?: (() => string | null | Promise<string | null>) | undefined;
+    defaultHeaders?: Record<string, string> | undefined;
+    defaultRetry?: number | undefined;
+    defaultTimeoutMs?: number | undefined;
+    plugins?: ApiPlugin[] | undefined;
+    responseHandler?: ResponseHandlerConfig | undefined;
+}
+type ApiRequestInput = string | {
+    path: string;
+    config?: ApiRequestConfig | undefined;
+};
+interface RtkBaseQueryResult<T = unknown> {
+    data?: T;
+    error?: {
+        status: number | "FETCH_ERROR";
+        data: unknown;
+        message: string;
+    };
+}
+
+declare class ApiClient {
+    private baseURL;
+    private transport;
+    private getToken;
+    private getLanguage;
+    private defaultHeaders;
+    private defaultRetry;
+    private defaultTimeoutMs;
+    private plugins;
+    private responseHandler;
+    constructor(options: ApiClientOptions);
+    addPlugin(plugin: ApiPlugin): void;
+    /**
+     * Monte un greffon et renvoie le client.
+     *
+     * Le chaînage rend l'assemblage lisible d'un coup d'œil — c'est là qu'on
+     * relit l'ordre des greffons, et l'ordre compte : le premier qui renvoie une
+     * valeur court-circuite les suivants.
+     */
+    use(plugin: ApiPlugin): this;
+    buildURL(path: string, params?: QueryParams): string;
+    private runPlugins;
+    private buildHeaders;
+    private shouldRetry;
+    private requestRaw;
+    request<T>(method: ApiMethod, path: string, config?: ApiRequestConfig): Promise<T>;
+    replay<T>(ctx: ApiRequestContext): Promise<T>;
+    get<T>(path: string, config?: ApiRequestConfig): Promise<T>;
+    post<T>(path: string, config?: ApiRequestConfig): Promise<T>;
+    put<T>(path: string, config?: ApiRequestConfig): Promise<T>;
+    patch<T>(path: string, config?: ApiRequestConfig): Promise<T>;
+    delete<T>(path: string, config?: ApiRequestConfig): Promise<T>;
+    /** Sans corps de réponse : sert à tester l'existence ou lire des en-têtes. */
+    head(path: string, config?: ApiRequestConfig): Promise<null>;
+    /**
+     * Une liste, qu'elle soit paginée ou non.
+     *
+     * Beaucoup d'points d'entrée renvoient un tableau nu quand il n'y a pas de
+     * pagination. Les appelants ne devraient pas avoir à deviner lequel : la
+     * méthode normalise les deux en `{ items, meta }`.
+     */
+    getList<T>(path: string, config?: ApiRequestConfig): Promise<PaginatedResponse<T>>;
+    getPaginated<T>(path: string, options?: {
+        page?: number;
+        limit?: number;
+        query?: QueryParams | undefined;
+        config?: ApiRequestConfig | undefined;
+    }): Promise<PaginatedResponse<T>>;
+    getCursorPage<T>(path: string, options?: {
+        cursor?: string | null;
+        limit?: number;
+        query?: QueryParams | undefined;
+        cursorParamName?: string | undefined;
+        config?: ApiRequestConfig | undefined;
+    }): Promise<PaginatedResponse<T>>;
+    query<T>(loader: () => Promise<T>): () => Promise<T>;
+    swrFetcher<T>(config?: ApiRequestConfig): (path: string) => Promise<T>;
+    rtkBaseQuery(): <T>(input: ApiRequestInput) => Promise<RtkBaseQueryResult<T>>;
+}
+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;
+}
+interface UnauthorizedPluginOptions {
+    shouldIgnore?: (ctx: ApiRequestContext) => boolean;
+    onUnauthorized: (error: HttpError, ctx: ApiRequestContext) => void;
+}
+declare function createAuthPlugin(options: AuthPluginOptions): ApiPlugin;
+declare function createUnauthorizedPlugin(options: UnauthorizedPluginOptions): ApiPlugin;
+declare function createRefreshTokenPlugin(config: RefreshTokenConfig, replayRequest: (ctx: ApiRequestContext) => Promise<unknown>): ApiPlugin;
+interface LoggerPluginOptions {
+    /** Où écrire. Par défaut la console; un collecteur de métriques fait l'affaire. */
+    log?: (message: string, detail?: unknown) => void;
+}
+/**
+ * Trace chaque requête avec sa durée.
+ *
+ * La durée est mesurée sur le contexte lui-même : c'est le seul objet qui
+ * traverse `onRequest` et `onResponse` pour une même requête.
+ */
+declare function createLoggerPlugin(options?: LoggerPluginOptions): ApiPlugin;
+interface IdempotencyPluginOptions {
+    header?: string;
+    newKey?: () => string;
+}
+/**
+ * Pose une clé d'idempotence sur les écritures.
+ *
+ * Sans elle, un `POST` rejoué après une coupure réseau crée deux ressources.
+ * Avec elle, le serveur reconnaît la seconde tentative — à condition qu'il la
+ * gère, ce que ce greffon ne peut pas vérifier.
+ */
+declare function createIdempotencyPlugin(options?: IdempotencyPluginOptions): ApiPlugin;
+/**
+ * Coupe toute écriture.
+ *
+ * Utile pour une démonstration, un compte en lecture seule, ou un
+ * environnement gelé. L'erreur est levée avant que la requête ne parte : rien
+ * n'atteint le serveur.
+ */
+declare function createReadOnlyPlugin(message?: string): ApiPlugin;
+interface HeaderSignalPluginOptions {
+    /** L'en-tête qui déclenche l'action. */
+    header: string;
+    /** Ce qu'il faut faire quand le serveur le renvoie. */
+    onSignal: (value: string, ctx: ApiRequestContext) => void | Promise<void>;
+    /** Valeur attendue; par défaut, `"true"`. */
+    expect?: (value: string) => boolean;
+}
+/**
+ * Réagit à un en-tête de réponse.
+ *
+ * Généralisation de ce qu'un projet faisait pour un cas précis : le serveur
+ * renvoie `x-permissions-refreshed: true`, le client recharge l'utilisateur.
+ * Le motif — « le serveur signale, le client réagit » — vaut pour bien
+ * d'autres cas, donc le greffon ne fixe ni l'en-tête ni la réaction.
+ *
+ * Les appels concurrents sont dédoublonnés : dix requêtes qui portent le même
+ * signal ne déclenchent qu'une réaction.
+ */
+declare function createHeaderSignalPlugin(options: HeaderSignalPluginOptions): ApiPlugin;
+
+/**
+ * Où vit une session entre deux lancements.
+ *
+ * Une interface plutôt qu'une implémentation, parce que la bonne réponse
+ * dépend de l'hôte : le navigateur a `localStorage`, une application native a
+ * son trousseau, un test ne veut ni l'un ni l'autre. Ce module n'importe donc
+ * aucune API de plateforme — on lui passe le stockage.
+ */
+interface TokenStorage {
+    getAccessToken(): string | null | Promise<string | null>;
+    getRefreshToken(): string | null | Promise<string | null>;
+    saveTokens(accessToken: string, refreshToken?: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+declare const ACCESS_TOKEN_KEY = "sia.accessToken";
+declare const REFRESH_TOKEN_KEY = "sia.refreshToken";
+/** Rien ne survit au rechargement — le bon défaut pour un test. */
+declare function createMemoryTokenStorage(): TokenStorage;
+interface BrowserTokenStorageOptions {
+    accessKey?: string;
+    refreshKey?: string;
+}
+/**
+ * Un stockage du navigateur — `localStorage` ou `sessionStorage`.
+ *
+ * Lisible par tout script de la page : c'est le compromis qu'accepte toute
+ * application web devant survivre à un rechargement. C'est aussi pourquoi le
+ * jeton d'accès doit être court, et le jeton de renouvellement à usage unique
+ * et révocable.
+ *
+ * Chaque accès est protégé : en navigation privée, ou avec les données de site
+ * bloquées, une simple lecture lève. Une session absente est un cas normal;
+ * une page qui tombe pour cette raison ne l'est pas.
+ */
+declare function createBrowserTokenStorage(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, options?: BrowserTokenStorageOptions): TokenStorage;
+
+/**
+ * Des filtres composés, transportés hors de l'URL.
+ *
+ * Une recherche à quatre critères sérialisée en paramètres produit une URL
+ * illisible, et dépasse vite la limite de longueur des serveurs. Un en-tête
+ * porte la même chose sans ces deux problèmes — au prix de ne pas apparaître
+ * dans un lien partageable, ce qui est acceptable pour un filtre de tableau.
+ */
+type FilterOperator = "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "nin" | "like" | "between" | "isNull";
+type FilterValue = string | number | boolean | null | Array<string | number | boolean>;
+/** `{ statut: "payé" }` ou `{ montant: { gte: 1000 } }`. */
+type FilterCondition = Record<string, FilterValue | Partial<Record<FilterOperator, FilterValue>>>;
+interface FilterGroup {
+    $and?: ApiFilters[];
+    $or?: ApiFilters[];
+}
+type ApiFilters = FilterCondition | FilterGroup;
+/**
+ * Ramène un filtre à sa forme composée.
+ *
+ * Un objet plat est le cas courant — « tous ces critères » — et il est plus
+ * agréable à écrire que `{ $and: [{ … }] }`. On accepte les deux et on
+ * normalise, pour que le serveur n'ait qu'une forme à lire.
+ */
+declare function normalizeFilters(filters: ApiFilters | undefined): FilterGroup | undefined;
+declare const FILTERS_HEADER = "X-Filters";
+/**
+ * L'en-tête à joindre à la requête, ou rien s'il n'y a pas de filtre.
+ *
+ * ```ts
+ * const headers = filtersHeader({ statut: "payé", montant: { gte: 1000 } });
+ * await api.get("/factures", { headers });
+ * ```
+ */
+declare function filtersHeader(filters: ApiFilters | undefined, header?: string): Record<string, string>;
+
+/**
+ * La chaîne de requête d'un appel API.
+ *
+ * L'implémentation est celle de `@sia-ui/utils` — une seule pour tout le
+ * dépôt. Ce qui reste ici est le typage : `QueryParams` décrit ce qu'un
+ * appel accepte, et c'est une information du module API, pas des utils.
+ */
+declare function buildQueryString(params?: QueryParams): string;
+
+declare class ResponseHandler {
+    private config;
+    constructor(config?: ResponseHandlerConfig);
+    extractData<T>(raw: unknown): T;
+    extractPaginated<T>(raw: unknown): PaginatedResponse<T> | null;
+    extractCursor<T>(raw: unknown): PaginatedResponse<T> | null;
+}
+
+declare class BaseService<TEntity, TCreateDTO = Partial<TEntity>, TUpdateDTO = Partial<TEntity>, TListParams extends QueryParams = QueryParams> {
+    protected client: ApiClient;
+    protected resource: string;
+    constructor(client: ApiClient, resource: string);
+    protected normalizeQueryParams(params?: TListParams): TListParams | undefined;
+    list(params?: TListParams, config?: ApiRequestConfig): Promise<TEntity[]>;
+    getById(id: string, config?: ApiRequestConfig): Promise<TEntity>;
+    create(payload: TCreateDTO, config?: ApiRequestConfig): Promise<TEntity>;
+    update(id: string, payload: TUpdateDTO, config?: ApiRequestConfig): Promise<TEntity>;
+    patch(id: string, payload: Partial<TUpdateDTO>, config?: ApiRequestConfig): Promise<TEntity>;
+    remove(id: string, config?: ApiRequestConfig): Promise<void>;
+    /**
+     * Suppression en lot.
+     *
+     * Un `POST` plutôt que N `DELETE` : le serveur décide en une transaction,
+     * et l'interface n'a pas à gérer une suppression à moitié réussie.
+     */
+    removeMany(ids: string[], options?: {
+        hardDelete?: boolean;
+    }, config?: ApiRequestConfig): Promise<void>;
+    /**
+     * Une liste filtrée, la forme composée passant par un en-tête.
+     *
+     * Voir `filters.ts` : une recherche à plusieurs critères tient mal dans une
+     * URL.
+     */
+    search(filters: ApiFilters, params?: TListParams, config?: ApiRequestConfig): Promise<PaginatedResponse<TEntity>>;
+    paginated(options?: {
+        page?: number;
+        limit?: number;
+        query?: TListParams | undefined;
+        config?: ApiRequestConfig | undefined;
+    }): Promise<PaginatedResponse<TEntity>>;
+    cursorPage(options?: {
+        cursor?: string | null;
+        limit?: number;
+        query?: TListParams | undefined;
+        cursorParamName?: string | undefined;
+        config?: ApiRequestConfig | undefined;
+    }): Promise<PaginatedResponse<TEntity>>;
+}
+declare function createResourceService<TEntity>(client: ApiClient, resourcePath: string): BaseService<TEntity, Partial<TEntity>, Partial<TEntity>, QueryParams>;
+
+interface AxiosLikeInstance {
+    request<T = unknown>(config: {
+        url: string;
+        method: string;
+        headers?: Record<string, string>;
+        data?: unknown;
+        signal?: AbortSignal | undefined;
+        timeout?: number | undefined;
+        onUploadProgress?: ((event: {
+            loaded: number;
+            total?: number | undefined;
+        }) => void) | undefined;
+    }): Promise<{
+        status: number;
+        statusText: string;
+        headers?: unknown;
+        data: T;
+    }>;
+}
+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 };