kuzzle-device-manager-types 2.4.0-beta.2 → 2.4.0-beta.21

package/dist/lib/modules/model/types/ModelDefinition.d.ts

@@ -1,5 +1,6 @@
 import { JSONObject } from "kuzzle-sdk";
 import { Decoder, NamedMeasures } from "../../../modules/decoder";
+import { MetadataDetails, MetadataGroups, MetadataMappings, TooltipModels } from "./ModelContent";
 /**
  * Define an asset model
  *
@@ -16,6 +17,83 @@ import { Decoder, NamedMeasures } from "../../../modules/decoder";
  *     },
  *     defaultMetadata: {
  *       height: 20
+ *     },
+ *     metadataDetails: {
+ *       "extTemp": {
+ *         "group": "buildingEnv",
+ *         "locales": {
+ *           "en": {
+ *             "friendlyName": "External temperature",
+ *             "description": "Container external temperature"
+ *           },
+ *           "fr": {
+ *             "friendlyName": "Température externe",
+ *             "description": "Température externe du conteneur"
+ *           }
+ *         },
+ *         "definition": {
+ *           "readOnly": false,
+ *           "type": MetadataDetailsEnum.DATETIME,
+ *           "date": true,
+ *           "time": true,
+ *           "customTimeZoneAllowed": true,
+ *        },
+ *       },
+ *     },
+ *     metadataGroups: {
+ *       buildingEnv: {
+ *         locales: {
+ *           en: {
+ *             groupFriendlyName: "Building environment",
+ *             description: "The building environment"
+ *           },
+ *           fr: {
+ *             groupFriendlyName: "Environnement du bâtiment",
+ *             description: "L'environnement du bâtiment"
+ *           }
+ *         }
+ *       }
+ *     },
+ *     tooltipModels: {
+ *       "defaultTooltipKey": {
+ *         "tooltipLabel": "Default Tooltip Model",
+ *         "content": [
+ *           {
+ *             "category": "metadata",
+ *             "label": {
+ *               "locales": {
+ *                 "en": {
+ *                   "friendlyName": "Container position",
+ *                   "description": ""
+ *                 },
+ *                 "fr": {
+ *                   "friendlyName": "Position du conteneur",
+ *                   "description": ""
+ *                 }
+ *               }
+ *             },
+ *             "metadataPath": "geolocation"
+ *           },
+ *           {
+ *             "category": "measure",
+ *             "label": {
+ *               "locales": {
+ *                 "en": {
+ *                   "friendlyName": "External temperature",
+ *                   "description": ""
+ *                 },
+ *                 "fr": {
+ *                   "friendlyName": "Température extérieure",
+ *                   "description": ""
+ *                 }
+ *               }
+ *             },
+ *             "measureSlot": "externalTemperature",
+ *             "measureValuePath": "externalTemperature",
+ *             "suffix": "°C"
+ *           }
+ *         ]
+ *       }
  *     }
  *   }
  *
@@ -28,11 +106,23 @@ export type AssetModelDefinition = {
     /**
      * Metadata mappings definition
      */
-    metadataMappings?: JSONObject;
+    metadataMappings?: MetadataMappings;
     /**
      * Default metadata values
      */
     defaultMetadata?: JSONObject;
+    /**
+     * Metadata details including tanslations and group.
+     */
+    metadataDetails?: MetadataDetails;
+    /**
+     * Metadata groups
+     */
+    metadataGroups?: MetadataGroups;
+    /**
+     * Tooltip models
+     */
+    tooltipModels?: TooltipModels;
 };
 /**
  * Define a device model
@@ -42,9 +132,47 @@ export type AssetModelDefinition = {
  *     decoder: new DummyTempPositionDecoder(),
  *     metadataMappings: {
  *       serial: { type: "keyword" },
- *     }
- *   }
- *
+ *     },
+ *     defaultMetadata: {
+ *       company: "Firebird"
+ *     },
+ *     metadataDetails: {
+ *       sensorType: {
+ *         group: "sensorSpecs",
+ *         locales: {
+ *           en: {
+ *             friendlyName: "Sensor type",
+ *             description: "Type of the sensor"
+ *           },
+ *           fr: {
+ *             friendlyName: "Type de traceur",
+ *             description: "Type du traceur"
+ *           }
+ *         },
+ *         definition: {
+ *           readOnly: false,
+ *           type: MetadataDetailsEnum.DATETIME,
+ *           date: true,
+ *           time: true,
+ *           customTimeZoneAllowed: true,
+ *        },
+ *       },
+ *     },
+ *     metadataGroups: {
+ *      sensorSpecs: {
+ *        locales: {
+ *          en: {
+ *            groupFriendlyName: "Sensor specifications",
+ *            description : "All sensors specifications"
+ *          },
+ *          fr: {
+ *            groupFriendlyName: "Spécifications techniques",
+ *            description: "Toutes les spécifications techniques"
+ *          }
+ *        }
+ *      }
+ *    }
+ *  }
  */
 export type DeviceModelDefinition = {
     /**
@@ -54,9 +182,17 @@ export type DeviceModelDefinition = {
     /**
      * Metadata mappings definition
      */
-    metadataMappings?: JSONObject;
+    metadataMappings?: MetadataMappings;
     /**
      * Default metadata values
      */
     defaultMetadata?: JSONObject;
+    /**
+     * Metadata details including tanslations and group.
+     */
+    metadataDetails?: MetadataDetails;
+    /**
+     * Metadata groups list and details.
+     */
+    metadataGroups?: MetadataGroups;
 };

package/dist/lib/modules/plugin/DeviceManagerEngine.d.ts

@@ -1,9 +1,20 @@
-import { Backend, Plugin } from "kuzzle";
-import { AbstractEngine, ConfigManager } from "kuzzle-plugin-commons";
-import { EngineContent } from "kuzzle-plugin-commons";
-import { DeviceManagerConfiguration } from "./types/DeviceManagerConfiguration";
+import { Backend, KDocumentContent, Plugin } from "kuzzle";
+import { AbstractEngine, ConfigManager, EngineContent } from "kuzzle-plugin-commons";
+import { AssetModelContent, DeviceModelContent, MeasureModelContent } from "../model";
 import { DeviceManagerPlugin } from "./DeviceManagerPlugin";
+import { DeviceManagerConfiguration } from "./types/DeviceManagerConfiguration";
 import { InternalCollection } from "./types/InternalCollection";
+import { ConflictChunk } from "../model/ModelsConflicts";
+export type TwinType = "asset" | "device";
+export type TwinModelContent = AssetModelContent | DeviceModelContent;
+export interface EngineDocument extends KDocumentContent {
+    type: "engine-device-manager";
+    engine: {
+        group: string;
+        index: string;
+        name: string;
+    };
+}
 export type AskEngineList = {
     name: "ask:device-manager:engine:list";
     payload: {
@@ -16,11 +27,48 @@ export type AskEngineUpdateAll = {
     payload: void;
     result: void;
 };
+export type AskEngineUpdateConflict = {
+    name: "ask:device-manager:engine:doesUpdateConflict";
+    payload: {
+        twin?: {
+            type: TwinType;
+            models: TwinModelContent[];
+        };
+        measuresModels?: MeasureModelContent[];
+    };
+    result: ConflictChunk[];
+};
 export declare class DeviceManagerEngine extends AbstractEngine<DeviceManagerPlugin> {
     config: DeviceManagerConfiguration;
     get app(): Backend;
     constructor(plugin: Plugin, adminConfigManager: ConfigManager, engineConfigManager: ConfigManager);
+    /**
+     * Return conflicts between the new and already present twin models
+     *
+     * @param twinType The target twin type
+     * @param twinModels The already present twin models
+     * @param additionalModels The new or updated twin models
+     * @param measureModels The already present measures models
+     *
+     * @throws If a measure type declared in the twin does not exists
+     * @returns An array of conflict chunk
+     */
+    private doesTwinUpdateConflicts;
+    /**
+     * Return conflicts between the new and already present measure models
+     *
+     * @param measuresModels The already present measure models
+     * @param additionalMeasures The new or updated measure models
+     * @returns An array of ConflictChunk
+     */
+    private doesMeasuresUpdateConflicts;
     updateEngines(): Promise<void>;
+    /**
+     * Search and return every engines in use
+     *
+     * @returns An array of the available engines
+     */
+    getEngines(): Promise<EngineDocument[]>;
     onCreate(index: string, group?: string): Promise<{
         collections: any[];
     }>;
@@ -30,12 +78,100 @@ export declare class DeviceManagerEngine extends AbstractEngine<DeviceManagerPlu
     onDelete(index: string): Promise<{
         collections: InternalCollection[];
     }>;
+    /**
+     * Generate assets mappings and create the assets collection in the engine
+     *
+     * @param engineId The target engine Id
+     * @param engineGroup The engine group
+     *
+     * @throws If it failed during the assets collection creation
+     */
     createAssetsCollection(engineId: string, engineGroup: string): Promise<InternalCollection>;
+    /**
+     * Generate assets mappings and create the assets history collection in the engine
+     *
+     * @param engineId The target engine Id
+     * @param engineGroup The engine group
+     *
+     * @throws If it failed during the assets history collection creation
+     */
     createAssetsHistoryCollection(engineId: string, engineGroup: string): Promise<InternalCollection>;
+    /**
+     * Create the assets groups collection with the assets groups mappings in the engine
+     *
+     * @param engineId The target engine Id
+     * @param engineGroup The engine group
+     *
+     * @throws If it failed during the assets groups collection creation
+     */
     createAssetsGroupsCollection(engineId: string): Promise<InternalCollection>;
-    private getDigitalTwinMappings;
+    /**
+     * Generate devices mappings and create the devices collection in the engine
+     *
+     * @param engineId The target engine Id
+     * @param engineGroup The engine group
+     *
+     * @throws If it failed during the devices collection creation
+     */
     createDevicesCollection(engineId: string): Promise<InternalCollection>;
+    /**
+     * Generate measures mappings and create the measures collection in the engine
+     *
+     * @param engineId The target engine Id
+     * @param engineGroup The engine group
+     *
+     * @throws If it failed during the measures collection creation
+     */
     createMeasuresCollection(engineId: string, engineGroup: string): Promise<InternalCollection>;
+    /**
+     * Create a collection with custom mappings in an engine
+     *
+     * @param engineIndex The target engine
+     * @param collection The collection name
+     * @param mappings The collection mappings
+     *
+     * @throws If it failed to create the collection
+     */
+    private tryCreateCollection;
+    /**
+     * Generate ES mappings from twin models and theirs associated measures, all fetched from the database
+     *
+     * @param digitalTwinType The target twin type
+     * @param engineGroup The twin engine group
+     * @returns The complete ES mappings produces by merging all the target type twins
+     */
+    private getDigitalTwinMappingsFromDB;
+    /**
+     * Generate ES mappings from twin models and theirs associated measures
+     *
+     * @param digitalTwinType The target twin type
+     * @param models The twin models
+     * @param measureModels The associated measures
+     * @returns The complete ES mappings produces by merging all the target type twins
+     */
+    private getDigitalTwinMappings;
+    /**
+     * Generate ES mappings from measures and theirs associated assets, all fetched via the database
+     *
+     * @param engineGroup The target engine group
+     * @returns The complete ES mappings produced by merging models mappings
+     */
+    private getMeasuresMappingsFromDB;
+    /**
+     * Generate ES mappings from measures and theirs associated assets
+     *
+     * @param models The measures models
+     * @param assetsMappings The assets complete mappings
+     * @returns The complete ES mappings produced by merging models mappings
+     */
     private getMeasuresMappings;
+    /**
+     * Retrieve a certain type of models associated to an engine
+     *
+     * @param engineId The target engine Id
+     * @param type The desired model type
+     * @param engineGroup The target engine group
+     * @returns An array of the generic type provided
+     */
     private getModels;
 }

package/dist/lib/modules/plugin/DeviceManagerPlugin.d.ts

@@ -22,10 +22,14 @@ export declare class DeviceManagerPlugin extends Plugin {
          * Register an asset model
          *
          * @param engineGroup Engine group name
-         * @param model Name of the asset model
-         * @param definition.measures Array describing measures names and types
-         * @param definition.metadataMappings Metadata mappings definition
-         * @param definition.defaultMetadata Default metadata values
+         * @param model Name of the asset model. Must follow a naming convention in PascalCase.
+         * @param definition Object containing the asset model definition, including:
+         *        - measures: Array describing measure names and their types.
+         *        - metadataMappings: Definition of metadata mappings, specifying types for each metadata field.
+         *        - defaultMetadata: Default values for metadata fields, applied when actual data is not provided.
+         *        - metadataDetails: Optional detailed descriptions for each metadata, including localizations, group association and definition.
+         *        - metadataGroups: Optional description of metadata groups, organizing metadata logically, with localizations for group names.
+         *        - tooltipModels: Optional tooltip model list, containing each labels and tooltip content to display.
          *
          * @example
          * ```
@@ -44,6 +48,74 @@ export declare class DeviceManagerPlugin extends Plugin {
          *     },
          *     defaultMetadata: {
          *       height: 20
+         *     },
+         *     metadataDetails: {
+         *       "extTemp": {
+         *         "group": "environment",
+         *         "locales": {
+         *           "en": {
+         *             "friendlyName": "External Temperature",
+         *             "description": "The temperature outside the container"
+         *           },
+         *           "fr": {
+         *             "friendlyName": "Température Externe",
+         *             "description": "La température à l'extérieur du conteneur"
+         *           }
+         *         }
+         *       }
+         *     },
+         *     metadataGroups: {
+         *       "environment": {
+         *         "locales": {
+         *           "en": {
+         *             "groupFriendlyName": "Environment"
+         *           },
+         *           "fr": {
+         *             "groupFriendlyName": "Environnement"
+         *           }
+         *         }
+         *       }
+         *     },
+         *     tooltipModels: {
+         *       "defaultTooltipKey": {
+         *         "tooltipLabel": "Default Tooltip Model",
+         *         "content": [
+         *           {
+         *             "category": "metadata",
+         *             "label": {
+         *               "locales": {
+         *                 "en": {
+         *                   "friendlyName": "Container position",
+         *                   "description": ""
+         *                 },
+         *                 "fr": {
+         *                   "friendlyName": "Position du conteneur",
+         *                   "description": ""
+         *                 }
+         *               }
+         *             },
+         *             "metadataPath": "geolocation"
+         *           },
+         *           {
+         *             "category": "measure",
+         *             "label": {
+         *               "locales": {
+         *                 "en": {
+         *                   "friendlyName": "External temperature",
+         *                   "description": ""
+         *                 },
+         *                 "fr": {
+         *                   "friendlyName": "Température extérieure",
+         *                   "description": ""
+         *                 }
+         *               }
+         *             },
+         *             "measureSlot": "externalTemperature",
+         *             "measureValuePath": "externalTemperature",
+         *             "suffix": "°C"
+         *           }
+         *         ]
+         *       }
          *     }
          *   }
          * );
@@ -51,12 +123,15 @@ export declare class DeviceManagerPlugin extends Plugin {
          */
         registerAsset: (engineGroup: string, model: string, definition: AssetModelDefinition) => void;
         /**
-         * Register a device model
+         * Register a device.
          *
          * @param model Name of the device model
-         * @param definition.decoded Decoder used to decode payloads
-         * @param definition.metadataMappings Metadata mappings definition
-         * @param definition.defaultMetadata Default metadata values
+         * @param definition Object containing the device model definition, including:
+         *                   - decoder: Decoder used to decode payloads
+         *                   - metadataMappings: Metadata mappings definition
+         *                   - defaultMetadata: Default metadata values
+         *                   - metadataDetails: Localizations, detailed metadata descriptions and definition
+         *                   - metadataGroups: Groups for organizing metadata, with localizations
          *
          * @example
          * ```
@@ -66,6 +141,36 @@ export declare class DeviceManagerPlugin extends Plugin {
          *     decoder: new DummyTempPositionDecoder(),
          *     metadataMappings: {
          *       serial: { type: "keyword" },
+         *     },
+         *     defaultMetadata: {
+         *       company: "Acme Inc"
+         *     },
+         *     metadataDetails: {
+         *       sensorVersion: {
+         *         group: "sensorSpecs",
+         *         locales: {
+         *           en: {
+         *             friendlyName: "Sensor version",
+         *             description: "Firmware version of the sensor"
+         *           },
+         *           fr: {
+         *             friendlyName: "Version du capteur",
+         *             description: "Version du micrologiciel du capteur"
+         *           }
+         *         }
+         *       }
+         *     },
+         *     metadataGroups: {
+         *       sensorSpecs: {
+         *         locales: {
+         *           en: {
+         *             groupFriendlyName: "Sensors specifications"
+         *           },
+         *           fr: {
+         *             groupFriendlyName: "Spécifications des capteurs"
+         *           }
+         *         }
+         *       }
          *     }
          *   }
          * );

package/dist/lib/modules/plugin/exports.d.ts

@@ -1,2 +1,2 @@
-export * from "./types/DeviceManagerConfiguration";
+export * from "./types/exports";
 export * from "./DeviceManagerPlugin";

package/dist/lib/modules/plugin/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./types/DeviceManagerConfiguration";
+export * from "./types";
 export * from "./DeviceManagerEngine";
 export * from "./DeviceManagerPlugin";
-export * from "./types/InternalCollection";

package/dist/lib/modules/plugin/types/DeviceManagerConfiguration.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import { CollectionMappings, JSONObject } from "kuzzle-sdk";
 export type DeviceManagerConfiguration = {
     /**
      * Ignore errors at startup such as wrong mappings update.
@@ -26,24 +26,46 @@ export type DeviceManagerConfiguration = {
         config: {
             name: string;
             mappings: JSONObject;
-            settings: JSONObject;
+            settings?: JSONObject;
         };
         devices: {
             name: string;
             mappings: JSONObject;
-            settings: JSONObject;
+            settings?: JSONObject;
         };
         payloads: {
             name: string;
             mappings: JSONObject;
-            settings: JSONObject;
+            settings?: JSONObject;
         };
     };
     engineCollections: {
         config: {
             name: string;
             mappings: JSONObject;
-            settings: JSONObject;
+            settings?: JSONObject;
+        };
+        asset: {
+            name: string;
+            mappings: CollectionMappings;
+            settings?: JSONObject;
+        };
+        assetGroups: {
+            name: string;
+            settings?: JSONObject;
+        };
+        assetHistory: {
+            name: string;
+            settings?: JSONObject;
+        };
+        device: {
+            name: string;
+            mappings: CollectionMappings;
+            settings?: JSONObject;
+        };
+        measures: {
+            name: string;
+            settings?: JSONObject;
         };
     };
 };

package/dist/lib/modules/plugin/types/Pipes.d.ts

@@ -0,0 +1,17 @@
+import { JSONObject, KDocumentContent, KHit, KuzzleRequest } from "kuzzle";
+export interface SearchQueryResult<T extends KDocumentContent> {
+    aggregations?: JSONObject;
+    hits: Array<KHit<T>>;
+    remaining: unknown;
+    scrollId: string;
+    suggest: JSONObject;
+    total: number;
+}
+export type EventGenericDocumentBeforeSearch = {
+    name: `generic:document:beforeSearch`;
+    args: [JSONObject, KuzzleRequest];
+};
+export type EventGenericDocumentAfterSearch<T extends KDocumentContent = KDocumentContent> = {
+    name: `generic:document:afterSearch`;
+    args: [SearchQueryResult<T>, KuzzleRequest];
+};

package/dist/lib/modules/plugin/types/exports.d.ts

@@ -0,0 +1 @@
+export * from "./DeviceManagerConfiguration";

package/dist/lib/modules/plugin/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./DeviceManagerConfiguration";
+export * from "./InternalCollection";
+export * from "./Pipes";

package/dist/lib/modules/shared/exports.d.ts

@@ -1,3 +1,5 @@
 export * from "./types/DigitalTwinContent";
+export * from "./types/DigitalTwinEvents";
+export * from "./types/DigitalTwinMeasures";
 export * from "./types/Metadata";
 export * from "./types/EmbeddedMeasure";

package/dist/lib/modules/shared/index.d.ts

@@ -1,11 +1,13 @@
-export * from "./services";
 export * from "./Module";
+export * from "./services";
+export * from "./types/DigitalTwinApi";
 export * from "./types/DigitalTwinContent";
-export * from "./types/Metadata";
+export * from "./types/DigitalTwinEvents";
+export * from "./types/DigitalTwinMeasures";
 export * from "./types/EmbeddedMeasure";
 export * from "./types/KuzzleRole";
-export * from "./utils/lock";
+export * from "./types/Metadata";
 export * from "./utils/flattenObject";
-export * from "./utils/ask";
 export * from "./utils/keepStack";
+export * from "./utils/lock";
 export * from "./utils/objectDiff";

package/dist/lib/modules/shared/services/AbstractExporter.d.ts

@@ -20,6 +20,7 @@ export interface Column {
     header: string;
     path: string;
     isMeasure?: boolean;
+    isIsoDate?: boolean;
 }
 export declare abstract class AbstractExporter<P extends ExportParams = ExportParams> {
     protected plugin: DeviceManagerPlugin;