@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/pipeline/pipeline-builder.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Pipeline builder for Express middleware chains.
+ * Provides fluent API for building middleware pipelines.
+ * @module pipeline/pipeline-builder
+ */
+
+import { RequestHandler } from 'express';
+
+/**
+ * Builder for creating Express middleware pipelines.
+ */
+export class Pipeline {
+  private middleware: RequestHandler[] = [];
+
+  static create(): Pipeline {
+    return new Pipeline();
+  }
+
+  use(handler: RequestHandler): this {
+    this.middleware.push(handler);
+    return this;
+  }
+
+  build(): RequestHandler[] {
+    return this.middleware;
+  }
+}

package/src/plugins/{index.d.ts → index.ts}

@@ -1,3 +1,2 @@
 export * from './plugin-interface';
 export * from './plugin-manager';
-//# sourceMappingURL=index.d.ts.map

package/src/plugins/plugin-interface.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Application plugin interface.
+ * Defines contract for application plugins.
+ * @module plugins/plugin-interface
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IApplication } from '../interfaces/application';
+
+/**
+ * Interface for application plugins.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export interface IApplicationPlugin<TID extends PlatformID = Buffer> {
+  readonly name: string;
+  readonly version?: string;
+  init(app: IApplication<TID>): Promise<void>;
+  stop?(): Promise<void>;
+}

package/src/plugins/plugin-manager.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Plugin manager for application plugins.
+ * Manages registration and lifecycle of application plugins.
+ * @module plugins/plugin-manager
+ */
+
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IApplication } from '../interfaces/application';
+import { IApplicationPlugin } from './plugin-interface';
+
+/**
+ * Manager for application plugins.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export class PluginManager<TID extends PlatformID = Buffer> {
+  private plugins = new Map<string, IApplicationPlugin<TID>>();
+  private initialized = false;
+
+  register(plugin: IApplicationPlugin<TID>): void {
+    if (this.initialized) {
+      throw new Error(
+        `Cannot register plugin ${plugin.name} after initialization`,
+      );
+    }
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin ${plugin.name} already registered`);
+    }
+    this.plugins.set(plugin.name, plugin);
+  }
+
+  async initAll(app: IApplication<TID>): Promise<void> {
+    for (const plugin of this.plugins.values()) {
+      await plugin.init(app);
+    }
+    this.initialized = true;
+  }
+
+  async stopAll(): Promise<void> {
+    for (const plugin of this.plugins.values()) {
+      if (plugin.stop) {
+        await plugin.stop();
+      }
+    }
+  }
+
+  get(name: string): IApplicationPlugin<TID> | undefined {
+    return this.plugins.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+}

package/src/registry/email-service-registry.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Email service registry singleton.
+ * Manages email service registration and retrieval.
+ * @module registry/email-service-registry
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { IEmailService } from '../interfaces/email-service';
+
+/**
+ * Singleton registry for email service.
+ */
+class EmailServiceRegistry {
+  private service?: IEmailService;
+
+  /**
+   * Registers an email service.
+   * @param {IEmailService} service - Email service implementation
+   */
+  setService(service: IEmailService): void {
+    this.service = service;
+  }
+
+  /**
+   * Retrieves the registered email service.
+   * @returns {IEmailService} Email service instance
+   * @throws {TranslatableSuiteError} If no service is registered
+   */
+  getService(): IEmailService {
+    if (!this.service) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_EmailService_NotConfigured,
+      );
+    }
+    return this.service;
+  }
+
+  /**
+   * Check if any email service is registered.
+   * @returns {boolean} True if service is registered
+   */
+  hasService(): boolean {
+    return this.service !== undefined;
+  }
+
+  /**
+   * Check if the registered service is an instance of a specific class.
+   * @template T - Email service type
+   * @param {Function} serviceClass - The class/constructor to check against
+   * @returns {boolean} True if the registered service is an instance of the given class
+   * @example
+   * emailServiceRegistry.isServiceType(EmailService) // true if EmailService is registered
+   * emailServiceRegistry.isServiceType(DummyEmailService) // true if DummyEmailService is registered
+   */
+  isServiceType<T extends IEmailService>(
+    serviceClass: new (...args: any[]) => T,
+  ): boolean {
+    return this.service !== undefined && this.service instanceof serviceClass;
+  }
+
+  /**
+   * Get the constructor name of the registered service.
+   * @returns {string | undefined} The name of the service class, or undefined if no service is registered
+   */
+  getServiceTypeName(): string | undefined {
+    return this.service?.constructor.name;
+  }
+}
+
+/**
+ * Singleton instance of EmailServiceRegistry.
+ */
+export const emailServiceRegistry = new EmailServiceRegistry();

package/src/registry/{index.d.ts → index.ts}

@@ -1,2 +1 @@
 export { emailServiceRegistry } from './email-service-registry';
-//# sourceMappingURL=index.d.ts.map

package/src/responses/{index.d.ts → index.ts}

@@ -1,2 +1 @@
 export * from './response-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/responses/response-builder.ts

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Response builder for API responses.
+ * Provides fluent API for building HTTP responses with status codes.
+ * @module responses/response-builder
+ */
+
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { IStatusCodeResponse } from '../interfaces';
+import { ApiResponse } from '../types';
+
+/**
+ * Builder for constructing API responses with fluent interface.
+ * @template T - Response type extending ApiResponse
+ */
+export class ResponseBuilder<T extends ApiResponse = ApiResponse> {
+  private statusCode: number = 200;
+  private responseData: Partial<T> = {};
+  private responseHeaders?: Record<string, string>;
+
+  /**
+   * Creates a 200 OK response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static ok<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(200);
+  }
+
+  /**
+   * Creates a 201 Created response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static created<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(201);
+  }
+
+  /**
+   * Creates a 202 Accepted response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static accepted<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(202);
+  }
+
+  /**
+   * Creates a 204 No Content response builder.
+   * @returns {ResponseBuilder<ApiResponse>} Response builder instance
+   */
+  static noContent(): ResponseBuilder<ApiResponse> {
+    return new ResponseBuilder<ApiResponse>().status(204);
+  }
+
+  /**
+   * Creates a 400 Bad Request response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static badRequest<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(400);
+  }
+
+  /**
+   * Creates a 401 Unauthorized response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static unauthorized<
+    T extends ApiResponse = ApiResponse,
+  >(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(401);
+  }
+
+  /**
+   * Creates a 403 Forbidden response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static forbidden<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(403);
+  }
+
+  /**
+   * Creates a 404 Not Found response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static notFound<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(404);
+  }
+
+  /**
+   * Creates a 500 Internal Server Error response builder.
+   * @template T - Response type
+   * @returns {ResponseBuilder<T>} Response builder instance
+   */
+  static error<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(500);
+  }
+
+  /**
+   * Sets the HTTP status code.
+   * @param {number} code - HTTP status code
+   * @returns {this} This builder instance for chaining
+   */
+  status(code: number): this {
+    this.statusCode = code;
+    return this;
+  }
+
+  /**
+   * Sets a translatable message on the response.
+   * @param {SuiteCoreStringKey} key - Translation key
+   * @param {Record<string, string>} [params] - Translation parameters
+   * @param {string} [language] - Target language
+   * @returns {this} This builder instance for chaining
+   */
+  message(
+    key: SuiteCoreStringKey,
+    params?: Record<string, string>,
+    language?: string,
+  ): this {
+    (this.responseData as T & { message?: string }).message =
+      getSuiteCoreTranslation(key, params, language as CoreLanguageCode);
+    return this;
+  }
+
+  /**
+   * Sets response data.
+   * @param {Partial<T>} data - Response data to merge
+   * @returns {this} This builder instance for chaining
+   */
+  data(data: Partial<T>): this {
+    this.responseData = { ...this.responseData, ...data };
+    return this;
+  }
+
+  /**
+   * Sets response headers.
+   * @param {Record<string, string>} headers - HTTP headers
+   * @returns {this} This builder instance for chaining
+   */
+  headers(headers: Record<string, string>): this {
+    this.responseHeaders = headers;
+    return this;
+  }
+
+  /**
+   * Builds the final response object.
+   * @returns {IStatusCodeResponse<T>} Complete response with status code and headers
+   */
+  build(): IStatusCodeResponse<T> {
+    return {
+      statusCode: this.statusCode,
+      response: this.responseData as T,
+      ...(this.responseHeaders ? { headers: this.responseHeaders } : {}),
+    };
+  }
+}
+
+export const Response = ResponseBuilder;

package/src/routers/api.ts

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview API router configuration with dependency injection and service registration.
+ * Manages user controller and all required services for API endpoints.
+ * @module routers/api
+ */
+
+import { IECIESConfig } from '@digitaldefiance/ecies-lib';
+import { ECIESService, PlatformID } from '@digitaldefiance/node-ecies-lib';
+import {
+  ITokenRole,
+  ITokenUser,
+  IUserBase,
+} from '@digitaldefiance/suite-core-lib';
+import { ServiceKeys } from '../container';
+import { UserController } from '../controllers/user';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+import { IApplication } from '../interfaces/application';
+import { IEmailService } from '../interfaces/email-service';
+import { emailServiceRegistry } from '../registry';
+import { BackupCodeService } from '../services/backup-code';
+import { JwtService } from '../services/jwt';
+import { KeyWrappingService } from '../services/key-wrapping';
+import { RoleService } from '../services/role';
+import { UserService } from '../services/user';
+import { BaseRouter } from './base';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+
+/**
+ * Router for the API endpoints.
+ * Manages user controller and registers all required services via dependency injection.
+ * @template TID Platform-specific ID type
+ * @template TDate Date type
+ * @template TLanguage Site language string literal type
+ * @template TAccountStatus Account status string literal type
+ * @template TUser User base type
+ * @template TTokenRole Token role type
+ * @template TBaseDocument Base document type
+ * @template TTokenUser Token user type
+ * @template TConstants Constants type
+ * @template TEnvironment Environment type
+ * @template TApplication Application type
+ */
+export class ApiRouter<
+  TID extends PlatformID,
+  TDate extends Date,
+  TLanguage extends CoreLanguageCode,
+  TAccountStatus extends string,
+  TUser extends IUserBase<TID, TDate, TLanguage, TAccountStatus> = IUserBase<
+    TID,
+    TDate,
+    TLanguage,
+    TAccountStatus
+  >,
+  TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>,
+  TBaseDocument extends IBaseDocument<any, TID> = IBaseDocument<any, TID>,
+  TTokenUser extends ITokenUser = ITokenUser,
+  TConstants extends IConstants = IConstants,
+  TEnvironment extends Environment<TID> = Environment<TID>,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> extends BaseRouter<TID, TApplication> {
+  /** User controller for handling user-related API endpoints */
+  private readonly userController: UserController<
+    TID,
+    TDate,
+    TLanguage,
+    TAccountStatus,
+    TUser,
+    TTokenRole,
+    TTokenUser,
+    TApplication
+  >;
+  /** JWT service for token generation and validation */
+  private readonly jwtService: JwtService<
+    TID,
+    TDate,
+    TTokenRole,
+    TTokenUser,
+    TApplication
+  >;
+  /** Email service for sending emails */
+  private readonly emailService: IEmailService;
+  /** User service for user management operations */
+  private readonly userService: UserService<
+    any,
+    TID,
+    TDate,
+    TLanguage,
+    TAccountStatus,
+    TEnvironment,
+    TConstants,
+    TBaseDocument,
+    TUser,
+    TTokenRole,
+    TApplication
+  >;
+  /** Role service for role management operations */
+  private readonly roleService: RoleService<TID, TDate, TTokenRole>;
+  /** Key wrapping service for password-based encryption */
+  private readonly keyWrappingService: KeyWrappingService;
+  /** ECIES service for elliptic curve encryption */
+  private readonly eciesService: ECIESService<TID>;
+  /** Backup code service for generating and validating backup codes */
+  private readonly backupCodeService: BackupCodeService<
+    TID,
+    TDate,
+    TTokenRole,
+    TApplication
+  >;
+  /**
+   * Creates a new API router instance.
+   * Registers all required services and initializes the user controller.
+   * @param application Application instance with database connection and configuration
+   */
+  constructor(application: TApplication) {
+    super(application);
+    this.registerServices();
+    this.jwtService = application.services.get(ServiceKeys.JWT);
+    this.roleService = application.services.get(ServiceKeys.ROLE);
+    this.emailService = application.services.get(ServiceKeys.EMAIL);
+    this.keyWrappingService = application.services.get(
+      ServiceKeys.KEY_WRAPPING,
+    );
+    this.eciesService = application.services.get(ServiceKeys.ECIES);
+    this.backupCodeService = application.services.get(ServiceKeys.BACKUP_CODE);
+    this.userService = application.services.get(ServiceKeys.USER);
+    this.userController = new UserController<
+      TID,
+      TDate,
+      TLanguage,
+      TAccountStatus,
+      TUser,
+      TTokenRole,
+      TTokenUser,
+      TApplication
+    >(
+      application,
+      this.jwtService,
+      this.userService,
+      this.backupCodeService,
+      this.roleService,
+      this.eciesService,
+    );
+    this.router.use('/user', this.userController.router);
+  }
+
+  /**
+   * Registers all required services in the application service container.
+   * Services are registered as singletons and lazily instantiated.
+   * @private
+   */
+  private registerServices(): void {
+    const app = this.application;
+
+    if (!app.services.has(ServiceKeys.JWT)) {
+      app.services.register(
+        ServiceKeys.JWT,
+        () =>
+          new JwtService<TID, TDate, TTokenRole, TTokenUser, TApplication>(app),
+      );
+    }
+    if (!app.services.has(ServiceKeys.ROLE)) {
+      app.services.register(
+        ServiceKeys.ROLE,
+        () => new RoleService<TID, TDate, TTokenRole>(app),
+      );
+    }
+    if (!app.services.has(ServiceKeys.EMAIL)) {
+      app.services.register(ServiceKeys.EMAIL, () =>
+        emailServiceRegistry.getService(),
+      );
+    }
+    if (!app.services.has(ServiceKeys.KEY_WRAPPING)) {
+      app.services.register(
+        ServiceKeys.KEY_WRAPPING,
+        () => new KeyWrappingService(),
+      );
+    }
+    if (!app.services.has(ServiceKeys.ECIES)) {
+      app.services.register(ServiceKeys.ECIES, () => {
+        const config: IECIESConfig = {
+          curveName: app.constants.ECIES.CURVE_NAME,
+          primaryKeyDerivationPath:
+            app.constants.ECIES.PRIMARY_KEY_DERIVATION_PATH,
+          mnemonicStrength: app.constants.ECIES.MNEMONIC_STRENGTH,
+          symmetricAlgorithm:
+            app.constants.ECIES.SYMMETRIC_ALGORITHM_CONFIGURATION,
+          symmetricKeyBits: app.constants.ECIES.SYMMETRIC.KEY_BITS,
+          symmetricKeyMode: app.constants.ECIES.SYMMETRIC.MODE,
+        };
+        return new ECIESService(config);
+      });
+    }
+    if (!app.services.has(ServiceKeys.BACKUP_CODE)) {
+      app.services.register(
+        ServiceKeys.BACKUP_CODE,
+        () =>
+          new BackupCodeService<TID, TDate, TTokenRole, TApplication>(
+            app,
+            app.services.get(ServiceKeys.ECIES),
+            app.services.get(ServiceKeys.KEY_WRAPPING),
+            app.services.get(ServiceKeys.ROLE),
+          ),
+      );
+    }
+    if (!app.services.has(ServiceKeys.USER)) {
+      app.services.register(
+        ServiceKeys.USER,
+        () =>
+          new UserService<
+            any,
+            TID,
+            TDate,
+            TLanguage,
+            TAccountStatus,
+            TEnvironment,
+            TConstants,
+            TBaseDocument,
+            TUser,
+            TTokenRole,
+            TApplication
+          >(
+            app,
+            app.services.get(ServiceKeys.ROLE),
+            app.services.get(ServiceKeys.EMAIL),
+            app.services.get(ServiceKeys.KEY_WRAPPING),
+            app.services.get(ServiceKeys.BACKUP_CODE),
+          ),
+      );
+    }
+  }
+}