itlab-internal-services 2.15.6 → 2.16.0

package/README.md

@@ -1,4 +1,5 @@
 # IT Lab Internal Services
+
 > Diese Library funktioniert nur mit NestJs
 
 [![npm version](https://img.shields.io/npm/v/itlab-internal-services.svg?style=flat-square)](https://www.npmjs.org/package/itlab-internal-services)
@@ -17,190 +18,3 @@ To begin using it, we first install the required dependency.
 ```bash
 yarn add itlab-internal-services
 ```
-
-### Getting started
-
-Once the installation process is complete, to use the `InternalServices`, first import `InternalModule`.
-
-```typescript
-@Module({
-  imports: [InternalModule],
-  providers: [NewsService],
-})
-export class NewsModule {}
-```
-
-Next, inject `CommentService`, `ContentService` or `SearchService` using normal constructor injection.
-
-> **Hint** `InternalModule`, `CommentService`, `ContentService` & `SearchService` are imported from `itlab-internal-services` package.
-
-```typescript
-@Injectable()
-export class NewsService {
-  constructor(
-    private readonly commentService: CommentService,
-    private readonly contentService: ContentService,
-    private readonly searchService: SearchService,
-  ) {}
-}
-```
-
-### Comment Service
-```typescript
-async post(targetId: string, authorId: string, comment: Comment): Promise<Comment>
-```
-
-```typescript
-async delete(targetId: string): Promise<void>
-```
-
-### Content Service
-
-```typescript
-async verify(content: Content): Promise<void>
-```
-
-```typescript
-async post(targetId: string, content: Content): Promise<void>
-```
-
-```typescript
-async delete(targetId: string): Promise<void>
-```
-
-### Pipes
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiTarget("target")
-  @Get(":target")
-  getNews(@Target("target") target: string) {}
-
-}
-```
-
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiHid("hid")
-  @Get(":hid")
-  getNews(@Hid("hid") hid: string) {}
-
-}
-```
-
-```typescript
-@Controller("news")
-export class NewsController {
-
-  @ApiId("id")
-  @Get(":id")
-  getNews(@Id("id") id: string) {}
-
-}
-```
-
-### Guards
-```typescript
-@Internal()
-@Controller()
-export class NewsController {}
-```
-
-```typescript
-@Jwt()
-@Controller()
-export class NewsController {
-  @Get("")
-  getNews(@Account() account: LAccount) {}
-
-  @Get("")
-  getNews(@AccountId() accountId: string) {}
-
-  @Perms("perms.get", "perms.list")
-  @Get("")
-  getNews(@AccountId() accountId: string, @AccountPerms() accountPerms: string[]) {}
-}
-```
-
-### Configuration
-
-To configure the underlying service instance, pass an optional options object to the `register()` method of `InternalModule` when importing it. This options object will be passed directly to the underlying service constructor.
-
-```typescript
-@Module({
-  imports: [
-    InternalModule.register({
-      target: Targets.NEWSROOM,
-      token: 'itlab token',
-      jwt_secret: 'secret',
-    }),
-  ],
-  providers: [NewsService],
-})
-export class NewsModule {}
-```
-
-### Async configuration
-
-When you need to pass module options asynchronously instead of statically, use the `registerAsync()` method. As with most dynamic modules, this package provides several techniques to deal with async configuration.
-
-One technique is to use a factory function:
-
-```typescript
-InternalModule.registerAsync({
-  useFactory: () => ({
-    target: Targets.NEWSROOM,
-    token: 'itlab token',
-    jwt_secret: 'secret',
-  }),
-});
-```
-
-Like other factory providers, our factory function can be [async](https://docs.nestjs.com/fundamentals/custom-providers#factory-providers-usefactory) and can inject dependencies through `inject`.
-
-```typescript
-InternalModule.registerAsync({
-  imports: [ConfigModule],
-  useFactory: (configService: ConfigService) => ({
-    target: Targets.NEWSROOM,
-    token: configService.get<string>('K8S_TOKEN'),
-    jwt_secret: configService.get<string>('JWT_SECRET'),
-  }),
-  inject: [ConfigService],
-});
-```
-
-Alternatively, you can configure the `InternalModule` using a class instead of a factory, as shown below.
-
-```typescript
-InternalModule.registerAsync({
-  useClass: InternalConfigService,
-});
-```
-
-The construction above instantiates `InternalConfigService` inside `InternalModule`, using it to create an options object. Note that in this example, the `InternalConfigService` has to implement `InternalModuleOptionsFactory` interface as shown below. The `InternalModule` will call the `createInternalOptions()` method on the instantiated object of the supplied class.
-
-```typescript
-@Injectable()
-class InternalConfigService implements InternalModuleOptionsFactory {
-  createInternalOptions(): InternalModuleOptions {
-    return {
-      target: Targets.NEWSROOM,
-      token: 'itlab token',
-      jwt_secret: 'secret',
-    };
-  }
-}
-```
-
-If you want to reuse an existing options provider instead of creating a private copy inside the `InternalModule`, use the `useExisting` syntax.
-
-```typescript
-InternalModule.registerAsync({
-  imports: [ConfigModule],
-  useExisting: InternalConfigService,
-});
-```

package/dist/classes/document-merger.class.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocumentMerger = void 0;
 const common_1 = require("@nestjs/common");
-const itlab_functions_1 = require("itlab-functions");
 /**
  * DocumentMerger
  *
@@ -51,8 +50,7 @@ class DocumentMerger {
     async merge(transform) {
         const startTime = Date.now();
         const cursor = this.model.find().cursor();
-        // Process documents one by one to handle large collections efficiently
-        for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
+        await cursor.eachAsync(async (doc) => {
             // Apply user-defined transformation if provided
             if (transform) {
                 doc = transform(doc);
@@ -74,10 +72,10 @@ class DocumentMerger {
             }
             // Save changes to the database without updating timestamps
             await doc.save({ timestamps: false });
-        }
+        });
         const elapsedTime = Date.now() - startTime;
         // Log completion with fields merged and time taken
-        this.logger.log(`Successfully merged fields: ${(0, itlab_functions_1.formatList)(this.fields)} (took ${elapsedTime} ms)`);
+        this.logger.log(`Successfully merged fields: ${this.fields.join(', ')} (took ${elapsedTime} ms)`);
     }
 }
 exports.DocumentMerger = DocumentMerger;

package/dist/classes/index.d.ts

@@ -1,2 +1,3 @@
 export { DocumentMerger } from './document-merger.class';
 export { DocumentUpdater } from './document-updater.class';
+export { ReportCategory } from './report-category.class';

package/dist/classes/index.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocumentUpdater = exports.DocumentMerger = void 0;
+exports.ReportCategory = exports.DocumentUpdater = exports.DocumentMerger = void 0;
 var document_merger_class_1 = require("./document-merger.class");
 Object.defineProperty(exports, "DocumentMerger", { enumerable: true, get: function () { return document_merger_class_1.DocumentMerger; } });
 var document_updater_class_1 = require("./document-updater.class");
 Object.defineProperty(exports, "DocumentUpdater", { enumerable: true, get: function () { return document_updater_class_1.DocumentUpdater; } });
+var report_category_class_1 = require("./report-category.class");
+Object.defineProperty(exports, "ReportCategory", { enumerable: true, get: function () { return report_category_class_1.ReportCategory; } });

package/dist/classes/report-category.class.d.ts

@@ -0,0 +1,55 @@
+import { Document } from 'mongoose';
+/**
+ * Defines which array-type attributes of a document should be tracked,
+ * along with human-readable labels for reporting.
+ *
+ * Only attributes of type `string[]` are tracked.
+ *
+ * Example:
+ * { genres: "Genres", tags: "Tags" }
+ */
+type ReportCategoryAttributes<T extends Document> = Partial<{
+    [K in keyof Omit<T, keyof Document> as T[K] extends string[] ? K : never]: string;
+}>;
+type ReportCategoryExport = Array<{
+    id: string;
+} & Record<string, number>>;
+/**
+ * ReportCategory
+ *
+ * Manages multiple AttributeAggregator instances, each associated
+ * with a unique entity key (e.g., organization, category).
+ * Provides methods to insert documents and export aggregated reports.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+export declare class ReportCategory<T extends Document> {
+    private aggregators;
+    private attributes;
+    /**
+     * Initializes the report manager with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes: ReportCategoryAttributes<T>);
+    /**
+     * Inserts a document into one or multiple entity aggregators.
+     * Automatically creates the aggregator if it does not exist.
+     *
+     * @param document - The document to insert.
+     * @param entityKeys - Single or multiple entity identifiers.
+     */
+    insertDocument(document: T, entityKeys: string[] | string): void;
+    /**
+     * Exports aggregated statistics for all entities.
+     *
+     * Each object contains:
+     * - id: Entity key
+     * - documents: Number of documents processed for this entity
+     * - totalX / uniqueX: Aggregated counts for each tracked attribute
+     *
+     * @returns An array of aggregated reports for all entities.
+     */
+    export(): ReportCategoryExport;
+}
+export {};

package/dist/classes/report-category.class.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportCategory = void 0;
+const itlab_functions_1 = require("itlab-functions");
+/**
+ * AttributeAggregator
+ *
+ * Responsible for aggregating statistics for specified array attributes
+ * across multiple document records. Tracks both total counts and
+ * unique values for each attribute.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+class AttributeAggregator {
+    /**
+     * Initializes the aggregator with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes) {
+        this.documents = 0;
+        this.totalCounts = new Map();
+        this.uniqueValues = new Map();
+        this.attributes = attributes;
+    }
+    /**
+     * Processes a single document, updating the total and unique value counts
+     * for each tracked attribute.
+     *
+     * @param document - The document to include in aggregation.
+     */
+    processDocument(document) {
+        this.documents++;
+        for (const attribute of Object.keys(this.attributes)) {
+            const values = document[attribute];
+            // Only handle array attributes
+            if (!Array.isArray(values))
+                continue;
+            // Update total count for this attribute
+            const previousTotal = this.totalCounts.get(attribute) || 0;
+            this.totalCounts.set(attribute, previousTotal + values.length);
+            // Update the set of unique values for this attribute
+            const currentUnique = this.uniqueValues.get(attribute) || new Set();
+            values.forEach((value) => currentUnique.add(String(value)));
+            this.uniqueValues.set(attribute, currentUnique);
+        }
+    }
+    /**
+     * Exports aggregated statistics for this aggregator.
+     *
+     * Returns an object containing:
+     * - documents: Number of documents processed
+     * - totalX: Total count of values for each attribute
+     * - uniqueX: Count of unique values for each attribute
+     *
+     * @returns An object representing the aggregated data.
+     */
+    export() {
+        var _a;
+        const report = {};
+        for (const [attribute, label] of Object.entries(this.attributes)) {
+            const capitalizedLabel = (0, itlab_functions_1.capitalize)(label);
+            report[`total${capitalizedLabel}`] = this.totalCounts.get(attribute) || 0;
+            report[`unique${capitalizedLabel}`] = ((_a = this.uniqueValues.get(attribute)) === null || _a === void 0 ? void 0 : _a.size) || 0;
+        }
+        return Object.assign({ documents: this.documents }, report);
+    }
+}
+/**
+ * ReportCategory
+ *
+ * Manages multiple AttributeAggregator instances, each associated
+ * with a unique entity key (e.g., organization, category).
+ * Provides methods to insert documents and export aggregated reports.
+ *
+ * @template T - A Mongoose document type with array attributes to track.
+ */
+class ReportCategory {
+    /**
+     * Initializes the report manager with the attributes to track.
+     *
+     * @param attributes - Mapping of document array attributes to display labels.
+     */
+    constructor(attributes) {
+        this.aggregators = new Map();
+        this.attributes = attributes;
+    }
+    /**
+     * Inserts a document into one or multiple entity aggregators.
+     * Automatically creates the aggregator if it does not exist.
+     *
+     * @param document - The document to insert.
+     * @param entityKeys - Single or multiple entity identifiers.
+     */
+    insertDocument(document, entityKeys) {
+        var _a;
+        const keys = Array.isArray(entityKeys) ? entityKeys : [entityKeys];
+        for (const key of keys) {
+            const aggregator = (_a = this.aggregators.get(key)) !== null && _a !== void 0 ? _a : new AttributeAggregator(this.attributes);
+            aggregator.processDocument(document);
+            this.aggregators.set(key, aggregator);
+        }
+    }
+    /**
+     * Exports aggregated statistics for all entities.
+     *
+     * Each object contains:
+     * - id: Entity key
+     * - documents: Number of documents processed for this entity
+     * - totalX / uniqueX: Aggregated counts for each tracked attribute
+     *
+     * @returns An array of aggregated reports for all entities.
+     */
+    export() {
+        return Array.from(this.aggregators.entries()).map(([id, aggregator]) => {
+            return Object.assign({ id }, aggregator.export());
+        });
+    }
+}
+exports.ReportCategory = ReportCategory;

package/dist/decorators/{account.decorator.d.ts → authenticated-account.decorator.d.ts}

@@ -1,4 +1,4 @@
-import { AccountEntity } from '../models';
+import { Account } from '../models';
 /**
  * Custom parameter decorator to extract the authenticated user's account
  * or a specific attribute from it within route handlers.
@@ -10,8 +10,8 @@ import { AccountEntity } from '../models';
  * If no user account is found on the request, it throws an UnprocessableEntityException,
  * signaling that the request is missing necessary authentication context.
  *
- * @param {keyof AccountEntity} [attribute] - Optional key of the AccountEntity to extract.
+ * @param {keyof Account} [attribute] - Optional key of the Account to extract.
  * @param {ExecutionContext} executionContext - The context of the current request.
- * @returns {AccountEntity[keyof AccountEntity] | AccountEntity} The requested account attribute or full account object.
+ * @returns {Account[keyof Account] | Account} The requested account attribute or full account object.
  */
-export declare const Account: (...dataOrPipes: (keyof AccountEntity | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>>)[]) => ParameterDecorator;
+export declare const AuthenticatedAccount: (...dataOrPipes: (keyof Account | import("@nestjs/common").PipeTransform<any, any> | import("@nestjs/common").Type<import("@nestjs/common").PipeTransform<any, any>>)[]) => ParameterDecorator;

package/dist/decorators/{account.decorator.js → authenticated-account.decorator.js}

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Account = void 0;
+exports.AuthenticatedAccount = void 0;
 const common_1 = require("@nestjs/common");
+const exceptions_1 = require("../exceptions");
 /**
  * Custom parameter decorator to extract the authenticated user's account
  * or a specific attribute from it within route handlers.
@@ -13,16 +14,13 @@ const common_1 = require("@nestjs/common");
  * If no user account is found on the request, it throws an UnprocessableEntityException,
  * signaling that the request is missing necessary authentication context.
  *
- * @param {keyof AccountEntity} [attribute] - Optional key of the AccountEntity to extract.
+ * @param {keyof Account} [attribute] - Optional key of the Account to extract.
  * @param {ExecutionContext} executionContext - The context of the current request.
- * @returns {AccountEntity[keyof AccountEntity] | AccountEntity} The requested account attribute or full account object.
+ * @returns {Account[keyof Account] | Account} The requested account attribute or full account object.
  */
-exports.Account = (0, common_1.createParamDecorator)((attribute, executionContext) => {
+exports.AuthenticatedAccount = (0, common_1.createParamDecorator)((attribute, executionContext) => {
     const request = executionContext.switchToHttp().getRequest();
-    const userAccount = request.user;
-    if (!userAccount) {
-        throw new common_1.UnprocessableEntityException('Authenticated user context is missing in the request.');
-    }
-    // Return the requested attribute if specified; otherwise, return the entire account object.
-    return attribute ? userAccount[attribute] : userAccount;
+    if (!request.account)
+        throw new exceptions_1.AuthenticatedAccountRequiredException();
+    return attribute ? request.account[attribute] : request.account;
 });

package/dist/decorators/index.d.ts

@@ -1,2 +1,2 @@
-export * from './account.decorator';
+export * from './authenticated-account.decorator';
 export * from './jwt.decorator';

package/dist/decorators/index.js

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./account.decorator"), exports);
+__exportStar(require("./authenticated-account.decorator"), exports);
 __exportStar(require("./jwt.decorator"), exports);

package/dist/exceptions/authenticated-user-required.exception.d.ts

@@ -0,0 +1,34 @@
+import { ForbiddenException } from '@nestjs/common';
+/**
+ * AuthenticatedAccountRequiredException
+ *
+ * Custom exception extending NestJS's `ForbiddenException`.
+ * This should be thrown when a request is made to an endpoint that
+ * explicitly requires a Bearer Token for authentication.
+ *
+ * By centralizing the exception here, we ensure consistent error
+ * messaging and simplify future changes (e.g., localization or
+ * error structure updates).
+ */
+export declare class AuthenticatedAccountRequiredException extends ForbiddenException {
+    /**
+     * Creates a new `AuthenticatedAccountRequiredException`.
+     *
+     * @param {string} [message] - Optional custom error message.
+     * Defaults to a standard message if none is provided.
+     */
+    constructor(message?: string);
+}
+/**
+ * ApiAuthenticatedAccountRequiredResponse
+ *
+ * Swagger documentation decorator for endpoints that return a `403 Forbidden`
+ * when accessed without authentication. Applying this makes the generated
+ * API docs clear about the requirement for a Bearer Token and communicates
+ * the error condition to consumers.
+ *
+ * @param {string} [description] - Optional custom description for the response.
+ * Defaults to the standard authentication error message.
+ * @returns {MethodDecorator} - Swagger decorator marking a 403 forbidden response.
+ */
+export declare function ApiAuthenticatedAccountRequiredResponse(description?: string): MethodDecorator;

package/dist/exceptions/authenticated-user-required.exception.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticatedAccountRequiredException = void 0;
+exports.ApiAuthenticatedAccountRequiredResponse = ApiAuthenticatedAccountRequiredResponse;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+/**
+ * Default error message used when an endpoint is accessed without authentication.
+ * This provides a consistent and descriptive response to unauthorized users.
+ */
+const defaultAuthenticatedAccountRequiredErrorMessage = 'Authenticated user context is missing in the request.';
+/**
+ * AuthenticatedAccountRequiredException
+ *
+ * Custom exception extending NestJS's `ForbiddenException`.
+ * This should be thrown when a request is made to an endpoint that
+ * explicitly requires a Bearer Token for authentication.
+ *
+ * By centralizing the exception here, we ensure consistent error
+ * messaging and simplify future changes (e.g., localization or
+ * error structure updates).
+ */
+class AuthenticatedAccountRequiredException extends common_1.ForbiddenException {
+    /**
+     * Creates a new `AuthenticatedAccountRequiredException`.
+     *
+     * @param {string} [message] - Optional custom error message.
+     * Defaults to a standard message if none is provided.
+     */
+    constructor(message) {
+        super(message || defaultAuthenticatedAccountRequiredErrorMessage);
+    }
+}
+exports.AuthenticatedAccountRequiredException = AuthenticatedAccountRequiredException;
+/**
+ * ApiAuthenticatedAccountRequiredResponse
+ *
+ * Swagger documentation decorator for endpoints that return a `403 Forbidden`
+ * when accessed without authentication. Applying this makes the generated
+ * API docs clear about the requirement for a Bearer Token and communicates
+ * the error condition to consumers.
+ *
+ * @param {string} [description] - Optional custom description for the response.
+ * Defaults to the standard authentication error message.
+ * @returns {MethodDecorator} - Swagger decorator marking a 403 forbidden response.
+ */
+function ApiAuthenticatedAccountRequiredResponse(description) {
+    return (0, swagger_1.ApiForbiddenResponse)({
+        description: description || defaultAuthenticatedAccountRequiredErrorMessage,
+    });
+}

package/dist/exceptions/bad-body.exception.d.ts

@@ -2,26 +2,37 @@ import { UnprocessableEntityException } from '@nestjs/common';
 /**
  * BadBodyException
  *
- * Thrown when an incoming request body is invalid or malformed.
- * Typical use cases include missing required fields, incorrect data types,
- * or values that violate schema or business validation rules.
+ * Custom exception extending NestJS's `UnprocessableEntityException`.
+ * This exception should be thrown when the request body fails validation
+ * or cannot be interpreted correctly by the server.
  *
- * Returns a standardized HTTP 422 Unprocessable Entity error.
+ * Typical scenarios include:
+ * - Missing required fields
+ * - Incorrect or unexpected data types
+ * - Values violating schema constraints or business rules
+ *
+ * By encapsulating this exception, we provide a clear and consistent
+ * mechanism for handling client input errors across the application.
  */
 export declare class BadBodyException extends UnprocessableEntityException {
     /**
-     * Creates a new BadBodyException with an optional custom message.
+     * Constructs a new `BadBodyException`.
      *
-     * @param {string} [message] - Optional error message describing the specific validation issue.
+     * @param {string} [message] - Optional custom error message for additional context.
+     * Defaults to a standardized message if not provided.
      */
     constructor(message?: string);
 }
 /**
  * ApiBadBodyResponse
  *
- * Swagger decorator for documenting 422 Unprocessable Entity responses due to invalid request bodies.
+ * Swagger documentation decorator for `422 Unprocessable Entity` responses.
+ * Apply this to routes that may reject invalid or malformed request bodies.
+ * This ensures the generated API documentation communicates the validation
+ * expectations and error conditions to API consumers.
  *
  * @param {string} [description] - Optional custom description for the response.
- * @returns {MethodDecorator} Swagger method decorator.
+ * Defaults to a standardized message if not provided.
+ * @returns {MethodDecorator} - Swagger method decorator marking the response.
  */
 export declare function ApiBadBodyResponse(description?: string): MethodDecorator;