fix: ConfigureAwait all he things for older consumers

Author: Antaris

apps/IssuuSDK.ConsoleSample/Program.cs

@@ -1,4 +1,54 @@
 // This work is licensed under the terms of the MIT license.
 // For a copy, see <https://opensource.org/licenses/MIT>.
 
-Console.WriteLine("Hello, World!");
+using System.Net.Http.Headers;
+
+using IssuuSDK;
+using IssuuSDK.Api;
+
+using Microsoft.Extensions.Configuration;
+
+var settings = GetSettings();
+var http = CreateHttpClient();
+var api = new IssuuApiClient(http, settings);
+
+var drafts = await api.Drafts.GetDraftsAsync().ConfigureAwait(false);
+
+var doc = await api.Publications.GetPublicationAsync("xryumedetev").ConfigureAwait(false);
+if (doc.IsSuccess)
+{
+	//var assets = await api.Publications.GetPublicationAssetsAsync("xryumedetev", AssetType.Cover, documentPageNumber: 3).ConfigureAwait(false);
+	//if (assets.IsSuccess)
+	//{
+
+	//}
+
+	var fullScreen = await api.Publications.GetPublicationFullScreenShareAsync(doc.Data!.Slug).ConfigureAwait(false);
+	var reader = await api.Publications.GetPublicationReaderShareAsync(doc.Data.Slug).ConfigureAwait(false);
+	var qrCode = await api.Publications.GetPublicationQrCodeAsync(doc.Data.Slug).ConfigureAwait(false);
+	var embed = await api.Publications.GetPublicationEmbedAsync(doc.Data.Slug).ConfigureAwait(false);
+}
+
+IssuuSettings GetSettings()
+{
+	var configuration = new ConfigurationBuilder()
+		.AddJsonFile("./appsettings.json", optional: false)
+		.AddJsonFile("./appsettings.env.json", optional: true)
+		.Build();
+
+	IssuuSettings settings = new();
+	configuration.GetSection(IssuuSettings.ConfigurationSection).Bind(settings);
+
+	settings.Validate();
+
+	return settings;
+}
+
+HttpClient CreateHttpClient()
+{
+	var http = new HttpClient();
+
+	http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+	return http;
+}

docs/docs/publications/_category_.json

@@ -0,0 +1,9 @@
+{
+    "label": "Publications",
+    "position": 7,
+    "link": {
+      "type": "generated-index",
+      "description": "Working with Issuu published documents."
+    }
+  }
+  

docs/docs/publications/getting-publications.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 1
+tags: [Publication, Document]
+---
+
+# Getting a list of publications
+
+This page discusses how to read a list of publications on Issuu
+
+### Getting a list of publications
+
+:::tip[Issuu API]
+
+This method corresponds to calling `HTTP GET https://api.issuu.com/v2/publications`.<br />
+API documentation: https://api.issuu.com/v2/reference/#get-/publications
+
+:::
+
+To read a list of published documents, we can use the `Publications.GetPublicationsAsync` operation. This operation will return a page of a set of documents.
+
+```csharp
+public async Task ReadPublishedDocuments(int page = 1, int size = 10, CancellationToken ct)
+{
+    var response = await _client.Publications.GetPublicationsAsync(page, size ct);
+    if (response.IsSuccess && response.Data is { Length: >0 })
+    {
+        var documents = response.Data;
+        // Do something with the documents.
+    }
+}
+```
+
+If the response is successful, the `Meta` property should be populated with additional paging information. You can use this to determine if you can read any other pages of information.
+
+:::tip[Paging Defaults]
+
+The following defaults are used for `page` and `size` if you do not provide them:
+
+| Parameter | Type | Default |
+|---|---|---|
+| `page` | `int` | 1 |
+| `size` | `int` |  10 |
+
+:::

docs/docs/requests-and-responses.md

@@ -19,6 +19,119 @@ You'd still need to use `IssuuRequest` for sending payload data where that paylo
 
 :::
 
+### Mapping HTTP responses
+
+A mapping delegate, `MapResponse<TResponse>` is provided for passing mapping functions to the `FetchAsync` code API. This is defined as:
+
+```csharp
+public delegate Task<MappedResponse<TResponse>> MapResponse<TResponse>(
+    HttpResponseMessage response, CancellationToken cancellationToken);
+```
+
+The mapping delegate must accept a HTTP response message, and return a `MappedResponse<TResponse>`, which will contain the result data, and any additional metadata and links.
+
+Example: 
+
+```csharp
+async Task<MappedResult<Document[]>> MapAsync(HttpResponse response, CancellationToken ct)
+{
+    DataContainer<TResponse>? data = default;
+    Meta? meta = default;
+    Dictionary<string, string>? links = default;
+    if (response.Content is not null)
+    {
+        data = await response.Content.ReadFromJsonAsync<DataContainer<TResponse>>(
+            _deserializerOptions, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (data is not null)
+        {
+            if (data.Count.HasValue && data.PageSize.HasValue)
+            {
+                meta = new()
+                {
+                    PageSize = data.PageSize.Value,
+                    TotalItems = data.Count.Value,
+                    TotalPages = (int)Math.Ceiling(data.Count.Value / (double)data.PageSize.Value)
+                };
+            }
+
+            if (data.Links is { Count: > 0 })
+            {
+                links = new();
+                foreach (var link in data.Links)
+                {
+                    links.Add(link.Key, link.Value.Href);
+                }
+            }
+        }
+    }
+}
+
+var request = new IssuuRequest(...);
+await client.FetchAsync<Document>(
+    request,
+    $"/drafts",
+    MapAsync,
+    cancellationToken);
+)
+```
+
+:::tip[Only Success Results]
+
+You do not need to worry about mapping an error response from the Issuu API, as the IssuuSDK will handle this automatically. When your mapping delegate is called, this is for a success HTTP status code
+
+:::
+
+Internally, the IssuuSDK makes use of this approach combined with specific container types which can be deserialized from the JSON responses.
+
+#### `DataContainer<TResult>` container type
+
+This container type is used when returning set operations, where `TResult` is the array of the intended type:
+
+| Property | Type | Notes |
+|---|---|---|
+| `Count` | `int?` | The total number of items |
+| `PageSize` | `int?` | The size of the page |
+| `Results` | `TData?` | The data |
+| `Links` | `Dictionary<string, LinkContainer>?` | The set of links for the resource |
+
+For example, when using the `Drafts.GetDraftsAsync(...)` operation, internally a `DataContainer<Document[]>` is used which returns a set of documents.
+
+:::info[Single Results]
+
+The `DataContainer<T>` type is only used for results that return sets of data. For individual result instances, such as a single document, the JSON result is directly deserialized, not in a wrapping type.
+
+:::
+
+#### `LinkContainer` container type
+
+This container type is used to deserialize a link:
+
+This container type is used to deserialzie a specific error message:
+
+| Property | Type | Notes |
+|---|---|---|
+| `Href` | `string` | The error message |
+
+#### `ErrorContainer` container type
+
+This container type is used to deserialize an error response:
+
+| Property | Type | Notes |
+|---|---|---|
+| `Fields` | `Dictionary<string, ErrorMessageContainer>?` | The set of field errors |
+| `Details` | `Dictionary<string, ErrorMessageContainer>?` | The set of specific error details |
+| `Message` | `string` | The error message |
+
+#### `ErrorMessageContainer` container type
+
+This container type is used to deserialzie a specific error message:
+
+| Property | Type | Notes |
+|---|---|---|
+| `Message` | `string` | The error message |
+
 ### HTTP GET example - returning a single resource
 
 ```csharp

libs/IssuuSDK/Api/DraftOperations.cs

@@ -137,7 +137,7 @@ public async Task<IssuuResponse<Document>> CreateDraftAsync(
 	{
 		var request = new IssuuRequest<Draft>(HttpMethod.Post, path, draft);
 
-		return await client.FetchSingleAsync<Draft, Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Draft, Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse> DeleteDraftAsync(
@@ -148,7 +148,7 @@ public async Task<IssuuResponse> DeleteDraftAsync(
 
 		var request = new IssuuRequest(HttpMethod.Delete, path + $"/{slug}");
 
-		return await client.SendAsync(request, cancellationToken);
+		return await client.SendAsync(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document>> GetDraftAsync(
@@ -159,7 +159,7 @@ public async Task<IssuuResponse<Document>> GetDraftAsync(
 
 		var request = new IssuuRequest(HttpMethod.Get, path + $"/{slug}");
 
-		return await client.FetchSingleAsync<Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document[]>> GetDraftsAsync(
@@ -169,7 +169,7 @@ public async Task<IssuuResponse<Document[]>> GetDraftsAsync(
 	{
 		var request = new IssuuRequest(HttpMethod.Get, path, page: page, size: size);
 
-		return await client.FetchManyAsync<Document[]>(request, cancellationToken);
+		return await client.FetchManyAsync<Document[]>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<PublishResult>> PublishDraftAsync(
@@ -192,7 +192,7 @@ public async Task<IssuuResponse<PublishResult>> PublishDraftAsync(
 				DesiredName = desiredName
 			});
 
-		return await client.FetchSingleAsync<PublishRequest, PublishResult>(request, cancellationToken);
+		return await client.FetchSingleAsync<PublishRequest, PublishResult>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document>> UpdateDraftAsync(
@@ -204,7 +204,7 @@ public async Task<IssuuResponse<Document>> UpdateDraftAsync(
 
 		var request = new IssuuRequest<Draft>(new HttpMethod("PATCH"), path + $"/{slug}", draft);
 
-		return await client.FetchSingleAsync<Draft, Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Draft, Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document>> UploadDocumentContentAsync(
@@ -227,7 +227,7 @@ public async Task<IssuuResponse<Document>> UploadDocumentContentAsync(
 			fileName: fileName,
 			filePath: filePath);
 
-		return await client.FetchSingleAsync<Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document>> UploadDocumentContentAsync(
@@ -251,6 +251,6 @@ public async Task<IssuuResponse<Document>> UploadDocumentContentAsync(
 			fileName: fileName,
 			fileStream: fileStream);
 
-		return await client.FetchSingleAsync<Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 }

libs/IssuuSDK/Api/PublicationOperations.cs

@@ -137,7 +137,7 @@ public async Task<IssuuResponse> DeletePublicationAsync(
 
 		var request = new IssuuRequest(HttpMethod.Delete, path + $"/{slug}");
 
-		return await client.SendAsync(request, cancellationToken);
+		return await client.SendAsync(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document>> GetPublicationAsync(
@@ -148,7 +148,7 @@ public async Task<IssuuResponse<Document>> GetPublicationAsync(
 
 		var request = new IssuuRequest(HttpMethod.Get, path + $"/{slug}");
 
-		return await client.FetchSingleAsync<Document>(request, cancellationToken);
+		return await client.FetchSingleAsync<Document>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<AssetResult[]>> GetPublicationAssetsAsync(
@@ -183,10 +183,10 @@ public async Task<IssuuResponse<AssetResult[]>> GetPublicationAssetsAsync(
 
 		if (assetType != AssetType.Cover)
 		{
-			return await client.FetchManyAsync<AssetResult[]>(request, cancellationToken);
+			return await client.FetchManyAsync<AssetResult[]>(request, cancellationToken).ConfigureAwait(false);
 		}
 
-		var result = await client.FetchManyAsync<AssetResult[][]>(request, cancellationToken);
+		var result = await client.FetchManyAsync<AssetResult[][]>(request, cancellationToken).ConfigureAwait(false);
 
 		var data = result.Data is { Length: > 0 } ? result.Data[0] : null;
 
@@ -230,7 +230,7 @@ public async Task<IssuuResponse<EmbedResult>> GetPublicationEmbedAsync(
 			path + $"/{slug}/embed",
 			query: query);
 
-		return await client.FetchSingleAsync<EmbedResult>(request, cancellationToken);
+		return await client.FetchSingleAsync<EmbedResult>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<ShareResult>> GetPublicationFullScreenShareAsync(
@@ -245,7 +245,7 @@ public async Task<IssuuResponse<ShareResult>> GetPublicationFullScreenShareAsync
 			path + $"/{slug}/fullscreen",
 			settings ?? new());
 
-		return await client.FetchSingleAsync<DisplaySettings, ShareResult>(request, cancellationToken);
+		return await client.FetchSingleAsync<DisplaySettings, ShareResult>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<ShareResult>> GetPublicationReaderShareAsync(
@@ -258,7 +258,7 @@ public async Task<IssuuResponse<ShareResult>> GetPublicationReaderShareAsync(
 			HttpMethod.Get,
 			path + $"/{slug}/reader");
 
-		return await client.FetchSingleAsync<ShareResult>(request, cancellationToken);
+		return await client.FetchSingleAsync<ShareResult>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<QrShareResult>> GetPublicationQrCodeAsync(
@@ -273,7 +273,7 @@ public async Task<IssuuResponse<QrShareResult>> GetPublicationQrCodeAsync(
 			path + $"/{slug}/qrcode",
 			settings ?? new());
 
-		return await client.FetchSingleAsync<QrDisplaySettings, QrShareResult>(request, cancellationToken);
+		return await client.FetchSingleAsync<QrDisplaySettings, QrShareResult>(request, cancellationToken).ConfigureAwait(false);
 	}
 
 	public async Task<IssuuResponse<Document[]>> GetPublicationsAsync(
@@ -283,7 +283,7 @@ public async Task<IssuuResponse<Document[]>> GetPublicationsAsync(
 	{
 		var request = new IssuuRequest(HttpMethod.Get, path, page: page, size: size);
 
-		return await client.FetchManyAsync<Document[]>(request, cancellationToken);
+		return await client.FetchManyAsync<Document[]>(request, cancellationToken).ConfigureAwait(false);
 	}
 }