npm package: @geekbears/gb-ngrx-account-basic
Description: This library provides a robust NgRx-based state management solution for account-related features in Angular applications. It centralizes the logic for managing user profile information, password updates, email changes, and verification workflows, offering
Latest version: 21.0.0

# @geekbears/gb-ngrx-account-basic

This library provides a robust NgRx-based state management solution for account-related features in Angular applications. It centralizes the logic for managing user profile information, password updates, email changes, and verification workflows, offering a predictable state container for your account data.

## Features

*   **Password Management**:
    *   **Forgot Password**: Complete flow for requesting password reset emails and submitting new passwords.
    *   **Change Password**: Securely update the logged-in user's password.
*   **Email Management**:
    *   **Change Email**: Process for updating user email addresses, including verification steps.
    *   **Verification**: Handle email verification codes and resend requests.
*   **Profile Management**:
    *   **Update Info**: seamless updates for general account information.
    *   **Profile Image**: Dedicated flow for uploading and updating profile pictures.
*   **State Management**:
    *   **Loading & Error States**: Built-in state tracking for all asynchronous operations.
    *   **Selectors**: Easy access to account data and operation status.

## Installation

Install the library using npm or yarn:

```bash
npm install @geekbears/gb-ngrx-account-basic
# or
yarn add @geekbears/gb-ngrx-account-basic
```

## Configuration

The library requires a configuration object to define API endpoints and custom mappers. You must provide this configuration using the `GbNgRxAccountConfigToken`.

### 1. Define your Configuration

Create a class or object that implements `GbNgRxAccountBasicModuleConfig`:

```typescript
import { GbNgRxAccountBasicModuleConfig, AccountUpdatePayload } from '@geekbears/gb-ngrx-account-basic';
import { AuthenticationData } from '@geekbears/gb-ngrx-auth-basic';
import { Observable } from 'rxjs';

export const myAccountConfig: GbNgRxAccountBasicModuleConfig = {
  // --- Profile Image ---
  updateAccountProfileImageApiUrl: (authData) => `${environment.apiUrl}/users/${authData.userId}/avatar`,
  updateAccountProfileImageRequestMapper: (file, authData) => {
    const formData = new FormData();
    formData.append('avatar', file);
    return of(formData);
  },

  // --- Account Info ---
  updateAccountInfoApiUrl: (authData) => `${environment.apiUrl}/users/${authData.userId}`,
  updateAccountInfoCustomRequestMapper: (authData, payload) => of(payload),
  getUserAccountInfoApiUrl: (userId) => `${environment.apiUrl}/users/${userId}`,
  
  // --- Response Parsers ---
  updateAccountInfoCustomResponseParser: (response) => of(response.data),
  updateUsernameCustomResponseParser: (response) => of(response.data),

  // --- Verification ---
  submitVerificationCodeApiUrl: (authData) => `${environment.apiUrl}/verify-code`,
  submitVerificationCodeCustomRequestMapper: (code, authData) => of({ code, userId: authData.userId }),
  
  resendVerificationCodeApiUrl: (authData) => `${environment.apiUrl}/resend-code`,
  resendVerificationCodeCustomRequestMapper: (authData) => of({ userId: authData.userId }),

  // --- Password Management ---
  requestForgotPasswordApiUrl: () => `${environment.apiUrl}/auth/forgot-password`,
  setNewForgottenPasswordApiUrl: () => `${environment.apiUrl}/auth/reset-password`,
  
  changePasswordApiUrl: (userId) => `${environment.apiUrl}/users/${userId}/password`,
  changePasswordCustomRequestMapper: (userId, data) => of(data),

  // --- Email Management ---
  changeEmailApiUrl: (userId) => `${environment.apiUrl}/users/${userId}/email`,
  changeEmailCustomRequestMapper: (userId, data) => of(data),
  
  submitEmailVerificationCodeApiUrl: (userId) => `${environment.apiUrl}/users/${userId}/email/verify`,
  submitEmailVerificationCodeCustomRequestMapper: (userId, code) => of({ code }),
  
  submitCancelEmailChangeApiUrl: (userId) => `${environment.apiUrl}/users/${userId}/email/cancel`,
  submitResendCodeEmailChangeApiUrl: (userId) => `${environment.apiUrl}/users/${userId}/email/resend`,
};
```

### 2. Import the Module

Import `GbNgrxAccountBasicModule` into your `AppModule` (or a Core module) and provide the configuration:

```typescript
import { NgModule } from '@angular/core';
import { GbNgrxAccountBasicModule, GbNgRxAccountConfigToken } from '@geekbears/gb-ngrx-account-basic';
import { myAccountConfig } from './my-account.config';

@NgModule({
  imports: [
    // ... other imports
    GbNgrxAccountBasicModule,
  ],
  providers: [
    {
      provide: GbNgRxAccountConfigToken,
      useValue: myAccountConfig
    }
  ],
})
export class AppModule { }
```

## Usage

### Dispatching Actions

Interact with the state by dispatching actions from your components or services.

```typescript
import { Store } from '@ngrx/store';
import { 
  updateAccountInfoAction, 
  changePasswordAction, 
  requestPasswordResetAction 
} from '@geekbears/gb-ngrx-account-basic';

@Component({ ... })
export class MyProfileComponent {
  constructor(private store: Store) {}

  updateProfile(info: any) {
    this.store.dispatch(updateAccountInfoAction({ info }));
  }

  changePassword(oldPassword: string, newPassword: string) {
    this.store.dispatch(changePasswordAction({ 
      userId: '123', 
      data: { oldPassword, newPassword } 
    }));
  }
}
```

### Selecting State

Use selectors to observe data from the store.

```typescript
import { Store } from '@ngrx/store';
import { selectAccountState, selectIsUpdatingAccount } from '@geekbears/gb-ngrx-account-basic';

@Component({ ... })
export class MyProfileComponent {
  accountState$ = this.store.select(selectAccountState);
  isLoading$ = this.store.select(selectIsUpdatingAccount);

  constructor(private store: Store) {}
}
```

## API Reference

### Key Selectors
- `selectAccountState`: Returns the entire account feature state.
- `selectAccountUser`: Returns the current user object.
- `selectIsUpdatingAccount`: Boolean indicating if an update is in progress.
- `selectAccountError`: Returns any error from the last operation.

### Key Actions
- `updateAccountInfoAction`
- `updateAccountProfileImageAction`
- `submitPasswordChangeAction`
- `submitEmailChangeAction`
- `requestPasswordResetAction`
- `submitVerificationCodeAction`