@twin.org/dataspace-control-plane-service 0.0.3-next.18 → 0.0.3-next.20

package/docs/examples.md

@@ -1 +1,144 @@
-# @twin.org/data-exchange-service - Examples
+# Control Plane Service Examples
+
+Use these snippets to negotiate agreements, manage transfer lifecycle, and resolve process identifiers in service components.
+
+## DataspaceControlPlaneService
+
+```typescript
+import { DataspaceControlPlaneService } from '@twin.org/dataspace-control-plane-service';
+
+const service = new DataspaceControlPlaneService({
+  loggingComponentType: 'logging',
+  trustComponentType: 'trust',
+  config: {
+    dataPlanePath: 'dataspace-data-plane'
+  }
+});
+
+console.log(service.className()); // DataspaceControlPlaneService
+```
+
+```typescript
+import { DataspaceControlPlaneService } from '@twin.org/dataspace-control-plane-service';
+
+const service = new DataspaceControlPlaneService();
+
+service.registerNegotiationCallback('supply-chain', {
+  onStateChanged: async (negotiationId, state) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(state); // OFFERED
+  },
+  onCompleted: async (negotiationId, agreementId) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(agreementId); // urn:agreement:001
+  },
+  onFailed: async (negotiationId, reason) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(reason); // negotiationTerminatedByProvider
+  }
+});
+
+await service.start();
+await service.stop();
+service.unregisterNegotiationCallback('supply-chain');
+```
+
+```typescript
+import { DataspaceControlPlaneService } from '@twin.org/dataspace-control-plane-service';
+import type {
+  IDataspaceProtocolAgreement,
+  IDataspaceProtocolTransferRequestMessage,
+  IDataspaceProtocolTransferStartMessage,
+  IDataspaceProtocolTransferCompletionMessage,
+  IDataspaceProtocolTransferSuspensionMessage,
+  IDataspaceProtocolTransferTerminationMessage
+} from '@twin.org/standards-dataspace-protocol';
+
+const service = new DataspaceControlPlaneService();
+const trustPayload = 'eyJhbGciOi...';
+
+declare const agreement: IDataspaceProtocolAgreement;
+declare const requestMessage: IDataspaceProtocolTransferRequestMessage;
+declare const startMessage: IDataspaceProtocolTransferStartMessage;
+declare const completionMessage: IDataspaceProtocolTransferCompletionMessage;
+declare const suspensionMessage: IDataspaceProtocolTransferSuspensionMessage;
+declare const terminationMessage: IDataspaceProtocolTransferTerminationMessage;
+
+const requested = await service.requestTransfer(requestMessage, trustPayload);
+const started = await service.startTransfer(startMessage, trustPayload);
+const completed = await service.completeTransfer(completionMessage, trustPayload);
+const suspended = await service.suspendTransfer(suspensionMessage, trustPayload);
+const terminated = await service.terminateTransfer(terminationMessage, trustPayload);
+
+const negotiationId = await service.negotiateAgreement(
+  agreement,
+  'https://provider.example',
+  trustPayload
+);
+const negotiation = await service.getNegotiation(negotiationId, trustPayload);
+const history = await service.getNegotiationHistory(negotiationId, trustPayload);
+
+console.log(requested['@type']); // TransferProcess
+console.log(started['@type']); // TransferStartMessage
+console.log(completed['@type']); // TransferProcess
+console.log(suspended['@type']); // TransferProcess
+console.log(terminated['@type']); // TransferProcess
+console.log(negotiation['@id']); // urn:negotiation:001
+console.log(history.length); // 3
+```
+
+```typescript
+import { DataspaceControlPlaneService } from '@twin.org/dataspace-control-plane-service';
+
+const service = new DataspaceControlPlaneService();
+
+const transfer = await service.getTransferProcess('consumer-process-id', 'eyJhbGciOi...');
+const consumerPid = await service.resolveConsumerPid('provider-process-id');
+const providerPid = await service.resolveProviderPid('consumer-process-id');
+
+console.log(transfer['@type']); // TransferProcess
+console.log(consumerPid); // consumer-process-id
+console.log(providerPid); // provider-process-id
+```
+
+## DataspaceControlPlanePolicyRequester
+
+```typescript
+import { DataspaceControlPlanePolicyRequester } from '@twin.org/dataspace-control-plane-service';
+import type {
+  IDataspaceProtocolAgreement,
+  IDataspaceProtocolOffer
+} from '@twin.org/standards-dataspace-protocol';
+
+const requester = new DataspaceControlPlanePolicyRequester('logging', {
+  onStateChanged: async (negotiationId, state) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(state); // OFFERED
+  },
+  onCompleted: async (negotiationId, agreementId) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(agreementId); // urn:agreement:001
+  },
+  onFailed: async (negotiationId, reason) => {
+    console.log(negotiationId); // urn:negotiation:001
+    console.log(reason); // negotiationTerminatedByProvider
+  }
+});
+
+console.log(requester.className()); // DataspaceControlPlanePolicyRequester
+
+requester.trackNegotiation('urn:negotiation:001');
+const active = requester.getActiveNegotiations();
+console.log(active.size); // 1
+
+declare const offer: IDataspaceProtocolOffer;
+declare const agreement: IDataspaceProtocolAgreement;
+
+await requester.offer('urn:negotiation:001', offer);
+await requester.agreement('urn:negotiation:001', agreement);
+await requester.finalised('urn:negotiation:001');
+
+requester.trackNegotiation('urn:negotiation:002');
+await requester.terminated('urn:negotiation:002');
+requester.removeNegotiation('urn:negotiation:002');
+```

package/docs/reference/classes/DataspaceControlPlanePolicyRequester.md

@@ -44,7 +44,7 @@ Optional callback interface for state change notifications.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -52,7 +52,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -70,7 +70,7 @@ The class name of the component.
 
 ***
 
-### trackNegotiation()
+### trackNegotiation() {#tracknegotiation}
 
 > **trackNegotiation**(`negotiationId`): `void`
 
@@ -91,7 +91,7 @@ The negotiation ID returned by PNP.sendRequestToProvider().
 
 ***
 
-### getActiveNegotiations()
+### getActiveNegotiations() {#getactivenegotiations}
 
 > **getActiveNegotiations**(): `Map`\<`string`, [`INegotiationState`](../interfaces/INegotiationState.md)\>
 
@@ -105,7 +105,7 @@ Map of negotiationId to negotiation state.
 
 ***
 
-### removeNegotiation()
+### removeNegotiation() {#removenegotiation}
 
 > **removeNegotiation**(`negotiationId`): `void`
 
@@ -125,7 +125,7 @@ The negotiation ID to remove.
 
 ***
 
-### offer()
+### offer() {#offer}
 
 > **offer**(`negotiationId`, `offer`): `Promise`\<`boolean`\>
 
@@ -158,7 +158,7 @@ True if the offer was accepted, false otherwise.
 
 ***
 
-### agreement()
+### agreement() {#agreement}
 
 > **agreement**(`negotiationId`, `agreement`): `Promise`\<`boolean`\>
 
@@ -191,7 +191,7 @@ True if the agreement was accepted, false otherwise.
 
 ***
 
-### finalised()
+### finalised() {#finalised}
 
 > **finalised**(`negotiationId`): `Promise`\<`void`\>
 
@@ -218,7 +218,7 @@ Nothing.
 
 ***
 
-### terminated()
+### terminated() {#terminated}
 
 > **terminated**(`negotiationId`): `Promise`\<`void`\>
 

package/docs/reference/classes/DataspaceControlPlaneService.md

@@ -33,7 +33,7 @@ The options for the service.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -41,7 +41,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -59,7 +59,7 @@ The class name of the component.
 
 ***
 
-### registerNegotiationCallback()
+### registerNegotiationCallback() {#registernegotiationcallback}
 
 > **registerNegotiationCallback**(`key`, `callback`): `void`
 
@@ -90,7 +90,7 @@ The callback interface to register.
 
 ***
 
-### unregisterNegotiationCallback()
+### unregisterNegotiationCallback() {#unregisternegotiationcallback}
 
 > **unregisterNegotiationCallback**(`key`): `void`
 
@@ -114,7 +114,7 @@ The key used when registering the callback.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -140,7 +140,7 @@ The node logging component type.
 
 ***
 
-### stop()
+### stop() {#stop}
 
 > **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
 
@@ -165,7 +165,7 @@ The node logging component type.
 
 ***
 
-### requestTransfer()
+### requestTransfer() {#requesttransfer}
 
 > **requestTransfer**(`request`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
@@ -201,7 +201,7 @@ Called by: Consumer when it wants to request a new Transfer Process
 
 ***
 
-### startTransfer()
+### startTransfer() {#starttransfer}
 
 > **startTransfer**(`message`, `publicOrigin`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferStartMessage`\>
 
@@ -242,7 +242,7 @@ Role Performed: Provider / Consumer
 
 ***
 
-### completeTransfer()
+### completeTransfer() {#completetransfer}
 
 > **completeTransfer**(`message`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
@@ -274,7 +274,7 @@ Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the o
 
 ***
 
-### suspendTransfer()
+### suspendTransfer() {#suspendtransfer}
 
 > **suspendTransfer**(`message`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
@@ -306,7 +306,7 @@ Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the o
 
 ***
 
-### terminateTransfer()
+### terminateTransfer() {#terminatetransfer}
 
 > **terminateTransfer**(`message`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
@@ -338,7 +338,7 @@ Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the
 
 ***
 
-### getTransferProcess()
+### getTransferProcess() {#gettransferprocess}
 
 > **getTransferProcess**(`pid`, `trustPayload`): `Promise`\<`IDataspaceProtocolTransferError` \| `IDataspaceProtocolTransferProcess`\>
 
@@ -370,7 +370,7 @@ Transfer Process (DSP compliant) with current state, or TransferError if the ope
 
 ***
 
-### negotiateAgreement()
+### negotiateAgreement() {#negotiateagreement}
 
 > **negotiateAgreement**(`datasetId`, `offerId`, `providerEndpoint`, `publicOrigin`, `trustPayload`): `Promise`\<\{ `negotiationId`: `string`; \}\>
 
@@ -422,7 +422,7 @@ The negotiation ID. Use the registered callback for completion notification.
 
 ***
 
-### getNegotiation()
+### getNegotiation() {#getnegotiation}
 
 > **getNegotiation**(`negotiationId`, `trustPayload`): `Promise`\<`IDataspaceProtocolContractNegotiation` \| `IDataspaceProtocolContractNegotiationError`\>
 
@@ -454,7 +454,7 @@ Current state of the negotiation.
 
 ***
 
-### getNegotiationHistory()
+### getNegotiationHistory() {#getnegotiationhistory}
 
 > **getNegotiationHistory**(`state`, `cursor`, `trustPayload`): `Promise`\<\{ `negotiations`: `object`[]; `cursor?`: `string`; `count`: `number`; \}\>
 
@@ -492,7 +492,7 @@ List of negotiation history entries with pagination.
 
 ***
 
-### resolveConsumerPid()
+### resolveConsumerPid() {#resolveconsumerpid}
 
 > **resolveConsumerPid**(`consumerPid`, `trustPayload`): `Promise`\<`ITransferContext`\>
 
@@ -524,7 +524,7 @@ Transfer Context with Agreement, datasetId, and Transfer Process metadata.
 
 ***
 
-### resolveProviderPid()
+### resolveProviderPid() {#resolveproviderpid}
 
 > **resolveProviderPid**(`providerPid`, `trustPayload`): `Promise`\<`ITransferContext`\>
 

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConfig.md

@@ -4,7 +4,7 @@ Dataspace Control Plane service configuration.
 
 ## Properties
 
-### overrideTrustGeneratorType?
+### overrideTrustGeneratorType? {#overridetrustgeneratortype}
 
 > `optional` **overrideTrustGeneratorType**: `string`
 
@@ -13,7 +13,7 @@ If not specified, the default trust generator configured in the trust component
 
 ***
 
-### dataPlanePath?
+### dataPlanePath? {#dataplanepath}
 
 > `optional` **dataPlanePath**: `string`
 

package/docs/reference/interfaces/IDataspaceControlPlaneServiceConstructorOptions.md

@@ -4,37 +4,25 @@ Dataspace Control Plane service constructor options.
 
 ## Properties
 
-### policyAdministrationPointComponentType?
+### policyAdministrationPointComponentType? {#policyadministrationpointcomponenttype}
 
 > `optional` **policyAdministrationPointComponentType**: `string`
 
 Policy Administration Point component type.
 Used for Agreement lookup and validation during Transfer Process initiation.
 
-#### Default
-
-```ts
-policy-administration-point
-```
-
 ***
 
-### policyNegotiationPointComponentType?
+### policyNegotiationPointComponentType? {#policynegotiationpointcomponenttype}
 
 > `optional` **policyNegotiationPointComponentType**: `string`
 
 Policy Negotiation Point component type.
 Used for contract negotiation to create agreements before transfer processes.
 
-#### Default
-
-```ts
-policy-negotiation-point
-```
-
 ***
 
-### policyNegotiationAdminPointComponentType?
+### policyNegotiationAdminPointComponentType? {#policynegotiationadminpointcomponenttype}
 
 > `optional` **policyNegotiationAdminPointComponentType**: `string`
 
@@ -42,15 +30,9 @@ Policy Negotiation Admin Point component type.
 Used for querying negotiation history.
 Optional - if not provided, negotiation history will not be available.
 
-#### Default
-
-```ts
-policy-negotiation-admin-point
-```
-
 ***
 
-### federatedCatalogueComponentType?
+### federatedCatalogueComponentType? {#federatedcataloguecomponenttype}
 
 > `optional` **federatedCatalogueComponentType**: `string`
 
@@ -58,72 +40,42 @@ Federated Catalogue component type.
 Used for dataset validation during Transfer Process initiation.
 Validates that Agreements reference valid catalog datasets.
 
-#### Default
-
-```ts
-federated-catalogue
-```
-
 ***
 
-### loggingComponentType?
+### loggingComponentType? {#loggingcomponenttype}
 
 > `optional` **loggingComponentType**: `string`
 
 Logging component type.
 
-#### Default
-
-```ts
-logging
-```
-
 ***
 
-### identityComponentType?
+### identityComponentType? {#identitycomponenttype}
 
 > `optional` **identityComponentType**: `string`
 
 Identity component type (for token signing/verification).
 
-#### Default
-
-```ts
-identity
-```
-
 ***
 
-### identityAuthenticationComponentType?
+### identityAuthenticationComponentType? {#identityauthenticationcomponenttype}
 
 > `optional` **identityAuthenticationComponentType**: `string`
 
 Identity Authentication component type (for token validation).
 
-#### Default
-
-```ts
-identity-authentication
-```
-
 ***
 
-### trustComponentType?
+### trustComponentType? {#trustcomponenttype}
 
 > `optional` **trustComponentType**: `string`
 
 Trust component type for trust verification.
 Used to verify JWT/VC tokens and extract identity information.
 
-#### Default
-
-```ts
-trust
-```
-
 ***
 
-### transferProcessEntityStorageType?
+### transferProcessEntityStorageType? {#transferprocessentitystoragetype}
 
 > `optional` **transferProcessEntityStorageType**: `string`
 
@@ -131,29 +83,17 @@ Entity storage type for Transfer Process entities.
 Used to persist transfer state for the consumerPid flow.
 Must match the Data Plane's transferProcessEntityStorageType for shared storage.
 
-#### Default
-
-```ts
-transfer-process
-```
-
 ***
 
-### taskSchedulerComponentType?
+### taskSchedulerComponentType? {#taskschedulercomponenttype}
 
 > `optional` **taskSchedulerComponentType**: `string`
 
 Task scheduler component type for periodic cleanup of stalled negotiations.
 
-#### Default
-
-```ts
-task-scheduler
-```
-
 ***
 
-### config?
+### config? {#config}
 
 > `optional` **config**: [`IDataspaceControlPlaneServiceConfig`](IDataspaceControlPlaneServiceConfig.md)
 

package/docs/reference/interfaces/INegotiationState.md

@@ -4,7 +4,7 @@ Negotiation state tracked internally for callback routing.
 
 ## Properties
 
-### negotiationId
+### negotiationId {#negotiationid}
 
 > **negotiationId**: `string`
 
@@ -12,7 +12,7 @@ The negotiation ID (self-reference for lookup).
 
 ***
 
-### state
+### state {#state}
 
 > **state**: `DataspaceProtocolContractNegotiationStateType`
 
@@ -20,7 +20,7 @@ Current negotiation state.
 
 ***
 
-### agreement?
+### agreement? {#agreement}
 
 > `optional` **agreement**: `IDataspaceProtocolAgreement`
 
@@ -28,7 +28,7 @@ Agreement received from provider (stored until finalized).
 
 ***
 
-### startedAt
+### startedAt {#startedat}
 
 > **startedAt**: `number`
 
@@ -36,7 +36,7 @@ Timestamp when negotiation started.
 
 ***
 
-### updatedAt
+### updatedAt {#updatedat}
 
 > **updatedAt**: `number`
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/dataspace-control-plane-service",
-	"version": "0.0.3-next.18",
-	"description": "Dataspace Control Plane service implementation for Eclipse Dataspace Protocol Transfer Process Protocol",
+	"version": "0.0.3-next.20",
+	"description": "Implements agreement negotiation and transfer process lifecycle management for control plane operations.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/dataspace.git",
@@ -17,7 +17,7 @@
 		"@twin.org/api-models": "next",
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
-		"@twin.org/dataspace-models": "0.0.3-next.18",
+		"@twin.org/dataspace-models": "0.0.3-next.20",
 		"@twin.org/entity": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/federated-catalogue-models": "next",