feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull request significantly expands and updates the integration and serialization tests for account onboarding entities, with a focus on schema 3.0 and representative document handling. It introduces new test cases for uploading and linking representative documents, adds utility methods for building valid company requests, and improves coverage for EEA Sole Trader scenarios. The changes ensure the SDK's test suite accurately reflects the latest API requirements and behaviors.

Integration test enhancements:

• Added new tests to verify onboarding of entities with representative documents, including identity verification and certified authorised signatory, and ensured that documents are echoed back by the API (test_should_onboard_entity_with_representative_documents).
• Added tests for uploading EEA Sole Trader proof files and retrieving them, covering the required purposes (test_should_upload_representative_proof_files).
• Updated the file upload and retrieval test to use a schema 3.0 entity and the correct file purpose (test_should_upload_entity_file_and_retrieve).

Test utility improvements:

• Introduced a build_company_v3_request helper to generate valid schema 3.0 company onboarding requests, reducing duplication and improving test maintainability.
• Enhanced the upload_file utility to support customizable file purposes for more flexible test scenarios.

Serialization test coverage:

• Added serialization tests for EEA Sole Trader representative documents, ensuring correct JSON structure and key presence, and validating that only accepted keys are declared in RepresentativeDocuments.
• Added regression and edge case tests to verify omission of unset attributes and correct handling of None values in representative documents.
• Added a test for serializing a controlling company as a representative, ensuring company structure is handled correctly.

Imports and dependency updates:

• Updated imports in test files to include new document-related classes and enums required for the new tests. [1] [2]

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:402>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 3

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 402>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🟠 Advisory review: Concerns worth a look

This PR needs a human approval. Before you give it, these are the things I'd want resolved.

The PR expands serialization/integration tests and adds docstrings for account onboarding entities. One concrete bug exists: the new unit test calls ApiClient.__new__(ApiClient)._process_custom_headers(...) directly on an uninitialized instance, which will fail or produce unreliable results depending on whether _process_custom_headers touches instance state.

Concerns

• In accounts_client_test.py, ApiClient.__new__(ApiClient)._process_custom_headers(body.headers) constructs an uninitialized ApiClient instance (bypassing __init__) and calls a method on it — if _process_custom_headers reads any instance attributes set in __init__, this will raise an AttributeError or silently return wrong data; the test should either use a properly constructed client or test the header translation at a higher level.
• The removed FilePurpose.IDENTIFICATION value in accounts_client_test.py (replaced with IDENTITY_VERIFICATION) should be verified against the actual enum definition in accounts.py to confirm IDENTIFICATION was genuinely removed/renamed and not just aliased, otherwise callers using the old name will break.
• The integration test test_should_create_get_and_update_onboard_entity removes national_tax_id from the payload and changes national_id_number from 'AB123456C' to '123456789' — if these are real sandbox credentials the test depends on, there is no explanation of why the old values stopped working, and the change may just be masking a real API rejection.
• The truncated diff means the full set of new classes (RepresentativeDocuments, CertifiedAuthorisedSignatory, EntityIdentification, etc.) and the build_company_v3_request helper cannot be reviewed for correctness; the review is necessarily incomplete.
• The update_payment_instrument patch passes headers=getattr(update_payment_instrument_request, 'headers', None) — if ApiClient.patch does not accept a headers kwarg, every call to update_payment_instrument will raise a TypeError; the diff does not show the ApiClient.patch signature to confirm this is safe.

⚠️ The diff was too large to read in full, so this review covers only part of the change.

---

_{This is not an approval. wall-e cannot auto-approve this PR — it is an opinion to help whoever does. Advisory review · us.anthropic.claude-sonnet-4-6 · wall-e 2026.06.19-02}

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:405>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 3

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 405>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:504>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 6

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 504>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

• exceeds_bounded_scope:903>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 8

---

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
exceeds_bounded_scope — 903>250	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud