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

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,19 @@
 # Changelog
 
+## [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.53",
 	"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.53",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",