@twin.org/dataspace-models 0.9.1-next.9 → 0.9.2-next.1

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -550,9 +550,59 @@ Transfer Process (DSP compliant) with current state, or TransferError if the ope
 
 ***
 
+### queryDataTransfer() {#querydatatransfer}
+
+> **queryDataTransfer**(`agreementId`, `state`, `cursor`, `trustPayload`): `Promise`\<[`ITransferQueryResult`](ITransferQueryResult.md)\>
+
+Query Transfer Processes by agreement id.
+Lets a caller check whether transfers already exist for an agreement
+(e.g. before initiating a new one) without knowing any process ids.
+
+Role Performed: Consumer / Provider
+Called by: Consumer orchestration before requesting a new transfer, or either
+party inspecting the transfers attached to an agreement on their side.
+
+Results are limited to transfers where the authenticated caller is a party
+(consumer or provider identity). A returned dataAddress is a point-in-time copy;
+if its token has expired the data plane rejects it and a new start is required.
+
+#### Parameters
+
+##### agreementId
+
+`string`
+
+The agreement id to look up transfer processes for.
+
+##### state
+
+`DataspaceProtocolTransferProcessStateType` \| `undefined`
+
+Optional filter to a single transfer process state.
+
+##### cursor
+
+`string` \| `undefined`
+
+Optional pagination cursor from a previous result page.
+
+##### trustPayload
+
+`unknown`
+
+Trust payload containing authorization information (JWT, VC, etc.).
+
+#### Returns
+
+`Promise`\<[`ITransferQueryResult`](ITransferQueryResult.md)\>
+
+The matching transfer processes and a pagination cursor when more pages exist, empty when none match.
+
+***
+
 ### createAppDataset() {#createappdataset}
 
-> **createAppDataset**(`id`, `appId`, `dataset`): `Promise`\<`string`\>
+> **createAppDataset**(`id`, `appId`, `dataset`, `options?`): `Promise`\<`string`\>
 
 Register an app dataset for a dataspace app, owned by the calling tenant.
 
@@ -578,6 +628,17 @@ The dataspace app this dataset belongs to (matches
 
 The dataset payload (may omit system-stamped fields).
 
+##### options?
+
+Optional dataset settings.
+
+###### transferIdleTimeoutMs?
+
+`number`
+
+Optional idle window (ms) overriding the node-level idle
+policy for this dataset's PULL transfers; 0 disables it for this dataset.
+
 #### Returns
 
 `Promise`\<`string`\>
@@ -638,7 +699,7 @@ The stored app datasets and the next-page cursor if more exist.
 
 ### updateAppDataset() {#updateappdataset}
 
-> **updateAppDataset**(`id`, `appId`, `dataset`): `Promise`\<`void`\>
+> **updateAppDataset**(`id`, `appId`, `dataset`, `options?`): `Promise`\<`void`\>
 
 Update an app dataset record owned by the calling tenant.
 
@@ -662,6 +723,17 @@ The dataspace app this dataset belongs to.
 
 The dataset payload.
 
+##### options?
+
+Optional dataset settings.
+
+###### transferIdleTimeoutMs?
+
+`number`
+
+Optional idle window (ms) overriding the node-level idle
+policy for this dataset's PULL transfers; 0 disables it for this dataset.
+
 #### Returns
 
 `Promise`\<`void`\>

package/docs/reference/interfaces/IPushDeliveryPayload.md

@@ -50,7 +50,7 @@ Optional Bearer token for authenticating the push request.
 
 ### agreement {#agreement}
 
-> **agreement**: `IDataspaceProtocolAgreement`
+> **agreement**: `IRightsManagementAgreement`
 
 The ODRL agreement governing the data transfer.
 

package/docs/reference/interfaces/ITransferCallback.md

@@ -174,9 +174,9 @@ Nothing.
 
 > `optional` **onTimeout**(`consumerPid`): `Promise`\<`void`\>
 
-Called when the transfer times out, i.e. the provider did not progress it (it sat in REQUESTED)
-within the configured window. Optional: implement it to be notified specifically of a non-response
-(otherwise the control plane falls back to `onFailed(consumerPid, "transferStalled")`).
+Called when the transfer times out: a consumer-side REQUESTED transfer the provider never
+progressed, or a provider-side STARTED transfer idle beyond the configured window. Optional:
+otherwise the control plane falls back to `onFailed` with the timeout reason.
 
 #### Parameters
 

package/docs/reference/interfaces/ITransferContext.md

@@ -25,7 +25,7 @@ Provider Process ID.
 
 ### agreement {#agreement}
 
-> **agreement**: `IDataspaceProtocolAgreement`
+> **agreement**: `IRightsManagementAgreement`
 
 Agreement associated with this Transfer Process.
 Contains permissions, obligations, and prohibitions that DSC uses for runtime policy enforcement.

package/docs/reference/interfaces/ITransferProcess.md

@@ -69,7 +69,7 @@ Offer ID from the original Catalog offer.
 
 ### policies? {#policies}
 
-> `optional` **policies?**: `IDataspaceProtocolPolicy`[]
+> `optional` **policies?**: `IRightsManagementPolicy`[]
 
 Policies from the Agreement.
 Used by DSC for runtime policy enforcement.
@@ -134,10 +134,8 @@ Specified by a Distribution for the Dataset associated with the Agreement.
 
 > `optional` **dataAddress?**: `IDataspaceProtocolDataAddress`
 
-Data address for consumer-initiated push transfers (HttpData-PUSH).
-Contains the consumer's /inbox endpoint as supplied in the TransferRequestMessage.
-Absent for PULL (HttpData-PULL) and provider-initiated push (HttpData-POST),
-where the consumer deliberately omits a dataAddress.
+Data address for the transfer: the consumer's inbox for PUSH, or the
+provider-built address persisted at start for PULL/POST; may expire while STARTED.
 
 ***
 

package/docs/reference/interfaces/ITransferQueryResult.md

@@ -0,0 +1,19 @@
+# Interface: ITransferQueryResult
+
+Result of querying Transfer Processes by agreement.
+
+## Properties
+
+### transfers {#transfers}
+
+> **transfers**: [`ITransferProcess`](ITransferProcess.md)[]
+
+The transfer processes matching the query, empty when none match.
+
+***
+
+### cursor? {#cursor}
+
+> `optional` **cursor?**: `string`
+
+Pagination cursor for retrieving the next page, omitted when no more results exist.

package/docs/reference/type-aliases/TransferTerminationCode.md

@@ -0,0 +1,5 @@
+# Type Alias: TransferTerminationCode
+
+> **TransferTerminationCode** = *typeof* [`TransferTerminationCode`](../variables/TransferTerminationCode.md)\[keyof *typeof* [`TransferTerminationCode`](../variables/TransferTerminationCode.md)\]
+
+Type for TransferTerminationCode values.

package/docs/reference/variables/TransferTerminationCode.md

@@ -0,0 +1,14 @@
+# Variable: TransferTerminationCode
+
+> `const` **TransferTerminationCode**: `object`
+
+Machine-readable codes set on provider-initiated TransferTerminationMessages
+by the control plane's transfer lifecycle policies.
+
+## Type Declaration
+
+### IdleTimeout {#idletimeout}
+
+> `readonly` **IdleTimeout**: `"idleTimeout"` = `"idleTimeout"`
+
+A Provider-side STARTED transfer had no data-plane activity within the configured idle window.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-models",
-	"version": "0.9.1-next.9",
+	"version": "0.9.2-next.1",
 	"description": "Defines shared entities, interfaces, and data types used by control plane and data plane components.",
 	"repository": {
 		"type": "git",
@@ -11,7 +11,7 @@
 	"license": "Apache-2.0",
 	"type": "module",
 	"engines": {
-		"node": ">=20.0.0"
+		"node": ">=24.0.0"
 	},
 	"dependencies": {
 		"@twin.org/background-task-models": "next",
@@ -20,6 +20,7 @@
 		"@twin.org/data-json-ld": "next",
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next",
+		"@twin.org/rights-management-models": "next",
 		"@twin.org/standards-dataspace-protocol": "next",
 		"@twin.org/standards-schema-org": "next",
 		"@twin.org/standards-w3c-activity-streams": "next",