@twin.org/dataspace-control-plane-service 0.0.3-next.32 → 0.0.3-next.34

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

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceControlPlaneServiceConfig } from \"./IDataspaceControlPlaneServiceConfig.js\";\n\n/**\n * Dataspace Control Plane service constructor options.\n */\nexport interface IDataspaceControlPlaneServiceConstructorOptions {\n\t/**\n\t * Policy Administration Point component type.\n\t * Used for Agreement lookup and validation during Transfer Process initiation.\n\t * @default policy-administration-point\n\t */\n\tpolicyAdministrationPointComponentType?: string;\n\n\t/**\n\t * Policy Negotiation Point component type.\n\t * Used for contract negotiation to create agreements before transfer processes.\n\t * @default policy-negotiation-point\n\t */\n\tpolicyNegotiationPointComponentType?: string;\n\n\t/**\n\t * Policy Negotiation Admin Point component type.\n\t * Used for querying negotiation history.\n\t * @default policy-negotiation-admin-point\n\t */\n\tpolicyNegotiationAdminPointComponentType?: string;\n\n\t/**\n\t * Federated Catalogue component type.\n\t * Used for dataset validation during Transfer Process initiation.\n\t * Validates that Agreements reference valid catalog datasets.\n\t * @default federated-catalogue\n\t */\n\tfederatedCatalogueComponentType?: string;\n\n\t/**\n\t * Logging component type.\n\t * @default logging\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * Identity component type (for token signing/verification).\n\t * @default identity\n\t */\n\tidentityComponentType?: string;\n\n\t/**\n\t * Identity Authentication component type (for token validation).\n\t * @default identity-authentication\n\t */\n\tidentityAuthenticationComponentType?: string;\n\n\t/**\n\t * Trust component type for trust verification.\n\t * Used to verify JWT/VC tokens and extract identity information.\n\t * @default trust\n\t */\n\ttrustComponentType?: string;\n\n\t/**\n\t * Entity storage type for Transfer Process entities.\n\t * Used to persist transfer state for the consumerPid flow.\n\t * Must match the Data Plane's transferProcessEntityStorageType for shared storage.\n\t * @default transfer-process\n\t */\n\ttransferProcessEntityStorageType?: string;\n\n\t/**\n\t * Entity storage type for Dataspace App Dataset entities.\n\t * @default dataspace-app-dataset\n\t */\n\tdataspaceAppDatasetEntityStorageType?: string;\n\n\t/**\n\t * Task scheduler component type for periodic cleanup of stalled negotiations.\n\t * @default task-scheduler\n\t */\n\ttaskSchedulerComponentType?: string;\n\n\t/**\n\t * Data Plane component type, used to invoke push subscription lifecycle methods.\n\t * @default dataspace-data-plane\n\t */\n\tdataPlaneComponentType?: string;\n\n\t/**\n\t * URL Transformer component type used to encrypt the tenant token into the data-plane.\n\t * @default url-transformer\n\t */\n\turlTransformerComponentType?: string;\n\n\t/**\n\t * The configuration of the Dataspace Control Plane Service.\n\t */\n\tconfig?: IDataspaceControlPlaneServiceConfig;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneServiceConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IDataspaceControlPlaneServiceConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IDataspaceControlPlaneServiceConfig } from \"./IDataspaceControlPlaneServiceConfig.js\";\n\n/**\n * Dataspace Control Plane service constructor options.\n */\nexport interface IDataspaceControlPlaneServiceConstructorOptions {\n\t/**\n\t * Policy Administration Point component type.\n\t * Used for Agreement lookup and validation during Transfer Process initiation.\n\t * @default policy-administration-point\n\t */\n\tpolicyAdministrationPointComponentType?: string;\n\n\t/**\n\t * Policy Negotiation Point component type.\n\t * Used for contract negotiation to create agreements before transfer processes.\n\t * @default policy-negotiation-point\n\t */\n\tpolicyNegotiationPointComponentType?: string;\n\n\t/**\n\t * Policy Negotiation Admin Point component type.\n\t * Used for querying negotiation history.\n\t * @default policy-negotiation-admin-point\n\t */\n\tpolicyNegotiationAdminPointComponentType?: string;\n\n\t/**\n\t * Federated Catalogue component type.\n\t * Used for dataset validation during Transfer Process initiation.\n\t * Validates that Agreements reference valid catalog datasets.\n\t * @default federated-catalogue\n\t */\n\tfederatedCatalogueComponentType?: string;\n\n\t/**\n\t * Logging component type.\n\t * @default logging\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * Identity component type (for token signing/verification).\n\t * @default identity\n\t */\n\tidentityComponentType?: string;\n\n\t/**\n\t * Identity Authentication component type (for token validation).\n\t * @default identity-authentication\n\t */\n\tidentityAuthenticationComponentType?: string;\n\n\t/**\n\t * Trust component type for trust verification.\n\t * Used to verify JWT/VC tokens and extract identity information.\n\t * @default trust\n\t */\n\ttrustComponentType?: string;\n\n\t/**\n\t * Entity storage type for Transfer Process entities.\n\t * Used to persist transfer state for the consumerPid flow.\n\t * Must match the Data Plane's transferProcessEntityStorageType for shared storage.\n\t * @default transfer-process\n\t */\n\ttransferProcessEntityStorageType?: string;\n\n\t/**\n\t * Entity storage type for Dataspace App Dataset entities.\n\t * @default dataspace-app-dataset\n\t */\n\tdataspaceAppDatasetEntityStorageType?: string;\n\n\t/**\n\t * Task scheduler component type for periodic cleanup of stalled negotiations.\n\t * @default task-scheduler\n\t */\n\ttaskSchedulerComponentType?: string;\n\n\t/**\n\t * Data Plane component type, used to invoke push subscription lifecycle methods.\n\t * @default dataspace-data-plane\n\t */\n\tdataPlaneComponentType?: string;\n\n\t/**\n\t * URL Transformer component type used to encrypt the tenant token into the data-plane.\n\t * @default url-transformer\n\t */\n\turlTransformerComponentType?: string;\n\n\t/**\n\t * Remote control plane component type used to make outbound DSP transfer requests.\n\t * Created dynamically via ComponentFactory.create() with the provider endpoint as config.\n\t * @default dataspace-control-plane-rest-client\n\t */\n\tremoteControlPlaneComponentType?: string;\n\n\t/**\n\t * The configuration of the Dataspace Control Plane Service.\n\t */\n\tconfig?: IDataspaceControlPlaneServiceConfig;\n}\n"]}

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -1,4 +1,4 @@
-import { type IDataspaceControlPlaneComponent, type IDataspaceControlPlaneResolverComponent, type INegotiationCallback, type IDataspaceAppDataset, type ITransferContext } from "@twin.org/dataspace-models";
+import { type IDataspaceControlPlaneComponent, type IDataspaceControlPlaneResolverComponent, type INegotiationCallback, type ITransferCallback, type IDataspaceAppDataset, type ITransferContext } from "@twin.org/dataspace-models";
 import { type IDataspaceProtocolContractNegotiation, type IDataspaceProtocolContractNegotiationError, type IDataspaceProtocolDataset, type IDataspaceProtocolTransferCompletionMessage, type IDataspaceProtocolTransferError, type IDataspaceProtocolTransferProcess, type IDataspaceProtocolTransferRequestMessage, type IDataspaceProtocolTransferStartMessage, type IDataspaceProtocolTransferSuspensionMessage, type IDataspaceProtocolTransferTerminationMessage } from "@twin.org/standards-dataspace-protocol";
 import type { IDataspaceControlPlaneServiceConstructorOptions } from "./models/IDataspaceControlPlaneServiceConstructorOptions.js";
 /**
@@ -35,6 +35,17 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * @param key The key used when registering the callback.
      */
     unregisterNegotiationCallback(key: string): void;
+    /**
+     * Register a callback to receive transfer process state change notifications.
+     * @param key A unique key identifying this callback registration.
+     * @param callback The callback interface to register.
+     */
+    registerTransferCallback(key: string, callback: ITransferCallback): void;
+    /**
+     * Unregister a previously registered transfer callback.
+     * @param key The key used when registering the callback.
+     */
+    unregisterTransferCallback(key: string): void;
     /**
      * The service needs to be started when the application is initialized.
      * Populates the Federated Catalogue with datasets from registered apps
@@ -61,6 +72,28 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * Called by: Consumer when it wants to request a new Transfer Process
      */
     requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Start 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.
+     * @param providerEndpoint The provider's DSP control plane base URL.
+     * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).
+     * @param format The transfer format (e.g. "HttpProxy-PULL", "HttpProxy-PUSH").
+     * @param trustPayload Trust payload for authenticating this call.
+     * @returns The consumerPid of the newly created TransferProcess.
+     *
+     * **Engine configuration requirement:** The outbound call to the provider uses
+     * `ComponentFactory.create(remoteControlPlaneComponentType, { endpoint, pathPrefix })`.
+     * For the runtime `providerEndpoint` to be forwarded correctly, the engine **must** register
+     * the component type (default: `dataspace-control-plane-rest-client`) as a
+     * **multi-instance** component (`isMultiInstance: true` in engine config). A singleton
+     * 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<{
+        consumerPid: string;
+    }>;
     /**
      * Start a Transfer Process.
      * Transitions Transfer Process from REQUESTED to STARTED state or resumes from SUSPENDED state.
@@ -202,4 +235,11 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
      * @returns The internal negotiation callback.
      */
     private createInternalCallback;
+    /**
+     * Creates the internal ITransferCallback that fans out to all registered transfer callbacks.
+     * Errors thrown by individual callbacks are logged and swallowed so they cannot affect
+     * the DSP protocol state machine or other registrants.
+     * @returns The internal transfer callback.
+     */
+    private createInternalTransferCallback;
 }

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

@@ -76,6 +76,12 @@ export interface IDataspaceControlPlaneServiceConstructorOptions {
      * @default url-transformer
      */
     urlTransformerComponentType?: string;
+    /**
+     * Remote control plane component type used to make outbound DSP transfer requests.
+     * Created dynamically via ComponentFactory.create() with the provider endpoint as config.
+     * @default dataspace-control-plane-rest-client
+     */
+    remoteControlPlaneComponentType?: string;
     /**
      * The configuration of the Dataspace Control Plane Service.
      */

package/docs/changelog.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [0.0.3-next.34](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.33...dataspace-control-plane-service-v0.0.3-next.34) (2026-06-01)
+
+
+### Features
+
+* add consumer transfer callbacks and startDataTransfer convenience method ([#151](https://github.com/iotaledger/twin-dataspace/issues/151)) ([0ab66c3](https://github.com/iotaledger/twin-dataspace/commit/0ab66c3636fd1f98f89baca1e99764d77c6f91d9))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.33 to 0.0.3-next.34
+
+## [0.0.3-next.33](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.32...dataspace-control-plane-service-v0.0.3-next.33) (2026-06-01)
+
+
+### Features
+
+* rename completed callback ([#147](https://github.com/iotaledger/twin-dataspace/issues/147)) ([f62baad](https://github.com/iotaledger/twin-dataspace/commit/f62baad0ff444e2913439b12dcd06d20c9a4f6a4))
+
+
+### Bug Fixes
+
+* implement missing trust check on negotiateAgreement ([#136](https://github.com/iotaledger/twin-dataspace/issues/136)) ([a3589c2](https://github.com/iotaledger/twin-dataspace/commit/a3589c279476d5450b68ea7c2790be7e3125bfe2))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.32 to 0.0.3-next.33
+
 ## [0.0.3-next.32](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.31...dataspace-control-plane-service-v0.0.3-next.32) (2026-05-29)
 
 

package/docs/reference/classes/DataspaceControlPlaneService.md

@@ -114,6 +114,60 @@ The key used when registering the callback.
 
 ***
 
+### registerTransferCallback() {#registertransfercallback}
+
+> **registerTransferCallback**(`key`, `callback`): `void`
+
+Register a callback to receive transfer process state change notifications.
+
+#### Parameters
+
+##### key
+
+`string`
+
+A unique key identifying this callback registration.
+
+##### callback
+
+`ITransferCallback`
+
+The callback interface to register.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+`IDataspaceControlPlaneComponent.registerTransferCallback`
+
+***
+
+### unregisterTransferCallback() {#unregistertransfercallback}
+
+> **unregisterTransferCallback**(`key`): `void`
+
+Unregister a previously registered transfer callback.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key used when registering the callback.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+`IDataspaceControlPlaneComponent.unregisterTransferCallback`
+
+***
+
 ### start() {#start}
 
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
@@ -203,6 +257,66 @@ Called by: Consumer when it wants to request a new Transfer Process
 
 ***
 
+### startDataTransfer() {#startdatatransfer}
+
+> **startDataTransfer**(`agreementId`, `providerEndpoint`, `publicOrigin`, `format`, `trustPayload`): `Promise`\<\{ `consumerPid`: `string`; \}\>
+
+Start 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.
+
+#### Parameters
+
+##### agreementId
+
+`string`
+
+The finalized agreement ID from contract negotiation.
+
+##### providerEndpoint
+
+`string`
+
+The provider's DSP control plane base URL.
+
+##### publicOrigin
+
+`string`
+
+The public origin URL of this control plane (used as callbackAddress).
+
+##### format
+
+`string`
+
+The transfer format (e.g. "HttpProxy-PULL", "HttpProxy-PUSH").
+
+##### trustPayload
+
+`unknown`
+
+Trust payload for authenticating this call.
+
+#### Returns
+
+`Promise`\<\{ `consumerPid`: `string`; \}\>
+
+The consumerPid of the newly created TransferProcess.
+
+**Engine configuration requirement:** The outbound call to the provider uses
+`ComponentFactory.create(remoteControlPlaneComponentType, { endpoint, pathPrefix })`.
+For the runtime `providerEndpoint` to be forwarded correctly, the engine **must** register
+the component type (default: `dataspace-control-plane-rest-client`) as a
+**multi-instance** component (`isMultiInstance: true` in engine config). A singleton
+registration ignores the runtime `endpoint` arg and silently POSTs to its
+static endpoint instead.
+
+#### Implementation of
+
+`IDataspaceControlPlaneComponent.startDataTransfer`
+
+***
+
 ### startTransfer() {#starttransfer}
 
 > **startTransfer**(`message`, `publicOrigin`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferStartMessage`\>

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConstructorOptions.md

@@ -194,6 +194,21 @@ url-transformer
 
 ***
 
+### remoteControlPlaneComponentType? {#remotecontrolplanecomponenttype}
+
+> `optional` **remoteControlPlaneComponentType?**: `string`
+
+Remote control plane component type used to make outbound DSP transfer requests.
+Created dynamically via ComponentFactory.create() with the provider endpoint as config.
+
+#### Default
+
+```ts
+dataspace-control-plane-rest-client
+```
+
+***
+
 ### config? {#config}
 
 > `optional` **config?**: [`IDataspaceControlPlaneServiceConfig`](IDataspaceControlPlaneServiceConfig.md)

package/locales/en.json

@@ -22,7 +22,9 @@
 			"getNegotiationHistory": "Retrieving negotiation history",
 			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
 			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})",
-			"pushTransferStarted": "PUSH transfer started (consumerPid: {consumerPid}, providerPid: {providerPid}, endpoint: {endpoint})"
+			"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})"
 		},
 		"dataspaceControlPlanePolicyRequester": {
 			"offerReceived": "Offer received from provider (negotiationId: {negotiationId}, offerId: {offerId})",
@@ -84,6 +86,10 @@
 			"datasetHasNoValidOffers": "Dataset \"{datasetId}\" has no valid ODRL offer objects. Cannot negotiate without a valid offer.",
 			"offerNotFoundInDataset": "Offer \"{offerId}\" not found in dataset \"{datasetId}\". Available offers: {availableOffers}",
 			"negotiationCallbackError": "Negotiation callback \"{key}\" threw an error during {method} for negotiation {negotiationId}",
+			"transferCallbackError": "Transfer callback \"{key}\" threw an error during {method} for consumerPid {consumerPid}",
+			"transferRequestRejectedByProvider": "Provider rejected transfer request for agreement {agreementId} at {providerEndpoint} (code: {code})",
+			"providerPidMissingInResponse": "Provider accepted transfer request for {consumerPid} but returned no providerPid",
+			"unsupportedTransferFormat": "Transfer format \"{format}\" is not supported. Supported formats: {supported}",
 			"catalogDatasetMissingId": "Catalog dataset is missing a required @id identifier",
 			"providerIdentityMissing": "Provider identity (DID) is required to sign data access tokens but was not set on the Transfer Process",
 			"callerNotAuthorizedForAgreement": "The caller's verified identity does not match the agreement assignee (consumer)",

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.0.3-next.32",
+	"version": "0.0.3-next.34",
 	"description": "Implements agreement negotiation and transfer process lifecycle management for control plane operations.",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/iotaledger/dataspace.git",
+		"url": "git+https://github.com/iotaledger/twin-dataspace.git",
 		"directory": "packages/dataspace-control-plane-service"
 	},
 	"author": "martyn.janes@iota.org",
@@ -19,7 +19,7 @@
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
-		"@twin.org/dataspace-models": "0.0.3-next.32",
+		"@twin.org/dataspace-models": "0.0.3-next.34",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",
@@ -67,7 +67,7 @@
 		"business-logic"
 	],
 	"bugs": {
-		"url": "git+https://github.com/iotaledger/dataspace/issues"
+		"url": "git+https://github.com/iotaledger/twin-dataspace/issues"
 	},
 	"homepage": "https://twindev.org"
 }