Data Types & Models

/**
 * Complete user object with attributes and metadata
 * Represents a user in the user pool with all associated information
 */
interface UserType {
  /** The username of the user */
  Username?: string;
  
  /** Array of user attributes (email, name, custom attributes, etc.) */
  Attributes?: AttributeType[];
  
  /** Date when the user was created */
  UserCreateDate?: Date;
  
  /** Date when the user was last modified */
  UserLastModifiedDate?: Date;
  
  /** Whether the user account is enabled */
  Enabled?: boolean;
  
  /** Current status of the user account */
  UserStatus?: UserStatusType;
  
  /** Configured MFA options for the user */
  MFAOptions?: MFAOptionType[];
}

/**
 * User attribute name-value pair
 * Represents a single attribute of a user (email, name, phone, custom attributes)
 */
interface AttributeType {
  /** The name of the attribute */
  Name: string;
  
  /** The value of the attribute */
  Value?: string;
}

/**
 * User account status enumeration
 * Indicates the current state of a user account
 */
type UserStatusType = 
  | "UNCONFIRMED"        // User registered but not confirmed
  | "CONFIRMED"          // User confirmed and active
  | "ARCHIVED"           // User account archived (soft deleted)
  | "COMPROMISED"        // User account flagged as compromised
  | "UNKNOWN"            // Status unknown
  | "RESET_REQUIRED"     // User must reset password
  | "FORCE_CHANGE_PASSWORD" // User must change temporary password
  | "EXTERNAL_PROVIDER"; // User authenticated via external provider

/**
 * MFA option configuration
 * Specifies MFA method settings for a user
 */
interface MFAOptionType {
  /** The MFA delivery medium */
  DeliveryMedium?: DeliveryMediumType;
  
  /** The attribute name used for MFA delivery */
  AttributeName?: string;
}

type DeliveryMediumType = "SMS" | "EMAIL";

/**
 * Authentication result containing tokens and metadata
 * Returned when authentication is successful
 */
interface AuthenticationResultType {
  /** Access token for API authorization */
  AccessToken?: string;
  
  /** Token expiration time in seconds */
  ExpiresIn?: number;
  
  /** Token type (typically "Bearer") */
  TokenType?: string;
  
  /** Refresh token for obtaining new access tokens */
  RefreshToken?: string;
  
  /** ID token containing user identity claims */
  IdToken?: string;
  
  /** New device metadata if device tracking is enabled */
  NewDeviceMetadata?: NewDeviceMetadataType;
}

/**
 * Authentication flow enumeration
 * Specifies the method used for user authentication
 */
type AuthFlowType = 
  | "USER_SRP_AUTH"           // Secure Remote Password (recommended)
  | "REFRESH_TOKEN_AUTH"      // Refresh token flow
  | "REFRESH_TOKEN"           // Legacy refresh token flow
  | "CUSTOM_AUTH"             // Custom authentication challenge
  | "ADMIN_NO_SRP_AUTH"       // Admin auth without SRP
  | "USER_PASSWORD_AUTH"      // Direct password authentication
  | "ADMIN_USER_PASSWORD_AUTH" // Admin password authentication
  | "USER_AUTH";              // Adaptive authentication

/**
 * Authentication challenge type enumeration
 * Indicates additional steps required for authentication
 */
type ChallengeNameType =
  | "SMS_MFA"                    // SMS-based MFA challenge
  | "SOFTWARE_TOKEN_MFA"         // TOTP-based MFA challenge
  | "SELECT_MFA_TYPE"            // MFA method selection
  | "MFA_SETUP"                  // MFA device setup
  | "PASSWORD_VERIFIER"          // SRP password verification
  | "CUSTOM_CHALLENGE"           // Custom Lambda challenge
  | "DEVICE_SRP_AUTH"            // Device-based SRP auth
  | "DEVICE_PASSWORD_VERIFIER"   // Device password verification
  | "ADMIN_NO_SRP_AUTH"          // Admin auth without SRP
  | "NEW_PASSWORD_REQUIRED"      // Temporary password change
  | "SMS_OTP"                    // SMS one-time password
  | "EMAIL_OTP";                 // Email one-time password

/**
 * Code delivery details for verification codes
 * Information about how verification codes are sent
 */
interface CodeDeliveryDetailsType {
  /** Destination for code delivery (masked email/phone) */
  Destination?: string;
  
  /** Delivery medium used */
  DeliveryMedium?: DeliveryMediumType;
  
  /** Attribute name used for delivery */
  AttributeName?: string;
}

/**
 * New device metadata for device tracking
 * Information about newly registered devices
 */
interface NewDeviceMetadataType {
  /** Unique device key */
  DeviceKey?: string;
  
  /** Device group key */
  DeviceGroupKey?: string;
}

/**
 * Complete user pool configuration object
 * Contains all settings and policies for a user pool
 */
interface UserPoolType {
  /** User pool ID */
  Id?: string;
  
  /** User pool name */
  Name?: string;
  
  /** Password and security policies */
  Policies?: UserPoolPolicyType;
  
  /** Lambda trigger configurations */
  LambdaConfig?: LambdaConfigType;
  
  /** User pool status */
  Status?: StatusType;
  
  /** Date when user pool was last modified */
  LastModifiedDate?: Date;
  
  /** Date when user pool was created */
  CreationDate?: Date;
  
  /** Custom attributes schema */
  SchemaAttributes?: SchemaAttributeType[];
  
  /** Auto-verified attributes */
  AutoVerifiedAttributes?: VerifiedAttributeType[];
  
  /** Attributes that can be used as aliases */
  AliasAttributes?: AliasAttributeType[];
  
  /** Attributes that can be used as username */
  UsernameAttributes?: UsernameAttributeType[];
  
  /** SMS configuration */
  SmsConfiguration?: SmsConfigurationType;
  
  /** Email configuration */
  EmailConfiguration?: EmailConfigurationType;
  
  /** User pool tags */
  UserPoolTags?: Record<string, string>;
  
  /** SMS configuration failure reason */
  SmsConfigurationFailure?: string;
  
  /** Email configuration failure reason */
  EmailConfigurationFailure?: string;
  
  /** User pool domain */
  Domain?: string;
  
  /** Custom domain configuration */
  CustomDomain?: string;
  
  /** Admin user creation configuration */
  AdminCreateUserConfig?: AdminCreateUserConfigType;
  
  /** User pool add-ons (advanced security) */
  UserPoolAddOns?: UserPoolAddOnsType;
  
  /** Username configuration */
  UsernameConfiguration?: UsernameConfigurationType;
  
  /** ARN of the user pool */
  Arn?: string;
  
  /** Account recovery settings */
  AccountRecoverySetting?: AccountRecoverySettingType;
}

/**
 * User pool policies configuration
 * Defines password and other security policies
 */
interface UserPoolPolicyType {
  /** Password policy configuration */
  PasswordPolicy?: PasswordPolicyType;
}

/**
 * Password policy configuration
 * Defines password complexity requirements
 */
interface PasswordPolicyType {
  /** Minimum password length */
  MinimumLength?: number;
  
  /** Require uppercase letters */
  RequireUppercase?: boolean;
  
  /** Require lowercase letters */
  RequireLowercase?: boolean;
  
  /** Require numbers */
  RequireNumbers?: boolean;
  
  /** Require symbols */
  RequireSymbols?: boolean;
  
  /** Temporary passwords validity period */
  TemporaryPasswordValidityDays?: number;
}

/**
 * MFA configuration enumeration for user pools
 * Specifies pool-wide MFA requirements
 */
type UserPoolMfaType = 
  | "OFF"      // MFA disabled
  | "ON"       // MFA required for all users
  | "OPTIONAL";// MFA optional (user choice)

/**
 * Verified attribute types
 * Attributes that can be auto-verified
 */
type VerifiedAttributeType = "phone_number" | "email";

/**
 * Alias attribute types
 * Attributes that can be used as username aliases
 */
type AliasAttributeType = "phone_number" | "email" | "preferred_username";

/**
 * Username attribute types
 * Attributes that can be used as username
 */
type UsernameAttributeType = "phone_number" | "email";

/**
 * User pool client configuration
 * Defines how applications can interact with the user pool
 */
interface UserPoolClientType {
  /** The user pool ID */
  UserPoolId?: string;
  
  /** The client name */
  ClientName?: string;
  
  /** The client ID */
  ClientId?: string;
  
  /** The client secret (for confidential clients) */
  ClientSecret?: string;
  
  /** Date when client was last modified */
  LastModifiedDate?: Date;
  
  /** Date when client was created */
  CreationDate?: Date;
  
  /** Refresh token validity period in days */
  RefreshTokenValidity?: number;
  
  /** Access token validity period in minutes */
  AccessTokenValidity?: number;
  
  /** ID token validity period in minutes */
  IdTokenValidity?: number;
  
  /** Token validity time units */
  TokenValidityUnits?: TokenValidityUnitsType;
  
  /** Allowed authentication flows */
  ExplicitAuthFlows?: ExplicitAuthFlowsType[];
  
  /** Supported identity providers */
  SupportedIdentityProviders?: string[];
  
  /** OAuth callback URLs */
  CallbackURLs?: string[];
  
  /** OAuth logout URLs */
  LogoutURLs?: string[];
  
  /** Default redirect URI */
  DefaultRedirectURI?: string;
  
  /** Allowed OAuth flows */
  AllowedOAuthFlows?: OAuthFlowType[];
  
  /** Allowed OAuth scopes */
  AllowedOAuthScopes?: string[];
  
  /** Whether OAuth flows are enabled */
  AllowedOAuthFlowsUserPoolClient?: boolean;
  
  /** Analytics configuration */
  AnalyticsConfiguration?: AnalyticsConfigurationType;
  
  /** Prevent user existence errors */
  PreventUserExistenceErrors?: PreventUserExistenceErrorTypes;
  
  /** Enable token revocation */
  EnableTokenRevocation?: boolean;
  
  /** Enable propagation of additional user context data */
  EnablePropagateAdditionalUserContextData?: boolean;
  
  /** Authentication session validity */
  AuthSessionValidity?: number;
}

/**
 * Token validity units configuration
 * Specifies time units for different token types
 */
interface TokenValidityUnitsType {
  /** Access token validity unit */
  AccessToken?: TimeUnitsType;
  
  /** ID token validity unit */
  IdToken?: TimeUnitsType;
  
  /** Refresh token validity unit */
  RefreshToken?: TimeUnitsType;
}

type TimeUnitsType = "seconds" | "minutes" | "hours" | "days";

/**
 * Explicit authentication flows enumeration
 * Authentication methods allowed for the client
 */
type ExplicitAuthFlowsType = 
  | "ADMIN_NO_SRP_AUTH"
  | "CUSTOM_AUTH_FLOW_ONLY" 
  | "USER_PASSWORD_AUTH"
  | "ALLOW_ADMIN_USER_PASSWORD_AUTH"
  | "ALLOW_CUSTOM_AUTH"
  | "ALLOW_USER_PASSWORD_AUTH"
  | "ALLOW_USER_SRP_AUTH"
  | "ALLOW_REFRESH_TOKEN_AUTH";

/**
 * OAuth flow types
 * Supported OAuth 2.0 flows
 */
type OAuthFlowType = "code" | "implicit" | "client_credentials";

/**
 * User existence error prevention
 * Strategy for handling user existence disclosure
 */
type PreventUserExistenceErrorTypes = "LEGACY" | "ENABLED";

/**
 * Device information and metadata
 * Represents a tracked device for a user
 */
interface DeviceType {
  /** Unique device key */
  DeviceKey?: string;
  
  /** Device attributes (name, type, etc.) */
  DeviceAttributes?: AttributeType[];
  
  /** Date when device was created */
  DeviceCreateDate?: Date;
  
  /** Date when device was last modified */
  DeviceLastModifiedDate?: Date;
  
  /** Date when device was last authenticated */
  DeviceLastAuthenticatedDate?: Date;
}

/**
 * Device remembered status
 * Whether the device is remembered for future logins
 */
type DeviceRememberedStatusType = "remembered" | "not_remembered";

/**
 * Device secret verifier configuration
 * Configuration for device secret verification
 */
interface DeviceSecretVerifierConfigType {
  /** Password verifier */
  PasswordVerifier?: string;
  
  /** Salt for password verification */
  Salt?: string;
}

/**
 * Device configuration for user pool
 * Pool-level device tracking settings
 */
interface DeviceConfigurationType {
  /** Whether device tracking is enabled */
  ChallengeRequiredOnNewDevice?: boolean;
  
  /** Whether devices can be remembered */
  DeviceOnlyRememberedOnUserPrompt?: boolean;
}

/**
 * User group configuration
 * Represents a group within a user pool
 */
interface GroupType {
  /** Group name */
  GroupName?: string;
  
  /** The user pool ID */
  UserPoolId?: string;
  
  /** Group description */
  Description?: string;
  
  /** IAM role ARN for group members */
  RoleArn?: string;
  
  /** Group precedence (lower number = higher precedence) */
  Precedence?: number;
  
  /** Date when group was last modified */
  LastModifiedDate?: Date;
  
  /** Date when group was created */
  CreationDate?: Date;
}

/**
 * Identity provider configuration
 * External identity provider settings
 */
interface IdentityProviderType {
  /** The user pool ID */
  UserPoolId?: string;
  
  /** Identity provider name */
  ProviderName?: string;
  
  /** Type of identity provider */
  ProviderType?: IdentityProviderTypeType;
  
  /** Provider-specific configuration */
  ProviderDetails?: Record<string, string>;
  
  /** Attribute mapping configuration */
  AttributeMapping?: Record<string, string>;
  
  /** IdP identifiers */
  IdpIdentifiers?: string[];
  
  /** Date when provider was last modified */
  LastModifiedDate?: Date;
  
  /** Date when provider was created */
  CreationDate?: Date;
}

/**
 * Identity provider type enumeration
 * Supported external identity provider types
 */
type IdentityProviderTypeType = 
  | "SAML"           // SAML 2.0 identity provider
  | "Facebook"       // Facebook Login
  | "Google"         // Google Sign-In  
  | "LoginWithAmazon" // Login with Amazon
  | "SignInWithApple" // Sign in with Apple
  | "OIDC";          // OpenID Connect provider

/**
 * Base exception class for all Cognito Identity Provider service errors
 */
class CognitoIdentityProviderServiceException extends Error {
  /** Error name identifier */
  readonly name: string;
  
  /** HTTP status code */
  readonly $fault: "client" | "server";
  
  /** Service metadata */
  readonly $metadata: ResponseMetadata;
  
  /** Request ID for tracking */
  readonly $requestId?: string;
}

/**
 * Authentication/authorization failure
 */
class NotAuthorizedException extends CognitoIdentityProviderServiceException {
  readonly name = "NotAuthorizedException";
  readonly $fault = "client";
}

/**
 * User does not exist
 */
class UserNotFoundException extends CognitoIdentityProviderServiceException {
  readonly name = "UserNotFoundException";
  readonly $fault = "client";
}

/**
 * User registration not confirmed
 */
class UserNotConfirmedException extends CognitoIdentityProviderServiceException {
  readonly name = "UserNotConfirmedException"; 
  readonly $fault = "client";
}

/**
 * Password reset required
 */
class PasswordResetRequiredException extends CognitoIdentityProviderServiceException {
  readonly name = "PasswordResetRequiredException";
  readonly $fault = "client";
}

/**
 * Invalid request parameter
 */
class InvalidParameterException extends CognitoIdentityProviderServiceException {
  readonly name = "InvalidParameterException";
  readonly $fault = "client";
}

/**
 * Resource not found
 */
class ResourceNotFoundException extends CognitoIdentityProviderServiceException {
  readonly name = "ResourceNotFoundException";
  readonly $fault = "client";
}

/**
 * Too many requests (rate limiting)
 */
class TooManyRequestsException extends CognitoIdentityProviderServiceException {
  readonly name = "TooManyRequestsException";
  readonly $fault = "client";
}

/**
 * Service limits exceeded
 */
class LimitExceededException extends CognitoIdentityProviderServiceException {
  readonly name = "LimitExceededException";
  readonly $fault = "client";
}

/**
 * Username already exists
 */
class UsernameExistsException extends CognitoIdentityProviderServiceException {
  readonly name = "UsernameExistsException";
  readonly $fault = "client";
}

/**
 * Verification code mismatch
 */
class CodeMismatchException extends CognitoIdentityProviderServiceException {
  readonly name = "CodeMismatchException";
  readonly $fault = "client";
}

/**
 * Verification code expired
 */
class ExpiredCodeException extends CognitoIdentityProviderServiceException {
  readonly name = "ExpiredCodeException";
  readonly $fault = "client";
}

/**
 * Password doesn't meet policy requirements
 */
class InvalidPasswordException extends CognitoIdentityProviderServiceException {
  readonly name = "InvalidPasswordException";
  readonly $fault = "client";
}

/**
 * Too many failed authentication attempts
 */
class TooManyFailedAttemptsException extends CognitoIdentityProviderServiceException {
  readonly name = "TooManyFailedAttemptsException";
  readonly $fault = "client";
}

/**
 * Internal service error
 */
class InternalErrorException extends CognitoIdentityProviderServiceException {
  readonly name = "InternalErrorException";
  readonly $fault = "server";
}

/**
 * Response metadata for all service operations
 * Contains request tracking and debugging information
 */
interface ResponseMetadata {
  /** Unique request identifier */
  requestId?: string;
  
  /** CloudFront distribution ID */
  cfId?: string;
  
  /** Extended request ID */
  extendedRequestId?: string;
  
  /** HTTP status code */
  httpStatusCode?: number;
  
  /** Number of retry attempts */
  attempts?: number;
  
  /** Total request time */
  totalRetryDelay?: number;
}

/**
 * Analytics metadata for Amazon Pinpoint
 * Used for collecting user analytics data
 */
interface AnalyticsMetadataType {
  /** Analytics endpoint ID */
  AnalyticsEndpointId?: string;
}

/**
 * User context data for advanced security
 * Additional context about the user's environment
 */
interface UserContextDataType {
  /** IP address of the user */
  IpAddress?: string;
  
  /** Encoded device fingerprint data */
  EncodedData?: string;
}

/**
 * Message action enumeration
 * Controls message delivery behavior
 */
type MessageActionType = "RESEND" | "SUPPRESS";

/**
 * Status enumeration for resources
 * General status indicator for various resources
 */
type StatusType = "Enabled" | "Disabled";