@yuuvis/client-core 3.0.0-beta.21.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuuvis/client-core",
-  "version": "3.0.0-beta.21.1",
+  "version": "3.0.0",
   "author": "OPTIMAL SYSTEMS GmbH <npm@optimal-systems.de>",
   "license": "MIT",
   "peerDependencies": {

package/types/yuuvis-client-core.d.ts

@@ -317,60 +317,132 @@ declare class YuvError implements Error {
 }
 
 /**
- * Represents an entry in the organization set, which can be either a user or a role.
- * Used in search results and organization entity queries.
+ * Represents an entity in the organization set — either a user or a role.
+ *
+ * This is the unified result type returned by {@link IdmService.queryOrganizationEntity}.
+ * It normalizes both user and role search results into a common shape so consumers
+ * (autocomplete fields, assignment dialogs, permission pickers) can treat them uniformly.
+ *
+ * **Mapping from backend:**
+ * ```
+ * User  → { id: user.id,   title: "Lastname, Firstname (username)", type: 'user' }
+ * Role  → { id: role.name, title: role.name,                        type: 'role' }
+ * ```
+ *
+ * **Usage:**
+ * Typically used in autocomplete/search components where a user can assign
+ * a document or task to either a person or a role:
+ * ```ts
+ * idmService.queryOrganizationEntity('admin', ['user', 'role'])
+ *   .subscribe((entries: OrganizationSetEntry[]) => {
+ *     // entries contains both matching users and roles
+ *   });
+ * ```
+ *
+ * @see {@link IdmService.queryOrganizationEntity} for the search method
  */
 interface OrganizationSetEntry {
-    /** The unique identifier of the user or role */
+    /** Unique identifier — user UUID for users, role name for roles */
     id: string;
-    /** The display title/name for the entry */
+    /** Human-readable display title for the entity */
     title: string;
-    /** The type of organization entity */
+    /** Discriminator indicating whether this entry is a user or a role */
     type: 'user' | 'role';
 }
 
 /**
- * Represents the user data structure returned from the IDM API.
- * Contains all essential user information including authentication and authorization details.
+ * Represents the user data structure returned from the IDM backend API (`/idm/users/{id}`).
+ *
+ * This is the raw transport interface — it maps 1:1 to the JSON payload from the identity
+ * management service. The application-level model {@link YuvUser} wraps this interface and
+ * adds computed properties (display name, locale, settings).
+ *
+ * **Typical Flow:**
+ * ```
+ * Backend API ──► IdmUserResponse (raw JSON) ──► YuvUser (app model)
+ * ```
+ *
+ * **Usage:**
+ * - Consumed internally by {@link IdmService.getUserById} to type the HTTP response
+ * - Passed into the {@link YuvUser} constructor for hydration
+ * - Stored in {@link IdmCachedUser} for persistence in the client cache
+ *
+ * @see {@link IdmService.getUserById} for the fetching and caching logic
+ * @see {@link YuvUser} for the application-level user model
  */
 interface IdmUserResponse {
-    /** The unique username for login */
+    /** Unique username used for login / authentication */
     username: string;
-    /** The unique user identifier */
+    /** Unique, immutable user identifier (UUID) */
     id: string;
-    /** The user's email address */
+    /** User's email address */
     email: string;
-    /** The user's first name */
+    /** User's first name */
     firstname: string;
-    /** The user's last name */
+    /** User's last name */
     lastname: string;
-    /** Whether the user account is enabled/active */
+    /** Whether the user account is currently enabled and active */
     enabled: boolean;
-    /** The tenant identifier this user belongs to */
+    /** Tenant identifier this user belongs to (multi-tenancy discriminator) */
     tenant: string;
-    /** Array of granted authorities/permissions for the user */
+    /** Granted authorities / permission roles assigned to the user */
     authorities: string[];
-    /** The formatted display name for the user */
+    /** Pre-formatted display name from the backend (e.g. "Lastname, Firstname (username)") */
     displayName: string;
 }
 
 /**
- * Represents a cached user entry with expiration timestamp.
- * Used internally by IdmService to manage user data caching.
+ * Represents a single cached user entry with an expiration timestamp.
+ *
+ * Used internally by {@link IdmService} to wrap raw {@link IdmUserResponse} data
+ * with a TTL-based expiry. When `Date.now()` exceeds {@link expires}, the entry
+ * is considered stale and the service re-fetches from the backend.
+ *
+ * **Cache Lifecycle:**
+ * ```
+ * [User fetched] ──► IdmCachedUser created ──► stored in IdmUserCache
+ *                    (expires = now + 1h)
+ *
+ * [Next access]
+ *   ├─ Date.now() < expires → return from cache (no HTTP call)
+ *   └─ Date.now() ≥ expires → re-fetch from backend, update cache
+ * ```
+ *
+ * @see {@link IdmUserCache} for the dictionary that holds these entries
+ * @see {@link IdmService.getUserById} for the caching logic
  */
 interface IdmCachedUser {
-    /** Timestamp when the cache expires (Date.now() + TTL) */
+    /** Unix timestamp (ms) when this cache entry expires (`Date.now() + TTL`) */
     expires: number;
-    /** The cached user data from the IDM API */
+    /** Raw user data from the IDM backend API */
     user: IdmUserResponse;
 }
 
 /**
- * Dictionary/map structure for storing cached user data.
- * Keys are user IDs and values are cached user entries with expiration.
+ * Dictionary structure for the in-memory and persisted IDM user cache.
+ *
+ * Maps user IDs (UUIDs) to their {@link IdmCachedUser} entries. The entire map
+ * is persisted as a single blob in {@link ClientCacheService} under the key
+ * `yuv-idm-user-cache`, so all cached users are loaded/saved atomically.
+ *
+ * **Storage Strategy:**
+ * ```
+ * ClientCacheService (IndexedDB / localStorage)
+ *   └─ "yuv-idm-user-cache" → IdmUserCache
+ *        ├─ "user-uuid-1" → { expires: ..., user: { ... } }
+ *        ├─ "user-uuid-2" → { expires: ..., user: { ... } }
+ *        └─ "user-uuid-N" → { expires: ..., user: { ... } }
+ * ```
+ *
+ * **Why a single map instead of per-user cache entries:**
+ * - Atomic load on startup — one read populates the entire in-memory cache
+ * - Avoids N+1 storage reads when resolving multiple users (e.g. audit trails, comment threads)
+ * - Per-entry TTL is still enforced via {@link IdmCachedUser.expires}
+ *
+ * @see {@link IdmCachedUser} for the per-user entry structure
+ * @see {@link IdmService} for the cache management logic
  */
 interface IdmUserCache {
-    /** Map of user IDs to their cached user data */
     [userId: string]: IdmCachedUser;
 }
 
@@ -1481,39 +1553,131 @@ type YuvEventUpdatedData = DmsObject;
 type YuvEventCreatedData = string[];
 
 /**
- * Service for managing Identity Management (IDM) operations.
- * Provides functionality for querying users, roles, and organization entities,
- * with built-in caching mechanisms to optimize performance.
+ * Centralized service for Identity Management (IDM) operations.
+ *
+ * Provides a typed API for querying users, roles, and organization entities
+ * from the IDM backend, with a built-in client-side caching layer that
+ * minimizes redundant HTTP calls.
+ *
+ * **Key Features:**
+ * - User lookup by ID with automatic 1-hour TTL cache
+ * - Unified search across users and roles via a single method
+ * - Role listing with optional name filter
+ * - Cache persisted to IndexedDB/localStorage (survives page refresh)
+ * - In-memory cache hydrated on service creation for instant access
+ *
+ * **Caching Strategy:**
+ * All cached users are stored as a single map ({@link IdmUserCache}) under one
+ * storage key. This enables atomic load on startup — one read populates the
+ * entire in-memory cache — and avoids N+1 reads when resolving multiple users
+ * (e.g. audit trails, comment threads, assignment lists). Per-entry TTL is
+ * enforced via {@link IdmCachedUser.expires}.
+ *
+ * ```
+ * getUserById("abc")
+ *   ├─ Cache hit & valid  → return immediately (no HTTP)
+ *   └─ Cache miss/expired → GET /idm/users/abc
+ *                           ├─ Update in-memory cache
+ *                           ├─ Persist to ClientCacheService
+ *                           └─ Return YuvUser
+ * ```
+ *
+ * **API Endpoints:**
+ * | Method                     | Endpoint             |
+ * |----------------------------|----------------------|
+ * | `queryOrganizationEntity`  | `GET /idm/search`    |
+ * | `getRoles`                 | `GET /idm/roles`     |
+ * | `getUserById`              | `GET /idm/users/:id` |
+ *
+ * **Usage:**
+ * ```ts
+ * const idm = inject(IdmService);
+ *
+ * // Search users and roles
+ * idm.queryOrganizationEntity('admin', ['user', 'role'])
+ *   .subscribe(entries => console.log(entries));
+ *
+ * // Get a user by ID (cached)
+ * idm.getUserById('user-uuid').subscribe(user => console.log(user?.title));
+ *
+ * // List roles
+ * idm.getRoles('ADMIN').subscribe(roles => console.log(roles));
+ * ```
+ *
+ * @see {@link ClientCacheService} for the underlying persistence layer
+ * @see {@link YuvUser} for the application-level user model
  */
 declare class IdmService {
     #private;
-    userCache: IdmUserCache;
     constructor();
     /**
-     * Queries organization entities (users and/or roles) based on search term.
+     * Searches organization entities (users and/or roles) by a free-text term.
+     *
+     * Returns a unified {@link OrganizationSetEntry} array so consumers
+     * (autocomplete fields, assignment dialogs, permission pickers) can
+     * treat users and roles interchangeably.
      *
-     * @param term - The search term to filter entities
-     * @param targetTypes - Array of entity types to search for ('user', 'role')
+     * @param term - Free-text search term to filter entities
+     * @param targetTypes - Entity types to include in results (`'user'`, `'role'`, or both)
      * @param size - Optional maximum number of results to return
-     * @returns Observable array of organization set entries matching the search criteria
+     * @returns Observable of matching organization entities
+     *
+     * @example
+     * ```ts
+     * // Search for users and roles matching "admin"
+     * idmService.queryOrganizationEntity('admin', ['user', 'role'], 10)
+     *   .subscribe(entries => {
+     *     const users = entries.filter(e => e.type === 'user');
+     *     const roles = entries.filter(e => e.type === 'role');
+     *   });
+     * ```
      */
     queryOrganizationEntity(term: string, targetTypes: string[], size?: number): Observable<OrganizationSetEntry[]>;
     /**
      * Retrieves available roles, optionally filtered by a search term.
      *
+     * Returns an empty array on error to ensure consumers can always
+     * safely iterate the result without null-checking.
+     *
      * @param role - Optional search term to filter roles by name
-     * @returns Observable array of role objects containing name and description
+     * @returns Observable of role objects containing name and description
+     *
+     * @example
+     * ```ts
+     * // List all roles
+     * idmService.getRoles().subscribe(roles => console.log(roles));
+     *
+     * // Filter roles by name
+     * idmService.getRoles('ADMIN').subscribe(roles => console.log(roles));
+     * ```
      */
     getRoles(role?: string): Observable<{
         name: string;
         description: string;
     }[]>;
     /**
-     * Retrieves user information by user ID with automatic caching.
-     * Uses a 1-hour TTL cache to minimize backend requests.
+     * Retrieves a user by ID with automatic caching.
+     *
+     * Checks the in-memory cache first. If a valid (non-expired) entry exists,
+     * it is returned immediately without an HTTP call. Otherwise, the user is
+     * fetched from the backend, stored in both the in-memory and persistent
+     * cache, and returned as a {@link YuvUser}.
+     *
+     * Returns `null` if the user is not found or the request fails,
+     * so consumers can safely use the result without try/catch.
      *
-     * @param id - The unique identifier of the user
-     * @returns Observable of YuvUser object or null if user is not found
+     * @param id - Unique user identifier (UUID)
+     * @returns Observable of the user model, or `null` if not found / on error
+     *
+     * @example
+     * ```ts
+     * idmService.getUserById('550e8400-e29b-41d4-a716-446655440000')
+     *   .subscribe(user => {
+     *     if (user) {
+     *       console.log(user.getFullName());
+     *     }
+     *   });
+     * ```
      */
     getUserById(id: string): Observable<YuvUser | null>;
     static ɵfac: i0.ɵɵFactoryDeclaration<IdmService, never>;