dce-reactkit 3.1.20 → 3.2.0-beta.10

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

@@ -48,6 +48,8 @@ import getPartOfDay from './helpers/getPartOfDay';
 import stringsToHumanReadableList from './helpers/stringsToHumanReadableList';
 import onlyKeepLetters from './helpers/onlyKeepLetters';
 import parallelLimit from './helpers/parallelLimit';
+import logClientEvent from './helpers/logClientEvent';
+import initLogCollection from './server/initLogCollection';
 
 // Import types
 import ModalButtonType from './types/ModalButtonType';
@@ -57,6 +59,11 @@ 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';
+import LogBuiltInMetadata from './types/LogBuiltInMetadata';
 
 // Component-specific-types
 import PickableItem from './components/ItemPicker/types/PickableItem';
@@ -111,11 +118,13 @@ export {
   parallelLimit,
   // Client helpers
   visitServerEndpoint,
+  logClientEvent,
   // Server helpers
   initServer,
   genRouteHandler,
   handleError,
   handleSuccess,
+  initLogCollection,
   // Types
   ModalButtonType,
   ModalSize,
@@ -123,6 +132,11 @@ export {
   ReactKitErrorCode,
   Variant,
   DayOfWeek,
+  Log,
+  LogType,
+  LogSource,
+  LogAction,
+  LogBuiltInMetadata,
   // Component-specific-types
   PickableItem,
   // Server types

package/src/server/initLogCollection.ts

@@ -0,0 +1,22 @@
+/**
+ * Initialize a log collection given the dce-mango Collection class
+ * @author Gabe Abrams
+ * @param Collection the Collection class from dce-mango
+ * @returns initialized logCollection
+ */
+const initLogCollection = (Collection: any) => {
+  return new Collection(
+    'Log',
+    {
+      uniqueIndexKey: 'id',
+      indexKeys: [
+        'courseId',
+        'context',
+        'subcontext',
+        'tags',
+      ],
+    },
+  );
+};
+
+export default initLogCollection;

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} context Context of the event (each app determines how to
+   *   organize its contexts)
+   * @param {string} subcontext Subcontext of the event (each app determines
+   *   how to organize its subcontexts)
+   * @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: {
+        context: ParamType.String,
+        subcontext: 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
+            ? {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              metadata: params.metadata,
+              error: {
+                message: params.errorMessage,
+                code: params.errorCode,
+                stack: params.errorStack,
+              },
+            }
+            // Action
+            : {
+              context: params.context,
+              subcontext: params.subcontext,
+              tags: params.tags,
+              metadata: params.metadata,
+              target: params.target,
+              action: params.action,
+            }
+        );
+
+        return log;
+      },
+    }),
+  );
 };
 
 export default initServer;

package/src/types/Log/LogMainInfo.ts

@@ -0,0 +1,64 @@
+/**
+ * Main information in a log event
+ * @author Gabe Abrams
+ */
+type LogMainInfo = {
+  // Unique id of the log event
+  id: string,
+  // First name of the user
+  userFirstName: string,
+  // Last name of the user
+  userLastName: string,
+  // User email
+  userEmail: string,
+  // User Canvas Id
+  userId: number,
+  // If true, the user is a learner
+  isLearner: boolean,
+  // If true, the user is an admin
+  isAdmin: boolean,
+  // If true, the user is a ttm
+  isTTM: boolean,
+  // The id of the Canvas course that the user launched from
+  courseId: number,
+  // The name of the Canvas course
+  courseName: string,
+  // Browser info
+  browser: {
+    // Name of the browser
+    name: string,
+    // Version of the browser
+    version: string,
+  },
+  // Device info
+  device: {
+    // Name of the operating system
+    os: string,
+    // If true, device is a mobile device
+    isMobile: boolean,
+  },
+  // Calendar year that the event is from
+  year: number,
+  // Month that the event is from (1 = Jan, 12 = Dec)
+  month: number,
+  // Day of the month that the event is from
+  day: number,
+  // Hour of the day (24hr) when the event occurred
+  hour: number,
+  // Minute of the day when the event occurred
+  minute: number,
+  // Timestamp of event (ms since epoch)
+  timestamp: number,
+  // Context of the event (each app determines how to organize contexts)
+  context: string,
+  // Subcontext of the event (each app determines how to organize subcontexts)
+  subcontext: string,
+  // List of tags that apply to this action (each app determines tag usage)
+  tags: string[],
+  // Additional optional custom metadata
+  metadata?: {
+    [k: string]: any,
+  },
+};
+
+export default LogMainInfo;

package/src/types/Log/LogSourceSpecificInfo.ts

@@ -0,0 +1,25 @@
+// Import shared types
+import LogSource from '../LogSource';
+
+/**
+ * Log info that is specific to the type of source
+ * @author Gabe Abrams
+ */
+type LogSourceSpecificInfo = (
+  // Client
+  | {
+    // Source of the event
+    source: LogSource.Client,
+  }
+  // Server
+  | {
+    // Source of the event
+    source: LogSource.Server,
+    // Route path (e.g. /api/admin/courses/53450/blocks)
+    routePath: string,
+    // Route template (e.g. /api/admin/courses/:courseId/blocks)
+    routeTemplate: string,
+  }
+);
+
+export default LogSourceSpecificInfo;

package/src/types/Log/LogTypeSpecificInfo.ts

@@ -0,0 +1,33 @@
+// Import shared types
+import LogAction from '../LogAction';
+import LogType from '../LogType';
+
+/**
+ * Log info that is specific to the type of log
+ * @author Gabe Abrams
+ */
+type LogTypeSpecificInfo = (
+  // Error
+  | {
+    // Type of the event
+    type: LogType.Error,
+    // The error message
+    errorMessage: string,
+    // The error code
+    errorCode: string,
+    // Error stack trace
+    errorStack: string,
+  }
+  // Action
+  | {
+    // Type of the event
+    type: LogType.Action,
+    // Target of the action (each app determines the list of targets)
+    // These are usually buttons, panels, elements, etc.
+    target: string,
+    // The type of action performed on the target
+    action: LogAction,
+  }
+);
+
+export default LogTypeSpecificInfo;

package/src/types/Log/index.ts

@@ -0,0 +1,17 @@
+// Import shared types
+import LogMainInfo from './LogMainInfo';
+import LogSourceSpecificInfo from './LogSourceSpecificInfo';
+import LogTypeSpecificInfo from './LogTypeSpecificInfo';
+
+/**
+ * A single log event corresponding to an action performed by a user or an
+ *   error encountered by a user
+ * @author Gabe Abrams
+ */
+type Log = (
+  LogMainInfo
+  & LogSourceSpecificInfo
+  & LogTypeSpecificInfo
+);
+
+export default Log;

package/src/types/LogAction.ts

@@ -0,0 +1,40 @@
+/**
+ * Types of actions
+ * @author Gabe Abrams
+ */
+enum LogAction {
+  // Target was opened by the user (it was not on screen, but now it is)
+  Open = 'open',
+  // Target was closed by the user (it was on screen, but now it is not)
+  Close = 'close',
+  // Target was cancelled by the user (it was on closed without saving)
+  Cancel = 'cancel',
+  // Target was expanded by the user (it always remains on screen, but size was changed)
+  Expand = 'expand',
+  // Target was collapsed by the user (it always remains on screen, but size was changed)
+  Collapse = 'collapse',
+  // Target was viewed by the user (only for items that are not opened or closed, those must use Open/Close actions)
+  View = 'view',
+  // Target interrupted the user (popup, dialog, validation message, etc. appeared without user prompting)
+  Interrupt = 'interrupt',
+  // Target was created by the user (it did not exist before)
+  Create = 'create',
+  // Target was edited by the user (it existed and was changed)
+  Edit = 'edit',
+  // Target was deleted by the user (it existed and now it doesn't)
+  Delete = 'delete',
+  // Target was added by the user (it already existed and was added to another place)
+  Add = 'add',
+  // Target was removed by the user (it was removed from something but still exists)
+  Remove = 'remove',
+  // Target was activated by the user (click, check, tap, keypress, etc.)
+  Activate = 'activate',
+  // Target was deactivated by the user (click away, uncheck, tap outside of, tab away, etc.)
+  Deactivate = 'deactivate',
+  // User showed interest in a target (hover, peek, etc.)
+  Peek = 'peek',
+  // Unknown action
+  Unknown = 'unknown',
+};
+
+export default LogAction;

package/src/types/LogBuiltInMetadata.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in metadata for logs
+ * @author Gabe Abrams
+ */
+const LogBuiltInMetadata = {
+  // Contexts
+  Context: {
+    Uncategorized: 'n/a',
+    ServerRenderedErrorPage: '_server-rendered-error-page',
+    ServerEndpointError: '_server-endpoint-error',
+  },
+  // Targets
+  Target: {
+    NoSpecificTarget: 'n/a',
+  },
+};
+
+export default LogBuiltInMetadata;

package/src/types/LogFunction.ts

@@ -0,0 +1,43 @@
+// Import shared types
+import Log from './Log';
+import LogAction from './LogAction';
+
+/**
+ * Type of a log action function
+ * @author Gabe Abrams
+ */
+type LogFunction = (
+  opts: (
+    // Shared info
+    {
+      // Context of the event (each app determines how to organize contexts)
+      context: string | { _: string },
+      // Subcontext of the event (each app determines how to organize subcontexts)
+      subcontext?: string | { _: string },
+      // List of tags that apply to this action (each app determines tag usage)
+      tags?: string[],
+      // Additional optional custom metadata
+      metadata?: {
+        [k: string]: any,
+      },
+    } & (
+      // Error
+      | {
+        // The error object to log
+        error: any,
+      }
+      // Action
+      | {
+        // The type of action performed
+        action: LogAction,
+        // Target of the action (each app determines the list of targets)
+        // These are usually buttons, panels, elements, etc.
+        // If no target is included, this should indicate that this is an action
+        // being performed on the whole feature (open/close/etc)
+        target?: string,
+      }
+    )
+  ),
+) => Promise<Log>;
+
+export default LogFunction;

package/src/types/LogSource.ts

@@ -0,0 +1,12 @@
+/**
+ * Source of a log event
+ * @author Gabe Abrams
+ */
+enum LogSource {
+  // Client
+  Client = 'client',
+  // Server
+  Server = 'server',
+};
+
+export default LogSource;

package/src/types/LogType.ts

@@ -0,0 +1,12 @@
+/**
+ * Type of a log event
+ * @author Gabe Abrams
+ */
+enum LogType {
+  // User action
+  Action = 'action',
+  // Error
+  Error = 'error',
+};
+
+export default LogType;