@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

npm install @perkos/util-logger

Usage

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)

{"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

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

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:

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:

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:

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

Related Packages

• @perkos/types-x402 - Core x402 types
• @perkos/service-x402 - x402 service orchestrator

License

MIT