# Contributing to Alfa Bank SDK

Thank you for your interest in contributing to the unofficial Alfa Bank SDK! We welcome pull requests, bug reports, and feature requests.

## Getting Started

1.  **Fork the repository** on GitHub.
2.  **Clone your fork** locally:
    ```bash
    git clone https://github.com/your-username/alfa-bank-sdk.git
    cd alfa-bank-sdk
    ```
3.  **Install dependencies**:
    ```bash
    composer install
    ```

## Development Standards (Strict)

To maintain the "Enterprise Grade" quality of this SDK, all contributions must adhere to the following architectural rules:

### 1. Requests & Responses
- **DTOs Only:** Never pass raw arrays to a Request constructor. Always create a dedicated DTO in `src/Data/...`.
- **Strict Typing:** All Request classes must implement the `createDtoFromResponse(Response $response)` method. Returning raw JSON is forbidden.
- **Saloon v3:** Follow [Saloon PHP](https://docs.saloon.dev) best practices.

### 2. Pagination
- If an endpoint returns a list (e.g. transactions, accounts), the Request class **MUST**:
    1. Implement `Saloon\PaginationPlugin\Contracts\Paginatable`.
    2. Use the `Apoloz\AlfaBank\Traits\HasAlfaPagination` trait.
    3. Return a `Spatie\LaravelData\DataCollection` in `createDtoFromResponse`.

### 3. Security
- **No Secrets:** Never commit real keys (`.pem`, `.key`, `.pfx`) or credentials.
- **Crypto:** Use the `CmsSigner` and `JwsSigner` utilities for cryptographic operations. Do not roll your own crypto logic.

## Running Quality Checks

We use **Pest** for testing and **PHPStan** for static analysis.

```bash
# Run Unit & Feature Tests
vendor/bin/pest

# Run Static Analysis (Level 5)
vendor/bin/phpstan analyse
```

**PRs with failing tests or PHPStan errors will not be merged.**

## Submitting a Pull Request

1.  Create a new branch: `git checkout -b feature/my-new-feature`.
2.  Write tests for your new feature (we aim for high coverage).
3.  Commit changes with clear, descriptive messages.
4.  Push to your fork and open a Pull Request against `main`.

## Reporting Bugs

Please open an issue on GitHub with:
- A clear description of the bug.
- Minimal reproducible code example.
- SDK version and PHP version.

Thank you for helping improve this SDK!