dce-reactkit 3.2.0-beta.1 → 3.2.0-beta.11

package/src/helpers/genRouteHandler.ts

@@ -23,6 +23,8 @@ import LogSource from '../types/LogSource';
 import LogTypeSpecificInfo from '../types/Log/LogTypeSpecificInfo';
 import LogMainInfo from '../types/Log/LogMainInfo';
 import LogSourceSpecificInfo from '../types/Log/LogSourceSpecificInfo';
+import LogBuiltInMetadata from '../types/LogBuiltInMetadata';
+import LogAction from '../types/LogAction';
 
 /**
  * Generate an express API route handler
@@ -469,101 +471,174 @@ const genRouteHandler = (
       // 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
+      try {
+        // 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,
+          context: (
+            typeof opts.context === 'string'
+              ? opts.context
+              : (
+                ((opts.context as any) ?? {})._
+                ?? LogBuiltInMetadata.Context.Uncategorized
+              )
+          ),
+          subcontext: (
+            opts.subcontext
+            ?? LogBuiltInMetadata.Context.Uncategorized
+          ),
+          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
+                ?? LogBuiltInMetadata.Target.NoSpecificTarget
+              ),
+              action: (
+                (opts as any).action
+                ?? LogAction.Unknown
+              ),
+            }
+        );
 
-      // 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,
-          }
-      );
+        // 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);
+        // 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 {
-          console.log('dce-reactkit action log:', log);
+          // 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;
+        // Return log entry
+        return log;
+      } catch (err) {
+        // Print because we cannot store the error
+        console.error('Could not log the following:', opts);
+        
+        // Create a dummy log to return
+        const dummyMainInfo: LogMainInfo = {
+          id: '-1',
+          userFirstName: 'Unknown',
+          userLastName: 'Unknown',
+          userEmail: 'unknown@harvard.edu',
+          userId: 1,
+          isLearner: false,
+          isAdmin: false,
+          isTTM: false,
+          courseId: 1,
+          courseName: 'Unknown',
+          browser: {
+            name: 'Unknown',
+            version: 'Unknown',
+          },
+          device: {
+            isMobile: false,
+            os: 'Unknown',
+          },
+          year: 1,
+          month: 1,
+          day: 1,
+          hour: 1,
+          minute: 1,
+          timestamp: Date.now(),
+          tags: [],
+          metadata: {},
+          context: LogBuiltInMetadata.Context.Uncategorized,
+          subcontext: LogBuiltInMetadata.Context.Uncategorized,
+        };
+        
+        const dummyTypeSpecificInfo: LogTypeSpecificInfo = {
+          type: LogType.Error,
+          errorMessage: 'Unknown',
+          errorCode: 'Unknown',
+          errorStack: 'No Stack',
+        };
+
+        const dummySourceSpecificInfo: LogSourceSpecificInfo = {
+          source: LogSource.Server,
+          routePath: req.path,
+          routeTemplate: req.route.path,
+        };
+
+        const log: Log = {
+          ...dummyMainInfo,
+          ...dummyTypeSpecificInfo,
+          ...dummySourceSpecificInfo,
+        };
+
+        return log;
+      }
     };
 
     /*------------------------------------------------------------------------*/
@@ -617,6 +692,22 @@ const genRouteHandler = (
     ) => {
       const html = genErrorPage(opts);
       send(html, opts.status ?? 500);
+
+      // Log
+      logServerEvent({
+        context: LogBuiltInMetadata.Context.ServerRenderedErrorPage,
+        error: {
+          message: `${opts.title}: ${opts.description}`,
+          code: opts.code,
+        },
+        metadata: {
+          title: opts.title,
+          description: opts.description,
+          code: opts.code,
+          pageTitle: opts.pageTitle,
+          status: opts.status ?? 500,
+        },
+      });
     };
 
     // Call the handler
@@ -641,7 +732,15 @@ const genRouteHandler = (
     } catch (err) {
       // Send error to client (only if next wasn't called)
       if (!responseSent) {
-        return handleError(res, err);
+        handleError(res, err);
+
+        // Log server-side error
+        logServerEvent({
+          context: LogBuiltInMetadata.Context.ServerEndpointError,
+          error: err,
+        });
+
+        return;
       }
 
       // Log error that was not responded with

package/src/helpers/logClientEvent.tsx

@@ -1,5 +1,6 @@
 // Import shared types
 import LOG_ROUTE_PATH from '../constants/LOG_ROUTE_PATH';
+import LogBuiltInMetadata from '../types/LogBuiltInMetadata';
 import LogFunction from '../types/LogFunction';
 
 // Import shared functions
@@ -14,9 +15,19 @@ const logClientEvent: LogFunction = async (opts) => {
     path: LOG_ROUTE_PATH,
     method: 'POST',
     params: {
-      category: opts.category,
-      subcategory: opts.subcategory,
-      tags: JSON.stringify(opts.tags),
+      context: (
+        typeof opts.context === 'string'
+          ? opts.context
+          : (
+            ((opts.context as any) ?? {})._
+            ?? LogBuiltInMetadata.Context.Uncategorized
+          )
+      ),
+      subcontext: (
+        opts.subcontext
+        ?? LogBuiltInMetadata.Context.Uncategorized
+      ),
+      tags: JSON.stringify(opts.tags ?? []),
       metadata: JSON.stringify(opts.metadata ?? {}),
       errorMessage: (
         (opts as any).error
@@ -34,8 +45,11 @@ const logClientEvent: LogFunction = async (opts) => {
           : undefined
       ),
       target: (
-        (opts as any).target
-          ? (opts as any).target
+        (opts as any).action
+          ? (
+            (opts as any).target
+            ?? LogBuiltInMetadata.Target.NoSpecificTarget
+          )
           : undefined
       ),
       action: (

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';
@@ -61,6 +63,7 @@ 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';
@@ -115,11 +118,13 @@ export {
   parallelLimit,
   // Client helpers
   visitServerEndpoint,
+  logClientEvent,
   // Server helpers
   initServer,
   genRouteHandler,
   handleError,
   handleSuccess,
+  initLogCollection,
   // Types
   ModalButtonType,
   ModalSize,
@@ -131,6 +136,7 @@ export {
   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

@@ -79,10 +79,10 @@ const initServer = (
   /**
    * 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} 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
@@ -98,8 +98,8 @@ const initServer = (
     LOG_ROUTE_PATH,
     genRouteHandler({
       paramTypes: {
-        category: ParamType.String,
-        subcategory: ParamType.String,
+        context: ParamType.String,
+        subcontext: ParamType.String,
         tags: ParamType.JSON,
         metadata: ParamType.JSON,
         errorMessage: ParamType.StringOptional,
@@ -113,8 +113,8 @@ const initServer = (
           (params.errorMessage || params.errorCode || params.errorStack)
             // Error
             ? {
-              category: params.category,
-              subcategory: params.subcategory,
+              context: params.context,
+              subcontext: params.subcontext,
               tags: params.tags,
               metadata: params.metadata,
               error: {
@@ -125,8 +125,8 @@ const initServer = (
             }
             // Action
             : {
-              category: params.category,
-              subcategory: params.subcategory,
+              context: params.context,
+              subcontext: params.subcontext,
               tags: params.tags,
               metadata: params.metadata,
               target: params.target,

package/src/types/Log/LogMainInfo.ts

@@ -49,10 +49,10 @@ type LogMainInfo = {
   minute: number,
   // Timestamp of event (ms since epoch)
   timestamp: number,
-  // Category of the event (each app determines how to categorize its events)
-  category: string,
-  // Subcategory of the event (each app determines how to categorize its events)
-  subcategory: string,
+  // 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

package/src/types/LogAction.ts

@@ -7,6 +7,8 @@ enum LogAction {
   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)

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

@@ -10,10 +10,10 @@ type LogFunction = (
   opts: (
     // Shared info
     {
-      // Category of the event (each app determines how to categorize its events)
-      category: string,
-      // Subcategory of the event (each app determines how to categorize its events)
-      subcategory?: string,
+      // 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,
       // List of tags that apply to this action (each app determines tag usage)
       tags?: string[],
       // Additional optional custom metadata
@@ -28,11 +28,13 @@ type LogFunction = (
       }
       // 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.
-        target: string,
-        // The type of action performed on the target
-        action: LogAction,
+        // If no target is included, this should indicate that this is an action
+        // being performed on the whole feature (open/close/etc)
+        target?: string,
       }
     )
   ),