npm package: @nxtoai/aag
Description: A flexible logging service for NestJS applications
Author: NxtoAI
Latest version: 1.0.1

# AAG  - Logging Service for NxtoAI APPLICATIONS

A powerful and flexible logging service for NxtoAI NestJS applications that provides structured logging with automatic formatting, timestamps, and labels.

## Installation

```bash
npm install @nxtoai/aag
```

## Configuration

Import the `AagModule` in your application module:

```typescript
import { Module } from '@nestjs/common';
import { AagModule } from '@nxtoai/aag';

@Module({
  imports: [
    AagModule.forRoot({
      environment: 'development', // Debug logs enabled on test/dev environments ; only info logs for prod environment 
      debugUsers: ['user1', 'user2'] // Optional: List of debug users, if passed debug logs on production environment will be available for these set of users
    }),
  ],
})
export class AppModule {}
```

## Usage

Inject the `AagService` into your service:

```typescript
import { Injectable } from '@nestjs/common';
import { AagService } from '@nxtoai/aag';

@Injectable()
export class UserService {
  constructor(private readonly aag: AagService) {}

  async createUser(userData: any) {
    try {
      this.aag.debug('Creating new user with email :', { email: userData.email });
      // ... user creation logic
      this.aag.info('User created successfully with user id : ', { userId: newUser.id });
    } catch (error) {
      this.aag.error('Failed to create user due to : ', error.stack);
      throw error;
    }
  }
}
```

## Logging Methods

### debug(message: string, data?: any)
Logs debug level messages. Useful for development and troubleshooting.

```typescript
this.aag.debug('Processing request', { requestId: '123' });
```

### info(message: string, data?: any)
Logs informational messages. Used for general application flow.

```typescript
this.aag.info('User logged in', { userId: '123' });
```

### warn(message: string, data?: any)
Logs warning messages. Used for potentially harmful situations.

```typescript
this.aag.warn('Rate limit approaching', { userId: '123', currentRate: 95 });
```

### error(message: string, stack?: string)
Logs error messages. Used for error conditions.

```typescript
try {
  // ... some code
} catch (error) {
  this.aag.error('Failed to process payment', error.stack);
}
```

## Features

### Automatic Formatting
- JSON formatting for structured logging
- Automatic timestamp addition
- Application name and environment labeling
- Stack trace formatting for errors

### Debug Users
The service includes a debug users feature that allows you to bypass certain validations or restrictions for specific users. This is particularly useful during development and testing.

To use debug users:

1. Configure debug users in your environment for whome debug logs will be available on prod environment:
```typescript
// In your configuration
{
  debugUsers: ['user1', 'user2'] // List of user IDs that are considered debug users
}
```

2. Check if a user is enabled for printing debug logs:
```typescript
// In your service
if (this.isDebugUser(userId)) {
  // Skip certain validations or restrictions
  // For example, bypass OTP verification
}
```

## Best Practices

1. Use appropriate log levels:
   - `debug`: Detailed information for debugging
   - `info`: General operational information
   - `warn`: Warning messages for potentially harmful situations
   - `error`: Error conditions that need attention

2. Include relevant context:
   ```typescript
   this.aag.info('User action completed', {
     userId: '123',
     action: 'profile_update',
     timestamp: new Date().toISOString()
   });
   ```

3. Always include stack traces for errors:
   ```typescript
   try {
     // ... some code
   } catch (error) {
     this.aag.error('Operation failed', error.stack);
   }
   ```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.