npm package: @perkos/util-logger
Description: Structured logging utility for x402 protocol services
Author: PerkOS
Latest version: 1.0.1

# @perkos/util-logger

Structured logging utility for x402 protocol services. Provides environment-aware logging with JSON output for production and readable output for development.

## Installation

```bash
npm install @perkos/util-logger
```

## Usage

```typescript
import { logger, createLogger, Logger } from '@perkos/util-logger';
import type { LogLevel, LogEntry, LoggerOptions } from '@perkos/util-logger';

// Use default logger instance
logger.info('Payment verified', { amount: '1000000', network: 'base' });
logger.warn('Retrying transaction', { attempt: 2 });
logger.error('Settlement failed', { error: 'Insufficient funds' });
logger.debug('Debug info', { payload: { ... } });

// Create custom logger
const customLogger = createLogger({
  isDev: true,           // Force development mode (readable output)
  minLevel: 'debug',     // Log all levels including debug
});

// Create child logger with context
const paymentLogger = logger.child({ service: 'payment', network: 'base' });
paymentLogger.info('Processing payment');
// => { timestamp: "...", level: "info", message: "Processing payment", service: "payment", network: "base" }
```

## Output Formats

### Production (JSON)
```json
{"timestamp":"2024-01-15T10:30:00.000Z","level":"info","message":"Payment verified","amount":"1000000","network":"base"}
```

### Development (Readable)
```
[2024-01-15T10:30:00.000Z] [INFO] Payment verified {"amount":"1000000","network":"base"}
```

## API Reference

### Logger Class

```typescript
class Logger {
  constructor(options?: LoggerOptions);

  info(message: string, meta?: Record<string, unknown>): void;
  warn(message: string, meta?: Record<string, unknown>): void;
  error(message: string, meta?: Record<string, unknown>): void;
  debug(message: string, meta?: Record<string, unknown>): void;

  child(context: Record<string, unknown>): Logger;
}
```

### Functions

| Function | Description |
|----------|-------------|
| `logger` | Default logger instance |
| `createLogger(options)` | Create a new logger with custom options |

### Types

```typescript
type LogLevel = "info" | "warn" | "error" | "debug";

interface LogEntry {
  timestamp: string;
  level: LogLevel;
  message: string;
  [key: string]: unknown;
}

interface LoggerOptions {
  /** Force development mode output (readable format) */
  isDev?: boolean;
  /** Minimum log level to output */
  minLevel?: LogLevel;
  /** Custom log handler */
  handler?: (entry: LogEntry) => void;
}
```

## Log Levels

| Level | Priority | Description |
|-------|----------|-------------|
| `debug` | 0 | Detailed debugging information |
| `info` | 1 | General informational messages |
| `warn` | 2 | Warning conditions |
| `error` | 3 | Error conditions |

Set `minLevel` to filter out lower priority logs:

```typescript
const logger = createLogger({ minLevel: 'warn' });
logger.debug('Not logged');  // Filtered out
logger.info('Not logged');   // Filtered out
logger.warn('Logged');       // ✓ Output
logger.error('Logged');      // ✓ Output
```

## Custom Handler

Provide a custom handler to integrate with external logging services:

```typescript
const logger = createLogger({
  handler: (entry) => {
    // Send to external service
    myLoggingService.log(entry);
  }
});
```

## Environment Detection

The logger automatically detects the environment:
- **Development**: `NODE_ENV === "development"` → readable format
- **Production**: JSON format for log aggregation services

Override with `isDev` option:

```typescript
const logger = createLogger({ isDev: true });  // Force readable format
```

## Related Packages

- [@perkos/types-x402](https://www.npmjs.com/package/@perkos/types-x402) - Core x402 types
- [@perkos/service-x402](https://www.npmjs.com/package/@perkos/service-x402) - x402 service orchestrator

## License

MIT