@nymphjs/tilmeld 1.0.0-beta.13 → 1.0.0-beta.130

package/dist/AbleObject.d.ts

@@ -1,7 +1,22 @@
 import { Entity } from '@nymphjs/nymph';
+/**
+ * AbleObject abstract class.
+ *
+ * Used in entities which support abilities, such as users and groups.
+ */
 export default abstract class AbleObject<T extends {
     abilities?: string[];
 }> extends Entity<T> {
+    /**
+     * Grant an ability.
+     *
+     * @param ability The ability.
+     */
     $grant(ability: string): void;
+    /**
+     * Revoke an ability.
+     *
+     * @param ability The ability.
+     */
     $revoke(ability: string): void;
 }

package/dist/AbleObject.js

@@ -1,15 +1,28 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const nymph_1 = require("@nymphjs/nymph");
-class AbleObject extends nymph_1.Entity {
+import { Entity } from '@nymphjs/nymph';
+/**
+ * AbleObject abstract class.
+ *
+ * Used in entities which support abilities, such as users and groups.
+ */
+export default class AbleObject extends Entity {
+    /**
+     * Grant an ability.
+     *
+     * @param ability The ability.
+     */
     $grant(ability) {
         if (!Array.isArray(this.$data.abilities)) {
             this.$data.abilities = [];
         }
-        if (this.$data.abilities.indexOf(ability) === -1) {
+        if (!this.$data.abilities.includes(ability)) {
             this.$data.abilities.push(ability);
         }
     }
+    /**
+     * Revoke an ability.
+     *
+     * @param ability The ability.
+     */
     $revoke(ability) {
         if (!Array.isArray(this.$data.abilities)) {
             this.$data.abilities = [];
@@ -23,5 +36,4 @@ class AbleObject extends nymph_1.Entity {
         } while (idx !== -1);
     }
 }
-exports.default = AbleObject;
 //# sourceMappingURL=AbleObject.js.map

package/dist/AbleObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbleObject.js","sourceRoot":"","sources":["../src/AbleObject.ts"],"names":[],"mappings":";;AAAA,0CAAwC;AAOxC,MAA8B,UAE5B,SAAQ,cAAS;IAMV,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;YACxC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;SAC3B;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE;YAChD,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;SACpC;IACH,CAAC;IAOM,OAAO,CAAC,OAAe;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;YACxC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;SAC3B;QACD,IAAI,GAAW,CAAC;QAChB,GAAG;YACD,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE;gBACd,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;aACrC;SACF,QAAQ,GAAG,KAAK,CAAC,CAAC,EAAE;IACvB,CAAC;CACF;AAlCD,6BAkCC"}
+{"version":3,"file":"AbleObject.js","sourceRoot":"","sources":["../src/AbleObject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAgB,UAE5B,SAAQ,MAAS;IACjB;;;;OAIG;IACI,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,OAAe;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;QAC5B,CAAC;QACD,IAAI,GAAW,CAAC;QAChB,GAAG,CAAC;YACF,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACtC,CAAC;QACH,CAAC,QAAQ,GAAG,KAAK,CAAC,CAAC,EAAE;IACvB,CAAC;CACF"}

package/dist/Group.d.ts

@@ -1,25 +1,111 @@
-import { EntityData, EntityJson, EntityPatch, Options, Selector, SerializedEntityData } from '@nymphjs/nymph';
-import type Tilmeld from './Tilmeld';
-import AbleObject from './AbleObject';
-import User, { UserData } from './User';
+import { type EntityData, type EntityJson, type EntityPatch, type Options, type Selector, type SerializedEntityData } from '@nymphjs/nymph';
+import AbleObject from './AbleObject.js';
+import UserClass from './User.js';
+import type { UserData } from './User.js';
+export type GroupEventType = 'checkGroupname' | 'beforeSave' | 'afterSave' | 'beforeDelete' | 'afterDelete';
+/**
+ * This is run when the user has entered an otherwise valid groupname into the
+ * signup form. It should return a result, which when false will stop the
+ * process and return the included message, disallowing the groupname.
+ */
+export type TilmeldCheckGroupnameCallback = (group: Group & GroupData, data: {
+    groupname: string;
+}) => Promise<{
+    result: boolean;
+    message?: string;
+}>;
+/**
+ * This is run just before the group is saved, so all checks have passed.
+ *
+ * The transaction is available in `group.$nymph`.
+ */
+export type TilmeldBeforeGroupSaveCallback = (group: Group & GroupData) => Promise<void>;
+/**
+ * This is run before the transaction is committed, and you can perform
+ * additional functions on the transaction, which is available in
+ * `group.$nymph`.
+ */
+export type TilmeldAfterGroupSaveCallback = (group: Group & GroupData) => Promise<void>;
+/**
+ * The transaction is available in `group.$nymph`.
+ */
+export type TilmeldBeforeGroupDeleteCallback = (group: Group & GroupData) => Promise<void>;
+/**
+ * This is run before the transaction is committed, and you can perform
+ * additional functions on the transaction, which is available in
+ * `group.$nymph`.
+ */
+export type TilmeldAfterGroupDeleteCallback = (group: Group & GroupData) => Promise<void>;
 export type GroupData = {
+    /**
+     * The abilities granted to the group.
+     */
     abilities?: string[];
+    /**
+     * The group's groupname.
+     */
     groupname?: string;
+    /**
+     * The group's name.
+     */
     name?: string;
+    /**
+     * The group's email address.
+     */
     email?: string;
+    /**
+     * The group's avatar URL. (Use getAvatar() to support Gravatar.)
+     */
     avatar?: string;
+    /**
+     * The group's telephone number.
+     */
     phone?: string;
+    /**
+     * The group's parent.
+     */
     parent?: Group & GroupData;
-    user?: (User & UserData) | null;
+    /**
+     * If generatePrimary is on, this will be the user who generated this group.
+     */
+    user?: (UserClass & UserData) | null;
+    /**
+     * Whether the group can be used.
+     */
     enabled?: boolean;
+    /**
+     * Whether this group is the default primary group for new users.
+     */
     defaultPrimary?: boolean;
+    /**
+     * Whether this group is a default secondary group for new users.
+     */
     defaultSecondary?: boolean;
+    /**
+     * Whether this group is a default secondary group for unverified users.
+     */
     unverifiedSecondary?: boolean;
 };
+/**
+ * A user group data model.
+ *
+ * Written by Hunter Perrin for SciActive.
+ *
+ * @author Hunter Perrin <hperrin@port87.com>
+ * @copyright SciActive Inc
+ * @see http://nymph.io/
+ */
 export default class Group extends AbleObject<GroupData> {
-    static tilmeld: Tilmeld;
+    /**
+     * The instance of Tilmeld to use for queries.
+     */
     static ETYPE: string;
     static class: string;
+    private static checkGroupnameCallbacks;
+    private static beforeSaveCallbacks;
+    private static afterSaveCallbacks;
+    private static beforeDeleteCallbacks;
+    private static afterDeleteCallbacks;
     private static DEFAULT_PRIVATE_DATA;
     private static DEFAULT_ALLOWLIST_DATA;
     protected $tags: never[];
@@ -29,35 +115,116 @@ export default class Group extends AbleObject<GroupData> {
     static searchRestrictedData: string[];
     protected $allowlistData?: string[] | undefined;
     protected $allowlistTags?: string[];
+    /**
+     * This should only be used by the backend.
+     */
     private $skipAcWhenSaving;
-    static factory(guid?: string): Promise<Group & GroupData>;
+    /**
+     * This should only be used by the backend.
+     */
+    private $skipAcWhenDeleting;
+    /**
+     * Used to save the current groupname for domain admin permissions.
+     */
+    $originalGroupname?: string;
+    static getFTSText(name: string, value: any): string | null;
     static factoryGroupname(groupname?: string): Promise<Group & GroupData>;
-    static factorySync(guid?: string): Group & GroupData;
-    constructor(guid?: string);
+    /**
+     * Get all the groups that can be assigned as primary groups.
+     *
+     * @param options The options for an optional search query.
+     * @param selectors The selectors for an optional search query.
+     * @returns An array of the assignable primary groups.
+     */
     static getPrimaryGroups(options?: Options, selectors?: Selector[]): Promise<(Group & GroupData)[]>;
+    /**
+     * Get all the groups that can be assigned as secondary groups.
+     *
+     * @param options The options for an optional search query.
+     * @param selectors The selectors for an optional search query.
+     * @returns An array of the assignable secondary groups.
+     */
     static getSecondaryGroups(options?: Options, selectors?: Selector[]): Promise<(Group & GroupData)[]>;
     private static getAssignableGroups;
+    constructor();
+    $getUniques(): Promise<string[]>;
     $getAvatar(): string;
     $jsonAcceptData(input: EntityJson, allowConflict?: boolean): void;
     $jsonAcceptPatch(patch: EntityPatch, allowConflict?: boolean): void;
-    $putData(data: EntityData, sdata?: SerializedEntityData): void;
-    $updateDataProtection(givenUser?: User & UserData): void;
-    $isDescendant(givenGroup: (Group & GroupData) | string): boolean;
+    private $checkIncomingAbilities;
+    $putData(data: EntityData, sdata?: SerializedEntityData, source?: 'server'): void;
+    /**
+     * Update the data protection arrays for a user.
+     *
+     * @param givenUser User to update protection for. If undefined, will use the currently logged in user.
+     */
+    $updateDataProtection(givenUser?: UserClass & UserData): void;
+    /**
+     * Check whether the group is a descendant of the given group.
+     *
+     * @param group The group, or the group's GUID.
+     * @returns True or false.
+     */
+    $isDescendant(givenGroup: (Group & GroupData) | string): Promise<boolean>;
+    /**
+     * Gets an array of the group's child groups.
+     *
+     * @returns An array of groups.
+     */
     $getChildren(): Promise<(Group & GroupData)[]>;
-    $getDescendants(andSelf?: boolean): Promise<(Group & GroupData)[]>;
-    $getDescendantsSync(andSelf?: boolean): (Group & GroupData)[];
-    $getLevel(): number;
-    $getUsers(descendants?: boolean, limit?: number, offset?: number): Promise<(User & UserData)[]>;
+    /**
+     * Gets an array of the group's descendant groups.
+     *
+     * @param andSelf Include this group in the returned array.
+     * @param andDisabled Include disabled groups.
+     * @returns An array of groups.
+     */
+    $getDescendants(andSelf?: boolean, andDisabled?: boolean): Promise<(Group & GroupData)[]>;
+    /**
+     * Get the number of parents the group has.
+     *
+     * If the group is a top level group, this will return 0. If it is a child of
+     * a top level group, this will return 1. If it is a grandchild of a top level
+     * group, this will return 2, and so on.
+     *
+     * Levels will max out at 1024 to avoid recursive loops.
+     *
+     * @returns The level of the group.
+     */
+    $getLevel(): Promise<number>;
+    /**
+     * Gets an array of enabled users in the group.
+     *
+     * @param descendants Include users in all descendant groups too.
+     * @param limit The limit for the query.
+     * @param offset The offset for the query.
+     * @returns An array of users.
+     */
+    $getUsers(descendants?: boolean, limit?: number, offset?: number): Promise<(UserClass & UserData)[]>;
+    /**
+     * Check that a groupname is valid.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     $checkGroupname(): Promise<{
         result: boolean;
         message: string;
     }>;
+    /**
+     * Check that an email is unique.
+     *
+     * @returns An object with a boolean 'result' entry and a 'message' entry.
+     */
     $checkEmail(): Promise<{
         result: boolean;
         message: string;
     }>;
-    $save(): Promise<boolean>;
-    $saveSkipAC(): Promise<boolean>;
+    $save(): Promise<void>;
+    $saveSkipAC(): Promise<void>;
     $tilmeldSaveSkipAC(): boolean;
-    $delete(): Promise<boolean>;
+    $delete(): Promise<void>;
+    $deleteSkipAC(): Promise<void>;
+    $tilmeldDeleteSkipAC(): boolean;
+    static on<T extends GroupEventType>(event: T, callback: T extends 'checkGroupname' ? TilmeldCheckGroupnameCallback : T extends 'beforeSave' ? TilmeldBeforeGroupSaveCallback : T extends 'afterSave' ? TilmeldAfterGroupSaveCallback : T extends 'beforeDelete' ? TilmeldBeforeGroupDeleteCallback : T extends 'afterDelete' ? TilmeldAfterGroupDeleteCallback : never): () => boolean;
+    static off<T extends GroupEventType>(event: T, callback: T extends 'checkGroupname' ? TilmeldCheckGroupnameCallback : T extends 'beforeSave' ? TilmeldBeforeGroupSaveCallback : T extends 'afterSave' ? TilmeldAfterGroupSaveCallback : T extends 'beforeDelete' ? TilmeldBeforeGroupDeleteCallback : T extends 'afterDelete' ? TilmeldAfterGroupDeleteCallback : never): boolean;
 }