@bloomneo/appkit 1.2.9

package/dist/logger/defaults.js

@@ -0,0 +1,213 @@
+/**
+ * Smart defaults with direct environment access and auto transport detection
+ * @module @bloomneo/appkit/logger
+ * @file src/logger/defaults.ts
+ *
+ * @llm-rule WHEN: App startup - need production-ready logging configuration
+ * @llm-rule AVOID: Calling multiple times - expensive environment parsing, cache results
+ * @llm-rule NOTE: Called once at startup, cached globally for performance like auth module
+ * @llm-rule NOTE: Now includes visual error configuration for enhanced developer experience
+ */
+/**
+ * Get smart defaults using direct VOILA_LOGGER_* environment access
+ * @llm-rule WHEN: App startup to get production-ready logging configuration
+ * @llm-rule AVOID: Calling repeatedly - validates environment each time, expensive operation
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ */
+export function getSmartDefaults() {
+    // Direct environment access with smart defaults (like auth module)
+    const nodeEnv = process.env.NODE_ENV || 'development';
+    const isProduction = nodeEnv === 'production';
+    const isDevelopment = nodeEnv === 'development';
+    const isTest = nodeEnv === 'test';
+    // Auto-detect logging scope
+    const scope = getScope();
+    const minimal = scope === 'minimal';
+    // Auto-detect log level
+    const level = getLevel(isProduction, isDevelopment);
+    // Auto-detect enabled transports
+    const transports = getEnabledTransports(isTest);
+    return {
+        level,
+        scope,
+        minimal,
+        transports,
+        // Console config - direct env access
+        console: {
+            colorize: process.env.VOILA_LOGGER_CONSOLE_COLOR !== 'false' && !isProduction,
+            timestamps: process.env.VOILA_LOGGER_CONSOLE_TIME !== 'false',
+            prettyPrint: isDevelopment && !minimal,
+        },
+        // File config - direct env access
+        file: {
+            dir: process.env.VOILA_LOGGER_DIR || 'logs',
+            filename: process.env.VOILA_LOGGER_FILE_NAME || 'app.log',
+            maxSize: parseInt(process.env.VOILA_LOGGER_FILE_SIZE || (isProduction ? '50000000' : '10000000')),
+            retentionDays: parseInt(process.env.VOILA_LOGGER_FILE_RETENTION || (isProduction ? '30' : '7')),
+        },
+        // Database config - direct env access
+        database: {
+            url: process.env.DATABASE_URL || null,
+            table: process.env.VOILA_LOGGER_DB_TABLE || 'logs',
+            batchSize: parseInt(process.env.VOILA_LOGGER_DB_BATCH || (minimal ? '50' : '100')),
+        },
+        // HTTP config - direct env access
+        http: {
+            url: process.env.VOILA_LOGGER_HTTP_URL || null,
+            batchSize: parseInt(process.env.VOILA_LOGGER_HTTP_BATCH || (minimal ? '25' : '50')),
+            timeout: parseInt(process.env.VOILA_LOGGER_HTTP_TIMEOUT || '30000'),
+        },
+        // Webhook config - direct env access
+        webhook: {
+            url: process.env.VOILA_LOGGER_WEBHOOK_URL || null,
+            level: process.env.VOILA_LOGGER_WEBHOOK_LEVEL || 'error',
+            rateLimit: parseInt(process.env.VOILA_LOGGER_WEBHOOK_RATE || (minimal ? '5' : '10')),
+        },
+        // Service identification - direct env access
+        service: {
+            name: process.env.VOILA_SERVICE_NAME || process.env.npm_package_name || 'app',
+            version: process.env.VOILA_SERVICE_VERSION || process.env.npm_package_version || '1.0.0',
+            environment: nodeEnv,
+        },
+    };
+}
+/**
+ * Auto-detect optimal logging scope
+ * @llm-rule WHEN: Need to determine minimal vs full logging automatically
+ * @llm-rule AVOID: Manual scope selection - auto-detection handles most cases correctly
+ */
+function getScope() {
+    // Manual override wins (like auth module pattern)
+    const manual = process.env.VOILA_LOGGER_SCOPE?.toLowerCase();
+    if (manual === 'minimal' || manual === 'full') {
+        return manual;
+    }
+    // Auto-detection logic
+    if (process.env.CI)
+        return 'minimal'; // CI/CD pipelines
+    if (process.env.NODE_ENV === 'production')
+        return 'minimal'; // Production efficiency
+    if (process.env.DEBUG || process.env.VOILA_DEBUG)
+        return 'full'; // Debug sessions
+    return 'minimal'; // Safe default for clean logs
+}
+/**
+ * Auto-detect appropriate log level
+ * @llm-rule WHEN: Need to set log level based on environment automatically
+ * @llm-rule AVOID: Hardcoding log levels - environment-based detection is better
+ */
+function getLevel(isProduction, isDevelopment) {
+    // Manual override wins (like auth module)
+    const manual = process.env.VOILA_LOGGER_LEVEL?.toLowerCase();
+    if (manual && ['debug', 'info', 'warn', 'error'].includes(manual)) {
+        return manual;
+    }
+    // Smart defaults based on environment
+    if (isProduction)
+        return 'warn'; // Production: only warnings and errors
+    if (isDevelopment)
+        return 'debug'; // Development: everything
+    return 'info'; // Test and others: standard
+}
+/**
+ * Auto-detect enabled transports from environment
+ * @llm-rule WHEN: Need to determine which transports to enable automatically
+ * @llm-rule AVOID: Manual transport configuration - auto-detection prevents errors
+ * @llm-rule NOTE: DATABASE_URL auto-enables database, WEBHOOK_URL auto-enables webhooks
+ */
+function getEnabledTransports(isTest) {
+    return {
+        // Console: default on (except test)
+        console: process.env.VOILA_LOGGER_CONSOLE !== 'false' && !isTest,
+        // File: default on (except test)
+        file: process.env.VOILA_LOGGER_FILE !== 'false' && !isTest,
+        // Database: auto-enable if DATABASE_URL exists
+        database: process.env.VOILA_LOGGER_DATABASE === 'true' && !!process.env.DATABASE_URL,
+        // HTTP: auto-enable if URL provided
+        http: !!process.env.VOILA_LOGGER_HTTP_URL,
+        // Webhook: auto-enable if URL provided
+        webhook: !!process.env.VOILA_LOGGER_WEBHOOK_URL,
+    };
+}
+/**
+ * Validate environment variables (like auth module validation)
+ * @llm-rule WHEN: App startup to catch configuration errors early
+ * @llm-rule AVOID: Skipping validation - invalid config causes silent failures
+ */
+export function validateEnvironment() {
+    // Validate log level
+    const level = process.env.VOILA_LOGGER_LEVEL;
+    if (level && !['debug', 'info', 'warn', 'error'].includes(level)) {
+        throw new Error(`Invalid VOILA_LOGGER_LEVEL: "${level}". Must be: debug, info, warn, error`);
+    }
+    // Validate scope
+    const scope = process.env.VOILA_LOGGER_SCOPE;
+    if (scope && !['minimal', 'full'].includes(scope.toLowerCase())) {
+        throw new Error(`Invalid VOILA_LOGGER_SCOPE: "${scope}". Must be: minimal, full`);
+    }
+    // Validate visual errors setting
+    const visualErrors = process.env.VOILA_VISUAL_ERRORS;
+    if (visualErrors && !['true', 'false'].includes(visualErrors)) {
+        throw new Error(`Invalid VOILA_VISUAL_ERRORS: "${visualErrors}". Must be: true, false`);
+    }
+    // Validate URLs if provided
+    const httpUrl = process.env.VOILA_LOGGER_HTTP_URL;
+    if (httpUrl && !isValidUrl(httpUrl)) {
+        throw new Error(`Invalid VOILA_LOGGER_HTTP_URL: "${httpUrl}"`);
+    }
+    const webhookUrl = process.env.VOILA_LOGGER_WEBHOOK_URL;
+    if (webhookUrl && !isValidUrl(webhookUrl)) {
+        throw new Error(`Invalid VOILA_LOGGER_WEBHOOK_URL: "${webhookUrl}"`);
+    }
+    // Validate database URL if database logging enabled
+    const dbEnabled = process.env.VOILA_LOGGER_DATABASE === 'true';
+    const dbUrl = process.env.DATABASE_URL;
+    if (dbEnabled && !dbUrl) {
+        throw new Error('VOILA_LOGGER_DATABASE=true but DATABASE_URL not provided');
+    }
+    if (dbUrl && !isValidDatabaseUrl(dbUrl)) {
+        throw new Error(`Invalid DATABASE_URL: "${dbUrl}"`);
+    }
+    // Validate numeric values
+    validateNumericEnv('VOILA_LOGGER_FILE_SIZE', 1000000, 100000000); // 1MB to 100MB
+    validateNumericEnv('VOILA_LOGGER_FILE_RETENTION', 1, 365); // 1 to 365 days
+    validateNumericEnv('VOILA_LOGGER_HTTP_TIMEOUT', 1000, 300000); // 1s to 5min
+}
+/**
+ * Validate numeric environment variable
+ */
+function validateNumericEnv(name, min, max) {
+    const value = process.env[name];
+    if (!value)
+        return;
+    const num = parseInt(value);
+    if (isNaN(num) || num < min || num > max) {
+        throw new Error(`Invalid ${name}: "${value}". Must be number between ${min} and ${max}`);
+    }
+}
+/**
+ * Validate URL format (like auth module)
+ */
+function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate database URL format
+ */
+function isValidDatabaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const validProtocols = ['postgres:', 'postgresql:', 'mysql:', 'sqlite:'];
+        return validProtocols.includes(parsed.protocol);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=defaults.js.map

package/dist/logger/defaults.js.map

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

package/dist/logger/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Ultra-simple logging that just works with enterprise features and enhanced error display
+ * @module @bloomneo/appkit/logger
+ * @file src/logger/index.ts
+ *
+ * @llm-rule WHEN: Need logging in any app - console, files, database, external services
+ * @llm-rule AVOID: Using console.log directly - this provides structured logging with levels
+ * @llm-rule NOTE: Uses loggerClass.get() pattern like auth - get() → log.info() → done
+ * @llm-rule NOTE: Enhanced error() method now provides automatic visual formatting in development
+ */
+export interface LogMeta {
+    [key: string]: any;
+}
+export interface Logger {
+    info(message: string, meta?: LogMeta): void;
+    error(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    debug(message: string, meta?: LogMeta): void;
+    child(bindings: LogMeta): Logger;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Get logger instance - the only function you need to learn
+ * @llm-rule WHEN: Starting any logging operation - this is your main entry point
+ * @llm-rule AVOID: Creating LoggerClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get() → info/error/warn/debug() → automatic transport
+ * @llm-rule NOTE: error() method now automatically provides visual formatting when appropriate
+ */
+declare function get(component?: string): Logger;
+/**
+ * Clear all loggers and close transports - essential for testing
+ * @llm-rule WHEN: Testing logging logic with different configurations
+ * @llm-rule AVOID: Using in production - only for tests and cleanup
+ */
+declare function clear(): Promise<void>;
+/**
+ * Get active transport names for debugging
+ * @llm-rule WHEN: Need to see which transports are running (console, file, database, etc)
+ * @llm-rule AVOID: Using for business logic - this is for debugging only
+ */
+declare function getActiveTransports(): string[];
+/**
+ * Check if specific transport is active
+ * @llm-rule WHEN: Conditionally logging based on transport availability
+ * @llm-rule AVOID: Complex transport detection - just log normally, transports auto-enable
+ */
+declare function hasTransport(name: string): boolean;
+/**
+ * Get current configuration for debugging
+ * @llm-rule WHEN: Debugging logging setup or checking environment detection
+ * @llm-rule AVOID: Using for runtime decisions - configuration is set at startup
+ */
+declare function getConfig(): {
+    level: "error" | "warn" | "info" | "debug";
+    scope: "minimal" | "full";
+    minimal: boolean;
+    transports: string[];
+    service: {
+        name: string;
+        version: string;
+        environment: string;
+    };
+    environment: {
+        NODE_ENV: string | undefined;
+        hasDbUrl: boolean;
+        hasHttpUrl: boolean;
+        hasWebhookUrl: boolean;
+    };
+} | null;
+/**
+ * Single logger export with minimal API (like auth module)
+ */
+export declare const loggerClass: {
+    readonly get: typeof get;
+    readonly clear: typeof clear;
+    readonly getActiveTransports: typeof getActiveTransports;
+    readonly hasTransport: typeof hasTransport;
+    readonly getConfig: typeof getConfig;
+};
+export type { LoggingConfig } from './defaults.js';
+export { LoggerClass } from './logger.js';
+export default loggerClass;
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,MAAM,WAAW,OAAO;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,iBAAS,GAAG,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBvC;AAED;;;;GAIG;AACH,iBAAe,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAMpC;AAED;;;;GAIG;AACH,iBAAS,mBAAmB,IAAI,MAAM,EAAE,CAKvC;AAED;;;;GAIG;AACH,iBAAS,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAK3C;AAED;;;;GAIG;AACH,iBAAS,SAAS;;;;;;;;;;;;;;;;SAKjB;AAED;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;CASd,CAAC;AAGX,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,eAAe,WAAW,CAAC"}

package/dist/logger/index.js

@@ -0,0 +1,101 @@
+/**
+ * Ultra-simple logging that just works with enterprise features and enhanced error display
+ * @module @bloomneo/appkit/logger
+ * @file src/logger/index.ts
+ *
+ * @llm-rule WHEN: Need logging in any app - console, files, database, external services
+ * @llm-rule AVOID: Using console.log directly - this provides structured logging with levels
+ * @llm-rule NOTE: Uses loggerClass.get() pattern like auth - get() → log.info() → done
+ * @llm-rule NOTE: Enhanced error() method now provides automatic visual formatting in development
+ */
+import { LoggerClass } from './logger.js';
+import { getSmartDefaults } from './defaults.js';
+// Global logger instances for performance (like auth module)
+let globalLogger = null;
+const namedLoggers = new Map();
+/**
+ * Get logger instance - the only function you need to learn
+ * @llm-rule WHEN: Starting any logging operation - this is your main entry point
+ * @llm-rule AVOID: Creating LoggerClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get() → info/error/warn/debug() → automatic transport
+ * @llm-rule NOTE: error() method now automatically provides visual formatting when appropriate
+ */
+function get(component) {
+    // Lazy initialization - parse environment once (like auth)
+    if (!globalLogger) {
+        const config = getSmartDefaults();
+        globalLogger = new LoggerClass(config);
+    }
+    // Return main logger if no component specified
+    if (!component) {
+        return globalLogger;
+    }
+    // Return cached or create new child logger
+    if (namedLoggers.has(component)) {
+        return namedLoggers.get(component);
+    }
+    const childLogger = globalLogger.child({ component });
+    namedLoggers.set(component, childLogger);
+    return childLogger;
+}
+/**
+ * Clear all loggers and close transports - essential for testing
+ * @llm-rule WHEN: Testing logging logic with different configurations
+ * @llm-rule AVOID: Using in production - only for tests and cleanup
+ */
+async function clear() {
+    if (globalLogger) {
+        await globalLogger.close();
+        globalLogger = null;
+    }
+    namedLoggers.clear();
+}
+/**
+ * Get active transport names for debugging
+ * @llm-rule WHEN: Need to see which transports are running (console, file, database, etc)
+ * @llm-rule AVOID: Using for business logic - this is for debugging only
+ */
+function getActiveTransports() {
+    if (!globalLogger) {
+        return [];
+    }
+    return globalLogger.getActiveTransports();
+}
+/**
+ * Check if specific transport is active
+ * @llm-rule WHEN: Conditionally logging based on transport availability
+ * @llm-rule AVOID: Complex transport detection - just log normally, transports auto-enable
+ */
+function hasTransport(name) {
+    if (!globalLogger) {
+        return false;
+    }
+    return globalLogger.hasTransport(name);
+}
+/**
+ * Get current configuration for debugging
+ * @llm-rule WHEN: Debugging logging setup or checking environment detection
+ * @llm-rule AVOID: Using for runtime decisions - configuration is set at startup
+ */
+function getConfig() {
+    if (!globalLogger) {
+        return null;
+    }
+    return globalLogger.getConfig();
+}
+/**
+ * Single logger export with minimal API (like auth module)
+ */
+export const loggerClass = {
+    // Core method (like auth.get())
+    get,
+    // Utility methods
+    clear,
+    getActiveTransports,
+    hasTransport,
+    getConfig,
+};
+export { LoggerClass } from './logger.js';
+// Default export
+export default loggerClass;
+//# sourceMappingURL=index.js.map

package/dist/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,6DAA6D;AAC7D,IAAI,YAAY,GAAuB,IAAI,CAAC;AAC5C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;AAgBpD;;;;;;GAMG;AACH,SAAS,GAAG,CAAC,SAAkB;IAC7B,2DAA2D;IAC3D,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAClC,YAAY,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,+CAA+C;IAC/C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,2CAA2C;IAC3C,IAAI,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,OAAO,YAAY,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;IACtC,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IACtD,YAAY,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACzC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,KAAK;IAClB,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,YAAY,CAAC,KAAK,EAAE,CAAC;QAC3B,YAAY,GAAG,IAAI,CAAC;IACtB,CAAC;IACD,YAAY,CAAC,KAAK,EAAE,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,YAAY,CAAC,mBAAmB,EAAE,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,YAAY,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS;IAChB,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,YAAY,CAAC,SAAS,EAAE,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,gCAAgC;IAChC,GAAG;IAEH,kBAAkB;IAClB,KAAK;IACL,mBAAmB;IACnB,YAAY;IACZ,SAAS;CACD,CAAC;AAIX,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,iBAAiB;AACjB,eAAe,WAAW,CAAC"}

package/dist/logger/logger.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Core logger class with visual error display and simplified transport management
+ * @module @bloomneo/appkit/logger
+ * @file src/logger/logger.ts
+ *
+ * @llm-rule WHEN: Building logger instances - called via loggerClass.get(), not directly
+ * @llm-rule AVOID: Creating LoggerClass directly - always use loggerClass.get() for proper setup
+ * @llm-rule NOTE: Enhanced error() method provides automatic visual formatting for better DX
+ */
+import type { LoggingConfig } from './defaults.js';
+import type { LogMeta, Logger } from './index.js';
+export interface LogEntry {
+    timestamp: string;
+    level: 'debug' | 'info' | 'warn' | 'error';
+    message: string;
+    [key: string]: any;
+}
+export interface Transport {
+    write(entry: LogEntry): void | Promise<void>;
+    shouldLog?(level: string, configLevel: string): boolean;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+export interface ErrorDiagnostic {
+    type: 'warning' | 'error' | 'info' | 'success';
+    message: string;
+    fix?: string;
+}
+/**
+ * Logger class with automatic transport management and enhanced error() method
+ */
+export declare class LoggerClass implements Logger {
+    private level;
+    private levelValue;
+    private defaultMeta;
+    private config;
+    private transports;
+    private pendingWrites;
+    constructor(config: LoggingConfig);
+    private initializeTransports;
+    /**
+     * Log informational message
+     * @llm-rule WHEN: Normal application events, user actions, business logic flow
+     * @llm-rule AVOID: Sensitive data in meta - passwords, tokens, full card numbers
+     */
+    info(message: string, meta?: LogMeta): void;
+    /**
+     * Enhanced error logging with automatic visual formatting
+     * @llm-rule WHEN: Exceptions, failures, critical issues requiring attention
+     * @llm-rule AVOID: Using for warnings - errors should indicate actual problems
+     * @llm-rule NOTE: Automatically provides visual formatting in development with smart diagnostics
+     */
+    error(message: string, meta?: LogMeta): void;
+    /**
+     * Log warning message
+     * @llm-rule WHEN: Potential issues, deprecated usage, performance concerns
+     * @llm-rule AVOID: Using for normal recoverable errors - use error() for those
+     */
+    warn(message: string, meta?: LogMeta): void;
+    /**
+     * Log debug message
+     * @llm-rule WHEN: Development debugging, detailed flow information
+     * @llm-rule AVOID: Production debug spam - automatically filtered in production
+     */
+    debug(message: string, meta?: LogMeta): void;
+    /**
+     * Create child logger with additional context
+     * @llm-rule WHEN: Adding component context or request-specific data
+     * @llm-rule AVOID: Creating many child loggers - reuse component loggers
+     */
+    child(bindings: LogMeta): LoggerClass;
+    private shouldShowVisual;
+    private renderVisualError;
+    /**
+     * Wrap long error messages with proper indentation and path handling
+     * @param message - The message to wrap
+     * @param prefix - The prefix (like "❌ ERROR:" or "✗") to account for in width
+     */
+    private wrapErrorMessage;
+    /**
+     * Preprocess message to handle very long paths and URLs intelligently
+     */
+    private preprocessLongPaths;
+    /**
+     * Strip ANSI color codes to get actual text length
+     */
+    private stripAnsiCodes;
+    private detectErrorType;
+    private detectImportVsSyntax;
+    private getErrorTitle;
+    private generateDiagnostics;
+    private getFixMessage;
+    /**
+     * Get contextual solutions based on error message patterns
+     */
+    private getSolutions;
+    private getCaller;
+    private log;
+    private writeToTransports;
+    /**
+     * Flush pending logs to all transports
+     * @llm-rule WHEN: App shutdown or ensuring logs are persisted before critical operations
+     * @llm-rule AVOID: Frequent flushing during normal operations - impacts performance
+     */
+    flush(): Promise<void>;
+    /**
+     * Close logger and cleanup all transports
+     * @llm-rule WHEN: App shutdown or logger cleanup - ensures graceful resource cleanup
+     * @llm-rule AVOID: Calling during normal operations - this permanently closes the logger
+     */
+    close(): Promise<void>;
+    /**
+     * Get list of active transport names
+     * @llm-rule WHEN: Debugging logger setup or checking which transports are running
+     * @llm-rule AVOID: Using for business logic - this is for debugging and monitoring only
+     */
+    getActiveTransports(): string[];
+    /**
+     * Check if specific transport is active
+     * @llm-rule WHEN: Conditionally logging based on transport availability
+     * @llm-rule AVOID: Complex transport detection - just log normally, transports auto-enable
+     */
+    hasTransport(name: string): boolean;
+    /**
+     * Set minimum log level dynamically
+     * @llm-rule WHEN: Runtime log level changes, debugging, or feature flags
+     * @llm-rule AVOID: Frequent level changes - impacts performance
+     */
+    setLevel(level: 'debug' | 'info' | 'warn' | 'error'): void;
+    /**
+     * Get current minimum log level
+     * @llm-rule WHEN: Debugging configuration or checking level settings
+     * @llm-rule AVOID: Using for filtering logic - logger handles level filtering automatically
+     */
+    getLevel(): string;
+    /**
+     * Check if specific log level would be written
+     * @llm-rule WHEN: Expensive log message preparation - check before building complex meta
+     * @llm-rule AVOID: Normal logging - level filtering is automatic and fast
+     */
+    isLevelEnabled(level: 'debug' | 'info' | 'warn' | 'error'): boolean;
+    /**
+     * Get current logger configuration for debugging
+     * @llm-rule WHEN: Debugging logger setup, checking environment detection, or monitoring
+     * @llm-rule AVOID: Using for runtime business logic - configuration is set at startup
+     */
+    getConfig(): {
+        level: "error" | "warn" | "info" | "debug";
+        scope: "minimal" | "full";
+        minimal: boolean;
+        transports: string[];
+        service: {
+            name: string;
+            version: string;
+            environment: string;
+        };
+        environment: {
+            NODE_ENV: string | undefined;
+            hasDbUrl: boolean;
+            hasHttpUrl: boolean;
+            hasWebhookUrl: boolean;
+        };
+    };
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger/logger.d.ts.map

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