Feat: Add background events (#2941)

This PR adds a new feature: background events, per
[SIP-28](https://github.com/MetaMask/SIPs/blob/main/SIPS/sip-28.md). A
summary of the changes made:

1. The `CronjobController` was updated to now include logic for handling
and storing background events.
2. `snap_scheduleBackgroundEvent` RPC method was added to schedule an
event.
3. `snap_cancelBackgroundEvent` RPC method was added to cancel an event.
4. `snap_getBackgroundEvents` RPC method was added to get a snap's
background events (not outlined in the SIP, but will be added as an
addendum soon).

packages/examples/packages/browserify-plugin/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snaps.git"
   },
   "source": {
-    "shasum": "82KbG3cf0wtxooJpWzHeM1g4FhO8O7zSYCAAGNPshfM=",
+    "shasum": "hy0TMeQeqznNQRX2j7DnxRt1Nn5Z+v0rjaWNpe1fEWE=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

packages/examples/packages/browserify/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snaps.git"
   },
   "source": {
-    "shasum": "5LsB950haZGnl0q5K7M4XgSh5J2e0p5O1Ptl/e6kpSQ=",
+    "shasum": "VR3Zwjo0yqKLkuKHGDfS9AmuyW3KMbXSmi9Nh9JgCMw=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

packages/examples/packages/cronjobs/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snaps.git"
   },
   "source": {
-    "shasum": "E8SzmLlC0rgCn0qOop9/zCLmrWLABS5LlnaQv/MYkUc=",
+    "shasum": "6RCKkCSH+tCAKsXIzAjpaZrWjvGDXbkMcuaCslVvwr4=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",
@@ -17,6 +17,10 @@
     }
   },
   "initialPermissions": {
+    "endowment:rpc": {
+      "dapps": true,
+      "snaps": false
+    },
     "endowment:cronjob": {
       "jobs": [
         {
@@ -27,7 +31,8 @@
         }
       ]
     },
-    "snap_dialog": {}
+    "snap_dialog": {},
+    "snap_notify": {}
   },
   "platformVersion": "6.14.0",
   "manifestVersion": "0.1"

packages/examples/packages/cronjobs/src/index.ts

@@ -1,14 +1,25 @@
-import type { OnCronjobHandler } from '@metamask/snaps-sdk';
+import type {
+  OnCronjobHandler,
+  OnRpcRequestHandler,
+} from '@metamask/snaps-sdk';
 import { panel, text, heading, MethodNotFoundError } from '@metamask/snaps-sdk';
 
+import type {
+  CancelNotificationParams,
+  ScheduleNotificationParams,
+} from './types';
+
 /**
- * Handle cronjob execution requests from MetaMask. This handler handles one
- * method:
+ * Handle cronjob execution requests from MetaMask. This handler handles two
+ * methods:
  *
  * - `execute`: The JSON-RPC method that is called by MetaMask when the cronjob
  * is triggered. This method is specified in the snap manifest under the
  * `endowment:cronjob` permission. If you want to support more methods (e.g.,
  * with different times), you can add them to the manifest there.
+ * - `fireNotification`: The JSON-RPC method that is called by MetaMask when the
+ * background event is triggered. This method call is scheduled by the `scheduleNotification`
+ * method in the `onRpcRequest` handler.
  *
  * @param params - The request parameters.
  * @param params.request - The JSON-RPC request object.
@@ -29,6 +40,57 @@ export const onCronjob: OnCronjobHandler = async ({ request }) => {
           ]),
         },
       });
+    case 'fireNotification':
+      return snap.request({
+        method: 'snap_notify',
+        params: {
+          type: 'inApp',
+          message: 'Hello world!',
+        },
+      });
+    default:
+      // eslint-disable-next-line @typescript-eslint/no-throw-literal
+      throw new MethodNotFoundError({ method: request.method });
+  }
+};
+
+/**
+ * Handle incoming JSON-RPC requests from the dapp, sent through the
+ * `wallet_invokeSnap` method. This handler handles three methods:
+ *
+ * - `scheduleNotification`: Schedule a notification in the future.
+ * - `cancelNotification`: Cancel a notification.
+ * - `getBackgroundEvents`: Get the Snap's background events.
+ *
+ * @param params - The request parameters.
+ * @param params.request - The JSON-RPC request object.
+ * @returns The JSON-RPC response.
+ * @see https://docs.metamask.io/snaps/reference/exports/#onrpcrequest
+ * @see https://docs.metamask.io/snaps/reference/rpc-api/#wallet_invokesnap
+ */
+export const onRpcRequest: OnRpcRequestHandler = async ({ request }) => {
+  switch (request.method) {
+    case 'scheduleNotification':
+      return snap.request({
+        method: 'snap_scheduleBackgroundEvent',
+        params: {
+          date: (request.params as ScheduleNotificationParams).date,
+          request: {
+            method: 'fireNotification',
+          },
+        },
+      });
+    case 'cancelNotification':
+      return snap.request({
+        method: 'snap_cancelBackgroundEvent',
+        params: {
+          id: (request.params as CancelNotificationParams).id,
+        },
+      });
+    case 'getBackgroundEvents':
+      return snap.request({
+        method: 'snap_getBackgroundEvents',
+      });
     default:
       // eslint-disable-next-line @typescript-eslint/no-throw-literal
       throw new MethodNotFoundError({ method: request.method });

packages/examples/packages/cronjobs/src/types.ts

@@ -0,0 +1,17 @@
+/**
+ * The parameters for calling the `scheduleNotification` JSON-RPC method.
+ *
+ * @property date - The ISO 8601 date of when the notification should be scheduled.
+ */
+export type ScheduleNotificationParams = {
+  date: string;
+};
+
+/**
+ * The parameters for calling the `cancelNotification` JSON-RPC method.
+ *
+ * @property id - The id of the notification event to cancel.
+ */
+export type CancelNotificationParams = {
+  id: string;
+};

packages/snaps-controllers/coverage.json

@@ -1,6 +1,6 @@
 {
-  "branches": 92.96,
-  "functions": 96.71,
-  "lines": 98.01,
-  "statements": 97.71
+  "branches": 93.06,
+  "functions": 96.54,
+  "lines": 98.02,
+  "statements": 97.74
 }

packages/snaps-controllers/package.json

@@ -100,6 +100,7 @@
     "fast-deep-equal": "^3.1.3",
     "get-npm-tarball-url": "^2.0.3",
     "immer": "^9.0.6",
+    "luxon": "^3.5.0",
     "nanoid": "^3.1.31",
     "readable-stream": "^3.6.2",
     "readable-web-to-node-stream": "^3.0.2",
@@ -124,6 +125,7 @@
     "@types/concat-stream": "^2.0.0",
     "@types/gunzip-maybe": "^1.4.0",
     "@types/jest": "^27.5.1",
+    "@types/luxon": "^3",
     "@types/mocha": "^10.0.1",
     "@types/node": "18.14.2",
     "@types/readable-stream": "^4.0.15",