feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull request significantly improves the documentation and test coverage for the Platforms API integration, with a special focus on onboarding sub-entities and uploading identity documents. The changes clarify how to use the API, especially regarding the handling of representative documents, and enhance tests to ensure correct behavior for file uploads and document submission.

Documentation improvements:

• Expanded and clarified JSDoc comments for PlatformFiles and Subentity classes, detailing required fields, API endpoints, and the handling of representative and top-level documents, including strictness and validation differences. [1] [2] [3] [4] [5] [6]

Test coverage enhancements:

• Added comprehensive tests for representative documents (including identity verification, proof of address, proof of registration, and certified authorised signatory) in onboarding and updating sub-entities, ensuring the SDK sends the correct structure to the API unchanged.
• Added a test to verify that the correct purpose values are sent in multipart file uploads for representative documents.

Consistency and correctness:

• Updated test cases to use the correct purpose value (identity_verification instead of identification) for file uploads, aligning with API requirements. [1] [2] [3]

These changes ensure developers have clear guidance on how to use the API and confidence that the SDK handles documents and file uploads as required by the platform.

[agent-wall-e]

🟢 Risk Classification: LOW

Approval route: AI Auto-Approval
Rollback controls: Automated Instant Rollback + feature flags

Classification reasons

• no_low_class_matched
• prod_source_modified
• 2.2.6_logical_extension:The PR only adds JSDoc comments and updates test fixture values (correcting a purpose string), with no logic, endpoint, auth, data persistence, or behavioral changes.

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 4

---

_{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
no_low_class_matched	informational	§2.2 (fall-through)	None of the deterministic Low classes (§2.2.3, §2.2.4, §2.2.7, docs-only) applied; classifier fell through to LLM evaluation.
prod_source_modified	informational	§2.1 M7 (informational)	At least one file is non-doc, non-test, non-IaC — i.e. application source code was modified.
2.2.6_logical_extension — The PR only adds JSDoc comments and updates test fixture values (correcting a purpose string), with no logic, endpoint, auth, data persistence, or behavioral changes.	classifying	§2.2.6	Sonnet 4.6 evaluator promoted minor → low: the change reuses existing code paths and does not cross a trust boundary.

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]

✅ Auto-approved — this PR meets all Low-risk criteria.

All checks passed, no unresolved comments, and the change classification is:

• no_low_class_matched
• prod_source_modified
• 2.2.6_logical_extension:The PR only adds JSDoc comments and updates test fixtures/assertions (correcting a purpose string value), with no logic, endpoint, data model, or auth changes.

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

[agent-wall-e]

🟢 Risk Classification: LOW

Approval route: AI Auto-Approval
Rollback controls: Automated Instant Rollback + feature flags

Classification reasons

• no_low_class_matched
• prod_source_modified
• 2.2.6_logical_extension:The diff contains only JSDoc comment expansions, inline documentation comments on existing methods, and test corrections (fixing a string value from 'identification' to 'identity_verification'), with no new endpoints, data classes, auth changes, or behavioral logic introduced.

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 5

---

_{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
no_low_class_matched	informational	§2.2 (fall-through)	None of the deterministic Low classes (§2.2.3, §2.2.4, §2.2.7, docs-only) applied; classifier fell through to LLM evaluation.
prod_source_modified	informational	§2.1 M7 (informational)	At least one file is non-doc, non-test, non-IaC — i.e. application source code was modified.
2.2.6_logical_extension — The diff contains only JSDoc comment expansions, inline documentation comments on existing methods, and test corrections (fixing a string value from 'identification' to 'identity_verification'), with no new endpoints, data classes, auth changes, or behavioral logic introduced.	classifying	§2.2.6	Sonnet 4.6 evaluator promoted minor → low: the change reuses existing code paths and does not cross a trust boundary.

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]

✅ Auto-approved — this PR meets all Low-risk criteria.

All checks passed, no unresolved comments, and the change classification is:

• no_low_class_matched
• prod_source_modified
• 2.2.6_logical_extension:The PR only adds JSDoc comments, inline documentation, and test coverage updates (correcting a purpose value string), with no new endpoints, data persistence, auth changes, external integrations, or behavioral logic changes.

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

[agent-wall-e]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:291>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 — 291>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: Looks good to me

This PR still needs a human approval — wall-e cannot auto-approve it. For what it's worth, I read the diff and found nothing I'd block on.

This PR improves JSDoc documentation, TypeScript type definitions, and test quality for the Platforms API — primarily clarifying document placement, fixing the identification → identity_verification purpose value in tests, and adding new tests for representative documents and ETag header handling. The changes are purely documentation, types, and tests; no runtime logic is altered.

What I checked

• The identification → identity_verification correction in test/platforms/files/files-unit.js is consistent across all three occurrences and matches the documented purpose enum in both the JSDoc and the new TypeScript type.
• The new ETag/If-Match test in payment-instruments-unit.js correctly uses nock's reqheaders to assert the header is forwarded, which validates the existing implementation rather than adding new code.
• The uploadAFile round-trip test iterates all 14 PlatformsFileUpload purposes and verifies the SDK sends { purpose } unchanged, which is a meaningful correctness check.
• The TypeScript OnboardingDocument type is generic over the type field string with concrete union constraints per document kind, which is sound; identity_verification correctly extends it with an optional back field.
• The (string & {}) trick on PlatformFiles['uploadFile'] and uploadAFile purpose parameters is a valid TypeScript pattern for keeping autocomplete while accepting arbitrary strings.
• The truncated diff means the new subentity representative-documents tests (~1100 lines added to subentity-unit.js) are not fully visible, but what is shown looks structurally correct.
• ID values in tests have been updated from short synthetic strings (ent_1, file_123) to realistic-format identifiers matching the ent_/file_ prefix patterns, which is cosmetic but harmless.
• No production source files (non-test, non-doc, non-types) were modified, so there is no regression risk to runtime behaviour.

⚠️ 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:321>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 15

---

_{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 — 321>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