SDK update: forward-compatible enums

🌿 Fern Regeneration -- June 30, 2025

Author: niteshsandal-merge

src/Merge.Client.Test/Core/Json/EnumSerializerTests.cs

@@ -0,0 +1,138 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Merge.Client.Core;
+using NUnit.Framework;
+
+namespace Merge.Client.Test.Core.Json;
+
+[TestFixture]
+[Parallelizable(ParallelScope.All)]
+public class StringEnumSerializerTests
+{
+    private static readonly JsonSerializerOptions JsonOptions = new() { WriteIndented = true };
+
+    private static readonly DummyEnum KnownEnumValue2 = DummyEnum.KnownValue2;
+    private static readonly DummyEnum UnknownEnumValue = DummyEnum.FromCustom("unknown_value");
+
+    private static readonly string JsonWithKnownEnum2 = $$"""
+        {
+            "enum_property": "{{KnownEnumValue2}}"
+        }
+        """;
+
+    private static readonly string JsonWithUnknownEnum = $$"""
+        {
+            "enum_property": "{{UnknownEnumValue}}"
+        }
+        """;
+
+    [Test]
+    public void ShouldParseKnownEnumValue2()
+    {
+        var obj = JsonSerializer.Deserialize<DummyObject>(JsonWithKnownEnum2, JsonOptions);
+        Assert.That(obj, Is.Not.Null);
+        Assert.That(obj.EnumProperty, Is.EqualTo(KnownEnumValue2));
+    }
+
+    [Test]
+    public void ShouldParseUnknownEnum()
+    {
+        var obj = JsonSerializer.Deserialize<DummyObject>(JsonWithUnknownEnum, JsonOptions);
+        Assert.That(obj, Is.Not.Null);
+        Assert.That(obj.EnumProperty, Is.EqualTo(UnknownEnumValue));
+    }
+
+    [Test]
+    public void ShouldSerializeKnownEnumValue2()
+    {
+        var json = JsonSerializer.SerializeToElement(
+            new DummyObject { EnumProperty = KnownEnumValue2 },
+            JsonOptions
+        );
+        TestContext.Out.WriteLine("Serialized JSON: \n" + json);
+        var enumString = json.GetProperty("enum_property").GetString();
+        Assert.That(enumString, Is.Not.Null);
+        Assert.That(enumString, Is.EqualTo(KnownEnumValue2));
+    }
+
+    [Test]
+    public void ShouldSerializeUnknownEnum()
+    {
+        var json = JsonSerializer.SerializeToElement(
+            new DummyObject { EnumProperty = UnknownEnumValue },
+            JsonOptions
+        );
+        TestContext.Out.WriteLine("Serialized JSON: \n" + json);
+        var enumString = json.GetProperty("enum_property").GetString();
+        Assert.That(enumString, Is.Not.Null);
+        Assert.That(enumString, Is.EqualTo(UnknownEnumValue));
+    }
+}
+
+public class DummyObject
+{
+    [JsonPropertyName("enum_property")]
+    public DummyEnum EnumProperty { get; set; }
+}
+
+[JsonConverter(typeof(StringEnumSerializer<DummyEnum>))]
+public readonly record struct DummyEnum : IStringEnum
+{
+    public DummyEnum(string value)
+    {
+        Value = value;
+    }
+
+    /// <summary>
+    /// The string value of the enum.
+    /// </summary>
+    public string Value { get; }
+
+    public static readonly DummyEnum KnownValue1 = FromCustom(Values.KnownValue1);
+
+    public static readonly DummyEnum KnownValue2 = FromCustom(Values.KnownValue2);
+
+    /// <summary>
+    /// Constant strings for enum values
+    /// </summary>
+    public static class Values
+    {
+        public const string KnownValue1 = "known_value1";
+
+        public const string KnownValue2 = "known_value2";
+    }
+
+    /// <summary>
+    /// Create a string enum with the given value.
+    /// </summary>
+    public static DummyEnum FromCustom(string value)
+    {
+        return new DummyEnum(value);
+    }
+
+    /// <summary>
+    /// Returns the string value of the enum.
+    /// </summary>
+    public override string ToString()
+    {
+        return Value;
+    }
+
+    public bool Equals(string? other)
+    {
+        return Value.Equals(other);
+    }
+
+    public override int GetHashCode()
+    {
+        return Value.GetHashCode();
+    }
+
+    public static explicit operator string(DummyEnum value) => value.Value;
+
+    public static explicit operator DummyEnum(string value) => new(value);
+
+    public static bool operator ==(DummyEnum value1, string value2) => value1.Value.Equals(value2);
+
+    public static bool operator !=(DummyEnum value1, string value2) => !value1.Value.Equals(value2);
+}

src/Merge.Client.Test/Core/Json/StringEnumSerializerTests.cs

@@ -0,0 +1,40 @@
+using Merge.Client;
+using Merge.Client.Core;
+using NUnit.Framework;
+using WireMock.Logging;
+using WireMock.Server;
+using WireMock.Settings;
+
+namespace Merge.Client.Test.Unit.MockServer;
+
+[SetUpFixture]
+public class BaseMockServerTest
+{
+    protected static WireMockServer Server { get; set; } = null!;
+
+    protected static BaseMergeClient Client { get; set; } = null!;
+
+    protected static RequestOptions RequestOptions { get; set; } = new();
+
+    [OneTimeSetUp]
+    public void GlobalSetup()
+    {
+        // Start the WireMock server
+        Server = WireMockServer.Start(
+            new WireMockServerSettings { Logger = new WireMockConsoleLogger() }
+        );
+
+        // Initialize the Client
+        Client = new BaseMergeClient(
+            "API_KEY",
+            clientOptions: new ClientOptions { BaseUrl = Server.Urls[0], MaxRetries = 0 }
+        );
+    }
+
+    [OneTimeTearDown]
+    public void GlobalTeardown()
+    {
+        Server.Stop();
+        Server.Dispose();
+    }
+}

src/Merge.Client.Test/Unit/MockServer/BaseMockServerTest.cs

@@ -0,0 +1,117 @@
+using global::System.Threading.Tasks;
+using Merge.Client.Ats;
+using Merge.Client.Core;
+using NUnit.Framework;
+
+namespace Merge.Client.Test.Unit.MockServer;
+
+[TestFixture]
+public class ChangeStageCreateTest : BaseMockServerTest
+{
+    [Test]
+    public async global::System.Threading.Tasks.Task MockServerTest()
+    {
+        const string requestJson = """
+            {}
+            """;
+
+        const string mockResponse = """
+            {
+              "model": {
+                "id": "92e8a369-fffe-430d-b93a-f7e8a16563f1",
+                "remote_id": "98796",
+                "created_at": "2021-09-15T00:00:00.000Z",
+                "modified_at": "2021-10-16T00:00:00.000Z",
+                "candidate": "candidate",
+                "job": "job",
+                "applied_at": "2021-10-15T00:00:00.000Z",
+                "rejected_at": "2021-11-15T00:00:00.000Z",
+                "offers": [
+                  "e9b5c11d-c588-468e-8567-cd6992e42b62"
+                ],
+                "source": "Campus recruiting event",
+                "credited_to": "credited_to",
+                "screening_question_answers": [
+                  "screening_question_answers",
+                  "screening_question_answers"
+                ],
+                "current_stage": "current_stage",
+                "reject_reason": "reject_reason",
+                "remote_was_deleted": true,
+                "field_mappings": {
+                  "organization_defined_targets": {
+                    "custom_key": "custom_value"
+                  },
+                  "linked_account_defined_targets": {
+                    "custom_key": "custom_value"
+                  }
+                },
+                "remote_data": [
+                  {
+                    "path": "/candidacies",
+                    "data": [
+                      "Varies by platform"
+                    ]
+                  }
+                ]
+              },
+              "warnings": [
+                {
+                  "source": {
+                    "pointer": "pointer"
+                  },
+                  "title": "Unrecognized Field",
+                  "detail": "An unrecognized field, age, was passed in with request data.",
+                  "problem_type": "UNRECOGNIZED_FIELD"
+                }
+              ],
+              "errors": [
+                {
+                  "source": {
+                    "pointer": "pointer"
+                  },
+                  "title": "Missing Required Field",
+                  "detail": "custom_fields is a required field on model.",
+                  "problem_type": "MISSING_REQUIRED_FIELD"
+                }
+              ],
+              "logs": [
+                {
+                  "log_id": "99433219-8017-4acd-bb3c-ceb23d663832",
+                  "dashboard_view": "https://app.merge.dev/logs/99433219-8017-4acd-bb3c-ceb23d663832",
+                  "log_summary": {
+                    "url": "www.exampleintegration.com/api/v1/exampleapi",
+                    "method": "POST",
+                    "status_code": 200
+                  }
+                }
+              ]
+            }
+            """;
+
+        Server
+            .Given(
+                WireMock
+                    .RequestBuilders.Request.Create()
+                    .WithPath("/ats/v1/applications/id/change-stage")
+                    .WithHeader("Content-Type", "application/json")
+                    .UsingPost()
+                    .WithBodyAsJson(requestJson)
+            )
+            .RespondWith(
+                WireMock
+                    .ResponseBuilders.Response.Create()
+                    .WithStatusCode(200)
+                    .WithBody(mockResponse)
+            );
+
+        var response = await Client.Ats.Applications.ChangeStageCreateAsync(
+            "id",
+            new UpdateApplicationStageRequest()
+        );
+        Assert.That(
+            response,
+            Is.EqualTo(JsonUtils.Deserialize<ApplicationResponse>(mockResponse)).UsingDefaults()
+        );
+    }
+}