@twin.org/dataspace-control-plane-service 0.0.3-next.52 → 0.0.3-next.55

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.\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"]}
+{"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.\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\t/**\n\t * Whether the provider immediately starts a transfer once it has been requested. This is a\n\t * provider-side decision only; the consumer cannot request or influence auto-start. When false\n\t * (the default) the transfer stays in REQUESTED until the provider explicitly calls transferStarted.\n\t *\n\t * Defaults to false.\n\t */\n\tautoStartTransfers?: boolean;\n\n\t/**\n\t * How long (ms) a negotiation may sit without progress before the periodic cleanup treats it as\n\t * timed out, removes it, and notifies the registered callbacks (onTimeout, falling back to\n\t * onFailed with reason \"negotiationStalled\"). Requires a task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledNegotiationTimeoutMs?: number;\n\n\t/**\n\t * How long (ms) a consumer-initiated transfer may sit in REQUESTED without the provider progressing\n\t * it before the periodic cleanup treats it as timed out, removes it, and notifies the registered\n\t * transfer callbacks (onTimeout, falling back to onFailed with reason \"transferStalled\"). Requires a\n\t * task-scheduler component to be configured.\n\t *\n\t * Defaults to 1800000 (30 minutes).\n\t */\n\tstalledTransferTimeoutMs?: number;\n}\n"]}

package/dist/types/dataspaceControlPlaneService.d.ts

@@ -61,20 +61,16 @@ export declare class DataspaceControlPlaneService implements IDataspaceControlPl
     stop(nodeLoggingComponentType?: string): Promise<void>;
     /**
      * Request a Transfer Process.
-     * Creates a new Transfer Process in REQUESTED state.
+     * Creates a new Transfer Process in REQUESTED state. Whether it auto-starts is a provider-side
+     * decision (the `autoStartTransfers` service config), never something the consumer can request.
      * @param request Transfer request message (DSP compliant).
-     * @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.
      * @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, options: {
-        autoStart?: boolean;
-    } | undefined, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
     /**
      * Prepare a data transfer as a Consumer.
      * Generates a consumerPid, POSTs a TransferRequestMessage to the provider's DSP endpoint,

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

@@ -25,4 +25,29 @@ export interface IDataspaceControlPlaneServiceConfig {
      * Example: "dataspace" or "api/dataspace".
      */
     callbackPath?: string;
+    /**
+     * Whether the provider immediately starts a transfer once it has been requested. This is a
+     * provider-side decision only; the consumer cannot request or influence auto-start. When false
+     * (the default) the transfer stays in REQUESTED until the provider explicitly calls transferStarted.
+     *
+     * Defaults to false.
+     */
+    autoStartTransfers?: boolean;
+    /**
+     * How long (ms) a negotiation may sit without progress before the periodic cleanup treats it as
+     * timed out, removes it, and notifies the registered callbacks (onTimeout, falling back to
+     * onFailed with reason "negotiationStalled"). Requires a task-scheduler component to be configured.
+     *
+     * Defaults to 1800000 (30 minutes).
+     */
+    stalledNegotiationTimeoutMs?: number;
+    /**
+     * How long (ms) a consumer-initiated transfer may sit in REQUESTED without the provider progressing
+     * it before the periodic cleanup treats it as timed out, removes it, and notifies the registered
+     * transfer callbacks (onTimeout, falling back to onFailed with reason "transferStalled"). Requires a
+     * task-scheduler component to be configured.
+     *
+     * Defaults to 1800000 (30 minutes).
+     */
+    stalledTransferTimeoutMs?: number;
 }

package/docs/changelog.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [0.0.3-next.55](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.54...dataspace-control-plane-service-v0.0.3-next.55) (2026-06-23)
+
+
+### 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))
+* add support for the new federated catalogue trust model ([#179](https://github.com/iotaledger/twin-dataspace/issues/179)) ([0d99a93](https://github.com/iotaledger/twin-dataspace/commit/0d99a9331e259e3efe5250e390fdfb1a2f0983b1))
+* add telemetry metrics to dataspace control and data plane services ([#212](https://github.com/iotaledger/twin-dataspace/issues/212)) ([b5b0248](https://github.com/iotaledger/twin-dataspace/commit/b5b024899ed12c0f639c5d51aefa3e509753eac6))
+* 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))
+* align all config times to ms ([40238d5](https://github.com/iotaledger/twin-dataspace/commit/40238d59a2b45caedc01792b682ce7206815dfd1))
+* 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))
+* docs update ([8b44c7a](https://github.com/iotaledger/twin-dataspace/commit/8b44c7a75afb8d377a6f606616f8a78d58439ab4))
+* endpoint encryption + getDatasetTargets multi-target fix ([#112](https://github.com/iotaledger/twin-dataspace/issues/112)) ([3288941](https://github.com/iotaledger/twin-dataspace/commit/328894113c19c7402f7d00dfa77b6a97ae40ca91))
+* implement DSP push transfer mode ([#109](https://github.com/iotaledger/twin-dataspace/issues/109)) ([71f5fee](https://github.com/iotaledger/twin-dataspace/commit/71f5feec1d92dfec8ed6899c951809818e1bf2a3))
+* improve open-api examples ([1368dbe](https://github.com/iotaledger/twin-dataspace/commit/1368dbed5c36e074b4854942304a19b9ce51e088))
+* improve open-api examples ([44f7350](https://github.com/iotaledger/twin-dataspace/commit/44f7350c625d8d6afdca88b292dd48ef03253412))
+* improve open-api examples ([f065f4b](https://github.com/iotaledger/twin-dataspace/commit/f065f4bd55540041a653ef141c4be29a83c5055e))
+* improve validation ([#82](https://github.com/iotaledger/twin-dataspace/issues/82)) ([8bfaf7b](https://github.com/iotaledger/twin-dataspace/commit/8bfaf7b830f89b63575f8a51ee96bd8ac4da02f4))
+* internalise constant ([9b9b293](https://github.com/iotaledger/twin-dataspace/commit/9b9b2933588ee70811a601bc485b5abaa12bed41))
+* local optimization ([#218](https://github.com/iotaledger/twin-dataspace/issues/218)) ([1daae6b](https://github.com/iotaledger/twin-dataspace/commit/1daae6be8be44abdbe2b4c883c35938506cdd34a))
+* organization identifiers ([#188](https://github.com/iotaledger/twin-dataspace/issues/188)) ([af643d3](https://github.com/iotaledger/twin-dataspace/commit/af643d3bb7f212d6cbb672e362a9e1bbe886d1a5))
+* provider-side transfer auto-start and negotiation/transfer timeout callbacks ([#227](https://github.com/iotaledger/twin-dataspace/issues/227)) ([619d858](https://github.com/iotaledger/twin-dataspace/commit/619d858e8d44e59744dc8a0f73e06be976932b53))
+* remove datasetsHandled method from apps ([9fdc950](https://github.com/iotaledger/twin-dataspace/commit/9fdc95018d38ab49c4a1094642be2ee83ee0e4cd))
+* remove hosting component ([#209](https://github.com/iotaledger/twin-dataspace/issues/209)) ([5e19328](https://github.com/iotaledger/twin-dataspace/commit/5e1932823aa8a0f88f559f096610b9df1f3b8615))
+* rename completed callback ([#147](https://github.com/iotaledger/twin-dataspace/issues/147)) ([f62baad](https://github.com/iotaledger/twin-dataspace/commit/f62baad0ff444e2913439b12dcd06d20c9a4f6a4))
+* resolve DSP transfer flow bugs for cross-node communication ([#76](https://github.com/iotaledger/twin-dataspace/issues/76)) ([506a45c](https://github.com/iotaledger/twin-dataspace/commit/506a45c94e63d5f958b1fc7131adfe452c3e2974))
+* shortcut implicit trust ([#215](https://github.com/iotaledger/twin-dataspace/issues/215)) ([f9bcfea](https://github.com/iotaledger/twin-dataspace/commit/f9bcfeab8f069b62017502833c108b4ee3791414))
+* skip tenant dsp transfer routes ([#97](https://github.com/iotaledger/twin-dataspace/issues/97)) ([2f1ad97](https://github.com/iotaledger/twin-dataspace/commit/2f1ad971bc50ad24bb9f68759fbd4d44527d3d02))
+* types update ([77c338e](https://github.com/iotaledger/twin-dataspace/commit/77c338e9244dcc7e3d597fdb06229513b1f13eac))
+* typescript 6 update ([340f10e](https://github.com/iotaledger/twin-dataspace/commit/340f10e4767f6285c694938944f7e044474f9aaa))
+* unification of the data exchange and the data space connector ([#57](https://github.com/iotaledger/twin-dataspace/issues/57)) ([df2644d](https://github.com/iotaledger/twin-dataspace/commit/df2644d989471e07dadd83d27bef736179e31bf4))
+* update DataspaceTransferFormat names ([2c9d424](https://github.com/iotaledger/twin-dataspace/commit/2c9d424a07b97346faa2124048c4675514d58109))
+* use inbuilt constants ([256bc03](https://github.com/iotaledger/twin-dataspace/commit/256bc0332bf439fcc16022e0b984b9035e9b0100))
+
+
+### Bug Fixes
+
+* avoid compaction of incoming activities ([#77](https://github.com/iotaledger/twin-dataspace/issues/77)) ([ff43d6a](https://github.com/iotaledger/twin-dataspace/commit/ff43d6a3e1563eb9cb185501134b2a53ae88787c))
+* defer startTransfer state mutation until dispatch succeeds ([#162](https://github.com/iotaledger/twin-dataspace/issues/162)) ([6704bbd](https://github.com/iotaledger/twin-dataspace/commit/6704bbd88c10c8b5b37b621b56cf9d8704e00a15))
+* dependency update ([fbff0dd](https://github.com/iotaledger/twin-dataspace/commit/fbff0ddae93d82bd2899001368d7a03b482ce05c))
+* docs and component init ([8557233](https://github.com/iotaledger/twin-dataspace/commit/8557233fb3b8273c5c9a5b580fb43061f8efe47c))
+* gate implicit-trust shortcut on local provider endpoint ([#221](https://github.com/iotaledger/twin-dataspace/issues/221)) ([1167c53](https://github.com/iotaledger/twin-dataspace/commit/1167c53d2a94d4672191d278fed69b4f2d607a3c))
+* handle missing target in catalogue offers during policy derivation check ([#89](https://github.com/iotaledger/twin-dataspace/issues/89)) ([a0e0dbc](https://github.com/iotaledger/twin-dataspace/commit/a0e0dbc8d9111d5d1c43e905249825e5d8d62816))
+* implement missing trust check on negotiateAgreement ([#136](https://github.com/iotaledger/twin-dataspace/issues/136)) ([a3589c2](https://github.com/iotaledger/twin-dataspace/commit/a3589c279476d5450b68ea7c2790be7e3125bfe2))
+* incorrect docs ([754aa8d](https://github.com/iotaledger/twin-dataspace/commit/754aa8d032a5dfefa69072aa460106badfa41ac9))
+* mock pnap ([35f21f8](https://github.com/iotaledger/twin-dataspace/commit/35f21f847d3fb9d2ffcb9191a18835093cd259b9))
+* persist STARTED before setupPushSubscription so data-plane read-back sees the right state ([#168](https://github.com/iotaledger/twin-dataspace/issues/168)) ([6a7c81a](https://github.com/iotaledger/twin-dataspace/commit/6a7c81a1247dcbfbec5d64958328e8b77798be0c))
+* remove inline i18n ([edde37e](https://github.com/iotaledger/twin-dataspace/commit/edde37e90ac397f253f57bc0d306b4bd0c797920))
+* return 409 Conflict on duplicate dataset creation ([#165](https://github.com/iotaledger/twin-dataspace/issues/165)) ([890a2f5](https://github.com/iotaledger/twin-dataspace/commit/890a2f59d881aed4c50f63f57cdec3a4ccfb572d))
+* use async getStore in tests ([739531e](https://github.com/iotaledger/twin-dataspace/commit/739531e1a159f728301835cd39cf06eab7a7bf4a))
+* validate dataset-id ([#138](https://github.com/iotaledger/twin-dataspace/issues/138)) ([92a6a9b](https://github.com/iotaledger/twin-dataspace/commit/92a6a9b7b82c3dd5c652a3685892f7e9156d458b))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.54 to 0.0.3-next.55
+
+## [0.0.3-next.54](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.53...dataspace-control-plane-service-v0.0.3-next.54) (2026-06-23)
+
+
+### Features
+
+* align all config times to ms ([40238d5](https://github.com/iotaledger/twin-dataspace/commit/40238d59a2b45caedc01792b682ce7206815dfd1))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.53 to 0.0.3-next.54
+
+## [0.0.3-next.53](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.52...dataspace-control-plane-service-v0.0.3-next.53) (2026-06-23)
+
+
+### Features
+
+* provider-side transfer auto-start and negotiation/transfer timeout callbacks ([#227](https://github.com/iotaledger/twin-dataspace/issues/227)) ([619d858](https://github.com/iotaledger/twin-dataspace/commit/619d858e8d44e59744dc8a0f73e06be976932b53))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/dataspace-models bumped from 0.0.3-next.52 to 0.0.3-next.53
+
 ## [0.0.3-next.52](https://github.com/iotaledger/twin-dataspace/compare/dataspace-control-plane-service-v0.0.3-next.51...dataspace-control-plane-service-v0.0.3-next.52) (2026-06-21)
 
 

package/docs/reference/classes/DataspaceControlPlaneService.md

@@ -223,10 +223,11 @@ A promise that resolves when the cleanup task has been removed.
 
 ### requestTransfer() {#requesttransfer}
 
-> **requestTransfer**(`request`, `options`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
+> **requestTransfer**(`request`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
 Request a Transfer Process.
-Creates a new Transfer Process in REQUESTED state.
+Creates a new Transfer Process in REQUESTED state. Whether it auto-starts is a provider-side
+decision (the `autoStartTransfers` service config), never something the consumer can request.
 
 #### Parameters
 
@@ -236,29 +237,6 @@ Creates a new Transfer Process in REQUESTED state.
 
 Transfer request message (DSP compliant).
 
-##### 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`

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConfig.md

@@ -36,3 +36,40 @@ 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".
+
+***
+
+### autoStartTransfers? {#autostarttransfers}
+
+> `optional` **autoStartTransfers?**: `boolean`
+
+Whether the provider immediately starts a transfer once it has been requested. This is a
+provider-side decision only; the consumer cannot request or influence auto-start. When false
+(the default) the transfer stays in REQUESTED until the provider explicitly calls transferStarted.
+
+Defaults to false.
+
+***
+
+### stalledNegotiationTimeoutMs? {#stallednegotiationtimeoutms}
+
+> `optional` **stalledNegotiationTimeoutMs?**: `number`
+
+How long (ms) a negotiation may sit without progress before the periodic cleanup treats it as
+timed out, removes it, and notifies the registered callbacks (onTimeout, falling back to
+onFailed with reason "negotiationStalled"). Requires a task-scheduler component to be configured.
+
+Defaults to 1800000 (30 minutes).
+
+***
+
+### stalledTransferTimeoutMs? {#stalledtransfertimeoutms}
+
+> `optional` **stalledTransferTimeoutMs?**: `number`
+
+How long (ms) a consumer-initiated transfer may sit in REQUESTED without the provider progressing
+it before the periodic cleanup treats it as timed out, removes it, and notifies the registered
+transfer callbacks (onTimeout, falling back to onFailed with reason "transferStalled"). Requires a
+task-scheduler component to be configured.
+
+Defaults to 1800000 (30 minutes).

package/locales/en.json

@@ -24,6 +24,7 @@
 			"getNegotiationHistory": "Retrieving negotiation history",
 			"negotiationHistoryRetrieved": "Negotiation history retrieved successfully",
 			"stalledNegotiationsCleanupComplete": "Stalled negotiations cleanup completed (cleanedUp: {cleanedUp})",
+			"stalledTransfersCleanupComplete": "Stalled transfers cleanup completed (cleanedUp: {cleanedUp})",
 			"pushTransferStarted": "PUSH transfer started (consumerPid: {consumerPid}, providerPid: {providerPid}, endpoint: {endpoint})",
 			"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})"
@@ -45,7 +46,8 @@
 	"warn": {
 		"dataspaceControlPlaneService": {
 			"catalogDatasetHasNoOffers": "Dataset has no Offers (odrl:hasPolicy) in Federated Catalogue",
-			"stalledNegotiationCleanedUp": "Stalled negotiation cleaned up (negotiationId: {negotiationId})"
+			"stalledNegotiationCleanedUp": "Stalled negotiation cleaned up (negotiationId: {negotiationId})",
+			"stalledTransferCleanedUp": "Stalled transfer cleaned up (consumerPid: {consumerPid})"
 		},
 		"dataspaceControlPlanePolicyRequester": {
 			"unknownNegotiationFinalized": "Unknown negotiation finalized (negotiationId: {negotiationId})",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.0.3-next.52",
+	"version": "0.0.3-next.55",
 	"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.52",
+		"@twin.org/dataspace-models": "0.0.3-next.55",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",