@flusys/nestjs-shared 3.0.0-rc → 3.0.1

package/fesm/constants/permissions.js

@@ -1,13 +1,4 @@
-/**
- * Centralized Permission Codes
- *
- * Single source of truth for all permission codes used across the application.
- * Use these constants instead of hardcoded strings to prevent typos and enable easy refactoring.
- *
- * Naming Convention: <entity>.<action>
- * - entity: The resource being accessed (e.g., user, role, company)
- * - action: The operation being performed (create, read, update, delete, assign)
- */ // ==================== AUTH MODULE ====================
+// ==================== AUTH MODULE ====================
 export const USER_PERMISSIONS = {
     CREATE: 'user.create',
     READ: 'user.read',
@@ -100,10 +91,28 @@ export const FORM_RESULT_PERMISSIONS = {
     UPDATE: 'form-result.update',
     DELETE: 'form-result.delete'
 };
+// ==================== EVENT MANAGER MODULE ====================
+export const EVENT_PERMISSIONS = {
+    CREATE: 'event.create',
+    READ: 'event.read',
+    UPDATE: 'event.update',
+    DELETE: 'event.delete'
+};
+export const EVENT_PARTICIPANT_PERMISSIONS = {
+    CREATE: 'event-participant.create',
+    READ: 'event-participant.read',
+    UPDATE: 'event-participant.update',
+    DELETE: 'event-participant.delete'
+};
+// ==================== NOTIFICATION MODULE ====================
+export const NOTIFICATION_PERMISSIONS = {
+    CREATE: 'notification.create',
+    READ: 'notification.read',
+    UPDATE: 'notification.update',
+    DELETE: 'notification.delete'
+};
 // ==================== AGGREGATED EXPORTS ====================
-/**
- * All permission codes grouped by module
- */ export const PERMISSIONS = {
+export const PERMISSIONS = {
     // Auth
     USER: USER_PERMISSIONS,
     COMPANY: COMPANY_PERMISSIONS,
@@ -124,5 +133,10 @@ export const FORM_RESULT_PERMISSIONS = {
     EMAIL_TEMPLATE: EMAIL_TEMPLATE_PERMISSIONS,
     // Form Builder
     FORM: FORM_PERMISSIONS,
-    FORM_RESULT: FORM_RESULT_PERMISSIONS
+    FORM_RESULT: FORM_RESULT_PERMISSIONS,
+    // Event Manager
+    EVENT: EVENT_PERMISSIONS,
+    EVENT_PARTICIPANT: EVENT_PARTICIPANT_PERMISSIONS,
+    // Notification
+    NOTIFICATION: NOTIFICATION_PERMISSIONS
 };

package/fesm/decorators/require-permission.decorator.js

@@ -1,75 +1,28 @@
 import { SetMetadata } from '@nestjs/common';
 import { PERMISSIONS_KEY } from '../constants';
-/**
- * Decorator to require specific permissions for a route
- *
- * By default uses AND logic (user must have ALL permissions).
- * This is the most common and secure pattern.
- *
- * @param permissions - One or more permission keys required (AND logic)
- *
- * @example
- * // Require single permission
- * @RequirePermission('users.read')
- *
- * @example
- * // Require ALL permissions (AND)
- * @RequirePermission('users.read', 'users.write')
- *
- * @example
- * // For OR logic, use RequireAnyPermission instead
- * @RequireAnyPermission('admin.access', 'manager.access')
- */ export const RequirePermission = (...permissions)=>SetMetadata(PERMISSIONS_KEY, {
+/** Require ALL permissions (AND logic) - most secure pattern */ export const RequirePermission = (...permissions)=>SetMetadata(PERMISSIONS_KEY, {
         permissions,
-        operator: 'and'
+        operator: 'AND'
     });
-/**
- * Decorator to require ANY of the specified permissions (OR logic)
- *
- * User must have at least ONE of the specified permissions.
- * Less secure than RequirePermission (AND), use carefully.
- *
- * @param permissions - User must have at least ONE of these permissions
- *
- * @example
- * @RequireAnyPermission('admin.access', 'manager.access')
- */ export const RequireAnyPermission = (...permissions)=>SetMetadata(PERMISSIONS_KEY, {
+/** Require ANY permission (OR logic) - use carefully */ export const RequireAnyPermission = (...permissions)=>SetMetadata(PERMISSIONS_KEY, {
         permissions,
-        operator: 'or'
+        operator: 'OR'
     });
 /**
- * Decorator for complex permission conditions with nested logic
- *
- * Supports building complex permission trees:
- * - AND/OR operators
- * - Nested children for complex logic
- *
- * @param condition - Complex permission condition
- *
- * @example
- * // Simple: User needs 'admin' OR 'manager'
- * @RequirePermissionCondition({
- *   operator: 'or',
- *   permissions: ['admin', 'manager'],
- * })
- *
+ * Require complex permission logic using ILogicNode tree
  * @example
- * // Complex: User needs 'users.read' AND ('admin' OR 'manager')
- * @RequirePermissionCondition({
- *   operator: 'and',
- *   permissions: ['users.read'],
- *   children: [
- *     { operator: 'or', permissions: ['admin', 'manager'] }
- *   ]
- * })
- *
+ * // Single permission
+ * @RequirePermissionLogic('users.read')
  * @example
- * // Very complex: (A AND B) OR (C AND D)
- * @RequirePermissionCondition({
- *   operator: 'or',
- *   children: [
- *     { operator: 'and', permissions: ['finance.read', 'finance.write'] },
- *     { operator: 'and', permissions: ['admin.full', 'reports.access'] }
- *   ]
+ * // Complex: users.read AND (admin OR manager)
+ * @RequirePermissionLogic({
+ *   type: 'group', operator: 'AND', children: [
+ *     { type: 'action', actionId: 'users.read' },
+ *     { type: 'group', operator: 'OR', children: [
+ *       { type: 'action', actionId: 'admin' },
+ *       { type: 'action', actionId: 'manager' },
+ *     ]},
+ *   ],
  * })
- */ export const RequirePermissionCondition = (condition)=>SetMetadata(PERMISSIONS_KEY, condition);
+ */ export const RequirePermissionLogic = (logic)=>SetMetadata(PERMISSIONS_KEY, logic);
+/** @deprecated Use RequirePermissionLogic instead */ export const RequirePermissionCondition = RequirePermissionLogic;

package/fesm/enums/index.js

@@ -0,0 +1,3 @@
+export * from './notification-type.enum';
+export * from './participant-status.enum';
+export * from './recurrence-type.enum';

package/fesm/enums/notification-type.enum.js

@@ -0,0 +1,7 @@
+export var NotificationType = /*#__PURE__*/ function(NotificationType) {
+    NotificationType["INFO"] = "info";
+    NotificationType["WARNING"] = "warning";
+    NotificationType["SUCCESS"] = "success";
+    NotificationType["ERROR"] = "error";
+    return NotificationType;
+}({});

package/fesm/enums/participant-status.enum.js

@@ -0,0 +1,7 @@
+export var ParticipantStatus = /*#__PURE__*/ function(ParticipantStatus) {
+    ParticipantStatus["PENDING"] = "pending";
+    ParticipantStatus["ACCEPTED"] = "accepted";
+    ParticipantStatus["DECLINED"] = "declined";
+    ParticipantStatus["TENTATIVE"] = "tentative";
+    return ParticipantStatus;
+}({});

package/fesm/enums/recurrence-type.enum.js

@@ -0,0 +1,8 @@
+export var RecurrenceType = /*#__PURE__*/ function(RecurrenceType) {
+    RecurrenceType["NONE"] = "none";
+    RecurrenceType["DAILY"] = "daily";
+    RecurrenceType["WEEKLY"] = "weekly";
+    RecurrenceType["BIWEEKLY"] = "biweekly";
+    RecurrenceType["MONTHLY"] = "monthly";
+    return RecurrenceType;
+}({});

package/fesm/exceptions/permission.exception.js

@@ -13,8 +13,8 @@ import { ForbiddenException, InternalServerErrorException } from '@nestjs/common
 /**
  * Exception thrown when user lacks required permissions
  */ export class InsufficientPermissionsException extends ForbiddenException {
-    constructor(missingPermissions, operator = 'and'){
-        const message = operator === 'or' ? `Requires at least one of: ${missingPermissions.join(', ')}` : `Missing required permissions: ${missingPermissions.join(', ')}`;
+    constructor(missingPermissions, operator = 'AND'){
+        const message = operator === 'OR' ? `Requires at least one of: ${missingPermissions.join(', ')}` : `Missing required permissions: ${missingPermissions.join(', ')}`;
         super({
             success: false,
             message,

package/fesm/guards/permission.guard.js

@@ -45,8 +45,6 @@ export class PermissionGuard {
             context.getClass()
         ]);
         if (!permissionConfig) return true;
-        const { permissions: requiredPermissions, operator } = this.normalizePermissionConfig(permissionConfig);
-        if (!requiredPermissions || requiredPermissions.length === 0) return true;
         const request = context.switchToHttp().getRequest();
         const user = request.user;
         if (!user) throw new UnauthorizedException('Authentication required');
@@ -59,90 +57,93 @@ export class PermissionGuard {
             this.logger.warn(`No permissions found (userId: ${user.id})`, 'PermissionGuard');
             throw new NoPermissionsFoundException();
         }
-        if (this.isNestedCondition(permissionConfig)) {
-            const result = this.evaluateCondition(permissionConfig, userPermissions);
-            if (!result.passed) {
-                this.logger.warn(`Permission denied (userId: ${user.id})`, 'PermissionGuard');
-                throw new InsufficientPermissionsException(result.missingPermissions, result.operator);
-            }
-        } else {
-            this.validateSimplePermissions(requiredPermissions, userPermissions, operator);
+        const logicNode = this.normalizeToLogicNode(permissionConfig);
+        if (!logicNode) return true;
+        const result = this.evaluateLogicNode(logicNode, userPermissions);
+        if (!result.passed) {
+            this.logger.warn(`Permission denied (userId: ${user.id})`, 'PermissionGuard');
+            throw new InsufficientPermissionsException(result.missingPermissions, result.operator);
         }
         return true;
     }
-    normalizePermissionConfig(config) {
-        if (Array.isArray(config)) return {
-            permissions: config,
-            operator: 'and'
-        };
-        return {
-            permissions: config.permissions || [],
-            operator: config.operator || 'and'
-        };
-    }
-    validateSimplePermissions(requiredPermissions, userPermissions, operator) {
-        if (operator === 'or') {
-            const hasAny = requiredPermissions.some((p)=>this.hasPermission(userPermissions, p));
-            if (!hasAny) throw new InsufficientPermissionsException(requiredPermissions, 'or');
-        } else {
-            const hasAll = requiredPermissions.every((p)=>this.hasPermission(userPermissions, p));
-            if (!hasAll) {
-                const missing = requiredPermissions.filter((p)=>!this.hasPermission(userPermissions, p));
-                throw new InsufficientPermissionsException(missing, 'and');
-            }
+    normalizeToLogicNode(config) {
+        // string - single permission
+        if (typeof config === 'string') {
+            return config ? {
+                type: 'action',
+                actionId: config
+            } : null;
         }
+        // string[] - treat as AND of multiple permissions
+        if (Array.isArray(config)) {
+            if (config.length === 0) return null;
+            if (config.length === 1) return {
+                type: 'action',
+                actionId: config[0]
+            };
+            return {
+                type: 'group',
+                operator: 'AND',
+                children: config.map((p)=>({
+                        type: 'action',
+                        actionId: p
+                    }))
+            };
+        }
+        // SimplePermissionConfig - { permissions: string[], operator: 'AND'|'OR' }
+        if ('permissions' in config && Array.isArray(config.permissions)) {
+            const simple = config;
+            if (simple.permissions.length === 0) return null;
+            if (simple.permissions.length === 1) return {
+                type: 'action',
+                actionId: simple.permissions[0]
+            };
+            return {
+                type: 'group',
+                operator: simple.operator || 'AND',
+                children: simple.permissions.map((p)=>({
+                        type: 'action',
+                        actionId: p
+                    }))
+            };
+        }
+        // ILogicNode
+        return config;
     }
-    isNestedCondition(config) {
-        if (Array.isArray(config)) return false;
-        return 'children' in config && Array.isArray(config.children) && config.children.length > 0;
-    }
-    evaluateCondition(condition, userPermissions) {
-        const { permissions = [], operator, children = [] } = condition;
-        // SECURITY: Fail-closed - deny access when no permissions configured (empty condition)
-        if (permissions.length === 0 && children.length === 0) {
+    evaluateLogicNode(node, userPermissions) {
+        if (node.type === 'action') {
+            const passed = this.hasPermission(userPermissions, node.actionId);
+            return {
+                passed,
+                missingPermissions: passed ? [] : [
+                    node.actionId
+                ],
+                operator: 'AND'
+            };
+        }
+        // Group node
+        const { operator, children } = node;
+        // SECURITY: Fail-closed - deny access when no children configured
+        if (!children || children.length === 0) {
             return {
                 passed: false,
-                message: 'No permissions configured - access denied by default',
                 missingPermissions: [],
                 operator
             };
         }
         const results = [];
-        const failureDetails = [];
         const missingPermissions = [];
-        if (permissions.length > 0) {
-            if (operator === 'or') {
-                const hasAny = permissions.some((p)=>this.hasPermission(userPermissions, p));
-                results.push(hasAny);
-                if (!hasAny) {
-                    failureDetails.push(`needs one of: [${permissions.join(', ')}]`);
-                    missingPermissions.push(...permissions);
-                }
-            } else {
-                const hasAll = permissions.every((p)=>this.hasPermission(userPermissions, p));
-                results.push(hasAll);
-                if (!hasAll) {
-                    const missing = permissions.filter((p)=>!this.hasPermission(userPermissions, p));
-                    failureDetails.push(`missing: [${missing.join(', ')}]`);
-                    missingPermissions.push(...missing);
-                }
-            }
-        }
         for (const child of children){
-            const childResult = this.evaluateCondition(child, userPermissions);
+            const childResult = this.evaluateLogicNode(child, userPermissions);
             results.push(childResult.passed);
             if (!childResult.passed) {
-                failureDetails.push(`(${childResult.message})`);
                 missingPermissions.push(...childResult.missingPermissions);
             }
         }
-        // Evaluate based on operator - empty results already handled above
-        const passed = operator === 'or' ? results.some((r)=>r) : results.every((r)=>r);
-        const message = passed ? 'OK' : `Denied: ${failureDetails.join(` ${operator.toUpperCase()} `)}`;
+        const passed = operator === 'OR' ? results.some((r)=>r) : results.every((r)=>r);
         return {
             passed,
-            message,
-            missingPermissions,
+            missingPermissions: passed ? [] : missingPermissions,
             operator
         };
     }

package/fesm/index.js

@@ -3,6 +3,7 @@ export * from './constants';
 export * from './decorators';
 export * from './dtos';
 export * from './entities';
+export * from './enums';
 export * from './exceptions';
 export * from './guards';
 export * from './interceptors';

package/fesm/interfaces/event-manager-adapter.interface.js

@@ -0,0 +1 @@
+export const EVENT_MANAGER_ADAPTER = 'EVENT_MANAGER_ADAPTER';

package/fesm/interfaces/index.js

@@ -1,7 +1,9 @@
 export * from './api.interface';
 export * from './datasource.interface';
+export * from './event-manager-adapter.interface';
 export * from './identity.interface';
 export * from './logged-user-info.interface';
 export * from './logger.interface';
 export * from './module-config.interface';
+export * from './notification-adapter.interface';
 export * from './permission.interface';

package/fesm/interfaces/notification-adapter.interface.js

@@ -0,0 +1 @@
+export const NOTIFICATION_ADAPTER = 'NOTIFICATION_ADAPTER';

package/fesm/interfaces/permission.interface.js

@@ -1,3 +1 @@
-/**
- * Configuration for the permission guard
- */ export { };
+/** Action node - checks a single permission/action code */ /** Configuration for the permission guard */ export { };

package/fesm/utils/request.util.js

@@ -1,3 +1,4 @@
+import { envConfig } from '@flusys/nestjs-core/config';
 import { CLIENT_TYPE_HEADER } from '../constants';
 /** Time unit multipliers in milliseconds */ const TIME_UNIT_MS = {
     s: 1000,
@@ -30,7 +31,7 @@ import { CLIENT_TYPE_HEADER } from '../constants';
  */ export function buildCookieOptions(req) {
     const hostname = req.hostname || '';
     const origin = req.headers.origin || '';
-    const isProduction = process.env.NODE_ENV === 'production';
+    const isProduction = envConfig.isProduction();
     const forwardedProto = req.headers['x-forwarded-proto'];
     const isHttps = isProduction || forwardedProto === 'https' || origin.startsWith('https://') || req.secure;
     let domain;

package/guards/permission.guard.d.ts

@@ -10,10 +10,8 @@ export declare class PermissionGuard implements CanActivate {
     private readonly logger;
     constructor(reflector: Reflector, cache?: HybridCache, config?: PermissionGuardConfig, logger?: ILogger);
     canActivate(context: ExecutionContext): Promise<boolean>;
-    private normalizePermissionConfig;
-    private validateSimplePermissions;
-    private isNestedCondition;
-    private evaluateCondition;
+    private normalizeToLogicNode;
+    private evaluateLogicNode;
     private getUserPermissions;
     private buildPermissionCacheKey;
     private hasPermission;

package/index.d.ts

@@ -3,6 +3,7 @@ export * from './constants';
 export * from './decorators';
 export * from './dtos';
 export * from './entities';
+export * from './enums';
 export * from './exceptions';
 export * from './guards';
 export * from './interceptors';

package/interfaces/event-manager-adapter.interface.d.ts

@@ -0,0 +1,43 @@
+import { ParticipantStatus } from '../enums/participant-status.enum';
+import { RecurrenceType } from '../enums/recurrence-type.enum';
+export interface IEventManagerAdapter {
+    createEvent(options: CreateEventOptions): Promise<EventResult>;
+    addParticipants(eventId: string, userIds: string[], companyId?: string): Promise<void>;
+    removeParticipant(eventId: string, userId: string): Promise<void>;
+    updateParticipantStatus(participantId: string, status: ParticipantStatus): Promise<void>;
+    getEventsForUser?(userId: string, startDate: Date, endDate: Date, companyId?: string): Promise<EventResult[]>;
+    getEventById?(eventId: string): Promise<EventResult | null>;
+}
+export interface CreateEventOptions {
+    title: string;
+    description?: string;
+    meetingLink?: string;
+    startDateTime: Date;
+    endDateTime: Date;
+    isAllDay?: boolean;
+    recurrenceType?: RecurrenceType;
+    recurrenceEndDate?: Date;
+    color?: string;
+    metadata?: Record<string, unknown>;
+    participantIds?: string[];
+    organizerId?: string;
+    companyId?: string;
+}
+export interface EventResult {
+    id: string;
+    title: string;
+    description?: string | null;
+    meetingLink?: string | null;
+    startDateTime: Date;
+    endDateTime: Date;
+    isAllDay: boolean;
+    recurrenceType: string;
+    recurrenceEndDate?: Date | null;
+    color: string;
+    isActive: boolean;
+    metadata?: Record<string, unknown> | null;
+    companyId?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare const EVENT_MANAGER_ADAPTER = "EVENT_MANAGER_ADAPTER";

package/interfaces/index.d.ts

@@ -1,7 +1,9 @@
 export * from './api.interface';
 export * from './datasource.interface';
+export * from './event-manager-adapter.interface';
 export * from './identity.interface';
 export * from './logged-user-info.interface';
 export * from './logger.interface';
 export * from './module-config.interface';
+export * from './notification-adapter.interface';
 export * from './permission.interface';

package/interfaces/notification-adapter.interface.d.ts

@@ -0,0 +1,22 @@
+import { NotificationType } from '../enums/notification-type.enum';
+export interface INotificationAdapter {
+    send(options: NotificationSendOptions): Promise<void>;
+    sendToMany(options: NotificationBulkSendOptions): Promise<void>;
+    broadcastToCompany?(companyId: string, title: string, message?: string, type?: NotificationType, data?: Record<string, unknown>): Promise<void>;
+    isUserOnline?(userId: string): boolean;
+}
+interface NotificationBaseOptions {
+    title: string;
+    message?: string;
+    type?: NotificationType;
+    data?: Record<string, unknown>;
+    companyId?: string;
+}
+export interface NotificationSendOptions extends NotificationBaseOptions {
+    userId: string;
+}
+export interface NotificationBulkSendOptions extends NotificationBaseOptions {
+    userIds: string[];
+}
+export declare const NOTIFICATION_ADAPTER = "NOTIFICATION_ADAPTER";
+export {};

package/interfaces/permission.interface.d.ts

@@ -1,14 +1,19 @@
-export type PermissionOperator = 'and' | 'or';
-export interface PermissionCondition {
-    permissions?: string[];
-    operator: PermissionOperator;
-    children?: PermissionCondition[];
+export interface IActionNode {
+    type: 'action';
+    actionId: string;
 }
-export interface LegacyPermissionConfig {
+export interface IGroupNode {
+    type: 'group';
+    operator: 'AND' | 'OR';
+    children: ILogicNode[];
+}
+export type ILogicNode = IActionNode | IGroupNode;
+export type IPermissionLogic = string | ILogicNode;
+export interface SimplePermissionConfig {
     permissions: string[];
-    operator: PermissionOperator;
+    operator: 'AND' | 'OR';
 }
-export type PermissionConfig = PermissionCondition | LegacyPermissionConfig | string[];
+export type PermissionConfig = IPermissionLogic | SimplePermissionConfig | string[];
 export interface PermissionGuardConfig {
     enableCompanyFeature?: boolean;
     userPermissionKeyFormat?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-shared",
-  "version": "3.0.0-rc",
+  "version": "3.0.1",
   "description": "Common shared utilities for Flusys NestJS applications",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -46,6 +46,11 @@
       "import": "./fesm/entities/index.js",
       "require": "./cjs/entities/index.js"
     },
+    "./enums": {
+      "types": "./enums/index.d.ts",
+      "import": "./fesm/enums/index.js",
+      "require": "./cjs/enums/index.js"
+    },
     "./exceptions": {
       "types": "./exceptions/index.d.ts",
       "import": "./fesm/exceptions/index.js",
@@ -105,6 +110,6 @@
     "winston-daily-rotate-file": "^5.0.0"
   },
   "dependencies": {
-    "@flusys/nestjs-core": "3.0.0-rc"
+    "@flusys/nestjs-core": "3.0.1"
   }
 }