kuzzle-device-manager-types 2.4.0-beta.9 → 2.4.0-dev.1

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/types/DeviceManagerConfiguration.d.ts

@@ -26,32 +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/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

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import { UUID } from "node:crypto";
 import { PassThrough, Readable } from "node:stream";
 import { JSONObject, KDocumentContentGeneric, KHit, SearchResult, User } from "kuzzle";
@@ -20,6 +18,7 @@ export interface Column {
     header: string;
     path: string;
     isMeasure?: boolean;
+    isIsoDate?: boolean;
 }
 export declare abstract class AbstractExporter<P extends ExportParams = ExportParams> {
     protected plugin: DeviceManagerPlugin;

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

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import { UUID } from "node:crypto";
 import { AbstractExporter } from "./AbstractExporter";
 export declare class DigitalTwinExporter extends AbstractExporter {

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

@@ -0,0 +1,21 @@
+import { MeasureContent } from "../../measure";
+import { DeviceManagerPlugin, InternalCollection } from "../../plugin";
+import { ApiDigitalTwinMGetLastMeasuredAtResult } from "../types/DigitalTwinApi";
+import { BaseService } from "./BaseService";
+export declare class DigitalTwinService extends BaseService {
+    private targetCollection;
+    private readonly digitalTwinType;
+    constructor(plugin: DeviceManagerPlugin, targetCollection: InternalCollection);
+    protected registerAskEvents(): void;
+    /**
+     * Gets the last measures of a digital twin
+     */
+    getLastMeasures(engineId: string, digitalTwinId: string, measureCount?: number): Promise<MeasureContent[]>;
+    /**
+     * Gets the last measures of multiple digital twins
+     */
+    mGetLastMeasures(engineId: string, digitalTwinIds: string[], measureCount?: number): Promise<Record<string, MeasureContent[]>>;
+    getLastMeasuredAt(engineId: string, digitalTwinId: string): Promise<number>;
+    mGetLastMeasuredAt(engineId: string, digitalTwinIds: string[]): Promise<ApiDigitalTwinMGetLastMeasuredAtResult>;
+    private getAggregationQueryParameters;
+}

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

@@ -1,3 +1,4 @@
 export * from "./AbstractExporter";
 export * from "./BaseService";
 export * from "./DigitalTwinExporter";
+export * from "./DigitalTwinService";

package/dist/lib/modules/shared/types/DigitalTwinApi.d.ts

@@ -0,0 +1,34 @@
+import { DigitalTwinMeasures } from "./DigitalTwinMeasures";
+interface DigitalTwinControllerRequest<ControllerName extends string> {
+    controller: ControllerName;
+    engineId: string;
+}
+export interface ApiDigitalTwinGetLastMeasuresRequest<ControllerName extends string> extends DigitalTwinControllerRequest<ControllerName> {
+    action: "getLastMeasures";
+    _id: string;
+    measureCount?: number;
+}
+export type ApiDigitalTwinGetLastMeasuresResult = DigitalTwinMeasures;
+export interface ApiDigitalTwinMGetLastMeasuresRequest<ControllerName extends string> extends DigitalTwinControllerRequest<ControllerName> {
+    action: "mGetLastMeasures";
+    measureCount?: number;
+    body: {
+        ids: string[];
+    };
+}
+export type ApiDigitalTwinMGetLastMeasuresResult = Record<string, DigitalTwinMeasures>;
+export interface ApiDigitalTwinGetLastMeasuredAtRequest<ControllerName extends string> extends DigitalTwinControllerRequest<ControllerName> {
+    action: "getLastMeasuredAt";
+    _id: string;
+}
+export type ApiDigitalTwinGetLastMeasuredAtResult = {
+    lastMeasuredAt: number;
+};
+export interface ApiDigitalTwinMGetLastMeasuredAtRequest<ControllerName extends string> extends DigitalTwinControllerRequest<ControllerName> {
+    action: "mGetLastMeasuredAt";
+    body: {
+        ids: string[];
+    };
+}
+export type ApiDigitalTwinMGetLastMeasuredAtResult = Record<string, number>;
+export {};

package/dist/lib/modules/shared/types/DigitalTwinContent.d.ts

@@ -1,12 +1,10 @@
 import { JSONObject, KDocumentContent } from "kuzzle-sdk";
-import { EmbeddedMeasure } from "./EmbeddedMeasure";
 import { Metadata } from "./Metadata";
+import { DigitalTwinMeasures } from "./DigitalTwinMeasures";
 export interface DigitalTwinContent<TMeasures extends JSONObject = JSONObject, TMetadata extends Metadata = Metadata> extends KDocumentContent {
     model: string;
     reference: string;
     metadata: TMetadata;
-    measures: {
-        [Property in keyof TMeasures]: EmbeddedMeasure<TMeasures[Property]> | null;
-    };
+    measures: DigitalTwinMeasures<TMeasures>;
     lastMeasuredAt: number;
 }

package/dist/lib/modules/shared/types/DigitalTwinEvents.d.ts

@@ -0,0 +1,9 @@
+import { MeasureContent } from "../../measure";
+export type AskDigitalTwinLastMeasuresGet = {
+    name: "ask:device-manager:asset:get-last-measures" | "ask:device-manager:device:get-last-measures";
+    payload: {
+        engineId: string;
+        digitalTwinId: string;
+    };
+    result: MeasureContent[];
+};

package/dist/lib/modules/shared/types/DigitalTwinMeasures.d.ts

@@ -0,0 +1,5 @@
+import { JSONObject } from "kuzzle-sdk";
+import { EmbeddedMeasure } from "./EmbeddedMeasure";
+export type DigitalTwinMeasures<TMeasures extends JSONObject = JSONObject> = {
+    [Property in keyof TMeasures]: EmbeddedMeasure<TMeasures[Property]> | null;
+};

package/dist/tests/application/assets/Container.d.ts

@@ -6,6 +6,9 @@ export interface ContainerMetadata extends Metadata {
         weight: number;
         capacity: number;
     };
+    person: {
+        company: string;
+    };
 }
 export type ContainerMeasurements = {
     temperatureExt: TemperatureMeasurement;

package/dist/tests/application/assets/Room.d.ts

@@ -0,0 +1,2 @@
+import { AssetModelDefinition } from "../../../index";
+export declare const roomAssetDefinition: AssetModelDefinition;

package/dist/tests/application/assets/StreetLamp.d.ts

@@ -0,0 +1,2 @@
+import { AssetModelDefinition } from "../../../index";
+export declare const streetLampAssetDefinition: AssetModelDefinition;

package/dist/tests/application/decoders/DummyTempPositionDecoder.d.ts

@@ -11,6 +11,7 @@ export declare class DummyTempPositionDecoder extends Decoder {
         readonly name: "position";
         readonly type: "position";
     }];
+    constructor();
     validate(payload: JSONObject): Promise<boolean>;
     decode(decodedPayload: DecodedPayload<DummyTempPositionDecoder>, payload: JSONObject): Promise<DecodedPayload<DummyTempPositionDecoder>>;
 }

package/dist/tests/application/measures/BrightnessMeasure.d.ts

@@ -0,0 +1,2 @@
+import { MeasureDefinition } from "lib/modules/measure";
+export declare const brightnessMeasureDefinition: MeasureDefinition;

package/dist/tests/application/measures/CO2Measure.d.ts

@@ -0,0 +1,2 @@
+import { MeasureDefinition } from "lib/modules/measure";
+export declare const co2MeasureDefinition: MeasureDefinition;

package/dist/tests/application/measures/IlluminanceMeasure.d.ts

@@ -0,0 +1,2 @@
+import { MeasureDefinition } from "lib/modules/measure";
+export declare const illuminanceMeasureDefinition: MeasureDefinition;

package/dist/tests/application/measures/PowerConsumptionMeasure.d.ts

@@ -0,0 +1,2 @@
+import { MeasureDefinition } from "lib/modules/measure";
+export declare const powerConsumptionMeasureDefinition: MeasureDefinition;

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "kuzzle-device-manager-types",
-  "version": "2.4.0-beta.9",
+  "version": "2.4.0-dev.1",
   "description": "Shared types for Kuzzle Device Manager",
   "author": "The Kuzzle Team (support@kuzzle.io)",
   "main": "index.js",
   "types": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kuzzleio/kuzzle-plugin-device-manager.git"
+    "url": "git+https://github.com/kuzzleio/kuzzle-plugin-device-manager.git",
+    "directory": "types"
   },
   "scripts": {
     "prepack": "npm run build",
-    "build": "./copy-types.sh && node scripts/copy-version.js"
+    "build": "./copy-types.sh"
   },
   "license": "Apache-2.0",
   "files": [

package/dist/lib/modules/shared/utils/ask.d.ts

@@ -1,8 +0,0 @@
-export type AskEventDefinition = {
-    name: string;
-    payload: any;
-    result: any;
-};
-export type AskEventHandler<TAskEventDefinition extends AskEventDefinition = AskEventDefinition> = (payload?: TAskEventDefinition["payload"]) => Promise<TAskEventDefinition["result"]>;
-export declare function onAsk<TAskEventDefinition extends AskEventDefinition = AskEventDefinition>(event: TAskEventDefinition["name"], handler: AskEventHandler<TAskEventDefinition>): any;
-export declare function ask<TAskEventDefinition extends AskEventDefinition = AskEventDefinition>(event: TAskEventDefinition["name"], payload?: TAskEventDefinition["payload"]): Promise<TAskEventDefinition["result"]>;