@digitaldefiance/express-suite-starter 2.4.6 → 2.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/express-suite-starter",
-  "version": "2.4.6",
+  "version": "2.4.7",
   "license": "MIT",
   "bin": {
     "create-express-suite": "./dist/src/cli.js"

package/scaffolding/api-lib/src/lib/application.ts

@@ -1,35 +1,84 @@
-import { Application, BaseApplication, IFailableResult, IServerInitResult, DummyEmailService, emailServiceRegistry, BaseRouter, IApplication } from '@digitaldefiance/node-express-suite';
+import {
+  Application,
+  BaseApplication,
+  IFailableResult,
+  IServerInitResult,
+  DummyEmailService,
+  emailServiceRegistry,
+  BaseRouter,
+  IApplication,
+  ApiRouter as LibraryApiRouter,
+} from '@digitaldefiance/node-express-suite';
 import { Environment } from './environment';
 import { IConstants } from './interfaces/constants';
 import { Constants } from './constants';
-import { ApiRouter } from './routers/api';
 import { AppRouter } from './routers/app';
 import { getSchemaMap } from './schemas/schema';
 import { initMiddleware } from './middlewares';
 import { EmailService } from './services/email';
+import { Types } from '@digitaldefiance/mongoose-types';
+import { ModelDocMap } from './shared-types';
 
-export class App<TInitResults extends IServerInitResult = IServerInitResult, TConstants extends IConstants = IConstants> extends Application<TInitResults, any, Environment, TConstants, any> {
+/**
+ * Main application class.
+ * 
+ * This class sets up the Express application with:
+ * - Library's ApiRouter which provides user authentication routes
+ * - App router for serving React frontend
+ * - Database initialization
+ * - Email service registration
+ * 
+ * Note: The library's ApiRouter includes UserController which provides:
+ * - /api/user/verify - Token verification
+ * - /api/user/request-direct-login - Direct login request
+ * - /api/user/login - User login
+ * - And other user management endpoints
+ * 
+ * For custom API routes, create additional decorator-based controllers
+ * and mount them on the router.
+ * 
+ * @example
+ * ```typescript
+ * const env = new Environment(join(App.distDir, 'my-api', '.env'));
+ * const app = new App(
+ *   env,
+ *   DatabaseInitializationService.initUserDb.bind(DatabaseInitializationService),
+ *   DatabaseInitializationService.serverInitResultHash.bind(DatabaseInitializationService),
+ *   Constants,
+ * );
+ * await app.start();
+ * ```
+ */
+export class App<
+  TInitResults extends IServerInitResult<Types.ObjectId> = IServerInitResult<Types.ObjectId>,
+  TConstants extends IConstants = IConstants,
+> extends Application<TInitResults, ModelDocMap, Types.ObjectId, Environment<Types.ObjectId>, TConstants, AppRouter> {
   constructor(
-    environment: Environment,
-    databaseInitFunction: (application: BaseApplication<any, TInitResults>) => Promise<IFailableResult<TInitResults>>,
+    environment: Environment<Types.ObjectId>,
+    databaseInitFunction: (
+      application: BaseApplication<Types.ObjectId, ModelDocMap, TInitResults>,
+    ) => Promise<IFailableResult<TInitResults>>,
     initResultHashFunction: (initResults: TInitResults) => string,
     constants: TConstants = Constants as TConstants,
   ) {
     super(
-      environment, 
-      (app: IApplication): BaseRouter<IApplication> => new ApiRouter(app), 
+      environment,
+      // Use the library's ApiRouter which includes UserController for auth routes
+      (app: IApplication<Types.ObjectId>): BaseRouter<Types.ObjectId> => {
+        return new LibraryApiRouter(app);
+      },
       getSchemaMap,
-      databaseInitFunction, 
-      initResultHashFunction, 
+      databaseInitFunction,
+      initResultHashFunction,
       undefined, // Default CSP config
       constants,
-      (apiRouter: BaseRouter<IApplication>): AppRouter => new AppRouter(apiRouter),
+      (apiRouter: BaseRouter<Types.ObjectId>): AppRouter => new AppRouter(apiRouter),
       initMiddleware,
     );
-    
+
     // Register the DummyEmailService - users should replace this with their own email service
-    const emailService = new DummyEmailService(this);
-    //const emailService = new EmailService(this);
+    const emailService = new DummyEmailService<Types.ObjectId>(this);
+    // const emailService = new EmailService(this);
     emailServiceRegistry.setService(emailService);
   }
 }

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

@@ -1,11 +1,77 @@
-import { ApiRouter as BaseApiRouter, IApplication, IBaseDocument } from '@digitaldefiance/node-express-suite';
+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 { Types } from '@digitaldefiance/mongoose-types';
 import { Environment } from '../environment';
 import { IConstants } from '../interfaces/constants';
 import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
 
-export class ApiRouter<
+/**
+ * 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 Types.ObjectId | string = Types.ObjectId,
   TDate extends Date = Date,
   TLanguage extends CoreLanguageCode = CoreLanguageCode,
@@ -15,10 +81,84 @@ export class ApiRouter<
   TTokenUser extends ITokenUser = ITokenUser,
   TEnvironment extends Environment<TID> = Environment<TID>,
   TConstants extends IConstants = IConstants,
-  TBaseDocument extends IBaseDocument<any, TID> = IBaseDocument<any, TID>,
   TApplication extends IApplication<TID> = IApplication<TID>,
-> extends BaseApiRouter<TID,TDate,TLanguage,TAccountStatus, TUser,TTokenRole,TBaseDocument, TTokenUser,TConstants, TEnvironment, TApplication> {
+> 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/src/lib/routers/app.ts

@@ -3,9 +3,10 @@ import { Request, Response, NextFunction } from 'express';
 import { Environment } from '../environment';
 import { IConstants } from '../interfaces/constants';
 import { Constants } from '../constants';
+import { Types } from '@digitaldefiance/mongoose-types';
 
-export class AppRouter extends BaseAppRouter<IApplication> {
-  constructor(apiRouter: BaseRouter<IApplication>) {
+export class AppRouter extends BaseAppRouter<Types.ObjectId, IApplication<Types.ObjectId>> {
+  constructor(apiRouter: BaseRouter<Types.ObjectId, IApplication<Types.ObjectId>>) {
     super(apiRouter);
   }
 
@@ -17,7 +18,7 @@ export class AppRouter extends BaseAppRouter<IApplication> {
     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;
+    const environment = this.application.environment as Environment<Types.ObjectId>;
     const SiteName = constants.Site;
     const locals = {
       ...this.getBaseViewLocals(req, res),

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

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

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

@@ -1,4 +1,4 @@
-import { Connection } from '@digitaldefiance/mongoose-types';
+import { Connection, Types } from '@digitaldefiance/mongoose-types';
 import { BaseModelName, createEmailTokenSchema, createMnemonicSchema, createRoleSchema, createUsedDirectLoginTokenSchema, createUserRoleSchema, MnemonicSchema, RoleSchema, SchemaCollection, SchemaMap, UsedDirectLoginTokenSchema, UserRoleSchema } from '@digitaldefiance/node-express-suite';
 import EmailTokenModel from '../models/email-token';
 import MnemonicModel from '../models/mnemonic';
@@ -11,7 +11,7 @@ import { ModelDocMap } from '../shared-types';
 import { IConstants } from '../interfaces/constants';
 import { Constants } from '../constants';
 
-export function getSchemaMap(connection: Connection, constants: IConstants = Constants): SchemaMap<ModelDocMap> {
+export function getSchemaMap(connection: Connection, constants: IConstants = Constants): SchemaMap<Types.ObjectId, ModelDocMap> {
   return {
     EmailToken: {
       collection: SchemaCollection.EmailToken,

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

@@ -48,7 +48,7 @@ export type SchemaMap = {
   /**
    * For each model name, contains the corresponding schema and model
    */
-  [K in keyof ModelDocMap]: ISchema<ModelDocMap[K]>;
+  [K in keyof ModelDocMap]: ISchema<Types.ObjectId, ModelDocMap[K]>;
 };
 
 export type ApiRequestHandler<T extends ApiResponse> = (

package/templates/api-lib/README.md.mustache

@@ -4,20 +4,88 @@ API business logic library for {{WORKSPACE_NAME}}.
 
 ## Purpose
 
-Business logic, services, and models for the API layer.
+Business logic, services, models, and decorator-based API controllers for the API layer.
 
 ## Structure
 
 ```
 src/
-├── services/       # Business logic services
-├── models/         # Data models
-├── validators/     # Input validation
-└── utils/          # API utilities
+├── lib/
+│   ├── routers/        # Decorator-based API controllers
+│   ├── services/       # Business logic services
+│   ├── models/         # Mongoose data models
+│   ├── documents/      # TypeScript document interfaces
+│   ├── schemas/        # Mongoose schemas
+│   ├── interfaces/     # TypeScript interfaces
+│   ├── application.ts  # Main application class
+│   ├── environment.ts  # Environment configuration
+│   └── constants.ts    # Application constants
+└── index.ts            # Public exports
+```
+
+## Decorator-Based Controllers
+
+This library uses the decorator-based approach from `@digitaldefiance/node-express-suite` for defining API routes. This provides:
+
+- **Type-safe routing** with `@Get`, `@Post`, `@Put`, `@Delete`, `@Patch` decorators
+- **Automatic OpenAPI documentation** with `@ApiTags`, `@ApiSummary`, `@Returns` decorators
+- **Built-in authentication** with `@RequireAuth`, `@Public` decorators
+- **Request validation** with `@ValidateBody`, `@ValidateParams`, `@ValidateQuery` decorators
+- **Parameter injection** with `@Param`, `@Body`, `@Query`, `@Header` decorators
+
+### Example Controller
+
+```typescript
+import {
+  DecoratorBaseController,
+  ApiController,
+  Get,
+  Post,
+  RequireAuth,
+  Public,
+  ApiTags,
+  ApiSummary,
+  Returns,
+  Param,
+  Body,
+  ValidateBody,
+} from '@digitaldefiance/node-express-suite';
+import { z } from 'zod';
+
+const CreateItemSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().optional(),
+});
+
+@ApiTags('Items')
+@ApiController('/api/items', { description: 'Item management endpoints' })
+@RequireAuth()
+export class ItemController extends DecoratorBaseController {
+  constructor(app: IApplication) {
+    super(app);
+  }
+
+  @Public()
+  @ApiSummary('List all items')
+  @Returns(200, 'ItemList')
+  @Get('/')
+  async listItems() {
+    return { items: [] };
+  }
+
+  @ValidateBody(CreateItemSchema)
+  @ApiSummary('Create a new item')
+  @Returns(201, 'Item')
+  @Returns(400, 'ValidationError')
+  @Post('/')
+  async createItem(@Body() data: z.infer<typeof CreateItemSchema>) {
+    return { id: 'new-id', ...data };
+  }
+}
 ```
 
 ## Usage
 
 ```typescript
-import { UserService } from '{{NAMESPACE_ROOT}}/api-lib';
+import { App, Environment, Constants } from '{{NAMESPACE_ROOT}}/api-lib';
 ```