hazo_logs 1.0.6 → 1.0.8

package/README.md

@@ -78,7 +78,8 @@ import { createLogApiHandler } from 'hazo_logs/ui/server';
 
 const handler = createLogApiHandler();
 
-export const { GET } = handler;
+// GET for log viewer, POST for client-side logging
+export const { GET, POST } = handler;
 ```
 
 **2. Create UI page** (`app/logs/page.tsx`):
@@ -116,35 +117,74 @@ Visit `/logs` in your app to view logs!
 
 ### Client-Side Logging (Browser)
 
-For logging from client components (browser), use the client logger:
+For logging from client components (browser), use the client logger.
+
+**1. Configure global defaults (recommended):**
+
+Set up global configuration once at app initialization. This ensures all client loggers (including those from dependency packages) use the correct API endpoint:
+
+```typescript
+// app/providers.tsx or lib/hazo-init.ts
+'use client';
+import { configureClientLogger } from 'hazo_logs/ui';
+
+// Configure once at app startup
+configureClientLogger({
+  apiBasePath: '/api/logs',  // Required: your log API endpoint
+  minLevel: 'info',          // Optional: minimum log level
+});
+```
+
+**2. Create loggers in your components:**
 
 ```typescript
 'use client';
 import { createClientLogger } from 'hazo_logs/ui';
 
+// No need to specify apiBasePath - inherits from global config
 const logger = createClientLogger({
   packageName: 'my-app-client',
-  apiBasePath: '/api/logs',
 });
 
 logger.info('User clicked button', { buttonId: 'submit' });
 logger.error('Failed to load data', { error: err.message });
 ```
 
+**Why use global configuration?**
+
+- Dependency packages (like `hazo_collab_forms`) automatically use your configured endpoint
+- Avoids 404 errors from loggers using the wrong default path
+- Single place to configure all client logging settings
+
 ## Important Notes
 
-### Server-Only Core Logger
+### Server/Client Import Paths
+
+hazo_logs provides different import paths for different environments:
 
-The main `hazo_logs` import uses Node.js APIs (`fs`, `async_hooks`) and **cannot be imported in client components**. If you try to import it in a client component, you'll get build errors.
+| Import Path | Environment | Use Case |
+|-------------|-------------|----------|
+| `hazo_logs` | Universal | Basic logging (console on client, file on server) |
+| `hazo_logs/server` | Server-only | Full logging with context, sessions, log reader |
+| `hazo_logs/ui` | Client | React components, `createClientLogger()` |
+| `hazo_logs/ui/server` | Server-only | API handlers for log viewer |
 
 ```typescript
-// Server components, API routes, middleware - OK
+// Universal - works everywhere (recommended for libraries)
 import { createLogger } from 'hazo_logs';
 
-// Client components - use client logger instead
+// Server-only - full capabilities (file logging, context, sessions)
+import { createLogger, runWithLogContext } from 'hazo_logs/server';
+
+// Client components - sends logs to server API
 import { createClientLogger } from 'hazo_logs/ui';
+
+// API routes - create log viewer endpoints
+import { createLogApiHandler } from 'hazo_logs/ui/server';
 ```
 
+**Note**: The `hazo_logs/server` and `hazo_logs/ui/server` imports use the `server-only` package and will throw an error if accidentally imported in client bundles. This prevents Next.js build errors from Node.js APIs (`fs`, `async_hooks`) being bundled for the browser.
+
 ### Tailwind CSS Setup Required
 
 The log viewer UI uses dynamic Tailwind classes that would be purged during build. You **must** configure both:
@@ -182,11 +222,10 @@ export default {
 
 ### Session and Reference Tracking
 
-Track logs across async operations:
+Track logs across async operations (server-only feature):
 
 ```typescript
-import { createLogger } from 'hazo_logs';
-import { runWithLogContext } from 'hazo_logs';
+import { createLogger, runWithLogContext } from 'hazo_logs/server';
 
 const logger = createLogger('auth');
 
@@ -344,6 +383,40 @@ Read logs from files with filtering and pagination (server-side only).
 
 ### UI Exports (`hazo_logs/ui`)
 
+#### `configureClientLogger(config: ClientLoggerGlobalConfig): void`
+
+Configure global defaults for all client loggers. Call once at app initialization.
+
+```typescript
+configureClientLogger({
+  apiBasePath: '/api/logs',  // Required
+  minLevel: 'info',          // Optional
+  consoleOutput: true,       // Optional
+  batchMode: false,          // Optional
+  batchInterval: 5000,       // Optional (ms)
+});
+```
+
+#### `getClientLoggerConfig(): ClientLoggerGlobalConfig | undefined`
+
+Get current global configuration (returns undefined if not configured).
+
+#### `isClientLoggerConfigured(): boolean`
+
+Check if global configuration has been set.
+
+#### `createClientLogger(config?: ClientLoggerConfig): ClientLogger`
+
+Create a client-side logger. Inherits from global config if set.
+
+```typescript
+const logger = createClientLogger({
+  packageName: 'my-component',  // Tag for this logger
+  sessionId: 'sess_123',        // Optional session tracking
+  reference: 'user_456',        // Optional reference tracking
+});
+```
+
 #### `LogViewerPage`
 
 Main log viewer component.
@@ -374,7 +447,8 @@ Create Next.js API route handler.
 **Returns:**
 ```typescript
 {
-  GET: (request: Request) => Promise<Response>
+  GET: (request: Request) => Promise<Response>,  // Log viewer queries
+  POST: (request: Request) => Promise<Response>, // Client-side log ingestion
 }
 ```
 
@@ -448,11 +522,15 @@ cp node_modules/hazo_logs/config/hazo_logs_config.example.ini config/hazo_logs_c
 ### Import errors in client components
 
 ```
-Error: fs is not defined
-Error: async_hooks is not defined
+Error: Module not found: Can't resolve 'async_hooks'
+Error: Module not found: Can't resolve 'fs'
 ```
 
-The core `hazo_logs` import is server-only. Use `createClientLogger` from `hazo_logs/ui` for browser logging.
+This happens when server-only code is imported in client components. Solutions:
+
+1. **For logging in client components**: Use `createClientLogger` from `hazo_logs/ui`
+2. **For server-only modules**: Import from `hazo_logs/server` instead of `hazo_logs`
+3. **For universal code**: The base `hazo_logs` import now works on both client and server (returns console logger on client)
 
 ### hazo_ui missing errors
 
@@ -462,6 +540,24 @@ The log viewer UI requires `hazo_ui` package. Install it:
 npm install hazo_ui
 ```
 
+### POST /api/logs 404 errors
+
+If you see repeated `POST /api/logs 404` errors, client loggers are using the default endpoint which doesn't match your API route location.
+
+**Solution**: Configure the global client logger at app startup:
+
+```typescript
+// app/providers.tsx or lib/hazo-init.ts
+'use client';
+import { configureClientLogger } from 'hazo_logs/ui';
+
+configureClientLogger({
+  apiBasePath: '/api/hazo_logs/logs',  // Match your actual route
+});
+```
+
+This ensures all client loggers (including those from dependency packages) use the correct endpoint.
+
 ## Contributing
 
 Contributions are welcome! Please:

package/dist/index.d.ts

@@ -1,32 +1,37 @@
 /**
- * hazo_logs - Winston logger wrapper with singleton pattern
+ * hazo_logs - Universal logging library for hazo packages
  *
- * ⚠️ SERVER-ONLY: This module uses Node.js APIs (fs, async_hooks) and CANNOT be
- * imported in client components. For client-side logging, use:
- *   import { createClientLogger } from 'hazo_logs/ui';
+ * This root export is SAFE for both server and client environments.
  *
- * Usage:
- *   import { createLogger, runWithLogContext } from 'hazo_logs';
+ * ## Quick Start
  *
- *   const logger = createLogger('my_package');
+ * ```typescript
+ * import { createLogger } from 'hazo_logs';
  *
- *   // Basic logging
- *   logger.info('Hello world', { key: 'value' });
+ * const logger = createLogger('my_app');
+ * logger.info('Application started');
+ * ```
  *
- *   // With context (session/user tracking)
- *   runWithLogContext({ sessionId: 'sess_123', reference: 'user_42' }, () => {
- *     logger.info('User action'); // automatically includes sessionId and reference
- *   });
+ * ## Environment-Specific Imports
  *
- * For UI components (requires Next.js, React, and hazo_ui):
- *   import { LogViewerPage } from 'hazo_logs/ui';
- *   import { createLogApiHandler } from 'hazo_logs/ui/server';
+ * ### Server-Only (full capabilities)
+ * For file logging, AsyncLocalStorage context, log reading:
+ * ```typescript
+ * import { createLogger, runWithLogContext, readLogs } from 'hazo_logs/server';
+ * ```
+ *
+ * ### Client Components (sends logs to server API)
+ * For logging that persists to server:
+ * ```typescript
+ * import { createClientLogger } from 'hazo_logs/ui';
+ * ```
+ *
+ * ### UI Components (log viewer)
+ * ```typescript
+ * import { LogViewerPage } from 'hazo_logs/ui';
+ * import { createLogApiHandler } from 'hazo_logs/ui/server';
+ * ```
  */
-export { HazoLogger } from './lib/hazo_logger.js';
-export { PackageLogger, createLogger } from './lib/package_logger.js';
-export { loadConfig } from './lib/config_loader.js';
-export { generateSessionId, startSession, startSessionAsync, runWithLogContext, runWithLogContextAsync, getLogContext, withSession, withContext, } from './lib/context/log-context.js';
-export { readLogs, getAvailableLogDates, getUniquePackages, getUniqueExecutionIds, getUniqueSessionIds, getUniqueReferences, } from './lib/log-reader.js';
-export type { Logger, LogLevel, LogData, LogEntry, LogContext, HazoLogConfig, PackageLoggerOptions, } from './lib/types.js';
-export type { ReadLogsOptions, LogQueryResult } from './lib/log-reader.js';
+export { createLogger, createLoggerAsync, preloadServerLogger, ConsoleLogger, } from './lib/universal-logger.js';
+export type { Logger, LogLevel, LogData, LogEntry, LogContext, HazoLogConfig, PackageLoggerOptions, LogSource, } 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,UAAU,EACV,aAAa,EACb,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,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,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,SAAS,GACV,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -1,33 +1,37 @@
 /**
- * hazo_logs - Winston logger wrapper with singleton pattern
+ * hazo_logs - Universal logging library for hazo packages
  *
- * ⚠️ SERVER-ONLY: This module uses Node.js APIs (fs, async_hooks) and CANNOT be
- * imported in client components. For client-side logging, use:
- *   import { createClientLogger } from 'hazo_logs/ui';
+ * This root export is SAFE for both server and client environments.
  *
- * Usage:
- *   import { createLogger, runWithLogContext } from 'hazo_logs';
+ * ## Quick Start
  *
- *   const logger = createLogger('my_package');
+ * ```typescript
+ * import { createLogger } from 'hazo_logs';
  *
- *   // Basic logging
- *   logger.info('Hello world', { key: 'value' });
+ * const logger = createLogger('my_app');
+ * logger.info('Application started');
+ * ```
  *
- *   // With context (session/user tracking)
- *   runWithLogContext({ sessionId: 'sess_123', reference: 'user_42' }, () => {
- *     logger.info('User action'); // automatically includes sessionId and reference
- *   });
+ * ## Environment-Specific Imports
  *
- * For UI components (requires Next.js, React, and hazo_ui):
- *   import { LogViewerPage } from 'hazo_logs/ui';
- *   import { createLogApiHandler } from 'hazo_logs/ui/server';
+ * ### Server-Only (full capabilities)
+ * For file logging, AsyncLocalStorage context, log reading:
+ * ```typescript
+ * import { createLogger, runWithLogContext, readLogs } from 'hazo_logs/server';
+ * ```
+ *
+ * ### Client Components (sends logs to server API)
+ * For logging that persists to server:
+ * ```typescript
+ * import { createClientLogger } from 'hazo_logs/ui';
+ * ```
+ *
+ * ### UI Components (log viewer)
+ * ```typescript
+ * import { LogViewerPage } from 'hazo_logs/ui';
+ * import { createLogApiHandler } from 'hazo_logs/ui/server';
+ * ```
  */
-// Core logging
-export { HazoLogger } from './lib/hazo_logger.js';
-export { PackageLogger, createLogger } from './lib/package_logger.js';
-export { loadConfig } from './lib/config_loader.js';
-// Log context
-export { generateSessionId, startSession, startSessionAsync, runWithLogContext, runWithLogContextAsync, getLogContext, withSession, withContext, } from './lib/context/log-context.js';
-// Log reader
-export { readLogs, getAvailableLogDates, getUniquePackages, getUniqueExecutionIds, getUniqueSessionIds, getUniqueReferences, } from './lib/log-reader.js';
+// Universal logger - works on both server and client
+export { createLogger, createLoggerAsync, preloadServerLogger, ConsoleLogger, } from './lib/universal-logger.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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,eAAe;AACf,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,cAAc;AACd,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAEtC,aAAa;AACb,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,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"}

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

@@ -0,0 +1,67 @@
+/**
+ * Universal Logger - Works on both server and client
+ *
+ * On server: Uses the full PackageLogger with file transports
+ * On client: Uses console-based logging (logs are not persisted)
+ *
+ * For full server logging capabilities, import from 'hazo_logs/server'
+ * For client logging that posts to server API, use 'hazo_logs/ui' createClientLogger
+ */
+import type { Logger, LogData, LogLevel } from './types.js';
+/**
+ * Console-based logger for client-side use
+ * Provides basic logging that outputs to browser console
+ */
+declare class ConsoleLogger implements Logger {
+    private packageName;
+    private minLevel;
+    constructor(packageName: string, minLevel?: LogLevel);
+    private shouldLog;
+    private formatMessage;
+    error(message: string, data?: LogData): void;
+    warn(message: string, data?: LogData): void;
+    info(message: string, data?: LogData): void;
+    debug(message: string, data?: LogData): void;
+}
+/**
+ * Pre-load the server logger module (call this early in server startup)
+ * This allows createLogger to return a real server logger synchronously
+ */
+export declare function preloadServerLogger(): Promise<void>;
+/**
+ * Create a universal logger that works on both server and client
+ *
+ * On server: Returns PackageLogger (may start as ConsoleLogger and upgrade)
+ * On client: Returns ConsoleLogger that outputs to browser console
+ *
+ * @param packageName - Name of the package (e.g., "hazo_auth", "my_app")
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from 'hazo_logs';
+ *
+ * const logger = createLogger('my_app');
+ * logger.info('Application started');
+ * ```
+ *
+ * Note: For full server capabilities (context, sessions), use:
+ * ```typescript
+ * import { createLogger } from 'hazo_logs/server';
+ * ```
+ *
+ * For client logging that persists to server, use:
+ * ```typescript
+ * import { createClientLogger } from 'hazo_logs/ui';
+ * ```
+ */
+export declare function createLogger(packageName: string): Logger;
+/**
+ * Async version of createLogger - returns real server logger immediately
+ *
+ * @param packageName - Name of the package
+ * @returns Promise<Logger>
+ */
+export declare function createLoggerAsync(packageName: string): Promise<Logger>;
+export { ConsoleLogger };
+//# sourceMappingURL=universal-logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"universal-logger.d.ts","sourceRoot":"","sources":["../../src/lib/universal-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAgB5D;;;GAGG;AACH,cAAM,aAAc,YAAW,MAAM;IACnC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAW;gBAEf,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAkB;IAK7D,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,aAAa;IAKrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CAK7C;AAoDD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAYzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB5E;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/lib/universal-logger.js

@@ -0,0 +1,191 @@
+/**
+ * Universal Logger - Works on both server and client
+ *
+ * On server: Uses the full PackageLogger with file transports
+ * On client: Uses console-based logging (logs are not persisted)
+ *
+ * For full server logging capabilities, import from 'hazo_logs/server'
+ * For client logging that posts to server API, use 'hazo_logs/ui' createClientLogger
+ */
+const LOG_LEVEL_PRIORITY = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+};
+/**
+ * Check if we're running on the server
+ */
+function isServer() {
+    return typeof window === 'undefined';
+}
+/**
+ * Console-based logger for client-side use
+ * Provides basic logging that outputs to browser console
+ */
+class ConsoleLogger {
+    packageName;
+    minLevel;
+    constructor(packageName, minLevel = 'debug') {
+        this.packageName = packageName;
+        this.minLevel = minLevel;
+    }
+    shouldLog(level) {
+        return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.minLevel];
+    }
+    formatMessage(level, message) {
+        const timestamp = new Date().toISOString();
+        return `[${timestamp}] [${level.toUpperCase()}] [${this.packageName}] ${message}`;
+    }
+    error(message, data) {
+        if (this.shouldLog('error')) {
+            console.error(this.formatMessage('error', message), data ?? '');
+        }
+    }
+    warn(message, data) {
+        if (this.shouldLog('warn')) {
+            console.warn(this.formatMessage('warn', message), data ?? '');
+        }
+    }
+    info(message, data) {
+        if (this.shouldLog('info')) {
+            console.info(this.formatMessage('info', message), data ?? '');
+        }
+    }
+    debug(message, data) {
+        if (this.shouldLog('debug')) {
+            console.debug(this.formatMessage('debug', message), data ?? '');
+        }
+    }
+}
+/**
+ * Deferred logger that upgrades from ConsoleLogger to real server logger
+ * when the server module is loaded asynchronously
+ */
+class DeferredServerLogger {
+    packageName;
+    innerLogger;
+    upgraded = false;
+    constructor(packageName) {
+        this.packageName = packageName;
+        this.innerLogger = new ConsoleLogger(packageName);
+        // Attempt async upgrade to real server logger
+        this.upgrade();
+    }
+    async upgrade() {
+        if (this.upgraded)
+            return;
+        try {
+            const { createLogger } = await import('./package_logger.js');
+            this.innerLogger = createLogger(this.packageName);
+            this.upgraded = true;
+        }
+        catch {
+            // Keep using ConsoleLogger
+        }
+    }
+    error(message, data) {
+        this.innerLogger.error(message, data);
+    }
+    warn(message, data) {
+        this.innerLogger.warn(message, data);
+    }
+    info(message, data) {
+        this.innerLogger.info(message, data);
+    }
+    debug(message, data) {
+        this.innerLogger.debug(message, data);
+    }
+}
+// Cache for pre-loaded server loggers
+const serverLoggerCache = new Map();
+let serverModuleLoaded = false;
+let serverModulePromise = null;
+/**
+ * Pre-load the server logger module (call this early in server startup)
+ * This allows createLogger to return a real server logger synchronously
+ */
+export async function preloadServerLogger() {
+    if (!isServer() || serverModuleLoaded)
+        return;
+    try {
+        if (!serverModulePromise) {
+            serverModulePromise = import('./package_logger.js');
+        }
+        await serverModulePromise;
+        serverModuleLoaded = true;
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Create a universal logger that works on both server and client
+ *
+ * On server: Returns PackageLogger (may start as ConsoleLogger and upgrade)
+ * On client: Returns ConsoleLogger that outputs to browser console
+ *
+ * @param packageName - Name of the package (e.g., "hazo_auth", "my_app")
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from 'hazo_logs';
+ *
+ * const logger = createLogger('my_app');
+ * logger.info('Application started');
+ * ```
+ *
+ * Note: For full server capabilities (context, sessions), use:
+ * ```typescript
+ * import { createLogger } from 'hazo_logs/server';
+ * ```
+ *
+ * For client logging that persists to server, use:
+ * ```typescript
+ * import { createClientLogger } from 'hazo_logs/ui';
+ * ```
+ */
+export function createLogger(packageName) {
+    if (!isServer()) {
+        // Client-side: return console logger
+        return new ConsoleLogger(packageName);
+    }
+    // Check cache first
+    const cached = serverLoggerCache.get(packageName);
+    if (cached) {
+        return cached;
+    }
+    // Server-side: create deferred logger that upgrades asynchronously
+    const logger = new DeferredServerLogger(packageName);
+    serverLoggerCache.set(packageName, logger);
+    return logger;
+}
+/**
+ * Async version of createLogger - returns real server logger immediately
+ *
+ * @param packageName - Name of the package
+ * @returns Promise<Logger>
+ */
+export async function createLoggerAsync(packageName) {
+    if (!isServer()) {
+        return new ConsoleLogger(packageName);
+    }
+    try {
+        if (!serverModulePromise) {
+            serverModulePromise = import('./package_logger.js');
+        }
+        const { createLogger } = await serverModulePromise;
+        serverModuleLoaded = true;
+        const logger = createLogger(packageName);
+        serverLoggerCache.set(packageName, logger);
+        return logger;
+    }
+    catch {
+        console.warn(`[hazo_logs] Failed to load server logger, falling back to console logger for ${packageName}`);
+        return new ConsoleLogger(packageName);
+    }
+}
+// Export ConsoleLogger for direct use if needed
+export { ConsoleLogger };
+//# sourceMappingURL=universal-logger.js.map

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

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

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * hazo_logs/server - Server-only logging module
+ *
+ * ⚠️ SERVER-ONLY: This module uses Node.js APIs (fs, async_hooks) and CANNOT be
+ * imported in client components. Import will fail in browser bundles.
+ *
+ * Usage:
+ *   import { createLogger, runWithLogContext } from 'hazo_logs/server';
+ *
+ *   const logger = createLogger('my_package');
+ *   logger.info('Hello world', { key: 'value' });
+ *
+ * For client-side logging, use:
+ *   import { createClientLogger } from 'hazo_logs/ui';
+ */
+import 'server-only';
+export { HazoLogger } from './lib/hazo_logger.js';
+export { PackageLogger, createLogger } from './lib/package_logger.js';
+export { loadConfig } from './lib/config_loader.js';
+export { generateSessionId, startSession, startSessionAsync, runWithLogContext, runWithLogContextAsync, getLogContext, withSession, withContext, } from './lib/context/log-context.js';
+export { readLogs, getAvailableLogDates, getUniquePackages, getUniqueExecutionIds, getUniqueSessionIds, getUniqueReferences, } from './lib/log-reader.js';
+export type { Logger, LogLevel, LogData, LogEntry, LogContext, HazoLogConfig, PackageLoggerOptions, } from './lib/types.js';
+export type { ReadLogsOptions, LogQueryResult } from './lib/log-reader.js';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,UAAU,EACV,aAAa,EACb,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/server.js

@@ -0,0 +1,25 @@
+/**
+ * hazo_logs/server - Server-only logging module
+ *
+ * ⚠️ SERVER-ONLY: This module uses Node.js APIs (fs, async_hooks) and CANNOT be
+ * imported in client components. Import will fail in browser bundles.
+ *
+ * Usage:
+ *   import { createLogger, runWithLogContext } from 'hazo_logs/server';
+ *
+ *   const logger = createLogger('my_package');
+ *   logger.info('Hello world', { key: 'value' });
+ *
+ * For client-side logging, use:
+ *   import { createClientLogger } from 'hazo_logs/ui';
+ */
+import 'server-only';
+// Core logging
+export { HazoLogger } from './lib/hazo_logger.js';
+export { PackageLogger, createLogger } from './lib/package_logger.js';
+export { loadConfig } from './lib/config_loader.js';
+// Log context (uses AsyncLocalStorage)
+export { generateSessionId, startSession, startSessionAsync, runWithLogContext, runWithLogContextAsync, getLogContext, withSession, withContext, } from './lib/context/log-context.js';
+// Log reader (uses fs, readline)
+export { readLogs, getAvailableLogDates, getUniquePackages, getUniqueExecutionIds, getUniqueSessionIds, getUniqueReferences, } from './lib/log-reader.js';
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,aAAa,CAAC;AAErB,eAAe;AACf,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,uCAAuC;AACvC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,8BAA8B,CAAC;AAEtC,iCAAiC;AACjC,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC"}

package/dist/ui/server.d.ts

@@ -1,8 +1,12 @@
 /**
  * Server-side UI exports for hazo_logs
  *
+ * ⚠️ SERVER-ONLY: This module uses Node.js APIs and CANNOT be
+ * imported in client components.
+ *
  * Use these in API routes and server components only.
  */
+import 'server-only';
 export { createLogApiHandler } from './api/log-api-handler.js';
 export { withLogAuth } from './middleware/with-log-auth.js';
 export type { LogApiConfig, LogApiHandler, AuthCheckFn, } from './types.js';

package/dist/ui/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/ui/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/ui/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,aAAa,CAAC;AAGrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG5D,YAAY,EACV,YAAY,EACZ,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/ui/server.js

@@ -1,8 +1,12 @@
 /**
  * Server-side UI exports for hazo_logs
  *
+ * ⚠️ SERVER-ONLY: This module uses Node.js APIs and CANNOT be
+ * imported in client components.
+ *
  * Use these in API routes and server components only.
  */
+import 'server-only';
 // API Handler
 export { createLogApiHandler } from './api/log-api-handler.js';
 // Middleware

package/dist/ui/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/ui/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,aAAa;AACb,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/ui/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,aAAa,CAAC;AAErB,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,aAAa;AACb,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_logs",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Logger for hazo packages - Winston wrapper with singleton pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.js"
+    },
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js",
@@ -57,6 +62,7 @@
   "homepage": "https://github.com/pub12/hazo_logs#readme",
   "dependencies": {
     "ini": "^4.1.0",
+    "server-only": "^0.0.1",
     "winston": "^3.17.0",
     "winston-daily-rotate-file": "^5.0.0"
   },