@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/dist/features/users/users.service.d.ts

@@ -0,0 +1,246 @@
+import { EntityManager } from 'typeorm';
+import { AuthOptions } from '../../auth-options.js';
+import { RequestContext } from '../../common/request-context.js';
+import { UserEntity } from '../../database/entities/index.js';
+import { AuthEventsService } from '../events/auth-events.service.js';
+import { SessionService } from '../sessions/session.service.js';
+import { AuthSettings } from '../settings/settings.types.js';
+import { PendingVerification, PublicUserProfile } from './users.types';
+import type { JsonObject } from '../../database/entities/json-object.js';
+export interface NewUserDetails {
+    email?: string | null;
+    phoneNumber?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    /** True when the sign-up itself proved the email (email code, magic link, Google...). */
+    isEmailVerified?: boolean;
+    isPhoneVerified?: boolean;
+    acceptedTerms?: boolean;
+    acceptedPrivacyPolicy?: boolean;
+}
+export interface ProfileChanges {
+    firstName?: string;
+    lastName?: string;
+    /** Your app's own extra fields. Replaces the whole object. */
+    metadata?: JsonObject;
+}
+/**
+ * Accounts and their life cycle:
+ *
+ *   PENDING_VERIFICATION --(required verifications done)--> ACTIVE
+ *   ACTIVE --(admin)--> SUSPENDED --(admin lifts it)--> ACTIVE
+ *   ACTIVE --(user)--> DEACTIVATED --(user reactivates)--> ACTIVE
+ *   any --(user or admin)--> DELETED (personal data wiped; cannot be undone)
+ *
+ * Suspending, deactivating and deleting all sign the user out everywhere.
+ */
+export declare class UsersService {
+    private readonly sessions;
+    private readonly events;
+    private readonly database;
+    constructor(options: AuthOptions, sessions: SessionService, events: AuthEventsService);
+    /**
+     * @param userId - The user's id.
+     * @returns The user (in any status, including DELETED), or null.
+     */
+    findUserById(userId: string): Promise<UserEntity | null>;
+    /**
+     * @param email - Must already be normalized (see `normalizeEmail`).
+     * @returns The user with this email, or null.
+     */
+    findUserByEmail(email: string): Promise<UserEntity | null>;
+    /**
+     * @param phoneNumber - Must already be normalized (see `normalizePhoneNumber`).
+     * @returns The user with this phone number, or null.
+     */
+    findUserByPhoneNumber(phoneNumber: string): Promise<UserEntity | null>;
+    /**
+     * Loads a user that must exist. Deleted accounts count as missing.
+     *
+     * @param userId - The user's id.
+     * @returns The user.
+     * @throws AuthError NOT_FOUND when there is no such user, or it was deleted.
+     */
+    getUserOrThrow(userId: string): Promise<UserEntity>;
+    /**
+     * Creates an account with the app's default roles (users can never pick their own role).
+     * The account starts ACTIVE if the sign-up already proved everything the settings require,
+     * otherwise PENDING_VERIFICATION.
+     *
+     * @param details - Contact details, names, and what the sign-up already verified.
+     * @param settings - The current settings (registration and activation rules).
+     * @param request - Who is asking (for the audit log).
+     * @param transaction - Pass one to create the user together with other rows (e.g. the password).
+     * @returns The saved user.
+     * @throws AuthError SIGN_UP_CLOSED when registration is turned off.
+     * @throws AuthError ACCOUNT_ALREADY_EXISTS when the email or phone number is already taken.
+     */
+    createUser(details: NewUserDetails, settings: AuthSettings, request: RequestContext, transaction?: EntityManager): Promise<UserEntity>;
+    /**
+     * Lists what the user still has to verify before the account becomes ACTIVE.
+     *
+     * @param user - The user.
+     * @param settings - The current settings (activation rules).
+     * @returns e.g. ["email"]; empty when nothing is left.
+     */
+    getPendingVerifications(user: UserEntity, settings: AuthSettings): PendingVerification[];
+    /**
+     * Marks the email verified, and activates the account if nothing else is pending.
+     *
+     * @param user - The user; updated in place.
+     * @param settings - The current settings.
+     * @param request - Who is asking (for the audit log).
+     * @returns The same user, with its new status.
+     */
+    markEmailVerified(user: UserEntity, settings: AuthSettings, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Marks the phone number verified, and activates the account if nothing else is pending.
+     *
+     * @param user - The user; updated in place.
+     * @param settings - The current settings.
+     * @param request - Who is asking (for the audit log).
+     * @returns The same user, with its new status.
+     */
+    markPhoneVerified(user: UserEntity, settings: AuthSettings, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Protects against "account pre-hijacking": someone registers YOUR email with THEIR password,
+     * never verifies it, and waits for you to sign in with a code, link or Google. When the real
+     * owner proves the email for the first time this way, any password set before that proof is
+     * removed and all earlier sessions end. Call it BEFORE markEmailVerified.
+     *
+     * A brand-new account (younger than UNVERIFIED_ACCOUNT_GRACE_SECONDS) is left alone: that is the
+     * normal "register with a password, then verify with the emailed code" flow.
+     *
+     * @param user - The user who just proved the email.
+     * @param request - Who is asking (for the audit log).
+     */
+    removeUnprovenPassword(user: UserEntity, request: RequestContext): Promise<void>;
+    /**
+     * Moves a PENDING_VERIFICATION account to ACTIVE once nothing is left to verify.
+     * Does nothing for accounts in any other status.
+     *
+     * @param user - The user; updated in place.
+     * @param settings - The current settings.
+     * @param request - Who is asking (for the audit log).
+     * @returns The same user.
+     */
+    activateIfReady(user: UserEntity, settings: AuthSettings, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Changes the user's names and/or app metadata. Fields left undefined are not touched.
+     *
+     * @param userId - The user to change.
+     * @param changes - The new values.
+     * @param performedBy - Who made the change, for the audit log (null when it was the user).
+     * @param request - Who is asking.
+     * @returns The updated user.
+     * @throws AuthError NOT_FOUND when the user doesn't exist.
+     */
+    updateProfile(userId: string, changes: ProfileChanges, performedBy: string | null, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Called by your app's profile module once the user has finished onboarding.
+     * Calling it again changes nothing.
+     *
+     * @param userId - The user.
+     * @param request - Who is asking (for the audit log).
+     * @returns The updated user.
+     */
+    completeOnboarding(userId: string, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Replaces a user's app-wide roles. Admin only. New roles show up in the user's next access token.
+     *
+     * @param userId - The user to change.
+     * @param roles - The full new list; duplicates are removed.
+     * @param adminUserId - The admin doing it (for the audit log).
+     * @param request - Who is asking.
+     * @returns The updated user.
+     * @throws AuthError VALIDATION_ERROR when a role name is invalid or there are too many roles.
+     */
+    setRoles(userId: string, roles: string[], adminUserId: string, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Remembers when the user last signed in (shown to admins and in the profile).
+     *
+     * @param user - The user; updated in place.
+     */
+    recordSignIn(user: UserEntity): Promise<void>;
+    /**
+     * Admin blocks an account. The reason is kept for support staff. Signs the user out everywhere.
+     *
+     * @param userId - The user to suspend.
+     * @param reason - Why (kept for support staff, not shown to the user).
+     * @param adminUserId - The admin doing it (for the audit log).
+     * @param request - Who is asking.
+     * @returns The updated user.
+     */
+    suspendUser(userId: string, reason: string, adminUserId: string, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Admin lifts a suspension. The account goes back to ACTIVE (or PENDING_VERIFICATION if still unverified).
+     *
+     * @param userId - The suspended user.
+     * @param adminUserId - The admin doing it (for the audit log).
+     * @param settings - The current settings.
+     * @param request - Who is asking.
+     * @returns The updated user (unchanged if it wasn't suspended).
+     */
+    liftSuspension(userId: string, adminUserId: string, settings: AuthSettings, request: RequestContext): Promise<UserEntity>;
+    /**
+     * The user switches their own account off for a while. Signs them out everywhere.
+     * They can switch it back on by signing in again.
+     *
+     * @param userId - The signed-in user.
+     * @param request - Who is asking (for the audit log).
+     * @throws AuthError ACCOUNT_SUSPENDED when an admin has suspended the account.
+     */
+    deactivateAccount(userId: string, request: RequestContext): Promise<void>;
+    /**
+     * The user switches their account back on (after proving who they are, see SignInService).
+     *
+     * @param userId - The deactivated user.
+     * @param settings - The current settings.
+     * @param request - Who is asking (for the audit log).
+     * @returns The updated user.
+     * @throws AuthError ACCOUNT_NOT_DEACTIVATED when the account isn't deactivated.
+     */
+    reactivateAccount(userId: string, settings: AuthSettings, request: RequestContext): Promise<UserEntity>;
+    /**
+     * Deletes the account. The row stays (so ids in your other tables don't dangle and the audit log
+     * still makes sense), but every piece of personal data and every way to sign in is wiped.
+     * This cannot be undone.
+     *
+     * @param userId - The user to delete.
+     * @param performedBy - Who did it, for the audit log (null when it was the user).
+     * @param request - Who is asking.
+     */
+    deleteUser(userId: string, performedBy: string | null, request: RequestContext): Promise<void>;
+    /**
+     * The user as your app may show it. Never includes secrets.
+     *
+     * @param user - The user.
+     * @param settings - The current settings (to work out pending verifications).
+     * @returns The profile to send to the client.
+     */
+    toPublicProfile(user: UserEntity, settings: AuthSettings): PublicUserProfile;
+    /**
+     * Where a returning (unsuspended / reactivated) account lands: ACTIVE, unless verification is still owed.
+     *
+     * @param user - The returning user.
+     * @param settings - The current settings.
+     * @returns ACTIVE or PENDING_VERIFICATION.
+     */
+    private statusAfterReturning;
+    /**
+     * Changes the status only if it is still `expectedStatus` (so two admins clicking at once can't
+     * clash). Updates `user` in place.
+     *
+     * @param user - The user to change.
+     * @param expectedStatus - The status the user must still have.
+     * @param newStatus - The status to set.
+     * @param extraColumns - Other columns to change in the same UPDATE.
+     * @returns False if someone else changed it first.
+     */
+    private changeStatus;
+    /**
+     * @param error - An error thrown by the database.
+     * @returns True when Postgres refused a duplicate value (e.g. an email that is already taken).
+     */
+    private isUniqueViolation;
+}