Merge branch 'main' into add-tx-severity-card

README.md

@@ -11,7 +11,7 @@ Build the documentation site locally using the following steps.
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) version 16+
+- [Node.js](https://nodejs.org/) version 16
 - [Yarn](https://yarnpkg.com/) version 3
 - [Git](https://git-scm.com/)
 

snaps/index.mdx

@@ -90,6 +90,12 @@ The following Snaps features are available in the stable version of MetaMask:
       href: "reference/rpc-api#snap_getlocale",
       title: "Localization",
       description: "Translate your Snap UI based on the user's locale."
+    },
+    {
+      icon: require("./assets/features/lifecycle-hooks.png").default,
+      href: "reference/permissions#endowmentlifecycle-hooks",
+      title: "Lifecycle hooks",
+      description: "Call an action when your Snap is installed or updated."
     }
   ]}
 />

snaps/reference/exports.md

@@ -270,3 +270,137 @@ module.exports.onCronjob = async ({ request }) => {
 ```
 
 <!--/tabs-->
+
+## onInstall
+
+To run an action on installation, a Snap must export `onInstall`.
+This method is called after the Snap is installed successfully. 
+
+:::note
+For MetaMask to call the Snap's `onInstall` method, you must request the
+[`endowment:lifecycle-hooks`](permissions.md#endowmentlifecycle-hooks) permission.
+:::
+
+#### Parameters
+
+None.
+
+
+#### Example
+
+<!--tabs-->
+
+# TypeScript
+
+```typescript
+import type { OnInstallHandler } from '@metamask/snaps-sdk';
+import { heading, panel, text } from '@metamask/snaps-sdk';
+
+export const onInstall: OnInstallHandler = async () => {
+  await snap.request({
+    method: 'snap_dialog',
+    params: {
+      type: 'alert',
+      content: panel([
+        heading('Thank you for installing my Snap'),
+        text(
+          'To use this Snap, visit the companion dapp at [metamask.io](https://metamask.io).',
+        ),
+      ]),
+    },
+  });
+};
+```
+
+# JavaScript
+
+```js
+import { heading, panel, text } from '@metamask/snaps-sdk';
+
+module.exports.onInstall = async () => {
+  await snap.request({
+    method: 'snap_dialog',
+    params: {
+      type: 'alert',
+      content: panel([
+        heading('Thank you for installing my Snap'),
+        text(
+          'To use this Snap, visit the companion dapp at [metamask.io](https://metamask.io).',
+        ),
+      ]),
+    },
+  });
+};
+```
+
+<!--/tabs-->
+
+## onUpdate
+
+To run an action on update, a Snap must export `onUpdate`.
+This method is called after the Snap is updated successfully. 
+
+:::note
+For MetaMask to call the Snap's `onUpdate` method, you must request the
+[`endowment:lifecycle-hooks`](permissions.md#endowmentlifecycle-hooks) permission.
+:::
+
+#### Parameters
+
+None.
+
+
+#### Example
+
+<!--tabs-->
+
+# TypeScript
+
+```typescript
+import type { OnUpdateHandler } from '@metamask/snaps-sdk';
+import { heading, panel, text } from '@metamask/snaps-sdk';
+
+export const onUpdate: OnUpdateHandler = async () => {
+  await snap.request({
+    method: 'snap_dialog',
+    params: {
+      type: 'alert',
+      content: panel([
+        heading('Thank you for updating my Snap'),
+        text(
+          'New features added in this version:',
+        ),
+        text(
+          'Added a dialog that appears when updating'
+        ), 
+      ]),
+    },
+  });
+};
+```
+
+# JavaScript
+
+```js
+import { heading, panel, text } from '@metamask/snaps-sdk';
+
+module.exports.onUpdate = async () => {
+  await snap.request({
+    method: 'snap_dialog',
+    params: {
+      type: 'alert',
+      content: panel([
+        heading('Thank you for updating my Snap'),
+        text(
+          'New features added in this version:',
+        ),
+        text(
+          'Added a dialog that appears when updating'
+        ), 
+      ]),
+    },
+  });
+};
+```
+
+<!--/tabs-->

snaps/reference/permissions.md

@@ -101,6 +101,22 @@ Specify this permission in the manifest file as follows:
 }
 ```
 
+### endowment:lifecycle-hooks
+
+To run an action when the user installs or updates the Snap, a Snap must request the `endowment:lifecycle-hooks` permission.
+This permission allows the Snap to export the 
+[`onInstall`](../reference/exports.md#oninstall) and 
+[`onUpdate`](../reference/exports.md#onupdate) 
+methods, which MetaMask calls after a successful installation or update, respectively.
+
+Specify this permission in the manifest file as follows:
+
+```json
+"initialPermissions": {
+  "endowment:lifecycle-hooks": {}
+},
+```
+
 ### endowment:network-access
 
 To access the internet, a Snap must request the `endowment:network-access` permission.