genesis_ruby 0.3.1 → 0.3.2

data/.kiro/specs/f2025112609_update_payee_request_params/requirements.md

@@ -0,0 +1,86 @@
+# Requirements Document
+
+## Introduction
+
+Update the existing Payee Create and Payee Update request classes in the genesis_ruby SDK to support the full set of request parameters defined in the current Payee API documentation. This includes adding `registration_number`, `date`, `notification_url`, and a nested `address` object with `city`, `street`, `state`, `country`, and `zip_code` fields. The obsolete flat address format and `neighborhood` field must not be emitted.
+
+## Glossary
+
+- **SDK**: The genesis_ruby Ruby gem that wraps the emerchantpay payment gateway API
+- **Payee_Create**: The `GenesisRuby::Api::Requests::NonFinancial::Payee::Create` class (POST /payee)
+- **Payee_Update**: The `GenesisRuby::Api::Requests::NonFinancial::Payee::Update` class (PATCH /payee/:payee_unique_id)
+- **Nested_Address**: A hash object under the `address` key containing `city`, `street`, `state`, `country`, `zip_code`
+- **Deep_Compact**: The SDK's mechanism that removes nil values and empty hashes from the request structure before serialization
+
+## Requirements
+
+### Requirement 1: Payee Create — New Request Parameters
+
+**User Story:** As a developer using the SDK, I want to set `registration_number`, `date`, `notification_url`, and nested address fields on Payee Create, so that the JSON payload matches the current Payee API documentation.
+
+#### Acceptance Criteria
+
+- [x] `payee_date` accessor is available and serialized as `payee.date`
+- [x] `payee_notification_url` accessor is available and serialized as `payee.notification_url`
+- [x] `payee_registration_number` accessor is available and serialized as `payee.registration_number`
+- [x] `payee_address_city` is serialized under `payee.address.city`
+- [x] `payee_address_street` is serialized under `payee.address.street`
+- [x] `payee_address_state` is serialized under `payee.address.state`
+- [x] `payee_address_country` is serialized under `payee.address.country`
+- [x] `payee_address_zip_code` is serialized under `payee.address.zip_code`
+- [x] `payee_address_country` is validated against the ISO country list (optional field)
+- [x] When all address fields are nil, the `address` key is not emitted in the payload
+- [x] The `neighborhood` field is never emitted
+- [x] Existing required fields (`payee_type`, `payee_name`, `payee_country`) remain unchanged
+- [x] All new fields are optional
+
+### Requirement 2: Payee Update — New Request Parameters
+
+**User Story:** As a developer using the SDK, I want to set `registration_number`, `date`, `notification_url`, and nested address fields on Payee Update, so that the JSON payload matches the current Payee API documentation.
+
+#### Acceptance Criteria
+
+- [x] `payee_date` accessor is available and serialized as `payee.date`
+- [x] `payee_notification_url` accessor is available and serialized as `payee.notification_url`
+- [x] `payee_registration_number` accessor is available and serialized as `payee.registration_number`
+- [x] `payee_address_city` is serialized under `payee.address.city`
+- [x] `payee_address_street` is serialized under `payee.address.street`
+- [x] `payee_address_state` is serialized under `payee.address.state`
+- [x] `payee_address_country` is serialized under `payee.address.country`
+- [x] `payee_address_zip_code` is serialized under `payee.address.zip_code`
+- [x] `payee_address_country` is validated against the ISO country list (optional field)
+- [x] When all address fields are nil, the `address` key is not emitted in the payload
+- [x] The `neighborhood` field is never emitted
+- [x] HTTP method remains PATCH
+- [x] Only `payee_unique_id` is required; all other fields are optional
+- [x] All new fields are optional
+
+### Requirement 3: No Obsolete Fields
+
+**User Story:** As a developer using the SDK, I want the Payee requests to not emit obsolete fields, so that the payload is compliant with the current API.
+
+#### Acceptance Criteria
+
+- [x] No `neighborhood` field is present in any request structure
+- [x] No flat `address` string field (e.g., `payee.address = "123 Main St"`) is used
+- [x] No flat `zip_code` field at the payee root level is used
+
+### Requirement 4: Test Coverage
+
+**User Story:** As a developer, I want RSpec tests covering all new parameters, so that regressions are caught.
+
+#### Acceptance Criteria
+
+- [x] Spec for Payee Create verifies full request structure including nested address
+- [x] Spec for Payee Create verifies address is omitted when all address fields are nil
+- [x] Spec for Payee Create verifies no `neighborhood` in address
+- [x] Spec for Payee Create verifies `registration_number` serialization
+- [x] Spec for Payee Create verifies `payee_address_country` validation
+- [x] Spec for Payee Update verifies full request structure including nested address
+- [x] Spec for Payee Update verifies address is omitted when all address fields are nil
+- [x] Spec for Payee Update verifies no `neighborhood` in address
+- [x] Spec for Payee Update verifies `registration_number` serialization
+- [x] Spec for Payee Update verifies `payee_address_country` validation
+- [x] Spec for Payee Update verifies minimum request data (only `payee_unique_id` required)
+- [x] All existing tests continue to pass
+- [x] `bundle exec rake styles` passes with 0 offenses

data/.kiro/specs/f2025112609_update_payee_request_params/tasks.md

@@ -0,0 +1,40 @@
+# Tasks
+
+## Task 1: Add new fields to Payee Create request class
+
+- [x] Add `attr_accessor` for `payee_date`, `payee_notification_url`, `payee_registration_number`
+- [x] Add `attr_accessor` for `payee_address_city`, `payee_address_street`, `payee_address_state`, `payee_address_country`, `payee_address_zip_code`
+- [x] Add `payee_address_country` to `field_values` for ISO validation
+- [x] Update `request_structure` to include new fields and nested `address`
+- [x] Add private `payee_address_structure` method
+
+## Task 2: Add new fields to Payee Update request class
+
+- [x] Add `attr_accessor` for `payee_date`, `payee_notification_url`, `payee_registration_number`
+- [x] Add `attr_accessor` for `payee_address_city`, `payee_address_street`, `payee_address_state`, `payee_address_country`, `payee_address_zip_code`
+- [x] Add `payee_address_country` to `field_values` for ISO validation
+- [x] Update `request_structure` to include new fields and nested `address`
+- [x] Add private `payee_address_structure` method
+
+## Task 3: Update Payee Create spec
+
+- [x] Add new fields to `sample_data` and `request` let blocks
+- [x] Update structure assertion to include all new fields
+- [x] Add context for nested address serialization (present, absent, no neighborhood)
+- [x] Add context for `registration_number`
+- [x] Add test for `payee_address_country` validation
+
+## Task 4: Update Payee Update spec
+
+- [x] Add new fields to `sample_data` and `request` let blocks
+- [x] Update structure assertion to include all new fields
+- [x] Add context for nested address serialization (present, absent, no neighborhood)
+- [x] Add context for `registration_number`
+- [x] Add test for `payee_address_country` validation
+- [x] Update minimum request data test to nil all new fields
+
+## Task 5: Validation
+
+- [x] `bundle exec rake test` — 7089 examples, 0 failures
+- [x] `bundle exec rake styles` — 933 files inspected, no offenses detected
+- [x] `git diff --stat` shows only 4 modified files (create.rb, update.rb, create_spec.rb, update_spec.rb)

data/.kiro/specs/f2025112612-add_payee_owner_documents_and_verification_requests/.config.kiro

@@ -0,0 +1 @@
+{"specId": "e7536868-191d-4a23-aacb-b036ee65c0bb", "workflowType": "requirements-first", "specType": "feature"}

data/.kiro/specs/f2025112612-add_payee_owner_documents_and_verification_requests/design.md

@@ -0,0 +1,246 @@
+# Design Document: Payee Owner, Documents & Verifications
+
+## Overview
+
+Extend the genesis_ruby SDK with 20 new non-financial request classes for the Payee API covering Owner management, Document management, and Verification management. Additionally, add HTTP DELETE method infrastructure since the existing codebase only supports POST, GET, PUT, and PATCH.
+
+All new request classes follow the established `Base::Versioned` pattern: JSON format, versioned API paths, `attr_accessor` parameters, field validations, request structure hashes, and path placeholder replacement in `process_request_parameters`.
+
+## Architecture
+
+The new classes follow the PHP SDK's flat layout — Payee-level operations (documents, owners association) sit directly in the `Payee` module, Owner CRUD and Owner sub-operations go in `Payee::Owners`, and Verifications in `Payee::Verifications`:
+
+```
+lib/genesis_ruby/api/requests/non_financial/payee/
+├── Account/                          (existing)
+│   ├── create.rb, retrieve.rb, update.rb, list.rb
+├── Owners/                           (Owner CRUD + Owner sub-operations)
+│   ├── create.rb                     (POST /payee/owners)
+│   ├── retrieve.rb                   (GET  /payee/owners/:owner_unique_id)
+│   ├── update.rb                     (PATCH /payee/owners/:owner_unique_id)
+│   ├── delete.rb                     (DELETE /payee/owners/:owner_unique_id)
+│   ├── list_owners.rb                (GET  /payee/owners)
+│   ├── associate_owner_with_owners.rb (POST /payee/owners/:owner_unique_id/owners)
+│   ├── dissociate_owners.rb          (DELETE /payee/owners/:owner_unique_id/owners)
+│   ├── create_owner_document.rb      (POST /payee/owners/:owner_unique_id/documents)
+│   ├── retrieve_owner_document.rb    (GET  /payee/owners/:owner_unique_id/documents/:document_unique_id)
+│   └── list_owner_documents.rb       (GET  /payee/owners/:owner_unique_id/documents)
+├── Verifications/
+│   ├── create_payee_verification.rb  (POST /payee/:payee_unique_id/verifications)
+│   ├── retrieve_payee_verification.rb (GET /payee/:payee_unique_id/verifications/:verification_unique_id)
+│   └── list_payee_verifications.rb   (GET  /payee/:payee_unique_id/verifications)
+├── create.rb, retrieve.rb, update.rb (existing Payee CRUD)
+├── list_payees.rb                    (GET  /payee)
+├── list_payee_owners.rb              (GET  /payee/:payee_unique_id/owners)
+├── associate_payee_with_owners.rb    (POST /payee/:payee_unique_id/owners)
+├── dissociate_payee_with_owners.rb   (DELETE /payee/:payee_unique_id/owners)
+├── create_payee_document.rb          (POST /payee/:payee_unique_id/documents)
+├── retrieve_payee_document.rb        (GET  /payee/:payee_unique_id/documents/:document_unique_id)
+└── list_payee_documents.rb           (GET  /payee/:payee_unique_id/documents)
+```
+
+Infrastructure changes for DELETE support:
+
+```
+Api::Request          → METHOD_DELETE constant + init_delete_configuration method
+Utils::Options::ApiConfig → load_delete_config method
+Network::Adapter::NetHttpAdapter → DELETE case in execute
+Utils::Options::NetworkAdapterConfig → DELETE format in fetch_content_type
+```
+
+## Components and Interfaces
+
+### 1. HTTP DELETE Infrastructure
+
+**`Api::Request`** — Add `METHOD_DELETE = 'DELETE'` constant and `init_delete_configuration` method that delegates to `@api_config.load_delete_config`.
+
+**`Utils::Options::ApiConfig`** — Add `load_delete_config` method:
+```ruby
+def load_delete_config
+  self.protocol              = GenesisRuby::Api::Request::PROTOCOL_HTTPS
+  self.port                  = GenesisRuby::Api::Request::PORT_HTTPS
+  self.type                  = GenesisRuby::Api::Request::METHOD_DELETE
+  self.format                = Builder::JSON
+  self.parser_skip_root_node = false
+  self.authorization         = GenesisRuby::Api::Request::AUTH_TYPE_BASIC
+  self.bearer_token          = nil
+end
+```
+
+**`Network::Adapter::NetHttpAdapter`** — Add DELETE case in `execute`:
+```ruby
+when Api::Request::METHOD_DELETE then @response = @request.delete path, headers
+```
+Note: DELETE requests send headers only (no body), similar to GET. The `headers` method should exclude payload headers for DELETE, same as GET.
+
+**`Utils::Options::NetworkAdapterConfig`** — Add `Builder::JSON` handling for DELETE in `fetch_content_type`. Since DELETE uses `Builder::JSON` format, it's already handled by the existing `when Builder::JSON then 'application/json'` case. No change needed here.
+
+### 2. Request Class Patterns
+
+All 20 request classes follow one of four patterns:
+
+**GET (Retrieve)** — `init_get_configuration` in `init_configuration`, empty `request_structure`, placeholder replacement in `process_request_parameters`.
+
+**GET (List)** — Same as Retrieve, plus optional query parameter building appended to the URL.
+
+**POST (Create/Associate)** — Default POST, `request_structure` returns the JSON body hash, placeholder replacement.
+
+**PATCH (Update)** — `init_patch_configuration` in constructor, `request_structure` returns updatable fields, placeholder replacement.
+
+**DELETE (Dissociate/Delete)** — `init_delete_configuration` in constructor, `request_structure` returns body (for dissociate) or empty hash (for delete), placeholder replacement.
+
+### 3. Constants Module
+
+**`Api::Constants::NonFinancial::Payee::OwnerTypes`**:
+```ruby
+COMPANY = 'company'
+PERSON = 'person'
+DIRECTOR = 'director'
+ULTIMATE_BENEFICIAL_OWNER = 'ultimate_beneficial_owner'
+```
+
+**`Api::Constants::NonFinancial::Payee::DocumentTypes`**:
+```ruby
+POI = 'poi'
+PASSPORT = 'passport'
+ID_CARD = 'id_card'
+DRIVING_LICENSE = 'driving_license'
+POA = 'poa'
+UTILITY_BILL = 'utility_bill'
+BANK_STATEMENT = 'bank_statement'
+COMPANY_REGISTRATION = 'company_registration'
+TAX_RETURN = 'tax_return'
+MEMORANDUM_OF_ASSOCIATION = 'memorandum_of_association'
+SHAREHOLDER_REGISTER = 'shareholder_register'
+BOARD_RESOLUTION = 'board_resolution'
+PROOF_OF_ADDRESS = 'proof_of_address'
+```
+
+## Data Models
+
+### Request Parameters by Class
+
+| Class | Required Fields | Optional Fields | Validated Fields |
+|-------|----------------|-----------------|------------------|
+| ListPayeeOwners | payee_unique_id | type (query param) | — |
+| AssociatePayeeWithOwners | payee_unique_id | owners[] | — |
+| DissociatePayeeWithOwners | payee_unique_id | owners[] | — |
+| CreatePayeeDocument | payee_unique_id, document_type, file | — | document_type |
+| RetrievePayeeDocument | payee_unique_id, document_unique_id | — | — |
+| ListPayeeDocuments | payee_unique_id | — | — |
+| Verifications::CreatePayeeVerification | payee_unique_id | notification_url, redirect_url, with_checks_retry | — |
+| Verifications::RetrievePayeeVerification | payee_unique_id, verification_unique_id | — | — |
+| Verifications::ListPayeeVerifications | payee_unique_id | — | — |
+| Owners::Create | owner_type, owner_name, owner_country | owner_date, notification_url, registration_number, owner_address{}, payees[], owners[] | owner_type, owner_country |
+| Owners::Retrieve | owner_unique_id | — | — |
+| Owners::Update | owner_unique_id | owner_name, owner_country, owner_date, notification_url, registration_number, owner_address{} | owner_country |
+| Owners::Delete | owner_unique_id | — | — |
+| Owners::ListOwners | — | — | — |
+| Owners::AssociateOwnerWithOwners | owner_unique_id | owners[] | — |
+| Owners::DissociateOwners | owner_unique_id | owners[] | — |
+| Owners::CreateOwnerDocument | owner_unique_id, document_type, file | — | document_type |
+| Owners::RetrieveOwnerDocument | owner_unique_id, document_unique_id | — | — |
+| Owners::ListOwnerDocuments | owner_unique_id | — | — |
+
+### URL Patterns
+
+| Class | HTTP Method | URL Pattern |
+|-------|------------|-------------|
+| ListPayeeOwners | GET | `payee/:payee_unique_id/owners[?type=X]` |
+| AssociatePayeeWithOwners | POST | `payee/:payee_unique_id/owners` |
+| DissociatePayeeWithOwners | DELETE | `payee/:payee_unique_id/owners` |
+| CreatePayeeDocument | POST | `payee/:payee_unique_id/documents` |
+| RetrievePayeeDocument | GET | `payee/:payee_unique_id/documents/:document_unique_id` |
+| ListPayeeDocuments | GET | `payee/:payee_unique_id/documents` |
+| Verifications::CreatePayeeVerification | POST | `payee/:payee_unique_id/verifications` |
+| Verifications::RetrievePayeeVerification | GET | `payee/:payee_unique_id/verifications/:verification_unique_id` |
+| Verifications::ListPayeeVerifications | GET | `payee/:payee_unique_id/verifications` |
+| Owners::Create | POST | `payee/owners` |
+| Owners::Retrieve | GET | `payee/owners/:owner_unique_id` |
+| Owners::Update | PATCH | `payee/owners/:owner_unique_id` |
+| Owners::Delete | DELETE | `payee/owners/:owner_unique_id` |
+| Owners::ListOwners | GET | `payee/owners` |
+| Owners::AssociateOwnerWithOwners | POST | `payee/owners/:owner_unique_id/owners` |
+| Owners::DissociateOwners | DELETE | `payee/owners/:owner_unique_id/owners` |
+| Owners::CreateOwnerDocument | POST | `payee/owners/:owner_unique_id/documents` |
+| Owners::RetrieveOwnerDocument | GET | `payee/owners/:owner_unique_id/documents/:document_unique_id` |
+| Owners::ListOwnerDocuments | GET | `payee/owners/:owner_unique_id/documents` |
+
+
+## Correctness Properties
+
+*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
+
+### Property 1: Required field validation rejects nil values
+
+*For any* request class and *for any* field declared in `required_fields`, setting that field to `nil` and calling `build_document` SHALL raise a `ParameterError`.
+
+**Validates: Requirements 2.3, 3.3, 4.3, 5.3, 6.3, 7.3, 8.3, 9.3, 10.3, 11.3, 12.3, 13.3, 14.3, 16.3, 17.3, 18.3, 19.3, 20.3**
+
+### Property 2: Path placeholder replacement produces valid URLs
+
+*For any* request class with path placeholders and *for any* valid non-empty ID string, after calling `build_document`, the resulting URL SHALL contain the ID string and SHALL NOT contain any `:placeholder` tokens.
+
+**Validates: Requirements 2.6, 3.6, 4.6, 5.6, 6.5, 7.5, 8.6, 9.5, 10.5, 12.5, 13.7, 14.5, 16.6, 17.6, 18.6, 19.5, 20.5, 21.3**
+
+### Property 3: Field value validation rejects invalid enum values
+
+*For any* request class with `field_values` constraints (owner_type, document_type, country) and *for any* string not in the allowed values list, calling `build_document` SHALL raise a `ParameterError`.
+
+**Validates: Requirements 5.4, 11.4, 11.5, 13.5, 18.4, 21.6**
+
+### Property 4: Request structure serialization preserves input data
+
+*For any* POST/PATCH/DELETE request class with a non-empty body and *for any* set of valid input parameters, the JSON-parsed output of `build_document` SHALL contain all non-nil input values under the correct nesting keys.
+
+**Validates: Requirements 3.4, 3.5, 4.4, 4.5, 5.5, 8.5, 11.7, 13.6, 16.4, 16.5, 17.4, 17.5, 18.5**
+
+### Property 5: Query parameter URL building for list endpoints
+
+*For any* list request class with optional query parameters and *for any* non-nil query parameter value, the resulting URL after `build_document` SHALL contain the parameter as a properly encoded query string. When all query parameters are nil, the URL SHALL NOT contain a `?`.
+
+**Validates: Requirements 2.4, 21.5**
+
+## Error Handling
+
+All request classes use the existing `Base::Versioned` validation framework:
+
+- **`ParameterError`** — Raised when required fields are nil/empty or field values don't match allowed lists. Raised during `build_document` → `process_request_parameters` → `check_requirements` → `validate`.
+- **`InvalidArgumentError`** — Raised for invalid API versions or builder interface mismatches.
+- **`BuilderError`** — Raised if the builder interface cannot be configured.
+- **`NetworkError`** — Raised by the network adapter for connection failures, timeouts, or invalid request types (including unrecognized HTTP methods).
+
+No new error types are needed. The DELETE infrastructure follows the same error patterns as existing methods.
+
+## Testing Strategy
+
+### Unit Tests (RSpec)
+
+Each of the 20 request classes gets a corresponding `_spec.rb` file following the existing pattern:
+
+1. **Config setup** — Standard `let(:config)` with username, password, token, endpoint, environment.
+2. **Sample data** — `let(:sample_data)` with Faker-generated values for all parameters.
+3. **Request setup** — `let(:request)` that creates and populates the request instance.
+4. **Structure test** — Verify `JSON.parse(request.build_document)` matches expected structure.
+5. **URL test** — Verify `request.api_config['url']` contains the correct path with replaced placeholders.
+6. **HTTP method test** — Verify `request.api_config['type']` matches expected method (GET/POST/PATCH/DELETE).
+7. **Token test** — Verify `request.api_config['token']` is nil (include_token: false).
+8. **Validation tests** — Required fields nil → ParameterError, invalid field values → ParameterError.
+9. **Shared examples** — `include_examples 'base request examples'` and `include_examples 'versioned request examples'`.
+
+Infrastructure tests:
+- `Api::Request` — Verify `METHOD_DELETE` constant and `init_delete_configuration` method.
+- `Utils::Options::ApiConfig` — Verify `load_delete_config` sets correct attributes.
+- `Network::Adapter::NetHttpAdapter` — Verify DELETE requests are dispatched correctly.
+
+### Property-Based Tests
+
+Using the `rspec-property` or `rantly` gem, minimum 100 iterations per property:
+
+- **Property 1**: Generate random request classes and nil out each required field, verify ParameterError.
+- **Property 2**: Generate random UUID strings for ID fields, verify URL contains them and has no placeholders.
+- **Property 3**: Generate random invalid strings for enum fields, verify ParameterError.
+- **Property 4**: Generate random valid parameter sets, verify JSON output contains all values.
+- **Property 5**: Generate random query param values, verify URL encoding.
+
+Each property test tagged with: `# Feature: payee-owner-documents-verifications, Property N: <title>`