@alacard-project/shared 1.0.10 → 1.1.0

package/src/dto/auth.dto.ts

@@ -1,5 +1,6 @@
 import { IsEmail, IsString, MinLength, IsEnum, IsOptional } from 'class-validator';
 import { UserRole } from '../enums/user.enum';
+import { ServiceTokenType, IdentifierType } from '../enums';
 
 export class RegisterDto {
     @IsEmail()
@@ -34,6 +35,32 @@ export class LoginDto {
     password!: string;
 }
 
+/**
+ * Employee Login DTO
+ * Used for employee authentication via email
+ */
+export class EmployeeLoginDto {
+    @IsEmail()
+    email!: string;
+
+    @IsString()
+    @MinLength(8)
+    password!: string;
+}
+
+/**
+ * Public Login DTO
+ * Used for client and partner authentication via username
+ */
+export class PublicLoginDto {
+    @IsString()
+    username!: string;
+
+    @IsString()
+    @MinLength(8)
+    password!: string;
+}
+
 export interface UserResponse {
     id: string;
     email: string;
@@ -105,3 +132,102 @@ export class ResetPasswordConfirmBody {
     @MinLength(8)
     newPassword!: string;
 }
+
+/**
+ * Logout DTO
+ */
+export class LogoutDto {
+    @IsString()
+    @IsOptional()
+    refreshToken?: string;
+
+    @IsString()
+    @IsOptional()
+    sessionId?: string;
+}
+
+export class RefreshTokenDto {
+    @IsString()
+    refreshToken!: string;
+}
+
+/**
+ * Service Token DTOs
+ */
+export class CreateServiceTokenDto {
+    @IsString()
+    serviceName!: string;
+
+    @IsEnum(ServiceTokenType)
+    type!: ServiceTokenType;
+
+    @IsOptional()
+    @IsString()
+    description?: string;
+
+    @IsOptional()
+    @IsString()
+    name?: string;
+
+    @IsString()
+    identityId!: string;
+
+    @IsOptional()
+    @IsString()
+    expiresInDays?: number;
+}
+
+export class ValidateServiceTokenDto {
+    @IsString()
+    token!: string;
+}
+
+/**
+ * Credential DTOs
+ */
+export class CreateCredentialDto {
+    @IsEnum(IdentifierType)
+    identifierType!: IdentifierType;
+
+    @IsString()
+    identifierValue!: string;
+
+    @IsString()
+    password!: string;
+
+    @IsString()
+    identityId!: string;
+}
+
+/**
+ * Session DTOs
+ */
+export class CreateSessionDto {
+    @IsString()
+    identityId!: string;
+
+    @IsOptional()
+    @IsString()
+    ipAddress?: string;
+
+    @IsOptional()
+    @IsString()
+    userAgent?: string;
+
+    @IsOptional()
+    @IsString()
+    deviceInfo?: string;
+}
+
+/**
+ * 2FA Verification DTO
+ */
+export class Verify2faDto {
+    @IsString()
+    challengeId!: string;
+
+    @IsString()
+    @MinLength(6)
+    code!: string;
+}
+

package/src/dto/card.dto.ts

@@ -3,7 +3,7 @@ import { Type } from 'class-transformer';
 
 export class CreateCardDto {
     @IsString()
-    cardNumber: string;
+    cardNumber!: string;
 
     @IsOptional()
     @IsString()

package/src/dto/client.dto.ts

@@ -4,10 +4,10 @@ import { RegisterDto } from './auth.dto';
 
 export class CreateClientContactDto {
     @IsString()
-    contactType: string;
+    contactType!: string;
 
     @IsString()
-    value: string;
+    value!: string;
 
     @IsOptional()
     @IsBoolean()
@@ -16,10 +16,10 @@ export class CreateClientContactDto {
 
 export class CreateClientDetailDto {
     @IsString()
-    detailType: string;
+    detailType!: string;
 
     @IsString()
-    value: string;
+    value!: string;
 
     @IsOptional()
     @IsBoolean()
@@ -28,21 +28,21 @@ export class CreateClientDetailDto {
 
 export class CreateClientDto {
     @IsString()
-    clientNumber: string;
+    clientNumber!: string;
 
     @IsOptional()
     @IsString()
     clientNumberFormatted?: string;
 
     @IsString()
-    clientType: string;
+    clientType!: string;
 
     @IsOptional()
     @IsString()
     shortName?: string;
 
     @IsString()
-    fullName: string;
+    fullName!: string;
 
     @IsOptional()
     @IsBoolean()

package/src/dto/index.ts

@@ -4,3 +4,5 @@ export * from './client.dto';
 export * from './transaction.dto';
 export * from './card.dto';
 export * from './partner.dto';
+export * from './user.dto';
+export * from './account.dto';

package/src/dto/logging.dto.ts

@@ -43,10 +43,10 @@ export class LogFilterDto {
 
 export class LogCleanupDto {
     @IsDateString()
-    startDate: string;
+    startDate!: string;
 
     @IsDateString()
-    endDate: string;
+    endDate!: string;
 
     @IsOptional()
     @IsString()
@@ -62,7 +62,7 @@ export class RetentionPeriodDto {
     @IsInt()
     @Min(1)
     @Max(365)
-    retentionDays: number;
+    retentionDays!: number;
 }
 
 export class UserActionFilterDto {

package/src/dto/partner.dto.ts

@@ -2,19 +2,16 @@ import { IsString, IsOptional, IsBoolean, ValidateNested, IsObject } from 'class
 import { Type } from 'class-transformer';
 import { RegisterDto } from './auth.dto';
 
-export class CreatePartnerDto {
+export class PartnerDto {
     @IsString()
-    name: string;
+    name!: string;
 
     @IsString()
-    type: string;
+    type!: string;
 
     @IsOptional()
     @IsBoolean()
     isActive?: boolean;
-
-    @IsOptional()
-    @ValidateNested()
     @IsObject()
     @Type(() => RegisterDto)
     adminUser?: RegisterDto;

package/src/dto/transaction.dto.ts

@@ -1,5 +1,6 @@
 import { IsString, IsOptional, IsNumber, Min, IsUUID } from 'class-validator';
 import { Type } from 'class-transformer';
+import type { JsonValue } from '../types/common.types';
 
 export class CreateTransactionDto {
     @IsOptional()
@@ -7,11 +8,11 @@ export class CreateTransactionDto {
     externalId?: string;
 
     @IsString()
-    cardId: string;
+    cardId!: string;
 
     @IsNumber()
     @Min(0)
-    amount: number;
+    amount!: number;
 
     @IsOptional()
     @IsString()
@@ -47,5 +48,5 @@ export class UpdateTransactionDto {
     status?: string;
 
     @IsOptional()
-    metadata?: any;
+    metadata?: JsonValue;
 }

package/src/dto/user.dto.ts

@@ -0,0 +1,28 @@
+import { IsEmail, IsEnum, IsOptional, IsString, IsUUID } from 'class-validator';
+import { UserRole } from '../enums';
+
+export class UserDto {
+    @IsUUID()
+    id!: string;
+
+    @IsEmail()
+    email!: string;
+
+    @IsString()
+    @IsOptional()
+    firstName?: string;
+
+    @IsString()
+    @IsOptional()
+    lastName?: string;
+
+    @IsEnum(UserRole)
+    role!: UserRole;
+
+    @IsString()
+    @IsOptional()
+    phoneNumber?: string;
+
+    createdAt!: Date;
+    updatedAt!: Date;
+}

package/src/enums/auth.enum.ts

@@ -0,0 +1,13 @@
+export enum CredentialStatus {
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+    LOCKED = 'LOCKED',
+    SUSPENDED = 'SUSPENDED',
+    DELETED = 'DELETED',
+}
+
+export enum ServiceTokenType {
+    API = 'API',
+    INTERNAL = 'INTERNAL',
+    WEBHOOK = 'WEBHOOK',
+}

package/src/enums/iam.enum.ts

@@ -0,0 +1,28 @@
+/**
+ * Subject Type Enum
+ * Defines the type of subject in the system (immutable after creation)
+ */
+export enum SubjectType {
+    EMPLOYEE = 'EMPLOYEE',
+    CLIENT = 'CLIENT',
+    PARTNER = 'PARTNER',
+}
+
+/**
+ * Identifier Type Enum
+ * Defines the type of login identifier used for authentication
+ */
+export enum IdentifierType {
+    EMAIL = 'EMAIL',
+    USERNAME = 'USERNAME',
+}
+
+/**
+ * Identity Status Enum
+ * Defines the status of an identity in the IAM system
+ */
+export enum IdentityStatus {
+    ACTIVE = 'ACTIVE',
+    BLOCKED = 'BLOCKED',
+    DELETED = 'DELETED',
+}

package/src/enums/index.ts

@@ -1,8 +1,10 @@
 export * from './env.enum';
 export * from './user.enum';
+export * from './iam.enum';
 export * from './health.enum';
 export * from './logging.enum';
 export * from './notification.enum';
 export * from './error.enum';
+export * from './auth.enum';
 export * from './permission.enum';
 export * from './events.enum';

package/src/filters/http-exception.filter.ts

@@ -0,0 +1,49 @@
+
+import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus, Logger } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+    private readonly logger = new Logger(HttpExceptionFilter.name);
+
+    catch(exception: unknown, host: ArgumentsHost) {
+        const ctx = host.switchToHttp();
+        const response = ctx.getResponse<Response>();
+        const request = ctx.getRequest<Request>();
+
+        const status =
+            exception instanceof HttpException
+                ? exception.getStatus()
+                : HttpStatus.INTERNAL_SERVER_ERROR;
+
+        const message =
+            exception instanceof HttpException
+                ? exception.getResponse()
+                : 'Internal server error';
+
+        // Determine the actual error message string
+        const errorMessage = typeof message === 'string'
+            ? message
+            : (message as any).message || message;
+
+        // Log the error
+        if (status >= 500) {
+            this.logger.error(
+                `[${request.method}] ${request.url} - ${status} - ${JSON.stringify(errorMessage)}`,
+                exception instanceof Error ? exception.stack : '',
+            );
+        } else {
+            this.logger.warn(
+                `[${request.method}] ${request.url} - ${status} - ${JSON.stringify(errorMessage)}`,
+            );
+        }
+
+        response.status(status).json({
+            statusCode: status,
+            timestamp: new Date().toISOString(),
+            path: request.url,
+            method: request.method,
+            error: errorMessage,
+        });
+    }
+}

package/src/filters/index.ts

@@ -0,0 +1,2 @@
+
+export * from './http-exception.filter';

package/src/index.ts

@@ -10,3 +10,8 @@ export * from './utils/proto-path';
 export * from './utils/user.utils';
 export * from './utils/app.utils';
 export * from './utils/health.utils';
+export * from './filters';
+export * from './interceptors';
+export * from './observability';
+export * from './resilience/resilience.module';
+export * from './resilience/circuit-breaker.service';

package/src/interceptors/index.ts

@@ -0,0 +1,3 @@
+
+export * from './logging.interceptor';
+export * from './transform.interceptor';

package/src/interceptors/logging.interceptor.ts

@@ -0,0 +1,37 @@
+
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { randomUUID } from 'crypto';
+import { Request, Response } from 'express';
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+    private readonly logger = new Logger(LoggingInterceptor.name);
+
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+        const httpContext = context.switchToHttp();
+        const request = httpContext.getRequest<Request>();
+        const response = httpContext.getResponse<Response>();
+
+        const userAgent = request.get('user-agent') || '';
+        const { ip, method, path: url } = request;
+
+        // Generate or retrieve Trace ID
+        const traceId = request.headers['x-request-id'] || randomUUID();
+        request.headers['x-request-id'] = traceId as string;
+        response.setHeader('x-request-id', traceId);
+
+        this.logger.log(`[${traceId}] Incoming Request: ${method} ${url} - ${userAgent} ${ip}`);
+
+        const now = Date.now();
+        return next
+            .handle()
+            .pipe(
+                tap(() => {
+                    const duration = Date.now() - now;
+                    this.logger.log(`[${traceId}] Response Sent: ${method} ${url} ${response.statusCode} - ${duration}ms`);
+                }),
+            );
+    }
+}

package/src/interceptors/transform.interceptor.ts

@@ -0,0 +1,21 @@
+
+import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+export interface Response<T> {
+    statusCode: number;
+    data: T;
+}
+
+@Injectable()
+export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
+        return next.handle().pipe(
+            map(data => ({
+                statusCode: context.switchToHttp().getResponse().statusCode,
+                data,
+            })),
+        );
+    }
+}

package/src/observability/index.ts

@@ -0,0 +1,3 @@
+
+export * from './metrics/metrics.module';
+export * from './tracing';

package/src/observability/metrics/metrics.module.ts

@@ -0,0 +1,16 @@
+
+import { Module } from '@nestjs/common';
+import { PrometheusModule } from '@willsoto/nestjs-prometheus';
+
+@Module({
+    imports: [
+        PrometheusModule.register({
+            path: '/metrics',
+            defaultMetrics: {
+                enabled: true,
+            },
+        }),
+    ],
+    exports: [PrometheusModule],
+})
+export class MetricsModule { }

package/src/observability/tracing.ts

@@ -0,0 +1,33 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { Logger } from '@nestjs/common';
+
+const logger = new Logger('Tracing');
+
+export function initTracing(serviceName: string) {
+    const otelExporterOtlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://jaeger:4318/v1/traces';
+
+    const traceExporter = new OTLPTraceExporter({
+        url: otelExporterOtlpEndpoint,
+    });
+
+    // Set service name via env var so auto-detection picks it up
+    process.env.OTEL_SERVICE_NAME = serviceName;
+
+    const sdk = new NodeSDK({
+        traceExporter,
+        instrumentations: [getNodeAutoInstrumentations()],
+    });
+
+    sdk.start();
+
+    logger.log(`Initialized tracing for ${serviceName} sending to ${otelExporterOtlpEndpoint}`);
+
+    process.on('SIGTERM', () => {
+        sdk.shutdown()
+            .then(() => console.log('Tracing terminated'))
+            .catch((error) => console.log('Error terminating tracing', error))
+            .finally(() => process.exit(0));
+    });
+}

package/src/resilience/circuit-breaker.service.ts

@@ -0,0 +1,46 @@
+import { Injectable, Logger } from '@nestjs/common';
+import CircuitBreaker = require('opossum');
+
+@Injectable()
+export class CircuitBreakerService {
+    private readonly logger = new Logger(CircuitBreakerService.name);
+    private readonly breakers = new Map<string, CircuitBreaker>();
+
+    /**
+     * Execute an async action through a circuit breaker.
+     * @param key Unique key for the breaker (e.g., service URL)
+     * @param action The async action to execute
+     * @param options Circuit Breaker options
+     */
+    async execute<T>(
+        key: string,
+        action: () => Promise<T>,
+        options?: CircuitBreaker.Options
+    ): Promise<T> {
+        let breaker = this.breakers.get(key);
+
+        if (!breaker) {
+            const defaultOptions: CircuitBreaker.Options = {
+                timeout: 5000,
+                errorThresholdPercentage: 50,
+                resetTimeout: 10000,
+                ...options,
+            };
+
+            // Wrap a pass-through function to allow dynamic actions
+            const passThrough = async (promiseFactory: () => Promise<T>) => promiseFactory();
+            breaker = new CircuitBreaker(passThrough, defaultOptions);
+            this.bindEvents(breaker, key);
+            this.breakers.set(key, breaker);
+        }
+
+        return breaker.fire(action) as Promise<T>;
+    }
+
+    private bindEvents(breaker: CircuitBreaker, key: string) {
+        breaker.on('open', () => this.logger.warn(`Circuit Breaker OPEN for ${key}`));
+        breaker.on('halfOpen', () => this.logger.log(`Circuit Breaker HALF-OPEN for ${key}`));
+        breaker.on('close', () => this.logger.log(`Circuit Breaker CLOSED for ${key}`));
+        breaker.on('fallback', () => this.logger.warn(`Circuit Breaker FALLBACK for ${key}`));
+    }
+}

package/src/resilience/resilience.module.ts

@@ -0,0 +1,9 @@
+import { Module, Global } from '@nestjs/common';
+import { CircuitBreakerService } from './circuit-breaker.service';
+
+@Global()
+@Module({
+    providers: [CircuitBreakerService],
+    exports: [CircuitBreakerService],
+})
+export class ResilienceModule { }

package/src/types/auth.types.ts

@@ -1,7 +1,10 @@
-export interface JwtPayload {
+import { JsonObject, JsonValue } from './common.types';
+import { SubjectType } from '../enums/iam.enum';
+export interface JwtPayload extends JsonObject {
     sub: string;
-    email: string;
+    email?: string;
     role: string;
+    subjectType: SubjectType;
     scopes: string[];
     iat?: number;
     exp?: number;
@@ -14,6 +17,22 @@ export interface JwtTokens {
 }
 
 export interface AuthenticatedRequest {
-    user: any;
-    [key: string]: any;
+    user: JwtPayload;
+    [key: string]: JsonValue;
+}
+export interface ValidateServiceTokenResponse {
+    isValid: boolean;
+    identityId?: string;
+    tokenId?: string;
+}
+
+export interface Session {
+    sessionId: string;
+    identityId: string;
+    ipAddress?: string;
+    userAgent?: string;
+    deviceInfo?: string;
+    createdAt: Date;
+    expiresAt: Date;
+    isRevoked?: boolean;
 }

package/src/types/common.types.ts

@@ -0,0 +1,18 @@
+export type JsonPrimitive = string | number | boolean | null | undefined;
+
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+
+export interface JsonArray extends Array<JsonValue> { }
+
+export type JsonValue =
+    | JsonPrimitive
+    | JsonObject
+    | JsonArray;
+
+export interface Metadata {
+    [key: string]: JsonValue;
+}
+
+export type MetricType = 'counter' | 'gauge' | 'histogram' | 'summary';