captify 0.1.15

package/dist/auth/services/cognito/services/cognito-admin.service.js

@@ -0,0 +1,1083 @@
+import { AccountStatus } from "../../..";
+import { COGNITO_ERROR_MESSAGES } from "../constants";
+import { classifyCognitoError } from "../errors";
+import { maskUsername, maskUserPoolId } from "../utilities";
+import { addUserToGroupParamsSchema, approveUserParamsSchema, rejectUserParamsSchema, createGroupParamsSchema, createUserParamsSchema, deleteGroupParamsSchema, deleteUserParamsSchema, disableUserParamsSchema, enableUserParamsSchema, getGroupParamsSchema, getUserParamsSchema, listGroupsForUserParamsSchema, listGroupsParamsSchema, listPendingUsersParamsSchema, listUsersInGroupParamsSchema, listUsersParamsSchema, removeUserFromGroupParamsSchema, updateGroupParamsSchema, updateUserParamsSchema, userPoolIdOptionsSchema, userPoolIdSchema, } from "../schemas";
+import { BaseAwsService } from "../../../../services/shared/services";
+import { invariant } from "../../../../utils";
+import { AdminAddUserToGroupCommand, AdminCreateUserCommand, AdminDeleteUserCommand, AdminDisableUserCommand, AdminEnableUserCommand, AdminGetUserCommand, AdminListGroupsForUserCommand, AdminRemoveUserFromGroupCommand, AdminUpdateUserAttributesCommand, CognitoIdentityProviderClient, CreateGroupCommand, DeleteGroupCommand, GetGroupCommand, ListGroupsCommand, ListUsersCommand, ListUsersInGroupCommand, UpdateGroupCommand, } from "@aws-sdk/client-cognito-identity-provider";
+/**
+ * Generic Cognito Admin Service for User Pool management.
+ *
+ * Features:
+ * - Reuses a single client instance for all operations (performance optimized)
+ * - Uses standard AWS credentials (no Identity Pool required)
+ * - Generic design - works with any User Pool
+ * - Comprehensive error classification and retry logic
+ * - Input validation for all parameters
+ *
+ * @example Basic usage
+ * ```typescript
+ * const service = CognitoAdminService.create({
+ *   region: 'us-east-1',
+ *   userPoolId: 'us-east-1_ABC123',
+ *   clientId: 'your-client-id',
+ *   credentials: {
+ *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   },
+ * });
+ *
+ * const user = await service.createUser({
+ *   username: 'john.doe',
+ *   temporaryPassword: 'TempPass123!',
+ *   email: 'john@example.com',
+ * });
+ * ```
+ */
+export class CognitoAdminService extends BaseAwsService {
+    constructor(deps) {
+        super({ logger: deps.logger, serviceName: "CognitoAdmin" });
+        this.config = deps.config;
+        this.defaultUserPoolId = deps.config.userPoolId;
+        // Validate credentials are provided (should be validated by static create())
+        invariant(deps.config.credentials, "AWS credentials are required");
+        // Create admin client ONCE with credentials from config
+        this.adminClient = new CognitoIdentityProviderClient({
+            region: deps.config.region,
+            credentials: Object.assign({ accessKeyId: deps.config.credentials.accessKeyId, secretAccessKey: deps.config.credentials.secretAccessKey }, (deps.config.credentials.sessionToken && {
+                sessionToken: deps.config.credentials.sessionToken,
+            })),
+        });
+    }
+    /**
+     * Resolves the User Pool ID, using the provided value or falling back to default.
+     * @param userPoolId - Optional User Pool ID override
+     * @returns The resolved User Pool ID
+     * @throws Error if no User Pool ID is available or invalid
+     */
+    resolveUserPoolId(userPoolId) {
+        const resolved = userPoolId !== null && userPoolId !== void 0 ? userPoolId : this.defaultUserPoolId;
+        if (!(resolved === null || resolved === void 0 ? void 0 : resolved.trim())) {
+            throw new Error(COGNITO_ERROR_MESSAGES.USER_POOL_ID_REQUIRED);
+        }
+        return userPoolIdSchema.parse(resolved);
+    }
+    /**
+     * Get the appropriate Cognito client for the operation
+     * @param userCredentials - Optional user-specific credentials from Identity Pool
+     * @returns CognitoIdentityProviderClient configured for the operation
+     */
+    getClientForOperation(userCredentials) {
+        if (!userCredentials) {
+            return this.adminClient;
+        }
+        // Create a new client with user's temporary credentials
+        // This enables IAM-based access control per user
+        const credentials = this.getAwsCredentials(userCredentials);
+        return new CognitoIdentityProviderClient(Object.assign({ region: this.config.region }, (credentials ? { credentials } : {})));
+    }
+    /**
+     * Creates a new Cognito Admin Service instance.
+     *
+     * @param config - Configuration object for Cognito User Pool
+     * @param config.region - AWS region (e.g., 'us-east-1')
+     * @param config.userPoolId - Cognito User Pool ID (e.g., 'us-east-1_ABC123')
+     * @param config.clientId - Cognito App Client ID
+     * @param config.clientSecret - Optional Cognito App Client Secret
+     * @param config.credentials - AWS credentials for admin operations
+     * @param config.credentials.accessKeyId - AWS Access Key ID
+     * @param config.credentials.secretAccessKey - AWS Secret Access Key
+     * @param logger - Optional logger instance (defaults to LoggerFactory-based logger)
+     * @returns A new CognitoAdminService instance
+     * @throws Error if required configuration is missing
+     *
+     * @example
+     * ```typescript
+     * const service = CognitoAdminService.create({
+     *   region: 'us-east-1',
+     *   userPoolId: 'us-east-1_ABC123',
+     *   clientId: 'your-client-id',
+     *   credentials: {
+     *     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+     *     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+     *   },
+     * });
+     * ```
+     */
+    static create(config, logger) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        invariant((_a = config.region) === null || _a === void 0 ? void 0 : _a.trim(), "Cognito Region is required");
+        invariant((_b = config.userPoolId) === null || _b === void 0 ? void 0 : _b.trim(), "Cognito User Pool ID is required");
+        invariant((_c = config.clientId) === null || _c === void 0 ? void 0 : _c.trim(), "Cognito Client ID is required");
+        invariant((_e = (_d = config.credentials) === null || _d === void 0 ? void 0 : _d.accessKeyId) === null || _e === void 0 ? void 0 : _e.trim(), "AWS Access Key ID is required");
+        invariant((_g = (_f = config.credentials) === null || _f === void 0 ? void 0 : _f.secretAccessKey) === null || _g === void 0 ? void 0 : _g.trim(), "AWS Secret Access Key is required");
+        const clientConfig = {
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+            region: config.region,
+            userPoolId: config.userPoolId,
+            credentials: {
+                accessKeyId: config.credentials.accessKeyId,
+                secretAccessKey: config.credentials.secretAccessKey,
+            },
+        };
+        return new CognitoAdminService({ logger, config: clientConfig });
+    }
+    static loadEnvConfig() {
+        const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+        const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+        const sessionToken = process.env.AWS_SESSION_TOKEN;
+        return Object.assign({ region: process.env.AWS_REGION, userPoolId: process.env.COGNITO_USER_POOL_ID, clientId: process.env.COGNITO_CLIENT_ID, clientSecret: process.env.COGNITO_CLIENT_SECRET }, (accessKeyId && secretAccessKey
+            ? {
+                credentials: Object.assign({ accessKeyId,
+                    secretAccessKey }, (sessionToken && { sessionToken })),
+            }
+            : {}));
+    }
+    classifyError(err) {
+        return classifyCognitoError(err);
+    }
+    /**
+     * Creates a new user in the Cognito User Pool.
+     *
+     * @param params - User creation parameters
+     * @param params.username - The username for the new user
+     * @param params.password - Optional password for the user
+     * @param params.temporaryPassword - If true, the password will be temporary and user must change it on first login
+     * @param params.attributes - User attributes (email, phone_number, custom attributes, etc.)
+     * @param params.messageAction - Whether to send welcome email/SMS (SUPPRESS to skip)
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns The created user details
+     *
+     * @example
+     * ```typescript
+     * const user = await service.createUser({
+     *   username: 'john.doe',
+     *   password: 'TempPass123!',
+     *   temporaryPassword: true,
+     *   attributes: {
+     *     email: 'john.doe@example.com',
+     *     given_name: 'John',
+     *     family_name: 'Doe',
+     *   },
+     *   messageAction: 'SUPPRESS',
+     * });
+     * ```
+     */
+    async createUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = createUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin create user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const userAttributes = Object.entries(validated.attributes || {}).map(([name, value]) => ({
+                Name: name,
+                Value: value,
+            }));
+            const command = new AdminCreateUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                TemporaryPassword: validated.temporaryPassword && validated.password ? validated.password : undefined,
+                UserAttributes: userAttributes,
+                MessageAction: validated.messageAction,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            this.logger.info("Cognito admin create user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return this.mapUserToAdminUser(response.User);
+        });
+    }
+    /**
+     * Updates user attributes in the Cognito User Pool.
+     *
+     * @param params - User update parameters
+     * @param params.username - The username of the user to update
+     * @param params.attributes - User attributes to update
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async updateUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = updateUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin update user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const userAttributes = Object.entries(validated.attributes || {}).map(([name, value]) => ({
+                Name: name,
+                Value: value,
+            }));
+            const command = new AdminUpdateUserAttributesCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                UserAttributes: userAttributes,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin update user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Deletes a user from the Cognito User Pool.
+     *
+     * @param params - User deletion parameters
+     * @param params.username - The username of the user to delete
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async deleteUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = deleteUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin delete user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminDeleteUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin delete user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Lists users in the Cognito User Pool with optional filtering and pagination.
+     *
+     * @param params - List users parameters
+     * @param params.limit - Maximum number of users to return (1-60)
+     * @param params.paginationToken - Token for pagination
+     * @param params.filter - Filter expression (e.g., 'email = "john@example.com"')
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing users array and optional pagination token
+     */
+    async listUsers(params = {}, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = listUsersParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list users attempt", {
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new ListUsersCommand({
+                UserPoolId: userPoolId,
+                Limit: validated.limit,
+                PaginationToken: validated.paginationToken,
+                Filter: validated.filter,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            const users = (response.Users || []).map((user) => this.mapUserToAdminUser(user));
+            this.logger.info("Cognito admin list users successful", {
+                count: users.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                users,
+                paginationToken: response.PaginationToken,
+            };
+        });
+    }
+    /**
+     * Gets a user's details from the Cognito User Pool.
+     *
+     * @param username - The username of the user to retrieve
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns The user details
+     */
+    async getUser(username, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = getUserParamsSchema.parse({ username });
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin get user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminGetUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            this.logger.info("Cognito admin get user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            // AdminGetUserCommandOutput uses UserAttributes, not Attributes like UserType
+            // Convert to the format expected by mapUserToAdminUser
+            return this.mapUserToAdminUser(Object.assign(Object.assign({}, response), { Attributes: response.UserAttributes }));
+        });
+    }
+    /**
+     * Creates a new group in the Cognito User Pool.
+     *
+     * @param params - Group creation parameters
+     * @param params.groupName - The name of the group
+     * @param params.description - Optional description of the group
+     * @param params.precedence - Optional precedence value for the group
+     * @param params.roleArn - Optional IAM role ARN for the group
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns The created group details
+     */
+    async createGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = createGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin create group attempt", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new CreateGroupCommand({
+                GroupName: validated.groupName,
+                Description: validated.description,
+                Precedence: validated.precedence,
+                RoleArn: validated.roleArn,
+                UserPoolId: userPoolId,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            this.logger.info("Cognito admin create group successful", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            // Validate response
+            if (!response.Group || !response.Group.GroupName) {
+                throw new Error("Invalid response from Cognito: missing group data");
+            }
+            return {
+                groupName: response.Group.GroupName,
+                description: response.Group.Description,
+                precedence: response.Group.Precedence,
+                roleArn: response.Group.RoleArn,
+                creationDate: response.Group.CreationDate,
+                lastModifiedDate: response.Group.LastModifiedDate,
+            };
+        });
+    }
+    /**
+     * Adds a user to a group in the Cognito User Pool.
+     *
+     * @param params - Parameters for adding user to group
+     * @param params.username - The username of the user
+     * @param params.groupName - The name of the group
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async addUserToGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = addUserToGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin add user to group attempt", {
+                username: maskUsername(validated.username),
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminAddUserToGroupCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                GroupName: validated.groupName,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin add user to group successful", {
+                username: maskUsername(validated.username),
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Removes a user from a group in the Cognito User Pool.
+     *
+     * @param params - Parameters for removing user from group
+     * @param params.username - The username of the user
+     * @param params.groupName - The name of the group
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async removeUserFromGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = removeUserFromGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin remove user from group attempt", {
+                username: maskUsername(validated.username),
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminRemoveUserFromGroupCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                GroupName: validated.groupName,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin remove user from group successful", {
+                username: maskUsername(validated.username),
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Lists all groups that a user belongs to in the Cognito User Pool.
+     *
+     * @param params - Parameters for listing user's groups
+     * @param params.username - The username of the user
+     * @param params.limit - Maximum number of groups to return
+     * @param params.nextToken - Token for pagination
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing groups array and optional next token
+     */
+    async listGroupsForUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = listGroupsForUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list groups for user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminListGroupsForUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                Limit: validated.limit,
+                NextToken: validated.nextToken,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            const groups = (response.Groups || [])
+                .filter((group) => group.GroupName) // Filter out groups without a name
+                .map((group) => ({
+                groupName: group.GroupName, // TypeScript now knows this is defined
+                description: group.Description,
+                precedence: group.Precedence,
+                roleArn: group.RoleArn,
+                creationDate: group.CreationDate,
+                lastModifiedDate: group.LastModifiedDate,
+            }));
+            this.logger.info("Cognito admin list groups for user successful", {
+                username: maskUsername(validated.username),
+                groupCount: groups.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                groups,
+                nextToken: response.NextToken,
+            };
+        });
+    }
+    /**
+     * Enables a user in the Cognito User Pool (allows them to sign in).
+     *
+     * @param username - The username of the user to enable
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async enableUser(username, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = enableUserParamsSchema.parse({ username });
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin enable user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminEnableUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin enable user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Disables a user in the Cognito User Pool (prevents them from signing in).
+     *
+     * @param username - The username of the user to disable
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     */
+    async disableUser(username, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = disableUserParamsSchema.parse({ username });
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin disable user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminDisableUserCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin disable user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Lists all groups in the Cognito User Pool with optional pagination.
+     *
+     * @param params - Parameters for listing groups
+     * @param params.limit - Maximum number of groups to return (1-60)
+     * @param params.nextToken - Token for pagination
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing groups array and optional next token
+     *
+     * @example
+     * ```typescript
+     * const result = await service.listGroups({ limit: 20 });
+     * console.log(`Found ${result.groups.length} groups`);
+     * if (result.nextToken) {
+     *   const nextPage = await service.listGroups({ limit: 20, nextToken: result.nextToken });
+     * }
+     * ```
+     */
+    async listGroups(params = {}, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = listGroupsParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list groups attempt", {
+                userPoolId: maskUserPoolId(userPoolId),
+                limit: validated.limit,
+            });
+            const command = new ListGroupsCommand({
+                UserPoolId: userPoolId,
+                Limit: validated.limit,
+                NextToken: validated.nextToken,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            const groups = (response.Groups || [])
+                .filter((group) => group.GroupName)
+                .map((group) => ({
+                groupName: group.GroupName,
+                description: group.Description,
+                precedence: group.Precedence,
+                roleArn: group.RoleArn,
+                creationDate: group.CreationDate,
+                lastModifiedDate: group.LastModifiedDate,
+            }));
+            this.logger.info("Cognito admin list groups successful", {
+                groupCount: groups.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                groups,
+                nextToken: response.NextToken,
+            };
+        });
+    }
+    /**
+     * Lists all groups in the Cognito User Pool by following pagination tokens.
+     * This method fetches all groups across multiple pages automatically.
+     *
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing all groups and total count
+     *
+     * @example
+     * ```typescript
+     * const result = await service.listAllGroups();
+     * console.log(`Found ${result.totalCount} groups`);
+     * ```
+     */
+    async listAllGroups(options) {
+        return this.executeWithRetry(async () => {
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list all groups attempt", {
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const allGroups = [];
+            let nextToken = undefined;
+            // Fetch all pages
+            do {
+                const result = await this.listGroups({
+                    limit: 60, // Use maximum allowed limit for efficiency
+                    nextToken,
+                }, options);
+                allGroups.push(...result.groups);
+                nextToken = result.nextToken;
+            } while (nextToken);
+            this.logger.info("Cognito admin list all groups successful", {
+                totalCount: allGroups.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                groups: allGroups,
+                totalCount: allGroups.length,
+            };
+        });
+    }
+    /**
+     * Gets details of a specific group in the Cognito User Pool.
+     *
+     * @param params - Parameters for getting group details
+     * @param params.groupName - The name of the group to retrieve
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns The group details
+     *
+     * @example
+     * ```typescript
+     * const group = await service.getGroup({ groupName: 'Admins' });
+     * console.log(`Group precedence: ${group.precedence}`);
+     * ```
+     */
+    async getGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = getGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin get group attempt", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new GetGroupCommand({
+                GroupName: validated.groupName,
+                UserPoolId: userPoolId,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            // Validate response
+            if (!response.Group || !response.Group.GroupName) {
+                throw new Error("Invalid response from Cognito: missing group data");
+            }
+            this.logger.info("Cognito admin get group successful", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                groupName: response.Group.GroupName,
+                description: response.Group.Description,
+                precedence: response.Group.Precedence,
+                roleArn: response.Group.RoleArn,
+                creationDate: response.Group.CreationDate,
+                lastModifiedDate: response.Group.LastModifiedDate,
+            };
+        });
+    }
+    /**
+     * Updates an existing group in the Cognito User Pool.
+     *
+     * @param params - Parameters for updating the group
+     * @param params.groupName - The name of the group to update
+     * @param params.description - Optional new description for the group
+     * @param params.precedence - Optional new precedence value
+     * @param params.roleArn - Optional new IAM role ARN
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns The updated group details
+     *
+     * @example
+     * ```typescript
+     * const updatedGroup = await service.updateGroup({
+     *   groupName: 'Admins',
+     *   description: 'Updated admin group description',
+     *   precedence: 1,
+     * });
+     * ```
+     */
+    async updateGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = updateGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin update group attempt", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new UpdateGroupCommand({
+                GroupName: validated.groupName,
+                UserPoolId: userPoolId,
+                Description: validated.description,
+                Precedence: validated.precedence,
+                RoleArn: validated.roleArn,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            // Validate response
+            if (!response.Group || !response.Group.GroupName) {
+                throw new Error("Invalid response from Cognito: missing group data");
+            }
+            this.logger.info("Cognito admin update group successful", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                groupName: response.Group.GroupName,
+                description: response.Group.Description,
+                precedence: response.Group.Precedence,
+                roleArn: response.Group.RoleArn,
+                creationDate: response.Group.CreationDate,
+                lastModifiedDate: response.Group.LastModifiedDate,
+            };
+        });
+    }
+    /**
+     * Deletes a group from the Cognito User Pool.
+     * WARNING: This operation is permanent and cannot be undone.
+     *
+     * @param params - Parameters for deleting the group
+     * @param params.groupName - The name of the group to delete
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     *
+     * @example
+     * ```typescript
+     * await service.deleteGroup({ groupName: 'OldGroup' });
+     * console.log('Group deleted successfully');
+     * ```
+     */
+    async deleteGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = deleteGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin delete group attempt", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new DeleteGroupCommand({
+                GroupName: validated.groupName,
+                UserPoolId: userPoolId,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin delete group successful", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Lists all users in a specific group with optional pagination.
+     *
+     * @param params - Parameters for listing users in the group
+     * @param params.groupName - The name of the group
+     * @param params.limit - Maximum number of users to return (1-60)
+     * @param params.nextToken - Token for pagination
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing users array and optional next token
+     *
+     * @example
+     * ```typescript
+     * const result = await service.listUsersInGroup({
+     *   groupName: 'Admins',
+     *   limit: 20
+     * });
+     * console.log(`Found ${result.users.length} users in group`);
+     * ```
+     */
+    async listUsersInGroup(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = listUsersInGroupParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list users in group attempt", {
+                groupName: validated.groupName,
+                userPoolId: maskUserPoolId(userPoolId),
+                limit: validated.limit,
+            });
+            const command = new ListUsersInGroupCommand({
+                UserPoolId: userPoolId,
+                GroupName: validated.groupName,
+                Limit: validated.limit,
+                NextToken: validated.nextToken,
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            const users = (response.Users || []).map((user) => this.mapUserToAdminUser(user));
+            this.logger.info("Cognito admin list users in group successful", {
+                groupName: validated.groupName,
+                userCount: users.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                users,
+                nextToken: response.NextToken,
+            };
+        });
+    }
+    /**
+     * Lists all users in the Cognito User Pool by following pagination tokens.
+     * This method fetches all users across multiple pages automatically.
+     *
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing all users and total count
+     *
+     * @example
+     * ```typescript
+     * const result = await service.listAllUsers();
+     * console.log(`Found ${result.totalCount} users`);
+     * ```
+     */
+    async listAllUsers(options) {
+        return this.executeWithRetry(async () => {
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list all users attempt", {
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const allUsers = [];
+            let paginationToken = undefined;
+            // Fetch all pages
+            do {
+                const result = await this.listUsers({
+                    limit: 60, // Use maximum allowed limit for efficiency
+                    paginationToken,
+                }, options);
+                allUsers.push(...result.users);
+                paginationToken = result.paginationToken;
+            } while (paginationToken);
+            this.logger.info("Cognito admin list all users successful", {
+                totalCount: allUsers.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                users: allUsers,
+                totalCount: allUsers.length,
+            };
+        });
+    }
+    /**
+     * Lists pending users in the Cognito User Pool.
+     * Pending users are those where custom:account_status attribute is strictly "PENDING".
+     *
+     * @param params - Parameters for listing pending users
+     * @param params.limit - Maximum number of users to return (1-60)
+     * @param params.paginationToken - Token for pagination
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     * @returns Object containing pending users array and optional pagination token
+     *
+     * @example
+     * ```typescript
+     * const result = await service.listPendingUsers({ limit: 20 });
+     * console.log(`Found ${result.users.length} pending users`);
+     * ```
+     */
+    async listPendingUsers(params = {}, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = listPendingUsersParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin list pending users attempt", {
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            // Fetch confirmed users and filter client-side by account_status
+            // Note: Cognito filter does not support custom attribute filtering
+            const command = new ListUsersCommand({
+                UserPoolId: userPoolId,
+                Limit: validated.limit,
+                PaginationToken: validated.paginationToken,
+                Filter: 'cognito:user_status = "CONFIRMED"',
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            const response = await client.send(command);
+            // Map all users
+            const allUsers = (response.Users || []).map((user) => this.mapUserToAdminUser(user));
+            // Filter for pending users (account_status is strictly "PENDING")
+            // Users with no status or "UNVERIFIED" are in the unverified list
+            const pendingUsers = allUsers.filter((user) => {
+                var _a;
+                const status = (_a = user.attributes) === null || _a === void 0 ? void 0 : _a["custom:account_status"];
+                return status === AccountStatus.PENDING;
+            });
+            this.logger.info("Cognito admin list pending users successful", {
+                totalCount: allUsers.length,
+                pendingCount: pendingUsers.length,
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            return {
+                users: pendingUsers,
+                paginationToken: response.PaginationToken,
+            };
+        });
+    }
+    /**
+     * Approves a pending user by setting their custom:account_status attribute to "VERIFIED".
+     *
+     * @param params - Parameters for approving a user
+     * @param params.username - The username of the user to approve
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     *
+     * @example
+     * ```typescript
+     * await service.approveUser({ username: 'john.doe' });
+     * console.log('User approved successfully');
+     * ```
+     */
+    async approveUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = approveUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin approve user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminUpdateUserAttributesCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                UserAttributes: [
+                    {
+                        Name: "custom:account_status",
+                        Value: AccountStatus.VERIFIED,
+                    },
+                ],
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin approve user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    /**
+     * Rejects a pending user by setting their custom:account_status attribute to "UNVERIFIED".
+     *
+     * @param params - Parameters for rejecting a user
+     * @param params.username - The username of the user to reject
+     * @param options - Optional operation configuration
+     * @param options.userPoolId - Optional User Pool ID override (uses default if not provided)
+     *
+     * @example
+     * ```typescript
+     * await service.rejectUser({ username: 'john.doe' });
+     * console.log('User rejected successfully');
+     * ```
+     */
+    async rejectUser(params, options) {
+        return this.executeWithRetry(async () => {
+            // Validate inputs with Zod
+            const validated = rejectUserParamsSchema.parse(params);
+            const validatedOptions = userPoolIdOptionsSchema.parse(options);
+            const userPoolId = this.resolveUserPoolId(validatedOptions === null || validatedOptions === void 0 ? void 0 : validatedOptions.userPoolId);
+            this.logger.info("Cognito admin reject user attempt", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+            const command = new AdminUpdateUserAttributesCommand({
+                UserPoolId: userPoolId,
+                Username: validated.username,
+                UserAttributes: [
+                    {
+                        Name: "custom:account_status",
+                        Value: AccountStatus.UNVERIFIED,
+                    },
+                ],
+            });
+            const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
+            await client.send(command);
+            this.logger.info("Cognito admin reject user successful", {
+                username: maskUsername(validated.username),
+                userPoolId: maskUserPoolId(userPoolId),
+            });
+        });
+    }
+    onMetric(name, dims) {
+        this.logger.debug(`Cognito Admin Metric: ${name}`, dims);
+    }
+    mapUserToAdminUser(user) {
+        var _a, _b;
+        // Validate required fields
+        if (!user.Username) {
+            throw new Error("User object missing required field: Username");
+        }
+        if (!user.UserStatus) {
+            throw new Error("User object missing required field: UserStatus");
+        }
+        const attributes = (_a = user.Attributes) === null || _a === void 0 ? void 0 : _a.reduce((acc, attr) => {
+            if (attr.Name && attr.Value) {
+                acc[attr.Name] = attr.Value;
+            }
+            return acc;
+        }, {});
+        return {
+            username: user.Username,
+            email: attributes === null || attributes === void 0 ? void 0 : attributes.email,
+            phoneNumber: attributes === null || attributes === void 0 ? void 0 : attributes.phone_number,
+            enabled: (_b = user.Enabled) !== null && _b !== void 0 ? _b : false,
+            userStatus: user.UserStatus,
+            attributes,
+            createdAt: user.UserCreateDate,
+            updatedAt: user.UserLastModifiedDate,
+            lastModifiedDate: user.UserLastModifiedDate,
+            lastLoginDate: user.UserLastModifiedDate,
+        };
+    }
+}
+// Singleton admin service instance
+let adminServiceInstance = null;
+/**
+ * Get or create a singleton instance of CognitoAdminService
+ * Loads configuration from environment variables
+ * @returns CognitoAdminService singleton instance
+ */
+export function getCognitoAdminService() {
+    if (!adminServiceInstance) {
+        const config = CognitoAdminService.loadEnvConfig();
+        adminServiceInstance = CognitoAdminService.create(config);
+    }
+    return adminServiceInstance;
+}
+//# sourceMappingURL=cognito-admin.service.js.map