README.md

<br />
<div align="center"><img src="https://www.fitko.de/fileadmin/_processed_/b/9/csm_FIT-Connect_3e8e926015.jpg" alt="Logo" width="50%" height="50%"> </div>

> $`\textcolor{#890000}{\text{THIS SDK IS IN DEVELOPMENT AND NOT READY FOR PRODUCTION USE YET!!!}}`$

## About the FIT-Connect Java SDK

The Java SDK for FIT-Connect enables to build clients for senders and subscribers without directly interacting with any REST-Endpoints.
It provides a simple fluent API that guides through the creation and sending of a submission, as well as receiving submissions as a subscriber.

For further information, check out the official docs: [FIT-Connect Documentation](https://docs.fitko.de/fit-connect/docs/) as well as the:

* [Self-Service-Portal (Testing Environment)](https://portal.auth-testing.fit-connect.fitko.dev/)
* [FITKO project website](https://www.fitko.de/projektmanagement/fit-connect)

## **Outline**
[[TOC]]

## Getting Started

How to set up the SDK project locally.

### Build Dependencies

This section lists major frameworks/libraries used in the SDK.

* Java 11 (LTS)
* Maven 3.x
* Junit 5

Further 3rd party dependencies:

* Nimbus-Jose JWT
* Spring Web/HTTP
* Jackson FasterXMl
* JCommander
* Snakeyaml

### Prerequisites

* Java Runtime >= 11, check your current setup in your commandline
  ```sh
  java --version 
  ```
<p align="right">(<a href="#top">back to top</a>)</p>

### Add FIT-Connect SDK to your build

To add a dependency on FIT-Connect using Maven, use the following:

```xml
<dependency>
  <groupId>dev.fitko.fitconnect.sdk</groupId>
  <artifactId>client</artifactId>
  <version>[Latest Version]</version>
</dependency>
```
With `[Latest Version]` of the last stable build or snapshot.

If you use a snapshot version, please add the maven snapshot repo to your pom.
```xml
<distributionManagement>
  <snapshotRepository>
  <id>ossrh</id>
  <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </snapshotRepository>
</distributionManagement>
```

<p align="right">(<a href="#top">back to top</a>)</p>

## Modules

See the projects' module documentation for more specific information:

* [API Module ](api/README.md)
* [Core Module ](core/README.md)
* [Client Module ](client/README.md)

## Setup

_The following steps show how to get the SDK running_

1. Create and [account](https://docs.fitko.de/fit-connect/docs/getting-started/account) on the self service portal
2. Get your sender/subscriber API-key credentials
3. Clone the sdk repo
   ```sh
   git clone https://git.fitko.de/fit-connect/sdk-java
   ```
4. Build the project
   ```sh
   ./mvnw clean install -DskipTests
   ```
5. Enter your API keys and references to your private decryption key in `config.yml`
6. Provide config via environment variable ``FIT_CONNECT_CONFIG`` or load the config with
    ````java
      var config = ApplicationConfigLoader.loadConfig("absolute/path/to/config.yml");
      var senderClient = ClientFactory.senderClient(config);
      ````

<p align="right">(<a href="#top">back to top</a>)</p>

## API Usage for Sender

The fluent API client for sender and subscriber allows method chaining to guide through all necessary steps and is called via `dev.fitko.fitconnect.client.factory.ClientFactory`.

### Hand in already encrypted submission (e.g. from frontend)
If all data, metadata and attachments are encrypted outside the SDK the sender client allows to retrieve the public key for encryption as well as sending of already encrypted payloads.

> For further information on how to implement end-2-end encryption please check the [FIT-Connect documentation](https://docs.fitko.de/fit-connect/docs/getting-started/encryption).

#### 1.  Retrieve public encryption key:

```java
Optional<String> publicJwk =  ClientFactory.senderClient(config).getPublicKey(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"));
```

#### 2. Send encrypted data

```java
ClientFactory.senderClient(config)
        .newSubmissionWithEncryptedData("$encrpyt€ed d@t@")
        .withEncryptedAttachment(UUID.fromString("attachmentId"), "$encrpyt€ed @tt@chment")
        .withEncryptedJsonData("{$encrpyt€ed json}")
        .withEncryptedMetadata("$encrpyt€ed metadata")
        .withDestination(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
        .withServiceType("TestService", "Führerscheinbeantragung",  "urn:de:fim:leika:leistung:99400048079000")
        .submit();
```

### Hand in a new submission with unencrypted data

If all data, metadata and attachments are encrypted in the sender using the SDK, the client automatically handles the encryption.

Be aware that this example is not end-2-end encrypted, see [FIT-Connect documentation](https://docs.fitko.de/fit-connect/docs/getting-started/encryption) for details.

```java
ClientFactory.senderClient(config)
        .newSubmission()
        .withAttachment(Path.of("path/to/attachment.txt").toFile()) // optional
        .withJsonData("{ \"foo\" : \"bar\"}")
        .withDestination(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
        .withServiceType("TestService", "Führerscheinbeantragung",  "urn:de:fim:leika:leistung:99400048079000")
        .submit();
```
## API Usage for Subscriber

### Retrieving submissions
Submissions can be fetched by id or as a list of submissions for a specific case.
#### List with pagination
Limit and offset parameters allow to page through the result.
```java
int offset = 0;
int limit = 100;
Set<SubmissionForPickup> firstOneHundredSubmissions = ClientFactory.subscriberClient(config).getAvailableSubmissions(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"), limit, offset);
```

#### List without pagination
Listing available submissions without pagination pulls the first 500 entries.
```java
Set<SubmissionForPickup> submissions = ClientFactory.subscriberClient(config).getAvailableSubmissions(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"));
```
#### Receive single submission

```java
Optional<ReceivedSubmission> submission =  ClientFactory.subscriberClient(config).requestSubmission(UUID.fromString("submissionId"));
```

### Sending events to the event-log

In order to accept or reject a submission, the subscriber client can send events ([security-event-tokens](https://www.rfc-editor.org/rfc/rfc8417.html)) to the event-log.
For more details please see the documentation on [events](https://docs.fitko.de/fit-connect/docs/getting-started/event-log/overview) and the creation of [set-events](https://docs.fitko.de/fit-connect/docs/getting-started/event-log/set-creation).

#### Accepting a submission
If the functional review by the subscriber was positive, the submission can be accepted with an `accept-submission` event.
```java
 ClientFactory.subscriberClient(config)
                    .requestSubmission(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
                    .acceptSubmission();
```
After the accept event was sent the submission transitions into the state `deleted` and is removed.
#### Rejecting a submission
If the functional or technical review by the subscriber was negative, e.g. there is a discrepancy within the semantics of the data, the submission can be rejected with an `reject-submission` event.
The rejection takes a list of `dev.fitko.fitconnect.api.domain.model.event.problems.*` as parameter to specify the problem. 
See the Fit-Connect documentation for more details on [available (technical) problems](https://docs.fitko.de/fit-connect/docs/receiving/verification).
```java
 ClientFactory.subscriberClient(config)
                    .requestSubmission(UUID.fromString("d2d43892-9d9c-4630-980a-5af341179b14"))
                    .rejectSubmission(List.of(new new DataSchemaViolation()));
```
After the rejection event was sent the submission transitions into the state `deleted` and is removed.

<p align="right">(<a href="#top">back to top</a>)</p>

## Roadmap
- [ ] Add SET-Event handling
- [ ] Add Routing features
- [ ] Add Callback handling

See the [open issues](https://git.fitko.de/fit-connect/planning/-/boards/44?search=SDK) for a full list of proposed features (and known issues).

<p align="right">(<a href="#top">back to top</a>)</p>

<!-- CONTACT -->

## Contact

[FIT-Connect Contact Page](https://docs.fitko.de/fit-connect/contact/) for further information

<p align="right">(<a href="#top">back to top</a>)</p>


## License
Source code is licensed under the [EUPL](https://joinup.ec.europa.eu/page/eupl-text-11-12).

*Rechtlicher Hinweis: Dieses Software Development Kit (SDK) ist dazu bestimmt, die Anbindung einer Software an die FIT-Connect-Infrastruktur zu ermöglichen.
Hierfür kann das SDK in die anzubindenden Software integriert werden.
Erfolgt die Integration des SDK in unveränderter Form, liegt keine Bearbeitung im Sinne der EUPL bzw. des deutschen Urheberrechts vor.
Die Art und Weise der Verlinkung des SDK führt insbesondere nicht zur Schaffung eines abgeleiteten Werkes.
Die unveränderte Übernahme des SDK in eine anzubindende Software führt damit nicht dazu, dass die anzubindende Software unter den Bedingungen der EUPL zu lizenzieren ist.
Für die Weitergabe des SDK selbst - in unveränderter oder bearbeiteter Form, als Quellcode oder ausführbares Programm - gelten die Lizenzbedingungen der EUPL in unverände*rter Weise.

<p align="right">(<a href="#top">back to top</a>)</p>