itlab-internal-services 2.16.8 → 2.16.9

package/dist/modules/services/base-http.service.d.ts

@@ -6,39 +6,40 @@ import { InternalExternalUrl } from './base-urls';
 /**
  * BaseHttpService
  *
- * A strongly typed, structured wrapper around Axios that standardizes outbound HTTP calls.
+ * A structured, type-safe abstraction over Axios that standardizes outbound HTTP requests
+ * to other internal or external microservices.
  *
- * Core Responsibilities:
- * - Dynamically resolves internal vs external base URLs depending on environment.
- * - Injects Kubernetes service authentication tokens into every request.
- * - Adds structured logging for visibility into outbound traffic.
- *
- * Why use composition over inheritance with Axios?
- * - Axios is both callable and constructable, leading to TypeScript conflicts when extended.
- * - Wrapping avoids prototype traps, giving us full control over configuration and flow.
+ * ### Key Principles:
+ * - **Controlled Configuration:** Rather than subclassing Axios (which creates prototype issues),
+ *   this class wraps Axios to maintain predictable behavior across environments.
+ * - **Environment-Aware Routing:** Selects internal vs. external base URLs automatically based on environment.
+ * - **Secure Communication:** Injects a Kubernetes service token into every outbound request header.
+ * - **Operational Transparency:** Implements structured logging for observability of inter-service communication.
  */
 export declare abstract class BaseHttpService {
     private readonly serviceName;
     private readonly baseUrls;
     private readonly authenticationOptions;
     private readonly configService;
-    readonly client: AxiosInstance;
+    readonly httpClient: AxiosInstance;
     protected readonly logger: Logger;
     protected readonly isProduction: boolean;
     /**
-     * Initializes a new HTTP service client tied to a specific downstream service.
+     * Constructs a base HTTP service instance configured for a downstream microservice.
      *
-     * @param {string} serviceName - Identifier used for contextual logging (e.g., `"Comments"`).
-     * @param {InternalExternalUrl} baseUrls - A tuple `[internalUrl, externalUrl]`. Production prefers internal.
-     * @param {AuthenticationModuleOptions} authenticationOptions - Authentication configuration containing Kubernetes token.
-     * @param {ConfigService} configService - NestJS config service used to resolve runtime environment.
+     * @param {string} serviceName - Name of the downstream service (used for contextualized logs).
+     * @param {InternalExternalUrl} baseUrls - Tuple `[internalUrl, externalUrl]`. In production, internal URLs are preferred for security and speed.
+     * @param {AuthenticationModuleOptions} authenticationOptions - Configuration containing Kubernetes token.
+     * @param {ConfigService} configService - NestJS configuration provider.
      */
     constructor(serviceName: string, baseUrls: InternalExternalUrl, authenticationOptions: AuthenticationModuleOptions, configService: ConfigService);
     /**
-     * Normalizes Axios error responses into a consistent object.
-     * Ensures structured error handling regardless of the downstream service implementation.
+     * Converts an Axios error into a structured and consistent error format.
+     *
+     * This allows downstream callers to rely on predictable error shapes,
+     * regardless of how the target service responds.
      *
-     * @param {any} error - Raw Axios error object.
+     * @param {any} error - Raw Axios error object from a failed request.
      * @returns {{ status: number; data: string | Record<string, any>; message: string }}
      */
     protected parseError(error: any): {
@@ -47,37 +48,40 @@ export declare abstract class BaseHttpService {
         message: string;
     };
     /**
-     * Fetches a single resource from the downstream service.
+     * Retrieves a single resource from the downstream service.
      *
-     * This is a safe wrapper around Axios `.get` that:
-     * - Allows request customization through an optional `config`.
-     * - Logs request failures with contextual detail for easier troubleshooting.
-     * - Returns `undefined` instead of throwing, enabling graceful fallbacks in callers.
+     * Why this abstraction matters:
+     * - Prevents unhandled promise rejections by returning `undefined` on failure.
+     * - Allows optional per-request configuration without mutating the shared Axios instance.
      *
      * @template T
-     * @param {string} endpoint - The relative endpoint to request from the downstream service.
-     * @param {AxiosRequestConfig} [config={}] - Optional Axios request configuration.
-     *   Use this to pass custom headers, query parameters, authentication tokens,
-     *   or override default client behavior for this specific request.
-     * @returns {Promise<T | undefined>} A promise resolving to the resource of type `T`,
-     *   or `undefined` if the request fails.
+     * @param {string} endpoint - Relative path (e.g., `"/users/42"`).
+     * @param {AxiosRequestConfig} [config={}] - Optional request overrides (headers, params, etc.).
+     * @returns {Promise<T | undefined>} - The fetched resource, or `undefined` if the request fails.
      */
     protected fetchResource<T>(endpoint: string, config?: AxiosRequestConfig): Promise<T | undefined>;
     /**
-     * Fetches a collection of resources from the downstream service.
+     * Retrieves a collection of resources from the downstream service.
      *
-     * This is a safe wrapper around Axios `.get` that:
-     * - Allows request customization through an optional `config`.
-     * - Logs request failures with contextual detail for easier troubleshooting.
-     * - Returns `undefined` instead of throwing, enabling graceful fallbacks in callers.
+     * Handles cases where large sets of IDs need to be split into chunks
+     * to avoid exceeding query parameter length limits.
      *
      * @template T
-     * @param {string} endpoint - The relative endpoint to request from the downstream service.
-     * @param {AxiosRequestConfig} [config={}] - Optional Axios request configuration.
-     *   Use this to pass custom headers, query parameters, authentication tokens,
-     *   or override default client behavior for this specific request.
-     * @returns {Promise<T[]>} A promise resolving to an array of resources of type `T`,
-     *   or an empty array if the request fails.
+     * @param {string} endpoint - Relative API path.
+     * @param {AxiosRequestConfig} [config={}] - Optional request customization.
+     * @returns {Promise<T[]>} - Array of resources, or an empty array if all attempts fail.
      */
     protected fetchResourceCollection<T>(endpoint: string, config?: AxiosRequestConfig): Promise<T[]>;
+    /**
+     * Helper for fetching a batch (or full collection) of resources in a single request.
+     *
+     * Encapsulated separately to isolate retry/fallback behavior and keep
+     * the main collection method simpler.
+     *
+     * @template T
+     * @param {string} endpoint - Target API path.
+     * @param {AxiosRequestConfig} [config={}] - Optional request customization.
+     * @returns {Promise<T[]>} - List of retrieved resources or an empty array if failed.
+     */
+    private fetchResourceCollectionBatch;
 }

package/dist/modules/services/base-http.service.js

@@ -7,29 +7,29 @@ exports.BaseHttpService = void 0;
 const common_1 = require("@nestjs/common");
 const axios_1 = __importDefault(require("axios"));
 const class_validator_1 = require("class-validator");
+const itlab_functions_1 = require("itlab-functions");
 const service_auth_guard_1 = require("../authentication/guards/service-auth.guard");
 /**
  * BaseHttpService
  *
- * A strongly typed, structured wrapper around Axios that standardizes outbound HTTP calls.
+ * A structured, type-safe abstraction over Axios that standardizes outbound HTTP requests
+ * to other internal or external microservices.
  *
- * Core Responsibilities:
- * - Dynamically resolves internal vs external base URLs depending on environment.
- * - Injects Kubernetes service authentication tokens into every request.
- * - Adds structured logging for visibility into outbound traffic.
- *
- * Why use composition over inheritance with Axios?
- * - Axios is both callable and constructable, leading to TypeScript conflicts when extended.
- * - Wrapping avoids prototype traps, giving us full control over configuration and flow.
+ * ### Key Principles:
+ * - **Controlled Configuration:** Rather than subclassing Axios (which creates prototype issues),
+ *   this class wraps Axios to maintain predictable behavior across environments.
+ * - **Environment-Aware Routing:** Selects internal vs. external base URLs automatically based on environment.
+ * - **Secure Communication:** Injects a Kubernetes service token into every outbound request header.
+ * - **Operational Transparency:** Implements structured logging for observability of inter-service communication.
  */
 class BaseHttpService {
     /**
-     * Initializes a new HTTP service client tied to a specific downstream service.
+     * Constructs a base HTTP service instance configured for a downstream microservice.
      *
-     * @param {string} serviceName - Identifier used for contextual logging (e.g., `"Comments"`).
-     * @param {InternalExternalUrl} baseUrls - A tuple `[internalUrl, externalUrl]`. Production prefers internal.
-     * @param {AuthenticationModuleOptions} authenticationOptions - Authentication configuration containing Kubernetes token.
-     * @param {ConfigService} configService - NestJS config service used to resolve runtime environment.
+     * @param {string} serviceName - Name of the downstream service (used for contextualized logs).
+     * @param {InternalExternalUrl} baseUrls - Tuple `[internalUrl, externalUrl]`. In production, internal URLs are preferred for security and speed.
+     * @param {AuthenticationModuleOptions} authenticationOptions - Configuration containing Kubernetes token.
+     * @param {ConfigService} configService - NestJS configuration provider.
      */
     constructor(serviceName, baseUrls, authenticationOptions, configService) {
         this.serviceName = serviceName;
@@ -38,26 +38,28 @@ class BaseHttpService {
         this.configService = configService;
         this.logger = new common_1.Logger(`${this.serviceName}Service`);
         this.isProduction = this.configService.get('NODE_ENV') === 'production';
-        // Create a scoped Axios instance bound to the appropriate base URL.
-        this.client = axios_1.default.create({
+        // Initialize Axios with base URL dynamically selected per environment.
+        this.httpClient = axios_1.default.create({
             baseURL: this.baseUrls[this.isProduction ? 0 : 1],
             headers: {
-                // Always include internal Kubernetes token for downstream service authentication.
+                // Kubernetes internal authentication for secure service-to-service calls.
                 [service_auth_guard_1.SERVICE_AUTH_HEADER_KEY]: this.authenticationOptions.k8sToken,
             },
         });
-        // Attach request interceptor for consistent logging of all outgoing requests.
-        this.client.interceptors.request.use((config) => {
+        // Add a request interceptor to log outbound traffic before each request is sent.
+        this.httpClient.interceptors.request.use((config) => {
             var _a;
             this.logger.log(`${(_a = config.method) === null || _a === void 0 ? void 0 : _a.toUpperCase()} ${config.url}`);
             return config;
         });
     }
     /**
-     * Normalizes Axios error responses into a consistent object.
-     * Ensures structured error handling regardless of the downstream service implementation.
+     * Converts an Axios error into a structured and consistent error format.
+     *
+     * This allows downstream callers to rely on predictable error shapes,
+     * regardless of how the target service responds.
      *
-     * @param {any} error - Raw Axios error object.
+     * @param {any} error - Raw Axios error object from a failed request.
      * @returns {{ status: number; data: string | Record<string, any>; message: string }}
      */
     parseError(error) {
@@ -67,51 +69,74 @@ class BaseHttpService {
         return { status, data, message: (0, class_validator_1.isObject)(data) ? JSON.stringify(data) : String(data) };
     }
     /**
-     * Fetches a single resource from the downstream service.
+     * Retrieves a single resource from the downstream service.
      *
-     * This is a safe wrapper around Axios `.get` that:
-     * - Allows request customization through an optional `config`.
-     * - Logs request failures with contextual detail for easier troubleshooting.
-     * - Returns `undefined` instead of throwing, enabling graceful fallbacks in callers.
+     * Why this abstraction matters:
+     * - Prevents unhandled promise rejections by returning `undefined` on failure.
+     * - Allows optional per-request configuration without mutating the shared Axios instance.
      *
      * @template T
-     * @param {string} endpoint - The relative endpoint to request from the downstream service.
-     * @param {AxiosRequestConfig} [config={}] - Optional Axios request configuration.
-     *   Use this to pass custom headers, query parameters, authentication tokens,
-     *   or override default client behavior for this specific request.
-     * @returns {Promise<T | undefined>} A promise resolving to the resource of type `T`,
-     *   or `undefined` if the request fails.
+     * @param {string} endpoint - Relative path (e.g., `"/users/42"`).
+     * @param {AxiosRequestConfig} [config={}] - Optional request overrides (headers, params, etc.).
+     * @returns {Promise<T | undefined>} - The fetched resource, or `undefined` if the request fails.
      */
     async fetchResource(endpoint, config = {}) {
+        // Defensive cleanup: prevent leaking invalid `id` parameters to downstream services.
+        if (config.params) {
+            delete config.params.ids;
+            delete config.params.id;
+        }
         try {
-            const response = await this.client.get(endpoint, config);
+            const response = await this.httpClient.get(endpoint, config);
             return response.data;
         }
         catch (error) {
             const { message } = this.parseError(error);
-            this.logger.error(`Failed to fetch resource at endpoint "${endpoint}": ${message}. Config: ${JSON.stringify(config)}`);
+            this.logger.error(`Failed to fetch single resource from "${endpoint}": ${message}. Config: ${JSON.stringify(config)}`);
             return undefined;
         }
     }
     /**
-     * Fetches a collection of resources from the downstream service.
+     * Retrieves a collection of resources from the downstream service.
      *
-     * This is a safe wrapper around Axios `.get` that:
-     * - Allows request customization through an optional `config`.
-     * - Logs request failures with contextual detail for easier troubleshooting.
-     * - Returns `undefined` instead of throwing, enabling graceful fallbacks in callers.
+     * Handles cases where large sets of IDs need to be split into chunks
+     * to avoid exceeding query parameter length limits.
      *
      * @template T
-     * @param {string} endpoint - The relative endpoint to request from the downstream service.
-     * @param {AxiosRequestConfig} [config={}] - Optional Axios request configuration.
-     *   Use this to pass custom headers, query parameters, authentication tokens,
-     *   or override default client behavior for this specific request.
-     * @returns {Promise<T[]>} A promise resolving to an array of resources of type `T`,
-     *   or an empty array if the request fails.
+     * @param {string} endpoint - Relative API path.
+     * @param {AxiosRequestConfig} [config={}] - Optional request customization.
+     * @returns {Promise<T[]>} - Array of resources, or an empty array if all attempts fail.
      */
     async fetchResourceCollection(endpoint, config = {}) {
+        var _a;
+        const ids = (_a = config.params) === null || _a === void 0 ? void 0 : _a.ids;
+        if (!(ids && (0, class_validator_1.isArray)(ids) && ids.length > 50)) {
+            return this.fetchResourceCollectionBatch(endpoint, config);
+        }
+        // Deduplicate and chunk IDs to avoid overloading downstream query limits.
+        const uniqueIds = Array.from(new Set(ids));
+        const idChunks = (0, itlab_functions_1.createChunks)(uniqueIds, 50);
+        // Parallelize requests for each chunk; flatten the results into one array.
+        const batchPromises = idChunks.map((chunk) => {
+            config.params.ids = chunk;
+            return this.fetchResourceCollectionBatch(endpoint, config);
+        });
+        return (await Promise.all(batchPromises)).flat();
+    }
+    /**
+     * Helper for fetching a batch (or full collection) of resources in a single request.
+     *
+     * Encapsulated separately to isolate retry/fallback behavior and keep
+     * the main collection method simpler.
+     *
+     * @template T
+     * @param {string} endpoint - Target API path.
+     * @param {AxiosRequestConfig} [config={}] - Optional request customization.
+     * @returns {Promise<T[]>} - List of retrieved resources or an empty array if failed.
+     */
+    async fetchResourceCollectionBatch(endpoint, config = {}) {
         try {
-            const response = await this.client.get(endpoint, config);
+            const response = await this.httpClient.get(endpoint, config);
             return response.data;
         }
         catch (error) {

package/dist/modules/services/base-urls.d.ts

@@ -1,22 +1,25 @@
 export type InternalExternalUrl = [internalUrl: string, externalUrl: string];
 export declare class BaseUrls {
-    static get NewsroomService(): InternalExternalUrl;
-    static get EventsService(): InternalExternalUrl;
-    static get HackschoolService(): InternalExternalUrl;
-    static get DemoHiveService(): InternalExternalUrl;
-    static get TechRadarService(): InternalExternalUrl;
-    static get PodcastsService(): InternalExternalUrl;
-    static get BooksService(): InternalExternalUrl;
-    static get TeamService(): InternalExternalUrl;
-    static get NewsletterService(): InternalExternalUrl;
-    static get IdeasService(): InternalExternalUrl;
-    static get LunchRouletteService(): InternalExternalUrl;
-    static get AccountsService(): InternalExternalUrl;
-    static get CommentsService(): InternalExternalUrl;
-    static get NotificationService(): InternalExternalUrl;
-    static get MailService(): InternalExternalUrl;
-    static get SearchService(): InternalExternalUrl;
-    static get ChangelogService(): InternalExternalUrl;
-    static get PassService(): InternalExternalUrl;
-    static get ContentService(): InternalExternalUrl;
+    static get newsroomService(): InternalExternalUrl;
+    static get eventsService(): InternalExternalUrl;
+    static get hackschoolService(): InternalExternalUrl;
+    static get demoHiveService(): InternalExternalUrl;
+    static get techRadarService(): InternalExternalUrl;
+    static get podcastsService(): InternalExternalUrl;
+    static get booksService(): InternalExternalUrl;
+    static get teamService(): InternalExternalUrl;
+    static get newsletterService(): InternalExternalUrl;
+    static get ideasService(): InternalExternalUrl;
+    static get lunchRouletteService(): InternalExternalUrl;
+    static get filesService(): InternalExternalUrl;
+    static get quickLinksService(): InternalExternalUrl;
+    static get accountsService(): InternalExternalUrl;
+    static get commentsService(): InternalExternalUrl;
+    static get conflictsService(): InternalExternalUrl;
+    static get notificationsService(): InternalExternalUrl;
+    static get mailService(): InternalExternalUrl;
+    static get searchService(): InternalExternalUrl;
+    static get changelogService(): InternalExternalUrl;
+    static get passService(): InternalExternalUrl;
+    static get contentService(): InternalExternalUrl;
 }

package/dist/modules/services/base-urls.js

@@ -2,116 +2,135 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseUrls = void 0;
 class BaseUrls {
-    static get NewsroomService() {
+    static get newsroomService() {
         return [
             'http://organisation-hub-newsroom-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/newsroom/',
         ];
     }
-    static get EventsService() {
+    static get eventsService() {
         return [
             'http://organisation-hub-events-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/events/',
         ];
     }
-    static get HackschoolService() {
+    static get hackschoolService() {
         return [
             'http://organisation-hub-hackschool-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/hackschool/',
         ];
     }
-    static get DemoHiveService() {
+    static get demoHiveService() {
         return [
             'http://organisation-hub-demo-hive-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/demo-hive/',
         ];
     }
-    static get TechRadarService() {
+    static get techRadarService() {
         return [
             'http://organisation-hub-tech-radar-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/tech-radar/',
         ];
     }
-    static get PodcastsService() {
+    static get podcastsService() {
         return [
             'http://organisation-hub-podcasts-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/podcasts/',
         ];
     }
-    static get BooksService() {
+    static get booksService() {
         return [
             'http://organisation-hub-books-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/books/',
         ];
     }
-    static get TeamService() {
+    static get teamService() {
         return [
             'http://organisation-hub-team-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/team/',
         ];
     }
-    static get NewsletterService() {
+    static get newsletterService() {
         return [
             'http://organisation-hub-newsletter-backend.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/newsletter/',
         ];
     }
-    static get IdeasService() {
+    static get ideasService() {
         return [
             'http://organisation-hub-ideas-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/ideas/',
         ];
     }
-    static get LunchRouletteService() {
+    static get lunchRouletteService() {
         return [
             'http://project-lunch-roulette-backend.project-lunch-roulette.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/lunch-roulette/',
         ];
     }
+    // Services
+    static get filesService() {
+        return [
+            'http://organisation-hub-files-service.organisation-hub-services.svc.cluster.local:3000/',
+            'https://services.svi-itlab.com/files/',
+        ];
+    }
+    static get quickLinksService() {
+        return [
+            'http://organisation-hub-quick-links-service.organisation-hub-services.svc.cluster.local:3000/',
+            'https://services.svi-itlab.com/quick-links/',
+        ];
+    }
     // Utils
-    static get AccountsService() {
+    static get accountsService() {
         return [
             'http://organisation-hub-accounts-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/accounts/',
         ];
     }
-    static get CommentsService() {
+    static get commentsService() {
         return [
             'http://organisation-hub-comments-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/comments/',
         ];
     }
-    static get NotificationService() {
+    static get conflictsService() {
+        return [
+            'http://organisation-hub-conflicts-service.organisation-hub-services.svc.cluster.local:3000/',
+            'https://services.svi-itlab.com/conflicts/',
+        ];
+    }
+    static get notificationsService() {
         return [
             'http://organisation-hub-notifications-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/notifications/',
         ];
     }
-    static get MailService() {
+    static get mailService() {
         return [
             'http://organisation-hub-email-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/email/',
         ];
     }
-    static get SearchService() {
+    static get searchService() {
         return [
             'http://organisation-hub-search-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/search/',
         ];
     }
-    static get ChangelogService() {
+    static get changelogService() {
         return [
             'http://organisation-hub-changelog-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/changelog/',
         ];
     }
-    static get PassService() {
+    static get passService() {
         return [
             'http://organisation-hub-pass-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/pass/',
         ];
     }
-    static get ContentService() {
+    static get contentService() {
         return [
             'http://organisation-hub-content-service.organisation-hub-services.svc.cluster.local:3000/',
             'https://services.svi-itlab.com/content/',

package/dist/modules/services/providers/accounts/accounts.service.d.ts

@@ -0,0 +1,99 @@
+import { ConfigService } from '@nestjs/config';
+import { EntityMap } from '../../../../classes';
+import { Account, User } from '../../../../models';
+import { AuthenticationModuleOptions } from '../../../authentication';
+import { BaseHttpService } from '../../base-http.service';
+import { FetchAccountOptionsDtoV1 } from './fetch-account-options.dto.v1.type';
+/**
+ * AccountsService
+ *
+ * Service client responsible for interacting with the Accounts microservice.
+ * Extends `BaseHttpService` to inherit:
+ * - Environment-sensitive URL resolution (internal vs. external).
+ * - Secure inter-service authentication.
+ * - Structured logging for traceability of outbound requests.
+ *
+ * Why this pattern?
+ * - Ensures all outbound calls follow a unified configuration and logging structure.
+ * - Promotes strong typing and maintainable HTTP logic.
+ * - Makes service interactions predictable and debuggable across environments.
+ */
+export declare class AccountsService extends BaseHttpService {
+    /**
+     * Constructs an Accounts service client instance.
+     *
+     * @param {AuthenticationModuleOptions} authenticationOptions - Injected authentication configuration.
+     * @param {ConfigService} configService - NestJS ConfigService for environment detection.
+     */
+    constructor(authenticationOptions: AuthenticationModuleOptions, configService: ConfigService);
+    /**
+     * Retrieves a single account entry by its MongoDB identifier.
+     *
+     * This method gracefully handles downstream failures by logging
+     * and returning `undefined` instead of throwing.
+     *
+     * @param {string} accountId - Unique MongoDB identifier of the account.
+     * @param {FetchAccountOptionsDtoV1} [options] - Optional query parameters for filtering or projection.
+     * @returns {Promise<Account | undefined>} Resolves to an Account or `undefined` on failure.
+     */
+    fetchAccountV1(accountId: string, options?: FetchAccountOptionsDtoV1): Promise<Account | undefined>;
+    /**
+     * Retrieves a collection of account entries.
+     *
+     * Useful for batch lookups or paginated listings.
+     * Returns an empty array if the downstream service call fails.
+     *
+     * @param {FetchAccountOptionsDtoV1} [options] - Optional filter options for narrowing results.
+     * @returns {Promise<Account[]>} Resolves to a list of accounts, or an empty array if none found.
+     */
+    fetchAccountCollectionV1(options?: FetchAccountOptionsDtoV1): Promise<Account[]>;
+    /**
+     * Fetches accounts for multiple groups of account IDs and returns a mapped result.
+     *
+     * This is particularly useful when aggregating accounts related to different entities
+     * (e.g., post authors, commenters, likedBy lists).
+     *
+     * The function ensures:
+     * - Each unique account is fetched only once.
+     * - The result is returned as an `EntityMap` for O(1) lookups.
+     *
+     * @param {string[][]} accountIdGroups - Nested arrays of account IDs.
+     * @returns {Promise<EntityMap<Account>>} Map of accountId → Account entity.
+     */
+    fetchAccountMapV1(accountIdGroups: string[][]): Promise<EntityMap<Account>>;
+    /**
+     * Retrieves a single user entry by its MongoDB identifier.
+     *
+     * This method gracefully handles downstream failures by logging
+     * and returning `undefined` instead of throwing.
+     *
+     * @param {string} userId - Unique MongoDB identifier of the user.
+     * @param {FetchAccountOptionsDtoV1} [options] - Optional query parameters for filtering or projection.
+     * @returns {Promise<User | undefined>} Resolves to an User or `undefined` on failure.
+     */
+    fetchUserV1(userId: string, options?: FetchAccountOptionsDtoV1): Promise<User | undefined>;
+    /**
+     * Retrieves a collection of user entries.
+     *
+     * Useful for batch lookups or paginated listings.
+     * Returns an empty array if the downstream service call fails.
+     *
+     * @param {FetchAccountOptionsDtoV1} [options] - Optional filter options for narrowing results.
+     * @returns {Promise<User[]>} Resolves to a list of users, or an empty array if none found.
+     */
+    fetchUserCollectionV1(options?: FetchAccountOptionsDtoV1): Promise<User[]>;
+    /**
+     * Fetches users for multiple groups of user IDs and returns a mapped result.
+     *
+     * This is particularly useful when aggregating users related to different entities
+     * (e.g., post authors, commenters, likedBy lists).
+     *
+     * The function ensures:
+     * - Each unique user is fetched only once.
+     * - The result is returned as an `EntityMap` for O(1) lookups.
+     *
+     * @param {string[][]} userIdGroups - Nested arrays of user IDs.
+     * @returns {Promise<EntityMap<User>>} Map of userId → User entity.
+     */
+    fetchUserMapV1(userIdGroups: string[][]): Promise<EntityMap<User>>;
+}