bbj/documentation/docs/validation.md

## Implementing good sanity checks in your client.

The server has an endpoint called `db_validate`. What this does is take
a `key` and a `value` argument, and compares `value` to a set of rules specified by
`key`. This is the same function used internally by the database to check
values before committing them to the database. By default it returns a
descriptive object under `data`, but you can specify the key/value pair
`"error": True` to get a standard error response back. A standard call
to `db_validate` will look like this.

```
{
    "key": "title",
    "value": "this title\nis bad \nbecause it contains \nnewlines"
}
```

and the server will respond like this when the input should be corrected.

```
{
    "data": {
        "bool": False,
        "description": "Titles cannot contain whitespace characters besides spaces."
    },
    "error": False,
    "usermap": {}
}
```

if everything is okay, the data object will look like this instead.

```
    "data": {
        "bool": True,
        "description": null
    },
```

Alternatively, you can supply `"error": True` in the request.

```
{
    "error": True,
    "key": "title",
    "value": "this title\nis bad \nbecause it contains \nnewlines"
}
// and you get...
{
    "data": null,
    "usermap": {},
    "error": {
        "code": 4,
        "description": "Titles cannot contain whitespace characters besides spaces."
    }
}
```

The following keys are currently available.

  * "user_name"
  * "auth_hash"
  * "quip"
  * "bio"
  * "title"
  * "body"
  * "color"

The descriptions returned are friendly, descriptive, and should be shown
directly to users


By using this endpoint, you will never have to validate values in your
own code before sending them to the server. This means you can do things
like implement an interactive prompt which will not allow the user to
submit it unless the value is correct.

This is used in the elisp client when registering users and for the thread
title prompt which is shown before opening a composure window. The reason
for rejection is displayed clearly to the user and input window is restored.

```lisp
(defun bbj-sane-value (prompt key)
  "Opens an input loop with the user, where the response is
passed to the server to check it for validity before the
user is allowed to continue. Will recurse until the input
is valid, then it is returned."
  (let* ((value (read-from-minibuffer prompt))
         (response (bbj-request! 'db_validate 'value value 'key key)))
    (if (alist-get 'bool response)
        value ;; return the user's input back to the caller
      (message (alist-get 'description response))
      (sit-for 2)
      (bbj-sane-value prompt key))))
```