Deprecate BuildAuthorizationUrl string grant methods

This commit deprecates the `BuildAuthorizationUrl(..., IEnumerable<string>? grants =
null)` methods and provided guidance to use the
`BuildAuthorizationUrl(AuthorizationUrlOptions)` method instead. The goal is to
improve maintainability, as it's easier to add/remove/deprecate properties from a
record than it is to modify the parameters of a method without introducing breaking
changes.

Scope: oauth, deprecation

Author: nozzlegear

ShopifySharp.Tests/Utilities/ShopifyOauthUtilityTests.cs

@@ -63,81 +63,18 @@ public void ShopifyOauthUtility_ShouldUseDomainUtilityFromDependencyInjection()
 
         // Act
         var utility = container.BuildServiceProvider().GetService<ShopifyOauthUtility>()!;
-        var act = () => utility.BuildAuthorizationUrl([ "some-scope" ], ShopDomain, ClientId, RedirectUrl, "some-state", [ "some-grant" ]);
+        var act = () => utility.BuildAuthorizationUrl(new AuthorizationUrlOptions
+        {
+            Scopes = ["some-scope"],
+            ShopDomain = ShopDomain,
+            ClientId = ClientId,
+            RedirectUrl = RedirectUrl
+        });
 
         // Assert
         act.Should().Throw<TestException>();
     }
 
-    [Theory]
-    [InlineData(null, null)]
-    [InlineData("some-state", null)]
-    [InlineData(null, new [] {"per-user"})]
-    [InlineData("some-state", new [] { "per-user" })]
-    public void BuildAuthorizationUrl_WhenGivenStringScopes_ReturnsTheUrl(string? state, string[]? grants)
-    {
-        // Setup
-        var scopes = new[] { "some-permission-1", "some-permission-2" };
-
-        // Act
-        var result = _sut.BuildAuthorizationUrl(scopes, ShopDomain, ClientId, RedirectUrl, state, grants);
-
-        // Assert
-        result.Host.Should().Be("example.myshopify.com");
-        result.Port.Should().Be(443);
-        result.Scheme.Should().Be(Uri.UriSchemeHttps);
-        result.Fragment.Should().BeEmpty();
-        result.AbsolutePath.Should().Be("/admin/oauth/authorize");
-        result.Query.Should().Contain($"client_id={ClientId}");
-        result.Query.Should().Contain("scope=" + string.Join(",", scopes));
-        result.Query.Should().Contain($"redirect_uri={RedirectUrl}");
-
-        if (state is not null)
-            result.Query.Should().Contain($"state={state}");
-        else
-            result.Query.Should().NotContain("state=");
-
-        if (grants is not null)
-            result.Query.Should().ContainAll(grants.Select(grant => $"grant_options[]={grant}"));
-        else
-            result.Query.Should().NotContain("grant_options[]=");
-    }
-
-    [Theory]
-    [InlineData(null, null)]
-    [InlineData("some-state", null)]
-    [InlineData(null, new [] {"per-user"})]
-    [InlineData("some-state", new [] { "per-user" })]
-    public void BuildAuthorizationUrl_WhenGivenEnumScopes_ReturnsTheUrl(string? state, string[]? grants)
-    {
-        // Setup
-        string[] expectedEnumStrings = ["read_customers", "write_customers"];
-        AuthorizationScope[] scopes = [ AuthorizationScope.ReadCustomers, AuthorizationScope.WriteCustomers ];
-
-        // Act
-        var result = _sut.BuildAuthorizationUrl(scopes, ShopDomain, ClientId, RedirectUrl, state, grants);
-
-        // Assert
-        result.Host.Should().Be("example.myshopify.com");
-        result.Port.Should().Be(443);
-        result.Scheme.Should().Be(Uri.UriSchemeHttps);
-        result.Fragment.Should().BeEmpty();
-        result.AbsolutePath.Should().Be("/admin/oauth/authorize");
-        result.Query.Should().Contain($"client_id={ClientId}");
-        result.Query.Should().Contain("scope=" + string.Join(",", expectedEnumStrings));
-        result.Query.Should().Contain($"redirect_uri={RedirectUrl}");
-
-        if (state is not null)
-            result.Query.Should().Contain($"state={state}");
-        else
-            result.Query.Should().NotContain("state=");
-
-        if (grants is not null)
-            result.Query.Should().ContainAll(grants.Select(grant => $"grant_options[]={grant}"));
-        else
-            result.Query.Should().NotContain("grant_options[]=");
-    }
-
     [Theory]
     [InlineData(null, AuthorizationAccessMode.Offline)]
     [InlineData("some-state", AuthorizationAccessMode.Offline)]
@@ -225,6 +162,84 @@ public void BuildAuthorizationUrl_WhenAuthorizationUrlOptionsContainsBothGrantsA
             .WithMessage("Invalid AuthorizationUrlOptions. Cannot use the obsolete Grants alongside AuthorizationAccessMode.");
     }
 
+    #region Deprecated BuildAuthorizationUrl methods
+
+    [Theory]
+    [InlineData(null, null)]
+    [InlineData("some-state", null)]
+    [InlineData(null, new [] {"per-user"})]
+    [InlineData("some-state", new [] { "per-user" })]
+    public void BuildAuthorizationUrl_WhenGivenStringScopes_ReturnsTheUrl(string? state, string[]? grants)
+    {
+        // Setup
+        var scopes = new[] { "some-permission-1", "some-permission-2" };
+
+        // Act
+#pragma warning disable CS0618 // Type or member is obsolete
+        var result = _sut.BuildAuthorizationUrl(scopes, ShopDomain, ClientId, RedirectUrl, state, grants);
+#pragma warning restore CS0618 // Type or member is obsolete
+
+        // Assert
+        result.Host.Should().Be("example.myshopify.com");
+        result.Port.Should().Be(443);
+        result.Scheme.Should().Be(Uri.UriSchemeHttps);
+        result.Fragment.Should().BeEmpty();
+        result.AbsolutePath.Should().Be("/admin/oauth/authorize");
+        result.Query.Should().Contain($"client_id={ClientId}");
+        result.Query.Should().Contain("scope=" + string.Join(",", scopes));
+        result.Query.Should().Contain($"redirect_uri={RedirectUrl}");
+
+        if (state is not null)
+            result.Query.Should().Contain($"state={state}");
+        else
+            result.Query.Should().NotContain("state=");
+
+        if (grants is not null)
+            result.Query.Should().ContainAll(grants.Select(grant => $"grant_options[]={grant}"));
+        else
+            result.Query.Should().NotContain("grant_options[]=");
+    }
+
+    [Theory]
+    [InlineData(null, null)]
+    [InlineData("some-state", null)]
+    [InlineData(null, new [] {"per-user"})]
+    [InlineData("some-state", new [] { "per-user" })]
+    public void BuildAuthorizationUrl_WhenGivenEnumScopes_ReturnsTheUrl(string? state, string[]? grants)
+    {
+        // Setup
+        string[] expectedEnumStrings = ["read_customers", "write_customers"];
+        AuthorizationScope[] scopes = [ AuthorizationScope.ReadCustomers, AuthorizationScope.WriteCustomers ];
+
+        // Act
+#pragma warning disable CS0618 // Type or member is obsolete
+        var result = _sut.BuildAuthorizationUrl(scopes, ShopDomain, ClientId, RedirectUrl, state, grants);
+#pragma warning restore CS0618 // Type or member is obsolete
+
+        // Assert
+        result.Host.Should().Be("example.myshopify.com");
+        result.Port.Should().Be(443);
+        result.Scheme.Should().Be(Uri.UriSchemeHttps);
+        result.Fragment.Should().BeEmpty();
+        result.AbsolutePath.Should().Be("/admin/oauth/authorize");
+        result.Query.Should().Contain($"client_id={ClientId}");
+        result.Query.Should().Contain("scope=" + string.Join(",", expectedEnumStrings));
+        result.Query.Should().Contain($"redirect_uri={RedirectUrl}");
+
+        if (state is not null)
+            result.Query.Should().Contain($"state={state}");
+        else
+            result.Query.Should().NotContain("state=");
+
+        if (grants is not null)
+            result.Query.Should().ContainAll(grants.Select(grant => $"grant_options[]={grant}"));
+        else
+            result.Query.Should().NotContain("grant_options[]=");
+    }
+
+
+    #endregion
+
     [Fact(DisplayName = "AuthorizeAsync(AuthorizeOptions) should call the base AuthorizeAsync(string, string, string, string) method")]
     public async Task AuthorizeAsync_WithAuthorizeOptionsParameters_ShouldCallBaseAuthorizeAsyncMethodAndPassOptionsToMethod()
     {

ShopifySharp/Enums/AuthorizationAccessMode.cs

@@ -3,8 +3,12 @@ namespace ShopifySharp.Enums;
 
 public enum AuthorizationAccessMode
 {
+    /// <summary>
+    /// The default, permanent access token mode scoped to the full permissions the shop grants to your app.
+    /// </summary>
     Offline = 1,
     /// <summary>
+    /// The temporary, online access token mode scoped to a single shop staff user and the permissions they hold on the shop.
     /// Alternately referred to as "Per-User" in Shopify's documentation.
     /// </summary>
     Online = 2,

ShopifySharp/Utilities/AuthorizationUrlOptions.cs

@@ -42,6 +42,7 @@ public record AuthorizationUrlOptions
     [Obsolete("Deprecated, please use " + nameof(Enums.AuthorizationAccessMode) + " instead.")]
     public IEnumerable<string>? Grants { get; set; }
 
-    /// Sets the access mode. For an "online access token", set to PerUserAccess.
+    /// Sets the access mode for the access token grant. For an "online access token" (alternately referred to as "per user"
+    /// in Shopify's documentation), set to <see cref="AuthorizationAccessMode.Online"/>.
     public AuthorizationAccessMode AuthorizationAccessMode { get; set; } = AuthorizationAccessMode.Offline;
 }

ShopifySharp/Utilities/ShopifyOauthUtility.cs

@@ -24,6 +24,10 @@ public interface IShopifyOauthUtility
     /// <param name="redirectUrl">URL to redirect the user to after integration.</param>
     /// <param name="state">An optional, random string value provided by your application which is unique for each authorization request. During the OAuth callback phase, your application should check that this value matches the one you provided to this method.</param>
     /// <param name="grants">Requested grant types, which will change the type of access token granted upon OAuth completion.</param>
+    /// <remarks>
+    /// Use the <see cref="BuildAuthorizationUrl(AuthorizationUrlOptions)"/> overload instead.
+    /// </remarks>
+    [Obsolete("Use " + nameof(BuildAuthorizationUrl) + "(" + nameof(AuthorizationUrlOptions) + ") instead. This method will be removed in a future version of ShopifySharp.")]
     Uri BuildAuthorizationUrl(
         IEnumerable<AuthorizationScope> scopes,
         string shopDomain,
@@ -42,6 +46,7 @@ Uri BuildAuthorizationUrl(
     /// <param name="redirectUrl">URL to redirect the user to after integration.</param>
     /// <param name="state">An optional, random string value provided by your application which is unique for each authorization request. During the OAuth callback phase, your application should check that this value matches the one you provided to this method.</param>
     /// <param name="grants">Requested grant types, which will change the type of access token granted upon OAuth completion.</param>
+    [Obsolete("Use " + nameof(BuildAuthorizationUrl) + "(" + nameof(AuthorizationUrlOptions) + ") instead. This method will be removed in a future version of ShopifySharp.")]
     Uri BuildAuthorizationUrl(
         IEnumerable<string> scopes,
         string shopDomain,
@@ -140,6 +145,7 @@ JsonSerializerOptions GetJsonSerializerOptions() => InternalServiceResolver.GetS
     }
 
     /// <inheritdoc />
+    [Obsolete("Use " + nameof(BuildAuthorizationUrl) + "(" + nameof(AuthorizationUrlOptions) + ") instead. This method will be removed in a future version of ShopifySharp.")]
     public Uri BuildAuthorizationUrl(
         IEnumerable<AuthorizationScope> scopes,
         string shopDomain,
@@ -160,6 +166,7 @@ public Uri BuildAuthorizationUrl(
     });
 
     /// <inheritdoc />
+    [Obsolete("Use " + nameof(BuildAuthorizationUrl) + "(" + nameof(AuthorizationUrlOptions) + ") instead. This method will be removed in a future version of ShopifySharp.")]
     public Uri BuildAuthorizationUrl(
         IEnumerable<string> scopes,
         string shopDomain,