crd-node-tools

v0.7.7

Published

14 days ago

A Node.js/TypeScript logging toolkit with file logging, email notifications, webhook alerts, remote API forwarding, and a built-in web admin panel.

0High
0Medium
0Low

andrey-commradian

logger logging webhook email admin-panel typescript

CRD Node Tools

A TypeScript-first, standalone logging toolkit for Node.js applications. Features file-based logging, SMTP email notifications, configurable webhooks, remote API forwarding, and a built-in web-based admin panel — all in a single package.

Features

| Feature | Description | | --- | --- | | File Logging | Daily-rotated .log files with configurable level filtering | | Log Levels | trace → debug → info → warning → error | | Console Echo | Optionally mirror log output to stdout | | Email Alerts | SMTP-based error notifications with 5-per-5-minute throttle | | Webhook | POST to any URL (Slack, Discord, etc.) with a JSON template | | Remote API | Forward structured log data to an external endpoint | | Admin Panel | Modern web UI for managing all settings at runtime | | Config File | Persistent JSON config (crd-tools.config.json) | | TypeScript | Full type definitions and strict mode |

Installation

# Clone or copy the crd-node-tools folder into your project
npm install

Or, if published to a registry:

npm install crd-node-tools

Quick Start

import { CrdTools } from 'crd-node-tools';

const crd = new CrdTools();

// Start the admin panel on port 9100
await crd.startAdminPanel();

// Log messages
crd.logger.info('Server started', 'server.ts', 'main');
crd.logger.warning('Memory usage high', 'monitor.ts', 'check');
crd.logger.error('DB timeout', 'db.ts', 'connect', true);
//                                                  ^^^^ sends email

Configuration

On first run, a crd-tools.config.json file is created in the working directory with sensible defaults:

{
  "appName": "My App",
  "appUrl": "http://localhost",
  "adminPort": 9100,
  "logger": {
    "logFolderPath": "logs",        // relative to project root
    "logLevel": "info",             // trace | debug | info | warning | error
    "alsoLogToConsole": false
  },
  "email": {
    "enabled": false,
    "recipientEmail": "",
    "smtp": {
      "host": "",
      "port": 587,
      "secure": false,
      "auth": { "user": "", "pass": "" },
      "fromName": "CRD Node Tools",
      "fromEmail": "noreply@localhost"
    }
  },
  "webhook": {
    "enabled": false,
    "url": "",
    "bodyTemplate": "{ ... }"
  },
  "remoteApi": {
    "enabled": false,
    "endpointUrl": "",
    "bodyTemplate": "{ ... }"
  }
}

Programmatic updates

crd.updateConfig({
  logger: { logLevel: 'debug', alsoLogToConsole: true },
  email: { enabled: true, recipientEmail: '[email protected]' },
});

Logger API

crd.logger.trace(message, file?, func?);
crd.logger.debug(message, file?, func?);
crd.logger.info(message, file?, func?);
crd.logger.warning(message, file?, func?);
crd.logger.error(message, file?, func?, notifyAdmin?);

| Parameter | Type | Description | | --- | --- | --- | | message | string | The log message | | file | string? | Source file name (for context) | | func | string? | Function name (for context) | | notifyAdmin | boolean | (error only) Send email notification |

Log output

[2025-01-15 09:32:14.123] [INFO   ] [server.ts] main() Application started
[2025-01-15 09:32:14.456] [ERROR  ] [db.ts] connect() Connection timed out

Admin Panel

Start the built-in web dashboard:

const port = await crd.startAdminPanel();   // default 9100
console.log(`Admin → http://localhost:${port}`);

The panel provides:

General settings — app name, URL, admin port
Logger config — log path, level, console echo toggle
Email / SMTP — full SMTP configuration with test buttons
Webhook — URL + JSON body template with placeholders
Remote API — endpoint URL + body template
Log Browser — list daily log files from the configured log directory
Log Export — download merged logs for a selected date range
Quick Start Guide — accordion-based in-panel documentation

Embed in existing Express app

import express from 'express';
import { ConfigManager, AdminPanel } from 'crd-node-tools';

const app = express();
const cfgMgr = new ConfigManager();
const panel = new AdminPanel(cfgMgr);

app.use('/admin', panel.getApp());
app.listen(3000);

Email Notifications

Configure SMTP settings via the admin panel or config file. When notifyAdmin: true is passed to .error(), an email is sent to the configured recipient.

Throttling: Maximum 5 emails per 5-minute window to prevent floods.

// This sends an email if email.enabled = true and SMTP is configured
crd.logger.error('Critical failure', 'payment.ts', 'charge', true);

Webhook

Enable the webhook to POST structured JSON on every log entry (above the level threshold):

{
  "level": "{{level}}",
  "message": "{{message}}",
  "file": "{{file}}",
  "function": "{{function}}",
  "app": "{{app_name}}",
  "time": "{{timestamp}}"
}

Available placeholders

| Placeholder | Value | | --- | --- | | {{level}} / {{severity}} | Log level (e.g. error) | | {{message}} | The log message | | {{file}} / {{filename}} | Source file | | {{function}} / {{function_name}} | Function name | | {{app_name}} | Configured app name | | {{app_url}} | Configured app URL | | {{timestamp}} | ISO timestamp |

Remote API

Forwards log data to an external API endpoint using a customisable JSON body template. Uses the same placeholder system as webhooks.

Architecture

crd-node-tools/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── LICENSE
└── src/
    ├── index.ts            ← Public API + CrdTools facade
    ├── config.ts           ← Type definitions & defaults
    ├── config-manager.ts   ← Load/save JSON config file
    ├── logger.ts           ← Core file logger + email/webhook/remote
    ├── email-service.ts    ← Nodemailer wrapper with throttling
    ├── admin-panel.ts      ← Express web dashboard (HTML/CSS/JS)
    └── demo.ts             ← Usage example

Scripts

npm run build       # Compile TypeScript → dist/
npm run demo        # Run the demo with ts-node
npm run dev         # Run src/index.ts with ts-node
npm start           # Run compiled dist/index.js (library entry)

Release Flow (npm)

Use this release sequence:

npm version patch
git push
git push --tags

What each step does:

npm version patch bumps package.json/lock version and creates a git commit + tag.
git push pushes the release commit.
git push --tags pushes the version tag.

If you use this repository's GitHub Actions publishing workflow (.github/workflows/publish-npm.yml), publishing is triggered when a GitHub Release is created, so create a Release for the pushed tag.