@metamask/snaps-rpc-methods 11.0.0 → 11.1.0

package/dist/restricted/manageState.mjs

@@ -1,20 +1,168 @@
-import {
-  STATE_ENCRYPTION_SALT,
-  STORAGE_SIZE_LIMIT,
-  getEncryptionEntropy,
-  getManageStateImplementation,
-  getValidatedParams,
-  manageStateBuilder,
-  specificationBuilder
-} from "../chunk-TE4W25CA.mjs";
-import "../chunk-W33UWNA2.mjs";
-export {
-  STATE_ENCRYPTION_SALT,
-  STORAGE_SIZE_LIMIT,
-  getEncryptionEntropy,
-  getManageStateImplementation,
-  getValidatedParams,
-  manageStateBuilder,
-  specificationBuilder
+import { PermissionType, SubjectType } from "@metamask/permission-controller";
+import { rpcErrors } from "@metamask/rpc-errors";
+import { ManageStateOperation } from "@metamask/snaps-sdk";
+import { STATE_ENCRYPTION_MAGIC_VALUE } from "@metamask/snaps-utils";
+import { isObject, getJsonSize } from "@metamask/utils";
+import { deriveEntropy } from "../utils.mjs";
+// The salt used for SIP-6-based entropy derivation.
+export const STATE_ENCRYPTION_SALT = 'snap_manageState encryption';
+const methodName = 'snap_manageState';
+/**
+ * The specification builder for the `snap_manageState` permission.
+ * `snap_manageState` lets the Snap store and manage some of its state on
+ * your device.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_manageState` permission.
+ */
+export const specificationBuilder = ({ allowedCaveats = null, methodHooks, }) => {
+    return {
+        permissionType: PermissionType.RestrictedMethod,
+        targetName: methodName,
+        allowedCaveats,
+        methodImplementation: getManageStateImplementation(methodHooks),
+        subjectTypes: [SubjectType.Snap],
+    };
 };
+const methodHooks = {
+    getUnlockPromise: true,
+    clearSnapState: true,
+    getSnapState: true,
+    updateSnapState: true,
+};
+export const manageStateBuilder = Object.freeze({
+    targetName: methodName,
+    specificationBuilder,
+    methodHooks,
+});
+export const STORAGE_SIZE_LIMIT = 104857600; // In bytes (100MB)
+/**
+ * Get a deterministic encryption key to use for encrypting and decrypting the
+ * state.
+ *
+ * This key should only be used for state encryption using `snap_manageState`.
+ * To get other encryption keys, a different salt can be used.
+ *
+ * @param args - The encryption key args.
+ * @param args.snapId - The ID of the snap to get the encryption key for.
+ * @param args.mnemonicPhrase - The mnemonic phrase to derive the encryption key
+ * from.
+ * @returns The state encryption key.
+ */
+export async function getEncryptionEntropy({ mnemonicPhrase, snapId, }) {
+    return await deriveEntropy({
+        mnemonicPhrase,
+        input: snapId,
+        salt: STATE_ENCRYPTION_SALT,
+        magic: STATE_ENCRYPTION_MAGIC_VALUE,
+    });
+}
+/**
+ * Builds the method implementation for `snap_manageState`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.clearSnapState - A function that clears the state stored for a
+ * snap.
+ * @param hooks.getSnapState - A function that fetches the persisted decrypted
+ * state for a snap.
+ * @param hooks.updateSnapState - A function that updates the state stored for a
+ * snap.
+ * @param hooks.getUnlockPromise - A function that resolves once the MetaMask
+ * extension is unlocked and prompts the user to unlock their MetaMask if it is
+ * locked.
+ * @returns The method implementation which either returns `null` for a
+ * successful state update/deletion or returns the decrypted state.
+ * @throws If the params are invalid.
+ */
+export function getManageStateImplementation({ getUnlockPromise, clearSnapState, getSnapState, updateSnapState, }) {
+    return async function manageState(options) {
+        const { params = {}, method, context: { origin }, } = options;
+        const validatedParams = getValidatedParams(params, method);
+        // If the encrypted param is undefined or null we default to true.
+        const shouldEncrypt = validatedParams.encrypted ?? true;
+        // We only need to prompt the user when the mnemonic is needed
+        // which it isn't for the clear operation or unencrypted storage.
+        if (shouldEncrypt &&
+            validatedParams.operation !== ManageStateOperation.ClearState) {
+            await getUnlockPromise(true);
+        }
+        switch (validatedParams.operation) {
+            case ManageStateOperation.ClearState:
+                clearSnapState(origin, shouldEncrypt);
+                return null;
+            case ManageStateOperation.GetState: {
+                return await getSnapState(origin, shouldEncrypt);
+            }
+            case ManageStateOperation.UpdateState: {
+                await updateSnapState(origin, validatedParams.newState, shouldEncrypt);
+                return null;
+            }
+            default:
+                throw rpcErrors.invalidParams(`Invalid ${method} operation: "${validatedParams.operation}"`);
+        }
+    };
+}
+/**
+ * Validates the manageState method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @param method - RPC method name used for debugging errors.
+ * @param storageSizeLimit - Maximum allowed size (in bytes) of a new state object.
+ * @returns The validated method parameter object.
+ */
+export function getValidatedParams(params, method, storageSizeLimit = STORAGE_SIZE_LIMIT) {
+    if (!isObject(params)) {
+        throw rpcErrors.invalidParams({
+            message: 'Expected params to be a single object.',
+        });
+    }
+    const { operation, newState, encrypted } = params;
+    if (!operation ||
+        typeof operation !== 'string' ||
+        !Object.values(ManageStateOperation).includes(operation)) {
+        throw rpcErrors.invalidParams({
+            message: 'Must specify a valid manage state "operation".',
+        });
+    }
+    if (encrypted !== undefined && typeof encrypted !== 'boolean') {
+        throw rpcErrors.invalidParams({
+            message: '"encrypted" parameter must be a boolean if specified.',
+        });
+    }
+    if (operation === ManageStateOperation.UpdateState) {
+        if (!isObject(newState)) {
+            throw rpcErrors.invalidParams({
+                message: `Invalid ${method} "updateState" parameter: The new state must be a plain object.`,
+                data: {
+                    receivedNewState: typeof newState === 'undefined' ? 'undefined' : newState,
+                },
+            });
+        }
+        let size;
+        try {
+            // `getJsonSize` will throw if the state is not JSON serializable.
+            size = getJsonSize(newState);
+        }
+        catch {
+            throw rpcErrors.invalidParams({
+                message: `Invalid ${method} "updateState" parameter: The new state must be JSON serializable.`,
+                data: {
+                    receivedNewState: typeof newState === 'undefined' ? 'undefined' : newState,
+                },
+            });
+        }
+        if (size > storageSizeLimit) {
+            throw rpcErrors.invalidParams({
+                message: `Invalid ${method} "updateState" parameter: The new state must not exceed ${storageSizeLimit} bytes in size.`,
+                data: {
+                    receivedNewState: typeof newState === 'undefined' ? 'undefined' : newState,
+                },
+            });
+        }
+    }
+    return params;
+}
 //# sourceMappingURL=manageState.mjs.map

package/dist/restricted/manageState.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"file":"manageState.mjs","sourceRoot":"","sources":["../../src/restricted/manageState.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  PermissionSpecificationBuilder,\n  RestrictedMethodOptions,\n  ValidPermissionSpecification,\n} from '@metamask/permission-controller';\nimport { PermissionType, SubjectType } from '@metamask/permission-controller';\nimport { rpcErrors } from '@metamask/rpc-errors';\nimport type { ManageStateParams, ManageStateResult } from '@metamask/snaps-sdk';\nimport { ManageStateOperation } from '@metamask/snaps-sdk';\nimport { STATE_ENCRYPTION_MAGIC_VALUE } from '@metamask/snaps-utils';\nimport type { Json, NonEmptyArray } from '@metamask/utils';\nimport { isObject, getJsonSize } from '@metamask/utils';\n\nimport type { MethodHooksObject } from '../utils';\nimport { deriveEntropy } from '../utils';\n\n// The salt used for SIP-6-based entropy derivation.\nexport const STATE_ENCRYPTION_SALT = 'snap_manageState encryption';\n\nconst methodName = 'snap_manageState';\n\nexport type ManageStateMethodHooks = {\n  /**\n   * Waits for the extension to be unlocked.\n   *\n   * @returns A promise that resolves once the extension is unlocked.\n   */\n  getUnlockPromise: (shouldShowUnlockRequest: boolean) => Promise<void>;\n\n  /**\n   * A function that clears the state of the requesting Snap.\n   */\n  clearSnapState: (snapId: string, encrypted: boolean) => void;\n\n  /**\n   * A function that gets the encrypted state of the requesting Snap.\n   *\n   * @returns The current state of the Snap.\n   */\n  getSnapState: (\n    snapId: string,\n    encrypted: boolean,\n  ) => Promise<Record<string, Json>>;\n\n  /**\n   * A function that updates the state of the requesting Snap.\n   *\n   * @param newState - The new state of the Snap.\n   */\n  updateSnapState: (\n    snapId: string,\n    newState: Record<string, Json>,\n    encrypted: boolean,\n  ) => Promise<void>;\n};\n\ntype ManageStateSpecificationBuilderOptions = {\n  allowedCaveats?: Readonly<NonEmptyArray<string>> | null;\n  methodHooks: ManageStateMethodHooks;\n};\n\ntype ManageStateSpecification = ValidPermissionSpecification<{\n  permissionType: PermissionType.RestrictedMethod;\n  targetName: typeof methodName;\n  methodImplementation: ReturnType<typeof getManageStateImplementation>;\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n}>;\n\n/**\n * The specification builder for the `snap_manageState` permission.\n * `snap_manageState` lets the Snap store and manage some of its state on\n * your device.\n *\n * @param options - The specification builder options.\n * @param options.allowedCaveats - The optional allowed caveats for the permission.\n * @param options.methodHooks - The RPC method hooks needed by the method implementation.\n * @returns The specification for the `snap_manageState` permission.\n */\nexport const specificationBuilder: PermissionSpecificationBuilder<\n  PermissionType.RestrictedMethod,\n  ManageStateSpecificationBuilderOptions,\n  ManageStateSpecification\n> = ({\n  allowedCaveats = null,\n  methodHooks,\n}: ManageStateSpecificationBuilderOptions) => {\n  return {\n    permissionType: PermissionType.RestrictedMethod,\n    targetName: methodName,\n    allowedCaveats,\n    methodImplementation: getManageStateImplementation(methodHooks),\n    subjectTypes: [SubjectType.Snap],\n  };\n};\n\nconst methodHooks: MethodHooksObject<ManageStateMethodHooks> = {\n  getUnlockPromise: true,\n  clearSnapState: true,\n  getSnapState: true,\n  updateSnapState: true,\n};\n\nexport const manageStateBuilder = Object.freeze({\n  targetName: methodName,\n  specificationBuilder,\n  methodHooks,\n} as const);\n\nexport const STORAGE_SIZE_LIMIT = 104857600; // In bytes (100MB)\n\ntype GetEncryptionKeyArgs = {\n  snapId: string;\n  mnemonicPhrase: Uint8Array;\n};\n\n/**\n * Get a deterministic encryption key to use for encrypting and decrypting the\n * state.\n *\n * This key should only be used for state encryption using `snap_manageState`.\n * To get other encryption keys, a different salt can be used.\n *\n * @param args - The encryption key args.\n * @param args.snapId - The ID of the snap to get the encryption key for.\n * @param args.mnemonicPhrase - The mnemonic phrase to derive the encryption key\n * from.\n * @returns The state encryption key.\n */\nexport async function getEncryptionEntropy({\n  mnemonicPhrase,\n  snapId,\n}: GetEncryptionKeyArgs) {\n  return await deriveEntropy({\n    mnemonicPhrase,\n    input: snapId,\n    salt: STATE_ENCRYPTION_SALT,\n    magic: STATE_ENCRYPTION_MAGIC_VALUE,\n  });\n}\n\n/**\n * Builds the method implementation for `snap_manageState`.\n *\n * @param hooks - The RPC method hooks.\n * @param hooks.clearSnapState - A function that clears the state stored for a\n * snap.\n * @param hooks.getSnapState - A function that fetches the persisted decrypted\n * state for a snap.\n * @param hooks.updateSnapState - A function that updates the state stored for a\n * snap.\n * @param hooks.getUnlockPromise - A function that resolves once the MetaMask\n * extension is unlocked and prompts the user to unlock their MetaMask if it is\n * locked.\n * @returns The method implementation which either returns `null` for a\n * successful state update/deletion or returns the decrypted state.\n * @throws If the params are invalid.\n */\nexport function getManageStateImplementation({\n  getUnlockPromise,\n  clearSnapState,\n  getSnapState,\n  updateSnapState,\n}: ManageStateMethodHooks) {\n  return async function manageState(\n    options: RestrictedMethodOptions<ManageStateParams>,\n  ): Promise<ManageStateResult> {\n    const {\n      params = {},\n      method,\n      context: { origin },\n    } = options;\n    const validatedParams = getValidatedParams(params, method);\n\n    // If the encrypted param is undefined or null we default to true.\n    const shouldEncrypt = validatedParams.encrypted ?? true;\n\n    // We only need to prompt the user when the mnemonic is needed\n    // which it isn't for the clear operation or unencrypted storage.\n    if (\n      shouldEncrypt &&\n      validatedParams.operation !== ManageStateOperation.ClearState\n    ) {\n      await getUnlockPromise(true);\n    }\n\n    switch (validatedParams.operation) {\n      case ManageStateOperation.ClearState:\n        clearSnapState(origin, shouldEncrypt);\n        return null;\n\n      case ManageStateOperation.GetState: {\n        return await getSnapState(origin, shouldEncrypt);\n      }\n\n      case ManageStateOperation.UpdateState: {\n        await updateSnapState(origin, validatedParams.newState, shouldEncrypt);\n        return null;\n      }\n\n      default:\n        throw rpcErrors.invalidParams(\n          `Invalid ${method} operation: \"${\n            validatedParams.operation as string\n          }\"`,\n        );\n    }\n  };\n}\n\n/**\n * Validates the manageState method `params` and returns them cast to the correct\n * type. Throws if validation fails.\n *\n * @param params - The unvalidated params object from the method request.\n * @param method - RPC method name used for debugging errors.\n * @param storageSizeLimit - Maximum allowed size (in bytes) of a new state object.\n * @returns The validated method parameter object.\n */\nexport function getValidatedParams(\n  params: unknown,\n  method: string,\n  storageSizeLimit = STORAGE_SIZE_LIMIT,\n): ManageStateParams {\n  if (!isObject(params)) {\n    throw rpcErrors.invalidParams({\n      message: 'Expected params to be a single object.',\n    });\n  }\n\n  const { operation, newState, encrypted } = params;\n\n  if (\n    !operation ||\n    typeof operation !== 'string' ||\n    !Object.values(ManageStateOperation).includes(\n      operation as ManageStateOperation,\n    )\n  ) {\n    throw rpcErrors.invalidParams({\n      message: 'Must specify a valid manage state \"operation\".',\n    });\n  }\n\n  if (encrypted !== undefined && typeof encrypted !== 'boolean') {\n    throw rpcErrors.invalidParams({\n      message: '\"encrypted\" parameter must be a boolean if specified.',\n    });\n  }\n\n  if (operation === ManageStateOperation.UpdateState) {\n    if (!isObject(newState)) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid ${method} \"updateState\" parameter: The new state must be a plain object.`,\n        data: {\n          receivedNewState:\n            typeof newState === 'undefined' ? 'undefined' : newState,\n        },\n      });\n    }\n\n    let size;\n    try {\n      // `getJsonSize` will throw if the state is not JSON serializable.\n      size = getJsonSize(newState);\n    } catch {\n      throw rpcErrors.invalidParams({\n        message: `Invalid ${method} \"updateState\" parameter: The new state must be JSON serializable.`,\n        data: {\n          receivedNewState:\n            typeof newState === 'undefined' ? 'undefined' : newState,\n        },\n      });\n    }\n\n    if (size > storageSizeLimit) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid ${method} \"updateState\" parameter: The new state must not exceed ${storageSizeLimit} bytes in size.`,\n        data: {\n          receivedNewState:\n            typeof newState === 'undefined' ? 'undefined' : newState,\n        },\n      });\n    }\n  }\n\n  return params as ManageStateParams;\n}\n"]}

package/dist/restricted/notify.cjs

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidatedParams = exports.getImplementation = exports.notifyBuilder = exports.specificationBuilder = void 0;
+const permission_controller_1 = require("@metamask/permission-controller");
+const rpc_errors_1 = require("@metamask/rpc-errors");
+const snaps_sdk_1 = require("@metamask/snaps-sdk");
+const snaps_utils_1 = require("@metamask/snaps-utils");
+const utils_1 = require("@metamask/utils");
+const methodName = 'snap_notify';
+/**
+ * The specification builder for the `snap_notify` permission.
+ * `snap_notify` allows snaps to send multiple types of notifications to its users.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_notify` permission.
+ */
+const specificationBuilder = ({ allowedCaveats = null, methodHooks }) => {
+    return {
+        permissionType: permission_controller_1.PermissionType.RestrictedMethod,
+        targetName: methodName,
+        allowedCaveats,
+        methodImplementation: getImplementation(methodHooks),
+        subjectTypes: [permission_controller_1.SubjectType.Snap],
+    };
+};
+exports.specificationBuilder = specificationBuilder;
+const methodHooks = {
+    showNativeNotification: true,
+    showInAppNotification: true,
+    isOnPhishingList: true,
+    maybeUpdatePhishingList: true,
+};
+exports.notifyBuilder = Object.freeze({
+    targetName: methodName,
+    specificationBuilder: exports.specificationBuilder,
+    methodHooks,
+});
+/**
+ * Builds the method implementation for `snap_notify`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.showNativeNotification - A function that shows a native browser notification.
+ * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.
+ * @param hooks.isOnPhishingList - A function that checks for links against the phishing list.
+ * @param hooks.maybeUpdatePhishingList - A function that updates the phishing list if needed.
+ * @returns The method implementation which returns `null` on success.
+ * @throws If the params are invalid.
+ */
+function getImplementation({ showNativeNotification, showInAppNotification, isOnPhishingList, maybeUpdatePhishingList, }) {
+    return async function implementation(args) {
+        const { params, context: { origin }, } = args;
+        const validatedParams = getValidatedParams(params);
+        await maybeUpdatePhishingList();
+        (0, snaps_utils_1.validateTextLinks)(validatedParams.message, isOnPhishingList);
+        switch (validatedParams.type) {
+            case snaps_sdk_1.NotificationType.Native:
+                return await showNativeNotification(origin, validatedParams);
+            case snaps_sdk_1.NotificationType.InApp:
+                return await showInAppNotification(origin, validatedParams);
+            default:
+                throw rpc_errors_1.rpcErrors.invalidParams({
+                    message: 'Must specify a valid notification "type".',
+                });
+        }
+    };
+}
+exports.getImplementation = getImplementation;
+/**
+ * Validates the notify method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @returns The validated method parameter object.
+ */
+function getValidatedParams(params) {
+    if (!(0, utils_1.isObject)(params)) {
+        throw rpc_errors_1.rpcErrors.invalidParams({
+            message: 'Expected params to be a single object.',
+        });
+    }
+    const { type, message } = params;
+    if (!type ||
+        typeof type !== 'string' ||
+        !Object.values(snaps_sdk_1.NotificationType).includes(type)) {
+        throw rpc_errors_1.rpcErrors.invalidParams({
+            message: 'Must specify a valid notification "type".',
+        });
+    }
+    const isNotString = !message || typeof message !== 'string';
+    // Set to the max message length on a Mac notification for now.
+    if (type === snaps_sdk_1.NotificationType.Native &&
+        (isNotString || message.length >= 50)) {
+        throw rpc_errors_1.rpcErrors.invalidParams({
+            message: 'Must specify a non-empty string "message" less than 50 characters long.',
+        });
+    }
+    if (type === snaps_sdk_1.NotificationType.InApp &&
+        (isNotString || message.length >= 500)) {
+        throw rpc_errors_1.rpcErrors.invalidParams({
+            message: 'Must specify a non-empty string "message" less than 500 characters long.',
+        });
+    }
+    return params;
+}
+exports.getValidatedParams = getValidatedParams;
+//# sourceMappingURL=notify.cjs.map

package/dist/restricted/notify.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.cjs","sourceRoot":"","sources":["../../src/restricted/notify.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  PermissionSpecificationBuilder,\n  RestrictedMethodOptions,\n  ValidPermissionSpecification,\n} from '@metamask/permission-controller';\nimport { PermissionType, SubjectType } from '@metamask/permission-controller';\nimport { rpcErrors } from '@metamask/rpc-errors';\nimport { NotificationType } from '@metamask/snaps-sdk';\nimport type {\n  NotifyParams,\n  NotifyResult,\n  EnumToUnion,\n} from '@metamask/snaps-sdk';\nimport { validateTextLinks } from '@metamask/snaps-utils';\nimport type { NonEmptyArray } from '@metamask/utils';\nimport { isObject } from '@metamask/utils';\n\nimport { type MethodHooksObject } from '../utils';\n\nconst methodName = 'snap_notify';\n\nexport type NotificationArgs = {\n  /**\n   * Enum type to determine notification type.\n   */\n  type: EnumToUnion<NotificationType>;\n\n  /**\n   * A message to show on the notification.\n   */\n  message: string;\n};\n\nexport type NotifyMethodHooks = {\n  /**\n   * @param snapId - The ID of the Snap that created the notification.\n   * @param args - The notification arguments.\n   */\n  showNativeNotification: (\n    snapId: string,\n    args: NotificationArgs,\n  ) => Promise<null>;\n\n  /**\n   * @param snapId - The ID of the Snap that created the notification.\n   * @param args - The notification arguments.\n   */\n  showInAppNotification: (\n    snapId: string,\n    args: NotificationArgs,\n  ) => Promise<null>;\n\n  isOnPhishingList: (url: string) => boolean;\n\n  maybeUpdatePhishingList: () => Promise<void>;\n};\n\ntype SpecificationBuilderOptions = {\n  allowedCaveats?: Readonly<NonEmptyArray<string>> | null;\n  methodHooks: NotifyMethodHooks;\n};\n\ntype Specification = ValidPermissionSpecification<{\n  permissionType: PermissionType.RestrictedMethod;\n  targetName: typeof methodName;\n  methodImplementation: ReturnType<typeof getImplementation>;\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n}>;\n\n/**\n * The specification builder for the `snap_notify` permission.\n * `snap_notify` allows snaps to send multiple types of notifications to its users.\n *\n * @param options - The specification builder options.\n * @param options.allowedCaveats - The optional allowed caveats for the permission.\n * @param options.methodHooks - The RPC method hooks needed by the method implementation.\n * @returns The specification for the `snap_notify` permission.\n */\nexport const specificationBuilder: PermissionSpecificationBuilder<\n  PermissionType.RestrictedMethod,\n  SpecificationBuilderOptions,\n  Specification\n> = ({ allowedCaveats = null, methodHooks }: SpecificationBuilderOptions) => {\n  return {\n    permissionType: PermissionType.RestrictedMethod,\n    targetName: methodName,\n    allowedCaveats,\n    methodImplementation: getImplementation(methodHooks),\n    subjectTypes: [SubjectType.Snap],\n  };\n};\n\nconst methodHooks: MethodHooksObject<NotifyMethodHooks> = {\n  showNativeNotification: true,\n  showInAppNotification: true,\n  isOnPhishingList: true,\n  maybeUpdatePhishingList: true,\n};\n\nexport const notifyBuilder = Object.freeze({\n  targetName: methodName,\n  specificationBuilder,\n  methodHooks,\n} as const);\n\n/**\n * Builds the method implementation for `snap_notify`.\n *\n * @param hooks - The RPC method hooks.\n * @param hooks.showNativeNotification - A function that shows a native browser notification.\n * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.\n * @param hooks.isOnPhishingList - A function that checks for links against the phishing list.\n * @param hooks.maybeUpdatePhishingList - A function that updates the phishing list if needed.\n * @returns The method implementation which returns `null` on success.\n * @throws If the params are invalid.\n */\nexport function getImplementation({\n  showNativeNotification,\n  showInAppNotification,\n  isOnPhishingList,\n  maybeUpdatePhishingList,\n}: NotifyMethodHooks) {\n  return async function implementation(\n    args: RestrictedMethodOptions<NotifyParams>,\n  ): Promise<NotifyResult> {\n    const {\n      params,\n      context: { origin },\n    } = args;\n\n    const validatedParams = getValidatedParams(params);\n\n    await maybeUpdatePhishingList();\n\n    validateTextLinks(validatedParams.message, isOnPhishingList);\n\n    switch (validatedParams.type) {\n      case NotificationType.Native:\n        return await showNativeNotification(origin, validatedParams);\n      case NotificationType.InApp:\n        return await showInAppNotification(origin, validatedParams);\n      default:\n        throw rpcErrors.invalidParams({\n          message: 'Must specify a valid notification \"type\".',\n        });\n    }\n  };\n}\n\n/**\n * Validates the notify method `params` and returns them cast to the correct\n * type. Throws if validation fails.\n *\n * @param params - The unvalidated params object from the method request.\n * @returns The validated method parameter object.\n */\nexport function getValidatedParams(params: unknown): NotifyParams {\n  if (!isObject(params)) {\n    throw rpcErrors.invalidParams({\n      message: 'Expected params to be a single object.',\n    });\n  }\n\n  const { type, message } = params;\n\n  if (\n    !type ||\n    typeof type !== 'string' ||\n    !Object.values(NotificationType).includes(type as NotificationType)\n  ) {\n    throw rpcErrors.invalidParams({\n      message: 'Must specify a valid notification \"type\".',\n    });\n  }\n\n  const isNotString = !message || typeof message !== 'string';\n  // Set to the max message length on a Mac notification for now.\n  if (\n    type === NotificationType.Native &&\n    (isNotString || message.length >= 50)\n  ) {\n    throw rpcErrors.invalidParams({\n      message:\n        'Must specify a non-empty string \"message\" less than 50 characters long.',\n    });\n  }\n\n  if (\n    type === NotificationType.InApp &&\n    (isNotString || message.length >= 500)\n  ) {\n    throw rpcErrors.invalidParams({\n      message:\n        'Must specify a non-empty string \"message\" less than 500 characters long.',\n    });\n  }\n\n  return params as NotificationArgs;\n}\n"]}

package/dist/{types/restricted/notify.d.ts → restricted/notify.d.cts}

@@ -1,9 +1,9 @@
-import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from '@metamask/permission-controller';
-import { PermissionType } from '@metamask/permission-controller';
-import { NotificationType } from '@metamask/snaps-sdk';
-import type { NotifyParams, NotifyResult, EnumToUnion } from '@metamask/snaps-sdk';
-import type { NonEmptyArray } from '@metamask/utils';
-import { type MethodHooksObject } from '../utils';
+import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from "@metamask/permission-controller";
+import { PermissionType } from "@metamask/permission-controller";
+import { NotificationType } from "@metamask/snaps-sdk";
+import type { NotifyParams, NotifyResult, EnumToUnion } from "@metamask/snaps-sdk";
+import type { NonEmptyArray } from "@metamask/utils";
+import { type MethodHooksObject } from "../utils.cjs";
 declare const methodName = "snap_notify";
 export type NotificationArgs = {
     /**
@@ -80,3 +80,4 @@ export declare function getImplementation({ showNativeNotification, showInAppNot
  */
 export declare function getValidatedParams(params: unknown): NotifyParams;
 export {};
+//# sourceMappingURL=notify.d.cts.map

package/dist/restricted/notify.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.cts","sourceRoot":"","sources":["../../src/restricted/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,EAC7B,wCAAwC;AACzC,OAAO,EAAE,cAAc,EAAe,wCAAwC;AAE9E,OAAO,EAAE,gBAAgB,EAAE,4BAA4B;AACvD,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,4BAA4B;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB;AAGrD,OAAO,EAAE,KAAK,iBAAiB,EAAE,qBAAiB;AAElD,QAAA,MAAM,UAAU,gBAAgB,CAAC;AAEjC,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAEpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,sBAAsB,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;OAGG;IACH,qBAAqB,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAE3C,uBAAuB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,cAAc,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;IACxD,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,KAAK,aAAa,GAAG,4BAA4B,CAAC;IAChD,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC;IAChD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,oBAAoB,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;IAC3D,cAAc,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;CACxD,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,8BAA8B,CAC/D,cAAc,CAAC,gBAAgB,EAC/B,2BAA2B,EAC3B,aAAa,CASd,CAAC;AASF,eAAO,MAAM,aAAa;;;wBApCR,eAAe,gBAAgB;oBACnC,iBAAiB;8BACP,WAAW,wBAAwB,CAAC;wBAC1C,SAAS,cAAc,MAAM,CAAC,CAAC,GAAG,IAAI;;;EAqC7C,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,GACxB,EAAE,iBAAiB,UAEV,wBAAwB,YAAY,CAAC,KAC1C,QAAQ,YAAY,CAAC,CAuBzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CA0ChE"}

package/dist/restricted/notify.d.mts

@@ -0,0 +1,83 @@
+import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from "@metamask/permission-controller";
+import { PermissionType } from "@metamask/permission-controller";
+import { NotificationType } from "@metamask/snaps-sdk";
+import type { NotifyParams, NotifyResult, EnumToUnion } from "@metamask/snaps-sdk";
+import type { NonEmptyArray } from "@metamask/utils";
+import { type MethodHooksObject } from "../utils.mjs";
+declare const methodName = "snap_notify";
+export type NotificationArgs = {
+    /**
+     * Enum type to determine notification type.
+     */
+    type: EnumToUnion<NotificationType>;
+    /**
+     * A message to show on the notification.
+     */
+    message: string;
+};
+export type NotifyMethodHooks = {
+    /**
+     * @param snapId - The ID of the Snap that created the notification.
+     * @param args - The notification arguments.
+     */
+    showNativeNotification: (snapId: string, args: NotificationArgs) => Promise<null>;
+    /**
+     * @param snapId - The ID of the Snap that created the notification.
+     * @param args - The notification arguments.
+     */
+    showInAppNotification: (snapId: string, args: NotificationArgs) => Promise<null>;
+    isOnPhishingList: (url: string) => boolean;
+    maybeUpdatePhishingList: () => Promise<void>;
+};
+type SpecificationBuilderOptions = {
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    methodHooks: NotifyMethodHooks;
+};
+type Specification = ValidPermissionSpecification<{
+    permissionType: PermissionType.RestrictedMethod;
+    targetName: typeof methodName;
+    methodImplementation: ReturnType<typeof getImplementation>;
+    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+}>;
+/**
+ * The specification builder for the `snap_notify` permission.
+ * `snap_notify` allows snaps to send multiple types of notifications to its users.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_notify` permission.
+ */
+export declare const specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, SpecificationBuilderOptions, Specification>;
+export declare const notifyBuilder: Readonly<{
+    readonly targetName: "snap_notify";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, SpecificationBuilderOptions, {
+        permissionType: PermissionType.RestrictedMethod;
+        targetName: typeof methodName;
+        methodImplementation: ReturnType<typeof getImplementation>;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+    readonly methodHooks: MethodHooksObject<NotifyMethodHooks>;
+}>;
+/**
+ * Builds the method implementation for `snap_notify`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.showNativeNotification - A function that shows a native browser notification.
+ * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.
+ * @param hooks.isOnPhishingList - A function that checks for links against the phishing list.
+ * @param hooks.maybeUpdatePhishingList - A function that updates the phishing list if needed.
+ * @returns The method implementation which returns `null` on success.
+ * @throws If the params are invalid.
+ */
+export declare function getImplementation({ showNativeNotification, showInAppNotification, isOnPhishingList, maybeUpdatePhishingList, }: NotifyMethodHooks): (args: RestrictedMethodOptions<NotifyParams>) => Promise<NotifyResult>;
+/**
+ * Validates the notify method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @returns The validated method parameter object.
+ */
+export declare function getValidatedParams(params: unknown): NotifyParams;
+export {};
+//# sourceMappingURL=notify.d.mts.map

package/dist/restricted/notify.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.mts","sourceRoot":"","sources":["../../src/restricted/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,EAC7B,wCAAwC;AACzC,OAAO,EAAE,cAAc,EAAe,wCAAwC;AAE9E,OAAO,EAAE,gBAAgB,EAAE,4BAA4B;AACvD,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACZ,4BAA4B;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB;AAGrD,OAAO,EAAE,KAAK,iBAAiB,EAAE,qBAAiB;AAElD,QAAA,MAAM,UAAU,gBAAgB,CAAC;AAEjC,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IAEpC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,sBAAsB,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;OAGG;IACH,qBAAqB,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,gBAAgB,KACnB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAE3C,uBAAuB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,cAAc,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;IACxD,WAAW,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF,KAAK,aAAa,GAAG,4BAA4B,CAAC;IAChD,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC;IAChD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,oBAAoB,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;IAC3D,cAAc,EAAE,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;CACxD,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,8BAA8B,CAC/D,cAAc,CAAC,gBAAgB,EAC/B,2BAA2B,EAC3B,aAAa,CASd,CAAC;AASF,eAAO,MAAM,aAAa;;;wBApCR,eAAe,gBAAgB;oBACnC,iBAAiB;8BACP,WAAW,wBAAwB,CAAC;wBAC1C,SAAS,cAAc,MAAM,CAAC,CAAC,GAAG,IAAI;;;EAqC7C,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,GACxB,EAAE,iBAAiB,UAEV,wBAAwB,YAAY,CAAC,KAC1C,QAAQ,YAAY,CAAC,CAuBzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,CA0ChE"}

package/dist/restricted/notify.mjs

@@ -1,13 +1,102 @@
-import {
-  getImplementation,
-  getValidatedParams,
-  notifyBuilder,
-  specificationBuilder
-} from "../chunk-JWDQUKKU.mjs";
-export {
-  getImplementation,
-  getValidatedParams,
-  notifyBuilder,
-  specificationBuilder
+import { PermissionType, SubjectType } from "@metamask/permission-controller";
+import { rpcErrors } from "@metamask/rpc-errors";
+import { NotificationType } from "@metamask/snaps-sdk";
+import { validateTextLinks } from "@metamask/snaps-utils";
+import { isObject } from "@metamask/utils";
+const methodName = 'snap_notify';
+/**
+ * The specification builder for the `snap_notify` permission.
+ * `snap_notify` allows snaps to send multiple types of notifications to its users.
+ *
+ * @param options - The specification builder options.
+ * @param options.allowedCaveats - The optional allowed caveats for the permission.
+ * @param options.methodHooks - The RPC method hooks needed by the method implementation.
+ * @returns The specification for the `snap_notify` permission.
+ */
+export const specificationBuilder = ({ allowedCaveats = null, methodHooks }) => {
+    return {
+        permissionType: PermissionType.RestrictedMethod,
+        targetName: methodName,
+        allowedCaveats,
+        methodImplementation: getImplementation(methodHooks),
+        subjectTypes: [SubjectType.Snap],
+    };
 };
+const methodHooks = {
+    showNativeNotification: true,
+    showInAppNotification: true,
+    isOnPhishingList: true,
+    maybeUpdatePhishingList: true,
+};
+export const notifyBuilder = Object.freeze({
+    targetName: methodName,
+    specificationBuilder,
+    methodHooks,
+});
+/**
+ * Builds the method implementation for `snap_notify`.
+ *
+ * @param hooks - The RPC method hooks.
+ * @param hooks.showNativeNotification - A function that shows a native browser notification.
+ * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.
+ * @param hooks.isOnPhishingList - A function that checks for links against the phishing list.
+ * @param hooks.maybeUpdatePhishingList - A function that updates the phishing list if needed.
+ * @returns The method implementation which returns `null` on success.
+ * @throws If the params are invalid.
+ */
+export function getImplementation({ showNativeNotification, showInAppNotification, isOnPhishingList, maybeUpdatePhishingList, }) {
+    return async function implementation(args) {
+        const { params, context: { origin }, } = args;
+        const validatedParams = getValidatedParams(params);
+        await maybeUpdatePhishingList();
+        validateTextLinks(validatedParams.message, isOnPhishingList);
+        switch (validatedParams.type) {
+            case NotificationType.Native:
+                return await showNativeNotification(origin, validatedParams);
+            case NotificationType.InApp:
+                return await showInAppNotification(origin, validatedParams);
+            default:
+                throw rpcErrors.invalidParams({
+                    message: 'Must specify a valid notification "type".',
+                });
+        }
+    };
+}
+/**
+ * Validates the notify method `params` and returns them cast to the correct
+ * type. Throws if validation fails.
+ *
+ * @param params - The unvalidated params object from the method request.
+ * @returns The validated method parameter object.
+ */
+export function getValidatedParams(params) {
+    if (!isObject(params)) {
+        throw rpcErrors.invalidParams({
+            message: 'Expected params to be a single object.',
+        });
+    }
+    const { type, message } = params;
+    if (!type ||
+        typeof type !== 'string' ||
+        !Object.values(NotificationType).includes(type)) {
+        throw rpcErrors.invalidParams({
+            message: 'Must specify a valid notification "type".',
+        });
+    }
+    const isNotString = !message || typeof message !== 'string';
+    // Set to the max message length on a Mac notification for now.
+    if (type === NotificationType.Native &&
+        (isNotString || message.length >= 50)) {
+        throw rpcErrors.invalidParams({
+            message: 'Must specify a non-empty string "message" less than 50 characters long.',
+        });
+    }
+    if (type === NotificationType.InApp &&
+        (isNotString || message.length >= 500)) {
+        throw rpcErrors.invalidParams({
+            message: 'Must specify a non-empty string "message" less than 500 characters long.',
+        });
+    }
+    return params;
+}
 //# sourceMappingURL=notify.mjs.map

package/dist/restricted/notify.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"file":"notify.mjs","sourceRoot":"","sources":["../../src/restricted/notify.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  PermissionSpecificationBuilder,\n  RestrictedMethodOptions,\n  ValidPermissionSpecification,\n} from '@metamask/permission-controller';\nimport { PermissionType, SubjectType } from '@metamask/permission-controller';\nimport { rpcErrors } from '@metamask/rpc-errors';\nimport { NotificationType } from '@metamask/snaps-sdk';\nimport type {\n  NotifyParams,\n  NotifyResult,\n  EnumToUnion,\n} from '@metamask/snaps-sdk';\nimport { validateTextLinks } from '@metamask/snaps-utils';\nimport type { NonEmptyArray } from '@metamask/utils';\nimport { isObject } from '@metamask/utils';\n\nimport { type MethodHooksObject } from '../utils';\n\nconst methodName = 'snap_notify';\n\nexport type NotificationArgs = {\n  /**\n   * Enum type to determine notification type.\n   */\n  type: EnumToUnion<NotificationType>;\n\n  /**\n   * A message to show on the notification.\n   */\n  message: string;\n};\n\nexport type NotifyMethodHooks = {\n  /**\n   * @param snapId - The ID of the Snap that created the notification.\n   * @param args - The notification arguments.\n   */\n  showNativeNotification: (\n    snapId: string,\n    args: NotificationArgs,\n  ) => Promise<null>;\n\n  /**\n   * @param snapId - The ID of the Snap that created the notification.\n   * @param args - The notification arguments.\n   */\n  showInAppNotification: (\n    snapId: string,\n    args: NotificationArgs,\n  ) => Promise<null>;\n\n  isOnPhishingList: (url: string) => boolean;\n\n  maybeUpdatePhishingList: () => Promise<void>;\n};\n\ntype SpecificationBuilderOptions = {\n  allowedCaveats?: Readonly<NonEmptyArray<string>> | null;\n  methodHooks: NotifyMethodHooks;\n};\n\ntype Specification = ValidPermissionSpecification<{\n  permissionType: PermissionType.RestrictedMethod;\n  targetName: typeof methodName;\n  methodImplementation: ReturnType<typeof getImplementation>;\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n}>;\n\n/**\n * The specification builder for the `snap_notify` permission.\n * `snap_notify` allows snaps to send multiple types of notifications to its users.\n *\n * @param options - The specification builder options.\n * @param options.allowedCaveats - The optional allowed caveats for the permission.\n * @param options.methodHooks - The RPC method hooks needed by the method implementation.\n * @returns The specification for the `snap_notify` permission.\n */\nexport const specificationBuilder: PermissionSpecificationBuilder<\n  PermissionType.RestrictedMethod,\n  SpecificationBuilderOptions,\n  Specification\n> = ({ allowedCaveats = null, methodHooks }: SpecificationBuilderOptions) => {\n  return {\n    permissionType: PermissionType.RestrictedMethod,\n    targetName: methodName,\n    allowedCaveats,\n    methodImplementation: getImplementation(methodHooks),\n    subjectTypes: [SubjectType.Snap],\n  };\n};\n\nconst methodHooks: MethodHooksObject<NotifyMethodHooks> = {\n  showNativeNotification: true,\n  showInAppNotification: true,\n  isOnPhishingList: true,\n  maybeUpdatePhishingList: true,\n};\n\nexport const notifyBuilder = Object.freeze({\n  targetName: methodName,\n  specificationBuilder,\n  methodHooks,\n} as const);\n\n/**\n * Builds the method implementation for `snap_notify`.\n *\n * @param hooks - The RPC method hooks.\n * @param hooks.showNativeNotification - A function that shows a native browser notification.\n * @param hooks.showInAppNotification - A function that shows a notification in the MetaMask UI.\n * @param hooks.isOnPhishingList - A function that checks for links against the phishing list.\n * @param hooks.maybeUpdatePhishingList - A function that updates the phishing list if needed.\n * @returns The method implementation which returns `null` on success.\n * @throws If the params are invalid.\n */\nexport function getImplementation({\n  showNativeNotification,\n  showInAppNotification,\n  isOnPhishingList,\n  maybeUpdatePhishingList,\n}: NotifyMethodHooks) {\n  return async function implementation(\n    args: RestrictedMethodOptions<NotifyParams>,\n  ): Promise<NotifyResult> {\n    const {\n      params,\n      context: { origin },\n    } = args;\n\n    const validatedParams = getValidatedParams(params);\n\n    await maybeUpdatePhishingList();\n\n    validateTextLinks(validatedParams.message, isOnPhishingList);\n\n    switch (validatedParams.type) {\n      case NotificationType.Native:\n        return await showNativeNotification(origin, validatedParams);\n      case NotificationType.InApp:\n        return await showInAppNotification(origin, validatedParams);\n      default:\n        throw rpcErrors.invalidParams({\n          message: 'Must specify a valid notification \"type\".',\n        });\n    }\n  };\n}\n\n/**\n * Validates the notify method `params` and returns them cast to the correct\n * type. Throws if validation fails.\n *\n * @param params - The unvalidated params object from the method request.\n * @returns The validated method parameter object.\n */\nexport function getValidatedParams(params: unknown): NotifyParams {\n  if (!isObject(params)) {\n    throw rpcErrors.invalidParams({\n      message: 'Expected params to be a single object.',\n    });\n  }\n\n  const { type, message } = params;\n\n  if (\n    !type ||\n    typeof type !== 'string' ||\n    !Object.values(NotificationType).includes(type as NotificationType)\n  ) {\n    throw rpcErrors.invalidParams({\n      message: 'Must specify a valid notification \"type\".',\n    });\n  }\n\n  const isNotString = !message || typeof message !== 'string';\n  // Set to the max message length on a Mac notification for now.\n  if (\n    type === NotificationType.Native &&\n    (isNotString || message.length >= 50)\n  ) {\n    throw rpcErrors.invalidParams({\n      message:\n        'Must specify a non-empty string \"message\" less than 50 characters long.',\n    });\n  }\n\n  if (\n    type === NotificationType.InApp &&\n    (isNotString || message.length >= 500)\n  ) {\n    throw rpcErrors.invalidParams({\n      message:\n        'Must specify a non-empty string \"message\" less than 500 characters long.',\n    });\n  }\n\n  return params as NotificationArgs;\n}\n"]}