@arsedizioni/ars-utils 21.2.203 → 21.2.205

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arsedizioni/ars-utils",
-  "version": "21.2.203",
+  "version": "21.2.205",
   "author": {
     "email": "software@arsedizioni.it",
     "name": "Fabio Buscaroli, Alberto Doria"

package/types/arsedizioni-ars-utils-clipper.common.d.ts

@@ -1,12 +1,12 @@
 import * as _angular_core from '@angular/core';
-import { Signal, OnDestroy } from '@angular/core';
+import { Signal } from '@angular/core';
 import { NameValueItem, Folder, QueryModel, LoginResult, ApiResult, UpdateResultModel, FolderTree, QueryResultModel } from '@arsedizioni/ars-utils/core';
 import { SendToDialogResult } from '@arsedizioni/ars-utils/ui.application';
 import { LoginOAuthType } from '@arsedizioni/ars-utils/ui.oauth';
 import * as _angular_common_http from '@angular/common/http';
 import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent } from '@angular/common/http';
 import * as rxjs from 'rxjs';
-import { Observable, Subscription } from 'rxjs';
+import { Observable } from 'rxjs';
 import { ResetPasswordDialogResult, RecoverPasswordDialogResult } from '@arsedizioni/ars-utils/ui';
 
 declare const ClipperMessages: {
@@ -1080,11 +1080,12 @@ declare class ClipperAuthInterceptor implements HttpInterceptor {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<ClipperAuthInterceptor>;
 }
 
-declare class ClipperService implements OnDestroy {
-    private httpClient;
-    private broadcastServiceSubscription?;
-    private broadcastService;
-    private dialogService;
+declare class ClipperService {
+    private readonly httpClient;
+    private readonly destroyRef;
+    private readonly broadcastService;
+    private readonly dialogService;
+    private broadcastInitialized;
     private _appUri?;
     get appUri(): string | undefined;
     private _serviceUri;
@@ -1110,12 +1111,11 @@ declare class ClipperService implements OnDestroy {
     readonly availableChannels: _angular_core.WritableSignal<ClipperAvailableChannel[]>;
     readonly activeChannels: Signal<ClipperAvailableChannel[]>;
     readonly allowTags: _angular_core.WritableSignal<boolean>;
-    ngOnDestroy(): void;
     /**
-     * Initialize service
-     * @param serviceUri : the service uri
-     * @param appUri : the clipper application uri
-     * @param flags: the service flags. Default is none.
+     * Initialises the service with the API base URI, optional app URI, and feature flags.
+     * @param serviceUri - The base URI of the Clipper REST API.
+     * @param appUri - Optional URI of the Clipper web application (used to build document links).
+     * @param flags - Feature flags that control service behaviour. Defaults to `ClipperServiceFlags.None`.
      */
     initialize(serviceUri: string, appUri?: string, flags?: ClipperServiceFlags): void;
     /**
@@ -1123,80 +1123,83 @@ declare class ClipperService implements OnDestroy {
    */
     ping(): void;
     /**
-     * Store context
+     * Persists the current login context to `localStorage`.
      */
     storeContext(): void;
     /**
-  * Update context
-  * @param result: the new context
-  */
+     * Updates the stored login context with the values from a fresh login result.
+     * @param result - The login result containing the new user context and channel settings.
+     */
     updateContext(result: ClipperLoginResult): void;
     /**
-    * Perform auto login using current link data
-    * @param onSuccess: function to execute on seccess
-    */
-    autoLogin(onSuccess?: Function): void;
+     * Attempts an automatic login using the credentials currently stored in session storage.
+     * @param onSuccess - Optional callback invoked with the login result value on success.
+     */
+    autoLogin(onSuccess?: (value?: any) => void): void;
     /**
-     * Perform auto logout
-     * @param onSuccess: function to execute on success
+     * Performs an automatic logout and clears the stored session.
+     * @param onSuccess - Optional callback invoked after a successful logout.
      */
-    autoLogout(onSuccess?: Function): void;
+    autoLogout(onSuccess?: () => void): void;
     /**
-     * Perform login
-     * @param email: the optioanl email if using OAuth2
-     * @parma password: the optional password if using OAuth2
-     * @param remember: remember credentials
-     * @param oauth: the optional open authentication supported
-     * @param oauthAccessToken: the optional OAuth2 access token
+     * Authenticates the user against the Clipper API, supporting both credential-based and
+     * OAuth2 login flows.
+     * @param email - The user's email address (credential login only).
+     * @param password - The user's password (credential login only).
+     * @param remember - When `true`, the session is remembered across browser restarts.
+     * @param oauth - The OAuth2 provider type, when authenticating via SSO.
+     * @param oauthAccessToken - The OAuth2 bearer token. Defaults to the value stored in session storage.
      */
     login(email?: string, password?: string, remember?: boolean, oauth?: LoginOAuthType, oauthAccessToken?: string | undefined): rxjs.Observable<ApiResult<ClipperLoginResult>>;
     /**
-     * Complete login
-     * @param result : the login result
+     * Finalises the login flow by updating the stored context, setting the logged-in signal,
+     * initialising channels, and broadcasting `LOGIN_COMPLETED`.
+     * @param result - The login result returned by the API.
      */
     private completeLogin;
     /**
-     * Confirm MFA procedure
-     * @param code: the confirm code
+     * Submits the MFA confirmation code to complete a two-factor login flow.
+     * @param code - The one-time confirmation code provided to the user.
      */
     confirmIdentity(code: string): rxjs.Observable<ApiResult<ClipperLoginResult>>;
     /**
-     * Perform logout
-     * @param forget: true to dispose all user informations
+     * Logs the user out and clears the current session.
+     * @param forget - When `true`, all stored user credentials are also removed.
      */
     logout(forget?: boolean): rxjs.Observable<any>;
     /**
-    * Reset login refresh timer and login state
-    */
+     * Resets the login state, clears the stored login info, and broadcasts `LOGOUT_COMPLETED`.
+     */
     reset(): void;
     /**
-     * Clear login data
-     * @param clearOAuthToken: true to clear oauth token also
+     * Clears all session-storage authentication keys and resets the login state.
+     * @param clearOAuthToken - When `true`, the OAuth bearer token is also removed.
      */
     clear(clearOAuthToken?: boolean): void;
     /**
-     * Update channel state
-     * @param value : the new dashboard result with updated channels and dashboard info
+     * Applies a new dashboard result: updates channel settings, dashboard counters, and
+     * re-initialises the available-channels signal.
+     * @param value - The dashboard result containing updated channel and counter data.
      */
     setChannelsState(value: ClipperDashboardResult): void;
     /**
-     * Update channels
-     * @param channels: the new channels settings
+     * Replaces the stored channel settings and re-initialises the available-channels signal.
+     * @param channels - The new channel settings to store and activate.
      */
     setChannels(channels: ClipperChannelSettings[]): void;
     /**
-   * Initialize channels
-   */
+     * Rebuilds the `availableChannels` signal from the current login context.
+     */
     private initializeChannels;
     /**
-     * Update channels
-     * @param values : the new channel values
+     * Toggles the active state of available channels based on the supplied selection list.
+     * @param values - The selected channel items; channels absent from this list are deactivated.
      */
     updateChannels(values: NameValueItem<ClipperChannel>[]): void;
     /**
-    * Get a new one time password
-    * @param id: the optional repository id
-    */
+     * Requests a new one-time password for the given repository.
+     * @param id - The repository ID for which the OTP should be generated.
+     */
     newOTP(id: string): rxjs.Observable<ApiResult<ClipperOTPInfo>>;
     /**
      * Load Ars events calendar
@@ -1226,6 +1229,10 @@ declare class ClipperService implements OnDestroy {
      * Send documents link by email
      */
     sendTo(params: ClipperSendDocumentsByEmailParams): rxjs.Observable<ApiResult<number>>;
+    /**
+     * Sends an email notification about a document property update to the specified recipients.
+     * @param params - The notification parameters including recipients and property details.
+     */
     notifyPropertyTo(params: ClipperNotifyDocumentUserPropertyParams): rxjs.Observable<ApiResult<UpdateResultModel<ClipperDocumentPropertyTracking>>>;
     /**
      * Display a page the full document report
@@ -1286,50 +1293,50 @@ declare class ClipperService implements OnDestroy {
     /**
     * Retrieve current dashboard
     */
-    loadDashboard(): Subscription;
+    loadDashboard(): rxjs.Subscription;
     /**
-   * Retrieve last 15 days
-   * @param params : the query params
-   */
+     * Retrieves documents updated in the last 15 days for the given search parameters.
+     * @param params - The search parameters to filter results.
+     */
     last15Days(params: ClipperSearchParams): rxjs.Observable<ApiResult<ClipperLastDaysResult>>;
     /**
-    * Update unread items
-    * @param module : the module
-    * @param model : the optional model
-    * @param increment : the increment (can be negative)
-    */
+     * Adjusts the unread-item counter for the given module and broadcasts a dashboard update.
+     * @param module - The Clipper module whose counter should be adjusted.
+     * @param model - Optional document model to further scope the counter update.
+     * @param increment - The signed increment to apply (use negative values to decrement).
+     */
     updateUnreadItems(module: ClipperModule, model?: ClipperModel, increment?: number): void;
     /**
      * Load working documents
      */
-    loadBag(): Subscription;
+    loadBag(): rxjs.Subscription;
     /**
-     * Add one or more working document
-     * @param documentIds : the document ids to add
+     * Adds one or more documents to the working documents bag.
+     * @param documentIds - The IDs of the documents to add.
      */
-    addToBag(documentIds: string[]): Subscription;
+    addToBag(documentIds: string[]): rxjs.Subscription;
     /**
-     * Remove one working document
-     * @param documentId : the document id
+     * Removes a document from the working documents bag.
+     * @param documentId - The ID of the document to remove.
      */
-    removeFromBag(documentId: string): Subscription;
+    removeFromBag(documentId: string): rxjs.Subscription;
     /**
      * Clear all working documents
      */
-    clearBag(): Subscription;
+    clearBag(): rxjs.Subscription;
     /**
-     * Load working searches
-     * @param: module: the module to load searches for
+     * Retrieves the saved searches for the given module.
+     * @param module - The Clipper module whose saved searches to load.
      */
     loadSearches(module: ClipperModule): rxjs.Observable<ApiResult<ClipperUserSearch[]>>;
     /**
-     * Save a working search
-     * @param params : the clipper user search
+     * Persists a user search configuration on the server.
+     * @param params - The search configuration to save.
      */
     saveSearch(params: ClipperUserSearch): rxjs.Observable<ApiResult<ClipperUserSearch>>;
     /**
-     * Remove one working search
-     * @param id : the id to remove
+     * Deletes a saved search by its ID.
+     * @param id - The ID of the saved search to remove.
      */
     deleteSearch(id: number): rxjs.Observable<ApiResult<number>>;
     /**
@@ -1341,105 +1348,105 @@ declare class ClipperService implements OnDestroy {
      */
     calendarSnapshot(params: ClipperCalendarSearchParams): rxjs.Observable<ApiResult<ClipperSearchCalendarSnapshotResult>>;
     /**
-     * Delete one or more items
-     * @param ids: ids to delete
+     * Deletes one or more calendar deadlines by ID.
+     * @param ids - The IDs of the deadlines to delete.
      */
     deleteCalendarDeadlines(ids: string[]): rxjs.Observable<ApiResult<number>>;
     /**
-     * Copy one or more items
-     * @param params parameters
+     * Copies one or more calendar deadlines using the given parameters.
+     * @param params - The copy operation parameters.
      */
     copyCalendarDeadlines(params: ClipperCalendarCopyDeadlinesParams): rxjs.Observable<ApiResult<number>>;
     /**
-     * Close a deadline
-     * @param id : the id to close
+     * Marks the given calendar deadline as closed.
+     * @param id - The ID of the deadline to close.
      */
     closeCalendarDeadline(id: string): rxjs.Observable<ApiResult<ClipperDeadlineInfo>>;
     /**
-     * Save an item
-     * @param params parameters
+     * Creates or updates a calendar deadline.
+     * @param params - The deadline data to save.
      */
     saveCalendarDeadline(params: ClipperCalendarSaveDeadlineParams): rxjs.Observable<ApiResult<ClipperDeadlineInfo[]>>;
     /**
-     * Retrive a n item
-     * @param id : the item id
+     * Retrieves a single calendar deadline by its ID.
+     * @param id - The ID of the deadline to retrieve.
      */
     getCalendarDeadline(id: string): rxjs.Observable<ApiResult<ClipperDeadlineInfo>>;
     /**
-     * Export to iCalendar format
-     * @param ids : deadlines to export
+     * Exports the selected deadlines in iCalendar (.ics) format.
+     * @param ids - The IDs of the deadlines to export.
      */
     exportCalendarDeadlines(ids: string[]): rxjs.Observable<Blob>;
     /**
-    * Retrieve all folders
-    * @param params : parameters
-    */
+     * Retrieves all archive folders matching the given search parameters.
+     * @param params - The folder search parameters.
+     */
     getArchiveFolders(params: ClipperArchiveFoldersSearchParams): rxjs.Observable<ApiResult<ClipperArchiveFoldersSearchResult>>;
     /**
-     * Save folder
-     * @param params : parameters
+     * Creates or updates an archive folder.
+     * @param params - The folder data to save.
      */
     saveArchiveFolder(params: Folder): rxjs.Observable<ApiResult<Folder>>;
     /**
-     * Export folders
-     * @param id: the folder id or undefined to export all folders
-     * @param teamId: the optional team id. Default undefined (personal)
+     * Exports archive folders as a downloadable file.
+     * @param id - The folder ID to export, or `undefined` to export all folders.
+     * @param teamId - The optional team ID. Defaults to `undefined` (personal workspace).
      */
     exportArchiveFolders(id?: string, teamId?: string): rxjs.Observable<Blob>;
     /**
-     * Import folders
-     * @param params : parameters
+     * Uploads and imports archive folders from a file.
+     * @param params - The import parameters including the source file and destination folder.
      */
     importArchiveFolders(params: ClipperArchiveFoldersImportParams): rxjs.Observable<_angular_common_http.HttpEvent<unknown>>;
     /**
-     * Get files and folders
-     * @param params : parameters
+     * Retrieves archive files and folders matching the given search parameters.
+     * @param params - The archive files search parameters.
      */
     queryArchiveItems(params: ClipperArchiveFilesSearchParams): rxjs.Observable<ApiResult<ClipperArchiveFilesSearchResult>>;
     /**
-     * Delete file and folders
-     * @param params parameters
+     * Deletes one or more archive files or folders.
+     * @param params - The delete operation parameters.
      */
     deleteArchiveItems(params: ClipperArchiveFilesDeleteParams): rxjs.Observable<ApiResult<number>>;
     /**
-     * Copy  file and folders to another folder or the same
-     * @param params parameters
+     * Copies archive files or folders to a destination folder.
+     * @param params - The copy operation parameters.
      */
     copyArchiveItems(params: ClipperArchiveFilesCopyParams): rxjs.Observable<ApiResult<number>>;
     /**
-     * Save a file
-     * @param params : parameters
+     * Uploads and saves an archive file using multipart form data.
+     * @param params - The file metadata and binary content to save.
      */
     saveArchiveFile(params: ClipperArchiveFileInfo): rxjs.Observable<_angular_common_http.HttpEvent<unknown>>;
     /**
-     * Get file data
-     * @param id : the item id
+     * Retrieves the metadata for a single archive file.
+     * @param id - The ID of the archive file to retrieve.
      */
     getArchiveFile(id: string): rxjs.Observable<ApiResult<ClipperArchiveFileInfo>>;
     /**
-     * Download file
-     * @param id : the binary id to download
-     * @param otp : the optional one time password
+     * Downloads the binary content of an archive file.
+     * @param id - The binary ID of the file to download.
+     * @param otp - An optional one-time password for authenticated downloads.
      */
     downloadArchiveFile(id: number, otp?: string): rxjs.Observable<Blob>;
     /**
-   * Reset a user password
-   * @param params parameters
-   */
+     * Resets the user's password using the provided parameters.
+     * @param params - The new password and confirmation data.
+     */
     resetPassword(params: ResetPasswordDialogResult): rxjs.Observable<ApiResult<ResetPasswordDialogResult>>;
     /**
-     * Recover password
-     * @param params parameters
+     * Initiates a password recovery flow by sending a reset link to the user's email.
+     * @param params - The password recovery request data.
      */
     recoverPassword(params: RecoverPasswordDialogResult): rxjs.Observable<ApiResult<boolean>>;
     /**
-     * Update settings
-       * @param params parameters
+     * Updates user account settings and applies any channel configuration changes.
+     * @param params - A map of settings key-value pairs to update.
      */
     updateSettings(params: any): rxjs.Observable<ApiResult<boolean>>;
     /**
-     * Update channel state
-     * @param id: the channel id (1, 2, 3, 4)
+     * Saves updated channel activation states to the server and applies the new dashboard result.
+     * @param params - The channel state update parameters.
      */
     updateChannelsState(params: ClipperUpdateChannelsStateParams): rxjs.Observable<ApiResult<ClipperDashboardResult>>;
     /**
@@ -1447,73 +1454,77 @@ declare class ClipperService implements OnDestroy {
      */
     private getTrialInfo;
     /**
-     * Update trial info
+     * Refreshes the trial status from the server and updates the stored login context.
      */
     updateTrialInfo(): void;
     /**
-    * Save a user link
-    * @param item: the user link
-    */
+     * Creates or updates a user link record.
+     * @param item - The user link data to save.
+     */
     saveLink(item: ClipperUserLink): rxjs.Observable<ApiResult<boolean>>;
     /**
-     * Delete a user link
-     * @param item: the user link
+     * Deletes a user link record.
+     * @param item - The user link to remove.
      */
     deleteLink(item: ClipperUserLink): rxjs.Observable<ApiResult<boolean>>;
     /**
-    * Rename a team
-    * @param newName : the new name
-    */
+     * Renames the current user's team.
+     * @param newName - The new display name for the team.
+     */
     renameTeam(newName: string): rxjs.Observable<ApiResult<ClipperTeamInfo>>;
     /**
-     * Retrieve teams
+     * Retrieves the list of teams available to the current user.
+     * @param params - The teams search parameters.
      */
     getTeams(params: ClipperTeamsSearchParams): rxjs.Observable<ApiResult<ClipperTeamsSearchResult>>;
     /**
-     * Retrieve team members
+     * Retrieves the members of a team matching the given search parameters.
+     * @param params - The team members search parameters.
      */
     getTeamMembers(params: ClipperTeamsSearchParams): rxjs.Observable<ApiResult<ClipperTeamMembersSearchResult>>;
     /**
-     * Delete members
-     * @param ids: the id list to delete
+     * Removes the specified members from the team.
+     * @param ids - The numeric IDs of the team members to remove.
      */
     deleteTeamMembers(ids: number[]): rxjs.Observable<ApiResult<number>>;
     /**
-     * Save member
-     * @param item: the item to save
+     * Creates or updates a team member record.
+     * @param item - The team member data to save.
      */
     saveTeamMember(item: ClipperTeamMemberInfo): rxjs.Observable<ApiResult<ClipperTeamMemberInfo>>;
     /**
-     * Retrieve contacts
+     * Retrieves contacts matching the given search parameters.
+     * @param params - The contacts search parameters.
      */
     queryContacts(params: ClipperContactsSearchParams): rxjs.Observable<ApiResult<QueryResultModel<ClipperContactInfo>>>;
     /**
-     * Delete contacts
-     * @param ids: the id list to delete
+     * Deletes the specified contacts.
+     * @param ids - The numeric IDs of the contacts to remove.
      */
     deleteContacts(ids: number[]): rxjs.Observable<ApiResult<number>>;
     /**
-     * Save contact
-     * @param item: the item to save
+     * Creates or updates a contact record.
+     * @param item - The contact data to save.
      */
     saveContact(item: ClipperContactInfo): rxjs.Observable<ApiResult<ClipperContactInfo>>;
     /**
-     * Retrieve properties
+     * Retrieves document properties matching the given search parameters.
+     * @param params - The properties search parameters.
      */
     queryProperties(params: ClipperPropertiesSearchParams): rxjs.Observable<ApiResult<QueryResultModel<ClipperDocumentProperty>>>;
     /**
-     * Delete properties
-     * @param ids: the id list to delete
+     * Deletes the specified document properties.
+     * @param ids - The numeric IDs of the properties to remove.
      */
     deleteProperties(ids: number[]): rxjs.Observable<ApiResult<number>>;
     /**
-     * Save property
-     * @param item: the item to save
+     * Creates or updates a document property.
+     * @param item - The property data to save.
      */
     saveProperty(item: ClipperDocumentProperty): rxjs.Observable<ApiResult<ClipperDocumentProperty>>;
     /**
-     * Get the property tracking list for a property
-     * @param id: the property id
+     * Retrieves the tracking history for the given document property.
+     * @param id - The numeric ID of the property whose tracking records to retrieve.
      */
     getPropertyTrackings(id: number): rxjs.Observable<ApiResult<ClipperDocumentPropertyTracking[]>>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClipperService, never>;