smartlog/API.md

# @push.rocks/smartlog API Reference

This document provides a detailed reference for all exports and APIs available in the @push.rocks/smartlog package and its submodules.

## Core Module (`@push.rocks/smartlog`)

The core module provides the main logging functionality.

### Classes

#### `Smartlog`

Main logger class for creating, managing, and routing logs.

```typescript
import { Smartlog } from '@push.rocks/smartlog';

const logger = new Smartlog({
  logContext: {
    company: 'MyCompany',
    environment: 'production',
    // ...other context properties
  },
  minimumLogLevel: 'info' // Optional, defaults to 'silly'
});
```

**Constructor Options:**
- `logContext`: Object containing context information about the environment
- `minimumLogLevel`: Optional minimum log level to process (defaults to 'silly')

**Methods:**
- `log(logLevel, message, data?, correlation?)`: Log a message with optional data and correlation
- `increment(logLevel, message, data?, correlation?)`: Log an increment counter
- `addLogDestination(destination)`: Add a custom log destination
- `enableConsole(options?)`: Enable console logging (with optional stdout/stderr capture)
- `createLogGroup(transactionId?)`: Create a log group for related logs
- `handleLog(logPackage)`: Handle a pre-formatted log package

**Static Methods:**
- `createForCommitinfo(commitinfo)`: Create a logger with commit information

#### `LogGroup`

Groups related logs together for better traceability.

```typescript
import { Smartlog } from '@push.rocks/smartlog';

const logger = new Smartlog({/*...*/});
const logGroup = logger.createLogGroup('transaction-123');

logGroup.log('info', 'Starting process');
// All logs in this group will share the same transaction ID
```

**Methods:**
- `log(logLevel, message, data?)`: Log a message within this group
- `increment(logLevel, message, data?)`: Log an increment within this group

#### `ConsoleLog`

Implementation of `ILogDestination` that logs to console.

## Interfaces Module (`@push.rocks/smartlog/interfaces`)

This module provides all type definitions and interfaces used by Smartlog.

### Types

- `TLogType`: Available log types
  - `'log' | 'increment' | 'gauge' | 'error' | 'success' | 'value' | 'finance' | 'compliance'`

- `TLogLevel`: Available log levels
  - `'silly' | 'info' | 'debug' | 'note' | 'ok' | 'success' | 'warn' | 'error' | 'lifecycle'`

- `TEnvironment`: Available environments
  - `'local' | 'test' | 'staging' | 'production'`

- `TRuntime`: Available runtime environments
  - `'node' | 'chrome' | 'rust' | 'deno' | 'cloudflare_workers'`

### Interfaces

#### `ILogContext`

Metadata about the environment where logging occurs.

```typescript
interface ILogContext {
  commitinfo?: ICommitInfo;
  company?: string;
  companyunit?: string;
  containerName?: string;
  environment?: TEnvironment;
  runtime?: TRuntime;
  zone?: string;
}
```

#### `ILogCorrelation`

Information for correlating related logs.

```typescript
interface ILogCorrelation {
  id: string;
  type: 'none' | 'service' | 'build' | 'infrastructure' | 'cdn';
  instance?: string;
  group?: string;
  transaction?: string;
}
```

#### `ILogPackage<T = unknown>`

The standard log package format.

```typescript
interface ILogPackage<T = unknown> {
  timestamp: number;
  type: TLogType;
  context: ILogContext;
  level: TLogLevel;
  correlation: ILogCorrelation;
  message: string;
  data?: T;
}
```

#### `ILogDestination`

Interface for implementing custom log destinations.

```typescript
interface ILogDestination {
  handleLog: (logPackage: ILogPackage) => Promise<void>;
}
```

## Interactive Console Module (`@push.rocks/smartlog/source-interactive`)

This module provides interactive console components like spinners and progress bars.

### Classes

#### `SmartlogSourceInteractive`

Creates interactive spinners for CLI applications.

```typescript
import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';

const spinner = new SmartlogSourceInteractive();
spinner.text('Loading data...');
// Later
spinner.finishSuccess('Data loaded successfully!');
```

**Methods:**
- `text(message)`: Sets the spinner text and starts it if not running
- `finishSuccess(message?)`: Completes the spinner with success message
- `finishFail(message?)`: Completes the spinner with failure message
- `successAndNext(message)`: Marks success and starts a new spinner
- `failAndNext(message)`: Marks failure and starts a new spinner
- `setSpinnerStyle(style)`: Sets spinner style ('dots', 'line', 'star', 'simple')
- `setColor(color)`: Sets the spinner color
- `setSpeed(ms)`: Sets the animation speed

#### `SmartlogProgressBar`

Creates progress bars for CLI applications.

```typescript
import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';

const bar = new SmartlogProgressBar({
  total: 100,
  width: 40,
  showEta: true
});

bar.update(50); // Update to 50%
bar.increment(10); // Increment by 10 units
bar.complete(); // Complete the progress bar
```

**Constructor Options:**
- `total`: Total number of items/steps
- `width`: Width of the bar in characters
- `complete`: Character for completed section
- `incomplete`: Character for incomplete section
- `renderThrottle`: Minimum time between renders
- `clear`: Whether to clear the bar on completion
- `showEta`: Show estimated time remaining
- `showPercent`: Show percentage completed
- `showCount`: Show count of items

**Methods:**
- `update(value)`: Update progress to a specific value
- `increment(value?)`: Increment progress by a value (default: 1)
- `complete()`: Mark the progress bar as complete
- `setColor(color)`: Set the color of the progress bar

## File Destination Module (`@push.rocks/smartlog/destination-file`)

This module provides a log destination that writes logs to a file.

### Classes

#### `SmartlogDestinationFile`

Writes logs to a file with timestamps.

```typescript
import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';

const logger = new Smartlog({/*...*/});
const fileDestination = new SmartlogDestinationFile('/absolute/path/to/logfile.log');
logger.addLogDestination(fileDestination);
```

**Constructor Parameters:**
- `filePath`: Absolute path to the log file

## Local Destination Module (`@push.rocks/smartlog/destination-local`)

This module provides a log destination with colorful formatting for local development.

### Classes

#### `DestinationLocal`

Formats logs with colors and prefixes for better readability in the console.

```typescript
import { Smartlog } from '@push.rocks/smartlog';
import { DestinationLocal } from '@push.rocks/smartlog/destination-local';

const logger = new Smartlog({/*...*/});
const localDestination = new DestinationLocal();
logger.addLogDestination(localDestination);
```

**Methods:**
- `handleLog(logPackage)`: Handles a log package
- `newLine(lines?)`: Adds empty lines to the console
- `logReduced(text, repeatEveryTimes?)`: Logs only when the message changes

## DevTools Destination Module (`@push.rocks/smartlog/destination-devtools`)

This module provides a log destination that formats logs for browser developer tools.

### Classes

#### `SmartlogDestinationDevtools`

Formats logs with colors for browser developer tools.

```typescript
import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';

const logger = new Smartlog({/*...*/});
const devtoolsDestination = new SmartlogDestinationDevtools();
logger.addLogDestination(devtoolsDestination);
```

## ClickHouse Destination Module (`@push.rocks/smartlog/destination-clickhouse`)

This module provides a log destination that stores logs in a ClickHouse database.

### Classes

#### `SmartlogDestinationClickhouse`

Stores logs in a ClickHouse database for analytics and querying.

```typescript
import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';

const logger = new Smartlog({/*...*/});
const clickhouseDestination = await SmartlogDestinationClickhouse.createAndStart({
  host: 'clickhouse.example.com',
  port: 8123,
  user: 'username',
  password: 'password',
  database: 'logs_db'
});
logger.addLogDestination(clickhouseDestination);
```

**Static Methods:**
- `createAndStart(options)`: Create and initialize a ClickHouse destination

**Methods:**
- `start()`: Initialize the connection to ClickHouse
- `handleLog(logPackage)`: Store a log in ClickHouse