✨ server: validate id document photos for manteca

[mainqueg]

---

Summary by CodeRabbit

• New Features

  • ID document photo validation added to Manteca onboarding to ensure required front/back photos and country-specific rules are respected.

• Refactor

  • Account evaluation and document-selection flows converted to async and now prioritize valid ID types per country and photo-side requirements.

• Tests

  • Expanded test coverage for Manteca scenarios, async flows, network/chain cases, and document retrieval/validation behaviors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: de60df2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@exactly/server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[sentry]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.01%. Comparing base (bb36bfb) to head (de60df2).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #693      +/-   ##
==========================================
+ Coverage   63.73%   64.01%   +0.28%     
==========================================
  Files         169      169              
  Lines        5324     5324              
  Branches     1501     1501              
==========================================
+ Hits         3393     3408      +15     
+ Misses       1744     1730      -14     
+ Partials      187      186       -1     

Flag	Coverage Δ
e2e	42.23% <0.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gemini-code-assist]

Summary of Changes

Hello @mainqueg, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the identity document verification process for Manteca users by introducing a more rigorous check for 'id' class documents. it ensures that such documents include both front and back photos, and intelligently falls back to passport documents if the primary ID is incomplete. This change improves the accuracy and reliability of identity verification, streamlining the onboarding experience while maintaining necessary security standards.

Highlights

• Asynchronous Operations: The evaluateAccount and getDocumentForManteca functions have been updated to be asynchronous, reflecting potential API calls for document validation.
• ID Document Photo Validation: For 'id' class documents in Manteca, the system now explicitly checks for the presence of both front and back photos.
• Fallback to Passport: If an 'id' document is found but lacks the required photos, the system will attempt to use a 'pp' (passport) document as a fallback, if available and allowed for the country.
• Refactored Document Retrieval: A new helper function, getValidDocumentForManteca, was introduced to centralize the logic for determining a valid document based on ID class priority and photo requirements.
• Brazil ID Class Update: The allowed identification classes for Brazil (BR) in Manteca have been updated to exclude 'dl' (driver's license).
• Test Suite Enhancements: Comprehensive test cases have been added and updated to cover the new asynchronous behavior, photo validation, and fallback mechanisms.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Warning

Rate limit exceeded

@mainqueg has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 0 minutes and 0 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

Walkthrough

Makes persona document-selection and Manteca validation asynchronous: evaluateAccount now returns a Promise, introduces getValidDocumentForManteca, converts getDocumentForManteca to async, updates allowed Manteca ID config, and updates callers/tests to await document validation.

Changes

Cohort / File(s)	Summary
Changeset .changeset/gentle-streets-attack.md	Adds a changeset for a patch release to @exactly/server noting ID document photo validation for Manteca.
Tests — manteca mocks server/test/utils/manteca.test.ts	Replaced synchronous mock returns with async mocks (mockResolvedValueOnce), added chain id mocking and new scenarios for unsupported chains and BASE network behavior.
Tests — persona coverage server/test/utils/persona.test.ts	Converted many tests to async/await and rejects.toThrow, added global fetch spy, expanded Manteca/ID/PP document scenarios, priority/fallback cases, and adjusted fixtures.
Core logic — persona server/utils/persona.ts	Made evaluateAccount async (returns Promise), added getValidDocumentForManteca (async) to validate documents (front/back/selfie), converted getDocumentForManteca to async wrapper, introduced AllowedIdConfig with side info and updated allowed-Manteca IDs and related logic.
Ramp integration server/utils/ramps/manteca.ts	Updated Manteca onboarding to await the now-async getDocumentForManteca and use the resolved identity document when present.

Sequence Diagram(s)

(Skipped — changes are an internal async refactor and tests; no new multi-component runtime sequence diagram produced.)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• ✨ server: support manteca inquiry #680: Directly overlaps the async refactor of getDocumentForManteca / getValidDocumentForManteca and evaluateAccount.
• ♻️ server: support multiple kyc inquiry templates #637: Modifies the same persona/Manteca code paths and onboarding usage.
• ✨ server: support pax's assistance #612: Touches server/utils/persona.ts types/fields and may conflict with the new document-selection signatures.

Suggested reviewers

• cruzdanilo
• nfmelendez

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding validation of ID document photos for the Manteca onboarding process across multiple modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch side

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces validation for ID document photos for Manteca onboarding by making evaluateAccount and getDocumentForManteca asynchronous. This allows fetching document details to verify the presence of front and back photos for 'id' type documents, with a fallback mechanism to other document types. The changes are logical, and the accompanying tests are thorough, covering the new asynchronous flows and validation logic. I have one suggestion to refactor a function for improved clarity and efficiency.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional flags.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@server/test/utils/persona.test.ts`:
- Around line 5-12: The test suite creates a spy named fetchSpy used in the
"evaluateAccount" tests and while it is reset in beforeEach, it is not restored
after the suite finishes; add an afterAll hook for the evaluateAccount suite
that calls fetchSpy.mockRestore() to properly clean up the spy (locate the
evaluateAccount describe block and add afterAll(() => fetchSpy.mockRestore()) so
the spy lifecycle is completed).

In `@server/utils/persona.ts`:
- Around line 473-494: getValidDocumentForManteca currently calls
getDocument(...) for "id" documents but does not handle exceptions, so any
thrown error prevents falling back to other allowedIds; wrap the getDocument
call in a try/catch, and on error treat it like a missing document (log/debug
the error if desired) and continue the loop to allow returning other documents
from documents (referencing getValidDocumentForManteca, getDocument,
AccountBasicFields, IdentityDocument).

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@server/test/utils/persona.test.ts`:
- Around line 480-485: The "get document for manteca" test suite creates a
fetchSpy via vi.spyOn(globalThis, "fetch") but never restores it; add an
afterAll hook to restore the spy (call fetchSpy.mockRestore()) to avoid leaking
the mocked global fetch across tests, keeping the existing beforeEach mockReset
intact; reference the describe block name "get document for manteca" and the
fetchSpy variable so you can locate and update the suite.