# Domain Entities — Unit 5: User Management

## Overview

Unit 5 introduces user listing, invitation management, and role changes. Two new backend endpoints are required: `GET /api/v1/Users` (list with invitation state) and `PUT /api/v1/Users/{userId}/role` (role assignment). The frontend extends `types.ts` with new interfaces for these operations.

## Entity Diagram

```mermaid
graph LR
    UserListItem["UserListItem\nid, email, name, role\nisActive, createdAt\ninvitationPending, inviteLink"]
    UserRole["UserRole\nOwner, Administrator, User"]
    InviteUserRequest["InviteUserRequest\nemail, role"]
    InviteUserResponse["InviteUserResponse\ninviteLink"]
    ChangeRoleRequest["ChangeRoleRequest\nnewRole"]

    UserListItem -->|has role| UserRole
    InviteUserRequest -->|assigns role| UserRole
    ChangeRoleRequest -->|assigns| UserRole

    classDef entity fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000
    classDef request fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000
    classDef enumType fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000

    class UserListItem entity
    class InviteUserRequest,InviteUserResponse,ChangeRoleRequest request
    class UserRole enumType
```

Text alternative: UserListItem (blauw) heeft een UserRole enum (geel); InviteUserRequest en ChangeRoleRequest (groen) wijzen een UserRole toe.

## Field Descriptions

### UserListItem — GET /api/v1/Users response item

| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Unique user identifier |
| email | string | User's email address |
| name | string | Display name (DisplayName ?? Email fallback, consistent with AuthResponse) |
| role | UserRole | Current role: Owner, Administrator, or User |
| isActive | bool | Whether the account is active |
| createdAt | string (ISO 8601) | Account creation timestamp |
| invitationPending | bool | True when the user has not yet completed invitation setup |
| inviteLink | string \| null | Full invite URL for pending users; null for active accounts |

### InviteUserRequest — POST /api/v1/Users/invite

| Field | Type | Description |
|---|---|---|
| email | string | Email address of the invitee |
| role | 'Administrator' \| 'User' | Role to assign — Owner is excluded by business rule |

### InviteUserResponse — POST /api/v1/Users/invite response

| Field | Type | Description |
|---|---|---|
| inviteLink | string | Relative URL for the invitation (e.g. `/invite/complete?token=...`) |

### ChangeRoleRequest — PUT /api/v1/Users/{userId}/role

| Field | Type | Description |
|---|---|---|
| newRole | UserRole | Role to assign to the target user |

## Type Extensions — frontend/src/api/types.ts

The existing `User` type covers the logged-in session user. Unit 5 adds:

```typescript
// User item returned by GET /api/v1/Users
export interface UserListItem extends User {
    createdAt: string;          // ISO 8601
    invitationPending: boolean;
    inviteLink: string | null;
}

// POST /api/v1/Users/invite
export interface InviteUserRequest {
    email: string;
    role: Exclude<UserRole, 'Owner'>;   // Owner cannot be invited
}

export interface InviteUserResponse {
    inviteLink: string;
}

// PUT /api/v1/Users/{userId}/role
export interface ChangeRoleRequest {
    newRole: UserRole;
}
```