unnbound-logger-sdk 3.0.0 → 3.0.2

package/dist/axios.d.ts

@@ -0,0 +1,9 @@
+import { Axios } from 'axios';
+import { HttpOptions } from './types';
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+export declare const traceAxios: (client: Axios, { ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => Axios;

package/dist/axios.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceAxios = void 0;
+const axios_1 = require("axios");
+const types_1 = require("./types");
+const storage_1 = require("./storage");
+const utils_1 = require("./utils");
+const span_1 = require("./span");
+const buildOutgoingHttpPayload = (config, res) => ({
+    type: 'http',
+    http: {
+        url: [config.baseURL, config.url].filter(Boolean).join(''),
+        method: config.method?.toUpperCase() || 'GET',
+        incoming: false,
+        request: {
+            headers: config.headers,
+            body: (0, utils_1.safeJsonParse)(config.data),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.status,
+                body: (0, utils_1.safeJsonParse)(res.data),
+            }
+            : undefined,
+    },
+});
+/**
+ * Wraps an axios instance to add tracing and span tracking
+ * @param axios - The axios instance to wrap
+ * @param options - Configuration options for HTTP tracing
+ * @returns The wrapped axios instance with span tracking
+ */
+const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => {
+    const createSpanWrappedRequest = (originalMethod, method) => {
+        const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
+        const headers = { ...defaultHeaders.common, ...(method && defaultHeaders[method]) };
+        const defaultConfig = { ...partialDefaultConfig, headers };
+        return async (config) => {
+            config = (0, axios_1.mergeConfig)(defaultConfig, config);
+            // Determine the actual config and URL
+            const url = [config.baseURL, config.url].filter(Boolean).join('');
+            // Check if this request should be ignored
+            if ((0, utils_1.shouldIgnorePath)(url, ignoreTraceRoutes))
+                return originalMethod(config);
+            const traceId = storage_1.storage.getStore()?.[storage_1.ContextAttribute.TraceId];
+            config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
+            // Execute the request within a span
+            return (0, span_1.startSpan)(`Outgoing HTTP request`, () => originalMethod(config), (options) => {
+                if (!options)
+                    return buildOutgoingHttpPayload(config);
+                if (options.error)
+                    return buildOutgoingHttpPayload(config, (0, axios_1.isAxiosError)(options.error) ? options.error.response : undefined);
+                return buildOutgoingHttpPayload(config, options.result);
+            });
+        };
+    };
+    const request = client.request.bind(client);
+    const tracedRequest = createSpanWrappedRequest(request);
+    client.request = tracedRequest;
+    ['post', 'put', 'patch'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, data, config) => func({ ...config, url, data });
+    });
+    ['delete', 'get', 'head', 'options'].forEach((method) => {
+        const func = createSpanWrappedRequest(request, method);
+        client[method] = (url, config) => func({ ...config, url });
+    });
+    return client;
+};
+exports.traceAxios = traceAxios;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * unnbound-logger
+ *
+ * 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, LogTransaction, SftpLog, HttpLog, SftpPayload, } from './types';
+export type { UnnboundLogger } from './logger';
+export { logger } from './logger';
+export { startSpan } from './span';
+export { traceAxios } from './axios';
+export { traceMiddleware } from './middleware';

package/dist/logger.d.ts

@@ -0,0 +1,15 @@
+import pino from 'pino';
+export interface UnnboundLogger extends Omit<pino.Logger, 'trace' | 'debug' | 'error' | 'info' | 'warn'> {
+    trace(object: {}, message: string): void;
+    trace(message: string): void;
+    debug(object: {}, message: string): void;
+    debug(message: string): void;
+    info(object: {}, message: string): void;
+    info(message: string): void;
+    warn(object: {}, message: string): void;
+    warn(message: string): void;
+    error<O extends {
+        err: unknown;
+    }>(object: O, message: string): void;
+}
+export declare const logger: UnnboundLogger;

package/dist/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const pino_1 = __importDefault(require("pino"));
+const storage_1 = require("./storage");
+exports.logger = (0, pino_1.default)({
+    level: process.env.LOG_LEVEL ?? 'info',
+    base: {
+        environment: process.env.ENVIRONMENT,
+        workflowId: process.env.UNNBOUND_WORKFLOW_ID,
+        workflowUrl: process.env.UNNBOUND_WORKFLOW_URL,
+        serviceId: process.env.UNNBOUND_SERVICE_ID,
+        deploymentId: process.env.UNNBOUND_DEPLOYMENT_ID,
+    },
+    mixin: () => ({ ...storage_1.storage.getStore() }),
+    serializers: {
+        req: pino_1.default.stdSerializers.req,
+        res: pino_1.default.stdSerializers.res,
+        err: pino_1.default.stdSerializers.err,
+    },
+    // Let CloudWatch handle timestamps
+    timestamp: false,
+    // Change message field from 'msg' to 'message'
+    messageKey: 'message',
+    formatters: {
+        level: (level) => ({ level }),
+    },
+    redact: {
+        paths: [
+            'http.request.headers.authorization',
+            'http.response.headers.authorization',
+            'http.request.headers.Authorization',
+            'http.response.headers.Authorization',
+            'err.config',
+        ],
+        remove: true,
+    },
+});
+process.on('uncaughtException', (err, origin) => {
+    exports.logger.error({ err, origin }, `Uncaught exception.`);
+});

package/dist/middleware.d.ts

@@ -0,0 +1,3 @@
+import { RequestHandler } from 'express';
+import { HttpOptions } from './types';
+export declare const traceMiddleware: ({ ignoreTraceRoutes, traceHeaderKey, }?: HttpOptions) => RequestHandler;

package/dist/middleware.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceMiddleware = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+const span_1 = require("./span");
+const types_1 = require("./types");
+const utils_1 = require("./utils");
+const getFullUrl = (req) => {
+    const url = req.originalUrl || req.url;
+    if (url?.startsWith('http://') || url?.startsWith('https://'))
+        return url;
+    // Check if we have a workflow URL configured (preferred method)
+    if (process.env.UNNBOUND_WORKFLOW_URL) {
+        // Use workflow URL as the base URL
+        return `${process.env.UNNBOUND_WORKFLOW_URL.replace(/\/$/, '')}${url}`;
+    }
+    // Fallback to constructing from request info for incoming requests
+    const protocol = req.protocol || (req.secure ? 'https' : 'http');
+    const host = req.get('host') || req.get('x-forwarded-host') || 'localhost';
+    return `${protocol}://${host}${url}`;
+};
+const buildIncomingHttpPayload = (req, res, body) => ({
+    type: 'http',
+    http: {
+        url: getFullUrl(req),
+        method: req.method,
+        ip: (0, utils_1.normalizeIp)(req.ip),
+        incoming: true,
+        request: {
+            headers: req.headers,
+            body: (0, utils_1.safeJsonParse)(req.body),
+        },
+        response: res
+            ? {
+                headers: res?.headers,
+                status: res.statusCode,
+                body: (0, utils_1.safeJsonParse)(body),
+            }
+            : undefined,
+    },
+});
+const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, } = {
+    ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
+    traceHeaderKey: types_1.defaultTraceHeaderKey,
+}) => async (req, res, next) => {
+    if ((0, utils_1.shouldIgnorePath)(req.path, ignoreTraceRoutes))
+        return next();
+    const traceId = req.header(traceHeaderKey) || (0, uuid_1.v4)();
+    res.setHeader(traceHeaderKey, traceId);
+    return await storage_1.storage.run({ [storage_1.ContextAttribute.TraceId]: traceId }, async () => {
+        return await (0, span_1.startSpan)('Incoming HTTP request', async () => {
+            return new Promise((resolve) => {
+                // Capture response body for logging
+                const send = res.send.bind(res);
+                res.send = (body) => {
+                    res.locals.body = body;
+                    return send(body);
+                };
+                res.on('finish', () => resolve());
+                return next();
+            });
+        }, (o) => {
+            return buildIncomingHttpPayload(req, o
+                ? { statusCode: res.statusCode, headers: res.getHeaders() }
+                : undefined, res.locals.body);
+        });
+    });
+};
+exports.traceMiddleware = traceMiddleware;

package/dist/span.d.ts

@@ -0,0 +1,16 @@
+type LogPayloadGetterOptions<T> = {
+    error: unknown;
+    result?: never;
+} | {
+    error?: never;
+    result: T;
+};
+type LogPayloadGetter<T> = object | ((o?: LogPayloadGetterOptions<T>) => object);
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+export declare const startSpan: <T>(spanName: string, callback: () => Promise<T>, getter?: LogPayloadGetter<T>) => Promise<T>;
+export {};

package/dist/span.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSpan = void 0;
+const uuid_1 = require("uuid");
+const storage_1 = require("./storage");
+const logger_1 = require("./logger");
+/**
+ * Starts a span that tracks the duration of a callback
+ * @param spanName - The span name to use for logging
+ * @param callback - The async callback to execute
+ * @returns The result of the callback
+ */
+const startSpan = async (spanName, callback, getter) => {
+    const spanId = (0, uuid_1.v4)();
+    const start = performance.now();
+    const previous = storage_1.storage.getStore();
+    return storage_1.storage.run({
+        ...previous,
+        [storage_1.ContextAttribute.SpanId]: previous?.[storage_1.ContextAttribute.SpanId]
+            ? `${spanId} ${previous?.[storage_1.ContextAttribute.SpanId]}`
+            : spanId,
+    }, async () => {
+        logger_1.logger.info({ ...getLogPayload(getter) }, `${spanName} started.`);
+        try {
+            const result = await callback();
+            logger_1.logger.info({ ...getLogPayload(getter, { result }), duration: getDuration(start) }, `${spanName} completed.`);
+            return result;
+        }
+        catch (error) {
+            logger_1.logger.error({ ...getLogPayload(getter, { error }), err: error, duration: getDuration(start) }, `${spanName} failed.`);
+            throw error;
+        }
+    });
+};
+exports.startSpan = startSpan;
+const getLogPayload = (getter, o) => {
+    if (typeof getter !== 'function')
+        return getter;
+    return getter(o);
+};
+const getDuration = (start) => Math.round(performance.now() - start);

package/dist/storage.d.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from 'async_hooks';
+export declare enum ContextAttribute {
+    TraceId = "traceId",
+    SpanId = "spanId"
+}
+export interface Context {
+    [ContextAttribute.TraceId]?: string;
+    [ContextAttribute.SpanId]?: string;
+}
+export declare const storage: AsyncLocalStorage<Context>;

package/dist/storage.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storage = exports.ContextAttribute = void 0;
+const async_hooks_1 = require("async_hooks");
+var ContextAttribute;
+(function (ContextAttribute) {
+    ContextAttribute["TraceId"] = "traceId";
+    ContextAttribute["SpanId"] = "spanId";
+})(ContextAttribute || (exports.ContextAttribute = ContextAttribute = {}));
+exports.storage = new async_hooks_1.AsyncLocalStorage();

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for structured logging library
+ */
+/**
+ * Available log levels
+ */
+export type LogLevel = 'info' | 'debug' | 'error' | 'warn';
+/**
+ * Available log types
+ */
+export type LogType = 'general' | 'http' | 'sftp' | 'dbQueryTransaction';
+/**
+ * HTTP methods supported for HTTP logging
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+export interface Log<T extends LogType = 'general'> {
+    level: LogLevel;
+    message: string;
+    traceId: string;
+    spanId?: string;
+    type: T;
+    serviceId: string;
+    deploymentId: string;
+    workflowId: string;
+    err?: unknown;
+}
+export interface LogTransaction<T extends LogType> extends Log<T> {
+    duration?: number;
+}
+export interface HttpLog extends LogTransaction<'http'> {
+    http: {
+        url: string;
+        method: string;
+        ip?: string;
+        request: {
+            headers: Record<string, string>;
+            body?: unknown;
+        };
+        response?: {
+            headers: Record<string, string>;
+            status: number;
+            body?: unknown;
+        };
+    };
+}
+export type SftpOperation = 'connect' | 'upload' | 'download' | 'list' | 'delete' | 'rename' | 'stat' | 'exists' | 'realPath' | 'get' | 'put' | 'cwd' | 'mkdir' | 'rmdir' | 'chmod' | 'append' | 'uploadDir' | 'downloadDir' | 'end';
+export interface SftpPayload {
+    host: string;
+    operation: SftpOperation;
+    path?: string;
+    bytes?: number;
+    destinationPath?: string;
+    files?: number;
+}
+export interface SftpLog extends LogTransaction<'sftp'> {
+    sftp: SftpPayload;
+}
+export interface HttpOptions {
+    ignoreTraceRoutes?: string[];
+    traceHeaderKey?: string;
+}
+export declare const defaultIgnoreTraceRoutes: string[];
+export declare const defaultTraceHeaderKey = "x-unnbound-trace-id";

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Type definitions for structured logging library
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultTraceHeaderKey = exports.defaultIgnoreTraceRoutes = void 0;
+exports.defaultIgnoreTraceRoutes = ['/health', '/healthcheck'];
+exports.defaultTraceHeaderKey = 'x-unnbound-trace-id';

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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
+ */
+export declare const shouldIgnorePath: (path: string, patterns: string[]) => boolean;
+/**
+ * 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.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldIgnorePath = void 0;
+exports.safeJsonParse = safeJsonParse;
+exports.normalizeIp = normalizeIp;
+/**
+ * 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
+ */
+const 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);
+    });
+};
+exports.shouldIgnorePath = shouldIgnorePath;
+/**
+ * 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;
+}

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.0",
+  "version": "3.0.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "keywords": [
@@ -50,7 +50,7 @@
     }
   },
   "files": [
-    "dist/src/**/*",
+    "dist/**/*",
     "README.md",
     "LICENSE"
   ],
@@ -63,6 +63,7 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "test:watch": "jest --watch",
+    "typecheck": "tsc -noEmit",
     "lint": "eslint --cache --cache-location ./node_modules/.cache/eslint .",
     "lint:fix": "pnpm lint --fix",
     "format": "prettier --write .",