@c8y/client
Version:
Client application programming interface to access the Cumulocity IoT-Platform REST services.
395 lines • 13.7 kB
TypeScript
import { IIdentified, Service, IResult } from '../core/index.js';
import { IUser } from './IUser.js';
import { ICurrentUser } from './ICurrentUser.js';
import { UserInventoryRoleService } from './UserInventoryRoleService.js';
import { IResetPassword } from './IResetPassword.js';
import { ITotp } from './ITotp.js';
import { ITotpStatus } from './ITotpStatus.js';
/**
* @description
* This service allows for managing users.
*/
export declare class UserService extends Service<IUser> {
protected get listUrl(): string;
protected baseUrl: string;
protected currentUserUrl: string;
protected passwordResetUrl: string;
protected validateResetTokenUrl: string;
protected currentUserPhoneUrl: string;
protected verifyTFACodeUrl: string;
protected totpCurrentUserURL: string;
protected verifyTOTPCodeUrl: string;
protected activateTOTPCodeUrl: string;
protected revokeTOTPSecretUrl: string;
protected get newsletterEmailsUrl(): string;
protected get currentUserPasswordUrl(): string;
protected get revokeAllTokensUrl(): string;
protected propertyName: string;
/**
* Gets the details of given user.
*
* @param {string | number | IUser} entityOrId User's id or user object.
* @param {object} params Additional query params.
*
* @returns Returns promise object that is resolved with the IUser wrapped by IResult.
*
* **Example**
* ```typescript
*
* const userId: number = 1;
* const params = { withCertificates: true };
*
* (async () => {
* const { data, res } = await userService.detail(userId, params);
* })();
* ```
* User password is never returned in GET response. Authentication mechanism is provided by another interface.
*/
detail(entityOrId: string | number | IUser, params?: object): Promise<IResult<IUser>>;
/**
* Creates a new user.
*
* @param {IUser} entity User object.
*
* @returns {IResult<IUser>} Returns promise object that is resolved with the details of newly created user.
*
* **Example**
* ```typescript
*
* const userObject: IUser = {
* userName: "newUser",
* password: "userPassword12!@"
* };
*
* (async () => {
* const {data, res} = await userService.create(userObject);
* })();
* ```
*/
create(entity: IUser): Promise<IResult<IUser>>;
/**
* Updates user data.
*
* @param {Partial<IUser>} entity User is partially updatable.
*
* @returns {IResult<IUserGroup>} Returns promise object that is resolved with the saved user object.
*
* **Example**
* ```typescript
*
* const partialUpdateObject: Partial<IUser> = {
* "id" : "myuser",
* "userName" : "newUserName",
* "email": "newUserEmail@example.com"
* ...
* }
*
* (async () => {
* const {data, res} = await userService.update(partialUpdateObject);
* })();
* ```
* When user is updated with changed permissions or groups, suitable audit record is created with type
* 'User' and activity 'User updated'.
*/
update(entity: Partial<IUser>): Promise<IResult<IUser>>;
/**
* Gets the list of users filtered by parameters.
*
* @param {object} filter Object containing filters for querying users.
*
* @returns Returns promise object that is resolved with the IUser wrapped by IResultList.
*
* **Example**
* ```typescript
*
* const filter: object = {
* pageSize: 100,
* withTotalPages: true
* };
*
* (async () => {
* const {data, res, paging} = await userService.list(filter);
* })();
* ```
*/
list(filter?: object): Promise<import("../core/IResultList.js").IResultList<IUser>>;
/**
* Removes user.
*
* @param {number|IIdentified} entityOrId User's id or user object.
*
* @returns Returns promise object that is resolved with the IResult of null.
*
* **Example**
* ```typescript
*
* const userId: string = "uniqueUserId";
*
* (async () => {
* const {data, res} = await userService.delete(userGroupId);
* })();
* ```
*/
delete(entityOrId: string | number | IIdentified): Promise<IResult<null>>;
/**
* Create instance of User Inventory Role Service related with given User.
*
* @param {string|number|IUser} entityOrId User's id or user object.
*
* @returns Returns UserInventoryRoleService object that is related with given User.
*
* **Example**
* ```typescript
*
* const userId: string = "uniqueUserId";
*
* const userInventoryRoleService = userService.inventoryAssignment(userGroupId);
* (async () => {
* const {data, res} = await userInventoryRoleService.create(...);
* })();
* ```
*/
inventoryAssignment(entityOrId: string | number | IUser): UserInventoryRoleService;
/**
* Gets user that is currently logged in.
*
* @returns Returns promise object that is resolved with the IUser wrapped by IResult.
*
* Note that this method will fail to retrieve the current user if the user is a service user.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.current();
* })();
* ```
*/
current(): Promise<IResult<IUser>>;
/**
* Gets user that is currently logged in with the list of all roles assigned.
*
* @returns Returns promise object that is resolved with the ICurrenUser wrapped by IResult.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.currentWithEffectiveRoles();
* })();
* ```
*/
currentWithEffectiveRoles(): Promise<IResult<ICurrentUser>>;
/**
* Updates the current user
*
* @param {IUser} user The user object with the properties to be updated
*
* @return Returns promise object resolved with the IUser wrapped by IResult
*/
updateCurrent(user: Partial<IUser>): Promise<IResult<IUser>>;
/**
* Sends an email message with a link allowing user to reset their password.
*
* @param {string} email The email address to send the message to.
* @param {string} tenantId The id of user's tenant (if cannot be inferred from URL).
*
* @returns Returns a request result object.
*
* **Example**
* ```typescript
* const email = 'user@example.com';
* const tenantId = 't123456';
*
* (async () => {
* const { res, data } = await userService.sendPasswordResetMail(email, tenantId);
* })();
* ```
*/
sendPasswordResetMail(email: string, tenantId?: string): Promise<IResult<null>>;
/**
* Resets user's password to a new one.
*
* @param {IResetPassword} newPassword Object with token, user's email, new password and its strength indicator.
* @param {string} tenantId The id of user's tenant (if cannot be inferred from URL).
*
* @returns Returns a request result object.
*
* **Example**
* ```typescript
* const newPassword: IResetPassword = {
* token: '123123ASDAWERER@#!WEDS$@#!WADA#A#EA#EA#EA',
* email: 'user@example.com',
* newPassword: 'myNewPassword',
* passwordStrength: PasswordStrength.GREEN
* };
* const tenantId = 't123456';
*
* (async () => {
* const { res, data } = await userService.resetPassword(newPassword, tenantId);
* })();
* ```
*/
resetPassword(newPassword: IResetPassword, tenantId?: string): Promise<IResult<null>>;
/**
* Validates a password reset token for a specific user and tenant.
*
* @param token - The reset token to validate.
* @param email - The email address of the user.
* @returns A promise that resolves to an IResult object containing the response and null data.
*
* @example
* ```typescript
* async function checkTokenStatus(token: string, email: string) {
* try {
* await userService.validateResetToken(token, email);
* return 'valid';
* } catch (e) {
* if (e.res?.status === 422) {
* return 'expired';
* } else {
* return 'invalid';
* }
* }
* }
* ```
*/
validateResetToken(token: string, email: string): Promise<IResult<null>>;
/**
* Verifies TFA code which is sent via SMS. If invoked with string '0', new TFA code will be sent.
*
* @param {string} pin The code to verify.
*
* @returns Returns a status object.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.verifyTFACode('123123');
* })();
* ```
*/
verifyTFACode(pin: string): Promise<IResult<null>>;
/**
* Verifies TFA code which is generated by a TOTP app.
*
* @param {string} code The code to verify.
*
* @returns Returns a status object.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.verifyTotpCode('123123');
* })();
* ```
*/
verifyTotpCode(code: any): Promise<IResult<null>>;
/**
* Verifies TFA code which is generated by a TOTP app.
*
* @returns Returns a status object.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.activateTotp();
* })();
* ```
*/
activateTotp(): Promise<IResult<null>>;
/**
* Checks if TOTP is activated and enforced.
*
* @returns Returns an object of ITotpStatus if it is active.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.getActivityTotp();
* console.log(data.isActive);
* })();
* ```
*/
getActivityTotp(): Promise<IResult<ITotpStatus>>;
/**
* Generates a secret which can be used to setup two-factor authentication with TOTP.
*
* @returns Returns the secret and an URL to a QR Code.
*
* **Example**
* ```typescript
*
* (async () => {
* const {data, res} = await userService.generateTotpSecret();
* console.log(secret);
* })();
* ```
*/
generateTotpSecret(): Promise<IResult<ITotp>>;
/**
* Revokes a specific user's TOTP secret.
*
* @param {IUser} user User whose TOTP secret to revoke.
*
* @returns Status object
*/
totpRevokeSecret(user: IUser): Promise<IResult<null>>;
/**
* Saves phone number for the current user.
* @param phoneNumber Phone number to save.
* @returns Server response and data with updated current user object.
*/
savePhoneNumber(phoneNumber: string): Promise<IResult<ICurrentUser>>;
/**
* Gets the list of emails of users subscribed for newsletter
* on the current tenant and its subtenants.
* @returns Server response and data with email addresses as plain text.
*/
getNewsletterEmails(): Promise<IResult<string>>;
/**
* Changes password for user.
*
* @param {string | number | IUser} entityOrId User's id or user object.
* @param {string} newPassword New user password.
* @param {string} currentUserPassword The password of the currently logged user.
*
* @returns Returns a result object.
*/
changeUserPassword(entityOrId: string | number | IUser, newPassword: string, currentUserPassword: string): Promise<IResult<null>>;
/**
* Changes password for current user.
*
* @param {string} newPassword New password for current user.
* @param {string} currentUserPassword The password of the currently logged user.
*
* @returns Returns a result object. During this action if preferred login mode is OAI_SECURE new jwt cookie will be set.
*/
changeCurrentUserPassword(newPassword: string, currentUserPassword: string): Promise<IResult<null>>;
/**
* Revoke tokens for all users. All users logged with "OAI-Secure" or "Single sign-on redirect" will be logged out.
*
* @returns Returns a result object.
*/
revokeTokens(): Promise<IResult<null>>;
hasRole(user: IUser | ICurrentUser, roleId: string): boolean;
hasAllRoles(user: IUser | ICurrentUser, roleIds: string[]): boolean;
hasAnyRole(user: IUser | ICurrentUser, roleIds: string[]): boolean;
hasAnyGlobalRole(user: IUser | ICurrentUser, globalRoleIds: number[]): boolean;
isDeviceUser(user: IUser | ICurrentUser): RegExpMatchArray;
isServiceUser(user: IUser | ICurrentUser): RegExpMatchArray;
isExternalUser(user: IUser | ICurrentUser): boolean;
protected onBeforeUpdate(user: Partial<IUser>): any;
protected getDetailUrl(entityOrId: string | number | IUser): string;
protected getId(entityOrId: string | number | IUser): string;
protected hasRoleInUser(user: IUser | ICurrentUser, roleId: any): any;
protected hasRoleInGroups(user: IUser | ICurrentUser, roleId: any): any;
protected hasRoleInReferences(references: any, roleId: any): any;
protected changeUserPasswordUrl(entityOrId: string | number | IUser): string;
protected hasGlobalRoleInUser(user: IUser | ICurrentUser, globalRoleId: number): boolean;
}
//# sourceMappingURL=UserService.d.ts.map