dce-reactkit 3.1.20 → 3.2.0-beta.1

package/dist/index.d.ts

@@ -515,6 +515,135 @@ declare enum ParamType {
     StringOptional = "string-optional"
 }
 
+/**
+ * Main information in a log event
+ * @author Gabe Abrams
+ */
+declare type LogMainInfo = {
+    id: string;
+    userFirstName: string;
+    userLastName: string;
+    userEmail: string;
+    userId: number;
+    isLearner: boolean;
+    isAdmin: boolean;
+    isTTM: boolean;
+    courseId: number;
+    courseName: string;
+    browser: {
+        name: string;
+        version: string;
+    };
+    device: {
+        os: string;
+        isMobile: boolean;
+    };
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    timestamp: number;
+    category: string;
+    subcategory: string;
+    tags: string[];
+    metadata?: {
+        [k: string]: any;
+    };
+};
+
+/**
+ * Source of a log event
+ * @author Gabe Abrams
+ */
+declare enum LogSource {
+    Client = "client",
+    Server = "server"
+}
+
+/**
+ * Log info that is specific to the type of source
+ * @author Gabe Abrams
+ */
+declare type LogSourceSpecificInfo = ({
+    source: LogSource.Client;
+} | {
+    source: LogSource.Server;
+    routePath: string;
+    routeTemplate: string;
+});
+
+/**
+ * Types of actions
+ * @author Gabe Abrams
+ */
+declare enum LogAction {
+    Open = "open",
+    Close = "close",
+    Expand = "expand",
+    Collapse = "collapse",
+    View = "view",
+    Interrupt = "interrupt",
+    Create = "create",
+    Edit = "edit",
+    Delete = "delete",
+    Add = "add",
+    Remove = "remove",
+    Activate = "activate",
+    Deactivate = "deactivate",
+    Peek = "peek",
+    Unknown = "unknown"
+}
+
+/**
+ * Type of a log event
+ * @author Gabe Abrams
+ */
+declare enum LogType {
+    Action = "action",
+    Error = "error"
+}
+
+/**
+ * Log info that is specific to the type of log
+ * @author Gabe Abrams
+ */
+declare type LogTypeSpecificInfo = ({
+    type: LogType.Error;
+    errorMessage: string;
+    errorCode: string;
+    errorStack: string;
+} | {
+    type: LogType.Action;
+    target: string;
+    action: LogAction;
+});
+
+/**
+ * A single log event corresponding to an action performed by a user or an
+ *   error encountered by a user
+ * @author Gabe Abrams
+ */
+declare type Log = (LogMainInfo & LogSourceSpecificInfo & LogTypeSpecificInfo);
+
+/**
+ * Type of a log action function
+ * @author Gabe Abrams
+ */
+declare type LogFunction = (opts: ({
+    category: string;
+    subcategory?: string;
+    tags?: string[];
+    metadata?: {
+        [k: string]: any;
+    };
+} & ({
+    error: any;
+} | {
+    target: string;
+    action: LogAction;
+}))) => Promise<Log>;
+
 /**
  * Generate an express API route handler
  * @author Gabe Abrams
@@ -556,6 +685,7 @@ declare const genRouteHandler: (opts: {
             pageTitle?: string | undefined;
             status?: number | undefined;
         } | undefined) => void;
+        logServerEvent: LogFunction;
     }) => any;
     skipSessionCheck?: boolean | undefined;
 }) => (req: any, res: any, next: () => void) => Promise<undefined>;
@@ -594,10 +724,16 @@ declare type GetLaunchInfoFunction = (req: any) => {
  * Prepare dce-reactkit to run on the server
  * @author Gabe Abrams
  * @param opts object containing all arguments
+ * @param opts.app express app from inside of the postprocessor function that
+ *   we will add routes to
  * @param opts.getLaunchInfo CACCL LTI's get launch info function
+ * @param [opts.logCollection] mongo collection from dce-mango to use for
+ *   storing logs. If none is included, logs are written to the console
  */
 declare const initServer: (opts: {
+    app: any;
     getLaunchInfo: GetLaunchInfoFunction;
+    logCollection?: any;
 }) => void;
 
 /**
@@ -727,4 +863,4 @@ declare enum DayOfWeek {
     Sunday = "u"
 }
 
-export { AppWrapper, ButtonInputGroup, CheckboxButton, CopiableBox, DAY_IN_MS, DayOfWeek, Drawer, ErrorBox, ErrorWithCode, HOUR_IN_MS, ItemPicker, LoadingSpinner, MINUTE_IN_MS, Modal, ModalButtonType, ModalSize, ModalType, ParamType, PickableItem, PopFailureMark, PopPendingMark, PopSuccessMark, RadioButton, ReactKitErrorCode, SimpleDateChooser, TabBox, Variant, abbreviate, alert, avg, ceilToNumDecimals, confirm, floorToNumDecimals, forceNumIntoBounds, genRouteHandler, getHumanReadableDate, getOrdinal, getPartOfDay, getTimeInfoInET, handleError, handleSuccess, initServer, onlyKeepLetters, padDecimalZeros, padZerosLeft, parallelLimit, roundToNumDecimals, showFatalError, startMinWait, stringsToHumanReadableList, stubServerEndpoint, sum, visitServerEndpoint, waitMs };
+export { AppWrapper, ButtonInputGroup, CheckboxButton, CopiableBox, DAY_IN_MS, DayOfWeek, Drawer, ErrorBox, ErrorWithCode, HOUR_IN_MS, ItemPicker, LoadingSpinner, Log, LogAction, LogSource, LogType, MINUTE_IN_MS, Modal, ModalButtonType, ModalSize, ModalType, ParamType, PickableItem, PopFailureMark, PopPendingMark, PopSuccessMark, RadioButton, ReactKitErrorCode, SimpleDateChooser, TabBox, Variant, abbreviate, alert, avg, ceilToNumDecimals, confirm, floorToNumDecimals, forceNumIntoBounds, genRouteHandler, getHumanReadableDate, getOrdinal, getPartOfDay, getTimeInfoInET, handleError, handleSuccess, initServer, onlyKeepLetters, padDecimalZeros, padZerosLeft, parallelLimit, roundToNumDecimals, showFatalError, startMinWait, stringsToHumanReadableList, stubServerEndpoint, sum, visitServerEndpoint, waitMs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dce-reactkit",
-  "version": "3.1.20",
+  "version": "3.2.0-beta.1",
   "description": "Shared components for Harvard DCE apps",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/components/AppWrapper.tsx

@@ -303,7 +303,7 @@ const AppWrapper: React.FC<Props> = (props: Props): React.ReactElement => {
     undefined
     | {
       title: string,
-      text: string
+      text: string,
     }
   >(undefined);
   setAlertInfo = setAlertInfoInner;

package/src/constants/LOG_ROUTE_PATH.ts

@@ -0,0 +1,9 @@
+import ROUTE_PATH_PREFIX from './ROUTE_PATH_PREFIX';
+
+/**
+ * Path of the route for storing client-side logs
+ * @author Gabe Abrams
+ */
+const LOG_ROUTE_PATH = `${ROUTE_PATH_PREFIX}/log`;
+
+export default LOG_ROUTE_PATH;

package/src/constants/ROUTE_PATH_PREFIX.ts

@@ -0,0 +1,7 @@
+/**
+ * Path that all routes start with
+ * @author Gabe Abrams
+ */
+const ROUTE_PATH_PREFIX = '/dce-reactkit';
+
+export default ROUTE_PATH_PREFIX;

package/src/helpers/genRouteHandler.ts

@@ -1,5 +1,8 @@
 // Import caccl functions
-import { cacclGetLaunchInfo } from '../server/initServer';
+import {
+  cacclGetLaunchInfo,
+  internalGetLogCollection,
+} from '../server/initServer';
 
 // Import shared types
 import ReactKitErrorCode from '../types/ReactKitErrorCode';
@@ -9,6 +12,17 @@ import ParamType from '../types/ParamType';
 import handleError from './handleError';
 import handleSuccess from './handleSuccess';
 import genErrorPage from '../html/genErrorPage';
+import parseUserAgent from './parseUserAgent';
+import getTimeInfoInET from './getTimeInfoInET';
+
+// Import shared types
+import LogFunction from '../types/LogFunction';
+import Log from '../types/Log';
+import LogType from '../types/LogType';
+import LogSource from '../types/LogSource';
+import LogTypeSpecificInfo from '../types/Log/LogTypeSpecificInfo';
+import LogMainInfo from '../types/Log/LogMainInfo';
+import LogSourceSpecificInfo from '../types/Log/LogSourceSpecificInfo';
 
 /**
  * Generate an express API route handler
@@ -55,6 +69,7 @@ const genRouteHandler = (
             status?: number,
           },
         ) => void,
+        logServerEvent: LogFunction,
       },
     ) => any,
     skipSessionCheck?: boolean,
@@ -439,6 +454,118 @@ const genRouteHandler = (
       );
     }
 
+    /*----------------------------------------*/
+    /*               Log Handler              */
+    /*----------------------------------------*/
+
+    // Create a log handler function
+
+    /**
+     * Log an event on the server
+     * @author Gabe Abrams
+     */
+    const logServerEvent: LogFunction = async (opts) => {
+      // NOTE: internally, we slip through an opts.overrideAsClientEvent boolean
+      // that indicates that this is actually a client event, but we don't
+      // include that in the LogFunction type because this is internal and
+      // hidden from users
+
+      // Parse user agent
+      const {
+        browser,
+        device,
+      } = parseUserAgent(req.headers['user-agent']);
+
+      // Get time info in ET
+      const {
+        timestamp,
+        year,
+        month,
+        day,
+        hour,
+        minute,
+      } = getTimeInfoInET();
+
+      // Main log info
+      const mainLogInfo: LogMainInfo = {
+        id: `${launchInfo.userId}-${Date.now()}-${Math.floor(Math.random() * 100000)}-${Math.floor(Math.random() * 100000)}`,
+        userFirstName: launchInfo.userFirstName,
+        userLastName: launchInfo.userLastName,
+        userEmail: launchInfo.userEmail,
+        userId: launchInfo.userId,
+        isLearner: !!launchInfo.isLearner,
+        isAdmin: !!launchInfo.isAdmin,
+        isTTM: !!launchInfo.isTTM,
+        courseId: launchInfo.courseId,
+        courseName: launchInfo.courseName,
+        browser,
+        device,
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        timestamp,
+        category: opts.category,
+        subcategory: opts.subcategory ?? 'none',
+        tags: opts.tags ?? [],
+        metadata: opts.metadata ?? {},
+      };
+
+      // Type-specific info
+      const typeSpecificInfo: LogTypeSpecificInfo = (
+        ('error' in opts && opts.error)
+          ? {
+            type: LogType.Error,
+            errorMessage: opts.error.message ?? 'Unknown message',
+            errorCode: opts.error.code ?? ReactKitErrorCode.NoCode,
+            errorStack: opts.error.stack ?? 'No stack',
+          }
+          : {
+            type: LogType.Action,
+            target: (opts as any).target ?? 'Unknown',
+            action: (opts as any).action ?? 'Unknown'
+          }
+      );
+
+      // Source-specific info
+      const sourceSpecificInfo: LogSourceSpecificInfo = (
+        (opts as any).overrideAsClientEvent
+          ? {
+            source: LogSource.Client,
+          }
+          : {
+            source: LogSource.Server,
+            routePath: req.path,
+            routeTemplate: req.route.path,
+          }
+      );
+
+      // Build log event
+      const log: Log = {
+        ...mainLogInfo,
+        ...typeSpecificInfo,
+        ...sourceSpecificInfo,
+      };
+
+      // Either print to console or save to db
+      const logCollection = internalGetLogCollection();
+      if (logCollection) {
+        // Store to the log collection
+        await logCollection.insert(log);
+      } else {
+        // Print to console
+        if (log.type === LogType.Error) {
+          console.error('dce-reactkit error log:', log);
+        } else {
+          console.log('dce-reactkit action log:', log);
+        }
+      }
+
+      // Return log entry
+      return log;
+    };
+
     /*------------------------------------------------------------------------*/
     /*                              Call handler                              */
     /*------------------------------------------------------------------------*/
@@ -504,6 +631,7 @@ const genRouteHandler = (
         },
         redirect,
         renderErrorPage,
+        logServerEvent,
       });
 
       // Send results to client (only if next wasn't called)

package/src/helpers/logClientEvent.tsx

@@ -0,0 +1,50 @@
+// Import shared types
+import LOG_ROUTE_PATH from '../constants/LOG_ROUTE_PATH';
+import LogFunction from '../types/LogFunction';
+
+// Import shared functions
+import visitServerEndpoint from './visitServerEndpoint';
+
+/**
+ * Log a user action on the client (cannot be used on the server)
+ * @author Gabe Abrams
+ */
+const logClientEvent: LogFunction = async (opts) => {
+  return visitServerEndpoint({
+    path: LOG_ROUTE_PATH,
+    method: 'POST',
+    params: {
+      category: opts.category,
+      subcategory: opts.subcategory,
+      tags: JSON.stringify(opts.tags),
+      metadata: JSON.stringify(opts.metadata ?? {}),
+      errorMessage: (
+        (opts as any).error
+          ? (opts as any).error.message
+          : undefined
+      ),
+      errorCode: (
+        (opts as any).error
+          ? (opts as any).error.code
+          : undefined
+      ),
+      errorStack: (
+        (opts as any).error
+          ? (opts as any).error.stack
+          : undefined
+      ),
+      target: (
+        (opts as any).target
+          ? (opts as any).target
+          : undefined
+      ),
+      action: (
+        (opts as any).action
+          ? (opts as any).action
+          : undefined
+      ),
+    },
+  });
+};
+
+export default logClientEvent;

package/src/helpers/parseUserAgent.ts

@@ -0,0 +1,108 @@
+/**
+ * Perform a rudimentary parsing of the user's browser agent string
+ * @author Gabe Abrams
+ * @param userAgent the user's browser agent
+ * @returns user info
+ */
+const parseUserAgent = (userAgent: string) => {
+  /* ------------- Browser ------------ */
+
+  let browser: { name: string, version: string } = {
+    name: 'Unknown',
+    version: 'Unknown',
+  };
+
+  // Parse user agent
+  let verOffset: number;
+  let nameOffset: number;
+  if ((verOffset = userAgent.indexOf('Opera')) !== -1) {
+    // In Opera, the true version is after 'Opera' or after 'Version'
+    browser = {
+      name: 'Opera',
+      version: userAgent.substring(verOffset + 6),
+    };
+    if ((verOffset = userAgent.indexOf('Version')) !== -1) {
+      browser.version = userAgent.substring(verOffset + 8);
+    }
+  } else if ((verOffset = userAgent.indexOf('MSIE')) !== -1) {
+    // In MSIE, the true version is after 'MSIE' in userAgent
+    browser = {
+      name: 'Internet Explorer',
+      version: userAgent.substring(verOffset + 5),
+    };
+  } else if ((verOffset = userAgent.indexOf('Chrome')) !== -1) {
+    // In Chrome, the true version is after 'Chrome'
+    browser = {
+      name: 'Chrome',
+      version: userAgent.substring(verOffset + 7),
+    };
+  } else if ((verOffset = userAgent.indexOf('Safari')) !== -1) {
+    // In Safari, the true version is after 'Safari' or after 'Version'
+    browser = {
+      name: 'Safari',
+      version: userAgent.substring(verOffset + 7),
+    };
+    if ((verOffset = userAgent.indexOf('Version')) !== -1) {
+      browser.version = userAgent.substring(verOffset + 8);
+    }
+  } else if ((verOffset = userAgent.indexOf('Firefox')) != -1) {
+    // In Firefox, the true version is after 'Firefox'
+    browser = {
+      name: 'Firefox',
+      version: userAgent.substring(verOffset + 8),
+    };
+  } else if (
+    (nameOffset = userAgent.lastIndexOf(' ') + 1)
+    < (verOffset = userAgent.lastIndexOf('/'))
+  ) {
+    browser = {
+      name: userAgent.substring(nameOffset, verOffset),
+      version: userAgent.substring(verOffset + 1),
+    };
+  }
+
+  // Postprocess version
+  // trim the fullVersion string at semicolon/space if present
+  let ix: number;
+  if ((ix = browser.version.indexOf(';')) !== -1) {
+    browser.version = browser.version.substring(0, ix);
+  }
+  if ((ix = browser.version.indexOf(' ')) !== -1) {
+    browser.version = browser.version.substring(0, ix);
+  }
+
+  /* ------------- Device ------------- */
+
+  // Detect os
+  let os = 'Unknown';
+  if (userAgent.includes('Linux')) {
+    os = 'Linux';
+  } else if (userAgent.includes('like Mac')) {
+    os = 'iOS';
+  } else if (userAgent.includes('Mac')) {
+    os = 'Mac';
+  } else if (userAgent.includes('Android')) {
+    os = 'Android';
+  } else if (userAgent.includes('Win')) {
+    os = 'Win';
+  }
+
+  // Check if mobile
+  const isMobile = !!userAgent.match(/(iPhone|iPod|iPad|Android|BlackBerry)/);
+
+  // Device
+  const device = {
+    isMobile,
+    os,
+  };
+
+  /* ------------- Finish ------------- */
+  
+  // Return info
+  return {
+    browser,
+    device,
+  };
+};
+
+export default parseUserAgent;

package/src/index.ts

@@ -57,6 +57,10 @@ import ReactKitErrorCode from './types/ReactKitErrorCode';
 import Variant from './types/Variant';
 import ParamType from './types/ParamType';
 import DayOfWeek from './types/DayOfWeek';
+import Log from './types/Log';
+import LogType from './types/LogType';
+import LogSource from './types/LogSource';
+import LogAction from './types/LogAction';
 
 // Component-specific-types
 import PickableItem from './components/ItemPicker/types/PickableItem';
@@ -123,6 +127,10 @@ export {
   ReactKitErrorCode,
   Variant,
   DayOfWeek,
+  Log,
+  LogType,
+  LogSource,
+  LogAction,
   // Component-specific-types
   PickableItem,
   // Server types

package/src/server/initServer.ts

@@ -1,5 +1,12 @@
 // Import custom error
+import LOG_ROUTE_PATH from '../constants/LOG_ROUTE_PATH';
 import ErrorWithCode from '../errors/ErrorWithCode';
+
+// Import shared helpers
+import genRouteHandler from '../helpers/genRouteHandler';
+import ParamType from '../types/ParamType';
+
+// Import shared types
 import ReactKitErrorCode from '../types/ReactKitErrorCode';
 
 // Types
@@ -11,6 +18,9 @@ type GetLaunchInfoFunction = (req: any) => {
 // Stored copy of caccl functions
 let _cacclGetLaunchInfo: GetLaunchInfoFunction;
 
+// Stored copy of dce-mango log collection
+let _logCollection: any;
+
 /*------------------------------------------------------------------------*/
 /*                                 Helpers                                */
 /*------------------------------------------------------------------------*/
@@ -32,6 +42,16 @@ export const cacclGetLaunchInfo: GetLaunchInfoFunction = (req: any) => {
   return _cacclGetLaunchInfo(req);
 };
 
+/**
+ * Get log collection
+ * @author Gabe Abrams
+ * @returns log collection if one was included during launch or null if we don't
+ *   have a log collection (yet)
+ */
+export const internalGetLogCollection = () => {
+  return _logCollection ?? null;
+};
+
 /*------------------------------------------------------------------------*/
 /*                                  Main                                  */
 /*------------------------------------------------------------------------*/
@@ -40,14 +60,84 @@ export const cacclGetLaunchInfo: GetLaunchInfoFunction = (req: any) => {
  * Prepare dce-reactkit to run on the server
  * @author Gabe Abrams
  * @param opts object containing all arguments
+ * @param opts.app express app from inside of the postprocessor function that
+ *   we will add routes to
  * @param opts.getLaunchInfo CACCL LTI's get launch info function
+ * @param [opts.logCollection] mongo collection from dce-mango to use for
+ *   storing logs. If none is included, logs are written to the console
  */
 const initServer = (
   opts: {
+    app: any,
     getLaunchInfo: GetLaunchInfoFunction,
+    logCollection?: any,
   },
 ) => {
   _cacclGetLaunchInfo = opts.getLaunchInfo;
+  _logCollection = opts.logCollection;
+
+  /**
+   * Log an event
+   * @author Gabe Abrams
+   * @param {string} category Category of the event (each app determines how to
+   *   categorize its events)
+   * @param {string} subcategory Subcategory of the event (each app determines
+   *   how to categorize its events)
+   * @param {string} tags stringified list of tags that apply to this action
+   *   (each app determines tag usage)
+   * @param {string} metadata stringified object containing optional custom metadata
+   * @param {string} [errorMessage] error message if type is an error
+   * @param {string} [errorCode] error code if type is an error
+   * @param {string} [errorStack] error stack if type is an error
+   * @param {string} [target] Target of the action (each app determines the list
+   *   of targets) These are usually buttons, panels, elements, etc.
+   * @param {LogAction} [action] the type of action performed on the target
+   * @returns {Log}
+   */
+  opts.app.post(
+    LOG_ROUTE_PATH,
+    genRouteHandler({
+      paramTypes: {
+        category: ParamType.String,
+        subcategory: ParamType.String,
+        tags: ParamType.JSON,
+        metadata: ParamType.JSON,
+        errorMessage: ParamType.StringOptional,
+        errorCode: ParamType.StringOptional,
+        errorStack: ParamType.StringOptional,
+        target: ParamType.StringOptional,
+        action: ParamType.StringOptional,
+      },
+      handler: ({ params, logServerEvent }) => {
+        const log = logServerEvent(
+          (params.errorMessage || params.errorCode || params.errorStack)
+            // Error
+            ? {
+              category: params.category,
+              subcategory: params.subcategory,
+              tags: params.tags,
+              metadata: params.metadata,
+              error: {
+                message: params.errorMessage,
+                code: params.errorCode,
+                stack: params.errorStack,
+              },
+            }
+            // Action
+            : {
+              category: params.category,
+              subcategory: params.subcategory,
+              tags: params.tags,
+              metadata: params.metadata,
+              target: params.target,
+              action: params.action,
+            }
+        );
+
+        return log;
+      },
+    }),
+  );
 };
 
 export default initServer;