feat: adds telemetry to cli (#125)

Author: aliasghar98

src/actions/portal/toc/new-toc.ts

@@ -10,14 +10,13 @@ import { TocEndpoint, TocGroup, TocModel } from "../../../types/toc/toc.js";
 import { PortalService } from "../../../infrastructure/services/portal-service.js";
 import { DirectoryPath } from "../../../types/file/directoryPath.js";
 
-const DEFAULT_TOC_FILENAME = "toc.yml";
-const APIMATIC_BUILD_FILENAME = "APIMATIC-BUILD.json";
-
 export class PortalNewTocAction {
   private readonly prompts: PortalNewTocPrompts;
   private readonly sdlParser: SdlParser;
   private readonly tocGenerator: TocStructureGenerator;
   private readonly contentParser: TocContentParser;
+  private readonly DEFAULT_TOC_FILENAME: string = "toc.yml" as const;
+  private readonly APIMATIC_BUILD_FILENAME: string = "APIMATIC-BUILD.json" as const;
 
   constructor() {
     this.prompts = new PortalNewTocPrompts();
@@ -26,7 +25,7 @@ export class PortalNewTocAction {
     this.contentParser = new TocContentParser();
   }
 
-  async createToc(
+  public async createToc(
     buildDirectory: DirectoryPath,
     configDir: string,
     tocDirectory?: DirectoryPath,
@@ -36,7 +35,7 @@ export class PortalNewTocAction {
   ): Promise<Result<string, string>> {
     try {
       const tocDir = await this.getDestinationPath(buildDirectory, tocDirectory);
-      const tocPath = path.join(tocDir, DEFAULT_TOC_FILENAME);
+      const tocPath = path.join(tocDir, this.DEFAULT_TOC_FILENAME);
       const tocCheckResult = await this.handleExistingToc(tocPath, force);
       if (!tocCheckResult.isSuccess()) {
         return tocCheckResult;
@@ -64,7 +63,7 @@ export class PortalNewTocAction {
       this.prompts.displayOutroMessage(tocPath);
       return Result.success(tocPath);
     } catch (error) {
-      this.prompts.logError(getMessageInRedColor(`${error}`));
+      this.prompts.logError(getMessageInRedColor(`${(error as Error).message}`));
       return Result.failure(`❌ An unexpected error occurred while generating the TOC file.`);
     }
   }
@@ -143,7 +142,7 @@ export class PortalNewTocAction {
   }
 
   private async getContentFolderPath(buildDirectory: DirectoryPath): Promise<string> {
-    const buildFilePath = path.join(buildDirectory.toString(), APIMATIC_BUILD_FILENAME);
+    const buildFilePath = path.join(buildDirectory.toString(), this.APIMATIC_BUILD_FILENAME);
     const defaultContentFolder = path.join(buildDirectory.toString(), "content");
 
     if (!(await fsExtra.pathExists(buildFilePath))) {
@@ -163,7 +162,7 @@ export class PortalNewTocAction {
   }
 
   private async getSpecFolderPath(buildDirectory: DirectoryPath): Promise<string> {
-    const buildFilePath = path.join(buildDirectory.toString(), APIMATIC_BUILD_FILENAME);
+    const buildFilePath = path.join(buildDirectory.toString(), this.APIMATIC_BUILD_FILENAME);
     const defaultSpecFolder = path.join(buildDirectory.toString(), "spec");
 
     if (!(await fsExtra.pathExists(buildFilePath))) {

src/client-utils/auth-manager.ts

@@ -1,9 +1,10 @@
 import * as path from "path";
-import fsExtra from "fs-extra";
+import fs from "fs-extra";
 
 export type AuthInfo = {
   email: string;
   authKey: string;
+  APIMATIC_CLI_TELEMETRY_OPTOUT?: string;
 };
 /**
  *
@@ -12,7 +13,7 @@ export type AuthInfo = {
  */
 export async function getAuthInfo(configDir: string): Promise<AuthInfo | null> {
   try {
-    const data: AuthInfo | null = JSON.parse(await fsExtra.readFile(path.join(configDir, "config.json"), "utf8"));
+    const data: AuthInfo | null = JSON.parse(await fs.readFile(path.join(configDir, "config.json"), "utf8"));
     return data;
   } catch (e) {
     return null;
@@ -21,14 +22,38 @@ export async function getAuthInfo(configDir: string): Promise<AuthInfo | null> {
 
 /**
  *
- * @param {AuthInfo} credentials
+ * @param {string} email
+ * @param {string} authKey
+ * @param {string} isTelemetryOptedOut
  * @param {string} configDir <- Directory with user configuration
  * //Function to set credentials.
  */
-export async function setAuthInfo(credentials: AuthInfo, configDir: string): Promise<void> {
+export async function setAuthInfo(
+  email: string,
+  authKey: string,
+  isTelemetryOptedOut: boolean,
+  configDir: string
+): Promise<void> {
+  const credentials: AuthInfo = {
+    email,
+    authKey,
+    APIMATIC_CLI_TELEMETRY_OPTOUT: isTelemetryOptedOut ? "1" : "0"
+  };
   const configFilePath = path.join(configDir, "config.json");
 
-  if (!fsExtra.existsSync(configFilePath)) fsExtra.createFileSync(configFilePath);
+  if (!fs.existsSync(configFilePath)) fs.createFileSync(configFilePath);
 
-  return await fsExtra.writeFile(configFilePath, JSON.stringify(credentials));
+  return await fs.writeFile(configFilePath, JSON.stringify(credentials));
 }
+
+export async function removeAuthInfo(configDir: string): Promise<void> {
+  const credentials: AuthInfo = {
+    email: "",
+    authKey: ""
+  };
+  const configFilePath = path.join(configDir, "config.json");
+
+  if (!fs.existsSync(configFilePath)) fs.createFileSync(configFilePath);
+
+  return await fs.writeFile(configFilePath, JSON.stringify(credentials));
+}

src/client-utils/sdk-client.ts

@@ -3,7 +3,7 @@ import axios, { AxiosResponse } from "axios";
 
 import { Client } from "@apimatic/sdk";
 import { baseURL } from "../config/env.js";
-import { setAuthInfo, getAuthInfo, AuthInfo } from "./auth-manager.js";
+import { setAuthInfo, getAuthInfo, AuthInfo, removeAuthInfo } from "./auth-manager.js";
 /**
  * The Singleton class defines the `getInstance` method that lets clients access
  * the unique singleton instance.
@@ -39,26 +39,16 @@ export class SDKClient {
   public async login(email: string, password: string, configDir: string): Promise<string> {
     const credentials: Credentials = { email, password };
     const authKey: string = await this.getAuthKey(credentials);
-      setAuthInfo(
-        {
-          email,
-          authKey
-        },
-        configDir
-      );
+    const isTelemetryOptedOut = process.env.APIMATIC_CLI_TELEMETRY_OPTOUT === "1";
 
-      return "✅ Logged in successfully as " + email;
+    await setAuthInfo(email, authKey, isTelemetryOptedOut, configDir);
 
+    return "✅ Logged in successfully as " + email;
   }
 
   public async logout(configDir: string): Promise<string> {
-    setAuthInfo(
-      {
-        email: "",
-        authKey: ""
-      },
-      configDir
-    );
+    await removeAuthInfo(configDir);
+
     return "Logged out";
   }
 
@@ -118,14 +108,12 @@ export class SDKClient {
     const authKey: string = response.data.EncryptedValue;
     return authKey;
   }
+
   public setAuthKey = (authKey: string, configDir: string) => {
-    setAuthInfo(
-      {
-        email: "",
-        authKey
-      },
-      configDir
-    );
+    const isTelemetryOptedOut = process.env.APIMATIC_CLI_TELEMETRY_OPTOUT === "1";
+    
+    setAuthInfo("", authKey, isTelemetryOptedOut, configDir);
+    
     return "Authentication key successfully set";
   };
 }

src/commands/portal/recipe/new.ts

@@ -2,6 +2,8 @@ import { Command, Flags } from "@oclif/core";
 import { PortalRecipeAction } from "../../../actions/portal/recipe/new-recipe.js";
 import { PortalRecipePrompts } from "../../../prompts/portal/recipe/new-recipe.js";
 import { getMessageInRedColor } from "../../../utils/utils.js";
+import { TelemetryService } from "../../../infrastructure/services/telemetry-service.js";
+import { RecipeCreationFailedEvent } from "../../../types/events/recipe-creation-failed.js";
 import { DirectoryPath } from "../../../types/file/directoryPath.js";
 
 const DEFAULT_WORKING_DIRECTORY = "./";
@@ -26,18 +28,18 @@ export default class PortalRecipeNew extends Command {
 
   public async run(): Promise<void> {
     const { flags } = await this.parse(PortalRecipeNew);
+    const telemetryService = new TelemetryService(this.config.configDir);
     const portalRecipeAction = new PortalRecipeAction();
     const portalRecipePrompts = new PortalRecipePrompts();
 
     const workingDirectory = new DirectoryPath(flags.folder ?? DEFAULT_WORKING_DIRECTORY);
     const buildDirectory = flags.folder ? new DirectoryPath(flags.folder, "build") : workingDirectory.join("build");
 
-    const createRecipeResult = await portalRecipeAction.createRecipe(
-      buildDirectory,
-      this.config.configDir,
-      flags.name
-    );
+    const createRecipeResult = await portalRecipeAction.createRecipe(buildDirectory, this.config.configDir, flags.name);
+
+    //TODO: Add a mapper for automatically mapping events to logger and telemetry service.
     if (createRecipeResult.isFailed()) {
+      telemetryService.trackEvent(new RecipeCreationFailedEvent(createRecipeResult.error!, PortalRecipeNew.id, flags));
       portalRecipePrompts.logError(getMessageInRedColor(createRecipeResult.error!));
     }
     if (createRecipeResult.isCancelled()) {

src/commands/portal/toc/new.ts

@@ -1,5 +1,7 @@
-import { Command, Flags } from "@oclif/core";
+import { Command, Config, Flags } from "@oclif/core";
 import { PortalNewTocAction } from "../../../actions/portal/toc/new-toc.js";
+import { TelemetryService } from "../../../infrastructure/services/telemetry-service.js";
+import { TocCreationFailedEvent } from "../../../types/events/toc-creation-failed.js";
 import { DirectoryPath } from "../../../types/file/directoryPath.js";
 
 const DEFAULT_WORKING_DIRECTORY = "./";
@@ -43,15 +45,16 @@ https://docs.apimatic.io/platform-api/#/http/guides/generating-on-prem-api-porta
   static examples = [
     `$ apimatic portal:toc:new --destination="./portal/content/"`,
     `$ apimatic portal:toc:new --folder="./my-project"`,
-    `$ apimatic portal:toc:new --folder="./my-project" --destination="./portal/content/"` 
+    `$ apimatic portal:toc:new --folder="./my-project" --destination="./portal/content/"`
   ];
 
-  constructor(argv: string[], config: any) {
+  constructor(argv: string[], config: Config) {
     super(argv, config);
   }
 
   async run(): Promise<void> {
     const { flags } = await this.parse(PortalTocNew);
+    const telemetryService = new TelemetryService(this.config.configDir);
     const portalNewTocAction = new PortalNewTocAction();
 
     const workingDirectory = new DirectoryPath(flags.folder ?? DEFAULT_WORKING_DIRECTORY);
@@ -72,7 +75,9 @@ https://docs.apimatic.io/platform-api/#/http/guides/generating-on-prem-api-porta
       flags["expand-models"]
     );
 
+    //TODO: Add a mapper for automatically mapping events to logger and telemetry service.
     if (result.isFailed()) {
+      telemetryService.trackEvent(new TocCreationFailedEvent(result.error!, PortalTocNew.id, flags));
       this.error(result.error!);
     }
   }

src/infrastructure/services/telemetry-service.ts

@@ -0,0 +1,97 @@
+import process from "process";
+import os from "os";
+import fs from "fs-extra";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { baseURL } from "../../config/env.js";
+import { DomainEvent } from "../../types/events/domain-event.js";
+import { AuthInfo } from "../../client-utils/auth-manager.js";
+
+type TelemetryPayload = {
+  payload: DomainEvent;
+  timestamp: string;
+  cliVersion: string;
+  platform: string;
+  releaseVersion: string;
+  nodeVersion: string;
+  userAgent: string;
+};
+
+export class TelemetryService {
+  private readonly url: string = `${baseURL}/api/telemetry/track`;
+  private readonly configDirectory: string;
+  private static cachedCliVersion: string | null = null; 
+
+  constructor(configDirectory: string) {
+    this.configDirectory = configDirectory;
+  }
+
+  public async trackEvent<T extends DomainEvent>(event: T): Promise<void> {
+    const authInfo = await this.getAuthInfo(this.configDirectory);
+    const telemetryOptedOut = process.env.APIMATIC_CLI_TELEMETRY_OPTOUT === "1";
+
+    if (telemetryOptedOut || authInfo?.APIMATIC_CLI_TELEMETRY_OPTOUT === "1") {
+      return;
+    }
+
+    const payload: TelemetryPayload = {
+      payload: event,
+      timestamp: new Date().toISOString(),
+      cliVersion: this.getCLIVersion(),
+      platform: os.platform(),
+      releaseVersion: os.release(),
+      nodeVersion: process.version,
+      userAgent: this.getUserAgent()
+    };
+
+    // TODO: Replace with method of API Service.
+    try {
+      await fetch(this.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `X-Auth-Key ${authInfo?.authKey || ""}`,
+        },
+        body: JSON.stringify(payload)
+      });
+    } catch {
+      // Ignore, fail silently.
+    }
+  }
+
+  private getCLIVersion(): string {
+    if (TelemetryService.cachedCliVersion) {
+      return TelemetryService.cachedCliVersion;
+    }
+
+    try {
+      const __filename = fileURLToPath(import.meta.url);
+      const __dirname = dirname(__filename);
+      const pkgPath = join(__dirname, "../../../package.json");
+      const pkgJson = fs.readFileSync(pkgPath, "utf-8");
+      const pkg = JSON.parse(pkgJson);
+      const version = pkg.version || "unknown";
+      TelemetryService.cachedCliVersion = version;
+      return version;
+    } catch {
+      return "unknown";
+    }
+  }
+
+  private async getAuthInfo(configDirectory: string): Promise<AuthInfo | null> {
+    try {
+      const data: AuthInfo | null = JSON.parse(await fs.readFile(join(configDirectory, "config.json"), "utf8"));
+      return data;
+    } catch {
+      return null;
+    }
+  }
+
+  private getUserAgent(): string {
+    const osInfo = `${os.platform()} ${os.release()}`;
+    const engine = "Node.js";
+    const engineVersion = process.version;
+
+    return `APIMATIC CLI - [OS: ${osInfo}, Engine: ${engine}/${engineVersion}]`;
+  }
+}

src/types/events/domain-event.ts

@@ -0,0 +1,16 @@
+export abstract class DomainEvent {
+  protected abstract readonly eventName: string;
+  private readonly message: string;
+  private readonly commandName: string;
+  private readonly flags: string[];
+
+  constructor(message: string, commandName: string, flags: Record<string, unknown>) {
+    this.message = message;
+    this.commandName = commandName;
+    this.flags = this.extractFlagKeys(flags);
+  }
+
+  private extractFlagKeys(flags: Record<string, unknown>): string[] {
+    return Object.keys(flags);
+  }
+}

src/types/events/recipe-creation-failed.ts

@@ -0,0 +1,9 @@
+import { DomainEvent } from "../../types/events/domain-event.js";
+
+export class RecipeCreationFailedEvent extends DomainEvent {
+  protected readonly eventName = RecipeCreationFailedEvent.name;
+
+  constructor(message: string, commandName: string, flags: Record<string, unknown>) {
+    super(message, commandName, flags);
+  }
+}

src/types/events/toc-creation-failed.ts

@@ -0,0 +1,9 @@
+import { DomainEvent } from "../../types/events/domain-event.js";
+
+export class TocCreationFailedEvent extends DomainEvent {
+  protected readonly eventName = TocCreationFailedEvent.name;
+
+  constructor(message: string, commandName: string, flags: Record<string, unknown>) {
+    super(message, commandName, flags);
+  }
+}