feat: enhance Snaps metrics tracking (#218)

* feat: enhance Snaps metrics tracking with additional permission data and justification support

* refactor: remove unused PermissionValue type from snapsMetricsService

Author: mj-kiwi

docs/snaps-metrics.md

@@ -36,14 +36,26 @@ The `SnapsMetricsService` class provides methods to track various events using M
 - `Permission Rejected`: When the user rejects a permission
 - `Permission Granted`: When a permission is successfully granted
 
-**Tracked Data:**
+**Common Tracked Data:**
 - `permission_type`: One of `native-token-stream`, `native-token-periodic`, `erc20-token-stream`, `erc20-token-periodic`
-- `chain_id`: The blockchain network ID
-- `period_seconds`: The time period for periodic permissions
-- `amount`: The token amount
-- `token`: The token address (0x0 for native tokens)
-- `duration_seconds`: Permission duration
-- `is_adjustment_allowed`: Boolean indicating if permission adjustment was allowed
+- `chain_id`: The blockchain network ID (hex string)
+- `justification`: Optional user-provided justification text
+- `is_adjustment_allowed`: Boolean indicating if permission adjustment was allowed (only for `Permission Granted`)
+
+**Permission-Specific Data:**
+
+For **Periodic Permissions** (`native-token-periodic`, `erc20-token-periodic`):
+- `period_amount`: The token amount per period (hex string)
+- `period_duration`: The time period duration in seconds (number)
+- `start_time`: Permission start timestamp in seconds (number)
+- `token_address`: Token contract address (hex string, only for ERC20)
+
+For **Streaming Permissions** (`native-token-stream`, `erc20-token-stream`):
+- `amount_per_second`: Token amount streamed per second (hex string)
+- `initial_amount`: Initial upfront amount (hex string, optional)
+- `max_amount`: Maximum total amount (hex string, optional)
+- `start_time`: Permission start timestamp in seconds (number)
+- `token_address`: Token contract address (hex string, only for ERC20)
 
 ### 2. Smart Account Upgrades
 
@@ -79,7 +91,6 @@ All events include:
 - `origin`: The dapp origin requesting the permission
 - Additional event-specific properties
 
-
 ## Data Flow
 
 1. User initiates permission request → `trackPermissionRequestStarted`
@@ -89,4 +100,3 @@ All events include:
 5. Delegation signing → `trackDelegationSigning`
 6. Permission granted → `trackPermissionGranted`
 7. Profile sync (if enabled) → `trackProfileSync`
-

packages/gator-permissions-snap/src/core/permissionRequestLifecycleOrchestrator.ts

@@ -127,9 +127,8 @@ export class PermissionRequestLifecycleOrchestrator {
     await this.#snapsMetricsService.trackPermissionRequestStarted({
       origin,
       permissionType,
-      permissionValue: {
-        chainId: permissionRequest.chainId,
-      },
+      chainId: permissionRequest.chainId,
+      permissionData: permissionRequest.permission.data,
     });
 
     // only necessary when not pre-installed, to ensure that the account
@@ -216,9 +215,9 @@ export class PermissionRequestLifecycleOrchestrator {
       await this.#snapsMetricsService.trackPermissionDialogShown({
         origin,
         permissionType,
-        permissionValue: {
-          chainId: permissionRequest.chainId,
-        },
+        chainId: permissionRequest.chainId,
+        permissionData: permissionRequest.permission.data,
+        justification: context.justification,
       });
     } catch (error) {
       await confirmationDialog.closeWithError(error as Error);
@@ -310,9 +309,9 @@ export class PermissionRequestLifecycleOrchestrator {
       await this.#snapsMetricsService.trackPermissionRejected({
         origin,
         permissionType,
-        permissionValue: {
-          chainId: permissionRequest.chainId,
-        },
+        chainId: permissionRequest.chainId,
+        permissionData: permissionRequest.permission.data,
+        justification: context.justification,
       });
 
       return {
@@ -502,9 +501,9 @@ export class PermissionRequestLifecycleOrchestrator {
     await this.#snapsMetricsService.trackPermissionGranted({
       origin,
       permissionType,
-      permissionValue: {
-        chainId: numberToHex(chainId),
-      },
+      chainId: numberToHex(chainId),
+      permissionData: populatedPermission.data,
+      justification: modifiedContext.justification,
       isAdjustmentAllowed,
     });
 

packages/gator-permissions-snap/src/services/snapsMetricsService.ts

@@ -3,22 +3,6 @@ import { logger } from '@metamask/7715-permissions-shared/utils';
 import type { Json, SnapsProvider } from '@metamask/snaps-sdk';
 import type { Hex } from '@metamask/utils';
 
-/**
- * Permission value details for analytics.
- */
-export type PermissionValue = {
-  /** The period in seconds (for periodic permissions) */
-  period?: number;
-  /** The amount in the token's base unit */
-  amount?: string;
-  /** The token address (0x0 for native tokens) */
-  token?: Hex;
-  /** The chain ID */
-  chainId?: Hex;
-  /** Duration/expiry in seconds */
-  duration?: number;
-};
-
 /**
  * Base parameters shared by all permission tracking methods.
  */
@@ -34,34 +18,48 @@ export type BasePermissionTrackingParams = {
  */
 export type TrackPermissionRequestStartedParams =
   BasePermissionTrackingParams & {
-    /** Optional permission value details */
-    permissionValue?: PermissionValue;
+    /** Chain ID */
+    chainId: Hex;
+    /** Permission data */
+    permissionData: Record<string, unknown>;
   };
 
 /**
  * Parameters for tracking permission dialog shown.
  */
 export type TrackPermissionDialogShownParams = BasePermissionTrackingParams & {
-  /** Optional permission value details */
-  permissionValue?: PermissionValue;
+  /** Chain ID */
+  chainId: Hex;
+  /** Permission data */
+  permissionData: Record<string, unknown>;
+  /** Optional justification text */
+  justification?: string;
 };
 
 /**
  * Parameters for tracking permission rejected.
  */
 export type TrackPermissionRejectedParams = BasePermissionTrackingParams & {
-  /** Optional permission value details */
-  permissionValue?: PermissionValue;
+  /** Chain ID */
+  chainId: Hex;
+  /** Permission data */
+  permissionData: Record<string, unknown>;
+  /** Optional justification text */
+  justification?: string;
 };
 
 /**
  * Parameters for tracking permission granted.
  */
 export type TrackPermissionGrantedParams = BasePermissionTrackingParams & {
-  /** Permission value details */
-  permissionValue: PermissionValue;
   /** Whether the permission adjustment was allowed */
   isAdjustmentAllowed: boolean;
+  /** Chain ID */
+  chainId: string;
+  /** Permission data */
+  permissionData: Record<string, unknown>;
+  /** Optional justification text */
+  justification?: string;
 };
 
 /**
@@ -151,7 +149,10 @@ export class SnapsMetricsService {
       message: 'User initiated permission request',
       origin: params.origin,
       permission_type: params.permissionType,
-      ...this.#formatPermissionValue(params.permissionValue),
+      ...this.#formatPermissionData({
+        chainId: params.chainId,
+        permissionData: params.permissionData,
+      }),
     });
   }
 
@@ -166,7 +167,11 @@ export class SnapsMetricsService {
       message: 'Permission confirmation dialog displayed',
       origin: params.origin,
       permission_type: params.permissionType,
-      ...this.#formatPermissionValue(params.permissionValue),
+      ...this.#formatPermissionData({
+        chainId: params.chainId,
+        permissionData: params.permissionData,
+        ...(params.justification && { justification: params.justification }),
+      }),
     });
   }
 
@@ -181,7 +186,11 @@ export class SnapsMetricsService {
       message: 'User rejected permission request',
       origin: params.origin,
       permission_type: params.permissionType,
-      ...this.#formatPermissionValue(params.permissionValue),
+      ...this.#formatPermissionData({
+        chainId: params.chainId,
+        permissionData: params.permissionData,
+        ...(params.justification && { justification: params.justification }),
+      }),
     });
   }
 
@@ -197,7 +206,11 @@ export class SnapsMetricsService {
       origin: params.origin,
       permission_type: params.permissionType,
       is_adjustment_allowed: params.isAdjustmentAllowed,
-      ...this.#formatPermissionValue(params.permissionValue),
+      ...this.#formatPermissionData({
+        chainId: params.chainId,
+        permissionData: params.permissionData,
+        ...(params.justification && { justification: params.justification }),
+      }),
     });
   }
 
@@ -253,37 +266,49 @@ export class SnapsMetricsService {
   }
 
   /**
-   * Format permission value for analytics.
-   * @param permissionValue - The permission value to format.
+   * Formats permission data for analytics.
+   * @param params - The formatting parameters.
+   * @param params.chainId - The chain ID for the permission.
+   * @param params.permissionData - The permission data to format.
+   * @param params.justification - Optional justification text provided by the user.
    * @returns Formatted properties for tracking.
    */
-  #formatPermissionValue(
-    permissionValue?: PermissionValue,
-  ): Record<string, Json> {
-    if (!permissionValue) {
-      return {};
-    }
+  #formatPermissionData(params: {
+    chainId: string;
+    permissionData: Record<string, unknown>;
+    justification?: string;
+  }): Record<string, Json> {
+    const formatted: Record<string, Json> = {
+      chain_id: params.chainId,
+    };
 
-    const formatted: Record<string, Json> = {};
+    const { permissionData } = params;
 
-    if (permissionValue.period !== undefined) {
-      formatted.period_seconds = permissionValue.period;
+    if (permissionData.periodAmount !== undefined) {
+      formatted.period_amount = permissionData.periodAmount as string;
     }
-
-    if (permissionValue.amount !== undefined) {
-      formatted.amount = permissionValue.amount;
+    if (permissionData.periodDuration !== undefined) {
+      formatted.period_duration = permissionData.periodDuration as number;
     }
-
-    if (permissionValue.token !== undefined) {
-      formatted.token = permissionValue.token;
+    if (permissionData.startTime !== undefined) {
+      formatted.start_time = permissionData.startTime as number;
     }
-
-    if (permissionValue.chainId !== undefined) {
-      formatted.chain_id = permissionValue.chainId;
+    if (permissionData.tokenAddress !== undefined) {
+      formatted.token_address = permissionData.tokenAddress as string;
+    }
+    if (permissionData.amountPerSecond !== undefined) {
+      formatted.amount_per_second = permissionData.amountPerSecond as string;
+    }
+    if (permissionData.initialAmount !== undefined) {
+      formatted.initial_amount = permissionData.initialAmount as string;
+    }
+    if (permissionData.maxAmount !== undefined) {
+      formatted.max_amount = permissionData.maxAmount as string;
     }
 
-    if (permissionValue.duration !== undefined) {
-      formatted.duration_seconds = permissionValue.duration;
+    // Add justification if provided
+    if (params.justification) {
+      formatted.justification = params.justification;
     }
 
     return formatted;