@twin.org/dataspace-models 0.0.3-next.15

package/dist/types/models/api/control-plane/ITerminateTransferResponse.d.ts

@@ -0,0 +1,15 @@
+import type { IDataspaceProtocolTransferProcess, IDataspaceProtocolTransferError } from "@twin.org/standards-dataspace-protocol";
+import type { HttpStatusCode } from "@twin.org/web";
+/**
+ * API response for terminating a transfer process.
+ */
+export interface ITerminateTransferResponse {
+    /**
+     * Transfer Process (DSP compliant) with state TERMINATED, or error.
+     */
+    body: IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError;
+    /**
+     * HTTP status code for the response.
+     */
+    statusCode?: HttpStatusCode;
+}

package/dist/types/models/app/IActivityQuery.d.ts

@@ -0,0 +1,17 @@
+/**
+ * (Activity,Object,Target) query for denoting combinations to be handled by a Dataspace App.
+ */
+export interface IActivityQuery {
+    /**
+     * FQN of the Activity type.
+     */
+    activityType?: string;
+    /**
+     * FQN of the Object Type.
+     */
+    objectType: string;
+    /**
+     * FQN of the target type.
+     */
+    targetType?: string;
+}

package/dist/types/models/app/IDataAssetEntitiesRequest.d.ts

@@ -0,0 +1,20 @@
+import type { IDataspaceProtocolDataset } from "@twin.org/standards-dataspace-protocol";
+import type { IEntitySet } from "../IEntitySet.js";
+import type { DataRequestType } from "./dataRequestType.js";
+/**
+ * Data Request type for representing data requests received by Dataspace Apps.
+ */
+export interface IDataAssetEntitiesRequest {
+    /**
+     * Data Asset Entities type.
+     */
+    type: typeof DataRequestType.DataAssetEntities;
+    /**
+     * The data asset we are referring to.
+     */
+    dataAsset: IDataspaceProtocolDataset;
+    /**
+     * The entity set.
+     * */
+    entitySet: IEntitySet;
+}

package/dist/types/models/app/IDataAssetQuery.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Data Asset query for internal service matching of datasets to apps.
+ *
+ * This interface is used internally by the Dataspace Data Plane service to match
+ * datasets with their corresponding apps. Apps should use `datasetsHandled(): IDataset[]`
+ * to declare which datasets they handle.
+ *
+ * @see IDataspaceDataPlaneApp.datasetsHandled
+ */
+export interface IDataAssetQuery {
+    /**
+     * Id of the dataset in the Catalogue (dataset @id).
+     */
+    datasetId: string;
+}

package/dist/types/models/app/IDataRequest.d.ts

@@ -0,0 +1,6 @@
+import type { IDataAssetEntitiesRequest } from "./IDataAssetEntitiesRequest.js";
+import type { IQueryDataAssetRequest } from "./IQueryDataAssetRequest.js";
+/**
+ * Data Request type for representing data requests received by Dataspace Data Plane Apps.
+ */
+export type IDataRequest = IDataAssetEntitiesRequest | IQueryDataAssetRequest;

package/dist/types/models/app/IDataspaceApp.d.ts

@@ -0,0 +1,43 @@
+import type { IComponent } from "@twin.org/core";
+import type { IJsonLdDocument } from "@twin.org/data-json-ld";
+import type { IDataspaceProtocolDataset } from "@twin.org/standards-dataspace-protocol";
+import type { IActivityStreamsActivity } from "@twin.org/standards-w3c-activity-streams";
+import type { IActivityQuery } from "./IActivityQuery.js";
+import type { IDataRequest } from "./IDataRequest.js";
+/**
+ * Interface describes a Dataspace App.
+ */
+export interface IDataspaceApp extends IComponent {
+    /**
+     * The activities handled by the App.
+     * @returns A query that describes the set of activities handled by the App.
+     */
+    activitiesHandled(): IActivityQuery[];
+    /**
+     * The datasets handled by the App.
+     * @returns The Dataspace Protocol compliant datasets handled by the App.
+     */
+    datasetsHandled(): Promise<IDataspaceProtocolDataset[]>;
+    /**
+     * The types of queries supported.
+     * @returns The types of queries supported by the Dataspace App to retrieve data.
+     */
+    supportedQueryTypes(): string[];
+    /**
+     * Handles an Activity and report about results through the Dataspace Data Plane Callback
+     * @param activity The Activity to be handled
+     * @returns The result of executing the Activity.
+     */
+    handleActivity?<T>(activity: IActivityStreamsActivity): Promise<T>;
+    /**
+     * Handles a Data Request.
+     * @param dataRequest The data request.
+     * @param cursor Cursor that points to the next item in the result set.
+     * @param limit Maximum number of entries retrieved or to be retrieved.
+     * @returns Data as JSON-Ld.
+     */
+    handleDataRequest?(dataRequest: IDataRequest, cursor?: string, limit?: number): Promise<{
+        data: IJsonLdDocument;
+        cursor?: string;
+    }>;
+}

package/dist/types/models/app/IQueryDataAssetRequest.d.ts

@@ -0,0 +1,20 @@
+import type { IDataspaceProtocolDataset } from "@twin.org/standards-dataspace-protocol";
+import type { IFilteringQuery } from "../IFilteringQuery.js";
+import type { DataRequestType } from "./dataRequestType.js";
+/**
+ * Data Request type for representing data requests received by Dataspace Apps.
+ */
+export interface IQueryDataAssetRequest {
+    /**
+     * Data Asset Entities type.
+     */
+    type: typeof DataRequestType.QueryDataAsset;
+    /**
+     * The data asset we are referring to.
+     */
+    dataAsset: IDataspaceProtocolDataset;
+    /**
+     * Query to perform filtering.
+     */
+    query: IFilteringQuery;
+}

package/dist/types/models/app/dataRequestType.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Data Request Types.
+ */
+export declare const DataRequestType: {
+    /**
+     * Data Asset Entities
+     */
+    readonly DataAssetEntities: "DataAssetEntities";
+    /**
+     * Query over a data asset
+     */
+    readonly QueryDataAsset: "QueryDataAsset";
+};
+/**
+ * Data Request Types.
+ */
+export type DataRequestType = (typeof DataRequestType)[keyof typeof DataRequestType];

package/dist/types/models/control-plane/IDataspaceControlPlaneComponent.d.ts

@@ -0,0 +1,179 @@
+import type { IComponent } from "@twin.org/core";
+import type { IDataspaceProtocolContractNegotiation, IDataspaceProtocolContractNegotiationError, IDataspaceProtocolTransferCompletionMessage, IDataspaceProtocolTransferError, IDataspaceProtocolTransferProcess, IDataspaceProtocolTransferRequestMessage, IDataspaceProtocolTransferStartMessage, IDataspaceProtocolTransferSuspensionMessage, IDataspaceProtocolTransferTerminationMessage } from "@twin.org/standards-dataspace-protocol";
+import type { INegotiationCallback } from "./INegotiationCallback.js";
+/**
+ * Dataspace Control Plane Component interface.
+ * Implements Eclipse Dataspace Protocol (DSP) specifications:
+ * - Contract Negotiation Protocol
+ * - Transfer Process Protocol
+ *
+ * This component acts as the Control Plane for contract negotiation and
+ * data transfers between nodes in a dataspace.
+ *
+ * DSP 2025-1 Specification: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/
+ */
+export interface IDataspaceControlPlaneComponent extends IComponent {
+    /**
+     * Register a callback to receive negotiation state change notifications.
+     * Upstream modules (e.g. supply-chain) register their callback here
+     * to be notified when negotiations complete, fail, or change state.
+     * @param key A unique key identifying this callback registration.
+     * @param callback The callback interface to register.
+     */
+    registerNegotiationCallback(key: string, callback: INegotiationCallback): void;
+    /**
+     * Unregister a previously registered negotiation callback.
+     * @param key The key used when registering the callback.
+     */
+    unregisterNegotiationCallback(key: string): void;
+    /**
+     * Negotiate a contract agreement with a provider.
+     * Implements DSP Contract Negotiation Protocol.
+     *
+     * 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.
+     *
+     * This method has NO REST client implementation — it is only accessible via ComponentFactory.get().
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol
+     *
+     * @param offerId The offer ID from the provider's catalog.
+     * @param providerEndpoint The provider's contract negotiation endpoint URL.
+     * @param publicOrigin The public origin URL of this control plane (for callbacks).
+     * @param trustPayload Trust payload for authentication (JWT or Verifiable Credential).
+     * @returns The negotiation ID for tracking. Use registered callback for completion.
+     */
+    negotiateAgreement(offerId: string, providerEndpoint: string, publicOrigin: string, trustPayload: unknown): Promise<{
+        negotiationId: string;
+    }>;
+    /**
+     * Get the current state of a contract negotiation.
+     * Implements DSP Contract Negotiation Protocol.
+     *
+     * Queries the current state of an ongoing or completed negotiation.
+     * Use this to monitor negotiation progress.
+     * Returns the DSP-compliant negotiation state or error.
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/#negotiation-protocol
+     *
+     * @param negotiationId The unique identifier of the negotiation.
+     * @param trustPayload Trust payload for authentication.
+     * @returns DSP ContractNegotiation with current state, or error.
+     */
+    getNegotiation(negotiationId: string, trustPayload: unknown): Promise<IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError>;
+    /**
+     * Get negotiation history.
+     * Queries past contract negotiations for audit trails and debugging.
+     *
+     * Returns a list of past negotiations with their states and metadata.
+     * Supports optional filtering by state and pagination via cursor.
+     *
+     * @param state Optional filter by negotiation state (e.g., "FINALIZED", "TERMINATED").
+     * @param cursor Optional pagination cursor for fetching next page.
+     * @param trustPayload Trust payload for authentication.
+     * @returns List of negotiation history entries with pagination cursor.
+     */
+    getNegotiationHistory(state: string | undefined, cursor: string | undefined, trustPayload: unknown): Promise<{
+        negotiations: {
+            negotiation: IDataspaceProtocolContractNegotiation | IDataspaceProtocolContractNegotiationError;
+            createdAt: string;
+            offerId?: string;
+            agreementId?: string;
+        }[];
+        cursor?: string;
+        count: number;
+    }>;
+    /**
+     * Request a Transfer Process.
+     * Creates a new Transfer Process in REQUESTED state.
+     *
+     * Role Performed: Provider
+     * Called by: Consumer when it wants to request a new Transfer Process
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-request-message
+     *
+     * @param request Transfer request message (DSP compliant) containing agreementId,
+     * consumerPid, callbackAddress, and format.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * The consumer must prove their identity by providing a valid trust payload.
+     * @returns Transfer Process (DSP compliant) with state REQUESTED, including
+     * both consumerPid and providerPid, or TransferError if the operation fails.
+     */
+    requestTransfer(request: IDataspaceProtocolTransferRequestMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Start a Transfer Process.
+     * Transitions Transfer Process from REQUESTED to STARTED state, or resumes from SUSPENDED state.
+     *
+     * Role Performed: Provider / Consumer
+     * Called by: Provider when a Transfer Process starts, or Consumer to attempt to start a Transfer Process after it has been suspended
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-start-message
+     *
+     * @param message Transfer start message (DSP compliant).
+     * @param publicOrigin The public origin URL of this service (used to construct data plane endpoint for PULL transfers).
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns Transfer Start Message (DSP compliant) with dataAddress for PULL transfers, or TransferError if the operation fails.
+     */
+    startTransfer(message: IDataspaceProtocolTransferStartMessage, publicOrigin: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferStartMessage | IDataspaceProtocolTransferError>;
+    /**
+     * Complete a Transfer Process.
+     * Transitions Transfer Process to COMPLETED state.
+     *
+     * Role Performed: Consumer / Provider
+     * Called by: Provider or Consumer when a Transfer process is completed on their side
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-completion-message
+     *
+     * @param message Transfer completion message (DSP compliant).
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns Transfer Process (DSP compliant) with state COMPLETED, or TransferError if the operation fails.
+     */
+    completeTransfer(message: IDataspaceProtocolTransferCompletionMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Suspend a Transfer Process.
+     * Transitions Transfer Process to SUSPENDED state.
+     *
+     * Role Performed: Consumer / Provider
+     * Called by: Provider or Consumer when a Transfer process needs to be temporarily suspended on their side
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-suspension-message
+     *
+     * @param message Transfer suspension message (DSP compliant) with optional reason.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns Transfer Process (DSP compliant) with state SUSPENDED, or TransferError if the operation fails.
+     */
+    suspendTransfer(message: IDataspaceProtocolTransferSuspensionMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Terminate a Transfer Process.
+     * Transitions Transfer Process to TERMINATED state.
+     *
+     * Role Performed: Consumer / Provider
+     * Called by: Provider or Consumer when a Transfer process needs to be terminated on their side (e.g., due to error)
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#transfer-termination-message
+     *
+     * @param message Transfer termination message (DSP compliant) with optional reason.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns Transfer Process (DSP compliant) with state TERMINATED, or TransferError if the operation fails.
+     */
+    terminateTransfer(message: IDataspaceProtocolTransferTerminationMessage, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+    /**
+     * Get Transfer Process State.
+     * Query the current state of a Transfer Process.
+     *
+     * Role Performed: Consumer / Provider
+     * Called by: Provider or Consumer when they need to check the status of a Transfer process on their side
+     *
+     * Supports role-agnostic lookup using either consumerPid or providerPid.
+     * The service will automatically detect which role the caller is acting as
+     * (Consumer or Provider) based on the PID provided.
+     *
+     * DSP Spec: https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/#ack-transfer-process
+     *
+     * @param pid The Process ID (consumerPid or providerPid) used to identify the transfer.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * @returns Transfer Process (DSP compliant) with current state, or TransferError if the operation fails.
+     */
+    getTransferProcess(pid: string, trustPayload: unknown): Promise<IDataspaceProtocolTransferProcess | IDataspaceProtocolTransferError>;
+}

package/dist/types/models/control-plane/IDataspaceControlPlaneResolverComponent.d.ts

@@ -0,0 +1,55 @@
+import type { IComponent } from "@twin.org/core";
+import type { ITransferContext } from "./ITransferContext.js";
+/**
+ * Dataspace Control Plane Resolver Component interface.
+ * Provides methods for resolving transfer process information.
+ * Used by dataspace-data-plane to retrieve dataset and policy information for data access.
+ *
+ * These methods are NOT part of the Eclipse Dataspace Protocol specification.
+ * They are TWIN-specific extensions for internal service communication.
+ *
+ * IMPORTANT: This interface has NO REST client implementation - methods are only
+ * accessible via ComponentFactory.get() for local, in-process service access.
+ */
+export interface IDataspaceControlPlaneResolverComponent extends IComponent {
+    /**
+     * Resolve consumerPid to Transfer Context.
+     * Returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     * Validates that Agreement assigner matches current organization ID for security.
+     * This method is called by the dataspace-data-plane to resolve a consumerPid
+     * to the corresponding Agreement and dataset information for data retrieval (pull mode).
+     *
+     * This method is only available via ComponentFactory.get().
+     * There is no REST client implementation.
+     *
+     * @param consumerPid Consumer Process ID from the transfer request.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * The trust service handles verification and extracts identity and token.
+     * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     * @throws NotFoundError if Transfer Process not found.
+     * @throws UnauthorizedError if trust verification fails or Agreement assigner doesn't match current organization.
+     * @throws GeneralError if Transfer Process is terminated or Agreement lookup fails.
+     */
+    resolveConsumerPid(consumerPid: string, trustPayload: unknown): Promise<ITransferContext>;
+    /**
+     * Resolve providerPid to Transfer Context.
+     * Returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     * Used for push mode data transfer where Provider needs to push data to Consumer via Activity Stream.
+     * Validates that Agreement assigner matches current organization ID and assignee matches expected consumer for security.
+     *
+     * This method is called by the Provider's dataspace-data-plane when it receives an Activity
+     * referencing a providerPid and needs to resolve it to get Agreement, dataset, and consumer's dataAddress.
+     *
+     * This method is only available via ComponentFactory.get().
+     * There is no REST client implementation.
+     *
+     * @param providerPid Provider Process ID from the transfer process.
+     * @param trustPayload Trust payload containing authorization information (JWT, VC, etc.).
+     * The trust service handles verification and extracts identity and token.
+     * @returns Transfer Context with Agreement, datasetId, and Transfer Process metadata.
+     * @throws NotFoundError if Transfer Process not found.
+     * @throws UnauthorizedError if trust verification fails, Agreement assigner doesn't match current organization, or assignee doesn't match expected consumer.
+     * @throws GeneralError if Transfer Process is terminated or Agreement lookup fails.
+     */
+    resolveProviderPid(providerPid: string, trustPayload: unknown): Promise<ITransferContext>;
+}

package/dist/types/models/control-plane/INegotiationCallback.d.ts

@@ -0,0 +1,37 @@
+import type { DataspaceProtocolContractNegotiationStateType } from "@twin.org/standards-dataspace-protocol";
+import type { IOdrlAgreement, IOdrlOffer } from "@twin.org/standards-w3c-odrl";
+/**
+ * Callback interface for negotiation state change notifications.
+ * Upstream modules register an implementation of this interface
+ * via IDataspaceControlPlaneComponent.registerNegotiationCallback()
+ * to be notified when PNP callbacks fire.
+ */
+export interface INegotiationCallback {
+    /**
+     * Called when the negotiation state changes (offer received, agreement received).
+     * @param negotiationId The negotiation ID.
+     * @param state The new state.
+     * @param data Optional data associated with the state change.
+     * @param data.offer The offer received from the provider.
+     * @param data.agreement The agreement received from the provider.
+     * @returns Nothing.
+     */
+    onStateChanged(negotiationId: string, state: DataspaceProtocolContractNegotiationStateType, data?: {
+        offer?: IOdrlOffer;
+        agreement?: IOdrlAgreement;
+    }): Promise<void>;
+    /**
+     * Called when the negotiation completes successfully (finalized).
+     * @param negotiationId The negotiation ID.
+     * @param agreementId The agreement ID (from agreement.uid).
+     * @returns Nothing.
+     */
+    onCompleted(negotiationId: string, agreementId: string): Promise<void>;
+    /**
+     * Called when the negotiation fails (terminated or stalled).
+     * @param negotiationId The negotiation ID.
+     * @param reason The failure reason.
+     * @returns Nothing.
+     */
+    onFailed(negotiationId: string, reason: string): Promise<void>;
+}

package/dist/types/models/control-plane/ITransferContext.d.ts

@@ -0,0 +1,52 @@
+import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolDataAddress } from "@twin.org/standards-dataspace-protocol";
+import type { IOdrlAgreement } from "@twin.org/standards-w3c-odrl";
+/**
+ * Transfer Context data structure.
+ * Contains all information needed by DSC to execute queries.
+ * This is NOT part of the DSP protocol - it's a TWIN internal API
+ * used by dataspace-control-plane to resolve consumerPid to datasetId and policies.
+ */
+export interface ITransferContext {
+    /**
+     * Consumer Process ID.
+     */
+    consumerPid: string;
+    /**
+     * Provider Process ID.
+     */
+    providerPid: string;
+    /**
+     * Agreement associated with this Transfer Process.
+     * Contains permissions, obligations, and prohibitions that DSC uses for runtime policy enforcement.
+     */
+    agreement: IOdrlAgreement;
+    /**
+     * Dataset ID - what the DSC needs to execute the query.
+     * Convenience field extracted from agreement.target for quick access.
+     */
+    datasetId: string;
+    /**
+     * Offer ID.
+     */
+    offerId: string;
+    /**
+     * Current Transfer Process state.
+     * DSC should only allow queries if state is STARTED.
+     */
+    state: DataspaceProtocolTransferProcessStateType;
+    /**
+     * Consumer identity (for auditing).
+     */
+    consumerIdentity?: string;
+    /**
+     * Provider identity (for auditing).
+     * Extracted from Agreement's assigner field.
+     */
+    providerIdentity?: string;
+    /**
+     * Data address for push mode transfers.
+     * Contains endpoint information where data should be pushed (for Activity Stream push mode).
+     * Only present when format is Http-Push-Activity-Stream-Format or Http-Post-Activity-Stream-Format.
+     */
+    dataAddress?: IDataspaceProtocolDataAddress;
+}

package/dist/types/models/control-plane/ITransferProcess.d.ts

@@ -0,0 +1,81 @@
+import type { DataspaceProtocolTransferProcessStateType, IDataspaceProtocolDataAddress } from "@twin.org/standards-dataspace-protocol";
+import type { IOdrlPolicy } from "@twin.org/standards-w3c-odrl";
+/**
+ * Transfer Process for internal storage.
+ * Combines DSP protocol fields with internal TWIN fields.
+ * This is NOT the DSP wire format (use ITransferProcess from standards for that).
+ */
+export interface ITransferProcess {
+    /**
+     * Internal UUID (primary key for entity storage).
+     */
+    id: string;
+    /**
+     * Consumer Process ID from the DSP protocol.
+     * Refers to the transfer identifier on the Consumer side.
+     */
+    consumerPid: string;
+    /**
+     * Provider Process ID from the DSP protocol.
+     * Refers to the transfer identifier on the Provider side.
+     */
+    providerPid: string;
+    /**
+     * Transfer Process state from the DSP protocol.
+     * One of: REQUESTED, STARTED, COMPLETED, SUSPENDED, TERMINATED.
+     */
+    state: DataspaceProtocolTransferProcessStateType;
+    /**
+     * Agreement ID linking to the rights-management Agreement.
+     * Used to resolve policies and permissions.
+     */
+    agreementId: string;
+    /**
+     * Dataset ID for DSC resolution.
+     * Identifies the dataset being transferred.
+     */
+    datasetId: string;
+    /**
+     * Offer ID from the original Catalog offer.
+     */
+    offerId: string;
+    /**
+     * Policies from the Agreement.
+     * Used by DSC for runtime policy enforcement.
+     */
+    policies?: IOdrlPolicy[];
+    /**
+     * Consumer identity (DID or URI).
+     * Used for auditing and access control.
+     */
+    consumerIdentity?: string;
+    /**
+     * Provider identity (DID or URI).
+     * Used for auditing.
+     */
+    providerIdentity?: string;
+    /**
+     * Callback address for Consumer notifications.
+     * URI where messages to the Consumer should be sent.
+     */
+    callbackAddress?: string;
+    /**
+     * Data format from the Dataset Distribution.
+     * Specified by a Distribution for the Dataset associated with the Agreement.
+     */
+    format?: string;
+    /**
+     * Data address for push mode transfers.
+     * Contains endpoint information where data should be pushed (for Activity Stream push mode).
+     * Only present when format is Http-Push-Activity-Stream-Format or Http-Post-Activity-Stream-Format.
+     */
+    dataAddress?: IDataspaceProtocolDataAddress;
+    /**
+     * Creation timestamp.
+     */
+    dateCreated: Date;
+    /**
+     * Last update timestamp.
+     */
+    dateModified: Date;
+}

package/dist/types/models/control-plane/api/ITransferContextResponse.d.ts

@@ -0,0 +1,12 @@
+import type { ITransferContext } from "../ITransferContext.js";
+/**
+ * Transfer Context Response (INTERNAL API for DSC).
+ * This is NOT part of the DSP protocol - it's a TWIN internal API
+ * used by dataspace-control-plane to resolve consumerPid to datasetId and policies.
+ */
+export interface ITransferContextResponse {
+    /**
+     * Request body
+     */
+    body: ITransferContext;
+}

package/dist/types/models/control-plane/transferProcessRole.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The role of a participant in a Transfer Process.
+ * Determines whether the party is acting as Consumer or Provider.
+ */
+export declare const TransferProcessRole: {
+    /**
+     * Consumer role - the party requesting data.
+     */
+    readonly Consumer: "consumer";
+    /**
+     * Provider role - the party providing data.
+     */
+    readonly Provider: "provider";
+};
+/**
+ * Type for TransferProcessRole values.
+ */
+export type TransferProcessRole = (typeof TransferProcessRole)[keyof typeof TransferProcessRole];