# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Testing
- `composer phpunit` - Run all PHPUnit tests
- `composer test-coverage` - Run tests with coverage report (generates coverage/ directory)
- Run a single test file: `./vendor/bin/phpunit tests/Service/Facade/PaymentsTest.php`
- Run a single test method: `./vendor/bin/phpunit --filter test_method_name`

### Code Quality
- `composer analyse` - Run PHPStan static analysis (level 8)
- `composer baseline` - Generate PHPStan baseline to ignore current errors
- `composer format` - Fix code style issues with PHP-CS-Fixer

### Make Commands (Docker-based)
- `make build` - Build Docker image (PHP 7.4 default, use `PHP_VERSION=8.4 make build` for others)
- `make test` - Run tests in Docker
- `make check` - Full check: formatting + analysis + tests
- `make help` - Show all available make commands

## Architecture

### Core Components
- **SdkFacade**: Main entry point providing access to specialized sub-facades:
  - **Infrastructure**: API configuration and common information services
  - **Authorization**: Authentication and credential management
  - **Payments**: Payment order and link creation
  - **Callbacks**: Webhook validation and processing
  - **Refunds**: Refund order operations
  - **Translations**: Localization with SDK/plugin namespace merging
- **SdkFacadeBuilder**: Builder pattern for configuring and creating SdkFacade instances with optional dependencies (logger, HTTP client, auth token repository, environment)

### Key Services
- **PaymentApiClient**: Handles API communication for payment operations
- **PaymentApiAuthorizationClient**: Manages authentication with the Paysera API
- **Callbacks** (facade): Validates and processes payment/refund callbacks via PaymentApiCallbackVerifier and PaymentApiCallbackBuilder
- **TranslationApiClient**: Fetches translations from proxy with optional plugin namespace merging (SDK base + plugin overrides)

### Entity Structure
- **Payment Flow**: PaymentOrderCreateRequest → PaymentOrderCreateResponse → PaymentLinkCreateRequest → PaymentLinkCreateResponse
- **Refund Flow**: RefundOrderRequest → RefundOrderResponse
- **Callbacks**: PaymentCallback, RefundCallback for webhook handling
- **Collections**: Typed collections for PaymentMethods, PaymentStatuses, RefundStatuses

### Configuration
- **Environment**: Sandbox/Production mode switching via SdkFacadeBuilder
- **ApiConfiguration**: API endpoints and environment-specific settings
- **PaymentApiAuthTokenRepository**: Token storage (InMemoryPaymentApiAuthTokenRepository by default, customizable)

### Error Handling
All public methods throw **IntegrationException** for user-facing errors, while internal exceptions extend **BaseException** with structured logging data.

## Code Standards
- **PSR-12** code style (enforced by PHP-CS-Fixer)
- **Strict types** required (`declare(strict_types=1)`)
- **PHPStan level 8** static analysis
- **PHP 7.4+** compatibility