v1.2.0 - Configurable validation, route classification & typed errors

Makes the international business-rule handling flexible instead of hard-coded, based on real
integrator feedback. Defaults stay strict, so upgrading from 1.1.0 is drop-in.

Added

Public pre-flight validation

• SuusClient::validate(ShipmentOrder): ValidationError[] — the same checks as createShipment()
  with no network call, auto-selecting the sender-country calendar. No need to reach into the
  @internal ShipmentValidator anymore.

Typed validation errors

• ValidationError (message / field / code, Stringable) and ValidationCode — reusing the
  exact SUUS codes where one exists (PRJ00372, PRJ00373, PRJ00351, PRJ00345, …).
• SuusValidationException::getValidationErrors(); getErrors(): string[] unchanged.

foreach ($client->validate($order) as $e) {
    echo "[{$e->code}] {$e} (field: {$e->field})\n";
}

Configurable validation policy

• ValidationPolicy::strict() (default) / ::relaxed(), plus per-rule flags:
  enforceInternationalB2B, enforceServiceRouteRestrictions,
  enforceInternationalPackagingRestrictions.

$client = new SuusClient($config, policy: ValidationPolicy::relaxed());

Overridable route classification

• RouteClassifierInterface with DefaultRouteClassifier / CallableRouteClassifier, driving
  both validation and the generated XML (<shipper>/<consignee> blocks + incoterms emission).

$client = new SuusClient($config, routeClassifier: new CallableRouteClassifier(
    fn (ShipmentOrder $o): bool => /* your domestic/international rule */
));

New typed services

• DocumentReturnDomesticService (StdDokumentyZwrotneINiezwrotneGrid2, domestic only)
• DocumentReturnInternationalService (StdDokumentyZwrotneINiezwrotneGrid3, international only)

Locally enforced route rules (previously only rejected server-side by SUUS), all
policy-toggleable and confirmed against the official 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 (…Grid3).

Changed

• ShipmentValidator::validate() (@internal) returns ValidationError[] and accepts optional
  ValidationPolicy / RouteClassifier; SoapEnvelopeBuilder takes a RouteClassifier.
• SuusValidationException::$errors now holds ValidationError objects. They are Stringable,
  bare strings passed to the constructor are wrapped, and getErrors(): string[] is unchanged —
  existing code keeps working.

Route-classifier caveat (verified against the sandbox)

The classifier is a client-side override only. SUUS classifies routes on its own side from the
address country codes, so a non-PL route (e.g. DE->DE) forced to "domestic" is still rejected with
BTN0002 ("produkt Drobnica międzynarodowa" + missing incoterms) unless your contract/product
supports it. Use ValidationPolicy when you only want to relax the local intl-only checks.

Verification

• 355 unit tests / 540 assertions, 0 failures (was 326); PHPStan level 8 clean; CI green on PHP
  8.2 / 8.3 / 8.4.
• Live sandbox addOrder runs, including the new document-return services on both route directions.

Docs

New README section Pre-flight Validation, Policies & Route Classification, validate() in the API
reference, updated services/exceptions tables, and a new runnable offline example
examples/08_validation_and_policies.php.

Full changelog: v1.1.0...v1.2.0

v1.1.0

Added

• Debug mode - SuusConfig gains a debug flag (constructor arg, SUUS_DEBUG
  env var, or 'debug' array key). When enabled, the client logs a full debug
  report (message + raw SUUS response + stack trace) at error level for every
  failure, ideal for diagnosing unrecognised errors such as bare BTN0001.
• SuusException::getRawResponse(): ?string - the exact XML SUUS returned (always
  captured for API/parse/transport errors, independent of the debug flag).
• SuusException::getDebugReport(): string - bundles the message, raw response and
  stack trace for logging or developer-facing output.
• ShipmentOrder: optional costGroup, freight and currency header fields for
  full international-order support (freight/currency are serialized only for
  international routes and must be provided together, per SUUS rule PRJ00387).
• ResponseParser::returnDesc() - parses the <returnDesc> element so bare SUUS
  codes without an errorCodes list (e.g. BTN0001) surface a human-readable
  reason in the thrown SuusApiException message.
• Validation: international (non-PL->PL) orders now require orderType B2B, reject
  a lone freight/currency, and enforce currency (3 chars) / costGroup (<=20)
  length limits.

Changed

• InsuranceService: int01 is now always emitted as "1" - the mandatory SUUS
  "goods not in excluded groups" declaration (missing it caused PRJ000293). The
  misleading ?string $goodsDeclaration constructor argument is replaced by
  bool $confirmGoodsNotExcluded = true.
• Error surfacing is centralised through a single internal fail() path so raw
  responses and debug logging are applied consistently across all API methods.

Fixed

• examples/05_additional_services.php: corrected constructor argument names
  (additionalServices, InsuranceService(amount:), CodService(amount:)) and
  added the EUR-pallet dimensions / sender e-mail required by SUUS.

v1.0.1

Fixes

• EUR pallet minimum height enforced to 20 cm — SUUS API rejects packages below this threshold (returns BTN0001). ShipmentValidator now catches this locally before sending the request.
• Fixed heightCm in example 01_create_shipment.php (was 15, now 20).

Upgrade

composer update very-code-com/suus-php

v1.0.0 - Initial Release

very-code-com/suus-php v1.0.0

First stable release of the PHP client library for SUUS Logistics SOAP API.

Features

• Full SUUS SOAP API integration (create shipments, fetch status, fetch documents)
• Business calendar support for PL, DE, AT, CH, CZ, HU, RO, SK, SI
• Config via constructor, fromEnv(), or fromArray()
• All 13 package types (PackageSymbol) and 7 additional services
• Typed exceptions hierarchy
• 164 unit tests, PHPStan level 8

Requirements

• PHP 8.2+
• ext-curl, ext-dom

Installation

composer require very-code-com/suus-php