# `Weavr.Users`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr/resources/users.ex#L1)

Users and Authorised Users.

All paths and the root-user-vs-authorised-user distinction are verified
against Weavr's published documentation.

## Critical distinction

`GET /users` returns **all** users including root users. However,
**modification operations** (create, update, activate, deactivate) on
`/users` endpoints **only apply to Authorised Users**.

To modify root user details, use `Weavr.Corporates.update/3` or
`Weavr.Consumers.update/3`.

## Confirmed endpoints

  * `GET    /users` — list all users (including root users)
  * `GET    /users/{id}` — get a user
  * `POST   /users` — create an authorised user
  * `PATCH  /users/{id}` — update an authorised user
  * `POST   /users/{id}/activate` — activate an authorised user
  * `POST   /users/{id}/deactivate` — deactivate an authorised user
  * `POST   /users/{id}/invite/send` — send (or resend) an invite
  * `POST   /users/{id}/enrolment/send` — send enrolment (mobile OTP setup)

# `activate`

```elixir
@spec activate(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Activates an authorised user. `POST /users/{id}/activate`.

# `create`

```elixir
@spec create(Weavr.Config.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Creates an authorised user under the current identity.

`POST /users`

Key fields in `attrs`:
- `"name"`, `"surname"`, `"email"` — required
- `"mobile"` — object with `"countryCode"` and `"number"`
- `"tag"` — optional custom searchable field

# `deactivate`

```elixir
@spec deactivate(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Deactivates an authorised user. `POST /users/{id}/deactivate`.

# `get`

```elixir
@spec get(Weavr.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Fetches a user (root or authorised) by id. `GET /users/{id}`.

# `list`

```elixir
@spec list(
  Weavr.Config.t(),
  keyword()
) :: {:ok, map()} | {:error, Weavr.Error.t()}
```

Lists all users for the authenticated identity, including root users.

`GET /users` — supports `opts[:filters]` as query params
(e.g. `offset`, `limit`, `email`, `active`, `createdFrom`, `createdTo`, `tag`).

# `send_enrolment`

```elixir
@spec send_enrolment(Weavr.Config.t(), String.t(), map(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Sends an enrolment (mobile OTP device setup) notification to the user.

`POST /users/{id}/enrolment/send` — pass `"channel"` in `attrs`
(e.g. `%{"channel" => "SMS"}` or `%{"channel" => "AUTHY"}`).

# `send_invite`

```elixir
@spec send_invite(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Sends (or re-sends) an invite to an authorised user.

`POST /users/{id}/invite/send`

# `update`

```elixir
@spec update(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Updates an authorised user's details. `PATCH /users/{id}`. Does not work on root users.

---

*Consult [api-reference.md](api-reference.md) for complete listing*