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

package/kos-models.json

@@ -0,0 +1,180 @@
+{
+  "generatedAt": "2026-04-24T22:12:30.229Z",
+  "packageName": "@kosdev-code/kos-freestyle-sdk",
+  "models": {
+    "test-future-model-model": {
+      "modelTypeId": "test-future-model-model",
+      "singleton": false,
+      "container": false,
+      "dependencies": [],
+      "children": []
+    },
+    "remote-tray-model": {
+      "modelTypeId": "remote-tray-model",
+      "className": "RemoteTrayModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/remote-tray/remote-tray-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "remote-tray-container-model": {
+      "modelTypeId": "remote-tray-container-model",
+      "className": "RemoteTrayContainerModelImpl",
+      "singleton": true,
+      "container": true,
+      "sourcePath": "src/models/models/remote-tray/remote-tray-container-model.ts",
+      "dependencies": [],
+      "children": [
+        {
+          "propertyName": "container",
+          "modelType": "remote-tray-model"
+        }
+      ]
+    },
+    "carb-agitator-model": {
+      "modelTypeId": "carb-agitator-model",
+      "className": "CarbAgitatorModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/carb-agitator/carb-agitator-model.ts",
+      "dependencies": [],
+      "children": [],
+      "companion": {
+        "mode": "composition",
+        "parentProperty": "companionParent",
+        "lifecycle": "load"
+      }
+    },
+    "agitation-required-trouble-model": {
+      "modelTypeId": "agitation-required-trouble-model",
+      "className": "AgitationRequiredTroubleModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/agitation-required-trouble/agitation-required-trouble-model.ts",
+      "dependencies": [],
+      "children": [],
+      "companion": {
+        "mode": "composition",
+        "parentProperty": "trouble"
+      }
+    },
+    "spm-pump-model": {
+      "modelTypeId": "spm-pump-model",
+      "className": "SpmPumpModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/spm-pump/spm-pump-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "freestyle-holder-model": {
+      "modelTypeId": "freestyle-holder-model",
+      "className": "FreestyleHolderModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/freestyle-holder/freestyle-holder-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "fcm-pump-model": {
+      "modelTypeId": "fcm-pump-model",
+      "className": "FcmPumpModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/fcm-pump/fcm-pump-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "cartridge-agitator-container-model": {
+      "modelTypeId": "cartridge-agitator-container-model",
+      "className": "CartridgeAgitatorContainerModelImpl",
+      "singleton": true,
+      "container": false,
+      "sourcePath": "src/models/models/cartridge-agitator/cartridge-agitator-container-model.ts",
+      "dependencies": [],
+      "children": [
+        {
+          "propertyName": "_models",
+          "modelType": "cartridge-agitator-model"
+        }
+      ]
+    },
+    "cartridge-agitator-model": {
+      "modelTypeId": "cartridge-agitator-model",
+      "className": "CartridgeAgitatorModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/cartridge-agitator/cartridge-agitator-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "freestyle-nozzle-model": {
+      "modelTypeId": "freestyle-nozzle-model",
+      "className": "FreestyleNozzleModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/freestyle-nozzle/freestyle-nozzle-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "ice-agitator-model": {
+      "modelTypeId": "ice-agitator-model",
+      "className": "IceAgitatorModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/ice-agitator/ice-agitator-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "freestyle-pump-model": {
+      "modelTypeId": "freestyle-pump-model",
+      "className": "FreestylePumpModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/freestyle-pump/freestyle-pump-model.ts",
+      "dependencies": [],
+      "children": []
+    },
+    "freestyle-assembly-model": {
+      "modelTypeId": "freestyle-assembly-model",
+      "className": "FreestyleAssemblyModelImpl",
+      "singleton": true,
+      "container": false,
+      "sourcePath": "src/models/models/freestyle-assembly/freestyle-assembly-model.ts",
+      "dependencies": [],
+      "children": [
+        {
+          "propertyName": "_remoteTrays",
+          "modelType": "remote-tray-container-model"
+        }
+      ]
+    },
+    "cgp-pump-model": {
+      "modelTypeId": "cgp-pump-model",
+      "className": "CgpPumpModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/cgp-pump/cgp-pump-model.ts",
+      "dependencies": [],
+      "children": [],
+      "companion": {
+        "mode": "composition",
+        "parentProperty": "companionParent"
+      }
+    },
+    "lfcv-pump-model": {
+      "modelTypeId": "lfcv-pump-model",
+      "className": "LfcvPumpModelImpl",
+      "singleton": false,
+      "container": false,
+      "sourcePath": "src/models/models/lfcv-pump/lfcv-pump-model.ts",
+      "dependencies": [],
+      "children": [],
+      "companion": {
+        "mode": "composition",
+        "parentProperty": "pumpModel"
+      }
+    }
+  }
+}

package/models/models/agitation-required-trouble/agitation-required-trouble-model.d.ts

@@ -1,25 +1,215 @@
 import { AgitationRequiredTroubleOptions } from './types';
-import { DeferAware, FutureResponse, IKosDataModel, IKosIdentifiable, KosConfigProperty, KosCreationContext, PublicModelInterface, ResolveAware, TroubleModel } from '@kosdev-code/kos-ui-sdk';
-import { HolderModel } from '@kosdev-code/kos-dispense-sdk';
+import { DeferAware, FutureResponse, IKosDataModel, IKosIdentifiable, KosCompanionComposition, KosConfigProperty, KosLoggerAware, KosModelRegistrationFactory, PublicModelInterface, ResolveAware, TroubleModel } from '@kosdev-code/kos-ui-sdk';
+import { HolderModel, HolderTroubleData } from '@kosdev-code/kos-dispense-sdk';
 
+/**
+ * Agitation required trouble model type identifier.
+ *
+ * Used for model registration and type predicates when working with
+ * agitation-related troubles in the KOS framework.
+ *
+ * @category Trouble Models
+ */
 export declare const MODEL_TYPE = "agitation-required-trouble-model";
+/**
+ * Public interface for the AgitationRequiredTrouble model.
+ *
+ * This model manages troubles related to insufficient agitation in beverage
+ * holders, providing resolution capabilities and deferral logic based on
+ * configuration properties.
+ *
+ * @see {@link AgitationRequiredTroubleModelImpl} for the implementation
+ * @category Trouble Models
+ */
 export type AgitationRequiredTroubleModel = PublicModelInterface<AgitationRequiredTroubleModelImpl>;
+/**
+ * Factory function to determine if a trouble requires agitation handling.
+ *
+ * Examines the trouble model's data to determine if it represents an
+ * insufficient agitation condition that requires a dedicated agitation
+ * trouble model.
+ *
+ * @param troubleModel - The trouble model to examine
+ * @returns The agitation model type if agitation is required, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const modelType = agitationModelFactory(troubleModel);
+ * if (modelType) {
+ *   // Create agitation trouble model
+ *   const agitationModel = AgitationRequiredTrouble
+ *     .instance(troubleModel.id)
+ *     .options({ companionParent: troubleModel })
+ *     .build();
+ * }
+ * ```
+ *
+ * @category Trouble Models
+ */
 export declare const agitationModelFactory: (troubleModel: TroubleModel) => "agitation-required-trouble-model" | undefined;
+/**
+ * Trouble type identifier for insufficient agitation troubles.
+ *
+ * This constant is used to filter and identify agitation-related troubles
+ * in the trouble system.
+ *
+ * @category Trouble Models
+ */
 export declare const AGITATION_REQUIRED_TROUBLE = "InsufficientAgitationTrouble";
+export interface AgitationRequiredTroubleModelImpl extends KosLoggerAware, KosCompanionComposition<TroubleModel<HolderTroubleData>> {
+    /** Parent trouble model (set by @kosCompanion decorator via parentProperty: "trouble") */
+    trouble: TroubleModel<HolderTroubleData>;
+}
+/**
+ * Companion model for managing agitation-required troubles in KOS beverage dispensers.
+ *
+ * This model represents troubles caused by insufficient agitation in ingredient holders,
+ * typically occurring when carbonation levels are too low or agitation mechanisms fail.
+ * It provides resolution capabilities and deferral logic to prevent pouring until
+ * agitation conditions are met.
+ *
+ * The model integrates with the KOS configuration system to respect the
+ * `ncui.agitateBeforePour` setting, allowing operators to control whether
+ * pouring should wait for agitation to complete.
+ *
+ * @remarks
+ * This is a companion model to the parent trouble model, created via the
+ * {@link agitationModelFactory} when a trouble's `agitationRequired` flag is set.
+ *
+ * @example
+ * ```typescript
+ * // Factory-based creation (typical usage)
+ * const agitationTrouble = AgitationRequiredTrouble
+ *   .instance(troubleId)
+ *   .options({ companionParent: parentTroubleModel })
+ *   .build();
+ *
+ * // Check if pouring should be deferred
+ * if (agitationTrouble.shouldDefer) {
+ *   await agitationTrouble.defer();
+ * }
+ *
+ * // Resolve the trouble
+ * await agitationTrouble.resolve();
+ * ```
+ *
+ * @category Trouble Models
+ * @author Mark Pomerant (mark@matrica.ca)
+ * @version 2.1.27
+ */
 export declare class AgitationRequiredTroubleModelImpl implements IKosDataModel, IKosIdentifiable, ResolveAware, DeferAware {
+    /**
+     * Registration factory for creating AgitationRequiredTrouble model instances.
+     *
+     * Automatically injected by the `@kosModel` decorator. Use the exported
+     * {@link AgitationRequiredTrouble} constant instead of accessing this directly.
+     *
+     * @see {@link AgitationRequiredTrouble}
+     */
+    static Registration: KosModelRegistrationFactory<AgitationRequiredTroubleModel, AgitationRequiredTroubleOptions>;
+    /**
+     * Unique identifier for this model instance.
+     */
     id: string;
-    private logger;
-    private trouble;
     private _deferred;
     private _holdersLoaded;
+    /**
+     * Configuration property controlling whether to wait for agitation before pouring.
+     *
+     * When enabled, pouring will be deferred if the holder has insufficient agitation troubles.
+     * This ensures beverage quality by preventing pours with inadequate carbonation or mixing.
+     */
     agitateBeforePour: KosConfigProperty<boolean>;
-    constructor(modelId: string, options: AgitationRequiredTroubleOptions, context: KosCreationContext);
+    /**
+     * Creates a new AgitationRequiredTrouble model instance.
+     *
+     * @param modelId - Unique identifier for this model instance (typically matches parent trouble ID)
+     */
+    constructor(modelId: string);
+    /**
+     * Resolves the agitation trouble by delegating to the parent trouble model.
+     *
+     * Resolution typically involves completing the agitation process and clearing
+     * the trouble state once carbonation or mixing levels are acceptable.
+     *
+     * @returns Promise resolving to the future response from the parent trouble's resolution
+     */
     resolve(): Promise<FutureResponse | undefined>;
+    /**
+     * Gets the holder model associated with this agitation trouble.
+     *
+     * The holder is the physical container (cartridge holder, ingredient holder, etc.)
+     * that requires agitation. Returns undefined if the holder model hasn't been
+     * loaded yet through the Assembly model initialization.
+     *
+     * @returns The holder model or undefined if not yet loaded
+     */
     get holder(): HolderModel<any> | undefined;
+    /**
+     * Handles Assembly model events to track when holder models become available.
+     *
+     * This topic handler listens for Assembly model lifecycle events to determine
+     * when holder models have been fully loaded and are accessible.
+     *
+     * @internal
+     */
     updateHolder(): void;
+    /**
+     * Determines if trouble resolution should be deferred until agitation completes.
+     *
+     * Trouble resolution is deferred when:
+     * 1. The holder has active insufficient agitation troubles
+     * 2. The `agitateBeforePour` configuration is enabled
+     *
+     * This ensures that operations requiring agitation (prime, purge, or other
+     * holder-related troubles) wait for proper carbonation or mixing before
+     * being marked as resolved.
+     *
+     * @returns true if trouble resolution should wait for agitation to complete
+     */
     get shouldDefer(): boolean;
+    /**
+     * Gets the current deferral state of this trouble.
+     *
+     * @returns true if this trouble resolution is currently deferred
+     */
     get deferred(): boolean;
+    /**
+     * Marks this trouble as deferred, preventing immediate resolution.
+     *
+     * Called by the trouble system to indicate that trouble resolution
+     * should wait for agitation to complete before being marked as resolved.
+     */
     defer(): void;
+    /**
+     * Clears the deferral state, allowing trouble resolution to proceed.
+     *
+     * Typically called after agitation has completed and the trouble can
+     * now be safely resolved.
+     */
     clearDefer(): void;
 }
+/**
+ * Registration factory for creating AgitationRequiredTrouble model instances.
+ *
+ * Use this constant to create new instances of the agitation trouble model
+ * using the fluent factory pattern.
+ *
+ * @example
+ * ```typescript
+ * // Create a new agitation trouble model
+ * const agitationTrouble = AgitationRequiredTrouble
+ *   .instance(troubleId)
+ *   .options({ companionParent: parentTroubleModel })
+ *   .build();
+ *
+ * // Check deferral status
+ * if (agitationTrouble.shouldDefer) {
+ *   console.log('Pouring deferred due to agitation');
+ * }
+ * ```
+ *
+ * @category Trouble Models
+ */
+export declare const AgitationRequiredTrouble: KosModelRegistrationFactory<AgitationRequiredTroubleModel, AgitationRequiredTroubleOptions>;
 //# sourceMappingURL=agitation-required-trouble-model.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"agitation-required-trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-freestyle-sdk/src/models/models/agitation-required-trouble/agitation-required-trouble-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EAEZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EAEjB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAE/D,eAAO,MAAM,UAAU,qCAAqC,CAAC;AAE7D,MAAM,MAAM,6BAA6B,GACvC,oBAAoB,CAAC,iCAAiC,CAAC,CAAC;AAE1D,eAAO,MAAM,qBAAqB,iBAAkB,YAAY,mDAK/D,CAAC;AAEF,eAAO,MAAM,0BAA0B,iCAAiC,CAAC;AACzE,qBACa,iCACX,YAAW,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU;IAEpE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,cAAc,CAAS;IAM/B,iBAAiB,EAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;gBAG7C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,+BAA+B,EACxC,OAAO,EAAE,kBAAkB;IAQvB,OAAO,IAAI,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAKpD,IAAI,MAAM,iCAST;IAMD,YAAY;IAUZ,IAAI,WAAW,YASd;IAED,IAAI,QAAQ,YAEX;IACD,KAAK;IAIL,UAAU;CAGX"}
+{"version":3,"file":"agitation-required-trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-freestyle-sdk/src/models/models/agitation-required-trouble/agitation-required-trouble-model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAEL,WAAW,EACX,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,2BAA2B,EAC3B,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACb,MAAM,yBAAyB,CAAC;AAWjC,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,qCAAqC,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACvC,oBAAoB,CAAC,iCAAiC,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,qBAAqB,iBAAkB,YAAY,mDAK/D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,iCAAiC,CAAC;AAEzE,MAAM,WAAW,iCACf,SAAQ,cAAc,EACpB,uBAAuB,CAAC,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC1D,0FAA0F;IAC1F,OAAO,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAGa,iCACX,YAAW,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,UAAU;IAEpE;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,EAAE,2BAA2B,CAC9C,6BAA6B,EAC7B,+BAA+B,CAChC,CAAC;IAEF;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,cAAc,CAAS;IAE/B;;;;;OAKG;IAKH,iBAAiB,EAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAE/C;;;;OAIG;gBACS,OAAO,EAAE,MAAM;IAK3B;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAIpD;;;;;;;;OAQG;IAEH,IAAI,MAAM,iCAYT;IAED;;;;;;;OAOG;IAKH,YAAY;IAUZ;;;;;;;;;;;;OAYG;IACH,IAAI,WAAW,YASd;IAED;;;;OAIG;IACH,IAAI,QAAQ,YAEX;IAED;;;;;OAKG;IACH,KAAK;IAIL;;;;;OAKG;IACH,UAAU;CAGX;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,wBAAwB,6FACW,CAAC"}

package/models/models/agitation-required-trouble/index.d.ts

@@ -1,4 +1,6 @@
-export { AGITATION_REQUIRED_TROUBLE, type AgitationRequiredTroubleModel, } from './agitation-required-trouble-model';
-export { AgitationRequiredTrouble } from './agitation-required-trouble-registration';
+/**
+ * (C) Copyright 2024, TCCC, All rights reserved.
+ */
+export { AGITATION_REQUIRED_TROUBLE, AgitationRequiredTrouble, type AgitationRequiredTroubleModel, } from './agitation-required-trouble-model';
 export type * from './types';
 //# sourceMappingURL=index.d.ts.map

package/models/models/agitation-required-trouble/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-freestyle-sdk/src/models/models/agitation-required-trouble/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,KAAK,6BAA6B,GACnC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AACrF,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-freestyle-sdk/src/models/models/agitation-required-trouble/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,6BAA6B,GACnC,MAAM,oCAAoC,CAAC;AAC5C,mBAAmB,SAAS,CAAC"}