@x12i/logxer 4.0.0

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * logxer - TypeScript Type Definitions
+ *
+ * This file contains all TypeScript interfaces and types for the logxer package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/utils/debug-config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Debug Configuration Loader
+ *
+ * Loads logxer-debug.json configuration file from project root
+ * for runtime log filtering based on identity and application name.
+ */
+import type { DebugScopingConfig } from '../types';
+/**
+ * Load logxer-debug.json configuration from project root
+ * Searches up the directory tree from process.cwd() to find the file
+ *
+ * @returns DebugScopingConfig if found and valid, null otherwise
+ */
+export declare function loadDebugConfig(): DebugScopingConfig | null;
+/**
+ * Reset the cached debug config (useful for testing)
+ */
+export declare function resetDebugConfigCache(): void;
+//# sourceMappingURL=debug-config.d.ts.map

package/dist/utils/debug-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-config.d.ts","sourceRoot":"","sources":["../../src/utils/debug-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAInD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,kBAAkB,GAAG,IAAI,CA6H3D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/utils/debug-config.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Debug Configuration Loader
+ *
+ * Loads logxer-debug.json configuration file from project root
+ * for runtime log filtering based on identity and application name.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDebugConfig = loadDebugConfig;
+exports.resetDebugConfigCache = resetDebugConfigCache;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+let cachedConfig = undefined;
+/**
+ * Load logxer-debug.json configuration from project root
+ * Searches up the directory tree from process.cwd() to find the file
+ *
+ * @returns DebugScopingConfig if found and valid, null otherwise
+ */
+function loadDebugConfig() {
+    // Return cached result if available
+    if (cachedConfig !== undefined) {
+        return cachedConfig;
+    }
+    try {
+        // Start from process.cwd() and search up for logxer-debug.json
+        let currentDir = process.cwd();
+        const rootPath = path.parse(currentDir).root;
+        while (currentDir !== rootPath) {
+            const configPath = path.join(currentDir, 'logxer-debug.json');
+            if (fs.existsSync(configPath)) {
+                try {
+                    const content = fs.readFileSync(configPath, 'utf8');
+                    const config = JSON.parse(content);
+                    // Validate structure
+                    if (config && config.scoping) {
+                        // Validate status
+                        if (config.scoping.status !== 'enabled' && config.scoping.status !== 'disabled') {
+                            console.warn('[logxer] Invalid logxer-debug.json: scoping.status must be "enabled" or "disabled"');
+                            cachedConfig = null;
+                            return null;
+                        }
+                        // Ensure arrays are arrays
+                        if (config.scoping.filterIdentities && !Array.isArray(config.scoping.filterIdentities)) {
+                            console.warn('[logxer] Invalid logxer-debug.json: filterIdentities must be an array');
+                            cachedConfig = null;
+                            return null;
+                        }
+                        if (config.scoping.filteredApplications && !Array.isArray(config.scoping.filteredApplications)) {
+                            console.warn('[logxer] Invalid logxer-debug.json: filteredApplications must be an array');
+                            cachedConfig = null;
+                            return null;
+                        }
+                        // Validate between array if present
+                        if (config.scoping.between !== undefined) {
+                            if (!Array.isArray(config.scoping.between)) {
+                                console.warn('[logxer] Invalid logxer-debug.json: between must be an array');
+                                cachedConfig = null;
+                                return null;
+                            }
+                            // Validate each between rule
+                            for (let i = 0; i < config.scoping.between.length; i++) {
+                                const rule = config.scoping.between[i];
+                                if (!rule || typeof rule !== 'object') {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}] must be an object`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                                // Validate action
+                                if (rule.action !== 'include' && rule.action !== 'exclude') {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}].action must be "include" or "exclude"`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                                // Validate optional boolean fields
+                                if (rule.exactMatch !== undefined && typeof rule.exactMatch !== 'boolean') {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}].exactMatch must be a boolean`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                                if (rule.searchLog !== undefined && typeof rule.searchLog !== 'boolean') {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}].searchLog must be a boolean`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                                // Validate startIdentities and endIdentities are arrays
+                                if (!Array.isArray(rule.startIdentities)) {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}].startIdentities must be an array`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                                if (!Array.isArray(rule.endIdentities)) {
+                                    console.warn(`[logxer] Invalid logxer-debug.json: between[${i}].endIdentities must be an array`);
+                                    cachedConfig = null;
+                                    return null;
+                                }
+                            }
+                        }
+                        // Cache and return valid config
+                        cachedConfig = config;
+                        return config;
+                    }
+                    else {
+                        console.warn('[logxer] Invalid logxer-debug.json: missing "scoping" field');
+                        cachedConfig = null;
+                        return null;
+                    }
+                }
+                catch (parseError) {
+                    console.warn('[logxer] Failed to parse logxer-debug.json:', parseError);
+                    cachedConfig = null;
+                    return null;
+                }
+            }
+            // Move up one directory
+            const parentDir = path.dirname(currentDir);
+            if (parentDir === currentDir) {
+                // Reached root, stop searching
+                break;
+            }
+            currentDir = parentDir;
+        }
+        // File not found - cache null result
+        cachedConfig = null;
+        return null;
+    }
+    catch (error) {
+        // If any error occurs, return null and cache it
+        cachedConfig = null;
+        return null;
+    }
+}
+/**
+ * Reset the cached debug config (useful for testing)
+ */
+function resetDebugConfigCache() {
+    cachedConfig = undefined;
+}
+//# sourceMappingURL=debug-config.js.map

package/dist/utils/debug-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-config.js","sourceRoot":"","sources":["../../src/utils/debug-config.ts"],"names":[],"mappings":"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"}

package/dist/utils/package-logs-level.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Package-level log threshold via `<packagePrefix>_LOGS_LEVEL` (canonical contract).
+ * See docs/package-usage.md in this package.
+ */
+import type { LogLevel } from '../types';
+/**
+ * Environment variable name for the canonical package log threshold: `<PREFIX>_LOGS_LEVEL`.
+ */
+export declare function packageLogsLevelEnvKey(envPrefix: string): string;
+/**
+ * Legacy env var: `<PREFIX>_LOG_LEVEL` (still supported when `_LOGS_LEVEL` is unset).
+ */
+export declare function legacyPackageLogLevelEnvKey(envPrefix: string): string;
+/**
+ * Parse a single value (case-insensitive). Unknown values are treated as disabled (off).
+ * Empty or whitespace-only string is treated as off.
+ */
+export declare function parsePackageLogsLevelString(raw: string | undefined): {
+    packageLogsDisabled: boolean;
+    logLevel?: LogLevel;
+};
+export interface ResolvePackageLogsLevelOptions {
+    envPrefix: string;
+    /** Programmatic override — wins over environment. */
+    userLogLevel?: LogLevel;
+    /** For tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolve package log threshold for a logger instance.
+ *
+ * Precedence: `userLogLevel` → `<PREFIX>_LOGS_LEVEL` (if set in env) → `<PREFIX>_LOG_LEVEL` (legacy, if set) → **`warn`** (neither key set in env).
+ *
+ * When silent, `logLevel` in the result is `'error'` as a placeholder for internal storage; emission is gated by `packageLogsDisabled`.
+ */
+export declare function resolvePackageLogsLevel(options: ResolvePackageLogsLevelOptions): {
+    packageLogsDisabled: boolean;
+    logLevel: LogLevel;
+};
+//# sourceMappingURL=package-logs-level.d.ts.map

package/dist/utils/package-logs-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-logs-level.d.ts","sourceRoot":"","sources":["../../src/utils/package-logs-level.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAYzC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG;IACpE,mBAAmB,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAaA;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,YAAY,CAAC,EAAE,QAAQ,CAAC;IACxB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC;IAAE,mBAAmB,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CA2BtD"}

package/dist/utils/package-logs-level.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Package-level log threshold via `<packagePrefix>_LOGS_LEVEL` (canonical contract).
+ * See docs/package-usage.md in this package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageLogsLevelEnvKey = packageLogsLevelEnvKey;
+exports.legacyPackageLogLevelEnvKey = legacyPackageLogLevelEnvKey;
+exports.parsePackageLogsLevelString = parsePackageLogsLevelString;
+exports.resolvePackageLogsLevel = resolvePackageLogsLevel;
+const OFF_SYNONYMS = new Set(['off', 'none', 'silent']);
+const LEVEL_ALIASES = {
+    verbose: 'verbose',
+    debug: 'debug',
+    info: 'info',
+    warn: 'warn',
+    error: 'error'
+};
+/**
+ * Environment variable name for the canonical package log threshold: `<PREFIX>_LOGS_LEVEL`.
+ */
+function packageLogsLevelEnvKey(envPrefix) {
+    return `${envPrefix}_LOGS_LEVEL`;
+}
+/**
+ * Legacy env var: `<PREFIX>_LOG_LEVEL` (still supported when `_LOGS_LEVEL` is unset).
+ */
+function legacyPackageLogLevelEnvKey(envPrefix) {
+    return `${envPrefix}_LOG_LEVEL`;
+}
+/**
+ * Parse a single value (case-insensitive). Unknown values are treated as disabled (off).
+ * Empty or whitespace-only string is treated as off.
+ */
+function parsePackageLogsLevelString(raw) {
+    if (raw === undefined) {
+        return { packageLogsDisabled: true };
+    }
+    const n = raw.trim().toLowerCase();
+    if (n.length === 0 || OFF_SYNONYMS.has(n)) {
+        return { packageLogsDisabled: true };
+    }
+    const level = LEVEL_ALIASES[n];
+    if (level) {
+        return { packageLogsDisabled: false, logLevel: level };
+    }
+    return { packageLogsDisabled: true };
+}
+/**
+ * Resolve package log threshold for a logger instance.
+ *
+ * Precedence: `userLogLevel` → `<PREFIX>_LOGS_LEVEL` (if set in env) → `<PREFIX>_LOG_LEVEL` (legacy, if set) → **`warn`** (neither key set in env).
+ *
+ * When silent, `logLevel` in the result is `'error'` as a placeholder for internal storage; emission is gated by `packageLogsDisabled`.
+ */
+function resolvePackageLogsLevel(options) {
+    const { envPrefix, userLogLevel, env = process.env } = options;
+    if (userLogLevel !== undefined) {
+        return { packageLogsDisabled: false, logLevel: userLogLevel };
+    }
+    const logsKey = packageLogsLevelEnvKey(envPrefix);
+    const legacyKey = legacyPackageLogLevelEnvKey(envPrefix);
+    if (Object.prototype.hasOwnProperty.call(env, logsKey)) {
+        const parsed = parsePackageLogsLevelString(env[logsKey]);
+        if (parsed.packageLogsDisabled || !parsed.logLevel) {
+            return { packageLogsDisabled: true, logLevel: 'error' };
+        }
+        return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+    }
+    if (Object.prototype.hasOwnProperty.call(env, legacyKey)) {
+        const parsed = parsePackageLogsLevelString(env[legacyKey]);
+        if (parsed.packageLogsDisabled || !parsed.logLevel) {
+            return { packageLogsDisabled: true, logLevel: 'error' };
+        }
+        return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+    }
+    return { packageLogsDisabled: false, logLevel: 'warn' };
+}
+//# sourceMappingURL=package-logs-level.js.map

package/dist/utils/package-logs-level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-logs-level.js","sourceRoot":"","sources":["../../src/utils/package-logs-level.ts"],"names":[],"mappings":"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"}

package/docs/package-usage.md

@@ -0,0 +1,155 @@
+# Package logging via `.env` (logs-gateway)
+
+**Canonical contract** for npm packages that emit diagnostics through **[logs-gateway](https://www.npmjs.com/package/logs-gateway)**.
+
+- **Per package:** only **logs level** is configured with that package’s **package prefix** on the variable name.
+- **Cross-cutting (once per app / process):** where logs go (console, file, unified, …) and **format** are **not** repeated per package—they are shared for the whole host. Downstream wiring implements that split; this doc defines the **package-level** part only.
+
+**Default when neither `<packagePrefix>_LOGS_LEVEL` nor `<packagePrefix>_LOG_LEVEL` is set in the environment:** **`warn`** (emit **`warn`** and **`error`** only). To silence a package, set **`off`** (or synonyms **`none`** / **`silent`**). To see **`info`**, **`debug`**, or **`verbose`**, raise the level explicitly.
+
+**Package prefix** is the short token a package owns for its **single** logs-gateway-related variable in this contract (illustrative examples: **`MY_LIB`**, **`EXAMPLE_SVC`**). Each package documents its own prefix in its README.
+
+**logs-gateway** implements this contract inside `createLogger` / `LogsGateway`. It also exposes **`resolvePackageLogsLevel`**, **`parsePackageLogsLevelString`**, **`packageLogsLevelEnvKey`**, and **`legacyPackageLogLevelEnvKey`** for the same rules outside the gateway if needed.
+
+---
+
+## For package authors — how to implement
+
+1. **Depend on** `logs-gateway` (normal `dependencies` for a library that logs).
+2. **Choose a stable prefix** (short acronym, not the full scoped npm name). Use the same string for **`envPrefix`** and for documenting the env var (e.g. **`MY_LIB`** → **`MY_LIB_LOGS_LEVEL`**).
+3. **Create one logger** (or one per logical surface, each with its own prefix if you truly need separate toggles—usually one prefix per package):
+
+   ```typescript
+   import { createLogger } from 'logs-gateway';
+
+   export const logger = createLogger({
+     packageName: 'MyLib',        // label in log lines
+     envPrefix: 'MY_LIB',         // reads MY_LIB_LOGS_LEVEL / MY_LIB_LOG_LEVEL
+     debugNamespace: 'my-lib'     // optional: DEBUG namespace
+   });
+   ```
+
+4. **Emit using gateway levels** — `logger.error`, `logger.warn`, `logger.info`, `logger.debug`, `logger.verbose`. What actually appears is filtered by the resolved **minimum level** (see table below).
+5. **Document for consumers** in your README: the prefix, the exact key **`<prefix>_LOGS_LEVEL`**, allowed values, and that **default is `warn`** if the variable is not set (and legacy **`_LOG_LEVEL`** is not set).
+6. **Optional programmatic default** — pass **`logLevel`** in the second argument to **`createLogger`** only when you need a non-env default (it overrides env for that instance).
+
+You do **not** need to read **`process.env`** for the level yourself if you use **`createLogger`** / **`LogsGateway`**; resolution is built in.
+
+---
+
+## For apps and operators — downstream (different levels per package)
+
+Integrators tune **verbosity per dependency** by setting **one variable per package prefix** in **`.env`** (or the host’s secret/config store). That flows **downstream** into each library’s logger without code changes:
+
+```dotenv
+# Quieter third-party package; louder in-house library
+EXAMPLE_GATEWAY_LOGS_LEVEL=error
+MY_LIB_LOGS_LEVEL=info
+
+# Turn one package off entirely
+OTHER_PKG_LOGS_LEVEL=off
+```
+
+Cross-cutting knobs (**where** logs go, **format**, file paths, unified sink, etc.) are configured **once** for the host (see logs-gateway README), not duplicated per package prefix.
+
+---
+
+## 1. Package-level variable (only): `<packagePrefix>_LOGS_LEVEL`
+
+```dotenv
+MY_LIB_LOGS_LEVEL=warn
+```
+
+Pattern: **`<packagePrefix>_LOGS_LEVEL`**.
+
+- If **both** **`<packagePrefix>_LOGS_LEVEL`** and **`<packagePrefix>_LOG_LEVEL`** are **absent** from the environment, **logs-gateway** uses **`warn`** as the effective threshold.
+- **`off`** (or **`none`** / **`silent`**) means that package does **not** emit diagnostic logs (regardless of cross-cutting sink configuration).
+
+No other **package-prefixed** `.env` keys are part of this contract—**not** `<packagePrefix>_LOG_TO_CONSOLE`, `<packagePrefix>_LOG_TO_FILE`, `<packagePrefix>_LOG_FORMAT`, etc. Those belong to **cross-cutting** configuration.
+
+---
+
+## 2. Allowed values for `<packagePrefix>_LOGS_LEVEL`
+
+| Value | Meaning |
+|--------|---------|
+| **`off`** | Package diagnostics disabled (`none` / `silent` are synonyms). |
+| **`error`** | Emit **`error`** only. |
+| **`warn`** | Emit **`warn`** and **`error`**. |
+| **`info`** | Emit **`info`** and above. |
+| **`debug`** | Emit **`debug`** and above. |
+| **`verbose`** | Most verbose. |
+
+**Default when the env keys are not set:** **`warn`** (see §1).
+
+Case-insensitive values are recommended; **logs-gateway** normalizes case when parsing.
+
+Unknown values are treated as **`off`** (silent) in **logs-gateway**.
+
+**Precedence in env:** if **both** **`_LOGS_LEVEL`** and **`_LOG_LEVEL`** are set, **`_LOGS_LEVEL`** wins. If only **`_LOG_LEVEL`** is set (legacy), it is used the same way as **`_LOGS_LEVEL`**.
+
+---
+
+## 3. Cross-cutting configuration (shared across packages)
+
+**Console, file, log file path, text/json/table format, unified logger, and similar** are **application- or host-level** concerns. They apply **once** to the process, not once per library prefix.
+
+- A package with **`_LOGS_LEVEL=off`** must not emit diagnostics; host settings do not override that.
+- When the package level is not **`off`**, lines use the **same** shared sinks and format as other packages that are allowed to emit.
+
+Exact host variable names are in **logs-gateway** and application docs; they are not **`<packagePrefix>_…`** patterns in this contract.
+
+---
+
+## 4. Choosing the package prefix
+
+- Prefer a **stable acronym or short name**, not the full scoped npm name.
+- Example (illustrative): **`@acme/example-lib`** might use **`EXAMPLE_LIB`**—pick one and keep it.
+
+Document the prefix and **`<prefix>_LOGS_LEVEL`** in the package README.
+
+---
+
+## 5. Example `.env` (placeholders)
+
+**Per package (levels only):**
+
+```dotenv
+MY_LIB_LOGS_LEVEL=warn
+EXAMPLE_GATEWAY_LOGS_LEVEL=info
+
+# Silence or debug one layer
+OTHER_PKG_LOGS_LEVEL=off
+MY_LIB_LOGS_LEVEL=debug
+```
+
+**Cross-cutting (illustrative—host / logs-gateway global keys):**
+
+```dotenv
+# LOG_TO_CONSOLE=true
+# LOG_FORMAT=json
+```
+
+---
+
+## 6. Interaction with process-wide `DEBUG`
+
+Some stacks use **`DEBUG`** (comma-separated namespaces). That is separate from this contract:
+
+- **`_LOGS_LEVEL=off`** stays authoritative: the package stays silent in **logs-gateway**.
+- **`DEBUG`** can still allow **`verbose`** / **`debug`** lines **only when the package is not silent** (`packageLogsDisabled` is false). See **logs-gateway** README for details.
+
+---
+
+## 7. Summary
+
+| Layer | What is configured |
+|--------|-------------------|
+| **Per package** | **Only** `<packagePrefix>_LOGS_LEVEL` (default **`warn`** when both `_LOGS_LEVEL` and `_LOG_LEVEL` are unset in the environment) |
+| **Cross-cutting** | Console, file, format, unified sink, etc.—**once** for the app / process |
+
+---
+
+## 8. Migration note
+
+If you relied on older behavior where **no** env vars implied **silent** output, set **`{PREFIX}_LOGS_LEVEL=off`** explicitly, or **`{PREFIX}_LOG_LEVEL=off`** if you only use the legacy key.

package/docs/package.md

@@ -0,0 +1,48 @@
+**don’t use CommonJS** 🙂
+
+### Use **ESM only**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
+  }
+}
+```
+
+### Why this is the *right* choice **now**
+
+* **Native ESM everywhere** (Node 18/20+, Bun, Deno, modern bundlers)
+* Clean `import` / `export`, no interop hacks
+* Future-proof for:
+
+  * tree-shaking
+  * edge / workers
+  * package `exports`
+* Matches how *new* libraries are written in 2025–2026
+
+### What *not* to do
+
+* ❌ `"module": "commonjs"` → legacy, friction, dead-end
+* ❌ `"module": "ES2020"` without `NodeNext` → subtle resolution bugs with Node ESM
+
+### Minimal `package.json` you should use
+
+```json
+{
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  }
+}
+```
+
+### One important rule (don’t trip on this)
+
+* Use **explicit file extensions** in imports:
+
+  ```ts
+  import { x } from "./utils.js";
+  ```

package/docs/upgrade-for-package-authors.md

@@ -0,0 +1,85 @@
+# Upgrading `logs-gateway` — instructions for package owners
+
+Share this note with maintainers of libraries that depend on **logs-gateway** when they bump to **≥ 3.5.x** (or your current release line that includes the package-level logging contract).
+
+---
+
+## 1. Bump the dependency
+
+```bash
+npm install logs-gateway@^3.6.0
+```
+
+(or whatever minimum version your release notes specify)
+
+No code change is **required** if you already use `createLogger({ packageName, envPrefix, ... })` — the gateway reads the new env rules automatically.
+
+---
+
+## 2. Per-package log level (what changed)
+
+| Topic | Detail |
+|--------|--------|
+| **Canonical env var** | **`<PREFIX>_LOGS_LEVEL`** — replace `<PREFIX>` with your **`envPrefix`** (e.g. `MY_LIB` → `MY_LIB_LOGS_LEVEL`). |
+| **Legacy** | **`<PREFIX>_LOG_LEVEL`** still works **only if** `*_LOGS_LEVEL` is **not** set in the environment. |
+| **Default** | If **both** `*_LOGS_LEVEL` and `*_LOG_LEVEL` are **unset**, the effective level is **`warn`** (warn + error only). **Not** `info` and **not** silent. |
+| **Silence** | Set **`off`**, **`none`**, or **`silent`** to disable that package’s diagnostics. |
+| **Values** | `off` \| `none` \| `silent` \| `error` \| `warn` \| `info` \| `debug` \| `verbose` (case-insensitive). |
+
+**You still choose** a stable **`envPrefix`** once and document it in your README. logs-gateway does **not** infer it from the npm package name.
+
+---
+
+## 3. What to document for your users
+
+Add to your README (or link to this section):
+
+1. **One line** naming your prefix, e.g. “Log level env: **`MY_LIB_LOGS_LEVEL`**.”
+2. **Default** when unset: **`warn`** (unless they set legacy `MY_LIB_LOG_LEVEL`).
+3. **Example** to raise verbosity: `MY_LIB_LOGS_LEVEL=info` or `debug`.
+4. **Example** to silence: `MY_LIB_LOGS_LEVEL=off`.
+
+Cross-cutting options (console, file, format, unified sink) stay **host/app** configuration — see **logs-gateway** README — not duplicated per library prefix.
+
+---
+
+## 4. Optional: use the same rules outside `LogsGateway`
+
+If you need the same resolution in code (e.g. custom bootstrap), import:
+
+```typescript
+import {
+  resolvePackageLogsLevel,
+  parsePackageLogsLevelString,
+  packageLogsLevelEnvKey,
+  legacyPackageLogLevelEnvKey
+} from 'logs-gateway';
+```
+
+- **`resolvePackageLogsLevel({ envPrefix, userLogLevel?, env? })`** — same precedence as `createLogger`.
+- **`parsePackageLogsLevelString(raw)`** — parse a single value string.
+- **`packageLogsLevelEnvKey(prefix)`** / **`legacyPackageLogLevelEnvKey(prefix)`** — build env key names.
+
+---
+
+## 5. Behavior to watch after upgrade
+
+| Situation | What to expect |
+|-----------|----------------|
+| **No env vars** for level | More **`warn`** / **`error`** line**s** than before if you relied on **silent** default; set **`PREFIX_LOGS_LEVEL=off`** to silence. |
+| **`DEBUG` env** | Still elevates **`verbose`** / **`debug`** only when the package is **not** fully silent (`off`). |
+| **`getConfig()`** | Includes **`packageLogsDisabled`** when the effective level is **`off`**. |
+
+---
+
+## 6. Full contract
+
+See **`docs/package-usage.md`** in the **logs-gateway** package (also on npm).
+
+---
+
+## Short blurb (copy-paste for your changelog)
+
+> Upgraded **logs-gateway**. Per-package verbosity is controlled with **`YOUR_PREFIX_LOGS_LEVEL`** (canonical); legacy **`YOUR_PREFIX_LOG_LEVEL`** remains if the new var is unset. Default when both are unset is **`warn`**. Set **`YOUR_PREFIX_LOGS_LEVEL=off`** to disable. See [logs-gateway `docs/package-usage.md`](https://github.com/nx-intelligence/logs-gateway/blob/main/docs/package-usage.md) for details.
+
+Replace **`YOUR_PREFIX`** with your documented prefix.