@twin.org/dataspace-models 0.0.3-next.17 → 0.0.3-next.19

package/README.md

@@ -1,6 +1,8 @@
-# TWIN Dataspace Models
+# Dataspace Models
 
-Models which define the structure of the dataspace contracts and connectors.
+This package defines the shared contracts and data types used across control plane and data plane components. It provides the common language that keeps request payloads, transfer records, and activity structures aligned between services and clients.
+
+The exported interfaces and entities are designed to support consistent integration behaviour across the repository, reducing mismatch risks when components evolve.
 
 ## Installation
 
@@ -8,48 +10,6 @@ Models which define the structure of the dataspace contracts and connectors.
 npm install @twin.org/dataspace-models
 ```
 
-## Overview
-
-This package provides the core interfaces and entities for the TWIN Dataspace Connector, implementing the Eclipse Dataspace Protocol (DSP) specification.
-
-### Key Components
-
-#### Control Plane
-
-- `IDataspaceControlPlaneComponent` - Interface for DSP protocol operations (negotiation, transfer management)
-- `IDataspaceControlPlaneResolverComponent` - Interface for resolving `consumerPid` to transfer context
-- `ITransferContext` - Transfer context containing datasetId, agreement, and policies
-- `TransferProcessEntity` - Entity storage model for transfer processes
-
-#### Data Plane
-
-- `IDataspaceDataPlaneComponent` - Interface for data access operations (GET/query entities)
-- `IDataspaceApp` - Interface for Dataspace Apps that handle specific datasets
-
-#### Shared Entities
-
-- `TransferProcessEntity` - Shared between Control Plane and Data Plane via entity storage
-  - Primary key: `id` (consumerPid)
-  - Stores: state, datasetId, agreement, dataAddress, token expiration
-  - Used for `consumerPid` flow
-
-### Architecture
-
-```text
-Control Plane                    Data Plane
-     │                               │
-     │ Creates/Updates               │ Reads
-     │                               │
-     └───── TransferProcessEntity ───┘
-                (shared storage)
-```
-
-The unified architecture enables:
-
-- Transfer-based access via `consumerPid` parameter
-- Shared state without resolver API calls
-- Policy enforcement from agreements
-
 ## Examples
 
 Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)

package/dist/es/dataTypes/dataspaceDataTypes.js

@@ -21,7 +21,10 @@ export class DataspaceDataTypes {
                 schema: DataspaceActivitySchema
             }
         ];
-        DataTypeHelper.registerTypes(DataspaceContexts.JsonSchemaNamespace, DataspaceContexts.JsonSchemaNamespace, types);
+        DataTypeHelper.registerTypes(DataspaceContexts.JsonSchemaNamespace, undefined, types.map(t => ({
+            type: `Dataspace${t.type}`,
+            schema: t.schema
+        })));
     }
 }
 //# sourceMappingURL=dataspaceDataTypes.js.map

package/dist/es/dataTypes/dataspaceDataTypes.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataspaceDataTypes.js","sourceRoot":"","sources":["../../../src/dataTypes/dataspaceDataTypes.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,uBAAuB,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAE9F;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC9B;;OAEG;IACI,MAAM,CAAC,aAAa;QAC1B,wBAAwB,CAAC,iBAAiB,EAAE,CAAC;QAC7C,wBAAwB,CAAC,aAAa,EAAE,CAAC;QAEzC,MAAM,KAAK,GAAG;YACb;gBACC,IAAI,EAAE,cAAc,CAAC,QAAQ;gBAC7B,MAAM,EAAE,uBAAuB;aAC/B;SACD,CAAC;QAEF,cAAc,CAAC,aAAa,CAC3B,iBAAiB,CAAC,mBAAmB,EACrC,iBAAiB,CAAC,mBAAmB,EACrC,KAAK,CACL,CAAC;IACH,CAAC;CACD","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\nimport { DataTypeHelper } from \"@twin.org/data-core\";\nimport { ActivityStreamsDataTypes } from \"@twin.org/standards-w3c-activity-streams\";\nimport { DataspaceContexts } from \"../models/dataspaceContexts.js\";\nimport { DataspaceTypes } from \"../models/dataspaceTypes.js\";\nimport DataspaceActivitySchema from \"../schemas/DataspaceActivity.json\" with { type: \"json\" };\n\n/**\n * Dataspace datatypes.\n */\nexport class DataspaceDataTypes {\n\t/**\n\t * Register all the data types.\n\t */\n\tpublic static registerTypes(): void {\n\t\tActivityStreamsDataTypes.registerRedirects();\n\t\tActivityStreamsDataTypes.registerTypes();\n\n\t\tconst types = [\n\t\t\t{\n\t\t\t\ttype: DataspaceTypes.Activity,\n\t\t\t\tschema: DataspaceActivitySchema\n\t\t\t}\n\t\t];\n\n\t\tDataTypeHelper.registerTypes(\n\t\t\tDataspaceContexts.JsonSchemaNamespace,\n\t\t\tDataspaceContexts.JsonSchemaNamespace,\n\t\t\ttypes\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"dataspaceDataTypes.js","sourceRoot":"","sources":["../../../src/dataTypes/dataspaceDataTypes.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,uBAAuB,MAAM,mCAAmC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAE9F;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC9B;;OAEG;IACI,MAAM,CAAC,aAAa;QAC1B,wBAAwB,CAAC,iBAAiB,EAAE,CAAC;QAC7C,wBAAwB,CAAC,aAAa,EAAE,CAAC;QAEzC,MAAM,KAAK,GAAG;YACb;gBACC,IAAI,EAAE,cAAc,CAAC,QAAQ;gBAC7B,MAAM,EAAE,uBAAuB;aAC/B;SACD,CAAC;QAEF,cAAc,CAAC,aAAa,CAC3B,iBAAiB,CAAC,mBAAmB,EACrC,SAAS,EACT,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACf,IAAI,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM;SAChB,CAAC,CAAC,CACH,CAAC;IACH,CAAC;CACD","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\nimport { DataTypeHelper } from \"@twin.org/data-core\";\nimport { ActivityStreamsDataTypes } from \"@twin.org/standards-w3c-activity-streams\";\nimport { DataspaceContexts } from \"../models/dataspaceContexts.js\";\nimport { DataspaceTypes } from \"../models/dataspaceTypes.js\";\nimport DataspaceActivitySchema from \"../schemas/DataspaceActivity.json\" with { type: \"json\" };\n\n/**\n * Dataspace datatypes.\n */\nexport class DataspaceDataTypes {\n\t/**\n\t * Register all the data types.\n\t */\n\tpublic static registerTypes(): void {\n\t\tActivityStreamsDataTypes.registerRedirects();\n\t\tActivityStreamsDataTypes.registerTypes();\n\n\t\tconst types = [\n\t\t\t{\n\t\t\t\ttype: DataspaceTypes.Activity,\n\t\t\t\tschema: DataspaceActivitySchema\n\t\t\t}\n\t\t];\n\n\t\tDataTypeHelper.registerTypes(\n\t\t\tDataspaceContexts.JsonSchemaNamespace,\n\t\t\tundefined,\n\t\t\ttypes.map(t => ({\n\t\t\t\ttype: `Dataspace${t.type}`,\n\t\t\t\tschema: t.schema\n\t\t\t}))\n\t\t);\n\t}\n}\n"]}

package/dist/es/models/control-plane/IDataspaceControlPlaneComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/control-plane/IDataspaceControlPlaneComponent.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\tIDataspaceProtocolContractNegotiation,\n\tIDataspaceProtocolContractNegotiationError,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\n\n/**\n * Dataspace Control Plane Component interface.\n * Implements Eclipse Dataspace Protocol (DSP) specifications:\n * - Contract Negotiation Protocol\n * - Transfer Process Protocol\n *\n * This component acts as the Control Plane for contract negotiation and\n * data transfers between nodes in a dataspace.\n *\n * DSP 2025-1 Specification: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/\n */\nexport interface IDataspaceControlPlaneComponent extends IComponent {\n\t// ============================================================================\n\t// CONTRACT NEGOTIATION PROTOCOL (DSP)\n\t// Methods for negotiating agreements before transfers\n\t// ============================================================================\n\n\t/**\n\t * Register a callback to receive negotiation state change notifications.\n\t * Upstream modules (e.g. supply-chain) register their callback here\n\t * to be notified when negotiations complete, fail, or change state.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterNegotiationCallback(key: string, callback: INegotiationCallback): void;\n\n\t/**\n\t * Unregister a previously registered negotiation callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterNegotiationCallback(key: string): void;\n\n\t/**\n\t * Negotiate a contract agreement with a provider.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Returns immediately with a negotiationId. The caller is notified\n\t * via the registered INegotiationCallback when the negotiation completes.\n\t * The negotiation follows DSP state machine: REQUESTED → OFFERED → AGREED → VERIFIED → FINALIZED.\n\t *\n\t * This method has NO REST client implementation — it is only accessible via ComponentFactory.get().\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param offerId The offer ID from the provider's catalog.\n\t * @param providerEndpoint The provider's contract negotiation endpoint URL.\n\t * @param publicOrigin The public origin URL of this control plane (for callbacks).\n\t * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).\n\t * @returns The negotiation ID for tracking. Use registered callback for completion.\n\t */\n\tnegotiateAgreement(\n\t\tofferId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ negotiationId: string }>;\n\n\t/**\n\t * Get the current state of a contract negotiation.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Queries the current state of an ongoing or completed negotiation.\n\t * Use this to monitor negotiation progress.\n\t * Returns the DSP-compliant negotiation state or error.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param negotiationId The unique identifier of the negotiation.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns DSP ContractNegotiation with current state, or error.\n\t */\n\tgetNegotiation(\n\t\tnegotiationId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;\n\n\t/**\n\t * Get negotiation history.\n\t * Queries past contract negotiations for audit trails and debugging.\n\t *\n\t * Returns a list of past negotiations with their states and metadata.\n\t * Supports optional filtering by state and pagination via cursor.\n\t *\n\t * @param state Optional filter by negotiation state (e.g., \"FINALIZED\", \"TERMINATED\").\n\t * @param cursor Optional pagination cursor for fetching next page.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns List of negotiation history entries with pagination cursor.\n\t */\n\tgetNegotiationHistory(\n\t\tstate: string | undefined,\n\t\tcursor: string | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tnegotiations: {\n\t\t\tnegotiation:\n\t\t\t\t| IDataspaceProtocolContractNegotiation\n\t\t\t\t| IDataspaceProtocolContractNegotiationError;\n\t\t\tcreatedAt: string;\n\t\t\tofferId?: string;\n\t\t\tagreementId?: string;\n\t\t}[];\n\t\tcursor?: string;\n\t\tcount: number;\n\t}>;\n\n\t// ============================================================================\n\t// TRANSFER PROCESS PROTOCOL (DSP)\n\t// Methods for managing data transfers after agreements are established\n\t// ============================================================================\n\n\t// ----------------------------------------------------------------------------\n\t// CONSUMER SIDE OPERATIONS\n\t// Methods called by the Data Consumer to initiate transfers\n\t// ----------------------------------------------------------------------------\n\n\t/**\n\t * Request a Transfer Process.\n\t * Creates a new Transfer Process in REQUESTED state.\n\t *\n\t * Role Performed: Provider\n\t * Called by: Consumer when it wants to request a new Transfer Process\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message\n\t *\n\t * @param request Transfer request message (DSP compliant) containing agreementId,\n\t * consumerPid, callbackAddress, and format.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * The consumer must prove their identity by providing a valid trust payload.\n\t * @returns Transfer Process (DSP compliant) with state REQUESTED, including\n\t * both consumerPid and providerPid, or TransferError if the operation fails.\n\t */\n\trequestTransfer(\n\t\trequest: IDataspaceProtocolTransferRequestMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// PROVIDER SIDE OPERATIONS\n\t// Methods called by the Data Provider to respond to transfer requests\n\t// ============================================================================\n\n\t/**\n\t * Start a Transfer Process.\n\t * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.\n\t *\n\t * Role Performed: Provider / Consumer\n\t * Called by: Provider when a Transfer Process starts, or Consumer to attempt to start a Transfer Process after it has been suspended\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message\n\t *\n\t * @param message Transfer start message (DSP compliant).\n\t * @param publicOrigin The public origin URL of this service (used to construct data plane endpoint for PULL transfers).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.\n\t */\n\tstartTransfer(\n\t\tmessage: IDataspaceProtocolTransferStartMessage,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// SHARED STATE MANAGEMENT OPERATIONS\n\t// Methods that can be called by either Consumer or Provider\n\t// ============================================================================\n\n\t/**\n\t * Complete a Transfer Process.\n\t * Transitions Transfer Process to COMPLETED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process is completed on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-completion-message\n\t *\n\t * @param message Transfer completion message (DSP compliant).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.\n\t */\n\tcompleteTransfer(\n\t\tmessage: IDataspaceProtocolTransferCompletionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Suspend a Transfer Process.\n\t * Transitions Transfer Process to SUSPENDED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be temporarily suspended on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message\n\t *\n\t * @param message Transfer suspension message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.\n\t */\n\tsuspendTransfer(\n\t\tmessage: IDataspaceProtocolTransferSuspensionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Terminate a Transfer Process.\n\t * Transitions Transfer Process to TERMINATED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be terminated on their side (e.g., due to error)\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message\n\t *\n\t * @param message Transfer termination message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.\n\t */\n\tterminateTransfer(\n\t\tmessage: IDataspaceProtocolTransferTerminationMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Get Transfer Process State.\n\t * Query the current state of a Transfer Process.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when they need to check the status of a Transfer process on their side\n\t *\n\t * Supports role-agnostic lookup using either consumerPid or providerPid.\n\t * The service will automatically detect which role the caller is acting as\n\t * (Consumer or Provider) based on the PID provided.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process\n\t *\n\t * @param pid The Process ID (consumerPid or providerPid) used to identify the transfer.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.\n\t */\n\tgetTransferProcess(\n\t\tpid: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/control-plane/IDataspaceControlPlaneComponent.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\tIDataspaceProtocolContractNegotiation,\n\tIDataspaceProtocolContractNegotiationError,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\n\n/**\n * Dataspace Control Plane Component interface.\n * Implements Eclipse Dataspace Protocol (DSP) specifications:\n * - Contract Negotiation Protocol\n * - Transfer Process Protocol\n *\n * This component acts as the Control Plane for contract negotiation and\n * data transfers between nodes in a dataspace.\n *\n * DSP 2025-1 Specification: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/\n */\nexport interface IDataspaceControlPlaneComponent extends IComponent {\n\t// ============================================================================\n\t// CONTRACT NEGOTIATION PROTOCOL (DSP)\n\t// Methods for negotiating agreements before transfers\n\t// ============================================================================\n\n\t/**\n\t * Register a callback to receive negotiation state change notifications.\n\t * Upstream modules (e.g. supply-chain) register their callback here\n\t * to be notified when negotiations complete, fail, or change state.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterNegotiationCallback(key: string, callback: INegotiationCallback): void;\n\n\t/**\n\t * Unregister a previously registered negotiation callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterNegotiationCallback(key: string): void;\n\n\t/**\n\t * Negotiate a contract agreement with a provider.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Returns immediately with a negotiationId. The caller is notified\n\t * via the registered INegotiationCallback when the negotiation completes.\n\t * The negotiation follows DSP state machine: REQUESTED → OFFERED → AGREED → VERIFIED → FINALIZED.\n\t *\n\t * This method has NO REST client implementation — it is only accessible via ComponentFactory.get().\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param datasetId The dataset ID from the provider's catalog.\n\t * @param offerId The offer ID from the provider's catalog.\n\t * @param providerEndpoint The provider's contract negotiation endpoint URL.\n\t * @param publicOrigin The public origin URL of this control plane (for callbacks).\n\t * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).\n\t * @returns The negotiation ID for tracking. Use registered callback for completion.\n\t */\n\tnegotiateAgreement(\n\t\tdatasetId: string,\n\t\tofferId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ negotiationId: string }>;\n\n\t/**\n\t * Get the current state of a contract negotiation.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Queries the current state of an ongoing or completed negotiation.\n\t * Use this to monitor negotiation progress.\n\t * Returns the DSP-compliant negotiation state or error.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param negotiationId The unique identifier of the negotiation.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns DSP ContractNegotiation with current state, or error.\n\t */\n\tgetNegotiation(\n\t\tnegotiationId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;\n\n\t/**\n\t * Get negotiation history.\n\t * Queries past contract negotiations for audit trails and debugging.\n\t *\n\t * Returns a list of past negotiations with their states and metadata.\n\t * Supports optional filtering by state and pagination via cursor.\n\t *\n\t * @param state Optional filter by negotiation state (e.g., \"FINALIZED\", \"TERMINATED\").\n\t * @param cursor Optional pagination cursor for fetching next page.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns List of negotiation history entries with pagination cursor.\n\t */\n\tgetNegotiationHistory(\n\t\tstate: string | undefined,\n\t\tcursor: string | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tnegotiations: {\n\t\t\tnegotiation:\n\t\t\t\t| IDataspaceProtocolContractNegotiation\n\t\t\t\t| IDataspaceProtocolContractNegotiationError;\n\t\t\tcreatedAt: string;\n\t\t\tofferId?: string;\n\t\t\tagreementId?: string;\n\t\t}[];\n\t\tcursor?: string;\n\t\tcount: number;\n\t}>;\n\n\t// ============================================================================\n\t// TRANSFER PROCESS PROTOCOL (DSP)\n\t// Methods for managing data transfers after agreements are established\n\t// ============================================================================\n\n\t// ----------------------------------------------------------------------------\n\t// CONSUMER SIDE OPERATIONS\n\t// Methods called by the Data Consumer to initiate transfers\n\t// ----------------------------------------------------------------------------\n\n\t/**\n\t * Request a Transfer Process.\n\t * Creates a new Transfer Process in REQUESTED state.\n\t *\n\t * Role Performed: Provider\n\t * Called by: Consumer when it wants to request a new Transfer Process\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message\n\t *\n\t * @param request Transfer request message (DSP compliant) containing agreementId,\n\t * consumerPid, callbackAddress, and format.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * The consumer must prove their identity by providing a valid trust payload.\n\t * @returns Transfer Process (DSP compliant) with state REQUESTED, including\n\t * both consumerPid and providerPid, or TransferError if the operation fails.\n\t */\n\trequestTransfer(\n\t\trequest: IDataspaceProtocolTransferRequestMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// PROVIDER SIDE OPERATIONS\n\t// Methods called by the Data Provider to respond to transfer requests\n\t// ============================================================================\n\n\t/**\n\t * Start a Transfer Process.\n\t * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.\n\t *\n\t * Role Performed: Provider / Consumer\n\t * Called by: Provider when a Transfer Process starts, or Consumer to attempt to start a Transfer Process after it has been suspended\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message\n\t *\n\t * @param message Transfer start message (DSP compliant).\n\t * @param publicOrigin The public origin URL of this service (used to construct data plane endpoint for PULL transfers).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.\n\t */\n\tstartTransfer(\n\t\tmessage: IDataspaceProtocolTransferStartMessage,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// SHARED STATE MANAGEMENT OPERATIONS\n\t// Methods that can be called by either Consumer or Provider\n\t// ============================================================================\n\n\t/**\n\t * Complete a Transfer Process.\n\t * Transitions Transfer Process to COMPLETED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process is completed on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-completion-message\n\t *\n\t * @param message Transfer completion message (DSP compliant).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.\n\t */\n\tcompleteTransfer(\n\t\tmessage: IDataspaceProtocolTransferCompletionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Suspend a Transfer Process.\n\t * Transitions Transfer Process to SUSPENDED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be temporarily suspended on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message\n\t *\n\t * @param message Transfer suspension message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.\n\t */\n\tsuspendTransfer(\n\t\tmessage: IDataspaceProtocolTransferSuspensionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Terminate a Transfer Process.\n\t * Transitions Transfer Process to TERMINATED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be terminated on their side (e.g., due to error)\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message\n\t *\n\t * @param message Transfer termination message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.\n\t */\n\tterminateTransfer(\n\t\tmessage: IDataspaceProtocolTransferTerminationMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Get Transfer Process State.\n\t * Query the current state of a Transfer Process.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when they need to check the status of a Transfer process on their side\n\t *\n\t * Supports role-agnostic lookup using either consumerPid or providerPid.\n\t * The service will automatically detect which role the caller is acting as\n\t * (Consumer or Provider) based on the PID provided.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process\n\t *\n\t * @param pid The Process ID (consumerPid or providerPid) used to identify the transfer.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.\n\t */\n\tgetTransferProcess(\n\t\tpid: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n}\n"]}

package/dist/es/models/dataspaceContexts.js

@@ -5,6 +5,9 @@
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const DataspaceContexts = {
+    /**
+     * The namespace location of the hosted version of the JSON Schema.
+     */
     JsonSchemaNamespace: "https://schema.twindev.org/dataspace/"
 };
 //# sourceMappingURL=dataspaceContexts.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataspaceContexts.js","sourceRoot":"","sources":["../../../src/models/dataspaceContexts.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,mBAAmB,EAAE,uCAAuC;CACnD,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The contexts related to Dataspace\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const DataspaceContexts = {\n\tJsonSchemaNamespace: \"https://schema.twindev.org/dataspace/\"\n} as const;\n\n/**\n * The types concerning dataspace.\n */\nexport type DataspaceContexts = (typeof DataspaceContexts)[keyof typeof DataspaceContexts];\n"]}
+{"version":3,"file":"dataspaceContexts.js","sourceRoot":"","sources":["../../../src/models/dataspaceContexts.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC;;OAEG;IACH,mBAAmB,EAAE,uCAAuC;CACnD,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The contexts related to Dataspace\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const DataspaceContexts = {\n\t/**\n\t * The namespace location of the hosted version of the JSON Schema.\n\t */\n\tJsonSchemaNamespace: \"https://schema.twindev.org/dataspace/\"\n} as const;\n\n/**\n * The types concerning dataspace.\n */\nexport type DataspaceContexts = (typeof DataspaceContexts)[keyof typeof DataspaceContexts];\n"]}

package/dist/types/models/control-plane/IDataspaceControlPlaneComponent.d.ts

@@ -38,13 +38,14 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      *
      * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol
      *
+     * @param datasetId The dataset ID from the provider's catalog.
      * @param offerId The offer ID from the provider's catalog.
      * @param providerEndpoint The provider's contract negotiation endpoint URL.
      * @param publicOrigin The public origin URL of this control plane (for callbacks).
      * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).
      * @returns The negotiation ID for tracking. Use registered callback for completion.
      */
-    negotiateAgreement(offerId: string, providerEndpoint: string, publicOrigin: string, trustPayload: unknown): Promise<{
+    negotiateAgreement(datasetId: string, offerId: string, providerEndpoint: string, publicOrigin: string, trustPayload: unknown): Promise<{
         negotiationId: string;
     }>;
     /**

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

@@ -2,6 +2,9 @@
  * The contexts related to Dataspace
  */
 export declare const DataspaceContexts: {
+    /**
+     * The namespace location of the hosted version of the JSON Schema.
+     */
     readonly JsonSchemaNamespace: "https://schema.twindev.org/dataspace/";
 };
 /**

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.19](https://github.com/twinfoundation/dataspace/compare/dataspace-models-v0.0.3-next.18...dataspace-models-v0.0.3-next.19) (2026-03-12)
+
+
+### Features
+
+* improve validation ([#82](https://github.com/twinfoundation/dataspace/issues/82)) ([8bfaf7b](https://github.com/twinfoundation/dataspace/commit/8bfaf7b830f89b63575f8a51ee96bd8ac4da02f4))
+
+## [0.0.3-next.18](https://github.com/twinfoundation/dataspace/compare/dataspace-models-v0.0.3-next.17...dataspace-models-v0.0.3-next.18) (2026-03-09)
+
+
+### Features
+
+* resolve DSP transfer flow bugs for cross-node communication ([#76](https://github.com/twinfoundation/dataspace/issues/76)) ([506a45c](https://github.com/twinfoundation/dataspace/commit/506a45c94e63d5f958b1fc7131adfe452c3e2974))
+
 ## [0.0.3-next.17](https://github.com/twinfoundation/dataspace/compare/dataspace-models-v0.0.3-next.16...dataspace-models-v0.0.3-next.17) (2026-03-06)
 
 

package/docs/examples.md

@@ -1 +1,33 @@
-# @twin.org/dataspace-models - Examples
+# Models Examples
+
+Use these snippets to register dataspace data types and shape transfer process records for shared persistence.
+
+## DataspaceDataTypes
+
+```typescript
+import { DataspaceDataTypes } from '@twin.org/dataspace-models';
+
+DataspaceDataTypes.registerTypes();
+console.log('registered'); // registered
+```
+
+## TransferProcess
+
+```typescript
+import { TransferProcess } from '@twin.org/dataspace-models';
+
+const process = new TransferProcess();
+process.id = 'tp-001';
+process.consumerPid = 'consumer-process-id';
+process.providerPid = 'provider-process-id';
+process.agreementId = 'urn:agreement:001';
+process.datasetId = 'https://twin.example.org/data-service-1';
+process.offerId = 'urn:policy:test-offer-read-consignment';
+process.state = 'REQUESTED';
+process.dateCreated = new Date().toISOString();
+process.dateModified = process.dateCreated;
+process.callbackAddress = 'https://consumer.example/dsp/callback';
+
+console.log(process.consumerPid); // consumer-process-id
+console.log(process.state); // REQUESTED
+```

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -66,7 +66,7 @@ The key used when registering the callback.
 
 ### negotiateAgreement()
 
-> **negotiateAgreement**(`offerId`, `providerEndpoint`, `publicOrigin`, `trustPayload`): `Promise`\<\{ `negotiationId`: `string`; \}\>
+> **negotiateAgreement**(`datasetId`, `offerId`, `providerEndpoint`, `publicOrigin`, `trustPayload`): `Promise`\<\{ `negotiationId`: `string`; \}\>
 
 Negotiate a contract agreement with a provider.
 Implements DSP Contract Negotiation Protocol.
@@ -81,6 +81,12 @@ DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/20
 
 #### Parameters
 
+##### datasetId
+
+`string`
+
+The dataset ID from the provider's catalog.
+
 ##### offerId
 
 `string`

package/docs/reference/variables/DataspaceContexts.md

@@ -9,3 +9,5 @@ The contexts related to Dataspace
 ### JsonSchemaNamespace
 
 > `readonly` **JsonSchemaNamespace**: `"https://schema.twindev.org/dataspace/"` = `"https://schema.twindev.org/dataspace/"`
+
+The namespace location of the hosted version of the JSON Schema.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/dataspace-models",
-	"version": "0.0.3-next.17",
-	"description": "Models which define the structure of the Dataspace (Control Plane and Data Plane)",
+	"version": "0.0.3-next.19",
+	"description": "Defines shared entities, interfaces, and data types used by control plane and data plane components.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/dataspace.git",