@kosdev-code/kos-dispense-sdk 2.1.31 → 2.1.33

package/models/models/types/intent.d.ts

@@ -16,4 +16,102 @@ export interface IntentAware extends IKosIdentifiable {
     cancelPour: () => Promise<void>;
     performIntent(props: IntentAwareProps | string): Promise<FutureResponse | undefined>;
 }
+/**
+ * Interface for models that can resolve intent volumes for various operations.
+ *
+ * This interface extends intent-aware models with the ability to calculate
+ * appropriate volumes for specific intents (e.g., CALIBRATE, PRIME, FLUSH).
+ * Typically implemented by holder and pump models that have ingredient assignments
+ * and need to determine operation-specific volumes based on ingredient type,
+ * pump configuration, or operational requirements.
+ *
+ * Use this interface in combination with {@link IntentAware} to create models
+ * that can both determine appropriate volumes and execute the operations.
+ *
+ * @example
+ * Using IntentContainer for calibration:
+ * ```typescript
+ * async function calibratePump(holder: HolderModel & IntentContainer) {
+ *   // Resolve appropriate calibration volume
+ *   const result = await holder.resolveIntentVolume("CALIBRATE");
+ *   console.log(`Calibration requires ${result.volume} oz`);
+ *
+ *   // Execute calibration with resolved volume
+ *   await holder.performIntent("CALIBRATE");
+ * }
+ * ```
+ *
+ * @example
+ * Checking for ingredient assignment:
+ * ```typescript
+ * function canResolveVolume(model: IntentContainer): boolean {
+ *   return model.ingredientId !== undefined;
+ * }
+ * ```
+ *
+ * @category Model Interfaces
+ * @see {@link IntentAware} for intent execution capabilities
+ */
+export interface IntentContainer {
+    /**
+     * Resolves the appropriate volume for a given intent operation.
+     *
+     * Different intents require different volumes based on operational requirements:
+     * - **CALIBRATE**: Standard calibration volume based on ingredient type and pump configuration
+     * - **PRIME**: Volume needed to prime the line from reservoir to dispense point
+     * - **FLUSH**: Cleaning volume to flush contaminants from the system
+     * - **PURGE**: Volume to completely clear the line
+     *
+     * The resolved volume is calculated based on:
+     * - Ingredient type and properties
+     * - Pump hardware configuration (line length, diameter)
+     * - Operational parameters (flow rates, pressure)
+     * - Device-specific calibration data
+     *
+     * @param intent - The intent string identifier (e.g., "CALIBRATE", "PRIME", "FLUSH")
+     * @returns Promise resolving to object with `volume` property in ounces (oz)
+     *
+     * @throws May reject if ingredient is not assigned or volume cannot be determined
+     *
+     * @example
+     * Resolving calibration volume:
+     * ```typescript
+     * const result = await holder.resolveIntentVolume("CALIBRATE");
+     * console.log(`Calibration: ${result.volume} oz`);
+     * ```
+     *
+     * @example
+     * Handling volume resolution errors:
+     * ```typescript
+     * try {
+     *   const result = await holder.resolveIntentVolume("PRIME");
+     *   displayVolume(result.volume);
+     * } catch (error) {
+     *   console.error("Cannot resolve volume - ingredient may not be assigned");
+     * }
+     * ```
+     */
+    resolveIntentVolume(intent: string): Promise<{
+        volume: number;
+    }>;
+    /**
+     * Optional ingredient identifier for the assigned ingredient.
+     *
+     * When undefined, no ingredient is assigned to this holder/pump and volume
+     * resolution operations may fail or return default values. Check this property
+     * before calling {@link resolveIntentVolume} to ensure an ingredient is assigned.
+     *
+     * @example
+     * Checking for assignment before resolving volume:
+     * ```typescript
+     * if (holder.ingredientId) {
+     *   const volume = await holder.resolveIntentVolume("CALIBRATE");
+     *   // Use volume...
+     * } else {
+     *   console.log("No ingredient assigned - cannot calibrate");
+     * }
+     * ```
+     */
+    ingredientId?: string;
+}
 //# sourceMappingURL=intent.d.ts.map

package/models/models/types/intent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-dispense-sdk/src/models/models/types/intent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,aAAa,CACX,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAC/B,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CACxC"}
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-dispense-sdk/src/models/models/types/intent.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,aAAa,CACX,KAAK,EAAE,gBAAgB,GAAG,MAAM,GAC/B,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjE;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-dispense-sdk",
-  "version": "2.1.31",
+  "version": "2.1.33",
   "type": "module",
   "types": "./index.d.ts",
   "main": "./index.js",
@@ -33,7 +33,7 @@
   },
   "kos": {
     "build": {
-      "gitHash": "292ed660445b69d5a70bd9b40e6f910b97b19867"
+      "gitHash": "e05cb0b38c81d9ea95d719504f4afe4a6c8737bf"
     }
   }
 }