@kosdev-code/kos-ui-sdk 2.0.33 → 2.0.35

package/models/models/studio-properties/services/studio-properties-services.d.ts

@@ -1,8 +1,8 @@
-import { ApiPath, KosApi } from '../../../utils/service';
-import { ClientResponse, ServiceResponse } from '../../../../core';
+import { ApiPath, ApiResponse } from '../../../utils/service';
+import { ServiceResponse } from '../../../../core';
 
 declare const SERVICE_PATH: ApiPath;
-export type StudioPropertiesClientResponse = ClientResponse<KosApi, typeof SERVICE_PATH, "get">;
+export type StudioPropertiesClientResponse = ApiResponse<typeof SERVICE_PATH, "get">;
 export interface StudioPropertiesResponse {
     data?: Record<string, any>;
 }

package/models/models/studio-properties/services/studio-properties-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"studio-properties-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/services/studio-properties-services.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAY,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAOxE,QAAA,MAAM,YAAY,EAAE,OAAsC,CAAC;AAC3D,MAAM,MAAM,8BAA8B,GAAG,cAAc,CACzD,MAAM,EACN,OAAO,YAAY,EACnB,KAAK,CACN,CAAC;AACF,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,iBAChB,MAAM,KACnB,QAAQ,gBAAgB,wBAAwB,CAAC,CAcnD,CAAC"}
+{"version":3,"file":"studio-properties-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/services/studio-properties-services.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAY,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAO7E,QAAA,MAAM,YAAY,EAAE,OAAsC,CAAC;AAC3D,MAAM,MAAM,8BAA8B,GAAG,WAAW,CAAC,OAAO,YAAY,EAAE,KAAK,CAAC,CAAC;AACrF,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,iBAChB,MAAM,KACnB,QAAQ,gBAAgB,wBAAwB,CAAC,CAcnD,CAAC"}

package/models/models/studio-properties/studio-properties-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"studio-properties-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/studio-properties-model.ts"],"names":[],"mappings":"AAQA,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,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAGpD,MAAM,MAAM,qBAAqB,GAC/B,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;AAMlD,qBACa,yBACX,YAAW,aAAa,EAAE,gBAAgB;IAE1C,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,IAAI,CAA+B;gBAEzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,kBAAkB;IAWvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAG3C,2BAA2B;IA8BjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAKrB,wBAAwB,CAAC,GAAG,EAAE,MAAM;CAGrC"}
+{"version":3,"file":"studio-properties-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/studio-properties-model.ts"],"names":[],"mappings":"AAQA,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,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAGpD,MAAM,MAAM,qBAAqB,GAC/B,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;AAMlD,qBACa,yBACX,YAAW,aAAa,EAAE,gBAAgB;IAE1C,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,IAAI,CAA+B;gBAEzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,kBAAkB;IAWvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAG3C,2BAA2B;IA8BjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAIrB,wBAAwB,CAAC,GAAG,EAAE,MAAM;CAGrC"}

package/models/models/trouble/index.d.ts

@@ -1,6 +1,7 @@
 import * as TroubleServices from "./services";
 export { Trouble } from './trouble-registration';
 export type { DeferAware, ResolveAware, TroubleAware, TroubleModel, TroubleOptions, } from './types';
+export * from './utils/is-trouble-aware';
 export { EXTENSION_TROUBLE_DATA_MAPPER } from './utils/trouble-data-extension';
 export { EXTENSION_TROUBLE_MAPPER } from './utils/trouble-extension';
 export * from './utils/trouble-reducer';

package/models/models/trouble/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,eAAe,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,eAAe,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,cAAc,GACf,MAAM,SAAS,CAAC;AACjB,cAAc,0BAA0B,CAAC;AACzC,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/models/models/trouble/trouble-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/trouble-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAK1C,qBACa,gBAAgB,CAAC,cAAc,SAAS,MAAM,GAAG,GAAG,CAC/D,YAAW,YAAY,CAAC,cAAc,CAAC,EAAE,eAAe;IAExD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAU;IAE7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,oBAAoB,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAwB;gBAErC,OAAO,EAAE,MAAM,EACf,EACE,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,UAAU,EACV,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,UAAU,EACV,IAAI,EACJ,KAAK,EACL,GAAG,IAAI,EACR,EAAE,cAAc,EACjB,OAAO,EAAE,kBAAkB;IAyB7B,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAWnC,sBAAsB,CAAC,OAAO,EAAE,MAAM;IAWtC,IAAI,KAAK,WAER;IACD,IAAI,KAAK,WAER;IAED,IAAI,QAAQ,WAEX;IAED,IAAI,SAAS,WAEZ;IAED,IAAI,UAAU,YAEb;IAED,IAAI,MAAM,uFAET;IAEK,iBAAiB;IAIvB,IAAI,iBAAiB,qEAMpB;IACD,IAAI,QAAQ,YAKX;IACD,IAAI,WAAW,IAAI,OAAO,CAMzB;IAED,UAAU;IAGV,KAAK;IAIL,WAAW;IAML,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM;CAc/B"}
+{"version":3,"file":"trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/trouble-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAM1C,qBACa,gBAAgB,CAAC,cAAc,SAAS,MAAM,GAAG,GAAG,CAC/D,YAAW,YAAY,CAAC,cAAc,CAAC,EAAE,eAAe;IAExD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAU;IAE7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,oBAAoB,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAwB;gBAErC,OAAO,EAAE,MAAM,EACf,EACE,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,UAAU,EACV,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,UAAU,EACV,IAAI,EACJ,KAAK,EACL,GAAG,IAAI,EACR,EAAE,cAAc,EACjB,OAAO,EAAE,kBAAkB;IAyB7B,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAWnC,sBAAsB,CAAC,OAAO,EAAE,MAAM;IAWtC,IAAI,KAAK,WAER;IACD,IAAI,KAAK,WAER;IAED,IAAI,QAAQ,WAEX;IAED,IAAI,SAAS,WAEZ;IAED,IAAI,UAAU,YAEb;IAED,IAAI,MAAM,uFAET;IAEK,iBAAiB;IAIvB,IAAI,iBAAiB,qEAMpB;IACD,IAAI,QAAQ,YAKX;IACD,IAAI,WAAW,IAAI,OAAO,CAMzB;IAED,UAAU;IAGV,KAAK;IAIL,WAAW;IAML,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM;CAc/B"}

package/models/models/trouble/types/index.d.ts

@@ -3,98 +3,442 @@ import { FutureResponse } from '../../../services/future';
 import { IKosDataModel } from '../../../core';
 
 
+/**
+ * Configuration options for creating or updating a Trouble model.
+ *
+ * This interface defines all the properties that can be set when initializing
+ * a trouble instance. Troubles represent issues, alerts, or conditions that
+ * require attention in the KOS system.
+ *
+ * @template AdditionalData - Optional type parameter for domain-specific trouble data
+ *
+ * @example
+ * ```typescript
+ * const troubleOptions: TroubleOptions = {
+ *   id: 'low-fluid-001',
+ *   type: 'FLUID_LEVEL',
+ *   reason: 'Fluid level below minimum threshold',
+ *   rank: 7,
+ *   role: 'operator',
+ *   color: 'orange',
+ *   resolvable: true,
+ *   ifaces: ['fluid-monitor', 'alert-system'],
+ *   tags: ['maintenance', 'fluid', 'warning'],
+ *   createTime: new Date().toISOString()
+ * };
+ * ```
+ *
+ * @category Trouble Management
+ * @subcategory Types
+ */
 export interface TroubleOptions<AdditionalData extends object = any> {
+  /** Whether this trouble can be resolved through user action */
   resolvable?: boolean;
+  /** Human-readable description of why the trouble occurred */
   reason?: string;
+  /** ISO timestamp when the trouble was created */
   createTime?: string;
+  /** List of interface identifiers this trouble affects */
   ifaces: string[];
+  /** Unique identifier for the trouble instance */
   id: string;
+  /** Priority rank from 1-10 (10 being most critical) */
   rank: number;
+  /** User role required to view/resolve this trouble */
   role: string;
+  /** Display color for UI representation (e.g., 'red', 'yellow', 'orange') */
   color: string;
+  /** Client-specific data attached to the trouble */
   clientData: unknown;
+  /** Classification type of the trouble (e.g., 'ERROR', 'WARNING', 'INFO') */
   type: string;
+  /** Searchable tags for categorizing troubles */
   tags: string[];
+  /** Additional information about the trouble state */
   info: unknown;
+  /** Optional grouping identifier for related troubles */
   group?: string;
+  /** Index signature for additional domain-specific data */
   [key: keyof AdditionalData]: AdditionalData[key];
 }
 
 /**
- * Trouble Model
- * @category Model
+ * Represents a trouble (issue, alert, or condition) in the KOS system.
+ *
+ * TroubleModel is the core interface for managing system issues, warnings, and
+ * alerts throughout the KOS platform. It provides a unified way to track,
+ * display, resolve, and defer various types of operational issues.
+ *
+ * ## Key Features
+ * - **Priority ranking** - Troubles are ranked 1-10 for severity
+ * - **Role-based visibility** - Troubles can be filtered by user role
+ * - **Resolution support** - Resolvable troubles can be cleared through actions
+ * - **Deferral capability** - Troubles can be temporarily deferred
+ * - **Future integration** - Async resolution through futures
+ * - **Type categorization** - Troubles grouped by type for filtering
+ * - **Visual indicators** - Color coding for UI representation
+ *
+ * @template AdditionalData - Type parameter for domain-specific trouble data
+ *
+ * @example
+ * ```typescript
+ * // Check trouble severity
+ * function handleTrouble(trouble: TroubleModel) {
+ *   if (trouble.rank >= 8) {
+ *     console.error(`Critical trouble: ${trouble.reason}`);
+ *     notifyOperator(trouble);
+ *   } else if (trouble.rank >= 5) {
+ *     console.warn(`Warning: ${trouble.reason}`);
+ *   }
+ *
+ *   // Check if user can resolve
+ *   if (trouble.resolvable && hasRole(trouble.role)) {
+ *     showResolveButton(trouble);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Resolve a trouble with proper future handling
+ * async function resolveTrouble(trouble: TroubleModel) {
+ *   if (!trouble.resolvable) {
+ *     throw new Error('Trouble is not resolvable');
+ *   }
+ *
+ *   try {
+ *     // Resolution returns a FutureResponse with future tracking
+ *     const futureResponse = await trouble.resolve();
+ *     if (futureResponse) {
+ *       console.log(`Resolution started, future ID: ${futureResponse.id}`);
+ *
+ *       // The trouble's future property will be updated with the resolution future
+ *       // You can track progress through the future model
+ *       if (trouble.future) {
+ *         const endState = await trouble.future.waitForCompletion();
+ *         if (endState === 'COMPLETED') {
+ *           console.log('Trouble resolved successfully');
+ *         } else if (endState === 'FAILED') {
+ *           console.error('Resolution failed');
+ *         }
+ *       }
+ *     }
+ *   } catch (error) {
+ *     console.error('Failed to initiate resolution:', error);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using cancellable promise utilities with trouble resolution
+ * import { createCancellablePromise } from '@kosdev-code/kos-ui-sdk';
+ *
+ * async function resolveTroubleWithCancel(trouble: TroubleModel) {
+ *   const futureResponse = await trouble.resolve();
+ *
+ *   if (futureResponse && trouble.future) {
+ *     // Create a cancellable promise for the resolution
+ *     const cancellableResolve = createCancellablePromise(
+ *       trouble.future.waitForCompletion(),
+ *       undefined,
+ *       () => trouble.future?.cancelFuture(),
+ *       trouble.future
+ *     );
+ *
+ *     // Subscribe to progress updates
+ *     const unsubscribe = cancellableResolve.onProgressUpdate((progress, status) => {
+ *       console.log(`Resolution progress: ${(progress * 100).toFixed(0)}% - ${status}`);
+ *     });
+ *
+ *     try {
+ *       const endState = await cancellableResolve;
+ *       console.log(`Resolution completed with state: ${endState}`);
+ *     } catch (error) {
+ *       if (cancellableResolve.isCancelled()) {
+ *         console.log('Resolution was cancelled');
+ *       } else {
+ *         console.error('Resolution failed:', error);
+ *       }
+ *     } finally {
+ *       unsubscribe();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ *
+ * @category KOS Model
+ * @subcategory Trouble Management
+ *
+ * @see {@link TroubleAware} - Interface for models that can have troubles
+ * @see {@link DeferAware} - Deferral capabilities
+ * @see {@link ResolveAware} - Resolution capabilities
  */
 export interface TroubleModel<AdditionalData extends object = any>
   extends IKosDataModel,
     DeferAware,
     FutureContainer {
+  /** Unique identifier for the trouble instance */
   id: string;
+  /** Whether this trouble can be resolved through user action */
   resolvable?: boolean;
+  /** Human-readable description of why the trouble occurred */
   reason?: string;
+  /** ISO timestamp when the trouble was created */
   createTime?: string;
+  /** List of interface identifiers this trouble affects */
   ifaces: string[];
-  id: string;
+  /** Client-specific data attached to the trouble */
   clientData: unknown;
+  /** Associated future for async resolution operations */
   future?: IFutureModel;
+  /** Classification type of the trouble (e.g., 'ERROR', 'WARNING', 'INFO') */
   type: string;
+  /** Searchable tags for categorizing troubles */
   tags: string[];
+  /** Additional information about the trouble state */
   info: unknown;
+  /** Original trouble ID before any transformations */
   rawId: string;
+  /** Resolves the trouble, returning a promise with the resolution response */
   resolve: () => Promise<FutureResponse | undefined>;
+  /** Domain-specific additional data attached to the trouble */
   data: AdditionalData;
+  /** Priority rank from 1-10 (10 being most critical) */
   rank: number;
+  /** User role required to view/resolve this trouble */
   role: string;
+  /** Display color for UI representation (e.g., 'red', 'yellow', 'orange') */
   color: string;
+  /** Whether this trouble has been deferred */
   deferred: boolean;
+  /** Optional grouping identifier for related troubles */
   group?: string;
 }
 
+/**
+ * Domain-specific trouble data for handle-related issues.
+ *
+ * @category Trouble Management
+ * @subcategory Domain Data
+ */
 export interface HandleTroubleData {
+  /** Path to the affected handle component */
   path: string;
 }
 
+/**
+ * Domain-specific trouble data for nozzle-related issues.
+ *
+ * @category Trouble Management
+ * @subcategory Domain Data
+ */
 export interface NozzleTroubleData {
+  /** Path to the affected nozzle component */
   nozzlePath: string;
 }
 
+/**
+ * Domain-specific trouble data for container-related issues.
+ *
+ * @category Trouble Management
+ * @subcategory Domain Data
+ */
 export interface ContainerTroubleData {
+  /** Identifier of the affected container */
   containerId: string;
+  /** List of ingredients involved in the trouble */
   ingredients: string[];
 }
 
+/**
+ * Interface for objects that can be resolved asynchronously.
+ *
+ * Provides a standard resolution mechanism for troubles and other
+ * resolvable conditions in the KOS system. Resolution typically
+ * involves sending a command to clear the condition.
+ *
+ * @example
+ * ```typescript
+ * class ResolvableTrouble implements ResolveAware {
+ *   async resolve(tracker?: string) {
+ *     console.log(`Resolving with tracker: ${tracker}`);
+ *     const response = await sendResolveCommand(this.id, tracker);
+ *     return response;
+ *   }
+ * }
+ * ```
+ *
+ * @category Trouble Management
+ * @subcategory Capabilities
+ */
 export interface ResolveAware {
+  /**
+   * Resolves the condition asynchronously.
+   *
+   * @param tracker - Optional tracking identifier for the resolution operation
+   * @returns Promise resolving to the future response, or undefined if resolution fails
+   */
   resolve: (tracker?: string) => Promise<FutureResponse | undefined>;
 }
 
+/**
+ * Interface for objects that support deferral of actions.
+ *
+ * Deferral allows temporary postponement of trouble handling or
+ * other actions. Deferred items can be cleared to restore normal
+ * processing. This is useful for managing low-priority issues
+ * during critical operations.
+ *
+ * @example
+ * ```typescript
+ * class DeferrableTrouble implements DeferAware {
+ *   shouldDefer = false;
+ *   deferred = false;
+ *
+ *   defer() {
+ *     this.deferred = true;
+ *     console.log('Trouble deferred');
+ *   }
+ *
+ *   clearDefer() {
+ *     this.deferred = false;
+ *     console.log('Deferral cleared');
+ *   }
+ * }
+ *
+ * // Usage
+ * if (trouble.shouldDefer && !trouble.deferred) {
+ *   trouble.defer();
+ * }
+ * ```
+ *
+ * @category Trouble Management
+ * @subcategory Capabilities
+ */
 export interface DeferAware {
+  /** Whether this item should be deferred based on current conditions */
   shouldDefer: boolean;
+  /** Current deferral state */
   deferred: boolean;
+  /** Defers the item, preventing normal processing */
   defer: VoidFunction;
+  /** Clears the deferral, allowing normal processing to resume */
   clearDefer: VoidFunction;
 }
 /**
- * Provides a common interface for all trouble containers
+ * Interface for models that can track and expose trouble states.
+ *
+ * TroubleAware provides a standardized way for KOS models to expose
+ * their trouble states, making it easy to monitor, display, and react
+ * to issues throughout the system. Any model implementing this interface
+ * can be monitored for troubles and integrated with trouble management UI.
+ *
+ * ## Key Concepts
+ * - **Trouble aggregation** - Models can aggregate troubles from multiple sources
+ * - **Status summary** - Provides a single status string for quick checks
+ * - **Type grouping** - Troubles organized by type for filtering and display
+ * - **Read-only access** - Troubles are exposed as readonly for safety
+ *
+ * @example
+ * ```typescript
+ * // Check if a model has troubles
+ * function checkModelHealth(model: TroubleAware) {
+ *   if (model.troubles.length > 0) {
+ *     console.warn(`Model has ${model.troubles.length} troubles`);
+ *     console.warn(`Status: ${model.troubleStatus}`);
+ *
+ *     // Check specific trouble types
+ *     const errors = model.troublesByType['ERROR'] || [];
+ *     const warnings = model.troublesByType['WARNING'] || [];
+ *
+ *     if (errors.length > 0) {
+ *       handleCriticalErrors(errors);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // React component using TroubleAware
+ * const TroubleIndicator: React.FC<{ model: TroubleAware }> = ({ model }) => {
+ *   const troubles = model.troubles;
+ *   const highPriority = troubles.filter(t => t.rank >= 7);
+ *
+ *   if (troubles.length === 0) {
+ *     return <StatusIcon color="green" />;
+ *   }
+ *
+ *   return (
+ *     <div className="trouble-indicator">
+ *       <StatusIcon color={highPriority.length > 0 ? 'red' : 'yellow'} />
+ *       <span>{model.troubleStatus}</span>
+ *       <Badge count={troubles.length} />
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Implementing TroubleAware
+ * class MyModel implements TroubleAware {
+ *   private _troubles: TroubleModel[] = [];
  *
- * Allows a model to expose the troubles that are directly related to it.
- * Also provides a standard interface to get the status of the highest priority trouble.
+ *   get troubles(): readonly TroubleModel[] {
+ *     return this._troubles;
+ *   }
  *
+ *   get troubleStatus(): string {
+ *     if (this._troubles.length === 0) return 'OK';
+ *     const highest = this._troubles.reduce((max, t) =>
+ *       t.rank > max.rank ? t : max
+ *     );
+ *     return highest.reason || 'Unknown issue';
+ *   }
  *
+ *   get troublesByType(): Record<string, TroubleModel[]> {
+ *     return this._troubles.reduce((groups, trouble) => {
+ *       const type = trouble.type;
+ *       groups[type] = groups[type] || [];
+ *       groups[type].push(trouble);
+ *       return groups;
+ *     }, {} as Record<string, TroubleModel[]>);
+ *   }
+ * }
+ * ```
  *
+ * @category Trouble Management
+ * @subcategory Interfaces
  *
+ * @see {@link TroubleModel} - The trouble model interface
+ * @see {@link isTroubleAware} - Type guard for checking TroubleAware
+ * @see {@link useTroubleDecoration} - Hook for trouble-based styling
  */
 export interface TroubleAware {
   /**
-   * Returns the troubles that are directly related to this model.
+   * Array of troubles directly related to this model.
+   * Troubles are typically sorted by rank (highest priority first).
    */
   readonly troubles: TroubleModel[];
 
   /**
-   * Returns the highest priority trouble status.
+   * Summary status string representing the highest priority trouble.
+   * Returns a human-readable status or 'OK' if no troubles exist.
    */
   readonly troubleStatus: string;
 
   /**
-   * Returns the troubles that are directly related to this model, grouped by type.
+   * Troubles organized by their type property.
+   * Useful for filtering and categorized display of issues.
+   *
+   * @example
+   * ```typescript
+   * const errorTroubles = model.troublesByType['ERROR'] || [];
+   * const warningTroubles = model.troublesByType['WARNING'] || [];
+   * ```
    */
   readonly troublesByType: Record<string, TroubleModel[]>;
 }

package/models/models/trouble/utils/is-trouble-aware.d.ts

@@ -0,0 +1,98 @@
+import { TroubleAware } from '../types';
+
+/**
+ * Type guard function to check if an object implements the TroubleAware interface.
+ *
+ * This function performs runtime validation to determine whether a given object
+ * has the necessary properties and structure to be considered trouble-aware.
+ * It checks for the presence of both the `troubles` array and `troublesByType`
+ * object, which are required by the TroubleAware interface.
+ *
+ * @category Utilities
+ * @subcategory Trouble Management
+ *
+ * @param obj - The object to check for trouble awareness. Can be any type.
+ *
+ * @returns `true` if the object implements TroubleAware interface, `false` otherwise.
+ *          When this function returns true, TypeScript will narrow the type of `obj`
+ *          to `TroubleAware` in the current scope.
+ *
+ * @example
+ * ```typescript
+ * // Basic type guard usage
+ * function processModel(model: IKosDataModel) {
+ *   if (isTroubleAware(model)) {
+ *     // TypeScript now knows model has troubles property
+ *     console.log(`Found ${model.troubles.length} troubles`);
+ *     console.log(`Trouble status: ${model.troubleStatus}`);
+ *   } else {
+ *     console.log('Model is not trouble-aware');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using with React hooks for conditional trouble handling
+ * const TroubleDisplay: React.FC<{ model: IKosDataModel }> = ({ model }) => {
+ *   if (!isTroubleAware(model)) {
+ *     return <div>No trouble tracking available</div>;
+ *   }
+ *
+ *   // Safe to access trouble properties here
+ *   const criticalTroubles = model.troubles.filter(t => t.rank > 8);
+ *   const troubleTypes = Object.keys(model.troublesByType);
+ *
+ *   return (
+ *     <div>
+ *       <h3>Trouble Status: {model.troubleStatus}</h3>
+ *       <p>Critical issues: {criticalTroubles.length}</p>
+ *       <p>Types: {troubleTypes.join(', ')}</p>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Filtering trouble-aware models from a collection
+ * const models: IKosDataModel[] = getAllModels();
+ * const troubleAwareModels = models.filter(isTroubleAware);
+ *
+ * // TypeScript knows troubleAwareModels is TroubleAware[]
+ * troubleAwareModels.forEach(model => {
+ *   const troublesByType = model.troublesByType;
+ *   Object.entries(troublesByType).forEach(([type, troubles]) => {
+ *     console.log(`Type ${type}: ${troubles.length} troubles`);
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Early return pattern for non-trouble-aware models
+ * function calculateTroubleSeverity(model: any): number {
+ *   if (!isTroubleAware(model)) {
+ *     return 0; // No troubles means no severity
+ *   }
+ *
+ *   // Calculate weighted severity based on trouble ranks
+ *   return model.troubles.reduce((total, trouble) => {
+ *     return total + (trouble.rank * (trouble.deferred ? 0.5 : 1));
+ *   }, 0);
+ * }
+ * ```
+ *
+ * @remarks
+ * - This is a runtime check, not a compile-time check
+ * - The function checks for structural compatibility, not nominal typing
+ * - It validates that `troubles` is specifically an Array instance, not just array-like
+ * - The `troublesByType` property must be an object (not null or undefined)
+ * - Does not validate the contents of the arrays or object, only their presence and type
+ * - This function is commonly used as a guard before accessing trouble-related properties
+ *
+ * @see {@link TroubleAware} - The interface this function checks for
+ * @see {@link useTroubleDecoration} - Hook that uses this guard internally
+ */
+export declare function isTroubleAware(obj: any): obj is TroubleAware;
+//# sourceMappingURL=is-trouble-aware.d.ts.map

package/models/models/trouble/utils/is-trouble-aware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-trouble-aware.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/utils/is-trouble-aware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,YAAY,CAO5D"}

package/models/utils/client.d.ts

@@ -57,7 +57,11 @@ export declare const api: {
     } | undefined) => Promise<import('../../core').ServiceResponse<ClientResponse<paths, K_2, "put">>>;
     delete: <K_3 extends "/api/ext/dispense/nozzle/nozzle/pipeline/beverage/select" | "/api/app/kosdev.ddk/copyLogs/{id}" | "/api/ext/dispense/metrics/{name}" | "/api/ext/dispense/metrics/{nozzle}/{name}" | "/api/ext/dispense/assignments/{holderPath}" | "/api/kos/nodeMgr/node/{nodeId}/blockedManifests" | "/api/kos/nodeMgr/node/{nodeId}/blockedManifests/{manifestId}" | "/api/kos/nodeMgr/blockedManifests/{manifestId}" | "/api/kos/criticalData/data/{name}" | "/api/app/tccc.fits/medusa/profiles/{profileId}" | "/api/app/tccc.fits/medusa/profiles/{profileId}/recipes/{name}" | "/api/app/tccc.fits/medusa/profiles/{profileId}/tests/{testId}" | "/api/app/tccc.fits/medusa/profiles/{profileId}/builder/blocks" | "/api/app/tccc.fits/medusa/profiles/{profileId}/builder/bevs/{bevId}" | "/api/app/tccc.fits/medusa/profiles/{profileId}/results/{resultsId}" | "/api/app/tccc.fits/scales/{serialNum}" | "/api/app/tccc.fits.sim/scales/{serialNum}" | "/api/app/tccc.fits/session/data/{key}">(endpoint: K_3, params?: (paths[K_3]["delete"] extends {
         parameters: infer P_3;
-    } ? P_3 : never) | undefined, options?: {
+    } ? P_3 : never) | undefined, body?: (paths[K_3]["put"] extends {
+        requestBody: {
+            content: infer B_1;
+        };
+    } ? B_1[keyof B_1] : never) | undefined, options?: {
         ordered?: boolean | undefined;
         tracker?: string | undefined;
         timeout?: number | undefined;

package/models/utils/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/models/utils/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAEzC,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,MAAM,KAAK,EACrB,CAAC,SAAS,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAClC,cAAc,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/models/utils/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAwB,CAAC;AAEzC,MAAM,MAAM,gBAAgB,CAC1B,CAAC,SAAS,MAAM,KAAK,EACrB,CAAC,SAAS,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAClC,cAAc,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/models/utils/core-registration-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-registration-manager.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/models/utils/core-registration-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EAGnB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAkBpB,eAAO,MAAM,kBAAkB,YACnB,CAAC;;;;;CA6BV,CAAC;AAEJ,KAAK,aAAa,CAAC,CAAC,IAAI;IACtB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;IAC9C,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACnE,KAAK,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7D,SAAS,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;CACtE,CAAC;AAEF,QAAA,MAAM,iBAAiB,IAAK,CAAC;AAc7B,KAAK,oBAAoB,GAAG,aAAa,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEpE,QAAA,MAAM,gBAAgB,EAAE,oBAA+C,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,CAAC"}
+{"version":3,"file":"core-registration-manager.d.ts","sourceRoot":"","sources":["../../../../../../packages/sdk/kos-ui-sdk/src/models/utils/core-registration-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EAGnB,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAkBpB,eAAO,MAAM,kBAAkB,YACnB,CAAC;;;;;CA8BV,CAAC;AAEJ,KAAK,aAAa,CAAC,CAAC,IAAI;IACtB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;IAC9C,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACnE,KAAK,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7D,SAAS,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;CACtE,CAAC;AAEF,QAAA,MAAM,iBAAiB,IAAK,CAAC;AAc7B,KAAK,oBAAoB,GAAG,aAAa,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEpE,QAAA,MAAM,gBAAgB,EAAE,oBAA+C,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,CAAC"}