feat(auth): Add LinkDomain to ActionCodeSettings and deprecate DynamicLinkDomain (#475)

* feat(auth): Add LinkDomain to ActionCodeSettings

This change adds support for specifying a hosting link domain in `ActionCodeSettings`. This is used for email action links.

The following changes were made:
- Added the `LinkDomain` property to the `ActionCodeSettings` class.
- Deprecated the `DynamicLinkDomain` property in `ActionCodeSettings`.
- Added the `InvalidHostingLinkDomain` error code to `AuthErrorCode` and the corresponding error handling logic in `AuthErrorHandler`.
- Updated the `EmailActionLinkRequest` to use the new `LinkDomain` property and remove usage of the deprecated `DynamicLinkDomain` property.
- Updated unit tests to cover the new functionality and error conditions. Removed tests for the deprecated property as per repository guidelines to avoid build failures.
- Fixed a style error in the tests that was introduced.

* fix(auth): Correct implementation of LinkDomain feature

This commit corrects the implementation of the `LinkDomain` feature based on feedback. The previous implementation had incorrectly removed the deprecated `DynamicLinkDomain` functionality.

The following corrections were made:
- Restored the `DynamicLinkDomain` property and its related logic in the production code to maintain backward compatibility.
- Updated all `.csproj` files to suppress the `CS0618` obsolescence warning, which is the correct way to handle this deprecation without breaking the build.
- Restored the original unit tests for `DynamicLinkDomain` and added new, separate tests for the `LinkDomain` property.
- Updated the code snippets to use the new `LinkDomain` property.
- Fixed a style error in the test files.

* fix(auth): Refactor generated tests and use pragma directives instead of permitting obsolete warnings.

* fix(chore): Fixed docstring and updated `AGENTS.md` with learnings

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: jonathanedey

AGENTS.md

@@ -72,7 +72,7 @@ dotnet test FirebaseAdmin/FirebaseAdmin.Tests --framework net462
 ### Journey 2: How to Deprecate a Field/Method in an Existing API
 
 1.  **Add Deprecation Note**: Locate where the deprecated object is defined and add a deprecation warning with a note (e.g. [Obsolete("Use X instead")]).
-2.  **Remove Releted Tests and Update Snippets**: Because `Obsolete` warnings result in build errors, tests and snippets where the object is used should be removed or updated not no longer used the deprecated object.
+2.  **Suppress Obsolete Warnings**: Because `Obsolete` warnings result in build errors, tests and snippets where the object is used should be marked using `#pragma` directives to suppress warnings where the object is used.
 
 ## Critical Do's and Don'ts
 

FirebaseAdmin/FirebaseAdmin.Snippets/FirebaseAuthSnippets.cs

@@ -643,7 +643,7 @@ internal static ActionCodeSettings InitActionCodeSettings()
                 AndroidPackageName = "com.example.android",
                 AndroidInstallApp = true,
                 AndroidMinimumVersion = "12",
-                DynamicLinkDomain = "coolapp.page.link",
+                LinkDomain = "coolapp.page.link",
             };
             // [END init_action_code_settings]
             return actionCodeSettings;

FirebaseAdmin/FirebaseAdmin.Tests/Auth/AuthErrorHandlerTest.cs

@@ -63,6 +63,12 @@ public class AuthErrorHandlerTest
                     ErrorCode.NotFound,
                     AuthErrorCode.EmailNotFound,
                 },
+                new object[]
+                {
+                    "INVALID_HOSTING_LINK_DOMAIN",
+                    ErrorCode.InvalidArgument,
+                    AuthErrorCode.InvalidHostingLinkDomain,
+                },
             };
 
         [Theory]

FirebaseAdmin/FirebaseAdmin.Tests/Auth/Users/EmailActionRequestTest.cs

@@ -47,7 +47,17 @@ public class EmailActionRequestTest
                     new ActionCodeSettings()
                     {
                         Url = "https://example.dynamic.link",
+#pragma warning disable CS0618
                         DynamicLinkDomain = string.Empty,
+#pragma warning restore CS0618
+                    },
+                },
+                new object[]
+                {
+                    new ActionCodeSettings()
+                    {
+                        Url = "https://example.dynamic.link",
+                        LinkDomain = string.Empty,
                     },
                 },
                 new object[]
@@ -84,7 +94,10 @@ public class EmailActionRequestTest
         {
             Url = "https://example.dynamic.link",
             HandleCodeInApp = true,
+#pragma warning disable CS0618
             DynamicLinkDomain = "custom.page.link",
+#pragma warning restore CS0618
+            LinkDomain = "custom.page.link",
             IosBundleId = "com.example.ios",
             AndroidPackageName = "com.example.android",
             AndroidMinimumVersion = "6",
@@ -163,14 +176,17 @@ public async Task EmailVerificationLinkWithSettings()
 
             var request = NewtonsoftJsonSerializer.Instance.Deserialize<Dictionary<string, object>>(
                 handler.LastRequestBody);
-            Assert.Equal(10, request.Count);
+            Assert.Equal(11, request.Count);
             Assert.Equal("[email protected]", request["email"]);
             Assert.Equal("VERIFY_EMAIL", request["requestType"]);
             Assert.True((bool)request["returnOobLink"]);
 
             Assert.Equal(ActionCodeSettings.Url, request["continueUrl"]);
             Assert.True((bool)request["canHandleCodeInApp"]);
+#pragma warning disable CS0618
             Assert.Equal(ActionCodeSettings.DynamicLinkDomain, request["dynamicLinkDomain"]);
+#pragma warning restore CS0618
+            Assert.Equal(ActionCodeSettings.LinkDomain, request["linkDomain"]);
             Assert.Equal(ActionCodeSettings.IosBundleId, request["iOSBundleId"]);
             Assert.Equal(ActionCodeSettings.AndroidPackageName, request["androidPackageName"]);
             Assert.Equal(
@@ -229,14 +245,17 @@ public async Task PasswordResetLinkWithSettings()
 
             var request = NewtonsoftJsonSerializer.Instance.Deserialize<Dictionary<string, object>>(
                 handler.LastRequestBody);
-            Assert.Equal(10, request.Count);
+            Assert.Equal(11, request.Count);
             Assert.Equal("[email protected]", request["email"]);
             Assert.Equal("PASSWORD_RESET", request["requestType"]);
             Assert.True((bool)request["returnOobLink"]);
 
             Assert.Equal(ActionCodeSettings.Url, request["continueUrl"]);
             Assert.True((bool)request["canHandleCodeInApp"]);
+#pragma warning disable CS0618
             Assert.Equal(ActionCodeSettings.DynamicLinkDomain, request["dynamicLinkDomain"]);
+#pragma warning restore CS0618
+            Assert.Equal(ActionCodeSettings.LinkDomain, request["linkDomain"]);
             Assert.Equal(ActionCodeSettings.IosBundleId, request["iOSBundleId"]);
             Assert.Equal(ActionCodeSettings.AndroidPackageName, request["androidPackageName"]);
             Assert.Equal(
@@ -287,14 +306,17 @@ public async Task SignInWithEmailLink()
 
             var request = NewtonsoftJsonSerializer.Instance.Deserialize<Dictionary<string, object>>(
                 handler.LastRequestBody);
-            Assert.Equal(10, request.Count);
+            Assert.Equal(11, request.Count);
             Assert.Equal("[email protected]", request["email"]);
             Assert.Equal("EMAIL_SIGNIN", request["requestType"]);
             Assert.True((bool)request["returnOobLink"]);
 
             Assert.Equal(ActionCodeSettings.Url, request["continueUrl"]);
             Assert.True((bool)request["canHandleCodeInApp"]);
+#pragma warning disable CS0618
             Assert.Equal(ActionCodeSettings.DynamicLinkDomain, request["dynamicLinkDomain"]);
+#pragma warning restore CS0618
+            Assert.Equal(ActionCodeSettings.LinkDomain, request["linkDomain"]);
             Assert.Equal(ActionCodeSettings.IosBundleId, request["iOSBundleId"]);
             Assert.Equal(ActionCodeSettings.AndroidPackageName, request["androidPackageName"]);
             Assert.Equal(
@@ -351,6 +373,39 @@ public async Task InvalidDynamicLinkDomain()
             Assert.Null(exception.InnerException);
         }
 
+        [Fact]
+        public async Task InvalidHostingLinkDomain()
+        {
+            var json = $@"{{
+                ""error"": {{
+                    ""message"": ""INVALID_HOSTING_LINK_DOMAIN"",
+                }}
+            }}";
+            var handler = new MockMessageHandler()
+            {
+                StatusCode = HttpStatusCode.InternalServerError,
+                Response = json,
+            };
+            var auth = this.CreateFirebaseAuth(handler);
+            var settings = new ActionCodeSettings()
+            {
+                Url = "https://example.dynamic.link",
+                LinkDomain = "custom.page.link",
+            };
+
+            var exception = await Assert.ThrowsAsync<FirebaseAuthException>(
+                async () => await auth.GenerateSignInWithEmailLinkAsync(
+                    "[email protected]", settings));
+
+            Assert.Equal(ErrorCode.InvalidArgument, exception.ErrorCode);
+            Assert.Equal(AuthErrorCode.InvalidHostingLinkDomain, exception.AuthErrorCode);
+            Assert.Equal(
+                "The provided hosting link domain is not configured in Firebase Hosting or is not owned by the current project (INVALID_HOSTING_LINK_DOMAIN).",
+                exception.Message);
+            Assert.NotNull(exception.HttpResponse);
+            Assert.Null(exception.InnerException);
+        }
+
         private FirebaseAuth CreateFirebaseAuth(HttpMessageHandler handler)
         {
             var userManager = new FirebaseUserManager(new FirebaseUserManager.Args

FirebaseAdmin/FirebaseAdmin/Auth/ActionCodeSettings.cs

@@ -49,12 +49,21 @@ public sealed class ActionCodeSettings
         /// </summary>
         public bool HandleCodeInApp { get; set; }
 
+        /// <summary>
+        /// Gets or sets the hosting link domain to use for the current link if it is to be opened
+        /// using <c>handleCodeInApp</c>, as multiple hosting link domains can be configured per
+        /// project. This setting provides the ability to explicitly choose one. If none is provided,
+        /// the default hosting domain is used.
+        /// </summary>
+        public string LinkDomain { get; set; }
+
         /// <summary>
         /// Gets or sets the dynamic link domain to use for the current link if it is to be opened
         /// using Firebase Dynamic Links, as multiple dynamic link domains can be configured per
         /// project. This setting provides the ability to explicitly choose one. If none is provided,
         /// the oldest domain is used by default.
         /// </summary>
+        [System.Obsolete("DynamicLinkDomain is deprecated, use LinkDomain instead")]
         public string DynamicLinkDomain { get; set; }
 
         /// <summary>

FirebaseAdmin/FirebaseAdmin/Auth/AuthErrorCode.cs

@@ -64,6 +64,11 @@ public enum AuthErrorCode
         /// </summary>
         InvalidDynamicLinkDomain,
 
+        /// <summary>
+        /// The provided hosting link domain is not configured in Firebase Hosting or is not owned by the current project.
+        /// </summary>
+        InvalidHostingLinkDomain,
+
         /// <summary>
         /// The specified ID token has been revoked.
         /// </summary>

FirebaseAdmin/FirebaseAdmin/Auth/AuthErrorHandler.cs

@@ -77,6 +77,13 @@ internal sealed class AuthErrorHandler
                         AuthErrorCode.InvalidDynamicLinkDomain,
                         "Dynamic link domain specified in ActionCodeSettings is not authorized")
                 },
+                {
+                    "INVALID_HOSTING_LINK_DOMAIN",
+                    new ErrorInfo(
+                        ErrorCode.InvalidArgument,
+                        AuthErrorCode.InvalidHostingLinkDomain,
+                        "The provided hosting link domain is not configured in Firebase Hosting or is not owned by the current project")
+                },
                 {
                     "PHONE_NUMBER_EXISTS",
                     new ErrorInfo(

FirebaseAdmin/FirebaseAdmin/Auth/Users/EmailActionLinkRequest.cs

@@ -42,7 +42,10 @@ private EmailActionLinkRequest(string type, string email, ActionCodeSettings set
             {
                 this.Url = settings.Url;
                 this.HandleCodeInApp = settings.HandleCodeInApp;
+#pragma warning disable CS0618
                 this.DynamicLinkDomain = settings.DynamicLinkDomain;
+#pragma warning restore CS0618
+                this.LinkDomain = settings.LinkDomain;
                 this.IosBundleId = settings.IosBundleId;
                 this.AndroidPackageName = settings.AndroidPackageName;
                 this.AndroidMinimumVersion = settings.AndroidMinimumVersion;
@@ -70,6 +73,9 @@ private EmailActionLinkRequest(string type, string email, ActionCodeSettings set
         [JsonProperty("dynamicLinkDomain")]
         internal string DynamicLinkDomain { get; }
 
+        [JsonProperty("linkDomain")]
+        internal string LinkDomain { get; }
+
         [JsonProperty("iOSBundleId")]
         internal string IosBundleId { get; }
 
@@ -125,6 +131,11 @@ private void ValidateSettings()
                 throw new ArgumentException("DynamicLinkDomain must not be empty");
             }
 
+            if (this.LinkDomain == string.Empty)
+            {
+                throw new ArgumentException("LinkDomain must not be empty");
+            }
+
             if (this.IosBundleId == string.Empty)
             {
                 throw new ArgumentException("IosBundleId must not be empty");