kuzzle-device-manager-types 1.0.0 → 2.0.0-rc35

package/README.md

@@ -0,0 +1,17 @@
+# Kuzzle Device Manager Types
+
+This package only contains types to work with in a frontend application.
+
+```
+
+import { DeviceContent } from 'kuzzle-device-manager-types';
+
+
+let device: DeviceContent;
+
+device.model = "Abeeway";
+```
+
+See main package for more informations:
+ - [Github](https://github.com/kuzzleio/kuzzle-device-manager)
+ - [NPM](https://www.npmjs.com/package/kuzzle-device-manager)

package/dist/features/fixtures/application/app.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/fixtures/application/assets/Container.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/fixtures/application/decoders/DummyTempDecoder.d.ts

@@ -0,0 +1,11 @@
+import { JSONObject } from "kuzzle";
+import { Decoder, DecodedPayload } from "../../../../index";
+export declare class DummyTempDecoder extends Decoder {
+    measures: readonly [{
+        readonly name: "temperature";
+        readonly type: "temperature";
+    }];
+    constructor();
+    validate(payload: JSONObject): Promise<boolean>;
+    decode(decodedPayload: DecodedPayload<DummyTempDecoder>, payload: JSONObject): Promise<DecodedPayload<DummyTempDecoder>>;
+}

package/dist/features/fixtures/application/decoders/DummyTempPositionDecoder.d.ts

@@ -0,0 +1,16 @@
+import { JSONObject } from "kuzzle";
+import { Decoder, DecodedPayload } from "../../../../index";
+export declare class DummyTempPositionDecoder extends Decoder {
+    measures: readonly [{
+        readonly name: "temperature";
+        readonly type: "temperature";
+    }, {
+        readonly name: "battery";
+        readonly type: "battery";
+    }, {
+        readonly name: "position";
+        readonly type: "position";
+    }];
+    validate(payload: JSONObject): Promise<boolean>;
+    decode(decodedPayload: DecodedPayload<DummyTempPositionDecoder>, payload: JSONObject): Promise<DecodedPayload<DummyTempPositionDecoder>>;
+}

package/dist/features/fixtures/application/decoders/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./DummyTempDecoder";
+export * from "./DummyTempPositionDecoder";

package/dist/features/fixtures/application/testPipes.d.ts

@@ -0,0 +1,2 @@
+import { Backend } from "kuzzle";
+export declare function registerTestPipes(app: Backend): void;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './lib/core/DeviceManagerPlugin';
+export * from './lib/core/DeviceManagerConfiguration';
+export * from './lib/modules/asset';
+export * from './lib/modules/device';
+export * from './lib/modules/measure';
+export * from './lib/modules/decoder';
+export * from './lib/modules/shared';
+export * from './lib/modules/model';

package/dist/lib/core/DeviceManagerConfiguration.d.ts

@@ -0,0 +1,49 @@
+import { JSONObject } from "kuzzle";
+export type DeviceManagerConfiguration = {
+    /**
+     * Ignore errors at startup such as wrong mappings update.
+     *
+     * Useful to start the plugin even if the mappings are not up to date.
+     */
+    ignoreStartupErrors: boolean;
+    engine: {
+        /**
+         * Auto update collection mappings with models
+         *
+         * This can lead to huge pressure on the database at start if a lot
+         * of engine are present.
+         */
+        autoUpdate: true;
+    };
+    /**
+     * Administration index name
+     */
+    adminIndex: string;
+    /**
+     * Administration collections mappings (in admin index)
+     */
+    adminCollections: {
+        config: {
+            name: string;
+            mappings: JSONObject;
+            settings: JSONObject;
+        };
+        devices: {
+            name: string;
+            mappings: JSONObject;
+            settings: JSONObject;
+        };
+        payloads: {
+            name: string;
+            mappings: JSONObject;
+            settings: JSONObject;
+        };
+    };
+    engineCollections: {
+        config: {
+            name: string;
+            mappings: JSONObject;
+            settings: JSONObject;
+        };
+    };
+};

package/dist/lib/core/DeviceManagerEngine.d.ts

@@ -0,0 +1,31 @@
+import { Backend, Plugin } from "kuzzle";
+import { AbstractEngine, ConfigManager } from "kuzzle-plugin-commons";
+import { DeviceManagerConfiguration } from "./DeviceManagerConfiguration";
+import { DeviceManagerPlugin } from "./DeviceManagerPlugin";
+import { InternalCollection } from "./InternalCollection";
+export type AskEngineUpdateAll = {
+    name: "ask:device-manager:engine:updateAll";
+    payload: void;
+    result: void;
+};
+export declare class DeviceManagerEngine extends AbstractEngine<DeviceManagerPlugin> {
+    config: DeviceManagerConfiguration;
+    get app(): Backend;
+    constructor(plugin: Plugin, adminConfigManager: ConfigManager, engineConfigManager: ConfigManager);
+    updateEngines(): Promise<void>;
+    onCreate(index: string, group?: string): Promise<{
+        collections: string[];
+    }>;
+    onUpdate(index: string, group?: string): Promise<{
+        collections: any[];
+    }>;
+    onDelete(index: string): Promise<{
+        collections: string[];
+    }>;
+    createAssetsCollection(engineId: string, engineGroup: string): Promise<InternalCollection>;
+    private getDigitalTwinMappings;
+    createDevicesCollection(engineId: string): Promise<InternalCollection>;
+    createMeasuresCollection(engineId: string, engineGroup: string): Promise<InternalCollection>;
+    private getMeasuresMappings;
+    private getModels;
+}

package/dist/lib/core/DeviceManagerPlugin.d.ts

@@ -0,0 +1,115 @@
+import { Plugin, PluginContext, JSONObject } from "kuzzle";
+import { MeasureDefinition } from "../modules/measure";
+import { AssetModelDefinition, DeviceModelDefinition } from "../modules/model";
+import { DeviceManagerConfiguration } from "./DeviceManagerConfiguration";
+import { KuzzleRole } from "lib/modules/shared/types/KuzzleRole";
+export declare class DeviceManagerPlugin extends Plugin {
+    config: DeviceManagerConfiguration;
+    roles: KuzzleRole[];
+    private deviceManagerEngine;
+    private adminConfigManager;
+    private engineConfigManager;
+    private engineController;
+    private assetModule;
+    private deviceModule;
+    private decoderModule;
+    private measureModule;
+    private modelModule;
+    private modelsRegister;
+    private decodersRegister;
+    private get sdk();
+    get models(): {
+        /**
+         * Register an asset model
+         *
+         * @param engineGroup Engine group name
+         * @param model Name of the asset model
+         * @param definition.measuresNames Array describing measures names and types
+         * @param definition.metadataMappings Metadata mappings definition
+         * @param definition.defaultMetadata Default metadata values
+         *
+         * @example
+         * ```
+         * deviceManager.models.registerAsset(
+         *   "logistic",
+         *   "container",
+         *   {
+         *     measuresNames: [
+         *       { name: "temperatureExt", type: "temperature" },
+         *       { name: "temperatureInt", type: "temperature" },
+         *       { name: "position", type: "position" },
+         *     ],
+         *     metadataMappings: {
+         *       weight: { type: "integer" },
+         *       height: { type: "integer" },
+         *     },
+         *     defaultMetadata: {
+         *       height: 20
+         *     }
+         *   }
+         * );
+         * ```
+         */
+        registerAsset: (engineGroup: string, model: string, definition: AssetModelDefinition) => void;
+        /**
+         * Register a device model
+         *
+         * @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
+         *
+         * @example
+         * ```
+         * deviceManager.models.registerDevice(
+         *   "Abeeway",
+         *   {
+         *     decoder: new DummyTempPositionDecoder(),
+         *     metadataMappings: {
+         *       serial: { type: "keyword" },
+         *     }
+         *   }
+         * );
+         * ```
+         */
+        registerDevice: (model: string, definition: DeviceModelDefinition) => void;
+        /**
+         * Register a new measure
+         *
+         * @param name Name of the measure
+         * @param valuesMappings Mappings for the measure values
+         *
+         * @example
+         * ```
+         * deviceManager.models.registerMeasure("acceleration", {
+         *   x: { type: "float" },
+         *   y: { type: "float" },
+         *   z: { type: "float" },
+         * });
+         * ```
+         */
+        registerMeasure: (name: string, measureDefinition: MeasureDefinition) => void;
+    };
+    constructor();
+    /**
+     * Init the plugin
+     */
+    init(config: JSONObject, context: PluginContext): Promise<void>;
+    private createDefaultRoles;
+    /**
+     * Initialize the administration index of the plugin
+     */
+    private initDatabase;
+    /**
+     * Merge custom mappings defined in the Decoder into the "payloads" collection
+     * mappings.
+     *
+     * Those custom mappings allow to search raw payloads more efficiently.
+     */
+    private getPayloadsMappings;
+    /**
+     * Initialize the config document if it does not exists
+     */
+    private initializeConfig;
+    private pipeCheckEngine;
+}

package/dist/lib/core/InternalCollection.d.ts

@@ -0,0 +1,7 @@
+export declare enum InternalCollection {
+    ASSETS = "assets",
+    DEVICES = "devices",
+    MEASURES = "measures",
+    MODELS = "models",
+    CONFIG = "config"
+}

package/dist/lib/core/index.d.ts

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

package/dist/lib/core/registers/DecodersRegister.d.ts

@@ -0,0 +1,41 @@
+import { PluginContext } from "kuzzle";
+import { Decoder, DecoderContent } from "../../modules/decoder";
+export declare class DecodersRegister {
+    private context;
+    /**
+     * Map<deviceModel, Decoder>
+     */
+    private _decoders;
+    private get sdk();
+    get decoders(): Decoder[];
+    init(context: PluginContext): void;
+    get(deviceModel: string): Decoder;
+    list(): DecoderContent[];
+    /**
+     * Registers a new decoder for a device model.
+     * Decoder and device models share a 1:1 relationship
+     *
+     * This will register a new API action:
+     *  - controller: `device-manager/payload`
+     *  - action: `action` property of the decoder or the device model in kebab-case
+     *
+     * @param decoder Instantiated decoder
+     *
+     * @returns Corresponding API action requestPayload
+     */
+    register(decoder: Decoder): {
+        action: string;
+        controller: string;
+    };
+    printDecoders(): void;
+    /**
+     * Creates default roles, profiles and users associated to the generated actions
+     * in the Payload controller.
+     *
+     * This method never returns a rejected promise.
+     */
+    createDefaultRights(): Promise<void>;
+    private createDefaultUsers;
+    private createDefaultProfiles;
+    private createDefaultRoles;
+}

package/dist/lib/core/registers/ModelsRegister.d.ts

@@ -0,0 +1,17 @@
+import { JSONObject } from "kuzzle";
+import { MeasureDefinition } from "lib/modules/measure";
+import { DeviceManagerPlugin } from "../DeviceManagerPlugin";
+export declare class ModelsRegister {
+    private config;
+    private context;
+    private assetModels;
+    private deviceModels;
+    private measureModels;
+    private get sdk();
+    init(plugin: DeviceManagerPlugin): void;
+    loadModels(): Promise<void>;
+    registerAsset(engineGroup: string, model: string, metadataMappings: JSONObject, measures: Record<string, string>, defaultMetadata?: JSONObject): void;
+    registerDevice(model: string, measures: Record<string, string>, metadataMappings?: JSONObject, defaultMetadata?: JSONObject): void;
+    registerMeasure(type: string, measureDefinition: MeasureDefinition): void;
+    private load;
+}

package/dist/lib/modules/asset/AssetModule.d.ts

@@ -0,0 +1,6 @@
+import { Module } from "../shared/Module";
+export declare class AssetModule extends Module {
+    private assetService;
+    private assetController;
+    init(): Promise<void>;
+}

package/dist/lib/modules/asset/AssetService.d.ts

@@ -0,0 +1,44 @@
+import { JSONObject, KDocument, KHit, SearchResult } from "kuzzle";
+import { MeasureContent } from "../measure/";
+import { Metadata } from "../shared";
+import { DeviceManagerPlugin } from "../../core";
+import { AssetContent } from "./types/AssetContent";
+export declare class AssetService {
+    private context;
+    private config;
+    private get sdk();
+    private get app();
+    constructor(plugin: DeviceManagerPlugin);
+    /**
+     * Returns measures history for an asset
+     *
+     * @param engineId Engine ID
+     * @param assetId Asset ID
+     * @param options.size Number of measures to return
+     * @param options.startAt Returns measures starting from this date (ISO8601)
+     * @param options.endAt Returns measures until this date (ISO8601)
+     */
+    getMeasureHistory(engineId: string, assetId: string, { size, startAt, endAt, }: {
+        size?: number;
+        startAt?: string;
+        endAt?: string;
+    }): Promise<KDocument<MeasureContent>[]>;
+    get(engineId: string, assetId: string): Promise<KDocument<AssetContent>>;
+    update(engineId: string, assetId: string, metadata: Metadata, { refresh }: {
+        refresh: any;
+    }): Promise<KDocument<AssetContent>>;
+    create(engineId: string, model: string, reference: string, metadata: JSONObject, { refresh }: {
+        refresh: any;
+    }): Promise<KDocument<AssetContent>>;
+    delete(engineId: string, assetId: string, { refresh, strict }: {
+        refresh: any;
+        strict: boolean;
+    }): Promise<void>;
+    search(engineId: string, searchBody: JSONObject, { from, size, scroll, lang, }: {
+        from?: number;
+        size?: number;
+        scroll?: string;
+        lang?: string;
+    }): Promise<SearchResult<KHit<AssetContent>>>;
+    private getEngine;
+}

package/dist/lib/modules/asset/AssetsController.d.ts

@@ -0,0 +1,14 @@
+import { ControllerDefinition, KuzzleRequest } from "kuzzle";
+import { AssetService } from "./AssetService";
+import { ApiAssetCreateResult, ApiAssetDeleteResult, ApiAssetGetMeasuresResult, ApiAssetGetResult, ApiAssetSearchResult, ApiAssetUpdateResult } from "./types/AssetApi";
+export declare class AssetsController {
+    definition: ControllerDefinition;
+    private assetService;
+    constructor(assetService: AssetService);
+    get(request: KuzzleRequest): Promise<ApiAssetGetResult>;
+    update(request: KuzzleRequest): Promise<ApiAssetUpdateResult>;
+    create(request: KuzzleRequest): Promise<ApiAssetCreateResult>;
+    delete(request: KuzzleRequest): Promise<ApiAssetDeleteResult>;
+    search(request: KuzzleRequest): Promise<ApiAssetSearchResult>;
+    getMeasures(request: KuzzleRequest): Promise<ApiAssetGetMeasuresResult>;
+}

package/dist/lib/modules/asset/collections/assetsMappings.d.ts

@@ -0,0 +1,38 @@
+export declare const assetsMappings: {
+    dynamic: string;
+    properties: {
+        model: {
+            type: string;
+            fields: {
+                text: {
+                    type: string;
+                };
+            };
+        };
+        reference: {
+            type: string;
+            fields: {
+                text: {
+                    type: string;
+                };
+            };
+        };
+        metadata: {
+            properties: {};
+        };
+        measures: {
+            properties: {};
+        };
+        linkedDevices: {
+            properties: {
+                _id: {
+                    type: string;
+                };
+                measures: {
+                    dynamic: string;
+                    properties: {};
+                };
+            };
+        };
+    };
+};

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

@@ -0,0 +1,8 @@
+export * from "./collections/assetsMappings";
+export * from "./types/AssetContent";
+export * from "./types/AssetEvents";
+export * from "./types/AssetApi";
+export * from "./model/AssetSerializer";
+export * from "./AssetModule";
+export * from "./roles/RoleAssetsAdmin";
+export * from "./roles/RoleAssetsReader";

package/dist/lib/modules/asset/model/AssetSerializer.d.ts

@@ -0,0 +1,10 @@
+import { KDocument } from "kuzzle";
+import { AssetContent, AssetMeasureContext } from "../types/AssetContent";
+export declare class AssetSerializer {
+    static id(model: string, reference: string): string;
+    static serialize(asset: KDocument<AssetContent>): KDocument<AssetContent>;
+    /**
+     * Get asset description to contextualize measure data point
+     */
+    static measureContext(asset: KDocument<AssetContent>, measureName: string): AssetMeasureContext;
+}

package/dist/lib/modules/asset/roles/RoleAssetsAdmin.d.ts

@@ -0,0 +1,22 @@
+import { KuzzleRole } from "../../shared/types/KuzzleRole";
+/**
+ * This role allows to manage assets and their models.
+ *
+ * It's a tenant role.
+ *
+ * @example
+ *
+    "device-manager/assets": {
+      actions: {
+        "*": true,
+      },
+    },
+    "device-manager/models": {
+      actions: {
+        deleteAsset: true,
+        listAssets: true,
+        writeAsset: true,
+      },
+    },
+ */
+export declare const RoleAssetsAdmin: KuzzleRole;

package/dist/lib/modules/asset/roles/RoleAssetsReader.d.ts

@@ -0,0 +1,21 @@
+import { KuzzleRole } from "lib/modules/shared/types/KuzzleRole";
+/**
+ * This role only gives a read-only access to assets and their models.
+ *
+ * It's a tenant role.
+ *
+ * @example
+    "device-manager/assets": {
+      actions: {
+        get: true,
+        getMeasures: true,
+        search: true,
+      },
+    },
+    "device-manager/models": {
+      actions: {
+        listAssets: true,
+      },
+    },
+ */
+export declare const RoleAssetsReader: KuzzleRole;

package/dist/lib/modules/asset/roles/assetsAdmin.d.ts

@@ -0,0 +1,16 @@
+export declare const assetsAdmin: {
+    controllers: {
+        "device-manager/assets": {
+            actions: {
+                "*": boolean;
+            };
+        };
+        "device-manager/models": {
+            actions: {
+                deleteAsset: boolean;
+                listAssets: boolean;
+                writeAsset: boolean;
+            };
+        };
+    };
+};

package/dist/lib/modules/asset/roles/assetsReader.d.ts

@@ -0,0 +1,16 @@
+export declare const assetsReader: {
+    controllers: {
+        "device-manager/assets": {
+            actions: {
+                get: boolean;
+                getMeasures: boolean;
+                search: boolean;
+            };
+        };
+        "device-manager/models": {
+            actions: {
+                listAssets: boolean;
+            };
+        };
+    };
+};

package/dist/lib/modules/asset/types/AssetApi.d.ts

@@ -0,0 +1,58 @@
+import { JSONObject, KDocument, KHit, SearchResult } from "kuzzle";
+import { MeasureContent } from "../../../modules/measure";
+import { Metadata } from "../../shared";
+import { AssetContent } from "./AssetContent";
+interface AssetsControllerRequest {
+    controller: "device-manager/assets";
+    engineId: string;
+}
+export interface ApiAssetGetRequest extends AssetsControllerRequest {
+    action: "get";
+    _id: string;
+}
+export type ApiAssetGetResult = KDocument<AssetContent>;
+export interface ApiAssetUpdateRequest extends AssetsControllerRequest {
+    action: "update";
+    _id: string;
+    refresh?: string;
+    body: {
+        metadata: Metadata;
+    };
+}
+export type ApiAssetUpdateResult = KDocument<AssetContent>;
+export interface ApiAssetCreateRequest extends AssetsControllerRequest {
+    action: "create";
+    refresh?: string;
+    body: {
+        model: string;
+        reference: string;
+        metadata?: Metadata;
+    };
+}
+export type ApiAssetCreateResult = KDocument<AssetContent>;
+export interface ApiAssetDeleteRequest extends AssetsControllerRequest {
+    action: "delete";
+    _id: string;
+    refresh?: string;
+    strict?: boolean;
+}
+export type ApiAssetDeleteResult = void;
+export interface ApiAssetSearchRequest extends AssetsControllerRequest {
+    action: "search";
+    from?: number;
+    size?: number;
+    scrollTTL?: string;
+    body: JSONObject;
+}
+export type ApiAssetSearchResult = SearchResult<KHit<AssetContent>>;
+export interface ApiAssetGetMeasuresRequest extends AssetsControllerRequest {
+    action: "getMeasures";
+    _id: string;
+    size?: number;
+    startAt?: string;
+    endAt?: string;
+}
+export type ApiAssetGetMeasuresResult = {
+    measures: Array<KDocument<MeasureContent<JSONObject>>>;
+};
+export {};

package/dist/lib/modules/asset/types/AssetContent.d.ts

@@ -0,0 +1,41 @@
+import { JSONObject } from "kuzzle";
+import { DigitalTwinContent, Metadata } from "../../shared";
+/**
+ * Asset document content
+ */
+export interface AssetContent<TMeasures extends JSONObject = any, TMetadata extends Metadata = any> extends DigitalTwinContent<TMeasures, TMetadata> {
+    /**
+     * Link with attached device
+     */
+    linkedDevices: Array<{
+        /**
+         * Device ID
+         */
+        _id: string;
+        /**
+         * Names lookup table for measures
+         *
+         * Record<deviceName, assetName>
+         *
+         * @example
+         *
+         * {
+         *   "temperature": "externalTemperature",
+         * }
+         */
+        measures: Record<string, string>;
+    }>;
+}
+/**
+ * Asset description used to contextualize each measure data point
+ */
+export type AssetMeasureContext<TMetadata extends Metadata = Metadata> = {
+    /**
+     * ID of the asset
+     */
+    _id: string;
+    /**
+     * Name of the measure for the Asset
+     */
+    measureName: string;
+} & Pick<AssetContent<JSONObject, TMetadata>, "model" | "reference" | "metadata">;

package/dist/lib/modules/asset/types/AssetEvents.d.ts

@@ -0,0 +1,17 @@
+import { KDocument } from "kuzzle";
+import { Metadata } from "../../../modules/shared";
+import { AssetContent } from "./AssetContent";
+export type EventAssetUpdateBefore = {
+    name: "device-manager:asset:update:before";
+    args: [{
+        asset: KDocument<AssetContent>;
+        metadata: Metadata;
+    }];
+};
+export type EventAssetUpdateAfter = {
+    name: "device-manager:asset:update:after";
+    args: [{
+        asset: KDocument<AssetContent>;
+        metadata: Metadata;
+    }];
+};