# @leumas/control

Leumas Control — the vendor-only read/write API behind admin.leumas.tech. Mounted at /control ONLY where caps.staffPlane; every route behind requireStaff. Adds no data of its own — it is a window...


The vendor-only API behind `admin.leumas.tech`. Mounted at `/control` **only** where
`caps.staffPlane` — see [CONTROL-PLANE.md](../../../CONTROL-PLANE.md) §7.

```js
if (caps.staffPlane) app.use('/control', createControlRouter({ requireStaff }));
```

## Two independent gates

1. **The mount is conditional.** On `platform` and `appliance` these paths do not exist at all.
2. **`requireStaff` runs on every route** via `router.use`, so a new route is gated by default.

`requireRole('admin')` is **not** a substitute: it short-circuits on `isAdmin`, and on an appliance
the *customer* holds admin.

## Endpoints

| Route | Returns |
|---|---|
| `GET /control/overview` | the pulse — accounts · membership + MRR · fleet · moderation · wallet · billing. `?force=1` bypasses the 30s cache |
| `GET /control/whoami` | plane + staff identity; the console's boot check |

## Design rules

- **Counts, not rows.** `/overview` returns magnitudes only — no emails, no licence keys. It is the
  most-requested endpoint in the console, so it holds nothing worth stealing.
- **One aggregation, not N.** Eight deck tiles from one request, so the numbers agree with each other.
- **Tolerant.** Every block is independently caught and reports `null` on failure. A control plane
  whose home page 500s because one table is mid-migration is one you cannot use to find out what broke.
- **MRR is derived from `PLAN_CATALOG`**, which is config not a table — the only honest source. A
  membership on an unknown plan contributes 0 and is counted in `unpriced`, visibly.

## Adding a route

Add it to `src/router.js` below the `router.use(requireStaff)` line, then add an assertion to
`ops/infra/scripts/check-staff-boundary.mjs`.


---
Source: shared/services/control/README.md
Canonical: https://docs.leumas.tech/p/services/control