README.md

@happyvertical/logger

Structured logging for HAVE SDK with signal adapter integration and optional Sentry error tracking. Provides a Logger interface with four severity levels, a console implementation with level filtering, and adapters that convert SMRT framework signals into log entries or Sentry breadcrumbs/exceptions.

Installation

pnpm add @happyvertical/logger
# Registry: https://npm.pkg.github.com

# Optional: for Sentry integration
pnpm add @sentry/node

Depends on @happyvertical/utils. Optional peer dependency on @sentry/node (for the /sentry subpath).

Basic Usage

import { createLogger } from '@happyvertical/logger';

// Console logger with default 'info' level
const logger = createLogger(true);

logger.info('Application started');
logger.debug('Verbose detail'); // Not output (below 'info')
logger.warn('High memory usage', { memoryMB: 512 });
logger.error('Connection failed', { host: 'localhost', port: 5432 });

// Configure a specific level
const debugLogger = createLogger({ level: 'debug' });

// No-op logger — all calls discarded, zero overhead
const silent = createLogger(false);

Environment Variable

Set HAVE_LOGGER_LEVEL to debug, info, warn, or error. Applies when using createLogger(true) or createLogger({}). Explicit config takes precedence:

process.env.HAVE_LOGGER_LEVEL = 'debug';
const logger = createLogger(true); // uses 'debug' from env

const explicit = createLogger({ level: 'warn' }); // uses 'warn', ignores env

Log Levels

debug < info < warn < error — messages below the configured threshold are discarded.

const logger = createLogger({ level: 'warn' });
logger.debug('ignored');  // not output
logger.info('ignored');   // not output
logger.warn('output');    // output
logger.error('output');   // output

Output format: [LEVEL] message {"key":"value"}

Signal Adapter

LoggerAdapter converts SMRT framework signals into structured log entries:

import { createLogger, LoggerAdapter } from '@happyvertical/logger';

const logger = createLogger({ level: 'info' });
const adapter = new LoggerAdapter(logger);
// Register adapter with a signal bus to log operations automatically

Signal type mapping: start → debug, step → debug, end → info, error → error.

Sentry Adapter

The /sentry subpath routes signals to Sentry/GlitchTip. Requires @sentry/node as a peer dependency.

import { createSentryAdapter } from '@happyvertical/logger/sentry';

const adapter = createSentryAdapter({ category: 'myapp' });
// Register adapter with a signal bus

// Error signals → Sentry.captureException with scope tags
// Non-error signals → Sentry.addBreadcrumb for debugging trail

API Overview

Factory

Function	Description
createLogger(config)	Returns a Logger — ConsoleLogger when enabled, no-op when false
createSentryAdapter(config?)	Returns a SentryAdapter (from /sentry subpath)

Classes

Class	Description
ConsoleLogger	Logger implementation with level filtering, writes to console.*
LoggerAdapter	Signal adapter that converts signals to structured log messages
SentryAdapter	Signal adapter that routes errors to Sentry and adds breadcrumbs

Types

Type	Description
Logger	Interface with debug, info, warn, error methods
LogLevel	'debug' | 'info' | 'warn' | 'error'
LoggerConfig	boolean | { level?: LogLevel }
Signal	Signal event from operation execution
SignalAdapter	Interface for handling signals
SignalType	'start' | 'step' | 'end' | 'error'
SentryAdapterConfig	{ category?: string }

Custom Logger

Implement the Logger interface for custom backends:

import type { Logger } from '@happyvertical/logger';

class MyLogger implements Logger {
  debug(message: string, context?: Record<string, unknown>): void { /* ... */ }
  info(message: string, context?: Record<string, unknown>): void { /* ... */ }
  warn(message: string, context?: Record<string, unknown>): void { /* ... */ }
  error(message: string, context?: Record<string, unknown>): void { /* ... */ }
}

License

MIT