Refactor preview services to return Billing::PreviewResult objects

The following discussion from !14704 should be addressed:

  • @vitallium started a discussion:

    suggestion: I think we can use the existing PreviewResult class here to work with an object instead of plain hash. The naming is not that good, IMHO, Billing::PreviewResult, so I'd check if we can rename it to something more meaningful.

Problem

The Zuora::Orders::PreviewService and related services currently return raw hash objects when previewing orders and subscriptions. This creates inconsistent data access patterns across the codebase, where some parts of the application expect hash access (e.g., [:success]) while others may expect object methods (e.g., .success).

This inconsistency makes the code harder to maintain and more prone to errors when accessing preview results. Additionally, it violates the principle of returning structured domain objects instead of primitive data structures.

Proposal

Standardize all preview service responses to return Billing::PreviewResult objects instead of raw hashes. This involves:

  1. PreviewService: Return Billing::PreviewResult object
  2. Seat Addition Resolver: Update to use .success instead of [:success], handle message attribute
  3. Reconciliation Service: Convert hash to PreviewResult object before accessing
  4. Send Reconciliation Email Job: Convert hash to PreviewResult object before accessing
  5. Order Preview Resolver: Convert hash to PreviewResult object before accessing
  6. PreviewResult Model (Optional): Add message and errors attributes if needed for error handling
  7. Interactions (Review): Check if NewRatePlan.preview needs similar updates

Key Implementation Principle:

Wherever amendment_preview or similar methods return a hash from SubscriptionUpdateService.execute(...).payload, wrap it with Billing::PreviewResult.build_from_preview_service_data() before accessing its properties.