logixia 2.0.0 → 2.0.4

package/dist/browser.js

@@ -1,5 +1,258 @@
-
-//#region src/utils/safe-stringify.ts
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/utils/sensitive-names.ts
+/**
+* The one list of sensitive names. Log redaction (redact.utils), the HTTP logger
+* middleware and transport secret handling (transports/secret-config) all read it,
+* so the lists cannot drift. No imports: safe from any module, including browser code.
+*/
+/** Field names redacted by name, wherever they appear in logged data. */
+const SENSITIVE_KEY_NAMES = [
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"apiKey",
+	"api_key",
+	"accessToken",
+	"access_token",
+	"refreshToken",
+	"refresh_token",
+	"authorization",
+	"credentials",
+	"privateKey",
+	"private_key",
+	"clientSecret",
+	"client_secret",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"session",
+	"proxy-authorization",
+	"x-auth-token",
+	"x-access-token",
+	"aws_secret_access_key",
+	"awsSecretAccessKey",
+	"secretAccessKey"
+];
+/**
+* Extra names that only mean "secret" inside transport configuration, where
+* short words like `key` or `signature` are credentials, not log fields.
+*/
+const TRANSPORT_CONFIG_SECRET_NAMES = [
+	"writeKey",
+	"apiSecret",
+	"connectionString",
+	"sessionToken",
+	"passphrase",
+	"signature",
+	"pwd",
+	"pfx",
+	"cert",
+	"key",
+	"auth"
+];
+/** Query-string parameters whose values are never logged. */
+const DEFAULT_REDACT_QUERY_PARAMS = [
+	"token",
+	"access_token",
+	"refresh_token",
+	"code",
+	"password",
+	"secret",
+	"api_key",
+	"apikey",
+	"key",
+	"signature",
+	"sig",
+	"auth"
+];
+// src/transports/secret-config.ts
+/**
+* Keeps credentials out of serialized transport output and error text.
+*
+* `protectSecrets()` replaces each listed field with a non-enumerable accessor backed
+* by a WeakMap, whether or not the field is assigned yet, so later assignments (a
+* connection opened on first write, a refreshed token) stay hidden too. It also
+* installs `toJSON()` and a Node inspect hook returning a redacted view: scalar
+* fields stay for debugging, secret-looking keys become '[REDACTED]', URLs lose
+* userinfo, query and fragment. No Node imports, so browser bundles can use it.
+*/
+const REDACTED = "[REDACTED]";
+const INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+const MAX_DEPTH = 4;
+const SCHEME_PREFIX = /^[a-z][a-z0-9+.-]*:\/\//i;
+function normalizeName(name) {
+	return name.toLowerCase().replaceAll("-", "").replaceAll("_", "");
+}
+const SECRET_NAMES = [...SENSITIVE_KEY_NAMES, ...TRANSPORT_CONFIG_SECRET_NAMES].map(normalizeName);
+new Set(DEFAULT_REDACT_QUERY_PARAMS.map(normalizeName));
+/** Exact match for short names (`key`, `pfx`), suffix match for longer ones (`azureClientSecret`). */
+function isSecretKey(key) {
+	const name = normalizeName(key);
+	return SECRET_NAMES.some((n) => name === n || n.length >= 5 && name.endsWith(n));
+}
+function isUrlKey(key) {
+	return /url|uri|endpoint|href/i.test(key);
+}
+function isPlainObject(value) {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/** Absolute URL: `scheme://host` only. Relative or unparseable: path kept, query and fragment cut. */
+function redactUrl(raw) {
+	if (typeof raw !== "string") return `${raw.protocol}//${raw.host}`;
+	if (SCHEME_PREFIX.test(raw)) try {
+		const url = new URL(raw);
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return REDACTED;
+	}
+	return raw.split(/[?#]/, 1)[0] ?? "";
+}
+function redactHeaders(headers) {
+	if (!headers || typeof headers !== "object") return headers;
+	return Object.fromEntries(Object.keys(headers).map((name) => [name, REDACTED]));
+}
+/** Redacted deep copy of a config-like value. Never throws, never returns a secret. */
+function redactConfig(value, depth = 0, key = "") {
+	var _value$constructor;
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return SCHEME_PREFIX.test(value) || isUrlKey(key) ? redactUrl(value) : value;
+	if (typeof value === "number" || typeof value === "boolean") return value;
+	if (typeof value === "function") return "[Function]";
+	if (typeof value !== "object") return "[Unserializable]";
+	if (typeof URL !== "undefined" && value instanceof URL) return redactUrl(value);
+	if (Array.isArray(value)) return depth >= MAX_DEPTH ? "[Array]" : value.map((v) => redactConfig(v, depth + 1, key));
+	if (!isPlainObject(value) || depth >= MAX_DEPTH) return `[${((_value$constructor = value.constructor) === null || _value$constructor === void 0 ? void 0 : _value$constructor.name) ?? "Object"}]`;
+	const out = {};
+	for (const [name, inner] of Object.entries(value)) if (isSecretKey(name)) out[name] = inner === void 0 ? void 0 : REDACTED;
+	else if (name.toLowerCase() === "headers") out[name] = redactHeaders(inner);
+	else out[name] = redactConfig(inner, depth + 1, name);
+	return out;
+}
+const hiddenKeys = /* @__PURE__ */ new WeakMap();
+const hiddenValues = /* @__PURE__ */ new WeakMap();
+function viewOf(target) {
+	var _target$constructor;
+	const hidden = hiddenKeys.get(target) ?? /* @__PURE__ */ new Set();
+	const values = hiddenValues.get(target);
+	const view = { class: (_target$constructor = target.constructor) === null || _target$constructor === void 0 ? void 0 : _target$constructor.name };
+	for (const key of /* @__PURE__ */ new Set([...Object.keys(target), ...hidden])) {
+		const inner = hidden.has(key) ? values === null || values === void 0 ? void 0 : values.get(key) : target[key];
+		if (isSecretKey(key)) view[key] = inner === void 0 ? void 0 : REDACTED;
+		else if (key.toLowerCase() === "headers") view[key] = redactHeaders(inner);
+		else if (inner !== null && typeof inner === "object" && !hidden.has(key) && !(inner instanceof URL)) view[key] = "[Object]";
+		else if (hidden.has(key) && typeof inner === "string" && !isUrlKey(key)) view[key] = REDACTED;
+		else view[key] = redactConfig(inner, 0, key);
+	}
+	return view;
+}
+/**
+* Hides `keys` on `target` (assigned or not yet) and gives it a redacted `toJSON()` /
+* inspect view. Fields stay readable and writable. Safe to call more than once.
+* Throws when the target cannot carry the protection (frozen or sealed), instead of
+* silently leaving the secret enumerable.
+*/
+function protectSecrets(target, keys) {
+	if (!Object.isExtensible(target)) {
+		var _target$constructor2;
+		throw new TypeError(`protectSecrets: ${((_target$constructor2 = target.constructor) === null || _target$constructor2 === void 0 ? void 0 : _target$constructor2.name) ?? "object"} is not extensible`);
+	}
+	let hidden = hiddenKeys.get(target);
+	let values = hiddenValues.get(target);
+	if (!hidden || !values) {
+		hidden = /* @__PURE__ */ new Set();
+		values = /* @__PURE__ */ new Map();
+		hiddenKeys.set(target, hidden);
+		hiddenValues.set(target, values);
+		const view = () => viewOf(target);
+		Object.defineProperty(target, "toJSON", {
+			value: view,
+			enumerable: false,
+			configurable: true
+		});
+		Object.defineProperty(target, INSPECT_CUSTOM, {
+			value: view,
+			enumerable: false,
+			configurable: true
+		});
+	}
+	const store = values;
+	for (const key of keys) {
+		if (hidden.has(key)) continue;
+		const desc = Object.getOwnPropertyDescriptor(target, key);
+		if (desc && !desc.configurable) throw new TypeError(`protectSecrets: "${key}" is not configurable`);
+		if (desc && "value" in desc) store.set(key, desc.value);
+		hidden.add(key);
+		Object.defineProperty(target, key, {
+			enumerable: false,
+			configurable: true,
+			get: () => store.get(key),
+			set: (next) => void store.set(key, next)
+		});
+	}
+}
+// src/utils/internal-log.ts
+/**
+* Internal logging helpers for use within the logixia library itself.
+*
+* These functions write directly to stderr/stdout without going through
+* LogixiaLogger — this avoids circular dependencies and ensures internal
+* diagnostics still surface even when the logger is misconfigured.
+*
+* Library code must NEVER call console.log/warn/error directly. Use these
+* helpers instead so that internal output can be silenced in tests by setting
+* the LOGIXIA_SILENT_INTERNAL=1 environment variable.
+*/
+/**
+* Read the silence flag on each call rather than caching it at import time, so
+* setting LOGIXIA_SILENT_INTERNAL=1 AFTER the module is first imported (e.g. in
+* a test setup file) still takes effect — the documented test-silencing
+* behavior was previously unreliable because the value was frozen at load.
+*/
+function isSilent() {
+	var _process$env;
+	if (typeof process !== "undefined" && ((_process$env = process.env) === null || _process$env === void 0 ? void 0 : _process$env.LOGIXIA_SILENT_INTERNAL) === "1") return true;
+	const flag = globalThis["LOGIXIA_SILENT_INTERNAL"];
+	return flag === "1" || flag === 1 || flag === true;
+}
+/**
+* Write a line to stderr, falling back to the matching console method where
+* `process` is unavailable (browsers, Cloudflare Workers, Deno without Node compat).
+*/
+function writeLine(method, line) {
+	var _process$stderr;
+	if (typeof process !== "undefined" && typeof ((_process$stderr = process.stderr) === null || _process$stderr === void 0 ? void 0 : _process$stderr.write) === "function") process.stderr.write(`${line}\n`);
+	else if (typeof console !== "undefined" && typeof console[method] === "function") console[method](line);
+}
+/**
+* Emit an internal debug/info message to stderr.
+* Use for field-enable/disable notifications that a developer might want to see
+* during development but should not appear in production log streams.
+*/
+function internalLog(message) {
+	if (!isSilent()) writeLine("log", `[logixia] ${message}`);
+}
+/**
+* Emit an internal warning to stderr.
+* Use when something is misconfigured but logixia can continue operating.
+*/
+function internalWarn(message) {
+	if (!isSilent()) writeLine("warn", `[logixia:warn] ${message}`);
+}
+/**
+* Emit an internal error to stderr.
+* Use when a transport write fails or a serious internal error occurs.
+*/
+function internalError(message, error) {
+	if (!isSilent()) {
+		let errStr = "";
+		if (error instanceof Error) errStr = ` — ${error.message}`;
+		else if (error != null) errStr = ` — ${String(error)}`;
+		writeLine("error", `[logixia:error] ${message}${errStr}`);
+	}
+}
+// src/utils/safe-stringify.ts
 /** Build a JSONPath like `$["a"][0]["b"]` for a decycle pointer. */
 function jsonPath(parts) {
 	let path = "$";
@@ -83,9 +336,7 @@ function stringifyForLog(value) {
 		}
 	}
 }
-
-//#endregion
-//#region src/utils/otel.ts
+// src/utils/otel.ts
 let _otelApi;
 function tryLoadOtelApi() {
 	if (_otelApi !== void 0) return _otelApi;
@@ -149,7 +400,6 @@ function getOtelMetaFields(opts = {}) {
 		[traceFlagsField]: ctx.traceFlags
 	};
 }
-let _bridgeOptions = null;
 /**
 * Initialise the global OTel bridge.
 *
@@ -163,48 +413,59 @@ let _bridgeOptions = null;
 * initOtelBridge();
 * ```
 */
-function initOtelBridge(opts = {}) {
-	_bridgeOptions = opts;
-}
+function initOtelBridge(opts = {}) {}
 /**
 * Disable the OTel bridge (useful for tests).
 */
-function disableOtelBridge() {
-	_bridgeOptions = null;
-}
-
-//#endregion
-//#region src/utils/internal-log.ts
+function disableOtelBridge() {}
+// src/utils/typed-logger.ts
 /**
-* Internal logging helpers for use within the logixia library itself.
+* logixia — TypeScript typed log fields
 *
-* These functions write directly to stderr/stdout without going through
-* LogixiaLogger — this avoids circular dependencies and ensures internal
-* diagnostics still surface even when the logger is misconfigured.
+* Solves the type-safety gap: standard `Record<string, unknown>` metadata gives
+* zero IDE autocomplete and lets typos slip silently into production logs.
 *
-* Library code must NEVER call console.log/warn/error directly. Use these
-* helpers instead so that internal output can be silenced in tests by setting
-* the LOGIXIA_SILENT_INTERNAL=1 environment variable.
-*/
-/**
-* Read the silence flag on each call rather than caching it at import time, so
-* setting LOGIXIA_SILENT_INTERNAL=1 AFTER the module is first imported (e.g. in
-* a test setup file) still takes effect — the documented test-silencing
-* behavior was previously unreliable because the value was frozen at load.
-*/
-function isSilent() {
-	return process.env.LOGIXIA_SILENT_INTERNAL === "1";
-}
-/**
-* Emit an internal warning to stderr.
-* Use when something is misconfigured but logixia can continue operating.
+* Two complementary utilities:
+*
+* 1. `createTypedLogger<TFields>()` — wraps any IBaseLogger so that the second
+*    argument of every log method is constrained to `TFields` (a typed object).
+*    Compile-time safety, zero runtime overhead.
+*
+* 2. `defineLogSchema<TFields>(schema)` — declares expected fields with optional
+*    validators. In development (NODE_ENV !== 'production') every log call is
+*    validated against the schema and a warning is emitted for missing required
+*    fields or type mismatches.
+*
+* @example
+* ```ts
+* import { createTypedLogger, defineLogSchema } from 'logixia';
+*
+* interface OrderFields {
+*   orderId: string;
+*   userId: string;
+*   amount?: number;
+*   currency?: string;
+* }
+*
+* const schema = defineLogSchema<OrderFields>({
+*   orderId: { type: 'string', required: true },
+*   userId:  { type: 'string', required: true },
+*   amount:  { type: 'number' },
+*   currency: { type: 'string' },
+* });
+*
+* const orderLogger = createTypedLogger<OrderFields>(baseLogger, schema);
+* await orderLogger.info('Order created', { orderId: 'ord_123', userId: 'usr_456', amount: 99.99 });
+* //                                       ^^^^ fully typed autocomplete ^^^^
+* ```
 */
-function internalWarn(message) {
-	if (!isSilent()) process.stderr.write(`[logixia:warn] ${message}\n`);
+function isProduction() {
+	try {
+		return process.env.NODE_ENV === "production";
+	} catch {
+		return false;
+	}
 }
-
-//#endregion
-//#region src/utils/typed-logger.ts
 /**
 * Define a typed schema for a category of log entries.
 *
@@ -215,7 +476,7 @@ function defineLogSchema(fields) {
 	return {
 		fields,
 		validate(payload) {
-			if (process.env["NODE_ENV"] === "production") return [];
+			if (isProduction()) return [];
 			const warnings = [];
 			for (const [key, def] of Object.entries(fields)) {
 				const value = payload[key];
@@ -267,9 +528,42 @@ function createTypedLogger(logger, schema) {
 		trace: (m, d) => withValidation("trace", (logger.trace ?? logger.debug).bind(logger), m, d)
 	};
 }
-
-//#endregion
-//#region src/browser.ts
+// src/browser.ts
+/**
+* logixia — Browser / Edge Runtime entry point
+*
+* This module is the browser-safe subset of logixia. It contains **no**
+* references to Node.js built-ins (`node:fs`, `node:http`, `node:worker_threads`,
+* `node:crypto`, `node:async_hooks`) so it can be bundled for:
+*
+* - Browser (Webpack / Vite / esbuild)
+* - Cloudflare Workers / Vercel Edge Functions
+* - Deno (via ESM import)
+* - Bun (core subset, no file/DB transports)
+*
+* Excluded from this entry: FileTransport, DatabaseTransport, WorkerTransport,
+* CloudWatchTransport, GCPTransport, AzureMonitorTransport, and anything that
+* requires `AsyncLocalStorage`.
+*
+* @example Basic browser usage
+* ```ts
+* import { createBrowserLogger, BrowserConsoleTransport } from 'logixia/browser';
+*
+* const logger = createBrowserLogger({ appName: 'my-app' });
+* logger.info('Page loaded', { url: location.href });
+* ```
+*
+* @example Custom transport in browser
+* ```ts
+* import { createBrowserLogger, BrowserConsoleTransport } from 'logixia/browser';
+*
+* const logger = createBrowserLogger({
+*   appName: 'my-app',
+*   json: false,       // pretty-print in devtools
+*   level: 'debug',
+* });
+* ```
+*/
 const LEVEL_ORDER = {
 	verbose: 0,
 	debug: 1,
@@ -364,7 +658,7 @@ function validateRemoteUrl(raw) {
 	try {
 		parsed = new URL(raw);
 	} catch {
-		throw new TypeError(`BrowserRemoteTransport: invalid url "${raw}"`);
+		throw new TypeError(`BrowserRemoteTransport: invalid url [redacted]`);
 	}
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new TypeError(`BrowserRemoteTransport: url scheme "${parsed.protocol}" is not allowed; use http: or https:`);
 	return raw;
@@ -377,8 +671,33 @@ function validateRemoteUrl(raw) {
 function byteLength(s) {
 	return new TextEncoder().encode(s).length;
 }
+const FAILURE_REPORT_INTERVAL_MS = 6e4;
+/**
+* Error name/code, HTTP status and host only. The error message is never
+* included: runtimes embed request URLs (absolute or relative) and header
+* values in it.
+*/
+function describeFailure(error, url) {
+	let host = "relative endpoint";
+	try {
+		host = `host ${new URL(url).host}`;
+	} catch {}
+	const e = error;
+	const parts = [];
+	if (e && typeof e.name === "string") parts.push(e.name);
+	if (e && typeof e.code === "string") parts.push(e.code);
+	if (e && typeof e.status === "number") parts.push(`HTTP ${e.status}`);
+	parts.push(host);
+	return parts.join(" ");
+}
+/** True only in a real browser page, where console noise reaches end users. */
+function isBrowserPage() {
+	const g = globalThis;
+	return typeof g["window"] !== "undefined" && typeof g["document"] !== "undefined";
+}
 function isKeepaliveError(error) {
-	return error instanceof Error && /keepalive/i.test(error.message);
+	const message = error === null || error === void 0 ? void 0 : error.message;
+	return typeof message === "string" && /keepalive/i.test(message);
 }
 /**
 * Browser transport that batches log entries and sends them to a remote
@@ -405,12 +724,17 @@ var BrowserRemoteTransport = class {
 		this.failedFlushCount = 0;
 		this.timer = null;
 		this.droppedEntries = 0;
+		this.reporting = false;
+		this.failureReported = false;
+		this.silent = options.silent ?? isBrowserPage();
+		this.onError = options.onError;
 		this.url = validateRemoteUrl(options.url);
 		this.headers = options.headers ?? {};
 		this.batchSize = options.batchSize ?? 100;
 		this.flushIntervalMs = options.flushIntervalMs ?? 5e3;
 		this.maxBufferSize = options.maxBufferSize ?? 1e3;
 		if (options.level !== void 0) this.level = options.level;
+		protectSecrets(this, ["headers", "url"]);
 		this.scheduleFlush();
 	}
 	/**
@@ -421,15 +745,23 @@ var BrowserRemoteTransport = class {
 	get dropped() {
 		return this.droppedEntries;
 	}
-	/** Number of flush attempts that failed with a network error and were re-buffered. */
+	/** Number of flush attempts that failed (network error or non-OK HTTP status). */
 	get failedFlushes() {
 		return this.failedFlushCount;
 	}
-	/** The most recent network error from a failed flush, if any. */
+	/**
+	* The most recent failure from a flush, if any: the raw fetch error (which on
+	* some runtimes embeds the request URL, so do not log it blindly) or an
+	* `Error` carrying only the HTTP status.
+	*/
 	get lastError() {
 		return this.lastFlushError;
 	}
 	write(entry) {
+		if (this.reporting) {
+			this.droppedEntries += 1;
+			return;
+		}
 		this.batch.push(entry);
 		while (this.batch.length > this.maxBufferSize) {
 			this.batch.shift();
@@ -460,10 +792,15 @@ var BrowserRemoteTransport = class {
 				}
 			}
 			if (!res.ok) {
-				if (res.status >= 500 || res.status === 429) this.batch.unshift(...entries);
-				else this.droppedEntries += entries.length;
+				const failure = Object.assign(/* @__PURE__ */ new Error(`HTTP ${res.status}`), { status: res.status });
+				if (res.status >= 500 || res.status === 429) this.recordFailure(entries, failure);
+				else {
+					this.droppedEntries += entries.length;
+					this.recordFailure([], failure);
+				}
 				return;
 			}
+			this.reportRecovery();
 		}
 	}
 	send(body, keepalive) {
@@ -481,6 +818,34 @@ var BrowserRemoteTransport = class {
 		this.batch.unshift(...entries);
 		this.failedFlushCount += 1;
 		this.lastFlushError = error;
+		const now = Date.now();
+		const shouldReport = this.lastReportAt === void 0 || now - this.lastReportAt >= FAILURE_REPORT_INTERVAL_MS;
+		this.guarded(() => {
+			if (this.onError) try {
+				this.onError(error);
+			} catch {}
+			if (shouldReport && !this.silent) {
+				this.lastReportAt = now;
+				this.failureReported = true;
+				internalError(`BrowserRemoteTransport flush failed (${describeFailure(error, this.url)})`);
+			}
+		});
+	}
+	reportRecovery() {
+		if (!this.failureReported) return;
+		this.failureReported = false;
+		const now = Date.now();
+		if (this.lastRecoveryAt !== void 0 && now - this.lastRecoveryAt < FAILURE_REPORT_INTERVAL_MS) return;
+		this.lastRecoveryAt = now;
+		this.guarded(() => internalLog("BrowserRemoteTransport delivery recovered"));
+	}
+	guarded(fn) {
+		this.reporting = true;
+		try {
+			fn();
+		} finally {
+			this.reporting = false;
+		}
 	}
 	scheduleFlush() {
 		if (this.flushIntervalMs <= 0) return;
@@ -517,7 +882,10 @@ var BrowserLogger = class BrowserLogger {
 			context: config.context
 		};
 		if (config.silent) this.transports = [];
-		else this.transports = [new BrowserConsoleTransport({ json: this.config.json }), ...config.transports ?? []];
+		else {
+			const builtIn = new BrowserConsoleTransport({ json: this.config.json });
+			this.transports = [builtIn, ...config.transports ?? []];
+		}
 	}
 	verbose(message, payload) {
 		this.emit("verbose", message, payload);
@@ -605,8 +973,6 @@ function createBrowserLogger(config) {
 * ```
 */
 const browserLogger = new BrowserLogger({ appName: "App" });
-
-//#endregion
 exports.BrowserConsoleTransport = BrowserConsoleTransport;
 exports.BrowserLogger = BrowserLogger;
 exports.BrowserRemoteTransport = BrowserRemoteTransport;
@@ -618,4 +984,5 @@ exports.disableOtelBridge = disableOtelBridge;
 exports.getActiveOtelContext = getActiveOtelContext;
 exports.getOtelMetaFields = getOtelMetaFields;
 exports.initOtelBridge = initOtelBridge;
+
 //# sourceMappingURL=browser.js.map