@adobe/ccweb-add-on-analytics 0.1.0

package/src/index.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+export * from "./app/index.js";
+export * from "./config/index.js";
+export * from "./constants.js";
+export * from "./models/index.js";

package/src/models/CLIProgram.ts

@@ -0,0 +1,49 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+/**
+ * A CLI program.
+ */
+export class CLIProgram {
+    /**
+     * Name of the program.
+     */
+    readonly name: string;
+
+    /**
+     * Current version of the program.
+     */
+    readonly version: string;
+
+    /**
+     * Instantiate {@link CLIProgram}.
+     * @param name - Name of the program.
+     * @param version - Current version of the program.
+     * @returns Reference to a new {@link CLIProgram} instance.
+     */
+    constructor(name: string, version: string) {
+        this.name = name;
+        this.version = version;
+    }
+}

package/src/models/index.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+export * from "./CLIProgram.js";

package/src/test/app/WxpAnalyticsConsent.spec.ts

@@ -0,0 +1,190 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+import type { Logger, Preferences } from "@adobe/ccweb-add-on-core";
+import { ADD_ON_PREFERENCES_FILE, PreferenceJson } from "@adobe/ccweb-add-on-core";
+import { assert } from "chai";
+import chalk from "chalk";
+import "mocha";
+import prompts from "prompts";
+import type { SinonSandbox } from "sinon";
+import sinon from "sinon";
+import type { StubbedInstance } from "ts-sinon";
+import { stubInterface } from "ts-sinon";
+import type { AnalyticsConsent } from "../../app/index.js";
+import { WxpAnalyticsConsent } from "../../app/index.js";
+
+describe("WxpAnalyticsConsent", () => {
+    let sandbox: SinonSandbox;
+
+    let cliPreferences: StubbedInstance<Preferences>;
+    let logger: StubbedInstance<Logger>;
+    let analyticsConsent: AnalyticsConsent;
+
+    const choices: { title: string; value: boolean }[] = [];
+    choices.push({
+        title: promptMessageOption("Yes, send analytics to Adobe"),
+        value: true
+    });
+    choices.push({
+        title: promptMessageOption("No, don't send analytics to Adobe"),
+        value: false
+    });
+
+    beforeEach(() => {
+        sandbox = sinon.createSandbox();
+
+        cliPreferences = stubInterface<Preferences>();
+
+        logger = stubInterface<Logger>();
+        logger.warning.returns();
+
+        analyticsConsent = new WxpAnalyticsConsent(cliPreferences, logger);
+    });
+
+    afterEach(() => {
+        sandbox.restore();
+    });
+
+    describe("get", () => {
+        beforeEach(() => {
+            sandbox = sinon.createSandbox();
+        });
+
+        afterEach(() => {
+            sandbox.restore();
+        });
+
+        it(`should ask the user for analytics consent if it does not exist in ${ADD_ON_PREFERENCES_FILE}.`, async () => {
+            const promptsStub = sandbox.stub(prompts, "prompt");
+            promptsStub.resolves({ analyticsConsent: choices[0].value });
+
+            const preferenceJson = new PreferenceJson({});
+            cliPreferences.get.returns(preferenceJson);
+
+            const userConsent = await analyticsConsent.get();
+
+            assert.equal(
+                logger.warning.calledWith(
+                    "This tool collects and sends analytics to help Adobe improve its products.",
+                    {
+                        prefix: "\n"
+                    }
+                ),
+                true
+            );
+
+            assert.equal(promptsStub.callCount, 1);
+            assert.equal(
+                promptsStub.calledWith({
+                    type: "select",
+                    name: "analyticsConsent",
+                    message: promptMessage("Do you want to allow sending analytics to Adobe"),
+                    choices,
+                    initial: 0
+                }),
+                true
+            );
+            assert.equal(userConsent, true);
+        });
+
+        it(`should return the user's analytics consent if it exists in ${ADD_ON_PREFERENCES_FILE}.`, async () => {
+            const promptsStub = sandbox.stub(prompts, "prompt");
+            promptsStub.resolves({ analyticsConsent: choices[0].value });
+
+            const preferenceJson = new PreferenceJson({ hasTelemetryConsent: true });
+            cliPreferences.get.returns(preferenceJson);
+
+            const userConsent = await analyticsConsent.get();
+
+            assert.equal(userConsent, true);
+            assert.equal(promptsStub.callCount, 0);
+        });
+
+        it("should exit if the user does not select any option when asked for analytics consent.", async () => {
+            const promptsStub = sandbox.stub(prompts, "prompt");
+            const exitProcessStub = sandbox.stub(process, "exit");
+            promptsStub.resolves({ analyticsConsent: undefined });
+
+            const preferenceJson = new PreferenceJson({});
+            cliPreferences.get.returns(preferenceJson);
+
+            const userConsent = await analyticsConsent.get();
+
+            assert.equal(
+                logger.warning.calledWith(
+                    "This tool collects and sends analytics to help Adobe improve its products.",
+                    {
+                        prefix: "\n"
+                    }
+                ),
+                true
+            );
+
+            assert.equal(promptsStub.callCount, 1);
+            assert.equal(
+                promptsStub.calledWith({
+                    type: "select",
+                    name: "analyticsConsent",
+                    message: promptMessage("Do you want to allow sending analytics to Adobe"),
+                    choices,
+                    initial: 0
+                }),
+                true
+            );
+            assert.equal(userConsent, undefined);
+            assert.equal(exitProcessStub.calledWith(0), true);
+        });
+    });
+
+    describe("set", () => {
+        beforeEach(() => {
+            sandbox = sinon.createSandbox();
+        });
+
+        afterEach(() => {
+            sandbox.restore();
+        });
+
+        it(`should set the user's analytics consent in ${ADD_ON_PREFERENCES_FILE}.`, async () => {
+            const preferenceJson = new PreferenceJson({ hasTelemetryConsent: false });
+            cliPreferences.get.returns(preferenceJson);
+
+            const analyticsConsent: AnalyticsConsent = new WxpAnalyticsConsent(cliPreferences, logger);
+
+            await analyticsConsent.set(true);
+
+            assert.equal(cliPreferences.set.callCount, 1);
+            assert.equal(cliPreferences.set.calledWith(new PreferenceJson({ hasTelemetryConsent: true })), true);
+        });
+    });
+});
+
+function promptMessage(message: string): string {
+    return chalk.hex("#E59400")(message);
+}
+
+function promptMessageOption(message: string): string {
+    return chalk.green.bold(message);
+}

package/src/test/app/WxpAnalyticsService.spec.ts

@@ -0,0 +1,162 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+import type { Preferences } from "@adobe/ccweb-add-on-core";
+import { PreferenceJson } from "@adobe/ccweb-add-on-core";
+import axios from "axios";
+import { assert } from "chai";
+import "mocha";
+import osName from "os-name";
+import type { SinonSandbox } from "sinon";
+import sinon from "sinon";
+import type { StubbedInstance } from "ts-sinon";
+import { stubInterface } from "ts-sinon";
+import type { AnalyticsService } from "../../app/AnalyticsService.js";
+import { WxpAnalyticsService } from "../../app/WxpAnalyticsService.js";
+import { ANALYTICS_API } from "../../constants.js";
+import { CLIProgram } from "../../models/CLIProgram.js";
+
+describe("WxpAnalyticsService", () => {
+    let sandbox: SinonSandbox;
+
+    let cliPreferences: StubbedInstance<Preferences>;
+    let analyticsService: AnalyticsService;
+
+    const program = new CLIProgram("test-program", "1.0.0");
+
+    beforeEach(() => {
+        sandbox = sinon.createSandbox();
+
+        cliPreferences = stubInterface<Preferences>();
+        analyticsService = new WxpAnalyticsService(cliPreferences);
+    });
+
+    afterEach(() => {
+        sandbox.restore();
+    });
+
+    describe("postEvent", () => {
+        it("should post event when user has provided consent to collect and send analytics to Adobe.", async () => {
+            const currentTime = Date.now();
+            sandbox.stub(Date, "now").returns(currentTime);
+
+            const clientId = 10001;
+            const preferenceJSON = new PreferenceJson({ clientId, hasTelemetryConsent: true });
+
+            cliPreferences.get.returns(preferenceJSON);
+
+            sandbox.stub(Math, "random").returns(0.3);
+
+            const axiosPostStub = sandbox.stub(axios, "post");
+            axiosPostStub.resolves();
+
+            const eventType = "SUCCESS";
+            const eventData = "foobar";
+
+            const expectedApiRequestBody = JSON.stringify({
+                id: Math.floor(currentTime * Math.random()),
+                timestamp: currentTime,
+                _adobeio: {
+                    eventType,
+                    eventData,
+                    cliVersion: program.version,
+                    clientId,
+                    command: program.name,
+                    commandDuration: 0,
+                    commandSuccess: true,
+                    nodeVersion: process.version,
+                    osNameVersion: osName()
+                }
+            });
+
+            analyticsService.program = program;
+            analyticsService.startTime = Date.now();
+
+            await analyticsService.postEvent(eventType, eventData, true);
+
+            assert.equal(cliPreferences.set.callCount, 0);
+            assert.equal(
+                axiosPostStub.calledOnceWith(ANALYTICS_API.URL, expectedApiRequestBody, {
+                    headers: ANALYTICS_API.HEADERS
+                }),
+                true
+            );
+        });
+
+        const runs = [{ hasTelemetryConsent: undefined }, { hasTelemetryConsent: false }];
+        runs.forEach(({ hasTelemetryConsent }) => {
+            it("should not post event when user has not provided consent to collect and send analytics to Adobe.", async () => {
+                const currentTime = Date.now();
+                sandbox.stub(Date, "now").returns(currentTime);
+
+                const clientId = 10001;
+                const preferenceJSON = new PreferenceJson({ clientId, hasTelemetryConsent });
+
+                cliPreferences.get.returns(preferenceJSON);
+
+                sandbox.stub(Math, "random").returns(0.3);
+
+                const axiosPostStub = sandbox.stub(axios, "post");
+
+                const eventType = "SUCCESS";
+                const eventData = "foobar";
+
+                analyticsService.program = program;
+                analyticsService.startTime = currentTime;
+
+                await analyticsService.postEvent(eventType, eventData, true);
+
+                assert.equal(axiosPostStub.callCount, 0);
+            });
+        });
+
+        it("should set a new clientId for the user if it does not exist and silently return for any errors.", async () => {
+            const currentTime = Date.now();
+            sandbox.stub(Date, "now").returns(currentTime);
+
+            const preferenceJSON = new PreferenceJson({ hasTelemetryConsent: true });
+
+            cliPreferences.get.returns(preferenceJSON);
+            cliPreferences.set.returns();
+
+            sandbox.stub(Math, "random").returns(0.3);
+
+            const axiosPostStub = sandbox.stub(axios, "post");
+            axiosPostStub.rejects();
+
+            const eventType = "SUCCESS";
+            const eventData = "foobar";
+
+            analyticsService.program = program;
+            analyticsService.startTime = currentTime;
+
+            await analyticsService.postEvent(eventType, eventData, true);
+
+            preferenceJSON.clientId = Math.floor(Date.now() * Math.random());
+
+            assert.equal(cliPreferences.set.calledOnceWith(preferenceJSON), true);
+            assert.equal(axiosPostStub.callCount, 1);
+        });
+    });
+});

package/src/test/models/CLIProgram.spec.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * MIT License
+
+ * © Copyright 2023 Adobe. All rights reserved.
+
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ********************************************************************************/
+
+import { assert } from "chai";
+import "mocha";
+import { CLIProgram } from "../../models/index.js";
+
+describe("CLIProgram", () => {
+    describe("constructor", () => {
+        it("should create a new instance of CLIOptions.", () => {
+            const name = "test-program";
+            const version = "1.0.0";
+
+            const cliProgram = new CLIProgram(name, version);
+
+            assert.equal(cliProgram.name, name);
+            assert.equal(cliProgram.version, version);
+        });
+    });
+});

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "allowSyntheticDefaultImports": true,
+        "declaration": true,
+        "declarationMap": true,
+        "emitDecoratorMetadata": true,
+        "esModuleInterop": true,
+        "experimentalDecorators": true,
+        "forceConsistentCasingInFileNames": true,
+        "importHelpers": true,
+        "incremental": true,
+        "isolatedModules": true,
+        "module": "ESNext",
+        "moduleResolution": "node",
+        "noImplicitOverride": false,
+        "noUnusedLocals": true,
+        "outDir": "dist",
+        "preserveConstEnums": true,
+        "resolveJsonModule": true,
+        "sourceMap": true,
+        "strict": true,
+        "target": "ESNext",
+        "types": ["reflect-metadata"],
+        "useUnknownInCatchVariables": false
+    },
+    "exclude": ["node_modules", "src/test/**/*"],
+    "include": ["src/**/*"],
+    "ts-node": {
+        "files": true
+    }
+}