@twin.org/federated-catalogue-models 0.0.3-next.21 → 0.0.3-next.23

package/dist/es/factories/federatedCatalogueFilterFactory.js

@@ -3,7 +3,6 @@
 import { Factory } from "@twin.org/core";
 /**
  * Factory for managing filter plugin registration and retrieval.
- * Follows the TWIN Platform factory pattern used by ComponentFactory and EntityStorageConnectorFactory.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const FederatedCatalogueFilterFactory = Factory.createFactory("federated-catalogue-filter");

package/dist/es/factories/federatedCatalogueFilterFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"federatedCatalogueFilterFactory.js","sourceRoot":"","sources":["../../../src/factories/federatedCatalogueFilterFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;;GAGG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,+BAA+B,GAAG,OAAO,CAAC,aAAa,CACnE,4BAA4B,CAC5B,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { IFederatedCatalogueFilter } from \"../models/IFederatedCatalogueFilter.js\";\n\n/**\n * Factory for managing filter plugin registration and retrieval.\n * Follows the TWIN Platform factory pattern used by ComponentFactory and EntityStorageConnectorFactory.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueFilterFactory = Factory.createFactory<IFederatedCatalogueFilter>(\n\t\"federated-catalogue-filter\"\n);\n"]}
+{"version":3,"file":"federatedCatalogueFilterFactory.js","sourceRoot":"","sources":["../../../src/factories/federatedCatalogueFilterFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,+BAA+B,GAAG,OAAO,CAAC,aAAa,CACnE,4BAA4B,CAC5B,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { IFederatedCatalogueFilter } from \"../models/IFederatedCatalogueFilter.js\";\n\n/**\n * Factory for managing filter plugin registration and retrieval.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueFilterFactory = Factory.createFactory<IFederatedCatalogueFilter>(\n\t\"federated-catalogue-filter\"\n);\n"]}

package/dist/es/index.js

@@ -9,6 +9,8 @@ export * from "./models/api/IDatasetRemoveRequest.js";
 export * from "./models/api/IDatasetRemoveResponse.js";
 export * from "./models/api/IDatasetSetRequest.js";
 export * from "./models/api/IDatasetSetResponse.js";
+export * from "./models/federatedCatalogueMetricIds.js";
+export * from "./models/federatedCatalogueMetrics.js";
 export * from "./models/IFederatedCatalogueComponent.js";
 export * from "./models/IFederatedCatalogueFilter.js";
 //# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/federatedCatalogueFilterFactory.js\";\nexport * from \"./models/api/ICatalogRequestRequest.js\";\nexport * from \"./models/api/ICatalogRequestResponse.js\";\nexport * from \"./models/api/IDatasetGetRequest.js\";\nexport * from \"./models/api/IDatasetGetResponse.js\";\nexport * from \"./models/api/IDatasetRemoveRequest.js\";\nexport * from \"./models/api/IDatasetRemoveResponse.js\";\nexport * from \"./models/api/IDatasetSetRequest.js\";\nexport * from \"./models/api/IDatasetSetResponse.js\";\nexport * from \"./models/IFederatedCatalogueComponent.js\";\nexport * from \"./models/IFederatedCatalogueFilter.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./factories/federatedCatalogueFilterFactory.js\";\nexport * from \"./models/api/ICatalogRequestRequest.js\";\nexport * from \"./models/api/ICatalogRequestResponse.js\";\nexport * from \"./models/api/IDatasetGetRequest.js\";\nexport * from \"./models/api/IDatasetGetResponse.js\";\nexport * from \"./models/api/IDatasetRemoveRequest.js\";\nexport * from \"./models/api/IDatasetRemoveResponse.js\";\nexport * from \"./models/api/IDatasetSetRequest.js\";\nexport * from \"./models/api/IDatasetSetResponse.js\";\nexport * from \"./models/federatedCatalogueMetricIds.js\";\nexport * from \"./models/federatedCatalogueMetrics.js\";\nexport * from \"./models/IFederatedCatalogueComponent.js\";\nexport * from \"./models/IFederatedCatalogueFilter.js\";\n"]}

package/dist/es/models/IFederatedCatalogueComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFederatedCatalogueComponent.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type {\n\tIDataspaceProtocolCatalog,\n\tIDataspaceProtocolCatalogError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a federated catalogue component.\n * Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and query.\n */\nexport interface IFederatedCatalogueComponent extends IComponent {\n\t/**\n\t * Retrieve a dataset by its unique identifier.\n\t * @param datasetId The unique identifier of the dataset.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns The dataset if found, or a CatalogError if not found or an error occurs.\n\t */\n\tget(\n\t\tdatasetId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDcatDataset | IDataspaceProtocolCatalogError>;\n\n\t/**\n\t * Insert or update a dataset in the catalogue.\n\t * This method is internal and should not be exposed via REST endpoints.\n\t * @param dataset The dataset to store.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns The unique identifier of the stored dataset, or a CatalogError if an error occurs.\n\t */\n\tset(\n\t\tdataset: IDcatDataset,\n\t\ttrustPayload: unknown\n\t): Promise<string | IDataspaceProtocolCatalogError>;\n\n\t/**\n\t * Execute a query against the catalogue using registered filter plugins.\n\t * Returns a DS Protocol compliant Catalog object with participantId.\n\t *\n\t * The root catalog's participantId is the requesting participant (from context).\n\t * Own datasets (matching requestingParticipantId) go directly in root dataset[].\n\t * Other participants' datasets are grouped in nested catalog[] entries.\n\t *\n\t * For anonymous requests (no context), uses the first publisher found as fallback.\n\t * Returns CatalogError 404 when no datasets exist.\n\t *\n\t * @param filter The filter criteria containing @type.\n\t * @param cursor Optional cursor for pagination.\n\t * @param limit Optional limit for pagination.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,\n\t * or IDataspaceProtocolCatalogError if no datasets found.\n\t */\n\tquery(\n\t\tfilter: unknown[] | undefined,\n\t\tcursor: string | undefined,\n\t\tlimit: number | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tresult: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Remove a dataset from the catalogue by its unique identifier.\n\t * @param datasetId The unique identifier of the dataset to remove.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns Nothing.\n\t */\n\tremove(\n\t\tdatasetId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolCatalogError | undefined>;\n}\n"]}
+{"version":3,"file":"IFederatedCatalogueComponent.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type {\n\tIDataspaceProtocolCatalog,\n\tIDataspaceProtocolCatalogError\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * Interface describing a federated catalogue component.\n * Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and query.\n */\nexport interface IFederatedCatalogueComponent extends IComponent {\n\t/**\n\t * Retrieve a dataset by its unique identifier.\n\t * @param datasetId The unique identifier of the dataset.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns A promise that resolves with the dataset if found, or a CatalogError if not found or an error occurs.\n\t */\n\tget(\n\t\tdatasetId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDcatDataset | IDataspaceProtocolCatalogError>;\n\n\t/**\n\t * Insert or update a dataset in the catalogue.\n\t * This method is internal and should not be exposed via REST endpoints.\n\t * @param dataset The dataset to store.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns A promise that resolves with the unique identifier of the stored dataset, or a CatalogError if an error occurs.\n\t */\n\tset(\n\t\tdataset: IDcatDataset,\n\t\ttrustPayload: unknown\n\t): Promise<string | IDataspaceProtocolCatalogError>;\n\n\t/**\n\t * Execute a query against the catalogue using registered filter plugins.\n\t * Returns a Dataspace Protocol compliant Catalog object with participantId.\n\t *\n\t * The root catalog's participantId is the requesting participant (from context).\n\t * Own datasets (matching requestingParticipantId) go directly in root dataset[].\n\t * Other participants' datasets are grouped in nested catalog[] entries.\n\t *\n\t * For anonymous requests (no context), uses the first publisher found as fallback.\n\t * Returns a CatalogError with status 404 when no datasets exist.\n\t *\n\t * @param filter The filter criteria array, where the first element contains @type.\n\t * @param cursor Optional cursor for pagination.\n\t * @param limit Optional limit for pagination.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns A promise that resolves with the catalog result and optional next-page cursor.\n\t */\n\tquery(\n\t\tfilter: unknown[] | undefined,\n\t\tcursor: string | undefined,\n\t\tlimit: number | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tresult: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Remove a dataset from the catalogue by its unique identifier.\n\t * @param datasetId The unique identifier of the dataset to remove.\n\t * @param trustPayload Optional payload for trust evaluation, if applicable.\n\t * @returns A promise that resolves with undefined on success, or a CatalogError if removal fails.\n\t */\n\tremove(\n\t\tdatasetId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolCatalogError | undefined>;\n}\n"]}

package/dist/es/models/IFederatedCatalogueFilter.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFederatedCatalogueFilter.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueFilter.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\nimport type { ITrustVerificationInfo } from \"@twin.org/trust-models\";\n\n/**\n * Interface describing a filter plugin for the federated catalogue.\n * Filter plugins provide extensible query semantics and indexing strategies.\n * Filters are registered by name in the FilterFactory and do not need to self-identify.\n */\nexport interface IFederatedCatalogueFilter extends IComponent {\n\t/**\n\t * Execute a filter-specific query over the catalogue.\n\t * Each filter interprets the payload according to its own semantics.\n\t * @param trustInfo The trust verification information for the current request.\n\t * @param filter The filter criteria (structure depends on the filter implementation).\n\t * @param cursor The pagination cursor from the previous query, if any.\n\t * @param limit The maximum number of results to return.\n\t * @returns Object containing datasets matching the filter criteria and optional cursor for next page.\n\t */\n\tquery(\n\t\ttrustInfo: ITrustVerificationInfo,\n\t\tfilter: unknown,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{ datasets: IDcatDataset[]; cursor?: string }>;\n\n\t/**\n\t * Generate filter indexes for a dataset to optimize future queries.\n\t * Indexes are stored as properties on the dataset entity itself.\n\t * @param dataset The dataset to index.\n\t * @returns Record mapping filter-specific index keys to values.\n\t */\n\tcreateIndex(dataset: IDcatDataset): Promise<{ [key: string]: unknown }>;\n}\n"]}
+{"version":3,"file":"IFederatedCatalogueFilter.js","sourceRoot":"","sources":["../../../src/models/IFederatedCatalogueFilter.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\nimport type { ITrustVerificationInfo } from \"@twin.org/trust-models\";\n\n/**\n * Interface describing a filter plugin for the federated catalogue.\n * Filter plugins provide extensible query semantics and indexing strategies.\n * Filters are registered by name in the FilterFactory and do not need to self-identify.\n */\nexport interface IFederatedCatalogueFilter extends IComponent {\n\t/**\n\t * Execute a filter-specific query over the catalogue.\n\t * Each filter interprets the payload according to its own semantics.\n\t * @param trustInfo The trust verification information for the current request.\n\t * @param filter The filter criteria (structure depends on the filter implementation).\n\t * @param cursor The pagination cursor from the previous query, if any.\n\t * @param limit The maximum number of results to return.\n\t * @returns A promise that resolves with datasets matching the filter criteria and an optional cursor for the next page.\n\t */\n\tquery(\n\t\ttrustInfo: ITrustVerificationInfo,\n\t\tfilter: unknown,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{ datasets: IDcatDataset[]; cursor?: string }>;\n\n\t/**\n\t * Generate filter indexes for a dataset to optimize future queries.\n\t * Indexes are stored as properties on the dataset entity itself.\n\t * @param dataset The dataset to index.\n\t * @returns A promise that resolves with a record mapping filter-specific index keys to values.\n\t */\n\tcreateIndex(dataset: IDcatDataset): Promise<{ [key: string]: unknown }>;\n}\n"]}

package/dist/es/models/api/IDatasetSetRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDatasetSetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IDatasetSetRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\nimport type { HeaderTypes } from \"@twin.org/web\";\n\n/**\n * The request parameters for the set dataset method.\n */\nexport interface IDatasetSetRequest {\n\t/**\n\t * The request headers. Authorization header carries the trust token (Bearer scheme).\n\t */\n\theaders?: {\n\t\t[HeaderTypes.Authorization]?: string;\n\t};\n\n\t/**\n\t * The response payload containing the dataset or error.\n\t */\n\tbody: IDcatDataset;\n}\n"]}
+{"version":3,"file":"IDatasetSetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IDatasetSetRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDcatDataset } from \"@twin.org/standards-w3c-dcat\";\nimport type { HeaderTypes } from \"@twin.org/web\";\n\n/**\n * The request parameters for the set dataset method.\n */\nexport interface IDatasetSetRequest {\n\t/**\n\t * The request headers. Authorization header carries the trust token (Bearer scheme).\n\t */\n\theaders?: {\n\t\t[HeaderTypes.Authorization]?: string;\n\t};\n\n\t/**\n\t * The request body containing the dataset to store.\n\t */\n\tbody: IDcatDataset;\n}\n"]}

package/dist/es/models/federatedCatalogueMetricIds.js

@@ -0,0 +1,33 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * Metric IDs for the federated catalogue service.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const FederatedCatalogueMetricIds = {
+    /**
+     * Number of datasets retrieved.
+     */
+    DatasetsRetrieved: "fc_datasets_retrieved",
+    /**
+     * Number of datasets stored.
+     */
+    DatasetsStored: "fc_datasets_stored",
+    /**
+     * Number of datasets removed.
+     */
+    DatasetsRemoved: "fc_datasets_removed",
+    /**
+     * Number of queries executed.
+     */
+    QueriesExecuted: "fc_queries_executed",
+    /**
+     * Number of filter indexes created.
+     */
+    FilterIndexesCreated: "fc_filter_indexes_created",
+    /**
+     * Number of filter index failures.
+     */
+    FilterIndexFailures: "fc_filter_index_failures"
+};
+//# sourceMappingURL=federatedCatalogueMetricIds.js.map

package/dist/es/models/federatedCatalogueMetricIds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federatedCatalogueMetricIds.js","sourceRoot":"","sources":["../../../src/models/federatedCatalogueMetricIds.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,2BAA2B,GAAG;IAC1C;;OAEG;IACH,iBAAiB,EAAE,uBAAuB;IAE1C;;OAEG;IACH,cAAc,EAAE,oBAAoB;IAEpC;;OAEG;IACH,eAAe,EAAE,qBAAqB;IAEtC;;OAEG;IACH,eAAe,EAAE,qBAAqB;IAEtC;;OAEG;IACH,oBAAoB,EAAE,2BAA2B;IAEjD;;OAEG;IACH,mBAAmB,EAAE,0BAA0B;CACtC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Metric IDs for the federated catalogue service.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueMetricIds = {\n\t/**\n\t * Number of datasets retrieved.\n\t */\n\tDatasetsRetrieved: \"fc_datasets_retrieved\",\n\n\t/**\n\t * Number of datasets stored.\n\t */\n\tDatasetsStored: \"fc_datasets_stored\",\n\n\t/**\n\t * Number of datasets removed.\n\t */\n\tDatasetsRemoved: \"fc_datasets_removed\",\n\n\t/**\n\t * Number of queries executed.\n\t */\n\tQueriesExecuted: \"fc_queries_executed\",\n\n\t/**\n\t * Number of filter indexes created.\n\t */\n\tFilterIndexesCreated: \"fc_filter_indexes_created\",\n\n\t/**\n\t * Number of filter index failures.\n\t */\n\tFilterIndexFailures: \"fc_filter_index_failures\"\n} as const;\n\n/**\n * Metric IDs for the federated catalogue service.\n */\nexport type FederatedCatalogueMetricIds =\n\t(typeof FederatedCatalogueMetricIds)[keyof typeof FederatedCatalogueMetricIds];\n"]}

package/dist/es/models/federatedCatalogueMetrics.js

@@ -0,0 +1,41 @@
+// Copyright 2025 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { MetricType } from "@twin.org/telemetry-models";
+import { FederatedCatalogueMetricIds } from "./federatedCatalogueMetricIds.js";
+/**
+ * Metrics registered by the federated catalogue service.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const FederatedCatalogueMetrics = [
+    {
+        id: FederatedCatalogueMetricIds.DatasetsRetrieved,
+        label: "Datasets retrieved",
+        type: MetricType.Counter
+    },
+    {
+        id: FederatedCatalogueMetricIds.DatasetsStored,
+        label: "Datasets stored",
+        type: MetricType.Counter
+    },
+    {
+        id: FederatedCatalogueMetricIds.DatasetsRemoved,
+        label: "Datasets removed",
+        type: MetricType.Counter
+    },
+    {
+        id: FederatedCatalogueMetricIds.QueriesExecuted,
+        label: "Queries executed",
+        type: MetricType.Counter
+    },
+    {
+        id: FederatedCatalogueMetricIds.FilterIndexesCreated,
+        label: "Filter indexes created",
+        type: MetricType.Counter
+    },
+    {
+        id: FederatedCatalogueMetricIds.FilterIndexFailures,
+        label: "Filter index failures",
+        type: MetricType.Counter
+    }
+];
+//# sourceMappingURL=federatedCatalogueMetrics.js.map

package/dist/es/models/federatedCatalogueMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federatedCatalogueMetrics.js","sourceRoot":"","sources":["../../../src/models/federatedCatalogueMetrics.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAyB,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAE/E;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAuB;IAC5D;QACC,EAAE,EAAE,2BAA2B,CAAC,iBAAiB;QACjD,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;IACD;QACC,EAAE,EAAE,2BAA2B,CAAC,cAAc;QAC9C,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;IACD;QACC,EAAE,EAAE,2BAA2B,CAAC,eAAe;QAC/C,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;IACD;QACC,EAAE,EAAE,2BAA2B,CAAC,eAAe;QAC/C,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;IACD;QACC,EAAE,EAAE,2BAA2B,CAAC,oBAAoB;QACpD,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;IACD;QACC,EAAE,EAAE,2BAA2B,CAAC,mBAAmB;QACnD,KAAK,EAAE,uBAAuB;QAC9B,IAAI,EAAE,UAAU,CAAC,OAAO;KACxB;CACD,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { type ITelemetryMetric, MetricType } from \"@twin.org/telemetry-models\";\nimport { FederatedCatalogueMetricIds } from \"./federatedCatalogueMetricIds.js\";\n\n/**\n * Metrics registered by the federated catalogue service.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueMetrics: ITelemetryMetric[] = [\n\t{\n\t\tid: FederatedCatalogueMetricIds.DatasetsRetrieved,\n\t\tlabel: \"Datasets retrieved\",\n\t\ttype: MetricType.Counter\n\t},\n\t{\n\t\tid: FederatedCatalogueMetricIds.DatasetsStored,\n\t\tlabel: \"Datasets stored\",\n\t\ttype: MetricType.Counter\n\t},\n\t{\n\t\tid: FederatedCatalogueMetricIds.DatasetsRemoved,\n\t\tlabel: \"Datasets removed\",\n\t\ttype: MetricType.Counter\n\t},\n\t{\n\t\tid: FederatedCatalogueMetricIds.QueriesExecuted,\n\t\tlabel: \"Queries executed\",\n\t\ttype: MetricType.Counter\n\t},\n\t{\n\t\tid: FederatedCatalogueMetricIds.FilterIndexesCreated,\n\t\tlabel: \"Filter indexes created\",\n\t\ttype: MetricType.Counter\n\t},\n\t{\n\t\tid: FederatedCatalogueMetricIds.FilterIndexFailures,\n\t\tlabel: \"Filter index failures\",\n\t\ttype: MetricType.Counter\n\t}\n];\n"]}

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

@@ -2,6 +2,5 @@ import { Factory } from "@twin.org/core";
 import type { IFederatedCatalogueFilter } from "../models/IFederatedCatalogueFilter.js";
 /**
  * Factory for managing filter plugin registration and retrieval.
- * Follows the TWIN Platform factory pattern used by ComponentFactory and EntityStorageConnectorFactory.
  */
 export declare const FederatedCatalogueFilterFactory: Factory<IFederatedCatalogueFilter>;

package/dist/types/index.d.ts

@@ -7,5 +7,7 @@ export * from "./models/api/IDatasetRemoveRequest.js";
 export * from "./models/api/IDatasetRemoveResponse.js";
 export * from "./models/api/IDatasetSetRequest.js";
 export * from "./models/api/IDatasetSetResponse.js";
+export * from "./models/federatedCatalogueMetricIds.js";
+export * from "./models/federatedCatalogueMetrics.js";
 export * from "./models/IFederatedCatalogueComponent.js";
 export * from "./models/IFederatedCatalogueFilter.js";

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

@@ -10,7 +10,7 @@ export interface IFederatedCatalogueComponent extends IComponent {
      * Retrieve a dataset by its unique identifier.
      * @param datasetId The unique identifier of the dataset.
      * @param trustPayload Optional payload for trust evaluation, if applicable.
-     * @returns The dataset if found, or a CatalogError if not found or an error occurs.
+     * @returns A promise that resolves with the dataset if found, or a CatalogError if not found or an error occurs.
      */
     get(datasetId: string, trustPayload: unknown): Promise<IDcatDataset | IDataspaceProtocolCatalogError>;
     /**
@@ -18,26 +18,25 @@ export interface IFederatedCatalogueComponent extends IComponent {
      * This method is internal and should not be exposed via REST endpoints.
      * @param dataset The dataset to store.
      * @param trustPayload Optional payload for trust evaluation, if applicable.
-     * @returns The unique identifier of the stored dataset, or a CatalogError if an error occurs.
+     * @returns A promise that resolves with the unique identifier of the stored dataset, or a CatalogError if an error occurs.
      */
     set(dataset: IDcatDataset, trustPayload: unknown): Promise<string | IDataspaceProtocolCatalogError>;
     /**
      * Execute a query against the catalogue using registered filter plugins.
-     * Returns a DS Protocol compliant Catalog object with participantId.
+     * Returns a Dataspace Protocol compliant Catalog object with participantId.
      *
      * The root catalog's participantId is the requesting participant (from context).
      * Own datasets (matching requestingParticipantId) go directly in root dataset[].
      * Other participants' datasets are grouped in nested catalog[] entries.
      *
      * For anonymous requests (no context), uses the first publisher found as fallback.
-     * Returns CatalogError 404 when no datasets exist.
+     * Returns a CatalogError with status 404 when no datasets exist.
      *
-     * @param filter The filter criteria containing @type.
+     * @param filter The filter criteria array, where the first element contains @type.
      * @param cursor Optional cursor for pagination.
      * @param limit Optional limit for pagination.
      * @param trustPayload Optional payload for trust evaluation, if applicable.
-     * @returns Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,
-     * or IDataspaceProtocolCatalogError if no datasets found.
+     * @returns A promise that resolves with the catalog result and optional next-page cursor.
      */
     query(filter: unknown[] | undefined, cursor: string | undefined, limit: number | undefined, trustPayload: unknown): Promise<{
         result: IDataspaceProtocolCatalog | IDataspaceProtocolCatalogError;
@@ -47,7 +46,7 @@ export interface IFederatedCatalogueComponent extends IComponent {
      * Remove a dataset from the catalogue by its unique identifier.
      * @param datasetId The unique identifier of the dataset to remove.
      * @param trustPayload Optional payload for trust evaluation, if applicable.
-     * @returns Nothing.
+     * @returns A promise that resolves with undefined on success, or a CatalogError if removal fails.
      */
     remove(datasetId: string, trustPayload: unknown): Promise<IDataspaceProtocolCatalogError | undefined>;
 }

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

@@ -14,7 +14,7 @@ export interface IFederatedCatalogueFilter extends IComponent {
      * @param filter The filter criteria (structure depends on the filter implementation).
      * @param cursor The pagination cursor from the previous query, if any.
      * @param limit The maximum number of results to return.
-     * @returns Object containing datasets matching the filter criteria and optional cursor for next page.
+     * @returns A promise that resolves with datasets matching the filter criteria and an optional cursor for the next page.
      */
     query(trustInfo: ITrustVerificationInfo, filter: unknown, cursor?: string, limit?: number): Promise<{
         datasets: IDcatDataset[];
@@ -24,7 +24,7 @@ export interface IFederatedCatalogueFilter extends IComponent {
      * Generate filter indexes for a dataset to optimize future queries.
      * Indexes are stored as properties on the dataset entity itself.
      * @param dataset The dataset to index.
-     * @returns Record mapping filter-specific index keys to values.
+     * @returns A promise that resolves with a record mapping filter-specific index keys to values.
      */
     createIndex(dataset: IDcatDataset): Promise<{
         [key: string]: unknown;

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

@@ -11,7 +11,7 @@ export interface IDatasetSetRequest {
         [HeaderTypes.Authorization]?: string;
     };
     /**
-     * The response payload containing the dataset or error.
+     * The request body containing the dataset to store.
      */
     body: IDcatDataset;
 }

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

@@ -0,0 +1,33 @@
+/**
+ * Metric IDs for the federated catalogue service.
+ */
+export declare const FederatedCatalogueMetricIds: {
+    /**
+     * Number of datasets retrieved.
+     */
+    readonly DatasetsRetrieved: "fc_datasets_retrieved";
+    /**
+     * Number of datasets stored.
+     */
+    readonly DatasetsStored: "fc_datasets_stored";
+    /**
+     * Number of datasets removed.
+     */
+    readonly DatasetsRemoved: "fc_datasets_removed";
+    /**
+     * Number of queries executed.
+     */
+    readonly QueriesExecuted: "fc_queries_executed";
+    /**
+     * Number of filter indexes created.
+     */
+    readonly FilterIndexesCreated: "fc_filter_indexes_created";
+    /**
+     * Number of filter index failures.
+     */
+    readonly FilterIndexFailures: "fc_filter_index_failures";
+};
+/**
+ * Metric IDs for the federated catalogue service.
+ */
+export type FederatedCatalogueMetricIds = (typeof FederatedCatalogueMetricIds)[keyof typeof FederatedCatalogueMetricIds];

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

@@ -0,0 +1,5 @@
+import { type ITelemetryMetric } from "@twin.org/telemetry-models";
+/**
+ * Metrics registered by the federated catalogue service.
+ */
+export declare const FederatedCatalogueMetrics: ITelemetryMetric[];

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.23](https://github.com/iotaledger/twin-federated-catalogue/compare/federated-catalogue-models-v0.0.3-next.22...federated-catalogue-models-v0.0.3-next.23) (2026-06-19)
+
+
+### Features
+
+* add telemetry metrics to federated catalogue ([#93](https://github.com/iotaledger/twin-federated-catalogue/issues/93)) ([abd8965](https://github.com/iotaledger/twin-federated-catalogue/commit/abd89657d3991e6a50f8ed3845186069549df769))
+
+## [0.0.3-next.22](https://github.com/iotaledger/twin-federated-catalogue/compare/federated-catalogue-models-v0.0.3-next.21...federated-catalogue-models-v0.0.3-next.22) (2026-06-18)
+
+
+### Miscellaneous Chores
+
+* **federated-catalogue-models:** Synchronize repo versions
+
 ## [0.0.3-next.21](https://github.com/iotaledger/twin-federated-catalogue/compare/federated-catalogue-models-v0.0.3-next.20...federated-catalogue-models-v0.0.3-next.21) (2026-06-12)
 
 

package/docs/reference/index.md

@@ -13,6 +13,12 @@
 - [IDatasetSetRequest](interfaces/IDatasetSetRequest.md)
 - [IDatasetSetResponse](interfaces/IDatasetSetResponse.md)
 
+## Type Aliases
+
+- [FederatedCatalogueMetricIds](type-aliases/FederatedCatalogueMetricIds.md)
+
 ## Variables
 
 - [FederatedCatalogueFilterFactory](variables/FederatedCatalogueFilterFactory.md)
+- [FederatedCatalogueMetricIds](variables/FederatedCatalogueMetricIds.md)
+- [FederatedCatalogueMetrics](variables/FederatedCatalogueMetrics.md)

package/docs/reference/interfaces/IDatasetSetRequest.md

@@ -20,4 +20,4 @@ The request headers. Authorization header carries the trust token (Bearer scheme
 
 > **body**: `IDcatDataset`
 
-The response payload containing the dataset or error.
+The request body containing the dataset to store.

package/docs/reference/interfaces/IFederatedCatalogueComponent.md

@@ -33,7 +33,7 @@ Optional payload for trust evaluation, if applicable.
 
 `Promise`\<`IDcatDataset` \| `IDataspaceProtocolCatalogError`\>
 
-The dataset if found, or a CatalogError if not found or an error occurs.
+A promise that resolves with the dataset if found, or a CatalogError if not found or an error occurs.
 
 ***
 
@@ -62,7 +62,7 @@ Optional payload for trust evaluation, if applicable.
 
 `Promise`\<`string` \| `IDataspaceProtocolCatalogError`\>
 
-The unique identifier of the stored dataset, or a CatalogError if an error occurs.
+A promise that resolves with the unique identifier of the stored dataset, or a CatalogError if an error occurs.
 
 ***
 
@@ -71,14 +71,14 @@ The unique identifier of the stored dataset, or a CatalogError if an error occur
 > **query**(`filter`, `cursor`, `limit`, `trustPayload`): `Promise`\<\{ `result`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
 
 Execute a query against the catalogue using registered filter plugins.
-Returns a DS Protocol compliant Catalog object with participantId.
+Returns a Dataspace Protocol compliant Catalog object with participantId.
 
 The root catalog's participantId is the requesting participant (from context).
 Own datasets (matching requestingParticipantId) go directly in root dataset[].
 Other participants' datasets are grouped in nested catalog[] entries.
 
 For anonymous requests (no context), uses the first publisher found as fallback.
-Returns CatalogError 404 when no datasets exist.
+Returns a CatalogError with status 404 when no datasets exist.
 
 #### Parameters
 
@@ -86,7 +86,7 @@ Returns CatalogError 404 when no datasets exist.
 
 `unknown`[] \| `undefined`
 
-The filter criteria containing @type.
+The filter criteria array, where the first element contains @type.
 
 ##### cursor
 
@@ -110,8 +110,7 @@ Optional payload for trust evaluation, if applicable.
 
 `Promise`\<\{ `result`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
 
-Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,
-or IDataspaceProtocolCatalogError if no datasets found.
+A promise that resolves with the catalog result and optional next-page cursor.
 
 ***
 
@@ -139,4 +138,4 @@ Optional payload for trust evaluation, if applicable.
 
 `Promise`\<`IDataspaceProtocolCatalogError` \| `undefined`\>
 
-Nothing.
+A promise that resolves with undefined on success, or a CatalogError if removal fails.

package/docs/reference/interfaces/IFederatedCatalogueFilter.md

@@ -47,7 +47,7 @@ The maximum number of results to return.
 
 `Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>
 
-Object containing datasets matching the filter criteria and optional cursor for next page.
+A promise that resolves with datasets matching the filter criteria and an optional cursor for the next page.
 
 ***
 
@@ -70,4 +70,4 @@ The dataset to index.
 
 `Promise`\<\{\[`key`: `string`\]: `unknown`; \}\>
 
-Record mapping filter-specific index keys to values.
+A promise that resolves with a record mapping filter-specific index keys to values.

package/docs/reference/type-aliases/FederatedCatalogueMetricIds.md

@@ -0,0 +1,5 @@
+# Type Alias: FederatedCatalogueMetricIds
+
+> **FederatedCatalogueMetricIds** = *typeof* [`FederatedCatalogueMetricIds`](../variables/FederatedCatalogueMetricIds.md)\[keyof *typeof* [`FederatedCatalogueMetricIds`](../variables/FederatedCatalogueMetricIds.md)\]
+
+Metric IDs for the federated catalogue service.

package/docs/reference/variables/FederatedCatalogueFilterFactory.md

@@ -3,4 +3,3 @@
 > `const` **FederatedCatalogueFilterFactory**: `Factory`\<[`IFederatedCatalogueFilter`](../interfaces/IFederatedCatalogueFilter.md)\>
 
 Factory for managing filter plugin registration and retrieval.
-Follows the TWIN Platform factory pattern used by ComponentFactory and EntityStorageConnectorFactory.

package/docs/reference/variables/FederatedCatalogueMetricIds.md

@@ -0,0 +1,43 @@
+# Variable: FederatedCatalogueMetricIds
+
+> `const` **FederatedCatalogueMetricIds**: `object`
+
+Metric IDs for the federated catalogue service.
+
+## Type Declaration
+
+### DatasetsRetrieved {#datasetsretrieved}
+
+> `readonly` **DatasetsRetrieved**: `"fc_datasets_retrieved"` = `"fc_datasets_retrieved"`
+
+Number of datasets retrieved.
+
+### DatasetsStored {#datasetsstored}
+
+> `readonly` **DatasetsStored**: `"fc_datasets_stored"` = `"fc_datasets_stored"`
+
+Number of datasets stored.
+
+### DatasetsRemoved {#datasetsremoved}
+
+> `readonly` **DatasetsRemoved**: `"fc_datasets_removed"` = `"fc_datasets_removed"`
+
+Number of datasets removed.
+
+### QueriesExecuted {#queriesexecuted}
+
+> `readonly` **QueriesExecuted**: `"fc_queries_executed"` = `"fc_queries_executed"`
+
+Number of queries executed.
+
+### FilterIndexesCreated {#filterindexescreated}
+
+> `readonly` **FilterIndexesCreated**: `"fc_filter_indexes_created"` = `"fc_filter_indexes_created"`
+
+Number of filter indexes created.
+
+### FilterIndexFailures {#filterindexfailures}
+
+> `readonly` **FilterIndexFailures**: `"fc_filter_index_failures"` = `"fc_filter_index_failures"`
+
+Number of filter index failures.

package/docs/reference/variables/FederatedCatalogueMetrics.md

@@ -0,0 +1,5 @@
+# Variable: FederatedCatalogueMetrics
+
+> `const` **FederatedCatalogueMetrics**: `ITelemetryMetric`[]
+
+Metrics registered by the federated catalogue service.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/federated-catalogue-models",
-	"version": "0.0.3-next.21",
+	"version": "0.0.3-next.23",
 	"description": "Models which define the structure of the Federated Catalogue Service",
 	"repository": {
 		"type": "git",
@@ -21,6 +21,7 @@
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-dataspace-protocol": "next",
 		"@twin.org/standards-w3c-dcat": "next",
+		"@twin.org/telemetry-models": "next",
 		"@twin.org/trust-models": "next",
 		"@twin.org/web": "next"
 	},