Release v10.0.0 and add documentation

.github/workflows/deploy-docs.yml

@@ -0,0 +1,35 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs/docusaurus/
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          cache: npm
+          cache-dependency-path: ./docs/
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: docs
+          publish_dir: ./docs/docusaurus/build
+          user_name: RobinTTY
+          user_email: [email protected]

.gitignore

@@ -33,6 +33,75 @@ Thumbs.db
 Desktop.ini
 .DS_Store
 
+## Web
+# ignore all files starting with . or ~
+~*
+
+# ignore node/grunt dependency directories
+node_modules/
+
+# Ignore build directories.
+/build
+/dist
+
+# ignore composer vendor directory
+/vendor
+
+# ignore components loaded via Bower
+/bower_components
+
+# ignore jekyll build directory
+/_site
+
+# ignore OS generated files
+ehthumbs.db
+Thumbs.db
+
+# ignore Editor files
+*.sublime-project
+*.sublime-workspace
+*.komodoproject
+
+# ignore log files and databases
+*.log
+*.sql
+*.sqlite
+
+# ignore compiled files
+*.com
+*.class
+*.dll
+*.exe
+*.o
+*.so
+
+# ignore packaged files
+*.7z
+*.dmg
+*.gz
+*.iso
+*.jar
+*.rar
+*.tar
+*.zip
+
+# ignore private/secret files
+*.der
+*.key
+*.pem
+
+# --------------------------------------------------------
+# BEGIN Explictly Allowed Files (i.e. do NOT ignore these)
+# --------------------------------------------------------
+
+# track these files, if they exist
+!.editorconfig
+!.env.example
+!.git-blame-ignore-revs
+!.gitignore
+!.nvmrc
+!.phpcs.xml.dist
+
 # Custom
 *.pubxml
 /src/RobinTTY.NordigenApiClient.Tests/secrets.txt

README.md

@@ -1,23 +1,24 @@
+<p align="center">
+   <img src="docs/static/img/nordigen-api-client-logo.png" width="30%">
+</p>
+
 # NordigenApiClient
 
-This project provides a C# client for
-the [GoCardless Bank Account Data API](https://gocardless.com/bank-account-data/) (formerly Nordigen API). The following
-API endpoints are supported:
+This library provides a .NET client for the [GoCardless Bank Account Data API](https://gocardless.com/bank-account-data/) (formerly Nordigen API). The following API endpoints are supported:
 
 - Token
 - Institutions
 - Agreements
 - Requisitions
 - Accounts
 
-You can find the official GoCardless documentation for the
-API [here](https://developer.gocardless.com/bank-account-data/endpoints).
+You can get started with the Quickstart Guide below or take a look at the [full documentation](https://robintty.github.io/NordigenApiClient/).
 
-## Getting started
+## Quickstart Guide
 
 1. To get started install the package via the package manager:
 
-   ```ps
+   ```powershell
    Install-Package RobinTTY.NordigenApiClient
    ```
 
@@ -29,174 +30,84 @@ API [here](https://developer.gocardless.com/bank-account-data/endpoints).
    var client = new NordigenClient(httpClient, credentials);
    ```
 
-   Note: The client will obtain the required JWT access/refresh token itself and manage it accordingly, for
-   access/refresh token reuse see the advanced section.
-
-3. You can now use the different endpoints through the client:
+3. Then we need the list of banking institutions in your country (e.g. United Kingdom)
 
    ```cs
-   var response = await client.InstitutionsEndpoint.GetInstitutions(SupportedCountry.UnitedKingdom);
+   var institutionsResponse = await client.InstitutionsEndpoint.GetInstitutions(SupportedCountry.UnitedKingdom);
+   if (institutionsResponse.IsSuccess)
+       institutionsResponse.Result.ForEach(institution =>
+       {
+           Console.WriteLine($"Institution: {institution.Name}, Id: {institution.Id}");
+       });
+   else
+       Console.WriteLine($"Couldn't retrieve institutions, error: {institutionsResponse.Error.Summary}");
    ```
 
-   The responses that are returned always have the same structure:
+4. Choose the institution your bank account is registered with and create a requisition for it:
 
    ```cs
-   // If the request was successful "Result" will contain the returned data (Error will be null)
-   if(response.IsSuccess){
-      var institutions = response.Result;
-      institutions.ForEach(institution => Console.WriteLine(institution.Name));
+   // Use the id of the bank you want to connect to here (we acquired it in the last step)
+   var institution = "BANK_OF_SCOTLAND_BOFSGBS1";
+   var redirect = new Uri("https://where-nordigen-will-redirect-after-authentication.com");
+   var requisitionResponse = await client.RequisitionsEndpoint.CreateRequisition(institution, redirect);
+
+   if (requisitionResponse.IsSuccess)
+   {
+       Console.WriteLine($"Requisition id: {requisitionResponse.Result.Id}");
+       Console.WriteLine($"Start authentication: {requisitionResponse.Result.AuthenticationLink}");
    }
-   // If the request was not successful "Error" will contain the reason it failed (Result will be null)
+
    else
-      Console.WriteLine(response.Error.Summary);
+       Console.WriteLine($"Requisition couldn't be created: {requisitionResponse.Error.Summary}");
+   ```
+
+5. You will now need to accept the end user agreement by following the authentication link you got in the last step. The authentication flow will roughly look like this:
+
+   ![authentication-flow](docs/static/img/authentication_flow.png)
+
+6. Now that you have accepted the agreement we once again need to retrieve the requisition we created in step 4. This time the response will include the accounts you are now able to access.
+
+   ```cs
+   var requisitionId = "your-requisition-id";
+   var accountsResponse = await client.RequisitionsEndpoint.GetRequisition(requisitionId);
+   if (accountsResponse.IsSuccess)
+       accountsResponse.Result.Accounts.ForEach(accountId =>
+       {
+           Console.WriteLine($"Account id: {accountId}");
+       });
+   else
+       Console.WriteLine($"Accounts couldn't be retrieved: {accountsResponse.Error.Summary}");
+   ```
+
+7. Now you can retrieve details about your bank account and the balances/transactions using the account ID(s) we just acquired:
+
+   ```cs
+   var accountId = "your-account-id";
+   var bankAccountDetailsResponse = await client.AccountsEndpoint.GetAccountDetails(accountId);
+   if (bankAccountDetailsResponse.IsSuccess)
+   {
+       Console.WriteLine($"IBAN: {bankAccountDetailsResponse.Result.Iban}");
+       Console.WriteLine($"Account name: {bankAccountDetailsResponse.Result.Name}");
+   }
+
+   var balancesResponse = await client.AccountsEndpoint.GetBalances(accountId);
+   if (balancesResponse.IsSuccess)
+       balancesResponse.Result.ForEach(balance =>
+       {
+           var balanceAmount = balance.BalanceAmount;
+           Console.WriteLine($"Type: {balance.BalanceType}");
+           Console.WriteLine($"Balance: {balanceAmount.Amount} {balanceAmount.Currency}");
+       });
+
+   var transactionsResponse = await client.AccountsEndpoint.GetTransactions(accountId);
+   if (transactionsResponse.IsSuccess)
+       transactionsResponse.Result.BookedTransactions.ForEach(transaction =>
+       {
+           var transactionAmount = transaction.TransactionAmount;
+           Console.WriteLine($"Remittance: {transaction.RemittanceInformationUnstructured}");
+           Console.WriteLine($"Booking date:{transaction.ValueDate}");
+           Console.WriteLine($"Amount: {transactionAmount.Amount} {transactionAmount.Currency}");
+       });
    ```
 
-## Getting balances and transactions for a bank account
-
-Here is how you would go about retrieving the balances and transactions for a bank account (you can find this full
-example [here](src/RobinTTY.NordigenApiClient.ExampleApplication)):
-
-1. Get a list of institutions in your country (e.g. Great Britain):
-
-    ```cs
-    var institutionsResponse = await client.InstitutionsEndpoint.GetInstitutions(SupportedCountry.UnitedKingdom);
-    if (institutionsResponse.IsSuccess)
-        institutionsResponse.Result.ForEach(institution =>
-        {
-            Console.WriteLine($"Institution: {institution.Name}, Id: {institution.Id}");
-        });
-    else
-        Console.WriteLine($"Couldn't retrieve institutions, error: {institutionsResponse.Error.Summary}");
-    ```
-
-2. Choose the institution your bank account is registered with and create a requisition for it:
-
-    ```cs
-    var institution = "BANK_OF_SCOTLAND_BOFSGBS1";
-    var redirect = new Uri("https://where-nordigen-will-redirect-after-authentication.com");
-    var requisitionResponse = await client.RequisitionsEndpoint.CreateRequisition(institution, redirect);
-
-    if (requisitionResponse.IsSuccess)
-    {
-        Console.WriteLine($"Requisition id: {requisitionResponse.Result.Id}");
-        Console.WriteLine($"Start authentication: {requisitionResponse.Result.AuthenticationLink}");
-    }
-
-    else
-        Console.WriteLine($"Requisition couldn't be created: {requisitionResponse.Error.Summary}");
-    ```
-
-3. You will now need to accept the end user agreement by following the authentication link. After that you will be able
-   to retrieve the accounts linked to your bank account:
-
-    ```cs
-    var requisitionId = "your-requisition-id";
-    var accountsResponse = await client.RequisitionsEndpoint.GetRequisition(requisitionId);
-    if (accountsResponse.IsSuccess)
-        accountsResponse.Result.Accounts.ForEach(accountId =>
-        {
-            Console.WriteLine($"Account id: {accountId}");
-        });
-    else
-        Console.WriteLine($"Accounts couldn't be retrieved: {accountsResponse.Error.Summary}");
-    ```
-
-4. Now you can retrieve details about the bank account and the balances/transactions:
-
-    ```cs
-    var accountId = "your-account-id";
-    var bankAccountDetailsResponse = await client.AccountsEndpoint.GetAccountDetails(accountId);
-    if (bankAccountDetailsResponse.IsSuccess)
-    {
-        Console.WriteLine($"IBAN: {bankAccountDetailsResponse.Result.Iban}");
-        Console.WriteLine($"Account name: {bankAccountDetailsResponse.Result.Name}");
-    }
-
-    var balancesResponse = await client.AccountsEndpoint.GetBalances(accountId);
-    if (balancesResponse.IsSuccess)
-        balancesResponse.Result.ForEach(balance =>
-        {
-            var balanceAmount = balance.BalanceAmount;
-            Console.WriteLine($"Type: {balance.BalanceType}");
-            Console.WriteLine($"Balance: {balanceAmount.Amount} {balanceAmount.Currency}");
-        });
-
-    var transactionsResponse = await client.AccountsEndpoint.GetTransactions(accountId);
-    if (transactionsResponse.IsSuccess)
-        transactionsResponse.Result.BookedTransactions.ForEach(transaction =>
-        {
-            var transactionAmount = transaction.TransactionAmount;
-            Console.WriteLine($"Remittance: {transaction.RemittanceInformationUnstructured}");
-            Console.WriteLine($"Booking date:{transaction.ValueDate}");
-            Console.WriteLine($"Amount: {transactionAmount.Amount} {transactionAmount.Currency}");
-        });
-    ```
-
-## Advanced Usage
-
-### Acess/Refresh Token reuse
-
-If you wan't to persist the access/refresh token used by the client you can do so by accessing the `JsonWebTokenPair`
-property of the client. After the first request that requires authentication this property will be populated with the
-access/refresh token that was automatically aquired.
-
-```cs
-Console.WriteLine(client.JsonWebTokenPair.AccessToken.EncodedToken);
-Console.WriteLine(client.JsonWebTokenPair.RefreshToken.EncodedToken);
-```
-
-The next time you instantiate the client you can pass the access/refresh token to the client constructor:
-
-```cs
-using var httpClient = new HttpClient();
-var credentials = new NordigenClientCredentials("my-secret-id", "my-secret-key");
-var tokenPair = new JsonWebTokenPair("encoded-access-token", "encoded-refresh-token");
-var client = new NordigenClient(httpClient, credentials, tokenPair);
-```
-
-The client will now use the given token pair and refresh it automatically if it is expired.
-
-Alternatively you can also use the tokens endpoint directly:
-
-```cs
-var response = await client.TokenEndpoint.GetTokenPair();
-if (response.IsSuccess)
-{
-    Console.WriteLine($"Access token: {response.Result.AccessToken.EncodedToken}");
-    Console.WriteLine($"Refresh token: {response.Result.RefreshToken.EncodedToken}");
-}
-
-// Set the token pair on the client
-client.JsonWebTokenPair = response.Result;
-```
-
-### Getting notified when the Access/Refresh Token is updated
-
-To get notified whenever the token pair is updated you can subscribe to the ```TokenPairUpdated``` event:
-
-```cs
-client.TokenPairUpdated += OnTokenPairUpdated;
-
-void OnTokenPairUpdated(object? sender, TokenPairUpdatedEventArgs e)
-{
-    // The event args contain the updated token
-    Console.WriteLine("Updated token pair:");
-    Console.WriteLine($"Access Token: {e.JsonWebTokenPair.AccessToken.EncodedToken}");
-    Console.WriteLine($"Refresh Token: {e.JsonWebTokenPair.RefreshToken.EncodedToken}");
-}
-```
-
-## Usage with Frameworks older than .NET 6.0
-
-If you use this library with .NET versions older than 6.0 you will receive warnings informing you that some dependencies
-of this packet don't necessarily support your chosen .NET version. The .NET Standard version of this package is tested
-against .NET Framework 4.8 and older versions (including .NET Core) should work fine as well. You can surpress these
-warnings by adding the following option to your csproj file:
-
-```xml
-<PropertyGroup>
-   ...
-   <SuppressTfmSupportBuildWarnings>true</SuppressTfmSupportBuildWarnings>
-   ...
-</PropertyGroup>
-```
+That's it! You are now able to retrieve the account details, balances and transactions of your bank account. If you wanna learn more about this library please refer to the [full documentation](https://robintty.github.io/NordigenApiClient/).