Expand PurchaseBuilder with all missing API fields

[wzul]

What does this change?

This PR brings the PurchaseBuilder into full parity with the CHIP Collect OpenAPI specification. Previously, the SDK's fluent interface was incomplete, forcing developers to manually assign values to model properties, which bypassed type safety and led to inconsistent code styles.

Key technical changes:

• Fluent Interface Expansion: Implemented a comprehensive set of setter methods across three logical areas:
  • Top-level Purchase: Added clientId, sendReceipt, skipCapture, forceRecurring, reference, issued, due, creatorAgent, platform, tags, and paymentMethodWhitelist.
  • Purchase Details: Added methods for notes, debt, subtotalOverride, totalTaxOverride, totalDiscountOverride, totalOverride, requestClientDetails, timezone, dueStrict, emailMessage, shippingOptions, paymentMethodDetails, hasUpsellProducts, singleAttempt, and metadata.
  • Client Details: Added full address support (street, city, zip, state, country) for both billing and shipping, contact lists (cc, bcc), and corporate identity fields (legal name, registration, tax numbers, bank details).
• Refined Product Logic: The addProduct() method signature has been extended to support optional fields (discount, tax_percent, category, total_price_override).
• Data Normalization: Standardized the quantity field to be handled as a string. This aligns with the API's expectation for high-precision decimals and prevents floating-point rounding issues during serialization.
• Lazy Initialization: Leveraged ensureClient() within the builder to manage nested ClientDetails objects, ensuring the fluent API remains clean without requiring the developer to instantiate nested models manually.

Asana / Jira / Trello task link

How to test

1. Unit Testing: Execute the expanded test suite to verify all new mappings:

   vendor/bin/phpunit tests/PurchaseBuilderTest.php

2. Coverage Verification: Ensure the following new test cases pass:
   • testTopLevelPurchaseFields: Verifies mapping of root-level properties.
   • testPurchaseDetailsFields: Verifies overrides and metadata nesting.
   • testClientDetailsFields & testNullableClientDetailsFields: Validates the ClientDetails object construction and handling of null values for optional states/bank codes.
   • testProductWithAllFields: Confirms the new optional parameters in addProduct map to the Product model correctly.
   • testClientIsCreatedOnlyOnce: Ensures the ensureClient() logic preserves state across multiple calls.

Potential Risks & Senior Review Items

• Core Method Signature Change: addProduct() now has four additional optional parameters. While this is backward compatible for positional arguments, it may affect consumers using reflection or specific interceptors.
• Field Mapping Accuracy: Please cross-reference the snake_case keys in PurchaseBuilder.php (e.g., total_tax_override, shipping_street_address) against the official CHIP Collect API docs to ensure no typos were introduced in the mapping logic.
• Type Casting: quantity is now strictly cast to string. Verify that existing integrations expecting float in the resulting model object (though unlikely for a builder) are not negatively impacted.
• Nested Object State: Review the ensureClient() pattern to confirm that calling multiple client* methods sequentially correctly modifies the same ClientDetails instance.

Is this PR warrant an automatic approval?

No. While many of the additions are boilerplate setters, the sheer volume of new fields and the modification of the addProduct signature require a manual sanity check to ensure architectural consistency and API alignment.

Images