@enonic-types/lib-auth 7.11.0-B1 → 7.11.0-B3

package/README.md

@@ -5,7 +5,7 @@
 ## Install
 
 ```bash
-npm i --save-dev @enonic/lib-auth
+npm i --save-dev @enonic-types/lib-auth
 ```
 
 ## Use
@@ -26,8 +26,8 @@ Add the corresponding types to your `tsconfig.json` file that is used for applic
 
 ### Require and custom imports
 
-To make `require` work out of box, you must install and add the `@enonic-types/global` types. Aside from providing definitions for XP global
-objects, e.g. `log`, `app`, `__`, etc, requiring library by the default path will return typed object.
+To make `require` work out of the box, you must install and add the `@enonic-types/global` types. Aside from providing definitions for XP
+global objects, e.g. `log`, `app`, `__`, etc, requiring a library by the default path will return typed object.
 
 `tsconfig.json`
 
@@ -49,7 +49,7 @@ const {login, logout, getUser, generatePassword} = require('/lib/xp/auth');
 ```
 
 More detailed explanation on how it works and how to type custom import function can be
-found [here](https://github.com/enonic/xp/tree/master/modules/lib/typescript/README.md).
+found [here](https://developer.enonic.com/docs/xp/stable/api).
 
 ### ES6-style import
 

package/auth.d.ts

@@ -11,8 +11,12 @@ declare global {
         '/lib/xp/auth': typeof import('./auth');
     }
 }
-export declare type EditorFn<T> = (value: T) => T;
+import type { Group, GroupKey, Principal, PrincipalKey, Role, RoleKey, User, UserKey } from '@enonic-types/core';
+export type { PrincipalKey, UserKey, GroupKey, RoleKey, Principal, User, Group, Role } from '@enonic-types/core';
 export declare type LoginScopeType = 'SESSION' | 'REQUEST' | 'NONE';
+export interface UserWithProfile<Profile extends Record<string, unknown> = Record<string, unknown>> extends User {
+    profile?: Profile;
+}
 export interface LoginParams {
     user: string;
     skipAuth?: boolean;
@@ -21,29 +25,10 @@ export interface LoginParams {
     scope?: LoginScopeType;
     sessionTimeout?: number;
 }
-export interface Principal {
-    type: string;
-    key: string;
-    displayName: string;
-    modifiedTime: string;
-}
-export interface User extends Principal {
-    disabled?: boolean;
-    email?: string;
-    login?: string;
-    idProvider: string;
-    profile?: Record<string, unknown>;
-}
-export interface Role extends Principal {
-    description?: string;
-}
-export interface Group extends Principal {
-    description?: string;
-}
 export interface LoginResult {
     authenticated: boolean;
     message: string;
-    users?: Principal;
+    user?: User;
 }
 /**
  * Login a user with the specified idProvider, userName, password and scope.
@@ -79,14 +64,19 @@ export interface GetUserParams {
  *
  * @returns {User} Information for logged-in user.
  */
-export declare function getUser(params?: GetUserParams): User | null;
+export declare function getUser(params?: {
+    includeProfile?: false;
+}): User | null;
+export declare function getUser<Profile extends Record<string, unknown> = Record<string, unknown>>(params: {
+    includeProfile: true;
+}): UserWithProfile<Profile> | null;
 /**
  * Checks if the logged-in user has the specified role.
  *
  * @example-ref examples/auth/hasRole.js
  *
- * @param {string} role Role to check for.
- * @returns {boolean} True if the user has specfied role, false otherwise.
+ * @param {string} role Role name to check for.
+ * @returns {boolean} True if the user has specified role, false otherwise.
  */
 export declare function hasRole(role: string): boolean;
 /**
@@ -117,31 +107,31 @@ export declare function changePassword(params: ChangePasswordParams): void;
  * @example-ref examples/auth/getPrincipal.js
  *
  * @param {string} principalKey Principal key to look for.
- * @returns {Principal} the principal specified, or null if it doesn't exist.
+ * @returns {User | Group | Role} the principal specified, or null if it doesn't exist.
  */
-export declare function getPrincipal(principalKey: string): User | Group | Role | null;
+export declare function getPrincipal(principalKey: PrincipalKey): Principal | null;
 /**
  * Returns a list of principals the specified principal is a member of.
  *
  * @example-ref examples/auth/getMemberships.js
  *
- * @param {string} principalKey Principal key to retrieve memberships for.
+ * @param {string} principalKey Principal key of user or group to retrieve memberships for.
  * @param {boolean} [transitive=false] Retrieve transitive memberships.
- * @returns {Array.<User | Group | Role>} Returns the list of principals.
+ * @returns {Array<Group | Role>} Returns the list of groups and roles.
  */
-export declare function getMemberships(principalKey: string, transitive: boolean): (User | Group | Role)[];
+export declare function getMemberships(principalKey: UserKey | GroupKey, transitive?: boolean): (Group | Role)[];
 /**
  * Returns a list of principals that are members of the specified principal.
  *
  * @example-ref examples/auth/getMembers.js
  *
  * @param {string} principalKey Principal key to retrieve members for.
- * @returns {Array.<User | Group | Role>} Returns the list of principals.
+ * @returns {Array<User | Group>} Returns the list of users and groups.
  */
-export declare function getMembers(principalKey: string): (User | Group | Role)[];
+export declare function getMembers(principalKey: GroupKey | RoleKey): (User | Group)[];
 export interface CreateUserParams {
     name: string;
-    displayName: string;
+    displayName?: string;
     idProvider: string;
     email?: string;
 }
@@ -153,13 +143,13 @@ export interface CreateUserParams {
  * @param {object} params JSON parameters.
  * @param {string} params.idProvider Key for id provider where user has to be created.
  * @param {string} params.name User login name to set.
- * @param {string} params.displayName User display name.
+ * @param {string} [params.displayName] User display name.
  * @param {string} [params.email] User email.
  */
 export declare function createUser(params: CreateUserParams): User;
 export interface ModifyUserParams {
-    key: string;
-    editor: EditorFn<User>;
+    key: UserKey;
+    editor: (user: User) => User;
 }
 /**
  * Retrieves the user specified and updates it with the changes applied.
@@ -175,8 +165,8 @@ export declare function modifyUser(params: ModifyUserParams): User | null;
 export interface CreateGroupParams {
     idProvider: string;
     name: string;
-    displayName: string;
-    description: string;
+    displayName?: string;
+    description?: string;
 }
 /**
  * Creates a group.
@@ -186,13 +176,13 @@ export interface CreateGroupParams {
  * @param {object} params JSON parameters.
  * @param {string} params.idProvider Key for id provider where group has to be created.
  * @param {string} params.name Group name.
- * @param {string} params.displayName Group display name.
- * @param {string} params.description as principal description .
+ * @param {string} [params.displayName] Group display name.
+ * @param {string} [params.description] as principal description .
  */
 export declare function createGroup(params: CreateGroupParams): Group;
 export interface ModifyGroupParams {
-    key: string;
-    editor: EditorFn<Group>;
+    key: GroupKey;
+    editor: (group: Group) => Group;
 }
 /**
  * Retrieves the group specified and updates it with the changes applied.
@@ -211,9 +201,9 @@ export declare function modifyGroup(params: ModifyGroupParams): Group | null;
  * @example-ref examples/auth/addMembers.js
  *
  * @param {string} principalKey Key of the principal to add members to.
- * @param {string} members Keys of the principals to add.
+ * @param {Array<string>} members Keys of users and groups to add.
  */
-export declare function addMembers(principalKey: string, members: string): void;
+export declare function addMembers(principalKey: GroupKey | RoleKey, members: (UserKey | GroupKey)[]): void;
 /**
  * Removes members from a principal (user or role).
  *
@@ -222,19 +212,19 @@ export declare function addMembers(principalKey: string, members: string): void;
  * @param {string} principalKey Key of the principal to remove members from.
  * @param {string} members Keys of the principals to remove.
  */
-export declare function removeMembers(principalKey: string, members: string): void;
+export declare function removeMembers(principalKey: GroupKey | RoleKey, members: (UserKey | GroupKey)[]): void;
 export interface FindPrincipalsParams {
-    type?: string;
+    type?: Principal['type'];
     idProvider?: string;
     start?: number;
     count?: number;
     name?: string;
     searchText?: string;
 }
-export interface FindPrincipalsResult {
+export interface FindPrincipalsResult<P extends Principal = Principal> {
     total: number;
     count: number;
-    hits: (User | Group | Role)[];
+    hits: P[];
 }
 /**
  * Search for principals matching the specified criteria.
@@ -259,7 +249,7 @@ export declare function findPrincipals(params: FindPrincipalsParams): FindPrinci
  * @param {string} principalKey Principal key to delete.
  * @returns {boolean} True if deleted, false otherwise.
  */
-export declare function deletePrincipal(principalKey: string): boolean;
+export declare function deletePrincipal(principalKey: PrincipalKey): boolean;
 /**
  * This function returns the ID provider configuration.
  * It is meant to be called from an ID provider controller.
@@ -268,9 +258,9 @@ export declare function deletePrincipal(principalKey: string): boolean;
  *
  * @returns {object} The ID provider configuration as JSON.
  */
-export declare function getIdProviderConfig(): Record<string, unknown> | null;
+export declare function getIdProviderConfig<IdProviderConfig extends Record<string, unknown>>(): IdProviderConfig | null;
 export interface GetProfileParams {
-    key: string;
+    key: UserKey;
     scope?: string;
 }
 /**
@@ -283,11 +273,11 @@ export interface GetProfileParams {
  * @param {string} [params.scope] Scope of the data to retrieve.
  * @returns {object} The extra data as JSON
  */
-export declare function getProfile(params: GetProfileParams): Record<string, unknown> | null;
+export declare function getProfile<Profile extends Record<string, unknown> = Record<string, unknown>>(params: GetProfileParams): Profile | null;
 export interface ModifyProfileParams {
-    key: string;
+    key: UserKey;
     scope?: string | null;
-    editor: EditorFn<User>;
+    editor: (user: User) => User;
 }
 /**
  * This function retrieves the profile of a user and updates it.
@@ -300,7 +290,7 @@ export interface ModifyProfileParams {
  * @param {function} params.editor Profile editor function to apply.
  * @returns {object} The extra data as JSON
  */
-export declare function modifyProfile(params: ModifyProfileParams): Record<string, unknown> | null;
+export declare function modifyProfile<Profile extends Record<string, unknown> = Record<string, unknown>>(params: ModifyProfileParams): Profile | null;
 export interface FindUsersParams {
     start?: number;
     count?: number;
@@ -322,11 +312,16 @@ export interface FindUsersParams {
  *
  * @returns {FindPrincipalsResult} Result of query.
  */
-export declare function findUsers(params: FindUsersParams): FindPrincipalsResult;
+export declare function findUsers(params: FindUsersParams & {
+    includeProfile?: false;
+}): FindPrincipalsResult<User>;
+export declare function findUsers<Profile extends Record<string, unknown> = Record<string, unknown>>(params: FindUsersParams & {
+    includeProfile: true;
+}): FindPrincipalsResult<UserWithProfile<Profile>>;
 export interface CreateRoleParams {
     name: string;
-    displayName: string;
-    description: string;
+    displayName?: string;
+    description?: string;
 }
 /**
  * Creates a role.
@@ -339,8 +334,8 @@ export interface CreateRoleParams {
  */
 export declare function createRole(params: CreateRoleParams): Role;
 export interface ModifyRoleParams {
-    key: string;
-    editor: EditorFn<Role>;
+    key: RoleKey;
+    editor: (role: Role) => Role;
 }
 /**
  * Retrieves the role specified and updates it with the changes applied.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@enonic-types/lib-auth",
-    "version": "7.11.0-B1",
+    "version": "7.11.0-B3",
     "description": "Type definitions for lib-auth.",
     "types": "auth.d.ts",
     "files": [
@@ -26,6 +26,9 @@
         "url": "https://github.com/enonic/xp/issues"
     },
     "homepage": "https://github.com/enonic/xp/tree/master#readme",
+    "dependencies": {
+        "@enonic-types/core": "7.11.0-B3"
+    },
     "publishConfig": {
         "access": "public"
     }