@twin.org/dataspace-models 0.0.3-next.45 → 0.0.3-next.47

package/dist/es/entities/transferProcess.js

@@ -45,6 +45,12 @@ let TransferProcess = class TransferProcess {
      * Provider identity (DID or URI).
      */
     providerIdentity;
+    /**
+     * This node's role in the transfer, captured at write time so state transitions and async delivery
+     * can tell which party we are without inferring it from the matched PID (consumerPid is the primary
+     * key on both nodes). Optional for back-compat with records written before this field existed.
+     */
+    localRole;
     /**
      * Data format from the Dataset Distribution.
      */
@@ -110,6 +116,10 @@ __decorate([
     property({ type: "string", optional: true }),
     __metadata("design:type", String)
 ], TransferProcess.prototype, "providerIdentity", void 0);
+__decorate([
+    property({ type: "string", optional: true }),
+    __metadata("design:type", String)
+], TransferProcess.prototype, "localRole", void 0);
 __decorate([
     property({ type: "string", optional: true }),
     __metadata("design:type", String)

package/dist/es/entities/transferProcess.js.map

@@ -1 +1 @@
-{"version":3,"file":"transferProcess.js","sourceRoot":"","sources":["../../../src/entities/transferProcess.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAOnE;;;GAGG;AAEI,IAAM,eAAe,GAArB,MAAM,eAAe;IAC3B;;;OAGG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,EAAE,CAAU;IAEnB;;;OAGG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,WAAW,CAAU;IAE5B;;;OAGG;IAEI,KAAK,CAA6C;IAEzD;;OAEG;IAEI,SAAS,CAAU;IAE1B;;OAEG;IAEI,OAAO,CAAU;IAExB;;OAEG;IAEI,gBAAgB,CAAU;IAEjC;;OAEG;IAEI,gBAAgB,CAAU;IAEjC;;OAEG;IAEI,MAAM,CAAU;IAEvB;;OAEG;IAEI,eAAe,CAAU;IAEhC;;OAEG;IAEI,oBAAoB,CAAU;IAErC;;OAEG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,YAAY,CAAU;IAE7B;;OAEG;IAEI,QAAQ,CAA8B;IAE7C;;OAEG;IAEI,WAAW,CAAiC;CACnD,CAAA;AA7FO;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;oDAClB;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;2CACV;AAOZ;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;;oDACpB;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;oDACD;AAOrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;8CAC4B;AAMlD;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;kDACH;AAMnB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;gDACL;AAMjB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;yDACZ;AAM1B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;yDACZ;AAM1B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;+CACtB;AAMhB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;wDACb;AAMzB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;6DACQ;AAM9B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,CAAC,UAAU,EAAE,CAAC;;oDAC/D;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;qDACrB;AAMtB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;iDACf;AAMtC;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;oDACV;AAlGvC,eAAe;IAD3B,MAAM,EAAE;GACI,eAAe,CAmG3B","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property, SortDirection } from \"@twin.org/entity\";\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress,\n\tIDataspaceProtocolPolicy\n} from \"@twin.org/standards-dataspace-protocol\";\n\n/**\n * Transfer Process for shared storage between Control Plane and Data Plane.\n * This entity is the persistent representation of ITransferProcess.\n */\n@entity()\nexport class TransferProcess {\n\t/**\n\t * The consumer PID is the primary key.\n\t * Used for direct lookup by consumerPid.\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic consumerPid!: string;\n\n\t/**\n\t * Internal UUID for storage (secondary key for providerPid lookup).\n\t */\n\t@property({ type: \"string\" })\n\tpublic id!: string;\n\n\t/**\n\t * Provider Process ID from the DSP protocol.\n\t * Indexed for lookup by providerPid.\n\t */\n\t@property({ type: \"string\", isSecondary: true })\n\tpublic providerPid!: string;\n\n\t/**\n\t * Agreement ID linking to the rights-management Agreement.\n\t */\n\t@property({ type: \"string\" })\n\tpublic agreementId!: string;\n\n\t/**\n\t * Transfer Process state from the DSP protocol.\n\t * One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.\n\t */\n\t@property({ type: \"string\" })\n\tpublic state!: DataspaceProtocolTransferProcessStateType;\n\n\t/**\n\t * Dataset ID for DSC resolution.\n\t */\n\t@property({ type: \"string\" })\n\tpublic datasetId!: string;\n\n\t/**\n\t * Offer ID from the original Catalog offer.\n\t */\n\t@property({ type: \"string\" })\n\tpublic offerId!: string;\n\n\t/**\n\t * Consumer identity (DID or URI).\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic consumerIdentity?: string;\n\n\t/**\n\t * Provider identity (DID or URI).\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic providerIdentity?: string;\n\n\t/**\n\t * Data format from the Dataset Distribution.\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic format?: string;\n\n\t/**\n\t * Callback address for Consumer notifications.\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic callbackAddress?: string;\n\n\t/**\n\t * The organization that owns this transfer process, captured from the request context at write time.\n\t */\n\t@property({ type: \"string\" })\n\tpublic organizationIdentity!: string;\n\n\t/**\n\t * Creation timestamp (ISO string format).\n\t */\n\t@property({ type: \"string\", format: \"date-time\", sortDirection: SortDirection.Descending })\n\tpublic dateCreated!: string;\n\n\t/**\n\t * Last update timestamp (ISO string format).\n\t */\n\t@property({ type: \"string\", format: \"date-time\" })\n\tpublic dateModified!: string;\n\n\t/**\n\t * Policies from the Agreement (stored as JSON).\n\t */\n\t@property({ type: \"array\", format: \"json\", optional: true })\n\tpublic policies?: IDataspaceProtocolPolicy[];\n\n\t/**\n\t * Data address for push mode transfers (stored as JSON).\n\t */\n\t@property({ type: \"object\", format: \"json\", optional: true })\n\tpublic dataAddress?: IDataspaceProtocolDataAddress;\n}\n"]}
+{"version":3,"file":"transferProcess.js","sourceRoot":"","sources":["../../../src/entities/transferProcess.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQnE;;;GAGG;AAEI,IAAM,eAAe,GAArB,MAAM,eAAe;IAC3B;;;OAGG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,EAAE,CAAU;IAEnB;;;OAGG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,WAAW,CAAU;IAE5B;;;OAGG;IAEI,KAAK,CAA6C;IAEzD;;OAEG;IAEI,SAAS,CAAU;IAE1B;;OAEG;IAEI,OAAO,CAAU;IAExB;;OAEG;IAEI,gBAAgB,CAAU;IAEjC;;OAEG;IAEI,gBAAgB,CAAU;IAEjC;;;;OAIG;IAEI,SAAS,CAAuB;IAEvC;;OAEG;IAEI,MAAM,CAAU;IAEvB;;OAEG;IAEI,eAAe,CAAU;IAEhC;;OAEG;IAEI,oBAAoB,CAAU;IAErC;;OAEG;IAEI,WAAW,CAAU;IAE5B;;OAEG;IAEI,YAAY,CAAU;IAE7B;;OAEG;IAEI,QAAQ,CAA8B;IAE7C;;OAEG;IAEI,WAAW,CAAiC;CACnD,CAAA;AArGO;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;;oDAClB;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;2CACV;AAOZ;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;;oDACpB;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;oDACD;AAOrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;8CAC4B;AAMlD;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;kDACH;AAMnB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;gDACL;AAMjB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;yDACZ;AAM1B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;yDACZ;AAQ1B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;kDACN;AAMhC;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;+CACtB;AAMhB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;wDACb;AAMzB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;;6DACQ;AAM9B;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,CAAC,UAAU,EAAE,CAAC;;oDAC/D;AAMrB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;;qDACrB;AAMtB;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;iDACf;AAMtC;IADN,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;oDACV;AA1GvC,eAAe;IAD3B,MAAM,EAAE;GACI,eAAe,CA2G3B","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { entity, property, SortDirection } from \"@twin.org/entity\";\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress,\n\tIDataspaceProtocolPolicy\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { TransferProcessRole } from \"../models/controlPlane/transferProcessRole.js\";\n\n/**\n * Transfer Process for shared storage between Control Plane and Data Plane.\n * This entity is the persistent representation of ITransferProcess.\n */\n@entity()\nexport class TransferProcess {\n\t/**\n\t * The consumer PID is the primary key.\n\t * Used for direct lookup by consumerPid.\n\t */\n\t@property({ type: \"string\", isPrimary: true })\n\tpublic consumerPid!: string;\n\n\t/**\n\t * Internal UUID for storage (secondary key for providerPid lookup).\n\t */\n\t@property({ type: \"string\" })\n\tpublic id!: string;\n\n\t/**\n\t * Provider Process ID from the DSP protocol.\n\t * Indexed for lookup by providerPid.\n\t */\n\t@property({ type: \"string\", isSecondary: true })\n\tpublic providerPid!: string;\n\n\t/**\n\t * Agreement ID linking to the rights-management Agreement.\n\t */\n\t@property({ type: \"string\" })\n\tpublic agreementId!: string;\n\n\t/**\n\t * Transfer Process state from the DSP protocol.\n\t * One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.\n\t */\n\t@property({ type: \"string\" })\n\tpublic state!: DataspaceProtocolTransferProcessStateType;\n\n\t/**\n\t * Dataset ID for DSC resolution.\n\t */\n\t@property({ type: \"string\" })\n\tpublic datasetId!: string;\n\n\t/**\n\t * Offer ID from the original Catalog offer.\n\t */\n\t@property({ type: \"string\" })\n\tpublic offerId!: string;\n\n\t/**\n\t * Consumer identity (DID or URI).\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic consumerIdentity?: string;\n\n\t/**\n\t * Provider identity (DID or URI).\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic providerIdentity?: string;\n\n\t/**\n\t * This node's role in the transfer, captured at write time so state transitions and async delivery\n\t * can tell which party we are without inferring it from the matched PID (consumerPid is the primary\n\t * key on both nodes). Optional for back-compat with records written before this field existed.\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic localRole?: TransferProcessRole;\n\n\t/**\n\t * Data format from the Dataset Distribution.\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic format?: string;\n\n\t/**\n\t * Callback address for Consumer notifications.\n\t */\n\t@property({ type: \"string\", optional: true })\n\tpublic callbackAddress?: string;\n\n\t/**\n\t * The organization that owns this transfer process, captured from the request context at write time.\n\t */\n\t@property({ type: \"string\" })\n\tpublic organizationIdentity!: string;\n\n\t/**\n\t * Creation timestamp (ISO string format).\n\t */\n\t@property({ type: \"string\", format: \"date-time\", sortDirection: SortDirection.Descending })\n\tpublic dateCreated!: string;\n\n\t/**\n\t * Last update timestamp (ISO string format).\n\t */\n\t@property({ type: \"string\", format: \"date-time\" })\n\tpublic dateModified!: string;\n\n\t/**\n\t * Policies from the Agreement (stored as JSON).\n\t */\n\t@property({ type: \"array\", format: \"json\", optional: true })\n\tpublic policies?: IDataspaceProtocolPolicy[];\n\n\t/**\n\t * Data address for push mode transfers (stored as JSON).\n\t */\n\t@property({ type: \"object\", format: \"json\", optional: true })\n\tpublic dataAddress?: IDataspaceProtocolDataAddress;\n}\n"]}

package/dist/es/models/api/controlPlane/IRequestTransferRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IRequestTransferRequest.js","sourceRoot":"","sources":["../../../../../src/models/api/controlPlane/IRequestTransferRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceProtocolTransferRequestMessage } from \"@twin.org/standards-dataspace-protocol\";\nimport type { HeaderTypes } from \"@twin.org/web\";\n\n/**\n * API request for requesting a transfer process.\n */\nexport interface IRequestTransferRequest {\n\t/**\n\t * Authorization header containing the Base64-encoded trust payload.\n\t */\n\theaders: {\n\t\t[HeaderTypes.Authorization]: string;\n\t};\n\n\t/**\n\t * Transfer request message (DSP compliant).\n\t */\n\tbody: IDataspaceProtocolTransferRequestMessage;\n}\n"]}
+{"version":3,"file":"IRequestTransferRequest.js","sourceRoot":"","sources":["../../../../../src/models/api/controlPlane/IRequestTransferRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceProtocolTransferRequestMessage } from \"@twin.org/standards-dataspace-protocol\";\nimport type { HeaderTypes } from \"@twin.org/web\";\n\n/**\n * API request for requesting a transfer process.\n */\nexport interface IRequestTransferRequest {\n\t/**\n\t * Authorization header containing the Base64-encoded trust payload.\n\t */\n\theaders: {\n\t\t[HeaderTypes.Authorization]: string;\n\t};\n\n\t/**\n\t * The query parameters of the request.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * When \"true\", the provider immediately starts the requested transfer once it has been created.\n\t\t */\n\t\tautoStart?: string;\n\t};\n\n\t/**\n\t * Transfer request message (DSP compliant).\n\t */\n\tbody: IDataspaceProtocolTransferRequestMessage;\n}\n"]}

package/dist/es/models/controlPlane/IDataspaceControlPlaneComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/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\tIDataspaceProtocolDataset,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDataspaceAppDataset } from \"./IDataspaceAppDataset.js\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\nimport type { ITransferCallback } from \"./ITransferCallback.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 * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\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 * Register a callback to receive transfer process state change notifications.\n\t * Upstream modules register their callback here to be notified when a\n\t * consumer-initiated transfer changes state (STARTED, COMPLETED, SUSPENDED,\n\t * TERMINATED).\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterTransferCallback(key: string, callback: ITransferCallback): void;\n\n\t/**\n\t * Unregister a previously registered transfer callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterTransferCallback(key: string): void;\n\n\t/**\n\t * Start a data transfer as a Consumer.\n\t * High-level convenience wrapper around the DSP Transfer Request protocol.\n\t *\n\t * This method:\n\t * 1. Generates a consumerPid.\n\t * 2. POSTs a TransferRequestMessage to the provider's DSP endpoint.\n\t * 3. Persists a local TransferProcess in REQUESTED state (only if provider accepts).\n\t * 4. Returns the consumerPid immediately.\n\t *\n\t * The caller is notified of subsequent state changes (STARTED, COMPLETED, etc.)\n\t * via the registered ITransferCallback. The transfer moves to STARTED when the\n\t * provider POSTs a TransferStartMessage back to this node's callback address.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * @param agreementId The finalized agreement ID (from contract negotiation).\n\t * @param providerEndpoint The provider's DSP control plane base URL.\n\t * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).\n\t * @param format The transfer format (e.g. \"HttpData-PULL\", \"HttpData-PUSH\").\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns The consumerPid of the newly created TransferProcess.\n\t */\n\tstartDataTransfer(\n\t\tagreementId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\tformat: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ consumerPid: string }>;\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\t// ============================================================================\n\t// DATASET MANAGEMENT\n\t// CRUD over the tenant-scoped dataset records the Control Plane reads at\n\t// start time to populate the federated catalogue.\n\t// ============================================================================\n\n\t/**\n\t * Register an app dataset for a dataspace app, owned by the calling tenant.\n\t * @param id Optional explicit id. If omitted, derived from `dataset[\"@id\"]`\n\t * or generated.\n\t * @param appId The dataspace app this dataset belongs to (matches\n\t * `DataspaceAppFactory` registration name).\n\t * @param dataset The dataset payload (may omit system-stamped fields).\n\t * @returns The resolved dataset id.\n\t */\n\tcreateAppDataset(\n\t\tid: string | undefined,\n\t\tappId: string,\n\t\tdataset: IDataspaceProtocolDataset\n\t): Promise<string>;\n\n\t/**\n\t * Get an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns The stored app dataset record.\n\t */\n\tgetAppDataset(id: string): Promise<IDataspaceAppDataset>;\n\n\t/**\n\t * List the app datasets owned by the calling tenant.\n\t * @param cursor Optional pagination cursor.\n\t * @param limit Optional maximum number of entries to return.\n\t * @returns The stored app datasets and the next-page cursor if more exist.\n\t */\n\tlistAppDatasets(\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tentities: IDataspaceAppDataset[];\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Update an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @param appId The dataspace app this dataset belongs to.\n\t * @param dataset The dataset payload.\n\t * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.\n\t */\n\tupdateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;\n\n\t/**\n\t * Delete an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.\n\t */\n\tdeleteAppDataset(id: string): Promise<void>;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/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\tIDataspaceProtocolDataset,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDataspaceAppDataset } from \"./IDataspaceAppDataset.js\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\nimport type { ITransferCallback } from \"./ITransferCallback.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 * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\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 * Register a callback to receive transfer process state change notifications.\n\t * Upstream modules register their callback here to be notified when a\n\t * consumer-initiated transfer changes state (STARTED, COMPLETED, SUSPENDED,\n\t * TERMINATED).\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterTransferCallback(key: string, callback: ITransferCallback): void;\n\n\t/**\n\t * Unregister a previously registered transfer callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterTransferCallback(key: string): void;\n\n\t/**\n\t * Prepare a data transfer as a Consumer.\n\t * High-level convenience wrapper around the DSP Transfer Request protocol.\n\t *\n\t * This method:\n\t * 1. Generates a consumerPid.\n\t * 2. POSTs a TransferRequestMessage to the provider's DSP endpoint.\n\t * 3. Persists a local TransferProcess in REQUESTED state (only if provider accepts).\n\t * 4. Returns the consumerPid immediately.\n\t *\n\t * The caller is notified of subsequent state changes (STARTED, COMPLETED, etc.)\n\t * via the registered ITransferCallback. The transfer moves to STARTED when the\n\t * provider POSTs a TransferStartMessage back to this node's callback address.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * @param agreementId The finalized agreement ID (from contract negotiation).\n\t * @param providerEndpoint The provider's DSP control plane base URL.\n\t * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).\n\t * @param format The transfer format (e.g. \"HttpData-PULL\", \"HttpData-PUSH\").\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns The consumerPid of the newly created TransferProcess.\n\t */\n\tprepareTransfer(\n\t\tagreementId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\tformat: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ consumerPid: string }>;\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 publicOrigin The public origin of this provider node (resolved server-side by the REST route\n\t * from the hosting component); used to build the data-plane endpoint when auto-starting.\n\t * @param options Request options.\n\t * @param options.autoStart When true, the provider immediately starts the requested transfer; when\n\t * omitted/false the provider start must be triggered explicitly.\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\tpublicOrigin: string,\n\t\toptions: { autoStart?: boolean } | undefined,\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 * Start a Transfer Process as the Provider.\n\t * Implements DSP Transfer Process Protocol.\n\t *\n\t * Builds a DSP TransferStartMessage for a transfer this node already accepted (created in\n\t * REQUESTED state by requestTransfer, or in SUSPENDED state to resume), transitions it to\n\t * STARTED, and POSTs the message to the consumer's callback address. Use this when the\n\t * transfer was requested with autoStart=false and the provider now wants to start (or\n\t * resume) it explicitly.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message\n\t *\n\t * @param pid The Process ID (consumerPid or providerPid) identifying the transfer to start.\n\t * @param publicOrigin The public origin URL of this provider node (used to construct the data plane endpoint for PULL transfers).\n\t * @param trustPayload Trust payload proving the caller is the provider (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\ttransferStarted(\n\t\tpid: string,\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\t// ============================================================================\n\t// DATASET MANAGEMENT\n\t// CRUD over the tenant-scoped dataset records the Control Plane reads at\n\t// start time to populate the federated catalogue.\n\t// ============================================================================\n\n\t/**\n\t * Register an app dataset for a dataspace app, owned by the calling tenant.\n\t * @param id Optional explicit id. If omitted, derived from `dataset[\"@id\"]`\n\t * or generated.\n\t * @param appId The dataspace app this dataset belongs to (matches\n\t * `DataspaceAppFactory` registration name).\n\t * @param dataset The dataset payload (may omit system-stamped fields).\n\t * @returns The resolved dataset id.\n\t */\n\tcreateAppDataset(\n\t\tid: string | undefined,\n\t\tappId: string,\n\t\tdataset: IDataspaceProtocolDataset\n\t): Promise<string>;\n\n\t/**\n\t * Get an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns The stored app dataset record.\n\t */\n\tgetAppDataset(id: string): Promise<IDataspaceAppDataset>;\n\n\t/**\n\t * List the app datasets owned by the calling tenant.\n\t * @param cursor Optional pagination cursor.\n\t * @param limit Optional maximum number of entries to return.\n\t * @returns The stored app datasets and the next-page cursor if more exist.\n\t */\n\tlistAppDatasets(\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tentities: IDataspaceAppDataset[];\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Update an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @param appId The dataspace app this dataset belongs to.\n\t * @param dataset The dataset payload.\n\t * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.\n\t */\n\tupdateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;\n\n\t/**\n\t * Delete an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.\n\t */\n\tdeleteAppDataset(id: string): Promise<void>;\n}\n"]}

package/dist/es/models/controlPlane/ITransferProcess.js.map

@@ -1 +1 @@
-{"version":3,"file":"ITransferProcess.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/ITransferProcess.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress,\n\tIDataspaceProtocolPolicy\n} from \"@twin.org/standards-dataspace-protocol\";\n\n/**\n * Transfer Process for internal storage.\n * Combines DSP protocol fields with internal TWIN fields.\n * This is NOT the DSP wire format (use ITransferProcess from standards for that).\n */\nexport interface ITransferProcess {\n\t/**\n\t * Internal UUID (primary key for entity storage).\n\t */\n\tid: string;\n\n\t// === DSP Protocol fields (public) ===\n\n\t/**\n\t * Consumer Process ID from the DSP protocol.\n\t * Refers to the transfer identifier on the Consumer side.\n\t */\n\tconsumerPid: string;\n\n\t/**\n\t * Provider Process ID from the DSP protocol.\n\t * Refers to the transfer identifier on the Provider side.\n\t */\n\tproviderPid: string;\n\n\t/**\n\t * Transfer Process state from the DSP protocol.\n\t * One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.\n\t */\n\tstate: DataspaceProtocolTransferProcessStateType;\n\n\t// === Internal TWIN fields (NOT in DSP protocol) ===\n\n\t/**\n\t * Agreement ID linking to the rights-management Agreement.\n\t * Used to resolve policies and permissions.\n\t */\n\tagreementId: string;\n\n\t/**\n\t * Dataset ID for DSC resolution.\n\t * Identifies the dataset being transferred.\n\t */\n\tdatasetId: string;\n\n\t/**\n\t * Offer ID from the original Catalog offer.\n\t */\n\tofferId: string;\n\n\t/**\n\t * Policies from the Agreement.\n\t * Used by DSC for runtime policy enforcement.\n\t */\n\tpolicies?: IDataspaceProtocolPolicy[];\n\n\t/**\n\t * Consumer identity (DID or URI).\n\t * Used for auditing and access control.\n\t */\n\tconsumerIdentity?: string;\n\n\t/**\n\t * Provider identity (DID or URI).\n\t * Used for auditing.\n\t */\n\tproviderIdentity?: string;\n\n\t/**\n\t * Callback address for Consumer notifications.\n\t * URI where messages to the Consumer should be sent.\n\t */\n\tcallbackAddress?: string;\n\n\t/**\n\t * The organization that owns this transfer process, captured at write time so async\n\t * delivery tasks and delayed state transitions can re-enter the right organization context.\n\t */\n\torganizationIdentity: string;\n\n\t/**\n\t * Data format from the Dataset Distribution.\n\t * Specified by a Distribution for the Dataset associated with the Agreement.\n\t */\n\tformat?: string;\n\n\t/**\n\t * Data address for consumer-initiated push transfers (HttpData-PUSH).\n\t * Contains the consumer's /inbox endpoint as supplied in the TransferRequestMessage.\n\t * Absent for PULL (HttpData-PULL) and provider-initiated push (HttpData-POST),\n\t * where the consumer deliberately omits a dataAddress.\n\t */\n\tdataAddress?: IDataspaceProtocolDataAddress;\n\n\t/**\n\t * Creation timestamp.\n\t */\n\tdateCreated: Date;\n\n\t/**\n\t * Last update timestamp.\n\t */\n\tdateModified: Date;\n}\n"]}
+{"version":3,"file":"ITransferProcess.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/ITransferProcess.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type {\n\tDataspaceProtocolTransferProcessStateType,\n\tIDataspaceProtocolDataAddress,\n\tIDataspaceProtocolPolicy\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { TransferProcessRole } from \"./transferProcessRole.js\";\n\n/**\n * Transfer Process for internal storage.\n * Combines DSP protocol fields with internal TWIN fields.\n * This is NOT the DSP wire format (use ITransferProcess from standards for that).\n */\nexport interface ITransferProcess {\n\t/**\n\t * Internal UUID (primary key for entity storage).\n\t */\n\tid: string;\n\n\t// === DSP Protocol fields (public) ===\n\n\t/**\n\t * Consumer Process ID from the DSP protocol.\n\t * Refers to the transfer identifier on the Consumer side.\n\t */\n\tconsumerPid: string;\n\n\t/**\n\t * Provider Process ID from the DSP protocol.\n\t * Refers to the transfer identifier on the Provider side.\n\t */\n\tproviderPid: string;\n\n\t/**\n\t * Transfer Process state from the DSP protocol.\n\t * One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.\n\t */\n\tstate: DataspaceProtocolTransferProcessStateType;\n\n\t// === Internal TWIN fields (NOT in DSP protocol) ===\n\n\t/**\n\t * Agreement ID linking to the rights-management Agreement.\n\t * Used to resolve policies and permissions.\n\t */\n\tagreementId: string;\n\n\t/**\n\t * Dataset ID for DSC resolution.\n\t * Identifies the dataset being transferred.\n\t */\n\tdatasetId: string;\n\n\t/**\n\t * Offer ID from the original Catalog offer.\n\t */\n\tofferId: string;\n\n\t/**\n\t * Policies from the Agreement.\n\t * Used by DSC for runtime policy enforcement.\n\t */\n\tpolicies?: IDataspaceProtocolPolicy[];\n\n\t/**\n\t * Consumer identity (DID or URI).\n\t * Used for auditing and access control.\n\t */\n\tconsumerIdentity?: string;\n\n\t/**\n\t * Provider identity (DID or URI).\n\t * Used for auditing.\n\t */\n\tproviderIdentity?: string;\n\n\t/**\n\t * This node's role in the transfer, captured at write time so state transitions and async delivery\n\t * can tell which party we are without inferring it from the matched PID. Optional for back-compat.\n\t */\n\tlocalRole?: TransferProcessRole;\n\n\t/**\n\t * Callback address for Consumer notifications.\n\t * URI where messages to the Consumer should be sent.\n\t */\n\tcallbackAddress?: string;\n\n\t/**\n\t * The organization that owns this transfer process, captured at write time so async\n\t * delivery tasks and delayed state transitions can re-enter the right organization context.\n\t */\n\torganizationIdentity: string;\n\n\t/**\n\t * Data format from the Dataset Distribution.\n\t * Specified by a Distribution for the Dataset associated with the Agreement.\n\t */\n\tformat?: string;\n\n\t/**\n\t * Data address for consumer-initiated push transfers (HttpData-PUSH).\n\t * Contains the consumer's /inbox endpoint as supplied in the TransferRequestMessage.\n\t * Absent for PULL (HttpData-PULL) and provider-initiated push (HttpData-POST),\n\t * where the consumer deliberately omits a dataAddress.\n\t */\n\tdataAddress?: IDataspaceProtocolDataAddress;\n\n\t/**\n\t * Creation timestamp.\n\t */\n\tdateCreated: Date;\n\n\t/**\n\t * Last update timestamp.\n\t */\n\tdateModified: Date;\n}\n"]}

package/dist/types/entities/transferProcess.d.ts

@@ -1,4 +1,5 @@
 import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolDataAddress, IDataspaceProtocolPolicy } from "@twin.org/standards-dataspace-protocol";
+import type { TransferProcessRole } from "../models/controlPlane/transferProcessRole.js";
 /**
  * Transfer Process for shared storage between Control Plane and Data Plane.
  * This entity is the persistent representation of ITransferProcess.
@@ -43,6 +44,12 @@ export declare class TransferProcess {
      * Provider identity (DID or URI).
      */
     providerIdentity?: string;
+    /**
+     * This node's role in the transfer, captured at write time so state transitions and async delivery
+     * can tell which party we are without inferring it from the matched PID (consumerPid is the primary
+     * key on both nodes). Optional for back-compat with records written before this field existed.
+     */
+    localRole?: TransferProcessRole;
     /**
      * Data format from the Dataset Distribution.
      */

package/dist/types/models/api/controlPlane/IRequestTransferRequest.d.ts

@@ -10,6 +10,15 @@ export interface IRequestTransferRequest {
     headers: {
         [HeaderTypes.Authorization]: string;
     };
+    /**
+     * The query parameters of the request.
+     */
+    query?: {
+        /**
+         * When "true", the provider immediately starts the requested transfer once it has been created.
+         */
+        autoStart?: string;
+    };
     /**
      * Transfer request message (DSP compliant).
      */

package/dist/types/models/controlPlane/IDataspaceControlPlaneComponent.d.ts

@@ -106,7 +106,7 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      */
     unregisterTransferCallback(key: string): void;
     /**
-     * Start a data transfer as a Consumer.
+     * Prepare a data transfer as a Consumer.
      * High-level convenience wrapper around the DSP Transfer Request protocol.
      *
      * This method:
@@ -129,7 +129,7 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @param trustPayload Trust payload for authentication.
      * @returns The consumerPid of the newly created TransferProcess.
      */
-    startDataTransfer(agreementId: string, providerEndpoint: string, publicOrigin: string, format: string, trustPayload: unknown): Promise<{
+    prepareTransfer(agreementId: string, providerEndpoint: string, publicOrigin: string, format: string, trustPayload: unknown): Promise<{
         consumerPid: string;
     }>;
     /**
@@ -143,12 +143,19 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      *
      * @param request Transfer request message (DSP compliant) containing agreementId,
      * consumerPid, callbackAddress, and format.
+     * @param publicOrigin The public origin of this provider node (resolved server-side by the REST route
+     * from the hosting component); used to build the data-plane endpoint when auto-starting.
+     * @param options Request options.
+     * @param options.autoStart When true, the provider immediately starts the requested transfer; when
+     * omitted/false the provider start must be triggered explicitly.
      * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
      * The consumer must prove their identity by providing a valid trust payload.
      * @returns Transfer Process (DSP compliant) with state REQUESTED, including
      * both consumerPid and providerPid, or TransferError if the operation fails.
      */
-    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, publicOrigin: string, options: {
+        autoStart?: boolean;
+    } | undefined, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
     /**
      * Start a Transfer Process.
      * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.
@@ -164,6 +171,24 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
      */
     startTransfer(message: IDataspaceProtocolTransferStartMessage, publicOrigin: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;
+    /**
+     * Start a Transfer Process as the Provider.
+     * Implements DSP Transfer Process Protocol.
+     *
+     * Builds a DSP TransferStartMessage for a transfer this node already accepted (created in
+     * REQUESTED state by requestTransfer, or in SUSPENDED state to resume), transitions it to
+     * STARTED, and POSTs the message to the consumer's callback address. Use this when the
+     * transfer was requested with autoStart=false and the provider now wants to start (or
+     * resume) it explicitly.
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message
+     *
+     * @param pid The Process ID (consumerPid or providerPid) identifying the transfer to start.
+     * @param publicOrigin The public origin URL of this provider node (used to construct the data plane endpoint for PULL transfers).
+     * @param trustPayload Trust payload proving the caller is the provider (JWT, VC, etc.).
+     * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
+     */
+    transferStarted(pid: string, publicOrigin: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;
     /**
      * Complete a Transfer Process.
      * Transitions Transfer Process to COMPLETED state.

package/dist/types/models/controlPlane/ITransferProcess.d.ts

@@ -1,4 +1,5 @@
 import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolDataAddress, IDataspaceProtocolPolicy } from "@twin.org/standards-dataspace-protocol";
+import type { TransferProcessRole } from "./transferProcessRole.js";
 /**
  * Transfer Process for internal storage.
  * Combines DSP protocol fields with internal TWIN fields.
@@ -53,6 +54,11 @@ export interface ITransferProcess {
      * Used for auditing.
      */
     providerIdentity?: string;
+    /**
+     * This node's role in the transfer, captured at write time so state transitions and async delivery
+     * can tell which party we are without inferring it from the matched PID. Optional for back-compat.
+     */
+    localRole?: TransferProcessRole;
     /**
      * Callback address for Consumer notifications.
      * URI where messages to the Consumer should be sent.

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.47](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.46...dataspace-models-v0.0.3-next.47) (2026-06-17)
+
+
+### Features
+
+* add transferStarted provider method to start a data transfer ([#206](https://github.com/iotaledger/twin-dataspace/issues/206)) ([3ec2dc8](https://github.com/iotaledger/twin-dataspace/commit/3ec2dc8943c8531cd8d8e4ab07cb970ef7b11090))
+
+## [0.0.3-next.46](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.45...dataspace-models-v0.0.3-next.46) (2026-06-17)
+
+
+### Features
+
+* cross-node transfer callbacks and DataTransferManager auto-start ([#199](https://github.com/iotaledger/twin-dataspace/issues/199)) ([1089aa3](https://github.com/iotaledger/twin-dataspace/commit/1089aa344e3598e382f37a82ca03230c5cf6cacd))
+
 ## [0.0.3-next.45](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.44...dataspace-models-v0.0.3-next.45) (2026-06-17)
 
 

package/docs/reference/classes/TransferProcess.md

@@ -90,6 +90,16 @@ Provider identity (DID or URI).
 
 ***
 
+### localRole? {#localrole}
+
+> `optional` **localRole?**: [`TransferProcessRole`](../type-aliases/TransferProcessRole.md)
+
+This node's role in the transfer, captured at write time so state transitions and async delivery
+can tell which party we are without inferring it from the matched PID (consumerPid is the primary
+key on both nodes). Optional for back-compat with records written before this field existed.
+
+***
+
 ### format? {#format}
 
 > `optional` **format?**: `string`

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -245,11 +245,11 @@ The key used when registering the callback.
 
 ***
 
-### startDataTransfer() {#startdatatransfer}
+### prepareTransfer() {#preparetransfer}
 
-> **startDataTransfer**(`agreementId`, `providerEndpoint`, `publicOrigin`, `format`, `trustPayload`): `Promise`\<\{ `consumerPid`: `string`; \}\>
+> **prepareTransfer**(`agreementId`, `providerEndpoint`, `publicOrigin`, `format`, `trustPayload`): `Promise`\<\{ `consumerPid`: `string`; \}\>
 
-Start a data transfer as a Consumer.
+Prepare a data transfer as a Consumer.
 High-level convenience wrapper around the DSP Transfer Request protocol.
 
 This method:
@@ -307,7 +307,7 @@ The consumerPid of the newly created TransferProcess.
 
 ### requestTransfer() {#requesttransfer}
 
-> **requestTransfer**(`request`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferProcess` \| `IDataspaceProtocolTransferError`\>
+> **requestTransfer**(`request`, `publicOrigin`, `options`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferProcess` \| `IDataspaceProtocolTransferError`\>
 
 Request a Transfer Process.
 Creates a new Transfer Process in REQUESTED state.
@@ -326,6 +326,36 @@ DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#t
 Transfer request message (DSP compliant) containing agreementId,
 consumerPid, callbackAddress, and format.
 
+##### publicOrigin
+
+`string`
+
+The public origin of this provider node (resolved server-side by the REST route
+from the hosting component); used to build the data-plane endpoint when auto-starting.
+
+##### options
+
+\{ `autoStart?`: `boolean`; \} \| `undefined`
+
+Request options.
+
+###### Type Literal
+
+\{ `autoStart?`: `boolean`; \}
+
+Request options.
+
+###### autoStart?
+
+`boolean`
+
+When true, the provider immediately starts the requested transfer; when
+omitted/false the provider start must be triggered explicitly.
+
+***
+
+`undefined`
+
 ##### trustPayload
 
 `unknown`
@@ -382,6 +412,49 @@ Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or T
 
 ***
 
+### transferStarted() {#transferstarted}
+
+> **transferStarted**(`pid`, `publicOrigin`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferStartMessage` \| `IDataspaceProtocolTransferError`\>
+
+Start a Transfer Process as the Provider.
+Implements DSP Transfer Process Protocol.
+
+Builds a DSP TransferStartMessage for a transfer this node already accepted (created in
+REQUESTED state by requestTransfer, or in SUSPENDED state to resume), transitions it to
+STARTED, and POSTs the message to the consumer's callback address. Use this when the
+transfer was requested with autoStart=false and the provider now wants to start (or
+resume) it explicitly.
+
+DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message
+
+#### Parameters
+
+##### pid
+
+`string`
+
+The Process ID (consumerPid or providerPid) identifying the transfer to start.
+
+##### publicOrigin
+
+`string`
+
+The public origin URL of this provider node (used to construct the data plane endpoint for PULL transfers).
+
+##### trustPayload
+
+`unknown`
+
+Trust payload proving the caller is the provider (JWT, VC, etc.).
+
+#### Returns
+
+`Promise`\<`IDataspaceProtocolTransferStartMessage` \| `IDataspaceProtocolTransferError`\>
+
+Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
+
+***
+
 ### completeTransfer() {#completetransfer}
 
 > **completeTransfer**(`message`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferProcess` \| `IDataspaceProtocolTransferError`\>

package/docs/reference/interfaces/IRequestTransferRequest.md

@@ -16,6 +16,20 @@ Authorization header containing the Base64-encoded trust payload.
 
 ***
 
+### query? {#query}
+
+> `optional` **query?**: `object`
+
+The query parameters of the request.
+
+#### autoStart?
+
+> `optional` **autoStart?**: `string`
+
+When "true", the provider immediately starts the requested transfer once it has been created.
+
+***
+
 ### body {#body}
 
 > **body**: `IDataspaceProtocolTransferRequestMessage`

package/docs/reference/interfaces/ITransferProcess.md

@@ -94,6 +94,15 @@ Used for auditing.
 
 ***
 
+### localRole? {#localrole}
+
+> `optional` **localRole?**: [`TransferProcessRole`](../type-aliases/TransferProcessRole.md)
+
+This node's role in the transfer, captured at write time so state transitions and async delivery
+can tell which party we are without inferring it from the matched PID. Optional for back-compat.
+
+***
+
 ### callbackAddress? {#callbackaddress}
 
 > `optional` **callbackAddress?**: `string`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-models",
-	"version": "0.0.3-next.45",
+	"version": "0.0.3-next.47",
 	"description": "Defines shared entities, interfaces, and data types used by control plane and data plane components.",
 	"repository": {
 		"type": "git",