feat: geolocation controller fix

[MarioAslau]

Explanation

The /geolocation API endpoint returns ISO 3166-2 subdivision codes (e.g. US-NY, CA-ON, GB), not ISO 3166-1 alpha-2 country-only codes (e.g. US, CA, GB).

The GeolocationApiService.#performFetch() validation regex was /^[A-Z]{2}$/u, which only accepts exactly 2 uppercase letters. Since the API returns values like US-NY, the regex rejects every valid response and the controller always stores UNKNOWN.

This causes all downstream consumers to receive UNKNOWN as the geolocation:

• Perps: Geo-blocking is ineffective — users in restricted regions (e.g. US) can access geo-blocked features because EligibilityService defaults to eligible for UNKNOWN.
• Ramps: Region detection always fails, breaking region-specific flows.
• Card: Geolocation is unavailable.

Fix: Updated the validation regex to /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/u, which accepts both 2-letter country codes (US, GB) and country+subdivision codes (US-NY, CA-ON). This matches the actual API response format and is consistent with the previous mobile implementation (useDetectGeolocation), which stored the raw API response with no validation.

Updated all JSDoc references from "ISO 3166-1 alpha-2" to "ISO 3166-2" to accurately reflect the API contract.

References

• Fixes regression introduced in feat: Implementation of gelocation controller #8037
• Related to the geolocation controller implementation

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

---

Note

Medium Risk
Changes geolocation response validation to allow ISO 3166-2 subdivision codes, which can affect region-based eligibility/geo-blocking decisions across consumers. Logic change is small (regex + tests/docs) but touches compliance-sensitive behavior.

Overview
Fixes geolocation parsing to match the API contract. GeolocationApiService.#performFetch() now accepts ISO 3166-2 codes (country plus optional subdivision like US-NY, CA-ON) instead of rejecting everything except 2-letter country codes.

Updates JSDoc/auto-generated method action docs and the package changelog to describe the new location-code format, and expands the service test suite to cover valid/invalid subdivision variants.

^{Written by Cursor Bugbot for commit 2a922f4. This will update automatically on new commits. Configure here.}

[cryptodev-2s]

@MarioAslau Could you also update the changelog file ?

[mcmire]

@MarioAslau FYI, this repo has its own pull request template, it doesn't use the same template as extension/mobile. Updating changelogs also follows a different process.

[MarioAslau]

@MarioAslau FYI, this repo has its own pull request template, it doesn't use the same template as extension/mobile. Updating changelogs also follows a different process.

Found it! Thanks for pointing that out! I configured a mono repo folder with cursor rules at the root, to allow the agent to learn from both codebases for more complex cross repo implementations. I'm modifying it !

[mcmire]

Tests could be more comprehensive, but I guess they can be adjusted as the need arises.