fix: handle polling subscriptions after subscription with card cp-13.13.0 (#38610)

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

Previously after subscription with card we navigate to shield settings
screen with wait for active subscriptions params but in background we
only fetch subscription once so if stripe event handle in backend is
slower than client fetch, it would timeout in shield settings screen.
This PR add subscriptions polling after subscription with card stripe
checkout succeeded to ensure we fetch for latest subscription created.

[![Open in GitHub
Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MetaMask/metamask-extension/pull/38610?quickstart=1)

## **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: fix shield subscription subscribe with card race
condition

## **Related issues**

Fixes: #38615

## **Manual testing steps**

1. Go to shield plan
2. Subscribe with card
3. After succeed should navigate to shield settings screen and wait for
subscription creation

## **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
Extension Coding
Standards](https://github.com/MetaMask/metamask-extension/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-extension/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [x] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [x] 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]
> Adds polling after card checkout to wait for active/paused Shield
subscription with configurable interval/timeout, and centralizes Shield
error constants; updates tests and UI usage.
> 
> - **Subscription Service**
(`app/scripts/services/subscription/subscription-service.ts`):
> - Add polling (`#pollForSubscription`) using
`getIsShieldSubscriptionActive/Paused`, with defaults
`SUBSCRIPTION_POLL_INTERVAL` and `SUBSCRIPTION_POLL_TIMEOUT`; throws
`SHIELD_ERROR.subscriptionPollingTimedOut`.
> - `startSubscriptionWithCard` now polls until subscription exists;
accepts optional `subscriptionPollInterval`/`subscriptionPollTimeout`;
on "already exists" error, refreshes `getSubscriptions`.
> - Use `SHIELD_ERROR.tabActionFailed` when checkout tab closes without
success; open settings with `waitForSubscriptionCreation=true`.
>   - Minor: import time constants (`SECOND`) and Shield helpers.
> - **Shared** (`shared/modules/shield/constants.ts`):
> - Introduce `SHIELD_ERROR` with `tabActionFailed` and
`subscriptionPollingTimedOut`.
> - **UI Hook** (`ui/hooks/subscription/useSubscription.ts`):
> - Switch to `SHIELD_ERROR.tabActionFailed` for non-API tab failure
handling.
> - **Tests**
(`app/scripts/services/subscription/subscription-service.test.ts`):
> - Add mocks and cases for polling behavior (paused, multi-attempts,
timeout) and environment setup; assert results/errors accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3dfb3b6. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: tuna1207

app/scripts/services/subscription/subscription-service.test.ts

@@ -9,6 +9,9 @@ import {
   PAYMENT_TYPES,
   PRODUCT_TYPES,
   RECURRING_INTERVALS,
+  Subscription,
+  SUBSCRIPTION_STATUSES,
+  SubscriptionPaymentMethod,
 } from '@metamask/subscription-controller';
 import browser from 'webextension-polyfill';
 import { TransactionType } from '@metamask/transaction-controller';
@@ -17,6 +20,8 @@ import { ENVIRONMENT } from '../../../../development/build/constants';
 import { WebAuthenticator } from '../oauth/types';
 import { createSwapsMockStore } from '../../../../test/jest';
 import getFetchWithTimeout from '../../../../shared/modules/fetch-with-timeout';
+import { DAY } from '../../../../shared/constants/time';
+import { SHIELD_ERROR } from '../../../../shared/modules/shield';
 import { SubscriptionService } from './subscription-service';
 import { SubscriptionServiceMessenger } from './types';
 
@@ -50,6 +55,24 @@ const MAINNET_BASE = {
 
 const MOCK_REDIRECT_URI = 'https://mocked-redirect-uri';
 
+const MOCK_ACTIVE_SHIELD_SUBSCRIPTION: Subscription = {
+  id: 'sub_123',
+  status: SUBSCRIPTION_STATUSES.active,
+  products: [
+    {
+      name: PRODUCT_TYPES.SHIELD,
+      currency: 'usd',
+      unitAmount: 100,
+      unitDecimals: 2,
+    },
+  ],
+  paymentMethod: { type: PAYMENT_TYPES.byCard } as SubscriptionPaymentMethod,
+  interval: RECURRING_INTERVALS.month,
+  currentPeriodStart: new Date().toISOString(),
+  currentPeriodEnd: new Date(Date.now() + 30 * DAY).toISOString(),
+  isEligibleForSupport: true,
+};
+
 const getRedirectUrlSpy = jest.fn().mockReturnValue(MOCK_REDIRECT_URI);
 const mockSubmitSponsorshipIntents = jest.fn();
 const mockGetTransactions = jest.fn();
@@ -194,11 +217,14 @@ describe('SubscriptionService - startSubscriptionWithCard', () => {
 
   beforeEach(() => {
     process.env = { ...originalEnv };
+    process.env.METAMASK_SHIELD_ENABLED = 'true';
     delete process.env.IN_TEST; // unset IN_TEST environment variable
 
     mockStartShieldSubscriptionWithCard.mockResolvedValue({
       checkoutSessionUrl: mockCheckoutSessionUrl,
     });
+    // Mock getSubscriptions to return active subscription for polling to complete
+    mockGetSubscriptions.mockResolvedValue([MOCK_ACTIVE_SHIELD_SUBSCRIPTION]);
     mockGetAppStateControllerState.mockReturnValue({
       defaultSubscriptionPaymentOptions: {
         defaultBillingInterval: RECURRING_INTERVALS.month,
@@ -345,6 +371,64 @@ describe('SubscriptionService - startSubscriptionWithCard', () => {
     expect(mockGetRewardSeasonMetadata).toHaveBeenCalledWith('current');
     expect(mockGetHasAccountOptedIn).not.toHaveBeenCalled();
   });
+
+  it('should poll until paused subscription is found', async () => {
+    mockGetSubscriptions.mockRestore();
+    const pausedSubscription = {
+      ...MOCK_ACTIVE_SHIELD_SUBSCRIPTION,
+      status: SUBSCRIPTION_STATUSES.paused,
+    };
+    mockGetSubscriptions.mockResolvedValue([pausedSubscription]);
+
+    const result = await subscriptionService.startSubscriptionWithCard({
+      products: [PRODUCT_TYPES.SHIELD],
+      isTrialRequested: false,
+      recurringInterval: RECURRING_INTERVALS.month,
+    });
+
+    expect(mockGetSubscriptions).toHaveBeenCalled();
+    expect(result).toEqual([pausedSubscription]);
+  });
+
+  it('should poll multiple times until active subscription is found', async () => {
+    mockGetSubscriptions.mockRestore();
+    // First call returns no subscription, second call returns active subscription
+    mockGetSubscriptions
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([MOCK_ACTIVE_SHIELD_SUBSCRIPTION]);
+
+    const result = await subscriptionService.startSubscriptionWithCard(
+      {
+        products: [PRODUCT_TYPES.SHIELD],
+        isTrialRequested: false,
+        recurringInterval: RECURRING_INTERVALS.month,
+      },
+      undefined,
+      100,
+    );
+
+    expect(mockGetSubscriptions).toHaveBeenCalledTimes(2);
+    expect(result).toEqual([MOCK_ACTIVE_SHIELD_SUBSCRIPTION]);
+  });
+
+  it('should throw timeout error when subscription is not activated within timeout period', async () => {
+    mockGetSubscriptions.mockRestore();
+    // Always return empty subscriptions to simulate no active subscription
+    mockGetSubscriptions.mockResolvedValue([]);
+
+    await expect(() =>
+      subscriptionService.startSubscriptionWithCard(
+        {
+          products: [PRODUCT_TYPES.SHIELD],
+          isTrialRequested: false,
+          recurringInterval: RECURRING_INTERVALS.month,
+        },
+        undefined,
+        100,
+        1000,
+      ),
+    ).rejects.toThrow(SHIELD_ERROR.subscriptionPollingTimedOut);
+  });
 });
 
 describe('SubscriptionService - handlePostTransaction', () => {

app/scripts/services/subscription/subscription-service.ts

@@ -4,6 +4,7 @@ import {
   PAYMENT_TYPES,
   PRODUCT_TYPES,
   StartSubscriptionRequest,
+  Subscription,
   UpdatePaymentMethodOpts,
 } from '@metamask/subscription-controller';
 import {
@@ -36,6 +37,12 @@ import {
   MetaMetricsEventCategory,
   MetaMetricsEventName,
 } from '../../../../shared/constants/metametrics';
+import { SECOND } from '../../../../shared/constants/time';
+import {
+  getIsShieldSubscriptionActive,
+  getIsShieldSubscriptionPaused,
+} from '../../../../shared/lib/shield';
+import { SHIELD_ERROR } from '../../../../shared/modules/shield';
 import {
   SubscriptionServiceAction,
   SubscriptionServiceEvent,
@@ -44,6 +51,9 @@ import {
   ServiceName,
 } from './types';
 
+const SUBSCRIPTION_POLL_INTERVAL = 5 * SECOND;
+const SUBSCRIPTION_POLL_TIMEOUT = 60 * SECOND;
+
 export class SubscriptionService {
   // Required for modular initialisation.
   name: ServiceName = SERVICE_NAME;
@@ -137,6 +147,8 @@ export class SubscriptionService {
   async startSubscriptionWithCard(
     params: StartSubscriptionRequest,
     currentTabId?: number,
+    subscriptionPollInterval?: number,
+    subscriptionPollTimeout?: number,
   ) {
     try {
       const redirectUrl = this.#webAuthenticator.getRedirectURL();
@@ -169,8 +181,10 @@ export class SubscriptionService {
         }
       }
 
-      const subscriptions = await this.#messenger.call(
-        'SubscriptionController:getSubscriptions',
+      // Poll subscriptions until active or paused subscription is created (stripe webhook may be delayed)
+      const subscriptions = await this.#pollForSubscription(
+        subscriptionPollInterval,
+        subscriptionPollTimeout,
       );
       this.trackSubscriptionRequestEvent('completed');
 
@@ -187,6 +201,11 @@ export class SubscriptionService {
         // eslint-disable-next-line @typescript-eslint/naming-convention
         error_message: errorMessage,
       });
+
+      // fetch latest subscriptions to update the state in case subscription already created error (not when polling timed out)
+      if (errorMessage.toLocaleLowerCase().includes('already exists')) {
+        await this.#messenger.call('SubscriptionController:getSubscriptions');
+      }
       throw error;
     }
   }
@@ -365,14 +384,46 @@ export class SubscriptionService {
           if (succeeded) {
             resolve();
           } else {
-            reject(new Error('Tab action failed'));
+            reject(new Error(SHIELD_ERROR.tabActionFailed));
           }
         }
       };
       this.#platform.addTabRemovedListener(onTabRemovedListener);
     });
   }
 
+  /**
+   * Poll for active subscription until one is found or timeout.
+   * This is needed because Stripe webhook may be delayed after card payment.
+   *
+   * @param interval
+   * @param timeout
+   * @returns Promise<Subscription[]> - The subscriptions when an active one is found.
+   */
+  async #pollForSubscription(
+    interval: number = SUBSCRIPTION_POLL_INTERVAL,
+    timeout: number = SUBSCRIPTION_POLL_TIMEOUT,
+  ): Promise<Subscription[]> {
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < timeout) {
+      const subscriptions = await this.#messenger.call(
+        'SubscriptionController:getSubscriptions',
+      );
+
+      if (
+        getIsShieldSubscriptionActive(subscriptions) ||
+        getIsShieldSubscriptionPaused(subscriptions)
+      ) {
+        return subscriptions;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+
+    throw new Error(SHIELD_ERROR.subscriptionPollingTimedOut);
+  }
+
   async #handleShieldSubscriptionApproveTransaction(txMeta: TransactionMeta) {
     const { isGasFeeSponsored, chainId } = txMeta;
     const bundlerSupported = await isSendBundleSupported(chainId);

shared/modules/shield/constants.ts

@@ -1,2 +1,4 @@
-export const SHIELD_SUBSCRIPTION_CARD_TAB_ACTION_ERROR_MESSAGE =
-  'tab action failed';
+export const SHIELD_ERROR = {
+  tabActionFailed: 'tab action failed',
+  subscriptionPollingTimedOut: 'subscription polling timed out',
+};

ui/hooks/subscription/useSubscription.ts

@@ -66,7 +66,7 @@ import {
   getLatestSubscriptionStatus,
   getShieldMarketingUtmParamsForMetrics,
   getUserBalanceCategory,
-  SHIELD_SUBSCRIPTION_CARD_TAB_ACTION_ERROR_MESSAGE,
+  SHIELD_ERROR,
 } from '../../../shared/modules/shield';
 import { openWindow } from '../../helpers/utils/window';
 import { SUPPORT_LINK } from '../../../shared/lib/ui-utils';
@@ -596,9 +596,7 @@ export const useHandleSubscription = ({
             e instanceof Error &&
             e.message
               .toLowerCase()
-              .includes(
-                SHIELD_SUBSCRIPTION_CARD_TAB_ACTION_ERROR_MESSAGE.toLowerCase(),
-              )
+              .includes(SHIELD_ERROR.tabActionFailed.toLowerCase())
           ) {
             // tab action failed is not api error, only log it here
             console.error('[useHandleSubscription error]:', e);