Update RPC methods and endowment

packages/snaps-rpc-methods/src/endowments/devices.ts

@@ -60,7 +60,7 @@ export const devicesEndowmentBuilder = Object.freeze({
  * value of the namespaces object itself, as this is handled by the
  * `PermissionsController` when the permission is requested.
  *
- * @param permission - The permission to get the keyring namespaces from.
+ * @param permission - The permission to get the device IDs from.
  * @returns The device IDs, or `null` if the permission does not have a
  * device IDs caveat.
  */
@@ -83,7 +83,7 @@ export function getPermittedDeviceIds(
 }
 
 /**
- * Validate the cronjob specification values associated with a caveat.
+ * Validate the device IDs specification values associated with a caveat.
  * This validates that the value is a non-empty array with valid device
  * specification objects.
  *

packages/snaps-rpc-methods/src/permitted/listDevices.ts

@@ -0,0 +1,76 @@
+import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';
+import type { PermittedHandlerExport } from '@metamask/permission-controller';
+import type {
+  JsonRpcRequest,
+  ListDevicesParams,
+  ListDevicesResult,
+} from '@metamask/snaps-sdk';
+import type { InferMatching } from '@metamask/snaps-utils';
+import { array, literal, object, optional, union } from '@metamask/superstruct';
+import { assertStruct, type PendingJsonRpcResponse } from '@metamask/utils';
+
+import type { MethodHooksObject } from '../utils';
+
+const hookNames: MethodHooksObject<ListDevicesHooks> = {
+  listDevices: true,
+};
+
+export type ListDevicesHooks = {
+  /**
+   * A hook to list the available devices.
+   *
+   * @param params - The parameters for reading data from the device.
+   * @returns The data read from the device.
+   */
+  listDevices: (params: ListDevicesParams) => Promise<ListDevicesResult>;
+};
+
+export const listDevicesHandler: PermittedHandlerExport<
+  ListDevicesHooks,
+  ListDevicesParams,
+  ListDevicesResult
+> = {
+  methodNames: ['snap_listDevices'],
+  implementation: listDevicesImplementation,
+  hookNames,
+};
+
+const ListDevicesParametersStruct = object({
+  type: optional(union([literal('hid'), array(literal('hid'))])),
+});
+
+export type ListDevicesParameters = InferMatching<
+  typeof ListDevicesParametersStruct,
+  ListDevicesParams
+>;
+
+/**
+ * Handles the `snap_listDevices` method.
+ *
+ * @param request - The JSON-RPC request object.
+ * @param response - The JSON-RPC response object.
+ * @param _next - The `json-rpc-engine` "next" callback. Not used by this
+ * method.
+ * @param end - The `json-rpc-engine` "end" callback.
+ * @param hooks - The RPC method hooks.
+ * @param hooks.listDevices - The function to read data from a device.
+ * @returns Nothing.
+ */
+async function listDevicesImplementation(
+  request: JsonRpcRequest<ListDevicesParameters>,
+  response: PendingJsonRpcResponse<ListDevicesResult>,
+  _next: unknown,
+  end: JsonRpcEngineEndCallback,
+  { listDevices }: ListDevicesHooks,
+): Promise<void> {
+  const { params } = request;
+  assertStruct(params, ListDevicesParametersStruct);
+
+  try {
+    response.result = await listDevices(params);
+  } catch (error) {
+    return end(error);
+  }
+
+  return end();
+}

packages/snaps-rpc-methods/src/permitted/readDevice.ts

@@ -24,9 +24,10 @@ const hookNames: MethodHooksObject<ReadDeviceHooks> = {
 
 export type ReadDeviceHooks = {
   /**
-   * A hook to request a device.
+   * A hook to read data from a device.
    *
-   * @returns The requested device, or `null` if no device was provided.
+   * @param params - The parameters for reading data from the device.
+   * @returns The data read from the device.
    */
   readDevice: (params: ReadDeviceParams) => Promise<ReadDeviceResult>;
 };
@@ -62,7 +63,7 @@ export type ReadDeviceParameters = InferMatching<
  * method.
  * @param end - The `json-rpc-engine` "end" callback.
  * @param hooks - The RPC method hooks.
- * @param hooks.readDevice - The function to request a device.
+ * @param hooks.readDevice - The function to read data from a device.
  * @returns Nothing.
  */
 async function readDeviceImplementation(

packages/snaps-rpc-methods/src/permitted/requestDevice.ts

@@ -20,6 +20,7 @@ export type RequestDeviceHooks = {
   /**
    * A hook to request a device.
    *
+   * @param params - The parameters for requesting a device.
    * @returns The requested device, or `null` if no device was provided.
    */
   requestDevice: (params: RequestDeviceParams) => Promise<RequestDeviceResult>;

packages/snaps-rpc-methods/src/permitted/writeDevice.ts

@@ -22,9 +22,11 @@ const hookNames: MethodHooksObject<WriteDeviceHooks> = {
 
 export type WriteDeviceHooks = {
   /**
-   * A hook to request a device.
+   * A hook to write data to a device.
    *
-   * @returns The requested device, or `null` if no device was provided.
+   * @param params - The parameters for writing data to the device.
+   * @returns A promise that resolves when the data has been written to the
+   * device.
    */
   writeDevice: (params: WriteDeviceParams) => Promise<WriteDeviceResult>;
 };
@@ -60,7 +62,7 @@ export type WriteDeviceParameters = InferMatching<
  * method.
  * @param end - The `json-rpc-engine` "end" callback.
  * @param hooks - The RPC method hooks.
- * @param hooks.writeDevice - The function to request a device.
+ * @param hooks.writeDevice - The function to write data to a device.
  * @returns Nothing.
  */
 async function writeDeviceImplementation(

packages/snaps-sdk/src/types/methods/list-devices.ts

@@ -5,9 +5,9 @@ import type { Device, DeviceType } from '../device';
  */
 export type ListDevicesParams = {
   /**
-   * The type of the device to list. If not provided, all devices are listed.
+   * The type(s) of the device to list. If not provided, all devices are listed.
    */
-  type?: DeviceType;
+  type?: DeviceType | DeviceType[];
 };
 
 /**