feat!: Namespace refactor, PHP 8.3, webhook DTOs & improved error handling

[yannelli]

⚠️ Breaking Changes

• Namespace Change: Nextvisit\ClaimMDWrapper has been renamed to Nextvisit\ClaimMD. All imports must be updated
  accordingly.
• PHP Version Requirement: Minimum PHP version bumped from 8.2 to 8.3.

Description

Enhancements and New Features

• Added detailed documentation for webhook integration, including usage examples (enroll and appeal events) and
  WebhookPayloadDTO utility.
• Introduced WebhookEventDTO, WebhookEnrollEventDTO, and WebhookAppealEventDTO for managing and validating webhook
  payloads.
• Implemented custom exceptions for improved error handling in multiple request classes (ClaimRequest, FileRequest,
  ProviderRequest, and more).
• Expanded exception handling to include ClaimMD-specific errors for Client and Claim.MD SDK requests.

Bug Fixes

• Improved validation safeguards (e.g., empty array check and date validation) across DTOs and request implementations.
• Enhanced error messaging for validation failures.

Refactoring

• Transitioned namespaces, removing "Wrapper" suffix across DTOs, requests, and configuration files.
• Updated test configurations and Pest namespaces to align with the new structure.
• Enforced stricter type declarations and improved docblock consistency for better code maintainability.

Checklist

• Tests added/updated.
• Documentation updated where necessary.
• Verified compatibility with PHP 8.3.
• Code reviewed and approved.

[Copilot]

Pull request overview

This PR delivers a breaking namespace rename (Nextvisit\ClaimMDWrapper → Nextvisit\ClaimMD), raises the minimum PHP version to 8.3, and expands the SDK with webhook DTOs and more structured HTTP error handling via custom exceptions.

Changes:

• Renamed namespaces across src/ and tests/, updated Composer PSR-4 autoloading, and bumped PHP requirement to >=8.3.
• Added webhook DTOs (WebhookPayloadDTO, WebhookEventDTO, enroll/appeal event DTOs) with serialization + validation and corresponding unit tests.
• Implemented richer client-side error handling with new exception types for common HTTP failure modes and added client tests.

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/Unit/Requests/ResponseRequestTest.php	Updates imports to new Nextvisit\ClaimMD namespace.
tests/Unit/Requests/ProviderRequestTest.php	Updates imports to new namespace.
tests/Unit/Requests/PayerRequestTest.php	Updates imports to new namespace.
tests/Unit/Requests/FileRequestTest.php	Updates imports to new namespace.
tests/Unit/Requests/EligibilityRequestTest.php	Updates imports to new namespace.
tests/Unit/Requests/ERARequestTest.php	Updates imports to new namespace.
tests/Unit/Requests/ClaimRequestTest.php	Updates imports to new namespace.
tests/Unit/DTO/WebhookPayloadDTOTest.php	Adds unit tests for webhook payload DTO parsing/validation/serialization.
tests/Unit/DTO/WebhookEventDTOTest.php	Adds unit tests for webhook event DTO parsing/validation/serialization.
tests/Unit/DTO/WebhookEnrollEventDTOTest.php	Adds unit tests for webhook enroll event DTO parsing/validation/serialization.
tests/Unit/DTO/WebhookAppealEventDTOTest.php	Adds unit tests for webhook appeal event DTO parsing/validation/serialization.
tests/Unit/DTO/ProviderEnrollmentDTOTest.php	Updates import namespace for DTO tests.
tests/Unit/DTO/EligibilityDTOTest.php	Updates import namespace for DTO tests.
tests/Unit/DTO/ERADTOTest.php	Updates import namespace and adjusts expected validation message.
tests/Unit/DTO/ClaimAppealDTOTest.php	Updates import namespace for DTO tests.
tests/Unit/ConfigTest.php	Updates import namespace for config tests.
tests/Unit/ClientTest.php	Updates imports and adds coverage for new exception mapping/error handling paths.
tests/TestCase.php	Updates test namespace to Nextvisit\ClaimMD\Tests.
tests/Pest.php	Updates Pest bootstrap to use new TestCase namespace.
src/Requests/ResponseRequest.php	Renames namespace, types endpoint const, and documents new exception behavior.
src/Requests/ProviderRequest.php	Renames namespace, types endpoint const, and documents new exception behavior.
src/Requests/PayerRequest.php	Renames namespace, types endpoint const, and documents new exception behavior.
src/Requests/FileRequest.php	Renames namespace, adds upload date calendar validation, and tightens typing.
src/Requests/EligibilityRequest.php	Renames namespace, uses Utils::streamFor for multipart, and updates docs.
src/Requests/ERARequest.php	Renames namespace, types endpoint consts, and changes getList() default argument semantics.
src/Requests/ClaimRequest.php	Renames namespace, types endpoint consts, and updates docs for new exceptions.
src/Exceptions/ServerException.php	Adds 5xx-specific API exception type.
src/Exceptions/RateLimitException.php	Adds 429-specific API exception type with Retry-After support.
src/Exceptions/NotFoundException.php	Adds 404-specific API exception type.
src/Exceptions/InvalidResponseException.php	Adds exception for non-JSON/undecodable responses.
src/Exceptions/ClaimMDException.php	Introduces base SDK exception type.
src/Exceptions/AuthenticationException.php	Adds 401-specific API exception type.
src/Exceptions/ApiException.php	Adds generic HTTP error exception with status + decoded body.
src/DTO/WebhookPayloadDTO.php	Adds webhook payload DTO with toArray(), fromArray(), fromJsonString().
src/DTO/WebhookEventDTO.php	Adds webhook event DTO with validation and (de)serialization helpers.
src/DTO/WebhookEnrollEventDTO.php	Adds webhook enroll event DTO with validation + mapping.
src/DTO/WebhookAppealEventDTO.php	Adds webhook appeal event DTO with validation + mapping.
src/DTO/ProviderEnrollmentDTO.php	Renames namespace and adjusts situational validation logic/comment.
src/DTO/EligibilityDTO.php	Renames namespace and adds calendar-date validation + strict in_array.
src/DTO/ERADTO.php	Renames namespace and improves date error messaging based on allowed values.
src/DTO/ClaimAppealDTO.php	Renames namespace and standardizes InvalidArgumentException usage/import.
src/Config.php	Renames namespace to Nextvisit\ClaimMD.
src/Client.php	Renames namespace, disables Guzzle http_errors, and adds structured error-to-exception mapping.
composer.json	Bumps PHP requirement to 8.3 and updates PSR-4 autoload namespaces.
README.md	Updates documentation examples to the new namespace and adds webhook docs.
CLAUDE.md	Adds repository guidance docs (commands, architecture, testing notes).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.