@3sixty/telemetry-models 0.0.0-stage → 0.20.0-next.0

package/dist/types/connectors/silentTelemetryConnector.d.ts

@@ -0,0 +1,56 @@
+import type { ITelemetryConnector } from "../models/ITelemetryConnector.js";
+import type { ITelemetryMetric } from "../models/ITelemetryMetric.js";
+import type { ITelemetryMetricValueEntry } from "../models/ITelemetryMetricValueEntry.js";
+import type { MetricCounterOperation } from "../models/metricCounterOperation.js";
+/**
+ * Class for performing telemetry operations to nowhere.
+ */
+export declare class SilentTelemetryConnector implements ITelemetryConnector {
+    /**
+     * The namespace for the class.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create one or more metrics.
+     * @param metric The metric details, or the details of several metrics.
+     * @returns A promise that resolves when the metric has been created.
+     */
+    createMetric(metric: ITelemetryMetric | ITelemetryMetric[]): Promise<void>;
+    /**
+     * Update metric.
+     * @param metric The metric details.
+     * @returns A promise that resolves when the metric has been updated.
+     */
+    updateMetric(metric: Omit<ITelemetryMetric, "type">): Promise<void>;
+    /**
+     * Update metric value.
+     * @param id The id of the metric.
+     * @param value The value for the update operation.
+     * @param customData The custom data for the update operation.
+     * @returns The created metric value id.
+     */
+    addMetricValue(id: string, value: MetricCounterOperation | number, customData?: {
+        [key: string]: unknown;
+    }): Promise<string>;
+    /**
+     * Add multiple metric values.
+     * @param values The metric values to add.
+     * @returns The created metric value ids.
+     */
+    addMetricValues(values: ITelemetryMetricValueEntry[]): Promise<string[]>;
+    /**
+     * Remove metric.
+     * @param id The id of the metric.
+     * @returns A promise that resolves when the metric and all its values have been removed.
+     */
+    removeMetric(id: string): Promise<void>;
+}

package/dist/types/factories/metricsProducerFactory.d.ts

@@ -0,0 +1,10 @@
+import { Factory } from "@3sixty/core";
+import type { IMetricsProducer } from "../models/IMetricsProducer.js";
+/**
+ * Factory for `IMetricsProducer` implementations.
+ *
+ * The engine registers producers with `MetricsProducerFactory` during
+ * initialisation. Third-party apps can also register their own producers
+ * before `engine.start()` is called.
+ */
+export declare const MetricsProducerFactory: Factory<IMetricsProducer>;

package/dist/types/factories/telemetryConnectorFactory.d.ts

@@ -0,0 +1,6 @@
+import { Factory } from "@3sixty/core";
+import type { ITelemetryConnector } from "../models/ITelemetryConnector.js";
+/**
+ * Factory for creating telemetry connectors.
+ */
+export declare const TelemetryConnectorFactory: Factory<ITelemetryConnector>;

package/dist/types/helpers/metricHelper.d.ts

@@ -0,0 +1,67 @@
+import type { ITelemetryComponent } from "../models/ITelemetryComponent.js";
+import type { ITelemetryMetric } from "../models/ITelemetryMetric.js";
+import type { ITelemetryMetricValueEntry } from "../models/ITelemetryMetricValueEntry.js";
+/**
+ * Helper class for performing common metric operations, swallowing any errors from the telemetry component.
+ */
+export declare class MetricHelper {
+    /**
+     * Create multiple metrics if they don't already exist, swallowing any already exists errors.
+     * A convenience wrapper over createMetric for callers that always have a list.
+     * @param telemetryComponent The telemetry component to use for creating the metrics.
+     * @param metrics The telemetry metrics to create.
+     * @returns A promise that resolves when all metrics have been created or confirmed to exist.
+     */
+    static createMetrics(telemetryComponent: ITelemetryComponent | undefined, metrics: ITelemetryMetric[]): Promise<void>;
+    /**
+     * Create one or more metrics if they don't already exist, swallowing any already exists errors.
+     * @param telemetryComponent The telemetry component to use for creating the metrics.
+     * @param metric The telemetry metric to create, or the metrics to create.
+     * @returns A promise that resolves when the metrics have been created or confirmed to exist.
+     */
+    static createMetric(telemetryComponent: ITelemetryComponent | undefined, metric: ITelemetryMetric | ITelemetryMetric[]): Promise<void>;
+    /**
+     * Increment a metric counter, swallowing any telemetry errors.
+     * @param telemetryComponent The telemetry component to use for incrementing the metric.
+     * @param id The metric ID.
+     * @param customData Optional custom data for the increment.
+     * @param onError Optional callback invoked with the swallowed error, for callers that want visibility.
+     * @returns A promise that resolves when the increment has been recorded or the error swallowed.
+     */
+    static metricIncrement(telemetryComponent: ITelemetryComponent | undefined, id: string, customData?: {
+        [key: string]: unknown;
+    }, onError?: (err: unknown) => Promise<void> | void): Promise<void>;
+    /**
+     * Decrement a metric counter, swallowing any telemetry errors.
+     * @param telemetryComponent The telemetry component to use for decrementing the metric.
+     * @param id The metric ID.
+     * @param customData Optional custom data for the decrement.
+     * @param onError Optional callback invoked with the swallowed error, for callers that want visibility.
+     * @returns A promise that resolves when the decrement has been recorded or the error swallowed.
+     */
+    static metricDecrement(telemetryComponent: ITelemetryComponent | undefined, id: string, customData?: {
+        [key: string]: unknown;
+    }, onError?: (err: unknown) => Promise<void> | void): Promise<void>;
+    /**
+     * Set a metric value, swallowing any telemetry errors.
+     * @param telemetryComponent The telemetry component to use for setting the metric value.
+     * @param id The metric ID.
+     * @param value The metric value to set.
+     * @param customData Optional custom data for setting the value.
+     * @param onError Optional callback invoked with the swallowed error, for callers that want visibility.
+     * @returns A promise that resolves when the value has been recorded or the error swallowed.
+     */
+    static metricValue(telemetryComponent: ITelemetryComponent | undefined, id: string, value: number, customData?: {
+        [key: string]: unknown;
+    }, onError?: (err: unknown) => Promise<void> | void): Promise<void>;
+    /**
+     * Set several metric values at once, swallowing any telemetry errors.
+     * Components which support it record the whole set in one operation, which for a persisted
+     * connector is a single write rather than one per value.
+     * @param telemetryComponent The telemetry component to use for setting the metric values.
+     * @param values The metric values to set.
+     * @param onError Optional callback invoked with the swallowed error, for callers that want visibility.
+     * @returns A promise that resolves when the values have been recorded or the error swallowed.
+     */
+    static metricValues(telemetryComponent: ITelemetryComponent | undefined, values: ITelemetryMetricValueEntry[], onError?: (err: unknown) => Promise<void> | void): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+export * from "./connectors/multiTelemetryConnector.js";
+export * from "./connectors/silentTelemetryConnector.js";
+export * from "./factories/metricsProducerFactory.js";
+export * from "./factories/telemetryConnectorFactory.js";
+export * from "./helpers/metricHelper.js";
+export * from "./models/api/ITelemetryAddMetricValueRequest.js";
+export * from "./models/api/ITelemetryCreateMetricRequest.js";
+export * from "./models/api/ITelemetryGetMetricRequest.js";
+export * from "./models/api/ITelemetryGetMetricResponse.js";
+export * from "./models/api/ITelemetryGetMetricValueRequest.js";
+export * from "./models/api/ITelemetryGetMetricValueResponse.js";
+export * from "./models/api/ITelemetryListRequest.js";
+export * from "./models/api/ITelemetryListResponse.js";
+export * from "./models/api/ITelemetryRemoveMetricRequest.js";
+export * from "./models/api/ITelemetryUpdateMetricRequest.js";
+export * from "./models/api/ITelemetryValuesListRequest.js";
+export * from "./models/api/ITelemetryValuesListResponse.js";
+export * from "./models/IMetricsCollectorComponent.js";
+export * from "./models/IMetricsProducer.js";
+export * from "./models/IMultiTelemetryConnectorConstructorOptions.js";
+export * from "./models/ITelemetryComponent.js";
+export * from "./models/ITelemetryConnector.js";
+export * from "./models/ITelemetryMetric.js";
+export * from "./models/ITelemetryMetricValue.js";
+export * from "./models/ITelemetryMetricValueEntry.js";
+export * from "./models/metricCounterOperation.js";
+export * from "./models/metricType.js";

package/dist/types/models/IMetricsCollectorComponent.d.ts

@@ -0,0 +1,6 @@
+import type { IComponent } from "@3sixty/core";
+/**
+ * Contract for a metrics collector component.
+ */
+export interface IMetricsCollectorComponent extends IComponent {
+}

package/dist/types/models/IMetricsProducer.d.ts

@@ -0,0 +1,27 @@
+import type { IComponent } from "@3sixty/core";
+import type { ITelemetryMetricValueEntry } from "./ITelemetryMetricValueEntry.js";
+/**
+ * Contract for a metrics producer.
+ *
+ * A producer declares its metrics with `register()` once and pushes current
+ * values with `collect()` on every poll cycle. Producers are discovered via
+ * `MetricsProducerFactory` and orchestrated by a `MetricsCollectorService`.
+ *
+ * Producers are factory-only entries - they are not lifecycle components of
+ * the engine. The orchestrating service owns the polling timer.
+ */
+export interface IMetricsProducer extends IComponent {
+    /**
+     * Register every metric this producer emits with the telemetry component.
+     * Called once when the orchestrating service starts.
+     * @returns A promise that resolves when all metrics have been registered.
+     */
+    register(): Promise<void>;
+    /**
+     * Read the current values for every metric this producer emits.
+     * Called on every poll cycle. The values are returned rather than recorded, so the
+     * orchestrating service can record a whole cycle in one operation.
+     * @returns The current values for this producer's metrics.
+     */
+    collect(): Promise<ITelemetryMetricValueEntry[]>;
+}

package/dist/types/models/IMultiTelemetryConnectorConstructorOptions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The options for the multi telemetry connector constructor.
+ */
+export interface IMultiTelemetryConnectorConstructorOptions {
+    /**
+     * The telemetry connector types to multiplex.
+     */
+    telemetryConnectorTypes: string[];
+}

package/dist/types/models/ITelemetryComponent.d.ts

@@ -0,0 +1,109 @@
+import type { IComponent } from "@3sixty/core";
+import type { ITelemetryMetric } from "./ITelemetryMetric.js";
+import type { ITelemetryMetricValue } from "./ITelemetryMetricValue.js";
+import type { ITelemetryMetricValueEntry } from "./ITelemetryMetricValueEntry.js";
+import type { MetricCounterOperation } from "./metricCounterOperation.js";
+import type { MetricType } from "./metricType.js";
+/**
+ * Interface describing a telemetry component contract.
+ */
+export interface ITelemetryComponent extends IComponent {
+    /**
+     * Create one or more metrics.
+     * A single metric fails if it already exists; an array declares the set that should exist,
+     * creating the ones that are missing and leaving the rest untouched, so implementations
+     * which persist the definitions can resolve the whole set in one operation.
+     * @param metric The metric details, or the details of several metrics.
+     * @returns A promise that resolves when the metrics have been created.
+     */
+    createMetric(metric: ITelemetryMetric | ITelemetryMetric[]): Promise<void>;
+    /**
+     * Get the metric details and it's most recent value.
+     * @param id The metric id.
+     * @returns The metric details and it's most recent value.
+     */
+    getMetric(id: string): Promise<{
+        metric: ITelemetryMetric;
+        value?: ITelemetryMetricValue;
+    }>;
+    /**
+     * Get a specific metric value by its id.
+     * @param id The id of the metric.
+     * @param valueId The id of the metric value.
+     * @returns The metric value.
+     */
+    getMetricValue(id: string, valueId: string): Promise<ITelemetryMetricValue>;
+    /**
+     * Update metric.
+     * @param metric The metric details.
+     * @returns A promise that resolves when the metric has been updated.
+     */
+    updateMetric(metric: Omit<ITelemetryMetric, "type">): Promise<void>;
+    /**
+     * Add a metric value.
+     * @param id The id of the metric.
+     * @param value The value for the add operation.
+     * @param customData The custom data for the add operation.
+     * @returns The created metric value id.
+     */
+    addMetricValue(id: string, value: MetricCounterOperation | number, customData?: {
+        [key: string]: unknown;
+    }): Promise<string>;
+    /**
+     * Add multiple metric values, so implementations which persist them can do so in one
+     * operation instead of one per value.
+     * @param values The metric values to add.
+     * @returns The created metric value ids, in the order the values were supplied.
+     */
+    addMetricValues(values: ITelemetryMetricValueEntry[]): Promise<string[]>;
+    /**
+     * Remove metric.
+     * @param id The id of the metric.
+     * @returns A promise that resolves when the metric and all its values have been removed.
+     */
+    removeMetric(id: string): Promise<void>;
+    /**
+     * Query the metrics.
+     * @param type The type of the metric.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    query(type?: MetricType, cursor?: string, limit?: number): Promise<{
+        /**
+         * The metrics.
+         */
+        entities: ITelemetryMetric[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more values.
+         */
+        cursor?: string;
+    }>;
+    /**
+     * Query the metric values.
+     * @param id The id of the metric.
+     * @param timeStart The inclusive time as the start of the metric entries.
+     * @param timeEnd The inclusive time as the end of the metric entries.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    queryValues(id: string, timeStart?: number, timeEnd?: number, cursor?: string, limit?: number): Promise<{
+        /**
+         * The metric details.
+         */
+        metric: ITelemetryMetric;
+        /**
+         * The values for the metric.
+         */
+        entities: ITelemetryMetricValue[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more values.
+         */
+        cursor?: string;
+    }>;
+}

package/dist/types/models/ITelemetryConnector.d.ts

@@ -0,0 +1,109 @@
+import type { IComponent } from "@3sixty/core";
+import type { ITelemetryMetric } from "./ITelemetryMetric.js";
+import type { ITelemetryMetricValue } from "./ITelemetryMetricValue.js";
+import type { ITelemetryMetricValueEntry } from "./ITelemetryMetricValueEntry.js";
+import type { MetricCounterOperation } from "./metricCounterOperation.js";
+import type { MetricType } from "./metricType.js";
+/**
+ * Interface describing a telemetry connector.
+ */
+export interface ITelemetryConnector extends IComponent {
+    /**
+     * Create one or more metrics.
+     * A single metric fails if it already exists; an array declares the set that should exist,
+     * creating the ones that are missing and leaving the rest untouched, so implementations
+     * which persist the definitions can resolve the whole set in one operation.
+     * @param metric The metric details, or the details of several metrics.
+     * @returns A promise that resolves when the metrics have been created.
+     */
+    createMetric(metric: ITelemetryMetric | ITelemetryMetric[]): Promise<void>;
+    /**
+     * Get the metric details and it's most recent value.
+     * @param id The metric id.
+     * @returns The metric details and it's most recent value.
+     */
+    getMetric?(id: string): Promise<{
+        metric: ITelemetryMetric;
+        value?: ITelemetryMetricValue;
+    }>;
+    /**
+     * Get a specific metric value by its id.
+     * @param id The id of the metric.
+     * @param valueId The id of the metric value.
+     * @returns The metric value.
+     */
+    getMetricValue?(id: string, valueId: string): Promise<ITelemetryMetricValue>;
+    /**
+     * Update metric.
+     * @param metric The metric details.
+     * @returns A promise that resolves when the metric has been updated.
+     */
+    updateMetric(metric: Omit<ITelemetryMetric, "type">): Promise<void>;
+    /**
+     * Update metric value.
+     * @param id The id of the metric.
+     * @param value The value for the update operation.
+     * @param customData The custom data for the update operation.
+     * @returns The created metric value id.
+     */
+    addMetricValue(id: string, value: MetricCounterOperation | number, customData?: {
+        [key: string]: unknown;
+    }): Promise<string>;
+    /**
+     * Add multiple metric values, so implementations which persist them can do so in one
+     * operation instead of one per value.
+     * @param values The metric values to add.
+     * @returns The created metric value ids, in the order the values were supplied.
+     */
+    addMetricValues(values: ITelemetryMetricValueEntry[]): Promise<string[]>;
+    /**
+     * Remove metric.
+     * @param id The id of the metric.
+     * @returns A promise that resolves when the metric and all its values have been removed.
+     */
+    removeMetric(id: string): Promise<void>;
+    /**
+     * Query the metrics.
+     * @param type The type of the metric.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    query?(type?: MetricType, cursor?: string, limit?: number): Promise<{
+        /**
+         * The metrics.
+         */
+        entities: ITelemetryMetric[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more values.
+         */
+        cursor?: string;
+    }>;
+    /**
+     * Query the metric values.
+     * @param id The id of the metric.
+     * @param timeStart The inclusive time as the start of the metric entries.
+     * @param timeEnd The inclusive time as the end of the metric entries.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    queryValues?(id: string, timeStart?: number, timeEnd?: number, cursor?: string, limit?: number): Promise<{
+        /**
+         * The metric details.
+         */
+        metric: ITelemetryMetric;
+        /**
+         * The values for the metric.
+         */
+        entities: ITelemetryMetricValue[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more values.
+         */
+        cursor?: string;
+    }>;
+}

package/dist/types/models/ITelemetryMetric.d.ts

@@ -0,0 +1,31 @@
+import type { MetricType } from "./metricType.js";
+/**
+ * Interface describing a telemetry metric.
+ */
+export interface ITelemetryMetric {
+    /**
+     * The id of the metric.
+     */
+    id: string;
+    /**
+     * The label of the metric.
+     */
+    label: string;
+    /**
+     * The type of the metric.
+     */
+    type: MetricType;
+    /**
+     * Description.
+     */
+    description?: string;
+    /**
+     * The unit the metric describes.
+     */
+    unit?: string;
+    /**
+     * The maximum number of values to retain; oldest are trimmed on each addMetricValue call.
+     * Unlimited when absent.
+     */
+    maxHistory?: number;
+}

package/dist/types/models/ITelemetryMetricValue.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Interface describing a telemetry metric value.
+ */
+export interface ITelemetryMetricValue {
+    /**
+     * The id of the metric value.
+     */
+    id: string;
+    /**
+     * The timestamp of the metric.
+     */
+    ts: number;
+    /**
+     * The value of the metric.
+     */
+    value: number;
+    /**
+     * The custom data for the metric value.
+     */
+    customData?: {
+        [key: string]: unknown;
+    };
+}

package/dist/types/models/ITelemetryMetricValueEntry.d.ts

@@ -0,0 +1,20 @@
+import type { MetricCounterOperation } from "./metricCounterOperation.js";
+/**
+ * A single metric value in a batch add operation.
+ */
+export interface ITelemetryMetricValueEntry {
+    /**
+     * The id of the metric.
+     */
+    id: string;
+    /**
+     * The value for the add operation.
+     */
+    value: MetricCounterOperation | number;
+    /**
+     * The custom data for the metric value.
+     */
+    customData?: {
+        [key: string]: unknown;
+    };
+}

package/dist/types/models/api/ITelemetryAddMetricValueRequest.d.ts

@@ -0,0 +1,30 @@
+import type { MetricCounterOperation } from "../metricCounterOperation.js";
+/**
+ * Add a telemetry metric value.
+ */
+export interface ITelemetryAddMetricValueRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+    };
+    /**
+     * The data to be used in the update.
+     */
+    body: {
+        /**
+         * The value for the update operation.
+         */
+        value: MetricCounterOperation | number;
+        /**
+         * The custom data for the update operation.
+         */
+        customData?: {
+            [key: string]: unknown;
+        };
+    };
+}

package/dist/types/models/api/ITelemetryCreateMetricRequest.d.ts

@@ -0,0 +1,11 @@
+import type { ITelemetryMetric } from "../ITelemetryMetric.js";
+/**
+ * Create one or more telemetry metrics.
+ */
+export interface ITelemetryCreateMetricRequest {
+    /**
+     * The data to be used in the create. A single metric fails if it already exists; an array
+     * declares the set that should exist, creating the ones that are missing.
+     */
+    body: ITelemetryMetric | ITelemetryMetric[];
+}

package/dist/types/models/api/ITelemetryGetMetricRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Get a telemetry metric.
+ */
+export interface ITelemetryGetMetricRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/ITelemetryGetMetricResponse.d.ts

@@ -0,0 +1,20 @@
+import type { ITelemetryMetric } from "../ITelemetryMetric.js";
+import type { ITelemetryMetricValue } from "../ITelemetryMetricValue.js";
+/**
+ * Get a telemetry metric response.
+ */
+export interface ITelemetryGetMetricResponse {
+    /**
+     * The body parameters.
+     */
+    body: {
+        /**
+         * The metric.
+         */
+        metric: ITelemetryMetric;
+        /**
+         * The latest metric value.
+         */
+        value?: ITelemetryMetricValue;
+    };
+}

package/dist/types/models/api/ITelemetryGetMetricValueRequest.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Get a telemetry metric value.
+ */
+export interface ITelemetryGetMetricValueRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+        /**
+         * The id of the metric value.
+         */
+        valueId: string;
+    };
+}

package/dist/types/models/api/ITelemetryGetMetricValueResponse.d.ts

@@ -0,0 +1,10 @@
+import type { ITelemetryMetricValue } from "../ITelemetryMetricValue.js";
+/**
+ * Get a telemetry metric value response.
+ */
+export interface ITelemetryGetMetricValueResponse {
+    /**
+     * The body parameters.
+     */
+    body: ITelemetryMetricValue;
+}

package/dist/types/models/api/ITelemetryListRequest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Get the a list of the telemetry metrics.
+ */
+export interface ITelemetryListRequest {
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The type of the metric.
+         */
+        type?: string;
+        /**
+         * The optional cursor to get next chunk.
+         */
+        cursor?: string;
+        /**
+         * Limit the number of entities to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/ITelemetryListResponse.d.ts

@@ -0,0 +1,19 @@
+import type { ITelemetryMetric } from "../ITelemetryMetric.js";
+/**
+ * Response for telemetry list request.
+ */
+export interface ITelemetryListResponse {
+    /**
+     * The response payload.
+     */
+    body: {
+        /**
+         * The metrics.
+         */
+        entities: ITelemetryMetric[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    };
+}