@kosdev-code/kos-ui-sdk 2.0.44 → 2.0.45

package/models/models/key-value/types/index.d.ts

@@ -1,3 +1,60 @@
+/**
+ * Configuration options for creating KeyValue model instances.
+ *
+ * The namespace option allows you to create isolated key-value stores that don't
+ * interfere with each other, even when using the same keys. This is essential for
+ * organizing different types of data and preventing key collisions.
+ *
+ * @example Default Namespace
+ * ```typescript
+ * // Uses default 'studio' namespace
+ * const store = KeyValue.instance('my-store')
+ *   .options({})
+ *   .build();
+ * ```
+ *
+ * @example Custom Namespace
+ * ```typescript
+ * // Create isolated stores with custom namespaces
+ * const userStore = KeyValue.instance('user')
+ *   .options({ namespace: 'user-data' })
+ *   .build();
+ *
+ * const appStore = KeyValue.instance('app')
+ *   .options({ namespace: 'app-state' })
+ *   .build();
+ *
+ * // Same key, different namespaces = no collision
+ * await userStore.updateState('id', 'user-123');
+ * await appStore.updateState('id', 'app-456');
+ * ```
+ *
+ * @example Namespace Conventions
+ * ```typescript
+ * // Recommended namespace patterns
+ * const examples: KeyValueOptions[] = [
+ *   { namespace: 'user-preferences' },     // User-specific settings
+ *   { namespace: 'application-state' },    // Global app state
+ *   { namespace: 'feature-flags' },        // Feature toggles
+ *   { namespace: 'session-data' },         // Session-specific data
+ *   { namespace: 'cache-layer' },          // Cached API responses
+ *   { namespace: 'dev-tools' }             // Development/debug data
+ * ];
+ * ```
+ *
+ * @kosService core.key-value
+ * @group KOS Model
+ * @category Data Persistence
+ * @category Key-Value Store
+ */
 export interface KeyValueOptions {
+  /**
+   * Namespace for the key-value store to prevent key collisions between different stores.
+   *
+   * Defaults to 'studio' if not specified. Choose descriptive namespaces that clearly
+   * indicate the purpose of the stored data.
+   *
+   * @default 'studio'
+   */
   namespace?: string;
 }

package/models/models/kos-expression-evaluator/index.d.ts

@@ -0,0 +1,4 @@
+export type { KosExpressionEvaluatorModel, KosExpressionEvaluatorModelImpl, ExpressionResult, NamedExpression, } from './kos-expression-evaluator-model';
+export type * from './types';
+export declare const KosExpressionEvaluator: import('../../..').KosModelRegistrationType<import('./kos-expression-evaluator-model').KosExpressionEvaluatorModel<string>, import('./types').KosExpressionEvaluatorOptions>;
+//# sourceMappingURL=index.d.ts.map

package/models/models/kos-expression-evaluator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/index.ts"],"names":[],"mappings":"AAEA,YAAY,EACV,2BAA2B,EAC3B,+BAA+B,EAC/B,gBAAgB,EAChB,eAAe,GAChB,MAAM,kCAAkC,CAAC;AAC1C,mBAAmB,SAAS,CAAC;AAE7B,eAAO,MAAM,sBAAsB,8KACW,CAAC"}

package/models/models/kos-expression-evaluator/kos-expression-evaluator-model.d.ts

@@ -0,0 +1,209 @@
+import { KosExpressionEvaluatorOptions } from './types';
+import { PublicModelInterface } from '../../../core/types';
+import { IKosIdentifiable } from '../../../core/core/types';
+import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
+import { KosModelRegistrationType } from '../../../core';
+
+export declare const MODEL_TYPE = "kos-expression-evaluator-model";
+/**
+ * Result of evaluating an expression, containing either a successful value or error details.
+ *
+ * @example
+ * ```typescript
+ * const result = evaluator.getExpressionValue('myExpression');
+ * if (result?.error) {
+ *   console.error(`Expression error: ${result.error}`);
+ * } else {
+ *   console.log(`Result: ${result?.value}`);
+ * }
+ * ```
+ */
+export interface ExpressionResult {
+    /** The computed value of the expression, or undefined if evaluation failed */
+    value: unknown;
+    /** Error message if expression evaluation failed, undefined if successful */
+    error?: string;
+}
+export interface NamedExpression {
+    /** Unique name identifier for this expression */
+    name: string;
+    /** The expression string (JavaScript-like syntax) */
+    expression: string;
+    /** Getter that returns the cached result */
+    get result(): ExpressionResult;
+    /** Method to evaluate the expression with given context data */
+    evaluate(contextData: Record<string, unknown>): ExpressionResult;
+    /** Method to update the cached result */
+    updateResult(result: ExpressionResult): void;
+}
+/**
+ * KOS Expression Evaluator Model - Reactive expression evaluation with dynamic context and type-safe named expressions.
+ *
+ * This model provides a reactive expression evaluation system that automatically re-evaluates
+ * expressions when their context data changes. Perfect for business rules, computed values,
+ * and conditional logic that needs to stay synchronized with changing data.
+ *
+ * ## Key Features
+ * - **Automatic reactivity** - Expressions re-evaluate when dependencies change thanks to KOS reactive patterns
+ * - **Type safety** - Generic type parameter provides compile-time checking for expression names
+ * - **Efficient updates** - Only affected expressions recalculate when their data dependencies change
+ * - **Synchronous access** - Results available immediately via getters
+ * - **Error handling** - Expressions with runtime errors are handled gracefully
+ * - **KOS model integration** - Add any KOS model to context for fully reactive expressions
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const evaluator = KosExpressionEvaluatorModel.instance('my-evaluator').build();
+ *
+ * evaluator.setContextData({ temperature: 72, humidity: 45 });
+ * evaluator.addExpression('isComfortable', 'temperature >= 68 && temperature <= 78');
+ *
+ * console.log(evaluator.results.isComfortable?.value); // true
+ * ```
+ *
+ * @group KOS Model
+ * @category Expression Processing
+ * @useDeclaredType
+ */
+export type KosExpressionEvaluatorModel<T extends string = string> = PublicModelInterface<KosExpressionEvaluatorModelImpl<T>>;
+/**
+ * @ignore
+ * @internal
+ */
+export declare class KosExpressionEvaluatorModelImpl<T extends string = string> implements IKosDataModel, IKosIdentifiable {
+    static Registration: KosModelRegistrationType<KosExpressionEvaluatorModel, KosExpressionEvaluatorOptions>;
+    id: string;
+    private logger;
+    private parser;
+    private _data;
+    private _expressions;
+    private _results;
+    private _contextRevision;
+    constructor(modelId: string, _options: KosExpressionEvaluatorOptions, context: KosCreationContext);
+    /**
+     * Get the current context data that expressions are evaluated against.
+     *
+     * @returns The current context data as a record of key-value pairs
+     */
+    get data(): Record<string, unknown>;
+    get contextRevision(): number;
+    /**
+     * Replace the entire context data with new values. All expressions will
+     * automatically re-evaluate against the new context.
+     *
+     * @param newData - Complete new context data to replace existing data
+     *
+     * @example
+     * ```typescript
+     * evaluator.setContextData({ temperature: 75, humidity: 40 });
+     * ```
+     */
+    setContextData(newData: Record<string, unknown>): void;
+    /**
+     * Update a single value in the context data. All expressions using this
+     * value will automatically re-evaluate.
+     *
+     * @param key - The context data key to update
+     * @param value - The new value to set
+     *
+     * @example
+     * ```typescript
+     * evaluator.updateContextValue('temperature', 85);
+     * ```
+     */
+    updateContextValue(key: string, value: unknown): void;
+    /**
+     * Update a nested property in the context data using dot notation.
+     * This method safely updates nested properties without replacing the entire object structure.
+     *
+     * @param path - Dot-separated path to the nested property (e.g., 'sensors.humidity', 'config.thresholds.temp')
+     * @param value - The new value to set at the nested path
+     *
+     * @example
+     * ```typescript
+     * evaluator.updateNestedValue('sensors.humidity', 60);
+     * ```
+     */
+    updateNestedValue(path: string, value: unknown): void;
+    /**
+     * Add a KOS model to the evaluation context. The model's observable properties
+     * will be accessible via dotted notation and expressions will automatically
+     * re-evaluate when the model's data changes.
+     *
+     * @param key - The context key to store the model under
+     * @param model - Any KOS model instance (must be observable)
+     *
+     * @example
+     * ```typescript
+     * const sensorModel = SensorModel.instance('main-sensor').build();
+     * evaluator.addModelToContext('sensor', sensorModel);
+     * evaluator.addExpression('isCritical', 'sensor.temperature > 80');
+     * ```
+     */
+    addModelToContext(key: string, model: unknown): void;
+    /**
+     * Add a named expression that will be automatically evaluated against context data.
+     * The expression will re-evaluate whenever its dependencies in the context change.
+     *
+     * @param name - Unique identifier for this expression (type-safe when using generic)
+     * @param expressionString - JavaScript-like expression string
+     * @throws {Error} If the expression has invalid syntax
+     *
+     * @example
+     * ```typescript
+     * evaluator.addExpression('isHot', 'temperature > 80');
+     * ```
+     */
+    addExpression(name: T, expressionString: string): void;
+    removeExpression(name: T): boolean;
+    getExpression(name: T): NamedExpression | undefined;
+    getExpressionValue(name: T): ExpressionResult | undefined;
+    /**
+     * Get the cached result of an expression without triggering re-evaluation.
+     * This is useful for dependency tracking in effects where you want to avoid
+     * creating reactive chains through the expression evaluation.
+     *
+     * @param name - The expression name to get the cached result for
+     * @returns The last cached result, or undefined if expression doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const cached = evaluator.getCachedExpressionValue('myExpression');
+     * ```
+     */
+    getCachedExpressionValue(name: T): ExpressionResult | undefined;
+    get expressions(): NamedExpression[];
+    get expressionNames(): T[];
+    get results(): Record<T, ExpressionResult>;
+    /**
+     * Force re-evaluation of all expressions and update cached results.
+     * This is called by the effect when context data changes.
+     */
+    private evaluateAllExpressions;
+    /**
+     * Evaluate a specific expression and update the cached result if it changed.
+     */
+    private evaluateExpression;
+    /**
+     * Internal method to update the results object when expression values change.
+     * This is called by ReactiveExpression when its value changes.
+     * ObservableData handles dynamic properties automatically with MobX atoms.
+     */
+    private updateResult;
+    /**
+     * Create an anonymous reactive expression and return its generated ID.
+     * The expression becomes fully reactive and can be accessed via the returned ID.
+     *
+     * @param expressionString - JavaScript-like expression string
+     * @returns Generated UUID that can be used to access the expression via `getExpressionValue(id)` or `results[id]`
+     *
+     * @example
+     * ```typescript
+     * const tempCheckId = evaluator.createExpression('temperature > 75');
+     * const result = evaluator.getExpressionValue(tempCheckId);
+     * ```
+     */
+    createExpression(expressionString: string): string;
+}
+//# sourceMappingURL=kos-expression-evaluator-model.d.ts.map

package/models/models/kos-expression-evaluator/kos-expression-evaluator-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-expression-evaluator-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/kos-expression-evaluator-model.ts"],"names":[],"mappings":"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"}

package/models/models/kos-expression-evaluator/services/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * KOS Expression Evaluator Services
+ *
+ * No services are exported as this is a local computation model.
+ */
+//# sourceMappingURL=index.d.ts.map

package/models/models/kos-expression-evaluator/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.d.ts

@@ -0,0 +1,15 @@
+/**
+ * KOS Expression Evaluator Services
+ *
+ * The Expression Evaluator model is a purely computational model that performs
+ * local expression evaluation against context data. It does not require any
+ * HTTP services or external API calls.
+ *
+ * All functionality is self-contained within the model using:
+ * - expr-eval library for expression parsing and evaluation
+ * - KOS reactive patterns for automatic re-evaluation
+ * - Local context data storage
+ *
+ * No external services are needed.
+ */
+//# sourceMappingURL=kos-expression-evaluator-services.d.ts.map

package/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-expression-evaluator-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-expression-evaluator/services/kos-expression-evaluator-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/models/models/kos-expression-evaluator/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration options for KosExpressionEvaluator model instances.
+ *
+ * @kosService core.kos-expression-evaluator
+ */
+export interface KosExpressionEvaluatorOptions {}

package/models/models/kos-log-manager/kos-log-manager-model.d.ts

@@ -10,23 +10,68 @@ import { KosRequest, KosResponse } from '../../../core';
  */
 export declare const MODEL_TYPE = "kos-log-manager-model";
 /**
- * Public interface for the KOS Log Manager Model.
- * Provides runtime log level management capabilities for the KOS UI SDK.
- */
-export type KosLogManagerModel = PublicModelInterface<KosLogManagerModelImpl>;
-/**
- * Implementation of the KOS Log Manager Model.
+ * KOS Log Manager Model - Centralized runtime log level management for the entire KOS system.
+ *
+ * This singleton model provides comprehensive control over logging behavior across the KOS UI SDK
+ * and connected applications. It manages dynamic log level overrides, responds to real-time
+ * configuration changes, and provides both REST API and WebSocket interfaces for log management.
+ * Essential for debugging, performance monitoring, and production troubleshooting.
+ *
+ * ## Key Features
+ * - **Runtime Log Level Control** - Dynamically adjust log levels without application restart
+ * - **Hierarchical Logger Management** - Apply overrides to parent loggers and all children
+ * - **Real-time Configuration** - WebSocket-based updates propagate instantly across clients
+ * - **REST API Integration** - Query and manage logger configurations via HTTP endpoints
+ * - **Override Persistence** - Log overrides are maintained across sessions and page refreshes
+ * - **Multi-Node Support** - Coordinate logging across different KOS device nodes
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to these KOS topics for real-time log management:
+ * - **`/kos/logs/override/add/*`** - Fired when new log level overrides are created
+ * - **`/kos/logs/override/remove/*`** - Fired when log level overrides are removed
+ *
+ * Both topics support wildcard capture for node type targeting, enabling precise
+ * control over which device nodes receive logging configuration changes.
  *
- * This model manages log levels for different loggers in the KOS system,
- * allowing dynamic runtime configuration of logging verbosity.
+ * ## Architecture Integration
+ * The log manager integrates with the broader KOS logging ecosystem:
+ * - **KosLog System** - Manages underlying logger instances and level settings
+ * - **LogStreamModel** - Streams managed by this model's log level policies
+ * - **LogBlockModel** - Individual log entries governed by level settings
+ * - **REST Endpoints** - Provides `/api/kos/ui/loggers` for external access
  *
- * Key features:
- * - Maintains a collection of log level overrides
- * - Responds to WebSocket events for adding/removing log overrides
- * - Provides REST API endpoint for retrieving all logger configurations
- * - Automatically applies log level changes to matching loggers
+ * ## Common Use Cases
+ * - **Development Debugging** - Increase log verbosity for specific components during development
+ * - **Production Troubleshooting** - Temporarily enable debug logging to diagnose issues
+ * - **Performance Monitoring** - Adjust log levels to reduce overhead in production
+ * - **System Administration** - Centrally manage logging across distributed KOS deployments
+ * - **Dynamic Configuration** - Change logging behavior without service interruption
+ * - **Selective Logging** - Enable detailed logging for specific modules while keeping others quiet
  *
- * @kosModel Decorated as a KOS model with type 'kos-log-manager-model'
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const logManager = KosLogManager.instance('log-control').build();
+ *
+ * // Get all current logger configurations via REST API
+ * const loggers = await logManager.getAllLoggers();
+ * console.log(`Managing ${loggers.length} loggers`);
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamModel} - Streams whose content is governed by log levels managed here
+ * @see {@link LogBlockModel} - Individual log entries affected by level settings
+ * @see {@link KosLogManagerOptions} - Configuration options for the log manager
+ * @see {@link LogOverride} - Log level override structure for runtime control
+ * @see {@link LogLevelDescriptor} - Logger information structure returned by REST API
+ */
+export type KosLogManagerModel = PublicModelInterface<KosLogManagerModelImpl>;
+/**
+ * @ignore
+ * @internal
  */
 export declare class KosLogManagerModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
@@ -80,12 +125,14 @@ export declare class KosLogManagerModelImpl implements IKosDataModel, IKosIdenti
     /**
      * Initializes the log manager model.
      * Called during model creation lifecycle.
+     * @internal
      */
     init(): Promise<void>;
     /**
      * Loads existing log overrides from the server.
      * Fetches UI-specific overrides and applies them to the current loggers.
      * Called after model initialization.
+     * @internal
      */
     load(): Promise<void>;
 }

package/models/models/kos-log-manager/kos-log-manager-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-log-manager-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-log-manager/kos-log-manager-model.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAElB,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,UAAU,0BAA0B,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AA0B9E;;;;;;;;;;;;;GAaG;AACH,qBACa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,UAAU,CAAiC;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAU7B,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAMjD;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;OAMG;IAEG,aAAa,CACjB,IAAI,CAAC,EAAE,UAAU,EACjB,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOhC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;OAKG;IAMH,mBAAmB,CACjB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAWvC;;;;OAIG;IAMH,qBAAqB,CAAC,QAAQ,EAAE,WAAW;IAK3C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAsB5B"}
+{"version":3,"file":"kos-log-manager-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/kos-log-manager/kos-log-manager-model.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAElB,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,UAAU,0BAA0B,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AA2B9E;;;GAGG;AACH,qBACa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,UAAU,CAAiC;gBAEjD,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAU7B,WAAW,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAMjD;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAqBtB;;;;;;OAMG;IAEG,aAAa,CACjB,IAAI,CAAC,EAAE,UAAU,EACjB,GAAG,CAAC,EAAE,WAAW,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOhC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAwBpB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;OAKG;IAMH,mBAAmB,CACjB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAWvC;;;;OAIG;IAMH,qBAAqB,CAAC,QAAQ,EAAE,WAAW;IAK3C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAwB5B"}

package/models/models/kos-log-manager/types/index.d.ts

@@ -1,14 +1,205 @@
+/**
+ * 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;
 }