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

package/docs/reference/classes/TransferRetrieval.md

@@ -0,0 +1,38 @@
+# Class: TransferRetrieval
+
+Records the consumer's first successful retrieval for a transfer.
+Written by the Data Plane, read by the Control Plane's one-shot policy sweep.
+
+## Constructors
+
+### Constructor
+
+> **new TransferRetrieval**(): `TransferRetrieval`
+
+#### Returns
+
+`TransferRetrieval`
+
+## Properties
+
+### consumerPid {#consumerpid}
+
+> **consumerPid**: `string`
+
+The consumer PID of the transfer, primary key.
+
+***
+
+### dateFirstRetrieved {#datefirstretrieved}
+
+> **dateFirstRetrieved**: `string`
+
+When the first successful retrieval happened (ISO string format).
+
+***
+
+### dateLastRetrieved {#datelastretrieved}
+
+> **dateLastRetrieved**: `string`
+
+When the most recent successful retrieval happened (ISO string format).

package/docs/reference/index.md

@@ -4,7 +4,10 @@
 
 - [DataspaceDataTypes](classes/DataspaceDataTypes.md)
 - [DataspaceAppDataset](classes/DataspaceAppDataset.md)
+- [DataspaceAppDatasetV0](classes/DataspaceAppDatasetV0.md)
 - [TransferProcess](classes/TransferProcess.md)
+- [TransferProcessV0](classes/TransferProcessV0.md)
+- [TransferRetrieval](classes/TransferRetrieval.md)
 
 ## Interfaces
 
@@ -65,6 +68,7 @@
 - [ITransferCallback](interfaces/ITransferCallback.md)
 - [ITransferContext](interfaces/ITransferContext.md)
 - [ITransferProcess](interfaces/ITransferProcess.md)
+- [ITransferQueryResult](interfaces/ITransferQueryResult.md)
 - [ITransferContextResponse](interfaces/ITransferContextResponse.md)
 - [IDataspaceDataPlaneComponent](interfaces/IDataspaceDataPlaneComponent.md)
 
@@ -76,6 +80,7 @@
 - [DataRequestType](type-aliases/DataRequestType.md)
 - [DataspaceControlPlaneMetricIds](type-aliases/DataspaceControlPlaneMetricIds.md)
 - [TransferProcessRole](type-aliases/TransferProcessRole.md)
+- [TransferTerminationCode](type-aliases/TransferTerminationCode.md)
 - [DataspaceDataPlaneMetricIds](type-aliases/DataspaceDataPlaneMetricIds.md)
 - [DataspaceContexts](type-aliases/DataspaceContexts.md)
 - [DataspaceTransferFormat](type-aliases/DataspaceTransferFormat.md)
@@ -90,6 +95,7 @@
 - [DataspaceControlPlaneMetricIds](variables/DataspaceControlPlaneMetricIds.md)
 - [DataspaceControlPlaneMetrics](variables/DataspaceControlPlaneMetrics.md)
 - [TransferProcessRole](variables/TransferProcessRole.md)
+- [TransferTerminationCode](variables/TransferTerminationCode.md)
 - [DataspaceDataPlaneMetricIds](variables/DataspaceDataPlaneMetricIds.md)
 - [DataspaceDataPlaneMetrics](variables/DataspaceDataPlaneMetrics.md)
 - [DataspaceContexts](variables/DataspaceContexts.md)

package/docs/reference/interfaces/IAppDatasetCreateRequest.md

@@ -3,7 +3,7 @@
 API request to register an app dataset.
 
 The owning `tenantId` is captured automatically from the request's tenant
-context — callers do not supply it.
+context - callers do not supply it.
 
 ## Properties
 
@@ -34,4 +34,11 @@ registered name in `DataspaceAppFactory` (typically the app's URI).
 > **dataset**: `IDataspaceProtocolDataset`
 
 The dataset payload. System-stamped fields like `dcterms:publisher`
-may be omitted — the Control Plane fills them in at publish time.
+may be omitted - the Control Plane fills them in at publish time.
+
+#### transferIdleTimeoutMs?
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Optional idle window (ms) overriding the node-level idle policy for this
+dataset's PULL transfers; 0 disables it for this dataset.

package/docs/reference/interfaces/IAppDatasetUpdateRequest.md

@@ -36,3 +36,10 @@ update if the tenant wants to retarget the dataset.
 > **dataset**: `IDataspaceProtocolDataset`
 
 The dataset payload.
+
+#### transferIdleTimeoutMs?
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Optional idle window (ms) overriding the node-level idle policy for this
+dataset's PULL transfers; 0 disables it for this dataset.

package/docs/reference/interfaces/IDataspaceAppDataset.md

@@ -28,6 +28,15 @@ The dataset payload.
 
 ***
 
+### transferIdleTimeoutMs? {#transferidletimeoutms}
+
+> `optional` **transferIdleTimeoutMs?**: `number`
+
+Idle window (ms) for this dataset's PULL transfers, overriding the node-level
+providerTransferIdleTimeoutMs; 0 disables the idle policy for this dataset.
+
+***
+
 ### dateCreated {#datecreated}
 
 > **dateCreated**: `string`

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -79,7 +79,7 @@ Otherwise the method returns immediately with a `negotiationId`. The caller is
 notified via the registered INegotiationCallback when the negotiation completes.
 The negotiation follows DSP state machine: REQUESTED → OFFERED → AGREED → VERIFIED → FINALIZED.
 
-The REST client does not support this method and throws a not supported error —
+The REST client does not support this method and throws a not supported error -
 use ComponentFactory.get() for the in-process service.
 
 DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol
@@ -200,7 +200,7 @@ Upstream modules register their callback here to be notified when a
 consumer-initiated transfer changes state (STARTED, COMPLETED, SUSPENDED,
 TERMINATED).
 
-The REST client does not support this method and throws a not supported error —
+The REST client does not support this method and throws a not supported error -
 use ComponentFactory.get() for the in-process service.
 
 #### Parameters
@@ -260,7 +260,7 @@ The caller is notified of subsequent state changes (STARTED, COMPLETED, etc.)
 via the registered ITransferCallback. The transfer moves to STARTED when the
 provider POSTs a TransferStartMessage back to this node's callback address.
 
-The REST client does not support this method and throws a not supported error —
+The REST client does not support this method and throws a not supported error -
 use ComponentFactory.get() for the in-process service.
 
 #### Parameters
@@ -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/IDataspaceDataPlaneComponent.md

@@ -119,7 +119,7 @@ NotFoundError if activity log entry is not known.
 
 #### Throws
 
-UnauthorizedError if trustPayload is absent or the verified identity is not the entry generator.
+UnauthorizedError if trustPayload is absent or the verified identity is not authorised for the entry.
 
 ***
 

package/docs/reference/interfaces/IPushDeliveryPayload.md

@@ -79,7 +79,7 @@ The JSON-LD
 The tenant that owns this push delivery, captured at schedule time from the active
 `ContextIdStore` context (typically from the subscription's `tenantId` field).
 The runner re-establishes this tenant context via `ContextIdStore.run` before invoking
-tenant-scoped operations (PEP, trust signing, vault lookups). Optional — single-tenant
+tenant-scoped operations (PEP, trust signing, vault lookups). Optional - single-tenant
 nodes operate without a tenant context.
 
 ***

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/ITransferProcess.md

@@ -46,7 +46,6 @@ One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.
 > **agreementId**: `string`
 
 Agreement ID linking to the rights-management Agreement.
-Used to resolve policies and permissions.
 
 ***
 
@@ -67,15 +66,6 @@ Offer ID from the original Catalog offer.
 
 ***
 
-### policies? {#policies}
-
-> `optional` **policies?**: `IRightsManagementPolicy`[]
-
-Policies from the Agreement.
-Used by DSC for runtime policy enforcement.
-
-***
-
 ### consumerIdentity? {#consumeridentity}
 
 > `optional` **consumerIdentity?**: `string`
@@ -134,10 +124,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/DataspaceControlPlaneMetricIds.md

@@ -65,3 +65,9 @@ Number of app datasets updated.
 > `readonly` **AppDatasetsDeleted**: `"dcp_app_datasets_deleted"` = `"dcp_app_datasets_deleted"`
 
 Number of app datasets deleted.
+
+### AgreementsSwept {#agreementsswept}
+
+> `readonly` **AgreementsSwept**: `"dcp_agreements_swept"` = `"dcp_agreements_swept"`
+
+Number of agreements removed by the agreement sweep.

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",
+	"version": "0.9.2-next.10",
 	"description": "Defines shared entities, interfaces, and data types used by control plane and data plane components.",
 	"repository": {
 		"type": "git",
@@ -14,19 +14,20 @@
 		"node": ">=24.0.0"
 	},
 	"dependencies": {
-		"@twin.org/background-task-models": "^0.9.1",
-		"@twin.org/core": "^0.9.1",
-		"@twin.org/data-core": "^0.9.1",
-		"@twin.org/data-json-ld": "^0.9.1",
-		"@twin.org/entity": "^0.9.1",
-		"@twin.org/nameof": "^0.9.1",
-		"@twin.org/rights-management-models": "^0.9.1",
-		"@twin.org/standards-dataspace-protocol": "^0.9.1",
-		"@twin.org/standards-schema-org": "^0.9.1",
-		"@twin.org/standards-w3c-activity-streams": "^0.9.1",
-		"@twin.org/standards-w3c-dcat": "^0.9.1",
-		"@twin.org/standards-w3c-odrl": "^0.9.1",
-		"@twin.org/telemetry-models": "^0.9.1"
+		"@twin.org/background-task-models": "next",
+		"@twin.org/core": "next",
+		"@twin.org/data-core": "next",
+		"@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",
+		"@twin.org/standards-w3c-dcat": "next",
+		"@twin.org/standards-w3c-odrl": "next",
+		"@twin.org/telemetry-models": "next",
+		"@twin.org/web": "next"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",