@c8y/client 1018.487.7 → 1018.497.2

package/lib/esm2015/src/user/UserService.d.ts

@@ -0,0 +1,364 @@
+import { IIdentified, Service, IResult } from '../core';
+import { IUser } from './IUser';
+import { ICurrentUser } from './ICurrentUser';
+import { UserInventoryRoleService } from './UserInventoryRoleService';
+import { IResetPassword } from './IResetPassword';
+import { ITotp } from './ITotp';
+import { ITotpStatus } from './ITotpStatus';
+/**
+ * @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 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.
+     *
+     * @returns Returns promise object that is resolved with the IUser wrapped by IResult.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userId: number = 1;
+     *
+     *    (async () => {
+     *      const {data, res} = await userService.detail(userId);
+     *   })();
+     * ```
+     * User password is never returned in GET response. Authentication mechanism is provided by another interface.
+     */
+    detail(entityOrId: string | number | IUser): 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<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.
+     *
+     * **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: 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>>;
+    /**
+     * 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, roleId: string): boolean;
+    hasAllRoles(user: IUser, roleIds: string[]): boolean;
+    hasAnyRole(user: IUser, roleIds: string[]): boolean;
+    hasAnyGlobalRole(user: IUser, globalRoleIds: number[]): boolean;
+    isDeviceUser(user: IUser): RegExpMatchArray;
+    protected onBeforeUpdate(user: IUser): any;
+    protected getDetailUrl(entityOrId: string | number | IUser): string;
+    protected getId(entityOrId: string | number | IUser): string;
+    protected hasRoleInUser(user: any, roleId: any): any;
+    protected hasRoleInGroups(user: any, roleId: any): any;
+    protected hasRoleInReferences(references: any, roleId: any): any;
+    protected changeUserPasswordUrl(entityOrId: string | number | IUser): string;
+    protected hasGlobalRoleInUser(user: IUser, globalRoleId: number): any;
+}
+//# sourceMappingURL=UserService.d.ts.map

package/lib/esm2015/src/user/index.d.ts

@@ -0,0 +1,10 @@
+export * from './IUser';
+export * from './ICurrentUser';
+export * from './IUserInventoryRole';
+export * from './ITotp';
+export * from './ITotpStatus';
+export * from './UserService';
+export * from './UserInventoryRoleService';
+export * from './IResetPassword';
+export * from './PasswordStrength';
+//# sourceMappingURL=index.d.ts.map

package/lib/esm2015/src/user-group/IDevicePermissions.d.ts

@@ -0,0 +1,6 @@
+/** Description of IDevicePermissions interface */
+export interface IDevicePermissions {
+    /** Any keys */
+    [key: string]: string[];
+}
+//# sourceMappingURL=IDevicePermissions.d.ts.map

package/lib/esm2015/src/user-group/IUserGroup.d.ts

@@ -0,0 +1,31 @@
+import { ICustomProperties } from '../core';
+import { IRoleReferences } from '../user-role';
+import { IUserReferences } from '../user';
+import { IApplication } from '../application';
+import { IDevicePermissions } from './IDevicePermissions';
+/** Description of IUserGroup interface */
+export interface IUserGroup {
+    /** Uniquely identifies a User Group */
+    id?: number;
+    /** Descriptive Name of the Group */
+    name?: string;
+    /** Description of the Group */
+    description?: string;
+    /** Object contains all role references assigned to group */
+    roles?: IRoleReferences;
+    /** List of device permissions */
+    devicePermissions?: IDevicePermissions;
+    /** List of applications */
+    applications?: IApplication[];
+    /** List of custom properties */
+    customProperties?: ICustomProperties;
+    /** Link to this Resource */
+    self: string;
+    /** Object contains all user assigned to group */
+    users?: IUserReferences;
+    /**
+     * Other custom keys
+     */
+    [key: string]: any;
+}
+//# sourceMappingURL=IUserGroup.d.ts.map

package/lib/esm2015/src/user-group/UserGroupService.d.ts

@@ -0,0 +1,208 @@
+import { Service, IIdentified, IResult, ISource, IResultList } from '../core';
+import { IUserGroup } from './IUserGroup';
+import { IRoleReference } from '../user-role';
+import { IUserReference } from '../user';
+/**
+ * @description
+ * This service allows for managing user groups.
+ */
+export declare class UserGroupService extends Service<IUserGroup> {
+    protected baseUrl: string;
+    protected propertyName: string;
+    protected get listUrl(): string;
+    /**
+     * Gets the details of given user group.
+     *
+     * @param {string|number|IUserGroup} entityOrId Group's id or role object.
+     *
+     * @returns Returns promise object that is resolved with the IUserGroup wrapped by IResult.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const groupId: number = 1;
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.detail(roleId);
+     *   })();
+     * ```
+     */
+    detail(entityOrId: string | number | IUserGroup): Promise<IResult<IUserGroup>>;
+    /**
+     * Creates a new user group.
+     *
+     * @param {IUserGroup} entity User Group object.
+     *
+     * @returns {IResult<IUserGroup>} Returns promise object that is resolved with
+     * the details of newly created user group.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *  const userGroupObject: IUserGroup = {
+     *    name: "new user group"
+     *  };
+     *
+     *  (async () => {
+     *    const {data, res} = await userGroupService.create(userGroupObject);
+     *  })();
+     * ```
+     */
+    create(entity: Partial<IUserGroup>): Promise<IResult<IUserGroup>>;
+    /**
+     * Updates user group data.
+     *
+     * @param {Partial<IUserGroup>} entity User group is partially updatable.
+     *
+     * @returns {IResult<IUserGroup>} Returns promise object that is resolved with the saved user group object.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *  const partialUpdateObject: Partial<IUserGroup> = {
+     *     "id" : 1,
+     *     "self" : "[URL to this resource]",
+     *     "name" : "PlatformAdministrators",
+     *     ...
+     *   }
+     *
+     *  (async () => {
+     *    const {data, res} = await userGroupService.update(partialUpdateObject);
+     *  })();
+     * ```
+     */
+    update(entity: Partial<IUserGroup>): Promise<IResult<IUserGroup>>;
+    /**
+     * Gets the list of user groups filtered by parameters.
+     *
+     * @param {object} filter Object containing filters for querying User Groups.
+     *
+     * @returns Returns promise object that is resolved with the IUserGroup wrapped by IResultList.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *  const filter: object = {
+     *     severity: Severity.MAJOR,
+     *     pageSize: 100,
+     *     withTotalPages: true
+     *   };
+     *
+     *   (async () => {
+     *     const {data, res, paging} = await userGroupService.list(filter);
+     *   })();
+     * ```
+     */
+    list(filter?: object): Promise<IResultList<IUserGroup>>;
+    /**
+     * Removes user group.
+     *
+     * @param {number | IIdentified} entityOrId User group's id or user group object.
+     *
+     * @returns Returns promise object that is resolved with the IResult of null.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userGroupId: number = 1;
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.delete(userGroupId);
+     *   })();
+     * ```
+     * When group is removed, suitable audit records are created with type 'User'
+     * and activity 'User updated' with information that user has been removed from group.
+     *
+     * Please, note that the ADMINS and DEVICES groups can not be deleted.
+     */
+    delete(entityOrId: number | IIdentified): Promise<IResult<null>>;
+    /**
+     * Assign role to user group.
+     *
+     * @param {string | number | Partial<IUserGroup>} entityOrId User group's id or user group object.
+     * @param {string | Partial<ISource>} childEntityOrSelf Url to role resource or IRoleReference object.
+     *
+     * @returns Returns promise object that is resolved with the IRoleReference wrapped by IResult.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userGroupId: number = 1;
+     *    const roleResource: string = "[URL to the Role resource]";
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.addRoleToGroup(userGroupId, roleResource);
+     *   })();
+     * ```
+     * When role is assigned to user, suitable audit record is created with type 'User' and activity 'User updated'.
+     */
+    addRoleToGroup(entityOrId: string | number | Partial<IUserGroup>, childEntityOrSelf: string | Partial<ISource>): Promise<IResult<IRoleReference>>;
+    /**
+     * Unassign role from user
+     *
+     * @param {string | number | Partial<IUserGroup>} entityOrId User group's id or user group object.
+     * @param {string | Partial<ISource>} childEntityOrSelf Url to user resource or IRoleReference object.
+     *
+     * @returns Returns promise object that is resolved with the IResult of null.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userGroupId: number = 1;
+     *    const userResource: string = "[URL to the Role resource]";
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.removeRoleFromGroup(userGroupId, userResource);
+     *   })();
+     * ```
+     */
+    removeRoleFromGroup(entityOrId: string | number | Partial<IUserGroup>, childEntityOrSelf: string | Partial<ISource>): Promise<IResult<null>>;
+    /**
+     * Assign user to user group.
+     *
+     * @param {string | number | Partial<IUserGroup>} entityOrId User group's id or user group object.
+     * @param {string | Partial<ISource>} childEntityOrSelf Url to user resource or IUserReference object.
+     *
+     * @returns Returns promise object that is resolved with the IUserReference wrapped by IResult.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userGroupId: number = 1;
+     *    const userResource: string = "[URL to the User resource]";
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.addUserToGroup(userGroupId, userResource);
+     *   })();
+     * ```
+     * When user is added to group, suitable audit record is created with type 'User' and activity 'User updated'.
+     */
+    addUserToGroup(entityOrId: string | number | Partial<IUserGroup>, childEntityOrSelf: string | Partial<ISource>): Promise<IResult<IUserReference>>;
+    /**
+     * Remove user from a group
+     *
+     * @param {string | number | Partial<IUserGroup>} entityOrId User group's id or user group object.
+     * @param {string | Partial<ISource>} childEntityOrSelf Url to user resource or IUserReference object.
+     *
+     * @returns Returns promise object that is resolved with the IResult of null.
+     *
+     * **Example**
+     * ```typescript
+     *
+     *    const userGroupId: number = 1;
+     *    const userResource: string = "[URL to the User resource]";
+     *
+     *    (async () => {
+     *      const {data, res} = await userGroupService.removeUserFromGroup(userGroupId, userResource);
+     *   })();
+     * ```
+     * When user is removed from group, suitable audit record is created with type 'User' and activity 'User updated'.
+     */
+    removeUserFromGroup(entityOrId: string | number | Partial<IUserGroup>, childEntityOrSelf: string | Partial<ISource>): Promise<IResult<null>>;
+    protected getSelf(childReference: string | Partial<ISource>): string;
+    private getChildUrl;
+    private getChildReferenceAsBody;
+    private addChild;
+    private removeChild;
+}
+//# sourceMappingURL=UserGroupService.d.ts.map

package/lib/esm2015/src/user-group/index.d.ts

@@ -0,0 +1,4 @@
+export * from './UserGroupService';
+export * from './IDevicePermissions';
+export * from './IUserGroup';
+//# sourceMappingURL=index.d.ts.map

package/lib/esm2015/src/user-role/IRole.d.ts

@@ -0,0 +1,10 @@
+/** Description of IRole interface */
+export interface IRole {
+    /** Uniquely identifies a Role */
+    id?: string;
+    /** Descriptive Name of the Role */
+    name?: string;
+    /** Link to this Resource - optional property */
+    self?: string;
+}
+//# sourceMappingURL=IRole.d.ts.map

package/lib/esm2015/src/user-role/IRoleReference.d.ts

@@ -0,0 +1,16 @@
+import { IRole } from './IRole';
+/** Description of IRoleReferences interface */
+export interface IRoleReferences {
+    /** List of role references */
+    references: IRoleReference[];
+    /** Link to this Resource */
+    self: string;
+}
+/** Description of IRoleReference interface */
+export interface IRoleReference {
+    /** A role resource being referenced */
+    role: IRole;
+    /** Link to this Resource */
+    self: string;
+}
+//# sourceMappingURL=IRoleReference.d.ts.map