Update office plugin for mixpanel support

Author: jgreywolf

cSpell.json

@@ -4,17 +4,20 @@
   "words": [
     "Cataa",
     "colour",
+    "Cookiebot",
     "jsnext",
     "lintstagedrc",
     "mermaidchart",
     "mermaidjs",
     "openapi",
     "outfile",
+    "pino",
     "pkce",
     "pnpm",
     "regexes",
     "sidharth",
     "sidharthv",
+    "skeletonlabs",
     "treeshake",
     "treeshaking",
     "ts-nocheck",

packages/office/package.json

@@ -35,6 +35,8 @@
     "lodash-es": "^4.17.21",
     "luxon": "^3.1.1",
     "mermaid": "10.2.3",
+    "mixpanel": "^0.18.0",
+    "mixpanel-browser": "^2.49.0",
     "office-addin-dev-certs": "^1.11.4",
     "openapi-types": "^12.1.3",
     "pino": "^8.11.0",
@@ -50,6 +52,7 @@
     "@tailwindcss/forms": "^0.5.3",
     "@types/lodash-es": "^4.17.6",
     "@types/luxon": "^3.1.0",
+    "@types/mixpanel-browser": "^2.38.1",
     "@types/office-js": "^1.0.350",
     "@types/office-runtime": "^1.0.33",
     "@typescript-eslint/eslint-plugin": "^5.48.2",

packages/office/src/.env.dev

@@ -2,4 +2,5 @@ PUBLIC_ENVIRONMENT="dev"
 BASIC_AUTH_LOGIN=""
 E2E_ENV="dev"
 PUBLIC_LEVEL_EXCEPTIONS="[]"
-PUBLIC_LOG_LEVEL="debug"
+PUBLIC_LOG_LEVEL="debug"
+PUBLIC_MIXPANEL_TOKEN="invalid"

packages/office/src/lib/client/featureSet.ts

@@ -0,0 +1,56 @@
+import { RuntimeEnvironment } from '$lib/enums';
+import { currentEnv } from '$lib/env';
+
+enum FeatureState {
+  Ready = 'ready',
+  UnderDevelopment = 'under development',
+  OnlyInProd = 'only in prod',
+  StageAndProd = 'only in stage and prod',
+  NotInProd = 'everywhere but in prod'
+}
+
+export enum FeatureName {
+  Editor = 'editor',
+  Dashboard = 'dashboard',
+  UserBehavior = 'userBehavior',
+  CookieBot = 'cookieBot'
+}
+
+/**
+ * Define the Features interface to describe the shape of the features object.
+ * Create a features object with a set of feature keys and their corresponding statuses.
+ */
+const features: Record<FeatureName, FeatureState> = {
+  editor: FeatureState.UnderDevelopment,
+  dashboard: FeatureState.UnderDevelopment,
+  userBehavior: FeatureState.StageAndProd,
+  cookieBot: FeatureState.OnlyInProd
+};
+
+/**
+ * Check if a feature should be used based on its status in the features object and the current environment.
+ * @param featureId - The string identifier of the feature to check.
+ * @returns true if the feature is ready or not found in the features object, or if the environment is 'dev' or 'test', false otherwise.
+ */
+export const shouldUseFeature = (featureId: FeatureName): boolean => {
+  if (features[featureId] === FeatureState.Ready) {
+    return true;
+  }
+  if (features[featureId] === FeatureState.OnlyInProd) {
+    return currentEnv === RuntimeEnvironment.Prod;
+  }
+
+  if (features[featureId] === FeatureState.StageAndProd) {
+    return currentEnv === RuntimeEnvironment.Prod || currentEnv === RuntimeEnvironment.Stage;
+  }
+
+  if (currentEnv === RuntimeEnvironment.Dev || currentEnv === RuntimeEnvironment.Test) {
+    return true;
+  }
+
+  if (features[featureId] === FeatureState.NotInProd) {
+    return currentEnv !== RuntimeEnvironment.Prod;
+  }
+
+  return false;
+};

packages/office/src/lib/client/stores/analytics.ts

@@ -0,0 +1,30 @@
+import { RuntimeEnvironment } from '$lib/enums';
+import { currentEnv } from '$lib/env';
+import { writable } from 'svelte/store';
+import { FeatureName, shouldUseFeature } from '../featureSet';
+
+interface CookieBotConsent {
+  necessary: boolean;
+  preferences: boolean;
+  marketing: boolean;
+  statistics: boolean;
+}
+
+declare global {
+  interface Window {
+    Cookiebot?: {
+      consent: CookieBotConsent;
+    };
+  }
+}
+
+export const analyticsEnabled = writable(
+  shouldUseFeature(FeatureName.UserBehavior)
+);
+
+export const updateConsent = (consent?: CookieBotConsent) => {
+  if (!consent) {
+    return;
+  }
+  analyticsEnabled.set(consent.statistics && shouldUseFeature(FeatureName.UserBehavior));
+};

packages/office/src/lib/client/stores/session.ts

@@ -0,0 +1,36 @@
+import { Tier } from '$lib/enums';
+import type { MCUser } from '$lib/mermaidChartApi';
+import { derived, writable } from 'svelte/store';
+
+const defaultSession: MCUser = {
+  emailAddress: '',
+  id: '',
+  authID: '',
+  analyticsID: '',
+  subscriptionTier: Tier.Free,
+  fullName: '',
+  allowMarketingEmail: false,
+  allowProductEmail: true
+};
+
+function createSession() {
+  const { subscribe, set, update } = writable(defaultSession);
+
+  return {
+    subscribe,
+    update: (user: MCUser) => {
+      const res = update((session) => {
+        return { ...session, ...user };
+      });
+      return res;
+    },
+    set,
+    reset: () => set(defaultSession)
+  };
+}
+
+export const sessionStore = createSession();
+
+export const isFreeUser = derived(sessionStore, ({ subscriptionTier }) => {
+  return subscriptionTier === Tier.Free;
+});

packages/office/src/lib/client/util/sendEvents.ts

@@ -0,0 +1,95 @@
+import { browser } from '$app/environment';
+import type { BehaviorEvent } from '$lib/types';
+import mixpanel from 'mixpanel-browser';
+import { analyticsEnabled } from '../stores/analytics';
+import { minutesToMilliSeconds } from '$lib/utils';
+import type { MCUser } from '$lib/mermaidChartApi';
+import log from '$lib/log';
+
+let initialized = false;
+
+interface QueueItem {
+  description: string;
+  event: BehaviorEvent;
+}
+
+const MAX_QUEUE_SIZE = 100;
+const queue: QueueItem[] = [];
+
+function sendQueue() {
+  if (queue.length === 0 || !initialized) {
+    return;
+  }
+  log.info('Sending mixpanel events');
+  for (const { description, event } of queue) {
+    try {
+      mixpanel.track(description, event);
+    } catch (error) {
+      log.error(error);
+    }
+  }
+  queue.length = 0;
+}
+
+function init(mixPanelProject: string, sessionID: string, session: MCUser) {
+  if (initialized) {
+    return;
+  }
+  // Execute code that sets marketing cookies
+  mixpanel.init(mixPanelProject, { debug: true, ignore_dnt: true });
+
+  mixpanel.identify(session?.analyticsID || sessionID);
+  mixpanel.people.set({
+    $email: session.emailAddress,
+    $name: session.fullName,
+    tier: session.subscriptionTier,
+    AllowProductEmail: session.allowProductEmail
+  });
+  initialized = true;
+  sendQueue();
+}
+
+export function initializeMixPanel(mixPanelProject: string, sessionID: string, session: MCUser) {
+  if (!browser || !mixPanelProject) {
+    return;
+  }
+  analyticsEnabled.subscribe((enabled) => {
+    // This will initialize MixPanel only after the user has accepted analytics cookies
+    if (enabled) {
+      init(mixPanelProject, sessionID, session);
+    }
+  });
+}
+
+function sendEvent(description: string, event: BehaviorEvent) {
+  // Avoid queueing too many events
+  if (queue.length < MAX_QUEUE_SIZE) {
+    queue.push({ description, event });
+  }
+  sendQueue();
+}
+
+const delaysPerEvent: Record<string, number> = {
+  DIAGRAM_TYPE: minutesToMilliSeconds(1)
+};
+const timeouts: Record<string, number> = {};
+
+export function sendBehaviorEvent(description: string, event: BehaviorEvent) {
+  if (timeouts[event.eventID]) {
+    clearTimeout(timeouts[event.eventID]);
+  }
+  if (delaysPerEvent[event.eventID] === undefined) {
+    sendEvent(description, event);
+  } else {
+    timeouts[event.eventID] = window.setTimeout(() => {
+      sendEvent(description, event);
+      delete timeouts[event.eventID];
+    }, delaysPerEvent[event.eventID]);
+  }
+}
+
+export function clear() {
+  if (browser && initialized) {
+    mixpanel.reset();
+  }
+}

packages/office/src/lib/enums.ts

@@ -19,6 +19,13 @@ export enum MessageType {
   Success = 'success'
 }
 
+export enum Tier {
+  Free = 'free',
+  Individual = 'individual',
+  Pro = 'pro',
+  Team = 'team',
+  Enterprise = 'enterprise'
+}
 
 /**
  * Type guard for enum values

packages/office/src/lib/log.ts

@@ -0,0 +1,109 @@
+/* eslint-disable no-console */
+import { browser } from '$app/environment';
+import { env as publicEnv } from '$env/dynamic/public';
+import pino, { type LoggerOptions } from 'pino';
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace';
+type LogLevelException = { name: string; level: LogLevel };
+type LogLevelExceptionArray = LogLevelException[];
+
+const logLevel = publicEnv.PUBLIC_LOG_LEVEL as LogLevel;
+const exceptionsStr = publicEnv.PUBLIC_LEVEL_EXCEPTIONS;
+
+let urlOverride;
+if (browser) {
+  urlOverride = new URLSearchParams(window.location.search).get('log-level') as LogLevel;
+}
+const logLevelKey = urlOverride || logLevel || 'info';
+
+function logMethod(args: string[], method: unknown) {
+  let newArgs;
+  if (args.length > 1) {
+    newArgs = ['%s', args.join(' ')];
+  }
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+  method.apply(this, newArgs ?? args);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = () => {};
+const getLoggerForLevel = (level: LogLevel) => {
+  let logger;
+  if (import.meta.env?.DEV) {
+    logger = {
+      trace: console.trace,
+      debug: console.debug,
+      info: console.info,
+      warn: console.warn,
+      error: console.error
+    };
+
+    switch (level) {
+      case 'error': {
+        {
+          logger.warn = noop;
+          logger.info = noop;
+          logger.debug = noop;
+          logger.trace = noop;
+        }
+        break;
+      }
+      case 'warn': {
+        {
+          logger.info = noop;
+          logger.debug = noop;
+          logger.trace = noop;
+        }
+        break;
+      }
+      case 'info': {
+        {
+          logger.debug = noop;
+          logger.trace = noop;
+        }
+        break;
+      }
+      case 'debug': {
+        logger.trace = noop;
+      }
+    }
+  } else {
+    const pinoOptions: LoggerOptions = {
+      hooks: { logMethod },
+      level
+    };
+    logger = pino(pinoOptions);
+  }
+  return logger;
+};
+const log = getLoggerForLevel(logLevelKey);
+
+export const getLogger = (name: string) => {
+  try {
+    const exceptions = JSON.parse(exceptionsStr || '[]') as LogLevelExceptionArray;
+    let logLevelForName = logLevelKey;
+
+    if (exceptions) {
+      for (const e of exceptions) {
+        if (e.name === name) {
+          logLevelForName = e.level;
+        }
+      }
+    }
+
+    const namedLogger = getLoggerForLevel(logLevelForName || logLevelKey);
+    return namedLogger;
+  } catch (error) {
+    console.error('error parsing log level exceptions', error);
+  }
+
+  return log;
+};
+
+export const getModuleLogger = (name: string) => {
+  return pino({ name, timestamp: true });
+};
+
+export default log;