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

package/docs/examples.md

@@ -1 +1,55 @@
-# @twin.org/federated-catalogue-models - Examples
+# Federated Catalogue Models Examples
+
+These examples show how to register, discover and resolve filter components so catalogue services can select filtering logic at runtime.
+
+## FederatedCatalogueFilterFactory
+
+```typescript
+import { FederatedCatalogueFilterFactory } from '@twin.org/federated-catalogue-models';
+
+FederatedCatalogueFilterFactory.clear();
+
+FederatedCatalogueFilterFactory.register('PublisherFilter', () => ({
+  className() {
+    return 'PublisherFilter';
+  },
+  async query() {
+    return { datasets: [] };
+  },
+  async createIndex() {
+    return {};
+  }
+}));
+
+FederatedCatalogueFilterFactory.clear();
+
+FederatedCatalogueFilterFactory.register('PublisherFilter', () => ({
+  className() {
+    return 'PublisherFilter';
+  },
+  async query() {
+    return { datasets: [] };
+  },
+  async createIndex() {
+    return {};
+  }
+}));
+
+const filterNames = FederatedCatalogueFilterFactory.names();
+
+console.log(filterNames.includes('PublisherFilter')); // true
+```
+
+```typescript
+import { FederatedCatalogueFilterFactory } from '@twin.org/federated-catalogue-models';
+
+const filter = FederatedCatalogueFilterFactory.get('PublisherFilter');
+const queryResult = await filter.query([
+  {
+    '@type': 'PublisherFilter'
+  }
+]);
+
+console.log(filter.className()); // PublisherFilter
+console.log(queryResult.datasets.length); // 0
+```

package/docs/reference/index.md

@@ -6,15 +6,13 @@
 - [IFederatedCatalogueFilter](interfaces/IFederatedCatalogueFilter.md)
 - [ICatalogRequestRequest](interfaces/ICatalogRequestRequest.md)
 - [ICatalogRequestResponse](interfaces/ICatalogRequestResponse.md)
-- [IGetDatasetRequest](interfaces/IGetDatasetRequest.md)
-- [IGetDatasetResponse](interfaces/IGetDatasetResponse.md)
-- [IBaseFilter](interfaces/IBaseFilter.md)
-
-## Type Aliases
-
-- [FederatedCatalogueContexts](type-aliases/FederatedCatalogueContexts.md)
+- [IDatasetGetRequest](interfaces/IDatasetGetRequest.md)
+- [IDatasetGetResponse](interfaces/IDatasetGetResponse.md)
+- [IDatasetRemoveRequest](interfaces/IDatasetRemoveRequest.md)
+- [IDatasetRemoveResponse](interfaces/IDatasetRemoveResponse.md)
+- [IDatasetSetRequest](interfaces/IDatasetSetRequest.md)
+- [IDatasetSetResponse](interfaces/IDatasetSetResponse.md)
 
 ## Variables
 
 - [FederatedCatalogueFilterFactory](variables/FederatedCatalogueFilterFactory.md)
-- [FederatedCatalogueContexts](variables/FederatedCatalogueContexts.md)

package/docs/reference/interfaces/ICatalogRequestRequest.md

@@ -4,8 +4,41 @@ The request parameters for the catalog request method.
 
 ## Properties
 
-### body
+### headers? {#headers}
 
-> **body**: `ICatalogRequestMessage`
+> `optional` **headers?**: `object`
+
+The request headers. Authorization header carries the trust token (Bearer scheme).
+
+#### authorization?
+
+> `optional` **authorization?**: `string`
+
+***
+
+### body {#body}
+
+> **body**: `IDataspaceProtocolCatalogRequestMessage`
 
 The request body containing the catalog query.
+
+***
+
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+Optional query parameters for pagination.
+Used when following Link header URLs per DS Protocol spec.
+
+#### cursor?
+
+> `optional` **cursor?**: `string`
+
+Opaque cursor token for pagination.
+
+#### limit?
+
+> `optional` **limit?**: `string`
+
+Limit for pagination.

package/docs/reference/interfaces/ICatalogRequestResponse.md

@@ -1,11 +1,35 @@
 # Interface: ICatalogRequestResponse
 
 The response payload for the catalog request method.
+Returns a DS Protocol compliant Catalog with participantId, or CatalogError if no datasets found.
 
 ## Properties
 
-### body
+### headers? {#headers}
 
-> **body**: `ICatalog`
+> `optional` **headers?**: `object`
 
-The response payload containing the catalog with matching datasets.
+Optional headers including RFC 8288 Link header for pagination.
+
+#### link?
+
+> `optional` **link?**: `string` \| `string`[]
+
+***
+
+### statusCode? {#statuscode}
+
+> `optional` **statusCode?**: `HttpStatusCode`
+
+Response status code.
+Per DS Protocol: Returns appropriate HTTP code (e.g., 404) when returning CatalogError.
+
+***
+
+### body {#body}
+
+> **body**: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`
+
+The response payload containing the DS Protocol compliant catalog with participantId,
+or a CatalogError if no datasets are found (404).
+Per DS Protocol: Single participant returns flat catalog, multiple participants return nested catalogs.

package/docs/reference/interfaces/IDatasetGetRequest.md

@@ -0,0 +1,29 @@
+# Interface: IDatasetGetRequest
+
+The request parameters for the get dataset method.
+
+## Properties
+
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+The request headers. Authorization header carries the trust token (Bearer scheme).
+
+#### authorization?
+
+> `optional` **authorization?**: `string`
+
+***
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### datasetId
+
+> **datasetId**: `string`
+
+The unique identifier of the dataset.

package/docs/reference/interfaces/IDatasetGetResponse.md

@@ -0,0 +1,19 @@
+# Interface: IDatasetGetResponse
+
+The response payload for the get dataset method.
+
+## Properties
+
+### statusCode? {#statuscode}
+
+> `optional` **statusCode?**: `HttpStatusCode`
+
+Response status code.
+
+***
+
+### body {#body}
+
+> **body**: `IDcatDataset` \| `IDataspaceProtocolCatalogError`
+
+The response payload containing the dataset or error.

package/docs/reference/interfaces/IDatasetRemoveRequest.md

@@ -0,0 +1,29 @@
+# Interface: IDatasetRemoveRequest
+
+The request parameters for the remove dataset method.
+
+## Properties
+
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+The request headers. Authorization header carries the trust token (Bearer scheme).
+
+#### authorization?
+
+> `optional` **authorization?**: `string`
+
+***
+
+### pathParams {#pathparams}
+
+> **pathParams**: `object`
+
+The path parameters.
+
+#### datasetId
+
+> **datasetId**: `string`
+
+The unique identifier of the dataset.

package/docs/reference/interfaces/IDatasetRemoveResponse.md

@@ -0,0 +1,19 @@
+# Interface: IDatasetRemoveResponse
+
+The response payload for the remove dataset method.
+
+## Properties
+
+### statusCode? {#statuscode}
+
+> `optional` **statusCode?**: `HttpStatusCode`
+
+Response status code.
+
+***
+
+### body? {#body}
+
+> `optional` **body?**: `IDataspaceProtocolCatalogError`
+
+The response payload containing the dataset or error.

package/docs/reference/interfaces/IDatasetSetRequest.md

@@ -0,0 +1,23 @@
+# Interface: IDatasetSetRequest
+
+The request parameters for the set dataset method.
+
+## Properties
+
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+The request headers. Authorization header carries the trust token (Bearer scheme).
+
+#### authorization?
+
+> `optional` **authorization?**: `string`
+
+***
+
+### body {#body}
+
+> **body**: `IDcatDataset`
+
+The response payload containing the dataset or error.

package/docs/reference/interfaces/IDatasetSetResponse.md

@@ -0,0 +1,31 @@
+# Interface: IDatasetSetResponse
+
+The response payload for the set dataset method.
+
+## Properties
+
+### statusCode? {#statuscode}
+
+> `optional` **statusCode?**: `HttpStatusCode`
+
+Response status code.
+
+***
+
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+Optional headers.
+
+#### location?
+
+> `optional` **location?**: `string`
+
+***
+
+### body? {#body}
+
+> `optional` **body?**: `IDataspaceProtocolCatalogError`
+
+The response payload containing the dataset or error.

package/docs/reference/interfaces/IFederatedCatalogueComponent.md

@@ -9,102 +9,134 @@ Provides Dataspace Protocol-compliant catalog endpoints for dataset registry and
 
 ## Methods
 
-### get()
+### get() {#get}
 
-> **get**(`dataSetId`): `Promise`\<`IDataset`\>
+> **get**(`datasetId`, `trustPayload`): `Promise`\<`IDcatDataset` \| `IDataspaceProtocolCatalogError`\>
 
 Retrieve a dataset by its unique identifier.
 
 #### Parameters
 
-##### dataSetId
+##### datasetId
 
 `string`
 
 The unique identifier of the dataset.
 
-#### Returns
+##### trustPayload
+
+`unknown`
 
-`Promise`\<`IDataset`\>
+Optional payload for trust evaluation, if applicable.
 
-The dataset if found.
+#### Returns
 
-#### Throws
+`Promise`\<`IDcatDataset` \| `IDataspaceProtocolCatalogError`\>
 
-NotFoundError if the dataset does not exist.
+The dataset if found, or a CatalogError if not found or an error occurs.
 
 ***
 
-### set()
+### set() {#set}
 
-> **set**(`dataSet`): `Promise`\<`void`\>
+> **set**(`dataset`, `trustPayload`): `Promise`\<`string` \| `IDataspaceProtocolCatalogError`\>
 
 Insert or update a dataset in the catalogue.
 This method is internal and should not be exposed via REST endpoints.
 
 #### Parameters
 
-##### dataSet
+##### dataset
 
-`IDataset`
+`IDcatDataset`
 
 The dataset to store.
 
+##### trustPayload
+
+`unknown`
+
+Optional payload for trust evaluation, if applicable.
+
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`string` \| `IDataspaceProtocolCatalogError`\>
 
-Nothing.
+The unique identifier of the stored dataset, or a CatalogError if an error occurs.
 
 ***
 
-### query()
+### query() {#query}
 
-> **query**(`filter?`): `Promise`\<`ICatalog`\>
+> **query**(`filter`, `cursor`, `limit`, `trustPayload`): `Promise`\<\{ `result`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
 
 Execute a query against the catalogue using registered filter plugins.
-Returns a complete DCAT Catalog object with proper JSON-LD context, metadata, and datasets.
-Filter plugins must be registered in FilterFactory before service initialization.
-The filter payload is evaluated by the appropriate filter plugin based on its structure.
-Pagination properties (cursor, limit) and filter type (@type) should be included
-within the filter object per Eclipse Dataspace Protocol JSON-LD extension patterns.
+Returns a DS 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.
 
 #### Parameters
 
-##### filter?
+##### filter
 
-`unknown`[]
+`unknown`[] \| `undefined`
 
-The filter criteria containing @type, optional cursor and limit properties.
+The filter criteria containing @type.
 
-#### Returns
+##### cursor
+
+`string` \| `undefined`
 
-`Promise`\<`ICatalog`\>
+Optional cursor for pagination.
 
-Complete ICatalog object with @context, @id, @type, dcat:dataset, and optional cursor.
+##### limit
 
-#### Throws
+`number` \| `undefined`
 
-NotFoundError if the
+Optional limit for pagination.
+
+##### trustPayload
+
+`unknown`
+
+Optional payload for trust evaluation, if applicable.
+
+#### Returns
+
+`Promise`\<\{ `result`: `IDataspaceProtocolCatalog` \| `IDataspaceProtocolCatalogError`; `cursor?`: `string`; \}\>
+
+Complete IDataspaceProtocolCatalog with @context, @id, @type, participantId, dataset/catalog,
+or IDataspaceProtocolCatalogError if no datasets found.
 
 ***
 
-### remove()
+### remove() {#remove}
 
-> **remove**(`dataSetId`): `Promise`\<`void`\>
+> **remove**(`datasetId`, `trustPayload`): `Promise`\<`IDataspaceProtocolCatalogError` \| `undefined`\>
 
 Remove a dataset from the catalogue by its unique identifier.
 
 #### Parameters
 
-##### dataSetId
+##### datasetId
 
 `string`
 
 The unique identifier of the dataset to remove.
 
+##### trustPayload
+
+`unknown`
+
+Optional payload for trust evaluation, if applicable.
+
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`IDataspaceProtocolCatalogError` \| `undefined`\>
 
 Nothing.

package/docs/reference/interfaces/IFederatedCatalogueFilter.md

@@ -10,42 +10,59 @@ Filters are registered by name in the FilterFactory and do not need to self-iden
 
 ## Methods
 
-### query()
+### query() {#query}
 
-> **query**(`filter`): `Promise`\<\{ `datasets`: `IDataset`[]; `cursor?`: `string`; \}\>
+> **query**(`trustInfo`, `filter`, `cursor?`, `limit?`): `Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>
 
 Execute a filter-specific query over the catalogue.
 Each filter interprets the payload according to its own semantics.
-Pagination properties (cursor, limit) are extracted from the filter object by the service layer.
 
 #### Parameters
 
+##### trustInfo
+
+`ITrustVerificationInfo`
+
+The trust verification information for the current request.
+
 ##### filter
 
 `unknown`
 
 The filter criteria (structure depends on the filter implementation).
 
+##### cursor?
+
+`string`
+
+The pagination cursor from the previous query, if any.
+
+##### limit?
+
+`number`
+
+The maximum number of results to return.
+
 #### Returns
 
-`Promise`\<\{ `datasets`: `IDataset`[]; `cursor?`: `string`; \}\>
+`Promise`\<\{ `datasets`: `IDcatDataset`[]; `cursor?`: `string`; \}\>
 
 Object containing datasets matching the filter criteria and optional cursor for next page.
 
 ***
 
-### createIndex()
+### createIndex() {#createindex}
 
-> **createIndex**(`dataSet`): `Promise`\<\{\[`key`: `string`\]: `unknown`; \}\>
+> **createIndex**(`dataset`): `Promise`\<\{\[`key`: `string`\]: `unknown`; \}\>
 
 Generate filter indexes for a dataset to optimize future queries.
 Indexes are stored as properties on the dataset entity itself.
 
 #### Parameters
 
-##### dataSet
+##### dataset
 
-`IDataset`
+`IDcatDataset`
 
 The dataset to index.
 

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@twin.org/federated-catalogue-models",
-	"version": "0.0.3-next.2",
+	"version": "0.0.3-next.21",
 	"description": "Models which define the structure of the Federated Catalogue Service",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/twinfoundation/federated-catalogue.git",
+		"url": "git+https://github.com/iotaledger/twin-federated-catalogue.git",
 		"directory": "packages/federated-catalogue-models"
 	},
-	"author": "jose.cantera@iota.org",
+	"author": "cornel.filip@iota.org",
 	"license": "Apache-2.0",
 	"type": "module",
 	"engines": {
@@ -20,7 +20,9 @@
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next",
 		"@twin.org/standards-dataspace-protocol": "next",
-		"@twin.org/standards-w3c-dcat": "next"
+		"@twin.org/standards-w3c-dcat": "next",
+		"@twin.org/trust-models": "next",
+		"@twin.org/web": "next"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",
@@ -50,7 +52,7 @@
 		"schemas"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/federated-catalogue/issues"
+		"url": "git+https://github.com/iotaledger/twin-federated-catalogue/issues"
 	},
 	"homepage": "https://twindev.org"
 }

package/dist/es/models/api/IGetDatasetRequest.js

@@ -1,4 +0,0 @@
-// Copyright 2025 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-export {};
-//# sourceMappingURL=IGetDatasetRequest.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"IGetDatasetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IGetDatasetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The request parameters for the get dataset method.\n */\nexport interface IGetDatasetRequest {\n\t/**\n\t * The path parameters.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The unique identifier of the dataset.\n\t\t */\n\t\tdatasetId: string;\n\t};\n}\n"]}

package/dist/es/models/api/IGetDatasetResponse.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=IGetDatasetResponse.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"IGetDatasetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IGetDatasetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataset } from \"@twin.org/standards-w3c-dcat\";\n\n/**\n * The response payload for the get dataset method.\n */\nexport interface IGetDatasetResponse {\n\t/**\n\t * The response payload containing the dataset.\n\t */\n\tbody: IDataset;\n}\n"]}

package/dist/es/models/federatedCatalogueContexts.js

@@ -1,13 +0,0 @@
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * The contexts of federated catalogue data.
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const FederatedCatalogueContexts = {
-    /**
-     * The context root for the federated catalogue types.
-     */
-    ContextRoot: "https://schema.twindev.org/federated-catalogue/"
-};
-//# sourceMappingURL=federatedCatalogueContexts.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"federatedCatalogueContexts.js","sourceRoot":"","sources":["../../../src/models/federatedCatalogueContexts.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACzC;;OAEG;IACH,WAAW,EAAE,iDAAiD;CACrD,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The contexts of federated catalogue data.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const FederatedCatalogueContexts = {\n\t/**\n\t * The context root for the federated catalogue types.\n\t */\n\tContextRoot: \"https://schema.twindev.org/federated-catalogue/\"\n} as const;\n\n/**\n * The contexts of federated catalogue data.\n */\nexport type FederatedCatalogueContexts =\n\t(typeof FederatedCatalogueContexts)[keyof typeof FederatedCatalogueContexts];\n"]}

package/dist/es/models/filters/IBaseFilter.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=IBaseFilter.js.map

package/dist/es/models/filters/IBaseFilter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IBaseFilter.js","sourceRoot":"","sources":["../../../../src/models/filters/IBaseFilter.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IJsonLdNodeObject } from \"@twin.org/data-json-ld\";\n\n/**\n * Base filter interface with pagination support.\n * All filter objects in the federated catalogue extend this base.\n *\n * Per Eclipse Dataspace Protocol constraints, cursor and limit cannot be\n * top-level properties in CatalogRequestMessage. They must be embedded\n * within the filter object using a custom JSON-LD vocabulary.\n *\n * After JSON-LD compaction, properties use direct names (cursor, limit) rather\n * than prefixed names. Each filter implementation should extend this interface\n * to define its own filter-specific properties.\n */\nexport interface IBaseFilter extends IJsonLdNodeObject {\n\t/**\n\t * Filter type discriminator.\n\t * Used to route filter to appropriate filter implementation.\n\t * Example: \"FilterByExample\", \"FilterByPolicy\", etc.\n\t * Required for filter routing.\n\t */\n\t\"@type\": string;\n\n\t/**\n\t * Optional cursor for pagination.\n\t * When provided, returns results starting after this cursor.\n\t * Namespace: https://schema.twindev.org/federated-catalogue/cursor\n\t */\n\tcursor?: string;\n\n\t/**\n\t * Optional limit for number of results.\n\t * Defaults to implementation-specific value if not provided.\n\t * Namespace: https://schema.twindev.org/federated-catalogue/limit\n\t */\n\tlimit?: number;\n}\n"]}

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

@@ -1,14 +0,0 @@
-/**
- * The request parameters for the get dataset method.
- */
-export interface IGetDatasetRequest {
-    /**
-     * The path parameters.
-     */
-    pathParams: {
-        /**
-         * The unique identifier of the dataset.
-         */
-        datasetId: string;
-    };
-}

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

@@ -1,10 +0,0 @@
-import type { IDataset } from "@twin.org/standards-w3c-dcat";
-/**
- * The response payload for the get dataset method.
- */
-export interface IGetDatasetResponse {
-    /**
-     * The response payload containing the dataset.
-     */
-    body: IDataset;
-}