Fix STJUnixDateTimeConverter to handle null values for nullable DateTime properties

[jmtdev0]

Pull Request: Fix STJUnixDateTimeConverter to handle null values for nullable DateTime properties

⚠️ DISCLAIMER: Educational/Demonstration Purpose

This PR was created as a demonstration of how AI coding agents can assist developers in their first encounter with a new codebase. The entire process—from understanding the issue, analyzing the repository structure, investigating related work, reproducing the bug, creating tests, and implementing the fix—was conducted as a conversation with a coding agent (GitHub Copilot with Claude).

While this kind of AI-assisted exploration of unfamiliar codebases might not be particularly impressive by January 2026 standards, it remains an interesting exercise in understanding how these tools can facilitate initial contact with complex projects.

I do not expect this PR to be merged, primarily because there is already a more comprehensive solution in the origin/prathmesh/stj-datetimeconvertor branch that the team has been working on. Additionally, the team may have architectural considerations or release timing concerns that make merging this change inappropriate at this time.

This PR exists purely as an educational artifact documenting the journey of understanding and fixing a bug with AI assistance.

---

Why?

Fixes #3157

When deserializing a Stripe.Event payload using System.Text.Json, nullable DateTime? properties throw a JsonException when the JSON value is null. This affects common webhook scenarios where properties like canceled_at, trial_end, or ended_at are null.

Error:

System.Text.Json.JsonException: Unexpected token parsing date. Expected Integer or String, got Null.
   at Stripe.Infrastructure.STJUnixDateTimeConverter.Read(...)

What?

This PR makes two changes:

1. Convert STJUnixDateTimeConverter to a JsonConverterFactory

The converter is now a factory that creates specialized converters for each type:

• STJUnixDateTimeConverterImpl for non-nullable DateTime
• STJUnixNullableDateTimeConverter for nullable DateTime?

The nullable converter properly handles JsonTokenType.Null and returns null instead of throwing an exception.

2. Add JsonConverterFactory support to SerializablePropertyCache

The GetConverter method now detects when a property-level [JsonConverter] attribute specifies a JsonConverterFactory type and handles it appropriately by calling CreateConverter with the property's actual type.

Testing

Added comprehensive unit tests in STJUnixDateTimeConverterTest.cs:

• Deserialization with valid Unix timestamps
• Deserialization with null DateTime values (the core bug scenario)
• Deserialization with multiple nullable DateTime fields
• Deserialization with mixed null and non-null values
• Serialization with null DateTime
• Serialization with DateTime value
• Round-trip tests for both null and non-null values
• Full event payload scenario matching issue STJUnixDateTimeConverter does not handle nullable DateTime properties correctly #3157

Test execution output (click to expand)

dotnet test StripeTests/StripeTests.csproj -f net8.0 --filter "FullyQualifiedName~STJUnixDateTimeConverterTest"
  Stripe.net net8.0 succeeded (7.2s) → Stripe.net\bin\Debug\net8.0\Stripe.net.dll
  StripeTests net8.0 succeeded (0.1s) → StripeTests\bin\Debug\net8.0\StripeTests.dll
[xUnit.net 00:00:00.00] xUnit.net VSTest Adapter v2.4.3+1b45f5407b (64-bit .NET 8.0.20)
[xUnit.net 00:00:00.27]   Discovering: StripeTests (method display = ClassAndMethod, method display options = None)
[xUnit.net 00:00:00.34]   Discovered:  StripeTests (found 1654 test cases)
[xUnit.net 00:00:00.34]   Starting:    StripeTests (parallel test collections = on, max threads = 12)
[xUnit.net 00:00:00.39]   Finished:    StripeTests
  StripeTests test net8.0 succeeded (0.9s)

Test summary: total: 9, failed: 0, succeeded: 9, skipped: 0, duration: 0.8s
Build succeeded in 8.7s

All 9 tests pass without requiring stripe-mock.

Files Changed

• src/Stripe.net/Infrastructure/JsonConverters/STJUnixDateTimeConverter.cs - Converted to JsonConverterFactory pattern with specialized converters
• src/Stripe.net/Infrastructure/JsonConverters/SerializablePropertyCache.cs - Added support for JsonConverterFactory in property-level attributes
• src/StripeTests/Infrastructure/JsonConverters/STJUnixDateTimeConverterTest.cs - New comprehensive test suite

Changelog

• Bug fix for STJUnixDateTimeConverter does not handle nullable DateTime properties correctly #3157. STJUnixDateTimeConverter now properly handles null values for nullable DateTime? properties when deserializing JSON with System.Text.Json.

---

Journey with AI Assistance

This fix was developed through an interactive conversation with a coding agent. Here's the chronology of how we arrived at this solution:

TL;DR: Claude Opus initially attempted a simple fix (just adding null handling). During the investigation, we discovered the origin/prathmesh/stj-datetimeconvertor branch that already contained a comprehensive solution. After running our tests, we realized the simple approach wasn't sufficient due to JsonConverter<DateTime> return type constraints, and we needed the JsonConverterFactory pattern—essentially arriving at the same solution already implemented in that branch.

Phase 1: Issue Discovery & Analysis

• Read and understood issue STJUnixDateTimeConverter does not handle nullable DateTime properties correctly #3157 and its symptoms
• Identified the root cause: STJUnixDateTimeConverter.Read() doesn't handle JsonTokenType.Null
• Compared with the Newtonsoft version (UnixDateTimeConverter) which correctly handles null

Phase 2: Differentiating Related Issues

• Analyzed PR Check if a datetime is in millis #3254 (milliseconds vs seconds handling) and confirmed it's a separate bug
• Understood that issue STJUnixDateTimeConverter does not handle nullable DateTime properties correctly #3157 is specifically about null handling, not timestamp format

Phase 3: Reproduction & Test Creation

• Created a reproduction console app demonstrating the bug
• Created comprehensive unit tests that don't require stripe-mock
• Verified tests fail with the original code and pass with the fix

Phase 4: Investigation of Existing Work

• Discovered the origin/prathmesh/stj-datetimeconvertor branch with a more comprehensive solution
• Understood that the team has been working on this with a JsonConverterFactory approach
• Recognized that SerializablePropertyCache needed modification to support factories

Phase 5: Implementation

• Initially tried a simpler fix (just adding null check) but discovered it doesn't work due to JsonConverter<DateTime> return type constraints
• Understood why JsonConverterFactory is necessary for proper null handling with DateTime?
• Implemented the factory pattern similar to the approach in prathmesh's branch
• Added factory support to SerializablePropertyCache

Phase 6: Validation

• All 9 new tests pass
• All 16 Wholesome tests pass (converter validation)
• No regressions in the codebase

---

Acknowledgments

Thanks to @sebastiencrevier for the detailed bug report with reproduction steps, and to @prathmesh-stripe and @jar-stripe for their work and collaboration in addressing this issue.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

JMTDESKTOP25\jmart seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

JMTDESKTOP25\jmart seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}