Merge remote-tracking branch 'origin/support/10.x' into develop

# Conflicts:
#	src/Umbraco.AuthorizedServices/Controllers/AuthorizedServiceController.cs
#	version.json

Author: AndyButland

README.md

@@ -287,7 +287,7 @@ To make a call to an authorized service, you first need to obtain an instance of
 If making a request where all information is provided via the path and querystring, such as GET requests, the following method should be invoked:
 
 ```csharp
-Task<Attempt<TResponse?>> SendRequestAsync<TResponse>(string serviceAlias, string path, HttpMethod httpMethod);
+Task<Attempt<AuthorizedServiceResponse<TResponse>>> SendRequestAsync<TResponse>(string serviceAlias, string path, HttpMethod httpMethod);
 ```
 
 The parameters for the request are as follows:
@@ -302,7 +302,7 @@ There is also a type parameter:
 If you need to provide data in the request, as is usually the case for POST or PUT requests that required the creation or update of a resource, an overload is available:
 
 ```csharp
-Task<Attempt<TResponse>> SendRequestAsync<TRequest, TResponse>(string serviceAlias, string path, HttpMethod httpMethod, TRequest? requestContent = null)
+Task<Attempt<AuthorizedServiceResponse<TResponse>>> SendRequestAsync<TRequest, TResponse>(string serviceAlias, string path, HttpMethod httpMethod, TRequest? requestContent = null)
     where TRequest : class;
 ```
 
@@ -317,18 +317,24 @@ And additional type parameter:
 If you need to work with the raw JSON response, there are equivalent methods for both of these that omit the deserialization step:
 
 ```csharp
-Task<Attempt<string?>> SendRequestRawAsync(string serviceAlias, string path, HttpMethod httpMethod);
+Task<Attempt<AuthorizedServiceResponse<string>>> SendRequestRawAsync(string serviceAlias, string path, HttpMethod httpMethod);
 
-Task<<Attempt<string?>> SendRequestRawAsync<TRequest>(string serviceAlias, string path, HttpMethod httpMethod, TRequest? requestContent = null)
+Task<Attempt<AuthorizedServiceResponse<string>>> SendRequestRawAsync<TRequest>(string serviceAlias, string path, HttpMethod httpMethod, TRequest? requestContent = null)
     where TRequest : class;
 ```
 
 Finally, there are convenience extension methods available for each of the common HTTP verbs, allowing you to simplify the requests and omit the `HttpMethod` parameter, e.g.
 
 ```csharp
-Task<Attempt<TResponse?>> GetRequestAsync<TResponse>(string serviceAlias, string path);
+Task<Attempt<AuthorizedServiceResponse<TResponse>>> GetRequestAsync<TResponse>(string serviceAlias, string path);
 ```
 
+The response is received wrapped in an instance of `AuthorizedServiceResponse` which has three properties:
+
+- `Data` - the response data deserialized into an instance of the provided `TResponse` type.
+- `Raw` - the raw JSON response string.
+- `Metadata` - various metadata from the service response, provided in headers and parsed into an instance of `ServiceResponseMetadata`.
+
 ## Providers
 
 The list of providers for which the package has been verified is maintained at the [Umbraco Documentation website](https://docs.umbraco.com/umbraco-dxp/packages/authorized-services#verified-providers).
@@ -456,6 +462,10 @@ Switching the encryption engine to for example `AesSecretEncryptor` can be done
 builder.Services.AddUnique<ISecretEncryptor, AesSecretEncryptor>();
 ```
 
+#### IServiceResponseMetadataParser
+
+Responsible for parsing header values from the response received when calling an authorized service into an instance of `ServiceResponseMetadata`.
+
 #### ITokenFactory
 
 Responsible for instantiating a new strongly typed `Token` instance from the service response. Implemented by `TokenFactory`.

examples/Umbraco.AuthorizedServices.TestSite/Controllers/HubspotContactsController.cs

@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.AuthorizedServices.Extensions;
+using Umbraco.AuthorizedServices.Models;
 using Umbraco.AuthorizedServices.Services;
 using Umbraco.AuthorizedServices.TestSite.Models.Dtos;
 using Umbraco.AuthorizedServices.TestSite.Models.ServiceResponses;
@@ -21,15 +22,15 @@ public HubspotContactsController(IAuthorizedServiceCaller authorizedServiceCalle
     [HttpGet]
     public async Task<IActionResult> Get()
     {
-       Attempt<HubspotContactResponse?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse>(
+       Attempt<AuthorizedServiceResponse<HubspotContactResponse>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse>(
             ServiceAlias,
             BasePath);
         if (!responseAttempt.Success || responseAttempt.Result is null)
         {
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve contacts.");
         }
 
-        HubspotContactResponse response = responseAttempt.Result;
+        HubspotContactResponse response = responseAttempt.Result.Data!;
         return Ok(
             response.Results
                 .Select(MapToDto)
@@ -40,7 +41,7 @@ public async Task<IActionResult> Get()
     [Route("{id}")]
     public async Task<IActionResult> Get(string id)
     {
-        Attempt<HubspotContactResponse.Result?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse.Result>(
+        Attempt<AuthorizedServiceResponse<HubspotContactResponse.Result>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse.Result>(
             ServiceAlias,
             $"{BasePath}{id}");
 
@@ -49,14 +50,14 @@ public async Task<IActionResult> Get(string id)
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve contact.");
         }
 
-        HubspotContactResponse.Result response = responseAttempt.Result;
+        HubspotContactResponse.Result response = responseAttempt.Result.Data!;
         return Ok(MapToDto(response));
     }
 
     [HttpPost]
     public async Task<IActionResult> Create([FromBody] ContactDto contact)
     {
-        Attempt<HubspotContactResponse.Result?> responseAttempt = await AuthorizedServiceCaller.PostRequestAsync<HubspotContactResponse.Result, HubspotContactResponse.Result>(
+        Attempt<AuthorizedServiceResponse<HubspotContactResponse.Result>> responseAttempt = await AuthorizedServiceCaller.PostRequestAsync<HubspotContactResponse.Result, HubspotContactResponse.Result>(
             ServiceAlias,
             BasePath,
             MapToRequest(contact));
@@ -65,14 +66,14 @@ public async Task<IActionResult> Create([FromBody] ContactDto contact)
             return HandleFailedRequest(responseAttempt.Exception, "Could not create contact.");
         }
 
-        HubspotContactResponse.Result response = responseAttempt.Result;
+        HubspotContactResponse.Result response = responseAttempt.Result.Data!;
         return CreatedAtAction(nameof(Get), new { id = response.Id }, MapToDto(response));
     }
 
     [HttpPut]
     public async Task<IActionResult> Update([FromBody] ContactDto contact)
     {
-        Attempt<HubspotContactResponse.Result?> responseAttempt = await AuthorizedServiceCaller.PatchRequestAsync<HubspotContactResponse.Result, HubspotContactResponse.Result>(
+        Attempt<AuthorizedServiceResponse<HubspotContactResponse.Result>> responseAttempt = await AuthorizedServiceCaller.PatchRequestAsync<HubspotContactResponse.Result, HubspotContactResponse.Result>(
             ServiceAlias,
             $"{BasePath}{contact.Id}",
             MapToRequest(contact));
@@ -81,7 +82,7 @@ public async Task<IActionResult> Update([FromBody] ContactDto contact)
             return HandleFailedRequest(responseAttempt.Exception, "Could not update contact.");
         }
 
-        HubspotContactResponse.Result response = responseAttempt.Result;
+        HubspotContactResponse.Result response = responseAttempt.Result.Data!;
         return Ok(MapToDto(response));
     }
 

examples/Umbraco.AuthorizedServices.TestSite/Controllers/TestAuthorizedServicesController.cs

@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Mvc;
 using Umbraco.AuthorizedServices.Extensions;
+using Umbraco.AuthorizedServices.Models;
 using Umbraco.AuthorizedServices.Services;
 using Umbraco.AuthorizedServices.TestSite.Models.ServiceResponses;
 using Umbraco.Cms.Core;
@@ -15,29 +16,29 @@ public TestAuthorizedServicesController(IAuthorizedServiceCaller authorizedServi
 
     public async Task<IActionResult> GetUmbracoContributorsFromGitHub()
     {
-        Attempt<List<GitHubContributorResponse>?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<List<GitHubContributorResponse>>(
+        Attempt<AuthorizedServiceResponse<List<GitHubContributorResponse>>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<List<GitHubContributorResponse>>(
             "github",
             "/repos/Umbraco/Umbraco-CMS/contributors");
         if (!responseAttempt.Success || responseAttempt.Result is null)
         {
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve contributors.");
         }
 
-        List<GitHubContributorResponse> response = responseAttempt.Result;
+        List<GitHubContributorResponse> response = responseAttempt.Result.Data!;
         return Content(string.Join(", ", response.Select(x => x.Login)));
     }
 
     public async Task<IActionResult> GetContactsFromHubspot()
     {
-        Attempt<HubspotContactResponse?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse>(
+        Attempt<AuthorizedServiceResponse<HubspotContactResponse>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<HubspotContactResponse>(
             "hubspot",
             "/crm/v3/objects/contacts?limit=10&archived=false");
         if (!responseAttempt.Success || responseAttempt.Result is null)
         {
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve contacts.");
         }
 
-        HubspotContactResponse response = responseAttempt.Result;
+        HubspotContactResponse response = responseAttempt.Result.Data!;
         return Content(
             string.Join(
                 ", ",
@@ -48,7 +49,7 @@ public async Task<IActionResult> GetContactsFromHubspot()
     public async Task<IActionResult> GetMeetupSelfUserInfo()
     {
         // This makes a GraphQL query
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "meetup",
             "/gql",
             HttpMethod.Post,
@@ -62,13 +63,13 @@ public async Task<IActionResult> GetMeetupSelfUserInfo()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve user info.");
         }
 
-        var response = responseAttempt.Result;
-        return Content(response);
+        AuthorizedServiceResponse<string> response = responseAttempt.Result;
+        return Content(response.Data ?? string.Empty);
     }
 
     public async Task<IActionResult> GetFormsFromDynamics()
     {
-        Attempt<DynamicsFormResponse?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<DynamicsFormResponse>(
+        Attempt<AuthorizedServiceResponse<DynamicsFormResponse>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<DynamicsFormResponse>(
             "dynamics",
             "/msdyncrm_marketingforms");
 
@@ -77,13 +78,13 @@ public async Task<IActionResult> GetFormsFromDynamics()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve forms.");
         }
 
-        DynamicsFormResponse response = responseAttempt.Result;
+        DynamicsFormResponse response = responseAttempt.Result.Data!;
         return Content(string.Join(", ", response.Results.Select(x => x.Name)));
     }
 
     public async Task<IActionResult> GetSearchResultsFromGoogle()
     {
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "google",
             "/v1/urlInspection/index:inspect",
             HttpMethod.Post,
@@ -99,12 +100,12 @@ public async Task<IActionResult> GetSearchResultsFromGoogle()
         }
 
         var response = responseAttempt.Result;
-        return Content(response);
+        return Content(response.Data ?? string.Empty);
     }
 
     public async Task<IActionResult> GetFoldersFromDropbox()
     {
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "dropbox",
             "/2/files/list_folder",
             HttpMethod.Post,
@@ -119,13 +120,13 @@ public async Task<IActionResult> GetFoldersFromDropbox()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve folders.");
         }
 
-        var response = responseAttempt.Result;
-        return Content(response);
+        var response = responseAttempt.Result.Data;
+        return Content(response ?? string.Empty);
     }
 
     public async Task<IActionResult> GetAssetsFromAssetBank(string assetIds)
     {
-        Attempt<AssetBankSearchResponse?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<AssetBankSearchResponse>(
+        Attempt<AuthorizedServiceResponse<AssetBankSearchResponse>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<AssetBankSearchResponse>(
             "assetBank",
             "/assetbank-rya-assets-test/rest/asset-search?assetIds=" + assetIds);
 
@@ -134,13 +135,13 @@ public async Task<IActionResult> GetAssetsFromAssetBank(string assetIds)
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve assets.");
         }
 
-        AssetBankSearchResponse response = responseAttempt.Result;
+        AssetBankSearchResponse response = responseAttempt.Result.Data!;
         return Content(string.Join(", ", response.Select(x => x.ToString())));
     }
 
     public async Task<IActionResult> GetVideoDetailsFromYouTube(string videoId)
     {
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "youtube",
             $"/v3/videos?id={videoId}&part=snippet,contentDetails,statistics,status",
             HttpMethod.Get);
@@ -150,13 +151,13 @@ public async Task<IActionResult> GetVideoDetailsFromYouTube(string videoId)
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve video details.");
         }
 
-        var response = responseAttempt.Result;
-        return Content(response);
+        var response = responseAttempt.Result.Data;
+        return Content(response ?? string.Empty);
     }
 
     public async Task<IActionResult> GetInstagramProfile()
     {
-        Attempt<InstagramProfileResponse?> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<InstagramProfileResponse>(
+        Attempt<AuthorizedServiceResponse<InstagramProfileResponse>> responseAttempt = await AuthorizedServiceCaller.GetRequestAsync<InstagramProfileResponse>(
             "instagram",
             $"/v3.0/me?fields=username");
 
@@ -165,12 +166,12 @@ public async Task<IActionResult> GetInstagramProfile()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve account details.");
         }
 
-        return Content(responseAttempt.Result.Username);
+        return Content(responseAttempt.Result.Data!.Username);
     }
 
     public async Task<IActionResult> GetTwitterProfileUsingOAuth1()
     {
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "twitter",
             "/1.1/account/settings.json",
             HttpMethod.Get);
@@ -180,13 +181,13 @@ public async Task<IActionResult> GetTwitterProfileUsingOAuth1()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve account details.");
         }
 
-        var response = responseAttempt.Result;
-        return Content(response);
+        var response = responseAttempt.Result.Data;
+        return Content(response ?? string.Empty);
     }
 
     public async Task<IActionResult> GetTwitterProfileUsingOAuth2()
     {
-        Attempt<string?> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
+        Attempt<AuthorizedServiceResponse<string>> responseAttempt = await AuthorizedServiceCaller.SendRequestRawAsync(
             "twitter_oauth2",
             "/2/users/me",
             HttpMethod.Get);
@@ -196,8 +197,8 @@ public async Task<IActionResult> GetTwitterProfileUsingOAuth2()
             return HandleFailedRequest(responseAttempt.Exception, "Could not retrieve account details.");
         }
 
-        var response = responseAttempt.Result;
-        return Content(response);
+        var response = responseAttempt.Result.Data;
+        return Content(response ?? string.Empty);
     }
 
     public async Task<IActionResult> GetApiKey(string serviceAlias)

src/Umbraco.AuthorizedServices/Api/Management/Controllers/Service/SendSampleRequestController.cs

@@ -5,6 +5,7 @@
 using Microsoft.Extensions.Options;
 using Umbraco.AuthorizedServices.Configuration;
 using Umbraco.AuthorizedServices.Exceptions;
+using Umbraco.AuthorizedServices.Models;
 using Umbraco.AuthorizedServices.Services;
 using Umbraco.Cms.Core;
 
@@ -31,7 +32,7 @@ public async Task<IActionResult> SendSampleRequest(string alias)
         {
             ServiceDetail serviceDetail = ServiceDetailOptions.Get(alias);
 
-            Attempt<string?> responseAttempt = await _authorizedServiceCaller.SendRequestRawAsync(alias, serviceDetail.SampleRequest ?? string.Empty, HttpMethod.Get);
+            Attempt<AuthorizedServiceResponse<string>> responseAttempt = await _authorizedServiceCaller.SendRequestRawAsync(alias, serviceDetail.SampleRequest ?? string.Empty, HttpMethod.Get);
             if (responseAttempt.Success && responseAttempt.Result is not null)
             {
                 return Ok(responseAttempt.Result);

src/Umbraco.AuthorizedServices/AuthorizedServicesComposer.cs

@@ -45,6 +45,7 @@ private static void RegisterServices(IUmbracoBuilder builder)
         builder.Services.AddUnique<IAuthorizedRequestBuilder, AuthorizedRequestBuilder>();
 
         builder.Services.AddUnique<IAuthorizedServiceCaller, AuthorizedServiceCaller>();
+        builder.Services.AddUnique<IServiceResponseMetadataParser, ServiceResponseMetadataParser>();
         builder.Services.AddUnique<IDateTimeProvider, DateTimeProvider>();
         builder.Services.AddUnique<IRefreshTokenParametersBuilder, RefreshTokenParametersBuilder>();