@metamask/snaps-rpc-methods 14.2.0 → 15.0.0

package/dist/permitted/listEntropySources.d.mts

@@ -1,5 +1,7 @@
-import type { PermittedHandlerExport } from "@metamask/permission-controller";
-import type { EntropySource, ListEntropySourcesParams, ListEntropySourcesResult } from "@metamask/snaps-sdk";
+import type { JsonRpcEngineEndCallback } from "@metamask/json-rpc-engine";
+import type { EntropySource, JsonRpcRequest, ListEntropySourcesParams, ListEntropySourcesResult } from "@metamask/snaps-sdk";
+import type { PendingJsonRpcResponse } from "@metamask/utils";
+import type { MethodHooksObject } from "../utils.mjs";
 export type ListEntropySourcesHooks = {
     /**
      * Check if the requesting origin has a given permission.
@@ -21,5 +23,64 @@ export type ListEntropySourcesHooks = {
      */
     getUnlockPromise: (shouldShowUnlockRequest: boolean) => Promise<void>;
 };
-export declare const listEntropySourcesHandler: PermittedHandlerExport<ListEntropySourcesHooks, ListEntropySourcesParams, ListEntropySourcesResult>;
+/**
+ * Get a list of entropy sources available to the Snap. The requesting origin
+ * must have at least one of the following permissions to access entropy source
+ * metadata:
+ *
+ * - `snap_getBip32Entropy`
+ * - `snap_getBip32PublicKey`
+ * - `snap_getBip44Entropy`
+ * - `snap_getEntropy`
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "snap_getBip32Entropy": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * const entropySources = await snap.request({ method: 'snap_listEntropySources' });
+ * console.log(entropySources);
+ * // Example output:
+ * // [
+ * //   {
+ * //     name: 'Mnemonic 1',
+ * //     id: 'mnemonic-1',
+ * //     type: 'mnemonic',
+ * //     primary: true,
+ * //   },
+ * //   {
+ * //     name: 'Mnemonic 2',
+ * //     id: 'mnemonic-2',
+ * //     type: 'mnemonic',
+ * //     primary: false,
+ * //   },
+ * // ]
+ * ```
+ */
+export declare const listEntropySourcesHandler: {
+    methodNames: ["snap_listEntropySources"];
+    implementation: typeof listEntropySourcesImplementation;
+    hookNames: MethodHooksObject<ListEntropySourcesHooks>;
+};
+/**
+ * The `snap_listEntropySources` method implementation.
+ *
+ * @param _request - The JSON-RPC request object. Not used by this function.
+ * @param response - The JSON-RPC response object.
+ * @param _next - The `json-rpc-engine` "next" callback. Not used by this
+ * function.
+ * @param end - The `json-rpc-engine` "end" callback.
+ * @param hooks - The RPC method hooks.
+ * @param hooks.hasPermission - The function to check if the origin has a
+ * permission.
+ * @param hooks.getEntropySources - The function to get the entropy sources.
+ * @param hooks.getUnlockPromise - The function to get the unlock promise.
+ * @returns Noting.
+ */
+declare function listEntropySourcesImplementation(_request: JsonRpcRequest<ListEntropySourcesParams>, response: PendingJsonRpcResponse<ListEntropySourcesResult>, _next: unknown, end: JsonRpcEngineEndCallback, { hasPermission, getEntropySources, getUnlockPromise, }: ListEntropySourcesHooks): Promise<void>;
+export {};
 //# sourceMappingURL=listEntropySources.d.mts.map

package/dist/permitted/listEntropySources.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"listEntropySources.d.mts","sourceRoot":"","sources":["../../src/permitted/listEntropySources.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wCAAwC;AAE9E,OAAO,KAAK,EACV,aAAa,EAEb,wBAAwB,EACxB,wBAAwB,EACzB,4BAA4B;AA0B7B,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IAEnD;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,aAAa,EAAE,CAAC;IAEzC;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,uBAAuB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,sBAAsB,CAC5D,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,CAKzB,CAAC"}
+{"version":3,"file":"listEntropySources.d.mts","sourceRoot":"","sources":["../../src/permitted/listEntropySources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kCAAkC;AAG1E,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,wBAAwB,EACxB,wBAAwB,EACzB,4BAA4B;AAC7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB;AAM9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAiB;AAqBlD,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IAEnD;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,aAAa,EAAE,CAAC;IAEzC;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,uBAAuB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,yBAAyB;;;;CAQrC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,iBAAe,gCAAgC,CAC7C,QAAQ,EAAE,cAAc,CAAC,wBAAwB,CAAC,EAClD,QAAQ,EAAE,sBAAsB,CAAC,wBAAwB,CAAC,EAC1D,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,wBAAwB,EAC7B,EACE,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,EAAE,uBAAuB,GACzB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/permitted/listEntropySources.mjs

@@ -13,13 +13,52 @@ const REQUIRED_PERMISSIONS = [
     getBip44EntropyBuilder.targetName,
     getEntropyBuilder.targetName,
 ];
+const methodName = 'snap_listEntropySources';
 const hookNames = {
     hasPermission: true,
     getEntropySources: true,
     getUnlockPromise: true,
 };
+/**
+ * Get a list of entropy sources available to the Snap. The requesting origin
+ * must have at least one of the following permissions to access entropy source
+ * metadata:
+ *
+ * - `snap_getBip32Entropy`
+ * - `snap_getBip32PublicKey`
+ * - `snap_getBip44Entropy`
+ * - `snap_getEntropy`
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "snap_getBip32Entropy": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * const entropySources = await snap.request({ method: 'snap_listEntropySources' });
+ * console.log(entropySources);
+ * // Example output:
+ * // [
+ * //   {
+ * //     name: 'Mnemonic 1',
+ * //     id: 'mnemonic-1',
+ * //     type: 'mnemonic',
+ * //     primary: true,
+ * //   },
+ * //   {
+ * //     name: 'Mnemonic 2',
+ * //     id: 'mnemonic-2',
+ * //     type: 'mnemonic',
+ * //     primary: false,
+ * //   },
+ * // ]
+ * ```
+ */
 export const listEntropySourcesHandler = {
-    methodNames: ['snap_listEntropySources'],
+    methodNames: [methodName],
     implementation: listEntropySourcesImplementation,
     hookNames,
 };

package/dist/permitted/listEntropySources.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"listEntropySources.mjs","sourceRoot":"","sources":["../../src/permitted/listEntropySources.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,6BAA6B;AAStD,OAAO,EAAE,sBAAsB,EAAE,0CAAsC;AACvE,OAAO,EAAE,wBAAwB,EAAE,4CAAwC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,0CAAsC;AACvE,OAAO,EAAE,iBAAiB,EAAE,qCAAiC;AAG7D;;;GAGG;AACH,MAAM,oBAAoB,GAAG;IAC3B,sBAAsB,CAAC,UAAU;IACjC,wBAAwB,CAAC,UAAU;IACnC,sBAAsB,CAAC,UAAU;IACjC,iBAAiB,CAAC,UAAU;CAC7B,CAAC;AAEF,MAAM,SAAS,GAA+C;IAC5D,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;CACvB,CAAC;AA0BF,MAAM,CAAC,MAAM,yBAAyB,GAIlC;IACF,WAAW,EAAE,CAAC,yBAAyB,CAAC;IACxC,cAAc,EAAE,gCAAgC;IAChD,SAAS;CACV,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,gCAAgC,CAC7C,QAAkD,EAClD,QAA0D,EAC1D,KAAc,EACd,GAA6B,EAC7B,EACE,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACQ;IAE1B,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAE7B,QAAQ,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACtC,OAAO,GAAG,EAAE,CAAC;AACf,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors } from '@metamask/rpc-errors';\nimport type {\n  EntropySource,\n  JsonRpcRequest,\n  ListEntropySourcesParams,\n  ListEntropySourcesResult,\n} from '@metamask/snaps-sdk';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { getBip32EntropyBuilder } from '../restricted/getBip32Entropy';\nimport { getBip32PublicKeyBuilder } from '../restricted/getBip32PublicKey';\nimport { getBip44EntropyBuilder } from '../restricted/getBip44Entropy';\nimport { getEntropyBuilder } from '../restricted/getEntropy';\nimport type { MethodHooksObject } from '../utils';\n\n/**\n * A list of permissions that the requesting origin must have at least one of\n * in order to call this method.\n */\nconst REQUIRED_PERMISSIONS = [\n  getBip32EntropyBuilder.targetName,\n  getBip32PublicKeyBuilder.targetName,\n  getBip44EntropyBuilder.targetName,\n  getEntropyBuilder.targetName,\n];\n\nconst hookNames: MethodHooksObject<ListEntropySourcesHooks> = {\n  hasPermission: true,\n  getEntropySources: true,\n  getUnlockPromise: true,\n};\n\nexport type ListEntropySourcesHooks = {\n  /**\n   * Check if the requesting origin has a given permission.\n   *\n   * @param permissionName - The name of the permission to check.\n   * @returns Whether the origin has the permission.\n   */\n  hasPermission: (permissionName: string) => boolean;\n\n  /**\n   * Get the entropy sources from the client.\n   *\n   * @returns The entropy sources.\n   */\n  getEntropySources: () => EntropySource[];\n\n  /**\n   * Wait 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\nexport const listEntropySourcesHandler: PermittedHandlerExport<\n  ListEntropySourcesHooks,\n  ListEntropySourcesParams,\n  ListEntropySourcesResult\n> = {\n  methodNames: ['snap_listEntropySources'],\n  implementation: listEntropySourcesImplementation,\n  hookNames,\n};\n\n/**\n * The `snap_listEntropySources` method implementation.\n *\n * @param _request - The JSON-RPC request object. Not used by this function.\n * @param response - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this\n * function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if the origin has a\n * permission.\n * @param hooks.getEntropySources - The function to get the entropy sources.\n * @param hooks.getUnlockPromise - The function to get the unlock promise.\n * @returns Noting.\n */\nasync function listEntropySourcesImplementation(\n  _request: JsonRpcRequest<ListEntropySourcesParams>,\n  response: PendingJsonRpcResponse<ListEntropySourcesResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  {\n    hasPermission,\n    getEntropySources,\n    getUnlockPromise,\n  }: ListEntropySourcesHooks,\n): Promise<void> {\n  const isPermitted = REQUIRED_PERMISSIONS.some(hasPermission);\n  if (!isPermitted) {\n    return end(providerErrors.unauthorized());\n  }\n\n  await getUnlockPromise(true);\n\n  response.result = getEntropySources();\n  return end();\n}\n"]}
+{"version":3,"file":"listEntropySources.mjs","sourceRoot":"","sources":["../../src/permitted/listEntropySources.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,6BAA6B;AAStD,OAAO,EAAE,sBAAsB,EAAE,0CAAsC;AACvE,OAAO,EAAE,wBAAwB,EAAE,4CAAwC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,0CAAsC;AACvE,OAAO,EAAE,iBAAiB,EAAE,qCAAiC;AAG7D;;;GAGG;AACH,MAAM,oBAAoB,GAAG;IAC3B,sBAAsB,CAAC,UAAU;IACjC,wBAAwB,CAAC,UAAU;IACnC,sBAAsB,CAAC,UAAU;IACjC,iBAAiB,CAAC,UAAU;CAC7B,CAAC;AAEF,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C,MAAM,SAAS,GAA+C;IAC5D,aAAa,EAAE,IAAI;IACnB,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;CACvB,CAAC;AA0BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,WAAW,EAAE,CAAC,UAAU,CAAU;IAClC,cAAc,EAAE,gCAAgC;IAChD,SAAS;CAKV,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,gCAAgC,CAC7C,QAAkD,EAClD,QAA0D,EAC1D,KAAc,EACd,GAA6B,EAC7B,EACE,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACQ;IAE1B,MAAM,WAAW,GAAG,oBAAoB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAE7B,QAAQ,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACtC,OAAO,GAAG,EAAE,CAAC;AACf,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors } from '@metamask/rpc-errors';\nimport type {\n  EntropySource,\n  JsonRpcRequest,\n  ListEntropySourcesParams,\n  ListEntropySourcesResult,\n} from '@metamask/snaps-sdk';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { getBip32EntropyBuilder } from '../restricted/getBip32Entropy';\nimport { getBip32PublicKeyBuilder } from '../restricted/getBip32PublicKey';\nimport { getBip44EntropyBuilder } from '../restricted/getBip44Entropy';\nimport { getEntropyBuilder } from '../restricted/getEntropy';\nimport type { MethodHooksObject } from '../utils';\n\n/**\n * A list of permissions that the requesting origin must have at least one of\n * in order to call this method.\n */\nconst REQUIRED_PERMISSIONS = [\n  getBip32EntropyBuilder.targetName,\n  getBip32PublicKeyBuilder.targetName,\n  getBip44EntropyBuilder.targetName,\n  getEntropyBuilder.targetName,\n];\n\nconst methodName = 'snap_listEntropySources';\n\nconst hookNames: MethodHooksObject<ListEntropySourcesHooks> = {\n  hasPermission: true,\n  getEntropySources: true,\n  getUnlockPromise: true,\n};\n\nexport type ListEntropySourcesHooks = {\n  /**\n   * Check if the requesting origin has a given permission.\n   *\n   * @param permissionName - The name of the permission to check.\n   * @returns Whether the origin has the permission.\n   */\n  hasPermission: (permissionName: string) => boolean;\n\n  /**\n   * Get the entropy sources from the client.\n   *\n   * @returns The entropy sources.\n   */\n  getEntropySources: () => EntropySource[];\n\n  /**\n   * Wait 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/**\n * Get a list of entropy sources available to the Snap. The requesting origin\n * must have at least one of the following permissions to access entropy source\n * metadata:\n *\n * - `snap_getBip32Entropy`\n * - `snap_getBip32PublicKey`\n * - `snap_getBip44Entropy`\n * - `snap_getEntropy`\n *\n * @example\n * ```json name=\"Manifest\"\n * {\n *   \"initialPermissions\": {\n *     \"snap_getBip32Entropy\": {}\n *   }\n * }\n * ```\n * ```ts name=\"Usage\"\n * const entropySources = await snap.request({ method: 'snap_listEntropySources' });\n * console.log(entropySources);\n * // Example output:\n * // [\n * //   {\n * //     name: 'Mnemonic 1',\n * //     id: 'mnemonic-1',\n * //     type: 'mnemonic',\n * //     primary: true,\n * //   },\n * //   {\n * //     name: 'Mnemonic 2',\n * //     id: 'mnemonic-2',\n * //     type: 'mnemonic',\n * //     primary: false,\n * //   },\n * // ]\n * ```\n */\nexport const listEntropySourcesHandler = {\n  methodNames: [methodName] as const,\n  implementation: listEntropySourcesImplementation,\n  hookNames,\n} satisfies PermittedHandlerExport<\n  ListEntropySourcesHooks,\n  ListEntropySourcesParams,\n  ListEntropySourcesResult\n>;\n\n/**\n * The `snap_listEntropySources` method implementation.\n *\n * @param _request - The JSON-RPC request object. Not used by this function.\n * @param response - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this\n * function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if the origin has a\n * permission.\n * @param hooks.getEntropySources - The function to get the entropy sources.\n * @param hooks.getUnlockPromise - The function to get the unlock promise.\n * @returns Noting.\n */\nasync function listEntropySourcesImplementation(\n  _request: JsonRpcRequest<ListEntropySourcesParams>,\n  response: PendingJsonRpcResponse<ListEntropySourcesResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  {\n    hasPermission,\n    getEntropySources,\n    getUnlockPromise,\n  }: ListEntropySourcesHooks,\n): Promise<void> {\n  const isPermitted = REQUIRED_PERMISSIONS.some(hasPermission);\n  if (!isPermitted) {\n    return end(providerErrors.unauthorized());\n  }\n\n  await getUnlockPromise(true);\n\n  response.result = getEntropySources();\n  return end();\n}\n"]}

package/dist/permitted/openWebSocket.cjs

@@ -6,6 +6,7 @@ const snaps_sdk_1 = require("@metamask/snaps-sdk");
 const snaps_utils_1 = require("@metamask/snaps-utils");
 const superstruct_1 = require("@metamask/superstruct");
 const endowments_1 = require("../endowments/index.cjs");
+const methodName = 'snap_openWebSocket';
 const hookNames = {
     hasPermission: true,
     openWebSocket: true,
@@ -15,10 +16,53 @@ const OpenWebSocketParametersStruct = (0, superstruct_1.object)({
     protocols: (0, superstruct_1.optional)((0, superstruct_1.array)((0, superstruct_1.string)())),
 });
 /**
- * Handler for the `snap_openWebSocket` method.
+ * Open a WebSocket connection to the specified URL with optional protocols.
+ *
+ * Note: This method is only available to snaps that have the
+ * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)
+ * permission.
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "endowment:network-access": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of
+ * // the Snap:
+ * snap.request({
+ *   method: 'snap_openWebSocket',
+ *   params: {
+ *     url: 'wss://example.com/socket',
+ *     protocols: ['protocol1', 'protocol2'], // Optional
+ *   },
+ * });
+ *
+ * // Listen for events from the WebSocket connection in the `onWebSocketEvent`
+ * // handler of the Snap:
+ * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {
+ *   switch (event.type) {
+ *     case 'open':
+ *       console.log(`WebSocket connection opened with origin ${event.origin}`);
+ *       break;
+ *     case 'message':
+ *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);
+ *       break;
+ *     case 'close':
+ *       console.log(`WebSocket connection closed with origin ${event.origin}`);
+ *       break;
+ *     case 'error':
+ *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);
+ *       break;
+ *   }
+ * };
+ * ```
  */
 exports.openWebSocketHandler = {
-    methodNames: ['snap_openWebSocket'],
+    methodNames: [methodName],
     implementation: openWebSocketImplementation,
     hookNames,
 };

package/dist/permitted/openWebSocket.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"openWebSocket.cjs","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":";;;AAEA,qDAAiE;AACjE,mDAM6B;AAC7B,uDAAgE;AAChE,uDAO+B;AAG/B,wDAA+C;AAG/C,MAAM,SAAS,GAAgD;IAC7D,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;CACpB,CAAC;AAOF,MAAM,6BAA6B,GAAG,IAAA,oBAAM,EAAC;IAC3C,GAAG,EAAE,IAAA,iBAAG,EAAC,EAAE,QAAQ,EAAE,IAAA,iBAAK,EAAC,CAAC,IAAA,mBAAO,EAAC,MAAM,CAAC,EAAE,IAAA,mBAAO,EAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,SAAS,EAAE,IAAA,sBAAQ,EAAC,IAAA,mBAAK,EAAC,IAAA,oBAAM,GAAE,CAAC,CAAC;CACrC,CAAC,CAAC;AAOH;;GAEG;AACU,QAAA,oBAAoB,GAI7B;IACF,WAAW,EAAE,CAAC,oBAAoB,CAAC;IACnC,cAAc,EAAE,2BAA2B;IAC3C,SAAS;CACV,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,2BAA2B,CACxC,GAA4C,EAC5C,GAAgD,EAChD,KAAc,EACd,GAA6B,EAC7B,EAAE,aAAa,EAAE,aAAa,EAA4B;IAE1D,IAAI,CAAC,aAAa,CAAC,2BAAc,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,2BAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtD,GAAG,CAAC,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,CAAC;QACH,OAAO,IAAA,oBAAM,EAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,yBAAW,EAAE,CAAC;YACjC,MAAM,sBAAS,CAAC,aAAa,CAAC;gBAC5B,OAAO,EAAE,mBAAmB,KAAK,CAAC,OAAO,GAAG;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,0BAA0B;QAC1B,MAAM,sBAAS,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors, rpcErrors } from '@metamask/rpc-errors';\nimport {\n  literal,\n  union,\n  type JsonRpcRequest,\n  type OpenWebSocketParams,\n  type OpenWebSocketResult,\n} from '@metamask/snaps-sdk';\nimport { uri, type InferMatching } from '@metamask/snaps-utils';\nimport {\n  create,\n  object,\n  array,\n  string,\n  optional,\n  StructError,\n} from '@metamask/superstruct';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { SnapEndowments } from '../endowments';\nimport type { MethodHooksObject } from '../utils';\n\nconst hookNames: MethodHooksObject<OpenWebSocketMethodHooks> = {\n  hasPermission: true,\n  openWebSocket: true,\n};\n\nexport type OpenWebSocketMethodHooks = {\n  hasPermission: (permissionName: string) => boolean;\n  openWebSocket: (url: string, protocols?: string[]) => Promise<string>;\n};\n\nconst OpenWebSocketParametersStruct = object({\n  url: uri({ protocol: union([literal('wss:'), literal('ws:')]) }),\n  protocols: optional(array(string())),\n});\n\nexport type OpenWebSocketParameters = InferMatching<\n  typeof OpenWebSocketParametersStruct,\n  OpenWebSocketParams\n>;\n\n/**\n * Handler for the `snap_openWebSocket` method.\n */\nexport const openWebSocketHandler: PermittedHandlerExport<\n  OpenWebSocketMethodHooks,\n  OpenWebSocketParams,\n  OpenWebSocketResult\n> = {\n  methodNames: ['snap_openWebSocket'],\n  implementation: openWebSocketImplementation,\n  hookNames,\n};\n\n/**\n * The `snap_openWebSocket` method implementation.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.\n * @param hooks.openWebSocket - The function to open a WebSocket.\n * @returns Nothing.\n */\nasync function openWebSocketImplementation(\n  req: JsonRpcRequest<OpenWebSocketParameters>,\n  res: PendingJsonRpcResponse<OpenWebSocketResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { hasPermission, openWebSocket }: OpenWebSocketMethodHooks,\n): Promise<void> {\n  if (!hasPermission(SnapEndowments.NetworkAccess)) {\n    return end(providerErrors.unauthorized());\n  }\n\n  const { params } = req;\n\n  try {\n    const { url, protocols } = getValidatedParams(params);\n    res.result = await openWebSocket(url, protocols);\n  } catch (error) {\n    return end(error);\n  }\n\n  return end();\n}\n\n/**\n * Validates the parameters for the snap_openWebSocket method.\n *\n * @param params - Parameters to validate.\n * @returns Validated parameters.\n * @throws Throws RPC error if validation fails.\n */\nfunction getValidatedParams(params: unknown): OpenWebSocketParameters {\n  try {\n    return create(params, OpenWebSocketParametersStruct);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid params: ${error.message}.`,\n      });\n    }\n    /* istanbul ignore next */\n    throw rpcErrors.internal();\n  }\n}\n"]}
+{"version":3,"file":"openWebSocket.cjs","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":";;;AAEA,qDAAiE;AACjE,mDAM6B;AAC7B,uDAAgE;AAChE,uDAO+B;AAG/B,wDAA+C;AAG/C,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAExC,MAAM,SAAS,GAAgD;IAC7D,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;CACpB,CAAC;AAOF,MAAM,6BAA6B,GAAG,IAAA,oBAAM,EAAC;IAC3C,GAAG,EAAE,IAAA,iBAAG,EAAC,EAAE,QAAQ,EAAE,IAAA,iBAAK,EAAC,CAAC,IAAA,mBAAO,EAAC,MAAM,CAAC,EAAE,IAAA,mBAAO,EAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,SAAS,EAAE,IAAA,sBAAQ,EAAC,IAAA,mBAAK,EAAC,IAAA,oBAAM,GAAE,CAAC,CAAC;CACrC,CAAC,CAAC;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACU,QAAA,oBAAoB,GAAG;IAClC,WAAW,EAAE,CAAC,UAAU,CAAU;IAClC,cAAc,EAAE,2BAA2B;IAC3C,SAAS;CAKV,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,2BAA2B,CACxC,GAA4C,EAC5C,GAAgD,EAChD,KAAc,EACd,GAA6B,EAC7B,EAAE,aAAa,EAAE,aAAa,EAA4B;IAE1D,IAAI,CAAC,aAAa,CAAC,2BAAc,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,2BAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtD,GAAG,CAAC,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,CAAC;QACH,OAAO,IAAA,oBAAM,EAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,yBAAW,EAAE,CAAC;YACjC,MAAM,sBAAS,CAAC,aAAa,CAAC;gBAC5B,OAAO,EAAE,mBAAmB,KAAK,CAAC,OAAO,GAAG;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,0BAA0B;QAC1B,MAAM,sBAAS,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors, rpcErrors } from '@metamask/rpc-errors';\nimport {\n  literal,\n  union,\n  type JsonRpcRequest,\n  type OpenWebSocketParams,\n  type OpenWebSocketResult,\n} from '@metamask/snaps-sdk';\nimport { uri, type InferMatching } from '@metamask/snaps-utils';\nimport {\n  create,\n  object,\n  array,\n  string,\n  optional,\n  StructError,\n} from '@metamask/superstruct';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { SnapEndowments } from '../endowments';\nimport type { MethodHooksObject } from '../utils';\n\nconst methodName = 'snap_openWebSocket';\n\nconst hookNames: MethodHooksObject<OpenWebSocketMethodHooks> = {\n  hasPermission: true,\n  openWebSocket: true,\n};\n\nexport type OpenWebSocketMethodHooks = {\n  hasPermission: (permissionName: string) => boolean;\n  openWebSocket: (url: string, protocols?: string[]) => Promise<string>;\n};\n\nconst OpenWebSocketParametersStruct = object({\n  url: uri({ protocol: union([literal('wss:'), literal('ws:')]) }),\n  protocols: optional(array(string())),\n});\n\nexport type OpenWebSocketParameters = InferMatching<\n  typeof OpenWebSocketParametersStruct,\n  OpenWebSocketParams\n>;\n\n/**\n * Open a WebSocket connection to the specified URL with optional protocols.\n *\n * Note: This method is only available to snaps that have the\n * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)\n * permission.\n *\n * @example\n * ```json name=\"Manifest\"\n * {\n *   \"initialPermissions\": {\n *     \"endowment:network-access\": {}\n *   }\n * }\n * ```\n * ```ts name=\"Usage\"\n * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of\n * // the Snap:\n * snap.request({\n *   method: 'snap_openWebSocket',\n *   params: {\n *     url: 'wss://example.com/socket',\n *     protocols: ['protocol1', 'protocol2'], // Optional\n *   },\n * });\n *\n * // Listen for events from the WebSocket connection in the `onWebSocketEvent`\n * // handler of the Snap:\n * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {\n *   switch (event.type) {\n *     case 'open':\n *       console.log(`WebSocket connection opened with origin ${event.origin}`);\n *       break;\n *     case 'message':\n *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);\n *       break;\n *     case 'close':\n *       console.log(`WebSocket connection closed with origin ${event.origin}`);\n *       break;\n *     case 'error':\n *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);\n *       break;\n *   }\n * };\n * ```\n */\nexport const openWebSocketHandler = {\n  methodNames: [methodName] as const,\n  implementation: openWebSocketImplementation,\n  hookNames,\n} satisfies PermittedHandlerExport<\n  OpenWebSocketMethodHooks,\n  OpenWebSocketParams,\n  OpenWebSocketResult\n>;\n\n/**\n * The `snap_openWebSocket` method implementation.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.\n * @param hooks.openWebSocket - The function to open a WebSocket.\n * @returns Nothing.\n */\nasync function openWebSocketImplementation(\n  req: JsonRpcRequest<OpenWebSocketParameters>,\n  res: PendingJsonRpcResponse<OpenWebSocketResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { hasPermission, openWebSocket }: OpenWebSocketMethodHooks,\n): Promise<void> {\n  if (!hasPermission(SnapEndowments.NetworkAccess)) {\n    return end(providerErrors.unauthorized());\n  }\n\n  const { params } = req;\n\n  try {\n    const { url, protocols } = getValidatedParams(params);\n    res.result = await openWebSocket(url, protocols);\n  } catch (error) {\n    return end(error);\n  }\n\n  return end();\n}\n\n/**\n * Validates the parameters for the snap_openWebSocket method.\n *\n * @param params - Parameters to validate.\n * @returns Validated parameters.\n * @throws Throws RPC error if validation fails.\n */\nfunction getValidatedParams(params: unknown): OpenWebSocketParameters {\n  try {\n    return create(params, OpenWebSocketParametersStruct);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid params: ${error.message}.`,\n      });\n    }\n    /* istanbul ignore next */\n    throw rpcErrors.internal();\n  }\n}\n"]}

package/dist/permitted/openWebSocket.d.cts

@@ -1,6 +1,8 @@
-import type { PermittedHandlerExport } from "@metamask/permission-controller";
-import { type OpenWebSocketParams, type OpenWebSocketResult } from "@metamask/snaps-sdk";
+import type { JsonRpcEngineEndCallback } from "@metamask/json-rpc-engine";
+import { type JsonRpcRequest, type OpenWebSocketParams, type OpenWebSocketResult } from "@metamask/snaps-sdk";
 import { type InferMatching } from "@metamask/snaps-utils";
+import type { PendingJsonRpcResponse } from "@metamask/utils";
+import type { MethodHooksObject } from "../utils.cjs";
 export type OpenWebSocketMethodHooks = {
     hasPermission: (permissionName: string) => boolean;
     openWebSocket: (url: string, protocols?: string[]) => Promise<string>;
@@ -14,8 +16,68 @@ declare const OpenWebSocketParametersStruct: import("@metamask/superstruct").Str
 }>;
 export type OpenWebSocketParameters = InferMatching<typeof OpenWebSocketParametersStruct, OpenWebSocketParams>;
 /**
- * Handler for the `snap_openWebSocket` method.
+ * Open a WebSocket connection to the specified URL with optional protocols.
+ *
+ * Note: This method is only available to snaps that have the
+ * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)
+ * permission.
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "endowment:network-access": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of
+ * // the Snap:
+ * snap.request({
+ *   method: 'snap_openWebSocket',
+ *   params: {
+ *     url: 'wss://example.com/socket',
+ *     protocols: ['protocol1', 'protocol2'], // Optional
+ *   },
+ * });
+ *
+ * // Listen for events from the WebSocket connection in the `onWebSocketEvent`
+ * // handler of the Snap:
+ * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {
+ *   switch (event.type) {
+ *     case 'open':
+ *       console.log(`WebSocket connection opened with origin ${event.origin}`);
+ *       break;
+ *     case 'message':
+ *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);
+ *       break;
+ *     case 'close':
+ *       console.log(`WebSocket connection closed with origin ${event.origin}`);
+ *       break;
+ *     case 'error':
+ *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);
+ *       break;
+ *   }
+ * };
+ * ```
  */
-export declare const openWebSocketHandler: PermittedHandlerExport<OpenWebSocketMethodHooks, OpenWebSocketParams, OpenWebSocketResult>;
+export declare const openWebSocketHandler: {
+    methodNames: ["snap_openWebSocket"];
+    implementation: typeof openWebSocketImplementation;
+    hookNames: MethodHooksObject<OpenWebSocketMethodHooks>;
+};
+/**
+ * The `snap_openWebSocket` method implementation.
+ *
+ * @param req - The JSON-RPC request object.
+ * @param res - The JSON-RPC response object.
+ * @param _next - The `json-rpc-engine` "next" callback. Not used by this function.
+ * @param end - The `json-rpc-engine` "end" callback.
+ * @param hooks - The RPC method hooks.
+ * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.
+ * @param hooks.openWebSocket - The function to open a WebSocket.
+ * @returns Nothing.
+ */
+declare function openWebSocketImplementation(req: JsonRpcRequest<OpenWebSocketParameters>, res: PendingJsonRpcResponse<OpenWebSocketResult>, _next: unknown, end: JsonRpcEngineEndCallback, { hasPermission, openWebSocket }: OpenWebSocketMethodHooks): Promise<void>;
 export {};
 //# sourceMappingURL=openWebSocket.d.cts.map

package/dist/permitted/openWebSocket.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"openWebSocket.d.cts","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wCAAwC;AAE9E,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,4BAA4B;AAC7B,OAAO,EAAO,KAAK,aAAa,EAAE,8BAA8B;AAmBhE,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,CAAC;AAEF,QAAA,MAAM,6BAA6B;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,aAAa,CACjD,OAAO,6BAA6B,EACpC,mBAAmB,CACpB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CACvD,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,CAKpB,CAAC"}
+{"version":3,"file":"openWebSocket.d.cts","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kCAAkC;AAG1E,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,4BAA4B;AAC7B,OAAO,EAAO,KAAK,aAAa,EAAE,8BAA8B;AAShE,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB;AAG9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAiB;AASlD,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,CAAC;AAEF,QAAA,MAAM,6BAA6B;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,aAAa,CACjD,OAAO,6BAA6B,EACpC,mBAAmB,CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,oBAAoB;;;;CAQhC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,iBAAe,2BAA2B,CACxC,GAAG,EAAE,cAAc,CAAC,uBAAuB,CAAC,EAC5C,GAAG,EAAE,sBAAsB,CAAC,mBAAmB,CAAC,EAChD,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,wBAAwB,EAC7B,EAAE,aAAa,EAAE,aAAa,EAAE,EAAE,wBAAwB,GACzD,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/permitted/openWebSocket.d.mts

@@ -1,6 +1,8 @@
-import type { PermittedHandlerExport } from "@metamask/permission-controller";
-import { type OpenWebSocketParams, type OpenWebSocketResult } from "@metamask/snaps-sdk";
+import type { JsonRpcEngineEndCallback } from "@metamask/json-rpc-engine";
+import { type JsonRpcRequest, type OpenWebSocketParams, type OpenWebSocketResult } from "@metamask/snaps-sdk";
 import { type InferMatching } from "@metamask/snaps-utils";
+import type { PendingJsonRpcResponse } from "@metamask/utils";
+import type { MethodHooksObject } from "../utils.mjs";
 export type OpenWebSocketMethodHooks = {
     hasPermission: (permissionName: string) => boolean;
     openWebSocket: (url: string, protocols?: string[]) => Promise<string>;
@@ -14,8 +16,68 @@ declare const OpenWebSocketParametersStruct: import("@metamask/superstruct").Str
 }>;
 export type OpenWebSocketParameters = InferMatching<typeof OpenWebSocketParametersStruct, OpenWebSocketParams>;
 /**
- * Handler for the `snap_openWebSocket` method.
+ * Open a WebSocket connection to the specified URL with optional protocols.
+ *
+ * Note: This method is only available to snaps that have the
+ * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)
+ * permission.
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "endowment:network-access": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of
+ * // the Snap:
+ * snap.request({
+ *   method: 'snap_openWebSocket',
+ *   params: {
+ *     url: 'wss://example.com/socket',
+ *     protocols: ['protocol1', 'protocol2'], // Optional
+ *   },
+ * });
+ *
+ * // Listen for events from the WebSocket connection in the `onWebSocketEvent`
+ * // handler of the Snap:
+ * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {
+ *   switch (event.type) {
+ *     case 'open':
+ *       console.log(`WebSocket connection opened with origin ${event.origin}`);
+ *       break;
+ *     case 'message':
+ *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);
+ *       break;
+ *     case 'close':
+ *       console.log(`WebSocket connection closed with origin ${event.origin}`);
+ *       break;
+ *     case 'error':
+ *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);
+ *       break;
+ *   }
+ * };
+ * ```
  */
-export declare const openWebSocketHandler: PermittedHandlerExport<OpenWebSocketMethodHooks, OpenWebSocketParams, OpenWebSocketResult>;
+export declare const openWebSocketHandler: {
+    methodNames: ["snap_openWebSocket"];
+    implementation: typeof openWebSocketImplementation;
+    hookNames: MethodHooksObject<OpenWebSocketMethodHooks>;
+};
+/**
+ * The `snap_openWebSocket` method implementation.
+ *
+ * @param req - The JSON-RPC request object.
+ * @param res - The JSON-RPC response object.
+ * @param _next - The `json-rpc-engine` "next" callback. Not used by this function.
+ * @param end - The `json-rpc-engine` "end" callback.
+ * @param hooks - The RPC method hooks.
+ * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.
+ * @param hooks.openWebSocket - The function to open a WebSocket.
+ * @returns Nothing.
+ */
+declare function openWebSocketImplementation(req: JsonRpcRequest<OpenWebSocketParameters>, res: PendingJsonRpcResponse<OpenWebSocketResult>, _next: unknown, end: JsonRpcEngineEndCallback, { hasPermission, openWebSocket }: OpenWebSocketMethodHooks): Promise<void>;
 export {};
 //# sourceMappingURL=openWebSocket.d.mts.map

package/dist/permitted/openWebSocket.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"openWebSocket.d.mts","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,wCAAwC;AAE9E,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,4BAA4B;AAC7B,OAAO,EAAO,KAAK,aAAa,EAAE,8BAA8B;AAmBhE,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,CAAC;AAEF,QAAA,MAAM,6BAA6B;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,aAAa,CACjD,OAAO,6BAA6B,EACpC,mBAAmB,CACpB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,sBAAsB,CACvD,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,CAKpB,CAAC"}
+{"version":3,"file":"openWebSocket.d.mts","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,kCAAkC;AAG1E,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,4BAA4B;AAC7B,OAAO,EAAO,KAAK,aAAa,EAAE,8BAA8B;AAShE,OAAO,KAAK,EAAE,sBAAsB,EAAE,wBAAwB;AAG9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAiB;AASlD,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,CAAC;AAEF,QAAA,MAAM,6BAA6B;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,aAAa,CACjD,OAAO,6BAA6B,EACpC,mBAAmB,CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,oBAAoB;;;;CAQhC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,iBAAe,2BAA2B,CACxC,GAAG,EAAE,cAAc,CAAC,uBAAuB,CAAC,EAC5C,GAAG,EAAE,sBAAsB,CAAC,mBAAmB,CAAC,EAChD,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,wBAAwB,EAC7B,EAAE,aAAa,EAAE,aAAa,EAAE,EAAE,wBAAwB,GACzD,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/permitted/openWebSocket.mjs

@@ -3,6 +3,7 @@ import { literal, union } from "@metamask/snaps-sdk";
 import { uri } from "@metamask/snaps-utils";
 import { create, object, array, string, optional, StructError } from "@metamask/superstruct";
 import { SnapEndowments } from "../endowments/index.mjs";
+const methodName = 'snap_openWebSocket';
 const hookNames = {
     hasPermission: true,
     openWebSocket: true,
@@ -12,10 +13,53 @@ const OpenWebSocketParametersStruct = object({
     protocols: optional(array(string())),
 });
 /**
- * Handler for the `snap_openWebSocket` method.
+ * Open a WebSocket connection to the specified URL with optional protocols.
+ *
+ * Note: This method is only available to snaps that have the
+ * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)
+ * permission.
+ *
+ * @example
+ * ```json name="Manifest"
+ * {
+ *   "initialPermissions": {
+ *     "endowment:network-access": {}
+ *   }
+ * }
+ * ```
+ * ```ts name="Usage"
+ * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of
+ * // the Snap:
+ * snap.request({
+ *   method: 'snap_openWebSocket',
+ *   params: {
+ *     url: 'wss://example.com/socket',
+ *     protocols: ['protocol1', 'protocol2'], // Optional
+ *   },
+ * });
+ *
+ * // Listen for events from the WebSocket connection in the `onWebSocketEvent`
+ * // handler of the Snap:
+ * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {
+ *   switch (event.type) {
+ *     case 'open':
+ *       console.log(`WebSocket connection opened with origin ${event.origin}`);
+ *       break;
+ *     case 'message':
+ *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);
+ *       break;
+ *     case 'close':
+ *       console.log(`WebSocket connection closed with origin ${event.origin}`);
+ *       break;
+ *     case 'error':
+ *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);
+ *       break;
+ *   }
+ * };
+ * ```
  */
 export const openWebSocketHandler = {
-    methodNames: ['snap_openWebSocket'],
+    methodNames: [methodName],
     implementation: openWebSocketImplementation,
     hookNames,
 };

package/dist/permitted/openWebSocket.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"openWebSocket.mjs","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B;AACjE,OAAO,EACL,OAAO,EACP,KAAK,EAIN,4BAA4B;AAC7B,OAAO,EAAE,GAAG,EAAsB,8BAA8B;AAChE,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACZ,8BAA8B;AAG/B,OAAO,EAAE,cAAc,EAAE,gCAAsB;AAG/C,MAAM,SAAS,GAAgD;IAC7D,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;CACpB,CAAC;AAOF,MAAM,6BAA6B,GAAG,MAAM,CAAC;IAC3C,GAAG,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;CACrC,CAAC,CAAC;AAOH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAI7B;IACF,WAAW,EAAE,CAAC,oBAAoB,CAAC;IACnC,cAAc,EAAE,2BAA2B;IAC3C,SAAS;CACV,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,2BAA2B,CACxC,GAA4C,EAC5C,GAAgD,EAChD,KAAc,EACd,GAA6B,EAC7B,EAAE,aAAa,EAAE,aAAa,EAA4B;IAE1D,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtD,GAAG,CAAC,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,MAAM,SAAS,CAAC,aAAa,CAAC;gBAC5B,OAAO,EAAE,mBAAmB,KAAK,CAAC,OAAO,GAAG;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,0BAA0B;QAC1B,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors, rpcErrors } from '@metamask/rpc-errors';\nimport {\n  literal,\n  union,\n  type JsonRpcRequest,\n  type OpenWebSocketParams,\n  type OpenWebSocketResult,\n} from '@metamask/snaps-sdk';\nimport { uri, type InferMatching } from '@metamask/snaps-utils';\nimport {\n  create,\n  object,\n  array,\n  string,\n  optional,\n  StructError,\n} from '@metamask/superstruct';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { SnapEndowments } from '../endowments';\nimport type { MethodHooksObject } from '../utils';\n\nconst hookNames: MethodHooksObject<OpenWebSocketMethodHooks> = {\n  hasPermission: true,\n  openWebSocket: true,\n};\n\nexport type OpenWebSocketMethodHooks = {\n  hasPermission: (permissionName: string) => boolean;\n  openWebSocket: (url: string, protocols?: string[]) => Promise<string>;\n};\n\nconst OpenWebSocketParametersStruct = object({\n  url: uri({ protocol: union([literal('wss:'), literal('ws:')]) }),\n  protocols: optional(array(string())),\n});\n\nexport type OpenWebSocketParameters = InferMatching<\n  typeof OpenWebSocketParametersStruct,\n  OpenWebSocketParams\n>;\n\n/**\n * Handler for the `snap_openWebSocket` method.\n */\nexport const openWebSocketHandler: PermittedHandlerExport<\n  OpenWebSocketMethodHooks,\n  OpenWebSocketParams,\n  OpenWebSocketResult\n> = {\n  methodNames: ['snap_openWebSocket'],\n  implementation: openWebSocketImplementation,\n  hookNames,\n};\n\n/**\n * The `snap_openWebSocket` method implementation.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.\n * @param hooks.openWebSocket - The function to open a WebSocket.\n * @returns Nothing.\n */\nasync function openWebSocketImplementation(\n  req: JsonRpcRequest<OpenWebSocketParameters>,\n  res: PendingJsonRpcResponse<OpenWebSocketResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { hasPermission, openWebSocket }: OpenWebSocketMethodHooks,\n): Promise<void> {\n  if (!hasPermission(SnapEndowments.NetworkAccess)) {\n    return end(providerErrors.unauthorized());\n  }\n\n  const { params } = req;\n\n  try {\n    const { url, protocols } = getValidatedParams(params);\n    res.result = await openWebSocket(url, protocols);\n  } catch (error) {\n    return end(error);\n  }\n\n  return end();\n}\n\n/**\n * Validates the parameters for the snap_openWebSocket method.\n *\n * @param params - Parameters to validate.\n * @returns Validated parameters.\n * @throws Throws RPC error if validation fails.\n */\nfunction getValidatedParams(params: unknown): OpenWebSocketParameters {\n  try {\n    return create(params, OpenWebSocketParametersStruct);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid params: ${error.message}.`,\n      });\n    }\n    /* istanbul ignore next */\n    throw rpcErrors.internal();\n  }\n}\n"]}
+{"version":3,"file":"openWebSocket.mjs","sourceRoot":"","sources":["../../src/permitted/openWebSocket.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B;AACjE,OAAO,EACL,OAAO,EACP,KAAK,EAIN,4BAA4B;AAC7B,OAAO,EAAE,GAAG,EAAsB,8BAA8B;AAChE,OAAO,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACZ,8BAA8B;AAG/B,OAAO,EAAE,cAAc,EAAE,gCAAsB;AAG/C,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAExC,MAAM,SAAS,GAAgD;IAC7D,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;CACpB,CAAC;AAOF,MAAM,6BAA6B,GAAG,MAAM,CAAC;IAC3C,GAAG,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;CACrC,CAAC,CAAC;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,WAAW,EAAE,CAAC,UAAU,CAAU;IAClC,cAAc,EAAE,2BAA2B;IAC3C,SAAS;CAKV,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,2BAA2B,CACxC,GAA4C,EAC5C,GAAgD,EAChD,KAAc,EACd,GAA6B,EAC7B,EAAE,aAAa,EAAE,aAAa,EAA4B;IAE1D,IAAI,CAAC,aAAa,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;QACjD,OAAO,GAAG,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACtD,GAAG,CAAC,MAAM,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,MAAe;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,MAAM,SAAS,CAAC,aAAa,CAAC;gBAC5B,OAAO,EAAE,mBAAmB,KAAK,CAAC,OAAO,GAAG;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,0BAA0B;QAC1B,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type { PermittedHandlerExport } from '@metamask/permission-controller';\nimport { providerErrors, rpcErrors } from '@metamask/rpc-errors';\nimport {\n  literal,\n  union,\n  type JsonRpcRequest,\n  type OpenWebSocketParams,\n  type OpenWebSocketResult,\n} from '@metamask/snaps-sdk';\nimport { uri, type InferMatching } from '@metamask/snaps-utils';\nimport {\n  create,\n  object,\n  array,\n  string,\n  optional,\n  StructError,\n} from '@metamask/superstruct';\nimport type { PendingJsonRpcResponse } from '@metamask/utils';\n\nimport { SnapEndowments } from '../endowments';\nimport type { MethodHooksObject } from '../utils';\n\nconst methodName = 'snap_openWebSocket';\n\nconst hookNames: MethodHooksObject<OpenWebSocketMethodHooks> = {\n  hasPermission: true,\n  openWebSocket: true,\n};\n\nexport type OpenWebSocketMethodHooks = {\n  hasPermission: (permissionName: string) => boolean;\n  openWebSocket: (url: string, protocols?: string[]) => Promise<string>;\n};\n\nconst OpenWebSocketParametersStruct = object({\n  url: uri({ protocol: union([literal('wss:'), literal('ws:')]) }),\n  protocols: optional(array(string())),\n});\n\nexport type OpenWebSocketParameters = InferMatching<\n  typeof OpenWebSocketParametersStruct,\n  OpenWebSocketParams\n>;\n\n/**\n * Open a WebSocket connection to the specified URL with optional protocols.\n *\n * Note: This method is only available to snaps that have the\n * [`endowment:network-access`](https://docs.metamask.io/snaps/features/network-access/)\n * permission.\n *\n * @example\n * ```json name=\"Manifest\"\n * {\n *   \"initialPermissions\": {\n *     \"endowment:network-access\": {}\n *   }\n * }\n * ```\n * ```ts name=\"Usage\"\n * // Open a connection to a WebSocket server, e.g., in the JSON-RPC handler of\n * // the Snap:\n * snap.request({\n *   method: 'snap_openWebSocket',\n *   params: {\n *     url: 'wss://example.com/socket',\n *     protocols: ['protocol1', 'protocol2'], // Optional\n *   },\n * });\n *\n * // Listen for events from the WebSocket connection in the `onWebSocketEvent`\n * // handler of the Snap:\n * export const onWebSocketEvent: OnWebSocketEventHandler = async ({ event }) => {\n *   switch (event.type) {\n *     case 'open':\n *       console.log(`WebSocket connection opened with origin ${event.origin}`);\n *       break;\n *     case 'message':\n *       console.log(`WebSocket message received from origin ${event.origin}:`, event.data);\n *       break;\n *     case 'close':\n *       console.log(`WebSocket connection closed with origin ${event.origin}`);\n *       break;\n *     case 'error':\n *       console.error(`WebSocket error from origin ${event.origin}:`, event.error);\n *       break;\n *   }\n * };\n * ```\n */\nexport const openWebSocketHandler = {\n  methodNames: [methodName] as const,\n  implementation: openWebSocketImplementation,\n  hookNames,\n} satisfies PermittedHandlerExport<\n  OpenWebSocketMethodHooks,\n  OpenWebSocketParams,\n  OpenWebSocketResult\n>;\n\n/**\n * The `snap_openWebSocket` method implementation.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.hasPermission - The function to check if a snap has the `endowment:network-access` permission.\n * @param hooks.openWebSocket - The function to open a WebSocket.\n * @returns Nothing.\n */\nasync function openWebSocketImplementation(\n  req: JsonRpcRequest<OpenWebSocketParameters>,\n  res: PendingJsonRpcResponse<OpenWebSocketResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { hasPermission, openWebSocket }: OpenWebSocketMethodHooks,\n): Promise<void> {\n  if (!hasPermission(SnapEndowments.NetworkAccess)) {\n    return end(providerErrors.unauthorized());\n  }\n\n  const { params } = req;\n\n  try {\n    const { url, protocols } = getValidatedParams(params);\n    res.result = await openWebSocket(url, protocols);\n  } catch (error) {\n    return end(error);\n  }\n\n  return end();\n}\n\n/**\n * Validates the parameters for the snap_openWebSocket method.\n *\n * @param params - Parameters to validate.\n * @returns Validated parameters.\n * @throws Throws RPC error if validation fails.\n */\nfunction getValidatedParams(params: unknown): OpenWebSocketParameters {\n  try {\n    return create(params, OpenWebSocketParametersStruct);\n  } catch (error) {\n    if (error instanceof StructError) {\n      throw rpcErrors.invalidParams({\n        message: `Invalid params: ${error.message}.`,\n      });\n    }\n    /* istanbul ignore next */\n    throw rpcErrors.internal();\n  }\n}\n"]}

package/dist/permitted/requestSnaps.cjs

@@ -6,16 +6,39 @@ const snaps_utils_1 = require("@metamask/snaps-utils");
 const utils_1 = require("@metamask/utils");
 const async_mutex_1 = require("async-mutex");
 const invokeSnap_1 = require("../restricted/invokeSnap.cjs");
+const methodName = 'wallet_requestSnaps';
 const hookNames = {
     installSnaps: true,
     requestPermissions: true,
     getPermissions: true,
 };
 /**
- * `wallet_requestSnaps` installs the requested Snaps and requests permission to use them if necessary.
+ * Request permission for a dapp to communicate with the specified Snaps and
+ * attempt to install them if they're not already installed.
+ *
+ * If the Snap version range is specified, MetaMask attempts to install a
+ * version of the Snap that satisfies the range. If a compatible version of the
+ * Snap is already installed, the request succeeds. If an incompatible version
+ * is installed, MetaMask attempts to update the Snap to the latest version that
+ * satisfies the range. The request succeeds if the Snap is successfully
+ * installed.
+ *
+ * If the installation of any Snap fails, or the user rejects the installation
+ * or permission request, this method returns the error that caused the failure.
+ *
+ * @example
+ * ```ts
+ * const result = await snap.request({
+ *   method: 'wallet_requestSnaps',
+ *   params: {
+ *     'npm:@metamask/example-snap': {},
+ *     'npm:@metamask/another-snap': { version: '1.2.3' },
+ *   },
+ * });
+ * ```
  */
 exports.requestSnapsHandler = {
-    methodNames: ['wallet_requestSnaps'],
+    methodNames: [methodName],
     implementation: requestSnapsImplementation,
     hookNames,
 };

package/dist/permitted/requestSnaps.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requestSnaps.cjs","sourceRoot":"","sources":["../../src/permitted/requestSnaps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type {\n  PermissionConstraint,\n  RequestedPermissions,\n  Caveat,\n  PermittedHandlerExport,\n} from '@metamask/permission-controller';\nimport { rpcErrors } from '@metamask/rpc-errors';\nimport type {\n  RequestSnapsParams,\n  RequestSnapsResult,\n} from '@metamask/snaps-sdk';\nimport type { SnapsPermissionRequest } from '@metamask/snaps-utils';\nimport {\n  SnapCaveatType,\n  verifyRequestedSnapPermissions,\n} from '@metamask/snaps-utils';\nimport type {\n  JsonRpcRequest,\n  PendingJsonRpcResponse,\n  Json,\n} from '@metamask/utils';\nimport { hasProperty, isObject } from '@metamask/utils';\nimport { Mutex } from 'async-mutex';\n\nimport { WALLET_SNAP_PERMISSION_KEY } from '../restricted/invokeSnap';\nimport type { MethodHooksObject } from '../utils';\n\nconst hookNames: MethodHooksObject<RequestSnapsHooks> = {\n  installSnaps: true,\n  requestPermissions: true,\n  getPermissions: true,\n};\n\n/**\n * `wallet_requestSnaps` installs the requested Snaps and requests permission to use them if necessary.\n */\nexport const requestSnapsHandler: PermittedHandlerExport<\n  RequestSnapsHooks,\n  RequestSnapsParams,\n  RequestSnapsResult\n> = {\n  methodNames: ['wallet_requestSnaps'],\n  implementation: requestSnapsImplementation,\n  hookNames,\n};\n\nexport type RequestSnapsHooks = {\n  /**\n   * Installs the requested snaps if they are permitted.\n   */\n  installSnaps: (\n    requestedSnaps: RequestSnapsParams,\n  ) => Promise<RequestSnapsResult>;\n\n  /**\n   * Initiates a permission request for the requesting origin.\n   *\n   * @returns The result of the permissions request.\n   */\n  requestPermissions: (\n    permissions: RequestedPermissions,\n  ) => Promise<\n    [\n      Record<string, PermissionConstraint>,\n      { data: Record<string, unknown>; id: string; origin: string },\n    ]\n  >;\n\n  /**\n   * Gets the current permissions for the requesting origin.\n   *\n   * @returns The current permissions of the requesting origin.\n   */\n  getPermissions: () => Promise<\n    Record<string, PermissionConstraint> | undefined\n  >;\n};\n\n/**\n * Checks whether an origin has existing `wallet_snap` permission and\n * whether or not it has the requested snapIds caveat.\n *\n * @param existingPermissions - The existing permissions for the origin.\n * @param requestedSnaps - The requested snaps.\n * @returns True if the existing permissions satisfy the requested snaps, otherwise false.\n */\nexport function hasRequestedSnaps(\n  existingPermissions: Record<string, PermissionConstraint>,\n  requestedSnaps: Record<string, unknown>,\n): boolean {\n  const snapIdCaveat = existingPermissions[\n    WALLET_SNAP_PERMISSION_KEY\n  ]?.caveats?.find(\n    (caveat: Caveat<string, Json>) => caveat.type === SnapCaveatType.SnapIds,\n  );\n\n  const permittedSnaps = snapIdCaveat?.value;\n  if (isObject(permittedSnaps)) {\n    return Object.keys(requestedSnaps).every((requestedSnap) =>\n      hasProperty(permittedSnaps, requestedSnap),\n    );\n  }\n  return false;\n}\n\n/**\n * Constructs a valid permission request with merged caveats based on existing permissions\n * and the requested snaps.\n *\n * @param existingPermissions - The existing permissions for the origin.\n * @param requestedPermissions - The permission request passed into `requestPermissions`.\n * @returns `requestedPermissions`.\n */\nexport function getSnapPermissionsRequest(\n  existingPermissions: Record<string, PermissionConstraint>,\n  requestedPermissions: unknown,\n): SnapsPermissionRequest {\n  verifyRequestedSnapPermissions(requestedPermissions);\n\n  if (!existingPermissions[WALLET_SNAP_PERMISSION_KEY]) {\n    return requestedPermissions;\n  }\n\n  const snapIdCaveat = existingPermissions[\n    WALLET_SNAP_PERMISSION_KEY\n  ].caveats?.find(\n    (caveat: Caveat<string, Json>) => caveat.type === SnapCaveatType.SnapIds,\n  );\n\n  const permittedSnaps = (snapIdCaveat?.value as Record<string, Json>) ?? {};\n\n  const requestedSnaps =\n    requestedPermissions[WALLET_SNAP_PERMISSION_KEY].caveats[0].value;\n\n  const snapIdSet = new Set([\n    ...Object.keys(permittedSnaps),\n    ...Object.keys(requestedSnaps),\n  ]);\n\n  const mergedCaveatValue = [...snapIdSet].reduce<Record<string, Json>>(\n    (request, snapId) => {\n      request[snapId] = requestedSnaps[snapId] ?? permittedSnaps[snapId];\n      return request;\n    },\n    {},\n  );\n\n  requestedPermissions[WALLET_SNAP_PERMISSION_KEY].caveats[0].value =\n    mergedCaveatValue;\n\n  return requestedPermissions;\n}\n\nconst mutexes = new Map();\n\n/**\n * Get the corresponding Snap installation mutex for a given origin.\n *\n * @param origin - The origin of the request.\n * @returns A mutex for that specific origin.\n */\nfunction getMutex(origin: string) {\n  if (!mutexes.has(origin)) {\n    mutexes.set(origin, new Mutex());\n  }\n  return mutexes.get(origin);\n}\n\n/**\n * The `wallet_requestSnaps` method implementation.\n * Tries to install the requested snaps and adds them to the JSON-RPC response.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this\n * function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.installSnaps - A function that tries to install a given snap, prompting the user if necessary.\n * @param hooks.requestPermissions - A function that requests permissions on\n * behalf of a subject.\n * @param hooks.getPermissions - A function that gets the current permissions.\n * @returns A promise that resolves once the JSON-RPC response has been modified.\n * @throws If the params are invalid.\n */\nasync function requestSnapsImplementation(\n  req: JsonRpcRequest<RequestSnapsParams>,\n  res: PendingJsonRpcResponse<RequestSnapsResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { installSnaps, requestPermissions, getPermissions }: RequestSnapsHooks,\n): Promise<void> {\n  const requestedSnaps = req.params;\n  if (!isObject(requestedSnaps)) {\n    return end(\n      rpcErrors.invalidParams({\n        message: '\"params\" must be an object.',\n      }),\n    );\n  }\n\n  if (Object.keys(requestedSnaps).length === 0) {\n    return end(\n      rpcErrors.invalidParams({\n        message: 'Request must have at least one requested snap.',\n      }),\n    );\n  }\n\n  // We expect the MM middleware stack to always add the origin to requests\n  const { origin } = req as JsonRpcRequest & { origin: string };\n\n  const mutex = getMutex(origin);\n\n  // Process requests sequentially for each origin as permissions need to be merged\n  // for every request.\n  await mutex.runExclusive(async () => {\n    try {\n      const requestedPermissions = {\n        [WALLET_SNAP_PERMISSION_KEY]: {\n          caveats: [{ type: SnapCaveatType.SnapIds, value: requestedSnaps }],\n        },\n      } as RequestedPermissions;\n      const existingPermissions = await getPermissions();\n\n      if (!existingPermissions) {\n        const [, metadata] = await requestPermissions(requestedPermissions);\n        res.result = metadata.data[\n          WALLET_SNAP_PERMISSION_KEY\n        ] as RequestSnapsResult;\n      } else if (hasRequestedSnaps(existingPermissions, requestedSnaps)) {\n        res.result = await installSnaps(requestedSnaps);\n      } else {\n        const mergedPermissionsRequest = getSnapPermissionsRequest(\n          existingPermissions,\n          requestedPermissions,\n        );\n\n        const [, metadata] = await requestPermissions(mergedPermissionsRequest);\n        res.result = metadata.data[\n          WALLET_SNAP_PERMISSION_KEY\n        ] as RequestSnapsResult;\n      }\n    } catch (error) {\n      res.error = error;\n    }\n  });\n\n  return end();\n}\n"]}
+{"version":3,"file":"requestSnaps.cjs","sourceRoot":"","sources":["../../src/permitted/requestSnaps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';\nimport type {\n  PermissionConstraint,\n  RequestedPermissions,\n  Caveat,\n  PermittedHandlerExport,\n} from '@metamask/permission-controller';\nimport { rpcErrors } from '@metamask/rpc-errors';\nimport type {\n  RequestSnapsParams,\n  RequestSnapsResult,\n} from '@metamask/snaps-sdk';\nimport type { SnapsPermissionRequest } from '@metamask/snaps-utils';\nimport {\n  SnapCaveatType,\n  verifyRequestedSnapPermissions,\n} from '@metamask/snaps-utils';\nimport type {\n  JsonRpcRequest,\n  PendingJsonRpcResponse,\n  Json,\n} from '@metamask/utils';\nimport { hasProperty, isObject } from '@metamask/utils';\nimport { Mutex } from 'async-mutex';\n\nimport { WALLET_SNAP_PERMISSION_KEY } from '../restricted/invokeSnap';\nimport type { MethodHooksObject } from '../utils';\n\nconst methodName = 'wallet_requestSnaps';\n\nconst hookNames: MethodHooksObject<RequestSnapsHooks> = {\n  installSnaps: true,\n  requestPermissions: true,\n  getPermissions: true,\n};\n\n/**\n * Request permission for a dapp to communicate with the specified Snaps and\n * attempt to install them if they're not already installed.\n *\n * If the Snap version range is specified, MetaMask attempts to install a\n * version of the Snap that satisfies the range. If a compatible version of the\n * Snap is already installed, the request succeeds. If an incompatible version\n * is installed, MetaMask attempts to update the Snap to the latest version that\n * satisfies the range. The request succeeds if the Snap is successfully\n * installed.\n *\n * If the installation of any Snap fails, or the user rejects the installation\n * or permission request, this method returns the error that caused the failure.\n *\n * @example\n * ```ts\n * const result = await snap.request({\n *   method: 'wallet_requestSnaps',\n *   params: {\n *     'npm:@metamask/example-snap': {},\n *     'npm:@metamask/another-snap': { version: '1.2.3' },\n *   },\n * });\n * ```\n */\nexport const requestSnapsHandler = {\n  methodNames: [methodName] as const,\n  implementation: requestSnapsImplementation,\n  hookNames,\n} satisfies PermittedHandlerExport<\n  RequestSnapsHooks,\n  RequestSnapsParams,\n  RequestSnapsResult\n>;\n\nexport type RequestSnapsHooks = {\n  /**\n   * Installs the requested snaps if they are permitted.\n   */\n  installSnaps: (\n    requestedSnaps: RequestSnapsParams,\n  ) => Promise<RequestSnapsResult>;\n\n  /**\n   * Initiates a permission request for the requesting origin.\n   *\n   * @returns The result of the permissions request.\n   */\n  requestPermissions: (\n    permissions: RequestedPermissions,\n  ) => Promise<\n    [\n      Record<string, PermissionConstraint>,\n      { data: Record<string, unknown>; id: string; origin: string },\n    ]\n  >;\n\n  /**\n   * Gets the current permissions for the requesting origin.\n   *\n   * @returns The current permissions of the requesting origin.\n   */\n  getPermissions: () => Promise<\n    Record<string, PermissionConstraint> | undefined\n  >;\n};\n\n/**\n * Checks whether an origin has existing `wallet_snap` permission and\n * whether or not it has the requested snapIds caveat.\n *\n * @param existingPermissions - The existing permissions for the origin.\n * @param requestedSnaps - The requested snaps.\n * @returns True if the existing permissions satisfy the requested snaps, otherwise false.\n */\nexport function hasRequestedSnaps(\n  existingPermissions: Record<string, PermissionConstraint>,\n  requestedSnaps: Record<string, unknown>,\n): boolean {\n  const snapIdCaveat = existingPermissions[\n    WALLET_SNAP_PERMISSION_KEY\n  ]?.caveats?.find(\n    (caveat: Caveat<string, Json>) => caveat.type === SnapCaveatType.SnapIds,\n  );\n\n  const permittedSnaps = snapIdCaveat?.value;\n  if (isObject(permittedSnaps)) {\n    return Object.keys(requestedSnaps).every((requestedSnap) =>\n      hasProperty(permittedSnaps, requestedSnap),\n    );\n  }\n  return false;\n}\n\n/**\n * Constructs a valid permission request with merged caveats based on existing permissions\n * and the requested snaps.\n *\n * @param existingPermissions - The existing permissions for the origin.\n * @param requestedPermissions - The permission request passed into `requestPermissions`.\n * @returns `requestedPermissions`.\n */\nexport function getSnapPermissionsRequest(\n  existingPermissions: Record<string, PermissionConstraint>,\n  requestedPermissions: unknown,\n): SnapsPermissionRequest {\n  verifyRequestedSnapPermissions(requestedPermissions);\n\n  if (!existingPermissions[WALLET_SNAP_PERMISSION_KEY]) {\n    return requestedPermissions;\n  }\n\n  const snapIdCaveat = existingPermissions[\n    WALLET_SNAP_PERMISSION_KEY\n  ].caveats?.find(\n    (caveat: Caveat<string, Json>) => caveat.type === SnapCaveatType.SnapIds,\n  );\n\n  const permittedSnaps = (snapIdCaveat?.value as Record<string, Json>) ?? {};\n\n  const requestedSnaps =\n    requestedPermissions[WALLET_SNAP_PERMISSION_KEY].caveats[0].value;\n\n  const snapIdSet = new Set([\n    ...Object.keys(permittedSnaps),\n    ...Object.keys(requestedSnaps),\n  ]);\n\n  const mergedCaveatValue = [...snapIdSet].reduce<Record<string, Json>>(\n    (request, snapId) => {\n      request[snapId] = requestedSnaps[snapId] ?? permittedSnaps[snapId];\n      return request;\n    },\n    {},\n  );\n\n  requestedPermissions[WALLET_SNAP_PERMISSION_KEY].caveats[0].value =\n    mergedCaveatValue;\n\n  return requestedPermissions;\n}\n\nconst mutexes = new Map();\n\n/**\n * Get the corresponding Snap installation mutex for a given origin.\n *\n * @param origin - The origin of the request.\n * @returns A mutex for that specific origin.\n */\nfunction getMutex(origin: string) {\n  if (!mutexes.has(origin)) {\n    mutexes.set(origin, new Mutex());\n  }\n  return mutexes.get(origin);\n}\n\n/**\n * The `wallet_requestSnaps` method implementation.\n * Tries to install the requested snaps and adds them to the JSON-RPC response.\n *\n * @param req - The JSON-RPC request object.\n * @param res - The JSON-RPC response object.\n * @param _next - The `json-rpc-engine` \"next\" callback. Not used by this\n * function.\n * @param end - The `json-rpc-engine` \"end\" callback.\n * @param hooks - The RPC method hooks.\n * @param hooks.installSnaps - A function that tries to install a given snap, prompting the user if necessary.\n * @param hooks.requestPermissions - A function that requests permissions on\n * behalf of a subject.\n * @param hooks.getPermissions - A function that gets the current permissions.\n * @returns A promise that resolves once the JSON-RPC response has been modified.\n * @throws If the params are invalid.\n */\nasync function requestSnapsImplementation(\n  req: JsonRpcRequest<RequestSnapsParams>,\n  res: PendingJsonRpcResponse<RequestSnapsResult>,\n  _next: unknown,\n  end: JsonRpcEngineEndCallback,\n  { installSnaps, requestPermissions, getPermissions }: RequestSnapsHooks,\n): Promise<void> {\n  const requestedSnaps = req.params;\n  if (!isObject(requestedSnaps)) {\n    return end(\n      rpcErrors.invalidParams({\n        message: '\"params\" must be an object.',\n      }),\n    );\n  }\n\n  if (Object.keys(requestedSnaps).length === 0) {\n    return end(\n      rpcErrors.invalidParams({\n        message: 'Request must have at least one requested snap.',\n      }),\n    );\n  }\n\n  // We expect the MM middleware stack to always add the origin to requests\n  const { origin } = req as JsonRpcRequest & { origin: string };\n\n  const mutex = getMutex(origin);\n\n  // Process requests sequentially for each origin as permissions need to be merged\n  // for every request.\n  await mutex.runExclusive(async () => {\n    try {\n      const requestedPermissions = {\n        [WALLET_SNAP_PERMISSION_KEY]: {\n          caveats: [{ type: SnapCaveatType.SnapIds, value: requestedSnaps }],\n        },\n      } as RequestedPermissions;\n      const existingPermissions = await getPermissions();\n\n      if (!existingPermissions) {\n        const [, metadata] = await requestPermissions(requestedPermissions);\n        res.result = metadata.data[\n          WALLET_SNAP_PERMISSION_KEY\n        ] as RequestSnapsResult;\n      } else if (hasRequestedSnaps(existingPermissions, requestedSnaps)) {\n        res.result = await installSnaps(requestedSnaps);\n      } else {\n        const mergedPermissionsRequest = getSnapPermissionsRequest(\n          existingPermissions,\n          requestedPermissions,\n        );\n\n        const [, metadata] = await requestPermissions(mergedPermissionsRequest);\n        res.result = metadata.data[\n          WALLET_SNAP_PERMISSION_KEY\n        ] as RequestSnapsResult;\n      }\n    } catch (error) {\n      res.error = error;\n    }\n  });\n\n  return end();\n}\n"]}