unnbound-logger-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unnbound Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,312 @@
+# Unnbound Logger
+
+A structured logging library with TypeScript support built on Pino. Provides consistent, well-typed logging across different operational contexts. All logs are output in JSON format for better machine readability and parsing.
+
+## Installation
+
+```bash
+npm install unnbound-logger
+```
+
+## Basic Usage
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+
+// Create a new logger instance
+const logger = new UnnboundLogger();
+
+// Log with string messages
+logger.info('Application started');
+logger.warn('Resource usage high');
+logger.error(new Error('Database connection failed'));
+logger.debug('Debug information');
+
+// Log with object messages
+logger.info({
+  event: 'user_login',
+  userId: '123',
+  timestamp: new Date().toISOString()
+});
+
+// Log with both string message and metadata
+logger.info('User logged in', {
+  userId: '123',
+  timestamp: new Date().toISOString()
+});
+
+// Log with object message and additional metadata
+logger.info(
+  { event: 'user_login', userId: '123' },
+  { timestamp: new Date().toISOString() }
+);
+```
+
+## Log Format
+
+All logs follow a standardized format:
+
+```typescript
+interface Log<T extends LogType = 'general'> {
+  level: LogLevel; // "info" | "debug" | "error" | "warn"
+  type: T; // "general" | "httpRequest" | "httpResponse" | "sftpTransaction" | "dbQueryTransaction"
+  message: string;
+  traceId: string;
+  requestId: string;
+  error?: SerializableError; // Only present for Error objects
+}
+
+interface LogTransaction<T extends LogType> extends Log<T> {
+  duration: number; // Duration in milliseconds
+}
+```
+
+## HTTP Request/Response Logging
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+import express from 'express';
+
+const app = express();
+const logger = new UnnboundLogger();
+
+// Middleware to log requests
+app.use((req, res, next) => {
+  // Log the request and get the request ID
+  const requestId = logger.httpRequest(req, {
+    startTime: Date.now()
+  });
+
+  // Store the request ID in res.locals for later use
+  res.locals.requestId = requestId;
+
+  // Add response listener to log the response
+  res.on('finish', () => {
+    logger.httpResponse(res, req, {
+      requestId,
+      startTime: res.locals.startTime
+    });
+  });
+
+  next();
+});
+
+// Example route
+app.post('/api/users', (req, res) => {
+  // Your route handler code here
+  res.status(201).json({ id: '123', status: 'created' });
+});
+```
+
+The logger automatically captures:
+- Request method, URL, body, and headers (filtered for security)
+- Response status code, body, and headers (filtered for security)
+- Request duration
+- Trace ID and request ID for correlation
+
+## SFTP Transaction Logging
+
+For logging SFTP operations:
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+
+const logger = new UnnboundLogger();
+
+// Log an SFTP upload
+logger.sftpTransaction({
+  host: 'sftp.example.com',
+  username: 'ftpuser',
+  operation: 'upload',
+  path: '/uploads/file.txt',
+  status: 'success',
+  bytesTransferred: 1024
+});
+
+// Log an SFTP download with failure
+logger.sftpTransaction({
+  host: 'sftp.example.com',
+  username: 'ftpuser',
+  operation: 'download',
+  path: '/downloads/file.txt',
+  status: 'failure'
+}, {
+  startTime: Date.now() - 5000 // Started 5 seconds ago
+});
+```
+
+## Database Query Transaction Logging
+
+For logging database operations:
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+
+const logger = new UnnboundLogger();
+
+// Log a successful database query
+logger.dbQueryTransaction({
+  instance: 'localhost:5432',
+  vendor: 'postgres',
+  query: 'SELECT * FROM users WHERE active = true',
+  status: 'success',
+  rowsReturned: 150
+});
+
+// Log a failed database operation
+logger.dbQueryTransaction({
+  instance: 'prod-db-cluster',
+  vendor: 'mysql',
+  query: 'UPDATE users SET last_login = NOW()',
+  status: 'failure',
+  rowsAffected: 0
+}, {
+  duration: 2500 // Operation took 2.5 seconds
+});
+```
+
+## Middleware Usage
+
+### Express Trace Middleware
+
+The library provides a trace middleware for Express applications that automatically logs HTTP requests and maintains trace context:
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+import express from 'express';
+
+const app = express();
+const logger = new UnnboundLogger();
+
+// Apply the trace middleware globally
+app.use(logger.traceMiddleware);
+
+```
+
+The trace middleware automatically:
+- Logs incoming requests with method, URL, headers, and body
+- Generates and maintains trace IDs across the request lifecycle
+- Measures request duration
+- Handles errors and logs them appropriately
+
+### Axios Trace Middleware
+
+For logging outgoing HTTP requests made with Axios:
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+import axios from 'axios';
+
+const logger = new UnnboundLogger();
+
+// Add Axios trace middleware
+axios.interceptors.request.use(
+  logger.axiosTraceMiddleware.onFulfilled,
+  logger.axiosTraceMiddleware.onRejected
+);
+
+// All requests made with axios will be automatically logged
+axios.get('https://api.example.com/data');
+```
+
+The Axios trace middleware:
+- Logs outgoing requests with method, URL, headers, and body
+- Maintains trace context across requests
+- Handles errors and logs them appropriately
+- Supports request/response filtering through configuration
+
+## Function Tracing with withTrace
+
+The `withTrace` higher-order function allows you to wrap any function with automatic trace context. This is particularly useful for maintaining consistent trace IDs across async operations and distributed systems:
+
+```typescript
+import { UnnboundLogger } from 'unnbound-logger';
+import { withTrace } from 'unnbound-logger/utils/with-trace';
+import { traceContext } from 'unnbound-logger/utils/trace-context';
+
+const logger = new UnnboundLogger();
+
+// Example: Wrapping a function with trace context
+const operation = (value: number) => {
+  const traceId = traceContext.getTraceId();
+  logger.info('Processing value', { value, traceId });
+  return value * 2;
+};
+
+// Wrap the function with trace context
+const tracedOperation = withTrace(operation);
+
+// Execute the function
+const result = tracedOperation(21); // Returns 42
+```
+
+### Using Custom Trace IDs
+
+You can provide your own trace ID when wrapping a function:
+
+```typescript
+const customTraceId = 'custom-trace-123';
+const tracedOperation = withTrace(operation, customTraceId);
+```
+
+### Async Operations
+
+The trace context is maintained across async operations:
+
+```typescript
+const asyncOperation = async (value: number) => {
+  const traceId1 = traceContext.getTraceId();
+  logger.info('First step', { traceId: traceId1 });
+
+  await someAsyncWork();
+
+  const traceId2 = traceContext.getTraceId();
+  logger.info('Second step', { traceId: traceId2 });
+  // traceId1 and traceId2 will be the same
+};
+
+const tracedOperation = withTrace(asyncOperation);
+await tracedOperation(42);
+```
+
+### Benefits
+
+- Automatic trace ID generation
+- Consistent trace context across async operations
+- Support for custom trace IDs
+- Type-safe implementation
+- Works with both sync and async functions
+- Maintains separate trace contexts for different operations
+
+> **Note:** When using `UnnboundLogger`, you don't need to manually call `traceContext.getTraceId()` in your logging calls. The logger automatically includes the current trace ID in all log entries. The example above shows manual trace ID retrieval for demonstration purposes, but in practice, you can simply use the logger methods directly:
+>
+> ```typescript
+> const operation = (value: number) => {
+>   logger.info('Processing value', { value }); // Trace ID is automatically included
+>   return value * 2;
+> };
+> ```
+
+## API Reference
+
+### UnnboundLogger
+
+The main logger class that provides all logging functionality using Pino.
+
+#### Constructor
+
+```typescript
+new UnnboundLogger(options?: LoggerOptions)
+```
+
+#### Methods
+
+- `log(level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
+- `error(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
+- `warn(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
+- `info(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
+- `debug(message: string | Error | Record<string, unknown>, options?: GeneralLogOptions): void`
+- `httpRequest(req: Request, options?: HttpRequestLogOptions): string`
+- `httpResponse(res: Response, req: Request, options: HttpResponseLogOptions): void`
+- `sftpTransaction(operation: SftpOperation, options?: SftpTransactionLogOptions): void`
+- `dbQueryTransaction(query: DbQuery, options?: DbQueryTransactionLogOptions): void`

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+import { UnnboundLogger } from './unnbound-logger';
+import { LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError } from './types';
+import { generateUuid, clearTraceId } from './utils/id-generator';
+export { UnnboundLogger, LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError, generateUuid, clearTraceId, };
+declare const defaultLogger: UnnboundLogger;
+export { defaultLogger };
+export declare const log: (level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const error: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const warn: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const info: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const debug: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const httpRequest: (req: import("express").Request, options?: HttpRequestLogOptions) => string;
+export declare const httpResponse: (res: import("express").Response, req: import("express").Request, options?: HttpResponseLogOptions) => void;
+export declare const 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;
+export declare const dbQueryTransaction: (query: {
+    instance: string;
+    vendor: "postgres" | "mysql" | "mssql" | "mongodb";
+    query?: string;
+    status: "success" | "failure";
+    rowsReturned?: number;
+    rowsAffected?: number;
+}, options?: DbQueryTransactionLogOptions) => void;
+export default UnnboundLogger;

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbQueryTransaction = exports.sftpTransaction = exports.httpResponse = exports.httpRequest = exports.debug = exports.info = exports.warn = exports.error = exports.log = exports.defaultLogger = exports.clearTraceId = exports.generateUuid = exports.UnnboundLogger = void 0;
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+const unnbound_logger_1 = require("./unnbound-logger");
+Object.defineProperty(exports, "UnnboundLogger", { enumerable: true, get: function () { return unnbound_logger_1.UnnboundLogger; } });
+const id_generator_1 = require("./utils/id-generator");
+Object.defineProperty(exports, "generateUuid", { enumerable: true, get: function () { return id_generator_1.generateUuid; } });
+Object.defineProperty(exports, "clearTraceId", { enumerable: true, get: function () { return id_generator_1.clearTraceId; } });
+// Create a default logger instance
+const defaultLogger = new unnbound_logger_1.UnnboundLogger();
+exports.defaultLogger = defaultLogger;
+// Export default logger functions for convenience
+exports.log = defaultLogger.log.bind(defaultLogger);
+exports.error = defaultLogger.error.bind(defaultLogger);
+exports.warn = defaultLogger.warn.bind(defaultLogger);
+exports.info = defaultLogger.info.bind(defaultLogger);
+exports.debug = defaultLogger.debug.bind(defaultLogger);
+exports.httpRequest = defaultLogger.httpRequest.bind(defaultLogger);
+exports.httpResponse = defaultLogger.httpResponse.bind(defaultLogger);
+exports.sftpTransaction = defaultLogger.sftpTransaction.bind(defaultLogger);
+exports.dbQueryTransaction = defaultLogger.dbQueryTransaction.bind(defaultLogger);
+// Default export is the UnnboundLogger class
+exports.default = unnbound_logger_1.UnnboundLogger;

package/dist/src/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+import { UnnboundLogger } from './unnbound-logger';
+import { LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError } from './types';
+import { generateUuid, clearTraceId } from './utils/id-generator';
+export { UnnboundLogger, LogLevel, LogType, HttpMethod, LoggerOptions, GeneralLogOptions, HttpRequestLogOptions, HttpResponseLogOptions, SftpTransactionLogOptions, DbQueryTransactionLogOptions, Log, LogTransaction, HttpRequestLog, HttpResponseLog, SftpTransactionLog, DbQueryTransactionLog, SerializableError, generateUuid, clearTraceId, };
+declare const defaultLogger: UnnboundLogger;
+export { defaultLogger };
+export declare const log: (level: LogLevel, message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const error: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const warn: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const info: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const debug: (message: string | Error | Record<string, unknown>, options?: GeneralLogOptions) => void;
+export declare const httpRequest: (req: import("express").Request, options?: HttpRequestLogOptions) => string;
+export declare const httpResponse: (res: import("express").Response, req: import("express").Request, options?: HttpResponseLogOptions) => void;
+export declare const 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;
+export declare const dbQueryTransaction: (query: {
+    instance: string;
+    vendor: "postgres" | "mysql" | "mssql" | "mongodb";
+    query?: string;
+    status: "success" | "failure";
+    rowsReturned?: number;
+    rowsAffected?: number;
+}, options?: DbQueryTransactionLogOptions) => void;
+export default UnnboundLogger;

package/dist/src/index.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dbQueryTransaction = exports.sftpTransaction = exports.httpResponse = exports.httpRequest = exports.debug = exports.info = exports.warn = exports.error = exports.log = exports.defaultLogger = exports.clearTraceId = exports.generateUuid = exports.UnnboundLogger = void 0;
+/**
+ * unnbound-logger
+ *
+ * A structured logging library built on Pino with TypeScript support.
+ * Provides consistent, well-typed logging across different operational contexts.
+ */
+const unnbound_logger_1 = require("./unnbound-logger");
+Object.defineProperty(exports, "UnnboundLogger", { enumerable: true, get: function () { return unnbound_logger_1.UnnboundLogger; } });
+const id_generator_1 = require("./utils/id-generator");
+Object.defineProperty(exports, "generateUuid", { enumerable: true, get: function () { return id_generator_1.generateUuid; } });
+Object.defineProperty(exports, "clearTraceId", { enumerable: true, get: function () { return id_generator_1.clearTraceId; } });
+// Create a default logger instance
+const defaultLogger = new unnbound_logger_1.UnnboundLogger();
+exports.defaultLogger = defaultLogger;
+// Export default logger functions for convenience
+exports.log = defaultLogger.log.bind(defaultLogger);
+exports.error = defaultLogger.error.bind(defaultLogger);
+exports.warn = defaultLogger.warn.bind(defaultLogger);
+exports.info = defaultLogger.info.bind(defaultLogger);
+exports.debug = defaultLogger.debug.bind(defaultLogger);
+exports.httpRequest = defaultLogger.httpRequest.bind(defaultLogger);
+exports.httpResponse = defaultLogger.httpResponse.bind(defaultLogger);
+exports.sftpTransaction = defaultLogger.sftpTransaction.bind(defaultLogger);
+exports.dbQueryTransaction = defaultLogger.dbQueryTransaction.bind(defaultLogger);
+// Default export is the UnnboundLogger class
+exports.default = unnbound_logger_1.UnnboundLogger;

package/dist/src/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/src/types.js

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