Modernize SDK: full API, 54-FZ receipts, webhook IPs, and QA

[listopad]

Brings the single-file SDK up to the current Unitpay backend: 54-FZ receipts,
the full REST API surface (incl. mass payouts), a dynamic webhook IP allowlist,
passive version telemetry, native type declarations, and a first PHPUnit suite +
QA tooling. No runtime dependencies added; still php >=7.4, ext-json, cURL
optional.

47 files changed (+4095 / −578).

Features

• 54-FZ receipts — CashItem dictionaries synced with the backend (new VAT
  rates incl. calculated ones; new payment objects; deprecated the ones the
  public API rejects) and optional fields (sum, currency, measure,
  nomenclatureCode, markCode, markQuantity, pre_text, post_text),
  serialized only when set.
• Full REST API coverage in api() — payments, refunds, confirm/cancel,
  subscriptions, account/reference calls, and mass payouts, each validating its
  required params; an explicit secretKey overrides the instance key for
  account-level methods.
• PAYMENT_TYPE_* constants (card, cardInvoice, sbp, sberpay, tinkoffpay,
  paypal, webmoney) — convenience/typo-guard only, still passed unvalidated.
• Dynamic webhook IP allowlist — setAllowedIps() / addAllowedIps() /
  getAllowedIps() and refreshAllowedIps() (pulls the published
  /ips/ips_webhooks.json feed, TLS-verified, fail-safe); CIDR matching for
  IPv4/IPv6 via UnitpayIpAllowlist.
• Passive telemetry — User-Agent + X-Unitpay-Client fingerprint on
  api() and an sdk token in the form() URL; no extra requests, no PII.
  Adds UnitPay::VERSION / UnitPay::API_VERSION.

Security & hardening

• getSignature(): PHP_INT_MAX guard retained; rejects a null/empty secret up
  front (a public call must not silently hash without the secret).
• checkHandlerRequest(): constant-time hash_equals() + is_string() guard;
  rejects an empty secret; accepts the preauth webhook.
• api(): fluent-setter params are cleared once the request has been attempted
  (success and transport failure), symmetric with form(), so a stale
  receipt/customer can't leak into an unrelated later call.
• IP allowlist checked against REMOTE_ADDR (not the spoofable
  X-Forwarded-For); setAllowedIps([]) documented as fail-closed.

Reliability & DX

• Typed exceptions — UnitpaySignatureException, UnitpayIpException,
  UnitpayTransportException, UnitpayUnsupportedMethodException,
  UnitpayValidationException, all implementing UnitpayExceptionInterface and
  still extending their former SPL classes (existing catch blocks keep working).
• cURL transport with connect/read timeouts and no allow_url_fopen
  dependency; falls back to file_get_contents(). Locale-independent float
  formatting so a comma-locale can't corrupt the signature/amount.
• Native type declarations across CashItem / UnitpayIpAllowlist /
  UnitPay within the PHP 7.4 subset; money/quantity params stay soft-typed by
  design (documented in PHPDoc). PHPStan raised to level 6.
• Injectable seams ($transport / $request / $clientIp) for testing
  without the network or superglobals.

Tests & QA

• First PHPUnit suite (121 tests, 243 assertions) — signatures (incl. the
  PHP_INT_MAX regression), handler verification, api() via injected
  transport, forms, CashItems, IP allowlist (CIDR/IPv6/fail-safe), floats.
• QA tooling wired via Composer: parallel-lint, php-cs-fixer (PSR-12),
  phpstan, phpmd; composer check runs them all.
• CI matrix PHP 7.4–8.4 with concurrency, least-privilege permissions, dependency
  cache and a non-blocking composer audit.

Docs

• README trimmed to a ~90-line landing page; detailed topics moved to docs/
  (getting-started, receipts, api-methods, webhooks, telemetry).
• Full example set (paymentForm, initPaymentApi, receipt, webhook,
  paymentInfo, refund, twoStagePayment, subscriptions, payout,
  accountInfo, offsetAdvance) reading secrets from the environment;
  config.php/order.php split. All code comments in English.

Compatibility (SemVer)

Effectively a minor at the API level (a clean bc-check against v2.0.6):

• Payment-type constants and CashItem values removed earlier were restored as
  @deprecated (removal in 3.0).
• Runtime validation was tightened (initPayment required params aligned with
  the backend; CashItem rejects non-numeric/non-positive count and negative
  price) — practically BC: it only rejects input the backend already refused.
• Minimum PHP raised 5.6 → 7.4 (Composer gates installation, so widely treated
  as minor).
• One behavior change: api() no longer retains fluent-setter params after a
  transport failure — a retry must re-apply the setters.

Verification

composer check green: parallel-lint, php-cs-fixer (0 findings), PHPStan level 6
(no errors), PHPMD, PHPUnit (121 tests).