feat(ramps): adopts new controller user region api interface (#24280)

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

## **Description**

This PR adopts the breaking changes from `@metamask/ramps-controller`
v3.1.0, which refactors the controller to use "userRegion" terminology
instead of "geolocation" and introduces proper initialization patterns.

### **Reason for Change**

The ramps-controller package was refactored to:
1. **Improve naming clarity**: "geolocation" implies a read-only,
automatically-detected value, but we plan to allow users to manually
change their region. The new "userRegion" terminology better reflects
that it's a user-selectable region.
2. **Add proper initialization**: Previously, consumers had to manually
call `updateGeolocation()` after creating the controller, which was
error-prone. The new `init()` method encapsulates initialization logic
and automatically fetches the user region at startup.
3. **Enable manual region setting**: The new `setUserRegion()` method
allows users to manually set their region without calling the
geolocation API, preparing for future UI features.

### **Changes in This PR**

#### **Selectors** (`app/selectors/rampsController/index.ts`)
- ✅ Removed deprecated `selectGeolocation` selector
- ✅ Removed deprecated `selectGeolocationRequest` selector  
- ✅ Added `selectUserRegion` selector (replaces `selectGeolocation`)
- ✅ Added `selectUserRegionRequest` selector (replaces
`selectGeolocationRequest`)

#### **Hooks** (`app/components/UI/Ramp/hooks/`)
- ✅ Renamed `useRampsGeolocation.ts` → `useRampsUserRegion.ts`
- ✅ Updated hook to use new `updateUserRegion()` and `setUserRegion()`
methods
- ✅ Updated hook to use new `selectUserRegion` and
`selectUserRegionRequest` selectors
- ✅ Updated all references and imports throughout the codebase

#### **Controller Initialization**
(`app/core/Engine/controllers/ramps-controller/ramps-controller-init.ts`)
- ✅ Updated to call `controller.init()` at startup (non-blocking)
- ✅ Initialization automatically fetches user region via geolocation API
- ✅ Errors are handled gracefully and available via selectors

#### **Tests**
- ✅ Updated `ramps-controller-init.test.ts` to test new `init()` method
- ✅ Updated `useRampsUserRegion.test.ts` to use new API and cache keys
- ✅ Updated selector tests to use `userRegion` state property
- ✅ All tests updated to use `'updateUserRegion'` cache key instead of
`'updateGeolocation'`

#### **Yarn Patch**
- ✅ Updated ramps-controller patch to include all local changes
(userRegion state, updateUserRegion, setUserRegion, init methods)

### **Migration Guide**

**Before:**
```ts
import { selectGeolocation, selectGeolocationRequest } from './selectors/rampsController';
import { useRampsGeolocation } from './hooks/useRampsGeolocation';

// Manual initialization required
Engine.context.RampsController.updateGeolocation();
```

**After:**
```ts
import { selectUserRegion, selectUserRegionRequest } from './selectors/rampsController';
import { useRampsUserRegion } from './hooks/useRampsUserRegion';

// Automatic initialization via controller.init() in ramps-controller-init.ts
```

### **Breaking Changes Adopted**

- ❌ `geolocation` state property → ✅ `userRegion`
- ❌ `updateGeolocation()` method → ✅ `updateUserRegion()`
- ❌ `selectGeolocation` selector → ✅ `selectUserRegion`
- ❌ `selectGeolocationRequest` selector → ✅ `selectUserRegionRequest`
- ❌ `useRampsGeolocation()` hook → ✅ `useRampsUserRegion()`

### **Related PRs**

- Core package PR:
[MetaMask/core#7563](MetaMask/core#7563) -
Refactors ramps-controller to use userRegion terminology and adds init()
method



## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: Adopted new ramp controller variable names

## **Related issues**

Fixes:

## **Manual testing steps**

```gherkin
Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [ ] I’ve followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [ ] I've completed the PR template to the best of my ability
- [ ] I’ve included tests if applicable
- [ ] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [ ] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.



<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adopts the new `@metamask/ramps-controller` v3 APIs and init model.
> 
> - Migrate from `geolocation` to `userRegion`: new `useRampsUserRegion`
hook (with `fetchUserRegion` and `setUserRegion`), selectors
`selectUserRegion`/`selectUserRegionRequest` (retain `selectGeolocation`
aliases); update `useRampsGeolocation` to call `updateUserRegion`
> - Initialize controller via `controller.init()` at startup
(`ramps-controller-init`), replacing `updateGeolocation` side-effect
> - Refactor ramps service init: derive environment via
`getRampsEnvironment` and platform context via `getRampsContext` (uses
`Platform.OS`)
> - Update fixtures, snapshots, and tests accordingly (new request keys
`updateUserRegion:[]`, added `eligibility`/`tokens` fields)
> - Bump dependency to `@metamask/ramps-controller@^3.0.0`
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
c99674b. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: georgeweiler

app/components/UI/Ramp/hooks/useRampsGeolocation.test.ts

@@ -47,11 +47,14 @@ export interface UseRampsGeolocationResult {
  */
 export function useRampsGeolocation(): UseRampsGeolocationResult {
   const geolocation = useSelector(selectGeolocation);
-  const { isFetching, error } = useSelector(selectGeolocationRequest);
+  const { isFetching, error } = useSelector(selectGeolocationRequest) as {
+    isFetching: boolean;
+    error: string | null;
+  };
 
   const fetchGeolocation = useCallback(
     (options?: ExecuteRequestOptions) =>
-      Engine.context.RampsController.updateGeolocation(options),
+      Engine.context.RampsController.updateUserRegion(options),
     [],
   );
 
@@ -69,4 +72,6 @@ export function useRampsGeolocation(): UseRampsGeolocationResult {
   };
 }
 
+export { useRampsUserRegion } from './useRampsUserRegion';
+
 export default useRampsGeolocation;

app/components/UI/Ramp/hooks/useRampsGeolocation.ts

@@ -0,0 +1,218 @@
+import { renderHook, waitFor } from '@testing-library/react-native';
+import { Provider } from 'react-redux';
+import { configureStore } from '@reduxjs/toolkit';
+import React from 'react';
+import { useRampsUserRegion } from './useRampsUserRegion';
+import { RequestStatus } from '@metamask/ramps-controller';
+import Engine from '../../../../core/Engine';
+
+jest.mock('../../../../core/Engine', () => ({
+  context: {
+    RampsController: {
+      updateUserRegion: jest.fn().mockResolvedValue('US'),
+      setUserRegion: jest.fn().mockResolvedValue({
+        aggregator: true,
+        deposit: true,
+        global: true,
+      }),
+    },
+  },
+}));
+
+const createMockStore = (rampsControllerState = {}) =>
+  configureStore({
+    reducer: {
+      engine: () => ({
+        backgroundState: {
+          RampsController: {
+            userRegion: null,
+            requests: {},
+            ...rampsControllerState,
+          },
+        },
+      }),
+    },
+  });
+
+const wrapper = (store: ReturnType<typeof createMockStore>) =>
+  function Wrapper({ children }: { children: React.ReactNode }) {
+    return React.createElement(Provider, { store } as never, children);
+  };
+
+describe('useRampsUserRegion', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('return value structure', () => {
+    it('returns userRegion, isLoading, error, fetchUserRegion, and setUserRegion', () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      expect(result.current).toMatchObject({
+        userRegion: null,
+        isLoading: false,
+        error: null,
+      });
+      expect(typeof result.current.fetchUserRegion).toBe('function');
+      expect(typeof result.current.setUserRegion).toBe('function');
+    });
+  });
+
+  describe('userRegion state', () => {
+    it('returns userRegion from state', () => {
+      const store = createMockStore({ userRegion: 'US-CA' });
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      expect(result.current.userRegion).toBe('US-CA');
+    });
+  });
+
+  describe('loading state', () => {
+    it('returns isLoading true when request is loading', () => {
+      const store = createMockStore({
+        requests: {
+          'updateUserRegion:[]': {
+            status: RequestStatus.LOADING,
+            data: null,
+            error: null,
+            timestamp: Date.now(),
+            lastFetchedAt: Date.now(),
+          },
+        },
+      });
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      expect(result.current.isLoading).toBe(true);
+    });
+  });
+
+  describe('error state', () => {
+    it('returns error from request state', () => {
+      const store = createMockStore({
+        requests: {
+          'updateUserRegion:[]': {
+            status: RequestStatus.ERROR,
+            data: null,
+            error: 'Network error',
+            timestamp: Date.now(),
+            lastFetchedAt: Date.now(),
+          },
+        },
+      });
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      expect(result.current.error).toBe('Network error');
+    });
+  });
+
+  describe('fetchUserRegion', () => {
+    it('calls updateUserRegion without options when called with no arguments', async () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      await result.current.fetchUserRegion();
+      expect(
+        Engine.context.RampsController.updateUserRegion,
+      ).toHaveBeenCalledWith(undefined);
+    });
+
+    it('calls updateUserRegion with forceRefresh true when specified', async () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      await result.current.fetchUserRegion({ forceRefresh: true });
+      expect(
+        Engine.context.RampsController.updateUserRegion,
+      ).toHaveBeenCalledWith({
+        forceRefresh: true,
+      });
+    });
+
+    it('calls updateUserRegion with forceRefresh false when specified', async () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      await result.current.fetchUserRegion({ forceRefresh: false });
+      expect(
+        Engine.context.RampsController.updateUserRegion,
+      ).toHaveBeenCalledWith({
+        forceRefresh: false,
+      });
+    });
+
+    it('rejects with error when updateUserRegion fails', async () => {
+      const store = createMockStore();
+      const mockUpdateUserRegion = Engine.context.RampsController
+        .updateUserRegion as jest.Mock;
+      mockUpdateUserRegion.mockReset();
+      mockUpdateUserRegion.mockRejectedValue(new Error('Network error'));
+
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+
+      await expect(result.current.fetchUserRegion()).rejects.toThrow(
+        'Network error',
+      );
+    });
+  });
+
+  describe('setUserRegion', () => {
+    it('calls setUserRegion on controller', async () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      await result.current.setUserRegion('US-CA');
+      expect(Engine.context.RampsController.setUserRegion).toHaveBeenCalledWith(
+        'US-CA',
+        undefined,
+      );
+    });
+
+    it('calls setUserRegion with options when specified', async () => {
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+      await result.current.setUserRegion('US-CA', { forceRefresh: true });
+      expect(Engine.context.RampsController.setUserRegion).toHaveBeenCalledWith(
+        'US-CA',
+        { forceRefresh: true },
+      );
+    });
+  });
+
+  describe('useEffect error handling', () => {
+    it('returns default state when fetchUserRegion rejects in useEffect', async () => {
+      const store = createMockStore();
+      const mockUpdateUserRegion = Engine.context.RampsController
+        .updateUserRegion as jest.Mock;
+      mockUpdateUserRegion.mockReset();
+      mockUpdateUserRegion.mockRejectedValue(new Error('Fetch failed'));
+
+      const { result } = renderHook(() => useRampsUserRegion(), {
+        wrapper: wrapper(store),
+      });
+
+      await waitFor(() => {
+        expect(mockUpdateUserRegion).toHaveBeenCalled();
+      });
+
+      expect(result.current).toMatchObject({
+        userRegion: null,
+        isLoading: false,
+        error: null,
+      });
+      expect(typeof result.current.fetchUserRegion).toBe('function');
+    });
+  });
+});

app/components/UI/Ramp/hooks/useRampsUserRegion.test.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect } from 'react';
+import { useSelector } from 'react-redux';
+import Engine from '../../../../core/Engine';
+import {
+  selectUserRegion,
+  selectUserRegionRequest,
+} from '../../../../selectors/rampsController';
+import {
+  ExecuteRequestOptions,
+  RequestSelectorResult,
+} from '@metamask/ramps-controller';
+
+/**
+ * Result returned by the useRampsUserRegion hook.
+ */
+export interface UseRampsUserRegionResult {
+  /**
+   * The user's region code (e.g., "US-CA"), or null if not loaded.
+   */
+  userRegion: string | null;
+  /**
+   * Whether the user region request is currently loading.
+   */
+  isLoading: boolean;
+  /**
+   * The error message if the request failed, or null.
+   */
+  error: string | null;
+  /**
+   * Manually fetch the user region from geolocation.
+   */
+  fetchUserRegion: (options?: ExecuteRequestOptions) => Promise<string>;
+  /**
+   * Set the user region manually (without fetching geolocation).
+   */
+  setUserRegion: (
+    region: string,
+    options?: ExecuteRequestOptions,
+  ) => Promise<void>;
+}
+
+/**
+ * Hook to get the user's region state from RampsController.
+ * This hook assumes Engine is already initialized.
+ *
+ * @returns User region state and fetch/set functions.
+ */
+export function useRampsUserRegion(): UseRampsUserRegionResult {
+  const userRegion = useSelector(selectUserRegion);
+  const { isFetching, error } = useSelector(
+    selectUserRegionRequest,
+  ) as RequestSelectorResult<string>;
+
+  const fetchUserRegion = useCallback(
+    (options?: ExecuteRequestOptions) =>
+      Engine.context.RampsController.updateUserRegion(options),
+    [],
+  );
+
+  const setUserRegion = useCallback(
+    async (region: string, options?: ExecuteRequestOptions) => {
+      await Engine.context.RampsController.setUserRegion(region, options);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    fetchUserRegion().catch(() => {
+      // Error is stored in state
+    });
+  }, [fetchUserRegion]);
+
+  return {
+    userRegion,
+    isLoading: isFetching,
+    error,
+    fetchUserRegion,
+    setUserRegion,
+  };
+}
+
+export default useRampsUserRegion;

app/components/UI/Ramp/hooks/useRampsUserRegion.ts

@@ -278,6 +278,7 @@ describe('Engine', () => {
       RampsController: {
         ...backgroundState.RampsController,
         eligibility: null,
+        tokens: null,
       },
     };