@yuuvis/client-core 2.13.0 → 2.15.0

package/lib/model/file-upload-options.model.d.ts

@@ -0,0 +1,5 @@
+export interface FileUploadOptions {
+    label?: string;
+    silent?: boolean;
+    scope?: string;
+}

package/lib/service/dms/dms.service.d.ts

@@ -1,16 +1,16 @@
 import { Observable } from 'rxjs';
+import { DmsObjectTag } from '../../model/dms-object.interface';
 import { DmsObject } from '../../model/dms-object.model';
+import { FileUploadOptions } from '../../model/file-upload-options.model';
 import { HttpOptions } from '../backend/backend.interface';
 import { SearchResponse, SearchResult } from '../search/search.service.interface';
 import { CoreApiResponse, ObjectCopyOptions, ObjectDeleteOptions, ObjectDeleteResult, ObjectMoveOptions, ObjectOptions } from './dms.service.interface';
-import { DmsObjectTag } from '../../model/dms-object.interface';
 import * as i0 from "@angular/core";
 /**
  * Service for working with dms objects: create them, delete, etc.
  */
 export declare class DmsService {
     #private;
-    private triggerEvent;
     /**
      * Create new dms object(s). Providing an array of files here instead of one will create
      * a new dms object for every file. In this case indexdata will shared across all files.
@@ -38,8 +38,48 @@ export declare class DmsService {
      * @param objectId ID of the dms object to upload the file to
      * @param file The file to be uploaded
      * @param label A label that will show up in the upload overlay dialog while uploading
+     *
+     * @deprecated use uploadFileContent instead. Provide label and silent through `options`
      */
     uploadContent(objectId: string, file: File, label?: string, silent?: boolean): Observable<any>;
+    /**
+     * Uploads a file as the content of an existing DMS object, replacing or setting its content stream.
+     *
+     * This is the preferred alternative to the legacy `uploadContent()` method. It accepts a typed
+     * `FileUploadOptions` object instead of individual parameters, which enables full control over
+     * the upload label, silent mode, and scope-based progress visibility.
+     *
+     * After a successful upload, a `DMS_OBJECT_UPDATED` event is triggered automatically so that
+     * any subscribed parts of the application can react to the change (e.g. refreshing a preview).
+     *
+     * **Behavior:**
+     * - Targets the content endpoint of the given DMS object: `/dms/objects/{objectId}/contents/file`
+     * - `options.label` is shown in the upload progress indicator; falls back to `file.name` if omitted
+     * - If `options.silent` is `true`, the upload runs in the background with no UI feedback
+     *   and no `DMS_OBJECT_UPDATED` event is emitted
+     * - `options.scope` tags the upload so that only the `UploadProgressComponent` instance
+     *   configured with the same scope will display progress for this upload
+     *
+     * @param objectId - ID of the DMS object whose content should be uploaded or replaced
+     * @param file - The `File` object to upload as the new content stream
+     * @param options - Upload configuration: label, silent mode, and optional scope
+     * @returns An `Observable` that emits the updated DMS object on completion
+     *
+     * @example
+     * ```typescript
+     * // Replace content with a visible progress indicator
+     * this.dmsService.uploadFileContent(objectId, file, { label: 'Uploading contract.pdf' }).subscribe();
+     *
+     * // Silent replacement (no UI feedback, no event emitted)
+     * this.dmsService.uploadFileContent(objectId, file, { label: 'report.pdf', silent: true }).subscribe();
+     *
+     * // Scoped upload — only UploadProgressComponent with scope 'detail-panel' will show this
+     * this.dmsService
+     *   .uploadFileContent(objectId, file, { label: 'photo.jpg', scope: 'detail-panel' })
+     *   .subscribe();
+     * ```
+     */
+    uploadFileContent(objectId: string, file: File, options: FileUploadOptions): Observable<unknown>;
     /**
      * Path of dms object content file.
      * @param objectId ID of the dms object
@@ -66,7 +106,7 @@ export declare class DmsService {
      * @param id ID of the object to be retrieved
      * @param version Desired version of the object
      */
-    getDmsObject(id: string, version?: number, silent?: boolean, requestOptions?: HttpOptions | undefined): Observable<DmsObject>;
+    getDmsObject(id: string, version?: number, silent?: boolean, requestOptions?: HttpOptions): Observable<DmsObject>;
     /**
      * Get tags of a dms object.
      * @param objectData  Data field of the dms object
@@ -161,6 +201,7 @@ export declare class DmsService {
      * @param searchResponse The backend response
      */
     toSearchResult(searchResponse: SearchResponse): SearchResult;
+    private triggerEvent;
     static ɵfac: i0.ɵɵFactoryDeclaration<DmsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<DmsService>;
 }

package/lib/service/dms/dms.service.interface.d.ts

@@ -1,5 +1,6 @@
 export interface ObjectOptions {
     waitForSearchConsistency?: boolean;
+    scope?: string;
 }
 export interface ObjectDeleteOptions extends ObjectOptions {
     silent?: boolean;

package/lib/service/event/event.service.d.ts

@@ -1,5 +1,5 @@
 import { Observable } from 'rxjs';
-import { YuvEvent, IsAny } from './event.interface';
+import { IsAny, YuvEvent } from './event.interface';
 import * as i0 from "@angular/core";
 /**
  * Service for providing triggered events

package/lib/service/upload/upload.interface.d.ts

@@ -15,6 +15,7 @@ export interface ProgressStatusItem {
     progress: Observable<number>;
     subscription: Subscription;
     result?: UploadResult[];
+    scope?: string;
     err?: {
         code: number;
         message: string;

package/lib/service/upload/upload.service.d.ts

@@ -1,4 +1,5 @@
 import { Observable } from 'rxjs';
+import { FileUploadOptions } from '../../model/file-upload-options.model';
 import { ProgressStatus } from './upload.interface';
 import * as i0 from "@angular/core";
 /**
@@ -13,20 +14,145 @@ export declare class UploadService {
      * @param url The URL to upload the file to
      * @param file The file to be uploaded
      * @param label A label that will show up in the upload overlay dialog while uploading
+     *
+     * @deprecated use uploadFile instead. `label`, `silent` as well as `scope` can be provided through `options`.
      */
     upload(url: string, file: File, label?: string, silent?: boolean): Observable<any>;
+    /**
+     * Uploads a single file to the specified URL using the structured `FileUploadOptions` object.
+     *
+     * This is the preferred alternative to the legacy `upload()` method. It accepts a typed
+     * options object instead of individual parameters, which makes it easier to pass optional
+     * settings such as `silent` mode and `scope` without relying on positional arguments.
+     *
+     * **Behavior:**
+     * - If `options.silent` is `false` (default), the upload appears in the upload overlay dialog
+     *   and progress is tracked via `status$`
+     * - If `options.silent` is `true`, the upload runs quietly in the background with no UI feedback
+     * - `options.label` is shown in the overlay dialog during upload; falls back to `file.name` if omitted
+     * - `options.scope` tags the upload with a named scope, enabling an `UploadProgressComponent`
+     *   configured with the same scope to display only the uploads relevant to its section of the UI
+     *
+     * @param url - The backend URL to POST the file to
+     * @param file - The `File` object to be uploaded
+     * @param options - Upload configuration: label, silent mode, and optional scope
+     * @returns An `Observable` that emits the server response on completion
+     *
+     * @example
+     * ```typescript
+     * // Standard upload with progress indicator
+     * this.uploadService.uploadFile(url, file, { label: 'Uploading contract.pdf' }).subscribe();
+     *
+     * // Silent upload (no UI, runs in background)
+     * this.uploadService.uploadFile(url, file, { label: 'document.pdf', silent: true }).subscribe();
+     *
+     * // Scoped upload — only the UploadProgressComponent with scope 'profile-editor' will show this
+     * this.uploadService.uploadFile(url, file, { label: 'photo.jpg', scope: 'profile-editor' }).subscribe();
+     * ```
+     */
+    uploadFile(url: string, file: File, options: FileUploadOptions): Observable<unknown>;
     /**
      * Upload files using multipart upload.
      * @param url The URL to upload the files to
      * @param files The files to be uploaded
      * @param data Data to be send along with the files
      * @param label A label that will show up in the upload overlay dialog while uploading
+     *
+     * @deprecated Use multipartUpload(url, files, options, data) instead. Provide scope through options.
      */
     uploadMultipart(url: string, files: File[], data?: any, label?: string, silent?: boolean): Observable<any>;
+    /**
+     * Uploads multiple files to the specified URL using a multipart/form-data request.
+     *
+     * This is the preferred method for multi-file uploads. It accepts a typed `FileUploadOptions`
+     * object for configuration, making it easier to pass `scope` and other options compared
+     * to the legacy `uploadMultipart()` overload.
+     *
+     * **Behavior:**
+     * - All files are bundled into a single `FormData` payload under the `files` field
+     * - Optional `data` is appended as a JSON blob under the `data` field
+     * - If `options.silent` is `false` (default), upload progress is shown in the overlay dialog
+     * - If `options.silent` is `true`, the upload runs in the background with no UI feedback
+     * - `options.scope` tags the upload with a named scope, enabling an `UploadProgressComponent`
+     *   configured with the same scope to display only the uploads relevant to its section of the UI
+     *
+     * @param url - The backend URL to POST the multipart request to
+     * @param files - Array of `File` objects to upload
+     * @param options - Upload configuration: label (required), silent mode, and optional scope
+     * @param data - Optional metadata object to send alongside the files (serialized as JSON)
+     * @returns An `Observable` that emits the server response on completion
+     *
+     * @example
+     * ```typescript
+     * // Upload files with a visible progress indicator
+     * this.uploadService.multipartUpload(url, files, { label: 'Uploading 3 files' }).subscribe();
+     *
+     * // Upload files with additional metadata
+     * this.uploadService
+     *   .multipartUpload(url, files, { label: 'Batch upload' }, { folderId: 'abc123' })
+     *   .subscribe();
+     *
+     * // Scoped upload — only the UploadProgressComponent with scope 'mail-editor' will show this
+     * this.uploadService
+     *   .multipartUpload(url, files, { label: 'attachments', scope: 'mail-editor' })
+     *   .subscribe();
+     * ```
+     */
+    multipartUpload(url: string, files: File[], options: FileUploadOptions, data?: unknown): Observable<unknown>;
+    /**
+     * Creates a document on the server by sending structured metadata without a file attachment.
+     *
+     * Unlike `uploadFile()` and `multipartUpload()`, this method does not attach any file content.
+     * It is intended for creating document objects from metadata alone — for example, creating
+     * a folder, a placeholder record, or a document entry where the content stream will be
+     * provided separately.
+     *
+     * **Behavior:**
+     * - Sends the `data` object as a JSON blob inside a `FormData` payload
+     * - Progress is NOT tracked — this method does not appear in `status$`
+     * - Errors are re-thrown so the caller can handle them via the returned `Observable`
+     *
+     * @param url - The backend URL to POST the document creation request to
+     * @param data - Metadata object describing the document to be created
+     * @returns An `Observable` that emits the created object(s) on success
+     *
+     * @example
+     * ```typescript
+     * const metadata = {
+     *   objectTypeId: 'yuv:document',
+     *   properties: { 'yuv:title': 'My Document' }
+     * };
+     *
+     * this.uploadService.createDocument(url, metadata).subscribe((result) => {
+     *   console.log('Created:', result);
+     * });
+     * ```
+     */
     createDocument(url: string, data: any): Observable<any>;
     /**
-     * Cancels an upload request and removes it from the list of files being uploaded.
-     * @param id ID of the UploadItem to be canceled
+     * Cancels one or all active upload requests and removes them from the tracked upload list.
+     *
+     * This method unsubscribes from the underlying HTTP request, effectively aborting the upload,
+     * and removes the corresponding item(s) from the internal status list. The updated status
+     * is then emitted via `status$` so that any subscribed UI components (e.g. the upload overlay)
+     * can reflect the change immediately.
+     *
+     * **Behavior:**
+     * - If `id` is provided, only the matching upload item is cancelled
+     * - If `id` is omitted, **all** active uploads are cancelled at once
+     * - If the provided `id` does not match any active item, the call is a no-op
+     * - After cancellation, the error count on `status$` is recalculated
+     *
+     * @param id - Optional ID of the upload item to cancel. Omit to cancel all active uploads.
+     *
+     * @example
+     * ```typescript
+     * // Cancel a specific upload by ID
+     * this.uploadService.cancelItem(uploadId);
+     *
+     * // Cancel all ongoing uploads (e.g. on component destroy or user confirmation)
+     * this.uploadService.cancelItem();
+     * ```
      */
     cancelItem(id?: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<UploadService, never>;

package/package.json

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