Merge pull request #32 from indexa-git/refactor-pyazul

Author: gustavovalverde

.bandit

@@ -0,0 +1,4 @@
+[bandit]
+exclude = tests,.venv,.mypy_cache,.ruff_cache,.pytest_cache
+tests = B201,B301
+skips = B101,B601

.cursor/rules/3ds_secure_flow.mdc

@@ -0,0 +1,54 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+\# PyAzul 3D Secure (3DS) Implementation Guide
+
+This guide details the 3D Secure flow implementation within the `pyazul` library.
+
+## Core Components for 3DS
+
+1.  **`SecureService` ([pyazul/pyazul/services/secure.py](mdc:pyazul/pyazul/pyazul/pyazul/services/secure.py))**:
+    *   Handles all logic specific to 3DS transactions, including:
+        *   Initiating 3DS sales, token sales, and holds (`process_sale`, `process_token_sale`, `process_hold`).
+        *   Processing 3DS method notifications (`process_3ds_method`).
+        *   Processing 3DS challenge responses (`process_challenge`).
+        *   Generating HTML forms for ACS redirection (`_create_challenge_form`).
+    *   Uses the shared `AzulAPI` client (passed during its initialization), ensuring `is_secure=True` is used for 3DS-specific authentication via `AzulAPI`.
+    *   Manages 3DS session state internally using dictionaries keyed by `secure_id` (for initial session data like `term_url` and `azul_order_id`) and `AzulOrderId` (for transaction processing states).
+
+2.  **`PyAzul` Facade ([pyazul/pyazul/index.py](mdc:pyazul/pyazul/pyazul/pyazul/index.py))**:
+    *   Exposes user-friendly methods for 3DS operations:
+        *   `secure_sale`, `secure_token_sale`, `secure_hold`
+        *   `process_3ds_method` (Note: the facade method is `process_3ds_method`, not `secure_3ds_method` as previously might have been implied by some docs/tests)
+        *   `process_challenge`
+        *   `create_challenge_form` (convenience wrapper around `SecureService._create_challenge_form`).
+        *   `get_secure_session_info(secure_id)`: retrieves session data stored by `SecureService`.
+    *   These methods delegate to the `SecureService` instance, which is initialized by `PyAzul`.
+
+## Flow Overview
+
+1.  **Initiation**:
+    *   User calls `azul.secure_sale()` (or `secure_token_sale`, `secure_hold`) with payment details, `cardHolderInfo`, and `threeDSAuth` (which includes `TermUrl` and `MethodNotificationUrl`).
+    *   `SecureService` generates a unique `secure_id` (UUID).
+    *   `TermUrl` and `MethodNotificationUrl` provided by the user are internally appended with `?secure_id=<generated_id>` by `SecureService` before being sent to Azul.
+    *   `SecureService` makes an initial request to Azul. It then stores initial session data (including `azul_order_id` from the Azul response and the modified `term_url`) internally, associated with the generated `secure_id`.
+    *   The response from `azul.secure_sale()` may include HTML for immediate redirection (to the ACS for a challenge or to the 3DS Method URL). This response will also contain the `id` (which is the `secure_id`).
+
+2.  **Method Notification Callback (Your `MethodNotificationUrl`)**:
+    *   Your application endpoint (the `MethodNotificationUrl` you provided) is called by the ACS/PSP, with `secure_id` available as a query parameter.
+    *   Your application should first use `secure_id` to retrieve the stored session data: `session_data = await azul.get_secure_session_info(secure_id)`.
+    *   From `session_data`, retrieve the `azul_order_id`: `azul_order_id = session_data.get("azul_order_id")`.
+    *   Then, call `await azul.process_3ds_method(azul_order_id=azul_order_id, method_notification_status="RECEIVED")`.
+    *   `SecureService` uses its internal state to check if this method was already processed (to prevent duplicates) and updates the transaction state.
+    *   The response from `azul.process_3ds_method` might trigger a challenge, requiring redirection. In this case, use `azul.create_challenge_form(...)` with data from the response and the `term_url` (retrieved from `session_data.get("term_url")`) to generate the necessary HTML form.
+
+3.  **Challenge Callback (Your `TermUrl`)**:
+    *   Your application endpoint (the `TermUrl` you provided) is called by the ACS, typically via POST, after the cardholder completes (or skips) the challenge.
+    *   The `secure_id` (from the `TermUrl` query parameters) and `CRes` (Challenge Response, from the POST body) are received.
+    *   Your application calls `await azul.process_challenge(session_id=secure_id, challenge_response=CRes)`.
+    *   `SecureService` uses `secure_id` to retrieve session data (like `azul_order_id`) from its internal store and makes the final API call to process the challenge result.
+    *   The final transaction status (Approved/Declined) is returned.
+
+Refer to [pyazul/pyazul/README.md](mdc:pyazul/pyazul/pyazul/pyazul/README.md) for detailed FastAPI examples of this flow.

.cursor/rules/architecture_overview.mdc

@@ -0,0 +1,46 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+\
+# PyAzul Architecture Overview
+
+This document outlines the high-level architecture of the `pyazul` library.
+
+## Core Components
+
+1.  **`PyAzul` Facade ([pyazul/index.py](mdc:pyazul/index.py))**:
+    *   This is the main entry point for users of the library.
+    *   It initializes and provides access to all underlying services.
+    *   It manages a shared `AzulAPI` client instance and configuration (`AzulSettings`).
+
+2.  **`AzulAPI` Client ([pyazul/api/client.py](mdc:pyazul/api/client.py))**:
+    *   A single instance of `AzulAPI` is created by `PyAzul` and passed to services that require API communication.
+    *   It's responsible for all HTTP requests to the Azul gateway.
+    *   Handles SSL context with certificates, request signing (including `Auth1`/`Auth2` headers), and distinguishes between standard and 3DS (`is_secure=True`) authentication headers using credentials from `AzulSettings`.
+    *   Implements retry logic for production environments.
+
+3.  **Service Layer ([pyazul/services/](mdc:pyazul/services))**:
+    *   Functionality is modularized into services:
+        *   `TransactionService` ([pyazul/services/transaction.py](mdc:pyazul/services/transaction.py)): Handles standard payment operations (sale, hold, refund, etc.).
+        *   `DataVaultService` ([pyazul/services/datavault.py](mdc:pyazul/services/datavault.py)): Manages card tokenization.
+        *   `PaymentPageService` ([pyazul/services/payment_page.py](mdc:pyazul/services/payment_page.py)): Generates HTML for Azul's hosted payment page.
+        *   `SecureService` ([pyazul/services/secure.py](mdc:pyazul/services/secure.py)): Manages the 3D Secure authentication flow.
+    *   Services receive the shared `AzulAPI` client and `AzulSettings` (or just `AzulAPI` if settings are only needed by the client itself, as `AzulAPI` now takes `settings` in its constructor).
+
+4.  **Configuration ([pyazul/core/config.py](mdc:pyazul/core/config.py))**:
+    *   Managed by the `AzulSettings` Pydantic model.
+    *   Settings are loaded from a `.env` file and environment variables.
+    *   `PyAzul` can be initialized with a custom `AzulSettings` instance.
+
+5.  **Pydantic Models ([pyazul/models/](mdc:pyazul/models))**:
+    *   Used for request and response data validation and serialization.
+    *   Centralized and re-exported via `[pyazul/models/__init__.py](mdc:pyazul/models/__init__.py)`.
+
+## Key Principles
+*   **Facade Pattern**: `PyAzul` simplifies interaction with the various services.
+*   **Dependency Injection**: `AzulAPI` client and `AzulSettings` are managed by `PyAzul` and provided to services. The 3DS session store is injected into `PyAzul` and then into `SecureService`.
+*   **Asynchronous**: Core operations are `async/await` based.
+
+Refer to [README.md](mdc:README.md) for usage examples.

.cursor/rules/coding_standards_and_linting.mdc

@@ -0,0 +1,45 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# PyAzul Coding Standards and Linting
+
+This document outlines key coding standards, linting practices, and items to add to the `pyazul` library to ensure code quality, consistency, and maintainability.
+
+## Exception Handling
+*   **Chaining (`raise ... from ...`)**:
+    *   As detailed in `[error_handling_conventions.mdc](mdc:pyazul/.cursor/rules/error_handling_conventions.mdc)`, always use `raise NewException(...) from original_exception` when re-raising exceptions.
+    *   **Linter Issue**: The linter (Trunk) correctly flags violations of this. Ensure all `raise` statements within `except` blocks adhere to this.
+    *   **Files to Check/Verify**:
+        *   `[pyazul/api/client.py](mdc:pyazul/pyazul/api/client.py)`: (e.g., in `_load_certificates`, `_async_request`). Ensure all are covered.
+
+## Linter Compliance & Specific Issues
+*   **Trunk Linters**: The project uses Trunk for linting. All linter warnings and errors should be addressed promptly.
+*   **Unused Variables**:
+    *   Pay attention to warnings about unused variables. If a variable is truly not needed, remove it. If it's part of a tuple unpacking and intentionally unused, prefix its name with an underscore (e.g., `_`).
+    *   **Specific Linter Issue**: In `[pyazul/api/client.py](mdc:pyazul/pyazul/api/client.py)`, method `_check_for_errors`, the loop `for field, value in error_indicators:` does not use `field`.
+        *   **Action**: Change to `for _, value in error_indicators:`.
+
+## Type Hinting
+*   **Comprehensive Typing**: All functions and methods must have comprehensive type hints for parameters and return values. This improves readability and allows for static analysis.
+*   **`typing.NoReturn`**: For functions that are guaranteed to always raise an exception and never return normally (e.g., they end in `raise`), use `typing.NoReturn` as the return type. This was applied to `_log_and_raise_api_error` in `[pyazul/api/client.py](mdc:pyazul/pyazul/api/client.py)`.
+*   **Pydantic Models**: Utilize Pydantic models for data structures passed between components. Service method signatures should generally expect these models, even if the `PyAzul` facade offers dictionary-based input for user convenience.
+
+## Logging
+*   Employ the standard `logging` module for clear, contextual logs.
+*   **`AzulAPI` ([pyazul/api/client.py](mdc:pyazul/pyazul/api/client.py))**:
+    *   Log request/response data at `DEBUG` level for troubleshooting.
+    *   Log significant errors at `ERROR` level.
+*   **Services (e.g., `[pyazul/services/secure.py](mdc:pyazul/pyazul/services/secure.py)`)**:
+    *   Log key events in flows at `INFO` or `DEBUG` level.
+    *   Log warnings for unexpected but recoverable situations with `WARNING`.
+    *   Log errors that lead to exceptions with `ERROR`.
+
+## Documentation
+*   **Docstrings**: All public classes, methods, and functions require clear docstrings. Describe purpose, arguments (`Args:`), return values (`Returns:`), and any exceptions raised (`Raises:`).
+*   **[README.md](mdc:pyazul/README.md)**: Must be kept current, reflecting the library's public API and common usage patterns, especially for complex flows like 3DS.
+*   **Code Comments**: Use to explain non-obvious logic. Avoid redundant comments that reiterate what the code clearly states.
+
+## Modularity and Cohesion
+*   Maintain the established separation of concerns: `PyAzul` (facade), Services (business logic), `AzulAPI` (HTTP client), `AzulSettings` (config), Models (data contracts).

.cursor/rules/configuration_management.mdc

@@ -0,0 +1,36 @@
+---
+description: Details how configuration is managed in PyAzul, focusing on AzulSettings and .env files.
+globs:
+alwaysApply: true
+---
+# PyAzul Configuration Management
+
+Configuration for the `pyazul` library is managed through the `AzulSettings` Pydantic model, defined in `[pyazul/core/config.py](mdc:pyazul/pyazul/core/config.py)`.
+
+## Loading Configuration
+*   By default, `PyAzul()` (see `[pyazul/index.py](mdc:pyazul/pyazul/index.py)`) initializes `AzulSettings` by loading values from a `.env` file in the project root and then from environment variables (environment variables override `.env` values).
+*   A custom, pre-configured `AzulSettings` instance can also be passed directly to the `PyAzul` constructor: `PyAzul(settings=my_custom_settings)`.
+
+## Key Configuration Variables (in `.env` or as environment variables)
+
+*   **API Credentials**:
+    *   `AUTH1`: Your primary Auth1 key. Used for all API requests.
+    *   `AUTH2`: Your primary Auth2 key. Used for all API requests.
+    *   `MERCHANT_ID`: Your merchant identifier. Used for all API calls and for the Payment Page.
+*   **Certificates**:
+    *   `AZUL_CERT`: Path to your SSL certificate file OR the full PEM content as a string.
+    *   `AZUL_KEY`: Path to your SSL private key file OR the full PEM content as a string OR Base64 encoded PEM content.
+    *   The library handles writing PEM content to temporary files if direct content is provided (see `_load_certificates` in `[pyazul/core/config.py](mdc:pyazul/pyazul/core/config.py)`). The `AzulAPI` client in `[pyazul/api/client.py](mdc:pyazul/pyazul/api/client.py)` uses these settings to establish its SSL context.
+*   **Environment**:
+    *   `ENVIRONMENT`: Set to `dev` for development/testing or `prod` for production. Controls API endpoints.
+*   **Payment Page Settings (Optional, if using Payment Page)**:
+    *   `AZUL_AUTH_KEY`: Authentication key for generating the payment page hash.
+    *   `MERCHANT_NAME`: Your business name displayed on the page.
+    *   `MERCHANT_TYPE`: Your business type.
+*   **Other**:
+    *   `CHANNEL`: Default payment channel (e.g., "EC" for E-Commerce).
+    *   `CUSTOM_URL`: Optionally override base API URLs.
+
+
+Consult `[pyazul/core/config.py](mdc:pyazul/pyazul/core/config.py)` for all available settings fields.
+The [README.md](mdc:pyazul/README.md) provides a `.env` example and further details.

.cursor/rules/error_handling_conventions.mdc

@@ -0,0 +1,51 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# PyAzul Error Handling Conventions
+
+`pyazul` uses a hierarchy of custom exceptions to report errors, all defined in `[pyazul/core/exceptions.py](mdc:pyazul/core/exceptions.py)`.
+
+## Custom Exception Hierarchy
+All custom exceptions inherit from `pyazul.core.exceptions.AzulError`.
+
+*   **`AzulError`**: Base class for all library-specific errors.
+*   **`SSLError`**: Raised for issues related to SSL certificate loading or configuration (e.g., file not found, invalid format). This is primarily raised from `_load_certificates` in `[pyazul/api/client.py](mdc:pyazul/api/client.py)`.
+*   **`APIError`**:
+    *   Raised for general issues during HTTP communication with the Azul API.
+    *   Examples: Network errors, unexpected HTTP status codes not covered by `AzulResponseError`, issues decoding JSON responses.
+*   **`AzulResponseError`**:
+    *   Raised when the Azul API explicitly returns an error in its response payload (e.g., transaction declined, invalid field value).
+    *   Contains a `response_data` attribute holding the raw dictionary response from Azul for inspection.
+    *   The error message typically includes `ErrorMessage` or `ErrorDescription` from the Azul response.
+    *   This is checked and raised in the `_check_for_errors` method of `[pyazul/api/client.py](mdc:pyazul/api/client.py)`.
+
+## Best Practices for Using and Raising Exceptions
+*   **Catch Specific Exceptions**: When handling errors from `pyazul`, catch more specific exceptions first, then broader ones.
+    ```python
+    from pyazul import AzulError, AzulResponseError, SSLError
+    # from pyazul.core.exceptions import APIError (if needing to catch it separately)
+
+    try:
+        response = await azul.sale(...)
+    except AzulResponseError as e:
+        print(f"Azul API Error: {e.message}")
+        print(f"Response Data: {e.response_data}")
+    except SSLError as e:
+        print(f"SSL Configuration Error: {e}")
+    except APIError as e: # Catches other API communication issues
+        print(f"API Communication Error: {e}")
+    except AzulError as e: # Catch-all for other pyazul errors
+        print(f"PyAzul Library Error: {e}")
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+    ```
+*   **Chaining Exceptions (`raise ... from ...`)**:
+    *   **Critically Important**: When catching an exception and raising a new custom `pyazul` exception (or any exception), use the `raise NewException(...) from original_exception` syntax. This preserves the context and stack trace of the original error, which is invaluable for debugging.
+    *   This practice is implemented in `[pyazul/services/secure.py](mdc:pyazul/services/secure.py)` and `[pyazul/api/client.py](mdc:pyazul/api/client.py)`.
+    *   Failure to do this can hide the root cause of problems.
+    *   Example: `raise AzulError("Something went wrong") from caught_exception`
+
+See the [README.md](mdc:README.md) for a basic error handling example.
+The `[coding_standards_and_linting.mdc](mdc:coding_standards_and_linting.mdc)` rule also emphasizes this.