feat: add perps order notifications (#6464)

## Explanation

Adds perp order notification support.

This is technically already supported here, but moving to core will
reduce logic/complexity of setting up notifs.

https://github.com/MetaMask/metamask-mobile/blob/3428d076e871e1ab7a68978bcc2da9770c4200b7/app/components/UI/Perps/controllers/PerpsController.ts#L697

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [x] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

Author: Prithpal-Sooriya

packages/notification-services-controller/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `sendPerpPlaceOrderNotification` method to `NotificationServicesController` ([#6464](https://github.com/MetaMask/core/pull/6464))
+- Add `createPerpOrderNotification` function to invoke perp notification service ([#6464](https://github.com/MetaMask/core/pull/6464))
+- Add `perps/schema.ts` file from perp notification OpenAPI types ([#6464](https://github.com/MetaMask/core/pull/6464))
+- Add exported `OrderInput` type ([#6464](https://github.com/MetaMask/core/pull/6464))
+
 ### Changed
 
 - Bump `@metamask/base-controller` from `^8.1.0` to `^8.3.0` ([#6355](https://github.com/MetaMask/core/pull/6355), [#6465](https://github.com/MetaMask/core/pull/6465))

packages/notification-services-controller/src/NotificationServicesController/NotificationServicesController.test.ts

@@ -16,6 +16,7 @@ import {
   mockGetOnChainNotifications,
   mockFetchFeatureAnnouncementNotifications,
   mockMarkNotificationsAsRead,
+  mockCreatePerpNotification,
 } from './__fixtures__/mockServices';
 import { waitFor } from './__fixtures__/test-utils';
 import { TRIGGER_TYPES } from './constants';
@@ -38,7 +39,7 @@ import { processFeatureAnnouncement } from './processors';
 import { processNotification } from './processors/process-notifications';
 import { processSnapNotification } from './processors/process-snap-notifications';
 import { notificationsConfigCache } from './services/notification-config-cache';
-import type { INotification } from './types';
+import type { INotification, OrderInput } from './types';
 import type {
   NotificationServicesPushControllerDisablePushNotificationsAction,
   NotificationServicesPushControllerEnablePushNotificationsAction,
@@ -1159,6 +1160,82 @@ describe('metamask-notifications - disablePushNotifications', () => {
   });
 });
 
+describe('metamask-notifications - sendPerpPlaceOrderNotification()', () => {
+  const arrangeMocks = () => {
+    const messengerMocks = mockNotificationMessenger();
+    const mockCreatePerpAPI = mockCreatePerpNotification({
+      status: 200,
+      body: { success: true },
+    });
+    return { ...messengerMocks, mockCreatePerpAPI };
+  };
+
+  const mockOrderInput: OrderInput = {
+    user_id: '0x111', // User Address
+    coin: '0x222', // Asset address
+  };
+
+  it('should successfully send perp order notification when authenticated', async () => {
+    const { messenger, mockCreatePerpAPI } = arrangeMocks();
+    const controller = new NotificationServicesController({
+      messenger,
+      env: { featureAnnouncements: featureAnnouncementsEnv },
+    });
+
+    await controller.sendPerpPlaceOrderNotification(mockOrderInput);
+
+    expect(mockCreatePerpAPI.isDone()).toBe(true);
+  });
+
+  it('should handle authentication errors gracefully', async () => {
+    const mocks = arrangeMocks();
+    mocks.mockIsSignedIn.mockReturnValue(false);
+
+    const controller = new NotificationServicesController({
+      messenger: mocks.messenger,
+      env: { featureAnnouncements: featureAnnouncementsEnv },
+    });
+
+    await controller.sendPerpPlaceOrderNotification(mockOrderInput);
+
+    expect(mocks.mockCreatePerpAPI.isDone()).toBe(false);
+  });
+
+  it('should handle bearer token retrieval errors gracefully', async () => {
+    const mocks = arrangeMocks();
+    mocks.mockGetBearerToken.mockRejectedValueOnce(
+      new Error('Failed to get bearer token'),
+    );
+
+    const controller = new NotificationServicesController({
+      messenger: mocks.messenger,
+      env: { featureAnnouncements: featureAnnouncementsEnv },
+    });
+
+    await controller.sendPerpPlaceOrderNotification(mockOrderInput);
+
+    expect(mocks.mockCreatePerpAPI.isDone()).toBe(false);
+  });
+
+  it('should handle API call failures gracefully', async () => {
+    const { messenger } = mockNotificationMessenger();
+    // Mock API to fail
+    const mockCreatePerpAPI = mockCreatePerpNotification({ status: 500 });
+    const mockConsoleError = jest
+      .spyOn(console, 'error')
+      .mockImplementation(jest.fn());
+
+    const controller = new NotificationServicesController({
+      messenger,
+      env: { featureAnnouncements: featureAnnouncementsEnv },
+    });
+
+    await controller.sendPerpPlaceOrderNotification(mockOrderInput);
+    expect(mockCreatePerpAPI.isDone()).toBe(true);
+    expect(mockConsoleError).toHaveBeenCalled();
+  });
+});
+
 // Type-Computation - we are extracting args and parameters from a generic type utility
 // Thus this `AnyFunc` can be used to help constrain the generic parameters correctly
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

packages/notification-services-controller/src/NotificationServicesController/NotificationServicesController.ts

@@ -28,11 +28,13 @@ import {
 } from './processors/process-notifications';
 import * as FeatureNotifications from './services/feature-announcements';
 import * as OnChainNotifications from './services/onchain-notifications';
+import { createPerpOrderNotification } from './services/perp-notifications';
 import type {
   INotification,
   MarkAsReadNotificationsParam,
 } from './types/notification/notification';
 import type { OnChainRawNotification } from './types/on-chain-notification/on-chain-notification';
+import type { OrderInput } from './types/perps';
 import type {
   NotificationServicesPushControllerEnablePushNotificationsAction,
   NotificationServicesPushControllerDisablePushNotificationsAction,
@@ -451,6 +453,7 @@ export default class NotificationServicesController extends BaseController<
     subscribe: () => {
       this.messagingSystem.subscribe(
         'KeyringController:stateChange',
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
         async (totalAccounts, prevTotalAccounts) => {
           const hasTotalAccountsChanged = totalAccounts !== prevTotalAccounts;
           if (
@@ -1249,4 +1252,19 @@ export default class NotificationServicesController extends BaseController<
       );
     }
   }
+
+  /**
+   * Creates an perp order notification subscription.
+   * Requires notifications and auth to be enabled to start receiving this notifications
+   *
+   * @param input perp input
+   */
+  public async sendPerpPlaceOrderNotification(input: OrderInput) {
+    try {
+      const { bearerToken } = await this.#getBearerToken();
+      await createPerpOrderNotification(bearerToken, input);
+    } catch {
+      // Do Nothing
+    }
+  }
 }

packages/notification-services-controller/src/NotificationServicesController/__fixtures__/mockServices.ts

@@ -6,6 +6,7 @@ import {
   getMockFeatureAnnouncementResponse,
   getMockListNotificationsResponse,
   getMockMarkNotificationsAsReadResponse,
+  getMockCreatePerpOrderNotification,
 } from '../mocks/mockResponses';
 
 type MockReply = {
@@ -70,3 +71,13 @@ export const mockMarkNotificationsAsRead = (mockReply?: MockReply) => {
 
   return mockEndpoint;
 };
+
+export const mockCreatePerpNotification = (mockReply?: MockReply) => {
+  const mockResponse = getMockCreatePerpOrderNotification();
+  const reply = mockReply ?? { status: 201 };
+  const mockEndpoint = nock(mockResponse.url)
+    .persist()
+    .post('')
+    .reply(reply.status);
+  return mockEndpoint;
+};

packages/notification-services-controller/src/NotificationServicesController/mocks/mockResponses.ts

@@ -7,6 +7,7 @@ import {
   TRIGGER_API_NOTIFICATIONS_ENDPOINT,
   TRIGGER_API_NOTIFICATIONS_QUERY_ENDPOINT,
 } from '../services/onchain-notifications';
+import { PERPS_API_CREATE_ORDERS } from '../services/perp-notifications';
 
 type MockResponse = {
   url: string;
@@ -58,3 +59,11 @@ export const getMockMarkNotificationsAsReadResponse = () => {
     response: null,
   } satisfies MockResponse;
 };
+
+export const getMockCreatePerpOrderNotification = () => {
+  return {
+    url: PERPS_API_CREATE_ORDERS,
+    requestMethod: 'POST',
+    response: null,
+  } satisfies MockResponse;
+};

packages/notification-services-controller/src/NotificationServicesController/services/perp-notifications.test.ts

@@ -0,0 +1,46 @@
+import { createPerpOrderNotification } from './perp-notifications';
+import { mockCreatePerpNotification } from '../__fixtures__/mockServices';
+import type { OrderInput } from '../types/perps';
+
+const mockOrderInput = (): OrderInput => ({
+  user_id: '0x111', // User Address
+  coin: '0x222', // Asset address
+});
+
+const mockBearerToken = 'mock-jwt-token';
+
+describe('Perps Service - createPerpOrderNotification', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const arrangeMocks = () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, 'error')
+      .mockImplementation(jest.fn());
+
+    return { consoleErrorSpy };
+  };
+
+  it('should successfully create a perp order notification', async () => {
+    const { consoleErrorSpy } = arrangeMocks();
+    const mockEndpoint = mockCreatePerpNotification();
+    await createPerpOrderNotification(mockBearerToken, mockOrderInput());
+
+    expect(mockEndpoint.isDone()).toBe(true);
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+  });
+
+  it('should handle fetch errors gracefully', async () => {
+    const { consoleErrorSpy } = arrangeMocks();
+    const mockEndpoint = mockCreatePerpNotification({ status: 500 });
+    let numberOfRequests = 0;
+    mockEndpoint.on('request', () => (numberOfRequests += 1));
+
+    await createPerpOrderNotification(mockBearerToken, mockOrderInput());
+
+    expect(mockEndpoint.isDone()).toBe(true);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(numberOfRequests).toBe(4); // 4 requests made - 1 initial + 3 retries
+  });
+});

packages/notification-services-controller/src/NotificationServicesController/services/perp-notifications.ts

@@ -0,0 +1,36 @@
+import {
+  createServicePolicy,
+  successfulFetch,
+} from '@metamask/controller-utils';
+
+import type { OrderInput } from '../types';
+
+export const PERPS_API = 'https://perps.api.cx.metamask.io';
+export const PERPS_API_CREATE_ORDERS = `${PERPS_API}/api/v1/orders`;
+
+/**
+ * Sends a perp order to our API to create a perp order subscription
+ *
+ * @param bearerToken - JWT for authentication
+ * @param orderInput - order input shape
+ */
+export async function createPerpOrderNotification(
+  bearerToken: string,
+  orderInput: OrderInput,
+) {
+  try {
+    await createServicePolicy().execute(async () => {
+      // console.log('called');
+      return successfulFetch(PERPS_API_CREATE_ORDERS, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${bearerToken}`,
+        },
+        body: JSON.stringify(orderInput),
+      });
+    });
+  } catch (e) {
+    console.error('Failed to create perp order notification', e);
+  }
+}

packages/notification-services-controller/src/NotificationServicesController/types/index.ts

@@ -2,3 +2,4 @@ export type * from './feature-announcement';
 export type * from './notification';
 export type * from './on-chain-notification';
 export type * from './snaps/snaps';
+export type * from './perps';

packages/notification-services-controller/src/NotificationServicesController/types/perps/index.ts

@@ -0,0 +1 @@
+export type * from './perp-types';

packages/notification-services-controller/src/NotificationServicesController/types/perps/perp-types.ts

@@ -0,0 +1,3 @@
+import type { components } from './schema';
+
+export type OrderInput = components['schemas']['OrderInput'];