feat: validation policy, route classifier and typed validation errors - #1
Merged
Merged
Conversation
…& document-return services Makes the international business-rule handling flexible instead of hard-coded, per integrator feedback (v1.1.0 -> v1.2.0). Default behaviour stays strict. New public API (VeryCodeCom\Suus\Validation, \Routing): - SuusClient::validate(ShipmentOrder): ValidationError[] - pre-flight validation with no network call; auto-selects the sender-country calendar (mirrors createShipment). Lets integrators surface validation without touching @internal. - ValidationError (message/field/code, Stringable) + ValidationCode - typed errors reusing the exact SUUS codes where one exists (PRJ00351/00352/00372/00373/...). - ValidationPolicy (strict()/relaxed() + per-rule flags enforceInternationalB2B, enforceServiceRouteRestrictions, enforceInternationalPackagingRestrictions), injectable via `new SuusClient($config, policy: ...)`. - RouteClassifierInterface + DefaultRouteClassifier + CallableRouteClassifier, injectable via `routeClassifier:`. Overrides the domestic/international decision the library uses for BOTH validation and the generated XML. Newly enforced locally (previously only rejected server-side by SUUS), all policy-toggleable and confirmed against the SUUS WebApi docs (WS PK 1.0): - international orders reject domestic-only services (StdAwizacjaSms, StdWniesienie2, StdDokumentyZwrotneINiezwrotneGrid2) and returnable/stackable packaging (PRJ00372/PRJ00373); - domestic orders reject the international-only document-return service (StdDokumentyZwrotneINiezwrotneGrid3). New typed services: - DocumentReturnDomesticService (StdDokumentyZwrotneINiezwrotneGrid2, domestic only) - DocumentReturnInternationalService (StdDokumentyZwrotneINiezwrotneGrid3, intl only) sharing AbstractDocumentReturnService with TAG_*/DOC_* constants. Internal changes: - ShipmentValidator::validate() now returns ValidationError[] and accepts optional ValidationPolicy/RouteClassifier; SoapEnvelopeBuilder takes a RouteClassifier. - SuusValidationException::$errors is now ValidationError[] (Stringable); bare strings are wrapped, so getErrors(): string[] and existing usage keep working. Adds getValidationErrors(): ValidationError[]. Route-classifier caveat (verified live on the sandbox): the classifier is a client-side override only. SUUS classifies each shipment on its own side from the address country codes, so a non-PL route (e.g. DE->DE) forced to "domestic" is still rejected (BTN0002, missing incoterms) unless the contract/product supports it. The README/example/docblocks document this explicitly. Docs/examples: README (Additional Services + new Pre-flight Validation, Policies & Route Classification section), CHANGELOG (1.2.0), examples 05 (document-return service) and new 08 (validate/policy/classifier). Tests: 326 -> 355 unit tests (540 assertions); existing validator tests adapted to typed errors; new ValidationPolicyAndRoutingTest covers policy/classifier/new services in both route directions. PHPStan level 8 clean. Existing sandbox integration tests still pass end-to-end.
very-code-com
changed the title
Repository owner
locked as resolved and limited conversation to collaborators
Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Development branch for the validation and routing work that ships in the 1.0.0 release.
SuusClient::validate()for pre-flight checks with no network call.ValidationError/ValidationCode, reusing the SUUS codes where one exists.ValidationPolicyto toggle the route-shaped rules, strict by default.RouteClassifierInterfaceto redefine which routes count as international, driving both validation and the generated XML.See the repository history and
CHANGELOG.mdfor the released state.