DX overhaul, gacela 1.19 / router 0.13 upgrade, CORS + LUD-06 fix, tooling

[Chemaclass]

Summary

A developer-experience pass over the library, plus the gacela stack upgrade that the new gacela-project/router 0.13 release unblocks, a LUD-06 wire-format fix, router middleware, and modernized dev tooling.

Reviewed commit-by-commit for a clean history.

1. DX overhaul (485e954)

• Metadata correctness: build LNURL-pay metadata via a shared LnurlPayMetadata value object using json_encode instead of string concatenation — a quote in the description no longer produces invalid JSON. Removes duplication between CallbackUrl and InvoiceGenerator.
• HTTP errors: HttpApi now catches Symfony transport/HTTP errors + JsonException and returns null, so the backend surfaces a clean "unreachable" error instead of leaking a stack trace (that graceful path was previously dead code).
• Remove dump($e) from the controller; normalize errors to the LNURL {status, reason} shape.
• Add a BackendType enum and clear errors in addBackendsFile (missing file, invalid JSON, missing/unknown type); add addBackend() to register backends programmatically without a JSON file.
• Centralize app-config keys in ConfigKey so the config writer/reader can't drift; fix the nonsensical REQUEST_URI receiver default.
• Add return-shape docblocks to the facade/generator for IDE autocomplete.
• Rename the misleadingly named nostr.json backends file to backends.json.
• Rewrite the README (install, config, HTTP API, programmatic use, reference table).

2. LUD-06 pr key fix (d5fc11e)

LUD-06 mandates the callback response carry the bolt11 invoice under a field named pr. The response keyed it bolt11, so spec-compliant wallets saw the invoice as missing. Renamed the output key to pr (the internal InvoiceTransfer property and the LNbits API field stay bolt11).

3. gacela 1.19 / router 0.13 upgrade (485e954)

gacela 1.9.1 -> 1.19, router 0.12.1 -> 0.13, container 0.6 -> 0.10, phpstan-extension 0.3 -> 0.4. Required fixes (caught by a live server smoke test, not the unit suite):

• SendableRange::__set_state for gacela's var_export'd merged-config file cache.
• Generic @extends params for the now-templated gacela base classes.
• DocBlockResolverAwareTrait -> ServiceResolverAwareTrait (deprecated).

4. CORS middleware + global exception handler (f2bca2d)

Uses router 0.13's new middleware support:

• CorsMiddleware sets Access-Control-Allow-Origin: * on every response and answers OPTIONS preflight directly (route registered for GET + OPTIONS).
• InvoiceExceptionHandler registered as the router's global Exception handler, rendering any uncaught error as the LNURL error object — the controller no longer needs a try/catch.

5. Tooling modernization (66e8cdd)

PHPUnit 9.6 -> 10.5 (config migrated to the 10.x schema), PHPStan 1.12 -> 2.2 (clean at level max), Rector 1.2 -> 2.0 (applied its new suggestions). Removed now-unused symfony/var-dumper.

Testing

• composer test-all green: psalm (98.9% type coverage), phpstan 2 level max, PHPUnit 10 (26 tests), rector 2 — all clean.
• Live server smoke-tested end-to-end: LNURL pay params, pr-keyed invoice, Backend "LnBits" unreachable path, CORS header on GET, OPTIONS preflight (200), and the global error handler — 0 fatals.

Notes

• gacela-project/gacela constraint is ^1.19; the upgrade depended on gacela-project/router 0.13 (which requires container ^0.10).
• Breaking for downstream consumers: the nostr.json -> backends.json rename and the bolt11 -> pr response key.