@twin.org/dataspace-models 0.0.3-next.43 → 0.0.3-next.45

package/dist/es/factories/dataspaceAppFactory.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0.
 import { Factory } from "@twin.org/core";
 /**
- * Factory for creating dataspace apps.
+ * Factory for registering and retrieving dataspace app instances by name.
  */
 // eslint-disable-next-line @typescript-eslint/naming-convention
 export const DataspaceAppFactory = Factory.createFactory("dataspace-app");

package/dist/es/factories/dataspaceAppFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataspaceAppFactory.js","sourceRoot":"","sources":["../../../src/factories/dataspaceAppFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAgB,eAAe,CAAC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { IDataspaceApp } from \"../models/app/IDataspaceApp.js\";\n\n/**\n * Factory for creating dataspace apps.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const DataspaceAppFactory = Factory.createFactory<IDataspaceApp>(\"dataspace-app\");\n"]}
+{"version":3,"file":"dataspaceAppFactory.js","sourceRoot":"","sources":["../../../src/factories/dataspaceAppFactory.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAGzC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAgB,eAAe,CAAC,CAAC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Factory } from \"@twin.org/core\";\nimport type { IDataspaceApp } from \"../models/app/IDataspaceApp.js\";\n\n/**\n * Factory for registering and retrieving dataspace app instances by name.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const DataspaceAppFactory = Factory.createFactory<IDataspaceApp>(\"dataspace-app\");\n"]}

package/dist/es/models/api/IActivityLogEntryGetRequest.js

@@ -1,4 +1,2 @@
-// Copyright 2025 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
 export {};
 //# sourceMappingURL=IActivityLogEntryGetRequest.js.map

package/dist/es/models/api/IActivityLogEntryGetRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IActivityLogEntryGetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogEntryGetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Get Request for an Activity Log Entry.\n */\nexport interface IActivityLogEntryGetRequest {\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The ID of the entry to get.\n\t\t */\n\t\tid: string;\n\t};\n}\n"]}
+{"version":3,"file":"IActivityLogEntryGetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogEntryGetRequest.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { HeaderTypes } from \"@twin.org/web\";\n\n/**\n * Get Request for an Activity Log Entry.\n */\nexport interface IActivityLogEntryGetRequest {\n\t/**\n\t * The headers which can be used to authenticate the requester.\n\t */\n\theaders?: {\n\t\t[HeaderTypes.Authorization]?: string;\n\t};\n\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The ID of the entry to get.\n\t\t */\n\t\tid: string;\n\t};\n}\n"]}

package/dist/es/models/api/IActivityLogEntryGetResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"IActivityLogEntryGetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogEntryGetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IActivityLogEntry } from \"../IActivityLogEntry.js\";\n\n/**\n * Service Offering response\n */\nexport interface IActivityLogEntryGetResponse {\n\t/**\n\t * The response payload.\n\t */\n\tbody: IActivityLogEntry;\n}\n"]}
+{"version":3,"file":"IActivityLogEntryGetResponse.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogEntryGetResponse.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IActivityLogEntry } from \"../IActivityLogEntry.js\";\n\n/**\n * Response containing a single activity log entry.\n */\nexport interface IActivityLogEntryGetResponse {\n\t/**\n\t * The response payload.\n\t */\n\tbody: IActivityLogEntry;\n}\n"]}

package/dist/es/models/api/IActivityLogStatusNotificationPayload.js.map

@@ -1 +1 @@
-{"version":3,"file":"IActivityLogStatusNotificationPayload.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogStatusNotificationPayload.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IActivityLogStatusNotification } from \"../IActivityLogStatusNotification.js\";\n\n/**\n * The status supplied to clients of the Dataspace Data Plane\n */\nexport interface IActivityLogStatusNotificationPayload {\n\t/**\n\t * Body\n\t */\n\tbody: IActivityLogStatusNotification;\n}\n"]}
+{"version":3,"file":"IActivityLogStatusNotificationPayload.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogStatusNotificationPayload.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IActivityLogStatusNotification } from \"../IActivityLogStatusNotification.js\";\n\n/**\n * WebSocket push payload carrying an activity log status notification to connected clients.\n */\nexport interface IActivityLogStatusNotificationPayload {\n\t/**\n\t * The activity log status notification.\n\t */\n\tbody: IActivityLogStatusNotification;\n}\n"]}

package/dist/es/models/api/IActivityLogStatusRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IActivityLogStatusRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogStatusRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Activity log status\n */\nexport interface IActivityLogStatusRequest {\n\t/**\n\t * Empty body.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The operation to perform.\n\t\t */\n\t\toperation: \"subscribe\" | \"unsubscribe\";\n\n\t\t/**\n\t\t * The subscription Id.\n\t\t */\n\t\tsubscriptionId: string;\n\t};\n}\n"]}
+{"version":3,"file":"IActivityLogStatusRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IActivityLogStatusRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * WebSocket request to subscribe or unsubscribe from the activity log stream.\n */\nexport interface IActivityLogStatusRequest {\n\t/**\n\t * Request body containing the subscribe or unsubscribe operation.\n\t */\n\tbody: {\n\t\t/**\n\t\t * The operation to perform.\n\t\t */\n\t\toperation: \"subscribe\" | \"unsubscribe\";\n\n\t\t/**\n\t\t * The subscription Id.\n\t\t */\n\t\tsubscriptionId: string;\n\t};\n}\n"]}

package/dist/es/models/controlPlane/IDataspaceControlPlaneComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/IDataspaceControlPlaneComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type {\n\tIDataspaceProtocolContractNegotiation,\n\tIDataspaceProtocolContractNegotiationError,\n\tIDataspaceProtocolDataset,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDataspaceAppDataset } from \"./IDataspaceAppDataset.js\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\nimport type { ITransferCallback } from \"./ITransferCallback.js\";\n\n/**\n * Dataspace Control Plane Component interface.\n * Implements Eclipse Dataspace Protocol (DSP) specifications:\n * - Contract Negotiation Protocol\n * - Transfer Process Protocol\n *\n * This component acts as the Control Plane for contract negotiation and\n * data transfers between nodes in a dataspace.\n *\n * DSP 2025-1 Specification: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/\n */\nexport interface IDataspaceControlPlaneComponent extends IComponent {\n\t// ============================================================================\n\t// CONTRACT NEGOTIATION PROTOCOL (DSP)\n\t// Methods for negotiating agreements before transfers\n\t// ============================================================================\n\n\t/**\n\t * Register a callback to receive negotiation state change notifications.\n\t * Upstream modules (e.g. supply-chain) register their callback here\n\t * to be notified when negotiations complete, fail, or change state.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterNegotiationCallback(key: string, callback: INegotiationCallback): void;\n\n\t/**\n\t * Unregister a previously registered negotiation callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterNegotiationCallback(key: string): void;\n\n\t/**\n\t * Negotiate a contract agreement with a provider.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Returns immediately with a negotiationId. The caller is notified\n\t * via the registered INegotiationCallback when the negotiation completes.\n\t * The negotiation follows DSP state machine: REQUESTED → OFFERED → AGREED → VERIFIED → FINALIZED.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param datasetId The dataset ID from the provider's catalog.\n\t * @param offerId The offer ID from the provider's catalog.\n\t * @param providerEndpoint The provider's contract negotiation endpoint URL.\n\t * @param publicOrigin The public origin URL of this control plane (for callbacks).\n\t * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).\n\t * @returns The negotiation ID for tracking. Use registered callback for completion.\n\t */\n\tnegotiateAgreement(\n\t\tdatasetId: string,\n\t\tofferId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ negotiationId: string }>;\n\n\t/**\n\t * Get the current state of a contract negotiation.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Queries the current state of an ongoing or completed negotiation.\n\t * Use this to monitor negotiation progress.\n\t * Returns the DSP-compliant negotiation state or error.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param negotiationId The unique identifier of the negotiation.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns DSP ContractNegotiation with current state, or error.\n\t */\n\tgetNegotiation(\n\t\tnegotiationId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;\n\n\t/**\n\t * Get negotiation history.\n\t * Queries past contract negotiations for audit trails and debugging.\n\t *\n\t * Returns a list of past negotiations with their states and metadata.\n\t * Supports optional filtering by state and pagination via cursor.\n\t *\n\t * @param state Optional filter by negotiation state (e.g., \"FINALIZED\", \"TERMINATED\").\n\t * @param cursor Optional pagination cursor for fetching next page.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns List of negotiation history entries with pagination cursor.\n\t */\n\tgetNegotiationHistory(\n\t\tstate: string | undefined,\n\t\tcursor: string | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tnegotiations: {\n\t\t\tnegotiation:\n\t\t\t\t| IDataspaceProtocolContractNegotiation\n\t\t\t\t| IDataspaceProtocolContractNegotiationError;\n\t\t\tcreatedAt: string;\n\t\t\tofferId?: string;\n\t\t\tagreementId?: string;\n\t\t}[];\n\t\tcursor?: string;\n\t\tcount: number;\n\t}>;\n\n\t// ============================================================================\n\t// TRANSFER PROCESS PROTOCOL (DSP)\n\t// Methods for managing data transfers after agreements are established\n\t// ============================================================================\n\n\t// ----------------------------------------------------------------------------\n\t// CONSUMER SIDE OPERATIONS\n\t// Methods called by the Data Consumer to initiate transfers\n\t// ----------------------------------------------------------------------------\n\n\t/**\n\t * Register a callback to receive transfer process state change notifications.\n\t * Upstream modules register their callback here to be notified when a\n\t * consumer-initiated transfer changes state (STARTED, COMPLETED, SUSPENDED,\n\t * TERMINATED).\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterTransferCallback(key: string, callback: ITransferCallback): void;\n\n\t/**\n\t * Unregister a previously registered transfer callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterTransferCallback(key: string): void;\n\n\t/**\n\t * Start a data transfer as a Consumer.\n\t * High-level convenience wrapper around the DSP Transfer Request protocol.\n\t *\n\t * This method:\n\t * 1. Generates a consumerPid.\n\t * 2. POSTs a TransferRequestMessage to the provider's DSP endpoint.\n\t * 3. Persists a local TransferProcess in REQUESTED state (only if provider accepts).\n\t * 4. Returns the consumerPid immediately.\n\t *\n\t * The caller is notified of subsequent state changes (STARTED, COMPLETED, etc.)\n\t * via the registered ITransferCallback. The transfer moves to STARTED when the\n\t * provider POSTs a TransferStartMessage back to this node's callback address.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * @param agreementId The finalized agreement ID (from contract negotiation).\n\t * @param providerEndpoint The provider's DSP control plane base URL.\n\t * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).\n\t * @param format The transfer format (e.g. \"HttpData-PULL\", \"HttpData-PUSH\").\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns The consumerPid of the newly created TransferProcess.\n\t */\n\tstartDataTransfer(\n\t\tagreementId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\tformat: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ consumerPid: string }>;\n\n\t/**\n\t * Request a Transfer Process.\n\t * Creates a new Transfer Process in REQUESTED state.\n\t *\n\t * Role Performed: Provider\n\t * Called by: Consumer when it wants to request a new Transfer Process\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message\n\t *\n\t * @param request Transfer request message (DSP compliant) containing agreementId,\n\t * consumerPid, callbackAddress, and format.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * The consumer must prove their identity by providing a valid trust payload.\n\t * @returns Transfer Process (DSP compliant) with state REQUESTED, including\n\t * both consumerPid and providerPid, or TransferError if the operation fails.\n\t */\n\trequestTransfer(\n\t\trequest: IDataspaceProtocolTransferRequestMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// PROVIDER SIDE OPERATIONS\n\t// Methods called by the Data Provider to respond to transfer requests\n\t// ============================================================================\n\n\t/**\n\t * Start a Transfer Process.\n\t * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.\n\t *\n\t * Role Performed: Provider / Consumer\n\t * Called by: Provider when a Transfer Process starts, or Consumer to attempt to start a Transfer Process after it has been suspended\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message\n\t *\n\t * @param message Transfer start message (DSP compliant).\n\t * @param publicOrigin The public origin URL of this service (used to construct data plane endpoint for PULL transfers).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.\n\t */\n\tstartTransfer(\n\t\tmessage: IDataspaceProtocolTransferStartMessage,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// SHARED STATE MANAGEMENT OPERATIONS\n\t// Methods that can be called by either Consumer or Provider\n\t// ============================================================================\n\n\t/**\n\t * Complete a Transfer Process.\n\t * Transitions Transfer Process to COMPLETED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process is completed on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-completion-message\n\t *\n\t * @param message Transfer completion message (DSP compliant).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.\n\t */\n\tcompleteTransfer(\n\t\tmessage: IDataspaceProtocolTransferCompletionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Suspend a Transfer Process.\n\t * Transitions Transfer Process to SUSPENDED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be temporarily suspended on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message\n\t *\n\t * @param message Transfer suspension message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.\n\t */\n\tsuspendTransfer(\n\t\tmessage: IDataspaceProtocolTransferSuspensionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Terminate a Transfer Process.\n\t * Transitions Transfer Process to TERMINATED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be terminated on their side (e.g., due to error)\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message\n\t *\n\t * @param message Transfer termination message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.\n\t */\n\tterminateTransfer(\n\t\tmessage: IDataspaceProtocolTransferTerminationMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Get Transfer Process State.\n\t * Query the current state of a Transfer Process.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when they need to check the status of a Transfer process on their side\n\t *\n\t * Supports role-agnostic lookup using either consumerPid or providerPid.\n\t * The service will automatically detect which role the caller is acting as\n\t * (Consumer or Provider) based on the PID provided.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process\n\t *\n\t * @param pid The Process ID (consumerPid or providerPid) used to identify the transfer.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.\n\t */\n\tgetTransferProcess(\n\t\tpid: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// DATASET MANAGEMENT\n\t// CRUD over the tenant-scoped dataset records the Control Plane reads at\n\t// start time to populate the federated catalogue.\n\t// ============================================================================\n\n\t/**\n\t * Register an app dataset for a dataspace app, owned by the calling tenant.\n\t * @param id Optional explicit id. If omitted, derived from `dataset[\"@id\"]`\n\t * or generated.\n\t * @param appId The dataspace app this dataset belongs to (matches\n\t * `DataspaceAppFactory` registration name).\n\t * @param dataset The dataset payload (may omit system-stamped fields).\n\t * @returns The resolved dataset id.\n\t */\n\tcreateAppDataset(\n\t\tid: string | undefined,\n\t\tappId: string,\n\t\tdataset: IDataspaceProtocolDataset\n\t): Promise<string>;\n\n\t/**\n\t * Get an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns The stored app dataset record.\n\t */\n\tgetAppDataset(id: string): Promise<IDataspaceAppDataset>;\n\n\t/**\n\t * List the app datasets owned by the calling tenant.\n\t * @param cursor Optional pagination cursor.\n\t * @param limit Optional maximum number of entries to return.\n\t * @returns The stored app datasets and the next-page cursor if more exist.\n\t */\n\tlistAppDatasets(\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tentities: IDataspaceAppDataset[];\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Update an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @param appId The dataspace app this dataset belongs to.\n\t * @param dataset The dataset payload.\n\t * @returns Nothing.\n\t */\n\tupdateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;\n\n\t/**\n\t * Delete an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns Nothing.\n\t */\n\tdeleteAppDataset(id: string): Promise<void>;\n}\n"]}
+{"version":3,"file":"IDataspaceControlPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/controlPlane/IDataspaceControlPlaneComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type {\n\tIDataspaceProtocolContractNegotiation,\n\tIDataspaceProtocolContractNegotiationError,\n\tIDataspaceProtocolDataset,\n\tIDataspaceProtocolTransferCompletionMessage,\n\tIDataspaceProtocolTransferError,\n\tIDataspaceProtocolTransferProcess,\n\tIDataspaceProtocolTransferRequestMessage,\n\tIDataspaceProtocolTransferStartMessage,\n\tIDataspaceProtocolTransferSuspensionMessage,\n\tIDataspaceProtocolTransferTerminationMessage\n} from \"@twin.org/standards-dataspace-protocol\";\nimport type { IDataspaceAppDataset } from \"./IDataspaceAppDataset.js\";\nimport type { INegotiationCallback } from \"./INegotiationCallback.js\";\nimport type { ITransferCallback } from \"./ITransferCallback.js\";\n\n/**\n * Dataspace Control Plane Component interface.\n * Implements Eclipse Dataspace Protocol (DSP) specifications:\n * - Contract Negotiation Protocol\n * - Transfer Process Protocol\n *\n * This component acts as the Control Plane for contract negotiation and\n * data transfers between nodes in a dataspace.\n *\n * DSP 2025-1 Specification: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/\n */\nexport interface IDataspaceControlPlaneComponent extends IComponent {\n\t// ============================================================================\n\t// CONTRACT NEGOTIATION PROTOCOL (DSP)\n\t// Methods for negotiating agreements before transfers\n\t// ============================================================================\n\n\t/**\n\t * Register a callback to receive negotiation state change notifications.\n\t * Upstream modules (e.g. supply-chain) register their callback here\n\t * to be notified when negotiations complete, fail, or change state.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterNegotiationCallback(key: string, callback: INegotiationCallback): void;\n\n\t/**\n\t * Unregister a previously registered negotiation callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterNegotiationCallback(key: string): void;\n\n\t/**\n\t * Negotiate a contract agreement with a provider.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Returns immediately with a negotiationId. The caller is notified\n\t * via the registered INegotiationCallback when the negotiation completes.\n\t * The negotiation follows DSP state machine: REQUESTED → OFFERED → AGREED → VERIFIED → FINALIZED.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param datasetId The dataset ID from the provider's catalog.\n\t * @param offerId The offer ID from the provider's catalog.\n\t * @param providerEndpoint The provider's contract negotiation endpoint URL.\n\t * @param publicOrigin The public origin URL of this control plane (for callbacks).\n\t * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).\n\t * @returns The negotiation ID for tracking. Use registered callback for completion.\n\t */\n\tnegotiateAgreement(\n\t\tdatasetId: string,\n\t\tofferId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ negotiationId: string }>;\n\n\t/**\n\t * Get the current state of a contract negotiation.\n\t * Implements DSP Contract Negotiation Protocol.\n\t *\n\t * Queries the current state of an ongoing or completed negotiation.\n\t * Use this to monitor negotiation progress.\n\t * Returns the DSP-compliant negotiation state or error.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol\n\t *\n\t * @param negotiationId The unique identifier of the negotiation.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns DSP ContractNegotiation with current state, or error.\n\t */\n\tgetNegotiation(\n\t\tnegotiationId: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;\n\n\t/**\n\t * Get negotiation history.\n\t * Queries past contract negotiations for audit trails and debugging.\n\t *\n\t * Returns a list of past negotiations with their states and metadata.\n\t * Supports optional filtering by state and pagination via cursor.\n\t *\n\t * @param state Optional filter by negotiation state (e.g., \"FINALIZED\", \"TERMINATED\").\n\t * @param cursor Optional pagination cursor for fetching next page.\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns List of negotiation history entries with pagination cursor.\n\t */\n\tgetNegotiationHistory(\n\t\tstate: string | undefined,\n\t\tcursor: string | undefined,\n\t\ttrustPayload: unknown\n\t): Promise<{\n\t\tnegotiations: {\n\t\t\tnegotiation:\n\t\t\t\t| IDataspaceProtocolContractNegotiation\n\t\t\t\t| IDataspaceProtocolContractNegotiationError;\n\t\t\tcreatedAt: string;\n\t\t\tofferId?: string;\n\t\t\tagreementId?: string;\n\t\t}[];\n\t\tcursor?: string;\n\t\tcount: number;\n\t}>;\n\n\t// ============================================================================\n\t// TRANSFER PROCESS PROTOCOL (DSP)\n\t// Methods for managing data transfers after agreements are established\n\t// ============================================================================\n\n\t// ----------------------------------------------------------------------------\n\t// CONSUMER SIDE OPERATIONS\n\t// Methods called by the Data Consumer to initiate transfers\n\t// ----------------------------------------------------------------------------\n\n\t/**\n\t * Register a callback to receive transfer process state change notifications.\n\t * Upstream modules register their callback here to be notified when a\n\t * consumer-initiated transfer changes state (STARTED, COMPLETED, SUSPENDED,\n\t * TERMINATED).\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t * @param key A unique key identifying this callback registration.\n\t * @param callback The callback interface to register.\n\t */\n\tregisterTransferCallback(key: string, callback: ITransferCallback): void;\n\n\t/**\n\t * Unregister a previously registered transfer callback.\n\t * @param key The key used when registering the callback.\n\t */\n\tunregisterTransferCallback(key: string): void;\n\n\t/**\n\t * Start a data transfer as a Consumer.\n\t * High-level convenience wrapper around the DSP Transfer Request protocol.\n\t *\n\t * This method:\n\t * 1. Generates a consumerPid.\n\t * 2. POSTs a TransferRequestMessage to the provider's DSP endpoint.\n\t * 3. Persists a local TransferProcess in REQUESTED state (only if provider accepts).\n\t * 4. Returns the consumerPid immediately.\n\t *\n\t * The caller is notified of subsequent state changes (STARTED, COMPLETED, etc.)\n\t * via the registered ITransferCallback. The transfer moves to STARTED when the\n\t * provider POSTs a TransferStartMessage back to this node's callback address.\n\t *\n\t * The REST client does not support this method and throws a not supported error —\n\t * use ComponentFactory.get() for the in-process service.\n\t *\n\t * @param agreementId The finalized agreement ID (from contract negotiation).\n\t * @param providerEndpoint The provider's DSP control plane base URL.\n\t * @param publicOrigin The public origin URL of this control plane (used as callbackAddress).\n\t * @param format The transfer format (e.g. \"HttpData-PULL\", \"HttpData-PUSH\").\n\t * @param trustPayload Trust payload for authentication.\n\t * @returns The consumerPid of the newly created TransferProcess.\n\t */\n\tstartDataTransfer(\n\t\tagreementId: string,\n\t\tproviderEndpoint: string,\n\t\tpublicOrigin: string,\n\t\tformat: string,\n\t\ttrustPayload: unknown\n\t): Promise<{ consumerPid: string }>;\n\n\t/**\n\t * Request a Transfer Process.\n\t * Creates a new Transfer Process in REQUESTED state.\n\t *\n\t * Role Performed: Provider\n\t * Called by: Consumer when it wants to request a new Transfer Process\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message\n\t *\n\t * @param request Transfer request message (DSP compliant) containing agreementId,\n\t * consumerPid, callbackAddress, and format.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * The consumer must prove their identity by providing a valid trust payload.\n\t * @returns Transfer Process (DSP compliant) with state REQUESTED, including\n\t * both consumerPid and providerPid, or TransferError if the operation fails.\n\t */\n\trequestTransfer(\n\t\trequest: IDataspaceProtocolTransferRequestMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// PROVIDER SIDE OPERATIONS\n\t// Methods called by the Data Provider to respond to transfer requests\n\t// ============================================================================\n\n\t/**\n\t * Start a Transfer Process.\n\t * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.\n\t *\n\t * Role Performed: Provider / Consumer\n\t * Called by: Provider when a Transfer Process starts, or Consumer to attempt to start a Transfer Process after it has been suspended\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message\n\t *\n\t * @param message Transfer start message (DSP compliant).\n\t * @param publicOrigin The public origin URL of this service (used to construct data plane endpoint for PULL transfers).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.\n\t */\n\tstartTransfer(\n\t\tmessage: IDataspaceProtocolTransferStartMessage,\n\t\tpublicOrigin: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// SHARED STATE MANAGEMENT OPERATIONS\n\t// Methods that can be called by either Consumer or Provider\n\t// ============================================================================\n\n\t/**\n\t * Complete a Transfer Process.\n\t * Transitions Transfer Process to COMPLETED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process is completed on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-completion-message\n\t *\n\t * @param message Transfer completion message (DSP compliant).\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.\n\t */\n\tcompleteTransfer(\n\t\tmessage: IDataspaceProtocolTransferCompletionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Suspend a Transfer Process.\n\t * Transitions Transfer Process to SUSPENDED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be temporarily suspended on their side\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message\n\t *\n\t * @param message Transfer suspension message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.\n\t */\n\tsuspendTransfer(\n\t\tmessage: IDataspaceProtocolTransferSuspensionMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Terminate a Transfer Process.\n\t * Transitions Transfer Process to TERMINATED state.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when a Transfer process needs to be terminated on their side (e.g., due to error)\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message\n\t *\n\t * @param message Transfer termination message (DSP compliant) with optional reason.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.\n\t */\n\tterminateTransfer(\n\t\tmessage: IDataspaceProtocolTransferTerminationMessage,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t/**\n\t * Get Transfer Process State.\n\t * Query the current state of a Transfer Process.\n\t *\n\t * Role Performed: Consumer / Provider\n\t * Called by: Provider or Consumer when they need to check the status of a Transfer process on their side\n\t *\n\t * Supports role-agnostic lookup using either consumerPid or providerPid.\n\t * The service will automatically detect which role the caller is acting as\n\t * (Consumer or Provider) based on the PID provided.\n\t *\n\t * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process\n\t *\n\t * @param pid The Process ID (consumerPid or providerPid) used to identify the transfer.\n\t * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).\n\t * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.\n\t */\n\tgetTransferProcess(\n\t\tpid: string,\n\t\ttrustPayload: unknown\n\t): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;\n\n\t// ============================================================================\n\t// DATASET MANAGEMENT\n\t// CRUD over the tenant-scoped dataset records the Control Plane reads at\n\t// start time to populate the federated catalogue.\n\t// ============================================================================\n\n\t/**\n\t * Register an app dataset for a dataspace app, owned by the calling tenant.\n\t * @param id Optional explicit id. If omitted, derived from `dataset[\"@id\"]`\n\t * or generated.\n\t * @param appId The dataspace app this dataset belongs to (matches\n\t * `DataspaceAppFactory` registration name).\n\t * @param dataset The dataset payload (may omit system-stamped fields).\n\t * @returns The resolved dataset id.\n\t */\n\tcreateAppDataset(\n\t\tid: string | undefined,\n\t\tappId: string,\n\t\tdataset: IDataspaceProtocolDataset\n\t): Promise<string>;\n\n\t/**\n\t * Get an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns The stored app dataset record.\n\t */\n\tgetAppDataset(id: string): Promise<IDataspaceAppDataset>;\n\n\t/**\n\t * List the app datasets owned by the calling tenant.\n\t * @param cursor Optional pagination cursor.\n\t * @param limit Optional maximum number of entries to return.\n\t * @returns The stored app datasets and the next-page cursor if more exist.\n\t */\n\tlistAppDatasets(\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tentities: IDataspaceAppDataset[];\n\t\tcursor?: string;\n\t}>;\n\n\t/**\n\t * Update an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @param appId The dataspace app this dataset belongs to.\n\t * @param dataset The dataset payload.\n\t * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.\n\t */\n\tupdateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;\n\n\t/**\n\t * Delete an app dataset record owned by the calling tenant.\n\t * @param id The stored app dataset id.\n\t * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.\n\t */\n\tdeleteAppDataset(id: string): Promise<void>;\n}\n"]}

package/dist/es/models/dataPlane/IDataspaceDataPlaneComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"IDataspaceDataPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/dataPlane/IDataspaceDataPlaneComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IJsonLdContextDefinitionElement } from \"@twin.org/data-json-ld\";\nimport type { IActivityStreamsActivity } from \"@twin.org/standards-w3c-activity-streams\";\nimport type { IActivityLogEntry } from \"../IActivityLogEntry.js\";\nimport type { IActivityLogStatusNotification } from \"../IActivityLogStatusNotification.js\";\nimport type { IDataAssetItemListResult } from \"../IDataAssetItemListResult.js\";\nimport type { IEntitySet } from \"../IEntitySet.js\";\nimport type { IFilteringQuery } from \"../IFilteringQuery.js\";\n\n/**\n * Dataspace Data Plane component interface.\n * Implements the Data Plane functionality for the Eclipse Dataspace Protocol.\n */\nexport interface IDataspaceDataPlaneComponent extends IComponent {\n\t/**\n\t * Notify an Activity to the Dataspace Data Plane Activity Stream.\n\t * @param activity The Activity notified.\n\t * @param trustPayload Optional trust payload to verify the requester's identity.\n\t * @returns The activity's entry.\n\t */\n\tnotifyActivity(\n\t\tactivity: IActivityStreamsActivity,\n\t\ttrustPayload?: unknown\n\t): Promise<string | IActivityLogEntry>;\n\n\t/**\n\t * Subscribes to the activity log.\n\t * @param callback The callback to be called when Activity Log is called.\n\t * @param subscriptionId The subscription Id.\n\t * @returns The subscription Id.\n\t */\n\tsubscribeToActivityLog(\n\t\tcallback: (notification: IActivityLogStatusNotification) => Promise<void>,\n\t\tsubscriptionId?: string\n\t): Promise<string>;\n\n\t/**\n\t * Unsubscribes to the activity log.\n\t * @param subscriptionId The subscription Id.\n\t * @returns The subscription Id.\n\t */\n\tunSubscribeToActivityLog(subscriptionId: string): Promise<void>;\n\n\t/**\n\t * Returns Activity Log Entry which contains the Activity processing details.\n\t * @param logEntryId The Id of the Activity Log Entry (a URI).\n\t * @returns the Activity Log Entry with the processing details.\n\t * @throws NotFoundError if activity log entry is not known.\n\t */\n\tgetActivityLogEntry(logEntryId: string): Promise<IActivityLogEntry>;\n\n\t/**\n\t * Get Data Asset entities. Allows to retrieve entities by their type or id.\n\t * @param entitySet The set of entities to be retrieved.\n\t * @param entitySet.jsonLdContext The JSON-LD Context to be used to expand the referred entityType.\n\t * @param consumerPid The consumer Process ID from the DSP Transfer Process.\n\t * Used to resolve datasetId from the Transfer Process.\n\t * @param cursor Pagination details - cursor.\n\t * @param limit Pagination details - max number of entities.\n\t * @param trustPayload Trust payload to verify the requesters identity.\n\t * @returns The item list and optional cursor for pagination via Link headers.\n\t */\n\tgetDataAssetEntities(\n\t\tentitySet: IEntitySet & {\n\t\t\tjsonLdContext?: IJsonLdContextDefinitionElement[];\n\t\t},\n\t\tconsumerPid: string,\n\t\tcursor?: string,\n\t\tlimit?: number,\n\t\ttrustPayload?: unknown\n\t): Promise<IDataAssetItemListResult>;\n\n\t/**\n\t * Queries a data asset controlled by this Dataspace App.\n\t * @param consumerPid The consumer Process ID from the DSP Transfer Process.\n\t * Used to resolve datasetId from the Transfer Process.\n\t * @param query The filtering query.\n\t * @param cursor Pagination details - cursor.\n\t * @param limit Pagination details - max number of entities.\n\t * @param trustPayload Trust payload to verify the requesters identity.\n\t * @returns The item list and optional cursor for pagination via Link headers.\n\t */\n\tqueryDataAsset(\n\t\tconsumerPid: string,\n\t\tquery: IFilteringQuery,\n\t\tcursor?: string,\n\t\tlimit?: number,\n\t\ttrustPayload?: unknown\n\t): Promise<IDataAssetItemListResult>;\n\n\t/**\n\t * Set up a push subscription after a transfer enters STARTED from REQUESTED.\n\t * Reads the TransferProcess, builds an IFollowActivity, calls the app's\n\t * subscribeToData, and persists a PushSubscription entity.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is created.\n\t */\n\tsetupPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Pause deliveries for a push subscription. The subscription entity stays\n\t * alive with status=Paused. No app unsubscribe call.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is paused.\n\t */\n\tsuspendPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Resume deliveries after a SUSPENDED → STARTED transition. Flips status\n\t * back to Active. No app subscribeToData call.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is resumed.\n\t */\n\tresumePushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Tear down a push subscription. Builds an IUndoActivity, calls the app's\n\t * unsubscribeToData, and deletes the PushSubscription entity.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is torn down.\n\t */\n\tteardownPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Called by the app when new data is available for a follower.\n\t * The activity's `to` attribute contains the consumerPid URN. This method\n\t * looks up the matching PushSubscription, validates transfer state, and\n\t * schedules a Background Task that POSTs the activity to the consumer.\n\t * @param activity The outbound activity carrying the data payload.\n\t * @returns Promise that resolves when the delivery task is scheduled.\n\t */\n\tprocessOutboxActivity(activity: IActivityStreamsActivity): Promise<void>;\n}\n"]}
+{"version":3,"file":"IDataspaceDataPlaneComponent.js","sourceRoot":"","sources":["../../../../src/models/dataPlane/IDataspaceDataPlaneComponent.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2025 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IComponent } from \"@twin.org/core\";\nimport type { IJsonLdContextDefinitionElement } from \"@twin.org/data-json-ld\";\nimport type { IActivityStreamsActivity } from \"@twin.org/standards-w3c-activity-streams\";\nimport type { IActivityLogEntry } from \"../IActivityLogEntry.js\";\nimport type { IActivityLogStatusNotification } from \"../IActivityLogStatusNotification.js\";\nimport type { IDataAssetItemListResult } from \"../IDataAssetItemListResult.js\";\nimport type { IEntitySet } from \"../IEntitySet.js\";\nimport type { IFilteringQuery } from \"../IFilteringQuery.js\";\n\n/**\n * Dataspace Data Plane component interface.\n * Implements the Data Plane functionality for the Eclipse Dataspace Protocol.\n */\nexport interface IDataspaceDataPlaneComponent extends IComponent {\n\t/**\n\t * Notify an Activity to the Dataspace Data Plane Activity Stream.\n\t * @param activity The Activity notified.\n\t * @param trustPayload Trust payload to verify the requesters identity.\n\t * @returns The activity's entry.\n\t */\n\tnotifyActivity(\n\t\tactivity: IActivityStreamsActivity,\n\t\ttrustPayload?: unknown\n\t): Promise<string | IActivityLogEntry>;\n\n\t/**\n\t * Subscribes to the activity log.\n\t * @param callback The callback to be called when Activity Log is called.\n\t * @param subscriptionId The subscription Id.\n\t * @returns The subscription Id.\n\t */\n\tsubscribeToActivityLog(\n\t\tcallback: (notification: IActivityLogStatusNotification) => Promise<void>,\n\t\tsubscriptionId?: string\n\t): Promise<string>;\n\n\t/**\n\t * Unsubscribes from the activity log.\n\t * @param subscriptionId The subscription Id to remove.\n\t * @returns A promise that resolves when the subscription has been removed.\n\t */\n\tunSubscribeToActivityLog(subscriptionId: string): Promise<void>;\n\n\t/**\n\t * Returns Activity Log Entry which contains the Activity processing details.\n\t * @param logEntryId The Id of the Activity Log Entry (a URI).\n\t * @param trustPayload Trust payload to verify the requester's identity.\n\t * @returns the Activity Log Entry with the processing details.\n\t * @throws NotFoundError if activity log entry is not known.\n\t * @throws UnauthorizedError if trustPayload is absent or the verified identity is not the entry generator.\n\t */\n\tgetActivityLogEntry(logEntryId: string, trustPayload?: unknown): Promise<IActivityLogEntry>;\n\n\t/**\n\t * Get Data Asset entities. Allows to retrieve entities by their type or id.\n\t * @param entitySet The set of entities to be retrieved.\n\t * @param entitySet.jsonLdContext The JSON-LD Context to be used to expand the referred entityType.\n\t * @param consumerPid The consumer Process ID from the DSP Transfer Process.\n\t * Used to resolve datasetId from the Transfer Process.\n\t * @param cursor Pagination details - cursor.\n\t * @param limit Pagination details - max number of entities.\n\t * @param trustPayload Trust payload to verify the requesters identity.\n\t * @returns The item list and optional cursor for pagination via Link headers.\n\t */\n\tgetDataAssetEntities(\n\t\tentitySet: IEntitySet & {\n\t\t\tjsonLdContext?: IJsonLdContextDefinitionElement[];\n\t\t},\n\t\tconsumerPid: string,\n\t\tcursor?: string,\n\t\tlimit?: number,\n\t\ttrustPayload?: unknown\n\t): Promise<IDataAssetItemListResult>;\n\n\t/**\n\t * Queries a data asset controlled by this Dataspace App.\n\t * @param consumerPid The consumer Process ID from the DSP Transfer Process.\n\t * Used to resolve datasetId from the Transfer Process.\n\t * @param query The filtering query.\n\t * @param cursor Pagination details - cursor.\n\t * @param limit Pagination details - max number of entities.\n\t * @param trustPayload Trust payload to verify the requesters identity.\n\t * @returns The item list and optional cursor for pagination via Link headers.\n\t */\n\tqueryDataAsset(\n\t\tconsumerPid: string,\n\t\tquery: IFilteringQuery,\n\t\tcursor?: string,\n\t\tlimit?: number,\n\t\ttrustPayload?: unknown\n\t): Promise<IDataAssetItemListResult>;\n\n\t/**\n\t * Set up a push subscription after a transfer enters STARTED from REQUESTED.\n\t * Reads the TransferProcess, builds an IFollowActivity, calls the app's\n\t * subscribeToData, and persists a PushSubscription entity.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is created.\n\t */\n\tsetupPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Pause deliveries for a push subscription. The subscription entity stays\n\t * alive with status=Paused. No app unsubscribe call.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is paused.\n\t */\n\tsuspendPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Resume deliveries after a SUSPENDED → STARTED transition. Flips status\n\t * back to Active. No app subscribeToData call.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is resumed.\n\t */\n\tresumePushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Tear down a push subscription. Builds an IUndoActivity, calls the app's\n\t * unsubscribeToData, and deletes the PushSubscription entity.\n\t * @param consumerPid The consumer process ID identifying the transfer.\n\t * @returns Promise that resolves when the subscription is torn down.\n\t */\n\tteardownPushSubscription(consumerPid: string): Promise<void>;\n\n\t/**\n\t * Called by the app when new data is available for a follower.\n\t * The activity's `to` attribute contains the consumerPid URN. This method\n\t * looks up the matching PushSubscription, validates transfer state, and\n\t * schedules a Background Task that POSTs the activity to the consumer.\n\t * @param activity The outbound activity carrying the data payload.\n\t * @returns Promise that resolves when the delivery task is scheduled.\n\t */\n\tprocessOutboxActivity(activity: IActivityStreamsActivity): Promise<void>;\n}\n"]}

package/dist/types/factories/dataspaceAppFactory.d.ts

@@ -1,6 +1,6 @@
 import { Factory } from "@twin.org/core";
 import type { IDataspaceApp } from "../models/app/IDataspaceApp.js";
 /**
- * Factory for creating dataspace apps.
+ * Factory for registering and retrieving dataspace app instances by name.
  */
 export declare const DataspaceAppFactory: Factory<IDataspaceApp>;

package/dist/types/models/api/IActivityLogEntryGetRequest.d.ts

@@ -1,7 +1,14 @@
+import type { HeaderTypes } from "@twin.org/web";
 /**
  * Get Request for an Activity Log Entry.
  */
 export interface IActivityLogEntryGetRequest {
+    /**
+     * The headers which can be used to authenticate the requester.
+     */
+    headers?: {
+        [HeaderTypes.Authorization]?: string;
+    };
     /**
      * The parameters from the path.
      */

package/dist/types/models/api/IActivityLogEntryGetResponse.d.ts

@@ -1,6 +1,6 @@
 import type { IActivityLogEntry } from "../IActivityLogEntry.js";
 /**
- * Service Offering response
+ * Response containing a single activity log entry.
  */
 export interface IActivityLogEntryGetResponse {
     /**

package/dist/types/models/api/IActivityLogStatusNotificationPayload.d.ts

@@ -1,10 +1,10 @@
 import type { IActivityLogStatusNotification } from "../IActivityLogStatusNotification.js";
 /**
- * The status supplied to clients of the Dataspace Data Plane
+ * WebSocket push payload carrying an activity log status notification to connected clients.
  */
 export interface IActivityLogStatusNotificationPayload {
     /**
-     * Body
+     * The activity log status notification.
      */
     body: IActivityLogStatusNotification;
 }

package/dist/types/models/api/IActivityLogStatusRequest.d.ts

@@ -1,9 +1,9 @@
 /**
- * Activity log status
+ * WebSocket request to subscribe or unsubscribe from the activity log stream.
  */
 export interface IActivityLogStatusRequest {
     /**
-     * Empty body.
+     * Request body containing the subscribe or unsubscribe operation.
      */
     body: {
         /**

package/dist/types/models/controlPlane/IDataspaceControlPlaneComponent.d.ts

@@ -255,13 +255,13 @@ export interface IDataspaceControlPlaneComponent extends IComponent {
      * @param id The stored app dataset id.
      * @param appId The dataspace app this dataset belongs to.
      * @param dataset The dataset payload.
-     * @returns Nothing.
+     * @returns A promise that resolves when the dataset has been updated in storage and the catalogue.
      */
     updateAppDataset(id: string, appId: string, dataset: IDataspaceProtocolDataset): Promise<void>;
     /**
      * Delete an app dataset record owned by the calling tenant.
      * @param id The stored app dataset id.
-     * @returns Nothing.
+     * @returns A promise that resolves when the dataset has been removed from storage and the catalogue.
      */
     deleteAppDataset(id: string): Promise<void>;
 }

package/dist/types/models/dataPlane/IDataspaceDataPlaneComponent.d.ts

@@ -14,7 +14,7 @@ export interface IDataspaceDataPlaneComponent extends IComponent {
     /**
      * Notify an Activity to the Dataspace Data Plane Activity Stream.
      * @param activity The Activity notified.
-     * @param trustPayload Optional trust payload to verify the requester's identity.
+     * @param trustPayload Trust payload to verify the requesters identity.
      * @returns The activity's entry.
      */
     notifyActivity(activity: IActivityStreamsActivity, trustPayload?: unknown): Promise<string | IActivityLogEntry>;
@@ -26,18 +26,20 @@ export interface IDataspaceDataPlaneComponent extends IComponent {
      */
     subscribeToActivityLog(callback: (notification: IActivityLogStatusNotification) => Promise<void>, subscriptionId?: string): Promise<string>;
     /**
-     * Unsubscribes to the activity log.
-     * @param subscriptionId The subscription Id.
-     * @returns The subscription Id.
+     * Unsubscribes from the activity log.
+     * @param subscriptionId The subscription Id to remove.
+     * @returns A promise that resolves when the subscription has been removed.
      */
     unSubscribeToActivityLog(subscriptionId: string): Promise<void>;
     /**
      * Returns Activity Log Entry which contains the Activity processing details.
      * @param logEntryId The Id of the Activity Log Entry (a URI).
+     * @param trustPayload Trust payload to verify the requester's identity.
      * @returns the Activity Log Entry with the processing details.
      * @throws NotFoundError if activity log entry is not known.
+     * @throws UnauthorizedError if trustPayload is absent or the verified identity is not the entry generator.
      */
-    getActivityLogEntry(logEntryId: string): Promise<IActivityLogEntry>;
+    getActivityLogEntry(logEntryId: string, trustPayload?: unknown): Promise<IActivityLogEntry>;
     /**
      * Get Data Asset entities. Allows to retrieve entities by their type or id.
      * @param entitySet The set of entities to be retrieved.

package/docs/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.3-next.45](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.44...dataspace-models-v0.0.3-next.45) (2026-06-17)
+
+
+### Features
+
+* get activity log add trust payload ([#201](https://github.com/iotaledger/twin-dataspace/issues/201)) ([cdb5486](https://github.com/iotaledger/twin-dataspace/commit/cdb5486942c1b94ddf6435236b9b9d190bea0407))
+
+## [0.0.3-next.44](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.43...dataspace-models-v0.0.3-next.44) (2026-06-12)
+
+
+### Bug Fixes
+
+* always verify trust in notifyActivity, no internal by ([#192](https://github.com/iotaledger/twin-dataspace/issues/192)) ([2cfc160](https://github.com/iotaledger/twin-dataspace/commit/2cfc16082a7c9d417f0b05f90f123e40f47d1e05))
+
 ## [0.0.3-next.43](https://github.com/iotaledger/twin-dataspace/compare/dataspace-models-v0.0.3-next.42...dataspace-models-v0.0.3-next.43) (2026-06-11)
 
 

package/docs/reference/interfaces/IActivityLogEntryGetRequest.md

@@ -4,6 +4,18 @@ Get Request for an Activity Log Entry.
 
 ## Properties
 
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+The headers which can be used to authenticate the requester.
+
+#### authorization?
+
+> `optional` **authorization?**: `string`
+
+***
+
 ### pathParams {#pathparams}
 
 > **pathParams**: `object`

package/docs/reference/interfaces/IActivityLogEntryGetResponse.md

@@ -1,6 +1,6 @@
 # Interface: IActivityLogEntryGetResponse
 
-Service Offering response
+Response containing a single activity log entry.
 
 ## Properties
 

package/docs/reference/interfaces/IActivityLogStatusNotificationPayload.md

@@ -1,6 +1,6 @@
 # Interface: IActivityLogStatusNotificationPayload
 
-The status supplied to clients of the Dataspace Data Plane
+WebSocket push payload carrying an activity log status notification to connected clients.
 
 ## Properties
 
@@ -8,4 +8,4 @@ The status supplied to clients of the Dataspace Data Plane
 
 > **body**: [`IActivityLogStatusNotification`](IActivityLogStatusNotification.md)
 
-Body
+The activity log status notification.

package/docs/reference/interfaces/IActivityLogStatusRequest.md

@@ -1,6 +1,6 @@
 # Interface: IActivityLogStatusRequest
 
-Activity log status
+WebSocket request to subscribe or unsubscribe from the activity log stream.
 
 ## Properties
 
@@ -8,7 +8,7 @@ Activity log status
 
 > **body**: `object`
 
-Empty body.
+Request body containing the subscribe or unsubscribe operation.
 
 #### operation
 

package/docs/reference/interfaces/IDataspaceControlPlaneComponent.md

@@ -638,7 +638,7 @@ The dataset payload.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the dataset has been updated in storage and the catalogue.
 
 ***
 
@@ -660,4 +660,4 @@ The stored app dataset id.
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the dataset has been removed from storage and the catalogue.

package/docs/reference/interfaces/IDataspaceDataPlaneComponent.md

@@ -27,7 +27,7 @@ The Activity notified.
 
 `unknown`
 
-Optional trust payload to verify the requester's identity.
+Trust payload to verify the requesters identity.
 
 #### Returns
 
@@ -69,7 +69,7 @@ The subscription Id.
 
 > **unSubscribeToActivityLog**(`subscriptionId`): `Promise`\<`void`\>
 
-Unsubscribes to the activity log.
+Unsubscribes from the activity log.
 
 #### Parameters
 
@@ -77,19 +77,19 @@ Unsubscribes to the activity log.
 
 `string`
 
-The subscription Id.
+The subscription Id to remove.
 
 #### Returns
 
 `Promise`\<`void`\>
 
-The subscription Id.
+A promise that resolves when the subscription has been removed.
 
 ***
 
 ### getActivityLogEntry() {#getactivitylogentry}
 
-> **getActivityLogEntry**(`logEntryId`): `Promise`\<[`IActivityLogEntry`](IActivityLogEntry.md)\>
+> **getActivityLogEntry**(`logEntryId`, `trustPayload?`): `Promise`\<[`IActivityLogEntry`](IActivityLogEntry.md)\>
 
 Returns Activity Log Entry which contains the Activity processing details.
 
@@ -101,6 +101,12 @@ Returns Activity Log Entry which contains the Activity processing details.
 
 The Id of the Activity Log Entry (a URI).
 
+##### trustPayload?
+
+`unknown`
+
+Trust payload to verify the requester's identity.
+
 #### Returns
 
 `Promise`\<[`IActivityLogEntry`](IActivityLogEntry.md)\>
@@ -111,6 +117,10 @@ the Activity Log Entry with the processing details.
 
 NotFoundError if activity log entry is not known.
 
+#### Throws
+
+UnauthorizedError if trustPayload is absent or the verified identity is not the entry generator.
+
 ***
 
 ### getDataAssetEntities() {#getdataassetentities}

package/docs/reference/variables/DataspaceAppFactory.md

@@ -2,4 +2,4 @@
 
 > `const` **DataspaceAppFactory**: `Factory`\<[`IDataspaceApp`](../interfaces/IDataspaceApp.md)\>
 
-Factory for creating dataspace apps.
+Factory for registering and retrieving dataspace app instances by name.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/dataspace-models",
-	"version": "0.0.3-next.43",
+	"version": "0.0.3-next.45",
 	"description": "Defines shared entities, interfaces, and data types used by control plane and data plane components.",
 	"repository": {
 		"type": "git",