@nymphjs/tilmeld 1.0.0-beta.9 → 1.0.0-beta.91

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 { Nymph, EntityData, EntityJson, EntityPatch, Options, Selector, 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@gmail.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,29 +115,105 @@ 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 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();
+    $setNymph(nymph: Nymph): void;
+    $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 a 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)[]>;
+    /**
+     * Gets an array of the group's descendant groups.
+     *
+     * @param andSelf Include this group in the returned array.
+     * @returns An array of groups.
+     */
     $getDescendants(andSelf?: boolean): Promise<(Group & GroupData)[]>;
-    $getDescendantsSync(andSelf?: boolean): (Group & GroupData)[];
-    $getLevel(): number;
-    $getUsers(descendants?: boolean, limit?: number, offset?: number): Promise<(User & UserData)[]>;
+    /**
+     * 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 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;
@@ -60,4 +222,8 @@ export default class Group extends AbleObject<GroupData> {
     $saveSkipAC(): Promise<boolean>;
     $tilmeldSaveSkipAC(): boolean;
     $delete(): Promise<boolean>;
+    $deleteSkipAC(): Promise<boolean>;
+    $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;
 }