Centralized error and log notification service for Invictus microservices. This package provides a unified way to send errors and logs directly to Telegram, eliminating the need for an intermediate notify service.

Installation

npm install @invictusdev/invictus-logger

Works with both TypeScript and JavaScript projects! See JavaScript Usage section below.

Usage

Basic Setup (Recommended)

Telegram credentials are already hardcoded in the library, so you only need to specify the service name:

import { createErrorNotifier } from "@invictusdev/invictus-logger";

const errorNotifier = createErrorNotifier({
  serviceName: "MY_SERVICE", // Must match a key in MessageThreadId
});

export default errorNotifier;

Advanced Setup (Custom Credentials)

If you need to use custom Telegram credentials:

import { createErrorNotifier } from "@invictusdev/invictus-logger";

const errorNotifier = createErrorNotifier({
  serviceName: "MY_SERVICE",
  telegramBotToken: process.env.CUSTOM_BOT_TOKEN, // optional
  telegramChatId: process.env.CUSTOM_CHAT_ID, // optional
  timeout: 5000, // optional, defaults to 5000ms
});

export default errorNotifier;

Environment Variables (Optional)

The library reads credentials from environment variables by default:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

You can override them per service if needed.

Sending Errors

// In your error handler middleware
app.use(async (err, req, res, next) => {
  console.error(err);

  // Send error to Telegram via notify service
  await errorNotifier.sendError(err, req);

  res.status(500).json({ error: "Internal server error" });
});

Sending Logs

// Send a log message
await errorNotifier.sendLog("Important event occurred", req);

// Or with custom context
await errorNotifier.sendLog("Cron job failed", {
  path: "/cron/job",
  method: "CRON",
  env: process.env.NODE_ENV,
});

Using with GraphQL

import { ErrorNotifier } from "@invictusdev/invictus-logger";

const errorNotifier = new ErrorNotifier({
  serviceName: "GRAPHQL_SERVICE",
});

const errorPlugin = {
  requestDidStart() {
    return {
      async didEncounterErrors(requestContext) {
        if (requestContext.errors?.length > 0) {
          const error = new Error(requestContext.errors[0].message);
          await errorNotifier.sendError(error, {
            path: requestContext.request.operationName,
            method: "GraphQL",
            user: requestContext.context.user,
          });
        }
      },
    };
  },
};

Using in Cron Jobs

try {
  await someCronTask();
} catch (error) {
  await errorNotifier.sendError(error as Error, {
    path: "/cron/task",
    method: "CRON",
    env: process.env.NODE_ENV,
  });
}

🆕 Enhanced Error Context (v1.6.0+)

The library now captures ALL additional context you provide, giving you maximum debugging information:

// Cluster/Worker errors
await errorNotifier.sendError(error, {
  path: "/api/users",
  method: "POST",
  body: req.body,
  query: req.query, // 🆕 Query params
  headers: req.headers, // 🆕 Headers (sensitive data filtered)
  user: req.user,
  workerId: worker.id, // 🆕 Worker ID
  workerPid: worker.process.pid, // 🆕 Worker PID
  instanceId: process.env.INSTANCE_ID, // 🆕 ECS/K8s instance
  reason: "uncaughtException", // 🆕 Error reason
  source: "cluster/worker-3", // 🆕 Error source
  memory: process.memoryUsage(), // 🆕 Memory stats
  customData: {
    /* anything */
  }, // 🆕 Any custom fields
});

What you'll see in Telegram:

🚨 Error in MY_SERVICE
🕐 Time: 2025-10-29 15:30:45 (UTC+5)
🌐 ENV: production
👤 User: 507f1f77bcf86cd799439011
⚙️ Worker: 3                    ← 🆕
🔧 PID: 12345                   ← 🆕
🖥️ Instance: i-0abc123def456789 ← 🆕
📝 Reason: uncaughtException     ← 🆕
📍 Source: cluster/worker-3      ← 🆕
📌 Path: /api/users
💊 Method: POST
🚨 Error: Cannot read property 'id' of undefined

🔍 Query Params:                 ← 🆕

{ "limit": "10", "sort": "createdAt" }


📋 Headers:                      ← 🆕

{ "content-type": "application/json", "user-agent": "axios/1.6.0", "authorization": "[REDACTED]" ← Sensitive data filtered }


📦 Request Body:

{ "name": "John", "email": "john@example.com" }


💾 Memory:                       ← 🆕

{ "heapUsed": 125829120, "heapTotal": 142606336, "rss": 189345792 }


📦 Stack Trace:

at UserController.create (/app/src/controllers/user.ts:45:12) ...


**Security Features:**

- 🔒 **Automatic sensitive data filtering** for headers:
  - `authorization`, `cookie`, `x-api-key`, `x-auth-token`, `x-csrf-token`, `password`, `secret`
  - Replaced with `[REDACTED]`

- 📏 **Smart message truncation**:
  - Automatically fits into Telegram's 4000 character limit
  - Prioritizes important sections (stack trace kept last)
  - Truncated sections show `...truncated...`

## Telegram Thread Mapping

Each service sends messages to its own thread in the Telegram group. The service name must match one of these:

```typescript
import { MessageThreadId } from "@invictusdev/invictus-logger";

// Available services:
// - NOTIFY
// - CONTENT_SERVICE
// - PAYMENT_SERVICE
// - MAIN_SERVICE
// - SOCIETY_SERVICE
// - GYMBUDDY_SERVICE
// - COACH_SERVICE
// - RABBITMQ
// - CRONS

To add a new service, update the MessageThreadId in the library.

API Reference

`createErrorNotifier(config)`

Creates a new ErrorNotifier instance.

Parameters:

config.serviceName (string, required) - Name of your service (must match MessageThreadId key)
config.telegramBotToken (string, required) - Telegram bot token
config.telegramChatId (string, required) - Telegram chat ID
config.timeout (number, optional) - Request timeout in ms (default: 5000)
config.suppressWarnings (boolean, optional) - Suppress warnings (default: false)

`errorNotifier.sendError(error, reqOrContext?)`

Sends an error notification.

Parameters:

error (Error, required) - The error object to send
reqOrContext (RequestLike | ErrorContext, optional) - Express request or custom context

`errorNotifier.sendLog(message, reqOrContext?)`

Sends a log notification.

Parameters:

message (string, required) - The log message
reqOrContext (RequestLike | ErrorContext, optional) - Express request or custom context

`errorNotifier.send(error, reqOrContext?)`

Alias for sendError() for backward compatibility.

Types

interface ErrorContext {
  path?: string;
  method?: string;
  body?: unknown;
  query?: unknown; // 🆕 v1.6.0
  user?: any;
  env?: string;
  headers?: Record<string, string | string[] | undefined>; // 🆕 v1.6.0
  [key: string]: any; // Any additional fields (workerId, memory, etc.)
}

interface RequestLike {
  originalUrl?: string;
  path?: string;
  method?: string;
  body?: unknown;
  query?: unknown; // 🆕 v1.6.0
  user?: any;
  headers?: Record<string, string | string[] | undefined>;
  [key: string]: any; // Any additional fields
}

Migration Guide

From Old HTTP-based Implementation

Before:

// Old: services/error-notifier.service.ts
import axios from "axios";

class ErrorNotifierService {
  async send(error: Error, req: any) {
    await axios.post(`${NOTIFY_SERVICE_URL}/api/errors`, {
      service: "MY_SERVICE",
      message: error.message,
      stack: error.stack,
      context: {
        /* ... */
      },
    });
  }
}

After:

// New: config/errorNotifier.ts
import { createErrorNotifier } from "@invictusdev/invictus-logger";

const errorNotifier = createErrorNotifier({
  serviceName: "MY_SERVICE",
  telegramBotToken: process.env.TELEGRAM_BOT_TOKEN!,
  telegramChatId: process.env.TELEGRAM_CHAT_ID!,
});

export default errorNotifier;

// Usage remains the same:
await errorNotifier.sendError(error, req);
await errorNotifier.send(error, req); // backward compatible

Benefits of Direct Telegram Integration

✅ No intermediate service - Reduces latency and points of failure
✅ Simplified architecture - One less microservice to maintain
✅ Better reliability - Direct connection to Telegram API
✅ Same interface - Drop-in replacement for existing code

Morgan Integration

The library includes a ready-to-use Morgan configuration for HTTP request logging:

import express from "express";
import morgan from "morgan";
import {
  createMorganConfig,
  captureResponseBody,
} from "@invictusdev/invictus-logger";

const app = express();
app.use(express.json());

// Capture response body (BEFORE morgan)
app.use(captureResponseBody());

// Use Morgan with configuration
const morganConfig = createMorganConfig({
  nodeEnv: process.env.NODE_ENV,
});

app.use(morgan(morganConfig.format, morganConfig.options));

Features:

✅ Auto-truncate base64 data URLs
✅ Beautiful log formatting
✅ Logs body, params, query, response
✅ Skip health-check endpoints
✅ Skip successful requests in production
✅ TypeScript types included

See MORGAN_GUIDE.md for detailed documentation.

Process Error Handlers

Automatically catch and log unhandled errors and process shutdowns:

import {
  createErrorNotifier,
  setupProcessErrorHandlers,
} from "@invictusdev/invictus-logger";

const errorNotifier = createErrorNotifier({
  serviceName: "MY_SERVICE",
});

// Setup automatic handlers for uncaught errors
setupProcessErrorHandlers(errorNotifier, {
  onBeforeExit: async () => {
    // Cleanup: close DB, Redis, RabbitMQ, etc.
    await closeAllConnections();
  },
});

Features:

✅ Auto-log uncaughtException
✅ Auto-log unhandledRejection
✅ Auto-log SIGTERM (Docker/Kubernetes shutdown)
✅ Auto-log SIGINT (Ctrl+C)
✅ Custom cleanup function before exit
✅ Configurable behavior

What gets logged:

💥 Uncaught exceptions with full stack trace
💥 Unhandled promise rejections
💤 Graceful shutdowns (SIGTERM/SIGINT)

See PROCESS_HANDLERS.md for detailed documentation.

JavaScript Compatibility

This library works perfectly with plain JavaScript projects (no TypeScript required):

// CommonJS
const { createErrorNotifier } = require("@invictusdev/invictus-logger");

const errorNotifier = createErrorNotifier({
  serviceName: "MY_SERVICE",
});

module.exports = errorNotifier;

// ES Modules
import { createErrorNotifier } from "@invictusdev/invictus-logger";

export default createErrorNotifier({
  serviceName: "MY_SERVICE",
});

Features:

✅ Full compatibility with JavaScript (CommonJS & ES Modules)
✅ TypeScript definitions optional (for autocomplete)
✅ Works in Node.js without TypeScript installed
✅ Same API for both JS and TS projects

See JAVASCRIPT_USAGE.md for complete JavaScript examples.

License

ISC

Keywords

FAQs

What is @invictusdev/invictus-logger?

Is @invictusdev/invictus-logger well maintained?

Package last updated on 05 Nov 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@invictusdev/invictus-logger