@venizia/ardor-admin 0.4.8-0 → 0.4.8-10

package/dist/providers/auth.d.ts

@@ -18,6 +18,7 @@ export declare class SessionClearReasons {
     /** `checkAuth` rejected: no token is stored, or the server answered with no data. */
     static readonly REJECTED = "rejected";
 }
+/** One of the `SessionClearReasons` values. */
 export type TSessionClearReason = TStringConstValue<typeof SessionClearReasons>;
 /**
  * The options hold data (`paths`); behaviour is in the protected hooks around `login` and the page
@@ -28,6 +29,27 @@ export type TSessionClearReason = TStringConstValue<typeof SessionClearReasons>;
  * hook that throws, or does not settle in `sessionHookTimeout`, is logged and does not stop the call
  * that fired it. A hook does not call this provider's methods: they wait behind it. Build one provider
  * per auth service: a second one listening to the same service calls every hook again.
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultAuthProvider, inject, provide } from '@venizia/ardor';
+ *
+ * class AppAuthProvider extends DefaultAuthProvider {
+ *   protected override get afterLoginPath() {
+ *     return '/products';
+ *   }
+ * }
+ *
+ * @configuration()
+ * export class AuthConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_AUTH_PROVIDER })
+ *   authProvider() {
+ *     return this.application.instantiate(AppAuthProvider).value(this.application);
+ *   }
+ * }
+ * ```
  */
 export declare class DefaultAuthProvider<TResource extends string = string> extends BaseProvider<IAuthProvider> {
     protected restDataProvider: IDataProvider<TResource>;
@@ -46,8 +68,8 @@ export declare class DefaultAuthProvider<TResource extends string = string> exte
     private hookQueue;
     /** Where `login` posts: `paths.signIn`, else the IGNIS auth controller's route. */
     protected get signInPath(): string;
-    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`. */
-    protected get afterLoginPath(): string;
+    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`; `false` stays on the page. */
+    protected get afterLoginPath(): string | false;
     /** The route of the login page, which `checkAuth` and a `401` redirect to. */
     protected get loginPagePath(): string;
     /** The route a `403` redirects to; the application mounts it. */
@@ -149,18 +171,60 @@ export declare class DefaultAuthProvider<TResource extends string = string> exte
     private clearSession;
     /** Announces the session in the store, when there is one. */
     private startStoredSession;
-    /** Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling. */
+    /**
+     * Runs when the session is gone, however it ended (sign-out, a `401`, a failed refresh, other
+     * code calling `cleanUp`): removes what the user stored under the store prefix of this
+     * application (`@app/store/`, or `@app/store/<id>/` with an application `id`) in `localStorage` and `sessionStorage`, so the next user does not see it.
+     * Override it to keep preferences, or put them under another prefix.
+     */
+    protected clearStoredData(): void;
+    /**
+     * Posts the sign-in body to `signInPath`, stores the session and resolves `{ ...response,
+     * redirectTo }`, where `redirectTo` is `afterLoginPath` (`false` when it is `false`). Rejects when the request fails, when the
+     * response carries no token or user id, or when `beforeSaveSession` throws; no session is stored
+     * then. Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling.
+     */
     login(params: ILoginParams): Promise<unknown>;
+    /** Clears the session and resolves. */
     logout(_params?: unknown): Promise<void>;
+    /**
+     * Resolves when a token is stored and, if `paths.checkAuth` is set, the server answers with data.
+     * Otherwise it ends the session (reason `rejected`) and rejects with `unauthenticatedRejection`;
+     * it rejects with the request's error when the check request fails.
+     */
     checkAuth(_params?: unknown): Promise<void>;
+    /**
+     * Resolves for every error but 401 and 403. A 401 clears the session (unless
+     * `unauthenticatedRejection` says `logoutUser: false`) and rejects with that rejection; a 403
+     * rejects with `{ redirectTo: unauthorizedPagePath, logoutUser: false }`.
+     */
     checkError(error: unknown): Promise<void>;
+    /** Resolves the stored user; rejects when there is no `userId`. */
     getIdentity(_params?: unknown): Promise<any>;
+    /** Resolves with nothing; the roles come from `getRoles`. */
     getPermissions(_params?: unknown): Promise<void>;
+    /**
+     * Resolves the roles of the stored session. They are read from browser storage, which the user can
+     * edit: use them to show or hide interface only, and let the backend check every permission.
+     */
     getRoles(_params?: unknown): Promise<Set<string>>;
     /**
      * Refreshes the session through the network service's `refresh`, the one place a refresh is made:
      * `true` when it was refreshed, `false` when the service has no refresh to make. The `401`
      * recovery calls the same method, so one burst of 401s and this call share one refresh.
+     *
+     * @example
+     * ```tsx
+     * import { useRefreshToken } from '@venizia/ardor';
+     *
+     * // The data provider options name the refresh endpoint:
+     * // { url: '/api', authRecovery: { refreshTokenPath: '/auth/refresh-token' } }
+     * export const RefreshButton = () => {
+     *   const refreshToken = useRefreshToken();
+     *
+     *   return <button onClick={() => refreshToken()}>Refresh</button>;
+     * };
+     * ```
      */
     refreshToken(): Promise<boolean>;
     value(container: Container): IAuthProvider;

package/dist/providers/auth.js

@@ -13,7 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 var DefaultAuthProvider_1;
 import { getError, inject } from '@venizia/ignis-inversion';
 import { removeDoubleSlashes } from 'ra-core';
-import { BaseProvider, CoreBindings, RequestMethods, } from '@venizia/ardor-kernel';
+import { BaseProvider, BrowserStorage, CoreBindings, LocalStorageKeys, RequestMethods, StorageAreas, } from '@venizia/ardor-kernel';
 /** Why `onSessionCleared` was called. */
 export class SessionClearReasons {
     /** `logout` ran. */
@@ -42,6 +42,27 @@ const readStatus = (error) => {
  * hook that throws, or does not settle in `sessionHookTimeout`, is logged and does not stop the call
  * that fired it. A hook does not call this provider's methods: they wait behind it. Build one provider
  * per auth service: a second one listening to the same service calls every hook again.
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultAuthProvider, inject, provide } from '@venizia/ardor';
+ *
+ * class AppAuthProvider extends DefaultAuthProvider {
+ *   protected override get afterLoginPath() {
+ *     return '/products';
+ *   }
+ * }
+ *
+ * @configuration()
+ * export class AuthConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_AUTH_PROVIDER })
+ *   authProvider() {
+ *     return this.application.instantiate(AppAuthProvider).value(this.application);
+ *   }
+ * }
+ * ```
  */
 let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider extends BaseProvider {
     constructor(restDataProvider, authProviderOptions, authService, permissionProvider) {
@@ -63,7 +84,7 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
     get signInPath() {
         return this.authProviderOptions.paths?.signIn ?? '/auth/sign-in';
     }
-    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`. */
+    /** Where the admin goes once `login` resolves: `paths.afterLogin`, else `/`; `false` stays on the page. */
     get afterLoginPath() {
         return this.authProviderOptions.paths?.afterLogin ?? '/';
     }
@@ -272,9 +293,17 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
     }
     /** Announces or ends the session after the service saved or cleared it. */
     syncSession() {
-        return this.authService.getAuth()?.value
-            ? this.startStoredSession()
-            : this.endSession({ reason: this.clearing ?? SessionClearReasons.EXTERNAL });
+        if (this.authService.getAuth()?.value) {
+            return this.startStoredSession();
+        }
+        try {
+            this.clearStoredData();
+        }
+        catch (error) {
+            // An override that throws must not stop the session from ending.
+            this.logger.error('[clearStoredData] failed, the session ends anyway | error: %o', error);
+        }
+        return this.endSession({ reason: this.clearing ?? SessionClearReasons.EXTERNAL });
     }
     async clearSession(opts) {
         this.clearing = opts.reason;
@@ -294,8 +323,24 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return this.startSession({ token, user: this.authService.getUser() });
     }
+    /**
+     * Runs when the session is gone, however it ended (sign-out, a `401`, a failed refresh, other
+     * code calling `cleanUp`): removes what the user stored under the store prefix of this
+     * application (`@app/store/`, or `@app/store/<id>/` with an application `id`) in `localStorage` and `sessionStorage`, so the next user does not see it.
+     * Override it to keep preferences, or put them under another prefix.
+     */
+    clearStoredData() {
+        const prefix = this.authService.keys.storePrefix;
+        BrowserStorage.removeWhere({ storage: StorageAreas.LOCAL, prefix });
+        BrowserStorage.removeWhere({ storage: StorageAreas.SESSION, prefix });
+    }
     // --- react-admin's auth provider -------------------------------------------------------------
-    /** Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling. */
+    /**
+     * Posts the sign-in body to `signInPath`, stores the session and resolves `{ ...response,
+     * redirectTo }`, where `redirectTo` is `afterLoginPath` (`false` when it is `false`). Rejects when the request fails, when the
+     * response carries no token or user id, or when `beforeSaveSession` throws; no session is stored
+     * then. Typed `Promise<unknown>` so that a subclass override of `login` keeps compiling.
+     */
     async login(params) {
         const response = await this.restDataProvider.send({
             resource: this.signInPath,
@@ -311,14 +356,21 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         await this.startSession(stored?.value === session.token.value
             ? { token: stored, user: this.authService.getUser() }
             : { token: session.token, user: { userId: session.userId, username } });
+        const afterLogin = this.afterLoginPath;
         return {
             ...response,
-            redirectTo: removeDoubleSlashes(`/${this.afterLoginPath}`),
+            redirectTo: afterLogin === false ? false : removeDoubleSlashes(`/${afterLogin}`),
         };
     }
+    /** Clears the session and resolves. */
     async logout(_params) {
         await this.clearSession({ reason: SessionClearReasons.LOGOUT });
     }
+    /**
+     * Resolves when a token is stored and, if `paths.checkAuth` is set, the server answers with data.
+     * Otherwise it ends the session (reason `rejected`) and rejects with `unauthenticatedRejection`;
+     * it rejects with the request's error when the check request fails.
+     */
     async checkAuth(_params) {
         const token = this.authService.getAuth();
         if (!token?.value) {
@@ -344,6 +396,11 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         await this.startStoredSession();
         return Promise.resolve();
     }
+    /**
+     * Resolves for every error but 401 and 403. A 401 clears the session (unless
+     * `unauthenticatedRejection` says `logoutUser: false`) and rejects with that rejection; a 403
+     * rejects with `{ redirectTo: unauthorizedPagePath, logoutUser: false }`.
+     */
     async checkError(error) {
         const status = readStatus(error);
         if (status === 401) {
@@ -361,6 +418,7 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return Promise.resolve();
     }
+    /** Resolves the stored user; rejects when there is no `userId`. */
     getIdentity(_params) {
         const user = this.authService.getUser();
         if (!user?.userId) {
@@ -368,9 +426,14 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         }
         return Promise.resolve(user);
     }
+    /** Resolves with nothing; the roles come from `getRoles`. */
     getPermissions(_params) {
         return Promise.resolve();
     }
+    /**
+     * Resolves the roles of the stored session. They are read from browser storage, which the user can
+     * edit: use them to show or hide interface only, and let the backend check every permission.
+     */
     getRoles(_params) {
         return Promise.resolve(this.authService.getRoles());
     }
@@ -378,6 +441,19 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
      * Refreshes the session through the network service's `refresh`, the one place a refresh is made:
      * `true` when it was refreshed, `false` when the service has no refresh to make. The `401`
      * recovery calls the same method, so one burst of 401s and this call share one refresh.
+     *
+     * @example
+     * ```tsx
+     * import { useRefreshToken } from '@venizia/ardor';
+     *
+     * // The data provider options name the refresh endpoint:
+     * // { url: '/api', authRecovery: { refreshTokenPath: '/auth/refresh-token' } }
+     * export const RefreshButton = () => {
+     *   const refreshToken = useRefreshToken();
+     *
+     *   return <button onClick={() => refreshToken()}>Refresh</button>;
+     * };
+     * ```
      */
     async refreshToken() {
         const isRefreshed = await this.restDataProvider.getNetworkService().refresh();
@@ -387,6 +463,18 @@ let DefaultAuthProvider = DefaultAuthProvider_1 = class DefaultAuthProvider exte
         return isRefreshed;
     }
     value(container) {
+        // A subclass of DefaultAuthService with its own constructor must forward the application info to
+        // super(info): without it the service keeps the unscoped session, silently shared with every other
+        // application of the origin. Refuse that here, where the application info is at hand.
+        const id = container.get({
+            key: CoreBindings.APPLICATION_INFO,
+            isOptional: true,
+        })?.id;
+        if (id !== undefined && this.authService.keys.token !== LocalStorageKeys.scoped({ id }).token) {
+            throw getError({
+                message: `[DefaultAuthProvider] The auth service does not use the application id '${id}': a subclass of DefaultAuthService with its own constructor passes the application info to super(info)`,
+            });
+        }
         // A subclass with its own constructor rarely forwards the optional 4th argument to `super`.
         const permissionProvider = this.permissionProvider ??
             container.get({

package/dist/providers/count-rest-data.d.ts

@@ -3,7 +3,15 @@ import { type TRequestType } from '@venizia/ardor-kernel';
 import type { TExtraRequest } from '@venizia/ignis-kernel/repository';
 import type { IListFilter } from './list-filter.js';
 import { DefaultRestDataProvider } from './rest-data.js';
+/**
+ * A `DefaultRestDataProvider` whose list reads take their `total` from the count route
+ * (`GET /{resource}/count` with the same `where`) instead of the `Content-Range` header.
+ */
 export declare class CountRestDataProvider<TResource extends string = string> extends DefaultRestDataProvider<TResource> {
+    /**
+     * Sends the list GET and the count GET together; `total` is the count's `count`, or `0` when the
+     * count answers none. Rejects when either request rejects.
+     */
     protected requestList<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         type: TRequestType;

package/dist/providers/count-rest-data.js

@@ -1,6 +1,14 @@
 import { RequestMethods, RequestTypes } from '@venizia/ardor-kernel';
 import { DefaultRestDataProvider } from './rest-data.js';
+/**
+ * A `DefaultRestDataProvider` whose list reads take their `total` from the count route
+ * (`GET /{resource}/count` with the same `where`) instead of the `Content-Range` header.
+ */
 export class CountRestDataProvider extends DefaultRestDataProvider {
+    /**
+     * Sends the list GET and the count GET together; `total` is the count's `count`, or `0` when the
+     * count answers none. Rejects when either request rejects.
+     */
     requestList(opts) {
         const { resource, queryKey, filter } = opts;
         // The base class reads the rows and keeps the route's list extras as `meta.extra`.

package/dist/providers/i18n.d.ts

@@ -7,6 +7,26 @@ import { LocaleSources } from './i18n-sources.js';
 /**
  * The options hold data (`i18nSources`, `languages`); the hooks are `resolveInitialLocale` and
  * `composeMessages`, each taking one `opts` object.
+ *
+ * @example
+ * ```ts
+ * import { configuration, CoreBindings, englishMessages, provide, vietnameseMessages } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class I18nConfiguration {
+ *   @provide({ key: CoreBindings.I18N_PROVIDER_OPTIONS })
+ *   options() {
+ *     return {
+ *       languages: [{ locale: 'en', name: 'English' }, { locale: 'vi', name: 'Tieng Viet' }],
+ *       i18nSources: {
+ *         en: englishMessages,
+ *         // A loader runs the first time the locale is used, such as () => import('./vi').
+ *         vi: async () => vietnameseMessages,
+ *       },
+ *     };
+ *   }
+ * }
+ * ```
  */
 export declare class DefaultI18nProvider extends BaseProvider<I18nProvider> {
     protected i18nProviderOptions: II18nProviderOptions;
@@ -15,8 +35,8 @@ export declare class DefaultI18nProvider extends BaseProvider<I18nProvider> {
     constructor(i18nProviderOptions: II18nProviderOptions, features?: Array<TFeature>);
     /**
      * The locale the admin starts in: the browser's language when it is one of `locales`, else `en`.
-     * Read when the provider is built, not when the module is imported, and not at all outside a
-     * browser.
+     * Read when the provider is built, not when the module is imported. Without a `navigator` the
+     * language is `en-US`.
      */
     protected resolveInitialLocale(opts: {
         locales: Array<string>;

package/dist/providers/i18n.js

@@ -12,15 +12,35 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 var DefaultI18nProvider_1;
 import { inject } from '@venizia/ignis-inversion';
-import merge from 'lodash/merge.js';
 import polyglotI18nProvider from 'ra-i18n-polyglot';
 import { BaseProvider, CoreBindings } from '@venizia/ardor-kernel';
 import { englishMessages } from '../common/locales/index.js';
+import { deepMerge } from '../common/merge.js';
 import { FeatureMessages } from '../features/messages.js';
 import { LazyLocales, LocaleSources } from './i18n-sources.js';
 /**
  * The options hold data (`i18nSources`, `languages`); the hooks are `resolveInitialLocale` and
  * `composeMessages`, each taking one `opts` object.
+ *
+ * @example
+ * ```ts
+ * import { configuration, CoreBindings, englishMessages, provide, vietnameseMessages } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class I18nConfiguration {
+ *   @provide({ key: CoreBindings.I18N_PROVIDER_OPTIONS })
+ *   options() {
+ *     return {
+ *       languages: [{ locale: 'en', name: 'English' }, { locale: 'vi', name: 'Tieng Viet' }],
+ *       i18nSources: {
+ *         en: englishMessages,
+ *         // A loader runs the first time the locale is used, such as () => import('./vi').
+ *         vi: async () => vietnameseMessages,
+ *       },
+ *     };
+ *   }
+ * }
+ * ```
  */
 let DefaultI18nProvider = DefaultI18nProvider_1 = class DefaultI18nProvider extends BaseProvider {
     constructor(i18nProviderOptions, features = []) {
@@ -34,8 +54,8 @@ let DefaultI18nProvider = DefaultI18nProvider_1 = class DefaultI18nProvider exte
     }
     /**
      * The locale the admin starts in: the browser's language when it is one of `locales`, else `en`.
-     * Read when the provider is built, not when the module is imported, and not at all outside a
-     * browser.
+     * Read when the provider is built, not when the module is imported. Without a `navigator` the
+     * language is `en-US`.
      */
     resolveInitialLocale(opts) {
         const browserLanguage = typeof navigator === 'undefined' ? undefined : navigator.language;
@@ -49,8 +69,11 @@ let DefaultI18nProvider = DefaultI18nProvider_1 = class DefaultI18nProvider exte
      */
     composeMessages(opts) {
         const source = this.localeSources.readNow({ locale: opts.locale });
-        // lodash `merge` loses the message type; every source is a (partial) set of messages.
-        return merge({}, opts.messages, source ?? englishMessages);
+        // A merge of (partial) message sets is a set of messages, which a merge that takes any object
+        // cannot say in its type: the assertion is here, where the sources are known, not inside it.
+        return deepMerge({
+            sources: [opts.messages, source ?? englishMessages],
+        });
     }
     value(_container) {
         const { languages = [{ locale: 'en', name: 'English' }] } = this.i18nProviderOptions;

package/dist/providers/list-filter.d.ts

@@ -4,16 +4,20 @@ import { type ICustomParams } from '@venizia/ardor-kernel';
 /** The IGNIS filter a list request sends. Any other key of the list params is a filter key too. */
 export interface IListFilter {
     where: Record<string, unknown>;
+    /** Each entry is `'<field> <ASC|DESC>'`. */
     order?: Array<string>;
     limit?: number;
+    /** IGNIS's offset; `ListFilterBuilder.build` sets this one. */
     skip?: number;
-    offset?: number;
     include?: unknown;
     fields?: unknown;
+    /** Not part of the filter sent: `ListFilterBuilder.build` moves it into the query string. */
     params?: Record<string, unknown>;
+    /** Lifts `limit` and `skip`: the list is not paginated. */
     noLimit?: boolean;
     [key: string]: unknown;
 }
+/** Builds the filter, query and extras of a list request from react-admin's list params. */
 export declare class ListFilterBuilder {
     /** `filter.params` as the keys of the query string, as a copy. */
     static extractQueryParams(opts: {

package/dist/providers/list-filter.js

@@ -1,5 +1,5 @@
-import omit from 'lodash/omit.js';
 import { ValueUtility } from '@venizia/ardor-kernel';
+/** Builds the filter, query and extras of a list request from react-admin's list params. */
 export class ListFilterBuilder {
     /** `filter.params` as the keys of the query string, as a copy. */
     static extractQueryParams(opts) {
@@ -18,13 +18,12 @@ export class ListFilterBuilder {
             filter = { ...filterInput, where: { ...filterInput.where } };
         }
         else {
-            filter['where'] = {
-                ...omit(filterInput, ['include', 'params', 'noLimit', 'fields']),
-            };
-            filter['include'] = filterInput?.include;
-            filter['fields'] = filterInput?.fields;
-            filter['params'] = filterInput?.params;
-            filter['noLimit'] = filterInput?.noLimit;
+            const { include, fields, params, noLimit, ...where } = filterInput ?? {};
+            filter['where'] = where;
+            filter['include'] = include;
+            filter['fields'] = fields;
+            filter['params'] = params;
+            filter['noLimit'] = noLimit;
         }
         if (sort?.field) {
             filter['order'] = [`${sort.field} ${sort.order}`];
@@ -38,7 +37,7 @@ export class ListFilterBuilder {
         }
         else {
             const { page = 1, perPage = 0 } = pagination ?? {};
-            // No `perPage` is no limit. `skip` is IGNIS's offset (`offset` is its alias): one is enough.
+            // No `perPage` is no limit. `skip` is IGNIS's offset.
             if (perPage > 0) {
                 filter['limit'] = perPage;
                 filter['skip'] = (Math.max(page, 1) - 1) * perPage;

package/dist/providers/rest-data.d.ts

@@ -1,13 +1,42 @@
 import { type Container } from '@venizia/ignis-inversion';
 import type { CreateParams, CreateResult, DeleteManyParams, DeleteManyResult, DeleteParams, DeleteResult, GetListParams, GetListResult, GetManyParams, GetManyReferenceParams, GetManyReferenceResult, GetManyResult, GetOneParams, GetOneResult, Identifier, QueryFunctionContext, RaRecord, UpdateManyParams, UpdateManyResult, UpdateParams, UpdateResult } from 'ra-core';
-import { BaseProvider, DefaultNetworkRequestService, type IApplicationInfo, type INetworkResponse, type ICustomParams, type IRestDataProviderOptions, type ISendParams, type ISendResponse, type TRequestType } from '@venizia/ardor-kernel';
+import { BaseProvider, type DefaultAuthService, DefaultNetworkRequestService, type IApplicationInfo, type INetworkResponse, type ICustomParams, type IRestDataProviderOptions, type ISendParams, type TRequestType } from '@venizia/ardor-kernel';
 import type { TExtraRequest } from '@venizia/ignis-kernel/repository';
 import type { IDataProvider, IRestRequestOptions } from '../common/index.js';
 import { type IListFilter } from './list-filter.js';
+/**
+ * The react-admin data provider over an IGNIS REST API. Each method takes one `opts` object
+ * (`{ resource, params }`) and resolves the result react-admin expects; it rejects with the error
+ * the network service throws (a non-2xx response, an empty base URL, an auth failure that cannot be
+ * recovered). A subclass overrides the protected hooks (`createNetworkService`, `buildListFilter`,
+ * `requestList`).
+ *
+ * @example
+ * ```ts
+ * import { type BaseArdorApplication, configuration, CoreBindings, DefaultRestDataProvider, inject, provide } from '@venizia/ardor';
+ *
+ * @configuration()
+ * export class DataConfiguration {
+ *   constructor(@inject({ key: CoreBindings.APPLICATION_INSTANCE }) private readonly application: BaseArdorApplication) {}
+ *
+ *   @provide({ key: CoreBindings.REST_DATA_PROVIDER_OPTIONS })
+ *   options() {
+ *     return { url: '/api', noAuthPaths: ['/auth/sign-in'] };
+ *   }
+ *
+ *   @provide({ key: CoreBindings.DEFAULT_REST_DATA_PROVIDER })
+ *   dataProvider() {
+ *     return this.application.instantiate(DefaultRestDataProvider).value(this.application);
+ *   }
+ * }
+ * ```
+ */
 export declare class DefaultRestDataProvider<TResource extends string = string> extends BaseProvider<IDataProvider<TResource>> {
     protected restDataProviderOptions: IRestDataProviderOptions;
     protected applicationInfo: IApplicationInfo;
     private cachedNetworkService?;
+    /** The auth service of the container, set when `value` builds the provider; pass it to the network service you return from `createNetworkService`. */
+    protected authService?: DefaultAuthService;
     constructor(restDataProviderOptions: IRestDataProviderOptions, applicationInfo: IApplicationInfo);
     /**
      * Builds the network service this provider sends through. Override it to return a subclass of
@@ -16,6 +45,7 @@ export declare class DefaultRestDataProvider<TResource extends string = string>
      */
     protected createNetworkService(): DefaultNetworkRequestService;
     protected get networkService(): DefaultNetworkRequestService;
+    /** The network service every request of this provider goes through; built on first use. */
     getNetworkService(): DefaultNetworkRequestService;
     /**
      * The ids a bulk write touched, read from the affected rows the server answers (not the ids asked
@@ -69,52 +99,85 @@ export declare class DefaultRestDataProvider<TResource extends string = string>
         filename?: string;
         contentDisposition?: string;
     }>;
+    /**
+     * `GET /{resource}` with the filter built from the list params in the query. Resolves the rows and
+     * `total` (the `Content-Range` total, else the page's row count), plus `meta.extra` when a route
+     * answered extras.
+     */
     getList<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetListParams & QueryFunctionContext & ICustomParams;
     }): Promise<GetListResult<RecordType>>;
+    /**
+     * `GET /{resource}/{id}`, with `params.meta.filter` as the query filter. Resolves `{ data }`.
+     */
     getOne<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetOneParams<RecordType> & QueryFunctionContext & ICustomParams;
     }): Promise<GetOneResult<RecordType>>;
+    /**
+     * `GET /{resource}` with the ids in `filter.where.id.inq`, merged into `params.meta.filter`.
+     * Resolves `{ data }`.
+     */
     getMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetManyParams<RecordType> & QueryFunctionContext & ICustomParams;
     }): Promise<GetManyResult<RecordType>>;
+    /**
+     * As `getList`, with `filter.where[target] = id`. Resolves the rows and `total`.
+     */
     getManyReference<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: GetManyReferenceParams & QueryFunctionContext & ICustomParams;
     }): Promise<GetManyReferenceResult<RecordType>>;
+    /** `PATCH /{resource}/{id}` with `params.data` as the body. Resolves `{ data }`. */
     update<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: UpdateParams;
     }): Promise<UpdateResult<RecordType>>;
+    /**
+     * `PATCH /{resource}` with `{ ...params.data, where: { id: { inq: ids } } }` as the body. Resolves
+     * `{ data }`, the ids of the rows the server answered (`undefined` when the answer is not a row
+     * array). Rejects when `ids` is empty or `params.data` has a `where` field, before any request.
+     */
     updateMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: UpdateManyParams;
     }): Promise<UpdateManyResult<RecordType>>;
+    /** `POST /{resource}` with `params.data` as the body. Resolves `{ data }`, the created record. */
     create<RecordType extends Omit<RaRecord, 'id'> = Omit<RaRecord, 'id'>, ResultRecordType extends RaRecord = RecordType & {
         id: Identifier;
     }>(opts: {
         resource: TResource;
         params: CreateParams;
     }): Promise<CreateResult<ResultRecordType>>;
+    /** `DELETE /{resource}/{id}`. Resolves `{ data }`, the record the server answered. */
     delete<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: DeleteParams<RecordType>;
     }): Promise<DeleteResult<RecordType>>;
+    /**
+     * `DELETE /{resource}` with `{ where: { id: { inq: ids } } }` as the body. Resolves `{ data }`, the
+     * ids of the rows the server answered (`undefined` when the answer is not a row array). Rejects
+     * when `ids` is empty, before any request.
+     */
     deleteMany<RecordType extends RaRecord = RaRecord>(opts: {
         resource: TResource;
         params: DeleteManyParams<RecordType>;
     }): Promise<DeleteManyResult<RecordType>>;
+    /**
+     * Sends `params.method` to `/{resource}` with the provider's headers and auth; `requestType`
+     * defaults to `RequestTypes.SEND`. Resolves the response read by that type. Rejects when
+     * `params.method` is missing, before any request.
+     */
     send<TResult = unknown>(opts: {
         resource: TResource;
         params: ISendParams;
-    }): Promise<ISendResponse<TResult>>;
+    }): Promise<INetworkResponse<TResult>>;
     /**
      * react-admin's data provider contract takes positional arguments, `(resource, params)`: the one
      * place this class does not take an `opts` object. Each method hands them to the `opts` method.
      */
-    value(_container: Container): IDataProvider<TResource>;
+    value(container: Container): IDataProvider<TResource>;
 }
 //# sourceMappingURL=rest-data.d.ts.map