tracelog-client-sdk 0.2.2 → 1.0.0

package/README.md

@@ -1,77 +1,146 @@
 # tracelog-client-sdk
 
-This is the official Node.js client library for the TraceLog (TraceLog API's address or website) platform.
+The official, high-performance Node.js client library for the TraceLog platform.
 
-This SDK allows you to easily send logs and metrics from your Node.js applications to the TraceLog API. It eliminates the complexity of issuing manual POST requests with axios.
+TraceLog SDK goes beyond simple logging. It automatically tracks HTTP request durations, redacts sensitive data (like passwords) before they leave your server, and provides global context management for advanced filtering.
 
-### Özellikler
----
--Simple and intuitive API (.info(), .error())
+Say goodbye to complex manual logging and missing performance metrics!
 
--Automatic API Key management
+## Features
 
--ypeScript support (includes type definitions)
+- **Express HTTP Middleware:** Automatically tracks HTTP method, URL, status code, client IP, and exact request duration (ms).
+- **Auto-Redaction (Security First):** Automatically masks sensitive keys (e.g., `password`, `token`, `credit_card`) with `[REDACTED]` before sending data to the backend.
+- **Global Context:** Inject custom data (like environment, app version, or user IDs) into all logs automatically.
+- **Graceful Shutdown:** Catches `SIGTERM/SIGINT` to securely log system shutdowns before your Node.js process exits.
+- **TypeScript Ready:** Built with TypeScript, providing out-of-the-box type safety, intelligent autocompletion, and zero friction.
 
--Asynchronous log sending in the background
+---
 
 ## Installation
+
 You can install the package in your project using NPM or Yarn:
-```
+
+```bash
 npm install tracelog-client-sdk
 ```
-🛠️ Usage
-Using the SDK is very simple. First, import the LogStreamer class and create an instance with your API Key.
+## Quick Start
+1. Initialization
+Import the SDK and initialize it with your Project ID and API Key.
+
+### JavaScript (CommonJS):
 
-JavaScript
---
+### JavaScript
 ```
+const { TraceLog } = require('tracelog-client-sdk');
 
-//JavaScript (CommonJS)
-const { LogStreamer } = require('tracelog-client-sdk');
+const logger = new TraceLog({
+    projectId: 'YOUR_PROJECT_ID',
+    apiKey: 'YOUR_API_KEY',
+    backendUrl: '[https://api.yourdomain.com](https://api.yourdomain.com)' // Optional: Defaults to localhost for local testing
+});
+```
+### TypeScript (ES Modules):
 
-//TypeScript (ES Modules)
-import { LogStreamer } from 'tracelog-client-sdk';
+### TypeScript
+```
+import { TraceLog } from 'tracelog-client-sdk';
 
-//1. Start the SDK with your API Key
-//(You must get this API Key from your LogStream panel)
-const logger = new LogStreamer('YOUR_SECRET_API_KEY_HERE');
+const logger = new TraceLog({
+    projectId: 'YOUR_PROJECT_ID',
+    apiKey: 'YOUR_API_KEY'
+});
+```
+---
+### 2. Basic Logging
+You can log messages with standard levels (info, warn, error, fatal, debug) and attach custom metadata.
 
-//2. Start sending logs!
+### JavaScript
+```
+// A log at the information level
+logger.log('info', 'User successfully authenticated', {
+    userId: 'user_123',
+    method: 'OAuth2'
+});
 
-//A log at the information level
-logger.info('User logged in successfully', {
-  userId: 'user-123',
-  process: 'auth'
+// The SDK automatically masks sensitive fields!
+logger.log('warn', 'Failed login attempt', {
+    email: 'test@test.com',
+    password: 'my_secret_password' // This will securely be sent as [REDACTED]
 });
+```
+
+## Advanced Features
+Auto HTTP Tracking (Express Middleware)
+Track every single request in your Express app without writing manual logs. It calculates the exact response time (durationMs) and detects errors automatically.
 
-//A log at the error level
-try {
-  //... Error-potential code ...
-  throw new Error('Database connection broken');
-} catch (error) {
-  logger.error(error.message, {
-    statusCode: 500,
-    component: 'database-service'
+### JavaScript
+```
+const express = require('express');
+const { TraceLog, expressMiddleware } = require('tracelog-client-sdk');
+
+const app = express();
+const logger = new TraceLog({ projectId: '123', apiKey: 'sk_...' });
+
+// Add this before your routes to track all incoming traffic!
+app.use(expressMiddleware(logger));
+
+app.get('/', (req, res) => {
+    res.send('TraceLog is watching this route!');
 });
-}
+
+app.listen(8080);
+```
+
+## Global Context Management
+If you want to attach specific data (like the current environment or app version) to every log sent from your application, use the context manager.
+
+### JavaScript
+```
+// Set it once (e.g., on app startup or user login)
+logger.setContext({
+    environment: 'production',
+    appVersion: '2.1.0'
+});
+
+// All subsequent logs will automatically include { environment: 'production', appVersion: '2.1.0' }.
+logger.log('info', 'Database connected successfully');
+
+// To clear context when needed:
+// logger.clearContext();
 ```
-Sending logs is done asynchronously in the background and does not prevent your main application from running.
 
 ## API Reference
--new LogStreamer(apiKey)
-Starts the SDK client.
+```
+new TraceLog(options)
+```
+### Starts the SDK client.
+
+- ***projectId (string | number, Required):*** Your TraceLog project ID.
 
--apiKey (string, Required): Your API key obtained from your LogStream panel.
+- ***apiKey (string, Required):*** Your secure API key obtained from your TraceLog panel.
 
--.info(message, [metadata])
-Sends a log at info level.
+- ***backendUrl (string, Optional):*** Custom backend URL for self-hosted instances.
+```
+logger.log(level, message, [metadata])
+```
+### Sends an asynchronous log to the TraceLog API.
+---
+- ***level (string, Required):*** 'info' | 'warn' | 'error' | 'fatal' | 'debug'
+
+- ***message (string, Required):*** The main log message.
+
+- ***metadata (object, Optional):*** Extra JSON data to be added to the log.
+```
+logger.setContext(contextData)
+```
 
--message (string, Required): The main log message to send.
+### Appends default metadata to all future logs.
+---
+- ***contextData (object, Required):*** JSON object containing the context data.
+```
+expressMiddleware(loggerInstance)
+```
+Returns an Express middleware function that auto-logs HTTP traffic, calculates durations, and maps HTTP status codes to log levels.
 
--metadata (object, Optional): Extra JSON data to be added to the log (eg: user ID, session ID, etc.).
--.error(message, [metadata])
-It sends a log at error level.
 
--message (string, Required): Error message.
 
--metadata (object, Optional): Extra context information about the error (e.g. stack trace, request ID, etc.).

package/dist/core/TraceLog.d.ts

@@ -0,0 +1,17 @@
+export interface TraceLogOptions {
+    projectId: string;
+    apiKey: string;
+    backendUrl?: string;
+}
+export declare class TraceLog {
+    private projectId;
+    private apiKey;
+    private backendUrl;
+    private globalContext;
+    private sensitiveKeys;
+    constructor(options: TraceLogOptions);
+    setContext(contextData: Record<string, any>): void;
+    clearContext(): void;
+    log(level: 'info' | 'warn' | 'error' | 'fatal' | 'debug', message: string, metadata?: any): Promise<void>;
+    private setupGracefulShutdown;
+}

package/dist/core/TraceLog.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceLog = void 0;
+const axios_1 = __importDefault(require("axios"));
+const redactor_1 = require("../utils/redactor");
+class TraceLog {
+    constructor(options) {
+        this.globalContext = {};
+        this.sensitiveKeys = ['password', 'token', 'secret', 'credit_card', 'authorization', 'ssn'];
+        this.projectId = options.projectId.toString();
+        this.apiKey = options.apiKey.replace('ApiKey ', '').trim();
+        this.backendUrl = options.backendUrl || 'http://localhost:3001';
+        this.setupGracefulShutdown();
+    }
+    setContext(contextData) {
+        this.globalContext = { ...this.globalContext, ...contextData };
+    }
+    clearContext() {
+        this.globalContext = {};
+    }
+    async log(level, message, metadata = {}) {
+        try {
+            const safeMetadata = (0, redactor_1.maskSensitiveData)({ ...this.globalContext, ...metadata }, this.sensitiveKeys);
+            await axios_1.default.post(`${this.backendUrl}/log/ingest`, {
+                level,
+                message,
+                metadata: safeMetadata,
+                timestamp: new Date().toISOString(),
+                projectId: this.projectId
+            }, {
+                headers: {
+                    'Authorization': `ApiKey ${this.apiKey}`,
+                    'x-project-id': this.projectId,
+                    'Content-Type': 'application/json',
+                },
+                timeout: 5000,
+            });
+        }
+        catch (error) {
+            console.error('[TraceLog SDK Error]: Log could not be sent:', error.message);
+        }
+    }
+    setupGracefulShutdown() {
+        const handleExit = async (signal) => {
+            await this.log('fatal', `System Shutdown Triggered: ${signal}`, { action: 'shutdown' });
+        };
+        process.on('SIGTERM', () => handleExit('SIGTERM'));
+        process.on('SIGINT', () => handleExit('SIGINT'));
+    }
+}
+exports.TraceLog = TraceLog;

package/dist/index.d.ts

@@ -1,9 +1,2 @@
-export declare class LogStreamer {
-    private apiKey;
-    private httpClient;
-    private baseUrl;
-    constructor(apikey: string);
-    info(message: string, metadata?: object): void;
-    error(message: string, metadata?: object): void;
-    private sendLog;
-}
+export { TraceLog, TraceLogOptions } from './core/TraceLog';
+export { expressMiddleware } from './middlewares/express';

package/dist/index.js

@@ -1,46 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogStreamer = void 0;
-const axios_1 = __importDefault(require("axios"));
-class LogStreamer {
-    constructor(apikey) {
-        this.baseUrl = 'http://localhost:3001/log';
-        if (!apikey) {
-            throw new Error('[TraceLog] API key is required.');
-        }
-        this.apiKey = apikey;
-        this.httpClient = axios_1.default.create({
-            baseURL: this.baseUrl,
-            headers: {
-                "Authorization": `ApiKey ${this.apiKey}`,
-                "Content-Type": "application/json",
-            }
-        });
-    }
-    info(message, metadata = {}) {
-        this.sendLog('info', message, metadata);
-    }
-    error(message, metadata = {}) {
-        this.sendLog('error', message, metadata);
-    }
-    async sendLog(level, message, metadata) {
-        const payload = {
-            message,
-            level,
-            metadata,
-            timestamp: new Date().toISOString()
-        };
-        try {
-            await this.httpClient.post('/ingest', payload);
-        }
-        catch (error) {
-            if (axios_1.default.isAxiosError(error)) {
-                console.error('[TraceLog Error] Sunucuya ulaşılamadı:', error.message);
-            }
-        }
-    }
-}
-exports.LogStreamer = LogStreamer;
+exports.expressMiddleware = exports.TraceLog = void 0;
+var TraceLog_1 = require("./core/TraceLog");
+Object.defineProperty(exports, "TraceLog", { enumerable: true, get: function () { return TraceLog_1.TraceLog; } });
+var express_1 = require("./middlewares/express");
+Object.defineProperty(exports, "expressMiddleware", { enumerable: true, get: function () { return express_1.expressMiddleware; } });

package/dist/middlewares/express.d.ts

@@ -0,0 +1,3 @@
+import { Request, Response, NextFunction } from 'express';
+import { TraceLog } from '../core/TraceLog';
+export declare const expressMiddleware: (logger: TraceLog) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/middlewares/express.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expressMiddleware = void 0;
+const expressMiddleware = (logger) => {
+    return (req, res, next) => {
+        const startTime = Date.now();
+        res.on('finish', () => {
+            const duration = Date.now() - startTime;
+            let level = 'info';
+            if (res.statusCode >= 400 && res.statusCode < 500)
+                level = 'warn';
+            if (res.statusCode >= 500)
+                level = 'error';
+            logger.log(level, `HTTP ${req.method} ${req.originalUrl}`, {
+                http: {
+                    method: req.method,
+                    url: req.originalUrl,
+                    statusCode: res.statusCode,
+                    duration: duration,
+                }
+            });
+        });
+        next();
+    };
+};
+exports.expressMiddleware = expressMiddleware;

package/dist/utils/redactor.d.ts

@@ -0,0 +1 @@
+export declare const maskSensitiveData: (data: any, sensitiveKeys: string[]) => any;

package/dist/utils/redactor.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskSensitiveData = void 0;
+const maskSensitiveData = (data, sensitiveKeys) => {
+    if (!data || typeof data !== 'object')
+        return data;
+    const maskedData = Array.isArray(data) ? [...data] : { ...data };
+    for (const key in maskedData) {
+        if (Object.prototype.hasOwnProperty.call(maskedData, key)) {
+            const lowerKey = key.toLocaleLowerCase();
+            const isSensitive = sensitiveKeys.some(sk => lowerKey.includes(sk));
+            if (isSensitive) {
+                maskedData[key] = '[REDACTED]';
+            }
+            else if (typeof maskedData[key] === 'object') {
+                maskedData[key] = (0, exports.maskSensitiveData)(maskedData[key], sensitiveKeys);
+            }
+        }
+    }
+    return maskedData;
+};
+exports.maskSensitiveData = maskSensitiveData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracelog-client-sdk",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "description": "Views of the official SDK for the TraceLog SaaS platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,9 +24,11 @@
   "author": "Yakup Hadutoğlu <yakuphad2004@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "axios": "^1.13.2"
+    "axios": "^1.13.2",
+    "express": "^5.2.1"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^24.10.1"
   }
 }