@takentrade/takentrade-libs 1.2.79 → 1.3.0

package/README.md

@@ -1,62 +1,53 @@
 # TakeNTrade Microservices Libraries
 
-This directory contains shared libraries used across the TakeNTrade microservices architecture. Below is a guide on how to use each library in your services.
+This package contains shared libraries used across the TakeNTrade microservices architecture. It provides authentication, caching, messaging, notifications, utilities, and common functionality to all services.
 
-## Cache Library (`@/libs/cache`)
-
-Redis-based caching implementation for the microservices.
+## Installation
 
-### Environment Variables
-
-Each service should have these Redis-related environment variables:
+```bash
+npm install @takentrade/takentrade-libs
+```
 
-- REDIS_HOST: Defaults to localhost
-- REDIS_PORT: Default to 6379
-- REDIS_USERNAME (Optional)
-- REDIS_PASSWORD (Optional)
+## Table of Contents
 
-### Usage
+- [Authentication & Authorization](#authentication--authorization)
+- [Cache Library (`@/libs/cache`)](#cache-library-libscache)
+- [BullMQ Library (`@/libs/bullmq`)](#bullmq-library-libsbullmq)
+- [NATS Library (`@/libs/nats`)](#nats-library-libsnats)
+- [Notification Client](#notification-client)
+- [Prisma Module](#prisma-module)
+- [RPC Utilities](#rpc-utilities)
+- [Common Utilities](#common-utilities)
+- [Utils Module](#utils-module)
+- [Configuration](#configuration)
 
-```typescript
-import { CacheModule, CacheService } from '@/libs/cache';
+---
 
-@Module({
-  imports: [
-    CacheModule.register()
-  ]
-})
+## Authentication & Authorization
 
-// In your service:
-constructor(private readonly cacheService: CacheService) {}
+### TNTBaseAuthGuard
 
-// Basic cache operations
-await this.cacheService.set('key', 'value', ttlSeconds);
-const value = await this.cacheService.get('key');
-await this.cacheService.del('key');
+A base implementation of the auth guard to be used across each service in the system.
 
-// Hash operations
-await this.cacheService.hset('key', 'field', 'value');
-const hashValue = await this.cacheService.hget('key', 'field');
-const allValues = await this.cacheService.hgetall('key');
-```
+#### Dependencies
 
-## TNTBaseAuthGuard
+- A JWT secret (provided via `ConfigService` or environment variable)
 
-A base implementation of the auth guard to be used across each service in the system
-
-### Dependencies:
-
-- A JWT secret.
-
-### Basic Usage
+#### Usage
 
 ```typescript
-import { TNTBaseAuthGuard } from '@takentrade/takentrade-libs';
+import {
+  TNTBaseAuthGuard,
+  Public,
+  Roles,
+  ROLES_KEY,
+} from '@takentrade/takentrade-libs';
+import { Reflector } from '@nestjs/core';
+import { ConfigService } from '@nestjs/config';
 
 /**
- * Create your own auth guard extending the TNTBaseAuthGuard. We
- * do this to put the TNTBaseAuthGuard in the same context as the
- * current NestJs application for better error capturing.
+ * Create your own auth guard extending the TNTBaseAuthGuard.
+ * This ensures the guard is in the same context as your NestJS application for better error capturing.
  */
 export class AuthGuard extends TNTBaseAuthGuard {
   constructor(
@@ -74,16 +65,116 @@ export class AuthGuard extends TNTBaseAuthGuard {
     return result;
   }
 }
+
+// In your controller
+@Controller('example')
+@UseGuards(AuthGuard)
+export class ExampleController {
+  // Public endpoint (no authentication required)
+  @Public()
+  @Get('public')
+  publicEndpoint() {
+    return { message: 'This is public' };
+  }
+
+  // Protected endpoint (authentication required)
+  @Get('protected')
+  protectedEndpoint() {
+    return { message: 'This requires authentication' };
+  }
+
+  // Role-based access control
+  @Roles('admin', 'moderator')
+  @Get('admin')
+  adminEndpoint() {
+    return { message: 'This requires admin or moderator role' };
+  }
+}
+```
+
+#### Decorators
+
+- **`@Public()`**: Marks a route as publicly accessible (bypasses authentication)
+- **`@Roles(...roles: string[])`**: Restricts access to routes based on user roles
+
+---
+
+## Cache Library (`@/libs/cache`)
+
+Redis-based caching implementation for the microservices.
+
+### Cache Environment Variables
+
+```env
+REDIS_HOST=localhost      # Default: localhost
+REDIS_PORT=6379           # Default: 6379
+REDIS_USERNAME=           # Optional
+REDIS_PASSWORD=           # Optional
 ```
 
+### Cache Usage
+
+```typescript
+import { CacheModule, CacheService } from '@takentrade/takentrade-libs';
+
+@Module({
+  imports: [CacheModule.register()],
+})
+export class AppModule {}
+
+// In your service
+@Injectable()
+export class MyService {
+  constructor(private readonly cacheService: CacheService) {}
+
+  // Basic cache operations
+  async example() {
+    // Set with TTL (time to live in seconds)
+    await this.cacheService.set('key', 'value', 3600); // expires in 1 hour
+
+    // Get value
+    const value = await this.cacheService.get('key');
+
+    // Delete key
+    await this.cacheService.del('key');
+
+    // Hash operations (Redis hashes)
+    await this.cacheService.hset('hash-key', 'field', 'value');
+    const hashValue = await this.cacheService.hget('hash-key', 'field');
+    const allValues = await this.cacheService.hgetall('hash-key');
+  }
+}
+```
+
+### Cache Methods
+
+- `set(key: string, value: any, ttlSeconds?: number)`: Set a key-value pair with optional TTL
+- `get(key: string)`: Get a value by key
+- `del(key: string)`: Delete a key
+- `hset(key: string, field: string, value: any)`: Set a hash field
+- `hget(key: string, field: string)`: Get a hash field value
+- `hgetall(key: string)`: Get all fields and values from a hash
+
+---
+
 ## BullMQ Library (`@/libs/bullmq`)
 
 Background job processing library for handling long-running tasks, retries, and scheduled jobs.
 
-### Usage
+### BullMQ Environment Variables
+
+```env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=your_password
+```
+
+### BullMQ Usage
 
 ```typescript
-import { BullmqModule } from '@/libs/bullmq';
+import { BullmqModule } from '@takentrade/takentrade-libs';
+import { Queue, Job } from 'bullmq';
+import { Inject } from '@nestjs/common';
 import { join } from 'path';
 
 // Register in your module
@@ -103,10 +194,9 @@ import { join } from 'path';
     }),
   ],
 })
+export class AppModule {}
 
 // Create a job processor (my.processor.ts)
-import { Job } from 'bullmq';
-
 export default async function myProcessor(job: Job) {
   try {
     console.log(`Processing job ${job.id}`);
@@ -124,19 +214,19 @@ export default async function myProcessor(job: Job) {
 export class MyService {
   constructor(
     @Inject('BullQueue_my-queue')
-    private myQueue: Queue,
+    private myQueue: Queue
   ) {}
 
   async addJob(data: any) {
     // Regular job
     await this.myQueue.add('job-name', data);
 
-    // Delayed job
+    // Delayed job (executes after 5 seconds)
     await this.myQueue.add('delayed-job', data, {
-      delay: 5000, // 5 seconds
+      delay: 5000,
     });
 
-    // Repeatable job
+    // Repeatable job (executes every minute)
     await this.myQueue.add('repeatable-job', data, {
       repeat: {
         every: 1000 * 60, // Every minute
@@ -146,7 +236,7 @@ export class MyService {
 }
 ```
 
-### Features
+### BullMQ Features
 
 1. **Queue Management**: Create, pause, resume, and clean queues
 2. **Job Processing**: Handle long-running tasks with progress tracking
@@ -155,62 +245,571 @@ export class MyService {
 5. **Event Handling**: Monitor job completion and failures
 6. **Resource Cleanup**: Automatic cleanup on application shutdown
 
-### Environment Variables
+---
+
+## NATS Library (`@/libs/nats`)
+
+NATS messaging utilities for microservice communication.
+
+### NATS Environment Variables
 
 ```env
-# BullMQ Configuration
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_PASSWORD=your_password
+NATS_URL=nats://localhost:4222
+NATS_SERVICE_QUEUE=service_queue  # Replace 'service' with your service name (e.g., payment_queue)
+```
+
+### NATS Usage
+
+```typescript
+import {
+  NatsSubjects,
+  NatsEventPattern,
+  NatsMessageDto,
+  NatsLoggingInterceptor,
+  NATS_CLIENT,
+  DEFAULT_NATS_CONFIG,
+} from '@takentrade/takentrade-libs';
+import { ClientProxy, Inject } from '@nestjs/common';
+
+// Event handler (listening to events)
+@Controller()
+export class MyController {
+  @NatsEventPattern(NatsSubjects.USER_CREATED)
+  async handleUserCreated(@Payload() data: NatsMessageDto) {
+    console.log('User created:', data);
+    // Handle the event
+  }
+
+  // Using the standard EventPattern with logging
+  @EventPattern('custom.event')
+  @UseInterceptors(NatsLoggingInterceptor)
+  async handleCustomEvent(@Payload() data: any) {
+    // Handle event
+  }
+}
+
+// Event publisher (sending events)
+@Injectable()
+export class MyService {
+  constructor(@Inject(NATS_CLIENT) private readonly natsClient: ClientProxy) {}
+
+  async publishEvent() {
+    this.natsClient.emit(NatsSubjects.USER_CREATED, {
+      userId: '123',
+      email: 'user@example.com',
+    });
+  }
+
+  // RPC request-response pattern
+  async requestData() {
+    const response = await this.natsClient
+      .send(NatsSubjects.GET_USER_BY_ID, { userId: '123' })
+      .toPromise();
+    return response;
+  }
+}
 ```
 
+### NATS Subjects
+
+The library provides a comprehensive enum of NATS subjects:
+
+```typescript
+import { NatsSubjects } from '@takentrade/takentrade-libs';
+
+// Available subjects include:
+NatsSubjects.USER_CREATED;
+NatsSubjects.SUBACCOUNT_UPDATE_AMOUNT;
+NatsSubjects.NOTIFICATION_SEND;
+NatsSubjects.AJO_CREATE;
+NatsSubjects.CHAT_GET_CONVERSATIONS;
+// ... and many more
+```
+
+### NATS Decorators
+
+- **`@NatsEventPattern(pattern: string)`**: Decorator for NATS event handlers with automatic logging
+- **`NatsLoggingInterceptor`**: Interceptor for logging NATS events
+
+---
+
 ## Notification Client
 
-Shared utilities, constants, interfaces, and enums used across services.
+Service for sending notifications via email, SMS, and push notifications.
+
+### Notification Client Usage
+
+```typescript
+import {
+  NotificationClientModule,
+  NotificationClient,
+} from '@takentrade/takentrade-libs';
+
+@Module({
+  imports: [NotificationClientModule],
+})
+export class AppModule {}
+
+// In your service
+@Injectable()
+export class MyService {
+  constructor(private readonly notificationClient: NotificationClient) {}
+
+  async sendNotifications() {
+    // Send SMS
+    await this.notificationClient.sendSms(
+      '+2341234567890',
+      'Your OTP is 123456'
+    );
+
+    // Send Email
+    await this.notificationClient.sendEmailVerificationMail(
+      'user@example.com',
+      {
+        name: 'John Doe',
+        verificationLink: 'https://example.com/verify?token=abc123',
+      }
+    );
+
+    // Send OTP Email
+    await this.notificationClient.sendOTPMail('user@example.com', {
+      name: 'John Doe',
+      otp: '123456',
+      purpose: 'phone_verification',
+    });
+
+    // Send Password Reset Email
+    await this.notificationClient.sendPasswordResetMail('user@example.com', {
+      name: 'John Doe',
+      resetLink: 'https://example.com/reset?token=abc123',
+    });
+
+    // Send Push Notification
+    await this.notificationClient.sendPushNotification({
+      userId: '123',
+      title: 'New Message',
+      body: 'You have a new message',
+      data: { messageId: '456' },
+    });
+  }
+}
+```
+
+### Notification Client Methods
+
+The `NotificationClient` provides numerous methods for different notification types:
+
+- Email notifications (verification, OTP, password reset, transaction alerts, etc.)
+- SMS notifications
+- Push notifications
+- Custom notifications
+
+---
+
+## Prisma Module
+
+Global Prisma service module for database access.
+
+### Prisma Usage
+
+```typescript
+import { PrismaModule, PrismaService } from '@takentrade/takentrade-libs';
+
+@Module({
+  imports: [PrismaModule], // Global module, available everywhere
+})
+export class AppModule {}
+
+// In your service
+@Injectable()
+export class MyService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async getUsers() {
+    return this.prisma.user.findMany();
+  }
+}
+```
+
+---
+
+## RPC Utilities
+
+Utilities for handling RPC (Request-Response) patterns in NATS.
+
+### RPC Usage
+
+```typescript
+import { TakeNTradeRpc, TakeNTradeRpcV2 } from '@takentrade/takentrade-libs';
+import { NatsContext } from '@nestjs/microservices';
+
+// RPC handler with automatic error handling
+@Controller()
+export class MyController {
+  @MessagePattern('get.user.by.id')
+  async getUserById(@Payload() data: any, @Ctx() ctx: NatsContext) {
+    return TakeNTradeRpc.handleRequest(
+      this.userService.findById(data.userId),
+      ctx
+    );
+  }
+
+  // Alternative version that returns error directly instead of RpcException
+  @MessagePattern('get.user.balance')
+  async getUserBalance(@Payload() data: any, @Ctx() ctx: NatsContext) {
+    return TakeNTradeRpcV2.handleRequest(
+      this.userService.getBalance(data.userId),
+      ctx
+    );
+  }
+}
 
-### Usage
+// RPC client (sending requests)
+@Injectable()
+export class MyService {
+  constructor(@Inject(NATS_CLIENT) private readonly natsClient: ClientProxy) {}
+
+  async getUserData(userId: string) {
+    const response = await TakeNTradeRpc.withReply(
+      this.natsClient.send('get.user.by.id', { userId })
+    );
+    return response.data;
+  }
+}
+```
+
+### RPC Classes
+
+- **`TakeNTradeRpc`**: Main RPC utility with automatic error handling that throws `RpcException`
+- **`TakeNTradeRpcV2`**: Alternative RPC utility that returns error objects instead of throwing exceptions
+
+---
+
+## Common Utilities
+
+### Common Constants
 
 ```typescript
 import {
   NOTIFICATION_QUEUE,
-  generateRandomString,
-  formatPhoneNumber,
+  AJO_QUEUE,
+  PAYMENT_QUEUE,
+  // ... and other queue constants
+} from '@takentrade/takentrade-libs';
+
+// Queue names for BullMQ
+const queueName = NOTIFICATION_QUEUE; // 'notification_queue'
+```
+
+### Common Enums
+
+```typescript
+import {
   OtpPurpose,
-  SwaggerConfig,
-} from '@/libs/common';
+  SubAccountType,
+  TicketStatus, // from common/enums
+  SupportActionType, // from common/enums
+} from '@takentrade/takentrade-libs';
+
+// OTP purposes
+const purpose: OtpPurpose = OtpPurpose.PHONE_VERIFICATION;
+
+// Subaccount types
+const accountType: SubAccountType = SubAccountType.SAVINGS_ACCOUNT;
+```
+
+### String Utilities
 
-// Use constants
-console.log(NOTIFICATION_QUEUE); // 'notification'
+```typescript
+import {
+  formatPhoneNumber,
+  maskPhoneNumber,
+} from '@takentrade/takentrade-libs';
 
-// Use utility functions
-const randomStr = generateRandomString();
-const formattedPhone = formatPhoneNumber('+2341234567890');
+// Format phone number to international format
+const formatted = formatPhoneNumber('08123456789'); // '2348123456789'
 
-// Use enums and interfaces
-const purpose: OtpPurpose = OtpPurpose.REGISTRATION;
+// Mask phone number for display
+const masked = maskPhoneNumber('+2348123456789'); // '2348******789'
 ```
 
-## Best Practices
+### Random Utilities
+
+```typescript
+import {
+  generateRandomString,
+  RandomStringOptions,
+} from '@takentrade/takentrade-libs';
+
+// Generate random string (default: 6 digits)
+const randomCode = generateRandomString(); // '123456'
+
+// Custom options
+const randomPassword = generateRandomString({
+  length: 12,
+  digits: true,
+  lowerCaseAlphabets: true,
+  upperCaseAlphabets: true,
+  specialChars: true,
+});
+```
+
+### Reference Utilities
+
+```typescript
+import { generateReference } from '@takentrade/takentrade-libs';
+
+// Generate unique reference string
+const ref = generateReference('TXN'); // 'TXN-1234567890-ABC'
+```
+
+### Circuit Breaker
+
+```typescript
+import {
+  CircuitBreakerModule,
+  CircuitBreakerService,
+} from '@takentrade/takentrade-libs';
+
+@Module({
+  imports: [CircuitBreakerModule],
+})
+export class AppModule {}
+
+@Injectable()
+export class MyService {
+  constructor(private readonly circuitBreaker: CircuitBreakerService) {}
+
+  async callExternalService() {
+    const breaker = this.circuitBreaker.createBreaker('external-api', {
+      failureThreshold: 5,
+      resetTimeout: 60000,
+    });
+
+    if (this.circuitBreaker.isOpen('external-api')) {
+      throw new Error('Circuit breaker is open');
+    }
+
+    try {
+      const result = await this.externalApiCall();
+      this.circuitBreaker.recordSuccess('external-api');
+      return result;
+    } catch (error) {
+      this.circuitBreaker.recordFailure('external-api');
+      throw error;
+    }
+  }
+}
+```
+
+### Health Module
+
+```typescript
+import { HealthModule } from '@takentrade/takentrade-libs';
+
+@Module({
+  imports: [HealthModule],
+})
+export class AppModule {}
+```
+
+The health module provides a `/health` endpoint for service health checks.
+
+---
+
+## Utils Module
+
+### DTOs
+
+```typescript
+import { PaginationDto } from '@takentrade/takentrade-libs';
+
+// Pagination DTO for request queries
+export class GetUsersDto extends PaginationDto {
+  @IsOptional()
+  @IsString()
+  search?: string;
+}
+```
+
+### Pipes
+
+```typescript
+import { PaginationQueryCleanerPipe } from '@takentrade/takentrade-libs';
+
+@Controller('users')
+export class UserController {
+  @Get()
+  async getUsers(
+    @Query(PaginationQueryCleanerPipe) query: any // Removes page and limit from query
+  ) {
+    // query object will not contain page and limit fields
+  }
+}
+```
+
+### Interceptors
 
-1. Always import from the library's main entry point (e.g., `@/libs/auth` not `@/libs/auth/src/*`)
-2. Use TypeScript types and interfaces provided by the libraries
-3. Follow the async/await pattern when working with services
-4. Configure modules properly in your service's root module
-5. Handle errors appropriately as most library functions are promise-based
+```typescript
+import { ResponseInterceptor } from '@takentrade/takentrade-libs';
+
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: ResponseInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+The `ResponseInterceptor` automatically wraps all responses in a standard format:
+
+```json
+{
+  "success": true,
+  "message": "Operation successful",
+  "data": {
+    /* your data */
+  },
+  "metadata": {
+    "path": "/api/users",
+    "requestId": "uuid",
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Filters
+
+```typescript
+import { HttpExceptionFilter } from '@takentrade/takentrade-libs';
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: HttpExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+The `HttpExceptionFilter` catches all exceptions and formats them consistently.
+
+### Validators
+
+```typescript
+import { ValidateNatsMessage } from '@takentrade/takentrade-libs';
+
+@Controller()
+export class MyController {
+  @EventPattern('user.created')
+  async handleUserCreated(
+    @Payload(ValidateNatsMessage(UserCreatedDto)) data: UserCreatedDto
+  ) {
+    // data is validated and typed
+  }
+}
+```
+
+### Response Utilities
+
+```typescript
+import { AppResponse } from '@takentrade/takentrade-libs';
+
+@Controller()
+export class MyController {
+  @Get('users')
+  async getUsers() {
+    const users = await this.userService.findAll();
+    return AppResponse.success(users, 'Users retrieved successfully');
+  }
+}
+```
+
+### Pagination Utilities
+
+```typescript
+import { paginate } from '@takentrade/takentrade-libs';
+
+const result = paginate([1, 2, 3, 4, 5], 1, 2);
+// Returns: { data: [1, 2], total: 5, page: 1, limit: 2, totalPages: 3 }
+```
+
+### OTP Utilities
+
+```typescript
+import { generateOTP, verifyOTP } from '@takentrade/takentrade-libs';
+
+// Generate OTP
+const otp = generateOTP(6); // 6-digit OTP
+
+// Verify OTP (with expiration)
+const isValid = verifyOTP(otp, storedOtp, expirationTime);
+```
+
+### Configuration Utilities
+
+```typescript
+import { getConfiguration } from '@takentrade/takentrade-libs';
+
+const config = getConfiguration();
+// Returns typed configuration object
+```
+
+---
 
 ## Configuration
 
 Most libraries require configuration through environment variables. Ensure these are set in your service's `.env` file:
 
 ```env
-# Cache Configuration
+# Cache & BullMQ Configuration
 REDIS_HOST=localhost
 REDIS_PORT=6379
+REDIS_USERNAME=
 REDIS_PASSWORD=your_password
 
 # NATS Configuration
 NATS_URL=nats://localhost:4222
-NATS_SERVICE_QUEUE=service_queue  # Replace 'service' with your service name (e.g., payment_queue)
+NATS_SERVICE_QUEUE=service_queue  # Replace 'service' with your service name
+
+# JWT Configuration
+JWT_SECRET=your_jwt_secret
 
-# Other configurations...
+# Database (for Prisma)
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
 ```
+
+---
+
+## Best Practices
+
+1. **Always import from the library's main entry point**: Use `@takentrade/takentrade-libs` instead of internal paths
+2. **Use TypeScript types and interfaces**: Take advantage of the provided types for better type safety
+3. **Follow async/await pattern**: Most library functions are promise-based
+4. **Configure modules properly**: Register modules in your service's root module
+5. **Handle errors appropriately**: Use the provided filters and interceptors for consistent error handling
+6. **Use constants for NATS subjects**: Always use `NatsSubjects` enum instead of hardcoding subject strings
+7. **Leverage RPC utilities**: Use `TakeNTradeRpc` for consistent RPC error handling
+
+---
+
+## Exports
+
+The package exports the following sub-paths:
+
+- `@takentrade/takentrade-libs` - Main entry point
+- `@takentrade/takentrade-libs/bullmq` - BullMQ module
+- `@takentrade/takentrade-libs/cache` - Cache module
+- `@takentrade/takentrade-libs/common` - Common utilities
+- `@takentrade/takentrade-libs/nats` - NATS utilities
+
+---
+
+## License
+
+MIT