feat: Include versions in snap_getClientStatus (#3724)

Include `clientVersion` and `platformVersion` in the response for
`snap_getClientStatus`. This is useful for ensuring backwards
compatibility in Snaps or enabling new features in certain versions.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Add `clientVersion` and `platformVersion` to `snap_getClientStatus`,
introduce `getVersion` hook, update types, simulation, and tests.
> 
> - **RPC Methods**:
> - Extend `snap_getClientStatus` to include `clientVersion` and
`platformVersion` in
`packages/snaps-rpc-methods/src/permitted/getClientStatus.ts`.
> - Add `getVersion` to `GetClientStatusHooks` and use
`getPlatformVersion()` in the implementation.
> - **SDK Types**:
> - Expand `GetClientStatusResult` to include `clientVersion` and
`platformVersion` in
`packages/snaps-sdk/src/types/methods/get-client-status.ts`.
> - **Simulation**:
> - Expose `getVersion` permitted hook (returns `"13.6.0-flask.0"`) in
`packages/snaps-simulation/src/simulation.ts` and add corresponding
test.
> - **Examples/Tests**:
> - Update example snap test to assert new fields in
`packages/examples/packages/client-status/src/index.test.ts` and add
`@metamask/snaps-utils` devDependency.
>   - Update `getClientStatus` tests to expect new fields.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
ed97239. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: FrederikBolding

packages/examples/packages/client-status/package.json

@@ -51,6 +51,7 @@
     "@metamask/auto-changelog": "^5.0.2",
     "@metamask/snaps-cli": "workspace:^",
     "@metamask/snaps-jest": "workspace:^",
+    "@metamask/snaps-utils": "workspace:^",
     "@swc/core": "1.11.31",
     "@swc/jest": "^0.2.38",
     "@types/node": "18.14.2",

packages/examples/packages/client-status/src/index.test.ts

@@ -1,5 +1,6 @@
 import { expect } from '@jest/globals';
 import { installSnap } from '@metamask/snaps-jest';
+import { getPlatformVersion } from '@metamask/snaps-utils';
 
 describe('onRpcRequest', () => {
   it('throws an error if the requested method does not exist', async () => {
@@ -31,6 +32,8 @@ describe('onRpcRequest', () => {
       expect(response).toRespondWith({
         locked: false,
         active: true,
+        clientVersion: '13.6.0-flask.0',
+        platformVersion: getPlatformVersion(),
       });
     });
   });

packages/snaps-rpc-methods/src/permitted/getClientStatus.test.ts

@@ -1,5 +1,6 @@
 import { JsonRpcEngine } from '@metamask/json-rpc-engine';
 import type { GetClientStatusResult } from '@metamask/snaps-sdk';
+import { getPlatformVersion } from '@metamask/snaps-utils';
 import type { PendingJsonRpcResponse } from '@metamask/utils';
 
 import { getClientStatusHandler } from './getClientStatus';
@@ -13,6 +14,7 @@ describe('snap_getClientStatus', () => {
         hookNames: {
           getIsLocked: true,
           getIsActive: true,
+          getVersion: true,
         },
       });
     });
@@ -24,9 +26,11 @@ describe('snap_getClientStatus', () => {
 
       const getIsLocked = jest.fn().mockReturnValue(true);
       const getIsActive = jest.fn().mockReturnValue(false);
+      const getVersion = jest.fn().mockReturnValue('13.6.0-flask.0');
       const hooks = {
         getIsLocked,
         getIsActive,
+        getVersion,
       };
 
       const engine = new JsonRpcEngine();
@@ -51,7 +55,12 @@ describe('snap_getClientStatus', () => {
       expect(response).toStrictEqual({
         jsonrpc: '2.0',
         id: 1,
-        result: { locked: true, active: false },
+        result: {
+          clientVersion: '13.6.0-flask.0',
+          platformVersion: getPlatformVersion(),
+          locked: true,
+          active: false,
+        },
       });
     });
   });

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

@@ -1,6 +1,7 @@
 import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';
 import type { PermittedHandlerExport } from '@metamask/permission-controller';
 import type { GetClientStatusResult } from '@metamask/snaps-sdk';
+import { getPlatformVersion } from '@metamask/snaps-utils';
 import type {
   JsonRpcParams,
   JsonRpcRequest,
@@ -12,6 +13,7 @@ import type { MethodHooksObject } from '../utils';
 const hookNames: MethodHooksObject<GetClientStatusHooks> = {
   getIsLocked: true,
   getIsActive: true,
+  getVersion: true,
 };
 
 /**
@@ -37,6 +39,11 @@ export type GetClientStatusHooks = {
    * @returns Whether the client is active or not.
    */
   getIsActive: () => boolean;
+
+  /**
+   * @returns The version string for the client.
+   */
+  getVersion: () => string;
 };
 
 /**
@@ -51,15 +58,21 @@ export type GetClientStatusHooks = {
  * @param hooks - The RPC method hooks.
  * @param hooks.getIsLocked - A function that returns whether the client is locked or not.
  * @param hooks.getIsActive - A function that returns whether the client is opened or not.
+ * @param hooks.getVersion - A function that returns the client version.
  * @returns Nothing.
  */
 async function getClientStatusImplementation(
   _request: JsonRpcRequest,
   response: PendingJsonRpcResponse<GetClientStatusResult>,
   _next: unknown,
   end: JsonRpcEngineEndCallback,
-  { getIsLocked, getIsActive }: GetClientStatusHooks,
+  { getIsLocked, getIsActive, getVersion }: GetClientStatusHooks,
 ): Promise<void> {
-  response.result = { locked: getIsLocked(), active: getIsActive() };
+  response.result = {
+    locked: getIsLocked(),
+    active: getIsActive(),
+    clientVersion: getVersion(),
+    platformVersion: getPlatformVersion(),
+  };
   return end();
 }

packages/snaps-sdk/src/types/methods/get-client-status.ts

@@ -10,4 +10,21 @@ export type GetClientStatusParams = never;
  *
  * It returns an object containing useful information about the client.
  */
-export type GetClientStatusResult = { locked: boolean; active: boolean };
+export type GetClientStatusResult = {
+  /**
+   * The semantic version of the client that the Snap is running in.
+   */
+  clientVersion: string;
+  /**
+   * The Snaps Platform version that the client is running.
+   */
+  platformVersion: string;
+  /**
+   * A boolean flag that indicates whether the client is locked or not.
+   */
+  locked: boolean;
+  /**
+   * A boolean flag that indicates whether the client is active or not.
+   */
+  active: boolean;
+};

packages/snaps-simulation/src/simulation.test.ts

@@ -334,6 +334,29 @@ describe('getPermittedHooks', () => {
     await close();
   });
 
+  it('returns the `getVersion` hook', async () => {
+    const { snapId, close } = await getMockServer({
+      manifest: getSnapManifest(),
+    });
+
+    const location = detectSnapLocation(snapId, {
+      allowLocal: true,
+    });
+
+    const snapFiles = await fetchSnap(snapId, location);
+
+    const { getVersion } = getPermittedHooks(
+      snapId,
+      snapFiles,
+      controllerMessenger,
+      runSaga,
+    );
+
+    expect(getVersion()).toBe('13.6.0-flask.0');
+
+    await close();
+  });
+
   it('returns the `getSnapFile` hook', async () => {
     const value = JSON.stringify({ bar: 'baz' });
     const { snapId, close } = await getMockServer({

packages/snaps-simulation/src/simulation.ts

@@ -195,6 +195,13 @@ export type PermittedMiddlewareHooks = {
    */
   getIsActive: () => boolean;
 
+  /**
+   * A hook that returns the client version.
+   *
+   * @returns A string that corresponds to the client version.
+   */
+  getVersion: () => string;
+
   /**
    * A hook that returns the Snap's auxiliary file for the given path. This hook
    * is bound to the Snap ID.
@@ -486,6 +493,7 @@ export function getPermittedHooks(
     getUnlockPromise: asyncResolve(),
     getIsLocked: () => false,
     getIsActive: () => true,
+    getVersion: () => '13.6.0-flask.0',
 
     getSnapFile: async (path: string, encoding: AuxiliaryFileEncoding) =>
       await getSnapFile(snapFiles.auxiliaryFiles, path, encoding),

yarn.lock

@@ -2971,6 +2971,7 @@ __metadata:
     "@metamask/snaps-cli": "workspace:^"
     "@metamask/snaps-jest": "workspace:^"
     "@metamask/snaps-sdk": "workspace:^"
+    "@metamask/snaps-utils": "workspace:^"
     "@swc/core": "npm:1.11.31"
     "@swc/jest": "npm:^0.2.38"
     "@types/node": "npm:18.14.2"