@takentrade/takentrade-libs 2.0.8 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/LICENSE +87 -0
  2. package/README.md +113 -743
  3. package/dist/auth/auth.interface.d.ts +8 -0
  4. package/dist/auth/auth.interface.js +2 -0
  5. package/dist/auth/decorators/get-user.decorator.d.ts +2 -0
  6. package/dist/auth/decorators/get-user.decorator.js +26 -0
  7. package/dist/auth/decorators/index.d.ts +1 -0
  8. package/dist/auth/decorators/index.js +1 -0
  9. package/dist/auth/index.d.ts +1 -0
  10. package/dist/auth/index.js +1 -0
  11. package/dist/common/health/health.controller.js +0 -2
  12. package/dist/common/index.d.ts +0 -2
  13. package/dist/common/index.js +0 -2
  14. package/dist/index.d.ts +3 -0
  15. package/dist/index.js +3 -0
  16. package/dist/metrics/circuit-breaker-metrics.service.d.ts +61 -0
  17. package/dist/metrics/circuit-breaker-metrics.service.js +149 -0
  18. package/dist/metrics/index.d.ts +5 -0
  19. package/dist/metrics/index.js +21 -0
  20. package/dist/metrics/metrics-registry.d.ts +50 -0
  21. package/dist/metrics/metrics-registry.js +156 -0
  22. package/dist/metrics/metrics-updater.d.ts +32 -0
  23. package/dist/metrics/metrics-updater.js +102 -0
  24. package/dist/metrics/metrics.controller.d.ts +11 -0
  25. package/dist/metrics/metrics.controller.js +32 -0
  26. package/dist/metrics/metrics.interface.d.ts +53 -0
  27. package/dist/metrics/metrics.interface.js +23 -0
  28. package/dist/metrics/metrics.module.d.ts +11 -0
  29. package/dist/metrics/metrics.module.js +39 -0
  30. package/dist/metrics/metrics.service.d.ts +50 -0
  31. package/dist/metrics/metrics.service.js +165 -0
  32. package/dist/monitoring/alerting.service.d.ts +82 -0
  33. package/dist/monitoring/alerting.service.js +290 -0
  34. package/dist/monitoring/index.d.ts +5 -0
  35. package/dist/monitoring/index.js +21 -0
  36. package/dist/monitoring/monitoring.interface.d.ts +102 -0
  37. package/dist/monitoring/monitoring.interface.js +10 -0
  38. package/dist/monitoring/monitoring.module.d.ts +8 -0
  39. package/dist/monitoring/monitoring.module.js +44 -0
  40. package/dist/monitoring/sentry.service.d.ts +65 -0
  41. package/dist/monitoring/sentry.service.js +218 -0
  42. package/dist/monitoring/uptime.service.d.ts +59 -0
  43. package/dist/monitoring/uptime.service.js +213 -0
  44. package/dist/resilience/circuit-breaker-event-handler.d.ts +16 -0
  45. package/dist/resilience/circuit-breaker-event-handler.js +70 -0
  46. package/dist/resilience/circuit-breaker-factory.d.ts +19 -0
  47. package/dist/resilience/circuit-breaker-factory.js +51 -0
  48. package/dist/resilience/circuit-breaker-stats.service.d.ts +37 -0
  49. package/dist/resilience/circuit-breaker-stats.service.js +69 -0
  50. package/dist/resilience/circuit-breaker.interface.d.ts +59 -0
  51. package/dist/resilience/circuit-breaker.interface.js +25 -0
  52. package/dist/{common/circuit-breaker → resilience}/circuit-breaker.module.js +1 -0
  53. package/dist/resilience/circuit-breaker.service.d.ts +119 -0
  54. package/dist/resilience/circuit-breaker.service.js +234 -0
  55. package/dist/resilience/index.d.ts +3 -0
  56. package/dist/resilience/index.js +19 -0
  57. package/dist/tsconfig.tsbuildinfo +1 -1
  58. package/dist/utils/dto/pagination.js +0 -6
  59. package/dist/utils/helpers/date.util.d.ts +8 -0
  60. package/dist/utils/helpers/date.util.js +30 -0
  61. package/dist/utils/helpers/decimal.util.d.ts +9 -0
  62. package/dist/utils/helpers/decimal.util.js +31 -0
  63. package/dist/utils/helpers/referral.util.d.ts +4 -0
  64. package/dist/utils/helpers/referral.util.js +53 -0
  65. package/dist/utils/helpers/role.util.d.ts +8 -0
  66. package/dist/utils/helpers/role.util.js +18 -0
  67. package/dist/utils/index.d.ts +4 -0
  68. package/dist/utils/index.js +4 -0
  69. package/package.json +8 -2
  70. package/dist/common/circuit-breaker/circuit-breaker.service.d.ts +0 -13
  71. package/dist/common/circuit-breaker/circuit-breaker.service.js +0 -120
  72. package/dist/common/circuit-breaker/circuit-breaker.types.d.ts +0 -19
  73. package/dist/common/circuit-breaker/circuit-breaker.types.js +0 -9
  74. /package/dist/{common/circuit-breaker → resilience}/circuit-breaker.module.d.ts +0 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # TakeNTrade Microservices Libraries
2
2
 
3
- This package contains shared libraries used across the TakeNTrade microservices architecture. It provides authentication, caching, messaging, notifications, utilities, and common functionality to all services.
3
+ Shared libraries for the TakeNTrade microservices architecture, providing authentication, caching, messaging, notifications, resilience patterns, metrics, and common utilities.
4
4
 
5
5
  ## Installation
6
6
 
@@ -8,808 +8,178 @@ This package contains shared libraries used across the TakeNTrade microservices
8
8
  npm install @takentrade/takentrade-libs
9
9
  ```
10
10
 
11
- ## Table of Contents
12
-
13
- - [Authentication & Authorization](#authentication--authorization)
14
- - [Cache Library (`@/libs/cache`)](#cache-library-libscache)
15
- - [BullMQ Library (`@/libs/bullmq`)](#bullmq-library-libsbullmq)
16
- - [NATS Library (`@/libs/nats`)](#nats-library-libsnats)
17
- - [Notification Client](#notification-client)
18
- - [Prisma Module](#prisma-module)
19
- - [RPC Utilities](#rpc-utilities)
20
- - [Common Utilities](#common-utilities)
21
- - [Utils Module](#utils-module)
22
- - [Configuration](#configuration)
23
-
24
- ---
25
-
26
- ## Authentication & Authorization
27
-
28
- ### TNTBaseAuthGuard
29
-
30
- A base implementation of the auth guard to be used across each service in the system.
31
-
32
- #### Dependencies
33
-
34
- - A JWT secret (provided via `ConfigService` or environment variable)
35
-
36
- #### Usage
11
+ ## Quick Start
37
12
 
38
13
  ```typescript
39
14
  import {
40
- TNTBaseAuthGuard,
41
- Public,
42
- Roles,
43
- ROLES_KEY,
15
+ CacheModule,
16
+ MetricsModule,
17
+ CircuitBreakerModule,
44
18
  } from '@takentrade/takentrade-libs';
45
- import { Reflector } from '@nestjs/core';
46
- import { ConfigService } from '@nestjs/config';
47
-
48
- /**
49
- * Create your own auth guard extending the TNTBaseAuthGuard.
50
- * This ensures the guard is in the same context as your NestJS application for better error capturing.
51
- */
52
- export class AuthGuard extends TNTBaseAuthGuard {
53
- constructor(
54
- private reflector: Reflector,
55
- private configService: ConfigService
56
- ) {
57
- super(reflector);
58
- }
59
-
60
- async canActivate(context: ExecutionContext): Promise<boolean> {
61
- const result = await super.canActivate(
62
- context,
63
- this.configService.get('JWT_SECRET') as string
64
- );
65
- return result;
66
- }
67
- }
68
-
69
- // In your controller
70
- @Controller('example')
71
- @UseGuards(AuthGuard)
72
- export class ExampleController {
73
- // Public endpoint (no authentication required)
74
- @Public()
75
- @Get('public')
76
- publicEndpoint() {
77
- return { message: 'This is public' };
78
- }
79
-
80
- // Protected endpoint (authentication required)
81
- @Get('protected')
82
- protectedEndpoint() {
83
- return { message: 'This requires authentication' };
84
- }
85
-
86
- // Role-based access control
87
- @Roles('admin', 'moderator')
88
- @Get('admin')
89
- adminEndpoint() {
90
- return { message: 'This requires admin or moderator role' };
91
- }
92
- }
93
- ```
94
-
95
- #### Decorators
96
-
97
- - **`@Public()`**: Marks a route as publicly accessible (bypasses authentication)
98
- - **`@Roles(...roles: string[])`**: Restricts access to routes based on user roles
99
-
100
- ---
101
-
102
- ## Cache Library (`@/libs/cache`)
103
-
104
- Redis-based caching implementation for the microservices.
105
-
106
- ### Cache Environment Variables
107
-
108
- ```env
109
- REDIS_HOST=localhost # Default: localhost
110
- REDIS_PORT=6379 # Default: 6379
111
- REDIS_USERNAME= # Optional
112
- REDIS_PASSWORD= # Optional
113
- ```
114
-
115
- ### Cache Usage
116
-
117
- ```typescript
118
- import { CacheModule, CacheService } from '@takentrade/takentrade-libs';
119
19
 
120
- @Module({
121
- imports: [CacheModule.register()],
122
- })
123
- export class AppModule {}
124
-
125
- // In your service
126
- @Injectable()
127
- export class MyService {
128
- constructor(private readonly cacheService: CacheService) {}
129
-
130
- // Basic cache operations
131
- async example() {
132
- // Set with TTL (time to live in seconds)
133
- await this.cacheService.set('key', 'value', 3600); // expires in 1 hour
134
-
135
- // Get value
136
- const value = await this.cacheService.get('key');
137
-
138
- // Delete key
139
- await this.cacheService.del('key');
140
-
141
- // Hash operations (Redis hashes)
142
- await this.cacheService.hset('hash-key', 'field', 'value');
143
- const hashValue = await this.cacheService.hget('hash-key', 'field');
144
- const allValues = await this.cacheService.hgetall('hash-key');
145
- }
146
- }
147
- ```
148
-
149
- ### Cache Methods
150
-
151
- - `set(key: string, value: any, ttlSeconds?: number)`: Set a key-value pair with optional TTL
152
- - `get(key: string)`: Get a value by key
153
- - `del(key: string)`: Delete a key
154
- - `hset(key: string, field: string, value: any)`: Set a hash field
155
- - `hget(key: string, field: string)`: Get a hash field value
156
- - `hgetall(key: string)`: Get all fields and values from a hash
157
-
158
- ---
159
-
160
- ## BullMQ Library (`@/libs/bullmq`)
161
-
162
- Background job processing library for handling long-running tasks, retries, and scheduled jobs.
163
-
164
- ### BullMQ Environment Variables
165
-
166
- ```env
167
- REDIS_HOST=localhost
168
- REDIS_PORT=6379
169
- REDIS_PASSWORD=your_password
170
- ```
171
-
172
- ### BullMQ Usage
173
-
174
- ```typescript
175
- import { BullmqModule } from '@takentrade/takentrade-libs';
176
- import { Queue, Job } from 'bullmq';
177
- import { Inject } from '@nestjs/common';
178
- import { join } from 'path';
179
-
180
- // Register in your module
181
20
  @Module({
182
21
  imports: [
183
- BullmqModule.forFeature({
184
- queueName: 'my-queue',
185
- processorPath: join(__dirname, 'processors', 'my.processor.js'),
186
- concurrency: 3,
187
- defaultJobOptions: {
188
- attempts: 3,
189
- backoff: {
190
- type: 'exponential',
191
- delay: 1000,
192
- },
193
- },
194
- }),
22
+ CacheModule.register(),
23
+ MetricsModule.register({ defaultMetrics: true }),
24
+ CircuitBreakerModule,
195
25
  ],
196
26
  })
197
27
  export class AppModule {}
198
-
199
- // Create a job processor (my.processor.ts)
200
- export default async function myProcessor(job: Job) {
201
- try {
202
- console.log(`Processing job ${job.id}`);
203
- await job.updateProgress(50);
204
- // Your job logic here
205
- return { processed: true };
206
- } catch (error) {
207
- console.error(`Error processing job ${job.id}:`, error);
208
- throw error;
209
- }
210
- }
211
-
212
- // In your service
213
- @Injectable()
214
- export class MyService {
215
- constructor(
216
- @Inject('BullQueue_my-queue')
217
- private myQueue: Queue
218
- ) {}
219
-
220
- async addJob(data: any) {
221
- // Regular job
222
- await this.myQueue.add('job-name', data);
223
-
224
- // Delayed job (executes after 5 seconds)
225
- await this.myQueue.add('delayed-job', data, {
226
- delay: 5000,
227
- });
228
-
229
- // Repeatable job (executes every minute)
230
- await this.myQueue.add('repeatable-job', data, {
231
- repeat: {
232
- every: 1000 * 60, // Every minute
233
- },
234
- });
235
- }
236
- }
237
28
  ```
238
29
 
239
- ### BullMQ Features
30
+ ## Modules
240
31
 
241
- 1. **Queue Management**: Create, pause, resume, and clean queues
242
- 2. **Job Processing**: Handle long-running tasks with progress tracking
243
- 3. **Automatic Retries**: Configure retry attempts and backoff strategies
244
- 4. **Job Scheduling**: Delayed and repeatable jobs
245
- 5. **Event Handling**: Monitor job completion and failures
246
- 6. **Resource Cleanup**: Automatic cleanup on application shutdown
32
+ | Module | Description | Documentation |
33
+ | ------------------ | ---------------------------------------------- | ---------------------------------------------- |
34
+ | **Authentication** | Route protection and role-based access control | [docs/auth.md](docs/auth.md) |
35
+ | **Cache** | Redis-based caching with TTL support | [docs/cache.md](docs/cache.md) |
36
+ | **BullMQ** | Background job processing and queues | [docs/bullmq.md](docs/bullmq.md) |
37
+ | **NATS** | Microservice messaging and event streaming | [docs/nats.md](docs/nats.md) |
38
+ | **Notifications** | Email, SMS, and push notifications | [docs/notifications.md](docs/notifications.md) |
39
+ | **RPC** | Request-response patterns for NATS | [docs/rpc.md](docs/rpc.md) |
40
+ | **Resilience** | Circuit breakers for fault tolerance | [docs/resilience.md](docs/resilience.md) |
41
+ | **Metrics** | Prometheus metrics collection | [docs/metrics.md](docs/metrics.md) |
42
+ | **Monitoring** | Error tracking, alerting, uptime monitoring | [docs/monitoring.md](docs/monitoring.md) |
43
+ | **Common** | Shared constants, enums, and utilities | [docs/common.md](docs/common.md) |
44
+ | **Utils** | DTOs, pipes, filters, and helpers | [docs/utils.md](docs/utils.md) |
247
45
 
248
- ---
46
+ ## Features
249
47
 
250
- ## NATS Library (`@/libs/nats`)
48
+ ### 🔐 Authentication & Authorization
251
49
 
252
- NATS messaging utilities for microservice communication.
50
+ - `@Public()` and `@Roles()` decorators
51
+ - JWT-based authentication support
52
+ - Role-based access control
253
53
 
254
- ### NATS Environment Variables
54
+ ### 💾 Caching
255
55
 
256
- ```env
257
- NATS_URL=nats://localhost:4222
258
- NATS_SERVICE_QUEUE=service_queue # Replace 'service' with your service name (e.g., payment_queue)
259
- ```
260
-
261
- ### NATS Usage
262
-
263
- ```typescript
264
- import {
265
- NatsSubjects,
266
- NatsEventPattern,
267
- NatsMessageDto,
268
- NatsLoggingInterceptor,
269
- NATS_CLIENT,
270
- DEFAULT_NATS_CONFIG,
271
- } from '@takentrade/takentrade-libs';
272
- import { ClientProxy, Inject } from '@nestjs/common';
273
-
274
- // Event handler (listening to events)
275
- @Controller()
276
- export class MyController {
277
- @NatsEventPattern(NatsSubjects.USER_CREATED)
278
- async handleUserCreated(@Payload() data: NatsMessageDto) {
279
- console.log('User created:', data);
280
- // Handle the event
281
- }
282
-
283
- // Using the standard EventPattern with logging
284
- @EventPattern('custom.event')
285
- @UseInterceptors(NatsLoggingInterceptor)
286
- async handleCustomEvent(@Payload() data: any) {
287
- // Handle event
288
- }
289
- }
290
-
291
- // Event publisher (sending events)
292
- @Injectable()
293
- export class MyService {
294
- constructor(@Inject(NATS_CLIENT) private readonly natsClient: ClientProxy) {}
295
-
296
- async publishEvent() {
297
- this.natsClient.emit(NatsSubjects.USER_CREATED, {
298
- userId: '123',
299
- email: 'user@example.com',
300
- });
301
- }
302
-
303
- // RPC request-response pattern
304
- async requestData() {
305
- const response = await this.natsClient
306
- .send(NatsSubjects.GET_USER_BY_ID, { userId: '123' })
307
- .toPromise();
308
- return response;
309
- }
310
- }
311
- ```
312
-
313
- ### NATS Subjects
56
+ - Redis integration with ioredis
57
+ - TTL support
58
+ - Hash operations
59
+ - Auto-reconnection
314
60
 
315
- The library provides a comprehensive enum of NATS subjects:
61
+ ### 📊 Metrics & Observability
316
62
 
317
- ```typescript
318
- import { NatsSubjects } from '@takentrade/takentrade-libs';
319
-
320
- // Available subjects include:
321
- NatsSubjects.USER_CREATED;
322
- NatsSubjects.SUBACCOUNT_UPDATE_AMOUNT;
323
- NatsSubjects.NOTIFICATION_SEND;
324
- NatsSubjects.AJO_CREATE;
325
- NatsSubjects.CHAT_GET_CONVERSATIONS;
326
- // ... and many more
327
- ```
63
+ - Prometheus metrics with prom-client
64
+ - Default process metrics (CPU, memory, event loop)
65
+ - Custom counters, gauges, histograms, summaries
66
+ - Circuit breaker metrics integration
67
+ - `/metrics` endpoint for scraping
328
68
 
329
- ### NATS Decorators
69
+ ### 🔄 Resilience
330
70
 
331
- - **`@NatsEventPattern(pattern: string)`**: Decorator for NATS event handlers with automatic logging
332
- - **`NatsLoggingInterceptor`**: Interceptor for logging NATS events
71
+ - Circuit breakers using Opossum
72
+ - Automatic failure detection
73
+ - Fallback support
74
+ - Health checks
75
+ - Request caching
76
+ - Comprehensive metrics
333
77
 
334
- ---
78
+ ### 🚀 Background Jobs
335
79
 
336
- ## Notification Client
80
+ - BullMQ integration
81
+ - Job scheduling and retries
82
+ - Delayed and repeatable jobs
83
+ - Progress tracking
337
84
 
338
- Service for sending notifications via email, SMS, and push notifications.
85
+ ### 📨 Messaging
339
86
 
340
- ### Notification Client Usage
87
+ - NATS integration
88
+ - Event patterns
89
+ - Request-response (RPC)
90
+ - Subject constants
91
+ - Automatic logging
341
92
 
342
- ```typescript
343
- import {
344
- NotificationClientModule,
345
- NotificationClient,
346
- } from '@takentrade/takentrade-libs';
93
+ ### 📧 Notifications
347
94
 
348
- @Module({
349
- imports: [NotificationClientModule],
350
- })
351
- export class AppModule {}
352
-
353
- // In your service
354
- @Injectable()
355
- export class MyService {
356
- constructor(private readonly notificationClient: NotificationClient) {}
357
-
358
- async sendNotifications() {
359
- // Send SMS
360
- await this.notificationClient.sendSms(
361
- '+2341234567890',
362
- 'Your OTP is 123456'
363
- );
364
-
365
- // Send Email
366
- await this.notificationClient.sendEmailVerificationMail(
367
- 'user@example.com',
368
- {
369
- name: 'John Doe',
370
- verificationLink: 'https://example.com/verify?token=abc123',
371
- }
372
- );
373
-
374
- // Send OTP Email
375
- await this.notificationClient.sendOTPMail('user@example.com', {
376
- name: 'John Doe',
377
- otp: '123456',
378
- purpose: 'phone_verification',
379
- });
380
-
381
- // Send Password Reset Email
382
- await this.notificationClient.sendPasswordResetMail('user@example.com', {
383
- name: 'John Doe',
384
- resetLink: 'https://example.com/reset?token=abc123',
385
- });
386
-
387
- // Send Push Notification
388
- await this.notificationClient.sendPushNotification({
389
- userId: '123',
390
- title: 'New Message',
391
- body: 'You have a new message',
392
- data: { messageId: '456' },
393
- });
394
- }
395
- }
396
- ```
397
-
398
- ### Notification Client Methods
399
-
400
- The `NotificationClient` provides numerous methods for different notification types:
401
-
402
- - Email notifications (verification, OTP, password reset, transaction alerts, etc.)
95
+ - Email (verification, OTP, password reset, etc.)
403
96
  - SMS notifications
404
97
  - Push notifications
405
- - Custom notifications
406
-
407
- ---
98
+ - Template support
408
99
 
409
- ## Prisma Module
100
+ ## Environment Variables
410
101
 
411
- Global Prisma service module for database access.
412
-
413
- ### Prisma Usage
414
-
415
- ```typescript
416
- import { PrismaModule, PrismaService } from '@takentrade/takentrade-libs';
417
-
418
- @Module({
419
- imports: [PrismaModule], // Global module, available everywhere
420
- })
421
- export class AppModule {}
422
-
423
- // In your service
424
- @Injectable()
425
- export class MyService {
426
- constructor(private readonly prisma: PrismaService) {}
427
-
428
- async getUsers() {
429
- return this.prisma.user.findMany();
430
- }
431
- }
432
- ```
433
-
434
- ---
435
-
436
- ## RPC Utilities
437
-
438
- Utilities for handling RPC (Request-Response) patterns in NATS.
439
-
440
- ### RPC Usage
441
-
442
- ```typescript
443
- import { TakeNTradeRpc, TakeNTradeRpcV2 } from '@takentrade/takentrade-libs';
444
- import { NatsContext } from '@nestjs/microservices';
445
-
446
- // RPC handler with automatic error handling
447
- @Controller()
448
- export class MyController {
449
- @MessagePattern('get.user.by.id')
450
- async getUserById(@Payload() data: any, @Ctx() ctx: NatsContext) {
451
- return TakeNTradeRpc.handleRequest(
452
- this.userService.findById(data.userId),
453
- ctx
454
- );
455
- }
456
-
457
- // Alternative version that returns error directly instead of RpcException
458
- @MessagePattern('get.user.balance')
459
- async getUserBalance(@Payload() data: any, @Ctx() ctx: NatsContext) {
460
- return TakeNTradeRpcV2.handleRequest(
461
- this.userService.getBalance(data.userId),
462
- ctx
463
- );
464
- }
465
- }
466
-
467
- // RPC client (sending requests)
468
- @Injectable()
469
- export class MyService {
470
- constructor(@Inject(NATS_CLIENT) private readonly natsClient: ClientProxy) {}
471
-
472
- async getUserData(userId: string) {
473
- const response = await TakeNTradeRpc.withReply(
474
- this.natsClient.send('get.user.by.id', { userId })
475
- );
476
- return response.data;
477
- }
478
- }
479
- ```
480
-
481
- ### RPC Classes
482
-
483
- - **`TakeNTradeRpc`**: Main RPC utility with automatic error handling that throws `RpcException`
484
- - **`TakeNTradeRpcV2`**: Alternative RPC utility that returns error objects instead of throwing exceptions
485
-
486
- ---
487
-
488
- ## Common Utilities
489
-
490
- ### Common Constants
102
+ ```env
103
+ # Cache & BullMQ
104
+ REDIS_HOST=localhost
105
+ REDIS_PORT=6379
106
+ REDIS_PASSWORD=your_password
491
107
 
492
- ```typescript
493
- import {
494
- NOTIFICATION_QUEUE,
495
- AJO_QUEUE,
496
- PAYMENT_QUEUE,
497
- // ... and other queue constants
498
- } from '@takentrade/takentrade-libs';
108
+ # NATS
109
+ NATS_URL=nats://localhost:4222
110
+ NATS_SERVICE_QUEUE=service_queue
499
111
 
500
- // Queue names for BullMQ
501
- const queueName = NOTIFICATION_QUEUE; // 'notification_queue'
112
+ # JWT
113
+ JWT_SECRET=your_jwt_secret
502
114
  ```
503
115
 
504
- ### Common Enums
116
+ ## Usage Examples
505
117
 
506
- ```typescript
507
- import {
508
- OtpPurpose,
509
- SubAccountType,
510
- TicketStatus, // from common/enums
511
- SupportActionType, // from common/enums
512
- } from '@takentrade/takentrade-libs';
513
-
514
- // OTP purposes
515
- const purpose: OtpPurpose = OtpPurpose.PHONE_VERIFICATION;
516
-
517
- // Subaccount types
518
- const accountType: SubAccountType = SubAccountType.SAVINGS_ACCOUNT;
519
- ```
520
-
521
- ### String Utilities
118
+ ### Cache
522
119
 
523
120
  ```typescript
524
- import {
525
- formatPhoneNumber,
526
- maskPhoneNumber,
527
- } from '@takentrade/takentrade-libs';
528
-
529
- // Format phone number to international format
530
- const formatted = formatPhoneNumber('08123456789'); // '2348123456789'
531
-
532
- // Mask phone number for display
533
- const masked = maskPhoneNumber('+2348123456789'); // '2348******789'
121
+ await this.cacheService.set('key', 'value', 3600); // 1 hour TTL
122
+ const value = await this.cacheService.get('key');
534
123
  ```
535
124
 
536
- ### Random Utilities
125
+ ### Metrics
537
126
 
538
127
  ```typescript
539
- import {
540
- generateRandomString,
541
- RandomStringOptions,
542
- } from '@takentrade/takentrade-libs';
543
-
544
- // Generate random string (default: 6 digits)
545
- const randomCode = generateRandomString(); // '123456'
546
-
547
- // Custom options
548
- const randomPassword = generateRandomString({
549
- length: 12,
550
- digits: true,
551
- lowerCaseAlphabets: true,
552
- upperCaseAlphabets: true,
553
- specialChars: true,
128
+ this.metricsService.registerCounter({
129
+ name: 'requests_total',
130
+ help: 'Total requests',
131
+ labelNames: ['method', 'status'],
132
+ });
133
+ this.metricsService.incrementCounter('requests_total', {
134
+ method: 'GET',
135
+ status: '200',
554
136
  });
555
- ```
556
-
557
- ### Reference Utilities
558
-
559
- ```typescript
560
- import { generateReference } from '@takentrade/takentrade-libs';
561
-
562
- // Generate unique reference string
563
- const ref = generateReference('TXN'); // 'TXN-1234567890-ABC'
564
137
  ```
565
138
 
566
139
  ### Circuit Breaker
567
140
 
568
141
  ```typescript
569
- import {
570
- CircuitBreakerModule,
571
- CircuitBreakerService,
572
- } from '@takentrade/takentrade-libs';
573
-
574
- @Module({
575
- imports: [CircuitBreakerModule],
576
- })
577
- export class AppModule {}
578
-
579
- @Injectable()
580
- export class MyService {
581
- constructor(private readonly circuitBreaker: CircuitBreakerService) {}
582
-
583
- async callExternalService() {
584
- const breaker = this.circuitBreaker.createBreaker('external-api', {
585
- failureThreshold: 5,
586
- resetTimeout: 60000,
587
- });
588
-
589
- if (this.circuitBreaker.isOpen('external-api')) {
590
- throw new Error('Circuit breaker is open');
591
- }
592
-
593
- try {
594
- const result = await this.externalApiCall();
595
- this.circuitBreaker.recordSuccess('external-api');
596
- return result;
597
- } catch (error) {
598
- this.circuitBreaker.recordFailure('external-api');
599
- throw error;
600
- }
601
- }
602
- }
603
- ```
604
-
605
- ### Health Module
606
-
607
- ```typescript
608
- import { HealthModule } from '@takentrade/takentrade-libs';
609
-
610
- @Module({
611
- imports: [HealthModule],
612
- })
613
- export class AppModule {}
614
- ```
615
-
616
- The health module provides a `/health` endpoint for service health checks.
617
-
618
- ---
619
-
620
- ## Utils Module
621
-
622
- ### DTOs
623
-
624
- ```typescript
625
- import { PaginationDto } from '@takentrade/takentrade-libs';
626
-
627
- // Pagination DTO for request queries
628
- export class GetUsersDto extends PaginationDto {
629
- @IsOptional()
630
- @IsString()
631
- search?: string;
632
- }
633
- ```
634
-
635
- ### Pipes
636
-
637
- ```typescript
638
- import { PaginationQueryCleanerPipe } from '@takentrade/takentrade-libs';
639
-
640
- @Controller('users')
641
- export class UserController {
642
- @Get()
643
- async getUsers(
644
- @Query(PaginationQueryCleanerPipe) query: any // Removes page and limit from query
645
- ) {
646
- // query object will not contain page and limit fields
647
- }
648
- }
649
- ```
650
-
651
- ### Interceptors
652
-
653
- ```typescript
654
- import { ResponseInterceptor } from '@takentrade/takentrade-libs';
655
-
656
- @Module({
657
- providers: [
658
- {
659
- provide: APP_INTERCEPTOR,
660
- useClass: ResponseInterceptor,
661
- },
662
- ],
663
- })
664
- export class AppModule {}
665
- ```
666
-
667
- The `ResponseInterceptor` automatically wraps all responses in a standard format:
668
-
669
- ```json
670
- {
671
- "success": true,
672
- "message": "Operation successful",
673
- "data": {
674
- /* your data */
675
- },
676
- "metadata": {
677
- "path": "/api/users",
678
- "requestId": "uuid",
679
- "timestamp": "2024-01-01T00:00:00Z"
680
- }
681
- }
682
- ```
683
-
684
- ### Filters
685
-
686
- ```typescript
687
- import { HttpExceptionFilter } from '@takentrade/takentrade-libs';
688
-
689
- @Module({
690
- providers: [
691
- {
692
- provide: APP_FILTER,
693
- useClass: HttpExceptionFilter,
694
- },
695
- ],
696
- })
697
- export class AppModule {}
698
- ```
699
-
700
- The `HttpExceptionFilter` catches all exceptions and formats them consistently.
701
-
702
- ### Validators
703
-
704
- ```typescript
705
- import { ValidateNatsMessage } from '@takentrade/takentrade-libs';
706
-
707
- @Controller()
708
- export class MyController {
709
- @EventPattern('user.created')
710
- async handleUserCreated(
711
- @Payload(ValidateNatsMessage(UserCreatedDto)) data: UserCreatedDto
712
- ) {
713
- // data is validated and typed
714
- }
715
- }
142
+ this.circuitBreaker.createBreaker('api', async (data) => this.apiCall(data), {
143
+ timeout: 5000,
144
+ errorThresholdPercentage: 50,
145
+ });
146
+ const result = await this.circuitBreaker.fire('api', requestData);
716
147
  ```
717
148
 
718
- ### Response Utilities
149
+ ### Background Jobs
719
150
 
720
151
  ```typescript
721
- import { AppResponse } from '@takentrade/takentrade-libs';
722
-
723
- @Controller()
724
- export class MyController {
725
- @Get('users')
726
- async getUsers() {
727
- const users = await this.userService.findAll();
728
- return AppResponse.success(users, 'Users retrieved successfully');
152
+ await this.queue.add(
153
+ 'process-order',
154
+ { orderId: '123' },
155
+ {
156
+ attempts: 3,
157
+ backoff: { type: 'exponential', delay: 1000 },
729
158
  }
730
- }
159
+ );
731
160
  ```
732
161
 
733
- ### Pagination Utilities
162
+ ## Documentation
734
163
 
735
- ```typescript
736
- import { paginate } from '@takentrade/takentrade-libs';
164
+ - [Authentication](docs/auth.md) - Route protection and RBAC
165
+ - [Cache](docs/cache.md) - Redis caching
166
+ - [BullMQ](docs/bullmq.md) - Background jobs
167
+ - [NATS](docs/nats.md) - Messaging
168
+ - [Notifications](docs/notifications.md) - Email, SMS, push
169
+ - [RPC](docs/rpc.md) - Request-response patterns
170
+ - [Resilience](docs/resilience.md) - Circuit breakers
171
+ - [Metrics](docs/metrics.md) - Prometheus metrics
172
+ - [Common](docs/common.md) - Shared utilities
173
+ - [Utils](docs/utils.md) - DTOs, pipes, filters
737
174
 
738
- const result = paginate([1, 2, 3, 4, 5], 1, 2);
739
- // Returns: { data: [1, 2], total: 5, page: 1, limit: 2, totalPages: 3 }
740
- ```
741
-
742
- ### OTP Utilities
743
-
744
- ```typescript
745
- import { generateOTP, verifyOTP } from '@takentrade/takentrade-libs';
175
+ ## Contributing
746
176
 
747
- // Generate OTP
748
- const otp = generateOTP(6); // 6-digit OTP
177
+ This is a private package for TakeNTrade microservices.
749
178
 
750
- // Verify OTP (with expiration)
751
- const isValid = verifyOTP(otp, storedOtp, expirationTime);
752
- ```
753
-
754
- ### Configuration Utilities
755
-
756
- ```typescript
757
- import { getConfiguration } from '@takentrade/takentrade-libs';
758
-
759
- const config = getConfiguration();
760
- // Returns typed configuration object
761
- ```
762
-
763
- ---
764
-
765
- ## Configuration
766
-
767
- Most libraries require configuration through environment variables. Ensure these are set in your service's `.env` file:
768
-
769
- ```env
770
- # Cache & BullMQ Configuration
771
- REDIS_HOST=localhost
772
- REDIS_PORT=6379
773
- REDIS_USERNAME=
774
- REDIS_PASSWORD=your_password
775
-
776
- # NATS Configuration
777
- NATS_URL=nats://localhost:4222
778
- NATS_SERVICE_QUEUE=service_queue # Replace 'service' with your service name
779
-
780
- # JWT Configuration
781
- JWT_SECRET=your_jwt_secret
782
-
783
- # Database (for Prisma)
784
- DATABASE_URL=postgresql://user:password@localhost:5432/dbname
785
- ```
786
-
787
- ---
788
-
789
- ## Best Practices
790
-
791
- 1. **Always import from the library's main entry point**: Use `@takentrade/takentrade-libs` instead of internal paths
792
- 2. **Use TypeScript types and interfaces**: Take advantage of the provided types for better type safety
793
- 3. **Follow async/await pattern**: Most library functions are promise-based
794
- 4. **Configure modules properly**: Register modules in your service's root module
795
- 5. **Handle errors appropriately**: Use the provided filters and interceptors for consistent error handling
796
- 6. **Use constants for NATS subjects**: Always use `NatsSubjects` enum instead of hardcoding subject strings
797
- 7. **Leverage RPC utilities**: Use `TakeNTradeRpc` for consistent RPC error handling
798
-
799
- ---
800
-
801
- ## Exports
802
-
803
- The package exports the following sub-paths:
804
-
805
- - `@takentrade/takentrade-libs` - Main entry point
806
- - `@takentrade/takentrade-libs/bullmq` - BullMQ module
807
- - `@takentrade/takentrade-libs/cache` - Cache module
808
- - `@takentrade/takentrade-libs/common` - Common utilities
809
- - `@takentrade/takentrade-libs/nats` - NATS utilities
179
+ ## License
810
180
 
811
- ---
181
+ Proprietary - See [LICENSE](LICENSE) file for details.
812
182
 
813
- ## License
183
+ ## Support
814
184
 
815
- MIT
185
+ For issues or questions, contact the TakeNTrade development team.