@twin.org/dataspace-control-plane-service 0.0.3-next.45 → 0.0.3-next.46

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

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Dataspace Control Plane service configuration.\n */\nexport interface IDataspaceControlPlaneServiceConfig {\n\t/**\n\t * Override the default trust generator type for token generation.\n\t * If not specified, the default trust generator configured in the trust component will be used.\n\t */\n\toverrideTrustGeneratorType?: string;\n\n\t/**\n\t * Data plane endpoint path for PULL transfers (path only, not full URL).\n\t * Will be combined with the public origin from the hosting component.\n\t *\n\t * REQUIRED if PULL transfers are supported.\n\t * If not specified, PULL transfers will not be available.\n\t *\n\t * Example: \"data-plane/data\" or \"api/data-plane/data\"\n\t */\n\tdataPlanePath?: string;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneServiceConfig.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Dataspace Control Plane service configuration.\n */\nexport interface IDataspaceControlPlaneServiceConfig {\n\t/**\n\t * Override the default trust generator type for token generation.\n\t * If not specified, the default trust generator configured in the trust component will be used.\n\t */\n\toverrideTrustGeneratorType?: string;\n\n\t/**\n\t * Data plane endpoint path for PULL transfers (path only, not full URL).\n\t * Will be combined with the public origin from the hosting component.\n\t *\n\t * REQUIRED if PULL transfers are supported.\n\t * If not specified, PULL transfers will not be available.\n\t *\n\t * Example: \"data-plane/data\" or \"api/data-plane/data\"\n\t */\n\tdataPlanePath?: string;\n\n\t/**\n\t * Control plane callback mount path (path only). Combined with this node's public origin to form the\n\t * consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.\n\t * `<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.\n\t *\n\t * Example: \"dataspace\" or \"api/dataspace\".\n\t */\n\tcallbackPath?: string;\n}\n"]}

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -63,15 +63,22 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * Request a Transfer Process.
      * Creates a new Transfer Process in REQUESTED state.
      * @param request Transfer request message (DSP compliant).
+     * @param publicOrigin The public origin of this provider node, resolved 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 (scheduled
+     * on the next tick); when omitted/false the provider start must be triggered explicitly.
      * @param trustPayload Trust payload containing authorization information (Base64-encoded token).
      * @returns Transfer Process (DSP compliant) with state REQUESTED, or TransferError if the operation fails.
      *
      * Role Performed: Provider
      * Called by: Consumer when it wants to request a new Transfer Process
      */
-    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, publicOrigin: string, options: {
+        autoStart?: boolean;
+    } | undefined, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
     /**
-     * Start a data transfer as a Consumer.
+     * Prepare a data transfer as a Consumer.
      * Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,
      * and (only if the provider accepts) persists a local TransferProcess in REQUESTED state.
      * @param agreementId The finalized agreement ID from contract negotiation.
@@ -89,7 +96,7 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * registration ignores the runtime `endpoint` arg and silently POSTs to its
      * static endpoint instead.
      */
-    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;
     }>;
     /**

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

@@ -17,4 +17,12 @@ export interface IDataspaceControlPlaneServiceConfig {
      * Example: "data-plane/data" or "api/data-plane/data"
      */
     dataPlanePath?: string;
+    /**
+     * Control plane callback mount path (path only). Combined with this node's public origin to form the
+     * consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.
+     * `<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.
+     *
+     * Example: "dataspace" or "api/dataspace".
+     */
+    callbackPath?: string;
 }

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.46](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.45...dataspace-control-plane-service-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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.45 to 0.0.3-next.46
+
 ## [0.0.3-next.45](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.44...dataspace-control-plane-service-v0.0.3-next.45) (2026-06-17)
 
 

package/docs/reference/classes/DataspaceControlPlaneService.md

@@ -223,7 +223,7 @@ A promise that resolves when the cleanup task has been removed.
 
 ### requestTransfer() {#requesttransfer}
 
-> **requestTransfer**(`request`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
+> **requestTransfer**(`request`, `publicOrigin`, `options`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
 Request a Transfer Process.
 Creates a new Transfer Process in REQUESTED state.
@@ -236,6 +236,36 @@ Creates a new Transfer Process in REQUESTED state.
 
 Transfer request message (DSP compliant).
 
+##### publicOrigin
+
+`string`
+
+The public origin of this provider node, resolved 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 (scheduled
+on the next tick); when omitted/false the provider start must be triggered explicitly.
+
+***
+
+`undefined`
+
 ##### trustPayload
 
 `unknown`
@@ -257,11 +287,11 @@ Called by: Consumer when it wants to request a new Transfer Process
 
 ***
 
-### 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.
 Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,
 and (only if the provider accepts) persists a local TransferProcess in REQUESTED state.
 
@@ -313,7 +343,7 @@ static endpoint instead.
 
 #### Implementation of
 
-`IDataspaceControlPlaneComponent.startDataTransfer`
+`IDataspaceControlPlaneComponent.prepareTransfer`
 
 ***
 

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConfig.md

@@ -24,3 +24,15 @@ REQUIRED if PULL transfers are supported.
 If not specified, PULL transfers will not be available.
 
 Example: "data-plane/data" or "api/data-plane/data"
+
+***
+
+### callbackPath? {#callbackpath}
+
+> `optional` **callbackPath?**: `string`
+
+Control plane callback mount path (path only). Combined with this node's public origin to form the
+consumer callbackAddress a provider POSTs DSP transfer messages back to (e.g.
+`<origin>/<callbackPath>/transfers/:pid/start`), with `?organization=` appended for tenant routing.
+
+Example: "dataspace" or "api/dataspace".

package/locales/en.json

@@ -23,8 +23,8 @@
 			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
 			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})",
 			"pushTransferStarted": "PUSH transfer started (consumerPid: {consumerPid}, providerPid: {providerPid}, endpoint: {endpoint})",
-			"startingDataTransfer": "Starting consumer-initiated data transfer (agreementId: {agreementId}, providerEndpoint: {providerEndpoint}, format: {format})",
-			"dataTransferStarted": "Consumer data transfer started successfully (consumerPid: {consumerPid}, providerPid: {providerPid}, agreementId: {agreementId}, format: {format})"
+			"preparingTransfer": "Preparing consumer-initiated data transfer (agreementId: {agreementId}, providerEndpoint: {providerEndpoint}, format: {format})",
+			"transferPrepared": "Consumer data transfer prepared successfully (consumerPid: {consumerPid}, providerPid: {providerPid}, agreementId: {agreementId}, format: {format})"
 		},
 		"dataspaceControlPlanePolicyRequester": {
 			"offerReceived": "Offer received from provider (negotiationId: {negotiationId}, offerId: {offerId})",
@@ -53,6 +53,10 @@
 	},
 	"error": {
 		"dataspaceControlPlaneService": {
+			"transferCallbackRejected": "Consumer rejected a transfer state-change callback (messageKind: {messageKind}, consumerPid: {consumerPid}, providerPid: {providerPid}, callbackAddress: {callbackAddress})",
+			"transferCallbackFailed": "Failed to deliver a transfer state-change callback to the consumer (messageKind: {messageKind}, consumerPid: {consumerPid}, providerPid: {providerPid}, callbackAddress: {callbackAddress})",
+			"autoStartFailed": "Provider auto-start of a requested transfer failed (consumerPid: {consumerPid})",
+			"autoStartPublicOriginMissing": "Cannot auto-start the transfer: this node's public origin could not be resolved; holding the transfer in REQUESTED (consumerPid: {consumerPid})",
 			"transferProcessNotFound": "Transfer Process not found",
 			"pullTransfersNotSupported": "PULL transfers are not supported. Configure dataPlanePath in service configuration to enable PULL transfers.",
 			"transferProcessTerminated": "Transfer Process \"{consumerPid}\" is terminated and cannot be used",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.0.3-next.45",
+	"version": "0.0.3-next.46",
 	"description": "Implements agreement negotiation and transfer process lifecycle management for control plane operations.",
 	"repository": {
 		"type": "git",
@@ -19,7 +19,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
-		"@twin.org/dataspace-models": "0.0.3-next.45",
+		"@twin.org/dataspace-models": "0.0.3-next.46",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",