@flusys/nestjs-auth 4.1.1 → 5.0.1

package/fesm/docs/auth-swagger.config.js

@@ -1,33 +1,14 @@
-/** Tags used for company-related APIs (excluded when company feature is disabled) */ const COMPANY_RELATED_TAGS = [
+// ============================================================================
+// Company feature exclusions
+// ============================================================================
+const COMPANY_RELATED_TAGS = [
     'Companies',
     'Branches',
     'User Permissions',
     'Company Selection'
 ];
-/** Examples to exclude when company feature is disabled */ const COMPANY_EXAMPLE_EXCLUSIONS = [
-    {
-        pathPattern: '/auth/login',
-        method: 'post',
-        examples: [
-            'loginSuccessWithCompany',
-            'companySelection'
-        ]
-    }
-];
-/**
- * Schema properties to exclude when company feature is disabled
- *
- * This list controls which DTO properties are hidden from Swagger documentation
- * when bootstrapConfig.enableCompanyFeature = false
- *
- * **Documentation:**
- * - Usage: See FLUSYS_NEST/docs/AUTH-GUIDE.md "Swagger Schema Behavior" section
- * - Mechanism: See FLUSYS_NEST/docs/CORE-GUIDE.md "excludeSchemaProperties" section
- *
- * @see setupSwaggerDocs in @flusys/nestjs-core/docs
- * @see ISchemaPropertyExclusion interface
- */ const COMPANY_SCHEMA_EXCLUSIONS = [
-    // ===== Authentication Request DTOs =====
+const COMPANY_SCHEMA_EXCLUSIONS = [
+    // Request DTOs
     {
         schemaName: 'RegistrationDto',
         properties: [
@@ -53,7 +34,7 @@
             'branchId'
         ]
     },
-    // ===== Authentication Response DTOs =====
+    // Response DTOs
     {
         schemaName: 'RegistrationResponseDto',
         properties: [
@@ -75,7 +56,7 @@
             'branch'
         ]
     },
-    // ===== Nested/Helper DTOs (completely excluded) =====
+    // Nested helper DTOs
     {
         schemaName: 'CompanyInfoDto',
         properties: [
@@ -123,7 +104,7 @@
             'companies'
         ]
     },
-    // ===== Company Management DTOs =====
+    // Company management DTOs
     {
         schemaName: 'CreateCompanyDto',
         properties: [
@@ -177,7 +158,7 @@
             'updatedAt'
         ]
     },
-    // ===== Branch Management DTOs =====
+    // Branch management DTOs
     {
         schemaName: 'CreateCompanyBranchDto',
         properties: [
@@ -231,7 +212,7 @@
             'updatedAt'
         ]
     },
-    // ===== User Permission DTOs =====
+    // User permission DTOs
     {
         schemaName: 'UserCompanyPermissionDto',
         properties: [
@@ -287,127 +268,179 @@
         ]
     }
 ];
-/**
- * Auth Module Swagger Configuration
- * Use this with setupSwaggerDocs() from @flusys/nestjs-core
- * Note: modules not specified to include ALL controllers from the app
- *
- * @param bootstrapConfig - Bootstrap configuration to determine feature visibility
- * @returns Swagger configuration with appropriate excludeTags based on enableCompanyFeature
- */ export function authSwaggerConfig(bootstrapConfig) {
-    const enableCompanyFeature = bootstrapConfig?.enableCompanyFeature ?? true;
-    // Exclude company-related tags when company feature is disabled
-    const excludeTags = enableCompanyFeature ? [] : COMPANY_RELATED_TAGS;
-    return {
-        title: 'Auth API',
-        description: enableCompanyFeature ? `
-## Authentication API
-
-Handles user authentication, registration, and company/branch management.
-
-### Features
-- User registration (with optional company assignment)
-- Login with email/password
-- JWT token-based authentication
-- Company/Branch selection flow (when multi-company enabled)
-- Token refresh
-- Password change
-
+const COMPANY_EXAMPLE_EXCLUSIONS = [
+    {
+        pathPattern: '/auth/login',
+        method: 'post',
+        examples: [
+            'loginSuccessWithCompany',
+            'companySelection'
+        ]
+    }
+];
+// ============================================================================
+// Email verification exclusions
+// ============================================================================
+const EMAIL_VERIFICATION_PATHS = [
+    '/auth/forgot-password',
+    '/auth/reset-password',
+    '/auth/resend-verification',
+    '/auth/verify-email'
+];
+const EMAIL_VERIFICATION_SCHEMA_EXCLUSIONS = [
+    {
+        schemaName: 'RegistrationResponseDto',
+        properties: [
+            'requiresEmailVerification'
+        ]
+    },
+    {
+        schemaName: 'LoginResponseRequiresEmailVerificationDto',
+        properties: [
+            'requiresEmailVerification',
+            'email'
+        ]
+    }
+];
+const EMAIL_VERIFICATION_EXAMPLE_EXCLUSIONS = [
+    {
+        pathPattern: '/auth/login',
+        method: 'post',
+        examples: [
+            'emailVerification'
+        ]
+    }
+];
+// ============================================================================
+// Description builder
+// ============================================================================
+function buildDescription(enableCompanyFeature, enableEmailVerification, isMultiTenant) {
+    const multiTenantNote = isMultiTenant ? `\n> **Multi-Tenant Mode**: Include \`x-tenant-id\` header to target a specific tenant database.\n` : '';
+    const features = [
+        '- User registration',
+        '- Login with email/password',
+        '- JWT token-based authentication',
+        ...enableEmailVerification ? [
+            '- Email verification',
+            '- Forgot/reset password'
+        ] : [],
+        ...enableCompanyFeature ? [
+            '- Company/Branch selection flow (multi-company enabled)'
+        ] : [],
+        '- Token refresh',
+        '- Password change'
+    ].join('\n');
+    const loginFlowSection = enableCompanyFeature ? `
 ### Authentication Flow
 
-#### Simple Login (Company feature disabled)
-\`\`\`
-POST /auth/login → { accessToken, refreshToken, user }
-\`\`\`
-
-#### Company-Based Login (Company feature enabled)
-
-**Case 1: Single company, single branch**
+#### Simple Login (single company/branch)
 \`\`\`
 POST /auth/login → { accessToken, refreshToken, user, company, branch }
 \`\`\`
 
-**Case 2: Multiple companies or branches**
+#### Multi-Company Login (multiple companies or branches)
 \`\`\`
 POST /auth/login → { requiresSelection: true, sessionId, companies }
 POST /auth/select → { accessToken, refreshToken, user, company, branch }
 \`\`\`
-
+${enableEmailVerification ? `
+#### Email Verification Required
+\`\`\`
+POST /auth/login → { requiresEmailVerification: true, email }
+POST /auth/verify-email → { accessToken, refreshToken, user }
+\`\`\`
+` : ''}
 ### Company/Branch Selection Endpoints
 - \`POST /auth/select\` - Complete login by selecting company and branch
 - \`POST /auth/switch-company\` - Switch to different company/branch while logged in
-- \`GET /auth/companies\` - Get user's available companies
-- \`GET /auth/companies/:companyId/branches\` - Get branches for a company
-
+` : `
+### Authentication Flow
+\`\`\`
+POST /auth/login → { accessToken, refreshToken, user }
+\`\`\`
+${enableEmailVerification ? `
+#### Email Verification Required
+\`\`\`
+POST /auth/login → { requiresEmailVerification: true, email }
+POST /auth/verify-email → { accessToken, refreshToken, user }
+\`\`\`
+` : ''}`;
+    const emailVerificationSection = enableEmailVerification ? `
+### Email Verification Endpoints
+- \`POST /auth/forgot-password\` - Request password reset email
+- \`POST /auth/reset-password\` - Reset password using token
+- \`POST /auth/resend-verification\` - Resend verification email
+- \`POST /auth/verify-email\` - Verify email using token
+` : '';
+    const administrationSection = enableCompanyFeature ? `
 ### Administration Endpoints
 - \`POST /administration/users/*\` - User management
 - \`POST /administration/company/*\` - Company management
 - \`POST /administration/branch/*\` - Branch management
 - \`POST /administration/user-permissions/*\` - User permission management
-
+` : `
+### Administration Endpoints
+- \`POST /administration/users/*\` - User management
+`;
+    const registrationSection = enableCompanyFeature ? `
 ### Registration Flow
 
 **Simple registration:**
 \`\`\`json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123"
-}
+{ "name": "John Doe", "email": "john@example.com", "password": "password123" }
 \`\`\`
 
 **Join existing company:**
 \`\`\`json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "companySlug": "acme-corp",
-  "branchSlug": "main-branch"
-}
+{ "name": "John Doe", "email": "john@example.com", "password": "password123", "companySlug": "acme-corp", "branchSlug": "main-branch" }
 \`\`\`
 
 **Create new company:**
 \`\`\`json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123",
-  "newCompanyName": "My New Company",
-  "newCompanyPhone": "+1234567890"
-}
+{ "name": "John Doe", "email": "john@example.com", "password": "password123", "newCompanyName": "My New Company" }
+\`\`\`
+` : `
+### Registration Flow
+\`\`\`json
+{ "name": "John Doe", "email": "john@example.com", "password": "password123" }
 \`\`\`
-  ` : `
+`;
+    return `
 ## Authentication API
-
-Handles user authentication and registration.
+${multiTenantNote}
+Handles user authentication${enableCompanyFeature ? ', company/branch management' : ''}, and registration.
 
 ### Features
-- User registration
-- Login with email/password
-- JWT token-based authentication
-- Token refresh
-- Password change
-
-### Authentication Flow
-\`\`\`
-POST /auth/login → { accessToken, refreshToken, user }
-\`\`\`
-
-### Registration Flow
-\`\`\`json
-{
-  "name": "John Doe",
-  "email": "john@example.com",
-  "password": "password123"
+${features}
+${loginFlowSection}${emailVerificationSection}${administrationSection}${registrationSection}`;
 }
-\`\`\`
-  `,
+// ============================================================================
+// Config factory
+// ============================================================================
+export function authSwaggerConfig(bootstrapConfig) {
+    const enableCompanyFeature = bootstrapConfig?.enableCompanyFeature ?? true;
+    const enableEmailVerification = bootstrapConfig?.enableEmailVerification ?? true;
+    const isMultiTenant = bootstrapConfig?.databaseMode === 'multi-tenant';
+    const excludeTags = enableCompanyFeature ? [] : COMPANY_RELATED_TAGS;
+    const excludeSchemaProperties = [
+        ...enableCompanyFeature ? [] : COMPANY_SCHEMA_EXCLUSIONS,
+        ...enableEmailVerification ? [] : EMAIL_VERIFICATION_SCHEMA_EXCLUSIONS
+    ];
+    // Merge example exclusions — both may target /auth/login with different example names
+    const excludeExamples = [
+        ...enableCompanyFeature ? [] : COMPANY_EXAMPLE_EXCLUSIONS,
+        ...enableEmailVerification ? [] : EMAIL_VERIFICATION_EXAMPLE_EXCLUSIONS
+    ];
+    const excludePaths = enableEmailVerification ? undefined : EMAIL_VERIFICATION_PATHS;
+    return {
+        title: 'Auth API',
+        description: buildDescription(enableCompanyFeature, enableEmailVerification, isMultiTenant),
         version: '1.0',
         path: 'api/docs/auth',
         bearerAuth: true,
         excludeTags,
-        excludeSchemaProperties: enableCompanyFeature ? undefined : COMPANY_SCHEMA_EXCLUSIONS,
-        excludeExamples: enableCompanyFeature ? undefined : COMPANY_EXAMPLE_EXCLUSIONS
+        excludeSchemaProperties: excludeSchemaProperties.length ? excludeSchemaProperties : undefined,
+        excludeExamples: excludeExamples.length ? excludeExamples : undefined,
+        excludePaths
     };
 }

package/fesm/dtos/authentication.dto.js

@@ -612,8 +612,6 @@ export class LoginResponseRequiresEmailVerificationDto {
     constructor(){
         _define_property(this, "requiresEmailVerification", void 0);
         _define_property(this, "email", void 0);
-        _define_property(this, "message", void 0);
-        _define_property(this, "messageKey", void 0);
     }
 }
 _ts_decorate([
@@ -628,19 +626,6 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", String)
 ], LoginResponseRequiresEmailVerificationDto.prototype, "email", void 0);
-_ts_decorate([
-    ApiProperty({
-        example: 'Please verify your email address before logging in.'
-    }),
-    _ts_metadata("design:type", String)
-], LoginResponseRequiresEmailVerificationDto.prototype, "message", void 0);
-_ts_decorate([
-    ApiProperty({
-        example: 'auth.login.email.not.verified',
-        description: 'Translation key for localization'
-    }),
-    _ts_metadata("design:type", String)
-], LoginResponseRequiresEmailVerificationDto.prototype, "messageKey", void 0);
 export class ForgotPasswordDto {
     constructor(){
         _define_property(this, "email", void 0);

package/fesm/entities/company-branch.entity.js

@@ -20,7 +20,7 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-import { Identity } from '@flusys/nestjs-shared';
+import { getJsonColumnType, Identity } from '@flusys/nestjs-shared';
 import { Column, Entity, JoinColumn, ManyToOne, OneToMany, Unique } from 'typeorm';
 import { Company } from './company.entity';
 export class CompanyBranch extends Identity {
@@ -99,7 +99,7 @@ _ts_decorate([
 ], CompanyBranch.prototype, "isActive", void 0);
 _ts_decorate([
     Column({
-        type: 'json',
+        type: getJsonColumnType(),
         nullable: true
     }),
     _ts_metadata("design:type", Object)

package/fesm/entities/company.entity.js

@@ -20,7 +20,7 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-import { Identity } from '@flusys/nestjs-shared';
+import { getJsonColumnType, Identity } from '@flusys/nestjs-shared';
 import { Column, Entity, OneToMany } from 'typeorm';
 import { CompanyBranch } from './company-branch.entity';
 export class Company extends Identity {
@@ -113,14 +113,14 @@ _ts_decorate([
 ], Company.prototype, "isActive", void 0);
 _ts_decorate([
     Column({
-        type: 'json',
+        type: getJsonColumnType(),
         nullable: true
     }),
     _ts_metadata("design:type", Object)
 ], Company.prototype, "settings", void 0);
 _ts_decorate([
     Column({
-        type: 'json',
+        type: getJsonColumnType(),
         nullable: true
     }),
     _ts_metadata("design:type", Object)

package/fesm/entities/pending-registration.entity.js

@@ -20,6 +20,7 @@ function _ts_decorate(decorators, target, key, desc) {
 function _ts_metadata(k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
+import { getJsonColumnType } from '@flusys/nestjs-shared';
 import { Column, CreateDateColumn, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';
 export class PendingRegistration {
     constructor(){
@@ -85,7 +86,7 @@ _ts_decorate([
 ], PendingRegistration.prototype, "expiresAt", void 0);
 _ts_decorate([
     Column({
-        type: 'json',
+        type: getJsonColumnType(),
         nullable: true,
         name: 'company_data'
     }),
@@ -93,7 +94,7 @@ _ts_decorate([
 ], PendingRegistration.prototype, "companyData", void 0);
 _ts_decorate([
     Column({
-        type: 'json',
+        type: getJsonColumnType(),
         nullable: true,
         name: 'additional_fields'
     }),

package/fesm/entities/user-company-permission.entity.js

@@ -33,7 +33,6 @@ export class UserCompanyPermission {
         _define_property(this, "user", void 0);
         /* ---------- Polymorphic Target ---------- */ _define_property(this, "permissionType", void 0);
         _define_property(this, "targetId", void 0);
-        _define_property(this, "metadata", void 0);
         _define_property(this, "isActive", void 0);
         /* ---------- Optional Relations (no FK - polymorphic) ---------- */ _define_property(this, "company", void 0);
         _define_property(this, "branch", void 0);
@@ -76,13 +75,6 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", String)
 ], UserCompanyPermission.prototype, "targetId", void 0);
-_ts_decorate([
-    Column({
-        type: 'json',
-        nullable: true
-    }),
-    _ts_metadata("design:type", typeof Record === "undefined" ? Object : Record)
-], UserCompanyPermission.prototype, "metadata", void 0);
 _ts_decorate([
     Column({
         type: 'boolean',

package/fesm/entities/user-token.entity.js

@@ -37,7 +37,6 @@ export class UserToken {
         _define_property(this, "token", void 0);
         _define_property(this, "expiresAt", void 0);
         _define_property(this, "usedAt", void 0);
-        _define_property(this, "metadata", void 0);
         _define_property(this, "createdAt", void 0);
     }
 }
@@ -81,14 +80,6 @@ _ts_decorate([
     }),
     _ts_metadata("design:type", Object)
 ], UserToken.prototype, "usedAt", void 0);
-_ts_decorate([
-    Column({
-        type: 'varchar',
-        length: 255,
-        nullable: true
-    }),
-    _ts_metadata("design:type", Object)
-], UserToken.prototype, "metadata", void 0);
 _ts_decorate([
     CreateDateColumn({
         type: 'timestamp',

package/fesm/interceptors/set-token.interceptor.js

@@ -43,16 +43,24 @@ export class SetToken {
         const req = context.switchToHttp().getRequest();
         const res = context.switchToHttp().getResponse();
         return next.handle().pipe(map((value)=>{
-            if (typeof value !== 'object' || value === null || !('refreshToken' in value)) {
+            if (typeof value !== 'object' || value === null) {
                 return value;
             }
             const response = value;
-            if (isBrowserRequest(req)) {
-                this.setRefreshTokenCookie(req, res, String(response.refreshToken));
-                const { refreshToken, ...responseWithoutToken } = response;
-                return responseWithoutToken;
+            const data = typeof response['data'] === 'object' && response['data'] !== null ? response['data'] : null;
+            const tokenInData = data && typeof data['refreshToken'] === 'string';
+            if (!tokenInData) {
+                return value;
+            }
+            if (!isBrowserRequest(req)) {
+                return value;
             }
-            return value;
+            this.setRefreshTokenCookie(req, res, data['refreshToken']);
+            const { refreshToken: _, ...dataWithoutToken } = data;
+            return {
+                ...response,
+                data: dataWithoutToken
+            };
         }), catchError((err)=>throwError(()=>err)));
     }
     setRefreshTokenCookie(req, res, tokenValue) {
@@ -62,7 +70,7 @@ export class SetToken {
             throw new PayloadTooLargeException({
                 message: `Refresh token too large (≈${estimatedBytes} bytes)`,
                 messageKey: AUTH_MESSAGES.TOKEN_TOO_LARGE,
-                messageParams: {
+                messageVariables: {
                     size: estimatedBytes
                 }
             });

package/fesm/services/auth-config.service.js

@@ -76,10 +76,6 @@ export class AuthConfigService {
     getRefreshTokenCookieName() {
         return this.config.refreshTokenCookieName ?? 'fsn_refresh_token';
     }
-    // Frontend Configuration
-    getFrontendUrl() {
-        return this.config.frontendUrl;
-    }
     constructor(injectedOptions){
         _define_property(this, "options", void 0);
         _define_property(this, "config", void 0);

package/fesm/services/auth-email.service.js

@@ -25,14 +25,12 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-import { SYSTEM_MESSAGES } from '@flusys/nestjs-shared/constants';
 import { LogAction } from '@flusys/nestjs-shared';
-import { AUTH_MESSAGES, EMAIL_VERIFICATION_MESSAGES, USER_MESSAGES } from '../config';
+import { SYSTEM_MESSAGES } from '@flusys/nestjs-shared/constants';
 import { BadRequestException, Inject, Injectable, InternalServerErrorException, Optional, Scope } from '@nestjs/common';
 import * as bcrypt from 'bcrypt';
 import * as crypto from 'crypto';
-import { LessThan } from 'typeorm';
-import { BCRYPT_SALT_ROUNDS } from '../config';
+import { AUTH_MESSAGES, BCRYPT_SALT_ROUNDS, EMAIL_VERIFICATION_MESSAGES, USER_MESSAGES } from '../config';
 import { PendingRegistration } from '../entities/pending-registration.entity';
 import { TokenType, UserToken } from '../entities/user-token.entity';
 import { User } from '../entities/user.entity';
@@ -47,7 +45,7 @@ export class AuthEmailService {
             throw new InternalServerErrorException({
                 message: `${String(entity)} repository not available`,
                 messageKey: SYSTEM_MESSAGES.REPOSITORY_NOT_AVAILABLE,
-                messageParams: {
+                messageVariables: {
                     entity: String(entity)
                 }
             });
@@ -186,7 +184,11 @@ export class AuthEmailService {
         } catch  {
             throw new BadRequestException({
                 message: 'Failed to process request. Please try again later.',
-                messageKey: SYSTEM_MESSAGES.INTERNAL_ERROR
+                messageKey: SYSTEM_MESSAGES.INTERNAL_ERROR,
+                messageVariables: {
+                    provider: 'EmailProvider',
+                    error: 'Send email failed'
+                }
             });
         }
         return {
@@ -377,23 +379,6 @@ export class AuthEmailService {
             messageKey: EMAIL_VERIFICATION_MESSAGES.RESEND_SUCCESS
         };
     }
-    async cleanupExpired() {
-        const tokenRepository = await this.getRepository(UserToken);
-        const pendingRepository = await this.getRepository(PendingRegistration);
-        const now = new Date();
-        const tokenResult = await tokenRepository.delete({
-            expiresAt: LessThan(now)
-        });
-        const pendingResult = await pendingRepository.delete({
-            expiresAt: LessThan(now)
-        });
-        const deletedTokens = tokenResult.affected ?? 0;
-        const deletedPending = pendingResult.affected ?? 0;
-        return {
-            deletedTokens,
-            deletedPending
-        };
-    }
     constructor(dataSourceProvider, emailProvider){
         _define_property(this, "dataSourceProvider", void 0);
         _define_property(this, "emailProvider", void 0);
@@ -466,15 +451,6 @@ _ts_decorate([
     ]),
     _ts_metadata("design:returntype", Promise)
 ], AuthEmailService.prototype, "resendVerificationEmail", null);
-_ts_decorate([
-    LogAction({
-        action: 'auth.cleanupExpiredTokens',
-        module: 'auth'
-    }),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", []),
-    _ts_metadata("design:returntype", Promise)
-], AuthEmailService.prototype, "cleanupExpired", null);
 AuthEmailService = _ts_decorate([
     Injectable({
         scope: Scope.REQUEST