@vulog/aima-user/README.md

User management — profiles, personal information, labels, billing groups, and service registration.

# @vulog/aima-user

User management — profiles, personal information, labels, billing groups, and service registration.

## Installation

```sh
npm install @vulog/aima-user @vulog/aima-client @vulog/aima-core @vulog/aima-config
```

## Usage

```ts
import { getUserById, createUser, findUser, getUsers } from '@vulog/aima-user';
import { getClient } from '@vulog/aima-client';

const client = getClient({ ... });

const user = await getUserById(client, 'user-uuid');

const results = await findUser(client, 'email', 'jane@example.com', ['PERSONAL']);
```

## API Reference

### acceptTAndC

```ts
acceptTAndC(client: Client, userId: string, cityId: string): Promise<void>
```

Accepts terms and conditions for a user in a given city.

| Param    | Type     | Description               |
| -------- | -------- | ------------------------- |
| `client` | `Client` | Authenticated AIMA client |
| `userId` | `string` | User identifier           |
| `cityId` | `string` | City identifier           |

---

### assignBillingGroup

```ts
assignBillingGroup(client: Client, entityId: string, billingGroupId: string): Promise<void>
```

Assigns an entity to a billing group.

| Param            | Type     | Description               |
| ---------------- | -------- | ------------------------- |
| `client`         | `Client` | Authenticated AIMA client |
| `entityId`       | `string` | Entity identifier         |
| `billingGroupId` | `string` | Billing group identifier  |

---

### unassignBillingGroup

```ts
unassignBillingGroup(client: Client, entityId: string, billingGroupId: string): Promise<void>
```

Removes an entity from a billing group.

| Param            | Type     | Description               |
| ---------------- | -------- | ------------------------- |
| `client`         | `Client` | Authenticated AIMA client |
| `entityId`       | `string` | Entity identifier         |
| `billingGroupId` | `string` | Billing group identifier  |

---

### createBusinessProfile

```ts
createBusinessProfile(client: Client, userId: string, businessId: string, data: { emailConsent: boolean; email: string; requestId: string; costCenterId?: string }): Promise<UserProfile>
```

**@deprecated.** Creates a business profile for a user.

| Param        | Type     | Description               |
| ------------ | -------- | ------------------------- |
| `client`     | `Client` | Authenticated AIMA client |
| `userId`     | `string` | User identifier           |
| `businessId` | `string` | Business identifier       |
| `data`       | `object` | Profile creation data     |

---

### createUser

```ts
createUser(client: Client, user: CreateUser, option?: CreateUserOptions): Promise<User>
```

Creates a new user account.

| Param    | Type                | Description               |
| -------- | ------------------- | ------------------------- |
| `client` | `Client`            | Authenticated AIMA client |
| `user`   | `CreateUser`        | User creation data        |
| `option` | `CreateUserOptions` | Creation options          |

---

### findUser

```ts
findUser(client: Client, searchType: 'email' | 'username' | 'phoneNumber', searchQuery: string, types: PersonalInformationUserType[]): Promise<ResponseFind>
```

Searches for users by email, username, or phone number.

| Param         | Type                                     | Description                    |
| ------------- | ---------------------------------------- | ------------------------------ |
| `client`      | `Client`                                 | Authenticated AIMA client      |
| `searchType`  | `'email' \| 'username' \| 'phoneNumber'` | Search field                   |
| `searchQuery` | `string`                                 | Value to search for            |
| `types`       | `PersonalInformationUserType[]`          | Personal info types to include |

---

### getProfilePersonalInfoById

```ts
getProfilePersonalInfoById(client: Client, userId: string, profileId: string, types: PersonalInformationProfileType[]): Promise<PersonalInformationProfile>
```

Returns personal information for a user profile.

| Param       | Type                               | Description                    |
| ----------- | ---------------------------------- | ------------------------------ |
| `client`    | `Client`                           | Authenticated AIMA client      |
| `userId`    | `string`                           | User identifier                |
| `profileId` | `string`                           | Profile identifier             |
| `types`     | `PersonalInformationProfileType[]` | Personal info types to include |

---

### getRegistrationOverview

```ts
getRegistrationOverview(client: Client, userId: string): Promise<UserServiceRegistration>
```

Returns the service registration overview for a single user.

| Param    | Type     | Description               |
| -------- | -------- | ------------------------- |
| `client` | `Client` | Authenticated AIMA client |
| `userId` | `string` | User identifier           |

---

### getUserById

```ts
getUserById(client: Client, id: string, addAccountStatus?: boolean): Promise<User>
```

Fetches a user by ID. Pass `addAccountStatus: true` to fetch extra account status data.

| Param              | Type      | Description               |
| ------------------ | --------- | ------------------------- |
| `client`           | `Client`  | Authenticated AIMA client |
| `id`               | `string`  | User identifier           |
| `addAccountStatus` | `boolean` | Include account status    |

---

### getUserByEmail

```ts
getUserByEmail(client: Client, email: string): Promise<User>
```

Fetches a user by email address.

| Param    | Type     | Description               |
| -------- | -------- | ------------------------- |
| `client` | `Client` | Authenticated AIMA client |
| `email`  | `string` | User email address        |

---

### getUserPersonalInfoById

```ts
getUserPersonalInfoById(client: Client, id: string, types: PersonalInformationUserType[]): Promise<PersonalInformationUser>
```

Returns personal information for a user.

| Param    | Type                            | Description                    |
| -------- | ------------------------------- | ------------------------------ |
| `client` | `Client`                        | Authenticated AIMA client      |
| `id`     | `string`                        | User identifier                |
| `types`  | `PersonalInformationUserType[]` | Personal info types to include |

---

### getUsersPIByIds

```ts
getUsersPIByIds(client: Client, ids: string[], types: PersonalInformationUserType[]): Promise<PersonalInformationUser[]>
```

Batch-fetches personal information for multiple users.

| Param    | Type                            | Description                    |
| -------- | ------------------------------- | ------------------------------ |
| `client` | `Client`                        | Authenticated AIMA client      |
| `ids`    | `string[]`                      | User identifiers               |
| `types`  | `PersonalInformationUserType[]` | Personal info types to include |

---

### getLabelsForUser

```ts
getLabelsForUser(client: Client, userId: string): Promise<Label[]>
```

Returns all labels assigned to a user.

| Param    | Type     | Description               |
| -------- | -------- | ------------------------- |
| `client` | `Client` | Authenticated AIMA client |
| `userId` | `string` | User identifier           |

---

### addLabelForUser

```ts
addLabelForUser(client: Client, userId: string, labelId: number): Promise<void>
```

Assigns a label to a user.

| Param     | Type     | Description               |
| --------- | -------- | ------------------------- |
| `client`  | `Client` | Authenticated AIMA client |
| `userId`  | `string` | User identifier           |
| `labelId` | `number` | Label identifier          |

---

### removeLabelForUser

```ts
removeLabelForUser(client: Client, userId: string, labelId: number): Promise<void>
```

Removes a label from a user.

| Param     | Type     | Description               |
| --------- | -------- | ------------------------- |
| `client`  | `Client` | Authenticated AIMA client |
| `userId`  | `string` | User identifier           |
| `labelId` | `number` | Label identifier          |

---

### setServicesStatus

```ts
setServicesStatus(client: Client, profileId: string, servicesUpdate: ServicesUpdate): Promise<void>
```

Updates service statuses for a profile.

| Param            | Type             | Description               |
| ---------------- | ---------------- | ------------------------- |
| `client`         | `Client`         | Authenticated AIMA client |
| `profileId`      | `string`         | Profile identifier        |
| `servicesUpdate` | `ServicesUpdate` | Service status changes    |

---

### registerUserToService

```ts
registerUserToService(client: Client, entityId: string, serviceId: string): Promise<void>
```

Registers an entity to a service. Required for private services; optional for public ones.

| Param       | Type     | Description               |
| ----------- | -------- | ------------------------- |
| `client`    | `Client` | Authenticated AIMA client |
| `entityId`  | `string` | Entity identifier         |
| `serviceId` | `string` | Service identifier        |

---

### updateProfilePersonalInfo

```ts
updateProfilePersonalInfo(client: Client, userId: string, profileId: string, actions: PatchAction<ProfilePaths>[]): Promise<void>
```

Updates profile personal information using JSON Patch format.

| Param       | Type                          | Description               |
| ----------- | ----------------------------- | ------------------------- |
| `client`    | `Client`                      | Authenticated AIMA client |
| `userId`    | `string`                      | User identifier           |
| `profileId` | `string`                      | Profile identifier        |
| `actions`   | `PatchAction<ProfilePaths>[]` | JSON Patch operations     |

---

### updateUser

```ts
updateUser(client: Client, id: string, user: UserUpdateBody): Promise<User>
```

Updates user account fields. Accepted fields: `locale`, `accountStatus`, `dataPrivacyConsent`, `marketingConsent`, `surveyConsent`, `shareDataConsent`, `profilingConsent`, `membershipNumber`.

| Param    | Type             | Description               |
| -------- | ---------------- | ------------------------- |
| `client` | `Client`         | Authenticated AIMA client |
| `id`     | `string`         | User identifier           |
| `user`   | `UserUpdateBody` | Fields to update          |

---

### updateUserPersonalInfo

```ts
updateUserPersonalInfo(client: Client, userId: string, actions: PatchAction<UserPaths>[]): Promise<void>
```

Updates user personal information via JSON Patch on `/phoneNumber`, `/email`, or `/idNumber`.

| Param     | Type                      | Description               |
| --------- | ------------------------- | ------------------------- |
| `client`  | `Client`                  | Authenticated AIMA client |
| `userId`  | `string`                  | User identifier           |
| `actions` | `PatchAction<UserPaths>[]`| JSON Patch operations     |

---

### getEntity

```ts
getEntity(client: Client, entityId: string): Promise<Entity>
```

Returns a user entity by ID.

| Param      | Type     | Description               |
| ---------- | -------- | ------------------------- |
| `client`   | `Client` | Authenticated AIMA client |
| `entityId` | `string` | Entity identifier         |

---

### getFleetBillingGroups

```ts
getFleetBillingGroups(client: Client, options?: PaginableOptions): Promise<PaginableResponse<BillingGroup>>
```

Returns paginated billing groups for the fleet.

| Param     | Type              | Description               |
| --------- | ----------------- | ------------------------- |
| `client`  | `Client`          | Authenticated AIMA client |
| `options` | `PaginableOptions`| Pagination options        |

---

### getUsersByIds

```ts
getUsersByIds(client: Client, ids: string[]): Promise<User[]>
```

Batch-fetches users by their IDs.

| Param    | Type       | Description               |
| -------- | ---------- | ------------------------- |
| `client` | `Client`   | Authenticated AIMA client |
| `ids`    | `string[]` | User identifiers          |

---

### getUsers

```ts
getUsers(client: Client, options?: PaginableOptions<UserFilters, UserSort>): Promise<PaginableResponse<UserStatus>>
```

Returns a paginated list of users with optional filters and sort.

| Param     | Type                                      | Description               |
| --------- | ----------------------------------------- | ------------------------- |
| `client`  | `Client`                                  | Authenticated AIMA client |
| `options` | `PaginableOptions<UserFilters, UserSort>` | Pagination, filters, sort |

---

### getServiceRegistrationOverview

```ts
getServiceRegistrationOverview(client: Client, userIds: string[]): Promise<UserServiceRegistrationOverview[]>
```

Batch-fetches service registration status for multiple users.

| Param     | Type       | Description               |
| --------- | ---------- | ------------------------- |
| `client`  | `Client`   | Authenticated AIMA client |
| `userIds` | `string[]` | User identifiers          |

---

### requestServiceRegistration

```ts
requestServiceRegistration(client: Client, profileId: string, serviceId: string): Promise<string>
```

Requests service registration for a profile. Returns the registration request ID.

| Param       | Type     | Description               |
| ----------- | -------- | ------------------------- |
| `client`    | `Client` | Authenticated AIMA client |
| `profileId` | `string` | Profile identifier        |
| `serviceId` | `string` | Service identifier        |

## Types

### User

Key fields: `fleetId`, `id`, `registrationDate`, `agreements[]`, `profiles[]`, `dataPrivacyConsent`, `marketingConsent`.

### BillingGroup

```ts
{
    id: string;
    fleetId: string;
    name: string;
    discount: number;
    overMileageCap: number;
    overMileageRate: number;
}
```

### ServicesUpdate

```ts
{
    disableEmailNotification: boolean;
    operatorProfileId: string;
    actions: {
        reasonForChange: string;
        serviceId: string;
        status: string;
    }[];
}
```

### Other exported types

`UserProfile`, `Entity`, `Label`, `PersonalInformationUser`, `PersonalInformationProfile`, `UserServiceRegistration`, `UserServiceRegistrationOverview`, `UserFilters`, `UserSort`, `UserStatus`, `ResponseFind`, `CreateUser`, `CreateUserOptions`, `UserUpdateBody`.