# Logger Interfaces and Utilities

This directory provides logging interfaces and utilities for consistent logging across all packages.

## Files

### `cb-logger.ts`
Internal logger implementation using Winston for system-level logging within the CLI framework.

### `internal-logger.ts`
Provides the global `__logger` instance used internally by all packages for framework logging.

## Core Components

### __logger (Global Instance)
A global logger instance available throughout the codebase for internal framework logging.

**Purpose:** Provides consistent logging for CLI operations, errors, and system messages that are separate from user application logs.

**Usage:**
```typescript
import { __logger } from '@chargebee/chargebee-apps-shared';

class CommandProcessor {
  execute(command: string): void {
    __logger.info('Executing command', { command });
    
    try {
      // Command logic
      __logger.success('Command completed successfully');
    } catch (error) {
      __logger.error('Command failed', { error: error.message });
    }
  }
}
```

### ICBLogger Interface
Standard logging interface that user code implementations must follow.

**Purpose:** Defines the contract for logger implementations that will be provided to user code in sandboxed environments.

**Usage:**
```typescript
import { ICBLogger } from '@chargebee/chargebee-apps-shared';

// User's logger implementation
class UserLogger implements ICBLogger {
  info(message: string, ...meta: any[]): void {
    // Custom logging logic for user code
  }
  
  error(message: string, ...meta: any[]): void {
    // Custom error logging
  }
  
  // ... other methods
}
```

### SafeConsole
A controlled console interface for user code execution in sandboxed environments.

**Purpose:** Provides a safe console replacement that channels user code output through the logging system.

**Usage:**
```typescript
import { createSafeConsole } from '@chargebee/chargebee-apps-shared';

const userLogger = new UserLogger();
const safeConsole = createSafeConsole(userLogger);

// Used in sandbox context
const sandboxGlobals = {
  console: safeConsole,
  // ... other globals
};
```

## Logging Patterns

### Framework Logging
Internal framework operations use the global `__logger`:

```typescript
// CLI command execution
__logger.info('Starting package creation...');
__logger.success('✅ Package created successfully');
__logger.error('Failed to create package', { error: err.message });
```

### User Code Logging
User application code receives an `ICBLogger` implementation:

```typescript
// In user's handler function
function customerHandler(event, logger) {
  logger.info('Processing customer event', { customerId: event.customer.id });
  // Handler logic
}
```

### Console Replacement
User code console calls are intercepted and routed through logging:

```typescript
// User writes:
console.log('Customer processed');

// Actually calls:
safeConsole.log('Customer processed'); // -> userLogger.info('Customer processed')
```

## Log Levels

The logging system supports standard log levels:
- **debug** - Detailed information for debugging
- **info** - General information about operations
- **warn** - Warning messages for potential issues
- **error** - Error messages for failures

## Best Practices

1. **Use __logger for framework operations** - All CLI internal logging should use the global instance
2. **Implement ICBLogger for user code** - Provide structured logging to user applications
3. **Replace console in sandboxes** - Use SafeConsole to control user code output
4. **Include context** - Add relevant metadata to log messages
5. **Use appropriate levels** - Choose the right log level for each message
6. **Handle errors gracefully** - Log errors with sufficient context for debugging