Add logic to send analytics data

v-next/core/src/global-dir.ts

@@ -11,6 +11,21 @@ export async function getConfigDir(): Promise<string> {
   return config;
 }
 
+/**
+ * Returns the path to the telemetry directory for the specified package.
+ * If no package name is provided, the default package name "hardhat" is used.
+ * Ensures that the directory exists before returning the path.
+ *
+ * @param packageName - The name of the package to get the telemetry directory for. Defaults to "hardhat".
+ *
+ * @returns A promise that resolves to the path of the telemetry directory.
+ */
+export async function getTelemetryDir(packageName?: string): Promise<string> {
+  const { data } = await generatePaths(packageName);
+  await ensureDir(data);
+  return data;
+}
+
 async function generatePaths(packageName = "hardhat") {
   const { default: envPaths } = await import("env-paths");
   return envPaths(packageName);

v-next/hardhat/src/internal/cli/telemetry/analytics/analytics-subprocess.ts

@@ -0,0 +1,15 @@
+import { postJsonRequest } from "@ignored/hardhat-vnext-utils/request";
+
+// These keys are expected to be public
+const ANALYTICS_URL = "https://www.google-analytics.com/mp/collect";
+const API_SECRET = "fQ5joCsDRTOp55wX8a2cVw";
+const MEASUREMENT_ID = "G-8LQ007N2QJ";
+
+const payload = JSON.parse(process.argv[2]);
+
+await postJsonRequest(ANALYTICS_URL, payload, {
+  queryParams: {
+    api_secret: API_SECRET,
+    measurement_id: MEASUREMENT_ID,
+  },
+});

v-next/hardhat/src/internal/cli/telemetry/analytics/analytics.ts

@@ -0,0 +1,109 @@
+import type {
+  EventNames,
+  Payload,
+  TaskParams,
+  TelemetryConsentPayload,
+} from "./types.js";
+
+import os from "node:os";
+
+import { spawnDetachedSubProcess } from "@ignored/hardhat-vnext-utils/subprocess";
+
+import { getHardhatVersion } from "../../../utils/package.js";
+import { getTelemetryConsent } from "../telemetry-consent.js";
+
+import { getAnalyticsClientId } from "./utils.js";
+
+// TODO:log const log = debug("hardhat:core:global-dir");
+
+const SESSION_ID = Math.random().toString();
+const ENGAGEMENT_TIME_MSEC = "10000";
+
+export async function sendTelemetryConsentAnalytics(
+  userConsent: boolean,
+): Promise<void> {
+  // This is a special scenario where only the consent is sent, all the other analytics info
+  // (like node version, hardhat version, etc.) are stripped.
+  const payload: TelemetryConsentPayload = {
+    client_id: "hardhat_telemetry_consent",
+    user_id: "hardhat_telemetry_consent",
+    user_properties: {},
+    events: [
+      {
+        name: "TelemetryConsentResponse",
+        params: {
+          userConsent: userConsent ? "yes" : "no",
+        },
+      },
+    ],
+  };
+
+  await createSubprocessToSendAnalytics(payload);
+}
+
+export async function sendTaskAnalytics(
+  taskName: string,
+  scopeName: string | undefined,
+): Promise<boolean> {
+  const eventParams: TaskParams = {
+    task: taskName,
+    scope: scopeName,
+  };
+
+  return sendAnalytics("task", eventParams);
+}
+
+// Return a boolean for test purposes, so we can check if the analytics was sent based on the consent value
+async function sendAnalytics(
+  eventName: EventNames,
+  eventParams: TaskParams,
+): Promise<boolean> {
+  if (!(await getTelemetryConsent())) {
+    return false;
+  }
+
+  const payload = await buildPayload(eventName, eventParams);
+
+  await createSubprocessToSendAnalytics(payload);
+
+  return true;
+}
+
+async function createSubprocessToSendAnalytics(
+  payload: TelemetryConsentPayload | Payload,
+): Promise<void> {
+  // The file extension is 'js' because the 'ts' file will be compiled
+  const analyticsSubprocessFilePath = `${import.meta.dirname}/analytics-subprocess.js`;
+
+  await spawnDetachedSubProcess(analyticsSubprocessFilePath, [
+    JSON.stringify(payload),
+  ]);
+}
+
+async function buildPayload(
+  eventName: EventNames,
+  eventParams: TaskParams,
+): Promise<Payload> {
+  const clientId = await getAnalyticsClientId();
+
+  return {
+    client_id: clientId,
+    user_id: clientId,
+    user_properties: {
+      projectId: { value: "hardhat-project" },
+      hardhatVersion: { value: await getHardhatVersion() },
+      operatingSystem: { value: os.platform() },
+      nodeVersion: { value: process.version },
+    },
+    events: [
+      {
+        name: eventName,
+        params: {
+          engagement_time_msec: ENGAGEMENT_TIME_MSEC,
+          session_id: SESSION_ID,
+          ...eventParams,
+        },
+      },
+    ],
+  };
+}

v-next/hardhat/src/internal/cli/telemetry/analytics/types.ts

@@ -0,0 +1,64 @@
+export interface AnalyticsFile {
+  analytics: {
+    clientId: string;
+  };
+}
+
+/* eslint-disable @typescript-eslint/naming-convention -- these payload is formatted based on what google analytics expects*/
+export interface BasePayload {
+  client_id: string;
+  user_id: string;
+  user_properties: {};
+  events: Array<{
+    name: string;
+    params: {
+      // From the GA docs: amount of time someone spends with your web
+      // page in focus or app screen in the foreground.
+      // The parameter has no use for our app, but it's required in order
+      // for user activity to display in standard reports like Realtime.
+      engagement_time_msec?: string;
+      session_id?: string;
+    };
+  }>;
+}
+
+export interface TelemetryConsentPayload extends BasePayload {
+  events: Array<{
+    name: "TelemetryConsentResponse";
+    params: {
+      userConsent: "yes" | "no";
+      session_id?: string;
+    };
+  }>;
+}
+
+export type EventNames = "task";
+
+export interface TaskParams {
+  task: string;
+  scope?: string;
+}
+
+export interface Payload extends BasePayload {
+  user_properties: {
+    projectId: {
+      value: string;
+    };
+    hardhatVersion: {
+      value: string;
+    };
+    operatingSystem: {
+      value: string;
+    };
+    nodeVersion: {
+      value: string;
+    };
+  };
+  events: Array<{
+    name: EventNames;
+    params: {
+      engagement_time_msec: string;
+      session_id: string;
+    } & TaskParams;
+  }>;
+}

v-next/hardhat/src/internal/cli/telemetry/analytics/utils.ts

@@ -0,0 +1,54 @@
+import type { AnalyticsFile } from "./types.js";
+
+import path from "node:path";
+
+import { getTelemetryDir } from "@ignored/hardhat-vnext-core/global-dir";
+import {
+  exists,
+  readJsonFile,
+  writeJsonFile,
+} from "@ignored/hardhat-vnext-utils/fs";
+
+const ANALYTICS_FILE_NAME = "analytics.json";
+
+export async function getAnalyticsClientId(): Promise<string> {
+  let clientId = await readAnalyticsClientId();
+
+  if (clientId === undefined) {
+    // TODO:log log("Client Id not found, generating a new one");
+    clientId = crypto.randomUUID();
+
+    await writeAnalyticsClientId(clientId);
+  }
+
+  return clientId;
+}
+
+async function readAnalyticsClientId(): Promise<string | undefined> {
+  const globalTelemetryDir = await getTelemetryDir();
+  const filePath = path.join(globalTelemetryDir, ANALYTICS_FILE_NAME);
+
+  // TODO:log log(`Looking up Client Id at ${filePath}`);
+
+  if ((await exists(filePath)) === false) {
+    return undefined;
+  }
+
+  const data: AnalyticsFile = await readJsonFile(filePath);
+  const clientId = data.analytics.clientId;
+  // TODO:log log(`Client Id found: ${clientId}`);
+
+  return clientId;
+}
+
+async function writeAnalyticsClientId(clientId: string): Promise<void> {
+  const globalTelemetryDir = await getTelemetryDir();
+  const filePath = path.join(globalTelemetryDir, ANALYTICS_FILE_NAME);
+  await writeJsonFile(filePath, {
+    analytics: {
+      clientId,
+    },
+  });
+
+  // TODO:log log(`Stored clientId ${clientId}`);
+}

v-next/hardhat/src/internal/cli/telemetry/telemetry-consent.ts

@@ -15,13 +15,32 @@ interface TelemetryConsent {
 }
 
 /**
- * Get the user's telemetry consent. If already provided, returns the answer.
- * If not, prompts the user.
+ * Ensure that the user's telemetry consent is set. If the consent is already provided, returns the answer.
+ * If not, prompts the user to provide it.
  * Consent is only asked in interactive environments.
  * @returns True if the user consents to telemetry, false otherwise.
  */
+export async function ensureTelemetryConsent(): Promise<boolean> {
+  const consent = await getTelemetryConsentIfAlreadySet();
+  if (consent !== undefined) {
+    return consent;
+  }
+
+  // Telemetry consent not provided yet, ask for it
+  return requestTelemetryConsent();
+}
+
+/**
+ * Retrieves the user's telemetry consent status.
+ * @returns True if the user consents to telemetry, false otherwise.
+ */
 export async function getTelemetryConsent(): Promise<boolean> {
-  if (canTelemetryBeEnabled() === false) {
+  const consent = await getTelemetryConsentIfAlreadySet();
+  return consent !== undefined ? consent : false;
+}
+
+async function getTelemetryConsentIfAlreadySet(): Promise<boolean | undefined> {
+  if (!canTelemetryBeEnabled()) {
     return false;
   }
 
@@ -33,8 +52,7 @@ export async function getTelemetryConsent(): Promise<boolean> {
       .consent;
   }
 
-  // Telemetry consent not provided yet, ask for it
-  return requestTelemetryConsent();
+  return undefined;
 }
 
 function canTelemetryBeEnabled(): boolean {

v-next/hardhat/test/fixture-projects/cli/telemetry/analytics/analytics-subprocess.js

@@ -0,0 +1,20 @@
+// This file will be copied to the "analytics" folder so it will be executed as a subprocess.
+// This will allow checking that the subprocess received the correct payload.
+
+// We need to directly use the node method "fs" instead of "writeJsonFile" because a TypeScript ESM file cannot be imported without compiling it first
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+
+const PATH_TO_RESULT_FILE = path.join(
+  process.cwd(),
+  "test",
+  "fixture-projects",
+  "cli",
+  "telemetry",
+  "analytics",
+  "result.json",
+);
+
+const stringifiedPayload = process.argv[2];
+
+writeFileSync(PATH_TO_RESULT_FILE, stringifiedPayload);

v-next/hardhat/test/fixture-projects/cli/telemetry/analytics/telemetry-consent-payload.json

@@ -0,0 +1,13 @@
+{
+  "client_id": "hardhat_telemetry_consent",
+  "user_id": "hardhat_telemetry_consent",
+  "user_properties": {},
+  "events": [
+    {
+      "name": "TelemetryConsentResponse",
+      "params": {
+        "userConsent": "yes"
+      }
+    }
+  ]
+}