dce-expresskit 4.0.0-beta.10

package/src/helpers/visitEndpointOnAnotherServer/sendServerToServerRequest.ts

@@ -0,0 +1,164 @@
+// Import libs
+import qs from 'qs';
+
+// Import dce-reactkit
+import {
+  ErrorWithCode,
+} from 'dce-reactkit';
+
+// Import shared types
+import ExpressKitErrorCode from '../../types/ExpressKitErrorCode';
+
+/**
+ * Sends and retries an http request
+ * @author Gabriel Abrams
+ * @param opts object containing all arguments
+ * @param opts.path path to send request to
+ * @param [opts.host] host to send request to
+ * @param [opts.method=GET] http method to use
+ * @param [opts.params] body/data to include in the request
+ * @param [opts.responseType=JSON] expected response type
+ * @returns { body, status, headers } on success
+ */
+const sendServerToServerRequest = async (
+  opts: {
+    path: string,
+    host?: string,
+    method?: ('GET' | 'POST' | 'PUT' | 'DELETE'),
+    params?: { [k in string]: any },
+    responseType?: 'Text' | 'JSON',
+  },
+): Promise<{
+  body: any,
+  status: number,
+  headers: { [k in string]: any },
+}> => {
+  // Process method
+  const method: ('GET' | 'POST' | 'PUT' | 'DELETE') = (opts.method || 'GET');
+
+  // Encode objects within params
+  let params: {
+    [k in string]: any
+  } | undefined;
+  if (opts.params) {
+    params = {};
+    Object.entries(opts.params).forEach(([key, val]) => {
+      if (typeof val === 'object' && !Array.isArray(val)) {
+        (params as any)[key] = JSON.stringify(val);
+      } else {
+        (params as any)[key] = val;
+      }
+    });
+  }
+
+  // Stringify parameters
+  const stringifiedParams = qs.stringify(params || {}, {
+    encodeValuesOnly: true,
+    arrayFormat: 'brackets',
+  });
+
+  // Create url (include query if GET)
+  const query = (method === 'GET' ? `?${stringifiedParams}` : '');
+  let url;
+  if (!opts.host) {
+    // No host included at all. Just send to a path
+    url = `${opts.path}${query}`;
+  } else {
+    url = `https://${opts.host}${opts.path}${query}`;
+  }
+
+  // Update headers
+  const headers: {
+    [k: string]: any,
+  } = {};
+  let data: string | null | { [k: string]: any } | undefined = null;
+  if (!headers['Content-Type']) {
+    // Form encoded
+    headers['Content-Type'] = 'application/x-www-form-urlencoded';
+    // Add data if applicable
+    data = (method !== 'GET' ? stringifiedParams : null);
+  } else {
+    // JSON encode
+    data = params;
+  }
+
+  // Encode data
+  let encodedData: URLSearchParams | string | undefined;
+  if (data) {
+    if (headers['Content-Type'] === 'application/x-www-form-urlencoded') {
+      encodedData = new URLSearchParams(params);
+    } else {
+      encodedData = JSON.stringify(data);
+    }
+  }
+
+  // Send request
+  try {
+    const response = await fetch(
+      url,
+      {
+        method,
+        mode: 'cors',
+        headers: headers ?? {},
+        body: (
+          (method !== 'GET' && encodedData)
+            ? encodedData
+            : undefined
+        ),
+        redirect: 'follow',
+      },
+    );
+
+    // Get headers map
+    const responseHeaders: {
+      [k in string]: string
+    } = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+
+    // Process response based on responseType
+    try {
+      // Parse response
+      let responseBody: any;
+      if (
+        opts.responseType
+        && opts.responseType === 'Text'
+      ) {
+        // Response type is text
+        responseBody = await response.text();
+      } else {
+        // Response type is JSON
+        responseBody = await response.json();
+      }
+
+      // Return response
+      return {
+        body: responseBody,
+        status: response.status,
+        headers: responseHeaders,
+      };
+    } catch (err) {
+      throw new ErrorWithCode(
+        `Failed to parse response as ${opts.responseType}: ${(err as any)?.message}`,
+        ExpressKitErrorCode.ResponseParseError,
+      );
+    }
+  } catch (err) {
+    // Self-signed certificate error:
+    if ((err as any)?.message?.includes('self signed certificate')) {
+      throw new ErrorWithCode(
+        'We refused to send a request because the receiver has self-signed certificates.',
+        ExpressKitErrorCode.SelfSigned,
+      );
+    }
+
+    // No tries left
+    throw new ErrorWithCode(
+      `We encountered an error when trying to send a network request. If this issue persists, contact an admin. Error: ${(err as any)?.message}`,
+      ExpressKitErrorCode.NotConnected,
+    );
+  }
+};
+
+export default sendServerToServerRequest;

package/src/html/genErrorPage.ts

@@ -0,0 +1,144 @@
+// Import dce-reactkit
+import { ReactKitErrorCode } from 'dce-reactkit';
+
+// Import shared types
+import ExpressKitErrorCode from '../types/ExpressKitErrorCode';
+
+/**
+ * Generate a static error page
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param [opts.title=An Error Occurred] title of the error box
+ * @param [opts.description=An unknown server error occurred. Please contact support.]
+ *   a human-readable description of the error
+ * @param [opts.code=ReactKitErrorCode.NoCode] error code to show
+ * @param [opts.pageTitle=opts.title] title of the page/tab if it differs from
+ *   the title of the error
+ * @returns html of the page
+ */
+const genErrorPage = (
+  opts: {
+    title?: string,
+    description?: string,
+    code?: string,
+    pageTitle?: string,
+  } = {},
+): string => {
+  const title = (opts.title ?? 'An Error Occurred');
+  const pageTitle = (opts.pageTitle ?? title);
+  const description = (
+    opts.description
+    ?? 'An unknown server error occurred. Please contact support.'
+  );
+  const code = (opts.code ?? ReactKitErrorCode.NoCode);
+
+  return `
+<head>
+  <!-- Metadata -->
+  <meta
+    name="viewport"
+    content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0"
+  >
+
+  <!-- Title -->
+  <title>${pageTitle}</title>
+
+  <!-- Bootstrap -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/css/bootstrap.min.css"
+    integrity="sha512-siwe/oXMhSjGCwLn+scraPOWrJxHlUgMBMZXdPe2Tnk3I0x3ESCoLz7WZ5NTH6SZrywMY+PB1cjyqJ5jAluCOg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+  <script
+    src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/js/bootstrap.min.js"
+    integrity="sha512-vyRAVI0IEm6LI/fVSv/Wq/d0KUfrg3hJq2Qz5FlfER69sf3ZHlOrsLriNm49FxnpUGmhx+TaJKwJ+ByTLKT+Yg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  ></script>
+
+  <!-- FontAwesome -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.0/css/all.min.css"
+    integrity="sha512-xh6O/CkQoPOWDdYTDqeRdPCVd1SpvCA9XXcUnZS2FmJNp1coAFzvtCN9BmamE+4aHK8yyUHUSCcJHgXloTyT2A=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+
+  <!-- Style -->
+  <style>
+    .DCEReactKit-pop-in {
+      animation-name: DCEReactKit-pop-in;
+      animation-duration: 0.5s;
+      animation-iteration-count: 1;
+      animation-timing-function: ease-out;
+      animation-fill-mode: both;
+
+      transform-origin: center;
+    }
+
+    @keyframes DCEReactKit-pop-in {
+      0% {
+        opacity: 0;
+        transform: scale(0.9);
+      }
+      100% {
+        opacity: 1;
+        transform: scale(1);
+      }
+    }
+
+    .DCEReactKit-slide-in {
+      animation-name: DCEReactKit-slide-in;
+      animation-duration: 1s;
+      animation-iteration-count: 1;
+      animation-timing-function: ease-out;
+      animation-fill-mode: both;
+      animation-delay: 0.2s;
+    }
+
+    @keyframes DCEReactKit-slide-in {
+      0% {
+        opacity: 0;
+        transform: translate(0, 0.3em);
+      }
+      100% {
+        opacity: 1;
+        transform: translate(0, 0);
+      }
+    }
+  </style>
+</head>
+
+<!-- Body -->
+<body class="bg-dark text-center pt-3 ps-3 pe-3">
+  <!-- Alert -->
+  <div
+    class="DCEReactKit-pop-in alert alert-warning d-inline-block"
+    style="width: 50em; max-width: 100%"
+  >
+    <!-- Title -->
+    <h2>
+      <i class="me-1 fa-solid fa-triangle-exclamation"></i>
+      ${title}
+    </h2>
+    <!-- Description -->
+    <div>
+      ${description}
+    </div>
+  </div>
+
+  <!-- Error Code -->
+  <div class="DCEReactKit-slide-in text-light">
+    <strong>
+      Error Code:
+    </strong>
+    ${code}
+  </div>
+</body>
+  `;
+};
+
+export default genErrorPage;

package/src/html/genInfoPage.ts

@@ -0,0 +1,101 @@
+/**
+ * Generate a static info page
+ * @author Gabe Abrams
+ * @param opts object containing all arguments
+ * @param opts.title title of the info box
+ * @param opts.body a human-readable text body for the info alert
+ * @returns the HTML for the info page
+ */
+const genInfoPage = (
+  opts: {
+    title: string,
+    body: string,
+  },
+): string => {
+  const {
+    title,
+    body,
+  } = opts;
+
+  return `
+<head>
+  <!-- Metadata -->
+  <meta
+    name="viewport"
+    content="width=device-width, height=device-height, initial-scale=1.0, minimum-scale=1.0"
+  >
+
+  <!-- Title -->
+  <title>${title}</title>
+
+  <!-- Bootstrap -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/css/bootstrap.min.css"
+    integrity="sha512-siwe/oXMhSjGCwLn+scraPOWrJxHlUgMBMZXdPe2Tnk3I0x3ESCoLz7WZ5NTH6SZrywMY+PB1cjyqJ5jAluCOg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+  <script
+    src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.2.1/js/bootstrap.min.js"
+    integrity="sha512-vyRAVI0IEm6LI/fVSv/Wq/d0KUfrg3hJq2Qz5FlfER69sf3ZHlOrsLriNm49FxnpUGmhx+TaJKwJ+ByTLKT+Yg=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  ></script>
+
+  <!-- FontAwesome -->
+  <link
+    rel="stylesheet"
+    href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.0/css/all.min.css"
+    integrity="sha512-xh6O/CkQoPOWDdYTDqeRdPCVd1SpvCA9XXcUnZS2FmJNp1coAFzvtCN9BmamE+4aHK8yyUHUSCcJHgXloTyT2A=="
+    crossorigin="anonymous"
+    referrerpolicy="no-referrer"
+  />
+
+  <!-- Style -->
+  <style>
+    .DCEReactKit-pop-in {
+      animation-name: DCEReactKit-pop-in;
+      animation-duration: 0.5s;
+      animation-iteration-count: 1;
+      animation-timing-function: ease-out;
+      animation-fill-mode: both;
+
+      transform-origin: center;
+    }
+
+    @keyframes DCEReactKit-pop-in {
+      0% {
+        opacity: 0;
+        transform: scale(0.9);
+      }
+      100% {
+        opacity: 1;
+        transform: scale(1);
+      }
+    }
+  </style>
+</head>
+
+<!-- Body -->
+<body class="bg-dark text-center pt-3 ps-3 pe-3">
+  <!-- Alert -->
+  <div
+    class="DCEReactKit-pop-in alert alert-info d-inline-block"
+    style="width: 50em; max-width: 100%"
+  >
+    <!-- Title -->
+    <h2>
+      <i class="me-1 fa-solid fa-circle-info"></i>
+      ${title}
+    </h2>
+    <!-- Body -->
+    <div>
+      ${body}
+    </div>
+  </div>
+</body>
+  `;
+};
+
+export default genInfoPage;

package/src/index.ts

@@ -0,0 +1,125 @@
+// Import dce-reactkit
+import {
+  abbreviate,
+  avg,
+  ceilToNumDecimals,
+  floorToNumDecimals,
+  forceNumIntoBounds,
+  padDecimalZeros,
+  padZerosLeft,
+  roundToNumDecimals,
+  sum,
+  waitMs,
+  getOrdinal,
+  getTimeInfoInET,
+  startMinWait,
+  getHumanReadableDate,
+  getPartOfDay,
+  stringsToHumanReadableList,
+  onlyKeepLetters,
+  parallelLimit,
+  getMonthName,
+  genCSV,
+  extractProp,
+  compareArraysByProp,
+  getLocalTimeInfo,
+  genCommaList,
+  prefixWithAOrAn,
+  everyAsync,
+  filterAsync,
+  forEachAsync,
+  mapAsync,
+  someAsync,
+  capitalize,
+  shuffleArray,
+  DayOfWeek,
+  Log,
+  LogType,
+  LogSource,
+  LogAction,
+  LogBuiltInMetadata,
+  LogMetadataType,
+  LogFunction,
+  MINUTE_IN_MS,
+  HOUR_IN_MS,
+  DAY_IN_MS,
+  ErrorWithCode,
+  ParamType,
+} from 'dce-reactkit';
+
+// Import helpers
+import initCrossServerCredentialCollection from './helpers/initCrossServerCredentialCollection';
+import initLogCollection from './helpers/initLogCollection';
+import initServer from './helpers/initServer';
+import genRouteHandler from './helpers/genRouteHandler';
+import handleError from './helpers/handleError';
+import handleSuccess from './helpers/handleSuccess';
+import addDBEditorEndpoints from './helpers/addDBEditorEndpoints';
+import visitEndpointOnAnotherServer from './helpers/visitEndpointOnAnotherServer';
+
+// Import types
+import CrossServerCredential from './types/CrossServerCredential';
+
+// Export each item
+export {
+  // Errors
+  ErrorWithCode,
+  // Constants
+  MINUTE_IN_MS,
+  HOUR_IN_MS,
+  DAY_IN_MS,
+  // Helpers
+  abbreviate,
+  avg,
+  ceilToNumDecimals,
+  floorToNumDecimals,
+  forceNumIntoBounds,
+  padDecimalZeros,
+  padZerosLeft,
+  roundToNumDecimals,
+  sum,
+  waitMs,
+  getOrdinal,
+  getTimeInfoInET,
+  startMinWait,
+  getHumanReadableDate,
+  getPartOfDay,
+  stringsToHumanReadableList,
+  onlyKeepLetters,
+  parallelLimit,
+  getMonthName,
+  genCSV,
+  extractProp,
+  compareArraysByProp,
+  genCommaList,
+  getLocalTimeInfo,
+  prefixWithAOrAn,
+  everyAsync,
+  filterAsync,
+  forEachAsync,
+  mapAsync,
+  someAsync,
+  capitalize,
+  shuffleArray,
+  // Server helpers
+  initServer,
+  genRouteHandler,
+  handleError,
+  handleSuccess,
+  initLogCollection,
+  initCrossServerCredentialCollection,
+  addDBEditorEndpoints,
+  visitEndpointOnAnotherServer,
+  // Types
+  DayOfWeek,
+  Log,
+  LogType,
+  LogSource,
+  LogAction,
+  LogBuiltInMetadata,
+  LogMetadataType,
+  LogFunction,
+  CrossServerCredential,
+  // Server types
+  ParamType,
+};

package/src/types/CrossServerCredential.ts

@@ -0,0 +1,16 @@
+/**
+ * Single cross-server credential
+ * @author Gabe Abrams
+ */
+type CrossServerCredential = {
+  // Description of the credential (human-readable)
+  description: string,
+  // The key of the credential
+  key: string,
+  // The encoded secret of the credential
+  encodedeSecret: string,
+  // The list of scopes for the credential
+  scopes: string[],
+};
+
+export default CrossServerCredential;

package/src/types/ExpressKitErrorCode.ts

@@ -0,0 +1,37 @@
+// Highest error code = DEK34
+
+/**
+ * List of error codes built into the express kit
+ * @author Gabe Abrams
+ */
+enum ExpressKitErrorCode {
+  // General errors
+  WrongCourse = 'DEK6',
+  NotTTM = 'DEK9',
+  NotAdmin = 'DEK10',
+  NotAllowedToReviewLogs = 'DEK11',
+  ThemeCheckedBeforeReactKitReady = 'DEK12',
+  InvalidParameter = 'DEK5',
+  MissingParameter = 'DEK4',
+
+  // Server-to-server requests
+  NotConnected = 'DEK14',
+  SelfSigned = 'DEK15',
+  ResponseParseError = 'DEK16',
+  SignedRequestUnparseable = 'DEK28',
+  SignedRequestInvalidCollection = 'DEK21',
+  SignedRequestInvalidCredential = 'DEK23',
+  SignedRequestInvalidScope = 'DEK22',
+  SignedRequestInvalidTimestamp = 'DEK24',
+  SignedRequestInvalidSignature = 'DEK25',
+  SignedRequestInvalidBody = 'DEK26',
+  CrossServerNoCredentialsToSignWith = 'DEK27',
+  CrossServerMissingSignedRequestInfo = 'DEK29',
+  CrossServerNoCredentialEncodingSalt = 'DEK30',
+  NoOauthLib = 'DEK31',
+  NoCryptoLib = 'DEK32',
+  InvalidCrossServerCredentialsFormat = 'DEK33',
+  UnknownCrossServerError = 'DEK34',
+}
+
+export default ExpressKitErrorCode;

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "noImplicitAny": true,
+    "noEmitOnError": true,
+    "removeComments": false,
+    "declaration": true,
+    "sourceMap": true,
+    "target": "es5",
+    "outDir": "./lib"
+  },
+  "include": [
+    "./src"
+  ],
+  "ts-node": {
+    "files": true
+  }
+}