feat: OAuth 2.0 authentication and refund support

[jfrosorio]

Closes #70

Adds the OAuth 2.0 foundation for Eupago's management API plus the first feature gated behind it: refunds. Ships as an additive minor (~v3.7.0) — the existing API-key transport for reference creation and status queries is untouched.

What's included

OAuth 2.0 foundation

• New config keys client_id / client_secret (EUPAGO_CLIENT_ID, EUPAGO_CLIENT_SECRET), only needed for management calls
• Auth\TokenProvider: client credentials grant against POST /api/auth/token, caching the token for the expires_in lifetime minus a 60s safety margin, scoped by environment + client id
• illuminate/cache added to require, following the existing one-package-per-facade convention

Refunds

• EuPago::refund($transactionId, $amount, ?$reason, ?$iban, ?$bic) against POST /api/management/v1.02/refund/{trid}, keyed by the callback's transacao
• Partial and total refunds; optional IBAN/BIC for methods without a direct refund path
• Success maps to normalized keys (success, status, refund_id); rejections (HTTP 4xx with transactionStatus: Rejected) land in the existing error bag keyed by the rejection code, while transport/server errors throw — mirroring create()/status()

Docs & tests

• README: OAuth configuration section + Refunds section
• 12 new Pest feature tests (token grant, caching, expiry margin, credential rejection, refund success/rejection/server error, bearer transport, optional params, token reuse)

Notes

• No migrations, no route changes — nothing for UPGRADE.md
• A live sandbox smoke test is pending OAuth client credentials for the sandbox account

[Copilot]

Pull request overview

Adds OAuth 2.0 client-credentials token acquisition + caching to support Eupago management API calls, and introduces a new refund() operation built on that foundation. This extends the package without changing the existing API-key flow used for reference creation and status queries.

Changes:

• Introduces Auth\TokenProvider to request/cache bearer tokens (client credentials grant).
• Adds EuPago::refund() with normalized response mapping and Pest feature coverage.
• Documents new OAuth config + refunds in the README; adds illuminate/cache dependency and config keys.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/TestCase.php	Adds test config for OAuth client credentials.
tests/Feature/TokenProviderTest.php	Adds feature tests for token grant behavior and caching/expiry margin.
tests/Feature/RefundTest.php	Adds feature tests for refund success/rejection/error behavior and bearer transport.
src/EuPago.php	Adds refund endpoint constant, refund() method, and response key normalization.
src/Auth/TokenProvider.php	Implements client-credentials token retrieval and cache scoping by env + client id.
README.md	Documents OAuth client credentials setup and the new refunds API.
config/eupago.php	Adds client_id / client_secret configuration keys.
composer.json	Adds illuminate/cache required dependency to support token caching.

---

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