@uniweb/api 1.1.1 → 1.2.1

package/README.md

@@ -52,13 +52,16 @@ function Account() {
 ```
 
 `viewer` is flat — `viewer.uuid`, `viewer.username`, `viewer.handle`, and `viewer.roles`,
-a list of `{ role, scope_unit_id }`. ⭐ **Roles describe the session, and a session
-signed in on a site holds a member's rights — the operator's too.** A site runs your
-foundation's code with the signed-in member's session, so no administrator's role
-rides with it: `viewer.roles` never names one there, and an ordinary member holds none
-(`[]`). `viewer.workspace` — the site service's home org, `{ handle: 'home', … }` — is
-the same for everyone. To decide whether to show an edit control for a particular
-record, read that record: `entity.can_edit` is the backend's own answer.
+a list of `{ role, scope_unit_id }`. ⭐ **Roles describe the session, and on a site a
+session holds the account's roles as a reader's until it is elevated.** A site runs
+your foundation's code with the signed-in member's session, so an administrator signed
+in on it reads what their role reaches — the operator reads every member's content —
+and changes nothing through the role until they confirm it is them (*Acting as an
+administrator*, below). Their own content they edit, delete and share as always. An
+ordinary member holds no role (`[]`). `viewer.workspace` — the site service's home org,
+`{ handle: 'home', … }` — is the same for everyone. To decide whether to show an edit
+control for a particular record, read that record: `entity.can_edit` is the backend's
+own answer.
 
 **Signing up** — `useSignUp().signUp({ username, email, password })` answers
 `{ status: 'verification_required', email }`, the same answer for an address already in
@@ -146,6 +149,42 @@ function Invitations() {
 - ⭐ Draw it wherever a signed-in member lands, not only after an `?offer=` link: an
   invitation sent to an account comes with no link to follow.
 
+**Acting as an administrator** — an administrator on the site reads what their role
+reaches; to change something through it — remove a member's post, grade a submission —
+they confirm it is them, and for a while the session acts through the role.
+`useElevation()` offers it:
+
+```jsx
+import { useElevation } from '@uniweb/api'
+
+function AdminMode() {
+  const { available, elevated, until, elevate, lower, error } = useElevation()
+  if (!available) return null
+  if (elevated) {
+    return <p>Acting as administrator until {new Date(until).toLocaleTimeString()}. <button onClick={lower}>Stop</button></p>
+  }
+  return <ConfirmItsYou onSubmit={(password, code) => elevate({ password, code })} refused={error?.kind === 'auth'} />
+}
+```
+
+- `available` — the account holds a role that does more than read. Offer it only then.
+- `elevate({ password, code })` — the account's password again, and `code` when it has a
+  second factor. Nothing tells you whether it has one, so offer the field to whoever
+  might. A wrong password or code is `error.kind === 'auth'`, one answer for both.
+- It lasts as long as the backend decides; `until` says when it ends. `elevated` turns
+  false by itself then, and the session is asked again. Elevating again starts the time
+  again; nothing extends it on its own. `lower()` ends it early.
+- While it lasts, `viewer.roles` names the role, and every record read before is read
+  again — `entity.can_edit` is the record's answer for the session as it is now.
+- `rolesInFull` — draw controls that act through a role from this: true while elevated,
+  and always on a backend that asks for no elevation.
+- An account with no password elevates through its provider:
+  `elevateWithProvider('google')` goes to the provider's sign-in and back to this page.
+  If the identity that comes back is not this account's, `error.extensions.reason` is
+  `'oauth_step_up_not_linked'`.
+
+Elevating does not open the backend's administration — the Admin link does.
+
 **The Admin link** — some of the site's members administer its backend, the operator
 among them. For them, `adminHref` is the address that takes them to the backend's
 administration, already signed in; for everyone else it is `null`, so draw the link
@@ -160,8 +199,8 @@ const { adminHref } = useSession()
 ⛔ **Navigate to it — a link, or `location.assign(adminHref)` — never `fetch` it.** It
 answers with a redirect carrying a one-time credential that no script on the site is
 to hold. The link decides what to offer, not what is allowed: on the site, an
-administrator's session acts as a member's, and administering happens at the other
-end of the link.
+administrator's session acts through their role only while elevated, and administering
+the backend happens at the other end of the link.
 
 ## Reading
 
@@ -178,10 +217,10 @@ live source — no `backend` service, or nobody signed in — so render your sit
 Showing "nothing yet" for the first case tells a visitor their content is missing
 when it is simply not being asked for.
 
-**Whose records.** Everyone signed in on the site — its operator too — reads their own
-entities and what was shared with them; other members' are private unless the site's
-service was set up to let members read each other's. `scope: 'mine'` lists only the
-viewer's own.
+**Whose records.** Everyone signed in on the site reads their own entities, what was
+shared with them, and what a role of theirs reaches — the operator's reaches every
+member's; other members' are private unless the site's service was set up to let members
+read each other's. `scope: 'mine'` lists only the viewer's own.
 
 A record is a summary: `record.brief` holds the fields of the Model's brief section. It
 carries no items — read the entity for those. `hasMore` is true when a page came back
@@ -205,6 +244,54 @@ the item.
 Its `absent` covers both not-found and not-permitted, on purpose: render your paywall
 or sign-in prompt on it and never say "deleted".
 
+### A Model's definition — what a form is built from
+
+```jsx
+import { useDefinition } from '@uniweb/api'
+
+const { status, definition } = useDefinition('@acme/cv')
+const brief = definition?.sections.find((s) => s.brief)
+// brief.fields → [{ key: 'title', kind: 'string', required: true, label: 'Title', max_length: 250 }, …]
+```
+
+Each field is its declaration as the backend stores it — `key`, `kind`, `required`,
+`multi`, and what the schema declares: `label`, `description`, `localized`, `format`,
+`max_length`, `min`, `max`, and `enum`. Each section is `{ name, path, kind, brief,
+fields, rules }`, plus its `label` and `description`; `path` is the name a write takes,
+`parent/child` for a nested section. ⭐ **These are the rules every write is checked
+against**, so a form that reads them checks what the backend will. `readDefinition({
+schema })` is the same outside React.
+
+### A field's choices
+
+A field that picks from a list — in a schema, `type: item_ref` with `options:` naming a
+section of a lists type — stores the uuid of the item chosen. Its choices are that
+section's items:
+
+```jsx
+import { useChoices } from '@uniweb/api'
+
+const { items, hasMore } = useChoices({ schema: '@acme/cv', field: 'country', q, searchIn: 'label' })
+// items[i].uuid — the value to store; items[i].data — the choice, in the site's language
+
+// a dependent list: the provinces of the country chosen above
+const provinces = useChoices(country ? { schema: '@acme/cv', field: 'province', parent: country } : null)
+```
+
+- **A page at a time** — `limit`, 50 by default and at most 1000; pass `nextCursor` back as
+  `cursor`. ⚠️ A searched page can be short while more follow: `hasMore` is the end, never
+  the page's length.
+- **A search** — `q` anywhere in the choices' field `searchIn`, ignoring case; a
+  localized field in the site's language.
+- **One level at a time** — `parent` reads the items under one item: the next level of a
+  list whose items nest (each says `has_children`), or a dependent field's choices under
+  the item chosen in the field it depends on.
+- **Whose lists** — the items of every entry of the lists type the viewer may read.
+- **Read back**, the field answers `{ item, brief }`: the chosen item's uuid and its data.
+
+`listChoices` is the same outside React, and `listSectionItems({ section })` reads a
+section by its uuid.
+
 ## Writing
 
 An entity's content is **items, each in a section** of its Model. A section that holds
@@ -258,6 +345,80 @@ Every failure is an `ApiError` with a `kind`: `auth` (sign in), `unverified`, `a
 (`error.extensions.field` names a field the Model refused), `conflict`, `rule`,
 `rate-limited`, `unavailable`, `disabled`. Branch on `kind`; `detail` is prose.
 
+## Rules, lists, and what stays in your foundation
+
+The backend checks every write against the Model's declaration, and refuses to register
+a schema with a declaration it does not take. So where a rule is written decides who
+keeps it.
+
+### On a field — checked on every write
+
+| declare | the backend |
+|---|---|
+| `required: true` | refuses a write without the field |
+| `max_length` on `string`, `text` | counts characters — each language of a localized value on its own |
+| `min`, `max` on `int`, `decimal` | refuses a value outside them |
+| `format` — `email`, `url` on `string` and `text`; `currency` on `string`; `markdown`, `html` on `text` | checks `email`, `url` and `currency` (an ISO 4217 code); `markdown` and `html` mark what the text is |
+| `localized: true` on text | holds one string for every language, or one per language |
+| `enum: [...]` | keeps the field to those values — in the definition, as its section's `one_of` rule |
+| `type: item_ref`, `options: '@acme/lists/countries'` | keeps the value to an item of that section — an item of another is `409`, `kind: 'rule'` |
+
+A refused value is `kind: 'invalid'`, its `extensions` naming the field (`data.title`,
+`data.label.fr` for one language), the `rule` it broke and the bound
+(`{ rule: 'max_length', max_length: 250 }`). ⚠️ An `enum`'s refusal, `rule: 'one_of'`,
+names its field only in `detail`.
+
+⛔ **A declaration the backend does not take refuses the whole schema** when it reaches
+the backend, naming the field and the key: a `format` its kind does not have
+(`year-month` on a `date`, `year` on an `int`), a key it does not know (`help`), or one it
+does not check yet (`pattern`, `min_length`).
+
+⚠️ **A `date` is a calendar day**, `YYYY-MM-DD`: `2024-05` is refused. A year alone is an
+`int`, with `min` and `max`.
+
+### On a section — rules across fields, and across items
+
+A section's `constraints` — a list of rules, in its definition as `rules`:
+
+| rule | keeps |
+|---|---|
+| `{ kind: 'exclusive', fields: [...] }` | at most one of the fields set — "another organization" beside a picked one |
+| `{ kind: 'required_one_of', fields: [...] }` | at least one of them set |
+| `{ kind: 'required_when', field, when: { field, equals } }` | the field set whenever another field equals a value |
+| `{ kind: 'field_order', before, after }` | one date no later than another |
+| `{ kind: 'unique_field', field }`, `{ kind: 'unique_combination', fields }` | a value — or values together — once among an entry's items in the section |
+| `{ kind: 'max_items', value }`, `{ kind: 'min_items', value }` | how many items the section holds — `min_items` refuses a delete below it, and does not make anyone add one |
+| `{ kind: 'show_when', field, when: { field, equals } }` | nothing: when a form shows a field — read it from the definition |
+
+### Shared lists
+
+Put the lists your fields pick from in **one lists type, a section per list** — not a
+type per list — and its entries where the people who should see them can read them.
+Then:
+
+- **A field that picks from one** is `type: item_ref` with `options:` naming its section
+  (`'@acme/lists/countries'`, a nested one by its path), and `useChoices` offers it.
+- **A list too long for a dropdown** is searched: `q` with `searchIn`, a page at a time.
+- **A dependent list** — a country, then one of its provinces — is a section nested in
+  the other: `countries` holding `subdivisions`, a field picking from each. The second
+  field's choices are `useChoices({ …, parent: country })`, and it holds only a province.
+- **A list in levels** — a discipline, then its branches — is a section whose items nest
+  (`self_nesting: true`): read it a level at a time with `parent`.
+- **A list people may add to** is one they may edit: who may write an entry's items is
+  who may edit the entry. They add a choice with `useEntityWriter` on the lists entry,
+  and `refresh()` reads the choices again.
+
+### What stays in your foundation
+
+The backend keeps content and checks it. How a field is edited is your foundation's — the
+toolbar of a rich text field, a default for a new entry, a field shown read-only, an
+autocomplete, a value computed from others (a currency converted, shares summed to 100
+before an entry is complete). None of these is a declaration the backend keeps.
+
+⭐ **Who may change a field is who may edit its entry** — the backend decides access per
+entry, never per field. A field only some people may change belongs on an entry only they
+edit.
+
 ## The service on your machine
 
 Building against a live service is slow and puts a shared database behind your
@@ -304,13 +465,16 @@ production, and nothing in your site's configuration changes between the two.
 
 ⭐ **The mock answers what the backend answers** — the same statuses, bodies and
 refusals, for every route this package uses. It enforces what your schemas declare —
-which sections are insert-only, the fields a section takes — and it is as strict as
-the backend about requests, so a mistake fails here rather than in front of a user.
-Everyone signed in — the operator too, as on a real site — reads and writes their own
-entities and nothing of anyone else's (`memberFloor: 'read'` in the seed models a
-service set up to let members read each other's — or per Model,
-`memberFloor: { '@acme/course': 'read' }`, so the operator's content is shared while
-each member's own records stay private). The mail the backend would send — a sign-up's
+which sections are insert-only, the fields a section takes and their rules (`required`,
+`max_length`, `min` and `max`, a date's form, an `enum`, the `email` and `url` formats, a
+choice from a list) — and it is as strict as the backend about requests, so a mistake
+fails here rather than in front of a user.
+Everyone signed in reads and writes their own entities, and a member nothing of anyone
+else's (`memberFloor: 'read'` in the seed models a service set up to let members read
+each other's — or per Model, `memberFloor: { '@acme/course': 'read' }`, so the
+operator's content is shared while each member's own records stay private). The
+operator, as on a real site, reads every member's entities and changes them only once
+elevated, with its password, for fifteen minutes. The mail the backend would send — a sign-up's
 confirmation, a password reset — is printed where the mock runs, in the terminal of
 `uniweb dev`, its link on your site's root as the backend's is, so following it is
 trying your page; the messages are in `mock.outbox` too. To try an invitation, seed one:
@@ -321,6 +485,20 @@ from the start.
 The operator's Admin link answers too, landing on a page of the mock's own — the backend's
 administration is not part of it. State is in memory: restart to reset.
 
+Write a seed's schemas as you write them for a backend — `type: 'int'`, `multiple: true`,
+`options:` — and the mock's definition answers what a backend keeps of them, so a key no
+backend takes is left out of it (a backend refuses it when you register). Seed a list's
+choices as items of a lists entry, each item holding the items that sit under it:
+
+```js
+{ section: 'countries', data: { code: 'CA', label: { en: 'Canada' } }, items: [
+  { section: 'countries/subdivisions', data: { name: { en: 'Ontario' } } },
+] }
+```
+
+A field whose `options:` names no section of a seeded Model is reported when the mock
+starts, and offers no choices — a backend refuses to register it.
+
 There is also a standalone server, for a frontend that is not a Uniweb site — `--site`
 names that frontend's origin, where the mail's links land:
 
@@ -332,7 +510,8 @@ npx uniweb-api-mock --port 8787 --site http://localhost:3000
 
 `@uniweb/api/client` carries the same operations as plain functions and imports no
 React: `probeSession`, `signIn`, `listEntities`, `readEntity`, `writeItems`,
-`createEntity`, `deleteEntity`, `adminHref`, for the links the backend mails,
+`createEntity`, `deleteEntity`, `adminHref`, for elevation, `elevate`, `lower`,
+`elevateWithProvider`, `isElevated` and `rolesInFull`, for the links the backend mails,
 `mailedLink`, `verifyEmail`, `claimOffer` and `forgetMailedLink`, and for invitations,
 `listInvitations`, `acceptInvitation` and `declineInvitation`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@uniweb/core": "~1.1.0"
+    "@uniweb/core": "~1.2.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/client.js

@@ -15,10 +15,11 @@ import { getUniweb, deriveCacheKey } from '@uniweb/core'
 import { resolveService } from '@uniweb/core'
 import { ApiError } from './errors.js'
 import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
-import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP, VIEWER } from './wire.js'
+import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, SECTION_ITEMS, PAGE, TOTP, VIEWER } from './wire.js'
 import { Ledger } from './ledger.js'
 import { verifyEmailWith, claimOfferWith } from './mailed-links.js'
 import { listInvitationsWith, acceptInvitationWith, declineInvitationWith } from './invitations.js'
+import { viewerElevation, watchLapse, elevateWith, lowerWith, elevateWithProviderOf } from './elevation.js'
 
 /**
  * The site service this package reads its base from — the only name it owns.
@@ -140,6 +141,68 @@ function labelSections(items, sections) {
   }
 }
 
+/** The values a `one_of` rule allows — `values`, or the `options: [{ value, label }]` form's values. */
+function allowedValues(rule) {
+  if (Array.isArray(rule?.[SCHEMA.ruleValues])) return rule[SCHEMA.ruleValues]
+  if (Array.isArray(rule?.options)) return rule.options.map((o) => o?.value)
+  return []
+}
+
+/**
+ * A definition as a form reads it (`ApiClient.readDefinition`): each field its own
+ * declaration, its `enum` folded back from its section's `one_of` rule; each section
+ * with what the schema declares of it, its `path`, and its rules.
+ *
+ * @param {object} body - `GET /models/@scope/name`, as the backend answers it (`SCHEMA`)
+ */
+function formOf(body) {
+  const rows = Array.isArray(body?.[SCHEMA.sections]) ? body[SCHEMA.sections] : []
+  const byId = new Map(rows.map((s) => [s[SCHEMA.id], s]))
+  const pathOf = (row) => {
+    const names = []
+    const seen = new Set()
+    for (let at = row; at && !seen.has(at[SCHEMA.id]); at = byId.get(at[SCHEMA.parent])) {
+      seen.add(at[SCHEMA.id])
+      names.unshift(at[SCHEMA.name])
+    }
+    return names.join('/')
+  }
+  const sections = rows.map((row) => {
+    const declared = row?.[SCHEMA.constraints]?.[SCHEMA.rules]
+    const rules = Array.isArray(declared) ? declared : []
+    const enums = new Map(
+      rules
+        .filter((r) => r?.kind === SCHEMA.oneOf && typeof r[SCHEMA.ruleField] === 'string')
+        .map((r) => [r[SCHEMA.ruleField], allowedValues(r)]),
+    )
+    const fields = (Array.isArray(row?.[SCHEMA.fields]) ? row[SCHEMA.fields] : []).map((f) => {
+      const declaration = f?.[SCHEMA.fieldType]?.[SCHEMA.fieldDecl] ?? {}
+      const field = {
+        ...declaration,
+        key: f?.key ?? declaration.key,
+        kind: declaration.kind ?? f?.[SCHEMA.fieldType]?.kind,
+        required: f?.required === true || declaration.required === true,
+        multi: f?.multi === true || declaration.multi === true,
+      }
+      if (enums.has(field.key)) field.enum = enums.get(field.key)
+      return field
+    })
+    const other = row?.[SCHEMA.otherData]
+    return {
+      ...(other && typeof other === 'object' ? other : {}),
+      id: row[SCHEMA.id],
+      name: row[SCHEMA.name],
+      path: pathOf(row),
+      kind: row[SCHEMA.kind],
+      brief: row[SCHEMA.isBrief] === true,
+      parent: row[SCHEMA.parent] ?? null,
+      rules,
+      fields,
+    }
+  })
+  return { model: body?.model ?? null, sections }
+}
+
 export class ApiClient {
   /**
    * @param {object} uniweb - the page's `Uniweb` singleton
@@ -219,6 +282,8 @@ export class ApiClient {
     const error = next.error ?? null
     if (cur.status === next.status && cur.viewer === viewer && cur.error === error) return cur
     this._session = Object.freeze({ status: next.status, viewer, error })
+    // An elevated session is asked again when its elevation runs out (`./elevation.js`).
+    watchLapse(this)
     for (const fn of this._listeners) fn()
     return this._session
   }
@@ -356,6 +421,7 @@ export class ApiClient {
       roles: Array.isArray(me?.roles) ? me.roles : [],
       workspace: viewerWorkspace(me?.workspace),
       adminApp: me?.[VIEWER.capabilities]?.[VIEWER.adminApp] === true,
+      elevation: viewerElevation(me?.[VIEWER.elevation]),
     })
     if (this._session.viewer && this._session.viewer.uuid !== viewer.uuid) this.forgetViewer()
     return this.setSession({ status: 'authenticated', viewer, error: null })
@@ -427,6 +493,35 @@ export class ApiClient {
     }
   }
 
+  /**
+   * Elevate the session — `{ password, code? }` — so it acts through the account's roles
+   * for a while. Answers `{ until }`. A refused credential throws `kind: 'auth'`, one
+   * answer for a wrong password or code (`./elevation.js`).
+   *
+   * @param {{ password: string, code?: string }} credentials
+   * @returns {Promise<{ until: string|null }>}
+   */
+  elevate(credentials) {
+    return elevateWith(this, credentials)
+  }
+
+  /** Lower the session before its time runs out. */
+  lower() {
+    return lowerWith(this)
+  }
+
+  /**
+   * Elevate through the account's provider — a navigation to its sign-in, which comes
+   * back to the page elevated. For an account with no password.
+   *
+   * @param {string} provider
+   * @param {{ returnTo?: string }} [options]
+   * @returns {string|null} the address navigated to
+   */
+  elevateWithProvider(provider, options) {
+    return elevateWithProviderOf(this, provider, options)
+  }
+
   /**
    * Sign up — `{ username, email, password }`, passed through unchanged.
    *
@@ -688,9 +783,9 @@ export class ApiClient {
    * a `401` too, never an empty list (so `records: []` means empty).
    *
    * `scope` decides whose: the default, `accessible`, is everything the viewer may
-   * read — signed in on a site, their own entities and what was shared with them, the
-   * operator's session included (`VIEWER` in `./wire.js`). `mine` is only what the
-   * viewer owns.
+   * read — signed in on a site, their own entities, what was shared with them, and what
+   * a role of theirs reaches, elevated or not: the operator's, every member's (`SCOPE`
+   * in `./wire.js`). `mine` is only what the viewer owns.
    *
    * ## Paging, as far as it can honestly be absorbed
    *
@@ -737,23 +832,182 @@ export class ApiClient {
    */
   sections(schema, signal) {
     if (!schema) return Promise.reject(ApiError.invalid('No Model', 'sections needs a schema'))
-    const held = this._schemas.get(schema)
-    if (held) return held
-    const pending = this.request('GET', ROUTES.schema(schema), { signal }).then((body) =>
+    return this._definition(schema, signal).then((body) =>
       (Array.isArray(body?.[SCHEMA.sections]) ? body[SCHEMA.sections] : []).map((s) => ({
         id: s[SCHEMA.id],
         name: s[SCHEMA.name],
         parent: s[SCHEMA.parent] ?? null,
       })),
     )
+  }
+
+  /** Drop a Model's kept definition, so the next read asks the backend again. */
+  forgetDefinition(schema) {
+    this._schemas.delete(schema)
+  }
+
+  /** The definition as the backend answers it — read once per viewer, and kept. */
+  _definition(schema, signal) {
+    const held = this._schemas.get(schema)
+    if (held) return held
+    const pending = this.request('GET', ROUTES.schema(schema), { signal })
     this._schemas.set(schema, pending)
-    // A failure is not kept: the next write asks again.
+    // A failure is not kept: the next read asks again.
     pending.catch(() => {
       if (this._schemas.get(schema) === pending) this._schemas.delete(schema)
     })
     return pending
   }
 
+  /**
+   * A Model's definition — what an editor builds a form from.
+   *
+   * ```js
+   * const { sections } = await readDefinition({ schema: '@acme/cv' })
+   * const brief = sections.find((s) => s.brief)
+   * // brief.fields → [{ key: 'title', kind: 'string', required: true, label: 'Title', max_length: 250 }, …]
+   * ```
+   *
+   * Each section is `{ id, name, path, kind, brief, parent, rules, fields }` plus what the
+   * schema declares of it — `label`, `description`, `append_only`, `allow_self_nesting`:
+   * `path` is the name a write takes (`parent/child` for a nested section), `parent` the
+   * parent section's id, `rules` its rules (`[]` with none). Each field is its declaration
+   * as the backend stores it — `key`, `kind`, `required`, `multi`, and what it declares:
+   * `label`, `description`, `localized`, `format`, `max_length`, `min`, `max` — with
+   * `enum`, the values its section's `one_of` rule allows, when it has one. A field of
+   * kind `item_ref` is a choice from a list: `section_uuid` names the section whose items
+   * are its choices (`listChoices`), and `entity_uuid` the entry that holds them, when the
+   * field pins one. `model` is the Model's row.
+   *
+   * ⭐ **These are the rules the backend applies to every write**, so a form that reads
+   * them checks what will be checked. What a form does with them — how a field is edited,
+   * what it shows — is the foundation's.
+   *
+   * Read once per viewer and kept. Signed out, the backend answers `401` (`auth`); an
+   * unknown Model is `absent`.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the Model, e.g. `@acme/cv`
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ model: object|null, sections: object[] }>}
+   */
+  async readDefinition({ schema, signal } = {}) {
+    if (!schema) throw ApiError.invalid('No Model', 'readDefinition needs a schema')
+    return formOf(await this._definition(schema, signal))
+  }
+
+  /**
+   * One page of a section's items — the choices an `item_ref` field offers, read by the
+   * section the field names (`section_uuid` on its declaration). `listChoices` finds
+   * that section for you from a field.
+   *
+   * Each item is `{ uuid, entity, parent?, data, has_children? }`: `uuid` is the value the
+   * field stores; `data` the item's content, in the site's language (`locale`, as every
+   * read); `parent` the item it sits under; `has_children` — for a list whose items nest
+   * — whether items sit under it.
+   *
+   * - **Whose items:** every entry of the section's Model the viewer may read, or only
+   *   `entity`'s.
+   * - **One level at a time:** without `parent`, the section's top level; with it, the
+   *   items under that item — the next level of a nesting list, or a dependent list's
+   *   choices under the item chosen in the field it depends on.
+   * - **A search:** `q` matched, ignoring case, anywhere in the section's field `field`
+   *   (a `string` or `text` field), in the site's language for a localized one.
+   * - **Paging:** pass `nextCursor` back as `cursor`. ⚠️ A searched page can be short
+   *   while more follow, so `hasMore` — a cursor came back — is the only end signal.
+   *
+   * @param {object} args
+   * @param {string} args.section - the section's uuid
+   * @param {string} [args.entity] - only this entry's items
+   * @param {string} [args.parent] - the uuid of the item whose children to read
+   * @param {string} [args.field] - the field `q` is matched in
+   * @param {string} [args.q] - the search term
+   * @param {string} [args.cursor] - the previous page's `nextCursor`
+   * @param {number} [args.limit] - default 50, at most 1000
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ items: object[], nextCursor: string|null, hasMore: boolean }>}
+   */
+  async listSectionItems({ section, entity, parent, field, q, cursor, limit, signal } = {}) {
+    if (!section) throw ApiError.invalid('No Section', 'listSectionItems needs a section uuid')
+    const query = {
+      [PARAM.entity]: entity || undefined,
+      [PARAM.parent]: parent || undefined,
+      [PARAM.field]: field || undefined,
+      [PARAM.q]: q || undefined,
+      [PARAM.cursor]: cursor || undefined,
+      [PARAM.limit]: limit ?? PAGE.size,
+      ...this._localeQuery(),
+    }
+    const body = await this.request('GET', ROUTES.sectionItems(section), { query, signal })
+    const items = Array.isArray(body?.[SECTION_ITEMS.items]) ? body[SECTION_ITEMS.items] : []
+    const nextCursor = typeof body?.[SECTION_ITEMS.next] === 'string' ? body[SECTION_ITEMS.next] : null
+    return { items, nextCursor, hasMore: nextCursor != null }
+  }
+
+  /**
+   * The choices a field offers — the field's own list, read from the Model's definition.
+   *
+   * ```js
+   * const { items } = await listChoices({ schema: '@acme/cv', field: 'country', q: 'can', searchIn: 'label' })
+   * // items[i].uuid is the value to store in `country`
+   * const provinces = await listChoices({ schema: '@acme/cv', field: 'province', parent: country })
+   * ```
+   *
+   * `field` is a field of kind `item_ref` — in a schema, `type: item_ref` with
+   * `options: '@scope/lists/countries'` — and `section` names its section when several
+   * declare a field of that name. Everything else is `listSectionItems`'s: `parent` reads
+   * the items under an item, which is how a dependent list follows the field it depends
+   * on; `q` searches the choices' field `searchIn`.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the Model whose field offers the choices
+   * @param {string} args.field - the field's key
+   * @param {string} [args.section] - the field's section, by name or path
+   * @param {string} [args.parent]
+   * @param {string} [args.q]
+   * @param {string} [args.searchIn] - the field of the choices `q` is matched in
+   * @param {string} [args.cursor]
+   * @param {number} [args.limit]
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ items: object[], nextCursor: string|null, hasMore: boolean }>}
+   */
+  async listChoices({ schema, field, section, parent, q, searchIn, cursor, limit, signal } = {}) {
+    if (!schema) throw ApiError.invalid('No Model', 'listChoices needs the schema whose field offers the choices')
+    if (!field) throw ApiError.invalid('No Field', 'listChoices needs the field whose choices to list')
+    const { sections } = await this.readDefinition({ schema, signal })
+    const found = sections
+      .filter((s) => section == null || s.name === section || s.path === section)
+      .flatMap((s) => s.fields.filter((f) => f.key === field))
+    if (found.length !== 1) {
+      throw ApiError.invalid(
+        'Unknown Field',
+        found.length
+          ? `${schema} declares '${field}' in several sections — name the section`
+          : `${schema} has no field '${field}'${section != null ? ` in section '${section}'` : ''}`,
+      )
+    }
+    const [declared] = found
+    const pinned = declared[SCHEMA.choicesSection]
+    if (!pinned) {
+      throw ApiError.invalid(
+        'No Choices',
+        declared.kind === 'item_ref'
+          ? `'${field}' of ${schema} names no list its choices are in`
+          : `'${field}' of ${schema} is not a choice from a list — its kind is ${declared.kind}`,
+      )
+    }
+    return this.listSectionItems({
+      section: pinned,
+      entity: declared[SCHEMA.choicesEntity],
+      parent,
+      field: searchIn,
+      q,
+      cursor,
+      limit,
+      signal,
+    })
+  }
+
   /**
    * The numeric id of a section, by name — or by `parent/child` path for a nested
    * one — which is how the item route names a section.
@@ -1023,6 +1277,12 @@ export const signIn = (credentials) => required().signIn(credentials)
 export const completeChallenge = (code) => required().completeChallenge(code)
 /** @see ApiClient#signOut */
 export const signOut = () => required().signOut()
+/** @see ApiClient#elevate — on any instance, an older copy's too */
+export const elevate = (credentials) => elevateWith(required(), credentials)
+/** @see ApiClient#lower — on any instance, an older copy's too */
+export const lower = () => lowerWith(required())
+/** @see ApiClient#elevateWithProvider — on any instance, an older copy's too */
+export const elevateWithProvider = (provider, options) => elevateWithProviderOf(required(), provider, options)
 /** @see ApiClient#signUp */
 export const signUp = (fields) => required().signUp(fields)
 /** @see ApiClient#requestPasswordReset */
@@ -1043,6 +1303,12 @@ export const declineInvitation = (id) => declineInvitationWith(required(), id)
 export const readEntity = (args) => required().readEntity(args)
 /** @see ApiClient#listEntities */
 export const listEntities = (args) => required().listEntities(args)
+
+export const readDefinition = (args) => required().readDefinition(args)
+
+export const listSectionItems = (args) => required().listSectionItems(args)
+
+export const listChoices = (args) => required().listChoices(args)
 /** @see ApiClient#writeItems */
 export const writeItems = (args) => required().writeItems(args)
 /** @see ApiClient#createEntity */
@@ -1053,5 +1319,6 @@ export const deleteEntity = (args) => required().deleteEntity(args)
 export const adminHref = () => adminHrefOf(getClient())
 
 export { mailedLink, forgetMailedLink } from './mailed-links.js'
+export { isElevated, rolesInFull, elevationReturn } from './elevation.js'
 export { ApiError, kindOf } from './errors.js'
 export { Ledger } from './ledger.js'