# `Sofa.User`
[🔗](https://github.com/skunkwerks/sofa/blob/0.5.1/lib/sofa/user.ex#L1)

Documentation for `Sofa.User`, a test-driven idiomatic Apache CouchDB client.

> If the only tool you have is CouchDB, then
> everything looks like `{:ok, :relax}`

The User module provides simple wrappers around the usual Sofa.DB and
Sofa.Doc functions, specifically for the `_users` DB.

You need appropriate permissions for this to work - either as administrator,
or alternatively, if your user/group have permissions *and* your `local.ini`
has `users_security_editable = true` set in `[couchdb]` section. If you
use a group to assign permissions, `users` is a good choice.

# `generate_random_secret`

```elixir
@spec generate_random_secret(integer()) :: String.t()
```

Generate small, random secret of length 16-64 characters inclusive,
using base64 encoding, suitable for CouchDB default user passwords.

## Examples

    > Sofa.User.generate_random_secret()
    "E3gZtvNhF7pkHpeyoPjMnfRJidI5nRHD/MeRPR11jMKBxcMUXl75U8msnRj1bG/R"

# `get`

```elixir
@spec get(Sofa.t(), String.t()) :: {:error, any()} | Sofa.Doc.t()
```

GET doc and returns standard HTTP status codes, or the user doc

- `{:error, :not_found}` - doc doesn't exist
- `%Sofa.Doc{}` - doc exists and has metadata

# `new`

```elixir
@spec new(String.t(), String.t(), [String.t()]) :: Sofa.Doc.t()
```

Create a new _user Sofa.Doc with the usual attributes per

  # https://docs.couchdb.org/en/stable/intro/security.html?highlight=_users#creating-a-new-user

    { _id: "org.couchdb.user:jan",
      "name": "jan",
      "password": "apple",
      "roles": ["chair"],
      "type": "user"
    }

## Examples

    iex> Sofa.User.new("jan", "apple", ["pointy_hat", "users"])

    %Sofa.Doc{
      attachments: %{},
      body: %{"name" => "jan", "password" => "apple", "roles" => ["pointy_hat", "users"]},
      id: "org.couchdb.user:jan",
      rev: nil,
      type: :user
    }

# `put`

```elixir
@spec put(Sofa.t(), Sofa.Doc.t()) :: {:ok, Sofa.Doc.t()} | {:error, any()}
```

PUT a valid Sofa.Doc with user attributes into the `/_users` DB.

If `doc.body.password` is supplied, remove hash info and update password.

# `reset_password`

```elixir
@spec reset_password(Sofa.Doc.t(), String.t()) :: Sofa.Doc.t()
```

Resets user password. NB you still need to write this doc to CouchDB.

---

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