@tc-libs/user 0.42.0 → 0.44.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@tc-libs/user",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "dependencies": {
     "tslib": "^2.3.0",
-    "@tc-libs/authentication": "0.42.0",
-    "@tc-libs/service": "0.42.0",
-    "@tc-libs/database": "0.42.0",
+    "@tc-libs/authentication": "0.44.0",
+    "@tc-libs/service": "0.44.0",
+    "@tc-libs/database": "0.44.0",
     "@nestjs/common": "^10.0.2"
   },
   "type": "commonjs",

package/src/interfaces/serializations/user.payload.serialization.interface.d.ts

@@ -1,6 +1,6 @@
 import { ENUM_AUTH_ACCESS_FOR } from '@tc-libs/authentication';
 import { IUserGetSerialization } from './user.get.serialization.interface';
-export interface IUserPayloadSerialization extends Omit<IUserGetSerialization, 'Role' | 'role' | 'confirmation' | 'confirmed' | 'agreements' | 'notifications' | 'authProvidersts' | 'active' | 'authProviders' | 'inactiveDate' | 'blocked' | 'createdAt' | 'updatedAt'> {
+export interface IUserPayloadSerialization extends Omit<IUserGetSerialization, 'Role' | 'role' | 'confirmation' | 'flags' | 'agreements' | 'notifications' | 'authProvidersts' | 'authProviders' | 'createdAt' | 'updatedAt'> {
     rememberMe: boolean;
     accessFor: ENUM_AUTH_ACCESS_FOR;
 }

package/src/interfaces/services/user.admin.service.interface.d.ts

@@ -1,6 +1,29 @@
 import { IBaseUser } from '../user.base.interface';
 import { IUserService } from './user.base.service.interface';
+/**
+ * Interface representing the administrative services for user management.
+ * Extends the basic user service interface.
+ */
 export interface IUserAdminService extends IUserService {
+    /**
+     * Toggles the confirmation status of a user.
+     *
+     * @param user - The user whose confirmation status is to be toggled.
+     * @returns A promise that resolves to a boolean indicating the success of the operation.
+     */
     toggleConfirm(user: IBaseUser): Promise<boolean>;
-    toggleBlocked(user: IBaseUser): Promise<boolean>;
+    /**
+     * Blocks a user.
+     *
+     * @param user - The user to be blocked.
+     * @returns A promise that resolves to the blocked user.
+     */
+    blocked(user: IBaseUser): Promise<IBaseUser>;
+    /**
+     * Unblocks a user.
+     *
+     * @param user - The user to be unblocked.
+     * @returns A promise that resolves to the unblocked user.
+     */
+    unblocked(user: IBaseUser): Promise<IBaseUser>;
 }

package/src/interfaces/services/user.auth.service.interface.d.ts

@@ -1,21 +1,66 @@
 import { IBaseUser } from '../user.base.interface';
 import { IUserPayloadSerialization } from '../serializations/user.payload.serialization.interface';
 import { IUserService } from './user.base.service.interface';
+/**
+ * Interface representing the user authentication service.
+ * Extends the IUserService interface.
+ */
 export interface IUserAuthService extends IUserService {
+    /**
+     * Serializes the payload data.
+     * @param data - The data to be serialized.
+     * @returns The serialized user payload.
+     */
     payloadSerialization(data: any): IUserPayloadSerialization;
+    /**
+     * Signs in a user with the provided credentials.
+     * @param email - The email of the user.
+     * @param password - The password of the user.
+     * @param rememberMe - Whether to remember the user for future sessions.
+     * @param ip - The IP address of the user.
+     * @param ua - The user agent of the user.
+     * @returns A promise that resolves to an object containing token information.
+     */
     signin(email: string, password: string, rememberMe: boolean, ip: string, ua: string): Promise<{
         tokenType: string;
         expiresIn: number;
         accessToken: string;
         refreshToken: string;
     }>;
+    /**
+     * Refreshes the authentication token for a user.
+     * @param user - The user object.
+     * @param refreshToken - The refresh token.
+     * @param rememberMe - Whether to remember the user for future sessions.
+     * @param loginDate - The date of the login.
+     * @returns A promise that resolves to an object containing token information.
+     */
     refreshToken(user: IBaseUser, refreshToken: string, rememberMe: boolean, loginDate: Date): Promise<{
         tokenType: string;
         expiresIn: number;
         accessToken: string;
         refreshToken: string;
     }>;
+    /**
+     * Signs up a new user with the provided information.
+     * @param body - The signup information.
+     * @param forceConfirmed - Whether to force the user to be confirmed.
+     * @param forceRole - The role to be assigned to the user, if any.
+     * @returns A promise that resolves to the signup result.
+     */
     signup(body: any, forceConfirmed: boolean, forceRole: string | null): Promise<any>;
+    /**
+     * Increases the password attempt count for a user.
+     * @param userId - The ID of the user.
+     * @returns A promise that resolves when the operation is complete.
+     */
     increasePasswordAttempt(userId: string): Promise<void>;
+    /**
+     * Updates the login data after a successful signin.
+     * @param userId - The ID of the user.
+     * @param ip - The IP address of the user.
+     * @param ua - The user agent of the user.
+     * @returns A promise that resolves when the operation is complete.
+     */
     updateLoginDataAfterSignin(userId: string, ip: string, ua: string): Promise<void>;
 }

package/src/interfaces/services/user.base.service.interface.d.ts

@@ -1,11 +1,45 @@
 import { IService } from '@tc-libs/service';
 import { IBaseUser, IUserBirthday } from '../user.base.interface';
+/**
+ * Interface representing the user service.
+ * Extends the generic IService interface with IBaseUser as the type parameter.
+ */
 export interface IUserService extends IService<IBaseUser> {
+    /**
+     * Finds a user by their email address.
+     *
+     * @param email - The email address of the user to find.
+     * @returns A promise that resolves to the found user.
+     */
     findByEmail(email: string): Promise<IBaseUser>;
+    /**
+     * Computes the birthday details of a user.
+     *
+     * @param day - The day of the month.
+     * @param month - The month of the year.
+     * @param year - The year.
+     * @returns An object representing the user's birthday.
+     */
     computeBDay(day: number, month: number, year: number): IUserBirthday;
-    active(repository: IBaseUser): Promise<IBaseUser>;
-    inactive(repository: IBaseUser): Promise<IBaseUser>;
-    blocked(repository: IBaseUser): Promise<IBaseUser>;
-    unblocked(repository: IBaseUser): Promise<IBaseUser>;
-    joinWithRole(repository: IBaseUser): Promise<IBaseUser>;
+    /**
+     * Marks a user as inactive.
+     *
+     * @param user - The user to mark as inactive.
+     * @returns A promise that resolves to the updated user.
+     */
+    inactive(user: IBaseUser): Promise<IBaseUser>;
+    /**
+     * Marks a user as active.
+     *
+     * @param user - The user to mark as active.
+     * @returns A promise that resolves to the updated user.
+     */
+    active(user: IBaseUser): Promise<IBaseUser>;
+    /**
+     * Joins a user with their role.
+     *
+     * @param user - The user to join with a role.
+     * @returns A promise that resolves to the updated user.
+     */
+    joinWithRole(user: IBaseUser): Promise<IBaseUser>;
 }

package/src/interfaces/services/user.confirm.service.interface.d.ts

@@ -1,9 +1,38 @@
 import { IUserConfirmResendSerialization, IUserConfirmSerialization } from '../serializations/user.confirm.serialization.interface';
 import { IBaseUser } from '../user.base.interface';
 import { IUserService } from './user.base.service.interface';
+/**
+ * Interface representing the user confirmation service.
+ * Extends the base user service interface.
+ */
 export interface IUserConfirmService extends IUserService {
+    /**
+     * Resets the confirmation code for a given email.
+     *
+     * @param email - The email address for which to reset the confirmation code.
+     * @returns A promise that resolves to the new confirmation code as a string.
+     */
     resetConfirmCode(email: string): Promise<string>;
+    /**
+     * Resends the confirmation details to the user.
+     *
+     * @param user - The user object containing the necessary information.
+     * @returns A promise that resolves to the serialization of the resend confirmation response.
+     */
     resendConfirm(user: IBaseUser): Promise<IUserConfirmResendSerialization>;
+    /**
+     * Retrieves a user by their email and confirmation code.
+     *
+     * @param email - The email address of the user.
+     * @param uuid - The confirmation code associated with the user.
+     * @returns A promise that resolves to the base user object.
+     */
     getUserByEmailAndConfirmCode(email: string, uuid: string): Promise<IBaseUser>;
+    /**
+     * Confirms the user.
+     *
+     * @param user - The user object to be confirmed.
+     * @returns A promise that resolves to the serialization of the confirmation response.
+     */
     confirm(user: IBaseUser): Promise<IUserConfirmSerialization>;
 }

package/src/interfaces/services/user.reset-password.service.interface.d.ts

@@ -2,8 +2,31 @@ import { IUserResetPasswordDto } from '../dtos/user.reset-password.dto.interface
 import { IUserResetPasswordConfirmSerialization, IUserResetPasswordSerialization } from '../serializations/user.reset-password.serialization.interface';
 import { IBaseUser } from '../user.base.interface';
 import { IUserService } from './user.base.service.interface';
+/**
+ * Interface representing the user reset password service.
+ * Extends the base user service interface.
+ */
 export interface IUserResetPasswordService extends IUserService {
+    /**
+     * Retrieves a user by their email and reset confirmation code.
+     *
+     * @param email - The email of the user.
+     * @param uuid - The reset confirmation code.
+     * @returns A promise that resolves to the base user object.
+     */
     getUserByEmailAndResetConfirmCode(email: string, uuid: string): Promise<IBaseUser>;
+    /**
+     * Resets the user's password.
+     *
+     * @param resetPasswordDto - The data transfer object containing the reset password information.
+     * @returns A promise that resolves to the reset password serialization object.
+     */
     resetPassword(resetPasswordDto: IUserResetPasswordDto): Promise<IUserResetPasswordSerialization>;
+    /**
+     * Confirms the user's password reset.
+     *
+     * @param user - The base user object.
+     * @returns A promise that resolves to the reset password confirmation serialization object.
+     */
     confirmResetPassword(user: IBaseUser): Promise<IUserResetPasswordConfirmSerialization>;
 }

package/src/interfaces/user.base.interface.d.ts

@@ -11,45 +11,116 @@ export declare enum AUTH_PROVIDERS {
     MI = "microsoft",
     PP = "paypal"
 }
+/**
+ * Interface representing the acceptance of a flag.
+ *
+ * @interface IFlagAcceptance
+ *
+ * @property {boolean} enabled - Indicates whether the flag is enabled.
+ * @property {Date} ts - The timestamp when the flag was accepted.
+ * @property {string} version - The version of the flag acceptance.
+ */
 export interface IFlagAcceptance {
     enabled: boolean;
     ts: Date;
     version: string;
 }
+/**
+ * Interface representing user notifications settings.
+ * @property {IFlagAcceptance} newsletter - User's acceptance of newsletter.
+ */
 export interface IUserNotifications {
     newsletter: IFlagAcceptance;
 }
+/**
+ * Interface representing user agreements.
+ *
+ * @interface IUserAgreements
+ *
+ * @property {IFlagAcceptance} terms - User's acceptance of the terms and conditions.
+ * @property {IFlagAcceptance} privacy - User's acceptance of the privacy policy.
+ * @property {IFlagAcceptance} commercial - User's acceptance of commercial communications.
+ */
 export interface IUserAgreements {
     terms: IFlagAcceptance;
     privacy: IFlagAcceptance;
     commercial: IFlagAcceptance;
 }
 export interface IUserBirthday {
-    day: number;
-    month: number;
-    year: number;
-    date: Date;
+    day?: number;
+    month?: number;
+    year?: number;
+    date?: Date;
 }
+/**
+ * Interface representing the structure of user reset password details.
+ *
+ * @interface IUserResetPassword
+ *
+ * @property {string} [code] - The reset password code.
+ * @property {string} [tmpPassword] - The temporary password assigned to the user.
+ * @property {Date} [ts] - The timestamp when the reset password was requested.
+ */
 export interface IUserResetPassword {
-    code: string;
-    tmpPassword: string;
-    ts: Date;
+    code?: string;
+    tmpPassword?: string;
+    ts?: Date;
 }
+/**
+ * Interface representing the history of user passwords.
+ *
+ * @interface IUserPasswordHistory
+ *
+ * @property {string} password - The user's previous password.
+ * @property {Date} ts - The timestamp when the password was changed.
+ */
 export interface IUserPasswordHistory {
     password: string;
     ts: Date;
 }
+/**
+ * Interface representing the structure of user email confirmation details.
+ * @interface IUserEmailConfirmation
+ * @property {string} [code] - The confirmation code.
+ * @property {Date} [ts] - The timestamp of the confirmation code.
+ */
 export interface IUserEmailConfirmation {
     code?: string;
     ts?: Date;
 }
+/**
+ * Interface representing user login information.
+ *
+ * @interface IUserLoginInfo
+ *
+ * @property {number} attempt - The number of unsuccessful login attempts made by the user.
+ * @property {number} count - The count of successful logins.
+ * @property {string} [ip] - The IP address from which the user attempted to log in.
+ * @property {string} [ua] - The user agent string of the browser or device used for login.
+ * @property {Date} [lastLogin] - The date and time of the last successful login.
+ */
 export interface IUserLoginInfo {
     attempt: number;
     count: number;
-    ip: string;
-    ua: string;
-    lastLogin: Date;
+    ip?: string;
+    ua?: string;
+    lastLogin?: Date;
 }
+/**
+ * Interface representing a user's social media information.
+ *
+ * @interface IUserSocialInfo
+ *
+ * @property {string} facebookId - The user's Facebook ID.
+ * @property {string} twitterId - The user's Twitter ID.
+ * @property {string} githubId - The user's GitHub ID.
+ * @property {string} linkedinId - The user's LinkedIn ID.
+ * @property {string} amazonId - The user's Amazon ID.
+ * @property {string} googleId - The user's Google ID.
+ * @property {string} bitbucketId - The user's Bitbucket ID.
+ * @property {string} microsoftId - The user's Microsoft ID.
+ * @property {string} paypalId - The user's PayPal ID.
+ */
 export interface IUserSocialInfo {
     facebookId: string;
     twitterId: string;
@@ -61,6 +132,46 @@ export interface IUserSocialInfo {
     microsoftId: string;
     paypalId: string;
 }
+/**
+ * Interface representing the flags associated with a user.
+ *
+ * @property {boolean} confirmed - Indicates if the user has confirmed their account by the email.
+ * @property {boolean} [iddqd] - Optional flag for a special status (e.g., god mode).
+ * @property {boolean} blocked - Indicates if the user is blocked by admin.
+ * @property {Date} [blockedDate] - Optional date when the user was blocked.
+ * @property {boolean} active - Indicates if the user is inactivated by itself.
+ * @property {Date} [inactiveDate] - Optional date when the user became inactivated by itself.
+ */
+export interface IUserFlags {
+    confirmed: boolean;
+    iddqd?: boolean;
+    blocked: boolean;
+    blockedDate?: Date;
+    active: boolean;
+    inactiveDate?: Date;
+}
+/**
+ * Interface representing the base structure of a user entity.
+ *
+ * @extends IDatabaseMongoBaseEntityAbstract
+ *
+ * @property {string} email - The email address of the user.
+ * @property {string} password - The password of the user.
+ * @property {string} role - The role assigned to the user.
+ * @property {string} [firstName] - The first name of the user.
+ * @property {string} [lastName] - The last name of the user.
+ * @property {string} [lang] - The preferred language of the user.
+ * @property {IUserFlags} flags - The flags associated with the user.
+ * @property {IUserResetPassword} [resetPassword] - Information related to password reset.
+ * @property {IUserEmailConfirmation} confirmation - Information related to email confirmation.
+ * @property {IUserPasswordHistory[]} [passwordHistory] - History of the user's passwords.
+ * @property {IUserLoginInfo} [login] - Information related to user login attempts.
+ * @property {IUserSocialInfo} [social] - Information related to user's social media accounts.
+ * @property {IUserAgreements} agreements - User's acceptance of various agreements.
+ * @property {IUserNotifications} notifications - User's notification preferences.
+ * @property {IUserBirthday} [birthday] - User's birthday information.
+ * @property {string[]} authProviders - List of authentication providers associated with the user.
+ */
 export interface IBaseUser extends IDatabaseMongoBaseEntityAbstract {
     email: string;
     password: string;
@@ -68,12 +179,7 @@ export interface IBaseUser extends IDatabaseMongoBaseEntityAbstract {
     firstName?: string;
     lastName?: string;
     lang?: string;
-    iddqd?: boolean;
-    confirmed: boolean;
-    blocked: boolean;
-    blockedDate?: Date;
-    active: boolean;
-    inactiveDate?: Date;
+    flags: IUserFlags;
     resetPassword?: IUserResetPassword;
     confirmation: IUserEmailConfirmation;
     passwordHistory?: IUserPasswordHistory[];