# Visitor rules

<!-- docs-test setup: owner -->

Visitor rules decide who a request is (a person, a bot, or a browser not yet shown to be either; the site's own or
not; which bot, of what type, run by whom) and what happens to it: whether it is let in, and where it is counted.
How they work is in [Visitor rules](../visitor-rules.md). Your account's rules are one versioned whole: reading needs
`bot:read`, changing `bot:write` with a token that is not limited to some sites. A preview also needs
`analytics:read`.

| Route | Scope |
|---|---|
| `GET /v1/rules` | `bot:read` |
| `PUT /v1/rules` | `bot:write` |
| `GET /v1/rules/library` | `bot:read` |
| `POST /v1/rules/upgrade` | `bot:write` |
| `GET /v1/rules/history` | `bot:read` |
| `GET /v1/rules/history/{version}` | `bot:read` |
| `POST /v1/rules/restore` | `bot:write` |
| `POST /v1/rules/preview` | `bot:read` |
| `GET /v1/sites/{id}/rules` | `bot:read` |

## Your rules

A new account runs the Recommended pack: every rule UsherStats has measured on real sites, each one switchable and
with its thresholds as parameters you can set.

```sh
curl https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200; VERSION=.version -->

The answer is `version`, `state` and `updates`. `state` holds:

- `refs`: the library rules you have, each `{id, version, enabled, params}`. A library rule is referenced, never
  copied: it changes only when you apply an update.
- `custom`: your own rules, each `{id, enabled, mode, sites, rule}`. `id` is `own:` and letters, digits or `-`;
  `sites` is `null` for every site or a list; `mode` is `log` (watched: shown, not applied) until you set `on`.
- `policy`: `analytics` (where each kind of visitor is counted: `people`, `crawlers`, `internal-people`,
  `internal-agents` or `excluded`) and `access` (`allow`, `challenge` or `block`), each by target -- `person`,
  `unproven`, `internal-person`, `internal-agent`, `bot`, `unknown-bot`, `type:<type>`, `company:<company>`,
  `name:<bot>`. The most specific target decides.
- `sites`: a site's own `policy` over yours, and the rules it switches `off` or `on` for itself.

## Changing them

`PUT` replaces the whole state, made from the version you read as `expect`. Here a rule of your own -- browsers whose
clock is in one time zone -- in log mode, and OpenAI's crawlers left out of the counts:

```sh
curl -X PUT https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expect": 1, "state": {"custom": [{"id": "own:fleet", "mode": "log", "rule": {"name": "The Shanghai-clock fleet", "priority": 650, "when": {"all": [{"signal": "tz", "op": "eq", "value": "Asia/Shanghai"}, {"signal": "interacted", "op": "is", "value": false}]}, "then": {"actor": "bot", "type": "proxy-fleet"}}}], "policy": {"analytics": {"company:openai": "excluded"}}}}'
```
<!-- expect 200 -->

Every save is a new version, kept, with the change in words. A save made from an older version than the one stored
is `409`: someone saved since, so read them again and make the change on top. A rule a field of which cannot be
accepted is `400` with `field` naming it, and so is a set of rules whose analytics filter would grow past what
Analytics Engine takes:

```sh
curl -X PUT https://api.usherstats.com/v1/rules \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expect": 2, "state": {"custom": [{"id": "own:x", "rule": {"name": "bad", "priority": 1, "when": {"signal": "seconds", "op": "contains", "value": "x"}, "then": {"actor": "bot"}}}]}}'
```
<!-- expect 400 -->

## The library

Every managed rule and every version of it -- what it says, its parameters, where it can act (`server`, `requests`,
`pageviews`, `events`, `sessions`), its release notes -- the packs, and the signals and operators your own rules can
use:

```sh
curl https://api.usherstats.com/v1/rules/library \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

When UsherStats publishes a new version of a rule, `GET /v1/rules` lists it under `updates` and nothing changes until
you apply it -- all of them, or by id:

```sh
curl -X POST https://api.usherstats.com/v1/rules/upgrade \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apply": "all", "expect": 2}'
```
<!-- expect 200 -->

## History

Every version, newest first; one version whole; and going back to one, which saves its rules as a new version:

```sh
curl https://api.usherstats.com/v1/rules/history \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

```sh
curl https://api.usherstats.com/v1/rules/history/1 \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

```sh
curl -X POST https://api.usherstats.com/v1/rules/restore \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1, "expect": 3}'
```
<!-- expect 200 -->

## What one site runs

A site's rules in the order they are decided -- from the library, from your account, from the site's own settings --
each with where it can act, the policy the site applies, and the rules only being watched:

```sh
curl https://api.usherstats.com/v1/sites \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "hostnames": ["shop.example"]}'
```
<!-- expect 201; SITE_ID=.site.id -->

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/rules \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

## Before you save: a preview

What a state would do to your counts, before it is saved: each site's pageviews and requests in each lane over the
last 7 or 30 days, under the rules in force and under these, and the human pageviews where the reader scrolled, clicked
or typed -- the people a change would move.

```sh
curl -X POST https://api.usherstats.com/v1/rules/preview \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": 7, "state": {"refs": [{"id": "clock-elsewhere", "version": 1, "enabled": false}]}}'
```
<!-- expect 200 -->
