Feature/sdk improvements

[wzul]

What does this change?

This PR represents a major architectural modernization of the CHIP PHP SDK, transitioning it from a basic Guzzle wrapper to a robust, enterprise-ready SDK (v2.0.0).

The Problem:
The previous version lacked strong type safety, had limited observability, and required developers to manually handle raw HTTP response parsing and Guzzle-specific exceptions. The absence of a structured CI/CD pipeline and static analysis made the codebase prone to regressions, while the reliance on legacy PHP versions prevented the use of modern language features.

The Solution:

1. Language Modernization: Bumped minimum requirement to PHP 8.1, adopting constructor property promotion, explicit type hints, and match expressions.
2. Resource-Based Architecture: Moved from a flat, trait-based client to a resource-oriented structure (e.g., $chip->purchases->create() instead of $chip->createPurchase()). This improves discoverability and organizes the API into logical domains (purchases, clients, webhooks, account, billing, etc.).
3. Domain-Specific Exception Hierarchy: Refactored the core request logic to map HTTP errors to specific exceptions (AuthenticationException, ValidationException, NotFoundException, etc.). ValidationException now allows developers to call $e->getErrors() to retrieve granular API feedback.
4. Observability & Logging: Integrated PSR-3 Logging support, allowing developers to inject any compliant logger to track the request/response lifecycle.
5. Resilience & Retries: Added an internal RetryClient decorator using Guzzle middleware to provide exponential backoff for 429 (Rate Limit) and 5xx (Server Error) responses.
6. Fluent Builder Pattern: Introduced PurchaseBuilder to provide a developer-friendly API for constructing complex Purchase models without manual nesting of objects.
7. Model Refinement: Replaced the netresearch/jsonmapper dependency with native fromArray() static factories on models. Fixed property types (e.g., changing Product::$quantity from float to string|null) to accurately reflect API payloads and prevent precision issues.
8. Pagination Iterators: Added iterate() methods to list endpoints, allowing developers to process large datasets without manually managing page tokens.
9. Robust CI/CD:
   • GitHub Actions for multi-version testing (PHP 8.1–8.4).
   • PHPStan (Level 8) for strict static analysis.
   • PHP-CS-Fixer (PSR-12) for automated linting.
   • Automated Changelog validation and Release notes generation.

Asana / Jira / Trello task link

How to test

1. Automated Suite: Run composer test to ensure the refactored exception mapping and new resource classes pass across PHP 8.1 through 8.4.
2. Static Analysis: Run composer phpstan to verify that all new type hints and docblocks satisfy Level 8 analysis.
3. Code Style: Run composer cs-check to ensure adherence to the new PSR-12 configuration.
4. Resource Migration: Verify the new access pattern in a test script:

   $chip = new \Chip\ChipApi('brand-id', 'api-key');
   $methods = $chip->paymentMethods->list('MYR');

5. Builder Verification:

   $purchase = \Chip\Builder\PurchaseBuilder::create()
       ->brandId('test-id')
       ->currency('MYR')
       ->addProduct('Item 1', 1000)
       ->build();

6. Error Mapping: Manually trigger a 422 error and verify that ValidationException::getErrors() correctly parses the error payload.
7. Pagination: Test the iterate() methods in ClientsResource or WebhooksResource against an account with multiple pages of data.

Potential Risks & Senior Review Items

• Major Breaking Changes: This PR drops support for PHP < 8.1 and completely changes the public API surface. Existing integrations will break upon upgrading to v2.0.0. Review MIGRATION.md for completeness.
• Model Property Types: Properties like Product::$quantity and Product::$tax_percent were changed from float to string|null. While this matches the API's string-based decimal representation, users performing direct arithmetic on these properties will now need to cast them to floats.
• Retry Logic: Review the exponential backoff implementation in lib/Http/RetryClient.php. Ensure the default max retries (3) and timing won't lead to excessive execution times in synchronous request cycles.
• Resource Lazy-Loading: The ChipApi class uses magic __get or direct instantiation for resources. Review lib/ChipApi.php to ensure resource objects are handled efficiently.
• Dependency Removal: We have removed netresearch/jsonmapper. Confirm that the manual fromArray() implementations in lib/Model/ cover all edge cases previously handled by the library.

Is this PR warrant an automatic approval?

No. This is a foundational refactor that changes the error-handling contract, introduces a new major PHP requirement, and alters the core request architecture. It requires a thorough manual architectural review.

Images

Back-End or Front-End dependency tasks/PRs?