Add logic to send analytics data

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

@@ -22,6 +22,21 @@ export async function getCacheDir(): Promise<string> {
   return cache;
 }
 
+/**
+ * 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.ts

@@ -0,0 +1,122 @@
+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 {
+  isTelemetryAllowedInEnvironment,
+  isTelemetryAllowed,
+} from "../telemetry-permissions.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";
+
+// Return a boolean for testing purposes to verify that analytics are not sent in CI environments
+export async function sendTelemetryConsentAnalytics(
+  consent: boolean,
+): Promise<boolean> {
+  // This is a special scenario where only the consent is sent, all the other analytics info
+  // (like node version, hardhat version, etc.) are stripped.
+
+  if (!isTelemetryAllowedInEnvironment()) {
+    return false;
+  }
+
+  const payload: TelemetryConsentPayload = {
+    client_id: "hardhat_telemetry_consent",
+    user_id: "hardhat_telemetry_consent",
+    user_properties: {},
+    events: [
+      {
+        name: "TelemetryConsentResponse",
+        params: {
+          userConsent: consent ? "yes" : "no",
+        },
+      },
+    ],
+  };
+
+  await createSubprocessToSendAnalytics(payload);
+
+  return true;
+}
+
+export async function sendTaskAnalytics(taskId: string[]): Promise<boolean> {
+  const eventParams: TaskParams = {
+    task: taskId.join(", "),
+  };
+
+  return sendAnalytics("task", eventParams);
+}
+
+// Return a boolean for testing purposes to confirm whether analytics were sent based on the consent value and not in CI environments
+async function sendAnalytics(
+  eventName: EventNames,
+  eventParams: TaskParams,
+): Promise<boolean> {
+  if (!(await isTelemetryAllowed())) {
+    return false;
+  }
+
+  const payload = await buildPayload(eventName, eventParams);
+
+  await createSubprocessToSendAnalytics(payload);
+
+  return true;
+}
+
+async function createSubprocessToSendAnalytics(
+  payload: TelemetryConsentPayload | Payload,
+): Promise<void> {
+  const fileExt =
+    process.env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH !== undefined ? "ts" : "js";
+  const subprocessFile = `${import.meta.dirname}/subprocess.${fileExt}`;
+
+  const env: Record<string, string> = {};
+  if (process.env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH !== undefined) {
+    // ATTENTION: only for testing
+    env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH =
+      process.env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH;
+  }
+
+  await spawnDetachedSubProcess(subprocessFile, [JSON.stringify(payload)], env);
+}
+
+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/subprocess.ts

@@ -0,0 +1,27 @@
+import { writeJsonFile } from "@ignored/hardhat-vnext-utils/fs";
+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 = "iXzTRik5RhahYpgiatSv1w";
+const MEASUREMENT_ID = "G-ZFZWHGZ64H";
+
+async function main(): Promise<void> {
+  const payload = JSON.parse(process.argv[2]);
+
+  if (process.env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH === undefined) {
+    await postJsonRequest(ANALYTICS_URL, payload, {
+      queryParams: {
+        api_secret: API_SECRET,
+        measurement_id: MEASUREMENT_ID,
+      },
+    });
+
+    return;
+  }
+
+  // ATTENTION: only for testing
+  await writeJsonFile(process.env.HARDHAT_TEST_SUBPROCESS_RESULT_PATH, payload);
+}
+
+await main();

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

@@ -0,0 +1,63 @@
+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;
+}
+
+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-permissions.ts

@@ -10,6 +10,8 @@ import {
 
 import { confirmationPromptWithTimeout } from "../prompt/prompt.js";
 
+import { sendTelemetryConsentAnalytics } from "./analytics/analytics.js";
+
 interface TelemetryConsent {
   consent: boolean;
 }
@@ -45,17 +47,43 @@ export async function isTelemetryAllowed(): Promise<boolean> {
     return false;
   }
 
+  // ATTENTION: only for testing
+  if (process.env.HARDHAT_TEST_TELEMETRY_CONSENT_VALUE !== undefined) {
+    return process.env.HARDHAT_TEST_TELEMETRY_CONSENT_VALUE === "true"
+      ? true
+      : false;
+  }
+
   const consent = await getTelemetryConsent();
+
   return consent !== undefined ? consent : false;
 }
 
+/**
+ * Determines if telemetry is allowed in the current environment.
+ * This function checks various environmental factors to decide if telemetry data can be collected.
+ * It verifies that the environment is not a continuous integration (CI) environment, that the terminal is interactive,
+ * and that telemetry has not been explicitly disabled through an environment variable.
+ *
+ * @returns True if telemetry is allowed in the environment, false otherwise.
+ */
+export function isTelemetryAllowedInEnvironment(): boolean {
+  return (
+    (!isCi() &&
+      process.stdout.isTTY === true &&
+      process.env.HARDHAT_DISABLE_TELEMETRY_PROMPT !== "true") ||
+    // ATTENTION: used in tests to force telemetry execution
+    process.env.HARDHAT_TEST_INTERACTIVE_ENV === "true"
+  );
+}
+
 /**
  * Retrieves the user's telemetry consent status from the consent file.
  *
  * @returns True if the user consents to telemetry, false if they do not consent,
  * and undefined if no consent has been provided.
  */
-export async function getTelemetryConsent(): Promise<boolean | undefined> {
+async function getTelemetryConsent(): Promise<boolean | undefined> {
   const telemetryConsentFilePath = await getTelemetryConsentFilePath();
 
   if (await exists(telemetryConsentFilePath)) {
@@ -67,23 +95,6 @@ export async function getTelemetryConsent(): Promise<boolean | undefined> {
   return undefined;
 }
 
-/**
- * Determines if telemetry is allowed in the current environment.
- * This function checks various environmental factors to decide if telemetry data can be collected.
- * It verifies that the environment is not a continuous integration (CI) environment, that the terminal is interactive,
- * and that telemetry has not been explicitly disabled through an environment variable.
- *
- * @returns True if telemetry is allowed in the environment, false otherwise.
- */
-export function isTelemetryAllowedInEnvironment(): boolean {
-  return (
-    (!isCi() &&
-      process.stdout.isTTY === true &&
-      process.env.HARDHAT_DISABLE_TELEMETRY_PROMPT !== "true") ||
-    process.env.HARDHAT_ENABLE_TELEMETRY_IN_TEST === "true" // Used in tests to force telemetry execution
-  );
-}
-
 async function getTelemetryConsentFilePath() {
   const configDir = await getConfigDir();
   return path.join(configDir, "telemetry-consent.json");
@@ -99,12 +110,7 @@ async function requestTelemetryConsent(): Promise<boolean> {
   // Store user's consent choice
   await writeJsonFile(await getTelemetryConsentFilePath(), { consent });
 
-  // TODO: this will be enabled in a following PR as soon as the function to send telemetry is implemented
-  // const subprocessFilePath = path.join(
-  //   path.dirname(fileURLToPath(import.meta.url)),
-  //   "report-telemetry-consent.js",
-  // );
-  // await spawnDetachedSubProcess(subprocessFilePath, [consent ? "yes" : "no"]);
+  await sendTelemetryConsentAnalytics(consent);
 
   return consent;
 }