@openinc/parse-server-opendash 2.4.7 → 2.4.9

package/README.md

@@ -16,6 +16,16 @@ const { init } = require("@openinc/parse-server-opendash");
 init();
 ```
 
+For a full list of exports see the file at [EXPORTS.md](./EXPORTS.md)
+
+## Configuration
+
+The configuration of this cloud code is done using environment variables.
+
+By default no classes will be created. To create classes from the schema definition, you need to enable the feature flags according your needs.
+
+For a full list of options see the file at [CONFIG.md](./CONFIG.md)
+
 ## Development
 
 See the file at [DEVELOPMENT.md](./DEVELOPMENT.md)

package/dist/config.js

@@ -9,7 +9,7 @@ const options = {
         required: true,
         secret: false,
         public: true,
-        description: "...",
+        description: "This is not the Parse Server URL, but the URL of the web app.",
     },
     ENFORCE_APP_URL: {
         env: "OPENINC_PARSE_ENFORCE_APP_URL",
@@ -17,7 +17,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If this setting is enabled, the app will redirect to the APP_URL if the request is not coming from this URL.",
     },
     APP_TITLE: {
         env: "OPENINC_PARSE_APP_TITLE",
@@ -26,7 +27,7 @@ const options = {
         secret: false,
         public: true,
         default: "open.DASH",
-        description: "...",
+        description: "Title of the application.",
     },
     APP_COPYRIGHT_TEXT: {
         env: "OPENINC_PARSE_APP_COPYRIGHT_TEXT",
@@ -35,7 +36,7 @@ const options = {
         secret: false,
         public: true,
         default: "Powered by open.INC",
-        description: "...",
+        description: "Text which is displayed in the footer of the application.",
     },
     APP_COPYRIGHT_LINK: {
         env: "OPENINC_PARSE_APP_COPYRIGHT_LINK",
@@ -44,7 +45,7 @@ const options = {
         secret: false,
         public: true,
         default: "https://openinc.de/",
-        description: "...",
+        description: "Link which is used for the copyright in the footer of the application.",
     },
     APP_IMPRINT_URL: {
         env: "OPENINC_PARSE_APP_IMPRINT_URL",
@@ -52,7 +53,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        description: "Link to the imprint of the application.",
     },
     APP_DATA_PROTECTION_URL: {
         env: "OPENINC_PARSE_APP_DATA_PROTECTION_URL",
@@ -60,7 +61,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        description: "Link to the data protection policy of the application.",
     },
     APP_TOS_URL: {
         env: "OPENINC_PARSE_APP_TOS_URL",
@@ -68,7 +69,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        description: "Link to the terms of service of the application.",
     },
     APP_NOTIFICATIONS_PER_EMAIL: {
         env: "OPENINC_PARSE_APP_NOTIFICATIONS_PER_EMAIL",
@@ -76,7 +77,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "Whether to send notifications via e-mail or not.",
         dependencies: ["SMTP_ENABLED"],
     },
     AUTH_SIGNUP_ENABLED: {
@@ -85,7 +87,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to false, users will not be able to sign up - users must be created by an admin.",
     },
     AUTH_SIGNUP_REQUIRE_TENANT: {
         env: "OPENINC_PARSE_AUTH_SIGNUP_REQUIRE_TENANT",
@@ -93,7 +96,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users must have a tenant when signing up.",
     },
     AUTH_VERIFY_EMAIL: {
         env: "OPENINC_PARSE_AUTH_VERIFY_EMAIL",
@@ -101,7 +105,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users must verify their e-mail address before they can log in.",
         dependencies: ["SMTP_ENABLED"],
     },
     AUTH_VERIFY_TENANT: {
@@ -110,7 +115,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users must be verified by a tenant admin before they can log in.",
     },
     AUTH_ALLOW_USERNAME: {
         env: "OPENINC_PARSE_AUTH_ALLOW_USERNAME",
@@ -118,7 +124,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users can sign up and login using a username. If set to false, the email will be used as the username.",
     },
     AUTH_ALLOW_PASSWORDLESS_LOGIN: {
         env: "OPENINC_PARSE_AUTH_ALLOW_PASSWORDLESS_LOGIN",
@@ -126,7 +133,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users will be able to login without a password, for example using a magic link sent to their email address.",
     },
     AUTH_ALLOW_PASSWORDLESS_SIGNUP: {
         env: "OPENINC_PARSE_AUTH_ALLOW_PASSWORDLESS_SIGNUP",
@@ -134,7 +142,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "If set to true, users will be able to sign up without a password, for example using a magic link sent to their email address.",
     },
     AUTH_PASSWORD_MIN_LENGTH: {
         env: "OPENINC_PARSE_AUTH_PASSWORD_MIN_LENGTH",
@@ -143,7 +152,7 @@ const options = {
         secret: false,
         public: true,
         default: "8",
-        description: "...",
+        description: "Minimum length of the password.",
     },
     AUTOLOAD_DIR: {
         env: "OPENINC_PARSE_CLOUDCODE_AUTOLOAD_DIR",
@@ -159,6 +168,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for core features.",
     },
     FEATURE_MONITORING: {
@@ -167,6 +177,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the Monitoring plugin.",
     },
     FEATURE_BDE: {
@@ -175,6 +186,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the BDE plugin.",
     },
     FEATURE_GTFS: {
@@ -183,6 +195,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the GTFS plugin.",
     },
     FEATURE_KNOWLEDGE: {
@@ -191,6 +204,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the open.KNOWLEDGE plugin.",
     },
     FEATURE_MAINTENANCE: {
@@ -199,6 +213,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the open.SERVICE plugin.",
     },
     FEATURE_MIAAS: {
@@ -207,6 +222,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable Parse Classes and Cloud Code for the MIAAS plugin.",
     },
     FORCE_SCHEMA: {
@@ -215,6 +231,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
+        default: "false",
         description: "This will force the schema to be updated on startup including removing fields and classes, which is a destructive operation and can result in data loss.",
     },
     EMAIL_TEMPLATE_DIR: {
@@ -223,7 +240,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "...",
+        description: "The directory where the email templates are stored. The default is 'views/emails'.",
         default: "views/emails",
     },
     SMTP_ENABLED: {
@@ -232,7 +249,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "Enable SMTP for sending e-mails.",
         dependencies: [
             "SMTP_HOST",
             "SMTP_PORT",
@@ -288,6 +306,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
+        default: "false",
         description: "E-Mail from/sender E-Mail",
     },
     SMTP_IGNORE_TLS: {
@@ -296,6 +315,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
+        default: "false",
         description: "E-Mail from/sender E-Mail",
     },
     WEB_PUSH_ENABLED: {
@@ -304,7 +324,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "Enable Web Push Notifications.",
         dependencies: [
             "WEB_PUSH_HOST",
             "WEB_PUSH_ICON",
@@ -319,7 +340,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "...",
+        description: "First/subject paramter of setVapidDetails() from https://www.npmjs.com/package/web-push",
     },
     WEB_PUSH_ICON: {
         env: "OPENINC_PARSE_WEB_PUSH_ICON",
@@ -327,7 +348,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "...",
+        description: "Icon URL for the push notifications.",
     },
     WEB_PUSH_VAPID_PUBLIC_KEY: {
         env: "OPENINC_PARSE_WEB_PUSH_VAPID_PUBLIC_KEY",
@@ -335,7 +356,7 @@ const options = {
         required: false,
         secret: true,
         public: false,
-        description: "...",
+        description: "Second paramter of setVapidDetails() from https://www.npmjs.com/package/web-push",
     },
     WEB_PUSH_VAPID_PRIVATE_KEY: {
         env: "OPENINC_PARSE_WEB_PUSH_VAPID_PRIVATE_KEY",
@@ -343,7 +364,7 @@ const options = {
         required: false,
         secret: true,
         public: false,
-        description: "...",
+        description: "Third paramter of setVapidDetails() from https://www.npmjs.com/package/web-push",
     },
     WEB_PUSH_FCM_KEY: {
         env: "OPENINC_PARSE_WEB_PUSH_FCM_KEY",
@@ -351,7 +372,7 @@ const options = {
         required: false,
         secret: true,
         public: false,
-        description: "...",
+        description: "First paramter of setGCMAPIKey() from https://www.npmjs.com/package/web-push",
     },
     GEO_VECTOR_STYLE: {
         env: "OPENINC_PARSE_GEO_VECTOR_STYLE",
@@ -359,7 +380,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "Enter a description here...",
+        description: "URL to the vector style file for mapgl.",
     },
     GEO_GOOGLE_ENABLED: {
         env: "OPENINC_PARSE_GEO_GOOGLE_ENABLED",
@@ -367,7 +388,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "Enable Google Maps for geocoding and routing.",
         dependencies: ["GEO_GOOGLE_API_KEY"],
     },
     GEO_GOOGLE_API_KEY: {
@@ -376,7 +398,7 @@ const options = {
         required: false,
         secret: true,
         public: false,
-        description: "Enter a description here...",
+        description: "Google Maps API Key. Needs places, autocomplate, geocoding and routing permissions.",
     },
     GEO_GRAPHHOPPER_ENABLED: {
         env: "OPENINC_PARSE_GEO_GRAPHHOPPER_ENABLED",
@@ -384,7 +406,8 @@ const options = {
         required: false,
         secret: false,
         public: true,
-        description: "...",
+        default: "false",
+        description: "Enable Graphhopper for geocding and routing.",
         dependencies: ["GEO_GRAPHHOPPER_HOST", "GEO_GRAPHHOPPER_API_KEY"],
     },
     GEO_GRAPHHOPPER_HOST: {
@@ -393,7 +416,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "Host of the Graphhopper API. The hosted service URL is https://graphhopper.com/api/1/",
     },
     GEO_GRAPHHOPPER_API_KEY: {
         env: "OPENINC_PARSE_GEO_GRAPHHOPPER_API_KEY",
@@ -401,7 +424,7 @@ const options = {
         required: false,
         secret: true,
         public: false,
-        description: "Enter a description here...",
+        description: "Graphhopper API Key.",
     },
     OPENWARE: {
         env: "PARSE_SERVER_OPENWARE",
@@ -409,6 +432,7 @@ const options = {
         required: false,
         secret: false,
         public: true,
+        default: "false",
         description: "Enable open.WARE Cloud Code features.",
     },
     OPENWARE_BASEURL: {
@@ -417,7 +441,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "Base URL of the open.WARE API.",
     },
     OPENWARE_JWT_SECRET: {
         env: "PARSE_SERVER_OPENWARE_JWT_SECRET",
@@ -425,7 +449,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "Secret for the JWT tokens for open.WARE.",
     },
     OPENWARE_JWT_ISS: {
         env: "PARSE_SERVER_OPENWARE_JWT_ISS",
@@ -433,7 +457,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "Issuer of the JWT tokens for open.WARE.",
     },
     OPENWARE_JWT_ADMIN_EMAIL: {
         env: "PARSE_SERVER_OPENWARE_JWT_ADMIN_EMAIL",
@@ -441,7 +465,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "E-Mail of the admin user for open.WARE.",
     },
     OPENWARE_JWT_TOKEN: {
         env: "PARSE_SERVER_OPENWARE_JWT_TOKEN",
@@ -449,7 +473,7 @@ const options = {
         required: false,
         secret: false,
         public: false,
-        description: "Enter a description here...",
+        description: "Use the given JWT token instead of creating a new one.",
     },
 };
 exports.config = new Config_1.Config(options);

package/dist/hooks/BDE_Page.js

@@ -7,7 +7,7 @@ async function init() {
     (0, __1.beforeSaveHook)(types_1.BDE_Page, async (request) => {
         const { object, original, user } = request;
         request.context.dirtyKeys = object.dirtyKeys();
-        const query = new Parse.Query(__1.PREFIX + "BDE_Form").equalTo("entries", object.id);
+        const query = new Parse.Query(types_1.BDE_Form).equalTo("entries", [object.id]);
         const affectedForms = await query.find({ useMasterKey: true });
         const aclCandidates = {};
         affectedForms.forEach((form) => {
@@ -28,7 +28,7 @@ async function init() {
     });
     (0, __1.afterSaveHook)(types_1.BDE_Page, async (request) => {
         const { object, original, user } = request;
-        const query = new Parse.Query(__1.PREFIX + "BDE_Form").equalTo("entries", object.id);
+        const query = new Parse.Query(types_1.BDE_Form).equalTo("entries", [object.id]);
         const affectedForms = await query.find({ useMasterKey: true });
         const dirtyKeys = request.context.dirtyKeys;
         if (dirtyKeys.length > 0 && dirtyKeys[0] !== "acl")
@@ -36,7 +36,7 @@ async function init() {
     });
     (0, __1.afterDeleteHook)(types_1.BDE_Page, async (request) => {
         const { object, original, user } = request;
-        const query = new Parse.Query(__1.PREFIX + "BDE_Form").equalTo("entries", object.id);
+        const query = new Parse.Query(types_1.BDE_Form).equalTo("entries", [object.id]);
         const affectedForms = await query.find({ useMasterKey: true });
         await Parse.Object.saveAll(affectedForms, { useMasterKey: true });
     });

package/dist/hooks/BDE_Result.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.init = void 0;
 const __1 = require("..");
-const types_1 = require("../types");
 const ow_1 = require("../ow");
+const types_1 = require("../types");
 async function init() {
     (0, __1.beforeSaveHook)(types_1.BDE_Result, async (request) => {
         const { object, original, user } = request;

package/dist/hooks/Dashboard.js

@@ -16,7 +16,7 @@ async function init() {
         if (acl && Array.isArray(widgetIds) && widgetIds.length > 0) {
             for (const widgetId of widgetIds) {
                 try {
-                    const widget = new Parse.Object(`${__1.PREFIX}Widget`, {
+                    const widget = new types_1.Widget({
                         objectId: widgetId,
                     });
                     await widget.fetch({ useMasterKey: true });

package/dist/hooks/_User.js

@@ -21,7 +21,7 @@ async function init() {
             !!user.get("emailVerified") &&
             !user.get("tenantVerified")) {
             const email = user.get("email");
-            const domains = await new Parse.Query(`${__1.PREFIX}TenantTrustedDomain`)
+            const domains = await new Parse.Query(types_1.TenantTrustedDomain)
                 .equalTo("tenant", tenant)
                 .find({ useMasterKey: true });
             for (const domain of domains) {

package/dist/index.d.ts

@@ -1,30 +1,104 @@
 import type { Cloud as ParseCloud } from "parse";
-export { Config } from "./helper/Config";
+import { Permission } from "./types";
 export { sendSimpleEmail, sendTemplateEmail } from "./hooks/Core_Email";
-export declare let PREFIX: string;
-export interface ConfigInterface {
-    configPath?: string;
-}
+/**
+ * Initializes the Cloud Code for open.DASH.
+ * This function performs various initialization tasks such as
+ * initializing configuration, setting up email transport, initializing web push,
+ * initializing class schema, setting up default roles, initializing parse lifecycle hooks,
+ * loading default data, initializing cloud functions, and setting up cloud code autoloading.
+ *
+ * @returns {Promise<void>} A promise that resolves when the initialization is complete.
+ */
 export declare function init(): Promise<void>;
+/**
+ * Checks if a user has a specific permission in OD3_Permission.
+ * @param sessionToken - The session token of the user.
+ * @param key - The key of the permission to check.
+ * @returns A promise that resolves to a boolean indicating whether the user has the permission.
+ */
 export declare function hasPermission(sessionToken: string, key: string): Promise<boolean>;
+/**
+ * Checks if the user has the required permission to perform an operation using hasPermission().
+ * If the user does not have the required permission, an error is thrown.
+ *
+ * @param request - The request object containing the user's session token and masterkey status.
+ * @param key - The permission key required for the operation.
+ * @param message - The error message to be thrown if the user does not have the required permission.
+ * @returns A Promise that resolves if the user has the required permission, or throws an error if not.
+ */
 export declare function requirePermission(request: {
     master?: boolean;
     sessionToken: string | undefined;
 }, key: string | null, message: string): Promise<void>;
+/**
+ * Retrieves the value of a configuration key from OD3_Config.
+ * @param key - The key of the configuration to retrieve.
+ * @returns A promise that resolves to the value of the configuration key, or undefined if not found.
+ */
 export declare function getConfig(key: string): Promise<string | undefined>;
+/**
+ * Retrieves the value of a configuration key from OD3_Config as a boolean
+ * Converts the string value to a boolean value using the following rules:
+ * - "true" or "1" -> true
+ * - "false" or "0" -> false
+ * - undefined/null -> false
+ * - Any other value -> true
+ *
+ * @param key - The key of the configuration value.
+ * @returns A boolean value indicating the configuration value.
+ */
 export declare function getConfigBoolean(key: string): Promise<boolean>;
+/**
+ * Ensures the existence of a role with the specified name.
+ * If the role does not exist, it creates a new role with the given name and options.
+ * If the role already exists, it updates the role with the provided options.
+ *
+ * @param name - The name of the role.
+ * @param options - Optional parameters for the role.
+ * @param options.label - The label for the role.
+ * @param options.acl - The Parse.ACL for the role.
+ * @param options.childRoles - An array of child role names to be associated with the role.
+ * @returns A Promise that resolves when the role is successfully created or updated.
+ */
 export declare function ensureRole(name: string, options?: {
     label?: string;
     acl?: Parse.ACL;
     childRoles?: string[];
 }): Promise<void>;
+/**
+ * Ensures that a user has a specific role.
+ * @param user The user to assign the role to.
+ * @param roleName The name of the role.
+ * @param add Specifies whether to add or remove the user from the role. Default is false (remove).
+ */
 export declare function ensureUserRole(user: Parse.User, roleName: string, add?: boolean): Promise<void>;
+/**
+ * Checks if a field is immutable and throws an error if an attempt is made to edit it in a beforeSave hook.
+ *
+ * This will not throw an error if the request is made with the master key.
+ *
+ * @param request - The request object containing the original and object Parse objects, master flag, and session token.
+ * @param fieldName - The name of the field to check for immutability.
+ * @param permissionName - The name of the permission required to edit the field. Defaults to "parse:edit-immutable-fields".
+ * @returns Promise<void>
+ */
 export declare function immutableField(request: {
     original?: Parse.Object;
     object: Parse.Object;
     master?: boolean;
     sessionToken: string | undefined;
 }, fieldName: string, permissionName?: string | null): Promise<void>;
+/**
+ * Handles the default beforeSave() logic for a Parse.Object.
+ *
+ * This function will check if a user or tenant field is present in the schema and set the value to the current user and/or the tenant of the current user if not provided.
+ * This will also mark the user and tenant fields as immutable, preventing them from being edited in the future.
+ *
+ * @param request - The Parse.Cloud.BeforeSaveRequest object.
+ * @returns - Returns void.
+ * @throws - Throws an error if the user is not provided.
+ */
 export declare function defaultHandler(request: {
     original?: Parse.Object;
     object: Parse.Object;
@@ -32,6 +106,17 @@ export declare function defaultHandler(request: {
     master?: boolean;
     sessionToken: string | undefined;
 }): Promise<void>;
+/**
+ * Handles the default Parse.ACL beforeSave() logic for a Parse.Object.
+ *
+ * This function will set the default ACL for the object based on the user and tenant fields. By default, the object will be readable and writable by the tenant role and readable by tenant users.
+ *
+ * @param request - The Parse.Cloud.BeforeSaveRequest object.
+ * @param options - Optional configuration options.
+ * @param options.allowCustomACL - Whether to allow custom ACL (default: false).
+ * @param options.allowTenantUserWrite - Whether to allow tenant users to write (default: false).
+ * @param options.denyTenantUserRead - Whether to deny tenant users from reading (default: false).
+ */
 export declare function defaultAclHandler(request: Parse.Cloud.BeforeSaveRequest, options?: {
     allowCustomACL?: boolean;
     allowTenantUserWrite?: boolean;
@@ -40,26 +125,72 @@ export declare function defaultAclHandler(request: Parse.Cloud.BeforeSaveRequest
 type beforeSaveHookType<T extends Parse.Object<Parse.Attributes>> = (request: ParseCloud.BeforeSaveRequest<T> & {
     sessionToken: string | undefined;
 }) => Promise<void>;
+/**
+ * Registers a beforeSave hook for a Parse class. In comparison to Parse.Cloud.beforeSave(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {beforeSaveHookType<T>} callback - The callback function to be executed before saving the object.
+ * @returns {void}
+ */
 export declare function beforeSaveHook<T extends Parse.Object<Parse.Attributes>>(target: string | {
     new (): T;
 }, callback: beforeSaveHookType<T>): void;
 type afterSaveHookType<T extends Parse.Object<Parse.Attributes>> = (request: ParseCloud.AfterSaveRequest<T> & {
     sessionToken: string | undefined;
 }) => Promise<void>;
+/**
+ * Registers a afterSave hook for a Parse class. In comparison to Parse.Cloud.afterSave(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {afterSaveHookType<T>} callback - The callback function to be executed after saving the object.
+ * @returns {void}
+ */
 export declare function afterSaveHook<T extends Parse.Object<Parse.Attributes>>(target: string | {
     new (): T;
 }, callback: afterSaveHookType<T>): void;
 type beforeDeleteHookType<T extends Parse.Object<Parse.Attributes>> = (request: ParseCloud.BeforeDeleteRequest<T> & {
     sessionToken: string | undefined;
 }) => Promise<void>;
+/**
+ * Registers a beforeDelete hook for a Parse class. In comparison to Parse.Cloud.beforeDelete(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {beforeDeleteHookType<T>} callback - The callback function to be executed before deleting an object.
+ */
 export declare function beforeDeleteHook<T extends Parse.Object<Parse.Attributes>>(target: string | {
     new (): T;
 }, callback: beforeDeleteHookType<T>): void;
 type afterDeleteHookType<T extends Parse.Object<Parse.Attributes>> = (request: ParseCloud.AfterDeleteRequest<T> & {
     sessionToken: string | undefined;
 }) => Promise<void>;
+/**
+ * Registers a afterDelete hook for a Parse class. In comparison to Parse.Cloud.afterDelete(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {afterDeleteHookType<T>} callback - The callback function to be executed after a delete operation.
+ * @returns {void}
+ */
 export declare function afterDeleteHook<T extends Parse.Object<Parse.Attributes>>(target: string | {
     new (): T;
 }, callback: afterDeleteHookType<T>): void;
+/**
+ * Autoloads cloud code files from the specified path. Each file MUST export an init() function that takes the file name (without it's extension) as an argument.
+ *
+ * @param path - The path to the directory containing the cloud code files.
+ * @param regex - Optional regular expression to filter the file names. Defaults to /^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$/.
+ * @returns A promise that resolves when all the cloud code files have been loaded and initialized.
+ */
 export declare function autoloadCloudCode(path: string, regex?: RegExp): Promise<void>;
-export declare function initAutoload(): Promise<void>;
+/**
+ * Ensures that a OD3_Permission with the specified key exists in the database.
+ * If the permission already exists, it updates the ACL if provided.
+ * If the permission does not exist, it creates a new permission with the specified key and ACL.
+ * @param key - The key of the permission.
+ * @param acl - The Parse.ACL to be set for the permission.
+ * @returns The updated or newly created permission.
+ */
+export declare function ensurePermission(key: string, acl?: Parse.ACL): Promise<Permission>;

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initAutoload = exports.autoloadCloudCode = exports.afterDeleteHook = exports.beforeDeleteHook = exports.afterSaveHook = exports.beforeSaveHook = exports.defaultAclHandler = exports.defaultHandler = exports.immutableField = exports.ensureUserRole = exports.ensureRole = exports.getConfigBoolean = exports.getConfig = exports.requirePermission = exports.hasPermission = exports.init = exports.PREFIX = exports.sendTemplateEmail = exports.sendSimpleEmail = exports.Config = void 0;
+exports.ensurePermission = exports.autoloadCloudCode = exports.afterDeleteHook = exports.beforeDeleteHook = exports.afterSaveHook = exports.beforeSaveHook = exports.defaultAclHandler = exports.defaultHandler = exports.immutableField = exports.ensureUserRole = exports.ensureRole = exports.getConfigBoolean = exports.getConfig = exports.requirePermission = exports.hasPermission = exports.init = exports.sendTemplateEmail = exports.sendSimpleEmail = void 0;
 const parse_server_schema_1 = require("@openinc/parse-server-schema");
 const fast_equals_1 = require("fast-equals");
 const fs_1 = __importDefault(require("fs"));
@@ -15,13 +15,21 @@ const _init_1 = require("./functions/_init");
 const Core_Email_1 = require("./hooks/Core_Email");
 const _init_2 = require("./hooks/_init");
 const types_1 = require("./types");
-var Config_1 = require("./helper/Config");
-Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return Config_1.Config; } });
+// export { Config } from "./helper/Config";
 var Core_Email_2 = require("./hooks/Core_Email");
 Object.defineProperty(exports, "sendSimpleEmail", { enumerable: true, get: function () { return Core_Email_2.sendSimpleEmail; } });
 Object.defineProperty(exports, "sendTemplateEmail", { enumerable: true, get: function () { return Core_Email_2.sendTemplateEmail; } });
-exports.PREFIX = "OD3_";
+const PREFIX = "OD3_";
 let schema = {};
+/**
+ * Initializes the Cloud Code for open.DASH.
+ * This function performs various initialization tasks such as
+ * initializing configuration, setting up email transport, initializing web push,
+ * initializing class schema, setting up default roles, initializing parse lifecycle hooks,
+ * loading default data, initializing cloud functions, and setting up cloud code autoloading.
+ *
+ * @returns {Promise<void>} A promise that resolves when the initialization is complete.
+ */
 async function init() {
     try {
         const pkg = require("../package.json");
@@ -33,8 +41,8 @@ async function init() {
     await initWebPush();
     await initSchema();
     await initDefaultRoles();
-    await initDefaultData();
     await (0, _init_2.init)();
+    await initDefaultData();
     await (0, _init_1.init)();
     await initAutoload();
 }
@@ -55,7 +63,7 @@ async function initSchema() {
     const schemaConfig = await (0, parse_server_schema_1.loadConfig)();
     try {
         await (0, parse_server_schema_1.up)(schemaConfig, (0, path_1.resolve)(__dirname, "../schema"), {
-            prefix: exports.PREFIX,
+            prefix: PREFIX,
             deleteClasses: config_1.config.getBoolean("FORCE_SCHEMA"),
             deleteFields: config_1.config.getBoolean("FORCE_SCHEMA"),
             filter: (className) => isClassEnabled(className),
@@ -85,12 +93,49 @@ async function initDefaultRoles() {
 }
 async function initDefaultData() {
     try {
-        // TODO
+        const permissions = [await ensurePermission("parse-admin")];
+        const tenantCount = await new Parse.Query(types_1.Tenant).count({
+            useMasterKey: true,
+        });
+        if (tenantCount > 0) {
+            return null;
+        }
+        const tenant = new types_1.Tenant({
+            label: "Default Tenant",
+        });
+        await tenant.save(null, { useMasterKey: true });
+        const password = await createRandomPassword();
+        const user = new Parse.User({
+            name: "Default User",
+            username: "openinc",
+            password: password,
+            email: "noreply@openinc.de",
+            emailVerified: true,
+            tenant,
+            tenantVerified: true,
+            tenantAdmin: true,
+        });
+        await user.save(null, { useMasterKey: true });
+        for (const permission of permissions) {
+            permission.getACL()?.setReadAccess(user, true);
+            await permission.save(null, { useMasterKey: true });
+        }
+        console.log("Default User and Tenant created.");
+        console.log("Username: " + user.get("username"));
+        console.log("Password: " + password);
+        console.log("User:     " + user.id);
+        console.log("Tenant:   " + tenant.id);
     }
     catch (error) {
         console.error(error);
     }
 }
+/**
+ * Checks if a user has a specific permission in OD3_Permission.
+ * @param sessionToken - The session token of the user.
+ * @param key - The key of the permission to check.
+ * @returns A promise that resolves to a boolean indicating whether the user has the permission.
+ */
 async function hasPermission(sessionToken, key) {
     const result = await new Parse.Query(types_1.Permission)
         .equalTo("key", key)
@@ -98,6 +143,15 @@ async function hasPermission(sessionToken, key) {
     return !!result;
 }
 exports.hasPermission = hasPermission;
+/**
+ * Checks if the user has the required permission to perform an operation using hasPermission().
+ * If the user does not have the required permission, an error is thrown.
+ *
+ * @param request - The request object containing the user's session token and masterkey status.
+ * @param key - The permission key required for the operation.
+ * @param message - The error message to be thrown if the user does not have the required permission.
+ * @returns A Promise that resolves if the user has the required permission, or throws an error if not.
+ */
 async function requirePermission(request, key, message) {
     if (request.master) {
         return;
@@ -114,6 +168,11 @@ async function requirePermission(request, key, message) {
     }
 }
 exports.requirePermission = requirePermission;
+/**
+ * Retrieves the value of a configuration key from OD3_Config.
+ * @param key - The key of the configuration to retrieve.
+ * @returns A promise that resolves to the value of the configuration key, or undefined if not found.
+ */
 async function getConfig(key) {
     const result = await new Parse.Query(types_1.Config).equalTo("key", key).first({
         useMasterKey: true,
@@ -123,6 +182,17 @@ async function getConfig(key) {
     return value || "";
 }
 exports.getConfig = getConfig;
+/**
+ * Retrieves the value of a configuration key from OD3_Config as a boolean
+ * Converts the string value to a boolean value using the following rules:
+ * - "true" or "1" -> true
+ * - "false" or "0" -> false
+ * - undefined/null -> false
+ * - Any other value -> true
+ *
+ * @param key - The key of the configuration value.
+ * @returns A boolean value indicating the configuration value.
+ */
 async function getConfigBoolean(key) {
     const value = await getConfig(key);
     if (!value || value.toLowerCase() === "false" || value === "0") {
@@ -131,6 +201,18 @@ async function getConfigBoolean(key) {
     return true;
 }
 exports.getConfigBoolean = getConfigBoolean;
+/**
+ * Ensures the existence of a role with the specified name.
+ * If the role does not exist, it creates a new role with the given name and options.
+ * If the role already exists, it updates the role with the provided options.
+ *
+ * @param name - The name of the role.
+ * @param options - Optional parameters for the role.
+ * @param options.label - The label for the role.
+ * @param options.acl - The Parse.ACL for the role.
+ * @param options.childRoles - An array of child role names to be associated with the role.
+ * @returns A Promise that resolves when the role is successfully created or updated.
+ */
 async function ensureRole(name, options) {
     const label = options?.label || undefined;
     const acl = options?.acl || new Parse.ACL();
@@ -179,6 +261,12 @@ async function ensureRole(name, options) {
     }
 }
 exports.ensureRole = ensureRole;
+/**
+ * Ensures that a user has a specific role.
+ * @param user The user to assign the role to.
+ * @param roleName The name of the role.
+ * @param add Specifies whether to add or remove the user from the role. Default is false (remove).
+ */
 async function ensureUserRole(user, roleName, add = false) {
     const role = await new Parse.Query(Parse.Role)
         .equalTo("name", roleName)
@@ -196,6 +284,16 @@ async function ensureUserRole(user, roleName, add = false) {
     }
 }
 exports.ensureUserRole = ensureUserRole;
+/**
+ * Checks if a field is immutable and throws an error if an attempt is made to edit it in a beforeSave hook.
+ *
+ * This will not throw an error if the request is made with the master key.
+ *
+ * @param request - The request object containing the original and object Parse objects, master flag, and session token.
+ * @param fieldName - The name of the field to check for immutability.
+ * @param permissionName - The name of the permission required to edit the field. Defaults to "parse:edit-immutable-fields".
+ * @returns Promise<void>
+ */
 async function immutableField(request, fieldName, permissionName = "parse:edit-immutable-fields") {
     if (!request.original || request.master) {
         return;
@@ -208,6 +306,16 @@ async function immutableField(request, fieldName, permissionName = "parse:edit-i
     await requirePermission(request, permissionName, `You are not allowed to edit the '${fieldName}' field.`);
 }
 exports.immutableField = immutableField;
+/**
+ * Handles the default beforeSave() logic for a Parse.Object.
+ *
+ * This function will check if a user or tenant field is present in the schema and set the value to the current user and/or the tenant of the current user if not provided.
+ * This will also mark the user and tenant fields as immutable, preventing them from being edited in the future.
+ *
+ * @param request - The Parse.Cloud.BeforeSaveRequest object.
+ * @returns - Returns void.
+ * @throws - Throws an error if the user is not provided.
+ */
 async function defaultHandler(request) {
     const className = request.object.className;
     if (request.master) {
@@ -243,6 +351,17 @@ async function defaultHandler(request) {
     }
 }
 exports.defaultHandler = defaultHandler;
+/**
+ * Handles the default Parse.ACL beforeSave() logic for a Parse.Object.
+ *
+ * This function will set the default ACL for the object based on the user and tenant fields. By default, the object will be readable and writable by the tenant role and readable by tenant users.
+ *
+ * @param request - The Parse.Cloud.BeforeSaveRequest object.
+ * @param options - Optional configuration options.
+ * @param options.allowCustomACL - Whether to allow custom ACL (default: false).
+ * @param options.allowTenantUserWrite - Whether to allow tenant users to write (default: false).
+ * @param options.denyTenantUserRead - Whether to deny tenant users from reading (default: false).
+ */
 async function defaultAclHandler(request, options) {
     const className = request.object.className;
     const currentSchema = schema[className];
@@ -281,6 +400,14 @@ async function defaultAclHandler(request, options) {
 }
 exports.defaultAclHandler = defaultAclHandler;
 const beforeSaveHooks = {};
+/**
+ * Registers a beforeSave hook for a Parse class. In comparison to Parse.Cloud.beforeSave(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {beforeSaveHookType<T>} callback - The callback function to be executed before saving the object.
+ * @returns {void}
+ */
 function beforeSaveHook(target, callback) {
     // @ts-ignore
     const className = typeof target === "string" ? target : target.className;
@@ -298,6 +425,14 @@ function beforeSaveHook(target, callback) {
 }
 exports.beforeSaveHook = beforeSaveHook;
 const afterSaveHooks = {};
+/**
+ * Registers a afterSave hook for a Parse class. In comparison to Parse.Cloud.afterSave(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {afterSaveHookType<T>} callback - The callback function to be executed after saving the object.
+ * @returns {void}
+ */
 function afterSaveHook(target, callback) {
     // @ts-ignore
     const className = typeof target === "string" ? target : target.className;
@@ -315,6 +450,13 @@ function afterSaveHook(target, callback) {
 }
 exports.afterSaveHook = afterSaveHook;
 const beforeDeleteHooks = {};
+/**
+ * Registers a beforeDelete hook for a Parse class. In comparison to Parse.Cloud.beforeDelete(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {beforeDeleteHookType<T>} callback - The callback function to be executed before deleting an object.
+ */
 function beforeDeleteHook(target, callback) {
     // @ts-ignore
     const className = typeof target === "string" ? target : target.className;
@@ -332,6 +474,14 @@ function beforeDeleteHook(target, callback) {
 }
 exports.beforeDeleteHook = beforeDeleteHook;
 const afterDeleteHooks = {};
+/**
+ * Registers a afterDelete hook for a Parse class. In comparison to Parse.Cloud.afterDelete(), this function allows multiple beforeSave hooks to be registered for the same class.
+ *
+ * @template T - The type of the Parse.Object.
+ * @param {string | { new (): T }} target - The name of the Parse class or the class itself.
+ * @param {afterDeleteHookType<T>} callback - The callback function to be executed after a delete operation.
+ * @returns {void}
+ */
 function afterDeleteHook(target, callback) {
     // @ts-ignore
     const className = typeof target === "string" ? target : target.className;
@@ -348,6 +498,13 @@ function afterDeleteHook(target, callback) {
     afterDeleteHooks[className].push(callback);
 }
 exports.afterDeleteHook = afterDeleteHook;
+/**
+ * Autoloads cloud code files from the specified path. Each file MUST export an init() function that takes the file name (without it's extension) as an argument.
+ *
+ * @param path - The path to the directory containing the cloud code files.
+ * @param regex - Optional regular expression to filter the file names. Defaults to /^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$/.
+ * @returns A promise that resolves when all the cloud code files have been loaded and initialized.
+ */
 async function autoloadCloudCode(path, regex = /^[a-zA-Z0-9]+(?:-[a-zA-Z0-9]+)*$/) {
     const fns = fs_1.default
         .readdirSync(path)
@@ -366,7 +523,6 @@ async function initAutoload() {
         await autoloadCloudCode((0, path_1.resolve)(process.cwd(), path));
     }
 }
-exports.initAutoload = initAutoload;
 function getFeatureForClassName(className) {
     const map = featuremap_json_1.default;
     return map[className] || "unknown";
@@ -397,3 +553,43 @@ function isClassEnabled(className) {
     const enabled = isFeatureEnabled(feature);
     return enabled;
 }
+/**
+ * Ensures that a OD3_Permission with the specified key exists in the database.
+ * If the permission already exists, it updates the ACL if provided.
+ * If the permission does not exist, it creates a new permission with the specified key and ACL.
+ * @param key - The key of the permission.
+ * @param acl - The Parse.ACL to be set for the permission.
+ * @returns The updated or newly created permission.
+ */
+async function ensurePermission(key, acl) {
+    const permission = await new Parse.Query(types_1.Permission)
+        .equalTo("key", key)
+        .first({ useMasterKey: true });
+    if (permission) {
+        if (acl) {
+            permission.setACL(acl);
+            return await permission.save(null, { useMasterKey: true });
+        }
+        return permission;
+    }
+    else {
+        const newPermission = new types_1.Permission({ key });
+        if (acl) {
+            newPermission.setACL(acl);
+        }
+        else {
+            newPermission.setACL(new Parse.ACL());
+        }
+        return await newPermission.save(null, { useMasterKey: true });
+    }
+}
+exports.ensurePermission = ensurePermission;
+async function createRandomPassword() {
+    const length = 32;
+    const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    let password = "";
+    for (let i = 0; i < length; i++) {
+        password += charset.charAt(Math.floor(Math.random() * charset.length));
+    }
+    return password;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openinc/parse-server-opendash",
-  "version": "2.4.7",
+  "version": "2.4.9",
   "description": "Parse Server Cloud Code for open.DASH",
   "keywords": [
     "parse",
@@ -30,12 +30,15 @@
     "@types/nunjucks": "^3.2.2",
     "@types/parse": "^3.0.0",
     "@types/web-push": "^3.0.0",
+    "typedoc": "^0.25.8",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.0.0"
   },
   "scripts": {
     "start": "tsc -w",
     "build": "tsc",
     "schema-down": "parse-server-schema down --prefix OD3_ ./schema",
-    "schema-ts": "parse-server-schema typescript --prefix OD3_ --global-sdk ./src/types"
+    "schema-ts": "parse-server-schema typescript --prefix OD3_ --global-sdk ./src/types",
+    "typedoc": "typedoc --plugin typedoc-plugin-markdown --hideBreadcrumbs --out docs src/index.ts"
   }
 }