chore(runway): cherry-pick fix: cp-7.65.0 MUSD-308 add progressive rollout flag support for validatedVersionGatedFeatureFlag util (#25985)

- fix: cp-7.65.0 MUSD-308 add progressive rollout flag support for
validatedVersionGatedFeatureFlag util (#25983)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**
This PR adds progressive rollout flag compatibility to
`validatedVersionGatedFeatureFlag` util. Without this,
`validatedVersionGatedFeatureFlag` incorrectly returns `undefined`.
<!--
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?
-->

## **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: updated validatedVersionGatedFeatureFlag to support
progressive rollout flag format

## **Related issues**

Fixes: [MUSD-308: Fix progressive rollout flags compatibility with
"validatedVersionGatedFeatureFlag"
util](https://consensyssoftware.atlassian.net/browse/MUSD-308)

## **Manual testing steps**

```gherkin
Feature: Progressive feature flag support for validatedVersionGatedFeatureFlag

  Scenario: User correctly sees feature
    Given user is part of selectedGroup threshold for flag to be enabled

    When user opens app
    Then user sees mUSD conversion feature
```

## **Screenshots/Recordings**

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

### **Before**

<!-- [screenshots/recordings] -->
N/A
### **After**

<!-- [screenshots/recordings] -->
N/A
## **Pre-merge author checklist**

- [x] 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).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] 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]
> **Low Risk**
> Small, well-tested change to a feature-flag normalization utility;
main risk is behavior change for callers passing non-standard flag
shapes.
> 
> **Overview**
> `validatedVersionGatedFeatureFlag` now accepts `unknown` input and
supports a second “progressive rollout” runtime shape where the flag is
wrapped under a `value` property, unwrapping and validating before
applying the version gate.
> 
> Adds an internal `unwrapVersionGatedFeatureFlag` helper plus new unit
tests covering wrapped enabled/disabled flags, version pass/fail, and
malformed/missing wrapped values (while preserving the override
behavior).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b04b201. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->


[c89260c](c89260c)

Co-authored-by: Matthew Grainger <46547583+Matt561@users.noreply.github.com>

Author: runway-github[bot]

app/util/remoteFeatureFlag/index.test.ts

@@ -210,6 +210,18 @@ describe('validatedVersionGatedFeatureFlag', () => {
       expect(result).toBe(true);
     });
 
+    it('returns true when flag is wrapped in a value property and version check passes', () => {
+      const wrappedFlag = {
+        value: {
+          enabled: true,
+          minimumVersion: '1.0.0',
+        },
+      };
+
+      const result = validatedVersionGatedFeatureFlag(wrappedFlag);
+      expect(result).toBe(true);
+    });
+
     it('returns false when flag is enabled but version check fails', () => {
       const flagWithHigherVersion: VersionGatedFeatureFlag = {
         enabled: true,
@@ -219,11 +231,35 @@ describe('validatedVersionGatedFeatureFlag', () => {
       expect(result).toBe(false);
     });
 
+    it('returns false when wrapped flag is enabled but version check fails', () => {
+      const wrappedFlag = {
+        value: {
+          enabled: true,
+          minimumVersion: '99.0.0',
+        },
+      };
+
+      const result = validatedVersionGatedFeatureFlag(wrappedFlag);
+      expect(result).toBe(false);
+    });
+
     it('returns false when flag is disabled regardless of version', () => {
       const result = validatedVersionGatedFeatureFlag(validDisabledFlag);
       expect(result).toBe(false);
     });
 
+    it('returns false when wrapped flag is disabled regardless of version', () => {
+      const wrappedFlag = {
+        value: {
+          enabled: false,
+          minimumVersion: '1.0.0',
+        },
+      };
+
+      const result = validatedVersionGatedFeatureFlag(wrappedFlag);
+      expect(result).toBe(false);
+    });
+
     it('returns false when flag is disabled with higher version', () => {
       const disabledFlagWithHigherVersion: VersionGatedFeatureFlag = {
         enabled: false,
@@ -272,6 +308,27 @@ describe('validatedVersionGatedFeatureFlag', () => {
       expect(result).toBeUndefined();
     });
 
+    it('returns undefined when flag is wrapped but value is malformed', () => {
+      const wrappedMalformedFlag = {
+        value: {
+          enabled: 'true',
+          minimumVersion: '1.0.0',
+        },
+      };
+
+      const result = validatedVersionGatedFeatureFlag(wrappedMalformedFlag);
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when flag is wrapped but value is missing', () => {
+      const wrappedMissingValueFlag = {
+        value: undefined,
+      };
+
+      const result = validatedVersionGatedFeatureFlag(wrappedMissingValueFlag);
+      expect(result).toBeUndefined();
+    });
+
     it('returns undefined when enabled property is missing', () => {
       const malformedFlag = {
         minimumVersion: '1.0.0',

app/util/remoteFeatureFlag/index.ts

@@ -33,20 +33,53 @@ export const hasMinimumRequiredVersion = (minRequiredVersion: string) => {
   return compareVersions.compare(currentVersion, minRequiredVersion, '>=');
 };
 
-export const validatedVersionGatedFeatureFlag = (
-  remoteFlag: VersionGatedFeatureFlag,
-) => {
-  // If failed to fetch remote flag or flag is overridden or misconfigured return undefined to trigger fallback
+/**
+ * Normalizes version-gated remote feature flags from two possible runtime shapes.
+ *
+ * 1) Direct shape:
+ * { enabled: true, minimumVersion: '7.65.0' }
+ *
+ * 2) Progressive rollout shape :
+ * { name: undefined | string, value: { enabled: true, minimumVersion: '7.65.0' } }
+ *
+ */
+const unwrapVersionGatedFeatureFlag = (
+  remoteFlag: unknown,
+): VersionGatedFeatureFlag | undefined => {
+  if (isVersionGatedFeatureFlag(remoteFlag)) {
+    return remoteFlag;
+  }
+
   if (
-    isRemoteFeatureFlagOverrideActivated ||
-    !remoteFlag ||
-    typeof remoteFlag.enabled !== 'boolean' ||
-    typeof remoteFlag.minimumVersion !== 'string'
+    typeof remoteFlag === 'object' &&
+    remoteFlag !== null &&
+    'value' in remoteFlag
   ) {
+    const wrappedValue = (remoteFlag as { name?: string; value?: unknown })
+      .value;
+    if (isVersionGatedFeatureFlag(wrappedValue)) {
+      return wrappedValue;
+    }
+  }
+
+  return undefined;
+};
+
+export const validatedVersionGatedFeatureFlag = (remoteFlag: unknown) => {
+  // If remote flag is overridden, return undefined to trigger caller fallback
+  if (isRemoteFeatureFlagOverrideActivated) {
+    return undefined;
+  }
+
+  // Support both direct flags and progressive rollout wrapper objects
+  const normalizedFlag = unwrapVersionGatedFeatureFlag(remoteFlag);
+
+  if (!normalizedFlag) {
     return undefined;
   }
 
   return (
-    remoteFlag.enabled && hasMinimumRequiredVersion(remoteFlag.minimumVersion)
+    normalizedFlag.enabled &&
+    hasMinimumRequiredVersion(normalizedFlag.minimumVersion)
   );
 };