cumulocity-cypress/shared/c8yclient/user.d.ts

Cypress commands for Cumulocity IoT

import { Client, IApplication, IResult, IUser } from "@c8y/client";
/**
 * Options for delete operations.
 */
export type DeleteOptions = {
    /**
     * If true, ignores 404 Not Found errors when deleting.
     */
    ignoreNotFound?: boolean;
};
/**
 * Input types for deleteUser function.
 */
export type DeleteUserInput = string | IUser | string[] | IUser[] | ((filter: IUser) => boolean);
/**
 * Creates a user with the specified global roles and optionally assigns applications.
 *
 * This function:
 * 1. Creates the user in Cumulocity
 * 2. Assigns the user to the specified global role groups
 * 3. Optionally assigns applications to the user (by name or IApplication object)
 *
 * @param client - The Cumulocity client instance
 * @param user - The user object to create (must include userName, email, etc.)
 * @param globalRoles - Array of global role names to assign to the user
 * @param applications - Optional array of application names (strings) or IApplication objects to assign
 * @returns Promise resolving to the created user result
 *
 * @throws Error if user creation fails or if roles/applications cannot be assigned
 *
 * @example
 * const userResult = await createUser(
 *   client,
 *   { userName: 'john.doe', email: 'john@example.com', password: 'SecurePass123!' },
 *   ['business'],
 *   ['cockpit', 'devicemanagement']
 * );
 */
export declare function createUser(client: Client, user: IUser, globalRoles: string[], applications?: string[] | IApplication[]): Promise<IResult<IUser>>;
/**
 * Deletes one or more users from Cumulocity.
 *
 * Supports multiple input formats:
 * - Single username string
 * - Single IUser object (matched by id, userName, displayName, self, or email)
 * - Array of usernames or IUser objects
 * - Filter function to select users to delete
 *
 * When an IUser object is provided, the function matches it against existing users using
 * any available identifying properties (id, userName, displayName, self, email). This allows
 * for flexible matching even with partial user objects.
 *
 * @param client - The Cumulocity client instance
 * @param user - Username(s), IUser object(s), or filter function to identify users to delete
 * @param options - Optional configuration
 * @param options.ignoreNotFound - If true (default), ignores 404 errors when user is not found
 * @returns Promise that resolves when all users are deleted
 *
 * @throws Error if user is missing required properties or if deletion fails (unless ignoreNotFound is true)
 *
 * @example
 * // Delete single user by username
 * await deleteUser(client, 'john.doe');
 *
 * @example
 * // Delete multiple users
 * await deleteUser(client, ['user1', 'user2', 'user3']);
 *
 * @example
 * // Delete users matching a filter
 * await deleteUser(client, (user) => user.email?.includes('@example.com'));
 *
 * @example
 * // Delete user by partial IUser object
 * await deleteUser(client, { displayName: 'John Doe', email: 'john@example.com' });
 */
export declare function deleteUser(client: Client, user: DeleteUserInput, options?: DeleteOptions): Promise<void>;
/**
 * Assigns one or more global roles to a user.
 *
 * This function adds the user to the specified global role groups, granting them
 * the permissions associated with those roles.
 *
 * @param client - The Cumulocity client instance
 * @param username - Username string or IUser object (must have userName property)
 * @param roles - Array of global role names to assign to the user
 * @returns Promise that resolves when all roles are assigned
 *
 * @throws Error if username is missing, roles array is empty, or if role assignment fails
 *
 * @example
 * await assignUserRoles(client, 'john.doe', ['business', 'admins']);
 *
 * @example
 * const user = await client.user.detail('john.doe');
 * await assignUserRoles(client, user.data, ['devicemanagement']);
 */
export declare function assignUserRoles(client: Client, username: string | IUser, roles: string[]): Promise<void>;
/**
 * Removes all global roles currently assigned to a user.
 *
 * This function removes the user from all global role groups, effectively
 * revoking all role-based permissions.
 *
 * @param client - The Cumulocity client instance
 * @param username - Username string or IUser object (must have userName property)
 * @returns Promise that resolves when all roles are removed
 *
 * @throws Error if username is missing or if role removal fails
 *
 * @example
 * await clearUserRoles(client, 'john.doe');
 *
 * @example
 * const user = await client.user.detail('john.doe');
 * await clearUserRoles(client, user.data);
 */
export declare function clearUserRoles(client: Client, username: string | IUser): Promise<void>;
/**
 * Generates a secure random password with mixed case letters, numbers, and special characters.
 *
 * The password includes:
 * - Uppercase and lowercase letters (50% chance for each letter)
 * - Numbers (from timestamp)
 * - Special characters (!@#$%^&*())
 *
 * @param length - The desired length of the password (default: 28, minimum: 8)
 * @returns A randomly generated password string
 *
 * @example
 * const password = generatePassword();
 * // Returns something like: "2Kl9j8Gh!4m2@x7n#5p3q8r9"
 *
 * @example
 * const shortPassword = generatePassword(12);
 * // Returns a 12-character password
 */
export declare function generatePassword(length?: number): string;