@digitaldefiance/express-suite-starter 3.0.3 → 4.20.0

package/scaffolding/api-lib-brightstack/src/lib/routers/api.ts

@@ -0,0 +1,164 @@
+import {
+  DecoratorBaseController,
+  ApiController,
+  Get,
+  RequireAuth,
+  Public,
+  ApiTags,
+  ApiSummary,
+  ApiDescription,
+  Returns,
+  Param,
+  Query,
+  Paginated,
+  IApplication,
+} from '@digitaldefiance/node-express-suite';
+import { ITokenRole, ITokenUser, IUserBase } from '@digitaldefiance/suite-core-lib';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces/constants';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+
+/**
+ * CustomApiController - Example decorator-based API controller.
+ *
+ * This controller demonstrates the recommended decorator-based approach for
+ * building custom Express API endpoints with @digitaldefiance/node-express-suite.
+ *
+ * Note: The main user authentication routes (/api/user/*) are provided by the
+ * library's ApiRouter which is configured in application.ts. This controller
+ * is for adding your own custom API endpoints.
+ *
+ * Features demonstrated:
+ * - @ApiController for controller registration and OpenAPI metadata
+ * - @Get, @Post, @Put, @Delete for HTTP method routing
+ * - @RequireAuth and @Public for authentication control
+ * - @ApiTags, @ApiSummary, @ApiDescription for OpenAPI documentation
+ * - @Returns for response documentation
+ * - @Param, @Query for parameter injection
+ * - @Paginated for pagination support
+ *
+ * To use this controller, mount it on your application's router in application.ts:
+ * ```typescript
+ * // In your Application class constructor, after creating the LibraryApiRouter:
+ * const customController = new CustomApiController(app);
+ * apiRouter.router.use('/custom', customController.router);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Create your own controller by extending DecoratorBaseController
+ * @ApiTags('Users')
+ * @ApiController('/api/users', { description: 'User management endpoints' })
+ * class UserController extends DecoratorBaseController {
+ *   constructor(app: IApplication) {
+ *     super(app);
+ *   }
+ *
+ *   @Public()
+ *   @ApiSummary('Get user by ID')
+ *   @Returns(200, 'User', { description: 'User found' })
+ *   @Returns(404, 'ErrorResponse', { description: 'User not found' })
+ *   @Get('/:id')
+ *   async getUser(@Param('id') id: string) {
+ *     // Your implementation here
+ *   }
+ * }
+ * ```
+ */
+@ApiTags('Custom')
+@ApiController('/custom', {
+  description: 'Custom API endpoints - add your own routes here',
+})
+@RequireAuth()
+export class CustomApiController<
+  TID extends PlatformID = PlatformID,
+  TDate extends Date = Date,
+  TLanguage extends CoreLanguageCode = CoreLanguageCode,
+  TAccountStatus extends string = string,
+  TUser extends IUserBase<TID, TDate, TLanguage, TAccountStatus> = IUserBase<TID, TDate, TLanguage, TAccountStatus>,
+  TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>,
+  TTokenUser extends ITokenUser = ITokenUser,
+  TEnvironment extends Environment<TID> = Environment<TID>,
+  TConstants extends IConstants = IConstants,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> extends DecoratorBaseController<TLanguage, TID> {
+  constructor(app: TApplication) {
+    super(app);
+  }
+
+  /**
+   * Health check endpoint.
+   * Returns the current server status.
+   */
+  @Public()
+  @ApiSummary('Health check')
+  @ApiDescription('Returns the current server health status')
+  @Returns(200, 'HealthResponse', { description: 'Server is healthy' })
+  @Get('/health')
+  async healthCheck() {
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Example paginated list endpoint.
+   * Demonstrates pagination with query parameter injection.
+   */
+  @Public()
+  @Paginated({ defaultPageSize: 20, maxPageSize: 100 })
+  @ApiSummary('List items')
+  @ApiDescription('Returns a paginated list of items')
+  @Returns(200, 'ItemList', { description: 'List of items' })
+  @Get('/items')
+  async listItems(
+    @Query('page') page: number = 1,
+    @Query('limit') limit: number = 20,
+  ) {
+    // Example implementation - replace with your actual logic
+    return {
+      items: [],
+      total: 0,
+      page,
+      pageSize: limit,
+    };
+  }
+
+  /**
+   * Example get by ID endpoint.
+   * Demonstrates path parameter injection.
+   */
+  @Public()
+  @ApiSummary('Get item by ID')
+  @ApiDescription('Returns a single item by its ID')
+  @Returns(200, 'Item', { description: 'Item found' })
+  @Returns(404, 'ErrorResponse', { description: 'Item not found' })
+  @Get('/items/:id')
+  async getItem(@Param('id') id: string) {
+    // Example implementation - replace with your actual logic
+    return {
+      id,
+      name: 'Example Item',
+      createdAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Example authenticated endpoint.
+   * Requires JWT authentication (inherited from class-level @RequireAuth).
+   */
+  @ApiSummary('Get current user profile')
+  @ApiDescription('Returns the authenticated user profile')
+  @Returns(200, 'UserProfile', { description: 'User profile' })
+  @Returns(401, 'ErrorResponse', { description: 'Unauthorized' })
+  @Get('/profile')
+  async getProfile() {
+    // Access authenticated user via this.req.user
+    return {
+      message: 'Authenticated endpoint',
+      // user: this.req.user,
+    };
+  }
+}

package/scaffolding/api-lib-brightstack/src/lib/routers/app.ts

@@ -0,0 +1,32 @@
+import { AppRouter as BaseAppRouter, BaseRouter, IApplication } from '@digitaldefiance/node-express-suite';
+import { Request, Response, NextFunction } from 'express';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces/constants';
+import { Constants } from '../constants';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+export class AppRouter extends BaseAppRouter<PlatformID, IApplication<PlatformID>> {
+  constructor(apiRouter: BaseRouter<PlatformID, IApplication<PlatformID>>) {
+    super(apiRouter);
+  }
+
+  public override renderIndex(req: Request, res: Response, next: NextFunction): void {
+    if (req.url.endsWith('.js')) {
+      res.type('application/javascript');
+    }
+
+    const jsFile = this.getAssetFilename(this.assetsDir, /^index-.*\.js$/);
+    const cssFile = this.getAssetFilename(this.assetsDir, /^index-.*\.css$/);
+    const constants = this.application.constants as IConstants;
+    const environment = this.application.environment as Environment<PlatformID>;
+    const SiteName = constants.Site;
+    const locals = {
+      ...this.getBaseViewLocals(req, res),
+      title: SiteName,
+      jsFile: jsFile ? `assets/${jsFile}` : undefined,
+      cssFile: cssFile ? `assets/${cssFile}` : undefined,
+    };
+
+    this.renderTemplate(req, res, next, 'index', locals);
+  }
+}

package/scaffolding/api-lib-brightstack/src/lib/routers/base.ts

@@ -0,0 +1,22 @@
+import {
+  BaseRouter,
+  IApplication,
+} from '@digitaldefiance/node-express-suite';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Concrete API router for BrightStack applications.
+ *
+ * Extends the abstract BaseRouter from @digitaldefiance/node-express-suite
+ * to provide a concrete router that can be instantiated without Mongoose
+ * dependencies. Mount decorator-based controllers on this router for
+ * custom API endpoints.
+ */
+export class ApiRouter<
+  TID extends PlatformID = PlatformID,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> extends BaseRouter<TID, TApplication> {
+  constructor(application: TApplication) {
+    super(application);
+  }
+}

package/scaffolding/api-lib-brightstack/src/lib/routers/index.ts

@@ -0,0 +1,2 @@
+export * from './app';
+export * from './base';

package/scaffolding/api-lib-brightstack/src/lib/schemas/index.ts

@@ -0,0 +1,2 @@
+export * from './schema';
+export * from './user';

package/scaffolding/api-lib-brightstack/src/lib/schemas/schema.ts

@@ -0,0 +1,28 @@
+import {
+  IBlockStorageSchemaEntry,
+  SchemaMap,
+} from '@brightchain/node-express-suite';
+import { UserSchema } from './user';
+import { IConstants } from '../interfaces/constants';
+import { Constants } from '../constants';
+
+/**
+ * Returns the BrightDB schema map for all collections.
+ *
+ * Unlike the MERN variant which creates Mongoose models via connection.model(),
+ * BrightDB uses declarative schema entries that describe the collection structure.
+ * The BrightDbDatabasePlugin uses this map to initialize collections.
+ */
+export function getSchemaMap(constants: IConstants = Constants): SchemaMap {
+  return {
+    User: {
+      collection: 'users',
+      model: {
+        modelName: 'User',
+        schema: UserSchema,
+      },
+      modelName: 'User',
+      schema: UserSchema,
+    },
+  };
+}

package/scaffolding/api-lib-brightstack/src/lib/schemas/user.ts

@@ -0,0 +1,26 @@
+import { IBlockStorageSchema } from '@brightchain/node-express-suite';
+import { IUserDocument } from '../documents';
+
+/**
+ * BrightDB schema definition for User documents.
+ *
+ * Unlike the MERN variant which uses Mongoose Schema with validators and hooks,
+ * BrightDB schemas are declarative field definitions used by the block storage layer.
+ */
+export const UserSchema: IBlockStorageSchema<IUserDocument> = {
+  name: 'User',
+  fields: {
+    name: { type: 'string', required: true },
+    email: { type: 'string', required: true },
+    passwordHash: { type: 'string', required: true },
+    language: { type: 'string', required: true },
+    accountStatus: { type: 'string', required: true },
+    roles: { type: 'array', required: false },
+    createdAt: { type: 'date', required: false },
+    updatedAt: { type: 'date', required: false },
+  },
+  indexes: [
+    { fields: { email: 1 }, options: { unique: true } },
+    { fields: { name: 1 } },
+  ],
+};

package/scaffolding/api-lib-brightstack/src/lib/services/email.ts

@@ -0,0 +1,108 @@
+import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
+import { IApplication } from '@digitaldefiance/node-express-suite';
+
+// Simple debugLog implementation
+function debugLog(debug: boolean, type: 'log' | 'warn' | 'error', ...args: any[]): void {
+  if (debug) {
+    console[type](...args);
+  }
+}
+import { Environment } from '../environment';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * A generic service for sending emails using Amazon SES.
+ */
+export class EmailService<TID extends PlatformID> {
+  private readonly sesClient: SESClient;
+  private readonly emailSender: string;
+  private readonly disableEmailSend: boolean;
+  private readonly debug: boolean;
+  private readonly application: IApplication<TID>;
+
+  /**
+   * Constructs an instance of EmailService.
+   * @param config Configuration object containing AWS credentials, region, sender email, and debug/disable flags.
+   */
+  constructor(application: IApplication<TID>) {
+    this.application = application;
+    const environment = application.environment as Environment<TID>;
+    this.emailSender = environment.emailSender;
+    this.disableEmailSend = environment.disableEmailSend;
+    this.debug = environment.debug;
+
+    // Initialize the SES client with provided AWS credentials and region.
+    this.sesClient = new SESClient({
+      region: environment.aws.region,
+      credentials: {
+        accessKeyId: environment.aws.accessKeyId.value ?? '',
+        secretAccessKey:
+          environment.aws.secretAccessKey.value ?? '',
+      },
+    });
+  }
+
+  /**
+   * Sends an email using Amazon SES.
+   * @param to The recipient's email address.
+   * @param subject The subject line of the email.
+   * @param text The plain text body of the email.
+   * @param html The HTML body of the email.
+   * @returns A Promise that resolves when the email is sent successfully, or rejects on failure.
+   * @throws Error if email sending is disabled or if SES encounters an error.
+   */
+  public async sendEmail(
+    to: string,
+    subject: string,
+    text: string,
+    html: string,
+  ): Promise<void> {
+    if (this.disableEmailSend) {
+      debugLog(
+        this.debug,
+        'log',
+        `Email sending disabled for: ${to} - Subject: ${subject}`,
+      );
+      return;
+    }
+
+    const sendCommand = new SendEmailCommand({
+      Destination: {
+        ToAddresses: [to], // Recipient email address
+      },
+      Message: {
+        Body: {
+          Html: {
+            Charset: 'UTF-8',
+            Data: html, // HTML content of the email
+          },
+          Text: {
+            Charset: 'UTF-8',
+            Data: text, // Plain text content of the email
+          },
+        },
+        Subject: {
+          Charset: 'UTF-8',
+          Data: subject, // Subject of the email
+        },
+      },
+      Source: this.emailSender, // Sender email address (must be verified in SES)
+    });
+
+    try {
+      await this.sesClient.send(sendCommand);
+      debugLog(
+        this.debug,
+        'log',
+        `Email sent successfully to ${to} with subject: ${subject}`,
+      );
+    } catch (error) {
+      console.error(`Failed to send email to ${to}:`, error);
+      throw new Error(
+        `Failed to send email: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+}

package/scaffolding/api-lib-brightstack/src/lib/shared-types.ts

@@ -0,0 +1,149 @@
+import { NextFunction, Request, RequestHandler, Response } from 'express';
+import { ValidationChain } from 'express-validator';
+import { Brand } from 'ts-brand';
+import type { IUserDocument } from './documents/user';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { IKeyPairBufferWithUnEncryptedPrivateKey, ISigningKeyPrivateKeyInfo, ISimplePublicKeyOnly, ISimpleKeyPairBuffer, ISimplePublicKeyOnlyBuffer, PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IApiErrorResponse, IApiMessageResponse, IStatusCodeResponse, IApiExpressValidationErrorResponse } from '@digitaldefiance/node-express-suite';
+import {
+  DefaultBackendIdType,
+  IBlockStorageSchema,
+  IBlockStorageModel,
+  IBlockStorageSchemaEntry,
+  SchemaMap as BrightDbSchemaMap,
+  BrightDbCollection,
+} from '@brightchain/node-express-suite';
+
+export type { DefaultBackendIdType } from '@brightchain/node-express-suite';
+
+/**
+ * Validated body for express-validator
+ */
+export type ValidatedBody<T extends string> = {
+  [K in T]: unknown;
+};
+
+/**
+ * Schema map type for BrightDB collections.
+ * Maps model names to their BrightDB schema entries.
+ */
+export type SchemaMap = BrightDbSchemaMap;
+
+export type ApiRequestHandler<T extends ApiResponse> = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => Promise<IStatusCodeResponse<T>>;
+
+export type TypedHandlers = {
+  [key: string]: ApiRequestHandler<ApiResponse>;
+};
+
+export interface IRouteDefinition<T extends TypedHandlers> {
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch';
+  path: string;
+  options: {
+    handlerKey: keyof T;
+    validation?: (validationLanguage: CoreLanguageCode) => ValidationChain[];
+    useAuthentication: boolean;
+    useCryptoAuthentication: boolean;
+  };
+}
+
+export type RouteHandlers = Record<string, ApiRequestHandler<ApiResponse>>;
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+
+export interface RouteConfig<H extends object> {
+  method: HttpMethod;
+  path: string;
+  handlerKey: keyof H;
+  handlerArgs?: Array<unknown>;
+  useAuthentication: boolean;
+  useCryptoAuthentication: boolean;
+  middleware?: RequestHandler[];
+  validation?: FlexibleValidationChain;
+  rawJsonHandler?: boolean;
+  authFailureStatusCode?: number;
+}
+
+export function routeConfig<T extends object>(
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch',
+  path: string,
+  options: {
+    handlerKey: keyof T;
+    validation?: (validationLanguage: CoreLanguageCode) => ValidationChain[];
+    useAuthentication: boolean;
+    useCryptoAuthentication: boolean;
+  },
+): RouteConfig<T> {
+  return {
+    method,
+    path,
+    handlerKey: options.handlerKey,
+    validation: options.validation,
+    useAuthentication: options.useAuthentication,
+    useCryptoAuthentication: options.useCryptoAuthentication,
+  };
+}
+
+export type THandlerArgs<T extends Array<unknown>> = T;
+
+export type FlexibleValidationChain =
+  | ValidationChain[]
+  | ((lang: CoreLanguageCode) => ValidationChain[]);
+
+export type JsonPrimitive = string | number | boolean | null | undefined;
+
+export type JsonResponse =
+  | JsonPrimitive
+  | { [key: string]: JsonResponse }
+  | JsonResponse[];
+
+export type ApiErrorResponse =
+  | IApiErrorResponse
+  | IApiExpressValidationErrorResponse;
+
+export type ApiResponse = IApiMessageResponse | ApiErrorResponse | JsonResponse;
+
+export type SendFunction<T extends ApiResponse> = (
+  statusCode: number,
+  data: T,
+  res: Response<T>,
+) => void;
+
+export type KeyPairBufferWithUnEncryptedPrivateKey = Brand<
+  IKeyPairBufferWithUnEncryptedPrivateKey,
+  'KeyPairBufferWithUnEncryptedPrivateKey'
+>;
+export type SigningKeyPrivateKeyInfo = Brand<
+  ISigningKeyPrivateKeyInfo,
+  'SigningKeyPrivateKeyInfo'
+>;
+export type SimpleKeyPair = Brand<SimplePublicKeyOnly, 'SimpleKeyPair'>;
+export type SimplePublicKeyOnly = Brand<
+  ISimplePublicKeyOnly,
+  'SimplePublicKeyOnly'
+>;
+export type SimpleKeyPairBuffer = Brand<
+  ISimpleKeyPairBuffer,
+  'SimpleKeyPairBuffer'
+>;
+export type SimplePublicKeyOnlyBuffer = Brand<
+  ISimplePublicKeyOnlyBuffer,
+  'SimplePublicKeyOnlyBuffer'
+>;
+export type HexString = Brand<string, 'HexString'>;
+export type SignatureString = Brand<HexString, 'SignatureString'>;
+export type SignatureBuffer = Buffer & Brand<Buffer, 'SignatureBuffer'>;
+export type ChecksumBuffer = Buffer &
+  Brand<Buffer, 'Sha3Checksum', 'ChecksumBuffer'>;
+export type ChecksumString = Brand<HexString, 'Sha3Checksum', 'ChecksumString'>;
+
+/**
+ * Extended Buffer type for data
+ */
+export type DataBuffer = Buffer & {
+  toBuffer(): Buffer;
+  toHex(): string;
+};

package/scaffolding/api-lib-mern/src/lib/constants.ts.mustache

@@ -0,0 +1,10 @@
+import { IConstants } from './interfaces/constants';
+import { createExpressConstants } from '@digitaldefiance/node-express-suite';
+
+export const Constants: IConstants = {
+  ...createExpressConstants('{{hostname}}', '{{hostname}}'),
+  Site: '{{siteTitle}}' as const,
+  SiteTagline: '{{siteTagline}}' as const,
+  SiteDescription: '{{siteDescription}}' as const,
+  PasswordRegex: /^(?=.*[A-Za-z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])[A-Za-z\d!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]{8,}$/,
+};

package/scaffolding/api-lib-mern/src/lib/documents/index.ts

@@ -0,0 +1 @@
+export type { IUserDocument } from './user';

package/scaffolding/api-lib-mern/src/lib/interfaces/constants.ts

@@ -0,0 +1,9 @@
+import { IConstants as IBaseConstants } from '@digitaldefiance/node-express-suite';
+
+export interface IConstants extends IBaseConstants {
+  readonly Site: string;
+  readonly SiteTagline: string;
+  readonly SiteDescription: string;
+  readonly SiteHostname: string;
+  readonly PasswordRegex: RegExp;
+}

package/scaffolding/api-lib-mern/src/lib/interfaces/environment-aws.ts

@@ -0,0 +1,7 @@
+import { SecureString } from '@digitaldefiance/ecies-lib';
+
+export interface IEnvironmentAws {
+  accessKeyId: SecureString;
+  secretAccessKey: SecureString;
+  region: string;
+}

package/scaffolding/api-lib-mern/src/lib/interfaces/environment.ts

@@ -0,0 +1,10 @@
+import { IEnvironment as IBaseEnvironment } from '@digitaldefiance/node-express-suite';
+import { IEnvironmentAws } from './environment-aws';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+export interface IEnvironment<TID extends PlatformID> extends IBaseEnvironment<TID> {
+  /**
+   * AWS configuration
+   */
+  aws: IEnvironmentAws;
+}