unnbound-logger-sdk 3.0.26 → 3.0.28

package/package.json

@@ -1,9 +1,23 @@
 {
   "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.26",
+  "version": "3.0.28",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "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 .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "pnpm build",
+    "start:example": "npx --yes tsx --watch examples/node-express.ts",
+    "version:bump": "npm version patch"
+  },
   "keywords": [
     "logging",
     "typescript",
@@ -57,18 +71,5 @@
   "engines": {
     "node": ">=22"
   },
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsc",
-    "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 .",
-    "format:check": "prettier --check .",
-    "start:example": "npx --yes tsx --watch examples/node-express.ts",
-    "version:bump": "npm version patch"
-  }
-}
+  "sideEffects": false
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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/dist/file.d.ts

@@ -1,175 +0,0 @@
-import { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios';
-export declare const hidden: (data: object) => unknown;
-export declare const internal: () => Record<string, unknown>;
-type GetAxiosPayload = (config: AxiosRequestConfig, res?: AxiosResponse) => object;
-/**
- * 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: AxiosInstance, { ignoreTraceRoutes, traceHeaderKey, getPayload, }?: HttpOptions<GetAxiosPayload>) => AxiosInstance;
-export declare const encode: (value: string) => string;
-export declare const decode: (value: string) => string;
-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;
-import { Request, RequestHandler } from 'express';
-interface Response {
-    status: number;
-    headers?: Record<string, string | undefined>;
-    body?: unknown;
-}
-type GetHttpPayload = (config: Request, res?: Response) => object;
-export declare const traceMiddleware: ({ ignoreTraceRoutes, traceHeaderKey, messageHeaderKey, getPayload, }?: HttpOptions<GetHttpPayload>) => RequestHandler;
-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>;
-import { AsyncLocalStorage } from 'async_hooks';
-export interface Context {
-    traceId?: string;
-    spanId?: string;
-    messageId?: string;
-}
-export declare const storage: AsyncLocalStorage<Context>;
-/**
- * Generates a trace ID
- * @returns A trace ID
- */
-export declare const getTraceId: () => string;
-/**
- * Generates a message ID
- * @returns A message ID
- */
-export declare const getMessageId: () => string;
-/**
- * Runs a callback with a trace ID
- * @param callback - The callback to run
- * @param extra - Extra context to add to the trace
- * @returns The result of the callback
- */
-export declare const withTrace: <T, E extends {
-    traceId?: string;
-    messageId?: string;
-}>(callback: () => T, extra?: E) => T;
-/**
- * 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' | 'edi';
-/**
- * HTTP methods supported for HTTP logging
- */
-export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'options' | 'head';
-export interface Log<T extends LogType = 'general'> {
-    logId: string;
-    level: LogLevel;
-    message: string;
-    type: T;
-    traceId?: string;
-    spanId?: string;
-    serviceId?: string;
-    deploymentId?: string;
-    workflowId?: string;
-    http: T extends 'http' ? HttpPayload : never;
-    sftp: T extends 'sftp' ? SftpPayload : never;
-    edi: T extends 'edi' ? EdiPayload : never;
-    duration?: number;
-    err?: unknown;
-}
-export interface HttpPayload {
-    url: string;
-    method: HttpMethod;
-    ip?: string;
-    request: {
-        headers: Record<string, string | string[]>;
-        body?: unknown;
-    };
-    response?: {
-        headers: Record<string, 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' | 'close';
-export interface SftpPayload {
-    host: string;
-    operation: SftpOperation;
-    path?: string;
-    bytes?: number;
-    destinationPath?: string;
-    files?: string[];
-    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;
-    messageHeaderKey?: string;
-    getPayload?: G;
-}
-export declare const defaultIgnoreTraceRoutes: string[];
-export declare const defaultTraceHeaderKey = "x-unnbound-trace-id";
-export declare const defaultMessageHeaderKey = "x-message-id";
-/**
- * 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;
-export {};

package/dist/file.js

@@ -1,362 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldIgnorePath = exports.defaultMessageHeaderKey = exports.defaultTraceHeaderKey = exports.defaultIgnoreTraceRoutes = exports.withTrace = exports.getMessageId = exports.getTraceId = exports.storage = exports.startSpan = exports.traceMiddleware = exports.logger = exports.decode = exports.encode = exports.traceAxios = exports.internal = exports.hidden = void 0;
-exports.safeJsonParse = safeJsonParse;
-exports.normalizeIp = normalizeIp;
-const axios_1 = require("axios");
-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 hidden = (data) => '_hide' in data && data._hide;
-exports.hidden = hidden;
-const internal = () => o;
-exports.internal = internal;
-const getAxiosNoopPayload = () => ({});
-const extractAxiosQueryParams = (url, config) => {
-    const object = new URL(url);
-    const query = { ...Object.fromEntries(object.searchParams.entries()), ...config.params };
-    const keys = Object.keys(query);
-    keys.forEach((key) => object.searchParams.delete(key));
-    return { url: object.toString(), query: keys.length > 0 ? query : undefined };
-};
-const buildOutgoingAxiosHttpPayload = (config, res) => ({
-    type: 'http',
-    http: {
-        ...extractAxiosQueryParams([config.baseURL, config.url].filter(Boolean).join(''), config),
-        method: config.method?.toLowerCase() ?? 'get',
-        incoming: false,
-        request: {
-            headers: config.headers,
-            body: safeJsonParse(config.data),
-        },
-        response: res
-            ? {
-                headers: res?.headers,
-                status: res.status,
-                body: 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 = exports.defaultIgnoreTraceRoutes, traceHeaderKey = exports.defaultTraceHeaderKey, getPayload = getAxiosNoopPayload, } = {
-    ignoreTraceRoutes: exports.defaultIgnoreTraceRoutes,
-    traceHeaderKey: exports.defaultTraceHeaderKey,
-    getPayload: getAxiosNoopPayload,
-}) => {
-    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, exports.shouldIgnorePath)(url, ignoreTraceRoutes))
-                return originalMethod(config);
-            const traceId = exports.storage.getStore()?.traceId;
-            config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
-            // Execute the request within a span
-            return (0, exports.startSpan)(`Outgoing HTTP request`, () => originalMethod(config), (options) => {
-                const response = options
-                    ? options.error
-                        ? (0, axios_1.isAxiosError)(options.error)
-                            ? options.error.response
-                            : undefined
-                        : options.result
-                    : undefined;
-                return {
-                    ...buildOutgoingAxiosHttpPayload(config, response),
-                    ...getPayload(config, response),
-                };
-            });
-        };
-    };
-    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, method, url, data });
-    });
-    ['delete', 'get', 'head', 'options'].forEach((method) => {
-        const func = createSpanWrappedRequest(request, method);
-        client[method] = (url, config) => func({ ...config, method, url });
-    });
-    return client;
-};
-exports.traceAxios = traceAxios;
-const encode = (value) => value.replaceAll('\n', '\r');
-exports.encode = encode;
-const decode = (value) => value.replaceAll('\r', '\n');
-exports.decode = decode;
-const pino_1 = __importDefault(require("pino"));
-const levels = new Set(['debug', 'info', 'warn', 'error']);
-const formatLevel = (level) => ({ level });
-const formatLog = (log) => {
-    Object.entries(log).forEach(([key, value]) => {
-        if (value && typeof value === 'object') {
-            log[key] = formatLog(value);
-            return;
-        }
-        if (typeof value === 'string') {
-            log[key] = (0, exports.encode)(value);
-            return;
-        }
-    });
-    return log;
-};
-exports.logger = (0, pino_1.default)({
-    level: process.env.LOG_LEVEL ?? 'debug',
-    base: {
-        environment: process.env.ENVIRONMENT,
-        workflowId: process.env.UNNBOUND_WORKFLOW_ID,
-        serviceId: process.env.UNNBOUND_SERVICE_ID,
-        deploymentId: process.env.UNNBOUND_DEPLOYMENT_ID,
-    },
-    mixin: () => ({ ...exports.storage.getStore(), logId: (0, uuid_1.v4)() }),
-    serializers: {
-        req: pino_1.default.stdSerializers.req,
-        res: pino_1.default.stdSerializers.res,
-        err: pino_1.default.stdSerializers.err,
-        message: exports.encode,
-    },
-    // Let CloudWatch handle timestamps
-    timestamp: false,
-    // Change message field from 'msg' to 'message'
-    messageKey: 'message',
-    formatters: { level: formatLevel, log: formatLog },
-    hooks: {
-        logMethod(args, method) {
-            const firstArg = args[0];
-            if (!!firstArg && typeof firstArg === 'object') {
-                // If the log entry is considered hidden, don't log it
-                if ((0, exports.hidden)(firstArg))
-                    return;
-                // Dynamic log level by allowing overwriting the 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',
-            '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.`);
-});
-const extractQueryParams = (url) => {
-    const object = new URL(url);
-    const query = Object.fromEntries(object.searchParams.entries());
-    const keys = Object.keys(query);
-    keys.forEach((key) => object.searchParams.delete(key));
-    return { url: object.toString(), query: keys.length > 0 ? query : undefined };
-};
-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 `https://${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 buildHttpIncomingHttpPayload = (req, res) => ({
-    type: 'http',
-    http: {
-        ...extractQueryParams(getFullUrl(req)),
-        method: req.method.toLowerCase(),
-        ip: normalizeIp(req.ip),
-        incoming: true,
-        request: {
-            headers: req.headers,
-            body: safeJsonParse(req.body),
-        },
-        response: res
-            ? {
-                headers: res.headers,
-                status: res.status,
-                body: safeJsonParse(res.body),
-            }
-            : undefined,
-    },
-});
-const getHttpNoopPayload = () => ({});
-const traceMiddleware = ({ ignoreTraceRoutes = exports.defaultIgnoreTraceRoutes, traceHeaderKey = exports.defaultTraceHeaderKey, messageHeaderKey = exports.defaultMessageHeaderKey, getPayload = getHttpNoopPayload, } = {
-    ignoreTraceRoutes: exports.defaultIgnoreTraceRoutes,
-    traceHeaderKey: exports.defaultTraceHeaderKey,
-    messageHeaderKey: exports.defaultMessageHeaderKey,
-    getPayload: getHttpNoopPayload,
-}) => async (req, res, next) => {
-    if ((0, exports.shouldIgnorePath)(req.path, ignoreTraceRoutes))
-        return next();
-    const traceId = req.header(traceHeaderKey) || (0, exports.getTraceId)();
-    const messageId = req.header(messageHeaderKey) || undefined;
-    res.setHeader(traceHeaderKey, traceId);
-    return await (0, exports.withTrace)(async () => {
-        return await (0, exports.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) => {
-            const response = o
-                ? {
-                    status: res.statusCode,
-                    headers: res.getHeaders(),
-                    body: res.locals.body,
-                }
-                : undefined;
-            return { ...buildHttpIncomingHttpPayload(req, response), ...getPayload(req, response) };
-        });
-    }, messageId ? { traceId, messageId } : { traceId });
-};
-exports.traceMiddleware = traceMiddleware;
-/**
- * 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 = exports.storage.getStore();
-    return exports.storage.run({
-        ...previous,
-        traceId: previous?.traceId ?? (0, exports.getTraceId)(),
-        spanId: previous?.spanId ? `${spanId} ${previous?.spanId}` : spanId,
-    }, async () => {
-        exports.logger.info({ ...getLogPayload(getter) }, `${spanName} started.`);
-        try {
-            const result = await callback();
-            exports.logger.info({ ...getLogPayload(getter, { result }), duration: getDuration(start) }, `${spanName} completed.`);
-            return result;
-        }
-        catch (error) {
-            exports.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);
-const async_hooks_1 = require("async_hooks");
-exports.storage = new async_hooks_1.AsyncLocalStorage();
-const uuid_1 = require("uuid");
-/**
- * Generates a trace ID
- * @returns A trace ID
- */
-const getTraceId = () => (0, uuid_1.v4)();
-exports.getTraceId = getTraceId;
-/**
- * Generates a message ID
- * @returns A message ID
- */
-const getMessageId = () => (0, uuid_1.v4)();
-exports.getMessageId = getMessageId;
-/**
- * Runs a callback with a trace ID
- * @param callback - The callback to run
- * @param extra - Extra context to add to the trace
- * @returns The result of the callback
- */
-const withTrace = (callback, extra) => {
-    const previous = exports.storage.getStore();
-    const traceId = extra?.traceId ?? previous?.traceId ?? (0, exports.getTraceId)();
-    const messageId = extra?.messageId ?? previous?.messageId ?? (0, exports.getMessageId)();
-    return exports.storage.run({ ...previous, ...extra, traceId, messageId }, callback);
-};
-exports.withTrace = withTrace;
-exports.defaultIgnoreTraceRoutes = ['/health', '/healthcheck'];
-exports.defaultTraceHeaderKey = 'x-unnbound-trace-id';
-exports.defaultMessageHeaderKey = 'x-message-id';
-/**
- * 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;
-}