# Mediator

> Enables participants to connect and authenticate with mediators, such as the DIDComm mediator, to send messages and connection offers. Mediator does not store permanently the messages and the content is not visible to the mediator.

## Install Dependency

Package: meeting_place_mediator

```bash
dart pub add meeting_place_mediator
```

Check the latest version on the [pub.dev registry](https://pub.dev/packages/meeting_place_mediator) or view the source on [GitHub](https://github.com/affinidi/affinidi-meetingplace-sdk-dart/tree/main/packages/meeting_place_mediator).

## Classes and Methods

### MeetingPlaceMediatorSDK

The MeetingPlaceMediatorSDK provides a high-level API for interacting with a DIDComm mediator in Meeting Place. It supports authenticating with a mediator, managing access control lists (ACL), creating and retrieving Out-Of-Band (OOB) invitations, sending and receiving DIDComm messages, and subscribing to message streams. The SDK abstracts DIDComm v2.1 protocol details, making it easy to build secure, privacy-preserving messaging and connection flows.

To create an instance of the MeetingPlaceMediatorSDK, use its generative constructor.

```dart
final mediatorSDK = MeetingPlaceMediatorSDK(
    mediatorDid: 'did:web:mediator.example.com:.well-known',
    didResolver: didResolver,
);
```

#### authenticateWithDid

Authenticates to a mediator instance using the provided DID manager.
This method establishes an authenticated session with the mediator. If a valid session already exists in the internal cache for the same DID manager and mediator combination, the cached session client will be returned instead of creating a new one.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

    forceNewSession
    bool
    Optional
  When true, creates a new authenticated session even if a cached session exists for this DID and mediator combination. Defaults to false.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// Authenticate with the mediator using the DID manager.
final MediatorClient session = await mediatorSDK.authenticateWithDid(
    didManager,
    mediatorDid: '', // Optional, uses SDK default if not provided.
);
```

#### updateAcl

Updates the Access Control List (ACL) for a specific owner on the mediator instance.
This method modifies the ACL permissions for the specified owner’s DID by sending the provided ACL payload to the mediator.
The ACL determines which entities have access to the owner’s resources and what operations they are permitted to perform.

Parameters

    ownerDidManager
    DidManager
    Required
  The DidManager instance representing the owner whose ACL should be updated.

    acl
    AclBody
    Required
  The ACL payload containing the permission changes to apply. Supported action types: AccessListAdd (grants new permissions) and AccessListRemove (revokes existing permissions).

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

// Prepare the owner's DID manager
final DidManager ownerDidManager = /* your DidManager instance */;

// Create an ACL body with permissions
final AclBody acl = AclBody(
    // Example: Grant access to specific entities
    // Replace with actual ACL structure from your implementation
);

// Update the ACL for the owner
await mediatorSDK.updateAcl(
    ownerDidManager: ownerDidManager,
    acl: acl
);
```

#### createOob

Allows a client to create an Out-Of-Band invitation in the mediator, resulting not only in an OOB ID but also in a complete OOB invitation URL that can be shared with other parties to initiate DIDComm interactions.

Parameters

    oobDidManager
    DidManager
    Required
  Responsible for managing out-of-band (OOB) DID exchanges.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager oobDidManager = /* your DidManager instance */;

// Create an Out-Of-Band invitation
final Uri oobUri = await mediatorSDK.createOob(
    oobDidManager
);
```

#### getOob

Allows a client to retrieve the OOB details from the mediator. This method fetches the Out-Of-Band invitation associated with the provided OOB URL, enabling the client to process and utilize the invitation for DIDComm interactions.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    oobUrl
    Uri
    Required
  Carries an out-of-band invitation used to initiate DIDComm interactions outside the normal communication channel, often shared via QR code.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// The OOB URL you want to retrieve (e.g., received via QR code or shared link)
final Uri oobUrl = Uri.parse('');

// Retrieve the OOB invitation details
final OobInvitationMessage oobInvitation = await mediatorSDK.getOob(
    oobUrl,
    didManager: didManager,
);
```

#### subscribeToMessages

Subscribes to incoming messages from the mediator.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final DidManager didManager = /* your DidManager instance */;
final mediatorDid = '';

final MediatorChannel channel = await mediatorSDK.subscribeToMessages(
    didManager,
    mediatorDid
);
```

#### listenForMessages

Subscribes to incoming messages from the mediator and executes registered listeners based on message type.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final DidManager didManager = /* your DidManager instance */;
final mediatorDid = '';

final MediatorChannel channel = await mediatorSDK.listenForMessages(
    didManager,
    mediatorDid
);
```

#### sendMessage

Encrypts and signs the message using the sender’s DID, then sends it to recipientDidDocument via DIDComm.

#### sendMessage

Encrypts and signs the message using the sender’s DID, then sends it to recipientDidDocument via DIDComm.

Parameters

    recipientDidDocument
    DidDocument
    Required
  DID document that contains the recipient agent’s public keys, service endpoints, and routing information required to securely receive, decrypt, and respond to DIDComm messages.

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';
import 'package:didcomm/didcomm.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager senderDidManager = /* your sender DidManager instance */;
final DidDocument recipientDidDocument = /* recipient's DidDocument */;

// Create a PlainTextMessage
final PlainTextMessage message = PlainTextMessage(
    id: 'message-id-123',
    body: {'text': 'Hello, this is a test message!'},
    // ...other required fields
);

// Send the message
await mediatorSDK.sendMessage(
    message,
    senderDidManager: senderDidManager,
    recipientDidDocument: recipientDidDocument,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    ephemeral: false, // Optional, defaults to false
    forwardExpiryInSeconds: 3600, // Optional, 1 hour expiry
  );
```

#### queueMessage

Stores incoming DIDComm messages to manage the sending process efficiently, ensuring messages are properly handled and dispatched.

Parameters

    recipientDidDocument
    DidDocument
    Required
  DID document that contains the recipient agent’s public keys, service endpoints, and routing information required to securely receive, decrypt, and respond to DIDComm messages.

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';
import 'package:didcomm/didcomm.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager senderDidManager = /* your sender DidManager instance */;
final DidDocument recipientDidDocument = /* recipient's DidDocument */;

// Create a PlainTextMessage
final PlainTextMessage message = PlainTextMessage(
    id: 'message-id-123',
    body: {'text': 'Hello, this is a test message!'},
    // ...other required fields
);

// Queue the message for later delivery
await mediatorSDK.queueMessage(
    message,
    senderDidManager: senderDidManager,
    recipientDidDocument: recipientDidDocument,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    ephemeral: false, // Optional, defaults to false
    forwardExpiryInSeconds: 3600, // Optional, 1 hour expiry
);
```

#### fetchMessages

Retrieves available messages from the specified mediator instance.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

    deleteOnRetrieve
    Boolean
    Required
  Boolean flag indicating whether messages should be deleted upon retrieval.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// Fetch messages from the mediator
final List messages = await mediatorSDK.fetchMessages(
    didManager: didManager,
    mediatorDid: 'did:example:mediator', // Optional, uses SDK default if not provided
    startFrom: DateTime.now().subtract(Duration(hours: 24)), // Optional, fetch from last 24 hours
    fetchMessagesBatchSize: 50, // Optional, limit batch size
    deleteOnRetrieve: false, // Optional, keep messages on mediator after fetch
    deleteFailedMessages: true, // Optional, delete messages that failed to process
);
```

#### deleteMessages

Deletes stored messages from the mediator’s queue, removing them permanently after they have been retrieved or are no longer needed.

Parameters

    didManager
    DidManager
    Required
  The DidManager instance used for authentication with the mediator and contains the identity credentials needed for the session.

    messageHashes
    List<String>
    Required
  List of cryptographic hashes representing stored messages, used to verify and track messages without exposing their content.

    mediatorDid
    String
    Optional
  Optional mediator DID to authenticate against. If not provided, the SDK instance’s default mediator DID will be used.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';
import 'package:ssi/ssi.dart';

final MeetingPlaceMediatorSDK mediatorSDK = /* your MeetingPlaceMediatorSDK instance */;

final DidManager didManager = /* your DidManager instance */;

// List of message hashes you want to delete
final List messageHashes = [
    'hash1234567890abcdef',
    'hash0987654321fedcba',
    // Add more message hashes as needed
];

// Delete the specified messages from the mediator
await mediatorSDK.deletedMessages(
    didManager: didManager,
    messageHashes: messageHashes
);
```

#### getMediatorDidFromUrl

Fetches the Mediator DID from a mediator’s endpoint.

Parameters

    mediatorEndpoint
    String
    Required
  Specifies the URL or address of the mediator service used to route and manage DIDComm messages.

Example

```dart
import 'package:meeting_place_mediator/meeting_place_mediator.dart';

final mediatorEndpoint = 'https://mediator.example.com/endpoint';

final String? mediatorDid = await mediatorSDK.getMediatorDidFromUrl(mediatorEndpoint);
```