chore: apply PR reword suggestions

Author: DevTKSS

docs/etsy.md

@@ -206,6 +206,10 @@ Here is a comprehensive `appsettings.json` example covering supported options an
   "Etsy": {
     "ClientId": "your-etsy-api-key",
     "IncludeDetailedUserInfo": true,
+    "DetailedUserInfoEndpoint": "https://openapi.etsy.com/v3/application/users/{0}",
+    "AuthorizationEndpoint": "https://www.etsy.com/oauth/connect",
+    "TokenEndpoint": "https://openapi.etsy.com/v3/public/oauth/token",
+    "UserInformationEndpoint": "https://openapi.etsy.com/v3/application/users/me",
     "SaveTokens": true,
     "Scopes": [ "shops_r", "email_r" ]
   }
@@ -215,7 +219,9 @@ Here is a comprehensive `appsettings.json` example covering supported options an
 > [!NOTE]
 > We recommend saving tokens (`SaveTokens = true`) to facilitate token refresh, so the user does not need to re-authenticate frequently.
 > [!NOTE]
-> If you bind from appsettings, make sure to either set no scopes, if the basic `shops_r` scope is sufficient (`IncludeDetailedUserInfo` set to `true` would also add `email_r`), or always include them into the configuration. The handler does not automatically add it when binding from configuration.
+> If `IncludeDetailedUserInfo` is set to `true` and the scopes `shops_r` and `email_r` scopes are sufficient, you don't need to set additional scopes in `appsettings.json`, they are added automatically.
+> [!TIP]
+> We recommend using the `EtsyAuthenticationDefaults` class in your `.AddEtsy` call which contains the default endpoint URLs.
 
 If you bind then from configuration, set the options in code, for example:
 
@@ -228,21 +234,35 @@ builder.Services.AddAuthentication(options =>
 .AddCookie()
 .AddEtsy(options =>
 {
-    var section = builder.Configuration.GetSection("Etsy").Get<EtsyAuthenticationOptions>();
-    options.ClientId = section.ClientId!;
-    options.IncludeDetailedUserInfo = section.IncludeDetailedUserInfo;
-    options.SaveTokens = section.SaveTokens;
+    var section = builder.Configuration.GetSection("Etsy");
+    options.ClientId = section.GetValue<string?>("ClientId")
+        ?? throw new InvalidOperationException("Etsy:ClientId configuration value is missing.");
+
+    // For the Detailed User Info Endpoint and SaveTokens are default values pre-set, but you can override them here
+    options.IncludeDetailedUserInfo = section.GetValue<bool>("IncludeDetailedUserInfo");
+    options.SaveTokens = section.GetValue<bool>("SaveTokens");
+
+    // Use the defaults from EtsyAuthenticationDefaults, if you want to repeat them here, but they are set automatically
+    options.AuthorizationEndpoint = EtsyAuthenticationDefaults.AuthorizationEndpoint;
+    options.TokenEndpoint = EtsyAuthenticationDefaults.TokenEndpoint;
+    options.UserInformationEndpoint = EtsyAuthenticationDefaults.UserInformationEndpoint;
 
     // Apply scopes from config if present
-    var scopes = section.GetSection("Scopes").Get<string[]?>();
+    var scopes = section.Get<string[]>("Scopes");
 
-    foreach (var scope in scopes)
+    if (scopes is not null)
     {
-        options.Scope.Add(scope);
+        foreach (var scope in scopes)
+        {
+            options.Scope.Add(scope);
+        }
     }
 
-    // Optionally add image claim
-    options.AddImageClaim();
+    // Optionally Map the image claim
+    options.ClaimActions.MapImageClaim();
+
+    // Map other Claims
+    options.ClaimActions.MapJsonKey("urn:etsy:listingsWrite", "listings_w");
 })
 ```
 

src/AspNet.Security.OAuth.Etsy/ClaimActionCollectionExtensions.cs

@@ -9,8 +9,14 @@
 
 namespace Microsoft.Extensions.DependencyInjection;
 
+/// <summary>
+/// Provides extension methods for <see cref="ClaimActionCollection"/> to map Etsy API specific user claims.
+/// </summary>
 public static class ClaimActionCollectionExtensions
 {
+    /// <summary>
+    /// Maps the Etsy user's profile image URL (75x75) to the <see cref="EtsyAuthenticationConstants.Claims.ImageUrl"/> claim.
+    /// </summary>
     public static void MapImageClaim(this ClaimActionCollection collection)
     {
         collection.MapJsonKey(EtsyAuthenticationConstants.Claims.ImageUrl, "image_url_75x75");