chore(runway): cherry-pick feat(card): add card FREEZE, BLOCKED warnings and card provisioning flow (#21641)

- feat(card): add card FREEZE, BLOCKED warnings and card provisioning
flow (#21489)

<!--
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**

<!--
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?
-->

This PR introduces specific warning messages for cards with BLOCKED and
FREEZED statuses, improving user feedback and clarity during card
interactions.
It also adds support for card provisioning, allowing users to initiate
the setup process for a new card directly within the app.

## **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: Added distinct warnings for BLOCKED and FREEZED card
statuses
CHANGELOG entry: Enabled card provisioning flow for eligible users

## **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**

- [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]
> Implements card provisioning (UI + hooks + SDK), adds status/warning
handling (NoCard/Frozen/Blocked/NeedDelegation), updates CardImage with
status/opacity and address, and expands tests/i18n.
> 
> - **Card Home (UI)**:
> - Show `CardWarningBox` from `cardDetailsWarning`; hide sections on
`NeedDelegation`.
> - Add enable actions: `ENABLE_CARD_BUTTON` (provision + poll, then
fetch token/change asset) and `ENABLE_ASSETS_BUTTON` (change asset).
>   - Button states reflect provisioning/polling/loading.
> - **Hooks**:
> - `useCardDetails`: track `warning`,
`isLoadingPollCardStatusUntilProvisioned`; set warnings from
`CardStatus`; add `pollCardStatusUntilProvisioned` to await ACTIVE
status; handle `NO_CARD` without error.
> - New `useCardProvision`: orchestrates `sdk.provisionCard()` with
loading and error logging.
> - **SDK**:
> - Add `provisionCard()` (`POST /v1/card/order` with
`CardType.VIRTUAL`), auth headers, and error handling.
> - **CardImage**:
> - Accept `status` and `address`; lower opacity for `FROZEN/BLOCKED`;
truncate and render address.
> - **Warnings**:
> - `CardWarningBox`: support `Frozen/Blocked/NoCard`; hide box for
`NoCard/NeedDelegation`; conditional buttons; minor style tweaks.
> - **Types/Selectors/Strings**:
> - Add `CardStatus`, extend `CardWarning`, new test IDs; update
`en.json` strings for buttons and warnings.
> - **Tests**:
> - Extensive updates and new tests for provisioning flow, warnings,
polling, CardImage status/address, and SDK endpoint; remove obsolete
snapshots.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
ffaf970. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->


[c05d9d2](c05d9d2)

Co-authored-by: Bruno Nascimento <[email protected]>

Author: runway-github[bot]

app/components/UI/Card/Views/CardHome/CardHome.test.tsx

@@ -33,7 +33,7 @@ import { useGetPriorityCardToken } from '../../hooks/useGetPriorityCardToken';
 import { strings } from '../../../../../../locales/i18n';
 import { useAssetBalance } from '../../hooks/useAssetBalance';
 import { useNavigateToCardPage } from '../../hooks/useNavigateToCardPage';
-import { AllowanceState, CardType, CardWarning } from '../../types';
+import { AllowanceState, CardStatus, CardType, CardWarning } from '../../types';
 import CardAssetItem from '../../components/CardAssetItem';
 import ManageCardListItem from '../../components/ManageCardListItem';
 import CardImage from '../../components/CardImage';
@@ -54,8 +54,9 @@ import { useCardSDK } from '../../sdk';
 import Routes from '../../../../../constants/navigation/Routes';
 import useIsBaanxLoginEnabled from '../../hooks/isBaanxLoginEnabled';
 import useCardDetails from '../../hooks/useCardDetails';
-import CardWarningBox from '../../components/CardWarningBox/CardWarningBox';
 import { selectIsAuthenticatedCard } from '../../../../../core/redux/slices/card';
+import { useCardProvision } from '../../hooks/useCardProvision';
+import CardWarningBox from '../../components/CardWarningBox/CardWarningBox';
 import { useIsSwapEnabledForPriorityToken } from '../../hooks/useIsSwapEnabledForPriorityToken';
 
 /**
@@ -98,10 +99,15 @@ const CardHome = () => {
     useAssetBalance(priorityToken);
   const {
     cardDetails,
+    pollCardStatusUntilProvisioned,
     fetchCardDetails,
     isLoading: isLoadingCardDetails,
     error: cardDetailsError,
+    warning: cardDetailsWarning,
+    isLoadingPollCardStatusUntilProvisioned,
   } = useCardDetails();
+  const { provisionCard, isLoading: isLoadingProvisionCard } =
+    useCardProvision();
   const { navigateToCardPage } = useNavigateToCardPage(navigation);
   const { openSwaps } = useOpenSwaps({
     priorityToken,
@@ -259,6 +265,21 @@ const CardHome = () => {
     [isLoadingPriorityToken, isLoadingCardDetails],
   );
 
+  const enableCardAction = useCallback(async () => {
+    await provisionCard();
+    const isProvisioned = await pollCardStatusUntilProvisioned();
+
+    if (isProvisioned) {
+      fetchPriorityToken();
+      changeAssetAction();
+    }
+  }, [
+    provisionCard,
+    pollCardStatusUntilProvisioned,
+    fetchPriorityToken,
+    changeAssetAction,
+  ]);
+
   const ButtonsSection = useMemo(() => {
     if (isLoading) {
       return (
@@ -272,7 +293,45 @@ const CardHome = () => {
     }
 
     if (isBaanxLoginEnabled) {
-      if (priorityTokenWarning === CardWarning.NeedDelegation) return null;
+      if (cardDetailsWarning === CardWarning.NoCard) {
+        return (
+          <Button
+            variant={ButtonVariants.Primary}
+            style={styles.defaultMarginTop}
+            label={strings('card.card_home.enable_card_button_label')}
+            size={ButtonSize.Lg}
+            onPress={enableCardAction}
+            width={ButtonWidthTypes.Full}
+            disabled={
+              isLoading ||
+              isLoadingPollCardStatusUntilProvisioned ||
+              isLoadingProvisionCard
+            }
+            loading={
+              isLoading ||
+              isLoadingPollCardStatusUntilProvisioned ||
+              isLoadingProvisionCard
+            }
+            testID={CardHomeSelectors.ENABLE_CARD_BUTTON}
+          />
+        );
+      }
+
+      if (priorityTokenWarning === CardWarning.NeedDelegation) {
+        return (
+          <Button
+            variant={ButtonVariants.Primary}
+            style={styles.defaultMarginTop}
+            label={strings('card.card_home.enable_assets_button_label')}
+            size={ButtonSize.Lg}
+            onPress={changeAssetAction}
+            width={ButtonWidthTypes.Full}
+            disabled={isLoading}
+            loading={isLoading}
+            testID={CardHomeSelectors.ENABLE_ASSETS_BUTTON}
+          />
+        );
+      }
 
       return (
         <View style={styles.buttonsContainer}>
@@ -380,12 +439,7 @@ const CardHome = () => {
       alwaysBounceVertical={false}
       contentContainerStyle={styles.contentContainer}
     >
-      {priorityTokenWarning && (
-        <CardWarningBox
-          warning={priorityTokenWarning}
-          onConfirm={addFundsAction}
-        />
-      )}
+      {cardDetailsWarning && <CardWarningBox warning={cardDetailsWarning} />}
       <View style={styles.cardBalanceContainer}>
         <View
           style={[
@@ -467,6 +521,7 @@ const CardHome = () => {
           ) : (
             <CardImage
               type={cardDetails?.type ?? CardType.VIRTUAL}
+              status={cardDetails?.status ?? CardStatus.ACTIVE}
               address={priorityToken?.walletAddress}
             />
           )}

app/components/UI/Card/Views/CardHome/CardHome.tsx

@@ -520,7 +520,7 @@ exports[`CardHome Component renders correctly and matches snapshot 1`] = `
                                     }
                                   }
                                 >
-                                  card.card_home.change_asset
+                                  Change asset
                                 </Text>
                               </TouchableOpacity>
                             </View>
@@ -578,7 +578,7 @@ exports[`CardHome Component renders correctly and matches snapshot 1`] = `
                                       }
                                     }
                                   >
-                                    card.card_home.manage_card_options.manage_spending_limit
+                                    Manage spending limit
                                   </Text>
                                   <Text
                                     accessibilityRole="text"
@@ -592,7 +592,7 @@ exports[`CardHome Component renders correctly and matches snapshot 1`] = `
                                       }
                                     }
                                   >
-                                    card.card_home.manage_card_options.manage_spending_limit_description_full
+                                    Full spending access
                                   </Text>
                                 </View>
                                 <View
@@ -1262,7 +1262,7 @@ exports[`CardHome Component renders correctly with privacy mode enabled 1`] = `
                                     }
                                   }
                                 >
-                                  card.card_home.change_asset
+                                  Change asset
                                 </Text>
                               </TouchableOpacity>
                             </View>
@@ -1320,7 +1320,7 @@ exports[`CardHome Component renders correctly with privacy mode enabled 1`] = `
                                       }
                                     }
                                   >
-                                    card.card_home.manage_card_options.manage_spending_limit
+                                    Manage spending limit
                                   </Text>
                                   <Text
                                     accessibilityRole="text"
@@ -1334,7 +1334,7 @@ exports[`CardHome Component renders correctly with privacy mode enabled 1`] = `
                                       }
                                     }
                                   >
-                                    card.card_home.manage_card_options.manage_spending_limit_description_full
+                                    Full spending access
                                   </Text>
                                 </View>
                                 <View

app/components/UI/Card/Views/CardHome/__snapshots__/CardHome.test.tsx.snap

@@ -1,9 +1,15 @@
 import React from 'react';
 import CardImage from './CardImage';
-import { CardType } from '../../types';
+import { CardType, CardStatus } from '../../types';
 import { renderScreen } from '../../../../../util/test/renderWithProvider';
 import { backgroundState } from '../../../../../util/test/initial-root-state';
 
+jest.mock('../../util/truncateAddress', () => ({
+  truncateAddress: jest.fn(
+    (address: string) => `${address.slice(0, 6)}...${address.slice(-4)}`,
+  ),
+}));
+
 function renderWithProvider(component: React.ComponentType) {
   return renderScreen(
     component,
@@ -21,57 +27,144 @@ function renderWithProvider(component: React.ComponentType) {
 }
 
 describe('CardImage Component', () => {
-  it('renders virtual card image when type is VIRTUAL', () => {
-    const { toJSON, getByTestId } = renderWithProvider(() => (
-      <CardImage type={CardType.VIRTUAL} testID="virtual-card-image" />
+  it('renders virtual card image for VIRTUAL type', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.ACTIVE}
+        testID="virtual-card-image"
+      />
     ));
 
-    expect(getByTestId('virtual-card-image')).toBeDefined();
-    expect(toJSON()).toMatchSnapshot();
+    expect(getByTestId('virtual-card-image')).toBeOnTheScreen();
   });
 
-  it('renders metal card image when type is PHYSICAL', () => {
-    const { toJSON, getByTestId } = renderWithProvider(() => (
-      <CardImage type={CardType.PHYSICAL} testID="physical-card-image" />
+  it('renders metal card image for PHYSICAL type', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.PHYSICAL}
+        status={CardStatus.ACTIVE}
+        testID="physical-card-image"
+      />
     ));
 
-    expect(getByTestId('physical-card-image')).toBeDefined();
-    expect(toJSON()).toMatchSnapshot();
+    expect(getByTestId('physical-card-image')).toBeOnTheScreen();
   });
 
-  it('renders metal card image when type is METAL', () => {
-    const { toJSON, getByTestId } = renderWithProvider(() => (
-      <CardImage type={CardType.METAL} testID="metal-card-image" />
+  it('renders metal card image for METAL type', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.METAL}
+        status={CardStatus.ACTIVE}
+        testID="metal-card-image"
+      />
     ));
 
-    expect(getByTestId('metal-card-image')).toBeDefined();
-    expect(toJSON()).toMatchSnapshot();
+    expect(getByTestId('metal-card-image')).toBeOnTheScreen();
   });
 
-  it('renders with custom SVG properties', () => {
-    const { toJSON } = renderWithProvider(() => (
+  it('applies lower opacity when status is FROZEN', () => {
+    const { getByTestId } = renderWithProvider(() => (
       <CardImage
         type={CardType.VIRTUAL}
-        width={200}
-        height={100}
-        fill="red"
-        stroke="blue"
-        opacity={0.5}
-        testID="custom-card-image"
+        status={CardStatus.FROZEN}
+        testID="frozen-card"
+      />
+    ));
+
+    expect(getByTestId('frozen-card')).toBeOnTheScreen();
+  });
+
+  it('applies lower opacity when status is BLOCKED', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.BLOCKED}
+        testID="blocked-card"
+      />
+    ));
+
+    expect(getByTestId('blocked-card')).toBeOnTheScreen();
+  });
+
+  it('renders with full opacity when status is ACTIVE', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.ACTIVE}
+        testID="active-card"
+      />
+    ));
+
+    expect(getByTestId('active-card')).toBeOnTheScreen();
+  });
+
+  it('renders with truncated address when address prop provided', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.ACTIVE}
+        address="0x1234567890123456789012345678901234567890"
+        testID="card-with-address"
+      />
+    ));
+
+    expect(getByTestId('card-with-address')).toBeOnTheScreen();
+  });
+
+  it('renders without address when address prop not provided', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.ACTIVE}
+        testID="card-without-address"
       />
     ));
 
-    expect(toJSON()).toMatchSnapshot();
+    expect(getByTestId('card-without-address')).toBeOnTheScreen();
   });
 
   it.each([CardType.VIRTUAL, CardType.PHYSICAL, CardType.METAL] as const)(
-    'renders %s card type without errors',
+    'renders %s card type with ACTIVE status',
     (cardType) => {
-      const { toJSON } = renderWithProvider(() => (
-        <CardImage type={cardType} />
+      const { getByTestId } = renderWithProvider(() => (
+        <CardImage
+          type={cardType}
+          status={CardStatus.ACTIVE}
+          testID={`${cardType}-card`}
+        />
+      ));
+
+      expect(getByTestId(`${cardType}-card`)).toBeOnTheScreen();
+    },
+  );
+
+  it.each([CardStatus.ACTIVE, CardStatus.FROZEN, CardStatus.BLOCKED] as const)(
+    'renders VIRTUAL card with %s status',
+    (status) => {
+      const { getByTestId } = renderWithProvider(() => (
+        <CardImage
+          type={CardType.VIRTUAL}
+          status={status}
+          testID={`card-${status}`}
+        />
       ));
 
-      expect(toJSON()).toBeDefined();
+      expect(getByTestId(`card-${status}`)).toBeOnTheScreen();
     },
   );
+
+  it('renders with custom SVG properties', () => {
+    const { getByTestId } = renderWithProvider(() => (
+      <CardImage
+        type={CardType.VIRTUAL}
+        status={CardStatus.ACTIVE}
+        width={200}
+        height={100}
+        testID="custom-card-image"
+      />
+    ));
+
+    expect(getByTestId('custom-card-image')).toBeOnTheScreen();
+  });
 });