unnbound-logger-sdk 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Type definitions for structured logging library
+ */
+/**
+ * Available log levels
+ */
+export type LogLevel = "info" | "debug" | "error" | "warn";
+/**
+ * Available log types
+ */
+export type LogType = "general" | "httpRequest" | "httpResponse" | "sftpTransaction" | "dbQueryTransaction";
+/**
+ * HTTP methods supported for HTTP logging
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+export interface SerializableError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export interface Log<T extends LogType = 'general'> {
+    level: LogLevel;
+    type: T;
+    message: string;
+    traceId: string;
+    requestId: string;
+    error?: SerializableError;
+}
+export interface LogTransaction<T extends LogType> extends Log<T> {
+    duration: number;
+}
+export interface HttpRequestLog extends LogTransaction<'httpRequest'> {
+    httpRequest: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        ip?: string;
+        body?: unknown;
+    };
+}
+export interface HttpResponseLog extends LogTransaction<'httpResponse'> {
+    httpResponse: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        ip?: string;
+        status: number;
+        body?: unknown;
+    };
+}
+export interface SftpTransactionLog extends LogTransaction<'sftpTransaction'> {
+    sftp: {
+        host: string;
+        username: string;
+        operation: 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat';
+        path: string;
+        status: 'success' | 'failure';
+        bytesTransferred?: number;
+        filesListed?: number;
+        sourcePath?: string;
+    };
+}
+export interface DbQueryTransactionLog extends LogTransaction<'dbQueryTransaction'> {
+    db: {
+        instance: string;
+        vendor: 'postgres' | 'mysql' | 'mssql' | 'mongodb';
+        query?: string;
+        status: 'success' | 'failure';
+        rowsReturned?: number;
+        rowsAffected?: number;
+    };
+}
+/**
+ * Configuration options for the logger
+ */
+export interface LoggerOptions {
+    /** Default log level */
+    defaultLevel?: LogLevel;
+    /** Optional service name to include in logs */
+    serviceName?: string;
+    /** Optional environment name to include in logs */
+    environment?: string;
+    /** Optional trace header key */
+    traceHeaderKey?: string;
+    /** Routes to ignore in trace middleware (supports glob patterns) */
+    ignoreTraceRoutes?: string[];
+    /** Routes to ignore in axios trace middleware (supports glob patterns) */
+    ignoreAxiosTraceRoutes?: string[];
+}
+/**
+ * Options for general logs
+ */
+export interface GeneralLogOptions {
+    /** Log level override */
+    level?: LogLevel;
+    /** Custom trace ID */
+    traceId?: string;
+    /** Custom request ID */
+    requestId?: string;
+    /** Custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Options for HTTP request logs
+ */
+export interface HttpRequestLogOptions extends GeneralLogOptions {
+    /** Start time of the request for duration calculation */
+    startTime?: number;
+}
+/**
+ * Options for HTTP response logs
+ */
+export interface HttpResponseLogOptions extends HttpRequestLogOptions {
+    /** Duration of the request in milliseconds */
+    duration?: number;
+}
+/**
+ * Options for SFTP transaction logs
+ */
+export interface SftpTransactionLogOptions extends GeneralLogOptions {
+    /** Start time of the transaction for duration calculation */
+    startTime?: number;
+    /** Duration of the transaction in milliseconds */
+    duration?: number;
+}
+/**
+ * Options for database query transaction logs
+ */
+export interface DbQueryTransactionLogOptions extends GeneralLogOptions {
+    /** Start time of the query for duration calculation */
+    startTime?: number;
+    /** Duration of the query in milliseconds */
+    duration?: number;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for structured logging library
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/unnbound-logger.d.ts

@@ -0,0 +1,105 @@
+import { LogLevel, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions } from './types';
+import { Request, Response, NextFunction } from 'express';
+import { InternalAxiosRequestConfig } from 'axios';
+/**
+ * UnnboundLogger provides typed, structured logging using Pino
+ */
+export declare class UnnboundLogger {
+    private logger;
+    private defaultLevel;
+    private serviceName?;
+    private environment?;
+    private traceHeaderKey;
+    private ignoreTraceRoutes;
+    private ignoreAxiosTraceRoutes;
+    /**
+     * Creates a new UnnboundLogger instance
+     * @param options - Configuration options for the logger
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Checks if a path matches any of the ignore patterns
+     * @param path - The path to check
+     * @param patterns - Array of glob patterns to match against
+     * @returns boolean indicating if the path should be ignored
+     */
+    private shouldIgnorePath;
+    /**
+     * Logs a general message
+     * @param level - Log level
+     * @param message - Log message
+     * @param options - Additional logging options
+     */
+    log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    /**
+     * Logs an error message
+     * @param message - Error message or object
+     * @param options - Additional logging options
+     */
+    error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param options - Additional logging options
+     */
+    warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    /**
+     * Logs an info message
+     * @param message - Info message
+     * @param options - Additional logging options
+     */
+    info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    /**
+     * Logs a debug message
+     * @param message - Debug message
+     * @param options - Additional logging options
+     */
+    debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void;
+    /**
+     * Logs an HTTP request
+     * @param req - Express request object
+     * @param options - Additional logging options
+     * @returns The request ID for correlating with the response
+     */
+    httpRequest(req: Request, options?: HttpRequestLogOptions): string;
+    /**
+     * Logs an HTTP response
+     * @param res - Express response object
+     * @param req - Express request object
+     * @param options - Additional logging options
+     */
+    httpResponse(res: Response, req: Request, options?: HttpResponseLogOptions): void;
+    /**
+     * Logs an SFTP transaction
+     * @param operation - SFTP operation details
+     * @param options - Additional logging options
+     */
+    sftpTransaction(operation: {
+        host: string;
+        username: string;
+        operation: 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat';
+        path: string;
+        status: 'success' | 'failure';
+        bytesTransferred?: number;
+        filesListed?: number;
+        sourcePath?: string;
+    }, options?: SftpTransactionLogOptions): void;
+    /**
+     * Logs a database query transaction
+     * @param query - Database query details
+     * @param options - Additional logging options
+     */
+    dbQueryTransaction(query: {
+        instance: string;
+        vendor: 'postgres' | 'mysql' | 'mssql' | 'mongodb';
+        query?: string;
+        status: 'success' | 'failure';
+        rowsReturned?: number;
+        rowsAffected?: number;
+    }, options?: DbQueryTransactionLogOptions): void;
+    traceMiddleware: (req: Request, res: Response, next: NextFunction) => void;
+    axiosTraceMiddleware: {
+        onFulfilled: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig;
+        onRejected: (error: any) => any;
+    };
+}

package/dist/unnbound-logger.js

@@ -0,0 +1,292 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnnboundLogger = void 0;
+/**
+ * Core logger implementation
+ */
+const pino_1 = __importDefault(require("pino"));
+const id_generator_1 = require("./utils/id-generator");
+const logger_utils_1 = require("./utils/logger-utils");
+const uuid_1 = require("uuid");
+const trace_context_1 = require("./utils/trace-context");
+const axios_1 = require("axios");
+/**
+ * UnnboundLogger provides typed, structured logging using Pino
+ */
+class UnnboundLogger {
+    /**
+     * Creates a new UnnboundLogger instance
+     * @param options - Configuration options for the logger
+     */
+    constructor(options = {}) {
+        // Trace middleware
+        this.traceMiddleware = (req, res, next) => {
+            // Check if the route should be ignored
+            if (this.shouldIgnorePath(req.path, this.ignoreTraceRoutes)) {
+                return next();
+            }
+            const traceId = req.header(this.traceHeaderKey) || (0, uuid_1.v4)();
+            res.setHeader(this.traceHeaderKey, traceId);
+            trace_context_1.traceContext.run(traceId, () => {
+                next();
+            });
+        };
+        // Axios trace middleware
+        this.axiosTraceMiddleware = {
+            onFulfilled: (config) => {
+                // Check if the URL should be ignored
+                if (config.url && this.shouldIgnorePath(config.url, this.ignoreAxiosTraceRoutes)) {
+                    return config;
+                }
+                const traceId = trace_context_1.traceContext.getTraceId();
+                if (traceId) {
+                    const headers = new axios_1.AxiosHeaders(config.headers);
+                    headers.set(this.traceHeaderKey, traceId);
+                    config.headers = headers;
+                }
+                return config;
+            },
+            onRejected: (error) => {
+                return Promise.reject(error);
+            }
+        };
+        this.defaultLevel = options.defaultLevel || 'info';
+        this.serviceName = options.serviceName;
+        this.environment = options.environment;
+        this.traceHeaderKey = options.traceHeaderKey || 'unnbound-trace-id';
+        this.ignoreTraceRoutes = options.ignoreTraceRoutes || [];
+        this.ignoreAxiosTraceRoutes = options.ignoreAxiosTraceRoutes || [];
+        // Create Pino logger
+        this.logger = (0, pino_1.default)({
+            level: this.defaultLevel,
+            base: {
+                ...(this.serviceName && { service: this.serviceName }),
+                ...(this.environment && { environment: this.environment }),
+            },
+            formatters: {
+                level: (label) => {
+                    return { level: label };
+                },
+            },
+            timestamp: () => `,"timestamp":"${new Date().toISOString()}"`,
+        });
+    }
+    /**
+     * Checks if a path matches any of the ignore patterns
+     * @param path - The path to check
+     * @param patterns - Array of glob patterns to match against
+     * @returns boolean indicating if the path should be ignored
+     */
+    shouldIgnorePath(path, patterns) {
+        return patterns.some(pattern => {
+            // Convert glob pattern to regex
+            const regexPattern = pattern
+                .replace(/\./g, '\\.') // Escape dots
+                .replace(/\*/g, '.*') // Convert * to .*
+                .replace(/\?/g, '.'); // Convert ? to .
+            const regex = new RegExp(`^${regexPattern}$`);
+            return regex.test(path);
+        });
+    }
+    /**
+     * Logs a general message
+     * @param level - Log level
+     * @param message - Log message
+     * @param options - Additional logging options
+     */
+    log(level, message, options = {}) {
+        const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, id_generator_1.generateUuid)();
+        const requestId = options.requestId || (0, id_generator_1.generateUuid)();
+        let logEntry;
+        let error;
+        if (message instanceof Error) {
+            error = {
+                name: message.name,
+                message: message.message,
+                stack: message.stack,
+            };
+            logEntry = {
+                level,
+                type: 'general',
+                message: message.message,
+                traceId,
+                requestId,
+                error,
+            };
+        }
+        else if (typeof message === 'string') {
+            logEntry = {
+                level,
+                type: 'general',
+                message,
+                traceId,
+                requestId,
+            };
+        }
+        else {
+            // If message is an object, stringify it
+            logEntry = {
+                level,
+                type: 'general',
+                message: JSON.stringify(message),
+                traceId,
+                requestId,
+            };
+        }
+        this.logger[level](logEntry);
+    }
+    /**
+     * Logs an error message
+     * @param message - Error message or object
+     * @param options - Additional logging options
+     */
+    error(message, options = {}) {
+        this.log('error', message, options);
+    }
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param options - Additional logging options
+     */
+    warn(message, options = {}) {
+        this.log('warn', message, options);
+    }
+    /**
+     * Logs an info message
+     * @param message - Info message
+     * @param options - Additional logging options
+     */
+    info(message, options = {}) {
+        this.log('info', message, options);
+    }
+    /**
+     * Logs a debug message
+     * @param message - Debug message
+     * @param options - Additional logging options
+     */
+    debug(message, options = {}) {
+        this.log('debug', message, options);
+    }
+    /**
+     * Logs an HTTP request
+     * @param req - Express request object
+     * @param options - Additional logging options
+     * @returns The request ID for correlating with the response
+     */
+    httpRequest(req, options = {}) {
+        const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, id_generator_1.generateUuid)();
+        const requestId = options.requestId || (0, id_generator_1.generateUuid)();
+        const startTime = options.startTime || Date.now();
+        // Store request metadata in res.locals for later use
+        if (req.res) {
+            req.res.locals.requestId = requestId;
+            req.res.locals.startTime = startTime;
+            req.res.locals.traceId = traceId;
+        }
+        const logEntry = {
+            level: options.level || this.defaultLevel,
+            type: 'httpRequest',
+            message: `${req.method} ${req.originalUrl || req.url}`,
+            traceId,
+            requestId,
+            duration: 0, // Will be updated in response
+            httpRequest: {
+                url: req.originalUrl || req.url,
+                method: req.method,
+                headers: (0, logger_utils_1.filterHeaders)(req.headers),
+                ip: req.ip,
+                body: req.body,
+            },
+        };
+        this.logger[options.level || this.defaultLevel](logEntry);
+        return requestId;
+    }
+    /**
+     * Logs an HTTP response
+     * @param res - Express response object
+     * @param req - Express request object
+     * @param options - Additional logging options
+     */
+    httpResponse(res, req, options = {}) {
+        const requestId = res.locals.requestId || options.requestId || (0, id_generator_1.generateUuid)();
+        const startTime = res.locals.startTime || options.startTime || Date.now();
+        const traceId = res.locals.traceId || options.traceId || trace_context_1.traceContext.getTraceId() || (0, id_generator_1.generateUuid)();
+        const duration = options.duration || (Date.now() - startTime);
+        // Determine log level based on status code
+        let level = options.level || this.defaultLevel;
+        if (!options.level) {
+            if (res.statusCode >= 500) {
+                level = 'error';
+            }
+            else if (res.statusCode >= 400) {
+                level = 'warn';
+            }
+            else {
+                level = 'info';
+            }
+        }
+        const logEntry = {
+            level,
+            type: 'httpResponse',
+            message: `${req.method} ${req.originalUrl || req.url} - ${res.statusCode}`,
+            traceId,
+            requestId,
+            duration,
+            httpResponse: {
+                url: req.originalUrl || req.url,
+                method: req.method,
+                headers: (0, logger_utils_1.filterHeaders)(res.getHeaders()),
+                ip: req.ip,
+                status: res.statusCode,
+                body: res.locals.body,
+            },
+        };
+        this.logger[level](logEntry);
+    }
+    /**
+     * Logs an SFTP transaction
+     * @param operation - SFTP operation details
+     * @param options - Additional logging options
+     */
+    sftpTransaction(operation, options = {}) {
+        const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, id_generator_1.generateUuid)();
+        const requestId = options.requestId || (0, id_generator_1.generateUuid)();
+        const duration = options.duration || (options.startTime ? Date.now() - options.startTime : 0);
+        const level = operation.status === 'success' ? 'info' : 'error';
+        const logEntry = {
+            level,
+            type: 'sftpTransaction',
+            message: `SFTP ${operation.operation} ${operation.status} - ${operation.path}`,
+            traceId,
+            requestId,
+            duration,
+            sftp: operation,
+        };
+        this.logger[level](logEntry);
+    }
+    /**
+     * Logs a database query transaction
+     * @param query - Database query details
+     * @param options - Additional logging options
+     */
+    dbQueryTransaction(query, options = {}) {
+        const traceId = options.traceId || trace_context_1.traceContext.getTraceId() || (0, id_generator_1.generateUuid)();
+        const requestId = options.requestId || (0, id_generator_1.generateUuid)();
+        const duration = options.duration || (options.startTime ? Date.now() - options.startTime : 0);
+        const level = query.status === 'success' ? 'info' : 'error';
+        const logEntry = {
+            level,
+            type: 'dbQueryTransaction',
+            message: `DB Query ${query.status} - ${query.vendor}`,
+            traceId,
+            requestId,
+            duration,
+            db: query,
+        };
+        this.logger[level](logEntry);
+    }
+}
+exports.UnnboundLogger = UnnboundLogger;

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generates a new UUID v4
+ * @returns A UUID v4 string
+ */
+export declare function generateUuid(): string;
+/**
+ * Generates the current timestamp in ISO format
+ * @returns ISO timestamp string
+ */
+export declare function generateTimestamp(): string;
+/**
+ * Gets or creates a trace ID for a workflow
+ * @param workflowId - The workflow ID to get a trace ID for
+ * @returns A trace ID associated with the workflow
+ */
+export declare function getTraceId(workflowId: string): string;
+/**
+ * Clears a trace ID from the map
+ * @param workflowId - The workflow ID to clear
+ */
+export declare function clearTraceId(workflowId: string): void;

package/dist/utils/id-generator.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateUuid = generateUuid;
+exports.generateTimestamp = generateTimestamp;
+exports.getTraceId = getTraceId;
+exports.clearTraceId = clearTraceId;
+/**
+ * Utilities for generating unique identifiers
+ */
+const uuid_1 = require("uuid");
+/**
+ * Generates a new UUID v4
+ * @returns A UUID v4 string
+ */
+function generateUuid() {
+    return (0, uuid_1.v4)();
+}
+/**
+ * Generates the current timestamp in ISO format
+ * @returns ISO timestamp string
+ */
+function generateTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Stores trace IDs by workflow ID for consistent tracking
+ */
+const traceIdMap = new Map();
+/**
+ * Gets or creates a trace ID for a workflow
+ * @param workflowId - The workflow ID to get a trace ID for
+ * @returns A trace ID associated with the workflow
+ */
+function getTraceId(workflowId) {
+    if (!traceIdMap.has(workflowId)) {
+        traceIdMap.set(workflowId, generateUuid());
+    }
+    return traceIdMap.get(workflowId);
+}
+/**
+ * Clears a trace ID from the map
+ * @param workflowId - The workflow ID to clear
+ */
+function clearTraceId(workflowId) {
+    traceIdMap.delete(workflowId);
+}

package/dist/utils/logger-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Utility functions for logging
+ */
+/**
+ * Filters an object of headers, returning a new object with only the allowed headers.
+ * @param headers The original headers object.
+ * @returns A new object containing only the headers from the allow-list.
+ */
+export declare function filterHeaders(headers: Record<string, any>): Record<string, string>;
+/**
+ * Safely parses JSON strings, returning the original data if parsing fails or if it's not a string.
+ * @param data The data to potentially parse as JSON.
+ * @returns Parsed JSON object or the original data.
+ */
+export declare function safeJsonParse(data: any): any;
+/**
+ * Normalizes IP addresses by removing IPv6 mapping prefix for IPv4 addresses.
+ * @param ip The IP address to normalize.
+ * @returns Normalized IP address string.
+ */
+export declare function normalizeIp(ip: string | undefined): string | undefined;

package/dist/utils/logger-utils.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Utility functions for logging
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterHeaders = filterHeaders;
+exports.safeJsonParse = safeJsonParse;
+exports.normalizeIp = normalizeIp;
+// --- Header Allow-Listing ---
+const ALLOWED_HEADERS = new Set([
+    'content-type',
+    'accept',
+    'user-agent',
+    'host',
+    'x-forwarded-for',
+    'x-request-id',
+    'content-length',
+    'cache-control',
+]);
+/**
+ * Filters an object of headers, returning a new object with only the allowed headers.
+ * @param headers The original headers object.
+ * @returns A new object containing only the headers from the allow-list.
+ */
+function filterHeaders(headers) {
+    const filtered = {};
+    for (const key in headers) {
+        if (ALLOWED_HEADERS.has(key.toLowerCase())) {
+            filtered[key] = String(headers[key]);
+        }
+    }
+    return filtered;
+}
+/**
+ * Safely parses JSON strings, returning the original data if parsing fails or if it's not a string.
+ * @param data The data to potentially parse as JSON.
+ * @returns Parsed JSON object or the original data.
+ */
+function safeJsonParse(data) {
+    if (typeof data === 'string') {
+        try {
+            return JSON.parse(data);
+        }
+        catch {
+            return data;
+        }
+    }
+    return data;
+}
+/**
+ * Normalizes IP addresses by removing IPv6 mapping prefix for IPv4 addresses.
+ * @param ip The IP address to normalize.
+ * @returns Normalized IP address string.
+ */
+function normalizeIp(ip) {
+    if (!ip)
+        return ip;
+    // Remove IPv4-mapped IPv6 prefix (::ffff:) to get clean IPv4 address
+    if (ip.startsWith('::ffff:')) {
+        return ip.substring(7);
+    }
+    return ip;
+}