v3.2.1

changelog.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 2026-02-20 - 3.2.1 - fix(destination-buffer)
+return entries in chronological order (oldest-first) and adjust pagination semantics
+
+- Change getEntries to return the most recent entries in chronological (oldest-first) order instead of newest-first
+- Adjust pagination to compute slice indices from the newest end (start = max(0, len - limit - offset), end = len - offset)
+- Update tests to expect chronological ordering and clarified pagination examples
+- Modified files: ts_destination_buffer/classes.destinationbuffer.ts, test/test.destination-buffer.node.ts
+
+## 2026-02-19 - 3.2.0 - feat(destination-buffer)
+add SmartlogDestinationBuffer in-memory circular buffer destination with query/filter/pagination and tests
+
+- Introduce SmartlogDestinationBuffer: an in-memory circular buffer implementing ILogDestination with configurable maxEntries (default 2000).
+- Expose APIs: handleLog, getEntries (supports level filtering, search, since timestamp, limit/offset pagination, newest-first ordering), getEntryCount, and clear.
+- Add package export './destination-buffer' and module entry points (index and plugins) to expose the new destination.
+- Add tests covering storage, filtering by level and search, pagination, eviction when maxEntries exceeded, clearing, and default maxEntries behavior.
+
+## 2026-02-14 - 3.1.11 - fix(destination-receiver)
+return full webrequest response from SmartlogDestinationReceiver and migrate to WebrequestClient; update tests, dependencies, docs, and npmextra metadata
+
+- SmartlogDestinationReceiver now uses plugins.webrequest.WebrequestClient instead of plugins.webrequest.WebRequest and returns the full response object instead of response.body — callers expecting the previous shape will need to adapt (breaking change)
+- Tests updated to match the new webrequest.postJson return shape
+- Bumped several devDependencies and dependencies (@git.zone/* toolchain, @push.rocks/* libs) to newer major/minor versions
+- Removed tsbundle from the build script and adjusted build tooling invocation
+- Added pnpm.onlyBuiltDependencies and updated npmextra.json namespace keys and release/tsdoc metadata
+- Documentation (readme.md) updated: examples changed to async/await usage, expanded legal and issue-reporting sections
+
+## 2025-09-22 - 3.1.10 - fix(tests)
+Bump dependency versions and adjust test to use enableConsole() default
+
+- Update devDependencies: @git.zone/tsbuild -> ^2.6.8, @git.zone/tsbundle -> ^2.5.1, @git.zone/tstest -> ^2.3.6
+- Update runtime dependencies: @push.rocks/consolecolor -> ^2.0.3, @push.rocks/smartfile -> ^11.2.7, @push.rocks/smarthash -> ^3.2.3
+- Simplify test invocation in test/test.ts: call testSmartLog.enableConsole() without the captureAll option
+
+## 2025-09-01 - 3.1.9 - fix(docs)
+Update README: expand documentation, examples and usage guides
+
+- Fully rewrote README to a comprehensive documentation page with badges, motivation and feature overview.
+- Added Quick Start, detailed usage examples and code snippets for Smartlog, destinations, and custom destinations.
+- Documented interactive console features (spinners, progress bars) including non-interactive fallbacks and configuration options.
+- Expanded sections on built-in destinations (console, file, devtools, ClickHouse, receiver) with practical examples and env-driven configuration.
+- Added integration examples (PM2, Docker), CLI usage, advanced features (context management, scoped logging, minimum log levels) and best practices.
+- Included API reference pointers and contributing / license information.
+
 ## 2025-05-20 - 3.1.8 - fix(devDependencies)
 Update devDependencies for tstest and Node types
 

npmextra.json

@@ -1,5 +1,5 @@
 {
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
@@ -25,13 +25,19 @@
         "error tracking",
         "development tools"
       ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "npmci": {
+  "@git.zone/tsdoc": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartlog",
-  "version": "3.1.8",
+  "version": "3.2.1",
   "private": false,
   "description": "A minimalistic, distributed, and extensible logging tool supporting centralized log management.",
   "keywords": [
@@ -30,6 +30,7 @@
     "./destination-devtools": "./dist_ts_destination_devtools/index.js",
     "./destination-file": "./dist_ts_destination_file/index.js",
     "./destination-local": "./dist_ts_destination_local/index.js",
+    "./destination-buffer": "./dist_ts_destination_buffer/index.js",
     "./destination-receiver": "./dist_ts_destination_receiver/index.js",
     "./receiver": "./dist_ts_receiver/index.js"
   },
@@ -37,28 +38,28 @@
   "license": "MIT",
   "scripts": {
     "test": "(tstest test/**/*.ts --verbose)",
-    "build": "(tsbuild tsfolders --allowimplicitany && tsbundle npm)",
+    "build": "(tsbuild tsfolders)",
     "format": "(gitzone format)",
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.5.1",
+    "@git.zone/tsbuild": "^4.1.2",
-    "@git.zone/tsbundle": "^2.2.5",
+    "@git.zone/tsbundle": "^2.8.3",
-    "@git.zone/tsrun": "^1.3.3",
+    "@git.zone/tsrun": "^2.0.1",
-    "@git.zone/tstest": "^1.9.0",
+    "@git.zone/tstest": "^3.1.8",
     "@types/node": "^22.15.20"
   },
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^3.0.19",
-    "@push.rocks/consolecolor": "^2.0.2",
+    "@push.rocks/consolecolor": "^2.0.3",
-    "@push.rocks/isounique": "^1.0.4",
+    "@push.rocks/isounique": "^1.0.5",
     "@push.rocks/smartclickhouse": "^2.0.17",
-    "@push.rocks/smartfile": "^11.2.0",
+    "@push.rocks/smartfile": "^11.2.7",
-    "@push.rocks/smarthash": "^3.0.4",
+    "@push.rocks/smarthash": "^3.2.6",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smarttime": "^4.1.1",
-    "@push.rocks/webrequest": "^3.0.37",
+    "@push.rocks/webrequest": "^4.0.1",
-    "@tsclass/tsclass": "^9.2.0"
+    "@tsclass/tsclass": "^9.3.0"
   },
   "files": [
     "ts/**/*",
@@ -86,6 +87,10 @@
     "url": "https://code.foss.global/push.rocks/smartlog/issues"
   },
   "pnpm": {
-    "overrides": {}
+    "overrides": {},
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "puppeteer"
+    ]
   }
 }

readme.md

@@ -1,300 +1,704 @@
-# @push.rocks/smartlog
+# @push.rocks/smartlog 🚀
+*The ultimate TypeScript logging solution for modern applications*
 
-Minimalistic distributed and extensible logging tool for TypeScript and JavaScript applications.
+[![npm version](https://img.shields.io/npm/v/@push.rocks/smartlog.svg)](https://www.npmjs.com/package/@push.rocks/smartlog)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Install
+> **smartlog** is a powerful, distributed, and extensible logging system designed for the cloud-native era. Whether you're debugging locally, monitoring production systems, or building complex microservices, smartlog adapts to your needs with style. 🎯
 
-Install `@push.rocks/smartlog` using pnpm (recommended), npm, or yarn:
+## Issue Reporting and Security
 
-```sh
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## 🌟 Why smartlog?
+
+- **🎨 Beautiful Console Output**: Color-coded, formatted logs that are actually readable
+- **🔌 Extensible Architecture**: Plug in any destination — databases, files, remote servers
+- **🌍 Distributed by Design**: Built for microservices with correlation and context tracking
+- **⚡ Zero-Config Start**: Works out of the box, scales when you need it
+- **🎭 Interactive CLI Tools**: Spinners and progress bars that handle non-TTY environments gracefully
+- **📊 Structured Logging**: JSON-based for easy parsing and analysis
+- **🔍 Smart Filtering**: Log levels and context-based filtering
+
+## 📦 Installation
+
+```bash
 # Using pnpm (recommended)
 pnpm add @push.rocks/smartlog
 
 # Using npm
-npm install @push.rocks/smartlog --save
+npm install @push.rocks/smartlog
-
-# Using yarn
-yarn add @push.rocks/smartlog
 ```
 
-Ensure you have TypeScript and Node.js installed for TypeScript projects.
+## 🚀 Quick Start
 
-## Package Exports
+### Your First Logger
-
-The package provides the following exports:
-
-```javascript
-// Main module
-import { Smartlog, LogGroup, ConsoleLog } from '@push.rocks/smartlog';
-
-// Type definitions and interfaces
-import { ILogPackage, ILogDestination, TLogLevel } from '@push.rocks/smartlog/interfaces';
-
-// Interactive console features (spinners, progress bars)
-import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
-
-// Context management
-import { ... } from '@push.rocks/smartlog/context';
-
-// Log destinations
-import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
-
-// Receiver functionality
-import { SmartlogReceiver } from '@push.rocks/smartlog/receiver';
-```
-
-## Usage
-
-`@push.rocks/smartlog` is a flexible, extensible logging tool designed for distributed systems. It provides a consistent logging interface across different environments while being lightweight and customizable.
-
-### Creating a Logger Instance
-
-Start by importing `Smartlog` and create a logger instance:
 
 ```typescript
 import { Smartlog } from '@push.rocks/smartlog';
 
+// Create a logger with context
 const logger = new Smartlog({
   logContext: {
-    company: 'My Company',
+    company: 'MyStartup',
-    companyunit: 'Cloud Team',
+    companyunit: 'Backend Team',
-    containerName: 'api-service',
+    containerName: 'api-gateway',
-    environment: 'production', // 'local', 'test', 'staging', 'production'
+    environment: 'production',
-    runtime: 'node',           // 'node', 'chrome', 'rust', 'deno', 'cloudflare_workers'
+    runtime: 'node',
-    zone: 'us-west',
+    zone: 'eu-central'
-  },
+  }
-  minimumLogLevel: 'info',     // Optional, defaults to 'silly'
 });
 
 // Enable console output
 logger.enableConsole();
+
+// Start logging!
+await logger.log('info', '🎉 Application started successfully');
+await logger.log('error', '💥 Database connection failed', {
+  errorCode: 'DB_TIMEOUT',
+  attemptCount: 3
+});
 ```
 
-The context enriches logs with valuable information for filtering and analysis across distributed systems.
+### Using `createForCommitinfo`
 
-### Logging Messages
+If you're integrating with a build system that provides commit info, you can use the static factory method:
 
 ```typescript
-// Basic logging
+import { Smartlog } from '@push.rocks/smartlog';
-logger.log('info', 'User authenticated successfully');
-logger.log('error', 'Database connection failed', { errorCode: 'DB_CONN_ERR', retryCount: 3 });
-logger.log('warn', 'Rate limit approaching', { currentRate: 95, limit: 100 });
 
-// Log levels: 'silly', 'info', 'debug', 'note', 'ok', 'success', 'warn', 'error', 'lifecycle'
+const logger = Smartlog.createForCommitinfo({
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My application'
+});
+
+logger.enableConsole();
+await logger.log('lifecycle', '🔄 App starting...');
 ```
 
-The third parameter accepts any additional data to attach to the log entry.
+## 📚 Core Concepts
 
-### Default Logger
+### Log Levels
 
-For simple cases, use the built-in default logger:
+smartlog supports semantic log levels for different scenarios:
 
 ```typescript
-import { defaultLogger } from '@push.rocks/smartlog';
+// Lifecycle events
+await logger.log('lifecycle', '🔄 Container starting up...');
 
-defaultLogger.log('info', 'Application started');
+// Success states
+await logger.log('success', '✅ Payment processed');
+await logger.log('ok', '👍 Health check passed');
+
+// Information and debugging
+await logger.log('info', '📋 User profile updated');
+await logger.log('note', '📌 Cache invalidated');
+await logger.log('debug', '🔍 Query execution plan', { sql: 'SELECT * FROM users' });
+
+// Warnings and errors
+await logger.log('warn', '⚠️  Memory usage above 80%');
+await logger.log('error', '❌ Failed to send email');
+
+// Verbose output
+await logger.log('silly', '🔬 Entering function processPayment()');
 ```
 
-### Log Groups
+Available levels (from most to least verbose): `silly`, `debug`, `info`, `note`, `ok`, `success`, `warn`, `error`, `lifecycle`
 
-Group related logs for better traceability:
+### Log Types
+
+Each log entry has a type that describes what kind of data it represents:
+
+| Type | Description |
+|------|-------------|
+| `log` | Standard log message |
+| `increment` | Counter/metric increment |
+| `gauge` | Gauge measurement |
+| `error` | Error event |
+| `success` | Success event |
+| `value` | Value recording |
+| `finance` | Financial transaction |
+| `compliance` | Compliance event |
+
+### Log Groups for Correlation
+
+Perfect for tracking request flows through your system:
 
 ```typescript
-// Create a log group with optional transaction ID
+// Track a user request through multiple operations
-const requestGroup = logger.createLogGroup('tx-123456');
+const requestGroup = logger.createLogGroup('req-7f3a2b');
 
-// Logs within this group will be correlated
+requestGroup.log('info', 'Received POST /api/users');
-requestGroup.log('info', 'Processing payment request');
+requestGroup.log('debug', 'Validating request body');
-requestGroup.log('debug', 'Validating payment details');
+requestGroup.log('info', 'Creating user in database');
-requestGroup.log('success', 'Payment processed successfully');
+requestGroup.log('success', 'User created successfully', { userId: 'usr_123' });
+
+// All logs in the group share the same group ID and transaction ID
 ```
 
-### Custom Log Destinations
+### Log Context
 
-Extend logging capabilities by adding custom destinations:
+Every log carries contextual information about the environment it was created in:
 
 ```typescript
-import { Smartlog, ILogDestination } from '@push.rocks/smartlog';
+interface ILogContext {
+  commitinfo?: ICommitInfo;  // Build/version info
+  company?: string;           // Company name
+  companyunit?: string;       // Team or department
+  containerName?: string;     // Container/service name
+  environment?: 'local' | 'test' | 'staging' | 'production';
+  runtime?: 'node' | 'chrome' | 'rust' | 'deno' | 'cloudflare_workers';
+  zone?: string;              // Deployment zone/region
+}
+```
 
-class DatabaseLogDestination implements ILogDestination {
+## 🎯 Log Destinations
-  async handleLog(logPackage) {
+
-    // Store log in database
+smartlog routes log packages to any number of destinations simultaneously. Each destination implements the `ILogDestination` interface with a single `handleLog` method.
-    await db.logs.insert({
+
-      timestamp: new Date(logPackage.timestamp),
+### Built-in Destinations
-      level: logPackage.level,
+
-      message: logPackage.message,
+#### 🖥️ Local Console (Enhanced)
-      data: logPackage.data,
+
-      context: logPackage.context
+Beautiful, color-coded output for local development:
+
+```typescript
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+
+const localDestination = new DestinationLocal();
+logger.addLogDestination(localDestination);
+
+// Output is color-coded per log level:
+// 🔵 info: blue prefix, white text
+// 🔴 error: red prefix, red text
+// 🟢 ok/success: green prefix, green text
+// 🟠 warn: orange prefix, orange text
+// 🟣 note/debug: pink prefix, pink text
+// 🔵 silly: blue background, blue text
+```
+
+The `DestinationLocal` also supports **reduced logging** — a mode where repeated identical log messages are suppressed:
+
+```typescript
+const localDest = new DestinationLocal();
+
+localDest.logReduced('Waiting for connection...'); // Logged
+localDest.logReduced('Waiting for connection...'); // Suppressed
+localDest.logReduced('Waiting for connection...'); // Suppressed
+localDest.logReduced('Connected!');                // Logged (new message)
+```
+
+#### 📁 File Logging
+
+Persist logs to files with timestamped entries:
+
+```typescript
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+
+// Path MUST be absolute
+const fileDestination = new SmartlogDestinationFile('/var/log/myapp/app.log');
+logger.addLogDestination(fileDestination);
+
+// Log entries are written as timestamped lines:
+// 2024-01-15T10:30:00.000Z: Application started
+// 2024-01-15T10:30:01.123Z: Processing request
+```
+
+#### 🌐 Browser DevTools
+
+Optimized for browser environments with styled console output:
+
+```typescript
+import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
+
+const devtools = new SmartlogDestinationDevtools();
+logger.addLogDestination(devtools);
+
+// Uses CSS styling in browser console for beautiful, categorized output
+// Different colors for error (red), info (pink), ok (green), success (green),
+// warn (orange), and note (blue) levels
+```
+
+#### 📊 ClickHouse Analytics
+
+Store logs in ClickHouse for powerful time-series analytics:
+
+```typescript
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+
+const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
+  url: 'https://analytics.example.com:8123',
+  database: 'logs',
+  username: 'logger',
+  password: process.env.CLICKHOUSE_PASSWORD
+});
+
+logger.addLogDestination(clickhouse);
+```
+
+#### 🔗 Remote Receiver
+
+Send logs to a centralized logging service with authenticated transport:
+
+```typescript
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
+
+const receiver = new SmartlogDestinationReceiver({
+  passphrase: process.env.LOG_PASSPHRASE,
+  receiverEndpoint: 'https://logs.mycompany.com/ingest'
+});
+
+logger.addLogDestination(receiver);
+```
+
+Logs are sent as authenticated JSON payloads with SHA-256 hashed passphrases.
+
+### 🛠️ Custom Destinations
+
+Build your own destination for any logging backend by implementing the `ILogDestination` interface:
+
+```typescript
+import type { ILogDestination, ILogPackage } from '@push.rocks/smartlog/interfaces';
+
+class ElasticsearchDestination implements ILogDestination {
+  async handleLog(logPackage: ILogPackage): Promise<void> {
+    await this.client.index({
+      index: `logs-${new Date().toISOString().split('T')[0]}`,
+      body: {
+        '@timestamp': logPackage.timestamp,
+        level: logPackage.level,
+        message: logPackage.message,
+        context: logPackage.context,
+        data: logPackage.data,
+        correlation: logPackage.correlation
+      }
     });
   }
 }
 
-// Add the custom destination to your logger
+logger.addLogDestination(new ElasticsearchDestination());
-logger.addLogDestination(new DatabaseLogDestination());
 ```
 
-### Built-in Destinations
+## 🎨 Interactive Console Features
 
-SmartLog comes with several built-in destinations for various logging needs:
+### Spinners
+
+Create beautiful loading animations that degrade gracefully in CI/CD:
 
 ```typescript
-// Log to a file
+import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
-import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
-logger.addLogDestination(new SmartlogDestinationFile('/path/to/logfile.log'));
 
-// Colorful local console logging
-import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
-logger.addLogDestination(new DestinationLocal());
-
-// Browser DevTools with colored formatting
-import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
-logger.addLogDestination(new SmartlogDestinationDevtools());
-
-// ClickHouse database logging
-import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
-const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
-  host: 'clickhouse.example.com',
-  port: 8123,
-  user: 'username',
-  password: 'password',
-  database: 'logs_db'
-});
-logger.addLogDestination(clickhouse);
-
-// Remote receiver logging
-import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
-logger.addLogDestination(new SmartlogDestinationReceiver({
-  endpoint: 'https://logs.example.com/api/logs'
-}));
-```
-
-### Interactive Console Features
-
-For CLI applications, use the interactive console features:
-
-```typescript
-import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
-```
-
-#### Spinners
-
-```typescript
 const spinner = new SmartlogSourceInteractive();
 
-// Start a spinner with text
+// Basic usage
-spinner.text('Loading data...');
+spinner.text('🔄 Fetching data from API...');
+// ... perform async operation
+spinner.finishSuccess('✅ Data fetched successfully!');
+
+// Chain success and move to next task
+spinner.text('📡 Connecting to database');
+// ... connect
+spinner.successAndNext('🔍 Running migrations');
+// ... migrate
+spinner.finishSuccess('🎉 Database ready!');
 
 // Customize appearance
-spinner.setSpinnerStyle('dots');  // 'dots', 'line', 'star', 'simple'
+spinner
-spinner.setColor('blue');         // 'red', 'green', 'yellow', 'blue', etc.
+  .setSpinnerStyle('dots')  // 'dots' | 'line' | 'star' | 'simple'
-spinner.setSpeed(80);             // Animation speed in milliseconds
+  .setColor('cyan')         // any terminal color
+  .setSpeed(80);            // animation speed in ms
 
-// Update spinner status
+spinner.text('🚀 Deploying application...');
-spinner.text('Processing records...');
 
-// Complete with success or failure
+// Handle failures
-spinner.finishSuccess('Data loaded successfully!');
+try {
-spinner.finishFail('Failed to load data!');
+  await deployApp();
-
+  spinner.finishSuccess('✅ Deployed!');
-// Chain operations
+} catch (error) {
-spinner.text('Connecting to server')
+  spinner.finishFail('❌ Deployment failed');
-  .successAndNext('Fetching records')
+}
-  .successAndNext('Processing data')
-  .finishSuccess('All done!');
 ```
 
-#### Progress Bars
+### Progress Bars
+
+Track long-running operations with style:
 
 ```typescript
-const progressBar = new SmartlogProgressBar({
+import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
-  total: 100,                // Total number of items
+
-  width: 40,                 // Width of the progress bar
+// Create a progress bar
-  complete: '█',             // Character for completed section
+const progress = new SmartlogProgressBar({
-  incomplete: '░',           // Character for incomplete section
+  total: 100,
-  showEta: true,             // Show estimated time remaining
+  width: 40,          // Bar width in characters
-  showPercent: true,         // Show percentage
+  complete: '█',      // Fill character
-  showCount: true            // Show count (e.g., "50/100")
+  incomplete: '░',    // Empty character
+  showEta: true,      // Show estimated time remaining
+  showPercent: true,  // Show percentage
+  showCount: true     // Show current/total count
 });
 
 // Update progress
-progressBar.update(25);      // Set to 25% progress
+for (let i = 0; i <= 100; i++) {
+  progress.update(i);
+  await someAsyncWork();
+}
 
-// Increment progress
+progress.complete();
-progressBar.increment(5);    // Increase by 5 units
 
-// Change color
+// Or use increment for simpler tracking
-progressBar.setColor('blue');
+const files = await getFiles();
+const fileProgress = new SmartlogProgressBar({ total: files.length });
 
-// Complete the progress bar
+for (const file of files) {
-progressBar.complete();
+  await processFile(file);
+  fileProgress.increment();
+}
+
+fileProgress.complete();
 ```
 
-#### Non-Interactive Environments
+### Non-Interactive Fallback
 
-Both spinners and progress bars automatically detect non-interactive environments (CI/CD, piped output) and fallback to plain text logging:
+Both spinners and progress bars automatically detect non-interactive environments (CI/CD, Docker logs, piped output) and fall back to simple text output:
 
 ```
-[Loading] Connecting to server
+[Loading] Connecting to database
-[Success] Connected to server
+[Success] Connected to database
-[Loading] Fetching records
+[Loading] Running migrations
+Progress: 25% (25/100)
 Progress: 50% (50/100)
 Progress: 100% (100/100)
-[Success] Fetching complete
+Completed: 100% (100/100)
 ```
 
-## Advanced Usage
+Detection checks for: TTY capability, CI environment variables (GitHub Actions, Jenkins, GitLab CI, Travis, CircleCI), and `TERM=dumb`.
 
-### Capturing All Console Output
+### Backward Compatibility
 
-Capture all `console.log` and `console.error` output through Smartlog:
+The `SmartlogSourceOra` class extends `SmartlogSourceInteractive` and provides a compatibility layer for code that previously used the `ora` npm package:
 
 ```typescript
-logger.enableConsole({ captureAll: true });
+import { SmartlogSourceOra } from '@push.rocks/smartlog/source-interactive';
+
+const ora = new SmartlogSourceOra();
+ora.oraInstance.start();
+ora.oraInstance.succeed('Done!');
+```
+
+## 🔧 Advanced Features
+
+### Minimum Log Level
+
+Set a minimum log level that destinations can use to filter messages:
+
+```typescript
+const logger = new Smartlog({
+  logContext: { environment: 'production', runtime: 'node' },
+  minimumLogLevel: 'warn'  // Destinations can check this to filter
+});
+
+// The minimumLogLevel is available as a public property
+console.log(logger.minimumLogLevel); // 'warn'
 ```
 
 ### Increment Logging
 
-For metrics and counters:
+Track metrics and counters alongside your logs:
 
 ```typescript
-logger.increment('info', 'api_requests', { endpoint: '/users' });
+// Track API calls
+logger.increment('info', 'api.requests', { endpoint: '/users', method: 'GET' });
+
+// Track error types
+logger.increment('error', 'payment.failed', { reason: 'insufficient_funds' });
 ```
 
-### Log Correlation
+Increment logs are routed to all destinations with `type: 'increment'` so analytics backends can aggregate them.
 
-Correlate logs across services with correlation IDs:
+### Capture All Console Output
+
+Redirect all `console.log` and `console.error` through smartlog:
 
 ```typescript
-logger.log('info', 'Request received', { userId: 'user-123' }, {
+logger.enableConsole({
-  id: 'req-abc-123',
+  captureAll: true
-  type: 'service',
+});
-  transaction: 'tx-payment-456'
+
+console.log('This goes through smartlog as info!');
+console.error('This goes through smartlog as error!');
+
+// Strings containing "Error:" are automatically classified as error level
+// All captured output is prefixed with "LOG =>" to prevent recursion
+```
+
+### Log Receiver Server
+
+Accept authenticated log packages from remote services:
+
+```typescript
+import { SmartlogReceiver } from '@push.rocks/smartlog/receiver';
+
+const receiver = new SmartlogReceiver({
+  smartlogInstance: logger,
+  passphrase: 'shared-secret',
+  validatorFunction: async (logPackage) => {
+    // Custom validation logic
+    return logPackage.context.company === 'MyCompany';
+  }
+});
+
+// Handle incoming authenticated log packages (e.g., from an HTTP endpoint)
+app.post('/logs', async (req, res) => {
+  const result = await receiver.handleAuthenticatedLog(req.body);
+  res.json(result); // { status: 'ok' } or { status: 'error' }
+});
+
+// Or handle batches
+app.post('/logs/batch', async (req, res) => {
+  await receiver.handleManyAuthenticatedLogs(req.body);
+  res.json({ status: 'ok' });
 });
 ```
 
-## API Documentation
+## 🏗️ Real-World Examples
 
-For detailed API documentation, see the [API.md](API.md) file.
+### Microservice with Distributed Tracing
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+
+// Initialize logger with service context
+const logger = new Smartlog({
+  logContext: {
+    company: 'TechCorp',
+    companyunit: 'Platform',
+    containerName: 'user-service',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'eu-central'
+  }
+});
+
+// Add ClickHouse for analytics
+const clickhouse = await SmartlogDestinationClickhouse.createAndStart({
+  url: process.env.CLICKHOUSE_URL,
+  database: 'microservices_logs'
+});
+logger.addLogDestination(clickhouse);
+
+// Add local console for container stdout
+logger.addLogDestination(new DestinationLocal());
+
+// Express middleware for request tracking
+app.use((req, res, next) => {
+  const logGroup = logger.createLogGroup(req.headers['x-request-id'] || 'unknown');
+
+  logGroup.log('info', 'Incoming request', {
+    method: req.method,
+    path: req.path,
+    ip: req.ip
+  });
+
+  res.on('finish', () => {
+    logGroup.log('info', 'Request completed', {
+      statusCode: res.statusCode,
+      duration: Date.now() - req.startTime
+    });
+  });
+
+  next();
+});
+```
+
+### CLI Tool with Progress Tracking
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { SmartlogSourceInteractive, SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
+
+const logger = new Smartlog({
+  logContext: {
+    containerName: 'migration-tool',
+    environment: 'local',
+    runtime: 'node'
+  }
+});
+
+logger.enableConsole();
+
+async function migrateDatabase() {
+  const spinner = new SmartlogSourceInteractive();
+
+  spinner.text('🔌 Connecting to database...');
+  await connectDB();
+  spinner.finishSuccess('✅ Connected to database');
+
+  spinner.text('📋 Loading migrations...');
+  const migrations = await getMigrations();
+  spinner.finishSuccess(`✅ Found ${migrations.length} migrations`);
+
+  const progress = new SmartlogProgressBar({
+    total: migrations.length,
+    width: 40,
+    showEta: true
+  });
+
+  for (const [index, migration] of migrations.entries()) {
+    await logger.log('info', `Running migration: ${migration.name}`);
+    await runMigration(migration);
+    progress.update(index + 1);
+  }
+
+  progress.complete();
+  await logger.log('success', '🎉 All migrations completed successfully!');
+}
+```
+
+### Production Logging with Multiple Destinations
+
+```typescript
+import { Smartlog } from '@push.rocks/smartlog';
+import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
+import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
+import { SmartlogDestinationReceiver } from '@push.rocks/smartlog/destination-receiver';
+
+const logger = new Smartlog({
+  logContext: {
+    company: 'Enterprise Corp',
+    containerName: 'payment-processor',
+    environment: 'production',
+    runtime: 'node',
+    zone: 'us-east-1'
+  },
+  minimumLogLevel: 'info'
+});
+
+// Color-coded console for container logs
+logger.addLogDestination(new DestinationLocal());
+
+// File for audit trail
+logger.addLogDestination(new SmartlogDestinationFile('/var/log/app/audit.log'));
+
+// Central logging service
+logger.addLogDestination(new SmartlogDestinationReceiver({
+  passphrase: process.env.LOG_PASSPHRASE,
+  receiverEndpoint: 'https://logs.enterprise.com/ingest'
+}));
+
+// Custom inline destination for critical alerts
+logger.addLogDestination({
+  async handleLog(logPackage) {
+    if (logPackage.level === 'error' && logPackage.data?.critical) {
+      await sendSlackAlert(`🚨 Critical error: ${logPackage.message}`);
+    }
+  }
+});
+```
+
+## 📖 API Reference
+
+### Smartlog Class
+
+```typescript
+class Smartlog {
+  // Static factory
+  static createForCommitinfo(commitinfo: ICommitInfo): Smartlog;
+
+  // Constructor
+  constructor(options: {
+    logContext: ILogContext;
+    minimumLogLevel?: TLogLevel;  // default: 'silly'
+  });
+
+  // Logging
+  log(level: TLogLevel, message: string, data?: any, correlation?: ILogCorrelation): Promise<void>;
+  increment(level: TLogLevel, message: string, data?: any, correlation?: ILogCorrelation): void;
+
+  // Configuration
+  enableConsole(options?: { captureAll: boolean }): void;
+  addLogDestination(destination: ILogDestination): void;
+
+  // Correlation
+  createLogGroup(transactionId?: string): LogGroup;
+
+  // Forwarding (for receiver pattern)
+  handleLog(logPackage: ILogPackage): Promise<void>;
+
+  // Instance identity
+  uniInstanceId: string;
+  logContext: ILogContext;
+  minimumLogLevel: TLogLevel;
+}
+```
+
+### LogGroup Class
+
+```typescript
+class LogGroup {
+  groupId: string;          // Auto-generated unique ID
+  transactionId: string;    // The transaction ID passed at creation
+  smartlogRef: Smartlog;    // Reference to the parent Smartlog
+
+  log(level: TLogLevel, message: string, data?: any): void;
+}
+```
+
+### ILogDestination Interface
+
+```typescript
+interface ILogDestination {
+  handleLog(logPackage: ILogPackage): Promise<void>;
+}
+```
+
+### ILogPackage Interface
+
+```typescript
+interface ILogPackage<T = unknown> {
+  timestamp: number;             // Unix timestamp in milliseconds
+  type: TLogType;                // 'log' | 'increment' | 'gauge' | ...
+  context: ILogContext;          // Environment context
+  level: TLogLevel;              // Log severity
+  correlation: ILogCorrelation;  // Correlation metadata
+  message: string;               // The log message
+  data?: T;                      // Optional structured data
+}
+```
+
+### Available Log Levels
+
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `silly` | Ultra-verbose | Function entry/exit, variable dumps |
+| `debug` | Debug info | Development-time diagnostics |
+| `info` | Informational | Standard operational messages |
+| `note` | Notable events | Important but non-critical events |
+| `ok` | Success confirmation | Health checks, validations |
+| `success` | Major success | Completed operations |
+| `warn` | Warnings | Degraded performance, approaching limits |
+| `error` | Errors | Failures requiring attention |
+| `lifecycle` | Lifecycle events | Start, stop, restart, deploy |
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH  
+Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

test/test.destination-buffer.node.ts

@@ -0,0 +1,120 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { SmartlogDestinationBuffer } from '../ts_destination_buffer/index.js';
+import type { ILogPackage, TLogLevel } from '../ts_interfaces/index.js';
+
+const createMockLogPackage = (level: TLogLevel, message: string): ILogPackage => {
+  return {
+    timestamp: Date.now(),
+    type: 'log',
+    level,
+    message,
+    context: {
+      environment: 'test',
+      runtime: 'node',
+      zone: 'test-zone',
+    },
+    correlation: {
+      id: '123',
+      type: 'none',
+    },
+  };
+};
+
+let buffer: SmartlogDestinationBuffer;
+
+tap.test('should create a buffer destination instance', async () => {
+  buffer = new SmartlogDestinationBuffer({ maxEntries: 100 });
+  expect(buffer).toBeTruthy();
+  expect(buffer.getEntryCount()).toEqual(0);
+});
+
+tap.test('should store log entries via handleLog', async () => {
+  await buffer.handleLog(createMockLogPackage('info', 'Hello world'));
+  await buffer.handleLog(createMockLogPackage('error', 'Something failed'));
+  await buffer.handleLog(createMockLogPackage('warn', 'Watch out'));
+
+  expect(buffer.getEntryCount()).toEqual(3);
+});
+
+tap.test('should retrieve entries in chronological order (oldest-first)', async () => {
+  const entries = buffer.getEntries();
+  expect(entries.length).toEqual(3);
+  expect(entries[0].message).toEqual('Hello world');
+  expect(entries[2].message).toEqual('Watch out');
+});
+
+tap.test('should filter entries by level', async () => {
+  const errorEntries = buffer.getEntries({ level: 'error' });
+  expect(errorEntries.length).toEqual(1);
+  expect(errorEntries[0].message).toEqual('Something failed');
+
+  const multiLevel = buffer.getEntries({ level: ['info', 'warn'] });
+  expect(multiLevel.length).toEqual(2);
+});
+
+tap.test('should filter entries by search string', async () => {
+  const results = buffer.getEntries({ search: 'hello' });
+  expect(results.length).toEqual(1);
+  expect(results[0].message).toEqual('Hello world');
+});
+
+tap.test('should support limit and offset pagination', async () => {
+  // limit=2, offset=0 → last 2 entries in chronological order
+  const page1 = buffer.getEntries({ limit: 2, offset: 0 });
+  expect(page1.length).toEqual(2);
+  expect(page1[0].message).toEqual('Something failed');
+  expect(page1[1].message).toEqual('Watch out');
+
+  // limit=2, offset=2 → skip 2 from end, return up to 2
+  const page2 = buffer.getEntries({ limit: 2, offset: 2 });
+  expect(page2.length).toEqual(1);
+  expect(page2[0].message).toEqual('Hello world');
+});
+
+tap.test('should filter by since timestamp', async () => {
+  const now = Date.now();
+  const freshBuffer = new SmartlogDestinationBuffer();
+
+  const oldPkg = createMockLogPackage('info', 'Old message');
+  oldPkg.timestamp = now - 60000;
+  await freshBuffer.handleLog(oldPkg);
+
+  const newPkg = createMockLogPackage('info', 'New message');
+  newPkg.timestamp = now;
+  await freshBuffer.handleLog(newPkg);
+
+  const results = freshBuffer.getEntries({ since: now - 1000 });
+  expect(results.length).toEqual(1);
+  expect(results[0].message).toEqual('New message');
+});
+
+tap.test('should enforce circular buffer max entries', async () => {
+  const smallBuffer = new SmartlogDestinationBuffer({ maxEntries: 5 });
+
+  for (let i = 0; i < 10; i++) {
+    await smallBuffer.handleLog(createMockLogPackage('info', `Message ${i}`));
+  }
+
+  expect(smallBuffer.getEntryCount()).toEqual(5);
+
+  // Should have kept the latest 5 (messages 5-9), returned chronologically
+  const entries = smallBuffer.getEntries({ limit: 10 });
+  expect(entries[0].message).toEqual('Message 5');
+  expect(entries[4].message).toEqual('Message 9');
+});
+
+tap.test('should clear all entries', async () => {
+  expect(buffer.getEntryCount()).toBeGreaterThan(0);
+  buffer.clear();
+  expect(buffer.getEntryCount()).toEqual(0);
+  expect(buffer.getEntries().length).toEqual(0);
+});
+
+tap.test('should use default maxEntries of 2000', async () => {
+  const defaultBuffer = new SmartlogDestinationBuffer();
+  // Just verify it was created without error
+  expect(defaultBuffer).toBeTruthy();
+  expect(defaultBuffer.getEntryCount()).toEqual(0);
+});
+
+export default tap.start();

test/test.destination-receiver.node.ts

@@ -53,10 +53,7 @@ tap.test('should attempt to send logs to the receiver endpoint', async () => {
   // Create a mock version of the webrequest.postJson method to avoid actual HTTP calls
   const originalPostJson = testDestination['webrequest'].postJson;
   testDestination['webrequest'].postJson = async () => {
-    return {
+    return { status: 'ok' };
-      body: { status: 'ok' },
-      statusCode: 200
-    };
   };
 
   try {

test/test.ts

@@ -23,9 +23,7 @@ tap.test('should produce instance of Smartlog', async () => {
 });
 
 tap.test('should enable console logging', async () => {
-  testSmartLog.enableConsole({
+  testSmartLog.enableConsole();
-    captureAll: true,
-  });
   console.log('this is a normal log that should be captured');
   console.log(new Error('hi there'));
   testSmartLog.log('info', 'this should only be printed once');

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartlog',
-  version: '3.1.8',
+  version: '3.2.1',
   description: 'A minimalistic, distributed, and extensible logging tool supporting centralized log management.'
 }

ts_destination_buffer/classes.destinationbuffer.ts

@@ -0,0 +1,67 @@
+import type { ILogDestination, ILogPackage, TLogLevel } from '../dist_ts_interfaces/index.js';
+
+export interface IDestinationBufferOptions {
+  maxEntries?: number;
+}
+
+export interface IBufferQueryOptions {
+  level?: TLogLevel | TLogLevel[];
+  search?: string;
+  limit?: number;
+  offset?: number;
+  since?: number;
+}
+
+export class SmartlogDestinationBuffer implements ILogDestination {
+  private logPackages: ILogPackage[] = [];
+  private maxEntries: number;
+
+  constructor(options?: IDestinationBufferOptions) {
+    this.maxEntries = options?.maxEntries ?? 2000;
+  }
+
+  public async handleLog(logPackage: ILogPackage): Promise<void> {
+    this.logPackages.push(logPackage);
+    if (this.logPackages.length > this.maxEntries) {
+      this.logPackages.shift();
+    }
+  }
+
+  public getEntries(options?: IBufferQueryOptions): ILogPackage[] {
+    const limit = options?.limit ?? 100;
+    const offset = options?.offset ?? 0;
+
+    let results = this.logPackages;
+
+    // Filter by level
+    if (options?.level) {
+      const levels = Array.isArray(options.level) ? options.level : [options.level];
+      results = results.filter((pkg) => levels.includes(pkg.level));
+    }
+
+    // Filter by search (message content)
+    if (options?.search) {
+      const searchLower = options.search.toLowerCase();
+      results = results.filter((pkg) => pkg.message.toLowerCase().includes(searchLower));
+    }
+
+    // Filter by timestamp
+    if (options?.since) {
+      results = results.filter((pkg) => pkg.timestamp >= options.since);
+    }
+
+    // Return most recent `limit` entries in chronological order (oldest-first)
+    // offset skips from the newest end
+    const start = Math.max(0, results.length - limit - offset);
+    const end = results.length - offset;
+    return results.slice(Math.max(0, start), Math.max(0, end));
+  }
+
+  public getEntryCount(): number {
+    return this.logPackages.length;
+  }
+
+  public clear(): void {
+    this.logPackages = [];
+  }
+}

ts_destination_buffer/index.ts

@@ -0,0 +1 @@
+export { SmartlogDestinationBuffer, type IDestinationBufferOptions, type IBufferQueryOptions } from './classes.destinationbuffer.js';

ts_destination_buffer/plugins.ts

@@ -0,0 +1,3 @@
+import * as smartlogInterfaces from '../dist_ts_interfaces/index.js';
+
+export { smartlogInterfaces };

ts_destination_receiver/index.ts

@@ -12,7 +12,7 @@ export interface ISmartlogDestinationReceiverConstructorOptions {
 
 export class SmartlogDestinationReceiver implements ILogDestination {
   private options: ISmartlogDestinationReceiverConstructorOptions;
-  private webrequest = new plugins.webrequest.WebRequest();
+  private webrequest = new plugins.webrequest.WebrequestClient();
 
   constructor(optionsArg: ISmartlogDestinationReceiverConstructorOptions) {
     this.options = optionsArg;
@@ -30,6 +30,6 @@ export class SmartlogDestinationReceiver implements ILogDestination {
       }
       this.errorCounter++;
     });
-    return response.body;
+    return response;
   }
 }