test(realtime): add tests for optional refs handling in message serialization

[grdsdev]

Description

This PR adds comprehensive tests for nil ref scenarios to verify and document that optional ref and joinRef fields are properly handled in JSON encoding/decoding. The Swift SDK already has the correct implementation with optional types, but these tests prevent regressions and ensure SDK parity with other language implementations.

Context

The JavaScript SDK recently fixed an issue with message serialization in the Realtime library to properly handle null/undefined ref and join_ref fields when encoding messages (PR #1862).

The Swift SDK already has the correct implementation:

• Both ref and joinRef are optional (String?)
• Codable protocol properly encodes/decodes optionals as JSON null
• Heartbeats already use nil for joinRef correctly

Changes

• Added comprehensive test coverage for nil ref scenarios:
  • Messages with both refs as nil
  • Heartbeat messages with nil joinRef
  • JSON encoding/decoding with nil values
  • Messages with both ref and joinRef
  • Messages with ref but nil joinRef
• Added documentation comments to RealtimeMessageV2 struct explaining why refs are optional

Testing

• ✅ All new tests pass (5/5)
• ✅ All existing tests pass (7/7 total in RealtimeMessageV2Tests)
• ✅ No breaking changes - this is purely additive (tests and documentation)

Code Review Verification

• ✅ No binary serialization paths exist that don't handle optional refs (only JSON encoding is used)
• ✅ JSON encoding/decoding handles nil refs correctly (Codable does this automatically)
• ✅ Heartbeats already use nil for joinRef (confirmed in RealtimeClientV2.swift:487)

Related

• Linear Issue: SDK-532
• JavaScript SDK PR: fix(realtime): account for null refs when encoding messages supabase-js#1862

[coveralls]

Pull Request Test Coverage Report for Build 20148490201

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 80.447%

---

Totals
Change from base Build 20096086835:	0.0%
Covered Lines:	6328
Relevant Lines:	7866

---

💛 - Coveralls