unnbound-logger-sdk 3.0.10 → 3.0.12

package/README.md

@@ -5,19 +5,20 @@ A structured logging library with TypeScript support built on Pino. Provides con
 ## Installation
 
 ```bash
-npm install unnbound-logger
+npm install unnbound-logger-sdk
 ```
 
 ## Basic Usage
 
 ```typescript
-import { logger } from 'unnbound-logger';
+import { logger } from 'unnbound-logger-sdk';
 
 // Log with string messages
 logger.info('Application started');
 logger.warn('Resource usage high');
 logger.error({ err: new Error('Database connection failed') }, 'Something bad happened');
 logger.debug('Debug information');
+logger.trace('Trace information');
 
 // Log with object messages (merged into top level)
 logger.info({ event: 'user_login', userId: '123' }, 'Event received.');
@@ -34,17 +35,20 @@ All logs follow a standardized format based on Pino with additional context:
 
 ```typescript
 interface Log<T extends LogType = 'general'> {
-  level: LogLevel; // "info" | "debug" | "error" | "warn"
+  logId: string; // Automatically generated unique ID for each log entry
+  level: LogLevel; // "info" | "debug" | "error" | "warn" | "trace"
   message: string;
+  type: T; // "general" | "http" | "sftp"
   traceId?: string; // Automatically included when in trace context
   spanId?: string; // Automatically included when in span context
-  type?: T; // "general" | "http" | "sftp" | "dbQueryTransaction"
   serviceId?: string; // From UNNBOUND_SERVICE_ID environment variable
   deploymentId?: string; // From UNNBOUND_DEPLOYMENT_ID environment variable
   workflowId?: string; // From UNNBOUND_WORKFLOW_ID environment variable
   environment?: string; // From ENVIRONMENT environment variable
   err?: unknown; // Only present for Error objects
   duration?: number; // Duration in milliseconds for span operations
+  http?: T extends 'http' ? HttpPayload : never;
+  sftp?: T extends 'sftp' ? SftpPayload : never;
 }
 ```
 
@@ -68,7 +72,7 @@ UNNBOUND_SERVICE_ID=order-service
 
 ```typescript
 // Import the logger - workflowId and serviceId are automatically set from environment
-import { logger } from 'unnbound-logger';
+import { logger } from 'unnbound-logger-sdk';
 ```
 
 ### Deployment Tracking
@@ -128,7 +132,7 @@ This follows Pino's standard behavior where all object properties are merged int
 ## HTTP Request/Response Logging
 
 ```typescript
-import { logger, traceMiddleware } from 'unnbound-logger';
+import { logger, traceMiddleware } from 'unnbound-logger-sdk';
 import express from 'express';
 
 const app = express();
@@ -169,7 +173,7 @@ export UNNBOUND_WORKFLOW_URL="https://api.yourservice.com"
 
 ```typescript
 import express from 'express';
-import { traceMiddleware } from 'unnbound-logger';
+import { traceMiddleware } from 'unnbound-logger-sdk';
 
 const app = express();
 
@@ -190,6 +194,45 @@ app.post('/webhooks/github', (req, res) => {
 
 This ensures webhook logs contain the complete URL for easy debugging and monitoring.
 
+## SFTP Operations Logging
+
+The logger supports structured logging for SFTP operations with automatic span tracking:
+
+```typescript
+import { logger, startSpan } from 'unnbound-logger-sdk';
+
+// Example SFTP operation with automatic logging
+const uploadFile = async (filePath: string, content: string) => {
+  return await startSpan(
+    'SFTP upload operation',
+    async () => {
+      // Your SFTP upload logic here
+      logger.info('Uploading file', { filePath, contentLength: content.length });
+      return { success: true, filePath };
+    },
+    (result) => ({
+      type: 'sftp',
+      sftp: {
+        host: 'sftp.example.com',
+        operation: 'upload',
+        path: filePath,
+        content: content,
+        bytes: content.length,
+      },
+    })
+  );
+};
+```
+
+The SFTP logging automatically captures:
+
+- Host information
+- Operation type (connect, upload, download, list, delete, etc.)
+- File paths and content
+- Byte counts for transfers
+- Operation duration
+- Success/failure status
+
 ## Middleware Usage
 
 ### Express Trace Middleware
@@ -197,7 +240,7 @@ This ensures webhook logs contain the complete URL for easy debugging and monito
 The library provides a comprehensive trace middleware for Express applications that automatically handles trace context and HTTP logging:
 
 ```typescript
-import { traceMiddleware } from 'unnbound-logger';
+import { traceMiddleware } from 'unnbound-logger-sdk';
 import express from 'express';
 
 const app = express();
@@ -221,7 +264,7 @@ The trace middleware automatically:
 For comprehensive logging of outgoing HTTP requests made with Axios:
 
 ```typescript
-import { traceAxios } from 'unnbound-logger';
+import { traceAxios } from 'unnbound-logger-sdk';
 import axios from 'axios';
 
 // Create an axios instance and wrap it with tracing
@@ -245,7 +288,7 @@ The Axios middleware:
 In case the function doesn't run inside an HTTP handler (for example a cron job), you can assign a trace id manually by using the `withTrace` function:
 
 ```typescript
-import { withTrace } from 'unnbound-logger';
+import { withTrace } from 'unnbound-logger-sdk';
 
 const operation = async (value: number) => {
   // This will log a { traceId, value }
@@ -261,7 +304,7 @@ setInterval(() => withTrace(() => operation(13)), 1000);
 The `startSpan` function allows you to wrap any async operation with automatic span tracking and logging. This is particularly useful for maintaining consistent trace IDs across async operations and distributed systems:
 
 ```typescript
-import { logger, startSpan } from 'unnbound-logger';
+import { logger, startSpan } from 'unnbound-logger-sdk';
 
 // Example: Wrapping a function with span tracking
 const operation = async (value: number) => {
@@ -320,17 +363,22 @@ The main logger instance that provides all logging functionality using Pino.
 #### Usage
 
 ```typescript
-import { logger } from 'unnbound-logger';
+import { logger } from 'unnbound-logger-sdk';
 ```
 
 The logger is a Pino instance with additional context automatically included from environment variables and trace context.
 
 #### Methods
 
+- `logger.trace(object: {}, message: string): void`
+- `logger.trace(message: string): void`
+- `logger.debug(object: {}, message: string): void`
+- `logger.debug(message: string): void`
 - `logger.info(object: {}, message: string): void`
+- `logger.info(message: string): void`
 - `logger.warn(object: {}, message: string): void`
-- `logger.error(object: {}, message: string): void`
-- `logger.debug(object: {}, message: string): void`
+- `logger.warn(message: string): void`
+- `logger.error<O extends { err: unknown }>(object: O, message: string): void`
 
 ### traceMiddleware
 
@@ -339,7 +387,7 @@ Express middleware for automatic HTTP request/response logging and trace context
 #### Usage
 
 ```typescript
-import { traceMiddleware } from 'unnbound-logger';
+import { traceMiddleware } from 'unnbound-logger-sdk';
 
 app.use(traceMiddleware(options?: HttpOptions));
 ```
@@ -356,7 +404,7 @@ Wraps an Axios instance with automatic request/response logging and trace contex
 #### Usage
 
 ```typescript
-import { traceAxios } from 'unnbound-logger';
+import { traceAxios } from 'unnbound-logger-sdk';
 import axios from 'axios';
 
 const client = traceAxios(axios.create(), options?: HttpOptions);
@@ -369,7 +417,7 @@ Creates a span for tracking async operations with automatic logging and duration
 #### Usage
 
 ```typescript
-import { startSpan } from 'unnbound-logger';
+import { startSpan } from 'unnbound-logger-sdk';
 
 const result = await startSpan<T>(
   spanName: string,
@@ -384,6 +432,19 @@ const result = await startSpan<T>(
 - `callback`: The async function to execute within the span
 - `getter`: Optional function to generate log payload based on operation result/error
 
+### getTraceId
+
+Generates a new trace ID for manual trace context management.
+
+#### Usage
+
+```typescript
+import { getTraceId } from 'unnbound-logger-sdk';
+
+const traceId = getTraceId();
+console.log(traceId); // "550e8400-e29b-41d4-a716-446655440000"
+```
+
 ### Environment Variables
 
 - `UNNBOUND_WORKFLOW_ID` - Workflow identifier (included in all logs)

package/dist/axios.d.ts

@@ -1,4 +1,4 @@
-import { Axios, type AxiosRequestConfig, type AxiosResponse } from 'axios';
+import { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios';
 import { HttpOptions } from './types';
 type GetPayload = (config: AxiosRequestConfig, res?: AxiosResponse) => object;
 /**
@@ -7,5 +7,5 @@ type GetPayload = (config: AxiosRequestConfig, res?: AxiosResponse) => object;
  * @param options - Configuration options for HTTP tracing
  * @returns The wrapped axios instance with span tracking
  */
-export declare const traceAxios: (client: Axios, { ignoreTraceRoutes, traceHeaderKey, getPayload, }?: HttpOptions<GetPayload>) => Axios;
+export declare const traceAxios: (client: AxiosInstance, { ignoreTraceRoutes, traceHeaderKey, getPayload, }?: HttpOptions<GetPayload>) => AxiosInstance;
 export {};

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * A structured logging library built on Pino with TypeScript support.
  * Provides consistent, well-typed logging across different operational contexts.
  */
-export type { LogLevel, LogType, HttpMethod, Log, HttpPayload, SftpPayload } from './types';
+export type { LogLevel, LogType, HttpMethod, Log, HttpPayload, SftpPayload, EdiPayload, EdiOperation, EdiFormat, EdiX12Payload, EdiX12Operation, } from './types';
 export type { UnnboundLogger } from './logger';
 export { logger } from './logger';
 export { withTrace, getTraceId } from './trace';

package/dist/internal.d.ts

@@ -1,3 +1 @@
-export declare const internal: () => {
-    _internal: boolean;
-};
+export declare const internal: () => Record<string, unknown>;

package/dist/internal.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.internal = void 0;
-const internal = () => ({ _internal: true });
+const o = { _internal: true };
+// Internal logs should be hidden in sandbox
+// TODO: Find a better way to detect sandbox
+if (process.env.UNNBOUND_IDLE_TIMEOUT)
+    o._hide = true;
+const internal = () => o;
 exports.internal = internal;

package/dist/logger.js

@@ -7,8 +7,10 @@ exports.logger = void 0;
 const pino_1 = __importDefault(require("pino"));
 const uuid_1 = require("uuid");
 const storage_1 = require("./storage");
+const levels = new Set(['debug', 'info', 'warn', 'error']);
+const hidden = (data) => '_hide' in data && data._hide;
 exports.logger = (0, pino_1.default)({
-    level: process.env.LOG_LEVEL ?? 'info',
+    level: process.env.LOG_LEVEL ?? 'debug',
     base: {
         environment: process.env.ENVIRONMENT,
         workflowId: process.env.UNNBOUND_WORKFLOW_ID,
@@ -28,6 +30,23 @@ exports.logger = (0, pino_1.default)({
     formatters: {
         level: (level) => ({ level }),
     },
+    hooks: {
+        logMethod(args, method) {
+            const firstArg = args[0];
+            if (!!firstArg && typeof firstArg === 'object') {
+                if (hidden(firstArg))
+                    return;
+                // Allow dynamic log level
+                if ('level' in firstArg &&
+                    typeof firstArg.level === 'string' &&
+                    levels.has(firstArg.level)) {
+                    method = this[firstArg.level];
+                    firstArg.level = undefined;
+                }
+            }
+            method.apply(this, args);
+        },
+    },
     redact: {
         paths: [
             'http.request.headers.authorization',

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export interface Log<T extends LogType = 'general'> {
     workflowId?: string;
     http: T extends 'http' ? HttpPayload : never;
     sftp: T extends 'sftp' ? SftpPayload : never;
+    edi: T extends 'edi' ? EdiPayload : never;
     duration?: number;
     err?: unknown;
 }
@@ -53,6 +54,18 @@ export interface SftpPayload {
     content?: string;
     exists?: string | false;
 }
+export type EdiX12Operation = 'fromX12' | 'toX12' | 'validateX12' | 'acknowledgeX12';
+export type EdiOperation = EdiX12Operation;
+export type EdiFormat = 'x12';
+export interface EdiX12Payload {
+    input: unknown;
+    output: unknown;
+}
+export interface EdiPayload {
+    operation: EdiOperation;
+    type: EdiFormat;
+    x12?: EdiX12Payload;
+}
 export interface HttpOptions<G extends Function> {
     ignoreTraceRoutes?: string[];
     traceHeaderKey?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-logger-sdk",
   "description": "A structured logging library with TypeScript support using Pino. Provides consistent, well-typed logging with automatic logId, workflowId, traceId, and deploymentId tracking across operational contexts.",
-  "version": "3.0.10",
+  "version": "3.0.12",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "keywords": [