npm package: @haykal/profile-management-backend
Description: > User profile management with CRUD, privacy settings, completeness tracking, and extensible metadata.
Latest version: 1.0.0

# @haykal/profile-management-backend

> User profile management with CRUD, privacy settings, completeness tracking, and extensible metadata.

## Installation

```bash
pnpm add @haykal/profile-management-backend
```

## Configuration

### `forRoot()` Options

```typescript
import { ProfileManagementModule } from '@haykal/profile-management-backend';

@Module({
  imports: [
    ProfileManagementModule.forRoot({
      maxBioLength: 500,
      maxSocialLinks: 10,
      defaultProfileVisibility: true,
    }),
  ],
})
export class AppModule {}
```

| Property                   | Type      | Default | Description                  |
| -------------------------- | --------- | ------- | ---------------------------- |
| `maxBioLength`             | `number`  | `500`   | Maximum bio character length |
| `maxSocialLinks`           | `number`  | `10`    | Maximum social link entries  |
| `defaultProfileVisibility` | `boolean` | `true`  | Default profile visibility   |

## Key Exports

| Export                        | Type          | Description                                                  |
| ----------------------------- | ------------- | ------------------------------------------------------------ |
| `ProfileManagementModule`     | NestJS Module | Main module with `forRoot()` / `forRootAsync()`              |
| `PROFILE_MANAGEMENT_CONFIG`   | Symbol        | Inject the config object                                     |
| `ProfilesService`             | Service       | Profile CRUD, privacy, completeness                          |
| `ProfilesRepository`          | Repository    | Data access for `UserProfileEntity`                          |
| `UserProfileEntity`           | Entity        | Profile entity with privacy controls                         |
| `PROFILE_MANAGEMENT_ENTITIES` | Array         | `[UserProfileEntity]` for migrations                         |
| `Gender`                      | Enum          | `MALE`, `FEMALE`, `NON_BINARY`, `PREFER_NOT_TO_SAY`, `OTHER` |

### DTOs

| DTO                        | Description                                     |
| -------------------------- | ----------------------------------------------- |
| `CreateUserProfileDto`     | Create profile (userId, displayName, bio, etc.) |
| `UpdateUserProfileDto`     | Partial profile update                          |
| `UpdatePrivacySettingsDto` | Privacy toggles (isPublic, showEmail, etc.)     |
| `UserProfileResponseDto`   | Serialized profile response                     |

### Domain Errors

| Error                         | Code                         | Status | Description                |
| ----------------------------- | ---------------------------- | ------ | -------------------------- |
| `ProfileNotFoundError`        | `PROFILE_NOT_FOUND`          | 404    | Profile not found by ID    |
| `ProfileNotFoundForUserError` | `PROFILE_NOT_FOUND_FOR_USER` | 404    | No profile for user        |
| `ProfileAlreadyExistsError`   | `PROFILE_ALREADY_EXISTS`     | 409    | Duplicate profile for user |

## API Endpoints

All endpoints require JWT authentication. Base path: `/api/profiles`.

| Method   | Path                     | Description                                     |
| -------- | ------------------------ | ----------------------------------------------- |
| `POST`   | `/profiles`              | Create a user profile                           |
| `GET`    | `/profiles`              | List profiles (paginated, filterable, sortable) |
| `GET`    | `/profiles/:id`          | Get profile by ID                               |
| `GET`    | `/profiles/user/:userId` | Get profile by user ID                          |
| `PATCH`  | `/profiles/:id`          | Update profile                                  |
| `PATCH`  | `/profiles/:id/privacy`  | Update privacy settings                         |
| `DELETE` | `/profiles/:id`          | Soft-delete profile                             |

## Usage Examples

```typescript
import { ProfilesService } from '@haykal/profile-management-backend';

@Injectable()
export class MyService {
  constructor(private readonly profiles: ProfilesService) {}

  async getOrCreateProfile(userId: string) {
    try {
      return await this.profiles.findByUserId(userId);
    } catch {
      return await this.profiles.create({ userId, displayName: 'New User' });
    }
  }
}
```

## Related Packages

- `@haykal/profile-management-client` — React Query hooks for profiles
- `@haykal/user-management-backend` — User entity and CRUD
- `@haykal/storage-backend` — Avatar and cover photo storage

## Further Reading

- [API Reference](../../../docs/api-reference.md) — Full endpoint listing
- [Architecture Overview](../../../docs/architecture.md) — System design and module composition
- [Backend Style Guide](../../../docs/backend-styleguide.md) — Coding conventions