@saltcorn/server 0.6.1-beta.0 → 0.6.1

package/auth/routes.js

@@ -1,3 +1,8 @@
+/**
+ * @category server
+ * @module auth/routes
+ * @subcategory auth
+ */
 const Router = require("express-promise-router");
 
 const db = require("@saltcorn/data/db");
@@ -45,9 +50,22 @@ const { restore } = require("@saltcorn/data/models/backup");
 const load_plugins = require("../load_plugins");
 const fs = require("fs");
 
+/**
+ * @type {object}
+ * @const
+ * @namespace routesRouter
+ * @category server
+ * @subcategory auth
+ */
+
 const router = new Router();
 module.exports = router;
 
+/**
+ * @param {object} req 
+ * @param {boolean} isCreating 
+ * @returns {Form}
+ */
 const loginForm = (req, isCreating) => {
   const postAuthMethods = Object.entries(getState().auth_methods)
     // TBD unresolved parameter K
@@ -84,6 +102,11 @@ const loginForm = (req, isCreating) => {
     submitLabel: req.__("Login"),
   });
 };
+
+/**
+ * @param {object} req 
+ * @returns {Form}
+ */
 const forgotForm = (req) =>
   new Form({
     blurb: req.__(
@@ -104,6 +127,11 @@ const forgotForm = (req) =>
     submitLabel: req.__("Reset password"),
   });
 
+/**
+ * @param {object} body 
+ * @param {object} req 
+ * @returns {Form}
+ */
 const resetForm = (body, req) => {
   const form = new Form({
     blurb: req.__("Enter your new password below"),
@@ -129,6 +157,12 @@ const resetForm = (body, req) => {
   form.values.token = body && body.token;
   return form;
 };
+
+/**
+ * @param {string} current 
+ * @param {boolean} noMethods 
+ * @returns {object}
+ */
 const getAuthLinks = (current, noMethods) => {
   const links = { methods: [] };
   const state = getState();
@@ -152,6 +186,11 @@ const getAuthLinks = (current, noMethods) => {
   return links;
 };
 
+/**
+ * @name get/login
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/login",
   setTenant,
@@ -175,6 +214,11 @@ router.get(
   })
 );
 
+/**
+ * @name get/logout
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get("/logout", setTenant, (req, res, next) => {
   req.logout();
   if (req.session.destroy)
@@ -190,6 +234,11 @@ router.get("/logout", setTenant, (req, res, next) => {
   }
 });
 
+/**
+ * @name get/forgot
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/forgot",
   setTenant,
@@ -210,6 +259,11 @@ router.get(
   })
 );
 
+/**
+ * @name get/reset
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/reset",
   setTenant,
@@ -219,6 +273,11 @@ router.get(
   })
 );
 
+/**
+ * @name get/verify
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/verify",
   setTenant,
@@ -238,6 +297,11 @@ router.get(
   })
 );
 
+/**
+ * @name post/reset
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/reset",
   setTenant,
@@ -258,6 +322,12 @@ router.post(
     res.redirect("/auth/login");
   })
 );
+
+/**
+ * @name post/forgot
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/forgot",
   setTenant,
@@ -286,6 +356,12 @@ router.post(
     }
   })
 );
+
+/**
+ * @name get/signup
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/signup",
   setTenant,
@@ -325,6 +401,11 @@ router.get(
   })
 );
 
+/**
+ * @name get/create_first_user
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/create_first_user",
   setTenant,
@@ -350,6 +431,11 @@ router.get(
   })
 );
 
+/**
+ * @name post/create_from_restore
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/create_from_restore",
   setTenant,
@@ -373,6 +459,12 @@ router.post(
     }
   })
 );
+
+/**
+ * @name post/create_first_user
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/create_first_user",
   setTenant,
@@ -417,6 +509,13 @@ router.post(
   })
 );
 
+/**
+ * @param {string} new_user_view_name 
+ * @param {object} req 
+ * @param {boolean} askEmail 
+ * @returns {Promise<Form>}
+ * @throws {InvalidConfiguration}
+ */
 const getNewUserForm = async (new_user_view_name, req, askEmail) => {
   const view = await View.findOne({ name: new_user_view_name });
   if (!view)
@@ -488,6 +587,12 @@ const getNewUserForm = async (new_user_view_name, req, askEmail) => {
   return form;
 };
 
+/**
+ * @param {object} u 
+ * @param {object} req 
+ * @param {object} res 
+ * @returns {void}
+ */
 const signup_login_with_user = (u, req, res) =>
   req.login(
     {
@@ -508,6 +613,11 @@ const signup_login_with_user = (u, req, res) =>
     }
   );
 
+/**
+ * @name get/signup_final_ext
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/signup_final_ext",
   setTenant,
@@ -525,6 +635,11 @@ router.get(
   })
 );
 
+/**
+ * @name post/signup_final_ext
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/signup_final_ext",
   setTenant,
@@ -572,6 +687,12 @@ router.post(
     }
   })
 );
+
+/**
+ * @name post/signup_final
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/signup_final",
   setTenant,
@@ -629,6 +750,11 @@ router.post(
   })
 );
 
+/**
+ * @name post/signup
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/signup",
   setTenant,
@@ -741,6 +867,11 @@ router.post(
   })
 );
 
+/**
+ * @param {object} req 
+ * @param {object} res 
+ * @returns {void}
+ */
 function handler(req, res) {
   console.log(
     `Failed login attempt for: ${req.body.email} from ${req.ip} UA ${req.get(
@@ -754,7 +885,12 @@ function handler(req, res) {
   );
   res.redirect("/auth/login"); // brute force protection triggered, send them back to the login page
 }
-// try to find a unique user id in login submit
+
+/**
+ * try to find a unique user id in login submit
+ * @param {object} body 
+ * @returns {string}
+ */
 const userIdKey = (body) => {
   if (body.email) return body.email;
   const { remember, password, _csrf, passwordRepeat, ...rest } = body;
@@ -777,6 +913,11 @@ const userLimiter = rateLimit({
   handler,
 });
 
+/**
+ * @name post/login
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/login",
   setTenant,
@@ -805,6 +946,12 @@ router.post(
     res.redirect("/");
   })
 );
+
+/**
+ * @name get/login-with/:method
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/login-with/:method",
   setTenant,
@@ -822,6 +969,12 @@ router.get(
     }
   })
 );
+
+/**
+ * @name post/login-with/:method
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.post(
   "/login-with/:method",
   setTenant,
@@ -845,6 +998,11 @@ router.post(
   })
 );
 
+/**
+ * @param {object}} req 
+ * @param {object} res 
+ * @returns {void}
+ */
 const loginCallback = (req, res) => () => {
   if (!req.user) return;
   if (!req.user.id) {
@@ -859,6 +1017,11 @@ const loginCallback = (req, res) => () => {
   }
 };
 
+/**
+ * @name get/callback/:method
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/callback/:method",
   setTenant,
@@ -875,6 +1038,10 @@ router.get(
   })
 );
 
+/**
+ * @param {object} req 
+ * @returns {Form}
+ */
 const changPwForm = (req) =>
   new Form({
     action: "/auth/settings",
@@ -895,6 +1062,12 @@ const changPwForm = (req) =>
       },
     ],
   });
+
+/**
+ * @param {object} req 
+ * @param {object} user 
+ * @returns {Form}
+ */
 const setLanguageForm = (req, user) =>
   form(
     {
@@ -916,6 +1089,14 @@ const setLanguageForm = (req, user) =>
     )
   );
 
+/**
+ * @param {object} opts
+ * @param {object} opts.req
+ * @param {object} opts.res
+ * @param {object} opts.pwform
+ * @param {object} opts.user
+ * @returns {Promise<object>}
+ */
 const userSettings = async ({ req, res, pwform, user }) => {
   let usersets;
   const user_settings_form = getState().getConfig("user_settings_form", "");
@@ -962,8 +1143,12 @@ const userSettings = async ({ req, res, pwform, user }) => {
     ],
   };
 };
+
 /**
  * Set language
+ * @name post/setlanguage
+ * @function
+ * @memberof module:auth/routes~routesRouter
  */
 router.post(
   "/setlanguage",
@@ -998,6 +1183,12 @@ router.post(
     }
   })
 );
+
+/**
+ * @name get/settings
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.get(
   "/settings",
   setTenant,
@@ -1010,9 +1201,10 @@ router.get(
     );
   })
 );
+
 /**
  * Define set email form for user
- * @param req
+ * @param {object} req
  * @returns {Form}
  */
 const setEmailForm = (req) =>
@@ -1031,8 +1223,12 @@ const setEmailForm = (req) =>
       },
     ],
   });
+
 /**
  * Render form for set email for user
+ * @name get/set-email
+ * @function
+ * @memberof module:auth/routes~routesRouter
  */
 router.get(
   "/set-email",
@@ -1044,8 +1240,12 @@ router.get(
     );
   })
 );
+
 /**
  * Execute set email for user
+ * @name post/set-email
+ * @function
+ * @memberof module:auth/routes~routesRouter
  */
 router.post(
   "/set-email",
@@ -1090,8 +1290,12 @@ router.post(
     );
   })
 );
+
 /**
  * Execute Change Password for User
+ * @name post/settings
+ * @function
+ * @memberof module:auth/routes~routesRouter
  */
 router.post(
   "/settings",
@@ -1139,6 +1343,11 @@ router.post(
   })
 );
 
+/**
+ * @name all/verification-flow
+ * @function
+ * @memberof module:auth/routes~routesRouter
+ */
 router.all(
   "/verification-flow",
   setTenant,

package/auth/testhelp.js

@@ -1,9 +1,20 @@
+/**
+ * @category server
+ * @module auth/testhelp
+ * @subcategory auth
+ */
 const request = require("supertest");
 const app = require("../app");
 const getApp = require("../app");
 const fixtures = require("@saltcorn/data/db/fixtures");
 const reset = require("@saltcorn/data/db/reset_schema");
 
+/**
+ * 
+ * @param {string} loc 
+ * @returns {void}
+ * @throws {Error}
+ */
 const toRedirect = (loc) => (res) => {
   if (res.statusCode !== 302) {
     console.log(res.text);
@@ -15,6 +26,13 @@ const toRedirect = (loc) => (res) => {
   }
 };
 
+/**
+ * 
+ * @param {number} txt 
+ * @param {number} expCode 
+ * @returns {void}
+ * @throws {Error}
+ */
 const toInclude = (txt, expCode = 200) => (res) => {
   if (res.statusCode !== expCode) {
     console.log(res.text);
@@ -29,6 +47,12 @@ const toInclude = (txt, expCode = 200) => (res) => {
   }
 };
 
+/**
+ * 
+ * @param {number} expCode 
+ * @returns {void}
+ * @throws {Error}
+ */
 const toSucceed = (expCode = 200) => (res) => {
   if (res.statusCode !== expCode) {
     console.log(res.text);
@@ -36,6 +60,13 @@ const toSucceed = (expCode = 200) => (res) => {
   }
 };
 
+/**
+ * 
+ * @param {number} txt 
+ * @param {number} expCode 
+ * @returns {void}
+ * @throws {Error}
+*/
 const toNotInclude = (txt, expCode = 200) => (res) => {
   if (res.statusCode !== expCode) {
     console.log(res.text);
@@ -49,6 +80,11 @@ const toNotInclude = (txt, expCode = 200) => (res) => {
     throw new Error(`Expected text ${txt} to be absent, but was present`);
   }
 };
+
+/**
+ * 
+ * @returns {Promise<void>}
+ */
 const getStaffLoginCookie = async () => {
   const app = await getApp({ disableCsrf: true });
   const res = await request(app)
@@ -59,6 +95,10 @@ const getStaffLoginCookie = async () => {
   return res.headers["set-cookie"][0];
 };
 
+/**
+ * 
+ * @returns {Promise<void>}
+ */
 const getAdminLoginCookie = async () => {
   const app = await getApp({ disableCsrf: true });
   const res = await request(app)
@@ -70,6 +110,12 @@ const getAdminLoginCookie = async () => {
   return res.headers["set-cookie"][0];
 };
 
+/**
+ * 
+ * @param {string} path 
+ * @param {string} dest 
+ * @returns {void}
+ */
 const itShouldRedirectUnauthToLogin = (path, dest) => {
   it(`should redirect unauth ${path} to ${dest || "login"}`, async () => {
     const app = await getApp({ disableCsrf: true });
@@ -82,11 +128,20 @@ const itShouldRedirectUnauthToLogin = (path, dest) => {
   });
 };
 
+/**
+ * @returns {Promise<void>}
+ */
 const resetToFixtures = async () => {
   await reset();
   await fixtures();
 };
 
+/**
+ * 
+ * @param {*} pred 
+ * @returns {void}
+ * @throws {Error}
+ */
 const succeedJsonWith = (pred) => (res) => {
   if (res.statusCode !== 200) {
     console.log(res.text);
@@ -99,6 +154,13 @@ const succeedJsonWith = (pred) => (res) => {
   }
 };
 
+/**
+ * 
+ * @param {number} code 
+ * @param {number} pred 
+ * @returns {void}
+ * @throws {Error}
+ */
 const respondJsonWith = (code, pred) => (res) => {
   if (res.statusCode !== code) {
     console.log(res.text);
@@ -110,6 +172,13 @@ const respondJsonWith = (code, pred) => (res) => {
     throw new Error(`Not satisfied`);
   }
 };
+
+/**
+ * 
+ * @param {object} res 
+ * @returns {void}
+ * @throws {Error}
+ */
 const notAuthorized = (res) => {
   if (res.statusCode !== 401) {
     console.log(res.text);

package/errors.js

@@ -1,9 +1,22 @@
+/**
+ * @category server
+ * @module errors
+ */
 const db = require("@saltcorn/data/db");
 const { pre, p, text, h3 } = require("@saltcorn/markup/tags");
 const Crash = require("@saltcorn/data/models/crash");
 const { getState } = require("@saltcorn/data/db/state");
 
-module.exports = async function (err, req, res, next) {
+module.exports = 
+/**
+ * 
+ * @param {object} err 
+ * @param {object} req 
+ * @param {object} res 
+ * @param {*} next 
+ * @returns {Promise<void>}
+ */
+async function (err, req, res, next) {
   if (!req.__) req.__ = (s) => s;
 
   const devmode = getState().getConfig("development_mode", false);

package/fixture_persons.js

@@ -1,3 +1,7 @@
+/**
+ * @category server
+ * @module fixture_persons
+ */
 const db = require("@saltcorn/data/db");
 const { getState } = require("@saltcorn/data/db/state");
 const Table = require("@saltcorn/data/models/table");
@@ -8,8 +12,15 @@ const basePlugin = require("@saltcorn/base-plugin");
 
 getState().registerPlugin("base", basePlugin);
 
+/**
+ * @param {object[]} vs 
+ * @returns {object}
+ */
 const rndElem = (vs) => vs[Math.floor(Math.random() * vs.length)];
 
+/**
+ * @returns {object}
+ */
 const randomPerson = () => {
   const gender = Math.random() > 0.5 ? "Female" : "Male";
   const last_name = rndElem(
@@ -27,6 +38,9 @@ const randomPerson = () => {
   return { gender, last_name, first_name, age };
 };
 
+/**
+ * @returns {Promise<void>}
+ */
 const fixturePersons = async () => {
   await db.query(`drop table if exists persons`);
   const table = await Table.create("persons");

package/index.js

@@ -0,0 +1,6 @@
+// for the jsdoc documentation
+/**
+ *
+ * @category server
+ * @module server/index
+ */

package/load_plugins.js

@@ -2,6 +2,8 @@
  * Load plugins
  * File: load_plugins.js
  *
+ * @category server
+ * @module load_plugins
  */
 const db = require("@saltcorn/data/db");
 const { PluginManager } = require("live-plugin-manager");
@@ -42,12 +44,12 @@ const manager = new PluginManager({
     "@saltcorn/data/models/workflow": require("@saltcorn/data/models/workflow"),
   },
 });
+
 /**
  * Load one plugin
  * TODO correct names for functions loadPlugin, requirePlugin - currently uncler
  * @param plugin - plugin to load
  * @param force - force flag
- * @returns {Promise<{plugin_module: *}|{readonly name: string, readonly location: string, plugin_module: *, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}|{readonly name: string, readonly location: string, plugin_module: *, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}|{readonly name: string, readonly location: string, plugin_module: *, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}|{readonly name: string, readonly location: string, plugin_module: *, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}|{readonly name: string, readonly location: string, plugin_module: *, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}>}
  */
 const loadPlugin = async (plugin, force) => {
   // load pluging
@@ -69,13 +71,12 @@ const loadPlugin = async (plugin, force) => {
   }
   return res;
 };
+
 /**
  *
  * @param plugin
  * @param force
- * @returns {Promise<{plugin_module: *}|{readonly name: string, readonly location: string, plugin_module: any, readonly mainFile: string, readonly version: string, readonly dependencies: {[p: string]: string}}>}
  */
-
 const gitPullOrClone = async (plugin) => {
   await fs.promises.mkdir("git_plugins", { recursive: true });
   let keyfnm,