🐛 server: fix bridge schema for non-us external accounts

[mainqueg]

Summary by CodeRabbit

Bug Fixes

• Fixed bridge schema handling for non-US external accounts, including currency-specific request/response mapping.
• Improved POST /external-account error translations for invalid bank name, postal code requirement, and already-existing external accounts.
• Updated update external account behavior so non-USD currencies omit account details appropriately, and bridge null values now map to optional fields.

Tests

• Added comprehensive test coverage for create, list, update, and delete external-account flows, including edge cases and new error handling.
• Expanded bridge mapping and schema validation tests for USD vs non-USD update payloads.

[changeset-bot]

🦋 Changeset detected

Latest commit: c9160e0

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 94552fcb-9a91-420d-b0c1-a7d3bca9d9e7

📥 Commits

Reviewing files that changed from the base of the PR and between 9594269 and c9160e0.

📒 Files selected for processing (5)

• .changeset/brave-heron-waves.md
• server/api/ramp.ts
• server/test/api/ramp.test.ts
• server/test/utils/bridge.test.ts
• server/utils/ramps/bridge.ts

---

Walkthrough

The Bridge UpdateExternalAccountInput schema is refactored into a currency-discriminated variant: USD permits optional address/account, while non-USD currencies require address and reject account. updateExternalAccount now omits the account payload for non-USD requests. ExternalAccount relaxes addressValid and beneficiary_address_valid to optional booleans. Error handling is extended to map Bridge validation failures (invalid bank name, required postal code, duplicate account) to new API error codes. Tests and a changeset entry are added to match.

Changes

Bridge schema fix for non-US external accounts

Layer / File(s)	Summary
UpdateExternalAccountInput schema and ExternalAccount relaxation server/utils/ramps/bridge.ts	UpdateExternalAccountInput is rewritten as a variant discriminated on currency: USD accepts optional address/account with an internal presence check; BRL/EUR/GBP/MXN require address and disallow account. ExternalAccount makes addressValid and beneficiary_address_valid optional.
Bridge function implementations server/utils/ramps/bridge.ts	updateExternalAccount gates the account payload on currency === "USD". createExternalAccount, updateExternalAccount, and listExternalAccounts map Bridge response fields beneficiary_address_valid and bank_name to optional ExternalAccount fields via nullish-to-undefined. getOfframpDepositDetails removes a prior TRANSFER_IN_USE guard for non-awaiting-funds transfers.
Error code definitions and API error mapping server/utils/ramps/bridge.ts, server/api/ramp.ts	ErrorCodes in bridge.ts extends with external-account failure modes. ErrorCodes in api/ramp.ts gains INVALID_BANK_NAME and POSTAL_CODE_REQUIRED. POST /external-account endpoint maps Bank name, postal code, and duplicate-account errors to HTTP 400 JSON responses.
bridge.test.ts unit tests for schema validation and mapping server/test/utils/bridge.test.ts	Existing updateExternalAccount PUT tests gain explicit currency: "USD". New non-USD test asserts addressValid: undefined when beneficiary_address_valid is absent. Schema validation tests added for empty payloads, account-only payloads, non-USD missing address, and non-USD account stripping. Error tests updated to pass {currency, address} and cover 404 normalization. createExternalAccount gains error-case coverage for bank name, postal code, and duplicate account. listExternalAccounts tests verify null fields map to undefined. externalAccountResponse helper conditionally emits beneficiary_address_valid only for USD.
ramp.test.ts API-level external account endpoint tests server/test/api/ramp.test.ts	Adds create external account, list external accounts, and update external account test suites covering credential/bridge preconditions, customer endorsement, error mapping, delegation, and non-USD account omission. Extends delete external account with TRANSFER_IN_USE → 400 scenario. Introduces a shared externalAccount constant.
Release notes .changeset/brave-heron-waves.md	Changeset entry for @exactly/server patch release documenting the bridge schema fix for non-US external accounts.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• exactly/exa#1024: Introduced the Bridge external account domain including UpdateExternalAccountInput, ExternalAccount schemas, and updateExternalAccount mapping in server/utils/ramps/bridge.ts — the exact contracts this PR refactors.

Suggested reviewers

• nfmelendez
• cruzdanilo

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 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: fixing the bridge schema to properly handle non-US external accounts, which is the central focus of the schema refactoring and test additions in this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch update

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch update

---

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 fixes the Bridge schema for non-US external accounts. Specifically, it updates the UpdateExternalAccountInput schema to require an address and omit account details for non-USD currencies (BRL, EUR, GBP, MXN), while keeping them optional for USD. Additionally, it makes the beneficiary_address_valid (and its mapped addressValid) field optional, as it is missing for non-US accounts. Comprehensive API and utility tests have been added to verify these changes. I have no feedback to provide as there are no review comments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9594269d71

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.72%. Comparing base (e59c92c) to head (c9160e0).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
server/api/ramp.ts	88.88%	1 Missing ⚠️
server/utils/ramps/bridge.ts	97.14%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1097      +/-   ##
==========================================
+ Coverage   74.95%   75.72%   +0.76%     
==========================================
  Files         245      245              
  Lines       11658    11874     +216     
  Branches     4050     4182     +132     
==========================================
+ Hits         8738     8991     +253     
+ Misses       2598     2561      -37     
  Partials      322      322              

Flag	Coverage Δ
e2e	74.54% <86.36%> (+0.24%)	⬆️

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

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

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.