{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/control",
  "slug": "services/control",
  "kind": "capabilities",
  "bucket": "package",
  "title": "@leumas/control",
  "name": "@leumas/control",
  "eyebrow": null,
  "chip": null,
  "summary": "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...",
  "keywords": [
    "control",
    "vendor-only",
    "staffplane",
    "requirestaff",
    "independent gates",
    "control api",
    "leumas control",
    "tech"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# @leumas/control\n\nThe vendor-only API behind `admin.leumas.tech`. Mounted at `/control` **only** where\n`caps.staffPlane` — see [CONTROL-PLANE.md](../../../CONTROL-PLANE.md) §7.\n\n```js\nif (caps.staffPlane) app.use('/control', createControlRouter({ requireStaff }));\n```\n\n## Two independent gates\n\n1. **The mount is conditional.** On `platform` and `appliance` these paths do not exist at all.\n2. **`requireStaff` runs on every route** via `router.use`, so a new route is gated by default.\n\n`requireRole('admin')` is **not** a substitute: it short-circuits on `isAdmin`, and on an appliance\nthe *customer* holds admin.\n\n## Endpoints\n\n| Route | Returns |\n|---|---|\n| `GET /control/overview` | the pulse — accounts · membership + MRR · fleet · moderation · wallet · billing. `?force=1` bypasses the 30s cache |\n| `GET /control/whoami` | plane + staff identity; the console's boot check |\n\n## Design rules\n\n- **Counts, not rows.** `/overview` returns magnitudes only — no emails, no licence keys. It is the\n  most-requested endpoint in the console, so it holds nothing worth stealing.\n- **One aggregation, not N.** Eight deck tiles from one request, so the numbers agree with each other.\n- **Tolerant.** Every block is independently caught and reports `null` on failure. A control plane\n  whose home page 500s because one table is mid-migration is one you cannot use to find out what broke.\n- **MRR is derived from `PLAN_CATALOG`**, which is config not a table — the only honest source. A\n  membership on an unknown plan contributes 0 and is counted in `unpriced`, visibly.\n\n## Adding a route\n\nAdd it to `src/router.js` below the `router.use(requireStaff)` line, then add an assertion to\n`ops/infra/scripts/check-staff-boundary.mjs`.\n",
  "source": {
    "path": "shared/services/control/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 1944,
    "hash": "4f330158ed379fc3e94fc48a1e0c2c9abf198057"
  },
  "urls": {
    "html": "/p/services/control",
    "json": "/docs/services/control.json",
    "md": "/docs/services/control.md"
  },
  "links": {
    "composes": [
      "pkg:@leumas/architecture-graph",
      "pkg:@leumas/auth",
      "pkg:@leumas/db",
      "pkg:@leumas/schemas"
    ],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  },
  "exports": null
}