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

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;
     }>;
     /**
@@ -103,6 +110,20 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * Role Performed: Provider / Consumer
      */
     startTransfer(message: IDataspaceProtocolTransferStartMessage, publicOrigin: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;
+    /**
+     * Start a Transfer Process as the Provider.
+     * Builds a TransferStartMessage for a transfer already accepted by this node (REQUESTED, or
+     * SUSPENDED to resume), transitions it to STARTED, and POSTs the message to the consumer callback.
+     * consumerPid/providerPid/callbackAddress are resolved from the stored record; the call is then
+     * forwarded to startTransfer, the single owner of the start state machine (it verifies the caller is
+     * the provider, builds the dataAddress for PULL, persists STARTED, and delivers to the consumer).
+     * This is the provider-side mirror of prepareTransfer.
+     * @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 build the data plane endpoint for PULL transfers).
+     * @param trustPayload Trust payload proving the caller is the provider.
+     * @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.
      * @param message Transfer completion message (DSP compliant).

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,33 @@
 # Changelog
 
+## [0.0.3-next.47](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.46...dataspace-control-plane-service-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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.46 to 0.0.3-next.47
+
+## [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`
 
 ***
 
@@ -358,6 +388,50 @@ Role Performed: Provider / Consumer
 
 ***
 
+### transferStarted() {#transferstarted}
+
+> **transferStarted**(`pid`, `publicOrigin`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferStartMessage`\>
+
+Start a Transfer Process as the Provider.
+Builds a TransferStartMessage for a transfer already accepted by this node (REQUESTED, or
+SUSPENDED to resume), transitions it to STARTED, and POSTs the message to the consumer callback.
+consumerPid/providerPid/callbackAddress are resolved from the stored record; the call is then
+forwarded to startTransfer, the single owner of the start state machine (it verifies the caller is
+the provider, builds the dataAddress for PULL, persists STARTED, and delivers to the consumer).
+This is the provider-side mirror of prepareTransfer.
+
+#### 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 build the data plane endpoint for PULL transfers).
+
+##### trustPayload
+
+`unknown`
+
+Trust payload proving the caller is the provider.
+
+#### Returns
+
+`Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferStartMessage`\>
+
+Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
+
+#### Implementation of
+
+`IDataspaceControlPlaneComponent.transferStarted`
+
+***
+
 ### completeTransfer() {#completetransfer}
 
 > **completeTransfer**(`message`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>

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,12 +53,17 @@
 	},
 	"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",
 			"transferProcessTerminatedProvider": "Transfer Process \"{providerPid}\" is terminated and cannot be used",
 			"invalidTransferRequest": "Transfer Request does not conform to Dataspace Protocol specification",
 			"invalidStateForStart": "Transfer Process cannot be started: current state is \"{currentState}\", expected REQUESTED or SUSPENDED",
+			"transferStartNotProvider": "Transfer Process cannot be started by this node: it is not acting as the Provider for this transfer (pid: {pid}, role: {role})",
 			"invalidStateForComplete": "Transfer Process cannot be completed: current state is \"{currentState}\", expected STARTED",
 			"invalidStateForSuspend": "Transfer Process cannot be suspended: current state is \"{currentState}\", expected STARTED",
 			"invalidTransferStartMessage": "Transfer Start Message does not conform to Dataspace Protocol specification",

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.47",
 	"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.47",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",