@metamask/snaps-utils 3.2.0 → 4.0.0

package/dist/types/handlers.d.ts

@@ -1,8 +1,7 @@
-import type { Json, JsonRpcParams, JsonRpcRequest } from '@metamask/utils';
-import type { Infer } from 'superstruct';
+import type { OnCronjobHandler, OnHomePageHandler, OnKeyringRequestHandler, OnNameLookupHandler, OnRpcRequestHandler, OnTransactionHandler } from '@metamask/snaps-sdk';
+import { SeverityLevel } from '@metamask/snaps-sdk';
 import type { SnapHandler } from './handler-types';
 import { HandlerType } from './handler-types';
-import type { AccountAddress, Caip2ChainId } from './namespace';
 export declare type SnapRpcHookArgs = {
     origin: string;
     handler: HandlerType;
@@ -12,7 +11,7 @@ export declare const SNAP_EXPORTS: {
     readonly onRpcRequest: {
         readonly type: HandlerType.OnRpcRequest;
         readonly required: true;
-        readonly validator: (snapExport: unknown) => snapExport is OnRpcRequestHandler<JsonRpcParams>;
+        readonly validator: (snapExport: unknown) => snapExport is OnRpcRequestHandler<import("@metamask/snaps-sdk").JsonRpcParams>;
     };
     readonly onTransaction: {
         readonly type: HandlerType.OnTransaction;
@@ -22,7 +21,7 @@ export declare const SNAP_EXPORTS: {
     readonly onCronjob: {
         readonly type: HandlerType.OnCronjob;
         readonly required: true;
-        readonly validator: (snapExport: unknown) => snapExport is OnCronjobHandler<JsonRpcParams>;
+        readonly validator: (snapExport: unknown) => snapExport is OnCronjobHandler<import("@metamask/snaps-sdk").JsonRpcParams>;
     };
     readonly onNameLookup: {
         readonly type: HandlerType.OnNameLookup;
@@ -32,190 +31,112 @@ export declare const SNAP_EXPORTS: {
     readonly onInstall: {
         readonly type: HandlerType.OnInstall;
         readonly required: false;
-        readonly validator: (snapExport: unknown) => snapExport is LifecycleEventHandler;
+        readonly validator: (snapExport: unknown) => snapExport is import("@metamask/snaps-sdk").LifecycleEventHandler;
     };
     readonly onUpdate: {
         readonly type: HandlerType.OnUpdate;
         readonly required: false;
-        readonly validator: (snapExport: unknown) => snapExport is LifecycleEventHandler;
+        readonly validator: (snapExport: unknown) => snapExport is import("@metamask/snaps-sdk").LifecycleEventHandler;
     };
     readonly onKeyringRequest: {
         readonly type: HandlerType.OnKeyringRequest;
         readonly required: true;
-        readonly validator: (snapExport: unknown) => snapExport is OnKeyringRequestHandler<JsonRpcParams>;
+        readonly validator: (snapExport: unknown) => snapExport is OnKeyringRequestHandler<import("@metamask/snaps-sdk").JsonRpcParams>;
+    };
+    readonly onHomePage: {
+        readonly type: HandlerType.OnHomePage;
+        readonly required: true;
+        readonly validator: (snapExport: unknown) => snapExport is OnHomePageHandler;
     };
 };
-/**
- * The `onRpcRequest` handler. This is called whenever a JSON-RPC request is
- * made to the snap.
- *
- * @param args - The request arguments.
- * @param args.origin - The origin of the request. This can be the ID of another
- * snap, or the URL of a dapp.
- * @param args.request - The JSON-RPC request sent to the snap.
- * @returns The JSON-RPC response. This must be a JSON-serializable value.
- */
-export declare type OnRpcRequestHandler<Params extends JsonRpcParams = JsonRpcParams> = (args: {
-    origin: string;
-    request: JsonRpcRequest<Params>;
-}) => Promise<unknown>;
-/**
- * Enum used to specify the severity level of content being returned from a transaction insight.
- */
-export declare enum SeverityLevel {
-    Critical = "critical"
-}
 export declare const OnTransactionResponseStruct: import("superstruct").Struct<{
-    content: import("@metamask/snaps-ui").Panel | {
+    content: import("@metamask/snaps-sdk").Panel | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Copyable;
+        type: import("@metamask/snaps-sdk").NodeType.Copyable;
+        sensitive?: boolean | undefined;
     } | {
-        type: import("@metamask/snaps-ui").NodeType.Divider;
+        type: import("@metamask/snaps-sdk").NodeType.Divider;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Heading;
-    } | {
-        type: import("@metamask/snaps-ui").NodeType.Spinner;
+        type: import("@metamask/snaps-sdk").NodeType.Heading;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Text;
-        markdown?: boolean | undefined;
+        type: import("@metamask/snaps-sdk").NodeType.Image;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Spinner;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Image;
+        type: import("@metamask/snaps-sdk").NodeType.Text;
+        markdown?: boolean | undefined;
     };
     severity?: SeverityLevel | undefined;
-}, {
-    content: import("superstruct").Struct<import("@metamask/snaps-ui").Panel | {
+} | null, {
+    content: import("superstruct").Struct<import("@metamask/snaps-sdk").Panel | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Copyable;
+        type: import("@metamask/snaps-sdk").NodeType.Copyable;
+        sensitive?: boolean | undefined;
     } | {
-        type: import("@metamask/snaps-ui").NodeType.Divider;
+        type: import("@metamask/snaps-sdk").NodeType.Divider;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Heading;
-    } | {
-        type: import("@metamask/snaps-ui").NodeType.Spinner;
+        type: import("@metamask/snaps-sdk").NodeType.Heading;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Text;
-        markdown?: boolean | undefined;
+        type: import("@metamask/snaps-sdk").NodeType.Image;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Spinner;
     } | {
         value: string;
-        type: import("@metamask/snaps-ui").NodeType.Image;
+        type: import("@metamask/snaps-sdk").NodeType.Text;
+        markdown?: boolean | undefined;
     }, null>;
     severity: import("superstruct").Struct<SeverityLevel | undefined, SeverityLevel>;
 }>;
-/**
- * The response from a snap's `onTransaction` handler.
- *
- * @property content - A custom UI component, that will be shown in MetaMask. Can be created using `@metamask/snaps-ui`.
- *
- * If the snap has no insights about the transaction, this should be `null`.
- */
-export declare type OnTransactionResponse = Infer<typeof OnTransactionResponseStruct>;
-/**
- * The `onTransaction` handler. This is called whenever a transaction is
- * submitted to the snap. It can return insights about the transaction, which
- * will be displayed to the user.
- *
- * @param args - The request arguments.
- * @param args.transaction - The transaction object.
- * @param args.chainId - The CAIP-2 chain ID of the network the transaction is
- * being submitted to.
- * @param args.transactionOrigin - The origin of the transaction. This is the
- * URL of the dapp that submitted the transaction.
- * @returns Insights about the transaction. See {@link OnTransactionResponse}.
- */
-export declare type OnTransactionHandler = (args: {
-    transaction: {
-        [key: string]: Json;
+export declare const OnHomePageResponseStruct: import("superstruct").Struct<{
+    content: import("@metamask/snaps-sdk").Panel | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Copyable;
+        sensitive?: boolean | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Heading;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Image;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Text;
+        markdown?: boolean | undefined;
     };
-    chainId: string;
-    transactionOrigin?: string;
-}) => Promise<OnTransactionResponse>;
-/**
- * The `onCronjob` handler. This is called on a regular interval, as defined by
- * the snap's manifest.
- *
- * @param args - The request arguments.
- * @param args.request - The JSON-RPC request sent to the snap.
- */
-export declare type OnCronjobHandler<Params extends JsonRpcParams = JsonRpcParams> = (args: {
-    request: JsonRpcRequest<Params>;
-}) => Promise<unknown>;
-/**
- * A handler that can be used for the lifecycle hooks.
- */
-export declare type LifecycleEventHandler = (args: {
-    request: JsonRpcRequest;
-}) => Promise<unknown>;
-/**
- * The `onInstall` handler. This is called after the snap is installed.
- *
- * This type is an alias for {@link LifecycleEventHandler}.
- */
-export declare type OnInstallHandler = LifecycleEventHandler;
-/**
- * The `onUpdate` handler. This is called after the snap is updated.
- *
- * This type is an alias for {@link LifecycleEventHandler}.
- */
-export declare type OnUpdateHandler = LifecycleEventHandler;
-/**
- * The `onKeyringRequest` handler. This is called by the MetaMask client for
- * privileged keyring actions.
- *
- * @param args - The request arguments.
- * @param args.origin - The origin of the request. This can be the ID of
- * another snap, or the URL of a dapp.
- * @param args.request - The JSON-RPC request sent to the snap.
- */
-export declare type OnKeyringRequestHandler<Params extends JsonRpcParams = JsonRpcParams> = (args: {
-    origin: string;
-    request: JsonRpcRequest<Params>;
-}) => Promise<unknown>;
+}, {
+    content: import("superstruct").Struct<import("@metamask/snaps-sdk").Panel | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Copyable;
+        sensitive?: boolean | undefined;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Divider;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Heading;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Image;
+    } | {
+        type: import("@metamask/snaps-sdk").NodeType.Spinner;
+    } | {
+        value: string;
+        type: import("@metamask/snaps-sdk").NodeType.Text;
+        markdown?: boolean | undefined;
+    }, null>;
+}>;
 /**
  * Utility type for getting the handler function type from a handler type.
  */
 export declare type HandlerFunction<Type extends SnapHandler> = Type['validator'] extends (snapExport: unknown) => snapExport is infer Handler ? Handler : never;
-/**
- * The response from a snap's `onNameLookup` handler.
- *
- * @property resolvedAddress - The resolved address for a given domain.
- * @property resolvedDomain - The resolved domain for a given address.
- *
- *
- * If the snap has no resolved address/domain from its lookup, this should be `null`.
- */
-export declare type OnNameLookupResponse = {
-    resolvedAddress: AccountAddress;
-    resolvedDomain?: never;
-} | {
-    resolvedDomain: string;
-    resolvedAddress?: never;
-} | null;
-export declare type OnNameLookupArgs = {
-    chainId: Caip2ChainId;
-} & ({
-    domain: string;
-    address?: never;
-} | {
-    address: string;
-    domain?: never;
-});
-/**
- * The `onNameLookup` handler. This is called whenever content is entered
- * into the send to field for sending assets to an EOA address.
- *
- * @param args - The request arguments.
- * @param args.domain - The human-readable address that is to be resolved.
- * @param args.chainId - The CAIP-2 chain ID of the network the transaction is
- * being submitted to.
- * @param args.address - The address that is to be resolved.
- * @returns Resolved address/domain from the lookup. See {@link OnNameLookupResponse}.
- */
-export declare type OnNameLookupHandler = (args: OnNameLookupArgs) => Promise<OnNameLookupResponse>;
 /**
  * All the function-based handlers that a snap can implement.
  */

package/dist/types/index.browser.d.ts

@@ -13,6 +13,7 @@ export * from './handler-types';
 export * from './iframe';
 export * from './json';
 export * from './json-rpc';
+export * from './localization';
 export * from './logging';
 export * from './manifest/index.browser';
 export * from './namespace';
@@ -21,6 +22,7 @@ export * from './snaps';
 export * from './strings';
 export * from './structs';
 export * from './types';
+export * from './ui';
 export * from './validation';
 export * from './versions';
 export * from './virtual-file/index.browser';

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export * from './handler-types';
 export * from './iframe';
 export * from './json';
 export * from './json-rpc';
+export * from './localization';
 export * from './logging';
 export * from './manifest';
 export * from './mock';
@@ -26,7 +27,7 @@ export * from './snaps';
 export * from './strings';
 export * from './structs';
 export * from './types';
+export * from './ui';
 export * from './validation';
 export * from './versions';
 export * from './virtual-file';
-export { assertLinksAreSafe } from '@metamask/snaps-ui';

package/dist/types/localization.d.ts

@@ -0,0 +1,143 @@
+import type { Infer } from 'superstruct';
+import type { SnapManifest } from './manifest';
+import type { VirtualFile } from './virtual-file';
+export declare const LOCALIZABLE_FIELDS: readonly ["description", "proposedName"];
+export declare const LocalizationFileStruct: import("superstruct").Struct<{
+    locale: string;
+    messages: Record<string, {
+        message: string;
+        description?: string | undefined;
+    }>;
+}, {
+    locale: import("superstruct").Struct<string, null>;
+    messages: import("superstruct").Struct<Record<string, {
+        message: string;
+        description?: string | undefined;
+    }>, null>;
+}>;
+export declare type LocalizationFile = Infer<typeof LocalizationFileStruct>;
+/**
+ * Validate a list of localization files.
+ *
+ * @param localizationFiles - The localization files to validate.
+ * @returns The validated localization files.
+ * @throws If any of the files are considered invalid.
+ */
+export declare function getValidatedLocalizationFiles(localizationFiles: VirtualFile[]): VirtualFile<LocalizationFile>[];
+/**
+ * Get the localization file for a given locale. If the locale is not found,
+ * the English localization file will be returned.
+ *
+ * @param locale - The locale to use.
+ * @param localizationFiles - The localization files to use.
+ * @returns The localization file, or `undefined` if no localization file was
+ * found.
+ */
+export declare function getLocalizationFile(locale: string, localizationFiles: LocalizationFile[]): {
+    locale: string;
+    messages: Record<string, {
+        message: string;
+        description?: string | undefined;
+    }>;
+} | undefined;
+export declare const TRANSLATION_REGEX: RegExp;
+/**
+ * Translate a string using a localization file. This will replace all instances
+ * of `{{key}}` with the localized version of `key`.
+ *
+ * @param value - The string to translate.
+ * @param file - The localization file to use, or `undefined` if no localization
+ * file was found.
+ * @returns The translated string.
+ * @throws If the string contains a key that is not present in the localization
+ * file, or if no localization file was found.
+ */
+export declare function translate(value: string, file: LocalizationFile | undefined): string;
+/**
+ * Get the localized Snap manifest for a given locale. This will replace all
+ * localized strings in the manifest with the localized version.
+ *
+ * @param snapManifest - The Snap manifest to localize.
+ * @param locale - The locale to use.
+ * @param localizationFiles - The localization files to use.
+ * @returns The localized Snap manifest.
+ */
+export declare function getLocalizedSnapManifest(snapManifest: SnapManifest, locale: string, localizationFiles: LocalizationFile[]): {
+    description: string;
+    version: import("@metamask/utils").SemVerVersion;
+    source: {
+        location: {
+            npm: {
+                registry: "https://registry.npmjs.org" | "https://registry.npmjs.org/";
+                filePath: string;
+                packageName: string;
+                iconPath?: string | undefined;
+            };
+        };
+        shasum: string;
+        files?: string[] | undefined;
+        locales?: string[] | undefined;
+    };
+    proposedName: string;
+    initialPermissions: {
+        snap_dialog?: {} | undefined;
+        snap_getBip32Entropy?: {
+            path: string[];
+            curve: "ed25519" | "secp256k1";
+        }[] | undefined;
+        snap_getBip32PublicKey?: {
+            path: string[];
+            curve: "ed25519" | "secp256k1";
+        }[] | undefined;
+        snap_getBip44Entropy?: {
+            coinType: number;
+        }[] | undefined;
+        snap_getEntropy?: {} | undefined;
+        snap_manageAccounts?: {} | undefined;
+        snap_manageState?: {} | undefined;
+        snap_notify?: {} | undefined;
+        wallet_snap?: Record<string, {
+            version?: string | undefined;
+        }> | undefined;
+        'endowment:network-access'?: {} | undefined;
+        'endowment:webassembly'?: {} | undefined;
+        'endowment:transaction-insight'?: {
+            allowTransactionOrigin?: boolean | undefined;
+        } | undefined;
+        'endowment:cronjob'?: {
+            jobs: {
+                request: {
+                    method: string;
+                    params?: Record<string, import("@metamask/snaps-sdk").Json> | import("@metamask/snaps-sdk").Json[] | undefined;
+                    id?: string | number | null | undefined;
+                    jsonrpc?: "2.0" | undefined;
+                };
+                expression: string;
+            }[];
+        } | undefined;
+        'endowment:rpc'?: {
+            dapps?: boolean | undefined;
+            snaps?: boolean | undefined;
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+        'endowment:name-lookup'?: `${string}:${string}`[] | undefined;
+        'endowment:keyring'?: {
+            allowedOrigins?: string[] | undefined;
+        } | undefined;
+        snap_confirm?: {} | undefined;
+    };
+    manifestVersion: "0.1";
+    repository?: {
+        type: string;
+        url: string;
+    } | undefined;
+    $schema?: string | undefined;
+};
+/**
+ * Validate the localization files for a Snap manifest.
+ *
+ * @param snapManifest - The Snap manifest to validate.
+ * @param localizationFiles - The localization files to validate.
+ * @throws If the manifest cannot be localized.
+ */
+export declare function validateSnapManifestLocalizations(snapManifest: SnapManifest, localizationFiles: LocalizationFile[]): void;

package/dist/types/manifest/manifest.d.ts

@@ -46,7 +46,7 @@ export declare function checkManifest(basePath: string, writeManifest?: boolean,
  * @param error - The {@link ProgrammaticallyFixableSnapError} that was thrown.
  * @returns A copy of the manifest file where the cause of the error is fixed.
  */
-export declare function fixManifest(snapFiles: SnapFiles, error: ProgrammaticallyFixableSnapError): VirtualFile<SnapManifest>;
+export declare function fixManifest(snapFiles: SnapFiles, error: ProgrammaticallyFixableSnapError): Promise<VirtualFile<SnapManifest>>;
 /**
  * Given an unvalidated Snap manifest, attempts to extract the location of the
  * bundle source file location and read the file.
@@ -67,14 +67,22 @@ export declare function getSnapSourceCode(basePath: string, manifest: Json, sour
  */
 export declare function getSnapIcon(basePath: string, manifest: Json): Promise<VirtualFile | undefined>;
 /**
- * Given an unvalidated Snap manifest, attempts to extract the auxiliary files
- * and read them.
+ * Get an array of paths from an unvalidated Snap manifest.
  *
- * @param basePath - The path to the folder with the manifest files.
  * @param manifest - The unvalidated Snap manifest file contents.
+ * @param selector - A function that returns the paths to the files.
+ * @returns The paths to the files, if any.
+ */
+export declare function getSnapFilePaths(manifest: Json, selector: (manifest: Partial<SnapManifest>) => string[] | undefined): string[] | undefined;
+/**
+ * Given an unvalidated Snap manifest, attempts to extract the files with the
+ * given paths and read them.
+ *
+ * @param basePath - The path to the folder with the manifest files.
+ * @param paths - The paths to the files.
  * @returns A list of auxiliary files and their contents, if any.
  */
-export declare function getSnapAuxiliaryFiles(basePath: string, manifest: Json): Promise<VirtualFile[] | undefined>;
+export declare function getSnapFiles(basePath: string, paths: string[] | undefined): Promise<VirtualFile[] | undefined>;
 /**
  * Sorts the given manifest in our preferred sort order and removes the
  * `repository` field if it is falsy (it may be `null`).
@@ -84,7 +92,7 @@ export declare function getSnapAuxiliaryFiles(basePath: string, manifest: Json):
  */
 export declare function getWritableManifest(manifest: SnapManifest): SnapManifest;
 /**
- * Validates the fields of an npm Snap manifest that has already passed JSON
+ * Validates the fields of an NPM Snap manifest that has already passed JSON
  * Schema validation.
  *
  * @param snapFiles - The relevant snap files to validate.
@@ -93,5 +101,6 @@ export declare function getWritableManifest(manifest: SnapManifest): SnapManifes
  * @param snapFiles.sourceCode - The Snap's source code.
  * @param snapFiles.svgIcon - The Snap's optional icon.
  * @param snapFiles.auxiliaryFiles - Any auxiliary files required by the snap at runtime.
+ * @param snapFiles.localizationFiles - The Snap's localization files.
  */
-export declare function validateNpmSnapManifest({ manifest, packageJson, sourceCode, svgIcon, auxiliaryFiles, }: SnapFiles): void;
+export declare function validateNpmSnapManifest({ manifest, packageJson, sourceCode, svgIcon, auxiliaryFiles, localizationFiles, }: SnapFiles): Promise<void>;