hazo_logs 1.1.0 → 2.0.1

package/README.md

@@ -5,12 +5,88 @@ A Winston-based logging library for Node.js/Next.js applications with a built-in
 [![npm version](https://img.shields.io/npm/v/hazo_logs.svg)](https://www.npmjs.com/package/hazo_logs)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
+## Log Level Convention
+
+hazo_logs uses a 5-level system (from design spec D-015). Each level has a defined purpose — use the narrowest one that fits.
+
+| Level | When to use |
+|-------|-------------|
+| `TRACE` | High-frequency operational noise: polling ticks, cache hits, ping responses. Off in production. |
+| `DEBUG` | Operational detail useful when actively debugging a problem. Off in production. |
+| `INFO` | State changes and user-facing events (login, job started, order placed). Default level in dev. |
+| `WARN` | Recoverable problems: rate-limited, retrying, degraded-mode fallback. Default level in production. |
+| `ERROR` | Unrecovered failures that require attention: unhandled exception, data loss, external service down. |
+
+### Default levels
+
+| Environment | Default level |
+|-------------|--------------|
+| `development` / `test` (`NODE_ENV`) | `info` |
+| `production` / `staging` (`HAZO_ENV` or `NODE_ENV`) | `warn` |
+
+The resolver checks `HAZO_ENV` first, then `NODE_ENV`, then falls back to `development`.
+
+### Per-namespace overrides (INI config)
+
+Fine-tune the level for a specific package or sub-namespace in `config/hazo_logs_config.ini`:
+
+```ini
+[log.overrides]
+; Package-level — matches hazo_chat and any hazo_chat/* sub-namespace
+hazo_chat = warn
+
+; Sub-namespace — more specific, takes precedence over the package-level override
+hazo_chat/poll = error
+
+; Prefix match — matches any hazo_files/* sub-namespace
+hazo_files/ = debug
+```
+
+Precedence (highest wins): exact match > prefix match > package-level > global default.
+
+You can also use environment variables to override INI config at runtime:
+
+```bash
+HAZO_LOGS_LOG_OVERRIDES_hazo_files=debug node server.js
+```
+
+### Smart logging helpers
+
+Use these instead of raw `log.info` loops to reduce noise without losing signal:
+
+**`log.heartbeat(name, { status, ...fields }, opts?)`**
+Emits only on state change. Silent on repeated same-status calls. Use for "is it still working?" checks on polled resources (DB connectivity, external API, queue depth).
+
+```typescript
+// Emits once when connected, once on disconnect, once when it reconnects
+log.heartbeat('db.primary', { status: connected ? 'ok' : 'down', latencyMs });
+```
+
+**`log.sampled(level, msg, fields?, { sample })`**
+Emits with the given probability. Default sample rate is 0.1 (10%). Use for high-frequency paths where you want occasional visibility without flooding logs.
+
+```typescript
+// Logs roughly 1 in 10 cache hits
+log.sampled('debug', 'cache.hit', { key }, { sample: 0.1 });
+```
+
+**`log.dedupe(level, msg, fields?, { window, key? })`**
+Collapses identical-keyed messages within a time window. The first occurrence emits immediately; at window end, if more than one occurred, emits a summary `"msg (×N over Xs)"`. Use when the same warning fires rapidly (e.g. validation errors on bulk import).
+
+```typescript
+// First occurrence emits; subsequent in the same minute are collapsed
+log.dedupe('warn', 'validation.failed', { field }, { window: '1m' });
+```
+
 ## Features
 
 - **Structured Logging**: Winston wrapper with singleton pattern for consistent logging across your app
 - **Package Tagging**: Automatically tag logs by package/module name
 - **Daily Rotation**: Automatic log file rotation with configurable retention
 - **Session Tracking**: Track logs across async operations with sessionId and reference
+- **Fatal Level**: `logger.fatal()` for process-critical events, above `error` in severity
+- **Context Fields**: Attach `scope` (dotted operation path) and `userId` to all logs via ALS context
+- **Error Handling Surface**: `withErrorHandler`, `installGlobalErrorHandlers`, `registerAlertTrigger`, `<ErrorBoundary />`, `useErrorReporter` — structured error capture with correlationId tracking
 - **Built-in UI**: React-based log viewer with filtering, sorting, and pagination
 - **Zero Config**: Works out of the box with sensible defaults
 - **Minimal Integration**: Add log viewer to your app with just 2 files (~6 lines of code)
@@ -249,22 +325,27 @@ import { createLogger, runWithLogContext } from 'hazo_logs/server';
 
 const logger = createLogger('auth');
 
-async function handleRequest(req) {
+async function handle_request(req) {
   await runWithLogContext(
     {
       sessionId: req.sessionId,
       reference: `user-${req.userId}`,
       depth: 0,
+      scope: 'auth.login',          // Fine-grained operation scope (dotted notation)
+      userId: req.userId,            // User ID propagated to all log entries
     },
     async () => {
-      logger.info('Request started'); // Automatically includes sessionId and reference
-      await processRequest(req);
+      logger.info('Request started'); // Automatically includes all context fields
+      await process_request(req);
       logger.info('Request completed');
     }
   );
 }
 ```
 
+Available context fields: `sessionId`, `reference`, `depth`, `scope`, `userId`. All fields present in the ALS context are automatically written to every `LogEntry` produced within the callback.
+```
+
 ### Embedded Log Viewer
 
 Use the log viewer as a sidebar component:
@@ -450,6 +531,7 @@ logger.info('Hello world');
 
 ```typescript
 interface Logger {
+  fatal(message: string, data?: Record<string, unknown>): void;
   error(message: string, data?: Record<string, unknown>): void;
   warn(message: string, data?: Record<string, unknown>): void;
   info(message: string, data?: Record<string, unknown>): void;
@@ -501,6 +583,52 @@ const logger = createClientLogger({
 });
 ```
 
+#### `ErrorBoundary`
+
+React class component that catches render errors, generates a `correlationId`, and logs to the server via the client logger pipeline. The `fallback` render prop receives `{ error, correlationId, retry }`.
+
+```tsx
+import { ErrorBoundary } from 'hazo_logs/ui';
+
+<ErrorBoundary
+  fallback={({ error, correlationId, retry }) => (
+    <div>
+      <p>Something went wrong. Reference: {correlationId}</p>
+      <button onClick={retry}>Retry</button>
+    </div>
+  )}
+>
+  <MyComponent />
+</ErrorBoundary>
+```
+
+Props: `fallback` (required), `onError?: (error, correlationId) => void`, `apiBasePath?: string`, `packageName?: string`.
+
+**React 19 + Next.js 16 note:** Wrap state changes that may cause throws inside `startTransition()` to prevent the dev overlay from covering the error fallback. React 19 dev mode re-reports caught errors globally; transitions suppress this.
+
+#### `useErrorReporter(options?)`
+
+React hook for manual error reporting. Each method returns a correlationId string. Auto-attaches `route_path` (window.location.pathname) and `user_agent` to every entry.
+
+```tsx
+import { useErrorReporter } from 'hazo_logs/ui';
+
+function MyComponent() {
+  const { reportError } = useErrorReporter({ userId: session?.user?.id });
+
+  const handle_action = async () => {
+    try {
+      await risky_operation();
+    } catch (err) {
+      const id = reportError(err, { component: 'MyComponent' });
+      show_toast(`Something went wrong. Reference: ${id}`);
+    }
+  };
+}
+```
+
+Methods: `reportError(error, context?)`, `reportWarning(message, context?)`, `reportInfo(message, context?)`. Pass `options.userId` to attach `user_id` to all entries — no `hazo_auth` import required.
+
 #### `LogViewerPage`
 
 Main log viewer component.
@@ -562,6 +690,70 @@ const authHandler = withLogAuth(handler, async (request) => {
 });
 ```
 
+### Error Handling Surface (`hazo_logs/server`)
+
+#### `withErrorHandler(handler)`
+
+Wraps a Next.js App Router handler with structured error handling. Generates a `correlationId` (UUID), sets `X-Correlation-Id` on error responses, catches `HandledError` duck-typed throws returning structured JSON with the correct HTTP status, and catches generic `Error` logging at `fatal` and returning 500 (internal message never reaches the client).
+
+```typescript
+import { withErrorHandler } from 'hazo_logs/server';
+
+export const GET = withErrorHandler(async (req: Request) => {
+  // Throw HandledError for structured 4xx/5xx responses:
+  throw { code: 'not_found', statusCode: 404, userMessage: 'Resource not found' };
+  // Throw Error for 500 — message never reaches client:
+  throw new Error('db connection failed');
+});
+```
+
+Error response shape:
+```json
+{ "error": "Resource not found", "code": "not_found", "correlationId": "uuid" }
+```
+
+Level routing: 5xx throws → `error`, 4xx throws → `warn`, generic `Error` → `fatal`.
+
+#### `installGlobalErrorHandlers(options?)`
+
+Installs `process.on('unhandledRejection')` and `process.on('uncaughtException')`. Both log at `fatal` with a correlationId, call optional `onFatal`, then wait 500ms and call `process.exit(1)`. Call once at process startup (e.g. `instrumentation.ts`).
+
+```typescript
+import { installGlobalErrorHandlers } from 'hazo_logs/server';
+
+installGlobalErrorHandlers({
+  onFatal: async (err) => {
+    await alertOpsTeam(err);
+  },
+  exitOnUncaught: true,  // default
+});
+```
+
+Options: `onFatal?: (err: Error) => void | Promise<void>`, `exitOnUncaught?: boolean`.
+
+#### `registerAlertTrigger(config)`
+
+Sliding-window alert trigger via `hazo_notify` (optional peer dep). Hooks into `HazoLogger.addLogHook` and fires when a match threshold is crossed within a time window. Returns an unregister function.
+
+```typescript
+import { registerAlertTrigger } from 'hazo_logs/server';
+
+const unregister = registerAlertTrigger({
+  id: 'payment_errors',
+  match: { level: 'error', scopePrefix: 'payment.' },
+  threshold: { count: 3, windowMs: 60_000 },
+  notify: {
+    kind: 'ops.payment_error',
+    scopeId: 'my_app',
+    recipientUserIds: ['ops-user-uuid'],
+    surfaces: ['email'],
+  },
+});
+// Call unregister() to stop listening
+```
+
+`match` supports: `level`, `scopePrefix`, `message_contains`. Set `threshold.count` to `0` to fire on every match. `recipientUserIds` can be a static array or `(entry) => string[]`.
+
 ## Live tail (v1.1+)
 
 `tailLogs` watches the active rotating log file and emits new entries as they are written. Filters mirror `readLogs`. Use it directly for in-process consumers:
@@ -597,7 +789,7 @@ Logs are stored as newline-delimited JSON:
 
 **Fields:**
 - `timestamp` - ISO 8601 timestamp
-- `level` - Log level (error, warn, info, debug)
+- `level` - Log level (fatal, error, warn, info, debug)
 - `package` - Package name from createLogger
 - `message` - Log message
 - `filename` - Source file name
@@ -606,6 +798,8 @@ Logs are stored as newline-delimited JSON:
 - `sessionId` - Optional session ID from context
 - `reference` - Optional reference from context
 - `depth` - Optional call depth from context
+- `scope` - Optional operation scope from context (dotted notation, e.g. `"payment.checkout.refund"`)
+- `userId` - Optional user ID from ALS context
 - `data` - Optional additional data
 
 ## UI Screenshots

package/config/hazo_logs_config.ini.sample

@@ -0,0 +1,2 @@
+; hazo_logs configuration sample
+; Copy to hazo_logs_config.ini and fill in values.

package/dist/index.d.ts

@@ -33,5 +33,10 @@
  * ```
  */
 export { createLogger, createLoggerAsync, preloadServerLogger, ConsoleLogger, } from './lib/universal-logger.js';
-export type { Logger, LogLevel, LogData, LogEntry, LogContext, HazoLogConfig, PackageLoggerOptions, LogSource, LogOrigin, } from './lib/types.js';
+export { getRingBuffer, RingBuffer, RingBufferRegistry, ringBufferRegistry } from './lib/ring_buffer.js';
+export { getCallerInfo, get_filename, get_line_number } from './lib/utils/caller_info.js';
+export type { CallerInfo } from './lib/utils/caller_info.js';
+export { LevelResolver } from './lib/level_resolver.js';
+export type { OverrideMap } from './lib/level_resolver.js';
+export type { Logger, LogLevel, LogData, LogEntry, LogContext, HazoLogConfig, PackageLoggerOptions, LogSource, LogOrigin, RingBufferEntry, } from './lib/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,SAAS,GACV,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGzG,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC1F,YAAY,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAG7D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAG3D,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,SAAS,EACT,eAAe,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -34,4 +34,10 @@
  */
 // Universal logger - works on both server and client
 export { createLogger, createLoggerAsync, preloadServerLogger, ConsoleLogger, } from './lib/universal-logger.js';
+// Ring buffer — safe for server; no-ops on client
+export { getRingBuffer, RingBuffer, RingBufferRegistry, ringBufferRegistry } from './lib/ring_buffer.js';
+// Caller-info utilities — server-side stack-trace helpers
+export { getCallerInfo, get_filename, get_line_number } from './lib/utils/caller_info.js';
+// LevelResolver — pure logic, no Node.js deps, safe for universal use
+export { LevelResolver } from './lib/level_resolver.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,qDAAqD;AACrD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,qDAAqD;AACrD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,GACd,MAAM,2BAA2B,CAAC;AAEnC,kDAAkD;AAClD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEzG,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAG1F,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/lib/alert-triggers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * registerAlertTrigger — fires hazo_notify dispatch when log volume crosses a threshold.
+ *
+ * Requires hazo_notify to be installed (optional peer dep).
+ * Sliding window state is in-memory — resets on process restart.
+ */
+import type { LogEntry, LogLevel } from './types.js';
+export interface AlertTriggerMatch {
+    /** Only match entries at this level or above */
+    level?: LogLevel;
+    /** Only match entries whose `scope` starts with this prefix */
+    scopePrefix?: string;
+    /** Only match entries whose message contains this substring */
+    message_contains?: string;
+}
+export interface AlertTriggerNotify {
+    /** hazo_notify event_type */
+    kind: string;
+    /** hazo_notify scope_id */
+    scopeId: string;
+    /** Static list OR function returning IDs from the triggering log entry */
+    recipientUserIds: string[] | ((entry: LogEntry) => string[]);
+    /** hazo_notify surfaces (e.g. ['email', 'bell']) */
+    surfaces?: string[];
+}
+export interface AlertTriggerConfig {
+    id: string;
+    match: AlertTriggerMatch;
+    threshold: {
+        /** Number of matching events required to fire */
+        count: number;
+        /** Sliding window duration in ms. 0 = fire on every match (no window) */
+        windowMs: number;
+    };
+    notify: AlertTriggerNotify;
+}
+/**
+ * Register an alert trigger. Returns an unregister function.
+ *
+ * @example
+ * const unregister = registerAlertTrigger({
+ *   id: 'payment_errors',
+ *   match: { level: 'error', scopePrefix: 'payment.' },
+ *   threshold: { count: 1, windowMs: 0 },
+ *   notify: {
+ *     kind: 'ops.payment_error',
+ *     scopeId: 'my_app',
+ *     recipientUserIds: ['ops-user-uuid'],
+ *     surfaces: ['email'],
+ *   },
+ * });
+ */
+export declare function registerAlertTrigger(config: AlertTriggerConfig): () => void;
+//# sourceMappingURL=alert-triggers.d.ts.map

package/dist/lib/alert-triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-triggers.d.ts","sourceRoot":"","sources":["../../src/lib/alert-triggers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,MAAM,EAAE,CAAC,CAAC;IAC7D,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,iBAAiB,CAAC;IACzB,SAAS,EAAE;QACT,iDAAiD;QACjD,KAAK,EAAE,MAAM,CAAC;QACd,yEAAyE;QACzE,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AA2DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,IAAI,CA2B3E"}

package/dist/lib/alert-triggers.js

@@ -0,0 +1,96 @@
+/**
+ * registerAlertTrigger — fires hazo_notify dispatch when log volume crosses a threshold.
+ *
+ * Requires hazo_notify to be installed (optional peer dep).
+ * Sliding window state is in-memory — resets on process restart.
+ */
+import { optional_import } from 'hazo_core';
+import { HazoLogger } from './hazo_logger.js';
+const HAZO_LOG_LEVEL_PRIORITY = {
+    fatal: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5,
+};
+function matchesTrigger(entry, match) {
+    if (match.level) {
+        // Entry level must be at least as severe as the match level
+        if (HAZO_LOG_LEVEL_PRIORITY[entry.level] > HAZO_LOG_LEVEL_PRIORITY[match.level]) {
+            return false;
+        }
+    }
+    if (match.scopePrefix && !entry.scope?.startsWith(match.scopePrefix)) {
+        return false;
+    }
+    if (match.message_contains && !entry.message.includes(match.message_contains)) {
+        return false;
+    }
+    return true;
+}
+async function fireNotification(config, entry) {
+    const dispatcher = await optional_import('hazo_notify/dispatcher');
+    if (!dispatcher) {
+        console.error(`[hazo_logs] Alert trigger "${config.id}" fired but hazo_notify is not installed. ` +
+            'Add hazo_notify as a dependency to receive alert notifications.');
+        return;
+    }
+    const recipientUserIds = Array.isArray(config.notify.recipientUserIds)
+        ? config.notify.recipientUserIds
+        : config.notify.recipientUserIds(entry);
+    await dispatcher.dispatch({
+        scope_id: config.notify.scopeId,
+        event_type: config.notify.kind,
+        subject_id: entry.timestamp,
+        recipient_user_ids: recipientUserIds,
+        surfaces: config.notify.surfaces,
+        payloads: {
+            log_level: entry.level,
+            log_package: entry.package,
+            log_message: entry.message,
+            log_scope: entry.scope,
+            log_timestamp: entry.timestamp,
+        },
+    });
+}
+/**
+ * Register an alert trigger. Returns an unregister function.
+ *
+ * @example
+ * const unregister = registerAlertTrigger({
+ *   id: 'payment_errors',
+ *   match: { level: 'error', scopePrefix: 'payment.' },
+ *   threshold: { count: 1, windowMs: 0 },
+ *   notify: {
+ *     kind: 'ops.payment_error',
+ *     scopeId: 'my_app',
+ *     recipientUserIds: ['ops-user-uuid'],
+ *     surfaces: ['email'],
+ *   },
+ * });
+ */
+export function registerAlertTrigger(config) {
+    // Per-trigger sliding window: array of event timestamps
+    const eventTimestamps = [];
+    const unregister = HazoLogger.addLogHook((entry) => {
+        if (!matchesTrigger(entry, config.match))
+            return;
+        const now = Date.now();
+        // Prune events outside the window (skip for windowMs = 0)
+        if (config.threshold.windowMs > 0) {
+            const cutoff = now - config.threshold.windowMs;
+            while (eventTimestamps.length > 0 && eventTimestamps[0] < cutoff) {
+                eventTimestamps.shift();
+            }
+        }
+        eventTimestamps.push(now);
+        if (eventTimestamps.length >= config.threshold.count) {
+            // Reset window before async fire so re-entrant logs don't double-fire
+            eventTimestamps.length = 0;
+            void fireNotification(config, entry);
+        }
+    });
+    return unregister;
+}
+//# sourceMappingURL=alert-triggers.js.map

package/dist/lib/alert-triggers.js.map

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

package/dist/lib/config_loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config_loader.d.ts","sourceRoot":"","sources":["../../src/lib/config_loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,YAAY,CAAC;AAQ1D;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CAmC7D"}
+{"version":3,"file":"config_loader.d.ts","sourceRoot":"","sources":["../../src/lib/config_loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAKhE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,CA6B7D"}

package/dist/lib/config_loader.js

@@ -7,8 +7,6 @@ import path from 'path';
 import ini from 'ini';
 import { DEFAULT_CONFIG } from './utils/constants.js';
 const CONFIG_FILENAME = 'config/hazo_logs_config.ini';
-// Track whether the missing config warning has been shown
-let _config_warning_shown = false;
 /**
  * Load configuration from INI file
  * @param configPath - Optional explicit path to config file
@@ -17,10 +15,6 @@ let _config_warning_shown = false;
 export function loadConfig(configPath) {
     const resolvedPath = configPath || findConfigFile();
     if (!resolvedPath || !fs.existsSync(resolvedPath)) {
-        if (!_config_warning_shown) {
-            _config_warning_shown = true;
-            console.warn(`[HazoLog] No config found, using defaults. Create ${CONFIG_FILENAME} to customize.`);
-        }
         return { ...DEFAULT_CONFIG };
     }
     try {
@@ -71,7 +65,7 @@ function findConfigFile() {
     return null;
 }
 /**
- * Validate and return a valid log level
+ * Validate and return a valid config log level (fatal excluded — not a valid min-level)
  */
 function validateLogLevel(level) {
     const validLevels = ['error', 'warn', 'info', 'debug'];

package/dist/lib/config_loader.js.map

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

package/dist/lib/console-logger.d.ts

@@ -5,7 +5,7 @@
  * This module imports ONLY from types.ts (pure type definitions)
  * so it is safe for both server and client environments.
  */
-import type { Logger, LogData, LogLevel } from './types.js';
+import type { Logger, LogData, LogLevel, RingBufferEntry } from './types.js';
 export declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
 /**
  * Console-based logger for client-side use
@@ -18,9 +18,25 @@ export declare class ConsoleLogger implements Logger {
     constructor(packageName: string, minLevel?: LogLevel, on_log?: (level: string, message: string, data?: Record<string, unknown>) => void);
     private shouldLog;
     private formatMessage;
+    fatal(message: string, data?: LogData): void;
     error(message: string, data?: LogData): void;
     warn(message: string, data?: LogData): void;
     info(message: string, data?: LogData): void;
     debug(message: string, data?: LogData): void;
+    trace(message: string, data?: LogData): void;
+    heartbeat(_name: string, _fields: {
+        status: string;
+        [key: string]: unknown;
+    }, _opts?: {
+        trigger?: (prev: Record<string, unknown>, curr: Record<string, unknown>) => boolean;
+    }): void;
+    sampled(level: 'trace' | 'debug' | 'info' | 'warn', msg: string, fields?: Record<string, unknown>, opts?: {
+        sample: number;
+    }): void;
+    dedupe(level: 'trace' | 'debug' | 'info' | 'warn', msg: string, fields?: Record<string, unknown>, _opts?: {
+        window: string;
+        key?: string;
+    }): void;
+    getRingBuffer(_correlationId: string, _n?: number): RingBufferEntry[];
 }
 //# sourceMappingURL=console-logger.d.ts.map

package/dist/lib/console-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"console-logger.d.ts","sourceRoot":"","sources":["../../src/lib/console-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5D,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAKvD,CAAC;AAEF;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,MAAM,CAAC,CAA2E;gBAE9E,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI;IAMhJ,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAKrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CAM7C"}
+{"version":3,"file":"console-logger.d.ts","sourceRoot":"","sources":["../../src/lib/console-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOvD,CAAC;AAEF;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,MAAM,CAAC,CAA2E;gBAE9E,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAkB,EAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI;IAMhJ,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAKrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAO5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAU5C,SAAS,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,EACnD,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;KAAE,GAC9F,IAAI;IAOP,OAAO,CACL,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EAC1C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GACxB,IAAI;IAUP,MAAM,CACJ,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,EAC1C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACvC,IAAI;IASP,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE;CAItE"}

package/dist/lib/console-logger.js

@@ -6,10 +6,12 @@
  * so it is safe for both server and client environments.
  */
 export const LOG_LEVEL_PRIORITY = {
-    error: 0,
-    warn: 1,
-    info: 2,
-    debug: 3,
+    fatal: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5,
 };
 /**
  * Console-based logger for client-side use
@@ -31,6 +33,12 @@ export class ConsoleLogger {
         const timestamp = new Date().toISOString();
         return `[${timestamp}] [${level.toUpperCase()}] [${this.packageName}] ${message}`;
     }
+    fatal(message, data) {
+        if (this.shouldLog('fatal')) {
+            console.error(this.formatMessage('fatal', message), data ?? '');
+            this.on_log?.('fatal', message, data);
+        }
+    }
     error(message, data) {
         if (this.shouldLog('error')) {
             console.error(this.formatMessage('error', message), data ?? '');
@@ -55,5 +63,40 @@ export class ConsoleLogger {
             this.on_log?.('debug', message, data);
         }
     }
+    trace(message, data) {
+        if (this.shouldLog('trace')) {
+            // Use console.debug for trace — console.trace prints a stack trace
+            console.debug(this.formatMessage('trace', message), data ?? '');
+            this.on_log?.('trace', message, data);
+        }
+    }
+    // ─── Smart helpers (no-ops on client — server-side state would be meaningless) ─
+    heartbeat(_name, _fields, _opts) {
+        // Client-side: emit at debug level so it is at least visible when debugging
+        if (this.shouldLog('debug')) {
+            console.debug(this.formatMessage('debug', `heartbeat: ${_name}`), _fields);
+        }
+    }
+    sampled(level, msg, fields, opts) {
+        const sample = opts?.sample ?? 0.1;
+        if (Math.random() < sample && this.shouldLog(level)) {
+            const sampleLabel = `(sampled ~1/${Math.round(1 / sample)})`;
+            const method = level === 'warn' ? 'warn' : level === 'info' ? 'info' : 'debug';
+            console[method](this.formatMessage(level, `${msg} ${sampleLabel}`), fields ?? '');
+            this.on_log?.(level, `${msg} ${sampleLabel}`, fields);
+        }
+    }
+    dedupe(level, msg, fields, _opts) {
+        // Client-side: no deduplication state — just emit
+        if (this.shouldLog(level)) {
+            const method = level === 'warn' ? 'warn' : level === 'info' ? 'info' : 'debug';
+            console[method](this.formatMessage(level, msg), fields ?? '');
+            this.on_log?.(level, msg, fields);
+        }
+    }
+    getRingBuffer(_correlationId, _n) {
+        // Client-side: no ring buffer
+        return [];
+    }
 }
 //# sourceMappingURL=console-logger.js.map

package/dist/lib/console-logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"console-logger.js","sourceRoot":"","sources":["../../src/lib/console-logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,kBAAkB,GAA6B;IAC1D,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,aAAa;IAChB,WAAW,CAAS;IACpB,QAAQ,CAAW;IACnB,MAAM,CAA4E;IAE1F,YAAY,WAAmB,EAAE,WAAqB,OAAO,EAAE,MAAiF;QAC9I,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAEO,SAAS,CAAC,KAAe;QAC/B,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxE,CAAC;IAEO,aAAa,CAAC,KAAe,EAAE,OAAe;QACpD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,OAAO,IAAI,SAAS,MAAM,KAAK,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;IACpF,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YAC9D,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YAC9D,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;YAChE,IAAI,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"console-logger.js","sourceRoot":"","sources":["../../src/lib/console-logger.ts"],"names":[],"mappings":"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"}