@kosdev-code/kos-ui-sdk 2.0.41 → 2.1.1

package/models/models/log-block/log-block-model.d.ts

@@ -4,7 +4,192 @@ import { IKosIdentifiable } from '../../../core/core/types';
 import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 
 export declare const MODEL_TYPE = "log-block-model";
+/**
+ * Log Block Model - Individual log data block management within streaming log systems.
+ *
+ * This model represents a single block of log data within a LogStreamModel, providing efficient
+ * memory management and organized access to log lines. Log blocks are the fundamental storage
+ * units that enable high-performance log streaming by breaking large log streams into
+ * manageable, sequential segments with precise line numbering and timing information.
+ *
+ * ## Key Features
+ * - **Block-based Storage** - Efficient memory usage through segmented log storage
+ * - **Line Management** - Precise line numbering with start/end tracking
+ * - **Time-based Organization** - Temporal ordering with start and end timestamps
+ * - **Dynamic Loading** - On-demand synchronization of log lines from source
+ * - **Incremental Updates** - Add new lines without full reload
+ * - **Stream Integration** - Seamless integration with LogStreamModel containers
+ *
+ * ## Architecture Relationship
+ * LogBlock works as a component within the broader log streaming architecture:
+ * - **LogStreamModel** contains multiple LogBlockModels via LogBlockContainerModel
+ * - **LogBlockContainerModel** manages and sorts blocks by block number
+ * - **LogBlockModel** stores the actual log lines and metadata for a specific segment
+ * - This design enables efficient memory usage and fast access to recent log data
+ *
+ * ## Common Use Cases
+ * - **Memory-efficient Log Storage** - Break large log streams into manageable blocks
+ * - **Sequential Log Access** - Navigate through log history by block
+ * - **Selective Loading** - Load only needed blocks for performance
+ * - **Log Line Management** - Add, retrieve, and manage individual log entries
+ * - **Time-based Log Analysis** - Filter and analyze logs by time ranges
+ * - **Stream Synchronization** - Keep log blocks synchronized with source streams
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * // Typically accessed through LogStreamModel, not created directly
+ * const logStream = LogStream.instance('app-logs')
+ *   .options({ name: 'application-logs', nodeId: 'primary' })
+ *   .build();
+ *
+ * await logStream.load();
+ *
+ * // Access blocks within the stream
+ * const blocks = logStream.blocks;
+ * const currentBlock = logStream.currentBlock;
+ *
+ * if (currentBlock) {
+ *   console.log(`Block ${currentBlock.blockNum}`);
+ *   console.log(`Lines: ${currentBlock.startLineNum}-${currentBlock.endLineNum}`);
+ *   console.log(`Time range: ${currentBlock.startTime} to ${currentBlock.endTime}`);
+ *   console.log(`Line count: ${currentBlock.lineCount}`);
+ * }
+ * ```
+ *
+ * @example Block Line Management
+ * ```typescript
+ * // Access through log stream
+ * const logStream = LogStream.instance('system-logs').build();
+ * const block = logStream.currentBlock;
+ *
+ * if (block) {
+ *   // Get current lines
+ *   console.log(`Block has ${block.lines.length} loaded lines`);
+ *
+ *   // Add new lines (typically done automatically by stream)
+ *   block.addLines(['New log entry 1', 'New log entry 2']);
+ *
+ *   // Sync with remote source
+ *   await block.syncLines();
+ *
+ *   // Process lines
+ *   block.lines.forEach((line, index) => {
+ *     const globalLineNum = block.startLineNum + index;
+ *     console.log(`Line ${globalLineNum}: ${line}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example Block Analysis and Filtering
+ * ```typescript
+ * // Analyze blocks within a stream
+ * const logStream = LogStream.instance('error-logs').build();
+ * await logStream.load();
+ *
+ * // Find blocks within a time range
+ * const startTime = new Date('2024-01-01T00:00:00Z');
+ * const endTime = new Date('2024-01-01T23:59:59Z');
+ *
+ * const blocksInRange = logStream.blocks.filter(block =>
+ *   block.startTime >= startTime && block.endTime <= endTime
+ * );
+ *
+ * console.log(`Found ${blocksInRange.length} blocks in date range`);
+ *
+ * // Process error logs from specific blocks
+ * for (const block of blocksInRange) {
+ *   await block.syncLines(); // Ensure lines are loaded
+ *
+ *   const errorLines = block.lines
+ *     .map((line, index) => ({ line, lineNum: block.startLineNum + index }))
+ *     .filter(({ line }) => line.includes('ERROR'));
+ *
+ *   if (errorLines.length > 0) {
+ *     console.log(`Block ${block.blockNum} has ${errorLines.length} errors`);
+ *     errorLines.forEach(({ line, lineNum }) => {
+ *       console.log(`Line ${lineNum}: ${line}`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Block Container Integration
+ * ```typescript
+ * // Access blocks through their container
+ * const logStream = LogStream.instance('debug-logs').build();
+ * const blockContainer = logStream.blocks; // This is a LogBlockContainerModel
+ *
+ * // Blocks are automatically sorted by block number
+ * const sortedBlocks = blockContainer.data;
+ * console.log(`Stream has ${sortedBlocks.length} blocks`);
+ *
+ * // Get specific block by ID
+ * const blockId = 'debug-logs-block-5';
+ * const specificBlock = blockContainer.getModel(blockId);
+ *
+ * if (specificBlock) {
+ *   console.log(`Block ${specificBlock.blockNum} loaded`);
+ *   await specificBlock.syncLines();
+ * }
+ *
+ * // Add new block to container (typically done automatically)
+ * const newBlockOptions: LogBlockOptions = {
+ *   nodeId: 'primary',
+ *   stream: 'debug-logs',
+ *   blockNum: 10,
+ *   startLineNum: 1000,
+ *   endLineNum: 1099,
+ *   startTime: new Date(),
+ *   endTime: new Date(Date.now() + 60000),
+ *   lineCount: 100
+ * };
+ *
+ * const newBlock = LogBlock.instance('debug-logs-block-10')
+ *   .options(newBlockOptions)
+ *   .build();
+ *
+ * blockContainer.addModel(newBlock);
+ * ```
+ *
+ * @example Block Update and Synchronization
+ * ```typescript
+ * const block = logStream.currentBlock;
+ *
+ * if (block) {
+ *   // Update block metadata (typically done by stream management)
+ *   const updatedOptions: LogBlockOptions = {
+ *     ...block,
+ *     endLineNum: block.endLineNum + 50,
+ *     endTime: new Date(),
+ *     lineCount: block.lineCount + 50
+ *   };
+ *
+ *   block.updateModel(updatedOptions);
+ *
+ *   // Sync to get new lines
+ *   await block.syncLines();
+ *
+ *   console.log(`Block now has ${block.lines.length} lines loaded`);
+ *   console.log(`Updated end time: ${block.endTime}`);
+ * }
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamModel} - Parent stream model that contains log blocks
+ * @see {@link LogBlockContainerModel} - Container that manages multiple log blocks
+ * @see {@link LogBlockOptions} - Configuration options for log block instances
+ * @see {@link LogBlockType} - Type definition for block data exchange
+ * @see {@link LogLinesType} - Type definition for line data with block metadata
+ */
 export type LogBlockModel = PublicModelInterface<LogBlockModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogBlockModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
     private logger;

package/models/models/log-block/log-block-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-block-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-model.ts"],"names":[],"mappings":"AACA,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,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,GAAG,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAiBvB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAehC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQ3C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAS5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"log-block-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-block/log-block-model.ts"],"names":[],"mappings":"AACA,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,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,UAAU,oBAAoB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoLG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;AAEpE;;;GAGG;AACH,qBACa,iBAAkB,YAAW,aAAa,EAAE,gBAAgB;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,GAAG,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,kBAAkB;IAiBvB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAehC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAQ3C,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAS5C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/models/models/log-block/types/index.d.ts

@@ -1,38 +1,167 @@
 // ---------------  LogBlock ---------------
 
+/**
+ * Configuration options for LogBlock model instances.
+ * 
+ * These options define the metadata and boundaries for a log block, including
+ * line numbering, timing information, and stream identification. Used when
+ * creating new log blocks or updating existing block metadata.
+ *
+ * @example Basic Configuration
+ * ```typescript
+ * const blockOptions: LogBlockOptions = {
+ *   nodeId: 'primary',
+ *   stream: 'application-logs',
+ *   blockNum: 5,
+ *   startLineNum: 401,
+ *   endLineNum: 500,
+ *   startTime: new Date('2024-01-01T10:00:00Z'),
+ *   endTime: new Date('2024-01-01T10:05:00Z'),
+ *   lineCount: 100
+ * };
+ * 
+ * const logBlock = LogBlock.instance('app-block-5')
+ *   .options(blockOptions)
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogBlockOptions {
+  /**
+   * Node identifier where the log block originates.
+   * 
+   * Specifies which KOS device node contains this log block.
+   * Used for routing and organization in multi-node environments.
+   */
   nodeId: string;
+  
+  /**
+   * Name of the log stream this block belongs to.
+   * 
+   * Identifies the parent stream that contains this block.
+   * Used for organization and cross-referencing with LogStreamModel.
+   */
   stream: string;
+  
+  /**
+   * Sequential block number within the stream.
+   * 
+   * Used for ordering blocks chronologically within a stream.
+   * Blocks are automatically sorted by this number in containers.
+   */
   blockNum: number;
+  
+  /**
+   * Global line number where this block starts.
+   * 
+   * The first line number in this block relative to the entire stream.
+   * Used for accurate line numbering across the complete log stream.
+   */
   startLineNum: number;
+  
+  /**
+   * Global line number where this block ends.
+   * 
+   * The last line number in this block relative to the entire stream.
+   * Used with startLineNum to define the block's line range.
+   */
   endLineNum: number;
+  
+  /**
+   * Timestamp when this log block period began.
+   * 
+   * Used for time-based filtering and analysis of log blocks.
+   */
   startTime: Date;
+  
+  /**
+   * Timestamp when this log block period ended.
+   * 
+   * Used with startTime to define the temporal range of the block.
+   */
   endTime: Date;
+  
+  /**
+   * Total number of log lines in this block.
+   * 
+   * Should equal (endLineNum - startLineNum + 1). Used for
+   * validation and progress tracking during block loading.
+   */
   lineCount: number;
 }
 
 // ---------------  LogBlockContainer ---------------
+
+/**
+ * Configuration options for LogBlockContainer model instances.
+ * 
+ * Currently an empty interface but reserved for future container-level
+ * configuration options such as block sorting preferences, memory limits,
+ * or automatic cleanup policies.
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface LogBlockContainerOptions {}
 
+/**
+ * Data exchange format for log block information from KOS topics.
+ * 
+ * Used in topic handlers for log block events, representing block metadata
+ * as received from the KOS system. Similar to LogBlockOptions but uses
+ * timestamp numbers instead of Date objects for serialization efficiency.
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogBlockType {
+  /** Node identifier where the log block originates */
   nodeId: string;
+  /** Name of the log stream this block belongs to */
   stream: string;
+  /** Sequential block number within the stream */
   blockNum: number;
+  /** Global line number where this block starts */
   startLineNum: number;
+  /** Global line number where this block ends */
   endLineNum: number;
+  /** Timestamp when this log block period began (milliseconds since epoch) */
   startTime: number;
+  /** Timestamp when this log block period ended (milliseconds since epoch) */
   endTime: number;
+  /** Total number of log lines in this block */
   lineCount: number;
 }
 
+/**
+ * Data exchange format for log lines with block metadata from KOS topics.
+ * 
+ * Used in topic handlers for log line events, containing both the actual
+ * log lines and the block metadata. Extends LogBlockType with the lines array.
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogLinesType {
+  /** Node identifier where the log block originates */
   nodeId: string;
+  /** Name of the log stream this block belongs to */
   stream: string;
+  /** Sequential block number within the stream */
   blockNum: number;
+  /** Global line number where this block starts */
   startLineNum: number;
+  /** Global line number where this block ends */
   endLineNum: number;
+  /** Timestamp when this log block period began (milliseconds since epoch) */
   startTime: number;
+  /** Timestamp when this log block period ended (milliseconds since epoch) */
   endTime: number;
+  /** Total number of log lines in this block */
   lineCount: number;
+  /** Array of actual log line strings */
   lines: string[];
 }

package/models/models/log-stream/index.d.ts

@@ -1,7 +1,11 @@
+export type { LogStreamContainerModel } from './log-stream-container-model';
 export { LogStreamContainer } from './log-stream-container-registration';
+export type { LogStreamModel } from './log-stream-model';
 export { LogStream } from './log-stream-registration';
 export type * from './types';
-export type { LogStreamModel } from './log-stream-model';
-export type { LogStreamContainerModel } from './log-stream-container-model';
+/**
+ * @group KOS Model
+ * @category Device Logging
+ */
 export * as LogStreamServices from './services';
 //# sourceMappingURL=index.d.ts.map

package/models/models/log-stream/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,mBAAmB,SAAS,CAAC;AAC7B,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,iBAAiB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,mBAAmB,SAAS,CAAC;AAC7B;;;GAGG;AACH,OAAO,KAAK,iBAAiB,MAAM,YAAY,CAAC"}

package/models/models/log-stream/log-stream-container-model.d.ts

@@ -7,11 +7,67 @@ import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 import { IKosModelContainer } from '../../../core/core/kos-container-model';
 
 export declare const MODEL_TYPE = "log-stream-container-model";
+/**
+ * Log Stream Container Model - Manages multiple log streams with real-time topic-based synchronization.
+ *
+ * This container model manages multiple LogStreamModel instances and handles real-time log events
+ * from the KOS system. It provides centralized management of log streams, automatic stream discovery,
+ * and coordinated event handling for efficient log processing across multiple sources.
+ *
+ * ## Topic-Based Reactivity
+ * The container listens to these KOS topics for real-time log management:
+ * - **`/kos/logs/subscription/addBlock/*`** - Fired when new log blocks are created
+ * - **`/kos/logs/subscription/updateBlock/*`** - Fired when existing log blocks are updated
+ * - **`/kos/logs/subscription/removeBlock/*`** - Fired when log blocks are removed
+ * - **`/kos/logs/subscription/lines/*`** - Fired when new log lines are added to blocks
+ * - **`/kos/logs/streams/add/*`** - Fired when new log streams are discovered
+ *
+ * ## Key Features
+ * - **Multi-stream Management** - Handle multiple log streams simultaneously
+ * - **Automatic Stream Discovery** - Automatically add new streams as they become available
+ * - **Topic-based Synchronization** - Real-time updates via KOS event system
+ * - **Stream Selection** - Track currently selected stream for UI purposes
+ * - **Block Management** - Coordinate block updates across all managed streams
+ *
+ * ## Common Use Cases
+ * - **Log Dashboard** - Central management of multiple log sources
+ * - **System Monitoring** - Monitor logs from all system components
+ * - **Debugging Interface** - Switch between different log streams during troubleshooting
+ * - **Log Aggregation** - Collect and manage logs from distributed sources
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const logContainer = LogStreamContainer.instance('main-logger')
+ *   .options({})
+ *   .build();
+ *
+ * // Subscribe to and manage multiple streams
+ * await logContainer.subscribeToLogStream('application-logs');
+ * const appStream = logContainer.getModel('application-logs');
+ * logContainer.updateSelectedStream(appStream);
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @interface
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamModel} - Individual log stream management
+ * @see {@link LogStreamContainerOptions} - Configuration options for the container
+ */
 export type LogStreamContainerModel = PublicModelInterface<LogStreamContainerModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogStreamContainerModelImpl implements IKosIdentifiable, IKosModelHolder<LogStreamModel>, IKosDataModel {
+    /** Unique identifier for the container model instance */
     id: string;
+    /** Context logger for debugging log stream operations */
     private logger;
+    /** Currently selected log stream for UI display purposes */
     selectedStream?: LogStreamModel;
+    /** Container for managing LogStream model instances */
     private _models;
     constructor(modelId: string, options: LogStreamContainerOptions, context: KosCreationContext);
     getModel(id: string): LogStreamModel | undefined;
@@ -28,8 +84,14 @@ export declare class LogStreamContainerModelImpl implements IKosIdentifiable, IK
     handleRemoveBlock(data: LogBlockType, payload: any): void;
     handleUpdateBlock(data: LogBlockType, payload: any): void;
     handleLogLine(data: LogLinesType, payload: any): void;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
     subscribeToLogStream(stream: string): Promise<void>;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
 }
 //# sourceMappingURL=log-stream-container-model.d.ts.map

package/models/models/log-stream/log-stream-container-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-stream-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/log-stream-container-model.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEzD,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAEvD,MAAM,MAAM,uBAAuB,GACjC,oBAAoB,CAAC,2BAA2B,CAAC,CAAC;AAOpD,qBACa,2BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa;IAE3E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,cAAc,CAAC,EAAE,cAAc,CAAC;IACtB,OAAO,CAAC,OAAO,CAAqC;gBAE5D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,kBAAkB;IAW7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,uCAET;IACD,IAAI,IAAI,qBAEP;IAED,WAAW,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAItD,QAAQ,CAAC,KAAK,EAAE,cAAc;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKtB,oBAAoB,CAAC,MAAM,CAAC,EAAE,cAAc;IAQ5C,iBAAiB,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;IAgB1C,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa1C,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa7C,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa7C,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAQnC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAqB5B"}
+{"version":3,"file":"log-stream-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/log-stream-container-model.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEzD,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,MAAM,uBAAuB,GACjC,oBAAoB,CAAC,2BAA2B,CAAC,CAAC;AAQpD;;;GAGG;AACH,qBACa,2BACX,YAAW,gBAAgB,EAAE,eAAe,CAAC,cAAc,CAAC,EAAE,aAAa;IAE3E,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAmB;IACjC,4DAA4D;IAC5D,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,uDAAuD;IAC7C,OAAO,CAAC,OAAO,CAAqC;gBAE5D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,kBAAkB;IAW7B,QAAQ,CAAC,EAAE,EAAE,MAAM;IAGnB,IAAI,MAAM,uCAET;IACD,IAAI,IAAI,qBAEP;IAED,WAAW,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAItD,QAAQ,CAAC,KAAK,EAAE,cAAc;IAI9B,WAAW,CAAC,EAAE,EAAE,MAAM;IAKtB,oBAAoB,CAAC,MAAM,CAAC,EAAE,cAAc;IAQ5C,iBAAiB,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;IAgB1C,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa1C,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa7C,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAa7C,aAAa,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,KAAA;IAQzC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAqB5B"}

package/models/models/log-stream/log-stream-model.d.ts

@@ -5,7 +5,56 @@ import { IKosIdentifiable } from '../../../core/core/types';
 import { IKosDataModel, IKosVisitor, KosCreationContext } from '../../../core/core/kosModel';
 
 export declare const MODEL_TYPE = "log-stream-model";
+/**
+ * Log Stream Model - Real-time streaming log viewer with efficient block-based management and async iteration.
+ *
+ * This model provides high-performance log streaming capabilities for monitoring KOS device logs in real-time.
+ * It organizes log data into efficient blocks for memory management and provides async iterator support
+ * for continuous log consumption. Essential for debugging, monitoring, and troubleshooting KOS applications.
+ *
+ * ## Key Features
+ * - **Real-time Log Streaming** - Live log updates as they are generated on the device
+ * - **Block-based Management** - Efficient memory usage through log block organization
+ * - **Async Iterator Support** - Stream logs using modern async/await patterns
+ * - **Subscription Control** - Subscribe/unsubscribe to specific log streams
+ * - **Line Number Tracking** - Maintains accurate line numbering across blocks
+ * - **Multi-stream Support** - Handle multiple log streams simultaneously through container model
+ *
+ * ## Common Use Cases
+ * - **Development Debugging** - Monitor application logs during development
+ * - **Production Monitoring** - Track system health and errors in deployed applications
+ * - **Troubleshooting** - Analyze log patterns to diagnose issues
+ * - **Log Analysis** - Process log streams for metrics and insights
+ * - **Real-time Dashboards** - Display live log feeds in monitoring interfaces
+ * - **Automated Log Processing** - Stream logs to external analysis tools
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const logStream = LogStream.instance('application-logs')
+ *   .options({ name: 'application-logs', nodeId: 'primary' })
+ *   .build();
+ *
+ * await logStream.subscribe();
+ * const iterator = logStream.start();
+ * for await (const logLine of iterator) {
+ *   console.log(`[LOG] ${logLine}`);
+ * }
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ * @useDeclaredType
+ *
+ * @see {@link LogStreamOptions} - Configuration options for log stream instances
+ * @see {@link LogStreamContainerModel} - Container model for managing multiple streams
+ * @see {@link LogBlockModel} - Individual log block management within streams
+ */
 export type LogStreamModel = PublicModelInterface<LogStreamModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class LogStreamModelImpl implements IKosDataModel, IKosIdentifiable {
     id: string;
     private logger;
@@ -27,7 +76,13 @@ export declare class LogStreamModelImpl implements IKosDataModel, IKosIdentifiab
     subscribe(): Promise<void>;
     unsubscribe(): Promise<void>;
     reset(): Promise<void>;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
     private generatorInstance?;
     private shouldStop;

package/models/models/log-stream/log-stream-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-stream-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/log-stream-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EAEX,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAOtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,CAAC;AAEtE,qBACa,kBAAmB,YAAW,aAAa,EAAE,gBAAgB;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,OAAO,CAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;gBAEnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB;IAa7B,IAAI,YAAY,WAGf;IACD,IAAI,YAAY,qDAIf;IAED,IAAI,SAAS,2CAEZ;IACD,IAAI,MAAM,2CAET;IAED,IAAI,cAAc,WAEjB;IAED,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC;IAI1C,WAAW,CAAC,SAAS,EAAE,YAAY;IAgCnC,QAAQ,CAAC,SAAS,EAAE,YAAY;IAwBhC,WAAW,CAAC,QAAQ,EAAE,MAAM;IAGtB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B,OAAO,CAAC,iBAAiB,CAAC,CAAqC;IAC/D,OAAO,CAAC,UAAU,CAAS;IAE3B,KAAK;IAML,IAAI;IAKG,UAAU,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;CAiExD"}
+{"version":3,"file":"log-stream-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/log-stream-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EAEX,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAOtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,CAAC;AACtE;;;GAGG;AACH,qBACa,kBAAmB,YAAW,aAAa,EAAE,gBAAgB;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,MAAM,EAAE,MAAM,CAAC;IAEf,OAAO,CAAC,OAAO,CAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;gBAEnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB;IAa7B,IAAI,YAAY,WAGf;IACD,IAAI,YAAY,qDAIf;IAED,IAAI,SAAS,2CAEZ;IACD,IAAI,MAAM,2CAET;IAED,IAAI,cAAc,WAEjB;IAED,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,aAAa,CAAC;IAI1C,WAAW,CAAC,SAAS,EAAE,YAAY;IAgCnC,QAAQ,CAAC,SAAS,EAAE,YAAY;IAwBhC,WAAW,CAAC,QAAQ,EAAE,MAAM;IAGtB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAI1B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B,OAAO,CAAC,iBAAiB,CAAC,CAAqC;IAC/D,OAAO,CAAC,UAAU,CAAS;IAE3B,KAAK;IAML,IAAI;IAKG,UAAU,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;CAgExD"}

package/models/models/log-stream/services/log-stream-services.d.ts

@@ -7,7 +7,8 @@ declare const SERVICE_PATH: ApiPath;
 export type LogStreamContainerClientResponse = ClientResponse<KosApi, typeof SERVICE_PATH, "get">;
 export type LogStreamContainerResponse = DeepRequired<ElementType<LogStreamContainerClientResponse>>;
 /**
- * @category Service
+ * @group KOS Model
+ * @category Device Logging
  * Retrieves the initial list of  log-stream-container data.
  */
 export declare const getLogStreams: () => Promise<ServiceResponse<LogStreamContainerClientResponse>>;

package/models/models/log-stream/services/log-stream-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log-stream-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/services/log-stream-services.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAY,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOpD,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,SAQ9C,CAAC;AAIF,QAAA,MAAM,YAAY,EAAE,OAA+C,CAAC;AACpE,MAAM,MAAM,gCAAgC,GAAG,cAAc,CAC3D,MAAM,EACN,OAAO,YAAY,EACnB,KAAK,CACN,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,YAAY,CACnD,WAAW,CAAC,gCAAgC,CAAC,CAC9C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,QACrC,gBAAgB,gCAAgC,CAAC,CAclD,CAAC;AAEF,eAAO,MAAM,oBAAoB,WACvB,MAAM,sBAEb,QAAQ,IAAI,CAcd,CAAC;AAEF,eAAO,MAAM,wBAAwB,WAC3B,MAAM,KACb,QAAQ,IAAI,CASd,CAAC;AAEF,eAAO,MAAM,cAAc,QAAa,QAAQ,IAAI,CAcnD,CAAC;AAEF,QAAA,MAAM,mBAAmB,EAAE,OACoB,CAAC;AAChD,MAAM,MAAM,6BAA6B,GAAG,cAAc,CACxD,MAAM,EACN,OAAO,mBAAmB,EAC1B,KAAK,CACN,CAAC;AAEF,eAAO,MAAM,kBAAkB,WACrB,MAAM,KACb,QAAQ,gBAAgB,6BAA6B,CAAC,CAcxD,CAAC;AAEF,eAAO,MAAM,iBAAiB,WACpB,MAAM,WACL,MAAM,KACd,QAAQ,gBAAgB,YAAY,CAAC,CAevC,CAAC"}
+{"version":3,"file":"log-stream-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/log-stream/services/log-stream-services.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAY,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAOpD,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,SAQ9C,CAAC;AAIF,QAAA,MAAM,YAAY,EAAE,OAA+C,CAAC;AACpE,MAAM,MAAM,gCAAgC,GAAG,cAAc,CAC3D,MAAM,EACN,OAAO,YAAY,EACnB,KAAK,CACN,CAAC;AACF,MAAM,MAAM,0BAA0B,GAAG,YAAY,CACnD,WAAW,CAAC,gCAAgC,CAAC,CAC9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,QAAa,QACrC,gBAAgB,gCAAgC,CAAC,CAclD,CAAC;AAEF,eAAO,MAAM,oBAAoB,WACvB,MAAM,sBAEb,QAAQ,IAAI,CAcd,CAAC;AAEF,eAAO,MAAM,wBAAwB,WAC3B,MAAM,KACb,QAAQ,IAAI,CASd,CAAC;AAEF,eAAO,MAAM,cAAc,QAAa,QAAQ,IAAI,CAcnD,CAAC;AAEF,QAAA,MAAM,mBAAmB,EAAE,OACoB,CAAC;AAChD,MAAM,MAAM,6BAA6B,GAAG,cAAc,CACxD,MAAM,EACN,OAAO,mBAAmB,EAC1B,KAAK,CACN,CAAC;AAEF,eAAO,MAAM,kBAAkB,WACrB,MAAM,KACb,QAAQ,gBAAgB,6BAA6B,CAAC,CAcxD,CAAC;AAEF,eAAO,MAAM,iBAAiB,WACpB,MAAM,WACL,MAAM,KACd,QAAQ,gBAAgB,YAAY,CAAC,CAevC,CAAC"}

package/models/models/log-stream/types/index.d.ts

@@ -1,9 +1,86 @@
 // ---------------  LogStream ---------------
 
+/**
+ * Configuration options for LogStream model instances.
+ * 
+ * These options specify the log stream identity and source location for connecting
+ * to specific log streams on KOS devices.
+ *
+ * @example Basic Log Stream Configuration
+ * ```typescript
+ * const options: LogStreamOptions = {
+ *   name: 'application-logs',
+ *   nodeId: 'primary'
+ * };
+ * 
+ * const logStream = LogStream.instance('app-logger')
+ *   .options(options)
+ *   .build();
+ * ```
+ *
+ * @example Multiple Stream Types
+ * ```typescript
+ * // System logs from primary node
+ * const systemLogs = LogStream.instance('system')
+ *   .options({ name: 'system-logs', nodeId: 'primary' })
+ *   .build();
+ *
+ * // Error logs from secondary node
+ * const errorLogs = LogStream.instance('errors') 
+ *   .options({ name: 'error-logs', nodeId: 'secondary' })
+ *   .build();
+ *
+ * // Debug logs from development node
+ * const debugLogs = LogStream.instance('debug')
+ *   .options({ name: 'debug-logs', nodeId: 'dev-node' })
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Logging
+ */
 export interface LogStreamOptions {
+  /**
+   * Name of the log stream to connect to.
+   * 
+   * This should match the log stream name available on the target device.
+   * Common stream names include 'application-logs', 'system-logs', 'error-logs'.
+   */
   name: string;
+  
+  /**
+   * Node identifier where the log stream is located.
+   * 
+   * Specifies which KOS device node contains the target log stream.
+   * Typically 'primary' for main device logs, but can be any valid node ID.
+   * 
+   * @default 'primary'
+   */
   nodeId: string;
 }
 
 // ---------------  LogStreamContainer ---------------
+
+/**
+ * Configuration options for LogStreamContainer model instances.
+ * 
+ * Currently an empty interface but reserved for future container-level
+ * configuration options such as stream filtering, automatic discovery settings,
+ * or performance tuning parameters.
+ *
+ * @example Basic Container Configuration
+ * ```typescript
+ * const options: LogStreamContainerOptions = {
+ *   // Future options will be added here
+ * };
+ * 
+ * const container = LogStreamContainer.instance('log-manager')
+ *   .options(options)
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category Data Persistence  
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface LogStreamContainerOptions {}