unnbound-logger-sdk 3.1.1 → 3.1.2

package/README.md

@@ -44,7 +44,7 @@ interface Log<T extends LogType = 'general'> {
   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 WORKFLOW_ENV, UNNBOUND_ENVIRONMENT, or ENVIRONMENT, whichever is set first
+  environment?: string; // From TEMPER_ENVIRONMENT, WORKFLOW_ENV, UNNBOUND_ENVIRONMENT, or ENVIRONMENT, whichever is set first
   err?: unknown; // Only present for Error objects
   duration?: number; // Duration in milliseconds for span operations
   http?: T extends 'http' ? HttpPayload : never;
@@ -464,5 +464,5 @@ console.log(traceId); // "550e8400-e29b-41d4-a716-446655440000"
 - `UNNBOUND_SERVICE_ID` - Service identifier (included in all logs)
 - `UNNBOUND_DEPLOYMENT_ID` - Deployment identifier (included in all logs)
 - `UNNBOUND_WORKFLOW_URL` - Base URL for webhook endpoint logging
-- `WORKFLOW_ENV`, `UNNBOUND_ENVIRONMENT`, `ENVIRONMENT` - Environment name, read in that order (included in all logs)
+- `TEMPER_ENVIRONMENT`, `WORKFLOW_ENV`, `UNNBOUND_ENVIRONMENT`, `ENVIRONMENT` - Environment name, read in that order (included in all logs). Temper injects `TEMPER_ENVIRONMENT`; the other names are legacy fallbacks.
 - `LOG_LEVEL` - Log level (default: 'debug')

package/dist/axios.d.ts

@@ -1,4 +1,5 @@
 import { type AxiosInstance, type AxiosRequestConfig, type AxiosResponse } from 'axios';
+import { startSpan } from './span';
 import { type HttpOptions } from './types';
 type GetPayload = (config: AxiosRequestConfig, res?: AxiosResponse) => object;
 type RedactOptions = {
@@ -15,6 +16,7 @@ interface HttpClientOptions extends HttpOptions<GetPayload> {
      * marker, suppression does not depend on runtime env vars.
      */
     silent?: boolean;
+    startSpan?: typeof startSpan;
 }
 /**
  * Wraps an axios instance to add tracing and span tracking.
@@ -24,5 +26,5 @@ interface HttpClientOptions extends HttpOptions<GetPayload> {
  * @param options - Configuration options for HTTP tracing
  * @returns The wrapped axios instance with span tracking
  */
-export declare const traceAxios: (client: AxiosInstance, { ignoreTraceRoutes, traceHeaderKey, getPayload, onRequest, redact: redactOptions, silent, }?: HttpClientOptions) => AxiosInstance;
+export declare const traceAxios: (client: AxiosInstance, { ignoreTraceRoutes, traceHeaderKey, getPayload, onRequest, redact: redactOptions, silent, startSpan: startSpanImpl, }?: HttpClientOptions) => AxiosInstance;
 export {};

package/dist/axios.js

@@ -46,7 +46,7 @@ const tracedMarker = Symbol.for('unnbound-logger-sdk.traceAxios.traced');
  * @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, getPayload = getNoopPayload, onRequest = onNoopRequest, redact: redactOptions, silent = false, } = {
+const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes, traceHeaderKey = types_1.defaultTraceHeaderKey, getPayload = getNoopPayload, onRequest = onNoopRequest, redact: redactOptions, silent = false, startSpan: startSpanImpl = span_1.startSpan, } = {
     ignoreTraceRoutes: types_1.defaultIgnoreTraceRoutes,
     traceHeaderKey: types_1.defaultTraceHeaderKey,
     getPayload: getNoopPayload,
@@ -54,7 +54,7 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
 }) => {
     if (tracedMarker in client)
         return client;
-    const redact = typeof redactOptions === 'boolean' ? { response: redactOptions } : redactOptions;
+    const redact = redactOptions === true || redactOptions === false ? { response: redactOptions } : redactOptions;
     const createSpanWrappedRequest = (originalMethod, method) => {
         const { headers: defaultHeaders, ...partialDefaultConfig } = client.defaults;
         const headers = { ...defaultHeaders.common, ...(method && defaultHeaders[method]) };
@@ -67,11 +67,14 @@ const traceAxios = (client, { ignoreTraceRoutes = types_1.defaultIgnoreTraceRout
                 return originalMethod(config);
             const traceId = storage_1.storage.getStore()?.traceId;
             config = { ...config, headers: { ...config.headers, [traceHeaderKey]: traceId } };
-            if (silent)
+            if (silent) {
+                // SAFETY: onRequest returns the originalMethod promise, typed as Axios R
                 return onRequest(config, (config) => originalMethod(config));
+            }
+            // SAFETY: startSpan resolves to the originalMethod promise, typed as Axios R
             return onRequest(config, (config) => {
                 // Execute the request within a span
-                return (0, span_1.startSpan)('Outgoing HTTP request', () => originalMethod(config), (options) => {
+                return startSpanImpl('Outgoing HTTP request', () => originalMethod(config), (options) => {
                     const response = options
                         ? options.error
                             ? (0, axios_1.isAxiosError)(options.error)

package/dist/emf.d.ts

@@ -1,3 +1,4 @@
+import type { Bindings } from 'pino';
 /**
  * CloudWatch Embedded Metric Format (EMF) support.
  *
@@ -18,7 +19,7 @@ export interface EmitMetricOptions {
     /** Dimension names to use for grouping (keys from dimensions object) */
     dimensionKeys?: string[];
     /** Additional properties to include in the log */
-    properties?: Record<string, unknown>;
+    properties?: Bindings;
 }
 /**
  * Emit a metric via CloudWatch EMF format.

package/dist/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * unnbound-logger
- *
- * A structured logging library built on Pino with TypeScript support.
- * Provides consistent, well-typed logging across different operational contexts.
- */
 export { type OnRequest, traceAxios } from './axios';
 export type { EmitMetricOptions, MetricDefinition, MetricUnit } from './emf';
 export { emitMetric, emitMetrics } from './emf';

package/dist/index.js

@@ -1,10 +1,4 @@
 "use strict";
-/**
- * unnbound-logger
- *
- * A structured logging library built on Pino with TypeScript support.
- * Provides consistent, well-typed logging across different operational contexts.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultTraceHeaderKey = exports.defaultMessageHeaderKey = exports.withTrace = exports.getTraceId = exports.withStorage = exports.storage = exports.startSpan = exports.traceMiddleware = exports.logger = exports.encode = exports.decode = exports.emitMetrics = exports.emitMetric = exports.traceAxios = void 0;
 var axios_1 = require("./axios");

package/dist/internal.d.ts

@@ -1,3 +1,11 @@
-export declare const hidden: (data: object) => unknown;
+interface InternalLogEntry {
+    _internal: true;
+    _hide?: true;
+}
+type LogEntry = object & {
+    _hide?: boolean;
+};
+export declare const hidden: (data: LogEntry) => boolean;
 /** @public - used by SDK consumers via dist/internal */
-export declare const internal: () => Record<string, unknown>;
+export declare const internal: () => InternalLogEntry;
+export {};

package/dist/internal.js

@@ -5,7 +5,7 @@ const o = { _internal: true };
 // Sandbox-internal logs are hidden from customer-visible streams.
 if (process.env.UNNBOUND_IDLE_TIMEOUT)
     o._hide = true;
-const hidden = (data) => '_hide' in data && data._hide;
+const hidden = (data) => data._hide === true;
 exports.hidden = hidden;
 /** @public - used by SDK consumers via dist/internal */
 const internal = () => o;

package/dist/logger.d.ts

@@ -1,13 +1,13 @@
 import pino from 'pino';
-import type { DestinationStream } from 'pino';
+import type { Bindings, DestinationStream } from 'pino';
 export interface ILogger {
-    trace(object: object, message: string): void;
+    trace(object: Bindings, message: string): void;
     trace(message: string): void;
-    debug(object: object, message: string): void;
+    debug(object: Bindings, message: string): void;
     debug(message: string): void;
-    info(object: object, message: string): void;
+    info(object: Bindings, message: string): void;
     info(message: string): void;
-    warn(object: object, message: string): void;
+    warn(object: Bindings, message: string): void;
     warn(message: string): void;
     error<O extends {
         err: unknown;

package/dist/logger.js

@@ -9,9 +9,22 @@ const uuid_1 = require("uuid");
 const encode_1 = require("./encode");
 const internal_1 = require("./internal");
 const storage_1 = require("./storage");
-const levels = new Set(['debug', 'info', 'warn', 'error']);
-const workflowEnvironment = process.env.WORKFLOW_ENV ?? process.env.UNNBOUND_ENVIRONMENT ?? process.env.ENVIRONMENT;
+// The Temper name wins while legacy fallbacks keep existing workflow images compatible.
+const workflowEnvironment = process.env.TEMPER_ENVIRONMENT ??
+    process.env.WORKFLOW_ENV ??
+    process.env.UNNBOUND_ENVIRONMENT ??
+    process.env.ENVIRONMENT;
 const formatLevel = (level) => ({ level });
+const isBindings = (value) => Object(value) === value;
+const isLogLevel = (value) => value === 'debug' || value === 'info' || value === 'warn' || value === 'error';
+const isStringAnnotation = (value) => {
+    try {
+        return String.prototype.valueOf.call(value) === value;
+    }
+    catch {
+        return false;
+    }
+};
 const formatLog = (log, visited = new WeakSet()) => {
     // Prevent infinite loops from circular references
     if (visited.has(log))
@@ -35,17 +48,13 @@ const formatLog = (log, visited = new WeakSet()) => {
         // We can't encode immutable properties.
         if (!Object.getOwnPropertyDescriptor(log, key)?.writable)
             continue;
-        if (typeof value === 'string') {
+        if (isStringAnnotation(value)) {
             log[key] = (0, encode_1.encode)(value);
         }
         else if (Array.isArray(value)) {
-            log[key] = value.map((item) => typeof item === 'string'
-                ? (0, encode_1.encode)(item)
-                : item && typeof item === 'object'
-                    ? formatLog(item, visited)
-                    : item);
+            log[key] = value.map((item) => isStringAnnotation(item) ? (0, encode_1.encode)(item) : isBindings(item) ? formatLog(item, visited) : item);
         }
-        else if (value !== null && typeof value === 'object') {
+        else if (isBindings(value)) {
             log[key] = formatLog(value, visited);
         }
     }
@@ -76,13 +85,14 @@ const loggerOptions = {
         logMethod(args, method) {
             const firstArg = args[0];
             let activeMethod = method;
-            if (!!firstArg && typeof firstArg === 'object') {
+            if (isBindings(firstArg)) {
                 // If the log entry is considered hidden, don't log it
                 if ((0, internal_1.hidden)(firstArg))
                     return;
                 // Dynamic log level by allowing overwriting the log level
-                if ('level' in firstArg && typeof firstArg.level === 'string' && levels.has(firstArg.level)) {
-                    activeMethod = this[firstArg.level];
+                const requestedLevel = firstArg.level;
+                if (isLogLevel(requestedLevel)) {
+                    activeMethod = this[requestedLevel];
                     firstArg.level = undefined;
                 }
             }

package/dist/middleware.js

@@ -75,6 +75,7 @@ const traceMiddleware = ({ ignoreTraceRoutes = types_1.defaultIgnoreTraceRoutes,
             const response = o
                 ? {
                     status: res.statusCode,
+                    // SAFETY: Express OutgoingHttpHeaders values are stringified by the tracer
                     headers: res.getHeaders(),
                     body: res.locals.body,
                 }

package/dist/span.d.ts

@@ -2,10 +2,8 @@ import type { Maybe } from './types';
 export type LogPayloadGetterOptions<T> = Maybe<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
+ * Logs `<spanName> started/completed/failed` with duration (ms); nested spans chain spanId
+ * "child parent". getter receives {result} or {error}.
  */
 export declare const startSpan: <T>(spanName: string, callback: () => Promise<T>, getter?: LogPayloadGetter<T>) => Promise<T>;
 export {};

package/dist/span.js

@@ -6,10 +6,8 @@ const logger_1 = require("./logger");
 const storage_1 = require("./storage");
 const trace_1 = require("./trace");
 /**
- * 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
+ * Logs `<spanName> started/completed/failed` with duration (ms); nested spans chain spanId
+ * "child parent". getter receives {result} or {error}.
  */
 const startSpan = async (spanName, callback, getter) => {
     const spanId = (0, uuid_1.v4)();
@@ -34,7 +32,7 @@ const startSpan = async (spanName, callback, getter) => {
 };
 exports.startSpan = startSpan;
 const getLogPayload = (getter, o) => {
-    if (typeof getter !== 'function')
+    if (!(getter instanceof Function))
         return getter;
     return getter(o);
 };

package/dist/storage.d.ts

@@ -8,5 +8,5 @@ interface UnnboundStorage extends AsyncLocalStorage<object> {
     getStore<T>(): T | undefined;
 }
 export declare const storage: UnnboundStorage;
-export declare const withStorage: <T>(data: object, callback: () => Promise<T>) => Promise<T>;
+export declare const withStorage: <T, Data extends object>(data: Data, callback: () => Promise<T>) => Promise<T>;
 export {};

package/dist/storage.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.withStorage = exports.storage = void 0;
 const node_async_hooks_1 = require("node:async_hooks");
-exports.storage = new node_async_hooks_1.AsyncLocalStorage();
+exports.storage = 
+// SAFETY: UnnboundStorage only adds a typed getStore helper over AsyncLocalStorage
+new node_async_hooks_1.AsyncLocalStorage();
 const withStorage = async (data, callback) => {
     const previous = exports.storage.getStore();
     return exports.storage.run({ ...previous, ...data }, callback);

package/dist/trace.d.ts

@@ -1,20 +1,7 @@
-/**
- * Generates a trace ID
- * @returns A trace ID
- */
 export declare const getTraceId: () => string;
-/**
- * Generates a message ID
- * @public - used by SDK consumers via dist/trace
- * @returns A message ID
- */
+/** @public Consumed via dist/trace; keep exported. */
 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
- */
+/** traceId/messageId precedence: extra → enclosing store → fresh uuid. */
 export declare const withTrace: <T, E extends {
     traceId?: string;
     messageId?: string;

package/dist/trace.js

@@ -3,25 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withTrace = exports.getMessageId = exports.getTraceId = void 0;
 const uuid_1 = require("uuid");
 const storage_1 = require("./storage");
-/**
- * Generates a trace ID
- * @returns A trace ID
- */
 const getTraceId = () => (0, uuid_1.v4)();
 exports.getTraceId = getTraceId;
-/**
- * Generates a message ID
- * @public - used by SDK consumers via dist/trace
- * @returns A message ID
- */
+/** @public Consumed via dist/trace; keep exported. */
 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
- */
+/** traceId/messageId precedence: extra → enclosing store → fresh uuid. */
 const withTrace = (callback, extra) => {
     const previous = storage_1.storage.getStore();
     const traceId = extra?.traceId ?? previous?.traceId ?? (0, exports.getTraceId)();

package/dist/utils.d.ts

@@ -1,19 +1,6 @@
-/**
- * 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
- */
+/** patterns are globs (`*`, `?`) matched against the whole path. */
 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.
- */
+/** Non-string or invalid JSON → input returned unchanged. */
 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.
- */
+/** Strips the IPv4-mapped IPv6 prefix (::ffff:). */
 export declare function normalizeIp(ip: string | undefined): string | undefined;

package/dist/utils.js

@@ -3,31 +3,18 @@ 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
- */
+/** patterns are globs (`*`, `?`) matched against the whole path. */
 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 regexPattern = pattern.replace(/\./g, '\\.').replace(/\*/g, '.*').replace(/\?/g, '.');
         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.
- */
+/** Non-string or invalid JSON → input returned unchanged. */
 function safeJsonParse(data) {
-    if (typeof data === 'string') {
+    if (String(data) === data) {
         try {
             return JSON.parse(data);
         }
@@ -37,15 +24,10 @@ function safeJsonParse(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.
- */
+/** Strips the IPv4-mapped IPv6 prefix (::ffff:). */
 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);
     }

package/package.json

@@ -1,15 +1,15 @@
 {
   "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.1.1",
+  "version": "3.1.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "test": "vitest run src",
     "typecheck": "tsc --noEmit",
-    "format": "biome format --write .",
-    "format:check": "biome format .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
     "prepublishOnly": "npm run build",
     "start:example": "tsx watch examples/node-express.ts",
     "version:bump": "npm version patch"
@@ -35,7 +35,7 @@
     "url": "https://github.com/unnbounddev/unnbound-sdks/issues"
   },
   "dependencies": {
-    "axios": "1.16.0",
+    "axios": "1.18.0",
     "express": "^4.0.0 || ^5.0.0",
     "pino": "^10.3.1",
     "uuid": "^11.1.1"
@@ -47,7 +47,7 @@
     "vitest": "^4.0.15"
   },
   "peerDependencies": {
-    "axios": "^1.15.1",
+    "axios": "^1.18.0",
     "express": "^4.0.0 || ^5.0.0"
   },
   "peerDependenciesMeta": {