@alacard-project/shared 1.0.0 → 1.0.3

package/src/contracts/index.ts

@@ -1,2 +1,3 @@
 export * from './config.contract';
 export * from './logging.contract';
+export * from './auth.contract';

package/src/decorators/scopes.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const SCOPES_KEY = 'scopes';
+export const Scopes = (...scopes: string[]) => SetMetadata(SCOPES_KEY, scopes);

package/src/dto/auth.dto.ts

@@ -0,0 +1,62 @@
+import { IsEmail, IsString, MinLength, IsEnum, IsOptional } from 'class-validator';
+import { UserRole } from '../enums/user.enum';
+
+export class RegisterDto {
+    @IsEmail()
+    email!: string;
+
+    @IsString()
+    @MinLength(8)
+    password!: string;
+
+    @IsEnum(UserRole)
+    @IsOptional()
+    role?: UserRole;
+
+    @IsString()
+    @IsOptional()
+    firstName?: string;
+
+    @IsString()
+    @IsOptional()
+    lastName?: string;
+}
+
+export class LoginDto {
+    @IsEmail()
+    email!: string;
+
+    @IsString()
+    password!: string;
+}
+
+export interface UserResponse {
+    id: string;
+    email: string;
+    role: UserRole;
+    firstName: string;
+    lastName: string;
+    middleName?: string;
+    name?: string;
+    isActive: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    password?: string;
+    shortName?: string;
+    internalPhone?: string;
+    mobilePhone?: string;
+    facsimileSignature?: string;
+}
+
+export interface UserProfileDto {
+    id: string;
+    email: string;
+    role: string;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    fullName: string;
+    position: string;
+    department: string;
+    emailVerified: boolean;
+}

package/src/dto/index.ts

@@ -0,0 +1,2 @@
+export * from './logging.dto';
+export * from './auth.dto';

package/src/{logging/dto/log-filter.dto.ts → dto/logging.dto.ts}

@@ -1,6 +1,6 @@
 import { IsOptional, IsString, IsEnum, IsDateString, IsInt, Min, Max } from 'class-validator';
 import { Type } from 'class-transformer';
-import { LogLevel } from '../../enums';
+import { LogLevel } from '../enums';
 
 export class LogFilterDto {
     @IsOptional()

package/src/enums/error.enum.ts

@@ -0,0 +1,26 @@
+export enum ErrorCode {
+    // Auth Errors
+    AUTH_USER_NOT_FOUND = 'AUTH_USER_NOT_FOUND',
+    AUTH_USER_ALREADY_EXISTS = 'AUTH_USER_ALREADY_EXISTS',
+    AUTH_USER_INACTIVE = 'AUTH_USER_INACTIVE',
+    AUTH_INVALID_PASSWORD = 'AUTH_INVALID_PASSWORD',
+    AUTH_INVALID_TOKEN = 'AUTH_INVALID_TOKEN',
+    AUTH_TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
+    AUTH_ACCESS_DENIED = 'AUTH_ACCESS_DENIED',
+    AUTH_INSUFFICIENT_SCOPES = 'AUTH_INSUFFICIENT_SCOPES',
+    AUTH_INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
+
+    // Config Errors
+    CONFIG_NOT_FOUND = 'CONFIG_NOT_FOUND',
+    CONFIG_LOAD_FAILED = 'CONFIG_LOAD_FAILED',
+
+    // Logging Errors
+    LOG_WRITE_FAILED = 'LOG_WRITE_FAILED',
+    LOG_READ_FAILED = 'LOG_READ_FAILED',
+
+    // General Errors
+    INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR',
+    BAD_REQUEST = 'BAD_REQUEST',
+    NOT_FOUND = 'NOT_FOUND',
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
+}

package/src/enums/events.enum.ts

@@ -0,0 +1,22 @@
+export enum ServiceEventType {
+    AUTH_USER_REGISTERED = 'auth.user.registered',
+    AUTH_USER_LOGGED_IN = 'auth.user.logged_in',
+    AUTH_PASSWORD_RESET_REQUESTED = 'auth.password_reset_requested',
+    AUTH_PASSWORD_RESET_SUCCESS = 'auth.password_reset_success',
+    USER_PROFILE_UPDATED = 'user.profile_updated',
+    USER_DELETED = 'user.deleted',
+    AUTH_USER_BLOCKED = 'auth.user.blocked',
+}
+
+export interface AuthUserRegisteredEvent {
+    userId: string;
+    email: string;
+    role: string;
+    occurredAt: Date;
+}
+
+export interface AuthUserBlockedEvent {
+    userId: string;
+    reason?: string;
+    blockedAt: Date;
+}

package/src/enums/health.enum.ts

@@ -0,0 +1,7 @@
+export enum ServiceHealth {
+    UP = 'UP',
+    HEALTHY = 'UP',
+    DOWN = 'DOWN',
+    DEGRADED = 'DEGRADED',
+    MAINTENANCE = 'MAINTENANCE',
+}

package/src/enums/index.ts

@@ -1,5 +1,8 @@
-export * from './environment.enum';
-export * from './user-role.enum';
-export * from './log-level.enum';
-export * from './notification-type.enum';
-export * from './error-code.enum';
+export * from './env.enum';
+export * from './user.enum';
+export * from './health.enum';
+export * from './logging.enum';
+export * from './notification.enum';
+export * from './error.enum';
+export * from './permission.enum';
+export * from './events.enum';

package/src/enums/permission.enum.ts

@@ -0,0 +1,31 @@
+export enum PermissionScope {
+    // User Management
+    USERS_VIEW = 'users:view',
+    USERS_MANAGE = 'users:manage',
+
+    // Auth Management
+    ROLES_MANAGE = 'roles:manage',
+    PERMISSIONS_MANAGE = 'permissions:manage',
+
+    // Client Management
+    CLIENTS_VIEW = 'clients:view',
+    CLIENTS_MANAGE = 'clients:manage',
+
+    // Partner Management
+    PARTNERS_VIEW = 'partners:view',
+    PARTNERS_MANAGE = 'partners:manage',
+
+    // Financial/Accounting
+    INVOICES_VIEW = 'invoices:view',
+    INVOICES_MANAGE = 'invoices:manage',
+    TRANSACTIONS_VIEW = 'transactions:view',
+    TRANSACTIONS_MANAGE = 'transactions:manage',
+
+    // System Config
+    CONFIG_VIEW = 'config:view',
+    CONFIG_MANAGE = 'config:manage',
+
+    // Logging/Monitoring
+    LOGS_VIEW = 'logs:view',
+    METRICS_VIEW = 'metrics:view',
+}

package/src/enums/{user-role.enum.ts → user.enum.ts}

@@ -1,6 +1,8 @@
 export enum UserRole {
+    SUPER_ADMIN = 'SUPER_ADMIN',
     ADMIN = 'ADMIN',
+    MANAGER = 'MANAGER',
+    ACCOUNTANT = 'ACCOUNTANT',
     PARTNER = 'PARTNER',
     CLIENT = 'CLIENT',
-    USER = 'USER',
 }

package/src/errors/app.error.ts

@@ -0,0 +1,33 @@
+import { ErrorCode } from '../enums/error.enum';
+import { ERROR_MAP } from './error-map';
+
+export class AppError extends Error {
+    public readonly code: ErrorCode;
+    public readonly statusCode: number;
+    public readonly description?: string;
+    public readonly metadata?: any;
+
+    constructor(code: ErrorCode, customMessage?: string, metadata?: any) {
+        const errorDetail = ERROR_MAP[code] || ERROR_MAP[ErrorCode.INTERNAL_SERVER_ERROR];
+        super(customMessage || errorDetail.message);
+
+        this.code = code;
+        this.statusCode = errorDetail.statusCode;
+        this.description = errorDetail.description;
+        this.metadata = metadata;
+
+        Object.setPrototypeOf(this, AppError.prototype);
+    }
+
+    toJSON() {
+        return {
+            success: false,
+            error: {
+                code: this.code,
+                message: this.message,
+                description: this.description,
+                metadata: this.metadata,
+            },
+        };
+    }
+}

package/src/errors/error-map.ts

@@ -0,0 +1,95 @@
+import { ErrorCode } from '../enums/error.enum';
+
+export interface ErrorDetail {
+    message: string;
+    statusCode: number;
+    description?: string;
+}
+
+export const ERROR_MAP: Record<ErrorCode, ErrorDetail> = {
+    [ErrorCode.AUTH_USER_NOT_FOUND]: {
+        message: 'User not found',
+        statusCode: 404,
+        description: 'The requested user could not be found in the system.',
+    },
+    [ErrorCode.AUTH_USER_ALREADY_EXISTS]: {
+        message: 'User already exists',
+        statusCode: 409,
+        description: 'A user with this email already exists.',
+    },
+    [ErrorCode.AUTH_USER_INACTIVE]: {
+        message: 'User is inactive',
+        statusCode: 403,
+        description: 'The user account is currently deactivated.',
+    },
+    [ErrorCode.AUTH_INVALID_PASSWORD]: {
+        message: 'Invalid password',
+        statusCode: 401,
+        description: 'The provided password does not match.',
+    },
+    [ErrorCode.AUTH_INVALID_TOKEN]: {
+        message: 'Invalid token',
+        statusCode: 401,
+        description: 'The provided authentication token is invalid or malformed.',
+    },
+    [ErrorCode.AUTH_TOKEN_EXPIRED]: {
+        message: 'Token expired',
+        statusCode: 401,
+        description: 'The authentication token has expired. Please log in again.',
+    },
+    [ErrorCode.AUTH_ACCESS_DENIED]: {
+        message: 'Access denied',
+        statusCode: 403,
+        description: 'You do not have permission to perform this action.',
+    },
+    [ErrorCode.AUTH_INSUFFICIENT_SCOPES]: {
+        message: 'Insufficient scopes',
+        statusCode: 403,
+        description: 'Your token does not have the required scopes for this resource.',
+    },
+    [ErrorCode.AUTH_INVALID_CREDENTIALS]: {
+        message: 'Invalid credentials',
+        statusCode: 401,
+        description: 'The email or password you entered is incorrect.',
+    },
+    [ErrorCode.CONFIG_NOT_FOUND]: {
+        message: 'Configuration not found',
+        statusCode: 404,
+        description: 'The requested configuration key was not found.',
+    },
+    [ErrorCode.CONFIG_LOAD_FAILED]: {
+        message: 'Configuration load failed',
+        statusCode: 500,
+        description: 'Failed to load configuration from the source.',
+    },
+    [ErrorCode.LOG_WRITE_FAILED]: {
+        message: 'Log write failed',
+        statusCode: 500,
+        description: 'Failed to write log to the destination.',
+    },
+    [ErrorCode.LOG_READ_FAILED]: {
+        message: 'Log read failed',
+        statusCode: 500,
+        description: 'Failed to read logs from the source.',
+    },
+    [ErrorCode.INTERNAL_SERVER_ERROR]: {
+        message: 'Internal server error',
+        statusCode: 500,
+        description: 'An unexpected error occurred on the server.',
+    },
+    [ErrorCode.BAD_REQUEST]: {
+        message: 'Bad request',
+        statusCode: 400,
+        description: 'The request is invalid or cannot be served.',
+    },
+    [ErrorCode.NOT_FOUND]: {
+        message: 'Resource not found',
+        statusCode: 404,
+        description: 'The requested resource could not be found.',
+    },
+    [ErrorCode.VALIDATION_ERROR]: {
+        message: 'Validation error',
+        statusCode: 422,
+        description: 'The provided data failed validation.',
+    },
+};

package/src/index.ts

@@ -2,5 +2,14 @@ export * from './enums';
 export * from './constants';
 export * from './types';
 export * from './contracts';
+export * from './dto';
+export * from './errors/app.error';
+export * from './errors/error-map';
+export * from './decorators/scopes.decorator';
 export * from './utils/proto-path';
-export * from './logging';
+export * from './utils/logging-client';
+export * from './config/base-config.service';
+export * from './utils/user.utils';
+export * from './utils/prometheus.utils';
+export * from './utils/app.utils';
+export * from './utils/health.utils';

package/src/types/auth.types.ts

@@ -7,3 +7,8 @@ export interface JwtPayload {
     exp?: number;
     iss?: string;
 }
+export interface JwtTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}

package/src/types/config.types.ts

@@ -1,5 +1,7 @@
+import { Environment } from '../enums/env.enum';
+
 export interface IBaseConfig {
-    environment: string;
+    environment: Environment;
 }
 
 export interface DbConfig {
@@ -21,7 +23,7 @@ export interface AppConfig {
     port: number;
     host?: string;
     serviceName: string;
-    environment?: string;
+    environment?: Environment;
     version?: string;
     description?: string;
     databaseUrl?: string;

package/src/types/index.ts

@@ -1,3 +1,4 @@
 export * from './config.types';
 export * from './auth.types';
-// ErrorCode moved to enums
+export * from './user.types';
+export * from './monitoring.types';

package/src/types/monitoring.types.ts

@@ -0,0 +1,79 @@
+/**
+ * Prometheus Metrics Types
+ */
+
+export interface PrometheusMetric {
+    name: string;
+    help: string;
+    type: 'counter' | 'gauge' | 'histogram' | 'summary';
+    labelNames?: string[];
+}
+
+export interface MetricValue {
+    value: number;
+    labels?: Record<string, string>;
+    timestamp?: number;
+}
+
+export interface ServiceMetrics {
+    serviceName: string;
+    timestamp: Date;
+    metrics: {
+        // HTTP Metrics
+        httpRequestsTotal?: number;
+        httpRequestDuration?: number;
+        httpErrorsTotal?: number;
+
+        // Database Metrics
+        dbConnectionsActive?: number;
+        dbConnectionsIdle?: number;
+        dbQueryDuration?: number;
+        dbQueriesTotal?: number;
+
+        // System Metrics
+        cpuUsage?: number;
+        memoryUsage?: number;
+        heapUsed?: number;
+        heapTotal?: number;
+
+        // Application Metrics
+        activeUsers?: number;
+        requestsPerSecond?: number;
+        errorRate?: number;
+
+        // Custom Metrics
+        [key: string]: number | undefined;
+    };
+}
+
+export interface HealthCheckResult {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    checks: {
+        [component: string]: {
+            status: 'up' | 'down';
+            message?: string;
+            responseTime?: number;
+        };
+    };
+    timestamp: Date;
+}
+
+export interface GrafanaDashboard {
+    id: string;
+    title: string;
+    panels: GrafanaPanel[];
+    tags: string[];
+}
+
+export interface GrafanaPanel {
+    id: number;
+    title: string;
+    type: 'graph' | 'singlestat' | 'table' | 'heatmap';
+    targets: GrafanaTarget[];
+}
+
+export interface GrafanaTarget {
+    expr: string; // Prometheus query
+    legendFormat?: string;
+    refId: string;
+}

package/src/types/user.types.ts

@@ -0,0 +1,11 @@
+import { Observable } from 'rxjs';
+import { UserResponse } from '../dto/auth.dto';
+import { GetUserByIdGrpcRequest, GetUserByEmailGrpcRequest } from '../contracts/auth.contract';
+
+export interface IUserService {
+    getUserById(data: GetUserByIdGrpcRequest): Observable<UserResponse>;
+    getUserByEmail(data: GetUserByEmailGrpcRequest): Observable<UserResponse>;
+    createUser(data: any): Observable<UserResponse>;
+    updateUser(data: any): Observable<UserResponse>;
+    deleteUser(data: any): Observable<any>;
+}

package/src/utils/app.utils.ts

@@ -0,0 +1,54 @@
+/**
+ * Application Setup Utilities
+ */
+
+import { INestApplication, ValidationPipe } from '@nestjs/common';
+import { API_PREFIX } from '../constants/http.constants';
+import helmet from 'helmet';
+
+export interface AppSetupOptions {
+    corsOrigins?: string[];
+    apiPrefix?: string;
+    helmet?: boolean;
+    validation?: boolean;
+}
+
+/**
+ * Setup standard NestJS application middleware
+ */
+export function setupStandardApp(
+    app: INestApplication,
+    options: AppSetupOptions = {}
+): void {
+    const {
+        corsOrigins = ['*'],
+        apiPrefix = API_PREFIX.V1,
+        helmet: useHelmet = true,
+        validation = true,
+    } = options;
+
+    // CORS
+    app.enableCors({
+        origin: corsOrigins,
+        credentials: true,
+    });
+
+    // API Prefix
+    app.setGlobalPrefix(apiPrefix);
+
+    // Security
+    if (useHelmet) {
+        app.use(helmet());
+    }
+
+    // Validation
+    if (validation) {
+        app.useGlobalPipes(
+            new ValidationPipe({
+                whitelist: true,
+                forbidNonWhitelisted: true,
+                transform: true,
+            })
+        );
+    }
+}

package/src/utils/health.utils.ts

@@ -0,0 +1,72 @@
+/**
+ * Health Check Utilities
+ */
+
+export interface ComponentHealth {
+    status: 'up' | 'down';
+    message?: string;
+    responseTime?: number;
+}
+
+/**
+ * Create Prisma health check function
+ */
+export function createPrismaHealthCheck(prisma: any) {
+    return async (): Promise<ComponentHealth> => {
+        const start = Date.now();
+        try {
+            await prisma.$queryRaw`SELECT 1`;
+            return {
+                status: 'up',
+                responseTime: Date.now() - start,
+            };
+        } catch (error: any) {
+            return {
+                status: 'down',
+                message: error.message,
+            };
+        }
+    };
+}
+
+/**
+ * Create Redis health check function
+ */
+export function createRedisHealthCheck(redis: any) {
+    return async (): Promise<ComponentHealth> => {
+        const start = Date.now();
+        try {
+            await redis.ping();
+            return {
+                status: 'up',
+                responseTime: Date.now() - start,
+            };
+        } catch (error: any) {
+            return {
+                status: 'down',
+                message: error.message,
+            };
+        }
+    };
+}
+
+/**
+ * Create gRPC service health check function
+ */
+export function createGrpcHealthCheck(client: any, methodName: string = 'ping') {
+    return async (): Promise<ComponentHealth> => {
+        const start = Date.now();
+        try {
+            await client[methodName]({});
+            return {
+                status: 'up',
+                responseTime: Date.now() - start,
+            };
+        } catch (error: any) {
+            return {
+                status: 'down',
+                message: error.message,
+            };
+        }
+    };
+}

package/src/utils/logging-client.ts

@@ -0,0 +1,21 @@
+export class LoggingClient {
+    logInfo(message: string, context?: any) {
+        console.log(`[INFO] ${message}`, context || '');
+    }
+
+    logWarn(message: string, context?: any) {
+        console.warn(`[WARN] ${message}`, context || '');
+    }
+
+    logError(message: string, context?: any) {
+        console.error(`[ERROR] ${message}`, context || '');
+    }
+
+    logUserAction(userId: string, email: string, action: string, resource: string, details?: any) {
+        console.log(`[USER_ACTION] ${action} by ${email} (${userId}) on ${resource}`, details || '');
+    }
+
+    updateServiceStatus(serviceName: string, status: string, version: string, uptime: number, metadata?: string) {
+        console.log(`[SERVICE_STATUS] ${serviceName} is ${status} (v${version}, uptime: ${uptime}s)`, metadata || '');
+    }
+}