/**
 * Configuration options for KosLogManager model instances.
 *
 * Currently an empty interface but reserved for future log management
 * configuration options such as default log levels, override policies,
 * or persistence settings.
 *
 * @example Basic Log Manager Configuration
 * ```typescript
 * const options: KosLogManagerOptions = {
 *   // Future options will be added here
 * };
 *
 * const logManager = KosLogManager.instance('log-control')
 *   .options(options)
 *   .build();
 * ```
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
// eslint-disable-next-line @typescript-eslint/no-empty-interface
export interface KosLogManagerOptions {}

/**
 * Standard log level names supported by the KOS logging system.
 *
 * These correspond to common logging levels with increasing severity:
 * - trace: Most verbose, includes all debug information
 * - debug: Detailed information for debugging
 * - info: General information messages (default)
 * - warn: Warning messages about potential issues
 * - error: Error messages for serious problems
 *
 * @example Log Level Usage
 * ```typescript
 * const levels: LogLevelNames[] = ['trace', 'debug', 'info', 'warn', 'error'];
 *
 * // Set different levels for different components
 * const productionLevel: LogLevelNames = 'warn';
 * const developmentLevel: LogLevelNames = 'debug';
 * const troubleshootingLevel: LogLevelNames = 'trace';
 * ```
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export type LogLevelNames = "trace" | "debug" | "info" | "warn" | "error";

/**
 * Log level override configuration for runtime log management.
 *
 * Used to dynamically change log levels for specific loggers or logger hierarchies
 * without requiring application restart. Overrides are applied to the target logger
 * and all child loggers whose names start with the override name.
 *
 * @example Creating Log Overrides
 * ```typescript
 * // Enable debug logging for all models
 * const modelDebugOverride: LogOverride = {
 *   name: 'kos-ui-sdk.models',
 *   level: 'debug',
 *   type: 'UI',
 *   id: 'models-debug'
 * };
 *
 * // Enable error-only logging for performance
 * const performanceOverride: LogOverride = {
 *   name: 'kos-ui-sdk.services.heavy-computation',
 *   level: 'error',
 *   type: 'UI',
 *   id: 'perf-override'
 * };
 *
 * // Troubleshooting override for specific component
 * const troubleshootOverride: LogOverride = {
 *   name: 'kos-ui-sdk.models.log-stream',
 *   level: 'trace',
 *   type: 'UI',
 *   id: 'log-stream-debug'
 * };
 * ```
 *
 * @example Hierarchical Override Effects
 * ```typescript
 * // Setting 'kos-ui-sdk' affects all child loggers:
 * const rootOverride: LogOverride = {
 *   name: 'kos-ui-sdk',
 *   level: 'debug',
 *   type: 'UI',
 *   id: 'sdk-debug'
 * };
 *
 * // This affects:
 * // - kos-ui-sdk.models.log-stream
 * // - kos-ui-sdk.models.log-block
 * // - kos-ui-sdk.services.api
 * // - kos-ui-sdk.core.events
 * // ... and all other loggers starting with 'kos-ui-sdk'
 * ```
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export interface LogOverride {
  /**
   * Target log level to apply to the logger and its children.
   *
   * All loggers whose names start with the 'name' property will
   * be set to this level until the override is removed.
   */
  level: LogLevelNames;

  /**
   * Logger name or prefix to target for the override.
   *
   * The override applies to this exact logger name and all loggers
   * whose names start with this string. Use hierarchical naming
   * like 'kos-ui-sdk.models' to target groups of related loggers.
   */
  name: string;

  /**
   * Type of override, typically 'UI' for KOS UI SDK overrides.
   *
   * Used to categorize and filter overrides by their source or purpose.
   * Different types can be managed separately.
   */
  type: string;

  /**
   * Unique identifier for this override.
   *
   * Used to track and remove specific overrides. Should be unique
   * within the system to prevent conflicts.
   */
  id: string;
}

/**
 * Logger information descriptor returned by the log manager REST API.
 *
 * Provides the current state of a logger including its name and active log level.
 * Used for querying logger configurations and displaying current system state.
 *
 * @example Processing Logger Descriptors
 * ```typescript
 * // Get all loggers from the API
 * const loggers: LogLevelDescriptor[] = await logManager.getAllLoggers();
 *
 * // Analyze logging configuration
 * const debugLoggers = loggers.filter(l => l.level === 'debug');
 * const errorOnlyLoggers = loggers.filter(l => l.level === 'error');
 *
 * console.log(`${debugLoggers.length} loggers in debug mode`);
 * console.log(`${errorOnlyLoggers.length} loggers showing errors only`);
 *
 * // Find specific logger
 * const streamLogger = loggers.find(l => l.name.includes('log-stream'));
 * if (streamLogger) {
 *   console.log(`Log stream logger level: ${streamLogger.level}`);
 * }
 * ```
 *
 * @example Building Logger Management UI
 * ```typescript
 * // Use descriptors to build management interfaces
 * const LoggerList: React.FC<{ loggers: LogLevelDescriptor[] }> = ({ loggers }) => (
 *   <div className="logger-list">
 *     {loggers.map(logger => (
 *       <div key={logger.name} className="logger-item">
 *         <span className="logger-name">{logger.name}</span>
 *         <span className={`logger-level level-${logger.level}`}>
 *           {logger.level.toUpperCase()}
 *         </span>
 *       </div>
 *     ))}
 *   </div>
 * );
 * ```
 *
 * @kosService core.logging
 * @group KOS Model
 * @category Device Logging
 */
export interface LogLevelDescriptor {
  /**
   * Full name of the logger.
   *
   * Typically follows hierarchical naming conventions like
   * 'kos-ui-sdk.models.log-stream' or 'kos-ui-sdk.services.api'.
   */
  name: string;

  /**
   * Current active log level for this logger.
   *
   * Shows the effective level after all overrides have been applied.
   * This is the level that determines which log messages are actually output.
   */
  level: LogLevelNames;
}
