@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

$3


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

$3

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

API Reference

$3

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

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

child(context: Record): Logger;
}
`

$3

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

$3

`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 - Core x402 types
- @perkos/service-x402 - x402 service orchestrator

License

MIT